@organigram/passkey-wallet 0.1.6

package/dist/webauthn-client.js

@@ -0,0 +1,234 @@
+import { startAuthentication, startRegistration } from '@simplewebauthn/browser';
+import { base64UrlToBytes, decryptPasskeyVaultSecret, derivePasskeyVaultKey, encryptPasskeyVaultSecret } from './crypto';
+import { PasskeyPrfUnavailableError } from './errors';
+import { createNewPasskeyWalletVault, createUnlockedPasskeyWallet } from './wallet';
+import { parsePasskeyWalletVaultPayload, serializePasskeyWalletVaultPayload } from './vault';
+export { parsePasskeyWalletVaultPayload, serializePasskeyWalletVaultPayload };
+const readJson = async (response) => {
+    const body = (await response.json().catch(() => null));
+    if (!response.ok) {
+        throw new Error(body?.error ?? `Request failed with status ${response.status}`);
+    }
+    return body;
+};
+const postJson = async (path, body) => {
+    const response = await fetch(path, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(body)
+    });
+    return await readJson(response);
+};
+export const createFetchPasskeyWalletApiClient = (basePath = '/api/auth/passkey') => ({
+    registerOptions: async (input) => await postJson(`${basePath}/register/options`, input),
+    registerVerify: async (input) => await postJson(`${basePath}/register/verify`, input),
+    unlockOptions: async () => await postJson(`${basePath}/unlock/options`, {}),
+    unlockVerify: async (input) => await postJson(`${basePath}/unlock/verify`, input)
+});
+const hydrateSerializedPrfValue = (value) => {
+    if (value == null)
+        return value;
+    if (typeof value === 'string')
+        return base64UrlToBytes(value);
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (Array.isArray(value))
+        return new Uint8Array(value);
+    if (typeof value === 'object') {
+        const entries = Object.entries(value);
+        if (entries.every(([key, entryValue]) => /^\d+$/.test(key) && typeof entryValue === 'number')) {
+            return new Uint8Array(entries
+                .sort(([left], [right]) => Number(left) - Number(right))
+                .map(([, entryValue]) => entryValue));
+        }
+    }
+    return value;
+};
+const hydratePrfValueSet = (valueSet) => {
+    if (valueSet == null)
+        return valueSet;
+    return {
+        ...valueSet,
+        first: hydrateSerializedPrfValue(valueSet.first),
+        ...(valueSet.second != null
+            ? {
+                second: hydrateSerializedPrfValue(valueSet.second)
+            }
+            : {})
+    };
+};
+export const hydratePasskeyPrfOptions = (options) => {
+    const extensions = options.extensions;
+    const prf = extensions?.prf;
+    if (prf == null)
+        return options;
+    return {
+        ...options,
+        extensions: {
+            ...extensions,
+            prf: {
+                ...prf,
+                ...(prf.eval != null ? { eval: hydratePrfValueSet(prf.eval) } : {}),
+                ...(prf.evalByCredential != null
+                    ? {
+                        evalByCredential: Object.fromEntries(Object.entries(prf.evalByCredential).map(([credentialId, valueSet]) => [
+                            credentialId,
+                            hydratePrfValueSet(valueSet)
+                        ]))
+                    }
+                    : {})
+            }
+        }
+    };
+};
+const getPasskeyPrfOutput = (response) => {
+    const first = response.clientExtensionResults?.prf?.results?.first;
+    if (first == null || first === '') {
+        throw new PasskeyPrfUnavailableError();
+    }
+    return typeof first === 'string'
+        ? base64UrlToBytes(first)
+        : new Uint8Array(first);
+};
+export async function registerPasskeyCredentialEnvelope({ api, address, vaultPayload, email, name }) {
+    const { options } = await api.registerOptions({
+        address,
+        email,
+        name
+    });
+    const registrationResponse = await startRegistration({
+        optionsJSON: hydratePasskeyPrfOptions(options)
+    });
+    const prfOutput = getPasskeyPrfOutput(registrationResponse);
+    const salt = crypto.getRandomValues(new Uint8Array(32));
+    const key = await derivePasskeyVaultKey({
+        prfOutput,
+        salt
+    });
+    const envelope = await encryptPasskeyVaultSecret({
+        plaintext: serializePasskeyWalletVaultPayload(vaultPayload),
+        key,
+        salt
+    });
+    return await api.registerVerify({
+        response: registrationResponse,
+        envelope: {
+            address,
+            encryptedMnemonic: envelope.ciphertext,
+            salt: envelope.salt,
+            nonce: envelope.nonce,
+            algorithm: envelope.algorithm,
+            keyVersion: envelope.keyVersion
+        }
+    });
+}
+export const registerPasskeyWallet = async ({ api, capabilities }) => {
+    const { address, vaultPayload } = await createNewPasskeyWalletVault({
+        capabilities
+    });
+    const credential = await registerPasskeyCredentialEnvelope({
+        api,
+        address,
+        vaultPayload,
+        email: capabilities.identity?.email ?? null,
+        name: capabilities.name ?? capabilities.identity?.email ?? null
+    });
+    return createUnlockedPasskeyWallet({
+        address: credential.address,
+        credentialId: credential.credentialId,
+        vaultPayload
+    });
+};
+export const unlockPasskeyWallet = async ({ api }) => {
+    const { options, hasCredentials } = await api.unlockOptions();
+    if (!hasCredentials)
+        return null;
+    const authenticationResponse = await startAuthentication({
+        optionsJSON: hydratePasskeyPrfOptions(options)
+    });
+    const prfOutput = getPasskeyPrfOutput(authenticationResponse);
+    const result = await api.unlockVerify({
+        response: authenticationResponse
+    });
+    const key = await derivePasskeyVaultKey({
+        prfOutput,
+        salt: base64UrlToBytes(result.envelope.salt)
+    });
+    const vaultPlaintext = await decryptPasskeyVaultSecret({
+        envelope: result.envelope,
+        key
+    });
+    const vaultPayload = parsePasskeyWalletVaultPayload(vaultPlaintext);
+    const wallet = createUnlockedPasskeyWallet({
+        address: result.address,
+        credentialId: result.credentialId,
+        vaultPayload
+    });
+    if (wallet.account.address.toLowerCase() !== result.address.toLowerCase()) {
+        throw new Error('Passkey wallet envelope does not match its address.');
+    }
+    return wallet;
+};
+export const exportPasskeyWalletRecoveryPhrase = async ({ api, expectedAddress }) => {
+    const wallet = await unlockPasskeyWallet({ api });
+    if (wallet == null) {
+        throw new Error('No passkey wallet is available to export.');
+    }
+    if (wallet.address.toLowerCase() !== expectedAddress.toLowerCase()) {
+        throw new Error('Selected passkey does not unlock this wallet.');
+    }
+    return wallet.recoveryPhrase;
+};
+export const registerAdditionalPasskeyCredential = async ({ api, wallet, name }) => await registerPasskeyCredentialEnvelope({
+    api,
+    address: wallet.address,
+    vaultPayload: {
+        version: 1,
+        recoveryPhrase: wallet.recoveryPhrase,
+        userEncryptionPrivateKey: wallet.userEncryptionPrivateKey,
+        userEncryptionPublicKey: wallet.userEncryptionPublicKey,
+        userEncryptionKeyVersion: wallet.userEncryptionKeyVersion
+    },
+    name: name ?? 'Backup passkey'
+});
+export const isPasskeyCredentialUnavailableError = (error) => {
+    if (typeof error !== 'object' || error == null)
+        return false;
+    const { name, message } = error;
+    const normalizedName = typeof name === 'string' ? name.toLowerCase() : '';
+    const normalizedMessage = typeof message === 'string' ? message.toLowerCase() : '';
+    return (normalizedName === 'notallowederror' ||
+        normalizedName === 'invalidstateerror' ||
+        normalizedMessage.includes('no credentials') ||
+        normalizedMessage.includes('not allowed') ||
+        normalizedMessage.includes('could not be completed'));
+};
+export const unlockOrCreatePasskeyWallet = async ({ api, capabilities }) => {
+    if (typeof window === 'undefined' || window.PublicKeyCredential == null) {
+        throw new Error('Passkeys are not available in this browser.');
+    }
+    if (capabilities.method !== 'register') {
+        try {
+            const wallet = await unlockPasskeyWallet({ api });
+            if (wallet != null)
+                return wallet;
+        }
+        catch (error) {
+            if (!isPasskeyCredentialUnavailableError(error)) {
+                throw error;
+            }
+        }
+    }
+    return await registerPasskeyWallet({
+        api,
+        capabilities: {
+            ...capabilities,
+            method: 'register'
+        }
+    });
+};

