feat(sdk-core): add attachPasskeyToWallet function

- fetch wallet to infer coin, keychainId, enterpriseId
- verify encryptedPrv exists before PRF assertion
- derive enterprise salt and re-encrypt prv with PRF-derived password
- PUT webauthnInfo to keychain endpoint

Ticket: WCN-189

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/attachPasskeyToWallet.ts

@@ -0,0 +1,99 @@
+import { BitGoBase, Keychain } from '@bitgo/sdk-core';
+import { deriveEnterpriseSalt } from './deriveEnterpriseSalt';
+import { derivePassword } from './derivePassword';
+import { WebAuthnOtpDevice, WebAuthnProvider } from './webAuthnTypes';
+
+export async function attachPasskeyToWallet(params: {
+  bitgo: BitGoBase;
+  coin: string;
+  walletId: string;
+  device: WebAuthnOtpDevice;
+  existingPassphrase: string;
+  provider: WebAuthnProvider;
+}): Promise<Keychain> {
+  const { bitgo, coin, walletId, device, existingPassphrase, provider } = params;
+
+  // Throw early if PRF extension is not supported
+  if (!device.prfSalt) {
+    throw new Error('PRF extension not supported by this device. Please use a different passkey.');
+  }
+
+  const baseCoin = bitgo.coin(coin);
+
+  // Fetch wallet and validate it is a hot wallet
+  const wallet = await baseCoin.wallets().get({ id: walletId });
+
+  if (wallet.type() !== 'hot') {
+    throw new Error(`Wallet ${walletId} is not a hot wallet. Only hot wallets support passkey attachment.`);
+  }
+
+  const keyIds = wallet.keyIds();
+  if (!keyIds || keyIds.length === 0) {
+    throw new Error(`Wallet ${walletId} has no keys.`);
+  }
+  const keychainId = keyIds[0];
+
+  const walletData = wallet.toJSON();
+  const enterpriseId = walletData.enterprise;
+  if (!enterpriseId) {
+    throw new Error(`Wallet ${walletId} has no enterprise.`);
+  }
+
+  // Fetch user keychain
+  const keychain = await baseCoin.keychains().get({ id: keychainId });
+
+  if (!keychain.encryptedPrv) {
+    throw new Error(
+      `Keychain ${keychainId} has no encryptedPrv. Cannot attach passkey without an existing encrypted private key.`
+    );
+  }
+
+  // Derive enterprise-scoped salt
+  const enterpriseSalt = deriveEnterpriseSalt(device.prfSalt, enterpriseId);
+
+  // Decrypt private key with existing passphrase
+  const privateKey = bitgo.decrypt({ password: existingPassphrase, input: keychain.encryptedPrv });
+
+  // Decode credentialId from base64url to ArrayBuffer for allowCredentials.
+  // The WebAuthn spec requires allowCredentials to be non-empty when using evalByCredential,
+  // and each entry must correspond to a key in the evalByCredential map.
+  const credentialIdBuffer = Buffer.from(device.credentialId.replace(/-/g, '+').replace(/_/g, '/'), 'base64').buffer;
+
+  // PRF assertion — evalByCredential maps this device's credentialId to its enterprise salt
+  const authResult = await provider.get({
+    publicKey: {
+      allowCredentials: [{ type: 'public-key', id: credentialIdBuffer }],
+    } as PublicKeyCredentialRequestOptions,
+    evalByCredential: { [device.credentialId]: enterpriseSalt },
+  });
+
+  if (!authResult.prfResult) {
+    throw new Error('PRF assertion did not return a result.');
+  }
+
+  // Derive password from PRF output and re-encrypt
+  const prfPassword = derivePassword(authResult.prfResult);
+  const encryptedPrv = bitgo.encrypt({ password: prfPassword, input: privateKey });
+
+  // Convert enterpriseSalt from hex to base64url (URL-safe, no padding)
+  // as required by the server's prfSalt validation.
+  const prfSaltBase64url = Buffer.from(enterpriseSalt, 'hex')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+
+  // PUT webauthnInfo to keychain endpoint
+  const updatedKeychain = await bitgo
+    .put(bitgo.url(`/${coin}/key/${keychainId}`, 2))
+    .send({
+      webauthnInfo: {
+        prfSalt: prfSaltBase64url,
+        otpDeviceId: device.id,
+        encryptedPrv,
+      },
+    })
+    .result();
+
+  return updatedKeychain as Keychain;
+}

modules/passkey-crypto/src/deriveEnterpriseSalt.ts

@@ -1,11 +1,4 @@
-import * as sjcl from '@bitgo/sjcl';
-import type { SjclCodecs, SjclHashes, SjclMisc } from '@bitgo/sjcl';
-
-type SjclType = {
-  hash: SjclHashes;
-  codec: SjclCodecs;
-  misc: SjclMisc;
-};
+import { createHmac } from 'crypto';
 
 /**
  * Derives an enterprise-scoped PRF salt to prevent cross-enterprise key reuse.
@@ -15,16 +8,9 @@ type SjclType = {
  *
  * @param baseSalt - Server-provided base64url-encoded PRF salt
  * @param enterpriseId - Enterprise identifier
- * @returns Base64-encoded HMAC-SHA256 digest
+ * @returns Hex-encoded HMAC-SHA256 digest
  */
 export function deriveEnterpriseSalt(baseSalt: string, enterpriseId: string): string {
-  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);
+  const keyBytes = Buffer.from(baseSalt.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+  return createHmac('sha256', keyBytes).update(enterpriseId).digest('hex');
 }

modules/passkey-crypto/src/index.ts

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