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,84 @@
+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 });
+
+  // PRF assertion — evalByCredential maps this device's credentialId to its enterprise salt
+  const authResult = await provider.get({
+    publicKey: {} 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 });
+
+  // PUT webauthnInfo to keychain endpoint
+  const updatedKeychain = await bitgo
+    .put(bitgo.url(`/${coin}/key/${keychainId}`, 2))
+    .send({
+      webauthnInfo: {
+        prfSalt: enterpriseSalt,
+        otpDeviceId: device.id,
+        encryptedPrv,
+      },
+    })
+    .result();
+
+  return updatedKeychain as Keychain;
+}

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

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

@@ -0,0 +1,265 @@
+import * as assert from 'assert';
+import * as sinon from 'sinon';
+import { attachPasskeyToWallet } from '../../src/attachPasskeyToWallet';
+import { WebAuthnOtpDevice, PasskeyAuthResult, WebAuthnProvider } from '../../src/webAuthnTypes';
+
+describe('attachPasskeyToWallet', function () {
+  const coin = 'tbtc';
+  const walletId = 'wallet-abc123';
+  const keychainId = 'key-user-id';
+  const enterpriseId = 'enterprise-xyz';
+  const encryptedPrv = 'encrypted-prv-string';
+  const decryptedPrv = 'xprv-decrypted';
+  const existingPassphrase = 'correct-passphrase';
+  const reEncryptedPrv = 're-encrypted-prv';
+
+  const prfResultBuffer = new Uint8Array([0x1e, 0x5c, 0xb4, 0x78]).buffer;
+
+  const device: WebAuthnOtpDevice = {
+    id: 'mongo-object-id-123',
+    credentialId: 'cred-id-456',
+    prfSalt: 'ZqJ64M2dL65zn2-Jxd58SMN2ILc9QjbCFxUTGHd_LC8',
+    isPasskey: true,
+  };
+
+  const mockAuthResult: PasskeyAuthResult = {
+    prfResult: prfResultBuffer,
+    credentialId: 'cred-id-456',
+    otpCode: '123456',
+  };
+
+  const updatedKeychain = {
+    id: keychainId,
+    pub: 'xpub-123',
+    type: 'independent' as const,
+    encryptedPrv,
+  };
+
+  let mockWallet: {
+    type: sinon.SinonStub;
+    keyIds: sinon.SinonStub;
+    toJSON: sinon.SinonStub;
+  };
+
+  let mockWallets: {
+    get: sinon.SinonStub;
+  };
+
+  let mockKeychains: {
+    get: sinon.SinonStub;
+  };
+
+  let mockBaseCoin: {
+    wallets: sinon.SinonStub;
+    keychains: sinon.SinonStub;
+  };
+
+  let mockBitGo: {
+    url: sinon.SinonStub;
+    coin: sinon.SinonStub;
+    put: sinon.SinonStub;
+    decrypt: sinon.SinonStub;
+    encrypt: sinon.SinonStub;
+  };
+
+  let mockProvider: {
+    create: sinon.SinonStub;
+    get: sinon.SinonStub;
+  };
+
+  beforeEach(function () {
+    mockWallet = {
+      type: sinon.stub().returns('hot'),
+      keyIds: sinon.stub().returns([keychainId, 'backup-key-id', 'bitgo-key-id']),
+      toJSON: sinon.stub().returns({ enterprise: enterpriseId }),
+    };
+
+    mockWallets = {
+      get: sinon.stub().resolves(mockWallet),
+    };
+
+    mockKeychains = {
+      get: sinon.stub().resolves({ id: keychainId, encryptedPrv }),
+    };
+
+    mockBaseCoin = {
+      wallets: sinon.stub().returns(mockWallets),
+      keychains: sinon.stub().returns(mockKeychains),
+    };
+
+    mockBitGo = {
+      url: sinon
+        .stub<[path: string, version?: number], string>()
+        .callsFake((path, version) => `/api/v${version ?? 1}${path}`),
+      coin: sinon.stub().returns(mockBaseCoin),
+      put: sinon.stub(),
+      decrypt: sinon.stub(),
+      encrypt: sinon.stub(),
+    };
+
+    mockProvider = {
+      create: sinon.stub(),
+      get: sinon.stub(),
+    };
+
+    mockBitGo.decrypt.returns(decryptedPrv);
+    mockBitGo.encrypt.returns(reEncryptedPrv);
+
+    const putSendStub = sinon.stub().returns({ result: sinon.stub().resolves(updatedKeychain) });
+    mockBitGo.put.returns({ send: putSendStub });
+
+    mockProvider.get.resolves(mockAuthResult);
+  });
+
+  afterEach(function () {
+    sinon.restore();
+  });
+
+  async function callAttach(overrides?: Partial<Parameters<typeof attachPasskeyToWallet>[0]>) {
+    return attachPasskeyToWallet({
+      bitgo: mockBitGo as unknown as Parameters<typeof attachPasskeyToWallet>[0]['bitgo'],
+      coin,
+      walletId,
+      device,
+      existingPassphrase,
+      provider: mockProvider as unknown as WebAuthnProvider,
+      ...overrides,
+    });
+  }
+
+  it('should attach a passkey and return the updated keychain', async function () {
+    const result = await callAttach();
+
+    sinon.assert.calledWith(mockBitGo.coin, coin);
+    sinon.assert.calledWith(mockWallets.get, { id: walletId });
+    sinon.assert.calledOnce(mockWallet.type);
+    sinon.assert.calledOnce(mockKeychains.get);
+    sinon.assert.calledWithMatch(mockKeychains.get, { id: keychainId });
+    sinon.assert.calledOnce(mockBitGo.decrypt);
+    sinon.assert.calledWithExactly(mockBitGo.decrypt, { password: existingPassphrase, input: encryptedPrv });
+
+    // provider.get called with evalByCredential keyed on device.credentialId
+    sinon.assert.calledOnce(mockProvider.get);
+    const getArgs = mockProvider.get.firstCall.args[0];
+    assert.ok(getArgs.evalByCredential);
+    assert.strictEqual(typeof getArgs.evalByCredential[device.credentialId], 'string');
+
+    // PUT called with correct shape
+    sinon.assert.calledOnce(mockBitGo.put);
+    sinon.assert.calledWith(mockBitGo.put, `/api/v2/${coin}/key/${keychainId}`);
+    const sendStub = mockBitGo.put.firstCall.returnValue.send;
+    sinon.assert.calledOnce(sendStub);
+    const putBody = sendStub.firstCall.args[0];
+    assert.ok(putBody.webauthnInfo);
+    assert.strictEqual(putBody.webauthnInfo.otpDeviceId, device.id);
+    assert.strictEqual(typeof putBody.webauthnInfo.prfSalt, 'string');
+    assert.strictEqual(typeof putBody.webauthnInfo.encryptedPrv, 'string');
+
+    assert.strictEqual(result.id, keychainId);
+  });
+
+  it('should throw if device.prfSalt is undefined', async function () {
+    const deviceNoPrf: WebAuthnOtpDevice = { ...device, prfSalt: undefined };
+
+    await assert.rejects(
+      () => callAttach({ device: deviceNoPrf }),
+      (err: Error) => {
+        assert.strictEqual(err.message, 'PRF extension not supported by this device. Please use a different passkey.');
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.coin);
+    sinon.assert.notCalled(mockBitGo.put);
+  });
+
+  it('should throw if wallet is not a hot wallet', async function () {
+    mockWallet.type.returns('cold');
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('not a hot wallet'));
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.put);
+  });
+
+  it('should throw descriptively if keychain has no encryptedPrv', async function () {
+    mockKeychains.get.resolves({ id: keychainId });
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('no encryptedPrv'));
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.decrypt);
+    sinon.assert.notCalled(mockBitGo.put);
+  });
+
+  it('should use device.credentialId as the key in evalByCredential', async function () {
+    await callAttach();
+
+    const getArgs = mockProvider.get.firstCall.args[0];
+    const evalKeys = Object.keys(getArgs.evalByCredential);
+    assert.strictEqual(evalKeys.length, 1);
+    assert.strictEqual(evalKeys[0], device.credentialId);
+  });
+
+  it('should throw if wallet has no keys', async function () {
+    mockWallet.keyIds.returns([]);
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('has no keys'));
+        return true;
+      }
+    );
+  });
+
+  it('should throw if wallet has no enterprise', async function () {
+    mockWallet.toJSON.returns({ enterprise: undefined });
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('has no enterprise'));
+        return true;
+      }
+    );
+  });
+
+  it('should throw if PRF assertion returns no result', async function () {
+    mockProvider.get.resolves({ ...mockAuthResult, prfResult: undefined });
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('PRF assertion did not return a result'));
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.put);
+  });
+
+  it('should propagate decrypt errors', async function () {
+    mockBitGo.decrypt.throws(new Error('decryption failed'));
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('decryption failed'));
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.put);
+  });
+});