@organigram/passkey-wallet 0.1.6

package/README.md

@@ -0,0 +1,427 @@
+# Organigram Passkey Wallet
+
+**The ultimate web3 experience: unlock wallets and sign transactions with passkeys in a
+breeze.**
+
+Organigram Passkey Wallet is a lightweight, headless, EIP-1193 wallet powered by
+WebAuthn passkeys. It gives users the day-to-day experience they expect from
+modern passwordless apps while preserving the core property that matters in
+web3: fully and safely owning a standard Ethereum address.
+
+No cumbersome smart account deployment. No per-network account ceremony. No
+custodial key service. No protocol lock-in. Just a standard EOA, encrypted
+client-side, unlocked with rotative passkeys, and exposed through a wallet interface the
+Ethereum ecosystem already understands.
+
+```sh
+pnpm add @organigram/passkey-wallet
+```
+
+## Web3 identity, solved
+
+Most web3 onboarding still asks users to understand browser extensions, seed
+phrases, hardware devices, account abstraction, gas sponsorship, recovery
+contracts, network-specific deployments, signer permissions... before they have
+even used the product. Organigram Passkey Wallet takes a simpler path.
+
+The user creates a wallet in the browser. The wallet is a normal Ethereum EOA
+derived from a recovery phrase. That recovery phrase is encrypted locally with a
+key derived from a WebAuthn passkey PRF output, then stored only as an encrypted
+vault envelope. When the user returns, their passkey unlocks the vault and the
+EOA signs messages or transactions like any other wallet.
+
+The result is a wallet experience that feels native to the web:
+
+- passkeys for everyday unlocks;
+- standard EIP-1193 semantics for dapps;
+- one address across every EVM network;
+- multiple backup passkeys for the same address;
+- seed phrase export for disaster recovery;
+- no onchain deployment required;
+- no offchain signing relay or hosted signer to trust.
+
+## Highlights
+
+### Unlock and sign with passkeys
+
+Users unlock the wallet with a WebAuthn passkey. Once unlocked, the wallet signs
+messages, typed data, and transactions with the underlying EOA.
+
+### Fully-fledged EIP-1193 wallet
+
+The wallet exposes the same interface dapps already expect from injected wallets,
+WalletConnect wallets, and RainbowKit connectors. It supports account
+requests, chain switching, message signing, typed data signing, and transaction
+submission like any other standard wallet.
+
+### Multiple backup keys, one address
+
+Users can add additional passkeys for the same address. A backup phone, laptop,
+password manager, or security key can unlock the same encrypted wallet vault.
+
+### No smart-account deployment burden
+
+The address is a standard EOA, so it exists everywhere EVM accounts exist. There
+is no need to deploy account contracts across networks before the user can start.
+
+### Seed phrase recovery
+
+Passkeys optimize daily use. Seed phrase export preserves portability and gives
+users a disaster recovery path if every passkey is lost.
+
+### Headless and open source
+
+The package provides wallet, WebAuthn, vault, provider, and RainbowKit building
+blocks. You own the product surface. No hosted signer, no mandatory backend
+service, no strings attached.
+
+## What You Get
+
+Passkey Wallet is built for production UX:
+
+- users unlock and sign with passkeys;
+- backup passkeys can be added to the same address;
+- compromised or obsolete passkeys can be rotated out by the host app;
+- recovery phrases can be exported for disaster recovery;
+- the same EOA works on every supported EVM chain without deploying anything;
+- the package is headless, so product teams own the UI;
+- all sensitive wallet material is encrypted client-side before persistence.
+
+It is also intentionally boring where it should be boring: the address is a
+standard EOA, the dapp integration is EIP-1193, the RainbowKit integration is a
+wallet descriptor, and the WebAuthn server helpers are explicit about
+registration, authentication, challenges, origins, RP IDs, counters, and vault
+envelopes.
+
+## Architecture
+
+```txt
+Browser
+  WebAuthn passkey with PRF
+        |
+        v
+  HKDF-derived vault key
+        |
+        v
+  AES-GCM encrypted wallet vault envelope
+        |
+        v
+  Recovery phrase -> EOA -> EIP-1193 provider
+
+Server
+  WebAuthn challenges
+  Credential public keys
+  Credential counters
+  Encrypted vault envelopes
+```
+
+In practice, the flow is:
+
+1. Generate a recovery phrase in the browser.
+2. Derive a standard Ethereum EOA from that phrase.
+3. Create a WebAuthn passkey with `residentKey: "required"`,
+   `userVerification: "required"`, and the `prf` extension.
+4. Derive a vault encryption key from the PRF output and a random salt.
+5. Encrypt the wallet vault with AES-GCM.
+6. Store only the credential metadata and encrypted vault envelope server-side.
+7. On unlock, verify WebAuthn, recover the PRF output, decrypt the envelope, and
+   expose the EOA through EIP-1193.
+
+The private wallet material is generated and decrypted in the browser. The server
+stores only WebAuthn verification material and encrypted vault envelopes. The
+server never needs the seed phrase, the private key, or the decrypted user vault.
+
+The passkey unlocks the local vault. The EOA signs Ethereum messages and
+transactions. Those are separate responsibilities, which keeps the integration
+simple and compatible with existing web3 infrastructure.
+
+## Package Exports
+
+```ts
+import {
+  buildPasskeyWalletCapabilities,
+  buildEmailPasskeyCapabilities
+} from '@organigram/passkey-wallet'
+
+import {
+  createFetchPasskeyWalletApiClient,
+  unlockOrCreatePasskeyWallet,
+  registerAdditionalPasskeyCredential,
+  exportPasskeyWalletRecoveryPhrase
+} from '@organigram/passkey-wallet/webauthn-client'
+
+import {
+  createPasskeyRegistrationOptions,
+  createPasskeyAuthenticationOptions,
+  verifyPasskeyRegistration,
+  verifyPasskeyAuthentication
+} from '@organigram/passkey-wallet/webauthn-server'
+
+import {
+  createOrganigramPasskeyWallet,
+  isOrganigramPasskeyConnector
+} from '@organigram/passkey-wallet/rainbowkit'
+```
+
+The package is split by runtime boundary:
+
+- `@organigram/passkey-wallet` exposes shared wallet, vault, and capability
+  types.
+- `@organigram/passkey-wallet/webauthn-client` runs in the browser and performs
+  WebAuthn ceremonies, PRF extraction, vault encryption, vault decryption, and
+  wallet unlock.
+- `@organigram/passkey-wallet/webauthn-server` runs on the server and verifies
+  WebAuthn registration/authentication responses.
+- `@organigram/passkey-wallet/eip1193` exposes the provider implementation.
+- `@organigram/passkey-wallet/rainbowkit` exposes a RainbowKit wallet adapter.
+
+## Quick Start
+
+Create a browser API client:
+
+```ts
+import {
+  createFetchPasskeyWalletApiClient,
+  unlockOrCreatePasskeyWallet
+} from '@organigram/passkey-wallet/webauthn-client'
+import { buildPasskeyWalletCapabilities } from '@organigram/passkey-wallet'
+
+const api = createFetchPasskeyWalletApiClient('/api/auth/passkey')
+
+const wallet = await unlockOrCreatePasskeyWallet({
+  api,
+  capabilities: buildPasskeyWalletCapabilities(),
+  targetChainId: 1
+})
+
+const signature = await wallet.account.signMessage({
+  message: 'gm'
+})
+```
+
+That is the headless primitive. Most apps will wrap it in the RainbowKit adapter
+below so the passkey wallet appears next to other connection methods.
+
+## RainbowKit Integration
+
+```ts
+import { connectorsForWallets } from '@rainbow-me/rainbowkit'
+import { createConfig, http } from 'wagmi'
+import { mainnet, sepolia } from 'wagmi/chains'
+import { createOrganigramPasskeyWallet } from '@organigram/passkey-wallet/rainbowkit'
+import {
+  createFetchPasskeyWalletApiClient,
+  unlockOrCreatePasskeyWallet,
+  registerAdditionalPasskeyCredential,
+  exportPasskeyWalletRecoveryPhrase
+} from '@organigram/passkey-wallet/webauthn-client'
+
+const api = createFetchPasskeyWalletApiClient('/api/auth/passkey')
+
+const passkeyWallet = createOrganigramPasskeyWallet({
+  unlockOrCreatePasskeyWallet: async input =>
+    await unlockOrCreatePasskeyWallet({
+      api,
+      capabilities: input.capabilities,
+      targetChainId: input.targetChainId
+    }),
+  registerAdditionalPasskeyCredential: async input =>
+    await registerAdditionalPasskeyCredential({
+      api,
+      wallet: input.wallet,
+      name: input.name
+    }),
+  exportPasskeyWalletRecoveryPhrase: async input =>
+    await exportPasskeyWalletRecoveryPhrase({
+      api,
+      expectedAddress: input.expectedAddress
+    })
+})
+
+export const wagmiConfig = createConfig({
+  chains: [mainnet, sepolia],
+  connectors: connectorsForWallets(
+    [
+      {
+        groupName: 'Recommended',
+        wallets: [() => passkeyWallet]
+      }
+    ],
+    {
+      appName: 'Your App',
+      projectId: 'walletconnect-project-id'
+    }
+  ),
+  transports: {
+    [mainnet.id]: http(),
+    [sepolia.id]: http()
+  }
+})
+```
+
+From the dapp's perspective, this behaves like a wallet. Calling
+`personal_sign`, `eth_signTypedData_v4`, or `eth_sendTransaction` goes through
+the unlocked EOA account behind the passkey vault.
+
+## Server Responsibilities
+
+This package does not hide persistence behind a hosted service. Your app owns the
+server boundary.
+
+At minimum, store:
+
+- short-lived WebAuthn challenges;
+- credential IDs;
+- credential public keys;
+- credential transports;
+- signature counters;
+- the wallet address linked to each credential;
+- encrypted vault envelopes for each credential.
+
+Typical endpoints:
+
+```txt
+POST /api/auth/passkey/register/options
+POST /api/auth/passkey/register/verify
+POST /api/auth/passkey/unlock/options
+POST /api/auth/passkey/unlock/verify
+```
+
+The server helpers generate WebAuthn options and verify responses, but your app
+decides how to persist credentials, consume challenges, enforce origin/RP ID
+rules, and link credentials to users.
+
+## Suggested Data Model
+
+The package does not require a specific database, but a production integration
+usually needs records shaped like this:
+
+```ts
+type PasskeyCredential = {
+  credentialId: string
+  userAddress: `0x${string}`
+  publicKey: string
+  transports: string[]
+  signCount: number
+  createdAt: Date
+  updatedAt: Date
+}
+
+type PasskeyVaultEnvelope = {
+  credentialId: string
+  userAddress: `0x${string}`
+  encryptedMnemonic: string
+  salt: string
+  nonce: string
+  algorithm: string
+  keyVersion: number
+  createdAt: Date
+}
+
+type PasskeyChallenge = {
+  challenge: string
+  type: 'registration' | 'authentication'
+  expiresAt: Date
+  consumedAt?: Date
+}
+```
+
+Use short challenge TTLs, consume challenges exactly once, and enforce uniqueness
+for credential IDs.
+
+## Backup Keys And Rotation
+
+A passkey wallet should never depend on a single authenticator.
+
+Organigram Passkey Wallet supports adding another passkey to the same wallet by
+re-encrypting the same vault payload for a new credential. The address does not
+change. The user can keep using the same EOA while adding a laptop passkey, a
+phone passkey, a password manager passkey, or a hardware security key.
+
+Rotation is the same idea in reverse: remove obsolete credentials only when
+another recovery method remains. The package gives you the wallet and envelope
+building blocks; your product should decide the UX policy for deletion,
+confirmation, and minimum backup requirements.
+
+## Recovery
+
+Passkeys make daily wallet use simple, but users still need an escape hatch.
+
+Organigram Passkey Wallet keeps the wallet portable by deriving the EOA from a
+standard recovery phrase. If every passkey is lost, the user can recover with the
+exported seed phrase in any compatible wallet. That is the difference between
+passwordless convenience and platform lock-in.
+
+The recovery phrase should always be exported before the user loses all passkeys.
+The package provides a helper to export the recovery phrase after a successful
+WebAuthn ceremony, but cannot do so after the access to the vault is lost.
+
+## Security Model
+
+Organigram Passkey Wallet is non-custodial by design.
+
+The browser creates the wallet. The browser encrypts the vault. The browser
+decrypts the vault after a successful WebAuthn ceremony. The server stores
+encrypted envelopes and verifies that WebAuthn responses are valid for the
+expected challenge, origin, RP ID, and credential public key.
+
+This model assumes:
+
+- WebAuthn PRF support is required for the passkey vault flow;
+- the host app serves the wallet UI from a trustworthy origin;
+- the server correctly expires and consumes challenges;
+- the server verifies credential counters and user verification;
+- recovery phrase export is treated as a sensitive operation;
+- backup passkey deletion never leaves the user without a recovery method;
+- a compromised browser session can access unlocked wallet material while it is
+  in memory.
+
+The package avoids custodial recovery, hosted signing, and smart-account
+dependency by keeping the encrypted EOA vault offchain and user-portable.
+
+## Browser Compatibility
+
+The passkey vault depends on the WebAuthn `prf` extension. Browsers or password
+managers that do not return PRF output cannot unlock the encrypted vault.
+
+Apps should present a clear fallback when PRF is unavailable:
+
+- retry with another passkey provider;
+- use a platform authenticator that supports PRF;
+- connect an external crypto wallet instead.
+
+## What This Is Not
+
+Organigram Passkey Wallet is not a smart account framework. It does not require
+4337 infrastructure, paymasters, bundlers, module registries, or per-chain
+deployments.
+
+It is not a custodial wallet. The server does not receive the recovery phrase or
+private key in clear text.
+
+It is not a hosted wallet service. The package is open source and headless; the
+host app owns persistence, authentication policy, UI, and deployment.
+
+It is not a replacement for hardware wallets in high-assurance custody flows. It
+is designed for the safest mainstream web UX possible while staying portable and
+EVM-compatible.
+
+## Philosophy
+
+The safest web3 UX is the one users can actually complete.
+
+Organigram Passkey Wallet keeps the cryptographic model understandable:
+
+- the wallet is an EOA;
+- the unlock method is a passkey;
+- the backup is another passkey;
+- the disaster recovery path is a seed phrase;
+- the dapp interface is EIP-1193;
+- the server stores encrypted envelopes, not keys.
+
+That is the whole point: the most frictionless, simplest, and safest UX possible
+for web3, without strings attached.
+
+## License
+
+MIT

