Organigram Passkey Wallet

The ultimate web3 experience: unlock wallets and sign transactions with recoverable passkeys in a breeze.

Organigram Passkey Wallet is a lightweight Ethereum 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 via Wagmi and Rainbowkit.

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:

• users unlock and sign with passkeys;
• multiple backup passkeys can be added to the same address;
• compromised or obsolete passkeys can be rotated;
• seed phrases can be exported for disaster prevention;
• encrypted backup vaults can be saved remotely or locally
• one address across every EVM network;
• standard EIP-1193 semantics for dapps;
• 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.

A fully-fledged Ethereum 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 export

Passkeys optimize daily use, while the capacity to export seed phrases preserves portability and gives users a disaster prevention path for the case where every passkey is lost.

Recoverable vaults

The app exports an encrypted vault that can be saved to and restored from anywhere. Use remote servers, save locally or in a password manager without fear to leak sensitive information.

Wallet UI

This package builds a production-ready app used to serve the wallet locally or on custom domains.

build:artifact builds the TypeScript library to app-dist, and packages a deterministic artifacts/passkey-wallet-app-v<version>.tar.gz with a .sha256 checksum and manifest.

Local development

pnpm dev serves the wallet at https://localhost:3002, behind an HTTPS proxy in front of Vite (port 3003). The first run creates a local certificate with mkcert.

Any other hostname can be passed as an argument (pnpm dev my.host.test): the certificate is regenerated to include it.

Run your own wallet

You do not have to trust the servers of wallet.organigram.ai, nor the code they serve, to use your Organigram accounts. The local-organigram profile serves your own copy of the wallet, built from this source code, on your machine:

(or pnpm passkey-wallet dev local-organigram from the repository root), then open https://local.wallet.organigram.ai:3002.

local.wallet.organigram.ai is a subdomain of wallet.organigram.ai, so this copy unlocks the same passkeys, hence the same accounts: the profile sets the passkey RP ID to wallet.organigram.ai. Its browser storage is separate, so restore your encrypted vault there once (see Recoverable vaults): your passkey then unlocks it as usual. Your keys never leave your browser, and signing in no longer depends on wallet.organigram.ai being online or unaltered.

The name already resolves to 127.0.0.1 through public DNS, so no setup is needed. For a stronger guarantee, also resolve it in your hosts file: a tampered DNS record could otherwise send it to a server able to request the PRF output of your passkeys (macOS and Linux):

To use it from any app, turn on Settings → Your own wallet on wallet.organigram.ai. Requests then go to your copy, and once it has answered, apps open it directly: wallet.organigram.ai is no longer loaded at all. If your copy stops answering, for instance because it is not running, the request goes back to wallet.organigram.ai after a few seconds.

Apps that use this package accept the local copy of the official wallet without any setting, on their pages and on their wallet endpoints (sign-in challenge, vault backups, RPC).

A wallet deployed elsewhere can offer the same to its users with its own local copy, served under a subdomain of its host so that it unlocks the same passkeys:

• the deployment declares it with localWalletOrigin in passkey-wallet.config.json (or PASSKEY_WALLET_LOCAL_WALLET_ORIGIN at build time), for example https://local.wallet.example.com:3002;
• users run it with PASSKEY_WALLET_PASSKEY_RP_ID=wallet.example.com pnpm dev local.wallet.example.com;
• apps accept it with NEXT_PUBLIC_ORGANIGRAM_PASSKEY_WALLET_LOCAL_URL, next to NEXT_PUBLIC_ORGANIGRAM_PASSKEY_WALLET_URL. The value is ignored unless it is an HTTPS subdomain of the wallet host.

Each production build of https://wallet.organigram.ai is published as a release of this repository, with the SHA-256 of every served file. To check that the live wallet serves one of these releases unchanged, run from a clone of this repository:

With Node.js 24 and pnpm 10.28, rebuilding a release commit reproduces its files:

Architecture

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.

Quick Start

Create and unlock vaults in the UI with wallet helpers:

The passkey ceremony and vault decryption happen in the wallet origin. Dapps should integrate through the remote connector.

RainbowKit Integration

From the dapp's perspective, this behaves like a wallet. Calling personal_sign, eth_signTypedData_v4, or eth_sendTransaction goes through the wallet origin, where the user approves the request.

Server Responsibilities

The wallet app is static. A server is optional and should only receive encrypted backup packages or dapp sign-in challenges. It should not create WebAuthn credentials, unlock vaults, or receive decrypted wallet material.

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 the account with the seed phrase, or use it in any other wallet.

The recovery phrase should always be exported before the user loses all passkeys. The package provides a helper to export a seed phrase after a successful WebAuthn ceremony, but cannot do so after all 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 read unlocked wallet material while a request is being processed.

Passkey scope

Passkeys are created for the exact hostname serving the wallet (for example wallet.organigram.ai). Any page served under the passkey RP ID can request the PRF output that decrypts the vault, so no other application should be hosted under it. Dapps never need the wallet RP ID: they reach the wallet through its popup and postMessage.

A wallet served from a subdomain can reuse the passkeys of its parent wallet host by setting passkeyRpId in passkey-wallet.config.json (or PASSKEY_WALLET_PASSKEY_RP_ID) to that host. The value must be the current hostname or one of its parent domains. pnpm dev local-organigram does so for wallet.organigram.ai (see Run your own wallet).

The wallet sends a Content-Security-Policy that forbids third-party scripts and any framing of the wallet origin.

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; the host app owns persistence, authentication, and backup policy.

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.

License

MIT

Connect an app

Apps reach the wallet through createOrganigramRemotePasskeyWallet(), a RainbowKit wallet whose wagmi connector opens the wallet in a popup. Each connection, signature, transaction or encryption is a request that the user approves in the popup. Apps exchange requests and answers with the popup through postMessage, and only accept answers from the wallet origin and its local copy. Signatures are checked against the connected address and chain before they reach the app. Private keys never leave the wallet origin.

CreateOrganigramRemotePasskeyWalletInput

Definition

export type CreateOrganigramRemotePasskeyWalletInput = {

walletOrigin?: string;

requestConnect?: RemoteRequestConnect;

requestPersonalSign?: RemoteRequestPersonalSign;

requestSignTypedData?: RemoteRequestSignTypedData;

requestSendTransaction?: RemoteRequestSendTransaction;

};

HydrateOrganigramRemoteWalletConnectionConnector

Definition

export type HydrateOrganigramRemoteWalletConnectionConnector = {

id: string;

};

HydrateOrganigramRemoteWalletConnectionInput

Definition

export type HydrateOrganigramRemoteWalletConnectionInput = {

address: `0x${string}`;

chainId?: number;

};

HydrateOrganigramRemoteWalletConnectionOptions

Definition

export type HydrateOrganigramRemoteWalletConnectionOptions<TConnector extends HydrateOrganigramRemoteWalletConnectionConnector> = HydrateOrganigramRemoteWalletConnectionInput & {

connectors: readonly TConnector[];

connectAsync: (input: {

connector: TConnector;

}) => Promise<unknown>;

defaultChainId?: number;

};

OrganigramRemotePasskeyWalletConnection

It only holds the public address and chain, never a key: every signature still asks the user in the wallet popup.

Definition

export type OrganigramRemotePasskeyWalletConnection = {

version: 1;

address: `0x${string}`;

chainId: number;

connectedAt: string;

};

beginOrganigramWalletApprovalSequence

Signature

beginOrganigramWalletApprovalSequence: (input: {

count: number;

label?: string;

}) => (() => void)

clearOrganigramRemotePasskeyWalletConnection

Signature

clearOrganigramRemotePasskeyWalletConnection: () => void

createOrganigramRemotePasskeyWallet

The connector exposes an EIP-1193 provider. Account and signing requests open the wallet popup, and every signature is checked against the connected address and chain. Other JSON-RPC requests go to the default RPC URL of the active chain.

Signature

createOrganigramRemotePasskeyWallet: (input?: CreateOrganigramRemotePasskeyWalletInput) => Wallet

Parameters

Name	Type	Description
input	CreateOrganigramRemotePasskeyWalletInput	The origin of the wallet, and replacements of its requests.

getOrganigramRemotePasskeyWalletConnection

Signature

getOrganigramRemotePasskeyWalletConnection: () => OrganigramRemotePasskeyWalletConnection | null

