Merge pull request #8663 from BitGo/WCN-187-passkey-types-v2

feat(passkey-crypto): extend package with PRF helpers and sdk-core passkey module

Author: derranW26

modules/passkey-crypto/package.json

@@ -34,6 +34,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@bitgo/public-types": "6.1.0",
     "@bitgo/sjcl": "^1.1.0"
   },
   "devDependencies": {

modules/passkey-crypto/src/index.ts

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

modules/passkey-crypto/src/prfHelpers.ts

@@ -0,0 +1,34 @@
+import type { WebauthnDevice } from '@bitgo/public-types';
+
+/**
+ * Builds the PRF eval map and credential-to-device lookup from a wallet
+ * keychain's webauthn devices. Devices without a prfSalt are skipped.
+ */
+export function buildEvalByCredential(devices: WebauthnDevice[]): {
+  evalByCredential: Record<string, string>;
+  credIdToDevice: Map<string, WebauthnDevice>;
+} {
+  const evalByCredential: Record<string, string> = {};
+  const credIdToDevice = new Map<string, WebauthnDevice>();
+
+  for (const device of devices) {
+    if (!device.prfSalt) continue;
+    const { credID } = device.authenticatorInfo;
+    evalByCredential[credID] = device.prfSalt;
+    credIdToDevice.set(credID, device);
+  }
+
+  return { evalByCredential, credIdToDevice };
+}
+
+/**
+ * Returns the WebauthnDevice matching the given credential ID.
+ * @throws if no matching device is found
+ */
+export function matchDeviceByCredentialId(devices: WebauthnDevice[], credentialId: string): WebauthnDevice {
+  const device = devices.find((d) => d.authenticatorInfo.credID === credentialId);
+  if (!device) {
+    throw new Error('Could not identify which passkey device was used');
+  }
+  return device;
+}

modules/passkey-crypto/src/webAuthnTypes.ts

@@ -0,0 +1,20 @@
+export type { WebAuthnOtpDevice } from '@bitgo/public-types';
+
+/** Result of a WebAuthn assertion with the PRF extension. */
+export interface PasskeyAuthResult {
+  prfResult: ArrayBuffer | undefined;
+  credentialId: string;
+  otpCode: string;
+}
+
+/** Options for WebAuthnProvider.get(). */
+export interface PasskeyGetOptions {
+  publicKey: PublicKeyCredentialRequestOptions;
+  evalByCredential?: Record<string, string>;
+}
+
+/** Abstraction over the WebAuthn credential API. */
+export interface WebAuthnProvider {
+  create(options: PublicKeyCredentialCreationOptions): Promise<PublicKeyCredential>;
+  get(options: PasskeyGetOptions): Promise<PasskeyAuthResult>;
+}

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

@@ -0,0 +1,79 @@
+import * as assert from 'assert';
+import { buildEvalByCredential, matchDeviceByCredentialId } from '../../src';
+import { WebauthnDevice } from '@bitgo/public-types';
+
+const device1: WebauthnDevice = {
+  otpDeviceId: 'oid-1',
+  authenticatorInfo: { credID: 'cred-aaa', fmt: 'none', publicKey: 'pk-1' },
+  prfSalt: 'salt-aaa',
+  encryptedPrv: 'enc-prv-1',
+};
+
+const device2: WebauthnDevice = {
+  otpDeviceId: 'oid-2',
+  authenticatorInfo: { credID: 'cred-bbb', fmt: 'none', publicKey: 'pk-2' },
+  prfSalt: 'salt-bbb',
+  encryptedPrv: 'enc-prv-2',
+};
+
+describe('buildEvalByCredential', function () {
+  it('maps each device credID to its prfSalt in evalByCredential', function () {
+    const { evalByCredential } = buildEvalByCredential([device1, device2]);
+    assert.deepStrictEqual(evalByCredential, { 'cred-aaa': 'salt-aaa', 'cred-bbb': 'salt-bbb' });
+  });
+
+  it('populates credIdToDevice with both devices', function () {
+    const { credIdToDevice } = buildEvalByCredential([device1, device2]);
+    assert.strictEqual(credIdToDevice.get('cred-aaa'), device1);
+    assert.strictEqual(credIdToDevice.get('cred-bbb'), device2);
+  });
+
+  it('returns empty maps for an empty device list', function () {
+    const { evalByCredential, credIdToDevice } = buildEvalByCredential([]);
+    assert.deepStrictEqual(evalByCredential, {});
+    assert.strictEqual(credIdToDevice.size, 0);
+  });
+
+  it('skips devices with empty prfSalt', function () {
+    const deviceNoPrf = { ...device1, prfSalt: '' };
+    const { evalByCredential, credIdToDevice } = buildEvalByCredential([deviceNoPrf, device2]);
+    assert.deepStrictEqual(evalByCredential, { 'cred-bbb': 'salt-bbb' });
+    assert.strictEqual(credIdToDevice.has('cred-aaa'), false);
+  });
+
+  it('skips devices with undefined prfSalt', function () {
+    const deviceNoPrf = { ...device1, prfSalt: undefined as unknown as string };
+    const { evalByCredential, credIdToDevice } = buildEvalByCredential([deviceNoPrf, device2]);
+    assert.deepStrictEqual(evalByCredential, { 'cred-bbb': 'salt-bbb' });
+    assert.strictEqual(credIdToDevice.has('cred-aaa'), false);
+  });
+});
+
+describe('matchDeviceByCredentialId', function () {
+  it('returns the matching device', function () {
+    assert.strictEqual(matchDeviceByCredentialId([device1, device2], 'cred-bbb'), device2);
+  });
+
+  it('returns the first device when it matches', function () {
+    assert.strictEqual(matchDeviceByCredentialId([device1, device2], 'cred-aaa'), device1);
+  });
+
+  it('returns a device even when it has no prfSalt', function () {
+    const deviceNoPrf = { ...device1, prfSalt: '' };
+    assert.strictEqual(matchDeviceByCredentialId([deviceNoPrf, device2], 'cred-aaa'), deviceNoPrf);
+  });
+
+  it('throws the expected error message when no device matches', function () {
+    assert.throws(
+      () => matchDeviceByCredentialId([device1, device2], 'cred-unknown'),
+      (err: Error) => {
+        assert.strictEqual(err.message, 'Could not identify which passkey device was used');
+        return true;
+      }
+    );
+  });
+
+  it('throws when the device list is empty', function () {
+    assert.throws(() => matchDeviceByCredentialId([], 'cred-aaa'), Error);
+  });
+});

modules/passkey-crypto/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "lib": ["ES2020", "DOM"],
     "outDir": "./dist",
     "rootDir": "./",
     "strictPropertyInitialization": false,

yarn.lock

@@ -1010,6 +1010,17 @@
     monocle-ts "^2.3.13"
     newtype-ts "^0.3.5"
 
+"@bitgo/public-types@6.1.0":
+  version "6.1.0"
+  resolved "https://registry.npmjs.org/@bitgo/public-types/-/public-types-6.1.0.tgz#7c3949a0ae4de706b3d6a748ab07669a330e3fad"
+  integrity sha512-k+3cYvcSzpaqBcBO3saZkwfsazE3JY9WC321WX76fAYFTt6v6Q71pyUSCH41dTEZz9KGi79DwicCnpKsREw8eg==
+  dependencies:
+    fp-ts "^2.0.0"
+    io-ts "npm:@bitgo-forks/io-ts@2.1.4"
+    io-ts-types "^0.5.16"
+    monocle-ts "^2.3.13"
+    newtype-ts "^0.3.5"
+
 "@bitgo/wasm-dot@^1.7.0":
   version "1.7.0"
   resolved "https://registry.npmjs.org/@bitgo/wasm-dot/-/wasm-dot-1.7.0.tgz"