feat(sdk-core): add derivePasskeyPrfKey function

- fetch keychain webauthn devices and build PRF eval map
- trigger WebAuthn assertion via provider
- derive hex wallet passphrase from PRF output

Ticket: WCN-411

Author: derranW26

modules/sdk-core/package.json

@@ -40,6 +40,7 @@
     ]
   },
   "dependencies": {
+    "@bitgo/passkey-crypto": "^0.1.0",
     "@bitgo/public-types": "5.97.0",
     "@bitgo/sdk-lib-mpc": "^10.11.1",
     "@bitgo/secp256k1": "^1.11.0",

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';

modules/sdk-core/src/bitgo/passkey/derivePasskeyPrfKey.ts

@@ -0,0 +1,54 @@
+import {
+  buildEvalByCredential,
+  matchDeviceByCredentialId,
+  derivePassword,
+  type WebAuthnProvider,
+} from '@bitgo/passkey-crypto';
+import type { BitGoBase } from '../bitgoBase';
+import type { IWallet } from '../wallet/iWallet';
+
+/**
+ * Derives a wallet passphrase from a passkey PRF output.
+ *
+ * Fetches the wallet's user keychain, triggers a WebAuthn assertion with PRF
+ * evaluation, and returns a hex-encoded passphrase suitable for use as
+ * walletPassphrase in signing calls.
+ */
+export async function derivePasskeyPrfKey(params: {
+  bitgo: BitGoBase;
+  wallet: IWallet;
+  provider: WebAuthnProvider;
+}): Promise<string> {
+  const { wallet, provider } = params;
+
+  // Fetch the wallet's user keychain to get webauthnDevices
+  const keychain = await wallet.getEncryptedUserKeychain();
+  const devices = keychain.webauthnDevices;
+
+  if (!devices || devices.length === 0) {
+    throw new Error('No passkey devices available');
+  }
+
+  // Build PRF eval map from devices
+  const { evalByCredential } = buildEvalByCredential(devices as Parameters<typeof buildEvalByCredential>[0]);
+
+  if (Object.keys(evalByCredential).length === 0) {
+    throw new Error('No passkey devices available with a valid PRF salt');
+  }
+
+  // Trigger WebAuthn assertion with PRF evaluation
+  const result = await provider.get({
+    publicKey: { challenge: new Uint8Array() } as PublicKeyCredentialRequestOptions,
+    evalByCredential,
+  });
+
+  // Verify the credential matches a known device
+  matchDeviceByCredentialId(devices as Parameters<typeof matchDeviceByCredentialId>[0], result.credentialId);
+
+  // Derive and return hex-encoded wallet passphrase
+  if (!result.prfResult) {
+    throw new Error('PRF output was not returned by the authenticator');
+  }
+
+  return derivePassword(result.prfResult);
+}

modules/sdk-core/src/bitgo/passkey/index.ts

@@ -0,0 +1,3 @@
+export { derivePasskeyPrfKey } from './derivePasskeyPrfKey';
+export * from './registerPasskey';
+export * from './types';

modules/sdk-core/src/bitgo/passkey/registerPasskey.ts

@@ -0,0 +1,87 @@
+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()) 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/sdk-core/src/bitgo/passkey/types.ts

@@ -0,0 +1 @@
+export type { WebAuthnOtpDevice, WebAuthnProvider, PasskeyAuthResult, PasskeyGetOptions } from '@bitgo/passkey-crypto';

modules/sdk-core/test/unit/bitgo/passkey/derivePasskeyPrfKey.ts

