signet-login 0.10.0 → 0.10.2

package/README.md

@@ -6,7 +6,8 @@ Published as `signet-login`.
 
 **Signet Access** is a drop-in auth and signer-access SDK for Nostr-aware websites. One picker, one session shape, multiple ways to prove identity and, when available, keep a live signer:
 
-- **Sign in with Signet** on this device or by cross-device QR
+- **Local Signet** on this device, against hosted or local-dev Signet
+- **Remote Signet** by cross-device QR, so a phone or second machine can approve
 - **Browser extension** via NIP-07 (bark, Alby, nos2x, Flamingo, ...)
 - **Connect a Nostr signer** via app-initiated NIP-46 / NostrConnect
 - **Paste or scan bunker URI** for Heartwood, nsecBunker, Amber, or compatible signers
@@ -76,13 +77,22 @@ interface LoginOptions {
   signetAppOrigin?: string;                     // default https://mysignet.app
   redirectCallback?: string;                    // for same-device redirect / Amber return
   mode?: 'relay' | 'redirect';                  // Signet delivery mode
-  persist?: boolean;                            // default true (localStorage)
+  storage?: SignetStorage;                      // default localStorage
+  persist?: boolean;                            // default true
+}
+
+interface SignetStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
 }
 
 type LoginPickerMethod =
   | 'nip07'
-  | 'redirect'      // same-device Signet, relay delivery
-  | 'qr'            // cross-device Signet QR
+  | 'local-signet'  // same-device Signet, relay delivery
+  | 'remote-signet' // cross-device Signet QR
+  | 'redirect'      // legacy alias for local-signet
+  | 'qr'            // legacy alias for remote-signet
   | 'bunker'        // paste bunker://
   | 'nostrconnect'  // show nostrconnect:// QR
   | 'amber'         // Android NIP-55
