feat: prepare credential creation skeleton and its tests

Author: jakubstec

src/components/MultifactorAuthentication/biometrics/operations/index.native.ts

@@ -1,3 +1,4 @@
+import type {CreateCredentialParams, CreateCredentialResult} from '@components/MultifactorAuthentication/biometrics/shared/types';
 import addMFABreadcrumb from '@components/MultifactorAuthentication/observability/breadcrumbs';
 
 import {decodeLibraryError, getKeyAlias} from '@libs/MultifactorAuthentication/NativeBiometricsHSM/helpers';
@@ -11,8 +12,9 @@ import {getAllKeys, isSensorAvailable} from '@sbaiahmed1/react-native-biometrics
 import {mfaCredentialIDsSelector} from '@selectors/Account';
 
 /**
- * Platform-resolved biometric operations for the MFA machine's pre-screen checks. These functions
- * read no React state, so the machine actors and other non-React callers can import them directly.
+ * Platform-resolved biometric operations for the MFA machine's pre-screen checks and credential
+ * creation ceremony. These functions read no React state, so the machine actors and other
+ * non-React callers can import them directly.
  */
 
 /** The authentication method this platform verifies with. Native verifies with HSM-backed biometrics. */
@@ -58,4 +60,9 @@ async function areLocalCredentialsKnownToServer(accountID: number, signal?: Abor
     return (mfaCredentialIDsSelector(account) ?? []).includes(localCredentialID);
 }
 
-export {areLocalCredentialsKnownToServer, deviceVerificationType, deviceCheckFailureReason, doesDeviceSupportAuthenticationMethod};
+/** Runs the platform HSM key-creation ceremony. */
+async function createCredential(params: CreateCredentialParams): Promise<CreateCredentialResult> {
+    throw new Error('Not implemented');
+}
+
+export {areLocalCredentialsKnownToServer, createCredential, deviceVerificationType, deviceCheckFailureReason, doesDeviceSupportAuthenticationMethod};

src/components/MultifactorAuthentication/biometrics/operations/index.ts

@@ -1,3 +1,5 @@
+import type {CreateCredentialParams, CreateCredentialResult} from '@components/MultifactorAuthentication/biometrics/shared/types';
+
 import {isWebAuthnSupported} from '@libs/MultifactorAuthentication/Passkeys/WebAuthn';
 import readOnyxValueOnce from '@libs/MultifactorAuthentication/shared/readOnyxValueOnce';
 
@@ -9,8 +11,9 @@ import ONYXKEYS from '@src/ONYXKEYS';
 import {mfaCredentialIDsSelector} from '@selectors/Account';
 
 /**
- * Platform-resolved biometric operations for the MFA machine's pre-screen checks. These functions
- * read no React state, so the machine actors and other non-React callers can import them directly.
+ * Platform-resolved biometric operations for the MFA machine's pre-screen checks and credential
+ * creation ceremony. These functions read no React state, so the machine actors and other
+ * non-React callers can import them directly.
  */
 
 /** The authentication method this platform verifies with. Web verifies with passkeys. */
@@ -37,4 +40,9 @@ async function areLocalCredentialsKnownToServer(accountID: number, signal?: Abor
     return (localPasskeyCredentials ?? []).some((credential) => serverKnownCredentialIDs.has(credential.id));
 }
 
-export {areLocalCredentialsKnownToServer, deviceVerificationType, deviceCheckFailureReason, doesDeviceSupportAuthenticationMethod};
+/** Runs the platform passkey ceremony and persists the resulting credential locally. */
+async function createCredential(params: CreateCredentialParams): Promise<CreateCredentialResult> {
+    throw new Error('Not implemented');
+}
+
+export {areLocalCredentialsKnownToServer, createCredential, deviceVerificationType, deviceCheckFailureReason, doesDeviceSupportAuthenticationMethod};

src/components/MultifactorAuthentication/biometrics/shared/types.ts

@@ -1,5 +1,5 @@
 import type {AuthenticationChallenge, RegistrationChallenge, SignedChallenge} from '@libs/MultifactorAuthentication/shared/challengeTypes';
-import type {MFAError} from '@libs/MultifactorAuthentication/shared/MFAResult';
+import type {MFAError, MFAResult} from '@libs/MultifactorAuthentication/shared/MFAResult';
 import type {AuthTypeInfo, RegistrationKeyInfo} from '@libs/MultifactorAuthentication/shared/types';
 
 type BaseRegisterResult = {
@@ -15,6 +15,18 @@ type RegisterResult =
           error: MFAError;
       } & Partial<BaseRegisterResult>);
 
