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-411

Author: derranW26

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

@@ -0,0 +1,81 @@
+import { BitGoBase } from '../bitgoBase';
+import { Keychain } from '../keychain';
+import { deriveEnterpriseSalt, derivePassword } from '@bitgo/passkey-crypto';
+import { WebAuthnOtpDevice, WebAuthnProvider } from './types';
+
+export async function attachPasskeyToWallet(params: {
+  bitgo: BitGoBase;
+  walletId: string;
+  device: WebAuthnOtpDevice;
+  existingPassphrase: string;
+  provider: WebAuthnProvider;
+}): Promise<Keychain> {
+  const { bitgo, 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.');
+  }
+
+  // Fetch wallet to infer coin, keychainId, enterpriseId
+  const walletData = await bitgo.get(bitgo.url(`/wallet/${walletId}`, 2)).result();
+
+  const coin = walletData.coin;
+  if (!coin || typeof coin !== 'string') {
+    throw new Error(`Wallet ${walletId} has no coin type.`);
+  }
+
+  const keys = walletData.keys as string[] | undefined;
+  if (!keys || keys.length === 0) {
+    throw new Error(`Wallet ${walletId} has no keys.`);
+  }
+  const keychainId = keys[0];
+
+  const enterpriseId = walletData.enterprise as string | undefined;
+  if (!enterpriseId) {
+    throw new Error(`Wallet ${walletId} has no enterprise.`);
+  }
+
+  // Fetch user keychain
+  const keychain = await bitgo.get(bitgo.url(`/${coin}/key/${keychainId}`, 2)).result();
+
+  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/sdk-core/src/bitgo/passkey/index.ts

@@ -0,0 +1,2 @@
+export * from './attachPasskeyToWallet';
+export * from './types';

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

@@ -0,0 +1 @@
+export type { WebAuthnOtpDevice, WebAuthnProvider, PasskeyAuthResult, PasskeyGetOptions } from '@bitgo/passkey-crypto';

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

@@ -0,0 +1,285 @@
+import * as assert from 'assert';
+import * as sinon from 'sinon';
+import 'should';
+import { attachPasskeyToWallet } from '../../../../src/bitgo/passkey/attachPasskeyToWallet';
+import { WebAuthnOtpDevice } from '../../../../src/bitgo/passkey/types';
+import { PasskeyAuthResult } from '@bitgo/passkey-crypto';
+
+describe('attachPasskeyToWallet', function () {
+  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 prfPassword = 'prf-derived-password';
+  const reEncryptedPrv = 're-encrypted-prv';
+  const enterpriseSalt = 'derived-enterprise-salt';
+
+  const prfResultBuffer = new Uint8Array([0x1e, 0x5c, 0xb4, 0x78]).buffer;
+
+  const device: WebAuthnOtpDevice = {
+    id: 'mongo-object-id-123',
+    credentialId: 'cred-id-456',
+    prfSalt: 'base64url-salt',
+    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,
+    webauthnDevices: [
+      {
+        otpDeviceId: device.id,
+        prfSalt: enterpriseSalt,
+        encryptedPrv: reEncryptedPrv,
+        authenticatorInfo: {
+          credID: device.credentialId,
+          fmt: 'none' as const,
+          publicKey: 'pub-key',
+        },
+      },
+    ],
+  };
+
+  let mockBitGo: {
+    url: sinon.SinonStub;
+    get: sinon.SinonStub;
+    put: sinon.SinonStub;
+    decrypt: sinon.SinonStub;
+    encrypt: sinon.SinonStub;
+  };
+
+  let mockProvider: {
+    create: sinon.SinonStub;
+    get: sinon.SinonStub;
+  };
+
+  let deriveEnterpriseSaltStub: sinon.SinonStub;
+  let derivePasswordStub: sinon.SinonStub;
+
+  beforeEach(function () {
+    mockBitGo = {
+      url: sinon
+        .stub<[path: string, version?: number], string>()
+        .callsFake((path, version) => `/api/v${version ?? 1}${path}`),
+      get: sinon.stub(),
+      put: sinon.stub(),
+      decrypt: sinon.stub(),
+      encrypt: sinon.stub(),
+    };
+
+    mockProvider = {
+      create: sinon.stub(),
+      get: sinon.stub(),
+    };
+
+    // Default: wallet fetch returns coin + keys + enterprise
+    mockBitGo.get.withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().resolves({
+        coin: 'tbtc',
+        keys: [keychainId, 'backup-key-id', 'bitgo-key-id'],
+        enterprise: enterpriseId,
+      }),
+    });
+
+    // Default: keychain fetch returns encryptedPrv
+    mockBitGo.get.withArgs(`/api/v2/tbtc/key/${keychainId}`).returns({
+      result: sinon.stub().resolves({ id: keychainId, encryptedPrv }),
+    });
+
+    // Default: decrypt succeeds
+    mockBitGo.decrypt.returns(decryptedPrv);
+
+    // Default: encrypt succeeds
+    mockBitGo.encrypt.returns(reEncryptedPrv);
+
+    // Default: PUT succeeds
+    const putSendStub = sinon.stub().returns({ result: sinon.stub().resolves(updatedKeychain) });
+    mockBitGo.put.returns({ send: putSendStub });
+
+    // Default: provider.get returns PRF result
+    mockProvider.get.resolves(mockAuthResult);
+
+    // Stub passkey-crypto functions
+    deriveEnterpriseSaltStub = sinon.stub();
+    deriveEnterpriseSaltStub.returns(enterpriseSalt);
+
+    derivePasswordStub = sinon.stub();
+    derivePasswordStub.returns(prfPassword);
+  });
+
+  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'],
+      walletId,
+      device,
+      existingPassphrase,
+      provider: mockProvider,
+      ...overrides,
+    });
+  }
+
+  it('should attach a passkey and return the updated keychain', async function () {
+    const result = await callAttach();
+
+    // Verify wallet was fetched
+    sinon.assert.calledWith(mockBitGo.get, `/api/v2/wallet/${walletId}`);
+
+    // Verify keychain was fetched
+    sinon.assert.calledWith(mockBitGo.get, `/api/v2/tbtc/key/${keychainId}`);
+
+    // Verify decrypt was called with existing passphrase
+    sinon.assert.calledOnce(mockBitGo.decrypt);
+    sinon.assert.calledWithExactly(mockBitGo.decrypt, { password: existingPassphrase, input: encryptedPrv });
+
+    // Verify provider.get was called with evalByCredential using device.credentialId
+    sinon.assert.calledOnce(mockProvider.get);
+    const getArgs = mockProvider.get.firstCall.args[0];
+    assert.deepStrictEqual(getArgs.evalByCredential, { [device.credentialId]: sinon.match.string });
+
+    // Verify encrypt was called with PRF-derived password
+    sinon.assert.calledOnce(mockBitGo.encrypt);
+
+    // Verify PUT was called with correct webauthnInfo shape
+    sinon.assert.calledOnce(mockBitGo.put);
+    sinon.assert.calledWith(mockBitGo.put, `/api/v2/tbtc/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');
+
+    // Verify result is the keychain from server
+    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;
+      }
+    );
+
+    // No API calls should be made
+    sinon.assert.notCalled(mockBitGo.get);
+    sinon.assert.notCalled(mockBitGo.put);
+  });
+
+  it('should throw descriptively if keychain has no encryptedPrv', async function () {
+    mockBitGo.get.withArgs(`/api/v2/tbtc/key/${keychainId}`).returns({
+      result: sinon.stub().resolves({ id: keychainId }),
+    });
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('no encryptedPrv'));
+        return true;
+      }
+    );
+
+    // No decrypt/encrypt/PUT should happen
+    sinon.assert.notCalled(mockBitGo.decrypt);
+    sinon.assert.notCalled(mockBitGo.encrypt);
+    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 coin', async function () {
+    mockBitGo.get.withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().resolves({ keys: [keychainId], enterprise: enterpriseId }),
+    });
+
+    await assert.rejects(
+      () => callAttach(),
+      (err: Error) => {
+        assert.ok(err.message.includes('has no coin type'));
+        return true;
+      }
+    );
+  });
+
+  it('should throw if wallet has no keys', async function () {
+    mockBitGo.get.withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().resolves({ coin: 'tbtc', keys: [], enterprise: enterpriseId }),
+    });
+
+    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 () {
+    mockBitGo.get.withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().resolves({ coin: 'tbtc', keys: [keychainId] }),
+    });
+
+    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;
+      }
+    );
+
+    // PUT should not have been called
+    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);
+  });
+});