feat(passkey-crypto): add @bitgo/passkey-crypto package

Pure cryptographic primitives for WebAuthn PRF-based key derivation:
- derivePassword: converts ArrayBuffer PRF result to hex walletPassphrase
- deriveEnterpriseSalt: HMAC-SHA256 via SJCL matching retail implementation exactly

TICKET: WCN-186

Author: derranW26

modules/passkey-crypto/.mocharc.yml

@@ -0,0 +1,8 @@
+require: 'tsx'
+timeout: '20000'
+reporter: 'min'
+reporter-option:
+  - 'cdn=true'
+  - 'json=false'
+exit: true
+spec: ['test/unit/**/*.ts']

modules/passkey-crypto/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bitgo/passkey-crypto",
+  "version": "0.1.0",
+  "description": "Pure cryptographic primitives for BitGo passkey (WebAuthn PRF) key derivation",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "yarn tsc --build --incremental --verbose .",
+    "fmt": "prettier --write .",
+    "check-fmt": "prettier --check '**/*.{ts,js,json}'",
+    "clean": "rm -r ./dist",
+    "lint": "eslint --quiet .",
+    "prepare": "npm run build",
+    "test": "npm run unit-test",
+    "unit-test": "mocha 'test/unit/**/*.ts'"
+  },
+  "author": "BitGo SDK Team <sdkteam@bitgo.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BitGo/BitGoJS.git",
+    "directory": "modules/passkey-crypto"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "yarn prettier --write",
+      "yarn eslint --fix"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@bitgo/sjcl": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0"
+  }
+}

modules/passkey-crypto/src/deriveEnterpriseSalt.ts

@@ -0,0 +1,35 @@
+import * as sjcl from '@bitgo/sjcl';
+import type { SjclCodecs, SjclHashes, SjclMisc } from '@bitgo/sjcl';
+
+type SjclType = {
+  hash: SjclHashes;
+  codec: SjclCodecs;
+  misc: SjclMisc;
+};
+
+/**
+ * Derives an enterprise-scoped PRF salt to prevent cross-enterprise key reuse.
+ *
+ * Computes HMAC-SHA256(key=prfSalt_base64url_decoded, data=enterpriseId_utf8).
+ * The baseSalt must always come from the server — never generate it client-side.
+ *
+ * @param baseSalt - Server-provided base64url-encoded PRF salt
+ * @param enterpriseId - Enterprise identifier
+ * @returns Base64-encoded HMAC-SHA256 digest
+ * @throws If baseSalt is missing
+ */
+export function deriveEnterpriseSalt(baseSalt: string | undefined, enterpriseId: string): string {
+  if (!baseSalt) {
+    throw new Error('Failed to derive enterprise salt');
+  }
+
+  const { misc, codec, hash } = sjcl as unknown as SjclType;
+
+  const keyBits = codec.base64url.toBits(baseSalt);
+  const dataBits = codec.utf8String.toBits(enterpriseId);
+
+  const hmacInstance = new misc.hmac(keyBits, hash.sha256);
+  const resultBits = hmacInstance.mac(dataBits);
+
+  return codec.base64.fromBits(resultBits);
+}

modules/passkey-crypto/src/derivePassword.ts

@@ -0,0 +1,16 @@
+/**
+ * Derives a wallet passphrase from a WebAuthn PRF result.
+ *
+ * The PRF output (ArrayBuffer) is hex-encoded and used directly as the
+ * walletPassphrase for SJCL-based encryption (bitgo.encrypt).
+ *
+ * @param prfResult - Raw PRF output from WebAuthn credential assertion
+ * @returns Lowercase hex string to use as walletPassphrase
+ * @throws If prfResult is missing
+ */
+export function derivePassword(prfResult: ArrayBuffer | undefined): string {
+  if (!prfResult) {
+    throw new Error('Failed to derive password');
+  }
+  return Buffer.from(prfResult).toString('hex');
+}

modules/passkey-crypto/src/index.ts

@@ -0,0 +1,2 @@
+export { derivePassword } from './derivePassword';
+export { deriveEnterpriseSalt } from './deriveEnterpriseSalt';

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

