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

package/README.md

@@ -5,7 +5,31 @@
 
 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.
+It derives an **app-scoped 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.
+
+The account belongs to the site that creates it. Read the security model before you ship it.
+
+## Security model
+
+The key is derived inside your page, so your site is part of the account's trust boundary:
+
+- **Your site can take the key.** The passkey only works on its domain (the RP ID), and any script running there can derive the account's key with one verified passkey prompt, which looks the same as signing in. That includes your own code, an XSS bug, a compromised dependency or third-party script, a takeover of your hosting, deploy or DNS accounts, a re-registered domain, and every subdomain when `rpId` is a parent domain.
+- **The library can't protect users from the site.** It runs in your page, so nothing in it can stop the site itself from taking the key. Users have to trust your site the way they'd trust an app that holds a balance for them.
+- **Other sites can't reach it.** Browsers bind a passkey to its domain, so another site can't derive this account, and this account gives no access to the user's other wallets.
+- **An unlocked session signs without a new key prompt.** Page scripts can request signatures through the adapter: silently if `confirm` returns `'silent'`, otherwise behind a passkey prompt. Getting the key itself always takes a fully verified prompt.
+- **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.
+
+Tell users plainly whose account it is, for example: _"This account is created by and for example.com. Keep only what you need here, and move larger amounts to a wallet you control."_ For the same reason, the adapter names the account after its domain (`Passkey · example.com`).
+
+### Best practices
+
+- Present it as a starting account: keep balances small, and offer both [moving to a wallet](#moving-to-a-wallet) and the [recovery phrase](#recovery-phrase).
+- Set a strict [Content Security Policy](#content-security-policy) and load as few third-party scripts as you can.
+- Keep `rpId` narrow: the default hostname, unless you need to share the account across subdomains.
+- Protect the domain and the accounts behind it: registrar lock, auto-renew, and two-factor authentication on your registrar, DNS, hosting and deploy accounts.
+- Choose `confirm` and the session timeouts deliberately, or [let users choose](#user-preferences). With `'silent'`, any script on your page can sign while the session is unlocked, so it's exactly as safe as your page. Asking for `'presence'` or `'verify'` above an amount you pick is a middle ground.
+- Show what's being signed in your own UI before you call `signTransactions`. The passkey prompt can only show your site's name.
 
 ## Installation
 
@@ -37,15 +61,17 @@ Call `connect`, `signTransactions` and `signData` directly from the click handle
 
 ### 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`)                                                                                            |
+| 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, maxAgeMs, lockWhenHidden }`.                           |
+| `confirm`  | `() => 'presence'`  | How to confirm each signature while a session is unlocked                                                                                |
+| `onLock`   | none                | Called with a reason when an unlocked session locks (see below)                                                                          |
+| `onUnlock` | none                | Called when a locked session unlocks (see below)                                                                                         |
+| `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.
 
@@ -53,15 +79,23 @@ The factory also accepts an optional `metadata` option to override the wallet's
 
 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:
+With `session`, only the first request after connecting or reloading does. The key then stays in a dedicated worker until the session locks, 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
 
+A session locks on `disconnect`, on a page reload, and when any of these options says so:
+
+- `idleTimeoutMs`: after this long without a signature. Default: 15 minutes.
+- `maxAgeMs`: this long after it unlocked, however active it is. Default: 1 hour.
+- `lockWhenHidden`: when the page is hidden, e.g. the user switches tabs or apps. A signing request in progress finishes first. Default: `false`, because on phones, leaving the browser to copy an address means one more verified prompt. Pass a function to follow a setting the user can change.
+
+`0` turns off either timeout.
+
 ```typescript
 passkey({
-  session: { idleTimeoutMs: 10 * 60 * 1000 },
+  session: { idleTimeoutMs: 10 * 60 * 1000, maxAgeMs: 30 * 60 * 1000, lockWhenHidden: true },
   confirm: (request) =>
     request.type === 'transactions' && request.transactions.some((txn) => txn.type === 'pay')
       ? 'verify'
@@ -71,6 +105,49 @@ passkey({
 
 `confirm` must be synchronous: awaiting before the prompt would lose the user's tap on iOS.
 
+### Unlocking and locking
+
+After a page reload, the first signature runs the PRF ceremony. On iOS, that prompt only appears if `signTransactions` is called straight from the user's tap. If your flow awaits something first, such as fetching a quote or building the group, unlock the session on an earlier tap instead:
+
+```typescript
+const wallet = manager.getWallet('passkey') as PasskeyAdapter
+
+wallet.isUnlocked // false after a reload or a lock
+await wallet.unlock() // call from a click handler: one verified prompt
+wallet.lock() // drops the key; the account stays connected
+```
+
+A session can also lock on its own, and a signature can unlock it. Pass `onLock` and `onUnlock` to keep your UI in step, e.g. to show an "Unlock" button:
+
+```typescript
+passkey({
+  session: true,
+  onLock: (reason) => setUnlocked(false), // 'idle' | 'max-age' | 'hidden' | 'lock' | 'disconnect' | 'connect' | 'key-store'
+  onUnlock: () => setUnlocked(true)
+})
+```
+
+`onUnlock` is called once each time a locked session unlocks: on `connect`, `unlock()`, or a signature that ran the PRF ceremony. `onLock` is called once each time it locks: `'idle'` and `'max-age'` are the timeouts, `'hidden'` is `lockWhenHidden`, `'lock'` is your own `lock()` call, `'connect'` means a new `connect` replaced or dropped the session, and `'key-store'` means the key store dropped the key itself, e.g. because its worker failed. Without `session`, neither is called and `unlock()` does nothing.
+
+### User preferences
+
+`confirm` runs on every request, so it can follow a setting the user changes at any time. `lockWhenHidden` can be a function for the same reason. For auto-lock settings, turn off the built-in timeouts and call `lock()` on your own schedule, starting from `onUnlock`:
+
+```typescript
+let autoLock: ReturnType<typeof setTimeout> | undefined
+
+passkey({
+  session: { idleTimeoutMs: 0, maxAgeMs: 0, lockWhenHidden: () => settings.lockWhenHidden },
+  confirm: () => settings.confirmation, // 'silent' | 'presence' | 'verify'
+  onUnlock: () => {
+    if (settings.autoLockMs) autoLock = setTimeout(() => wallet.lock(), settings.autoLockMs)
+  },
+  onLock: () => clearTimeout(autoLock)
+})
+```
+
+These settings decide how often honest requests prompt the user. They don't protect against a compromised page: a script that takes over your page can change them too.
+
 ### Recovery phrase
 
 The account is bound to your domain, so it's stranded if the domain is lost. Let users export its recovery phrase:
@@ -86,6 +163,44 @@ 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.
 
+### Moving to a wallet
+
+Give users a way to move to a wallet they control, such as Pera, Defly or Lute. After that, a compromise of your site can't reach their funds. There are two ways:
+
+- **Close the account:** send the whole balance to the wallet with `closeRemainderTo`. An account that still holds assets or app opt-ins can't close, so send or opt out of those first, or rekey instead.
+- **Rekey it:** keep the address, and give its signing authority to the wallet's account with `rekeyTo`. The passkey can no longer sign for it, so disconnect the passkey account afterwards. The user needs a wallet that supports rekeyed accounts to use the address. Rekeying to a regular (ed25519) account gives up post-quantum protection.
+
+```typescript
+import algosdk from 'algosdk'
+
+const wallet = manager.getWallet('passkey')!
+const sender = wallet.activeAddress!
+const params = await manager.algodClient.getTransactionParams().do()
+// A Falcon signature pays 3× the minimum fee; under congestion, simulate for the fee
+const suggestedParams = { ...params, flatFee: true, fee: params.minFee * 3n }
+
+// Close: send the whole balance to the wallet
+const close = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+  sender,
+  receiver: walletAddress,
+  amount: 0,
+  closeRemainderTo: walletAddress,
+  suggestedParams
+})
+
+// Or rekey: keep the address, and let the wallet sign for it
+const rekey = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+  sender,
+  receiver: sender,
+  amount: 0,
+  rekeyTo: walletAddress,
+  suggestedParams
+})
+
+const [signed] = await wallet.signTransactions([close]) // or [rekey]
+await manager.algodClient.sendRawTransaction(signed!).do()
+```
+
 ### 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:
@@ -106,10 +221,4 @@ Failures throw a `PasskeyError` with a `code`: `cancelled`, `unsupported` (no We
 - 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

@@ -1,7 +1,16 @@
 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/worker/protocol.d.ts
+/** Why the key worker locked itself */
+type PasskeyTimeoutReason = 'idle' | 'max-age';
+//#endregion
 //#region src/key-store.d.ts
+/**
+ * Why the built-in key store locked itself: a timeout, or `'key-store'` when
+ * its worker failed
+ */
+type WorkerKeyStoreLockReason = PasskeyTimeoutReason | 'key-store';
 /**
  * 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
@@ -25,8 +34,10 @@ interface PasskeyKeyStore {
 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;
+  /** Clear the key this long after `unlock`, however often it signs. 0 sets no limit. */
+  maxAgeMs?: number;
+  /** Called when the key store locks itself, not on `lock` */
+  onLock?: (reason: WorkerKeyStoreLockReason) => void;
   /** How long to wait for the worker to load. Default: 10000 */
   startTimeoutMs?: number;
 }
@@ -73,9 +84,28 @@ type PasskeySigningRequest = {
   type: 'data';
   siwa: Siwa;
 };
+/**
+ * Why an unlocked session locked:
+ * - `idle`, `max-age`: the built-in key store's timeouts
+ * - `hidden`: the page was hidden, with `lockWhenHidden`
+ * - `lock`: the app called `lock()`
+ * - `disconnect`: the wallet disconnected
+ * - `connect`: a new `connect` replaced or dropped the session
+ * - `key-store`: the key store dropped the key itself, e.g. its worker failed
+ */
+type PasskeyLockReason = WorkerKeyStoreLockReason | 'hidden' | 'lock' | 'disconnect' | 'connect';
 interface PasskeySessionOptions {
   /** Lock the session after this long without a signature; 0 never locks it. Default: 15 minutes */
   idleTimeoutMs?: number;
+  /** Lock the session this long after it unlocks, however active it is; 0 sets no limit. Default: 1 hour */
+  maxAgeMs?: number;
+  /**
+   * Lock the session when the page is hidden, e.g. the user switches tabs or
+   * apps. A signing request in progress finishes first. Also applies to a
+   * custom `keyStore`. Pass a function to follow a setting the user can
+   * change; it's read each time the page is hidden. Default: `false`
+   */
+  lockWhenHidden?: boolean | (() => boolean);
 }
 interface PasskeyOptions {
   /**
@@ -98,8 +128,8 @@ interface PasskeyOptions {
    * 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.
+   * the idle timeout, the maximum age, `disconnect` or a page reload. Default:
+   * `false`, a PRF ceremony for every request.
    */
   session?: boolean | PasskeySessionOptions;
   /**
@@ -108,6 +138,17 @@ interface PasskeyOptions {
    * across an await, so this must not be async. Default: `() => 'presence'`.
    */
   confirm?: (request: PasskeySigningRequest) => PasskeyConfirmation;
+  /**
+   * Called when an unlocked session locks, so the app can show it (e.g. an
+   * "Unlock" button) without polling `isUnlocked`. Not called without a
+   * session, where the key is only held during a request.
+   */
+  onLock?: (reason: PasskeyLockReason) => void;
+  /**
+   * Called when a locked session unlocks: on `connect`, `unlock`, or a
+   * signature that ran the PRF ceremony. Not called without a session.
+   */
+  onUnlock?: () => void;
   /**
    * 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
@@ -129,6 +170,10 @@ interface PasskeyRecoveryPhrase {
 }
 export declare class PasskeyAdapter extends BaseWallet<PasskeyOptions> {
   private keyStore;
+  /** Signing requests in progress; hiding the page doesn't lock in the middle of one */
+  private activeRequests;
+  /** Whether the session was unlocked when `onLock`/`onUnlock` last checked */
+  private reportedUnlocked;
   constructor(params: AdapterConstructorParams<PasskeyOptions>);
   static defaultMetadata: WalletMetadata;
   private get rpId();
@@ -136,10 +181,23 @@ export declare class PasskeyAdapter extends BaseWallet<PasskeyOptions> {
   private get context();
   /** True when the key stays unlocked between requests */
   private get isSession();
+  private get sessionOptions();
+  private get lockWhenHidden();
   private createKeyStore;
   private getKeyStore;
   /** Drop the key after a request, unless a session keeps it */
   private release;
+  /** True when the page is hidden and the session should lock for it */
+  private isHidden;
+  private onVisibilityChange;
+  /** Finish a request: drop the key unless the session keeps it, and report the session state */
+  private finishRequest;
+  /**
+   * Call `onLock` or `onUnlock` once when the session changes state, with
+   * `reason` for a lock. Checks the key store itself, so a change is reported
+   * however it happened.
+   */
+  private reportSession;
   /**
    * 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
@@ -151,6 +209,27 @@ export declare class PasskeyAdapter extends BaseWallet<PasskeyOptions> {
   resumeSession: () => Promise<void>;
   private matchesRecord;
   private requireRecord;
+  /** True when the key is unlocked, so the next signature needs no PRF ceremony */
+  get isUnlocked(): boolean;
+  /**
+   * Unlocks the session ahead of the next signature with one PRF ceremony
+   * (full user verification), e.g. from an "Unlock" button after a page
+   * reload, so signing needs no ceremony. Call it directly from the click
+   * handler: iOS drops the tap across an await. Does nothing if the session is
+   * already unlocked, or without `session`, where every request runs its own
+   * ceremony.
+   */
+  unlock: () => Promise<void>;
+  /**
+   * Drops the key. The account stays connected; the next signature (or
+   * `unlock`) runs a PRF ceremony.
+   */
+  lock: () => void;
+  /**
+   * Unlock the key with a PRF ceremony for the connected credential, and check
+   * it derives the connected account. Starts its prompt before any await.
+   */
+  private unlockKey;
   /**
    * 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
@@ -220,5 +299,5 @@ export declare const LOCAL_STORAGE_PASSKEY_KEY = "@txnlab/use-wallet:v5:passkey"
 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 };
+export type { PasskeyConfirmation, PasskeyConnectArgs, PasskeyErrorCode, PasskeyKeyStore, PasskeyLockReason, PasskeyOptions, PasskeyRecoveryPhrase, PasskeySessionOptions, PasskeySigningRequest, PasskeyTimeoutReason, WorkerKeyStoreLockReason, WorkerKeyStoreOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -122,7 +122,8 @@ var WorkerKeyStore = class {
 			const publicKey = await this.call({
 				op: "unlock",
 				entropy: buffer,
-				idleTimeoutMs: this.options.idleTimeoutMs
+				idleTimeoutMs: this.options.idleTimeoutMs,
+				maxAgeMs: this.options.maxAgeMs
 			}, [buffer]);
 			this.isUnlocked = true;
 			return publicKey;
@@ -149,7 +150,7 @@ var WorkerKeyStore = class {
 		this.pending.clear();
 	}
 	async start() {
-		const { WORKER_SOURCE } = await import("./source.generated-CISa6YOa.js");
+		const { WORKER_SOURCE } = await import("./source.generated-BdYdygOX.js");
 		const { startTimeoutMs = 1e4 } = this.options;
 		const url = URL.createObjectURL(new Blob([WORKER_SOURCE], { type: "text/javascript" }));
 		return new Promise((resolve, reject) => {
@@ -179,7 +180,9 @@ var WorkerKeyStore = class {
 				worker.onmessage = (event) => this.handle(event.data);
 				worker.onerror = (event) => {
 					event.preventDefault();
+					const wasUnlocked = this.isUnlocked;
 					this.lock();
+					if (wasUnlocked) this.options.onLock?.("key-store");
 				};
 				resolve(worker);
 			};
@@ -213,7 +216,7 @@ var WorkerKeyStore = class {
 	handle(message) {
 		if (message.type === "locked") {
 			this.lock();
-			this.options.onIdleLock?.();
+			this.options.onLock?.(message.reason);
 			return;
 		}
 		if (message.type !== "result") return;
@@ -411,11 +414,13 @@ function assertUser({ rpId, credentialId, userVerification }) {
 * provider (iCloud Keychain, Google Password Manager, 1Password, Windows
 * Hello, a security key) syncs and protects the credential.
 *
-* SECURITY CONSIDERATIONS:
-* - The account is bound to the relying party ID (by default the page's
-*   hostname). Whoever controls that domain can run a PRF ceremony and recover
-*   the key with one tap, and the account is stranded if the domain is lost,
-*   so offer `exportRecoveryPhrase`.
+* SECURITY MODEL: the account is app-scoped.
+* - It is bound to the relying party ID (by default the page's hostname). Any
+*   script running there can derive the key with one verified passkey prompt
+*   that looks like a sign-in: the dApp itself, an XSS bug, a compromised
+*   dependency, or whoever takes over the domain. Other sites can't derive it.
+* - The account is stranded if the domain is lost, so offer
+*   `exportRecoveryPhrase` and a way to move to a wallet. See the README.
 * - Only public data is persisted: the credential ID, public key, address
 *   salt and address. Never the PRF output, the entropy or the private key.
 * - The private key lives in a dedicated worker, never on the main thread.
@@ -423,6 +428,7 @@ function assertUser({ rpId, credentialId, userVerification }) {
 */
 const ICON = `data:image/svg+xml;base64,${btoa(icon)}`;
 const DEFAULT_IDLE_TIMEOUT_MS = 9e5;
+const DEFAULT_MAX_AGE_MS = 36e5;
 function bytesEqual(a, b) {
 	return a.length === b.length && a.every((byte, i) => byte === b[i]);
 }
@@ -439,9 +445,14 @@ async function sha256(data) {
 }
 var PasskeyAdapter = class extends BaseWallet {
 	keyStore = null;
+	/** Signing requests in progress; hiding the page doesn't lock in the middle of one */
+	activeRequests = 0;
+	/** Whether the session was unlocked when `onLock`/`onUnlock` last checked */
+	reportedUnlocked = false;
 	constructor(params) {
 		super(params);
 		assertValidContext(this.context);
+		if (this.isSession && this.sessionOptions.lockWhenHidden && typeof document !== "undefined") document.addEventListener("visibilitychange", this.onVisibilityChange);
 	}
 	static defaultMetadata = {
 		name: "Passkey",
@@ -460,12 +471,32 @@ var PasskeyAdapter = class extends BaseWallet {
 	get isSession() {
 		return !!this.options.session || !!this.options.keyStore;
 	}
+	get sessionOptions() {
+		const { session } = this.options;
+		return typeof session === "object" ? session : {};
+	}
+	get lockWhenHidden() {
+		const { lockWhenHidden } = this.sessionOptions;
+		if (!this.isSession) return false;
+		if (typeof lockWhenHidden !== "function") return !!lockWhenHidden;
+		try {
+			return lockWhenHidden();
+		} catch (error) {
+			this.logger.error("Error in lockWhenHidden:", error.message);
+			return true;
+		}
+	}
 	createKeyStore() {
 		if (this.options.keyStore) return this.options.keyStore();
-		const { session } = this.options;
+		const session = !!this.options.session;
+		const { idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS, maxAgeMs = DEFAULT_MAX_AGE_MS } = this.sessionOptions;
 		return new WorkerKeyStore({
-			idleTimeoutMs: session ? (typeof session === "object" ? session.idleTimeoutMs : void 0) ?? DEFAULT_IDLE_TIMEOUT_MS : 0,
-			onIdleLock: () => this.logger.info("Session locked after inactivity")
+			idleTimeoutMs: session ? idleTimeoutMs : 0,
+			maxAgeMs: session ? maxAgeMs : 0,
+			onLock: (reason) => {
+				this.logger.info(`Session locked (${reason})`);
+				this.reportSession(reason);
+			}
 		});
 	}
 	getKeyStore() {
@@ -474,7 +505,39 @@ var PasskeyAdapter = class extends BaseWallet {
 	}
 	/** Drop the key after a request, unless a session keeps it */
 	release() {
-		if (!this.isSession) this.keyStore?.lock();
+		if (!this.isSession || this.isHidden()) this.keyStore?.lock();
+	}
+	/** True when the page is hidden and the session should lock for it */
+	isHidden() {
+		return typeof document !== "undefined" && document.visibilityState === "hidden" && this.lockWhenHidden;
+	}
+	onVisibilityChange = () => {
+		if (this.activeRequests === 0 && this.isHidden()) {
+			this.keyStore?.lock();
+			this.reportSession("hidden");
+		}
+	};
+	/** Finish a request: drop the key unless the session keeps it, and report the session state */
+	finishRequest() {
+		this.activeRequests--;
+		this.release();
+		this.reportSession(this.isHidden() ? "hidden" : "key-store");
+	}
+	/**
+	* Call `onLock` or `onUnlock` once when the session changes state, with
+	* `reason` for a lock. Checks the key store itself, so a change is reported
+	* however it happened.
+	*/
+	reportSession(reason) {
+		const unlocked = this.isSession && this.isUnlocked;
+		if (unlocked === this.reportedUnlocked) return;
+		this.reportedUnlocked = unlocked;
+		try {
+			if (unlocked) this.options.onUnlock?.();
+			else this.options.onLock?.(reason);
+		} catch (error) {
+			this.logger.error(`Error in ${unlocked ? "onUnlock" : "onLock"}:`, error.message);
+		}
 	}
 	/**
 	* Sign in with an existing passkey, or create one with `{ create: true }`.
@@ -516,7 +579,7 @@ var PasskeyAdapter = class extends BaseWallet {
 			};
 			saveRecord(record);
 			const walletAccount = {
-				name: `${this.metadata.name} Account`,
+				name: `${this.metadata.name} · ${rpId}`,
 				address: record.address,
 				emptySignature: emptySignatureFor(record)
 			};
@@ -525,11 +588,13 @@ var PasskeyAdapter = class extends BaseWallet {
 				activeAccount: walletAccount
 			};
 			this.store.addWallet(walletState);
+			this.reportSession(this.isHidden() ? "hidden" : "connect");
 			this.logger.info("Connected successfully", walletState);
 			return [walletAccount];
 		} catch (error) {
 			result?.prf.fill(0);
 			this.keyStore?.lock();
+			this.reportSession("connect");
 			this.logger.error("Error connecting:", error.message);
 			throw error;
 		}
@@ -537,6 +602,7 @@ var PasskeyAdapter = class extends BaseWallet {
 	disconnect = async () => {
 		this.logger.info("Disconnecting...");
 		this.keyStore?.lock();
+		this.reportSession("disconnect");
 		this.keyStore = null;
 		removeRecord();
 		this.onDisconnect();
@@ -566,25 +632,64 @@ var PasskeyAdapter = class extends BaseWallet {
 		if (!walletState || !record || !this.matchesRecord(record, walletState)) throw new PasskeyError("not-connected", "No passkey account is connected.");
 		return record;
 	}
+	/** True when the key is unlocked, so the next signature needs no PRF ceremony */
+	get isUnlocked() {
+		return this.keyStore?.unlocked ?? false;
+	}
+	/**
+	* Unlocks the session ahead of the next signature with one PRF ceremony
+	* (full user verification), e.g. from an "Unlock" button after a page
+	* reload, so signing needs no ceremony. Call it directly from the click
+	* handler: iOS drops the tap across an await. Does nothing if the session is
+	* already unlocked, or without `session`, where every request runs its own
+	* ceremony.
+	*/
+	unlock = async () => {
+		const record = this.requireRecord();
+		if (!this.isSession || this.isUnlocked) return;
+		this.logger.info("Unlocking...");
+		this.activeRequests++;
+		try {
+			await this.unlockKey(record);
+			this.logger.info("Unlocked");
+		} catch (error) {
+			this.logger.error("Error unlocking:", error.message);
+			throw error;
+		} finally {
+			this.finishRequest();
+		}
+	};
+	/**
+	* Drops the key. The account stays connected; the next signature (or
+	* `unlock`) runs a PRF ceremony.
+	*/
+	lock = () => {
+		this.keyStore?.lock();
+		this.reportSession("lock");
+	};
+	/**
+	* Unlock the key with a PRF ceremony for the connected credential, and check
+	* it derives the connected account. Starts its prompt before any await.
+	*/
+	async unlockKey(record) {
+		const keyStore = this.getKeyStore();
+		const { prf } = await evaluatePrf({
+			rpId: record.rpId,
+			prfInput: prfInput(record.context),
+			credentialId: record.credentialId
+		});
+		if (!bytesEqual(await keyStore.unlock(prf), record.publicKey)) {
+			keyStore.lock();
+			throw new PasskeyError("key-mismatch", "This passkey derived a different key than the connected account. Disconnect and connect again.");
+		}
+	}
 	/**
 	* 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.
 	*/
 	async authorize(request, record) {
-		const keyStore = this.getKeyStore();
-		if (!keyStore.unlocked) {
-			const { prf } = await evaluatePrf({
-				rpId: record.rpId,
-				prfInput: prfInput(record.context),
-				credentialId: record.credentialId
-			});
-			if (!bytesEqual(await keyStore.unlock(prf), record.publicKey)) {
-				keyStore.lock();
-				throw new PasskeyError("key-mismatch", "This passkey derived a different key than the connected account. Disconnect and connect again.");
-			}
-			return;
-		}
+		if (!this.getKeyStore().unlocked) return this.unlockKey(record);
 		const confirmation = this.options.confirm?.(request) ?? "presence";
 		if (confirmation === "silent") return;
 		await assertUser({
@@ -614,6 +719,7 @@ var PasskeyAdapter = class extends BaseWallet {
 		const record = this.requireRecord();
 		const txnsToSign = isTransactionArray(txnGroup) ? this.processTxns(flattenTxnGroup(txnGroup), indexesToSign, record.address) : this.processEncodedTxns(flattenTxnGroup(txnGroup), indexesToSign, record.address);
 		if (txnsToSign.length === 0) return [];
+		this.activeRequests++;
 		try {
 			this.logger.debug("Signing transactions...", { txnsToSign });
 			await this.authorize({
@@ -632,7 +738,7 @@ var PasskeyAdapter = class extends BaseWallet {
 			this.logger.error("Error signing transactions:", error.message);
 			throw error;
 		} finally {
-			this.release();
+			this.finishRequest();
 		}
 	};
 	canSignData = true;
@@ -661,6 +767,7 @@ var PasskeyAdapter = class extends BaseWallet {
 		if (!siwa || typeof siwa !== "object" || canonify(siwa) !== json) throw new SignDataError("Bad JSON", 4609);
 		if (siwa.domain !== location.host) throw new SignDataError("Failed Domain Auth", 4610);
 		if (siwa.type !== "falcon-1024-det" || siwa.account_address !== record.address) throw new SignDataError("Invalid Signer", 4603);
+		this.activeRequests++;
 		try {
 			await this.authorize({
 				type: "data",
@@ -678,7 +785,7 @@ var PasskeyAdapter = class extends BaseWallet {
 			this.logger.error("Error signing data:", error.message);
 			throw error;
 		} finally {
-			this.release();
+			this.finishRequest();
 		}
 	};
 	/**