Returns

Type	Description
OrganigramRemotePasskeyWalletConnection | null	The connection, or null if none is valid.

hydrateOrganigramRemoteWalletConnection

Remembers the connection, then connects the wallet connector, which restores it. If connecting fails, the connection is forgotten.

Signature

hydrateOrganigramRemoteWalletConnection: <TConnector extends HydrateOrganigramRemoteWalletConnectionConnector>(input: HydrateOrganigramRemoteWalletConnectionOptions<TConnector>) => Promise<void>

rememberOrganigramRemotePasskeyWalletConnection

Signature

rememberOrganigramRemotePasskeyWalletConnection: (input: {

address: `0x${string}`;

chainId: number;

}) => void

Parameters

Name	Type	Description
input	{ address: `0x${string}`; chainId: number; }	The connected address and chain.

organigramRemotePasskeyWalletId

Definition

const organigramRemotePasskeyWalletId = "organigram-passkeys"

PasskeyWalletConnectPopupInput

Definition

export type PasskeyWalletConnectPopupInput = PasskeyWalletRemotePopupInput;

PasskeyWalletConnectRequest

Definition

export type PasskeyWalletConnectRequest = PasskeyWalletRemoteRequestBase & {

type: typeof passkeyWalletConnectType;

};

PasskeyWalletConnectResult

Definition

export type PasskeyWalletConnectResult = PasskeyWalletRemoteResultBase & {

type: typeof passkeyWalletConnectResultType;

};

PasskeyWalletDecryptPayloadRequest

Definition

export type PasskeyWalletDecryptPayloadRequest = PasskeyWalletRemoteRequestBase & {

type: typeof passkeyWalletDecryptPayloadType;

address: `0x${string}`;

encryptedPayload: WalletEncryptedPayload;

};

PasskeyWalletDecryptPayloadResult

Definition

export type PasskeyWalletDecryptPayloadResult = PasskeyWalletRemoteResultBase & {

type: typeof passkeyWalletDecryptPayloadResultType;

plaintext: string;

};

PasskeyWalletEncryptPayloadRequest

Definition

export type PasskeyWalletEncryptPayloadRequest = PasskeyWalletRemoteRequestBase & {

type: typeof passkeyWalletEncryptPayloadType;

address: `0x${string}`;

plaintext: string;

};

PasskeyWalletEncryptPayloadResult

Definition

export type PasskeyWalletEncryptPayloadResult = PasskeyWalletRemoteResultBase & {

type: typeof passkeyWalletEncryptPayloadResultType;

encryptedPayload: WalletEncryptedPayload;

};

PasskeyWalletRemoteErrorResult

Definition

export type PasskeyWalletRemoteErrorResult = Omit<PasskeyWalletRemoteResultBase, 'address'> & {

type: typeof passkeyWalletRemoteErrorResultType;

address?: undefined;

error: string;

};

PasskeyWalletRemotePopupInput

Definition

export type PasskeyWalletRemotePopupInput = {

walletOrigin?: string;

appOrigin?: string;

chainId: number;

requestId?: string;

requestedAt?: string;

approvalStep?: number;

approvalCount?: number;

approvalLabel?: string;

};

PasskeyWalletRemoteRequest

Definition

export type PasskeyWalletRemoteRequest = PasskeyWalletConnectRequest | PasskeyWalletSignMessageRequest | PasskeyWalletSignTypedDataRequest | PasskeyWalletSendTransactionRequest | PasskeyWalletEncryptPayloadRequest | PasskeyWalletDecryptPayloadRequest;

PasskeyWalletRemoteRequestPayloadMessage

Definition

export type PasskeyWalletRemoteRequestPayloadMessage = {

type: typeof passkeyWalletRemoteRequestPayloadType;

version: 1;

request: PasskeyWalletRemoteRequest;

};

PasskeyWalletRemoteRequestType

Definition

export type PasskeyWalletRemoteRequestType = typeof passkeyWalletConnectType | typeof passkeyWalletSignMessageType | typeof passkeyWalletSignTypedDataType | typeof passkeyWalletSendTransactionType | typeof passkeyWalletEncryptPayloadType | typeof passkeyWalletDecryptPayloadType;

PasskeyWalletRemoteResult

Definition

export type PasskeyWalletRemoteResult = PasskeyWalletConnectResult | PasskeyWalletSignMessageResult | PasskeyWalletSignTypedDataResult | PasskeyWalletSendTransactionResult | PasskeyWalletEncryptPayloadResult | PasskeyWalletDecryptPayloadResult | PasskeyWalletRemoteErrorResult;

PasskeyWalletSendTransactionRequest

Definition

export type PasskeyWalletSendTransactionRequest = PasskeyWalletRemoteRequestBase & {

type: typeof passkeyWalletSendTransactionType;

address: `0x${string}`;

transaction: PasskeyWalletTransaction;

};

PasskeyWalletSendTransactionResult

Definition

export type PasskeyWalletSendTransactionResult = PasskeyWalletRemoteResultBase & {

type: typeof passkeyWalletSendTransactionResultType;

transactionHash: `0x${string}`;

};

PasskeyWalletSignMessagePopupInput

Definition

export type PasskeyWalletSignMessagePopupInput = PasskeyWalletRemotePopupInput & {

address: `0x${string}`;

message: string;

};

PasskeyWalletSignMessageRequest

Definition

export type PasskeyWalletSignMessageRequest = PasskeyWalletRemoteRequestBase & {

type: typeof passkeyWalletSignMessageType;

address: `0x${string}`;

message: string;

};

PasskeyWalletSignMessageResult

Definition

export type PasskeyWalletSignMessageResult = PasskeyWalletRemoteResultBase & {

type: typeof passkeyWalletSignMessageResultType;

message: string;

signature: `0x${string}`;

};

PasskeyWalletSignTypedDataPopupInput

Definition

export type PasskeyWalletSignTypedDataPopupInput = PasskeyWalletRemotePopupInput & {

address: `0x${string}`;

typedData: PasskeyWalletTypedData;

};

PasskeyWalletSignTypedDataRequest

Definition

export type PasskeyWalletSignTypedDataRequest = PasskeyWalletRemoteRequestBase & {

type: typeof passkeyWalletSignTypedDataType;

address: `0x${string}`;

typedData: PasskeyWalletTypedData;

};

PasskeyWalletSignTypedDataResult

Definition

export type PasskeyWalletSignTypedDataResult = PasskeyWalletRemoteResultBase & {

type: typeof passkeyWalletSignTypedDataResultType;

typedData: PasskeyWalletTypedData;

signature: `0x${string}`;

};

PasskeyWalletTransaction

Definition

export type PasskeyWalletTransaction = {

from: `0x${string}`;

to: `0x${string}`;

data?: `0x${string}`;

value?: `0x${string}`;

gas?: `0x${string}`;

gasPrice?: `0x${string}`;

maxFeePerGas?: `0x${string}`;

maxPriorityFeePerGas?: `0x${string}`;

nonce?: `0x${string}`;

};

PasskeyWalletTypedData

Definition

export type PasskeyWalletTypedData = {

domain: Record<string, unknown>;

types: Record<string, ReadonlyArray<{

name: string;

type: string;

}>>;

primaryType: string;

message: Record<string, unknown>;

};

assertPasskeyWalletSignMessageResult

Recovers the signer from the signature, so that a forged answer is rejected. This only works for EOA signatures, which the wallet produces.

Signature

assertPasskeyWalletSignMessageResult: (input: {

result: PasskeyWalletSignMessageResult;

address: `0x${string}`;

chainId: number;

message: string;

}) => Promise<void>

Parameters

Name	Type	Description
input	{ result: PasskeyWalletSignMessageResult; address: `0x${string}`; chainId: number; message: string; }	The answer, and the address, chain and message of the request.

assertPasskeyWalletSignTypedDataResult

Recovers the signer from the signature, so that a forged answer is rejected.

Signature

assertPasskeyWalletSignTypedDataResult: (input: {

result: PasskeyWalletSignTypedDataResult;

address: `0x${string}`;

chainId: number;

typedData: PasskeyWalletTypedData;

}) => Promise<void>

Parameters

Name	Type	Description
input	{ result: PasskeyWalletSignTypedDataResult; address: `0x${string}`; chainId: number; typedData: PasskeyWalletTypedData; }	The answer, and the address, chain and typed data of the request.

