feat(sdk-core): add registerPasskey function

derranW26 · derranW26 · commit decca2c96419 · 2026-04-28T10:38:53.000-04:00
TICKET: WCN-188
diff --git a/modules/sdk-core/src/bitgo/index.ts b/modules/sdk-core/src/bitgo/index.ts
@@ -17,6 +17,7 @@ export * from './internal';
 export * from './keychain';
 export * as bitcoin from './legacyBitcoin';
 export * from './market';
+export * from './passkey';
 export * from './pendingApproval';
 export { WalletProofs } from './proofs';
 export * from './recovery';
diff --git a/modules/sdk-core/src/bitgo/passkey/index.ts b/modules/sdk-core/src/bitgo/passkey/index.ts
@@ -0,0 +1,2 @@
+export * from './registerPasskey';
+export * from './types';
diff --git a/modules/sdk-core/src/bitgo/passkey/registerPasskey.ts b/modules/sdk-core/src/bitgo/passkey/registerPasskey.ts
@@ -0,0 +1,85 @@
+import { BitGoBase } from '../bitgoBase';
+import { WebAuthnOtpDevice, WebAuthnProvider } from './types';
+
+interface RegisterChallengeResponse {
+  challenge: string;
+  baseSalt: string;
+  rp: PublicKeyCredentialRpEntity;
+  user: PublicKeyCredentialUserEntity;
+  pubKeyCredParams: PublicKeyCredentialParameters[];
+  timeout?: number;
+  excludeCredentials?: PublicKeyCredentialDescriptor[];
+  authenticatorSelection?: AuthenticatorSelectionCriteria;
+  attestation?: AttestationConveyancePreference;
+  extensions?: AuthenticationExtensionsClientInputs;
+}
+
+interface RegisterOtpResponse {
+  id: string;
+  credentialId: string;
+  prfSalt?: string;
+  isPasskey?: boolean;
+  extensions?: Record<string, boolean>;
+}
+
+export async function registerPasskey(params: {
+  bitgo: BitGoBase;
+  provider: WebAuthnProvider;
+  label: string;
+}): Promise<WebAuthnOtpDevice & { prfSupported: boolean }> {
+  const { bitgo, provider, label } = params;
+
+  // Step 1: Fetch server challenge (contains baseSalt)
+  const challenge = await bitgo.get(bitgo.url('/user/otp/webauthn/register', 2)).result<RegisterChallengeResponse>();
+
+  // Step 2: Pass challenge to provider.create() — browser returns attestation
+  const attestation = await provider.create({
+    challenge: Uint8Array.from(atob(challenge.challenge), (c) => c.charCodeAt(0)),
+    rp: challenge.rp,
+    user: challenge.user,
+    pubKeyCredParams: challenge.pubKeyCredParams,
+    timeout: challenge.timeout,
+    excludeCredentials: challenge.excludeCredentials,
+    authenticatorSelection: challenge.authenticatorSelection,
+    attestation: challenge.attestation,
+    extensions: challenge.extensions,
+  });
+
+  const attestationResponse = attestation.response as AuthenticatorAttestationResponse;
+
+  // Step 3: Check if PRF output is present in the attestation response
+  const clientExtensionResults = attestation.getClientExtensionResults() as {
+    prf?: { results?: { first?: ArrayBuffer } };
+  };
+  const prfOutput = clientExtensionResults.prf?.results?.first;
+  const prfSupported = prfOutput !== undefined;
+
+  // Step 4: Build payload — include scopes only if PRF output is present
+  const otpPayload = {
+    clientDataJSON: btoa(String.fromCharCode(...new Uint8Array(attestationResponse.clientDataJSON))),
+    attestationObject: btoa(String.fromCharCode(...new Uint8Array(attestationResponse.attestationObject))),
+  };
+
+  const putBody: Record<string, unknown> = {
+    otp: JSON.stringify(otpPayload),
+    type: 'webauthn',
+    label,
+  };
+
+  if (prfSupported) {
+    putBody.scopes = ['prf'];
+  }
+
+  // Step 5: PUT /api/v2/user/otp
+  const response = await bitgo.put(bitgo.url('/user/otp', 2)).send(putBody).result<RegisterOtpResponse>();
+
+  // Step 6: Return WebAuthnOtpDevice + prfSupported
+  return {
+    id: response.id,
+    credentialId: response.credentialId,
+    prfSalt: response.prfSalt,
+    isPasskey: response.isPasskey,
+    extensions: response.extensions,
+    prfSupported,
+  };
+}
diff --git a/modules/sdk-core/src/bitgo/passkey/types.ts b/modules/sdk-core/src/bitgo/passkey/types.ts
@@ -0,0 +1,18 @@
+// TODO: replace with: export type { WebAuthnOtpDevice } from '@bitgo/public-types'
+export interface WebAuthnOtpDevice {
+  id: string; // serialized MongoDB _id — used for DELETE
+  credentialId: string; // from authenticatorInfo.credID — used for PRF eval map
+  prfSalt?: string;
+  isPasskey?: boolean;
+  extensions?: Record<string, boolean>;
+}
+
+// Stays local permanently — never moves to public-types
+export interface WebAuthnProvider {
+  create(options: PublicKeyCredentialCreationOptions): Promise<PublicKeyCredential>;
+  get(
+    options: PublicKeyCredentialRequestOptions & {
+      evalByCredential?: Record<string, string>;
+    }
+  ): Promise<{ otpCode: string; prfOutput: ArrayBuffer | undefined; credentialId: string }>;
+}
diff --git a/modules/sdk-core/test/unit/bitgo/passkey/registerPasskey.ts b/modules/sdk-core/test/unit/bitgo/passkey/registerPasskey.ts
@@ -0,0 +1,179 @@
+import * as assert from 'assert';
+import * as sinon from 'sinon';
+import 'should';
+import { registerPasskey } from '../../../../src/bitgo/passkey/registerPasskey';
+
+describe('registerPasskey', function () {
+  let mockBitGo: sinon.SinonStubbedInstance<{
+    get: (url: string) => { result: <T>() => Promise<T> };
+    put: (url: string) => { send: (body: unknown) => { result: <T>() => Promise<T> } };
+    url: (path: string, version?: number) => string;
+  }>;
+
+  const mockChallenge = {
+    challenge: btoa('server-challenge-bytes'),
+    baseSalt: 'server-base-salt-abc123',
+    rp: { id: 'bitgo.com', name: 'BitGo' },
+    user: { id: new Uint8Array([1, 2, 3]), name: 'test@bitgo.com', displayName: 'Test User' },
+    pubKeyCredParams: [{ type: 'public-key' as const, alg: -7 }],
+    timeout: 60000,
+  };
+
+  const mockOtpResponse = {
+    id: 'mongo-device-id-123',
+    credentialId: 'cred-id-base64',
+    prfSalt: 'server-assigned-prf-salt',
+    isPasskey: true,
+    extensions: { prf: true },
+  };
+
+  const clientDataJSON = new TextEncoder().encode(JSON.stringify({ type: 'webauthn.create' }));
+  const attestationObject = new Uint8Array([0xde, 0xad, 0xbe, 0xef]);
+
+  function makeAttestation(prfFirst?: ArrayBuffer): PublicKeyCredential {
+    return {
+      id: 'cred-id-base64',
+      rawId: new ArrayBuffer(8),
+      type: 'public-key',
+      response: {
+        clientDataJSON: clientDataJSON.buffer,
+        attestationObject: attestationObject.buffer,
+        getTransports: () => [],
+      } as AuthenticatorAttestationResponse,
+      authenticatorAttachment: null,
+      getClientExtensionResults: () =>
+        prfFirst !== undefined
+          ? ({ prf: { results: { first: prfFirst } } } as unknown as AuthenticationExtensionsClientOutputs)
+          : ({} as AuthenticationExtensionsClientOutputs),
+    } as unknown as PublicKeyCredential;
+  }
+
+  beforeEach(function () {
+    mockBitGo = {
+      get: sinon.stub(),
+      put: sinon.stub(),
+      url: sinon.stub().callsFake((path: string, _version?: number) => `/api/v2${path}`),
+    } as unknown as typeof mockBitGo;
+  });
+
+  afterEach(function () {
+    sinon.restore();
+  });
+
+  describe('with PRF output present', function () {
+    it('should include scopes in PUT payload and return prfSupported: true', async function () {
+      const prfOutput = new ArrayBuffer(32);
+      const attestation = makeAttestation(prfOutput);
+
+      const mockProvider = {
+        create: sinon.stub().resolves(attestation),
+        get: sinon.stub(),
+      };
+
+      const getResultStub = sinon.stub().resolves(mockChallenge);
+      (mockBitGo.get as sinon.SinonStub).returns({ result: getResultStub });
+
+      const sendStub = sinon.stub().returns({ result: sinon.stub().resolves(mockOtpResponse) });
+      (mockBitGo.put as sinon.SinonStub).returns({ send: sendStub });
+
+      const result = await registerPasskey({
+        bitgo: mockBitGo as unknown as Parameters<typeof registerPasskey>[0]['bitgo'],
+        provider: mockProvider,
+        label: 'My Passkey',
+      });
+
+      // Verify GET challenge called
+      assert.ok((mockBitGo.get as sinon.SinonStub).calledOnce, 'GET challenge should be called');
+      assert.ok(
+        (mockBitGo.get as sinon.SinonStub).calledWith('/api/v2/user/otp/webauthn/register'),
+        'GET should call correct URL'
+      );
+
+      // Verify PUT called with scopes
+      const putBody = sendStub.firstCall.args[0] as Record<string, unknown>;
+      assert.ok(putBody.scopes !== undefined, 'scopes should be present when PRF output exists');
+      assert.deepStrictEqual(putBody.scopes, ['prf']);
+      assert.strictEqual(putBody.type, 'webauthn');
+      assert.strictEqual(putBody.label, 'My Passkey');
+
+      // Verify PUT uses correct endpoint
+      assert.ok((mockBitGo.put as sinon.SinonStub).calledWith('/api/v2/user/otp'), 'PUT should call correct URL');
+
+      // Verify return shape
+      assert.strictEqual(result.id, mockOtpResponse.id);
+      assert.strictEqual(result.credentialId, mockOtpResponse.credentialId);
+      assert.strictEqual(result.prfSalt, mockOtpResponse.prfSalt);
+      assert.strictEqual(result.isPasskey, mockOtpResponse.isPasskey);
+      assert.strictEqual(result.prfSupported, true);
+    });
+  });
+
+  describe('without PRF output', function () {
+    it('should omit scopes from PUT payload and return prfSupported: false', async function () {
+      const attestation = makeAttestation(undefined);
+
+      const mockProvider = {
+        create: sinon.stub().resolves(attestation),
+        get: sinon.stub(),
+      };
+
+      const getResultStub = sinon.stub().resolves(mockChallenge);
+      (mockBitGo.get as sinon.SinonStub).returns({ result: getResultStub });
+
+      const sendStub = sinon.stub().returns({ result: sinon.stub().resolves(mockOtpResponse) });
+      (mockBitGo.put as sinon.SinonStub).returns({ send: sendStub });
+
+      const result = await registerPasskey({
+        bitgo: mockBitGo as unknown as Parameters<typeof registerPasskey>[0]['bitgo'],
+        provider: mockProvider,
+        label: 'My Passkey No PRF',
+      });
+
+      // Verify scopes omitted
+      const putBody = sendStub.firstCall.args[0] as Record<string, unknown>;
+      assert.ok(putBody.scopes === undefined, 'scopes should be omitted when PRF output is absent');
+      assert.strictEqual(putBody.type, 'webauthn');
+      assert.strictEqual(putBody.label, 'My Passkey No PRF');
+
+      // Verify return shape
+      assert.strictEqual(result.id, mockOtpResponse.id);
+      assert.strictEqual(result.credentialId, mockOtpResponse.credentialId);
+      assert.strictEqual(result.prfSupported, false);
+    });
+  });
+
+  describe('baseSalt sourcing', function () {
+    it('should call GET challenge before provider.create()', async function () {
+      const callOrder: string[] = [];
+
+      const mockProvider = {
+        create: sinon.stub().callsFake(() => {
+          callOrder.push('provider.create');
+          return Promise.resolve(makeAttestation());
+        }),
+        get: sinon.stub(),
+      };
+
+      const getResultStub = sinon.stub().callsFake(() => {
+        callOrder.push('GET challenge');
+        return Promise.resolve(mockChallenge);
+      });
+      (mockBitGo.get as sinon.SinonStub).returns({ result: getResultStub });
+
+      const sendStub = sinon.stub().returns({ result: sinon.stub().resolves(mockOtpResponse) });
+      (mockBitGo.put as sinon.SinonStub).returns({ send: sendStub });
+
+      await registerPasskey({
+        bitgo: mockBitGo as unknown as Parameters<typeof registerPasskey>[0]['bitgo'],
+        provider: mockProvider,
+        label: 'Test',
+      });
+
+      assert.deepStrictEqual(
+        callOrder,
+        ['GET challenge', 'provider.create'],
+        'GET challenge must precede provider.create'
+      );
+    });
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export * from './registerPasskey';`
	`2`	`+export * from './types';`