feat(sdk-core): add registerPasskey function

TICKET: WCN-188

Author: derranW26

modules/passkey-crypto/package.json

@@ -35,6 +35,7 @@
   },
   "dependencies": {
     "@bitgo/public-types": "6.1.0",
+    "@bitgo/sdk-core": "^36.42.0",
     "@bitgo/sjcl": "^1.1.0"
   },
   "devDependencies": {

modules/passkey-crypto/src/index.ts

@@ -1,4 +1,5 @@
 export { derivePassword } from './derivePassword';
+export { registerPasskey } from './registerPasskey';
 export { deriveEnterpriseSalt } from './deriveEnterpriseSalt';
 export { buildEvalByCredential, matchDeviceByCredentialId } from './prfHelpers';
 export type { WebAuthnOtpDevice, PasskeyAuthResult, PasskeyGetOptions, WebAuthnProvider } from './webAuthnTypes';

modules/passkey-crypto/src/registerPasskey.ts

@@ -0,0 +1,87 @@
+import { BitGoBase } from '@bitgo/sdk-core';
+import { WebAuthnOtpDevice, WebAuthnProvider } from './webAuthnTypes';
+
+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()) as 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()) as RegisterOtpResponse;
+
+  // Step 6: Return WebAuthnOtpDevice + prfSupported
+  return {
+    id: response.id,
+    credentialId: response.credentialId,
+    prfSalt: response.prfSalt,
+    isPasskey: response.isPasskey,
+    extensions: response.extensions,
+    prfSupported,
+  };
+}

modules/passkey-crypto/test/unit/registerPasskey.test.ts

@@ -0,0 +1,139 @@
+import * as assert from 'assert';
+import * as sinon from 'sinon';
+import { registerPasskey } from '../../src/registerPasskey';
+
+describe('registerPasskey', function () {
+  let mockBitGo: {
+    get: sinon.SinonStub;
+    put: sinon.SinonStub;
+    url: sinon.SinonStub;
+  };
+
+  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 unknown 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}`),
+    };
+  });
+
+  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() };
+
+      mockBitGo.get.returns({ result: sinon.stub().resolves(mockChallenge) });
+      const sendStub = sinon.stub().returns({ result: sinon.stub().resolves(mockOtpResponse) });
+      mockBitGo.put.returns({ send: sendStub });
+
+      const result = await registerPasskey({
+        bitgo: mockBitGo as never,
+        provider: mockProvider,
+        label: 'My Passkey',
+      });
+
+      assert.ok(mockBitGo.get.calledWith('/api/v2/user/otp/webauthn/register'), 'GET should call correct URL');
+      assert.ok(mockBitGo.put.calledWith('/api/v2/user/otp'), 'PUT should call correct URL');
+
+      const putBody = sendStub.firstCall.args[0] as Record<string, unknown>;
+      assert.deepStrictEqual(putBody.scopes, ['prf']);
+      assert.strictEqual(putBody.type, 'webauthn');
+      assert.strictEqual(putBody.label, 'My Passkey');
+
+      assert.strictEqual(result.id, mockOtpResponse.id);
+      assert.strictEqual(result.credentialId, mockOtpResponse.credentialId);
+      assert.strictEqual(result.prfSalt, mockOtpResponse.prfSalt);
+      assert.strictEqual(result.prfSupported, true);
+    });
+  });
+
+  describe('without PRF output', function () {
+    it('should omit scopes from PUT payload and return prfSupported: false', async function () {
+      const mockProvider = { create: sinon.stub().resolves(makeAttestation(undefined)), get: sinon.stub() };
+
+      mockBitGo.get.returns({ result: sinon.stub().resolves(mockChallenge) });
+      const sendStub = sinon.stub().returns({ result: sinon.stub().resolves(mockOtpResponse) });
+      mockBitGo.put.returns({ send: sendStub });
+
+      const result = await registerPasskey({
+        bitgo: mockBitGo as never,
+        provider: mockProvider,
+        label: 'My Passkey No PRF',
+      });
+
+      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(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(),
+      };
+
+      mockBitGo.get.returns({
+        result: sinon.stub().callsFake(() => {
+          callOrder.push('GET challenge');
+          return Promise.resolve(mockChallenge);
+        }),
+      });
+      mockBitGo.put.returns({ send: sinon.stub().returns({ result: sinon.stub().resolves(mockOtpResponse) }) });
+
+      await registerPasskey({ bitgo: mockBitGo as never, provider: mockProvider, label: 'Test' });
+
+      assert.deepStrictEqual(callOrder, ['GET challenge', 'provider.create']);
+    });
+  });
+});