buildPasskeyWalletRemotePopupUrl

Every request other than connect is then delivered by postMessage. The wallet reads the requesting origin from the browser-authenticated MessageEvent instead of trusting the appOrigin written in the URL, and no message, transaction or secret lands in a URL.

Signature

buildPasskeyWalletRemotePopupUrl: (input: PasskeyWalletRemotePopupInput & {

type: PasskeyWalletRemoteRequestType;

address?: `0x${string}`;

}) => URL

Parameters

Name	Type	Description
input	PasskeyWalletRemotePopupInput & { type: PasskeyWalletRemoteRequestType; address?: `0x${string}`; }	The request, with its type and address.

isPasskeyWalletRemoteRequestPayloadMessage

The domain of the request must be the host of its appOrigin. The wallet must still compare appOrigin with the origin of the MessageEvent, which the browser authenticates.

Signature

isPasskeyWalletRemoteRequestPayloadMessage: (value: unknown, expectedRequestId?: string) => value is PasskeyWalletRemoteRequestPayloadMessage

Parameters

Name	Type	Description
value	unknown	The data of the message.
expectedRequestId	string	The identifier of the expected request, if known.

isPasskeyWalletTransaction

Signature

isPasskeyWalletTransaction: (value: unknown) => value is PasskeyWalletTransaction

Parameters

Name	Type	Description
value	unknown	The value to check.

parsePasskeyWalletRemoteRequest

Rejects encrypt and decrypt requests, which must be delivered by postMessage, and requests whose domain is not the host of their appOrigin.

Signature

parsePasskeyWalletRemoteRequest: (params: URLSearchParams) => PasskeyWalletRemoteRequest

Parameters

Name	Type	Description
params	URLSearchParams	The URL parameters.

parsePasskeyWalletTypedData

Signature

parsePasskeyWalletTypedData: (value: unknown) => PasskeyWalletTypedData

Parameters

Name	Type	Description
value	unknown	The typed data, or its JSON.

requestPasskeyWalletConnect

Signature

requestPasskeyWalletConnect: (input: PasskeyWalletConnectPopupInput & {

timeoutMs?: number;

}) => Promise<PasskeyWalletConnectResult>

Parameters

Name	Type	Description
input	PasskeyWalletConnectPopupInput & { timeoutMs?: number; }	The request, and a timeout, 5 minutes by default.

Returns

Type	Description
Promise<PasskeyWalletConnectResult>	The answer, with the address the user selected.

requestPasskeyWalletDecryptPayload

Signature

requestPasskeyWalletDecryptPayload: (input: PasskeyWalletRemotePopupInput & {

address: `0x${string}`;

encryptedPayload: WalletEncryptedPayload;

timeoutMs?: number;

}) => Promise<PasskeyWalletDecryptPayloadResult>

Parameters

Name	Type	Description
input	PasskeyWalletRemotePopupInput & { address: `0x${string}`; encryptedPayload: WalletEncryptedPayload; timeoutMs?: number; }	The request, the address, the encrypted payload, and a timeout, 5 minutes by default.

Returns

Type	Description
Promise<PasskeyWalletDecryptPayloadResult>	The answer, with the decrypted text.

requestPasskeyWalletEncryptPayload

Signature

requestPasskeyWalletEncryptPayload: (input: PasskeyWalletRemotePopupInput & {

address: `0x${string}`;

plaintext: string;

timeoutMs?: number;

}) => Promise<PasskeyWalletEncryptPayloadResult>

Parameters

Name	Type	Description
input	PasskeyWalletRemotePopupInput & { address: `0x${string}`; plaintext: string; timeoutMs?: number; }	The request, the address, the text, and a timeout, 5 minutes by default.

Returns

Type	Description
Promise<PasskeyWalletEncryptPayloadResult>	The answer, with the encrypted payload.

requestPasskeyWalletSignMessage

The answer is checked with assertPasskeyWalletSignMessageResult().

Signature

requestPasskeyWalletSignMessage: (input: PasskeyWalletSignMessagePopupInput & {

timeoutMs?: number;

}) => Promise<PasskeyWalletSignMessageResult>

Parameters

Name	Type	Description
input	PasskeyWalletSignMessagePopupInput & { timeoutMs?: number; }	The request, the address, the message, and a timeout, 5 minutes by default.

Returns

Type	Description
Promise<PasskeyWalletSignMessageResult>	The answer, with the signature.

stringifyPasskeyWalletTypedData

Signature

stringifyPasskeyWalletTypedData: (typedData: PasskeyWalletTypedData) => string

Parameters

Name	Type	Description
typedData	PasskeyWalletTypedData	The typed data.

passkeyWalletConnectResultType

Definition

const passkeyWalletConnectResultType = "organigram:wallet:connect-result"

passkeyWalletConnectType

Definition

const passkeyWalletConnectType = "organigram:wallet:connect"

passkeyWalletDecryptPayloadResultType

Definition

const passkeyWalletDecryptPayloadResultType = "organigram:wallet:decrypt-payload-result"

passkeyWalletDecryptPayloadType

Definition

const passkeyWalletDecryptPayloadType = "organigram:wallet:decrypt-payload"

passkeyWalletEncryptPayloadResultType

Definition

const passkeyWalletEncryptPayloadResultType = "organigram:wallet:encrypt-payload-result"

passkeyWalletEncryptPayloadType

Definition

const passkeyWalletEncryptPayloadType = "organigram:wallet:encrypt-payload"

passkeyWalletRemoteErrorResultType

Definition

const passkeyWalletRemoteErrorResultType = "organigram:wallet:remote-error"

passkeyWalletRemoteRequestPayloadType

Definition

const passkeyWalletRemoteRequestPayloadType = "organigram:wallet:request-payload"

passkeyWalletSendTransactionResultType

Definition

const passkeyWalletSendTransactionResultType = "organigram:wallet:send-transaction-result"

passkeyWalletSendTransactionType

Definition

const passkeyWalletSendTransactionType = "organigram:wallet:send-transaction"

passkeyWalletSignMessageResultType

Definition

const passkeyWalletSignMessageResultType = "organigram:wallet:sign-message-result"

passkeyWalletSignMessageType

Definition

const passkeyWalletSignMessageType = "organigram:wallet:sign-message"

passkeyWalletSignTypedDataResultType

Definition

const passkeyWalletSignTypedDataResultType = "organigram:wallet:sign-typed-data-result"

passkeyWalletSignTypedDataType

Definition

const passkeyWalletSignTypedDataType = "organigram:wallet:sign-typed-data"

getAcceptedWalletOrigins

Signature

getAcceptedWalletOrigins: (walletOrigin: string) => string[]

getLocalWalletOrigin

Signature

getLocalWalletOrigin: (walletOrigin: string) => string | null

isLocalWalletOriginOf

Signature

isLocalWalletOriginOf: (localWalletOrigin: string, walletOrigin: string) => boolean

postToWalletPopup

Signature

postToWalletPopup: (popup: Window, message: unknown, walletOrigin: string) => void

rememberWalletOrigin

Signature

rememberWalletOrigin: (walletOrigin: string, answeringOrigin: string) => void

toPreferredWalletUrl

Signature

toPreferredWalletUrl: (url: URL) => URL

watchLocalWalletPopup

Signature

watchLocalWalletPopup: (input: {

popup: Window;

popupUrl: URL;

walletOrigin: string;

requestId: string;

timeoutMs?: number;

}) => (() => void)

localWalletOptOutParam

Definition

const localWalletOptOutParam = "localWallet"

officialLocalWalletOrigin

A wallet can have a local copy: the same wallet run on the user's own machine, served under a subdomain of the wallet host, so that it unlocks the same passkeys. An app that trusts the wallet then also trusts that copy. The official wallet's copy is pnpm dev local-organigram; another deployment declares its own through NEXT_PUBLIC_ORGANIGRAM_PASSKEY_WALLET_LOCAL_URL.

Definition

const officialLocalWalletOrigin = "https://local.wallet.organigram.ai:3002"

officialWalletOrigin

Definition

const officialWalletOrigin = "https://wallet.organigram.ai"

passkeyWalletLocalHandoffType

Definition

const passkeyWalletLocalHandoffType = "organigram:wallet:local-handoff"

