FAC scoped token support

Author: sam-gc

common/api-review/app-check.api.md

@@ -60,6 +60,9 @@ export interface CustomProviderOptions {
     getToken: () => Promise<AppCheckToken>;
 }
 
+// @public
+export function getScopedToken(appCheckInstance: AppCheck): Promise<AppCheckTokenResult>;
+
 // @public
 export function getToken(appCheckInstance: AppCheck, forceRefresh?: boolean): Promise<AppCheckTokenResult>;
 

packages/app-check/src/api.test.ts

@@ -21,7 +21,8 @@ import {
   setTokenAutoRefreshEnabled,
   initializeAppCheck,
   getToken,
-  onTokenChanged
+  onTokenChanged,
+  getScopedToken
 } from './api';
 import {
   FAKE_SITE_KEY,
@@ -284,6 +285,33 @@ describe('api', () => {
       );
     });
   });
+  describe('getScopedToken()', () => {
+    it('getScopedToken() calls the internal getScopedToken() function', async () => {
+      const app = getFakeApp({ automaticDataCollectionEnabled: true });
+      const appCheck = getFakeAppCheck(app);
+      const internalGetScopedToken = stub(
+        internalApi,
+        'getScopedToken'
+      ).resolves({
+        token: 'a-token-string'
+      });
+      await getScopedToken(appCheck);
+      expect(internalGetScopedToken).to.be.calledWith(appCheck);
+    });
+    it('getScopedToken() throws errors returned with token', async () => {
+      const app = getFakeApp({ automaticDataCollectionEnabled: true });
+      const appCheck = getFakeAppCheck(app);
+      // If getScopedToken() errors, it returns a dummy token with an error field
+      // instead of throwing.
+      stub(internalApi, 'getScopedToken').resolves({
+        token: 'a-dummy-token',
+        error: Error('there was an error')
+      });
+      await expect(getScopedToken(appCheck)).to.be.rejectedWith(
+        'there was an error'
+      );
+    });
+  });
   describe('onTokenChanged()', () => {
     it('Listeners work when using top-level parameters pattern', async () => {
       const appCheck = initializeAppCheck(app, {

packages/app-check/src/api.ts

@@ -35,6 +35,7 @@ import { AppCheckService } from './factory';
 import { AppCheckProvider, ListenerType } from './types';
 import {
   getToken as getTokenInternal,
+  getScopedToken as getScopedTokenInternal,
   addTokenListener,
   removeTokenListener,
   isValid,
@@ -209,6 +210,28 @@ export async function getToken(
   return { token: result.token };
 }
 
+/**
+ * Requests a Firebase App Check token. This method should be used ONLY if you
+ * need to authorize requests to a non-Firebase backend. Tokens from this
+ * method are intended for use with the Admin SDKs when `consume` is set to
+ * true. Tokens from this method do not interact with FirebaseAppCheck’s token
+ * cache.
+ *
+ * @param appCheckInstance - The App Check service instance.
+ * @public
+ */
+export async function getScopedToken(
+  appCheckInstance: AppCheck
+): Promise<AppCheckTokenResult> {
+  const result = await getScopedTokenInternal(
+    appCheckInstance as AppCheckService
+  );
+  if (result.error) {
+    throw result.error;
+  }
+  return { token: result.token };
+}
+
 /**
  * Registers a listener to changes in the token state. There can be more
  * than one listener registered at the same time for one or more

packages/app-check/src/internal-api.test.ts

@@ -32,7 +32,8 @@ import {
   addTokenListener,
   removeTokenListener,
   formatDummyToken,
-  defaultTokenErrorData
+  defaultTokenErrorData,
+  getScopedToken
 } from './internal-api';
 import * as reCAPTCHA from './recaptcha';
 import * as client from './client';
@@ -637,6 +638,180 @@ describe('internal api', () => {
     });
   });
 
+  describe('getScopedToken()', () => {
+    it('uses customTokenProvider to get an AppCheck token', async () => {
+      const customTokenProvider = getFakeCustomTokenProvider();
+      const customProviderSpy = spy(customTokenProvider, 'getToken');
+
+      const appCheck = initializeAppCheck(app, {
+        provider: customTokenProvider
+      });
+      const token = await getScopedToken(appCheck as AppCheckService);
+
+      expect(customProviderSpy).to.be.called;
+      expect(token).to.deep.equal({
+        token: 'fake-custom-app-check-token'
+      });
+    });
+
+    it('does not interact with state', async () => {
+      const customTokenProvider = getFakeCustomTokenProvider();
+      spy(customTokenProvider, 'getToken');
+
+      const appCheck = initializeAppCheck(app, {
+        provider: customTokenProvider
+      });
+      await getScopedToken(appCheck as AppCheckService);
+
+      expect(getStateReference(app).token).to.be.undefined;
+      expect(getStateReference(app).isTokenAutoRefreshEnabled).to.be.false;
+    });
+
+    it('uses reCAPTCHA (V3) token to exchange for AppCheck token', async () => {
+      const appCheck = initializeAppCheck(app, {
+        provider: new ReCaptchaV3Provider(FAKE_SITE_KEY)
+      });
+
+      const reCAPTCHASpy = stub(reCAPTCHA, 'getToken').returns(
+        Promise.resolve(fakeRecaptchaToken)
+      );
+      const exchangeTokenStub: SinonStub = stub(
+        client,
+        'exchangeToken'
+      ).returns(Promise.resolve(fakeRecaptchaAppCheckToken));
+
+      const token = await getScopedToken(appCheck as AppCheckService);
+
+      expect(reCAPTCHASpy).to.be.called;
+
+      expect(exchangeTokenStub.args[0][0].body['recaptcha_v3_token']).to.equal(
+        fakeRecaptchaToken
+      );
+      expect(token).to.deep.equal({ token: fakeRecaptchaAppCheckToken.token });
+    });
+
+    it('uses reCAPTCHA (Enterprise) token to exchange for AppCheck token', async () => {
+      const appCheck = initializeAppCheck(app, {
+        provider: new ReCaptchaEnterpriseProvider(FAKE_SITE_KEY)
+      });
+
+      const reCAPTCHASpy = stub(reCAPTCHA, 'getToken').returns(
+        Promise.resolve(fakeRecaptchaToken)
+      );
+      const exchangeTokenStub: SinonStub = stub(
+        client,
+        'exchangeToken'
+      ).returns(Promise.resolve(fakeRecaptchaAppCheckToken));
+
+      const token = await getScopedToken(appCheck as AppCheckService);
+
+      expect(reCAPTCHASpy).to.be.called;
+
+      expect(
+        exchangeTokenStub.args[0][0].body['recaptcha_enterprise_token']
+      ).to.equal(fakeRecaptchaToken);
+      expect(token).to.deep.equal({ token: fakeRecaptchaAppCheckToken.token });
+    });
+
+    it('resolves with a dummy token and an error if failed to get a token', async () => {
+      const errorStub = stub(console, 'error');
+      const appCheck = initializeAppCheck(app, {
+        provider: new ReCaptchaV3Provider(FAKE_SITE_KEY)
+      });
+
+      const reCAPTCHASpy = stub(reCAPTCHA, 'getToken').returns(
+        Promise.resolve(fakeRecaptchaToken)
+      );
+
+      const error = new Error('oops, something went wrong');
+      stub(client, 'exchangeToken').returns(Promise.reject(error));
+
+      const token = await getScopedToken(appCheck as AppCheckService);
+
+      expect(reCAPTCHASpy).to.be.called;
+      expect(token).to.deep.equal({
+        token: formatDummyToken(defaultTokenErrorData),
+        error
+      });
+      expect(errorStub.args[0][1].message).to.include(
+        'oops, something went wrong'
+      );
+      errorStub.restore();
+    });
+
+    it('exchanges debug token if in debug mode', async () => {
+      const exchangeTokenStub: SinonStub = stub(
+        client,
+        'exchangeToken'
+      ).returns(Promise.resolve(fakeRecaptchaAppCheckToken));
+      const debugState = getDebugState();
+      debugState.enabled = true;
+      debugState.token = new Deferred();
+      debugState.token.resolve('my-debug-token');
+      const appCheck = initializeAppCheck(app, {
+        provider: new ReCaptchaV3Provider(FAKE_SITE_KEY)
+      });
+
+      const token = await getScopedToken(appCheck as AppCheckService);
+      expect(exchangeTokenStub.args[0][0].body['debug_token']).to.equal(
+        'my-debug-token'
+      );
+      expect(token).to.deep.equal({ token: fakeRecaptchaAppCheckToken.token });
+    });
+
+    it('throttles for a period less than 1d on 503', async () => {
+      // More detailed check of exponential backoff in providers.test.ts
+      const appCheck = initializeAppCheck(app, {
+        provider: new ReCaptchaV3Provider(FAKE_SITE_KEY)
+      });
+      const warnStub = stub(logger, 'warn');
+      stub(client, 'exchangeToken').returns(
+        Promise.reject(
+          ERROR_FACTORY.create(AppCheckError.FETCH_STATUS_ERROR, {
+            httpStatus: 503
+          })
+        )
+      );
+
+      const token = await getScopedToken(appCheck as AppCheckService);
+
+      // ReCaptchaV3Provider's _throttleData is private so checking
+      // the resulting error message to be sure it has roughly the
+      // correct throttle time. This also tests the time formatter.
+      // Check both the error itself and that it makes it through to
+      // console.warn
+      expect(token.error?.message).to.include('503');
+      expect(token.error?.message).to.include('00m');
+      expect(token.error?.message).to.not.include('1d');
+      expect(warnStub.args[0][0]).to.include('503');
+    });
+
+    it('throttles 1d on 403', async () => {
+      const appCheck = initializeAppCheck(app, {
+        provider: new ReCaptchaV3Provider(FAKE_SITE_KEY)
+      });
+      const warnStub = stub(logger, 'warn');
+      stub(client, 'exchangeToken').returns(
+        Promise.reject(
+          ERROR_FACTORY.create(AppCheckError.FETCH_STATUS_ERROR, {
+            httpStatus: 403
+          })
+        )
+      );
+
+      const token = await getScopedToken(appCheck as AppCheckService);
+
+      // ReCaptchaV3Provider's _throttleData is private so checking
+      // the resulting error message to be sure it has roughly the
+      // correct throttle time. This also tests the time formatter.
+      // Check both the error itself and that it makes it through to
+      // console.warn
+      expect(token.error?.message).to.include('403');
+      expect(token.error?.message).to.include('1d');
+      expect(warnStub.args[0][0]).to.include('403');
+    });
+  });
+
   describe('addTokenListener', () => {
     afterEach(async () => {
       clearState();

packages/app-check/src/internal-api.ts

@@ -205,6 +205,89 @@ export async function getToken(
   return interopTokenResult;
 }
 
+/**
+ * This function always resolves.
+ * The result will contain an error field if there is any error.
+ * In case there is an error, the token field in the result will be populated with a dummy value
+ */
+export async function getScopedToken(
+  appCheck: AppCheckService
+): Promise<AppCheckTokenResult> {
+  const app = appCheck.app;
+  ensureActivated(app);
+
+  const { provider } = getStateReference(app);
+
+  /**
+   * First check if there is a token in memory from a previous `getToken()` call.
+   */
+  let token: AppCheckTokenInternal | undefined = undefined;
+  let error: Error | undefined = undefined;
+
+  /**
+   * DEBUG MODE
+   * If debug mode is set, and there is no cached token, fetch a new App
+   * Check token using the debug token, and return it directly.
+   */
+  if (isDebugMode()) {
+    const debugToken = await getDebugToken();
+    const tokenFromDebugExchange: AppCheckTokenInternal = await exchangeToken(
+      getExchangeDebugTokenRequest(app, debugToken),
+      appCheck.heartbeatServiceProvider
+    );
+    return { token: tokenFromDebugExchange.token };
+  }
+
+  /**
+   * There are no valid tokens in memory or indexedDB and we are not in
+   * debug mode.
+   * Request a new token from the exchange endpoint.
+   */
+  try {
+    token = await provider!.getToken();
+  } catch (e) {
+    if ((e as FirebaseError).code === `appCheck/${AppCheckError.THROTTLED}`) {
+      // Warn if throttled, but do not treat it as an error.
+      logger.warn((e as FirebaseError).message);
+    } else {
+      // `getToken()` should never throw, but logging error text to console will aid debugging.
+      logger.error(e);
+    }
+    // Always save error to be added to dummy token.
+    error = e as FirebaseError;
+  }
+
+  let interopTokenResult: AppCheckTokenResult | undefined;
+  if (!token) {
+    // If token is undefined, there must be an error.
+    // Return a dummy token along with the error.
+    interopTokenResult = makeDummyTokenResult(error!);
+  } else if (error) {
+    if (isValid(token)) {
+      // It's also possible a valid token exists, but there's also an error.
+      // (Such as if the token is almost expired, tries to refresh, and
+      // the exchange request fails.)
+      // We add a special error property here so that the refresher will
+      // count this as a failed attempt and use the backoff instead of
+      // retrying repeatedly with no delay, but any 3P listeners will not
+      // be hindered in getting the still-valid token.
+      interopTokenResult = {
+        token: token.token,
+        internalError: error
+      };
+    } else {
+      // No invalid tokens should make it to this step. Memory and cached tokens
+      // are checked. Other tokens are from fresh exchanges. But just in case.
+      interopTokenResult = makeDummyTokenResult(error!);
+    }
+  } else {
+    interopTokenResult = {
+      token: token.token
+    };
+  }
+  return interopTokenResult;
+}
+
 export function addTokenListener(
   appCheck: AppCheckService,
   type: ListenerType,