@txnlab/use-wallet-passkey 0.0.0-stage → 5.2.0-next.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TxnLab, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @txnlab/use-wallet-passkey
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@txnlab/use-wallet-passkey)](https://www.npmjs.com/package/@txnlab/use-wallet-passkey)
+[![License](https://img.shields.io/github/license/TxnLab/use-wallet)](https://github.com/TxnLab/use-wallet/blob/main/LICENSE)
+
+Passkey adapter for [use-wallet](https://github.com/TxnLab/use-wallet), the Algorand wallet integration library.
+
+It derives a **Falcon-1024 (post-quantum) account** from a passkey's WebAuthn PRF output. Users need no extension, app or seed phrase: their passkey provider (iCloud Keychain, Google Password Manager, 1Password, Windows Hello or a FIDO2 security key) stores and syncs the credential.
+
+## Installation
+
+```bash
+npm install @txnlab/use-wallet @txnlab/use-wallet-passkey
+```
+
+If you use a framework adapter (`@txnlab/use-wallet-react`, `-vue`, `-solid`, or `-svelte`), install it in place of `@txnlab/use-wallet`.
+
+## Usage
+
+```typescript
+import { WalletManager } from '@txnlab/use-wallet'
+import { passkey } from '@txnlab/use-wallet-passkey'
+
+const manager = new WalletManager({
+  wallets: [passkey({ session: true })]
+})
+```
+
+Show two buttons. A missing passkey and a cancelled prompt raise the same browser error, so the adapter can't choose for the user:
+
+```typescript
+await wallet.connect() // Sign in with an existing passkey
+await wallet.connect({ create: true }) // Create a passkey (and a new account)
+```
+
+Call `connect`, `signTransactions` and `signData` directly from the click handler, before awaiting anything else. Safari and every iOS browser drop the user's tap across an `await`, and the passkey prompt needs it.
+
+### Options
+
+| Option     | Default             |                                                                                                                                              |
+| ---------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rpId`     | `location.hostname` | The domain the passkey, and so the account, is bound to. Set a parent domain (`example.com`) to share one account across its subdomains.     |
+| `rpName`   | the RP ID           | The name shown in passkey prompts                                                                                                            |
+| `context`  | `''`                | Separates this app's account from others on the same domain. No `:`; changing it changes the account.                                        |
+| `userName` | `<rpName> account`  | The name new passkeys are saved under                                                                                                        |
+| `session`  | `false`             | Keep the key unlocked between signatures (see below). `true` or `{ idleTimeoutMs }`; the default timeout is 15 minutes, and `0` disables it. |
+| `confirm`  | `() => 'presence'`  | How to confirm each signature while a session is unlocked                                                                                    |
+| `keyStore` | built-in worker     | Replace where the key is held (`PasskeyKeyStore`)                                                                                            |
+
+The factory also accepts an optional `metadata` option to override the wallet's display name and icon.
+
+### Sessions and confirmation
+
+Every passkey prompt that derives the key requires full user verification (biometric, PIN or system password), because the PRF output depends on it. Without `session`, every signing request runs one.
+
+With `session`, only the first request after connecting or reloading does. The key then stays in a dedicated worker until the idle timeout, `disconnect` or a page reload, and `confirm` decides how each later request is approved:
+
+- `'silent'`: no prompt
+- `'presence'`: a passkey prompt with `userVerification: 'preferred'`, which some providers satisfy with a tap
+- `'verify'`: a passkey prompt with full user verification
+
+```typescript
+passkey({
+  session: { idleTimeoutMs: 10 * 60 * 1000 },
+  confirm: (request) =>
+    request.type === 'transactions' && request.transactions.some((txn) => txn.type === 'pay')
+      ? 'verify'
+      : 'presence'
+})
+```
+
+`confirm` must be synchronous: awaiting before the prompt would lose the user's tap on iOS.
+
+### Recovery phrase
+
+The account is bound to your domain, so it's stranded if the domain is lost. Let users export its recovery phrase:
+
+```typescript
+import type { PasskeyAdapter } from '@txnlab/use-wallet-passkey'
+
+const wallet = manager.getWallet('passkey') as PasskeyAdapter
+const { phrase } = await wallet.exportRecoveryPhrase() // fresh passkey prompt, full verification
+```
+
+With a framework adapter, get the manager from `useWalletManager()`.
+
+Tell users to **import the phrase as a Falcon / quantum account**: in Lute, Add account → "Falcon25 account" → Import; in Pera, the quantum import; or `algokey pq import --scheme falcon-1024`. The same 25 words in a regular import restore a different, empty account.
+
+### Content Security Policy
+
+The key runs in a module worker started from a `blob:` URL, using WebAssembly. If your page sets a CSP, allow both:
+
+```
+script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob:
+```
+
+Without them, signing fails with a `PasskeyError` whose `code` is `key-store-failed`.
+
+### Errors
+
+Failures throw a `PasskeyError` with a `code`: `cancelled`, `unsupported` (no WebAuthn, or an in-app browser), `prf-unsupported` (the provider lacks the PRF extension; Ledger Stax and Dashlane on Android are known cases), `invalid-rp-id`, `key-mismatch`, `not-connected`, `key-store-failed` or `failed`. `signData` validation failures throw a `SignDataError` with an ARC-60 code.
+
+## Falcon accounts
+
+- Each signed transaction carries a ~3.2 KB `pqsig` and pays an extra 2× the minimum fee. Get fees by simulating with `emptyTransactionSigner` and `allowEmptySignatures`.
+- No multisig participation and no raw-bytes or program-data signing.
+- `signData` supports ARC-60 authentication with scheme `falcon-1024-det`.
+
+## Security
+
+- **The domain holds the keys.** Whoever controls the RP ID domain (including an XSS on it) can run a passkey prompt and recover the key with one tap.
+- **Post-quantum is bounded by the passkey's custody.** The PRF itself is symmetric, but synced passkeys are protected by each provider's classical encryption, and the CTAP2 channel uses P-256. Hardware security keys that don't sync close more of that gap.
+- Only public data is stored (credential ID, public key, address). The private key lives in a worker, never on the page's main thread, and is dropped on lock.
+
+### Visit [txnlab.gitbook.io/use-wallet](https://txnlab.gitbook.io/use-wallet) for docs, guides, and examples!

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+import algosdk from "algosdk";
+import { AdapterConstructorParams, BaseWallet, Siwa, StdSignDataResponse, StdSignMetadata, WalletAccount, WalletMetadata } from "@txnlab/use-wallet/adapter";
+import { WalletAdapterConfig, WalletFactoryOptions } from "@txnlab/use-wallet";
+//#region src/key-store.d.ts
+/**
+ * Holds the Falcon-1024 private key between a passkey's PRF ceremony and the
+ * signatures it authorizes. The adapter's built-in key store runs the key in a
+ * dedicated worker; supply your own (the `keyStore` option) to hold it
+ * elsewhere, e.g. a SharedWorker that outlives a page reload.
+ */
+interface PasskeyKeyStore {
+  /** True when `sign` can run without a new PRF ceremony */
+  readonly unlocked: boolean;
+  /**
+   * Derive the key from the passkey's 32-byte PRF output and return its
+   * Falcon-1024 public key. Implementations must zero `entropy` and derive the
+   * keygen seed with `keygenSeedFromEntropy`.
+   */
+  unlock(entropy: Uint8Array): Promise<Uint8Array>;
+  /** Sign exactly these bytes with the private key */
+  sign(bytes: Uint8Array): Promise<Uint8Array>;
+  /** Drop the private key */
+  lock(): void;
+}
+interface WorkerKeyStoreOptions {
+  /** Clear the key after this long without a signature. 0 keeps it until `lock`. */
+  idleTimeoutMs?: number;
+  /** Called when the idle timeout clears the key */
+  onIdleLock?: () => void;
+  /** How long to wait for the worker to load. Default: 10000 */
+  startTimeoutMs?: number;
+}
+/**
+ * The built-in key store: a dedicated module worker started from a Blob URL.
+ * The worker module is inlined into this package, so a consumer's bundler has
+ * no worker entry to resolve; the page's CSP must allow `worker-src blob:` and
+ * `'wasm-unsafe-eval'`. `lock` terminates the worker, which drops its WASM
+ * heap.
+ */
+export declare class WorkerKeyStore implements PasskeyKeyStore {
+  private readonly options;
+  private worker;
+  private isUnlocked;
+  private nextId;
+  private pending;
+  constructor(options?: WorkerKeyStoreOptions);
+  get unlocked(): boolean;
+  unlock(entropy: Uint8Array): Promise<Uint8Array>;
+  sign(bytes: Uint8Array): Promise<Uint8Array>;
+  lock(): void;
+  private start;
+  private startError;
+  private call;
+  private handle;
+}
+//#endregion
+//#region src/adapter.d.ts
+/**
+ * How to confirm a signing request while a session is unlocked:
+ * - `silent`: sign without a prompt
+ * - `presence`: a passkey prompt with `userVerification: 'preferred'`, which
+ *   some providers satisfy with a tap and no biometric or system password
+ * - `verify`: a passkey prompt with `userVerification: 'required'`
+ *
+ * These prompts evaluate no PRF, so they never change the account. When the
+ * session is locked, the PRF ceremony that unlocks it is the confirmation.
+ */
+type PasskeyConfirmation = 'silent' | 'presence' | 'verify';
+type PasskeySigningRequest = {
+  type: 'transactions';
+  transactions: algosdk.Transaction[];
+} | {
+  type: 'data';
+  siwa: Siwa;
+};
+interface PasskeySessionOptions {
+  /** Lock the session after this long without a signature; 0 never locks it. Default: 15 minutes */
+  idleTimeoutMs?: number;
+}
+interface PasskeyOptions {
+  /**
+   * The WebAuthn relying party ID: the domain the passkey (and so the account)
+   * is bound to. Default: `location.hostname`. Set a parent domain (e.g.
+   * `example.com` for `app.example.com`) to share one account across its
+   * subdomains.
+   */
+  rpId?: string;
+  /** The relying party name shown in passkey prompts. Default: the RP ID */
+  rpName?: string;
+  /**
+   * Separates this app's account from others on the same RP ID. Up to 128
+   * characters, no `:`. Default: `''`. Changing it changes the account.
+   */
+  context?: string;
+  /** The user name new passkeys are saved under. Default: `<rpName> account` */
+  userName?: string;
+  /**
+   * Keep the key unlocked between signatures, so only the first signature
+   * (or `connect`) runs a PRF ceremony with full user verification; later ones
+   * are confirmed per `confirm`. The key is held in a dedicated worker until
+   * the idle timeout, `disconnect` or a page reload. Default: `false`, a PRF
+   * ceremony for every request.
+   */
+  session?: boolean | PasskeySessionOptions;
+  /**
+   * Chooses how to confirm each signing request while a session is unlocked.
+   * Called synchronously, before the prompt: WebKit drops the user gesture
+   * across an await, so this must not be async. Default: `() => 'presence'`.
+   */
+  confirm?: (request: PasskeySigningRequest) => PasskeyConfirmation;
+  /**
+   * Replaces the built-in worker key store, e.g. to keep a session across page
+   * reloads. The adapter treats a custom key store as a session: it never
+   * locks it after signing, only on `disconnect`. May be called more than once.
+   */
+  keyStore?: () => PasskeyKeyStore;
+}
+interface PasskeyConnectArgs {
+  /** Create a new passkey (and account) instead of signing in with an existing one */
+  create?: boolean;
+  /** The user name to save a new passkey under */
+  userName?: string;
+}
+interface PasskeyRecoveryPhrase {
+  /** Import the phrase as a Falcon-1024 account, not a regular 25-word account */
+  scheme: 'falcon-1024';
+  /** The 25-word phrase */
+  phrase: string;
+}
+export declare class PasskeyAdapter extends BaseWallet<PasskeyOptions> {
+  private keyStore;
+  constructor(params: AdapterConstructorParams<PasskeyOptions>);
+  static defaultMetadata: WalletMetadata;
+  private get rpId();
+  private get rpName();
+  private get context();
+  /** True when the key stays unlocked between requests */
+  private get isSession();
+  private createKeyStore;
+  private getKeyStore;
+  /** Drop the key after a request, unless a session keeps it */
+  private release;
+  /**
+   * Sign in with an existing passkey, or create one with `{ create: true }`.
+   * Show both choices: a missing passkey and a cancelled prompt raise the same
+   * error, so the adapter can't tell which one happened.
+   */
+  connect: (args?: PasskeyConnectArgs) => Promise<WalletAccount[]>;
+  disconnect: () => Promise<void>;
+  /** Restores the account without a ceremony; the key unlocks on the first signature */
+  resumeSession: () => Promise<void>;
+  private matchesRecord;
+  private requireRecord;
+  /**
+   * Make sure the key is unlocked and the user approved this request. When the
+   * key is locked, the PRF ceremony that unlocks it is the approval. Starts its
+   * prompt before any await.
+   */
+  private authorize;
+  private processTxns;
+  private processEncodedTxns;
+  /**
+   * Signs the transactions sent from the connected account. Each one carries a
+   * Falcon-1024 `pqsig` (about 3.2 KB) and pays an extra 2× the minimum fee;
+   * get fees by simulating with `emptyTransactionSigner`.
+   */
+  signTransactions: <T extends algosdk.Transaction[] | Uint8Array[]>(txnGroup: T | T[], indexesToSign?: number[]) => Promise<(Uint8Array | null)[]>;
+  canSignData: boolean;
+  /**
+   * Signs an ARC-60 authentication request (SIWA) with the account's Falcon
+   * key, scheme `falcon-1024-det`. The signature covers
+   * `SHA-256(data) || SHA-256(authenticatorData)`.
+   */
+  signData: (data: string, metadata: StdSignMetadata) => Promise<StdSignDataResponse>;
+  /**
+   * Returns the account's 25-word recovery phrase after a fresh passkey
+   * ceremony with full user verification. Show it with a warning that it must
+   * be imported as a Falcon / quantum account (Lute: "Falcon25 account";
+   * Pera: quantum import; `algokey pq import --scheme falcon-1024`): the same
+   * words in a regular 25-word import restore a different, empty account.
+   */
+  exportRecoveryPhrase: () => Promise<PasskeyRecoveryPhrase>;
+}
+//#endregion
+//#region src/errors.d.ts
+type PasskeyErrorCode =
+/** The user cancelled or the request timed out (or, on iOS, an in-app browser blocked it) */
+'cancelled' |
+/** This browser can't run passkey ceremonies (no WebAuthn, or an Android WebView) */
+'unsupported' |
+/** The passkey's provider doesn't support the PRF extension */
+'prf-unsupported' |
+/** The relying party ID isn't valid for this page's origin */
+'invalid-rp-id' |
+/** The passkey derived a different key than the connected account's */
+'key-mismatch' |
+/** No account is connected */
+'not-connected' |
+/** The key store failed, e.g. the session worker was blocked by a CSP */
+'key-store-failed' | 'failed';
+export declare class PasskeyError extends Error {
+  readonly code: PasskeyErrorCode;
+  constructor(code: PasskeyErrorCode, message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/derivation.d.ts
+/** The PRF input prefix. Frozen: changing it moves every account. */
+export declare const PRF_LABEL_PREFIX = "@txnlab/use-wallet-passkey:falcon-1024:v1:";
+/** The PRF input (`eval.first`) for an account context */
+export declare function prfInput(context: string): Uint8Array;
+/** keygenSeed = SHA-512/256("PQK" || "f1" || entropy) */
+export declare function keygenSeedFromEntropy(entropy: Uint8Array): Uint8Array;
+//#endregion
+//#region src/record.d.ts
+export declare const LOCAL_STORAGE_PASSKEY_KEY = "@txnlab/use-wallet:v5:passkey";
+//#endregion
+//#region src/index.d.ts
+export declare const WALLET_ID: "passkey";
+export declare function passkey(options?: PasskeyOptions & WalletFactoryOptions): WalletAdapterConfig;
+//#endregion
+export type { PasskeyConfirmation, PasskeyConnectArgs, PasskeyErrorCode, PasskeyKeyStore, PasskeyOptions, PasskeyRecoveryPhrase, PasskeySessionOptions, PasskeySigningRequest, WorkerKeyStoreOptions };
+//# sourceMappingURL=index.d.ts.map