passkeyWalletReadyType

Definition

const passkeyWalletReadyType = "organigram:wallet:ready"

Sign in

Users sign in to an app with Sign-In with Ethereum. The app issues a message with a nonce from its server, the wallet signs it in a popup, and the server verifies the signature, the domain and the nonce before opening a session. With NextAuth, signInWithPasskeyWallet() runs the whole flow in the browser, and authorizePasskeyWalletCredentials() verifies the result in a credentials provider.

PasskeyWalletPopupInput

Definition

export type PasskeyWalletPopupInput = {

walletOrigin?: string;

appOrigin?: string;

nonce: string;

chainId: number;

requestId?: string;

requestedAt?: string;

popup?: Window | null;

};

PasskeyWalletStackSessionChangedMessage

Definition

export type PasskeyWalletStackSessionChangedMessage = {

type: typeof passkeyWalletStackSessionChangedType;

version: 1;

event: 'revoked';

appOrigin: string;

address: `0x${string}` | null;

};

SignInWithPasskeyWalletInput

Definition

export type SignInWithPasskeyWalletInput = {

chainId?: number;

walletOrigin?: string;

getCsrfToken: () => Promise<string | null | undefined>;

requestWalletSignIn?: (input: WalletSignInInput) => Promise<PasskeyWalletSignInResult>;

submitCredentials?: SubmitCredentials;

};

buildPasskeyWalletSignInPopupUrl

Signature

buildPasskeyWalletSignInPopupUrl: (input: PasskeyWalletPopupInput) => URL

Parameters

Name	Type	Description
input	PasskeyWalletPopupInput	The sign-in request.

createPasskeyWalletStackSessionChangedMessage

Signature

createPasskeyWalletStackSessionChangedMessage: (input: {

event: "revoked";

appOrigin: string;

address?: `0x${string}` | null;

}) => PasskeyWalletStackSessionChangedMessage

Parameters

Name	Type	Description
input	{ event: "revoked"; appOrigin: string; address?: `0x${string}` | null; }	The event, the origin of the app and the address of the session.

notifyCurrentTabNextAuthSessionChanged

Signature

notifyCurrentTabNextAuthSessionChanged: () => void

notifyPasskeyWalletStackSessionChanged

Signature

notifyPasskeyWalletStackSessionChanged: (input: {

event: "revoked";

appOrigin: string;

address?: `0x${string}` | null;

targetOrigin?: string;

}) => void

Parameters

Name	Type	Description
input	{ event: "revoked"; appOrigin: string; address?: `0x${string}` | null; targetOrigin?: string; }	The event, the origin of the app, the address of the session, and the origin to post to, the app origin by default.

parsePasskeyWalletStackSessionChangedMessage

Also check the origin of the MessageEvent carrying it: only trust messages from the wallet.

Signature

parsePasskeyWalletStackSessionChangedMessage: (value: unknown) => PasskeyWalletStackSessionChangedMessage | null

Parameters

Name	Type	Description
value	unknown	The data of the message.

Returns

Type	Description
PasskeyWalletStackSessionChangedMessage | null	The message, or null if it is invalid.

requestPasskeyWalletSignIn

Only accepts answers from the wallet origin and its local copy, for this request. The result is not verified: the server must verify it with verifyPasskeyWalletSiwe().

Signature

requestPasskeyWalletSignIn: (input: PasskeyWalletPopupInput & {

timeoutMs?: number;

}) => Promise<PasskeyWalletSignInResult>

Parameters

Name	Type	Description
input	PasskeyWalletPopupInput & { timeoutMs?: number; }	The sign-in request, and a timeout, 5 minutes by default.

Returns

Type	Description
Promise<PasskeyWalletSignInResult>	The signed message.

signInWithPasskeyWallet

Opens the wallet popup, uses the CSRF token as the nonce of the Sign-In with Ethereum message, and submits the signed message to the NextAuth credentials provider, which verifies it with authorizePasskeyWalletCredentials().

Signature

signInWithPasskeyWallet: (input: SignInWithPasskeyWalletInput) => Promise<PasskeyWalletSignInResult>

Parameters

Name	Type	Description
input	SignInWithPasskeyWalletInput	The CSRF token getter, the chain and the wallet origin.

Returns

Type	Description
Promise<PasskeyWalletSignInResult>	The signed message.

passkeyWalletStackSessionChangedType

Definition

const passkeyWalletStackSessionChangedType = "organigram:wallet:stack-session-changed"

submitPasskeyWalletCredentials

Definition

const submitPasskeyWalletCredentials: SubmitCredentials

AuthorizePasskeyWalletCredentialsInput

Definition

export type AuthorizePasskeyWalletCredentialsInput = {

credentials: PasskeyWalletNextAuthCredentials | undefined;

domain: string;

nonce: string | null | undefined;

chain?: Chain;

transportUrl: string;

transportOptions?: Parameters<typeof import('viem').http>[1];

};

PasskeyWalletNextAuthCredentials

Definition

export type PasskeyWalletNextAuthCredentials = {

message?: unknown;

signature?: unknown;

csrfToken?: unknown;

};

authorizePasskeyWalletCredentials

Rejects credentials without message, signature or nonce, then verifies them with verifyPasskeyWalletSiwe(). The nonce is the CSRF token of the session, which signInWithPasskeyWallet() puts in the message.

Signature

authorizePasskeyWalletCredentials: (input: AuthorizePasskeyWalletCredentialsInput) => Promise<PasskeyWalletVerifiedSiwe | null>

Parameters

Name	Type	Description
input	AuthorizePasskeyWalletCredentialsInput	The credentials, the domain and nonce of the app, and an RPC endpoint.

Returns

Type	Description
Promise<PasskeyWalletVerifiedSiwe | null>	The verified sign-in, or null.

PasskeyWalletChallenge

Definition

export type PasskeyWalletChallenge = {

domain: string;

nonce: string;

issuedAt: string;

expiresAt: string;

message: string;

};

PasskeyWalletVerifiedSiwe

Definition

export type PasskeyWalletVerifiedSiwe = {

address: `0x${string}`;

chainId: number;

domain: string;

uri: string;

nonce: string;

encryptionPublicKeyResource: WalletEncryptionPublicKeySiweResource | null;

};

PasskeyWalletVerifySiweInput

Definition

export type PasskeyWalletVerifySiweInput = {

message: string;

signature: Hex;

domain: string;

nonce: string;

chain?: Chain;

transportUrl: string;

transportOptions?: Parameters<typeof http>[1];

};

buildPasskeyWalletPopupUrl

Signature

buildPasskeyWalletPopupUrl: (input: {

walletOrigin: string;

domain: string;

challengeUrl: string;

requestId?: string;

requestedAt?: string;

returnUrl?: string;

}) => URL

Parameters

Name	Type	Description
input	{ walletOrigin: string; domain: string; challengeUrl: string; requestId?: string; requestedAt?: string; returnUrl?: string; }	The origin of the wallet, the domain of the app, its challenge URL, and optionally the request identifier, date and return URL.

createPasskeyWalletChallenge

Store the nonce on the server, for example in the session, and check it with verifyPasskeyWalletSiwe().

Signature

createPasskeyWalletChallenge: (input: {

request: Request;

address: `0x${string}`;

chainId: number;

encryptionPublicKeyResource?: string;

nonce?: string;

now?: Date;

statement?: string;

uri?: string;

}) => PasskeyWalletChallenge

Parameters

Name	Type	Description
input	{ request: Request; address: `0x${string}`; chainId: number; encryptionPublicKeyResource?: string; nonce?: string; now?: Date; statement?: string; uri?: string; }	The request, the address and chain, and optionally the public key resource from createWalletEncryptionPublicKeySiweResource(), a nonce, the current date, a statement and the URI of the app, the origin of the request by default.

createPasskeyWalletManifest

Signature

createPasskeyWalletManifest: (request: Request) => PasskeyWalletManifest

Parameters

Name	Type	Description
request	Request	The request for the manifest.

getPasskeyWalletCorsAllowedOrigins

Allows the official wallet and its local copy, the configured wallet and its local copy, other configured origins, and, when the app runs on localhost, the wallet served on port 3002 of the same host.

Signature

getPasskeyWalletCorsAllowedOrigins: (input: {

request: Request;

walletUrl?: string;

allowedOrigins?: string;

}) => string[]