+/**
+ * Params for the platform-resolved credential-creation ceremony. A params object (not positional
+ * args) keeps both platform signatures identical while native simply ignores `signal`.
+ */
+type CreateCredentialParams = {
+    accountID: number;
+    registrationChallenge: RegistrationChallenge;
+    signal?: AbortSignal;
+};
+
+type CreateCredentialResult = MFAResult<{keyInfo: RegistrationKeyInfo}>;
+
 type AuthorizeParams = {
     challenge: AuthenticationChallenge;
 };
@@ -58,4 +70,4 @@ type UseBiometricsReturn = {
     deleteLocalKeysForAccount: () => Promise<void>;
 };
 
-export type {RegisterResult, AuthorizeParams, AuthorizeResult, UseBiometricsReturn};
+export type {RegisterResult, AuthorizeParams, AuthorizeResult, UseBiometricsReturn, CreateCredentialParams, CreateCredentialResult};

src/components/MultifactorAuthentication/machine/mfaActors.ts

@@ -10,7 +10,15 @@ import {getDeviceBiometricsOnyxKey, requestRegistrationChallenge} from '@userAct
 
 import {fromPromise} from 'xstate';
 
-import type {CheckLocalCredentialsInput, ReadHasAcceptedSoftPromptInput, RequestRegistrationChallengeInput, RequestRegistrationChallengeOutput, ValidateDeviceInput} from './types';
+import type {
+    CheckLocalCredentialsInput,
+    CreateCredentialInput,
+    CreateCredentialOutput,
+    ReadHasAcceptedSoftPromptInput,
+    RequestRegistrationChallengeInput,
+    RequestRegistrationChallengeOutput,
+    ValidateDeviceInput,
+} from './types';
 
 /**
  * A refused device resolves as a failed MFAResult, so the machine's onError transition for this
@@ -45,12 +53,26 @@ const requestRegistrationChallengeActor = fromPromise<RequestRegistrationChallen
     return {success: true, challenge};
 });
 
+/**
+ * Turns a pending registration challenge into a real credential: platform ceremony, then backend
+ * registration.
+ */
+const createCredentialActor = fromPromise<CreateCredentialOutput, CreateCredentialInput>(async () => {
+    throw new Error('Not implemented');
+});
+
 /**
  * Builds the side-effect actors that the machine states invoke. The machine is always created with
  * these working implementations, so no caller needs to provide stubs or overrides.
  */
 function createActors() {
-    return {validateDevice, readHasAcceptedSoftPrompt, checkLocalCredentials, requestRegistrationChallenge: requestRegistrationChallengeActor};
+    return {
+        validateDevice,
+        readHasAcceptedSoftPrompt,
+        checkLocalCredentials,
+        requestRegistrationChallenge: requestRegistrationChallengeActor,
+        createCredential: createCredentialActor,
+    };
 }
 
 export default createActors;

src/components/MultifactorAuthentication/machine/types.ts

@@ -1,4 +1,5 @@
 import type {AllowedAuthenticationMethods} from '@components/MultifactorAuthentication/biometrics/checkDeviceEligibility';