package/dist/webauthn-server.d.ts

@@ -0,0 +1,62 @@
+import { verifyAuthenticationResponse, verifyRegistrationResponse } from '@simplewebauthn/server';
+import { type PasskeyVaultEnvelopeData } from './crypto';
+export declare const passkeyChallengeTtlMs: number;
+export type PasskeyVaultEnvelopeInput = {
+    address: string;
+    encryptedMnemonic: string;
+    salt: string;
+    nonce: string;
+    algorithm: string;
+    keyVersion: number;
+};
+export declare const validatePasskeyVaultEnvelopeInput: (input: PasskeyVaultEnvelopeInput) => PasskeyVaultEnvelopeInput & {
+    address: `0x${string}`;
+};
+export declare const createPasskeyChallengeExpiry: () => Date;
+export declare const getWebAuthnClientDataChallenge: (response: unknown) => string;
+export declare const createPasskeyRegistrationOptions: ({ rpId, userAddress, email }: {
+    rpId: string;
+    userAddress?: string | null;
+    email?: string | null;
+}) => Promise<import("@simplewebauthn/server").PublicKeyCredentialCreationOptionsJSON>;
+type VerifiedPasskeyRegistrationResponse = Awaited<ReturnType<typeof verifyRegistrationResponse>> & {
+    registrationInfo: NonNullable<Awaited<ReturnType<typeof verifyRegistrationResponse>>['registrationInfo']>;
+};
+export declare const verifyPasskeyRegistration: ({ response, expectedChallenge, expectedOrigin, expectedRpId, envelope }: {
+    response: unknown;
+    expectedChallenge: string;
+    expectedOrigin: string;
+    expectedRpId: string;
+    envelope: PasskeyVaultEnvelopeInput;
+}) => Promise<{
+    verification: VerifiedPasskeyRegistrationResponse;
+    vaultEnvelope: PasskeyVaultEnvelopeInput & {
+        address: `0x${string}`;
+    };
+}>;
+export declare const createPasskeyAuthenticationOptions: ({ rpId, credentials }: {
+    rpId: string;
+    credentials?: Array<{
+        credentialId: string;
+        transports: string[];
+    }>;
+}) => Promise<import("@simplewebauthn/server").PublicKeyCredentialRequestOptionsJSON>;
+export declare const verifyPasskeyAuthentication: ({ response, expectedChallenge, expectedOrigin, expectedRpId, credential }: {
+    response: unknown;
+    expectedChallenge: string;
+    expectedOrigin: string;
+    expectedRpId: string;
+    credential: {
+        credentialId: string;
+        publicKey: string;
+        signCount: number;
+    };
+}) => Promise<Awaited<ReturnType<typeof verifyAuthenticationResponse>>>;
+export declare const toPasskeyVaultEnvelopeData: ({ encryptedMnemonic, salt, nonce, algorithm, keyVersion }: {
+    encryptedMnemonic: string;
+    salt: string;
+    nonce: string;
+    algorithm: string;
+    keyVersion: number;
+}) => PasskeyVaultEnvelopeData;
+export {};