@@ -103,7 +113,14 @@ By default, the picker shows ordinary user-facing methods first and groups `bunk
 ```js
 await Signet.login({
   appName: 'My Game',
-  methods: ['redirect', 'qr', 'nip07'],
+  methods: ['local-signet', 'remote-signet', 'nip07'],
+});
+
+await Signet.login({
+  appName: 'My Local Dev Game',
+  preferredMethod: 'local-signet',
+  signetAppOrigin: 'http://localhost:5174',
+  relayUrl: 'ws://localhost:7777',
 });
 
 await Signet.login({
@@ -114,6 +131,8 @@ await Signet.login({
 });
 ```
 
+`redirect` and `qr` remain supported picker aliases for existing apps, but new integrations should use `local-signet` and `remote-signet`.
+
 When camera APIs are available, the bunker URI screen can scan `bunker://` QR codes directly. Paste remains the fallback.
 
 ### Headless/custom UI
@@ -148,9 +167,41 @@ await fetch('/api/login', {
 Headless exports include `hasNip07`, `createNip07Signer`, `createBunkerSigner`, `createBunkerSignerFromNostrConnect`, `buildNostrConnectUri`, `createLocalSignerFromNsec`, `createLoginAuthEvent`, `createSessionFromSigner`, and `generateSecretKey`.
 The IIFE bundle attaches the same helpers to `window.Signet`.
 
+### Custom storage
+
+By default, Signet Access stores session state in localStorage under `signet:login.*`. Pass `storage` when you need encrypted, async, IndexedDB, server-backed, or test storage:
+
+```js
+const encryptedStorage = {
+  async getItem(key) {
+    const value = localStorage.getItem(key);
+    return value ? await decrypt(value) : null;
+  },
+  async setItem(key, value) {
+    localStorage.setItem(key, await encrypt(value));
+  },
+  async removeItem(key) {
+    localStorage.removeItem(key);
+  },
+};
+
+const session = await Signet.login({
+  appName: 'My Game',
+  storage: encryptedStorage,
+});
+
+await Signet.restoreSession({ storage: encryptedStorage });
+await Signet.handleRedirectCallback({ storage: encryptedStorage });
+await Signet.logout(session, { storage: encryptedStorage });
+```
+
+Use the same storage adapter for `login`, `restoreSession`, `handleRedirectCallback`, and `logout`.
+
+This adapter is deliberately not called "Stash". `@forgesworn/stash` is the separate encrypted cloud-save vault for app data; Signet Access storage is local session/reconnect state needed before a signer is available.
+
 ### `Signet.restoreSession(opts?)`
 
-Restore a session from localStorage. For bunker sessions this attempts to reconnect to the stored bunker. Returns `null` if no session is stored, the session is malformed, or reconnection fails.
+Restore a session from configured storage. For bunker sessions this attempts to reconnect to the stored bunker. Returns `null` if no session is stored, the session is malformed, or reconnection fails.
 
 ```js
 const session = await Signet.restoreSession();
@@ -159,7 +210,7 @@ if (session?.signer.capabilities.canSignEvents) {
 }
 ```
 
-### `Signet.logout(currentSession?)`
+### `Signet.logout(currentSession?, opts?)`
 
 Clear stored session and close the active signer.
 
@@ -226,7 +277,7 @@ The verifier checks: schnorr signature, canonical event ID, kind=21236, challeng
 
 ## Storage
 
-Session data is stored in localStorage under `signet:login.*`:
+By default, session data is stored in localStorage under `signet:login.*`:
 
 | Key | Purpose |
 |---|---|
@@ -264,7 +315,7 @@ The ESM entry is approx **5.9 KB gzipped** before bundling dependencies. The sta
 
 ## Browser support
 
-ES2020 baseline. Tested on modern Chrome / Firefox / Safari. Requires `localStorage`, `crypto.subtle`, `WebSocket`, and the native `<dialog>` element.
+ES2020 baseline. Tested on modern Chrome / Firefox / Safari. Requires `crypto.subtle`, `WebSocket`, and the native `<dialog>` element. Session persistence defaults to `localStorage`, but apps can provide a custom storage adapter.
 
 ## Development
 
@@ -282,8 +333,6 @@ Examples in `examples/`:
 
 Build the IIFE bundle first, then serve the repo root with any static server and open `examples/basic.html` or `examples/headless.html`.
 
-See [docs/competitive-audit.md](docs/competitive-audit.md) for the current competitor comparison and roadmap priorities.
-
 ## Out of scope
 
 | Excluded | Where it lives |

package/dist/amber.d.ts

@@ -17,7 +17,7 @@
  * environment. Smoke test on a real Android device with Amber installed
  * before promoting to production.
  */
-import type { SignetSession } from './types.js';
+import type { SignetStorage, SignetSession } from './types.js';
 /** True when running on a likely-Android browser. Lets the picker hide the
  *  Amber option on iOS/desktop where the `nostrsigner:` scheme is unhandled. */
 export declare function isAndroid(): boolean;
@@ -27,6 +27,7 @@ export interface AmberStartOptions {
     origin: string;
     /** Optional override for the callback URL. Defaults to current page origin. */
     redirectCallback?: string;
+    storage?: SignetStorage;
 }
 /**
  * Build the `nostrsigner:` URL that Android dispatches to Amber. The auth
@@ -52,10 +53,5 @@ export type ConsumeAmberResult = {
     kind: 'invalid';
     reason: string;
 };
-/**
- * Consume an Amber callback. Detects `?event=<base64-or-json>` (or the
- * `signet_amber=1` flag) on the URL and reconstructs a session. Idempotent:
- * a second call after a successful consume returns 'no-callback' because
- * the params have been stripped.
- */
 export declare function consumeAmberCallback(): ConsumeAmberResult;
+export declare function consumeAmberCallbackFromStorage(storage?: SignetStorage): Promise<ConsumeAmberResult>;

package/dist/amber.js

@@ -1,5 +1,5 @@
 import { PENDING_REDIRECT_TTL_MS } from './types.js';
-import { clearPendingRedirect, loadPendingRedirect, savePendingRedirect, } from './storage.js';
+import { clearPendingRedirect, clearPendingRedirectFromStorage, loadPendingRedirect, loadPendingRedirectFromStorage, savePendingRedirectToStorage, } from './storage.js';
 import { EphemeralSigner } from './signers.js';
 /** True when running on a likely-Android browser. Lets the picker hide the
  *  Amber option on iOS/desktop where the `nostrsigner:` scheme is unhandled. */
@@ -55,7 +55,7 @@ export function buildAmberSignerUrl(opts) {
  * web URL handled by signet-app. The promise never resolves — the page is
  * gone before it can.
  */
-export function startAmberSignIn(opts) {
+export async function startAmberSignIn(opts) {
     if (typeof window === 'undefined') {
         throw new Error('signet-login: amber mode requires a browser environment');
     }
@@ -65,7 +65,7 @@ export function startAmberSignIn(opts) {
         appName: opts.appName,
         createdAt: Date.now(),
     };
-    savePendingRedirect(pending);
+    await savePendingRedirectToStorage(pending, opts.storage);
     window.location.href = buildAmberSignerUrl(opts);
     return new Promise(() => { });
 }
@@ -96,22 +96,16 @@ function cleanupAmberCallbackUrl() {
  * a second call after a successful consume returns 'no-callback' because
  * the params have been stripped.
  */
-export function consumeAmberCallback() {
+function consumeAmberCallbackWithPending(pending, finalize) {
     if (typeof window === 'undefined')
         return { kind: 'no-callback' };
     const params = new URLSearchParams(window.location.search);
     const flagged = params.has('signet_amber') || params.has('event');
     if (!flagged)
         return { kind: 'no-callback' };
-    const finalize = (result) => {
-        clearPendingRedirect();
-        cleanupAmberCallbackUrl();
-        return result;
-    };
     if (params.get('error') === 'denied') {
         return finalize({ kind: 'denied' });
     }
-    const pending = loadPendingRedirect();
     if (!pending) {
         return finalize({ kind: 'invalid', reason: 'no-pending-state' });
     }
@@ -179,3 +173,19 @@ export function consumeAmberCallback() {
     };
     return finalize({ kind: 'session', session });
 }
+export function consumeAmberCallback() {
+    const finalize = (result) => {
+        clearPendingRedirect();
+        cleanupAmberCallbackUrl();
+        return result;
+    };
+    return consumeAmberCallbackWithPending(loadPendingRedirect(), finalize);
+}
+export async function consumeAmberCallbackFromStorage(storage) {
+    const finalize = async (result) => {
+        await clearPendingRedirectFromStorage(storage);
+        cleanupAmberCallbackUrl();
+        return result;
+    };
+    return await consumeAmberCallbackWithPending(await loadPendingRedirectFromStorage(storage), finalize);
+}

package/dist/modal.js

@@ -7,14 +7,15 @@
 import { DEFAULTS } from './types.js';
 import { hasNip07, createNip07Signer, createBunkerSigner, createBunkerSignerFromNostrConnect, buildNostrConnectUri, EphemeralSigner, createLocalSignerFromNsec } from './signers.js';
 import { isAndroid, startAmberSignIn } from './amber.js';
-import { loadOrCreatePersistentClientSk } from './storage.js';
+import { loadOrCreatePersistentClientSkFromStorage } from './storage.js';
 import { waitForAuthResponse } from 'signet-verify';
 import { schnorr } from '@noble/curves/secp256k1';
 import { bytesToHex } from '@noble/hashes/utils';
 import QRCode from 'qrcode';
 import jsQR from 'jsqr';
 const QR_BUNKER_CONNECT_TIMEOUT_MS = 8000;
-const DEFAULT_PICKER_METHODS = ['nip07', 'amber', 'redirect', 'qr', 'bunker', 'nostrconnect', 'nsec'];
+const DEFAULT_PICKER_METHODS = ['nip07', 'amber', 'local-signet', 'remote-signet', 'bunker', 'nostrconnect', 'nsec'];
+const ALL_PICKER_METHODS = [...DEFAULT_PICKER_METHODS, 'redirect', 'qr'];
 const DEFAULT_ADVANCED_METHODS = ['bunker', 'nostrconnect', 'nsec'];
 const DEFAULT_NOSTR_CONNECT_PERMS = ['sign_event', 'nip44_encrypt', 'nip44_decrypt'];
 function escapeHtml(str) {
@@ -254,12 +255,28 @@ async function startCameraQrScanner(input) {
 const METHOD_META = {
     nip07: { icon: '🌐', title: 'Browser extension', hint: 'bark, Alby, nos2x' },
     amber: { icon: '🤖', title: 'Sign in with Amber', hint: 'Android signer (NIP-55)' },
-    redirect: { icon: '🪪', title: 'Sign in with Signet', hint: 'Open Signet on this device' },
-    qr: { icon: '📱', title: 'Signet on another device', hint: 'Scan QR with your phone' },
+    'local-signet': { icon: '🪪', title: 'Local Signet', hint: 'Open Signet on this device' },
+    'remote-signet': { icon: '📱', title: 'Remote Signet', hint: 'Scan with Signet on another device' },
+    redirect: { icon: '🪪', title: 'Local Signet', hint: 'Open Signet on this device' },
+    qr: { icon: '📱', title: 'Remote Signet', hint: 'Scan with Signet on another device' },
     bunker: { icon: '🔑', title: 'Paste bunker URI', hint: 'For NIP-46 power users' },
     nostrconnect: { icon: '📡', title: 'Connect a Nostr signer', hint: 'Scan with nsec.app, Amber, Keychat...' },
     nsec: { icon: '⚠️', title: 'Paste private key', hint: 'In-memory only - risky, last resort' },
 };
+function pickerMethodKey(method) {
+    if (method === 'local-signet' || method === 'redirect')
+        return 'local-signet';
+    if (method === 'remote-signet' || method === 'qr')
+        return 'remote-signet';
+    return method;
+}
+function routePickerChoice(choice) {
+    if (choice === 'local-signet')
+        return 'redirect';
+    if (choice === 'remote-signet')
+        return 'qr';
+    return choice;
+}
 function isMethodAvailable(method) {
     if (method === 'nip07')
         return hasNip07();
@@ -277,9 +294,9 @@ function renderPicker(refs, opts) {
     return new Promise(resolve => {
         let advancedOpen = false;
         const availableMethods = opts.methods.filter(isMethodAvailable);
-        const advancedSet = new Set(opts.advancedMethods);
-        const primaryMethods = availableMethods.filter(method => !advancedSet.has(method));
-        const advancedMethods = availableMethods.filter(method => advancedSet.has(method));
+        const advancedSet = new Set(opts.advancedMethods.map(pickerMethodKey));
+        const primaryMethods = availableMethods.filter(method => !advancedSet.has(pickerMethodKey(method)));
+        const advancedMethods = availableMethods.filter(method => advancedSet.has(pickerMethodKey(method)));
         const attachChoiceHandlers = () => {
             refs.dialog.querySelectorAll('button[data-choice]').forEach(btn => {
                 btn.addEventListener('click', () => {
@@ -506,7 +523,7 @@ async function runRedirectFlow(refs, opts, flowOpts = {}) {
         });
     });
 }
-async function buildSessionFromRedirectFlowResult(refs, result, _aborted) {
+async function buildSessionFromRedirectFlowResult(refs, result, opts, _aborted) {
     // Default: auth-only ephemeral signer (identity proof, no live signing).
     let signer = new EphemeralSigner(result.pubkey, result.authEvent);
     let method = 'redirect';
@@ -517,7 +534,7 @@ async function buildSessionFromRedirectFlowResult(refs, result, _aborted) {
     // DeferredBunkerSigner makes them classify the session as non-signing before
     // the relay handshake can finish.
     if (result.bunkerUri) {
-        const clientSecretKey = loadOrCreatePersistentClientSk();
+        const clientSecretKey = await loadOrCreatePersistentClientSkFromStorage(opts.storage);
         const expected = result.pubkey;
         const status = refs.dialog.querySelector('#signet-login-status');
         if (status)
@@ -649,7 +666,10 @@ async function runBunkerFlow(refs, opts) {
             }
             connectBtn.disabled = true;
             try {
-                const signer = await createBunkerSigner({ uri, clientSecretKey: loadOrCreatePersistentClientSk() });
+                const signer = await createBunkerSigner({
+                    uri,
+                    clientSecretKey: await loadOrCreatePersistentClientSkFromStorage(opts.storage),
+                });
                 settle(signer);
             }
             catch (err) {
@@ -675,7 +695,7 @@ async function runNostrConnectFlow(refs, opts) {
     // Persistent client key so the advertised client pubkey is stable across
     // logins (bunkers auto-approve a bound client pubkey). The connect `secret`
     // stays fresh per handshake — it's a one-time challenge, not an identity.
-    const sk = loadOrCreatePersistentClientSk();
+    const sk = await loadOrCreatePersistentClientSkFromStorage(opts.storage);
     const clientPubkey = bytesToHex(schnorr.getPublicKey(sk));
     const secret = bytesToHex(schnorr.utils.randomPrivateKey()).slice(0, 32);
     const uri = buildNostrConnectUri({
@@ -803,20 +823,25 @@ async function runNsecFlow(refs, opts) {
 }
 function uniquePickerMethods(input, fallback) {
     const source = input ?? fallback;
-    const allowed = new Set(DEFAULT_PICKER_METHODS);
+    const allowed = new Set(ALL_PICKER_METHODS);
+    const seen = new Set();
     const out = [];
     for (const method of source) {
         if (!allowed.has(method))
             continue;
-        if (!out.includes(method))
-            out.push(method);
+        const key = pickerMethodKey(method);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(method);
     }
     return input === undefined && out.length === 0 ? [...fallback] : out;
 }
 function resolveMethodConfig(opts) {
     const methods = uniquePickerMethods(opts.methods, DEFAULT_PICKER_METHODS);
+    const methodKeys = new Set(methods.map(pickerMethodKey));
     const advancedMethods = uniquePickerMethods(opts.advancedMethods, DEFAULT_ADVANCED_METHODS)
-        .filter(method => methods.includes(method));
+        .filter(method => methodKeys.has(pickerMethodKey(method)));
     return { methods, advancedMethods };
 }
 function resolveRelayUrls(opts) {
@@ -849,6 +874,8 @@ function resolveOptions(opts) {
         result.preferredMethod = opts.preferredMethod;
     if (opts.redirectCallback !== undefined)
         result.redirectCallback = opts.redirectCallback;
+    if (opts.storage !== undefined)
+        result.storage = opts.storage;
     return result;
 }
 let modalQueue = Promise.resolve();
@@ -890,11 +917,12 @@ async function runLoginModal(opts) {
             const choice = resolved.preferredMethod
                 ? resolved.preferredMethod
                 : await Promise.race([renderPicker(refs, resolved), aborted]);
+            const routeChoice = choice === null ? null : routePickerChoice(choice);
             if (userAborted)
                 return null;
-            if (choice === null || choice === 'cancel')
+            if (routeChoice === null || routeChoice === 'cancel')
                 return null;
-            if (choice === 'nip07') {
+            if (routeChoice === 'nip07') {
                 const result = await Promise.race([runNip07Flow(refs, resolved), aborted]);
                 if (userAborted)
                     return null;
@@ -914,7 +942,7 @@ async function runLoginModal(opts) {
                     authEvent: result.authEvent,
                 };
             }
-            if (choice === 'redirect') {
+            if (routeChoice === 'redirect') {
                 // Same-device Signet in the modal must keep this app tab alive and keep
                 // the My Signet tab alive as the ongoing bunker. Use the relay-backed
                 // auth response path here; explicit `login({ mode: 'redirect' })`
@@ -927,7 +955,7 @@ async function runLoginModal(opts) {
                         return null;
                     continue;
                 }
-                const session = await buildSessionFromRedirectFlowResult(refs, result, aborted);
+                const session = await buildSessionFromRedirectFlowResult(refs, result, resolved, aborted);
                 if (userAborted)
                     return null;
                 if (!session) {
@@ -937,7 +965,7 @@ async function runLoginModal(opts) {
                 }
                 return session;
             }
-            if (choice === 'amber') {
+            if (routeChoice === 'amber') {
                 // Same-tab navigation to a `nostrsigner:` URL. Android dispatches
                 // it to Amber; the page comes back via callbackUrl with the signed
                 // event in `?event=`. Picked up on next boot by handleRedirectCallback.
@@ -946,10 +974,11 @@ async function runLoginModal(opts) {
                     challenge: resolved.challenge,
                     origin: resolved.origin,
                     ...(resolved.redirectCallback !== undefined ? { redirectCallback: resolved.redirectCallback } : {}),
+                    ...(resolved.storage !== undefined ? { storage: resolved.storage } : {}),
                 });
                 return null; // unreachable
             }
-            if (choice === 'qr') {
+            if (routeChoice === 'qr') {
                 const result = await Promise.race([runRedirectFlow(refs, resolved), aborted]);
                 if (userAborted)
                     return null;
@@ -958,7 +987,7 @@ async function runLoginModal(opts) {
                         return null;
                     continue;
                 }
-                const session = await buildSessionFromRedirectFlowResult(refs, result, aborted);
+                const session = await buildSessionFromRedirectFlowResult(refs, result, resolved, aborted);
                 if (userAborted)
                     return null;
                 if (!session) {
@@ -968,7 +997,7 @@ async function runLoginModal(opts) {
                 }
                 return session;
             }
-            if (choice === 'bunker') {
+            if (routeChoice === 'bunker') {
                 const signer = await Promise.race([runBunkerFlow(refs, resolved), aborted]);
                 if (userAborted)
                     return null;
@@ -994,7 +1023,7 @@ async function runLoginModal(opts) {
                     authEvent,
                 };
             }
-            if (choice === 'nostrconnect') {
+            if (routeChoice === 'nostrconnect') {
                 const signer = await Promise.race([runNostrConnectFlow(refs, resolved), aborted]);
                 if (userAborted)
                     return null;
@@ -1023,7 +1052,7 @@ async function runLoginModal(opts) {
                     authEvent,
                 };
             }
-            if (choice === 'nsec') {
+            if (routeChoice === 'nsec') {
                 const signer = await Promise.race([runNsecFlow(refs, resolved), aborted]);
                 if (userAborted)
                     return null;

package/dist/redirect.d.ts

@@ -26,7 +26,7 @@
  * logs a warning — server-side strict verification will fail until the
  * issuer is upgraded.
  */
-import type { SignetSession } from './types.js';
+import type { SignetStorage, SignetSession } from './types.js';
 import { DEFAULTS } from './types.js';
 /** Subset of resolved options used by the redirect path. */
 export interface RedirectStartOptions {
@@ -35,6 +35,7 @@ export interface RedirectStartOptions {
     origin: string;
     signetAppOrigin: string;
     redirectCallback?: string;
+    storage?: SignetStorage;
 }
 /**
  * Build the signet-app auth URL for redirect mode. Deliberately omits `relay`
@@ -74,22 +75,6 @@ export type ConsumeCallbackResult = {
     kind: 'invalid';
     reason: string;
 };
-/**
- * Detect and consume a redirect-back callback. Returns:
- *
- *   - { kind: 'session', session }  — round-trip valid; clears pending state
- *                                     and strips auth params from the URL
- *   - { kind: 'denied' }            — signet-app sent `error=denied`
- *   - { kind: 'no-callback' }       — no auth params in the URL; do nothing
- *   - { kind: 'invalid', reason }   — params present but failed validation
- *                                     (pending state mismatch, stale, hex
- *                                     malformed, …). Pending state is cleared
- *                                     in this case too — a stale or attacker-
- *                                     supplied URL shouldn't poison the next
- *                                     login attempt.
- *
- * Idempotent: calling it twice on the same loaded page returns 'no-callback'
- * the second time because the URL params have been stripped.
- */
 export declare function consumeCallback(): ConsumeCallbackResult;
+export declare function consumeCallbackFromStorage(storage?: SignetStorage): Promise<ConsumeCallbackResult>;
 export { DEFAULTS };

package/dist/redirect.js

@@ -27,7 +27,7 @@
  * issuer is upgraded.
  */
 import { DEFAULTS, PENDING_REDIRECT_TTL_MS } from './types.js';
-import { clearPendingRedirect, loadPendingRedirect, savePendingRedirect, } from './storage.js';
+import { clearPendingRedirect, clearPendingRedirectFromStorage, loadPendingRedirect, loadPendingRedirectFromStorage, savePendingRedirectToStorage, } from './storage.js';
 import { EphemeralSigner } from './signers.js';
 /** Hex regexes — kept local to avoid pulling in @noble for two patterns. */
 const HEX_64 = /^[0-9a-f]{64}$/i;
@@ -58,7 +58,7 @@ export function buildRedirectAuthUrl(opts) {
  * mode in non-browser code is a programming error, not something to silently
  * swallow.
  */
-export function startRedirect(opts) {
+export async function startRedirect(opts) {
     if (typeof window === 'undefined') {
         throw new Error('signet-login: redirect mode requires a browser environment');
     }
@@ -68,7 +68,7 @@ export function startRedirect(opts) {
         appName: opts.appName,
         createdAt: Date.now(),
     };
-    savePendingRedirect(pending);
+    await savePendingRedirectToStorage(pending, opts.storage);
     const url = buildRedirectAuthUrl(opts);
     // Use assignment (not replace) so the user can hit back to abort. The
     // pending record stays put; consumeCallback will GC it via the freshness
@@ -106,24 +106,7 @@ function cleanupCallbackUrl() {
         // history API blocked (file:// origin, sandboxed iframe, …) — leave URL alone
     }
 }
-/**
- * Detect and consume a redirect-back callback. Returns:
- *
- *   - { kind: 'session', session }  — round-trip valid; clears pending state
- *                                     and strips auth params from the URL
- *   - { kind: 'denied' }            — signet-app sent `error=denied`
- *   - { kind: 'no-callback' }       — no auth params in the URL; do nothing
- *   - { kind: 'invalid', reason }   — params present but failed validation
- *                                     (pending state mismatch, stale, hex
- *                                     malformed, …). Pending state is cleared
- *                                     in this case too — a stale or attacker-
- *                                     supplied URL shouldn't poison the next
- *                                     login attempt.
- *
- * Idempotent: calling it twice on the same loaded page returns 'no-callback'
- * the second time because the URL params have been stripped.
- */
-export function consumeCallback() {
+function consumeCallbackWithPending(pending, finalize) {
     if (typeof window === 'undefined')
         return { kind: 'no-callback' };
     const params = new URLSearchParams(window.location.search);
@@ -135,14 +118,6 @@ export function consumeCallback() {
     if (!error && !pubkey && !signature && !eventId) {
         return { kind: 'no-callback' };
     }
-    const pending = loadPendingRedirect();
-    // From here on we're handling a callback — pending state must always be
-    // cleared on exit so a stale record can't be reused.
-    const finalize = (result) => {
-        clearPendingRedirect();
-        cleanupCallbackUrl();
-        return result;
-    };
     if (error === 'denied') {
         return finalize({ kind: 'denied' });
     }
@@ -254,6 +229,24 @@ export function consumeCallback() {
     }
     return finalize(bunkerUri ? { kind: 'session', session, bunkerUri } : { kind: 'session', session });
 }
+export function consumeCallback() {
+    // From here on we're handling a callback — pending state must always be
+    // cleared on exit so a stale record can't be reused.
+    const finalize = (result) => {
+        clearPendingRedirect();
+        cleanupCallbackUrl();
+        return result;
+    };
+    return consumeCallbackWithPending(loadPendingRedirect(), finalize);
+}
+export async function consumeCallbackFromStorage(storage) {
+    const finalize = async (result) => {
+        await clearPendingRedirectFromStorage(storage);
+        cleanupCallbackUrl();
+        return result;
+    };
+    return await consumeCallbackWithPending(await loadPendingRedirectFromStorage(storage), finalize);
+}
 // Re-export DEFAULTS for tree-shaking-friendly callers that want to avoid
 // importing the full types module just for one constant.
 export { DEFAULTS };

package/dist/signet-login.d.ts

@@ -14,8 +14,8 @@
  * already there (so `signet-verify.iife.js` and `signet-login.iife.js` coexist
  * in either load order on the same page).
  */
-export type { NostrEvent, EventTemplate, LoginMethod, LoginPickerMethod, SignerCapabilities, SignetSigner, SignetAuthEvent, SignetSession, LoginOptions, RestoreOptions, } from './types.js';
-import type { SignetSigner, LoginOptions, RestoreOptions, SignetSession, SignetAuthEvent } from './types.js';
+export type { NostrEvent, EventTemplate, LoginMethod, LoginPickerMethod, SignerCapabilities, SignetSigner, SignetAuthEvent, SignetSession, LoginOptions, RestoreOptions, SignetStorage, } from './types.js';
+import type { SignetSigner, LoginOptions, RestoreOptions, SignetSession, SignetAuthEvent, SignetStorage } from './types.js';
 import { hasNip07, createNip07Signer, createBunkerSigner, createBunkerSignerFromNostrConnect, buildNostrConnectUri, createLocalSignerFromNsec, generateSecretKey, Nip07Signer, BunkerSignerImpl, LocalSigner } from './signers.js';
 import { type ConsumeAmberResult } from './amber.js';
 import { handleCallback as handlePopupCallback } from './callback.js';
@@ -34,6 +34,11 @@ export interface HandleRedirectCallbackOptions {
      * should set this true and reject auth-only returns at their boundary.
      */
     waitForBunker?: boolean;
+    /**
+     * Storage backend for pending redirect consumption and session persistence.
+     * Must match the backend passed to `login({ mode: 'redirect', storage })`.
+     */
+    storage?: SignetStorage;
 }
 export interface CreateLoginAuthEventOptions {
     /** Required. Bound into the auth event's `app` tag. */
@@ -43,6 +48,10 @@ export interface CreateLoginAuthEventOptions {
     /** Origin to bind into the proof. Defaults to `window.location.origin`. */
     origin?: string;
 }
+export interface LogoutOptions {
+    /** Storage backend to clear. Defaults to localStorage. */
+    storage?: SignetStorage;
+}
 /**
  * Show the login picker and resolve to a SignetSession on success, or null on
  * cancel / timeout.
@@ -117,4 +126,4 @@ export declare function handleRedirectCallback(options?: HandleRedirectCallbackO
 /**
  * Clear the stored session and close the active signer.
  */
-export declare function logout(currentSession?: SignetSession): Promise<void>;
+export declare function logout(currentSession?: SignetSession, opts?: LogoutOptions): Promise<void>;