@firebase/auth 0.21.5-canary.ce79f7fe2 → 0.21.5-canary.f8a2c5865

package/README.md

@@ -17,6 +17,7 @@ host of npm scripts to run these tests. The most important commands are:
 | `yarn test:<platform>:unit:debug` | Runs \<platform> unit tests, auto-watching for file system changes |
 | `yarn test:<platform>:integration` | Runs only integration tests against the live environment |
 | `yarn test:<platform>:integration:local` | Runs all headless \<platform> integration tests against the emulator (more below) |
+| `yarn test:browser:integration:prodbackend` | Runs TOTP MFA integration tests against the backend (more below) |
 
 Where \<platform> is "browser" or "node". There are also cordova tests, but they
 are not broken into such granular details. Check out `package.json` for more.
@@ -39,6 +40,11 @@ commands also run various tests:
   * `yarn test:webdriver` — Executes only the Selenium WebDriver
     integration tests
 
+Note - The webdriver tests require the Chrome webdriver to match the version of Chrome running locally.
+In the CI environment, this is ensured using the environment variable [here.](https://github.com/firebase/firebase-js-sdk/blob/6e80a678fe0c31046860554cec0459a2be34d22b/.github/workflows/test-changed-auth.yml#L7)
+When running locally, change the chromedriver version in [package.json](https://github.com/firebase/firebase-js-sdk/blob/6e80a678fe0c31046860554cec0459a2be34d22b/packages/auth/package.json#L124) to match your local Chrome version and run `yarn install`.
+
+
 For example, to run all integration and WebDriver tests against the emulator,
 you would simply execute the following command:
 
@@ -46,6 +52,25 @@ you would simply execute the following command:
 firebase emulators:exec --project foo-bar --only auth "yarn test:integration:local"
 ```
 
+### Integration testing with the production backend
+
+Currently, MFA TOTP tests only run against the production backend (since they are not supported on the emulator yet).
+Running against the backend also makes it a more reliable end-to-end test.
+
+The TOTP tests require the following email/password combination to exist in the project, so if you are running this test against your test project, please create this user:
+
+'totpuser-donotdelete@test.com', 'password'
+
+You also need to verify this email address, in order to use MFA. This can be done with a curl command like this:
+
+```
+curl   -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   -H "X-Goog-User-Project: ${PROJECT_ID}"   -X POST https://identitytoolkit.googleapis.com/v1/accounts:sendOobCode   -d     '{
+      "email": "totpuser-donotdelete@test.com",
+      "requestType": "VERIFY_EMAIL",
+      "returnOobLink": true,
+    }'
+```
+
 ### Selenium Webdriver tests
 
 These tests assume that you have both Firefox and Chrome installed on your

package/dist/auth-public.d.ts

@@ -670,7 +670,7 @@ export declare interface AuthSettings {
 }
 
 /**
- * MFA Info as returned by the API
+ * MFA Info as returned by the API.
  */
 declare interface BaseMfaEnrollment {
     mfaEnrollmentId: string;
@@ -1154,8 +1154,11 @@ export declare class FacebookAuthProvider extends BaseOAuthProvider {
 export declare const FactorId: {
     /** Phone as second factor */
     readonly PHONE: "phone";
+    readonly TOTP: "totp";
 };
 
+/* Excluded from this release type: FactorId_2 */
+
 /**
  * The base class for all Federated providers (OAuth (including OIDC), SAML).
  *
@@ -1657,9 +1660,9 @@ export declare function linkWithPopup(user: User, provider: AuthProvider, resolv
 export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise<never>;
 
 /**
- * MfaEnrollment can be any subtype of BaseMfaEnrollment, currently only PhoneMfaEnrollment is supported
+ * MfaEnrollment can be any subtype of BaseMfaEnrollment, currently only PhoneMfaEnrollment and TotpMfaEnrollment are supported.
  */
-declare type MfaEnrollment = PhoneMfaEnrollment;
+declare type MfaEnrollment = PhoneMfaEnrollment | TotpMfaEnrollment;
 
 /**
  * The {@link MultiFactorUser} corresponding to the user.
@@ -2132,6 +2135,7 @@ export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObs
  *
  * @remarks
  * This includes sign-in, sign-out, and token refresh events.
+ * This will not be triggered automatically upon ID token expiration. Use {@link User.getIdToken} to refresh the ID token.
  *
  * @param auth - The {@link Auth} instance.
  * @param nextOrObserver - callback triggered on change.
@@ -2371,7 +2375,7 @@ export declare class PhoneAuthProvider {
 export declare type PhoneInfoOptions = PhoneSingleFactorInfoOptions | PhoneMultiFactorEnrollInfoOptions | PhoneMultiFactorSignInInfoOptions;
 
 /**
- * An MFA provided by SMS verification
+ * An MFA provided by SMS verification.
  */
 declare interface PhoneMfaEnrollment extends BaseMfaEnrollment {
     phoneInfo: string;
@@ -3148,10 +3152,139 @@ export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, r
  */
 export declare function signOut(auth: Auth): Promise<void>;
 
+declare interface StartTotpMfaEnrollmentResponse {
+    totpSessionInfo: {
+        sharedSecretKey: string;
+        verificationCodeLength: number;
+        hashingAlgorithm: string;
+        periodSec: number;
+        sessionInfo: string;
+        finalizeEnrollmentTime: number;
+    };
+}
+
 /* Excluded from this release type: StsTokenManager */
 
 /* Excluded from this release type: TaggedWithTokenResponse */
 
+/**
+ * An MFA provided by TOTP (Time-based One Time Password).
+ */
+declare interface TotpMfaEnrollment extends BaseMfaEnrollment {
+}
+
+/**
+ * The class for asserting ownership of a TOTP second factor. Provided by
+ * {@link TotpMultiFactorGenerator.assertionForEnrollment} and
+ * {@link TotpMultiFactorGenerator.assertionForSignIn}.
+ *
+ * @public
+ */
+export declare interface TotpMultiFactorAssertion extends MultiFactorAssertion {
+}
+
+/**
+ * Provider for generating a {@link TotpMultiFactorAssertion}.
+ *
+ * @public
+ */
+export declare class TotpMultiFactorGenerator {
+    /**
+     * Provides a {@link TotpMultiFactorAssertion} to confirm ownership of
+     * the TOTP (time-based one-time password) second factor.
+     * This assertion is used to complete enrollment in TOTP second factor.
+     *
+     * @param secret A {@link TotpSecret} containing the shared secret key and other TOTP parameters.
+     * @param oneTimePassword One-time password from TOTP App.
+     * @returns A {@link TotpMultiFactorAssertion} which can be used with
+     * {@link MultiFactorUser.enroll}.
+     */
+    static assertionForEnrollment(secret: TotpSecret, oneTimePassword: string): TotpMultiFactorAssertion;
+    /**
+     * Provides a {@link TotpMultiFactorAssertion} to confirm ownership of the TOTP second factor.
+     * This assertion is used to complete signIn with TOTP as the second factor.
+     *
+     * @param enrollmentId identifies the enrolled TOTP second factor.
+     * @param oneTimePassword One-time password from TOTP App.
+     * @returns A {@link TotpMultiFactorAssertion} which can be used with
+     * {@link MultiFactorResolver.resolveSignIn}.
+     */
+    static assertionForSignIn(enrollmentId: string, oneTimePassword: string): TotpMultiFactorAssertion;
+    /**
+     * Returns a promise to {@link TotpSecret} which contains the TOTP shared secret key and other parameters.
+     * Creates a TOTP secret as part of enrolling a TOTP second factor.
+     * Used for generating a QR code URL or inputting into a TOTP app.
+     * This method uses the auth instance corresponding to the user in the multiFactorSession.
+     *
+     * @param session The {@link MultiFactorSession} that the user is part of.
+     * @returns A promise to {@link TotpSecret}.
+     */
+    static generateSecret(session: MultiFactorSession): Promise<TotpSecret>;
+    /**
+     * The identifier of the TOTP second factor: `totp`.
+     */
+    static FACTOR_ID: FactorId_2;
+}
+
+/**
+ * The subclass of the {@link MultiFactorInfo} interface for TOTP
+ * second factors. The `factorId` of this second factor is {@link FactorId}.TOTP.
+ * @public
+ */
+export declare interface TotpMultiFactorInfo extends MultiFactorInfo {
+}
+
+/**
+ * Provider for generating a {@link TotpMultiFactorAssertion}.
+ *
+ * Stores the shared secret key and other parameters to generate time-based OTPs.
+ * Implements methods to retrieve the shared secret key and generate a QR code URL.
+ * @public
+ */
+export declare class TotpSecret {
+    private readonly sessionInfo;
+    private readonly auth;
+    /**
+     * Shared secret key/seed used for enrolling in TOTP MFA and generating OTPs.
+     */
+    readonly secretKey: string;
+    /**
+     * Hashing algorithm used.
+     */
+    readonly hashingAlgorithm: string;
+    /**
+     * Length of the one-time passwords to be generated.
+     */
+    readonly codeLength: number;
+    /**
+     * The interval (in seconds) when the OTP codes should change.
+     */
+    readonly codeIntervalSeconds: number;
+    /**
+     * The timestamp (UTC string) by which TOTP enrollment should be completed.
+     */
+    readonly enrollmentCompletionDeadline: string;
+    private constructor();
+    /* Excluded from this release type: _fromStartTotpMfaEnrollmentResponse */
+    /* Excluded from this release type: _makeTotpVerificationInfo */
+    /**
+     * Returns a QR code URL as described in
+     * https://github.com/google/google-authenticator/wiki/Key-Uri-Format
+     * This can be displayed to the user as a QR code to be scanned into a TOTP app like Google Authenticator.
+     * If the optional parameters are unspecified, an accountName of <userEmail> and issuer of <firebaseAppName> are used.
+     *
+     * @param accountName the name of the account/app along with a user identifier.
+     * @param issuer issuer of the TOTP (likely the app name).
+     * @returns A QR code URL string.
+     */
+    generateQrCodeUrl(accountName?: string, issuer?: string): string;
+}
+
+declare interface TotpVerificationInfo {
+    sessionInfo: string;
+    verificationCode: string;
+}
+
 /**
  * Provider for generating an {@link OAuthCredential} for {@link ProviderId}.TWITTER.
  *

package/dist/auth.d.ts

@@ -575,6 +575,7 @@ declare const enum AuthErrorCode {
     MISSING_MFA_INFO = "missing-multi-factor-info",
     MISSING_MFA_SESSION = "missing-multi-factor-session",
     MISSING_PHONE_NUMBER = "missing-phone-number",
+    MISSING_PASSWORD = "missing-password",
     MISSING_SESSION_INFO = "missing-verification-id",
     MODULE_DESTROYED = "app-deleted",
     NEED_CONFIRMATION = "account-exists-with-different-credential",
@@ -897,7 +898,7 @@ export declare interface AuthSettings {
 }
 
 /**
- * MFA Info as returned by the API
+ * MFA Info as returned by the API.
  */
 declare interface BaseMfaEnrollment {
     mfaEnrollmentId: string;
@@ -1420,8 +1421,20 @@ export declare class FacebookAuthProvider extends BaseOAuthProvider {
 export declare const FactorId: {
     /** Phone as second factor */
     readonly PHONE: "phone";
+    readonly TOTP: "totp";
 };
 
+/**
+ * An enum of factors that may be used for multifactor authentication.
+ *
+ * @internal
+ */
+declare const enum FactorId_2 {
+    /** Phone as second factor */
+    PHONE = "phone",
+    TOTP = "totp"
+}
+
 /**
  * The base class for all Federated providers (OAuth (including OIDC), SAML).
  *
@@ -1978,9 +1991,9 @@ export declare function linkWithPopup(user: User, provider: AuthProvider, resolv
 export declare function linkWithRedirect(user: User, provider: AuthProvider, resolver?: PopupRedirectResolver): Promise<never>;
 
 /**
- * MfaEnrollment can be any subtype of BaseMfaEnrollment, currently only PhoneMfaEnrollment is supported
+ * MfaEnrollment can be any subtype of BaseMfaEnrollment, currently only PhoneMfaEnrollment and TotpMfaEnrollment are supported.
  */
-declare type MfaEnrollment = PhoneMfaEnrollment;
+declare type MfaEnrollment = PhoneMfaEnrollment | TotpMfaEnrollment;
 
 /**
  * The {@link MultiFactorUser} corresponding to the user.
@@ -2457,6 +2470,7 @@ export declare function onAuthStateChanged(auth: Auth, nextOrObserver: NextOrObs
  *
  * @remarks
  * This includes sign-in, sign-out, and token refresh events.
+ * This will not be triggered automatically upon ID token expiration. Use {@link User.getIdToken} to refresh the ID token.
  *
  * @param auth - The {@link Auth} instance.
  * @param nextOrObserver - callback triggered on change.
@@ -2702,7 +2716,7 @@ export declare class PhoneAuthProvider {
 export declare type PhoneInfoOptions = PhoneSingleFactorInfoOptions | PhoneMultiFactorEnrollInfoOptions | PhoneMultiFactorSignInInfoOptions;
 
 /**
- * An MFA provided by SMS verification
+ * An MFA provided by SMS verification.
  */
 declare interface PhoneMfaEnrollment extends BaseMfaEnrollment {
     phoneInfo: string;
@@ -3572,6 +3586,17 @@ export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, r
  */
 export declare function signOut(auth: Auth): Promise<void>;
 
+declare interface StartTotpMfaEnrollmentResponse {
+    totpSessionInfo: {
+        sharedSecretKey: string;
+        verificationCodeLength: number;
+        hashingAlgorithm: string;
+        periodSec: number;
+        sessionInfo: string;
+        finalizeEnrollmentTime: number;
+    };
+}
+
 /**
  * We need to mark this class as internal explicitly to exclude it in the public typings, because
  * it references AuthInternal which has a circular dependency with UserInternal.
@@ -3602,6 +3627,126 @@ declare interface TaggedWithTokenResponse {
     _tokenResponse?: PhoneOrOauthTokenResponse;
 }
 
+/**
+ * An MFA provided by TOTP (Time-based One Time Password).
+ */
+declare interface TotpMfaEnrollment extends BaseMfaEnrollment {
+}
+
+/**
+ * The class for asserting ownership of a TOTP second factor. Provided by
+ * {@link TotpMultiFactorGenerator.assertionForEnrollment} and
+ * {@link TotpMultiFactorGenerator.assertionForSignIn}.
+ *
+ * @public
+ */
+export declare interface TotpMultiFactorAssertion extends MultiFactorAssertion {
+}
+
+/**
+ * Provider for generating a {@link TotpMultiFactorAssertion}.
+ *
+ * @public
+ */
+export declare class TotpMultiFactorGenerator {
+    /**
+     * Provides a {@link TotpMultiFactorAssertion} to confirm ownership of
+     * the TOTP (time-based one-time password) second factor.
+     * This assertion is used to complete enrollment in TOTP second factor.
+     *
+     * @param secret A {@link TotpSecret} containing the shared secret key and other TOTP parameters.
+     * @param oneTimePassword One-time password from TOTP App.
+     * @returns A {@link TotpMultiFactorAssertion} which can be used with
+     * {@link MultiFactorUser.enroll}.
+     */
+    static assertionForEnrollment(secret: TotpSecret, oneTimePassword: string): TotpMultiFactorAssertion;
+    /**
+     * Provides a {@link TotpMultiFactorAssertion} to confirm ownership of the TOTP second factor.
+     * This assertion is used to complete signIn with TOTP as the second factor.
+     *
+     * @param enrollmentId identifies the enrolled TOTP second factor.
+     * @param oneTimePassword One-time password from TOTP App.
+     * @returns A {@link TotpMultiFactorAssertion} which can be used with
+     * {@link MultiFactorResolver.resolveSignIn}.
+     */
+    static assertionForSignIn(enrollmentId: string, oneTimePassword: string): TotpMultiFactorAssertion;
+    /**
+     * Returns a promise to {@link TotpSecret} which contains the TOTP shared secret key and other parameters.
+     * Creates a TOTP secret as part of enrolling a TOTP second factor.
+     * Used for generating a QR code URL or inputting into a TOTP app.
+     * This method uses the auth instance corresponding to the user in the multiFactorSession.
+     *
+     * @param session The {@link MultiFactorSession} that the user is part of.
+     * @returns A promise to {@link TotpSecret}.
+     */
+    static generateSecret(session: MultiFactorSession): Promise<TotpSecret>;
+    /**
+     * The identifier of the TOTP second factor: `totp`.
+     */
+    static FACTOR_ID: FactorId_2;
+}
+
+/**
+ * The subclass of the {@link MultiFactorInfo} interface for TOTP
+ * second factors. The `factorId` of this second factor is {@link FactorId}.TOTP.
+ * @public
+ */
+export declare interface TotpMultiFactorInfo extends MultiFactorInfo {
+}
+
+/**
+ * Provider for generating a {@link TotpMultiFactorAssertion}.
+ *
+ * Stores the shared secret key and other parameters to generate time-based OTPs.
+ * Implements methods to retrieve the shared secret key and generate a QR code URL.
+ * @public
+ */
+export declare class TotpSecret {
+    private readonly sessionInfo;
+    private readonly auth;
+    /**
+     * Shared secret key/seed used for enrolling in TOTP MFA and generating OTPs.
+     */
+    readonly secretKey: string;
+    /**
+     * Hashing algorithm used.
+     */
+    readonly hashingAlgorithm: string;
+    /**
+     * Length of the one-time passwords to be generated.
+     */
+    readonly codeLength: number;
+    /**
+     * The interval (in seconds) when the OTP codes should change.
+     */
+    readonly codeIntervalSeconds: number;
+    /**
+     * The timestamp (UTC string) by which TOTP enrollment should be completed.
+     */
+    readonly enrollmentCompletionDeadline: string;
+    private constructor();
+    /** @internal */
+    static _fromStartTotpMfaEnrollmentResponse(response: StartTotpMfaEnrollmentResponse, auth: AuthInternal): TotpSecret;
+    /** @internal */
+    _makeTotpVerificationInfo(otp: string): TotpVerificationInfo;
+    /**
+     * Returns a QR code URL as described in
+     * https://github.com/google/google-authenticator/wiki/Key-Uri-Format
+     * This can be displayed to the user as a QR code to be scanned into a TOTP app like Google Authenticator.
+     * If the optional parameters are unspecified, an accountName of <userEmail> and issuer of <firebaseAppName> are used.
+     *
+     * @param accountName the name of the account/app along with a user identifier.
+     * @param issuer issuer of the TOTP (likely the app name).
+     * @returns A QR code URL string.
+     */
+    generateQrCodeUrl(accountName?: string, issuer?: string): string;
+}
+
+declare interface TotpVerificationInfo {
+    sessionInfo: string;
+    verificationCode: string;
+}
+
 /**
  * Provider for generating an {@link OAuthCredential} for {@link ProviderId}.TWITTER.
  *