package/__mocks__/organigram-js.ts

@@ -0,0 +1,19 @@
+export const createEncryptionKeyVersion = (): number => 1
+
+export const generateUserEncryptionKeyPair = async (): Promise<CryptoKeyPair> =>
+  await crypto.subtle.generateKey(
+    {
+      name: 'ECDH',
+      namedCurve: 'P-256'
+    },
+    true,
+    ['deriveKey']
+  )
+
+export const exportUserPrivateKey = async (
+  keyPair: CryptoKeyPair
+): Promise<JsonWebKey> => await crypto.subtle.exportKey('jwk', keyPair.privateKey)
+
+export const exportUserPublicKey = async (
+  keyPair: CryptoKeyPair
+): Promise<JsonWebKey> => await crypto.subtle.exportKey('jwk', keyPair.publicKey)

package/__mocks__/wagmi.ts

@@ -0,0 +1 @@
+export const createConnector = (factory: unknown): unknown => factory

package/dist/crypto.d.ts

@@ -0,0 +1,39 @@
+export declare const passkeyVaultAlgorithm = "AES-GCM-HKDF-SHA-256";
+export declare const passkeyVaultKeyVersion = 1;
+export type PasskeyVaultEnvelopeData = {
+    algorithm: typeof passkeyVaultAlgorithm;
+    keyVersion: typeof passkeyVaultKeyVersion;
+    ciphertext: string;
+    salt: string;
+    nonce: string;
+};
+type DerivePasskeyVaultKeyInput = {
+    prfOutput: Uint8Array;
+    salt: Uint8Array;
+};
+type EncryptPasskeyVaultSecretInput = {
+    plaintext: string;
+    key: CryptoKey;
+    salt: Uint8Array;
+    nonce?: Uint8Array;
+};
+type DecryptPasskeyVaultSecretInput = {
+    envelope: PasskeyVaultEnvelopeData;
+    key: CryptoKey;
+};
+type PrfSupportCredential = {
+    getClientExtensionResults: () => {
+        prf?: {
+            enabled?: boolean;
+        };
+    };
+};
+export declare const bytesToBase64Url: (bytes: Uint8Array) => string;
+export declare const base64UrlToBytes: (value: string) => Uint8Array;
+export declare const derivePasskeyVaultKey: ({ prfOutput, salt }: DerivePasskeyVaultKeyInput) => Promise<CryptoKey>;
+export declare const encryptPasskeyVaultSecret: ({ plaintext, key, salt, nonce }: EncryptPasskeyVaultSecretInput) => Promise<PasskeyVaultEnvelopeData>;
+export declare const decryptPasskeyVaultSecret: ({ envelope, key }: DecryptPasskeyVaultSecretInput) => Promise<string>;
+export declare const isPasskeyPrfSupported: ({ credential }: {
+    credential: PrfSupportCredential | null;
+}) => Promise<boolean>;
+export {};