@@ -0,0 +1,134 @@
+import * as assert from 'assert';
+import * as sinon from 'sinon';
+import { derivePasskeyPrfKey } from '../../../../src/bitgo/passkey/derivePasskeyPrfKey';
+
+describe('derivePasskeyPrfKey', function () {
+  const mockDevices = [
+    {
+      otpDeviceId: 'device-1',
+      authenticatorInfo: { credID: 'cred-aaa', fmt: 'none' as const, publicKey: 'pk-1' },
+      prfSalt: 'salt-aaa',
+      encryptedPrv: 'enc-prv-1',
+    },
+    {
+      otpDeviceId: 'device-2',
+      authenticatorInfo: { credID: 'cred-bbb', fmt: 'none' as const, publicKey: 'pk-2' },
+      prfSalt: 'salt-bbb',
+      encryptedPrv: 'enc-prv-2',
+    },
+  ];
+
+  function makeWallet(devices: typeof mockDevices | undefined) {
+    return {
+      getEncryptedUserKeychain: sinon.stub().resolves({
+        id: 'keychain-id',
+        pub: 'xpub123',
+        encryptedPrv: 'encrypted-prv',
+        type: 'independent',
+        webauthnDevices: devices,
+      }),
+    };
+  }
+
+  afterEach(function () {
+    sinon.restore();
+  });
+
+  it('should return a hex string on happy path', async function () {
+    const prfResult = new Uint8Array([0xde, 0xad, 0xbe, 0xef]).buffer;
+
+    const mockProvider = {
+      create: sinon.stub(),
+      get: sinon.stub().resolves({
+        prfResult,
+        credentialId: 'cred-aaa',
+        otpCode: 'otp-123',
+      }),
+    };
+
+    const wallet = makeWallet(mockDevices);
+
+    const result = await derivePasskeyPrfKey({
+      bitgo: {} as any,
+      wallet: wallet as any,
+      provider: mockProvider,
+    });
+
+    // derivePassword converts ArrayBuffer to hex
+    assert.strictEqual(result, 'deadbeef');
+    assert.ok(mockProvider.get.calledOnce);
+    // Verify evalByCredential was passed
+    const getCallArgs = mockProvider.get.firstCall.args[0];
+    assert.strictEqual(getCallArgs.evalByCredential['cred-aaa'], 'salt-aaa');
+    assert.strictEqual(getCallArgs.evalByCredential['cred-bbb'], 'salt-bbb');
+  });
+
+  it("should throw 'No passkey devices available' when no devices", async function () {
+    const wallet = makeWallet(undefined);
+    const mockProvider = { create: sinon.stub(), get: sinon.stub() };
+
+    await assert.rejects(
+      () => derivePasskeyPrfKey({ bitgo: {} as any, wallet: wallet as any, provider: mockProvider }),
+      (err: Error) => {
+        assert.strictEqual(err.message, 'No passkey devices available');
+        return true;
+      }
+    );
+  });
+
+  it("should throw 'No passkey devices available' when devices array is empty", async function () {
+    const wallet = makeWallet([] as any);
+    const mockProvider = { create: sinon.stub(), get: sinon.stub() };
+
+    await assert.rejects(
+      () => derivePasskeyPrfKey({ bitgo: {} as any, wallet: wallet as any, provider: mockProvider }),
+      (err: Error) => {
+        assert.strictEqual(err.message, 'No passkey devices available');
+        return true;
+      }
+    );
+  });
+
+  it("should throw 'No passkey devices available with a valid PRF salt' when no device has prfSalt", async function () {
+    const devicesWithoutSalt = [
+      {
+        otpDeviceId: 'device-1',
+        authenticatorInfo: { credID: 'cred-aaa', fmt: 'none' as const, publicKey: 'pk-1' },
+        prfSalt: '', // empty — buildEvalByCredential skips falsy prfSalt
+        encryptedPrv: 'enc-prv-1',
+      },
+    ];
+
+    const wallet = makeWallet(devicesWithoutSalt as any);
+    const mockProvider = { create: sinon.stub(), get: sinon.stub() };
+
+    await assert.rejects(
+      () => derivePasskeyPrfKey({ bitgo: {} as any, wallet: wallet as any, provider: mockProvider }),
+      (err: Error) => {
+        assert.strictEqual(err.message, 'No passkey devices available with a valid PRF salt');
+        return true;
+      }
+    );
+  });
+
+  it("should throw 'Could not identify which passkey device was used' when credentialId not found", async function () {
+    const mockProvider = {
+      create: sinon.stub(),
+      get: sinon.stub().resolves({
+        prfResult: new ArrayBuffer(32),
+        credentialId: 'unknown-cred-id',
+        otpCode: 'otp-123',
+      }),
+    };
+
+    const wallet = makeWallet(mockDevices);
+
+    await assert.rejects(
+      () => derivePasskeyPrfKey({ bitgo: {} as any, wallet: wallet as any, provider: mockProvider }),
+      (err: Error) => {
+        assert.strictEqual(err.message, 'Could not identify which passkey device was used');
+        return true;
+      }
+    );
+  });
+});