package/dist/webauthn-server.js

@@ -0,0 +1,133 @@
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from '@simplewebauthn/server';
+import { getAddress, isAddress } from 'viem';
+import { base64UrlToBytes, passkeyVaultAlgorithm, passkeyVaultKeyVersion } from './crypto';
+export const passkeyChallengeTtlMs = 5 * 60 * 1000;
+export const validatePasskeyVaultEnvelopeInput = (input) => {
+    if (!isAddress(input.address)) {
+        throw new Error('Passkey vault envelope requires a valid wallet address.');
+    }
+    if (input.encryptedMnemonic.trim() === '') {
+        throw new Error('Passkey vault envelope requires encrypted recovery phrase data.');
+    }
+    if (input.salt.trim() === '') {
+        throw new Error('Passkey vault envelope requires a salt.');
+    }
+    if (input.nonce.trim() === '') {
+        throw new Error('Passkey vault envelope requires a nonce.');
+    }
+    if (input.algorithm !== passkeyVaultAlgorithm) {
+        throw new Error('Passkey vault envelope algorithm is not supported.');
+    }
+    if (input.keyVersion !== passkeyVaultKeyVersion) {
+        throw new Error('Passkey vault envelope key version is not supported.');
+    }
+    return {
+        ...input,
+        address: getAddress(input.address)
+    };
+};
+export const createPasskeyChallengeExpiry = () => new Date(Date.now() + passkeyChallengeTtlMs);
+export const getWebAuthnClientDataChallenge = (response) => {
+    const clientDataJSON = response?.response?.clientDataJSON;
+    if (typeof clientDataJSON !== 'string' || clientDataJSON === '') {
+        throw new Error('WebAuthn response is missing client data.');
+    }
+    const clientData = JSON.parse(new TextDecoder().decode(base64UrlToBytes(clientDataJSON)));
+    if (typeof clientData.challenge !== 'string' || clientData.challenge === '') {
+        throw new Error('WebAuthn response is missing its challenge.');
+    }
+    return clientData.challenge;
+};
+export const createPasskeyRegistrationOptions = async ({ rpId, userAddress, email }) => await generateRegistrationOptions({
+    rpName: 'Organigram',
+    rpID: rpId,
+    userName: email ?? userAddress ?? 'Organigram passkey wallet',
+    userDisplayName: email ?? userAddress ?? 'Organigram passkey wallet',
+    attestationType: 'none',
+    authenticatorSelection: {
+        residentKey: 'required',
+        userVerification: 'required'
+    },
+    extensions: {
+        prf: {
+            eval: {
+                first: new Uint8Array(32)
+            }
+        }
+    }
+});
+export const verifyPasskeyRegistration = async ({ response, expectedChallenge, expectedOrigin, expectedRpId, envelope }) => {
+    const vaultEnvelope = validatePasskeyVaultEnvelopeInput(envelope);
+    const verification = await verifyRegistrationResponse({
+        response: response,
+        expectedChallenge,
+        expectedOrigin,
+        expectedRPID: expectedRpId,
+        requireUserVerification: true
+    });
+    if (!verification.verified || verification.registrationInfo == null) {
+        throw new Error('Passkey registration was not verified.');
+    }
+    return {
+        verification: verification,
+        vaultEnvelope
+    };
+};
+export const createPasskeyAuthenticationOptions = async ({ rpId, credentials = [] }) => {
+    const isDiscoverableAuthentication = credentials.length === 0;
+    return await generateAuthenticationOptions({
+        rpID: rpId,
+        userVerification: 'required',
+        ...(!isDiscoverableAuthentication
+            ? {
+                allowCredentials: credentials.map(credential => ({
+                    id: credential.credentialId,
+                    transports: credential.transports
+                }))
+            }
+            : {}),
+        extensions: {
+            prf: isDiscoverableAuthentication
+                ? {
+                    eval: {
+                        first: new Uint8Array(32)
+                    }
+                }
+                : {
+                    evalByCredential: Object.fromEntries(credentials.map(credential => [
+                        credential.credentialId,
+                        {
+                            first: new Uint8Array(32)
+                        }
+                    ]))
+                }
+        }
+    });
+};
+export const verifyPasskeyAuthentication = async ({ response, expectedChallenge, expectedOrigin, expectedRpId, credential }) => await verifyAuthenticationResponse({
+    response: response,
+    expectedChallenge,
+    expectedOrigin,
+    expectedRPID: expectedRpId,
+    credential: {
+        id: credential.credentialId,
+        publicKey: Buffer.from(credential.publicKey, 'base64url'),
+        counter: credential.signCount
+    },
+    requireUserVerification: true
+});
+export const toPasskeyVaultEnvelopeData = ({ encryptedMnemonic, salt, nonce, algorithm, keyVersion }) => {
+    if (algorithm !== passkeyVaultAlgorithm) {
+        throw new Error('Passkey vault envelope algorithm is not supported.');
+    }
+    if (keyVersion !== passkeyVaultKeyVersion) {
+        throw new Error('Passkey vault envelope key version is not supported.');
+    }
+    return {
+        algorithm,
+        keyVersion,
+        ciphertext: encryptedMnemonic,
+        salt,
+        nonce
+    };
+};

