feat(sdk-core): WCN-187 add passkey types, WebAuthnProvider interface, and PRF helpers

- PasskeyDevice, PasskeyAuthResult, WebAuthnProvider types in passkey/types.ts
- buildEvalByCredential: maps credId → prfSalt for WebAuthn PRF evalByCredential
- matchDeviceByCredentialId: finds device by asserting credential ID, throws descriptively
- Unit tests for both PRF helpers (happy path + not-found cases)

TICKET: WCN-187

Author: derranW26

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

@@ -0,0 +1,2 @@
+export { PasskeyDevice, PasskeyAuthResult, WebAuthnProvider } from './types';
+export { buildEvalByCredential, matchDeviceByCredentialId } from './prfHelpers';

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

@@ -0,0 +1,32 @@
+import { PasskeyDevice } from './types';
+
+/**
+ * Builds the `evalByCredential` map passed to `WebAuthnProvider.get()`.
+ * Maps each device's credId to its prfSalt so the authenticator can
+ * evaluate the PRF with the correct salt for whichever credential it selects.
+ *
+ * @param devices - passkey devices stored on the keychain
+ * @returns a map of { [credId]: prfSalt }
+ */
+export function buildEvalByCredential(devices: PasskeyDevice[]): Record<string, string> {
+  return Object.fromEntries(devices.map((d) => [d.credId, d.prfSalt]));
+}
+
+/**
+ * Finds the PasskeyDevice whose credId matches the credential ID returned
+ * by the WebAuthn assertion.
+ *
+ * @param devices - passkey devices stored on the keychain
+ * @param credentialId - base64url credential ID from the WebAuthn assertion
+ * @throws if no device matches
+ */
+export function matchDeviceByCredentialId(devices: PasskeyDevice[], credentialId: string): PasskeyDevice {
+  const device = devices.find((d) => d.credId === credentialId);
+  if (!device) {
+    throw new Error(
+      `No passkey device found matching credential ID "${credentialId}". ` +
+        `Known credential IDs: [${devices.map((d) => d.credId).join(', ')}]`
+    );
+  }
+  return device;
+}

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

@@ -0,0 +1,23 @@
+export interface PasskeyDevice {
+  /** MongoDB ObjectId — used for deletion API calls */
+  otpDeviceId: string;
+  /** base64url WebAuthn credential ID — used for PRF evalByCredential map */
+  credId: string;
+  /** Enterprise-scoped PRF salt stored on the keychain */
+  prfSalt: string;
+  /** SJCL-encrypted private key (present once passkey is attached to a wallet keychain) */
+  encryptedPrv?: string;
+}
+
+export interface PasskeyAuthResult {
+  /** Raw PRF output from a WebAuthn assertion */
+  prfResult: ArrayBuffer;
+  /** base64url credential ID returned by the authenticator — matches PasskeyDevice.credId */
+  credentialId: string;
+  otpCode?: string;
+}
+
+export interface WebAuthnProvider {
+  create(options: PublicKeyCredentialCreationOptions): Promise<PublicKeyCredential>;
+  get(options: PublicKeyCredentialRequestOptions): Promise<PublicKeyCredential>;
+}

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

@@ -0,0 +1 @@
+export { WebAuthnProvider } from './types';

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

@@ -0,0 +1,63 @@
+import * as assert from 'assert';
+import { buildEvalByCredential, matchDeviceByCredentialId } from '../../../../src/bitgo/passkey/prfHelpers';
+import { PasskeyDevice } from '../../../../src/bitgo/passkey/types';
+
+const device1: PasskeyDevice = {
+  otpDeviceId: 'oid-1',
+  credId: 'cred-aaa',
+  prfSalt: 'salt-aaa',
+  encryptedPrv: 'enc-prv-1',
+};
+
+const device2: PasskeyDevice = {
+  otpDeviceId: 'oid-2',
+  credId: 'cred-bbb',
+  prfSalt: 'salt-bbb',
+};
+
+describe('buildEvalByCredential', function () {
+  it('maps each device credId to its prfSalt', function () {
+    const result = buildEvalByCredential([device1, device2]);
+    assert.deepStrictEqual(result, {
+      'cred-aaa': 'salt-aaa',
+      'cred-bbb': 'salt-bbb',
+    });
+  });
+
+  it('returns an empty object for an empty device list', function () {
+    assert.deepStrictEqual(buildEvalByCredential([]), {});
+  });
+
+  it('returns a single-entry map for one device', function () {
+    const result = buildEvalByCredential([device1]);
+    assert.deepStrictEqual(result, { 'cred-aaa': 'salt-aaa' });
+  });
+});
+
+describe('matchDeviceByCredentialId', function () {
+  it('returns the matching device', function () {
+    const result = matchDeviceByCredentialId([device1, device2], 'cred-bbb');
+    assert.strictEqual(result, device2);
+  });
+
+  it('returns the first device when it matches', function () {
+    const result = matchDeviceByCredentialId([device1, device2], 'cred-aaa');
+    assert.strictEqual(result, device1);
+  });
+
+  it('throws a descriptive error when no device matches', function () {
+    assert.throws(
+      () => matchDeviceByCredentialId([device1, device2], 'cred-unknown'),
+      (err: Error) => {
+        assert.ok(err.message.includes('cred-unknown'));
+        assert.ok(err.message.includes('cred-aaa'));
+        assert.ok(err.message.includes('cred-bbb'));
+        return true;
+      }
+    );
+  });
+
+  it('throws when the device list is empty', function () {
+    assert.throws(() => matchDeviceByCredentialId([], 'cred-aaa'), Error);
+  });
+});