package/dist/crypto.js

@@ -0,0 +1,95 @@
+export const passkeyVaultAlgorithm = 'AES-GCM-HKDF-SHA-256';
+export const passkeyVaultKeyVersion = 1;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const getCrypto = () => {
+    if (globalThis.crypto == null) {
+        throw new Error('WebCrypto is not available in this environment.');
+    }
+    return globalThis.crypto;
+};
+const toArrayBuffer = (bytes) => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+export const bytesToBase64Url = (bytes) => bytesToBase64(bytes)
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replaceAll('=', '');
+export const base64UrlToBytes = (value) => {
+    const normalized = value.replaceAll('-', '+').replaceAll('_', '/');
+    const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), '=');
+    return base64ToBytes(padded);
+};
+const bytesToBase64 = (bytes) => {
+    if (typeof Buffer !== 'undefined') {
+        return Buffer.from(bytes).toString('base64');
+    }
+    let binary = '';
+    bytes.forEach(byte => {
+        binary += String.fromCharCode(byte);
+    });
+    return btoa(binary);
+};
+const base64ToBytes = (value) => {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(value, 'base64'));
+    }
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+};
+export const derivePasskeyVaultKey = async ({ prfOutput, salt }) => {
+    if (prfOutput.byteLength !== 32) {
+        throw new Error('Passkey PRF output must be 32 bytes.');
+    }
+    if (salt.byteLength !== 32) {
+        throw new Error('Passkey vault salt must be 32 bytes.');
+    }
+    const crypto = getCrypto();
+    const baseKey = await crypto.subtle.importKey('raw', toArrayBuffer(prfOutput), 'HKDF', false, ['deriveKey']);
+    return await crypto.subtle.deriveKey({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: toArrayBuffer(salt),
+        info: textEncoder.encode('organigram-passkey-wallet-v1')
+    }, baseKey, {
+        name: 'AES-GCM',
+        length: 256
+    }, false, ['encrypt', 'decrypt']);
+};
+export const encryptPasskeyVaultSecret = async ({ plaintext, key, salt, nonce = getCrypto().getRandomValues(new Uint8Array(12)) }) => {
+    if (plaintext.trim() === '') {
+        throw new Error('Passkey wallet vault plaintext cannot be empty.');
+    }
+    const ciphertext = await getCrypto().subtle.encrypt({
+        name: 'AES-GCM',
+        iv: toArrayBuffer(nonce)
+    }, key, textEncoder.encode(plaintext));
+    return {
+        algorithm: passkeyVaultAlgorithm,
+        keyVersion: passkeyVaultKeyVersion,
+        ciphertext: bytesToBase64Url(new Uint8Array(ciphertext)),
+        salt: bytesToBase64Url(salt),
+        nonce: bytesToBase64Url(nonce)
+    };
+};
+export const decryptPasskeyVaultSecret = async ({ envelope, key }) => {
+    try {
+        if (envelope.algorithm !== passkeyVaultAlgorithm) {
+            throw new Error('Unsupported passkey wallet vault algorithm.');
+        }
+        if (envelope.keyVersion !== passkeyVaultKeyVersion) {
+            throw new Error('Unsupported passkey wallet vault key version.');
+        }
+        const plaintext = await getCrypto().subtle.decrypt({
+            name: 'AES-GCM',
+            iv: toArrayBuffer(base64UrlToBytes(envelope.nonce))
+        }, key, toArrayBuffer(base64UrlToBytes(envelope.ciphertext)));
+        return textDecoder.decode(plaintext);
+    }
+    catch (error) {
+        throw new Error('Unable to decrypt passkey wallet.', { cause: error });
+    }
+};
+export const isPasskeyPrfSupported = async ({ credential }) => credential?.getClientExtensionResults().prf?.enabled === true;

