Add mockUserToken support for Firestore.

Author: yuchenshi

packages/app-types/index.d.ts

@@ -121,6 +121,84 @@ export interface VersionService {
   version: string;
 }
 
+export type FirebaseSignInProvider =
+  | 'custom'
+  | 'email'
+  | 'password'
+  | 'phone'
+  | 'anonymous'
+  | 'google.com'
+  | 'facebook.com'
+  | 'github.com'
+  | 'twitter.com'
+  | 'microsoft.com'
+  | 'apple.com';
+
+export interface FirebaseIdToken {
+  // Firebase Auth tokens contain snake_case claims following the JWT standard / convention.
+  /* eslint-disable camelcase */
+
+  // Always set to https://securetoken.google.com/PROJECT_ID
+  iss: string;
+
+  // Always set to PROJECT_ID
+  aud: string;
+
+  // The user's unique id
+  sub: string;
+
+  // The token issue time, in seconds since epoch
+  iat: number;
+
+  // The token expiry time, normally 'iat' + 3600
+  exp: number;
+
+  // The user's unique id, must be equal to 'sub'
+  user_id: string;
+
+  // The time the user authenticated, normally 'iat'
+  auth_time: number;
+
+  // The sign in provider, only set when the provider is 'anonymous'
+  provider_id?: 'anonymous';
+
+  // The user's primary email
+  email?: string;
+
+  // The user's email verification status
+  email_verified?: boolean;
+
+  // The user's primary phone number
+  phone_number?: string;
+
+  // The user's display name
+  name?: string;
+
+  // The user's profile photo URL
+  picture?: string;
+
+  // Information on all identities linked to this user
+  firebase: {
+    // The primary sign-in provider
+    sign_in_provider: FirebaseSignInProvider;
+
+    // A map of providers to the user's list of unique identifiers from
+    // each provider
+    identities?: { [provider in FirebaseSignInProvider]?: string[] };
+  };
+
+  // Custom claims set by the developer
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [claim: string]: any;
+
+  uid?: never; // Try to catch a common mistake of "uid" (should be "sub" instead).
+
+  /* eslint-enable camelcase */
+}
+
+export type EmulatorMockTokenOptions = ({ user_id: string } | { sub: string }) &
+  Partial<FirebaseIdToken>;
+
 declare module '@firebase/component' {
   interface NameServiceMapping {
     'app': FirebaseApp;

packages/firestore-types/index.d.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-import { FirebaseApp, FirebaseNamespace } from '@firebase/app-types';
+import { EmulatorMockTokenOptions } from '@firebase/app-types';
 
 export type DocumentData = { [field: string]: any };
 
@@ -61,7 +61,13 @@ export class FirebaseFirestore {
 
   settings(settings: Settings): void;
 
-  useEmulator(host: string, port: number): void;
+  useEmulator(
+    host: string,
+    port: number,
+    options?: {
+      mockUserToken?: EmulatorMockTokenOptions;
+    }
+  ): void;
 
   enablePersistence(settings?: PersistenceSettings): Promise<void>;
 

packages/firestore/src/api/credentials.ts

@@ -135,6 +135,38 @@ export class EmptyCredentialsProvider implements CredentialsProvider {
   }
 }
 
+/** A CredentialsProvider that always returns a constant token. Used for emulator token mocking. */
+export class EmulatorCredentialsProvider implements CredentialsProvider {
+  constructor(private token: Token) {}
+
+  /**
+   * Stores the listener registered with setChangeListener()
+   * This isn't actually necessary since the UID never changes, but we use this
+   * to verify the listen contract is adhered to in tests.
+   */
+  private changeListener: CredentialChangeListener | null = null;
+
+  getToken(): Promise<Token | null> {
+    return Promise.resolve(this.token);
+  }
+
+  invalidateToken(): void {}
+
+  setChangeListener(changeListener: CredentialChangeListener): void {
+    debugAssert(
+      !this.changeListener,
+      'Can only call setChangeListener() once.'
+    );
+    this.changeListener = changeListener;
+    // Fire with initial user.
+    changeListener(this.token.user);
+  }
+
+  removeChangeListener(): void {
+    this.changeListener = null;
+  }
+}
+
 export class FirebaseCredentialsProvider implements CredentialsProvider {
   /**
    * The auth token listener registered with FirebaseApp, retained here so we

packages/firestore/src/api/database.ts

@@ -44,7 +44,11 @@ import {
   WhereFilterOp as PublicWhereFilterOp,
   WriteBatch as PublicWriteBatch
 } from '@firebase/firestore-types';
-import { Compat, getModularInstance } from '@firebase/util';
+import {
+  Compat,
+  EmulatorMockTokenOptions,
+  getModularInstance
+} from '@firebase/util';
 
 import {
   LoadBundleTask,
@@ -223,8 +227,14 @@ export class Firestore
     this._delegate._setSettings(settingsLiteral);
   }
 
-  useEmulator(host: string, port: number): void {
-    useFirestoreEmulator(this._delegate, host, port);
+  useEmulator(
+    host: string,
+    port: number,
+    options: {
+      mockUserToken?: EmulatorMockTokenOptions;
+    } = {}
+  ): void {
+    useFirestoreEmulator(this._delegate, host, port, options);
   }
 
   enableNetwork(): Promise<void> {

packages/firestore/src/lite/database.ts

@@ -24,13 +24,17 @@ import {
 } from '@firebase/app-exp';
 import { FirebaseAuthInternalName } from '@firebase/auth-interop-types';
 import { Provider } from '@firebase/component';
+import { createMockUserToken, EmulatorMockTokenOptions } from '@firebase/util';
 
 import {
   CredentialsProvider,
   EmptyCredentialsProvider,
+  EmulatorCredentialsProvider,
   FirebaseCredentialsProvider,
-  makeCredentialsProvider
+  makeCredentialsProvider,
+  OAuthToken
 } from '../api/credentials';
+import { User } from '../auth/user';
 import { DatabaseId } from '../core/database_info';
 import { Code, FirestoreError } from '../util/error';
 import { cast } from '../util/input_validation';
@@ -228,7 +232,10 @@ export function getFirestore(app: FirebaseApp = getApp()): FirebaseFirestore {
 export function useFirestoreEmulator(
   firestore: FirebaseFirestore,
   host: string,
-  port: number
+  port: number,
+  options: {
+    mockUserToken?: EmulatorMockTokenOptions;
+  } = {}
 ): void {
   firestore = cast(firestore, FirebaseFirestore);
   const settings = firestore._getSettings();
@@ -245,6 +252,21 @@ export function useFirestoreEmulator(
     host: `${host}:${port}`,
     ssl: false
   });
+
+  if (options.mockUserToken) {
+    const uid = options.mockUserToken.sub || options.mockUserToken.user_id;
+    if (!uid) {
+      throw new FirestoreError(
+        Code.INVALID_ARGUMENT,
+        "mockUserToken must contain 'sub' or 'user_id' field!"
+      );
+    }
+
+    const token = createMockUserToken(options.mockUserToken);
+    firestore._credentials = new EmulatorCredentialsProvider(
+      new OAuthToken(token, new User(uid))
+    );
+  }
 }
 
 /**

packages/firestore/test/integration/api/validation.test.ts

@@ -157,6 +157,24 @@ apiDescribe('Validation:', (persistence: boolean) => {
         expect(() => db.useEmulator('localhost', 9000)).to.throw(errorMsg);
       }
     );
+
+    validationIt(persistence, 'useEmulator can set mockUserToken', () => {
+      const db = newTestFirestore('test-project');
+      // Verify that this doesn't throw.
+      db.useEmulator('localhost', 9000, { mockUserToken: { sub: 'foo' } });
+    });
+
+    validationIt(
+      persistence,
+      'throws if sub / user_id is missing in mockUserToken',
+      async db => {
+        const errorMsg = "mockUserToken must contain 'sub' or 'user_id' field!";
+
+        expect(() =>
+          db.useEmulator('localhost', 9000, { mockUserToken: {} as any })
+        ).to.throw(errorMsg);
+      }
+    );
   });
 
   describe('Firestore', () => {

packages/firestore/test/unit/api/database.test.ts

@@ -15,7 +15,9 @@
  * limitations under the License.
  */
 
+import { createMockUserToken } from '@firebase/util';
 import { expect } from 'chai';
+import { EmulatorCredentialsProvider } from '../../../src/api/credentials';
 
 import {
   collectionReference,
@@ -250,4 +252,19 @@ describe('Settings', () => {
     expect(db._delegate._getSettings().host).to.equal('localhost:9000');
     expect(db._delegate._getSettings().ssl).to.be.false;
   });
+
+  it('sets credentials based on mockUserToken', async () => {
+    // Use a new instance of Firestore in order to configure settings.
+    const db = newTestFirestore();
+    const mockUserToken = { sub: 'foobar' };
+    db.useEmulator('localhost', 9000, { mockUserToken });
+
+    expect(db._delegate._getSettings().host).to.equal('localhost:9000');
+    expect(db._delegate._getSettings().ssl).to.be.false;
+    const { credentials } = db._delegate._getSettings();
+    expect(credentials).to.be.instanceOf(EmulatorCredentialsProvider);
+    await expect(credentials.getToken()).to.eventually.be.eql(
+      createMockUserToken(mockUserToken)
+    );
+  });
 });