signet-login 0.9.15 → 0.10.1

package/README.md

@@ -1,14 +1,19 @@
-# signet-login
+# Signet Access
 
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/TheCryptoDonkey?logo=githubsponsors&color=ea4aaa&label=Sponsor)](https://github.com/sponsors/TheCryptoDonkey)
 
-**Sign in with Signet** for Nostr-aware websites. One picker, three backends:
+Published as `signet-login`.
 
-- **Browser extension** (NIP-07 — bark, Alby, nos2x, Flamingo, …)
-- **Sign in with Signet** (cross-device QR via NIP-17 gift-wrap)
-- **Paste bunker URI** (NIP-46 remote signer — Heartwood, nsecBunker, Amber)
+**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:
 
-Returns a unified `SignetSigner` your code can use to sign Nostr events going forward.
+- **Sign in with Signet** on this device or by cross-device QR
+- **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
+- **Sign in with Amber** via Android NIP-55
+- **Paste private key** as an in-memory, advanced fallback only
+
+Returns a unified `SignetSigner` plus a signed kind-21236 auth proof your server can verify before granting privileges.
 
 ## Install
 
@@ -58,20 +63,41 @@ Show the picker, return a `SignetSession` on success or `null` on cancel/timeout
 
 ```ts
 interface LoginOptions {
-  appName: string;                                      // shown in modal
-  challenge?: string;                                   // 64 hex; auto if omitted
-  preferredMethod?: 'nip07' | 'redirect' | 'bunker';    // skip the picker
-  relayUrl?: string;                                    // default wss://relay.damus.io
-  theme?: 'light' | 'dark' | 'auto';                    // default 'auto'
-  timeout?: number;                                     // default 120_000ms; clamped to [5k, 600k]
-  signetAppOrigin?: string;                             // default https://mysignet.app
-  redirectCallback?: string;                            // for same-device redirect (future)
-  persist?: boolean;                                    // default true (localStorage)
+  appName: string;                              // shown in modal
+  challenge?: string;                           // 64 hex; auto if omitted
+  preferredMethod?: LoginPickerMethod;          // skip the picker
+  methods?: LoginPickerMethod[];                // picker methods, in order
+  advancedMethods?: LoginPickerMethod[];        // grouped behind Advanced; [] = flat list
+  relayUrl?: string;                            // default wss://relay.damus.io
+  relayUrls?: string[];                         // repeated relay= params for NostrConnect
+  nostrConnectPerms?: string[];                 // default sign_event + NIP-44
+  theme?: 'light' | 'dark' | 'auto';            // default 'auto'
+  timeout?: number;                             // default 120_000ms; clamped to [5k, 600k]
+  signetAppOrigin?: string;                     // default https://mysignet.app
+  redirectCallback?: string;                    // for same-device redirect / Amber return
+  mode?: 'relay' | 'redirect';                  // Signet delivery mode
+  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
+  | 'bunker'        // paste bunker://
+  | 'nostrconnect'  // show nostrconnect:// QR
+  | 'amber'         // Android NIP-55
+  | 'nsec';         // in-memory private key fallback
+
 interface SignetSession {
   pubkey: string;                  // hex
-  method: 'nip07' | 'redirect' | 'bunker';
+  method: 'nip07' | 'redirect' | 'bunker' | 'nsec' | 'amber';
   signer: SignetSigner;
   authEvent: SignetAuthEvent;      // signed kind-21236 challenge proof
   expiresAt?: number;
@@ -79,9 +105,91 @@ interface SignetSession {
 }
 ```
 
+By default, the picker shows ordinary user-facing methods first and groups `bunker`, `nostrconnect`, and `nsec` behind **Advanced**. Control the surface per app:
+
+```js
+await Signet.login({
+  appName: 'My Game',
+  methods: ['redirect', 'qr', 'nip07'],
+});
+
+await Signet.login({
+  appName: 'Power User Tool',
+  methods: ['nip07', 'bunker', 'nostrconnect', 'nsec'],
+  advancedMethods: [], // flat picker
+  relayUrls: ['wss://relay.nsec.app', 'wss://relay.damus.io'],
+});
+```
+
+When camera APIs are available, the bunker URI screen can scan `bunker://` QR codes directly. Paste remains the fallback.
+
+### Headless/custom UI
+
+Use the exported signer constructors and proof helpers when your app owns the UI:
+
+```ts
+import {
+  createBunkerSigner,
+  createLoginAuthEvent,
+  createSessionFromSigner,
+  createLocalSignerFromNsec,
+} from 'signet-login';
+
+const signer = await createBunkerSigner({
+  uri: bunkerUri,
+  timeoutMs: 30_000,
+});
+
+const session = await createSessionFromSigner(signer, {
+  appName: 'My App',
+  challenge: challengeFromServer,
+  origin: 'https://my-app.example',
+});
+
+await fetch('/api/login', {
+  method: 'POST',
+  body: JSON.stringify({ authEvent: session.authEvent }),
+});
+```
+
+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();
@@ -90,7 +198,7 @@ if (session?.signer.capabilities.canSignEvents) {
 }
 ```
 
-### `Signet.logout(currentSession?)`
+### `Signet.logout(currentSession?, opts?)`
 
 Clear stored session and close the active signer.
 
@@ -98,14 +206,14 @@ Clear stored session and close the active signer.
 
 Run on your callback page when using the same-device redirect flow. Parses URL params and posts them to `window.opener` (if popup-opened), then closes the popup.
 
-## The three signers
+## Signers and capabilities
 
-All three implement `SignetSigner`:
+All session signers implement `SignetSigner`:
 
 ```ts
 interface SignetSigner {
   readonly pubkey: string;
-  readonly method: 'nip07' | 'redirect' | 'bunker';
+  readonly method: 'nip07' | 'redirect' | 'bunker' | 'nsec' | 'amber';
   readonly capabilities: { canSignEvents: boolean; hasNip44: boolean };
   signEvent(template: EventTemplate): Promise<NostrEvent>;
   nip44?: { encrypt, decrypt };
@@ -117,9 +225,10 @@ interface SignetSigner {
 |---|---|---|
 | `Nip07Signer` | true | `window.nostr` (any NIP-07 extension) |
 | `BunkerSignerImpl` | true | `nostr-tools` BunkerSigner over NIP-46 relay |
-| `EphemeralSigner` | **false** | Auth-only — redirect returned only `authEvent` |
+| `LocalSigner` | true | In-memory nsec fallback; never persisted |
+| `EphemeralSigner` | **false** | Auth-only Signet redirect / QR / Amber callback |
 
-`EphemeralSigner` exists because the v0.1 redirect flow returns a single signed challenge but no ongoing-signing channel. Use `signer.capabilities.canSignEvents` to gate UI:
+`EphemeralSigner` exists because some redirect-style flows return a signed challenge but no ongoing signing channel. Use `signer.capabilities.canSignEvents` to gate UI:
 
 ```js
 if (session.signer.capabilities.canSignEvents) {
@@ -129,7 +238,7 @@ if (session.signer.capabilities.canSignEvents) {
 }
 ```
 
-A future Option-B upgrade to signet-app will spawn a session-bunker per origin during the redirect approval, at which point redirect sessions will be full signers transparently. The SDK API does not change.
+When Signet or a signer app returns a `bunker://` handoff, the SDK upgrades the auth-only proof into a live `BunkerSignerImpl` if the handoff connects and matches the authenticated pubkey.
 
 ## Server-side verification
 
@@ -156,12 +265,12 @@ 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 |
 |---|---|
 | `signet:login.pubkey` | Authenticated pubkey |
-| `signet:login.method` | `nip07` / `redirect` / `bunker` |
+| `signet:login.method` | `nip07` / `redirect` / `bunker` / `amber` |
 | `signet:login.authEvent` | Serialised kind-21236 auth event |
 | `signet:login.bunkerUri` | Bunker URI for reconnect (bunker only) |
 | `signet:login.bunkerClientSk` | Client secret key hex (bunker only) |
@@ -190,11 +299,11 @@ Each SDK manages its own slice of `window.Signet` and `localStorage` namespaces.
 
 ## Bundle size
 
-Approx **48.5 KB gzipped** (135 KB unminified). The bulk is `nostr-tools` `BunkerSigner` for NIP-46 + `signet-verify` for the cross-device QR primitive. A future split-bundle could lazy-load the bunker path to halve the initial size.
+The ESM entry is approx **5.9 KB gzipped** before bundling dependencies. The standalone IIFE is approx **114.7 KB gzipped** because it includes NIP-46, Signet QR/relay support, and camera QR decoding. A future split-bundle could lazy-load advanced signer paths for smaller first-load pages.
 
 ## 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
 
@@ -207,9 +316,10 @@ npm test            # vitest in jsdom
 
 Examples in `examples/`:
 - `basic.html` — full demo with login / sign / logout / restore
+- `headless.html` — custom UI demo using signer constructors and proof helpers
 - `callback.html` — redirect-back receiver page
 
-Build the IIFE bundle first, then serve the repo root with any static server and open `examples/basic.html`.
+Build the IIFE bundle first, then serve the repo root with any static server and open `examples/basic.html` or `examples/headless.html`.
 
 ## Out of scope
 

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);
+}