package/dist/eip1193.d.ts

@@ -0,0 +1,24 @@
+import type { Chain, EIP1193RequestFn } from 'viem';
+import type { PasskeyProviderEvent, PasskeyProviderListener, PasskeyRegistrationResult, UnlockedPasskeyWallet } from './types';
+export type OrganigramPasskeyProvider = {
+    request: EIP1193RequestFn;
+    on: (event: PasskeyProviderEvent, listener: PasskeyProviderListener) => void;
+    removeListener: (event: PasskeyProviderEvent, listener: PasskeyProviderListener) => void;
+};
+export type OrganigramPasskeyProviderActions = {
+    registerAdditionalPasskeyCredential: (input: {
+        wallet: UnlockedPasskeyWallet;
+        name?: string;
+    }) => Promise<PasskeyRegistrationResult>;
+    exportPasskeyWalletRecoveryPhrase: (input: {
+        expectedAddress: `0x${string}`;
+    }) => Promise<string>;
+};
+export declare const createPasskeyWalletProvider: ({ wallet, chain, rpcUrl, switchChain, actions }: {
+    wallet: UnlockedPasskeyWallet;
+    chain: Chain;
+    rpcUrl: string;
+    switchChain: (chainId: number) => Chain;
+    actions: OrganigramPasskeyProviderActions;
+}) => OrganigramPasskeyProvider;
+export declare const normalizePasskeyWalletAddress: (address: `0x${string}`) => `0x${string}`;