Parameters

Name	Type	Description
input	{ request: Request; walletUrl?: string; allowedOrigins?: string; }	The request, the URL of the configured wallet, and other allowed origins, separated by commas.

getPasskeyWalletCorsOrigin

Signature

getPasskeyWalletCorsOrigin: (input: {

request: Request;

walletUrl?: string;

allowedOrigins?: string;

}) => string | null

Parameters

Name	Type	Description
input	{ request: Request; walletUrl?: string; allowedOrigins?: string; }	The request, the URL of the configured wallet, and other allowed origins, separated by commas.

Returns

Type	Description
string | null	The origin, or null.

getPasskeyWalletRequestOrigin

Clients can set these headers. Only rely on the result behind a proxy that overwrites them.

Signature

getPasskeyWalletRequestOrigin: (request: Request) => string

Parameters

Name	Type	Description
request	Request	The request.

isWalletSignInOriginAllowed

Signature

isWalletSignInOriginAllowed: (origin: string, allowedOrigins: readonly string[]) => boolean

Parameters

Name	Type	Description
origin	string	The origin to check.
allowedOrigins	readonly string[]	The allowed origins.

verifyPasskeyWalletSiwe

Checks the signature, the domain, the nonce and the validity dates of the message with viem. Never pass an empty domain or nonce: viem then skips their check. Check that the nonce is the one the app issued for this session, and use it only once.

Signature

verifyPasskeyWalletSiwe: (input: PasskeyWalletVerifySiweInput) => Promise<PasskeyWalletVerifiedSiwe | null>

Parameters

Name	Type	Description
input	PasskeyWalletVerifySiweInput	The message, signature, expected domain and nonce, and an RPC endpoint.

Returns

Type	Description
Promise<PasskeyWalletVerifiedSiwe | null>	The verified sign-in, or null if the message is invalid.

withPasskeyWalletCorsHeaders

Signature

withPasskeyWalletCorsHeaders: <Response extends {

headers: Headers;

}>(request: Request, response: Response, options?: {

allowedMethods?: string;

walletUrl?: string;

allowedOrigins?: string;

}) => Response

Parameters

Name	Type	Description
request	Request	The request.
response	Response	The response, returned with its headers changed.
options	{ allowedMethods?: string; walletUrl?: string; allowedOrigins?: string; }	Allowed methods, GET, OPTIONS by default, the URL of the configured wallet, and other allowed origins.

PasskeyWalletErrorResult

Definition

export type PasskeyWalletErrorResult = {

type: typeof passkeyWalletErrorType;

version: 1;

requestId: string;

code: 'user_rejected' | 'challenge_unavailable' | 'domain_mismatch' | 'wallet_locked' | 'unsupported_origin' | 'internal_error';

message: string;

};

PasskeyWalletManifest

Definition

export type PasskeyWalletManifest = {

version: 1;

domain: string;

signInChallengeUrl: string;

signInCompletionUrl?: string;

};

PasskeyWalletSignInRequest

Definition

export type PasskeyWalletSignInRequest = {

type: typeof passkeyWalletSignInType;

version: 1;

requestId: string;

domain: string;

challengeUrl: string;

returnUrl?: string;

requestedAt: string;

};

PasskeyWalletSignInResult

Definition

export type PasskeyWalletSignInResult = {

type: typeof passkeyWalletSignInResultType;

version: 1;

requestId: string;

domain: string;

address: `0x${string}`;

message: string;

signature: `0x${string}`;

completedAt: string;

};

assertSignInDomainMatches

Signature

assertSignInDomainMatches: (message: string, expectedDomain: string) => void

Parameters

Name	Type	Description
message	string	The message.
expectedDomain	string	The domain of the request.

parsePasskeyWalletSignInRequest

The challenge URL must use HTTPS and belong to the requested domain or one of its subdomains, and the return URL must use HTTPS, so that the wallet only signs messages fetched from the app asking for them.

Signature

parsePasskeyWalletSignInRequest: (params: URLSearchParams) => PasskeyWalletSignInRequest

Parameters

Name	Type	Description
params	URLSearchParams	The URL parameters.

resolveSiweDomain

Signature

resolveSiweDomain: (message: string) => string

Parameters

Name	Type	Description
message	string	The message.

validatePasskeyWalletManifest

The domain of the manifest must be the host serving it, and its URLs must use HTTPS and belong to that domain or its subdomains.

Signature

validatePasskeyWalletManifest: (manifest: unknown, servingHost: string) => PasskeyWalletManifest

Parameters

Name	Type	Description
manifest	unknown	The manifest, parsed from JSON.
servingHost	string	The host the manifest was fetched from.

passkeyWalletErrorType

Definition

const passkeyWalletErrorType = "organigram:wallet:error"

passkeyWalletSignInResultType

Definition

const passkeyWalletSignInResultType = "organigram:wallet:sign-in-result"

passkeyWalletSignInType

Definition

const passkeyWalletSignInType = "organigram:wallet:sign-in"

Passkey vaults

The wallet is a standard Ethereum account derived from a BIP-39 recovery phrase. The recovery phrase is encrypted in a vault with AES-256-GCM, under a key derived from the PRF output of a WebAuthn passkey, so that only that passkey can decrypt it. A wallet can have several passkeys, each with its own vault. These functions run in the wallet app: an unlocked wallet holds the recovery phrase and keys in memory, so keep it there only as long as needed, and never store, send or log it.

BrowserPasskeyWalletVaultPayload

Holds the recovery phrase in clear: never store, send or log it outside an encrypted envelope.

Definition

export type BrowserPasskeyWalletVaultPayload = {

version: 1;

recoveryPhrase: string;

walletEncryptionKey?: WalletEncryptionKeyPairPayload;

};

PasskeyPrfCredential

Definition

export type PasskeyPrfCredential = {

credentialId: string;

transports?: string[];

prfSalt: string;

};

createBrowserPasskeyWalletVaultPayload

Signature

createBrowserPasskeyWalletVaultPayload: (recoveryPhrase: string) => Promise<BrowserPasskeyWalletVaultPayload>

Parameters

Name	Type	Description
recoveryPhrase	string	The recovery phrase of the wallet.

createGeneratedRecoveryPhrase

Signature

createGeneratedRecoveryPhrase: () => string

decryptVaultPayloadWithPrfOutput

Does not zero the PRF output, so that the caller may try several envelopes with it. Zero it once done.

Signature

decryptVaultPayloadWithPrfOutput: (input: {

envelope: PasskeyVaultEnvelopeData;

prfOutput: Uint8Array;

}) => Promise<BrowserPasskeyWalletVaultPayload>

Parameters

Name	Type	Description
input	{ envelope: PasskeyVaultEnvelopeData; prfOutput: Uint8Array; }	The envelope and the PRF output.

derivePasskeyWalletAccount

Signature

derivePasskeyWalletAccount: (input: {

wallet: UnlockedPasskeyWallet;

account: StoredVaultAccount;

}) => UnlockedPasskeyWallet

Parameters

Name	Type	Description
input	{ wallet: UnlockedPasskeyWallet; account: StoredVaultAccount; }	The unlocked wallet and the account to select.

deriveStoredVaultAccount

Signature

deriveStoredVaultAccount: (input: {

recoveryPhrase: string;

addressIndex: number;

name: string;

}) => StoredVaultAccount

Parameters

Name	Type	Description
input	{ recoveryPhrase: string; addressIndex: number; name: string; }	The recovery phrase, the address index, and the name of the account, Account <index + 1> by default.

getDerivationPath

Signature

getDerivationPath: (addressIndex: number) => string

Parameters

Name	Type	Description
addressIndex	number	The address index.

hexEncodeMessage

Signature

hexEncodeMessage: (message: string) => `0x${string}`

Parameters

Name	Type	Description
message	string	The message.

parseBrowserPasskeyWalletVaultPayload

Signature

parseBrowserPasskeyWalletVaultPayload: (plaintext: string) => BrowserPasskeyWalletVaultPayload

Parameters

Name	Type	Description
plaintext	string	The decrypted payload, in JSON.

registerAdditionalBrowserPasskeyVault

Signature

registerAdditionalBrowserPasskeyVault: (input: {

wallet: UnlockedPasskeyWallet;

name: string;

accounts: StoredVaultAccount[];

rpId?: string;

rpName?: string;

}) => Promise<{

record: StoredVaultRecord;

wallet: UnlockedPasskeyWallet;

}>