@@ -0,0 +1,46 @@
+import * as assert from 'assert';
+import { deriveEnterpriseSalt } from '../../src';
+
+describe('deriveEnterpriseSalt', function () {
+  const PRF_SALT = 'deadbeefcafebabe';
+  const ENTERPRISE_ID = 'enterprise-abc123';
+
+  it('throws when baseSalt is undefined', function () {
+    assert.throws(() => deriveEnterpriseSalt(undefined, ENTERPRISE_ID), /Failed to derive enterprise salt/);
+  });
+
+  it('throws when baseSalt is empty string', function () {
+    assert.throws(() => deriveEnterpriseSalt('', ENTERPRISE_ID), /Failed to derive enterprise salt/);
+  });
+
+  it('is deterministic — same inputs always produce the same salt', function () {
+    const first = deriveEnterpriseSalt(PRF_SALT, ENTERPRISE_ID);
+    const second = deriveEnterpriseSalt(PRF_SALT, ENTERPRISE_ID);
+    assert.ok(first);
+    assert.strictEqual(first, second);
+  });
+
+  it('produces a known output for a given prfSalt and enterpriseId', function () {
+    // HMAC-SHA256(key=deadbeefcafebabe decoded as base64url, data=enterprise-abc123 utf8) encoded as base64
+    assert.strictEqual(deriveEnterpriseSalt(PRF_SALT, ENTERPRISE_ID), 'jdXFg2z9rGUspk4ofQy5fwoMKzAzQLC7rdWIQqOQTfM=');
+  });
+
+  it('produces different salts for different enterpriseIds with the same prfSalt', function () {
+    const saltA = deriveEnterpriseSalt(PRF_SALT, 'enterprise-abc123');
+    const saltB = deriveEnterpriseSalt(PRF_SALT, 'enterprise-xyz789');
+    assert.notStrictEqual(saltA, saltB);
+  });
+
+  it('produces different salts for different prfSalts with the same enterpriseId', function () {
+    const saltA = deriveEnterpriseSalt('deadbeefcafebabe', ENTERPRISE_ID);
+    const saltB = deriveEnterpriseSalt('0102030405060708', ENTERPRISE_ID);
+    assert.notStrictEqual(saltA, saltB);
+  });
+
+  it('returns a non-empty base64 string', function () {
+    const result = deriveEnterpriseSalt(PRF_SALT, ENTERPRISE_ID);
+    assert.strictEqual(typeof result, 'string');
+    assert.ok(result.length > 0);
+    assert.match(result, /^[A-Za-z0-9+/]+=*$/);
+  });
+});

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

@@ -0,0 +1,39 @@
+import * as assert from 'assert';
+import { derivePassword } from '../../src';
+
+describe('derivePassword', function () {
+  it('throws if prfResult is undefined', function () {
+    assert.throws(() => derivePassword(undefined), /Failed to derive password/);
+  });
+
+  it('produces a known hex password for a given PRF output', function () {
+    // Known 32-byte PRF result → expected hex-encoded wallet passphrase
+    const prfBytes = new Uint8Array([
+      0xde, 0xad, 0xbe, 0xef, 0xca, 0xfe, 0xba, 0xbe, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc,
+      0xba, 0x98, 0x76, 0x54, 0x32, 0x10, 0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77,
+    ]);
+    assert.strictEqual(
+      derivePassword(prfBytes.buffer),
+      'deadbeefcafebabe0123456789abcdeffedcba98765432100011223344556677'
+    );
+  });
+
+  it('converts an ArrayBuffer of zeros to a hex string of zeros', function () {
+    assert.strictEqual(derivePassword(new ArrayBuffer(4)), '00000000');
+  });
+
+  it('returns a lowercase hex string', function () {
+    const input = new Uint8Array([0xab, 0xcd]).buffer;
+    const result = derivePassword(input);
+    assert.strictEqual(result, result.toLowerCase());
+  });
+
+  it('returns a string of length 2x the input byte length', function () {
+    assert.strictEqual(derivePassword(new ArrayBuffer(32)).length, 64);
+  });
+
+  it('is deterministic — same inputs produce same output', function () {
+    const input = new Uint8Array([1, 2, 3, 4, 5]).buffer;
+    assert.strictEqual(derivePassword(input), derivePassword(input));
+  });
+});

modules/passkey-crypto/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strictPropertyInitialization": false,
+    "esModuleInterop": true,
+    "typeRoots": ["../../types", "./node_modules/@types", "../../node_modules/@types"]
+  },
+  "include": ["src/**/*", "test/**/*"],
+  "exclude": ["node_modules"]
+}