+import type {CreateCredentialParams} from '@components/MultifactorAuthentication/biometrics/shared/types';
 import type {MultifactorAuthenticationScenarioConfigFor} from '@components/MultifactorAuthentication/config';
 import type {
     MultifactorAuthenticationScenario,
@@ -89,8 +90,16 @@ type RequestRegistrationChallengeInput = {validateCode: string};
 /** A successful response must carry the validated registration challenge. */
 type RequestRegistrationChallengeOutput = MFAResult<{challenge: RegistrationChallenge}>;
 
+/** Input the machine passes to the credential-creation actor: everything `CreateCredentialParams` needs except the abort signal, which the actor supplies itself. */
+type CreateCredentialInput = Omit<CreateCredentialParams, 'signal'>;
+
+/** The credential-creation actor's result. `keyInfo` never leaves the actor, so a success carries no additional data. */
+type CreateCredentialOutput = MFAResult;
+
 export type {
     CheckLocalCredentialsInput,
+    CreateCredentialInput,
+    CreateCredentialOutput,
     MfaContext,
     MfaEvent,
     MfaModalState,

src/libs/MultifactorAuthentication/shared/VALUES.ts

@@ -230,6 +230,7 @@ const MFA_STATE = {
     REQUESTING_REGISTRATION_CHALLENGE: 'requestingRegistrationChallenge',
     PROMPT: 'prompt',
     AWAITING_SOFT_PROMPT: 'awaitingSoftPrompt',
+    CREATING_CREDENTIAL: 'creatingCredential',
     OUTCOME: 'outcome',
     RESOLVING_OUTCOME: 'resolvingOutcome',
     SUCCESS: 'success',

tests/unit/components/MultifactorAuthentication/biometricsOperations.test.ts

@@ -2,34 +2,47 @@
 // (operations/index.native.ts), which checks the HSM biometric sensor.
 import {
     areLocalCredentialsKnownToServer,
+    createCredential,
     deviceCheckFailureReason,
     deviceVerificationType,
     doesDeviceSupportAuthenticationMethod,
 } from '@components/MultifactorAuthentication/biometrics/operations';
 
+import type {RegistrationChallenge} from '@libs/MultifactorAuthentication/shared/challengeTypes';
 import VALUES from '@libs/MultifactorAuthentication/VALUES';
 
 import CONST from '@src/CONST';
 import ONYXKEYS from '@src/ONYXKEYS';
+import Base64URL from '@src/utils/Base64URL';
 
 import Onyx from 'react-native-onyx';
 import waitForBatchedUpdates from 'tests/utils/waitForBatchedUpdates';
 
 const mockIsSensorAvailable = jest.fn();
 const mockGetAllKeys = jest.fn();
+const mockCreateKeys = jest.fn();
 
 jest.mock('@sbaiahmed1/react-native-biometrics', () => ({
     // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     isSensorAvailable: (...args: unknown[]) => mockIsSensorAvailable(...args),
     // eslint-disable-next-line @typescript-eslint/no-unsafe-return
     getAllKeys: (...args: unknown[]) => mockGetAllKeys(...args),
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    createKeys: (...args: unknown[]) => mockCreateKeys(...args),
 }));
 
 const ACCOUNT_ID = 12345;
 // The keystore returns the public key as plain base64 while the server stores base64url IDs, so the
 // characters below only match after the module's base64url conversion.
 const LOCAL_PUBLIC_KEY_BASE64 = 'Ab+/cd==';
 const LOCAL_CREDENTIAL_ID = 'Ab-_cd';
+const REGISTRATION_CHALLENGE: RegistrationChallenge = {
+    challenge: 'native-registration-challenge',
+    rp: {id: 'expensify.com'},
+    user: {id: 'native-test-user', displayName: 'Native Test User'},
+    pubKeyCredParams: [{type: 'public-key', alg: -7}],
+    timeout: 60000,
+};
 
 describe('biometrics operations (native)', () => {
     beforeEach(() => {
@@ -97,4 +110,49 @@ describe('biometrics operations (native)', () => {
             await expect(areLocalCredentialsKnownToServer(ACCOUNT_ID)).resolves.toBe(false);
         });
     });
+
+    // Mirrors the `register` cases in useNativeBiometricsHSM.test.ts, which move over here when that
+    // hook is deleted.
+    describe('createCredential', () => {
+        beforeEach(() => {
+            mockCreateKeys.mockResolvedValue({publicKey: LOCAL_PUBLIC_KEY_BASE64});
+        });
+
+        it('creates the HSM key with the account-specific alias', async () => {
+            await createCredential({accountID: ACCOUNT_ID, registrationChallenge: REGISTRATION_CHALLENGE});
+
+            expect(mockCreateKeys).toHaveBeenCalledWith('12345_HSM_KEY', 'ec256', undefined, true, false);
+        });
+
+        it('returns the exact NativeBiometricsHSMKeyInfo shape on success', async () => {
+            const result = await createCredential({accountID: ACCOUNT_ID, registrationChallenge: REGISTRATION_CHALLENGE});
+
+            expect(result).toEqual({
+                success: true,
+                keyInfo: {
+                    rawId: LOCAL_CREDENTIAL_ID,
+                    type: CONST.MULTIFACTOR_AUTHENTICATION.BIOMETRICS_HSM_TYPE,
+                    response: {
+                        clientDataJSON: Base64URL.encode(JSON.stringify({challenge: REGISTRATION_CHALLENGE.challenge})),
+                        biometric: {
+                            publicKey: LOCAL_CREDENTIAL_ID,
+                            algorithm: CONST.COSE_ALGORITHM.ES256,
+                        },
+                    },
+                },
+            });
+        });
+
+        it('returns a failed result with the mapped reason when the library throws', async () => {
+            mockCreateKeys.mockRejectedValue(Object.assign(new Error('Key creation failed'), {code: 'CREATE_KEYS_ERROR'}));
+
+            const result = await createCredential({accountID: ACCOUNT_ID, registrationChallenge: REGISTRATION_CHALLENGE});
+
+            expect(result.success).toBe(false);
+            if (result.success) {
+                throw new Error('Expected credential creation to fail');
+            }
+            expect(result.error.reason).toBe(CONST.MULTIFACTOR_AUTHENTICATION.REASON.LOCAL_ERRORS.HSM.KEY_CREATION_FAILED);
+        });
+    });
 });