Parameters

Name	Type	Description
input	{ wallet: UnlockedPasskeyWallet; name: string; accounts: StoredVaultAccount[]; rpId?: string; rpName?: string; }	The unlocked wallet, the name of the passkey, the accounts it unlocks, and the WebAuthn relying party.

Returns

Type	Description
Promise<{ record: StoredVaultRecord; wallet: UnlockedPasskeyWallet; }>	The new vault record and the wallet, now attached to the new passkey.

registerBrowserPasskeyVault

Asks the browser to create a discoverable passkey with user verification and the PRF extension. The recovery phrase is encrypted with a key derived from the PRF output, which is then zeroed. Store the returned record, which holds no secret in clear, and keep the unlocked wallet in memory only.

Signature

registerBrowserPasskeyVault: (input: {

recoveryPhrase: string;

name: string;

rpId?: string;

rpName?: string;

}) => Promise<{

record: StoredVaultRecord;

wallet: UnlockedPasskeyWallet;

}>

Parameters

Name	Type	Description
input	{ recoveryPhrase: string; name: string; rpId?: string; rpName?: string; }	The recovery phrase, the name of the wallet, the WebAuthn relying party identifier, the current host name by default, and the relying party name.

Returns

Type	Description
Promise<{ record: StoredVaultRecord; wallet: UnlockedPasskeyWallet; }>	The vault record and the unlocked wallet, on its first account.

requestPasskeyPrfOutput

Signature

requestPasskeyPrfOutput: (input: {

credentials: PasskeyPrfCredential[];

rpId?: string;

}) => Promise<{

credentialId: string;

prfOutput: Uint8Array;

}>

signPersonalMessage

Signature

signPersonalMessage: (input: {

wallet: UnlockedPasskeyWallet;

message: string;

}) => Promise<`0x${string}`>

Parameters

Name	Type	Description
input	{ wallet: UnlockedPasskeyWallet; message: string; }	The unlocked wallet and the message.

signTypedDataMessage

Signature

signTypedDataMessage: (input: {

wallet: UnlockedPasskeyWallet;

typedData: PasskeyWalletTypedData;

}) => Promise<`0x${string}`>

Parameters

Name	Type	Description
input	{ wallet: UnlockedPasskeyWallet; typedData: PasskeyWalletTypedData; }	The unlocked wallet and the typed data.

unlockBrowserPasskeyVault

Asks the user to pick one of the passkeys of the records, with user verification. The vaults of that passkey are tried in turn, and the first whose recovery phrase derives the address of its record is unlocked. The PRF output is zeroed.

Signature

unlockBrowserPasskeyVault: (input: {

records: StoredVaultRecord[];

rpId?: string;

}) => Promise<{

record: StoredVaultRecord;

wallet: UnlockedPasskeyWallet;

}>

Parameters

Name	Type	Description
input	{ records: StoredVaultRecord[]; rpId?: string; }	The vault records to choose from, and the WebAuthn relying party identifier, the current host name by default.

Returns

Type	Description
Promise<{ record: StoredVaultRecord; wallet: UnlockedPasskeyWallet; }>	The record unlocked and the wallet, on the first account of the record.

updateStaticPasskeyVaultEncryptionKey

Asks the user for a passkey, and keeps the PRF salt of the vault. Store the returned record in place of the old one.

Signature

updateStaticPasskeyVaultEncryptionKey: (input: {

records: StoredVaultRecord[];

walletEncryptionKey: WalletEncryptionKeyPairPayload;

rpId?: string;

}) => Promise<{

record: StoredVaultRecord;

wallet: UnlockedPasskeyWallet;

}>

Parameters

Name	Type	Description
input	{ records: StoredVaultRecord[]; walletEncryptionKey: WalletEncryptionKeyPairPayload; rpId?: string; }	The vault records to choose from, the new key pair and the WebAuthn relying party identifier.

Returns

Type	Description
Promise<{ record: StoredVaultRecord; wallet: UnlockedPasskeyWallet; }>	The re-encrypted record and the unlocked wallet.

PasskeyVaultEnvelopeData

The envelope holds no secret: it can be stored anywhere, as only the passkey that created it can decrypt it.

Definition

export type PasskeyVaultEnvelopeData = {

algorithm: typeof passkeyVaultAlgorithm;

keyVersion: typeof passkeyVaultKeyVersion;

ciphertext: string;

salt: string;

prfSalt: string;

nonce: string;

};

base64UrlToBytes

Accepts canonical unpadded base64url only. Lenient decoders silently skip unknown characters, so a tampered value could otherwise decode to bytes other than the ones it appears to encode.

Signature

base64UrlToBytes: (value: string) => Uint8Array

Parameters

Name	Type	Description
value	string	The value to decode.

bytesToBase64Url

Signature

bytesToBase64Url: (bytes: Uint8Array) => string

Parameters

Name	Type	Description
bytes	Uint8Array	The bytes to encode.

decryptPasskeyVaultSecret

Signature

decryptPasskeyVaultSecret: (input: DecryptPasskeyVaultSecretInput) => Promise<string>

Parameters

Name	Type	Description
input	~DecryptPasskeyVaultSecretInput	The envelope and the key derived for it.

derivePasskeyVaultKey

The key cannot be exported. A copy of the PRF output made for the import is zeroed afterwards, but not the original: zero it once you no longer need it.

Signature

derivePasskeyVaultKey: (input: DerivePasskeyVaultKeyInput) => Promise<CryptoKey>

Parameters

Name	Type	Description
input	~DerivePasskeyVaultKeyInput	The 32-byte PRF output, the 32-byte salt of the vault, and an optional HKDF info that separates keys derived from the same PRF output for different purposes.

encryptPasskeyVaultSecret

Signature

encryptPasskeyVaultSecret: (input: EncryptPasskeyVaultSecretInput) => Promise<PasskeyVaultEnvelopeData>

Parameters

Name	Type	Description
input	~EncryptPasskeyVaultSecretInput	The secret, the key from derivePasskeyVaultKey(), the salt it was derived with, the 32-byte PRF salt, and an optional 12-byte nonce, random by default. Never reuse a nonce with the same key.

getCrypto

Signature

getCrypto: () => Crypto

hasBase64UrlByteLength

Signature

hasBase64UrlByteLength: (value: unknown, isValidLength: (byteLength: number) => boolean) => boolean

Parameters

Name	Type	Description
value	unknown	The value to check.
isValidLength	(byteLength: number) => boolean	Test of the decoded length, in bytes.

isPasskeyPrfSupported

Signature

isPasskeyPrfSupported: (input: {

credential: PrfSupportCredential | null;

}) => Promise<boolean>

Parameters

Name	Type	Description
input	{ credential: ~PrfSupportCredential | null; }	The credential returned by navigator.credentials.create().

isPasskeyVaultEnvelope

Signature

isPasskeyVaultEnvelope: (value: unknown) => value is PasskeyVaultEnvelopeData

Parameters

Name	Type	Description
value	unknown	The value to check.

randomBytes

Signature

randomBytes: (length: number) => Uint8Array

Parameters

Name	Type	Description
length	number	Number of bytes.

toArrayBuffer

Signature

toArrayBuffer: (bytes: Uint8Array) => ArrayBuffer

Parameters

Name	Type	Description
bytes	Uint8Array	The bytes to copy.

passkeyVaultAlgorithm

Definition

const passkeyVaultAlgorithm = "AES-GCM-HKDF-SHA-256"

passkeyVaultKeyVersion

Definition

const passkeyVaultKeyVersion = 2

textDecoder

Definition

const textDecoder: TextDecoder

textEncoder

Definition

const textEncoder: TextEncoder

PasskeyProviderEvent

Definition

export type PasskeyProviderEvent = 'accountsChanged' | 'chainChanged' | 'disconnect';

PasskeyProviderListener

Definition

export type PasskeyProviderListener = (...args: unknown[]) => void;

PasskeyRegistrationResult

Definition

export type PasskeyRegistrationResult = {

address: `0x${string}`;

credentialId: string;

};

UnlockedPasskeyWallet

It holds the recovery phrase and the private keys in memory. Keep it in memory only for as long as needed, never store, send or log it.

Definition

