feat(passkey-crypto): add removePasskeyFromWallet function

derranW26 · derranW26 · commit ebd4c33f3b95 · 2026-05-04T14:56:16.000-04:00
Removes a WebAuthn passkey credential from a wallet's user keychain. Verifies the wallet passphrase via decrypt() before issuing the DELETE to prevent accidental lockout. Validates device.id, wallet coin, and wallet keys before proceeding. TICKET: WCN-190
diff --git a/modules/passkey-crypto/package.json b/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": {
diff --git a/modules/passkey-crypto/src/index.ts b/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 { removePasskeyFromWallet } from './removePasskeyFromWallet';
diff --git a/modules/passkey-crypto/src/removePasskeyFromWallet.ts b/modules/passkey-crypto/src/removePasskeyFromWallet.ts
@@ -0,0 +1,46 @@
+import { BitGoBase } from '@bitgo/sdk-core';
+import { WebAuthnOtpDevice } from './webAuthnTypes';
+
+export async function removePasskeyFromWallet(params: {
+  bitgo: BitGoBase;
+  walletId: string;
+  device: WebAuthnOtpDevice;
+  walletPassphrase: string;
+}): Promise<void> {
+  const { bitgo, walletId, device, walletPassphrase } = params;
+
+  if (!device.id) {
+    throw new Error('device.id is required to remove a passkey from the wallet');
+  }
+
+  // Fetch wallet to infer coin and keychainId
+  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. Cannot remove passkey.`);
+  }
+
+  const keys = walletData.keys as string[] | undefined;
+  if (!keys || keys.length === 0) {
+    throw new Error(`Wallet ${walletId} has no keys. Cannot remove passkey.`);
+  }
+  const keychainId = keys[0];
+
+  // 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 verify passphrase before passkey removal.`);
+  }
+
+  // Verify passphrase before any mutation
+  try {
+    bitgo.decrypt({ password: walletPassphrase, input: keychain.encryptedPrv });
+  } catch {
+    throw new Error('Incorrect wallet passphrase. Passkey removal aborted to prevent lockout.');
+  }
+
+  // DELETE the webauthn device using device.id (MongoDB ObjectId), not credentialId
+  await bitgo.del(bitgo.url(`/key/${keychainId}/webauthndevice/${device.id}`, 2)).result();
+}
diff --git a/modules/passkey-crypto/test/unit/removePasskeyFromWallet.test.ts b/modules/passkey-crypto/test/unit/removePasskeyFromWallet.test.ts
@@ -0,0 +1,234 @@
+import * as assert from 'assert';
+import * as sinon from 'sinon';
+import { removePasskeyFromWallet } from '../../src';
+
+describe('removePasskeyFromWallet', function () {
+  const walletId = 'wallet-abc123';
+  const keychainId = 'key-user-id';
+  const encryptedPrv = 'encrypted-prv-string';
+  const walletPassphrase = 'correct-passphrase';
+  const decryptedPrv = 'xprv-decrypted';
+
+  const device = {
+    id: 'mongo-object-id-123',
+    credentialId: 'cred-id-456',
+    prfSalt: 'some-salt',
+    isPasskey: true,
+  };
+
+  let mockBitGo: sinon.SinonStubbedInstance<{
+    url: (path: string, version?: number) => string;
+    get: (url: string) => { result: () => Promise<unknown> };
+    del: (url: string) => { result: () => Promise<unknown> };
+    decrypt: (params: { password: string; input: string }) => string;
+  }>;
+
+  beforeEach(function () {
+    mockBitGo = {
+      url: sinon
+        .stub<[path: string, version?: number], string>()
+        .callsFake((path, version) => `/api/v${version ?? 1}${path}`),
+      get: sinon.stub(),
+      del: sinon.stub(),
+      decrypt: sinon.stub(),
+    };
+
+    // Default: wallet fetch returns coin + keys
+    (mockBitGo.get as sinon.SinonStub).withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().resolves({ coin: 'tbtc', keys: [keychainId, 'backup-key-id', 'bitgo-key-id'] }),
+    });
+
+    // Default: keychain fetch returns encryptedPrv
+    (mockBitGo.get as sinon.SinonStub).withArgs(`/api/v2/tbtc/key/${keychainId}`).returns({
+      result: sinon.stub().resolves({ id: keychainId, encryptedPrv }),
+    });
+
+    // Default: decrypt succeeds
+    (mockBitGo.decrypt as sinon.SinonStub).returns(decryptedPrv);
+
+    // Default: DELETE succeeds
+    (mockBitGo.del as sinon.SinonStub).returns({
+      result: sinon.stub().resolves({}),
+    });
+  });
+
+  afterEach(function () {
+    sinon.restore();
+  });
+
+  it('should successfully remove a passkey device', async function () {
+    await removePasskeyFromWallet({
+      bitgo: mockBitGo as any,
+      walletId,
+      device,
+      walletPassphrase,
+    });
+
+    // Verify decrypt was called with the right args
+    sinon.assert.calledOnce(mockBitGo.decrypt);
+    sinon.assert.calledWithExactly(mockBitGo.decrypt, { password: walletPassphrase, input: encryptedPrv });
+
+    // Verify DELETE was called with device.id (not credentialId)
+    sinon.assert.calledOnce(mockBitGo.del);
+    sinon.assert.calledWithExactly(mockBitGo.del, `/api/v2/key/${keychainId}/webauthndevice/${device.id}`);
+  });
+
+  it('should throw and not call DELETE if passphrase is wrong', async function () {
+    (mockBitGo.decrypt as sinon.SinonStub).throws(new Error('decryption failed'));
+
+    await assert.rejects(
+      () =>
+        removePasskeyFromWallet({
+          bitgo: mockBitGo as any,
+          walletId,
+          device,
+          walletPassphrase: 'wrong-passphrase',
+        }),
+      (err: Error) => {
+        assert.ok(err.message.includes('Incorrect wallet passphrase'));
+        assert.ok(err.message.includes('Passkey removal aborted to prevent lockout'));
+        return true;
+      }
+    );
+
+    // DELETE must NOT have been called
+    sinon.assert.notCalled(mockBitGo.del);
+  });
+
+  it('should throw descriptively if keychain has no encryptedPrv', async function () {
+    (mockBitGo.get as sinon.SinonStub).withArgs(`/api/v2/tbtc/key/${keychainId}`).returns({
+      result: sinon.stub().resolves({ id: keychainId }),
+    });
+
+    await assert.rejects(
+      () =>
+        removePasskeyFromWallet({
+          bitgo: mockBitGo as any,
+          walletId,
+          device,
+          walletPassphrase,
+        }),
+      (err: Error) => {
+        assert.ok(err.message.includes('no encryptedPrv'));
+        return true;
+      }
+    );
+
+    // No decrypt or DELETE should be called
+    sinon.assert.notCalled(mockBitGo.decrypt);
+    sinon.assert.notCalled(mockBitGo.del);
+  });
+
+  it('should throw if device.id is empty', async function () {
+    const deviceNoId = { ...device, id: '' };
+
+    await assert.rejects(
+      () =>
+        removePasskeyFromWallet({
+          bitgo: mockBitGo as any,
+          walletId,
+          device: deviceNoId,
+          walletPassphrase,
+        }),
+      (err: Error) => {
+        assert.ok(err.message.includes('device.id is required'));
+        return true;
+      }
+    );
+
+    // No API calls should be made
+    sinon.assert.notCalled(mockBitGo.get as sinon.SinonStub);
+    sinon.assert.notCalled(mockBitGo.del);
+  });
+
+  it('should throw if wallet has no coin', async function () {
+    (mockBitGo.get as sinon.SinonStub).withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().resolves({ keys: [keychainId] }),
+    });
+
+    await assert.rejects(
+      () =>
+        removePasskeyFromWallet({
+          bitgo: mockBitGo as any,
+          walletId,
+          device,
+          walletPassphrase,
+        }),
+      (err: Error) => {
+        assert.ok(err.message.includes('has no coin type'));
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.decrypt);
+    sinon.assert.notCalled(mockBitGo.del);
+  });
+
+  it('should throw if wallet has no keys', async function () {
+    (mockBitGo.get as sinon.SinonStub).withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().resolves({ coin: 'tbtc', keys: [] }),
+    });
+
+    await assert.rejects(
+      () =>
+        removePasskeyFromWallet({
+          bitgo: mockBitGo as any,
+          walletId,
+          device,
+          walletPassphrase,
+        }),
+      (err: Error) => {
+        assert.ok(err.message.includes('has no keys'));
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.decrypt);
+    sinon.assert.notCalled(mockBitGo.del);
+  });
+
+  it('should propagate wallet fetch errors', async function () {
+    (mockBitGo.get as sinon.SinonStub).withArgs(`/api/v2/wallet/${walletId}`).returns({
+      result: sinon.stub().rejects(new Error('404 Not Found')),
+    });
+
+    await assert.rejects(
+      () =>
+        removePasskeyFromWallet({
+          bitgo: mockBitGo as any,
+          walletId,
+          device,
+          walletPassphrase,
+        }),
+      (err: Error) => {
+        assert.ok(err.message.includes('404 Not Found'));
+        return true;
+      }
+    );
+
+    sinon.assert.notCalled(mockBitGo.del);
+  });
+
+  it('should propagate DELETE errors after passphrase verification', async function () {
+    (mockBitGo.del as sinon.SinonStub).returns({
+      result: sinon.stub().rejects(new Error('500 Internal Server Error')),
+    });
+
+    await assert.rejects(
+      () =>
+        removePasskeyFromWallet({
+          bitgo: mockBitGo as any,
+          walletId,
+          device,
+          walletPassphrase,
+        }),
+      (err: Error) => {
+        assert.ok(err.message.includes('500 Internal Server Error'));
+        return true;
+      }
+    );
+
+    // Passphrase verification should have succeeded before DELETE failed
+    sinon.assert.calledOnce(mockBitGo.decrypt);
+  });
+});
