@organigram/passkey-wallet 0.1.6

package/src/vault.ts

@@ -0,0 +1,77 @@
+import {
+  createEncryptionKeyVersion,
+  exportUserPrivateKey,
+  exportUserPublicKey,
+  generateUserEncryptionKeyPair
+} from '@organigram/js'
+
+export type PasskeyWalletVaultPayload = {
+  version: 1
+  recoveryPhrase: string
+  userEncryptionPrivateKey: JsonWebKey
+  userEncryptionPublicKey: JsonWebKey
+  userEncryptionKeyVersion: number
+}
+
+export const serializePasskeyWalletVaultPayload = ({
+  recoveryPhrase,
+  userEncryptionPrivateKey,
+  userEncryptionPublicKey,
+  userEncryptionKeyVersion
+}: Omit<PasskeyWalletVaultPayload, 'version'>): string =>
+  JSON.stringify({
+    version: 1,
+    recoveryPhrase,
+    userEncryptionPrivateKey,
+    userEncryptionPublicKey,
+    userEncryptionKeyVersion
+  } satisfies PasskeyWalletVaultPayload)
+
+export const parsePasskeyWalletVaultPayload = (
+  plaintext: string
+): PasskeyWalletVaultPayload => {
+  const payload = JSON.parse(plaintext) as Partial<PasskeyWalletVaultPayload>
+  if (payload.version !== 1) {
+    throw new Error('Unsupported passkey wallet vault payload version.')
+  }
+  if (
+    typeof payload.recoveryPhrase !== 'string' ||
+    payload.recoveryPhrase.trim() === ''
+  ) {
+    throw new Error('Passkey wallet vault is missing its recovery phrase.')
+  }
+  if (payload.userEncryptionPrivateKey == null) {
+    throw new Error('Passkey wallet vault is missing its IPFS private key.')
+  }
+  if (payload.userEncryptionPublicKey == null) {
+    throw new Error('Passkey wallet vault is missing its IPFS public key.')
+  }
+  if (
+    !Number.isInteger(payload.userEncryptionKeyVersion) ||
+    payload.userEncryptionKeyVersion == null
+  ) {
+    throw new Error('Passkey wallet vault has an invalid IPFS key version.')
+  }
+
+  return payload as PasskeyWalletVaultPayload
+}
+
+export const createPasskeyWalletVaultPayload = async (
+  recoveryPhrase: string
+): Promise<PasskeyWalletVaultPayload> => {
+  const userEncryptionKeyPair = await generateUserEncryptionKeyPair()
+  const userEncryptionPrivateKey = await exportUserPrivateKey(
+    userEncryptionKeyPair
+  )
+  const userEncryptionPublicKey = await exportUserPublicKey(
+    userEncryptionKeyPair
+  )
+
+  return {
+    version: 1,
+    recoveryPhrase,
+    userEncryptionPrivateKey,
+    userEncryptionPublicKey,
+    userEncryptionKeyVersion: createEncryptionKeyVersion()
+  }
+}

package/src/wallet.ts

@@ -0,0 +1,61 @@
+import { english, generateMnemonic, mnemonicToAccount } from 'viem/accounts'
+
+import type {
+  OrganigramPasskeyCapabilities,
+  UnlockedPasskeyWallet
+} from './types'
+import {
+  createPasskeyWalletVaultPayload,
+  type PasskeyWalletVaultPayload
+} from './vault'
+
+export const unlockedPasskeyWalletTtlMs = 15 * 60 * 1000
+
+export const createUnlockedPasskeyWallet = ({
+  address,
+  credentialId,
+  vaultPayload,
+  now = Date.now()
+}: {
+  address: `0x${string}`
+  credentialId: string
+  vaultPayload: PasskeyWalletVaultPayload
+  now?: number
+}): UnlockedPasskeyWallet => {
+  const account = mnemonicToAccount(vaultPayload.recoveryPhrase)
+
+  return {
+    address,
+    account,
+    recoveryPhrase: vaultPayload.recoveryPhrase,
+    userEncryptionPrivateKey: vaultPayload.userEncryptionPrivateKey,
+    userEncryptionPublicKey: vaultPayload.userEncryptionPublicKey,
+    userEncryptionKeyVersion: vaultPayload.userEncryptionKeyVersion,
+    credentialId,
+    expiresAt: now + unlockedPasskeyWalletTtlMs
+  }
+}
+
+export const createNewPasskeyWalletVault = async ({
+  capabilities
+}: {
+  capabilities: OrganigramPasskeyCapabilities
+}): Promise<{
+  address: `0x${string}`
+  vaultPayload: PasskeyWalletVaultPayload
+}> => {
+  const recoveryPhrase = generateMnemonic(english, 128)
+  const vaultPayload = await createPasskeyWalletVaultPayload(recoveryPhrase)
+  const account = mnemonicToAccount(recoveryPhrase)
+
+  return {
+    address: account.address,
+    vaultPayload: {
+      ...vaultPayload,
+      recoveryPhrase:
+        capabilities.method === 'register'
+          ? vaultPayload.recoveryPhrase
+          : vaultPayload.recoveryPhrase
+    }
+  }
+}