export type UnlockedPasskeyWallet = {

address: `0x${string}`;

account: HDAccount;

recoveryPhrase: string;

walletEncryptionKey?: WalletEncryptionKeyPairPayload;

credentialId: string;

};

organigramPasskeyWalletIcon

Definition

const organigramPasskeyWalletIcon = "/png/logo-gradient.png"

organigramPasskeyWalletId

Definition

const organigramPasskeyWalletId = "organigram-passkeys"

Vault records

A vault record holds a vault envelope with the public details needed to unlock it: the accounts, the passkey and its device. Records hold no secret in clear, so that they can be stored in the browser or exported. These functions read, list and update records.

StoredVaultAccount

Definition

export type StoredVaultAccount = {

address: `0x${string}`;

name: string;

addressIndex: number;

derivationPath: string;

};

StoredVaultRecord

A wallet has one record per passkey that can unlock it. The record holds no secret in clear: only its passkey can decrypt the envelope.

Definition

export type StoredVaultRecord = {

version: 1;

address: `0x${string}`;

accounts: StoredVaultAccount[];

credentialId: string;

rawCredentialId?: string;

name: string;

transports: string[];

passkeyDevice: {

kind: 'macos' | 'ios' | 'ipados' | 'windows' | 'android' | 'linux' | 'security-key' | 'cross-device' | 'platform' | 'passkey';

label: string;

};

createdAt: string;

lastUsedAt: string | null;

envelope: PasskeyVaultEnvelopeData;

};

VaultRegistry

Definition

export type VaultRegistry = {

version: 1;

vaults: StoredVaultRecord[];

};

addAccountToVaultRecords

Signature

addAccountToVaultRecords: (input: {

vaults: StoredVaultRecord[];

sourceAddress: `0x${string}`;

account: StoredVaultAccount;

}) => StoredVaultRecord[]

Parameters

Name	Type	Description
input	{ vaults: StoredVaultRecord[]; sourceAddress: `0x${string}`; account: StoredVaultAccount; }	The vault records, an account the wallet already holds, and the account to add.

createVaultRegistry

Signature

createVaultRegistry: (vaults: StoredVaultRecord[]) => VaultRegistry

Parameters

Name	Type	Description
vaults	StoredVaultRecord[]	The vault records.

isStoredVaultRecord

Signature

isStoredVaultRecord: (value: unknown) => value is StoredVaultRecord

Parameters

Name	Type	Description
value	unknown	The value to check.

markVaultRecordUsed

Signature

markVaultRecordUsed: (input: {

vaults: StoredVaultRecord[];

credentialId: string;

usedAt?: string;

}) => StoredVaultRecord[]

Parameters

Name	Type	Description
input	{ vaults: StoredVaultRecord[]; credentialId: string; usedAt?: string; }	The vault records, the identifier of the passkey, and the date, now by default.

parseVaultRegistry

Signature

parseVaultRegistry: (value: unknown) => VaultRegistry

Parameters

Name	Type	Description
value	unknown	The registry, parsed from JSON.

removeAccountFromVaultRecords

This only removes local records. Without a remaining vault or exported recovery phrase, the account can no longer be unlocked.

Signature

removeAccountFromVaultRecords: (input: {

vaults: StoredVaultRecord[];

address: `0x${string}`;

}) => StoredVaultRecord[]

Parameters

Name	Type	Description
input	{ vaults: StoredVaultRecord[]; address: `0x${string}`; }	The vault records and the address of the account.

removeVaultRecord

Signature

removeVaultRecord: (input: {

vaults: StoredVaultRecord[];

credentialId: string;

}) => StoredVaultRecord[]

Parameters

Name	Type	Description
input	{ vaults: StoredVaultRecord[]; credentialId: string; }	The vault records and the identifier of the passkey.

removeVaultRecords

Signature

removeVaultRecords: (input: {

vaults: StoredVaultRecord[];

credentialIds: Set<string>;

}) => StoredVaultRecord[]

Parameters

Name	Type	Description
input	{ vaults: StoredVaultRecord[]; credentialIds: Set<string>; }	The vault records and the identifiers of the passkeys.

serializeVaultRegistry

Signature

serializeVaultRegistry: (vaults: StoredVaultRecord[], space?: number) => string

Parameters

Name	Type	Description
vaults	StoredVaultRecord[]	The vault records.
space	number	Indentation of the JSON.

upsertVaultRecord

Signature

upsertVaultRecord: (input: {

vaults: StoredVaultRecord[];

record: StoredVaultRecord;

}) => StoredVaultRecord[]

Parameters

Name	Type	Description
input	{ vaults: StoredVaultRecord[]; record: StoredVaultRecord; }	The vault records and the record to add.

vaultHasAccount

Signature

vaultHasAccount: (vault: StoredVaultRecord, address: string) => boolean

Parameters

Name	Type	Description
vault	StoredVaultRecord	The vault record.
address	string	The address of the account.

VaultRegistryGroup

Definition

export type VaultRegistryGroup = {

id: string;

accounts: StoredVaultAccount[];

passkeys: StoredVaultRecord[];

createdAt: string;

};

WalletGroup

Definition

export type WalletGroup = {

address: `0x${string}`;

name: string;

addressIndex: number;

derivationPath: string;

passkeys: StoredVaultRecord[];

};

formatAddress

Signature

formatAddress: (address: string) => string

Parameters

Name	Type	Description
address	string	The address.

formatCredentialId

Signature

formatCredentialId: (credentialId: string) => string

Parameters

Name	Type	Description
credentialId	string	The passkey identifier.

getNextAddressIndex

Signature

getNextAddressIndex: (records: StoredVaultRecord[]) => number

Parameters

Name	Type	Description
records	StoredVaultRecord[]	The vault records.

getVaultAccount

Signature

getVaultAccount: (vault: StoredVaultRecord, address: string) => StoredVaultAccount | null

Parameters

Name	Type	Description
vault	StoredVaultRecord	The vault record.
address	string	The address of the account.

Returns

Type	Description
StoredVaultAccount | null	The account, or null.

getVaultRegistryGroupId

Signature

getVaultRegistryGroupId: (vault: StoredVaultRecord) => string

Parameters

Name	Type	Description
vault	StoredVaultRecord	The vault record.

groupVaultRecordsBySeed

Signature

groupVaultRecordsBySeed: (vaults: StoredVaultRecord[]) => VaultRegistryGroup[]

Parameters

Name	Type	Description
vaults	StoredVaultRecord[]	The vault records.

groupVaultsByWallet

Signature

groupVaultsByWallet: (vaults: StoredVaultRecord[]) => WalletGroup[]

Parameters

Name	Type	Description
vaults	StoredVaultRecord[]	The vault records.

mergeVaults

An imported record replaces the local record of the same passkey.

Signature

mergeVaults: (localVaults: StoredVaultRecord[], importedVaults: StoredVaultRecord[]) => StoredVaultRecord[]

Parameters

Name	Type	Description
localVaults	StoredVaultRecord[]	The local records.
importedVaults	StoredVaultRecord[]	The imported records.

Backups

Vault records can be backed up on a server. Each backup exposes only its vault envelope and passkey identifier: the rest of the record is encrypted with a key derived from the recovery phrase, so that the server learns nothing beyond the wallet address, and any passkey of the wallet can restore every backup.

RemoteVaultBackupPackage

Definition

export type RemoteVaultBackupPackage = {

version: 1;

address: `0x${string}`;

backups: RemoteVaultBackupRecord[];

exportedAt: string;

};

RemoteVaultBackupRecord

A backup exposes its vault envelope, which only its own passkey can decrypt, with the identifier of that passkey. The rest of the vault record (account addresses, names, devices) is encrypted with a key derived from the recovery phrase, so that any passkey of the wallet can restore every backup while the server learns nothing beyond the wallet address.

Definition

export type RemoteVaultBackupRecord = {

version: 2;

backupId: string;

credentialId: string;

envelope: PasskeyVaultEnvelopeData;

salt: string;

iv: string;

ciphertext: string;

createdAt: string;

};

createRemoteVaultBackupPackage

Signature

createRemoteVaultBackupPackage: (input: {

address: `0x${string}`;

backups: RemoteVaultBackupRecord[];

}) => RemoteVaultBackupPackage

Parameters