package/jest.config.ts

@@ -0,0 +1,32 @@
+import type { Config } from 'jest'
+
+const config: Config = {
+  preset: 'ts-jest/presets/default-esm',
+  testEnvironment: 'node',
+  watchman: false,
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@organigram/js$': '<rootDir>/__mocks__/organigram-js.ts',
+    '^wagmi$': '<rootDir>/__mocks__/wagmi.ts'
+  },
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          module: 'ESNext',
+          moduleResolution: 'bundler',
+          target: 'ESNext',
+          resolveJsonModule: true,
+          esModuleInterop: true,
+          types: ['jest', 'node']
+        },
+        diagnostics: false,
+        useESM: true
+      }
+    ]
+  }
+}
+
+export default config

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@organigram/passkey-wallet",
+  "version": "0.1.6",
+  "description": "Organigram Passkey Wallet.",
+  "author": "Organigram (https://organigram.ai)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "ssh://git@github.com:organigram/organigram.git",
+    "directory": "packages/passkey-wallet"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./crypto": "./dist/crypto.js",
+    "./vault": "./dist/vault.js",
+    "./webauthn-client": "./dist/webauthn-client.js",
+    "./webauthn-server": "./dist/webauthn-server.js",
+    "./wallet": "./dist/wallet.js",
+    "./eip1193": "./dist/eip1193.js",
+    "./rainbowkit": "./dist/rainbowkit.js",
+    "./errors": "./dist/errors.js"
+  },
+  "type": "module",
+  "peerDependencies": {
+    "@organigram/js": "workspace:^",
+    "@rainbow-me/rainbowkit": "^2.2.8",
+    "@simplewebauthn/browser": "^13.3.0",
+    "@simplewebauthn/server": "^13.3.2",
+    "viem": "^2.18.2",
+    "wagmi": "^2.16.3 || ^3.0.0"
+  },
+  "dependencies": {
+    "@organigram/js": "^0.1.6",
+    "@simplewebauthn/browser": "^13.3.0",
+    "@simplewebauthn/server": "^13.3.2",
+    "viem": "2.55.2"
+  },
+  "devDependencies": {
+    "@rainbow-me/rainbowkit": "^2.2.8",
+    "@tsconfig/recommended": "^1.0.7",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.19.37",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.3",
+    "typescript": "^5.5.4",
+    "wagmi": "^2.16.3"
+  },
+  "scripts": {
+    "docs:generate": "env-cmd --silent tsx ../docs/scripts/generatePackageTypeScriptReference.ts . passkey-wallet",
+    "build": "tsc -p tsconfig.build.json --pretty",
+    "test": "jest",
+    "typecheck": "tsc --noEmit --incremental false",
+    "lint": "eslint ."
+  },
+  "gitHead": "a2bf9b898c0c5f0dbcf80f2b9f705d5200519bb5"
+}