package/src/webauthn-client.test.ts

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import {
+  hydratePasskeyPrfOptions,
+  isPasskeyCredentialUnavailableError
+} from './webauthn-client'
+
+const webauthnClientPath = resolve('src/webauthn-client.ts')
+const walletPath = resolve('src/wallet.ts')
+
+describe('passkey WebAuthn client helpers', () => {
+  it('hydrates serialized WebAuthn PRF extension inputs before browser ceremonies', () => {
+    const serializedFirst = Object.fromEntries(
+      Array.from({ length: 32 }, (_, index) => [String(index), index])
+    )
+    const options = hydratePasskeyPrfOptions({
+      challenge: 'challenge',
+      user: {
+        id: 'user',
+        name: 'user@example.com',
+        displayName: 'user@example.com'
+      },
+      pubKeyCredParams: [],
+      extensions: {
+        prf: {
+          eval: {
+            first: serializedFirst
+          },
+          evalByCredential: {
+            credential: {
+              first: Array.from({ length: 32 }, (_, index) => 31 - index)
+            }
+          }
+        }
+      }
+    })
+
+    const prf = (options.extensions as {
+      prf?: {
+        eval?: { first?: unknown }
+        evalByCredential?: Record<string, { first?: unknown }>
+      }
+    }).prf
+
+    expect(prf?.eval?.first).toBeInstanceOf(Uint8Array)
+    expect(Array.from(prf?.eval?.first as Uint8Array)).toEqual(
+      Array.from({ length: 32 }, (_, index) => index)
+    )
+    expect(prf?.evalByCredential?.credential.first).toBeInstanceOf(Uint8Array)
+    expect(
+      Array.from(prf?.evalByCredential?.credential.first as Uint8Array)
+    ).toEqual(Array.from({ length: 32 }, (_, index) => 31 - index))
+  })
+
+  it('creates passkey wallets from a mnemonic recovery phrase, not a raw private key', () => {
+    const source = readFileSync(walletPath, 'utf8')
+
+    expect(source).toMatch(/generateMnemonic/)
+    expect(source).toMatch(/mnemonicToAccount/)
+    expect(source).toMatch(/english/)
+    expect(source).not.toMatch(/generatePrivateKey/)
+  })
+
+  it('exports a recovery phrase for mnemonic-backed passkey wallets', () => {
+    const source = readFileSync(webauthnClientPath, 'utf8')
+
+    expect(source).toMatch(/exportPasskeyWalletRecoveryPhrase/)
+    expect(source).toMatch(/recoveryPhrase/)
+    expect(source).not.toMatch(/exportPasskeyWalletPrivateKey/)
+  })
+
+  it('shows a user-facing message when a passkey provider does not return PRF output', () => {
+    const source = readFileSync(webauthnClientPath, 'utf8')
+    const errorsSource = readFileSync(resolve('src/errors.ts'), 'utf8')
+
+    expect(source).toMatch(/PasskeyPrfUnavailableError/)
+    expect(errorsSource).toMatch(
+      /This password manager is not compatible with Organigram's passkey wallet\. Please use a different password manager to unlock your wallet\./
+    )
+    expect(source).not.toMatch(/Ce gestionnaire/)
+    expect(errorsSource).not.toMatch(/Ce gestionnaire/)
+    expect(source).not.toMatch(/WebAuthn PRF is not supported/)
+  })
+
+  it('recognizes browser errors for missing passkey credentials', () => {
+    expect(
+      isPasskeyCredentialUnavailableError(
+        new DOMException('The operation was not allowed.', 'NotAllowedError')
+      )
+    ).toBe(true)
+    expect(
+      isPasskeyCredentialUnavailableError(
+        new Error('No credentials are available for this authenticator.')
+      )
+    ).toBe(true)
+    expect(
+      isPasskeyCredentialUnavailableError(
+        new Error('Passkey wallet envelope does not match its address.')
+      )
+    ).toBe(false)
+  })
+})