Name	Type	Description
input	{ address: `0x${string}`; backups: RemoteVaultBackupRecord[]; }	The address of the wallet and its backups.

createRemoteVaultBackupRecord

The backup key is derived with HKDF from a SHA-256 hash of the recovery phrase, a random salt, and the address. The recovery phrase itself is never part of the backup.

Signature

createRemoteVaultBackupRecord: (input: {

address: `0x${string}`;

record: StoredVaultRecord;

recoveryPhrase: string;

}) => Promise<RemoteVaultBackupRecord>

Parameters

Name	Type	Description
input	{ address: `0x${string}`; record: StoredVaultRecord; recoveryPhrase: string; }	The address of the wallet, the vault record and the recovery phrase of the wallet.

createVaultBackupDigest

Signature

createVaultBackupDigest: (backups: RemoteVaultBackupRecord[]) => Promise<string>

Parameters

Name	Type	Description
backups	RemoteVaultBackupRecord[]	The backups.

Returns

Type	Description
Promise<string>	The digest, in hex.

createVaultBackupSignatureMessage

Signature

createVaultBackupSignatureMessage: (input: {

address: `0x${string}`;

vaultCount: number;

digest: string;

}) => string

Parameters

Name	Type	Description
input	{ address: `0x${string}`; vaultCount: number; digest: string; }	The address of the wallet, the number of backups and their digest from createVaultBackupDigest().

decryptRemoteVaultBackupRecord

The result is not validated: check it with isStoredVaultRecord() before use.

Signature

decryptRemoteVaultBackupRecord: (input: {

address: `0x${string}`;

backup: RemoteVaultBackupRecord;

recoveryPhrase: string;

}) => Promise<StoredVaultRecord>

Parameters

Name	Type	Description
input	{ address: `0x${string}`; backup: RemoteVaultBackupRecord; recoveryPhrase: string; }	The address of the wallet, the backup and the recovery phrase of the wallet.

normalizeBackupAddress

Signature

normalizeBackupAddress: (value: string) => `0x${string}`

Parameters

Name	Type	Description
value	string	The address.

parseRemoteVaultBackupPackage

Signature

parseRemoteVaultBackupPackage: (value: unknown) => RemoteVaultBackupPackage

Parameters

Name	Type	Description
value	unknown	The package, parsed from JSON.

End-to-end encryption

Each wallet has an ECDH P-256 key pair, stored in its vaults, to encrypt files and texts that only it can decrypt. Its public key can be shared with an app in a Sign-In with Ethereum resource. Texts encrypted for an app are bound to the origin of that app, so that another app cannot have them decrypted.

WalletDecryptedFile

Definition

export type WalletDecryptedFile = {

name: string;

type: string;

bytes: Uint8Array;

lastModified?: number;

};

WalletEncryptedFilePackage

Definition

export type WalletEncryptedFilePackage = {

version: 1;

kind: 'organigram:wallet-encrypted-file';

algorithm: 'ECDH-P256+A256GCM';

recipient: {

address: `0x${string}`;

publicKey: JsonWebKey;

keyVersion: number;

};

file: {

name: string;

type: string;

size: number;

lastModified?: number;

};

iv: string;

ciphertext: string;

encryptedAt: string;

};

WalletEncryptedPayload

Definition

export type WalletEncryptedPayload = {

version: 1;

kind: 'organigram:wallet-encrypted-payload';

algorithm: 'ECDH-P256+A256GCM';

appOrigin: string;

recipient: {

address: `0x${string}`;

publicKey: JsonWebKey;

keyVersion: number;

};

iv: string;

ciphertext: string;

encryptedAt: string;

};

WalletEncryptionKeyPairPayload

Holds the private key in clear: keep it in the encrypted vault and in memory only, never store, send or log it elsewhere.

Definition

export type WalletEncryptionKeyPairPayload = {

version: 1;

algorithm: 'ECDH-P256';

privateKey: JsonWebKey;

publicKey: JsonWebKey;

keyVersion: number;

};

WalletEncryptionPublicKeySiweResource

Definition

export type WalletEncryptionPublicKeySiweResource = {

kind: typeof encryptionPublicKeyResourceKind;

address: string;

publicKey: JsonWebKey;

keyVersion: number;

};

createWalletEncryptionKeyPair

The private key is exportable, so that it can be stored in the passkey vaults of the wallet. Keep it there.

Signature

createWalletEncryptionKeyPair: () => Promise<WalletEncryptionKeyPairPayload>

createWalletEncryptionPublicKeySiweResource

Signing in with this resource lets the application learn the public key of the wallet, bound to its address by the signature.

Signature

createWalletEncryptionPublicKeySiweResource: (input: {

address: `0x${string}`;

keyPair: WalletEncryptionKeyPairPayload;

}) => string

Parameters

Name	Type	Description
input	{ address: `0x${string}`; keyPair: WalletEncryptionKeyPairPayload; }	The address of the wallet and its key pair. Only the public key is encoded.

decryptFileWithWalletEncryptionKey

Signature

decryptFileWithWalletEncryptionKey: (input: {

encryptedPackage: WalletEncryptedFilePackage;

keyPair: WalletEncryptionKeyPairPayload;

}) => Promise<WalletDecryptedFile>

Parameters

Name	Type	Description
input	{ encryptedPackage: WalletEncryptedFilePackage; keyPair: WalletEncryptionKeyPairPayload; }	The encrypted package and the key pair of the wallet.

decryptPayloadWithWalletEncryptionKey

Signature

decryptPayloadWithWalletEncryptionKey: (input: {

encryptedPayload: WalletEncryptedPayload;

appOrigin: string;

keyPair: WalletEncryptionKeyPairPayload;

}) => Promise<string>

Parameters

Name	Type	Description
input	{ encryptedPayload: WalletEncryptedPayload; appOrigin: string; keyPair: WalletEncryptionKeyPairPayload; }	The encrypted payload, the origin of the application asking for it, and the key pair of the wallet.

encryptFileWithWalletEncryptionKey

The AES-GCM key is derived by ECDH between the private and public keys of the same key pair. The name, type, size and date of the file stay in clear and are not authenticated with the ciphertext.

Signature

encryptFileWithWalletEncryptionKey: (input: {

address: `0x${string}`;

file: File;

keyPair: WalletEncryptionKeyPairPayload;

}) => Promise<WalletEncryptedFilePackage>

Parameters

Name	Type	Description
input	{ address: `0x${string}`; file: File; keyPair: WalletEncryptionKeyPairPayload; }	The address of the wallet, the file and the key pair.

encryptPayloadWithWalletEncryptionKey

The application origin, the address and the key version are authenticated with the ciphertext, so that the payload cannot be decrypted for another application or relabelled for it.

Signature

encryptPayloadWithWalletEncryptionKey: (input: {

address: `0x${string}`;

appOrigin: string;

plaintext: string;

keyPair: WalletEncryptionKeyPairPayload;

}) => Promise<WalletEncryptedPayload>

Parameters

Name	Type	Description
input	{ address: `0x${string}`; appOrigin: string; plaintext: string; keyPair: WalletEncryptionKeyPairPayload; }	The address of the wallet, the origin of the application, the text and the key pair.

parseWalletEncryptedFilePackage

Signature

parseWalletEncryptedFilePackage: (value: unknown) => WalletEncryptedFilePackage

Parameters

Name	Type	Description
value	unknown	The package, parsed from JSON.

parseWalletEncryptedPayload

Signature

parseWalletEncryptedPayload: (value: unknown) => WalletEncryptedPayload

Parameters

Name	Type	Description
value	unknown	The payload, parsed from JSON.

parseWalletEncryptionKeyPair

Signature

parseWalletEncryptionKeyPair: (value: unknown) => WalletEncryptionKeyPairPayload

Parameters

Name	Type	Description
value	unknown	The key pair, parsed from JSON.

parseWalletEncryptionPublicKeySiweResource

Only trust the result once the signature of the message is verified.

Signature

parseWalletEncryptionPublicKeySiweResource: (input: {

address: string;

resources: string[] | undefined;

}) => WalletEncryptionPublicKeySiweResource | null

Parameters

Name	Type	Description
input	{ address: string; resources: string[] | undefined; }	The address that signed the message, and the resources of the message.

Returns

Type	Description
WalletEncryptionPublicKeySiweResource | null	The public key, or null if no valid resource of this address is found.