package/src/crypto.test.ts

@@ -0,0 +1,69 @@
+import {
+  decryptPasskeyVaultSecret,
+  derivePasskeyVaultKey,
+  encryptPasskeyVaultSecret,
+  isPasskeyPrfSupported
+} from './crypto'
+
+describe('passkey vault crypto', () => {
+  it('encrypts and decrypts vault plaintext with a PRF-derived key', async () => {
+    const salt = new Uint8Array(32).fill(2)
+    const nonce = new Uint8Array(12).fill(3)
+    const key = await derivePasskeyVaultKey({
+      prfOutput: new Uint8Array(32).fill(1),
+      salt
+    })
+
+    const envelope = await encryptPasskeyVaultSecret({
+      plaintext: 'secret vault payload',
+      key,
+      salt,
+      nonce
+    })
+
+    await expect(
+      decryptPasskeyVaultSecret({ envelope, key })
+    ).resolves.toBe('secret vault payload')
+  })
+
+  it('rejects vault envelopes decrypted with the wrong passkey output', async () => {
+    const salt = new Uint8Array(32).fill(13)
+    const key = await derivePasskeyVaultKey({
+      prfOutput: new Uint8Array(32).fill(1),
+      salt
+    })
+    const wrongKey = await derivePasskeyVaultKey({
+      prfOutput: new Uint8Array(32).fill(2),
+      salt
+    })
+    const envelope = await encryptPasskeyVaultSecret({
+      plaintext: 'secret vault payload',
+      key,
+      salt
+    })
+
+    await expect(
+      decryptPasskeyVaultSecret({ envelope, key: wrongKey })
+    ).rejects.toThrow(/Unable to decrypt passkey wallet/)
+  })
+
+  it('detects PRF support from client extension results', async () => {
+    await expect(isPasskeyPrfSupported({ credential: null })).resolves.toBe(
+      false
+    )
+    await expect(
+      isPasskeyPrfSupported({
+        credential: {
+          getClientExtensionResults: () => ({ prf: { enabled: true } })
+        }
+      })
+    ).resolves.toBe(true)
+    await expect(
+      isPasskeyPrfSupported({
+        credential: {
+          getClientExtensionResults: () => ({ prf: { enabled: false } })
+        }
+      })
+    ).resolves.toBe(false)
+  })
+})