package/src/webauthn-client.ts

@@ -0,0 +1,430 @@
+import { startAuthentication, startRegistration } from '@simplewebauthn/browser'
+
+import {
+  base64UrlToBytes,
+  decryptPasskeyVaultSecret,
+  derivePasskeyVaultKey,
+  encryptPasskeyVaultSecret,
+  type PasskeyVaultEnvelopeData
+} from './crypto'
+import { PasskeyPrfUnavailableError } from './errors'
+import type {
+  OrganigramPasskeyCapabilities,
+  PasskeyRegistrationResult,
+  UnlockedPasskeyWallet
+} from './types'
+import { createNewPasskeyWalletVault, createUnlockedPasskeyWallet } from './wallet'
+import {
+  parsePasskeyWalletVaultPayload,
+  serializePasskeyWalletVaultPayload,
+  type PasskeyWalletVaultPayload
+} from './vault'
+
+export {
+  parsePasskeyWalletVaultPayload,
+  serializePasskeyWalletVaultPayload
+}
+export type { OrganigramPasskeyCapabilities, UnlockedPasskeyWallet } from './types'
+
+type PasskeyRegisterOptionsResponse = {
+  options: Parameters<typeof startRegistration>[0]['optionsJSON']
+}
+
+type PasskeyUnlockOptionsResponse = {
+  options: Parameters<typeof startAuthentication>[0]['optionsJSON']
+  hasCredentials: boolean
+}
+
+type PasskeyUnlockVerifyResponse = {
+  address: `0x${string}`
+  credentialId: string
+  envelope: PasskeyVaultEnvelopeData
+}
+
+type PasskeyExtensionResults = {
+  prf?: {
+    results?: {
+      first?: string | ArrayBuffer
+    }
+  }
+}
+
+type PasskeyPrfValue =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | number[]
+  | Record<string, number>
+
+export type PasskeyWalletApiClient = {
+  registerOptions: (input: {
+    address: `0x${string}`
+    email?: string | null
+    name?: string | null
+  }) => Promise<PasskeyRegisterOptionsResponse>
+  registerVerify: (input: {
+    response: unknown
+    envelope: {
+      address: `0x${string}`
+      encryptedMnemonic: string
+      salt: string
+      nonce: string
+      algorithm: string
+      keyVersion: number
+    }
+  }) => Promise<PasskeyRegistrationResult>
+  unlockOptions: () => Promise<PasskeyUnlockOptionsResponse>
+  unlockVerify: (input: {
+    response: unknown
+  }) => Promise<PasskeyUnlockVerifyResponse>
+}
+
+const readJson = async <T>(response: Response): Promise<T> => {
+  const body = (await response.json().catch(() => null)) as
+    | ({ error?: string } & T)
+    | null
+
+  if (!response.ok) {
+    throw new Error(
+      body?.error ?? `Request failed with status ${response.status}`
+    )
+  }
+
+  return body as T
+}
+
+const postJson = async <T>(
+  path: string,
+  body: Record<string, unknown>
+): Promise<T> => {
+  const response = await fetch(path, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  })
+
+  return await readJson<T>(response)
+}
+
+export const createFetchPasskeyWalletApiClient = (
+  basePath = '/api/auth/passkey'
+): PasskeyWalletApiClient => ({
+  registerOptions: async input =>
+    await postJson<PasskeyRegisterOptionsResponse>(
+      `${basePath}/register/options`,
+      input
+    ),
+  registerVerify: async input =>
+    await postJson<PasskeyRegistrationResult>(
+      `${basePath}/register/verify`,
+      input
+    ),
+  unlockOptions: async () =>
+    await postJson<PasskeyUnlockOptionsResponse>(
+      `${basePath}/unlock/options`,
+      {}
+    ),
+  unlockVerify: async input =>
+    await postJson<PasskeyUnlockVerifyResponse>(
+      `${basePath}/unlock/verify`,
+      input
+    )
+})
+
+const hydrateSerializedPrfValue = (value: unknown): unknown => {
+  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 as Record<string, unknown>)
+    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 as number)
+      )
+    }
+  }
+
+  return value
+}
+
+const hydratePrfValueSet = <T extends { first?: unknown; second?: unknown }>(
+  valueSet: T | undefined
+): T | undefined => {
+  if (valueSet == null) return valueSet
+
+  return {
+    ...valueSet,
+    first: hydrateSerializedPrfValue(valueSet.first) as PasskeyPrfValue,
+    ...(valueSet.second != null
+      ? {
+          second: hydrateSerializedPrfValue(valueSet.second) as PasskeyPrfValue
+        }
+      : {})
+  }
+}
+
+export const hydratePasskeyPrfOptions = <T extends { extensions?: unknown }>(
+  options: T
+): T => {
+  const extensions = options.extensions as
+    | {
+        prf?: {
+          eval?: { first?: unknown; second?: unknown }
+          evalByCredential?: Record<
+            string,
+            { first?: unknown; second?: unknown }
+          >
+        }
+      }
+    | undefined
+  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: unknown): Uint8Array => {
+  const first = (
+    response as {
+      clientExtensionResults?: PasskeyExtensionResults
+    }
+  ).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
+}: {
+  api: PasskeyWalletApiClient
+  address: `0x${string}`
+  vaultPayload: PasskeyWalletVaultPayload
+  email?: string | null
+  name?: string | null
+}): Promise<PasskeyRegistrationResult> {
+  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
+}: {
+  api: PasskeyWalletApiClient
+  capabilities: OrganigramPasskeyCapabilities
+}): Promise<UnlockedPasskeyWallet> => {
+  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
+}: {
+  api: PasskeyWalletApiClient
+}): Promise<UnlockedPasskeyWallet | null> => {
+  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
+}: {
+  api: PasskeyWalletApiClient
+  expectedAddress: `0x${string}`
+}): Promise<string> => {
+  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
+}: {
+  api: PasskeyWalletApiClient
+  wallet: UnlockedPasskeyWallet
+  name?: string
+}): Promise<PasskeyRegistrationResult> =>
+  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: unknown): boolean => {
+  if (typeof error !== 'object' || error == null) return false
+
+  const { name, message } = error as { name?: unknown; message?: unknown }
+  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
+}: {
+  api: PasskeyWalletApiClient
+  capabilities: OrganigramPasskeyCapabilities
+  targetChainId: number
+}): Promise<UnlockedPasskeyWallet> => {
+  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/src/webauthn-server.test.ts

@@ -0,0 +1,43 @@
+import {
+  passkeyChallengeTtlMs,
+  validatePasskeyVaultEnvelopeInput
+} from './webauthn-server'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const serverPath = resolve('src/webauthn-server.ts')
+
+describe('passkey WebAuthn server helpers', () => {
+  it('uses discoverable authentication without sending the global credential list', () => {
+    const source = readFileSync(serverPath, 'utf8')
+
+    expect(source).toMatch(/const isDiscoverableAuthentication = credentials\.length === 0/)
+    expect(source).toMatch(/isDiscoverableAuthentication\s+\?\s+\{\s*eval:/)
+    expect(source).toMatch(/\.\.\.\(!isDiscoverableAuthentication\s+\?\s+\{\s*allowCredentials:/)
+  })
+
+  it('requires discoverable credentials for passkey wallet registration', () => {
+    const source = readFileSync(serverPath, 'utf8')
+
+    expect(source).toMatch(/residentKey: 'required'/)
+  })
+
+  it('validates passkey vault envelopes without requiring a database', () => {
+    expect(
+      validatePasskeyVaultEnvelopeInput({
+        address: '0x0000000000000000000000000000000000000001',
+        encryptedMnemonic: 'ciphertext',
+        salt: 'salt',
+        nonce: 'nonce',
+        algorithm: 'AES-GCM-HKDF-SHA-256',
+        keyVersion: 1
+      })
+    ).toMatchObject({
+      address: '0x0000000000000000000000000000000000000001'
+    })
+  })
+
+  it('keeps passkey challenges short-lived', () => {
+    expect(passkeyChallengeTtlMs).toBe(5 * 60 * 1000)
+  })
+})