Merge pull request #18266 from mozilla/polish-auth-client-recovery-phone

polish(auth-client): Update auth client recovery-phone api

Author: dschom

packages/fxa-auth-client/lib/client.ts

@@ -2260,6 +2260,13 @@ export default class AuthClient {
     );
   }
 
+  /**
+   * Tries to register a recovery phone number
+   *
+   * @param sessionToken The user's current session token
+   * @param phoneNumber The phone number to register. Should be E.164 format
+   * @param headers
+   */
   async recoveryPhoneCreate(
     sessionToken: string,
     phoneNumber: string,
@@ -2273,6 +2280,11 @@ export default class AuthClient {
     );
   }
 
+  /**
+   * Checks to see if a recovery phone is available in the user's region.
+   * @param sessionToken The user's current session token
+   * @param headers
+   */
   async recoveryPhoneAvailable(sessionToken: string, headers?: Headers) {
     return this.sessionPost(
       '/recovery_phone/available',
@@ -2282,20 +2294,35 @@ export default class AuthClient {
     );
   }
 
-  async recoveryPhoneConfirm(
+  /**
+   * Confirms the code sent to the recovery phone when recoveryPhoneCreate was called.
+   *
+   * @param sessionToken The user's current session token
+   * @param code The otp code sent to the user's phone
+   * @param headers
+   */
+  async recoveryPhoneConfirmSetup(
     sessionToken: string,
     code: string,
     headers?: Headers
   ) {
     return this.sessionPost(
-      '/recovery_phone/available',
+      '/recovery_phone/confirm',
       sessionToken,
-      { code },
+      {
+        code,
+      },
       headers
     );
   }
 
-  async recoveryPhoneSendCode(sessionToken: string, headers?: Headers) {
+  /**
+   * Sends a code to the users phone during a signin flow.
+   *
+   * @param sessionToken The user's current session token
+   * @param headers
+   */
+  async recoveryPhoneSigninSendCode(sessionToken: string, headers?: Headers) {
     return this.sessionPost(
       '/recovery_phone/signin/send_code',
       sessionToken,
@@ -2304,10 +2331,48 @@ export default class AuthClient {
     );
   }
 
+  /**
+   * Confirms the code sent to the recovery phone during a sign in flow.
+   *
+   * @param sessionToken The user's current session token
+   * @param code The otp code sent to the user's phone
+   * @param headers
+   */
+  async recoveryPhoneSignInConfirm(
+    sessionToken: string,
+    code: string,
+    headers?: Headers
+  ) {
+    return this.sessionPost(
+      '/recovery_phone/signin/confirm',
+      sessionToken,
+      {
+        code,
+      },
+      headers
+    );
+  }
+
+  /**
+   * Removes a recovery phone from the user's account
+   *
+   * @param sessionToken The user's current session token
+   * @param headers
+   */
   async recoveryPhoneDelete(sessionToken: string, headers?: Headers) {
     return this.sessionDelete('/recovery_phone', sessionToken, {}, headers);
   }
 
+  /**
+   * Gets status of the recovery phone on the users account.\
+   * @param sessionToken The user's current session token
+   * @param headers
+   * @returns { exists:boolean, phoneNumber: string }
+   */
+  async recoveryPhoneGet(sessionToken: string, headers?: Headers) {
+    return this.sessionGet('/recovery_phone', sessionToken, headers);
+  }
+
   protected async getPayloadV2({
     kB,
     v1,

packages/fxa-auth-client/test/crypto.ts

@@ -12,7 +12,7 @@ import {
   randomKey,
   getRecoveryKeyIdByUid,
 } from 'fxa-auth-client/lib/recoveryKey';
-import { createSaltV1, createSaltV2 } from '../lib/salt';
+import { createSaltV2 } from '../lib/salt';
 import { hexToUint8 } from 'fxa-auth-client/lib/utils';
 
 const uid = 'aaaaabbbbbcccccdddddeeeeefffff00';
@@ -52,7 +52,7 @@ describe('lib/crypto', () => {
     it('returns the correct authPW and unwrapBKey with V2 salt', async () => {
       const password = 'pässwörd';
       const clientSalt = createSaltV2('0123456789abcdef0123456789abcdef');
-      const keys = await getCredentialsV2({password, clientSalt});
+      const keys = await getCredentialsV2({ password, clientSalt });
       assert.equal(
         keys.authPW,
         'd278c764bd1852a14bfc4e9d8c1682b4f1a57edb9a9372bf8c370cc41592155b'