signet-login 0.1.0

package/dist/redirect.js

@@ -0,0 +1,226 @@
+/**
+ * Same-tab redirect flow for "Sign in with Signet".
+ *
+ * Two halves:
+ *
+ *   1. `startRedirect()` — called from `Signet.login({ mode: 'redirect' })`.
+ *      Persists pending state to localStorage, builds the signet-app auth URL
+ *      WITHOUT relay/sessionPubkey (so signet-app falls into its
+ *      `window.location.href = callbackUrl` path), and navigates the current
+ *      tab. The caller's promise never resolves in this tab — the page is
+ *      gone.
+ *
+ *   2. `consumeCallback()` — called from `Signet.handleCallback()` on boot.
+ *      Detects auth params in `window.location.search`, validates them
+ *      against the persisted pending state, reconstructs the kind-21236 auth
+ *      event, persists the session via the existing storage layer, strips
+ *      the auth params from the URL, and returns a `SignetSession`.
+ *
+ * Verification note: the reconstructed auth event has a signature that was
+ * produced over the original `created_at` chosen by signet-app at sign time.
+ * To rebuild the event hash exactly, signet-app must emit `t` (unix seconds)
+ * alongside pubkey/signature/eventId in the redirect URL — see the
+ * coordinated change in signet-protocol's `buildAuthCallbackUrl`. When `t`
+ * is present, the reconstructed event passes signature verification. When
+ * absent (older signet-app deployments), the SDK falls back to "now" and
+ * logs a warning — server-side strict verification will fail until the
+ * issuer is upgraded.
+ */
+import { DEFAULTS, PENDING_REDIRECT_TTL_MS } from './types.js';
+import { clearPendingRedirect, loadPendingRedirect, savePendingRedirect, } 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;
+const HEX_128 = /^[0-9a-f]{128}$/i;
+/**
+ * Build the signet-app auth URL for redirect mode. Deliberately omits `relay`
+ * and `sessionPubkey` so signet-app's `isRelayMode` check (App.tsx) returns
+ * false and the redirect path runs.
+ */
+export function buildRedirectAuthUrl(opts) {
+    const callback = opts.redirectCallback ?? `${opts.origin}/`;
+    const params = new URLSearchParams({
+        auth: '1',
+        challenge: opts.challenge,
+        origin: opts.origin,
+        name: opts.appName,
+        callback,
+        t: String(Math.floor(Date.now() / 1000)),
+    });
+    return `${opts.signetAppOrigin}/?${params.toString()}`;
+}
+/**
+ * Persist pending state and navigate. Resolves to a never-settling promise on
+ * success (the page navigates before it can resolve) so callers using
+ * `await Signet.login()` see consistent behaviour with the relay path.
+ *
+ * Throws synchronously if the environment lacks `window` — calling redirect
+ * mode in non-browser code is a programming error, not something to silently
+ * swallow.
+ */
+export function startRedirect(opts) {
+    if (typeof window === 'undefined') {
+        throw new Error('signet-login: redirect mode requires a browser environment');
+    }
+    const pending = {
+        challenge: opts.challenge,
+        origin: opts.origin,
+        appName: opts.appName,
+        createdAt: Date.now(),
+    };
+    savePendingRedirect(pending);
+    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
+    // window if they never come back.
+    window.location.href = url;
+    // Page is navigating — return a promise that never resolves. Any code
+    // running after `await Signet.login()` won't see a value, but the tab is
+    // gone before that matters.
+    return new Promise(() => { });
+}
+/**
+ * Strip auth-callback params from the current URL via `history.replaceState`,
+ * preserving anything else the consumer has on the URL. No-op when there's
+ * no auth-callback param present.
+ */
+function cleanupCallbackUrl() {
+    if (typeof window === 'undefined')
+        return;
+    const url = new URL(window.location.href);
+    const removed = ['pubkey', 'npub', 'signature', 'eventId', 'error', 'warnings', 'fromNP', 'display_name', 't'];
+    let touched = false;
+    for (const key of removed) {
+        if (url.searchParams.has(key)) {
+            url.searchParams.delete(key);
+            touched = true;
+        }
+    }
+    if (!touched)
+        return;
+    const newHref = url.pathname + (url.search ? url.search : '') + url.hash;
+    try {
+        window.history.replaceState(window.history.state, document.title, newHref);
+    }
+    catch {
+        // 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() {
+    if (typeof window === 'undefined')
+        return { kind: 'no-callback' };
+    const params = new URLSearchParams(window.location.search);
+    const error = params.get('error');
+    const pubkey = params.get('pubkey');
+    const signature = params.get('signature');
+    const eventId = params.get('eventId');
+    // No callback at all — early return without touching pending state.
+    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' });
+    }
+    if (!pending) {
+        return finalize({ kind: 'invalid', reason: 'no-pending-state' });
+    }
+    // Origin sanity — protects against a callback URL fired at a different app
+    // (e.g. attacker emails a crafted link). Pending was issued by `origin`
+    // matching the calling page; on return the page must still be on that origin.
+    if (pending.origin !== window.location.origin) {
+        return finalize({ kind: 'invalid', reason: 'origin-mismatch' });
+    }
+    // Freshness — a callback hours after the user clicked Sign In is almost
+    // certainly a stale tab restore. Reject rather than reconstructing an
+    // expired auth event.
+    if (Date.now() - pending.createdAt > PENDING_REDIRECT_TTL_MS) {
+        return finalize({ kind: 'invalid', reason: 'pending-stale' });
+    }
+    if (!pubkey || !HEX_64.test(pubkey)) {
+        return finalize({ kind: 'invalid', reason: 'pubkey-malformed' });
+    }
+    if (!signature || !HEX_128.test(signature)) {
+        return finalize({ kind: 'invalid', reason: 'signature-malformed' });
+    }
+    if (!eventId || !HEX_64.test(eventId)) {
+        return finalize({ kind: 'invalid', reason: 'eventId-malformed' });
+    }
+    // `t` (created_at unix seconds) — emitted by signet-app for exact event
+    // reconstruction. Fall back to "now" with a warning when absent (older
+    // signet-app deployments). See module-level note.
+    let createdAt;
+    const tRaw = params.get('t');
+    if (tRaw && /^\d+$/.test(tRaw)) {
+        const t = Number(tRaw);
+        if (!Number.isFinite(t))
+            return finalize({ kind: 'invalid', reason: 't-malformed' });
+        createdAt = t;
+    }
+    else {
+        createdAt = Math.floor(Date.now() / 1000);
+        // Surface this in dev tools so consumers can spot upstream signet-app
+        // versions that don't emit `t`. Doesn't fail the flow because the
+        // session is still usable client-side; only strict server-side
+        // verification will reject it.
+        if (typeof console !== 'undefined') {
+            console.warn('signet-login: redirect callback missing `t` param — auth event ' +
+                'created_at approximated. Server-side verification may reject. ' +
+                'Upgrade signet-app to emit `t` in the redirect URL.');
+        }
+    }
+    const lowerPubkey = pubkey.toLowerCase();
+    const lowerSig = signature.toLowerCase();
+    const lowerEventId = eventId.toLowerCase();
+    const authEvent = {
+        id: lowerEventId,
+        pubkey: lowerPubkey,
+        kind: 21236,
+        created_at: createdAt,
+        tags: [
+            ['challenge', pending.challenge],
+            ['origin', pending.origin],
+            ['app', pending.appName],
+        ],
+        content: '',
+        sig: lowerSig,
+    };
+    const displayName = params.get('display_name') || undefined;
+    const ephemeral = new EphemeralSigner(lowerPubkey, authEvent);
+    const session = {
+        pubkey: lowerPubkey,
+        method: 'redirect',
+        signer: ephemeral,
+        authEvent,
+    };
+    if (displayName)
+        session.displayName = displayName;
+    return finalize({ kind: 'session', session });
+}
+// 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/signers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Three signer implementations behind one interface.
+ *
+ *   Nip07Signer       — wraps window.nostr (bark, Alby, nos2x, Flamingo, …)
+ *   BunkerSignerImpl  — wraps nostr-tools BunkerSigner (NIP-46 over relay)
+ *   EphemeralSigner   — auth-only fallback when only the redirect signature is available
+ */
+import type { EventTemplate, NostrEvent, SignetSigner, SignerCapabilities, SignetAuthEvent } from './types.js';
+import { BunkerSigner } from 'nostr-tools/nip46';
+/** The shape of `window.nostr` exposed by NIP-07 extensions. */
+interface Nip07Provider {
+    getPublicKey(): Promise<string>;
+    signEvent(event: EventTemplate): Promise<NostrEvent>;
+    nip44?: {
+        encrypt(peerPubkey: string, plaintext: string): Promise<string>;
+        decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
+    };
+}
+declare global {
+    interface Window {
+        nostr?: Nip07Provider;
+    }
+}
+/** Returns true if a NIP-07 extension is present on the page. */
+export declare function hasNip07(): boolean;
+export declare class Nip07Signer implements SignetSigner {
+    readonly pubkey: string;
+    private readonly provider;
+    readonly method: "nip07";
+    readonly capabilities: SignerCapabilities;
+    readonly nip44?: SignetSigner['nip44'];
+    constructor(pubkey: string, provider: Nip07Provider);
+    signEvent(template: EventTemplate): Promise<NostrEvent>;
+    close(): Promise<void>;
+}
+/** Connects to the page's NIP-07 provider and returns a Nip07Signer. */
+export declare function createNip07Signer(): Promise<Nip07Signer>;
+/** Wraps nostr-tools' BunkerSigner with our SignetSigner interface. */
+export declare class BunkerSignerImpl implements SignetSigner {
+    readonly pubkey: string;
+    private readonly bunker;
+    /** Original bunker URI — kept for persistence/reconnect. */
+    readonly bunkerUri: string;
+    /** The 32-byte client secret key used in this session — kept for reconnect. */
+    readonly clientSecretKey: Uint8Array;
+    readonly method: "bunker";
+    readonly capabilities: SignerCapabilities;
+    readonly nip44: SignetSigner['nip44'];
+    constructor(pubkey: string, bunker: BunkerSigner, 
+    /** Original bunker URI — kept for persistence/reconnect. */
+    bunkerUri: string, 
+    /** The 32-byte client secret key used in this session — kept for reconnect. */
+    clientSecretKey: Uint8Array);
+    signEvent(template: EventTemplate): Promise<NostrEvent>;
+    close(): Promise<void>;
+}
+/**
+ * Connect a bunker session from a `bunker://` or `nostr+connect://` URI (or a
+ * NIP-05 identifier). Generates a fresh client secret key for the session.
+ */
+export declare function createBunkerSigner(input: {
+    uri: string;
+    clientSecretKey?: Uint8Array;
+    onauth?: (url: string) => void;
+}): Promise<BunkerSignerImpl>;
+/** Generate a 32-byte secret key. */
+export declare function generateSecretKey(): Uint8Array;
+/**
+ * Auth-only signer returned by the redirect/QR flow before Option B is built.
+ * Holds the signed challenge but cannot sign further events.
+ */
+export declare class EphemeralSigner implements SignetSigner {
+    readonly pubkey: string;
+    readonly authEvent: SignetAuthEvent;
+    readonly method: "redirect";
+    readonly capabilities: SignerCapabilities;
+    constructor(pubkey: string, authEvent: SignetAuthEvent);
+    signEvent(_template: EventTemplate): Promise<NostrEvent>;
+    close(): Promise<void>;
+}
+export {};

package/dist/signers.js

@@ -0,0 +1,128 @@
+/**
+ * Three signer implementations behind one interface.
+ *
+ *   Nip07Signer       — wraps window.nostr (bark, Alby, nos2x, Flamingo, …)
+ *   BunkerSignerImpl  — wraps nostr-tools BunkerSigner (NIP-46 over relay)
+ *   EphemeralSigner   — auth-only fallback when only the redirect signature is available
+ */
+import { BunkerSigner, parseBunkerInput } from 'nostr-tools/nip46';
+/** Returns true if a NIP-07 extension is present on the page. */
+export function hasNip07() {
+    return typeof window !== 'undefined' && !!window.nostr && typeof window.nostr.signEvent === 'function';
+}
+export class Nip07Signer {
+    constructor(pubkey, provider) {
+        this.pubkey = pubkey;
+        this.provider = provider;
+        this.method = 'nip07';
+        this.capabilities = { canSignEvents: true, hasNip44: !!provider.nip44 };
+        if (provider.nip44) {
+            this.nip44 = {
+                encrypt: (peer, pt) => provider.nip44.encrypt(peer, pt),
+                decrypt: (peer, ct) => provider.nip44.decrypt(peer, ct),
+            };
+        }
+    }
+    async signEvent(template) {
+        return this.provider.signEvent(template);
+    }
+    async close() {
+        // NIP-07 extensions have no concept of disconnect — nothing to do.
+    }
+}
+/** Connects to the page's NIP-07 provider and returns a Nip07Signer. */
+export async function createNip07Signer() {
+    if (!hasNip07())
+        throw new Error('no-nip07-provider');
+    const provider = window.nostr;
+    const pubkey = await provider.getPublicKey();
+    if (!/^[0-9a-f]{64}$/i.test(pubkey))
+        throw new Error('invalid-pubkey-from-nip07');
+    return new Nip07Signer(pubkey.toLowerCase(), provider);
+}
+// ── NIP-46 bunker ─────────────────────────────────────────────────────────────
+/** Wraps nostr-tools' BunkerSigner with our SignetSigner interface. */
+export class BunkerSignerImpl {
+    constructor(pubkey, bunker, 
+    /** Original bunker URI — kept for persistence/reconnect. */
+    bunkerUri, 
+    /** The 32-byte client secret key used in this session — kept for reconnect. */
+    clientSecretKey) {
+        this.pubkey = pubkey;
+        this.bunker = bunker;
+        this.bunkerUri = bunkerUri;
+        this.clientSecretKey = clientSecretKey;
+        this.method = 'bunker';
+        this.capabilities = { canSignEvents: true, hasNip44: true };
+        this.nip44 = {
+            encrypt: (peer, pt) => bunker.nip44Encrypt(peer, pt),
+            decrypt: (peer, ct) => bunker.nip44Decrypt(peer, ct),
+        };
+    }
+    async signEvent(template) {
+        // BunkerSigner.signEvent expects EventTemplate with required created_at + tags.
+        // Strip any pubkey field, fill in defaults if omitted.
+        const { pubkey: _omit, ...rest } = template;
+        void _omit;
+        const filled = {
+            kind: rest.kind,
+            content: rest.content,
+            created_at: rest.created_at ?? Math.floor(Date.now() / 1000),
+            tags: rest.tags ?? [],
+        };
+        const verified = await this.bunker.signEvent(filled);
+        return verified;
+    }
+    async close() {
+        await this.bunker.close();
+    }
+}
+/**
+ * Connect a bunker session from a `bunker://` or `nostr+connect://` URI (or a
+ * NIP-05 identifier). Generates a fresh client secret key for the session.
+ */
+export async function createBunkerSigner(input) {
+    const trimmed = input.uri.trim();
+    if (!trimmed)
+        throw new Error('empty-bunker-uri');
+    const pointer = await parseBunkerInput(trimmed);
+    if (!pointer)
+        throw new Error('invalid-bunker-uri');
+    const sk = input.clientSecretKey ?? generateSecretKey();
+    if (sk.length !== 32)
+        throw new Error('invalid-client-secret-key');
+    const bunker = BunkerSigner.fromBunker(sk, pointer, { onauth: input.onauth });
+    await bunker.connect();
+    const pubkey = await bunker.getPublicKey();
+    if (!/^[0-9a-f]{64}$/i.test(pubkey)) {
+        await bunker.close().catch(() => { });
+        throw new Error('invalid-pubkey-from-bunker');
+    }
+    return new BunkerSignerImpl(pubkey.toLowerCase(), bunker, trimmed, sk);
+}
+/** Generate a 32-byte secret key. */
+export function generateSecretKey() {
+    const sk = new Uint8Array(32);
+    crypto.getRandomValues(sk);
+    return sk;
+}
+// ── Ephemeral (redirect-only) ─────────────────────────────────────────────────
+/**
+ * Auth-only signer returned by the redirect/QR flow before Option B is built.
+ * Holds the signed challenge but cannot sign further events.
+ */
+export class EphemeralSigner {
+    constructor(pubkey, authEvent) {
+        this.pubkey = pubkey;
+        this.authEvent = authEvent;
+        this.method = 'redirect';
+        this.capabilities = { canSignEvents: false, hasNip44: false };
+    }
+    async signEvent(_template) {
+        throw new Error('signer-auth-only: this session was established via redirect and cannot sign new events. ' +
+            'Install a NIP-07 extension (bark, Alby) or paste a bunker URI to upgrade.');
+    }
+    async close() {
+        // nothing to close
+    }
+}

package/dist/signet-login.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Signet Login SDK — Sign in with Signet for Nostr-aware websites.
+ *
+ * ESM / bundler usage:
+ *   import { login, restoreSession, logout } from 'signet-login';
+ *
+ * Script-tag / IIFE usage (additively extends `window.Signet`):
+ *   <script src="https://cdn.signet.forgesworn.dev/signet-login.iife.js"></script>
+ *   <script>
+ *     const session = await Signet.login({ appName: 'Asteroid Sats' });
+ *   </script>
+ *
+ * The IIFE bundle does NOT overwrite `window.Signet` — it augments whatever is
+ * 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, SignerCapabilities, SignetSigner, SignetAuthEvent, SignetSession, LoginOptions, RestoreOptions, } from './types.js';
+import type { LoginOptions, RestoreOptions, SignetSession } from './types.js';
+import { handleCallback as handlePopupCallback } from './callback.js';
+import type { ConsumeCallbackResult } from './redirect.js';
+export type { CallbackResult } from './callback.js';
+export type { ConsumeCallbackResult } from './redirect.js';
+/**
+ * Show the login picker and resolve to a SignetSession on success, or null on
+ * cancel / timeout.
+ *
+ * When `mode: 'redirect'` is set, the picker is skipped entirely — the current
+ * tab navigates to signet-app and this promise NEVER resolves in this tab.
+ * Callers should treat the returned promise as "fire and forget" in that case
+ * and call `Signet.handleCallback()` on the next page load to receive the
+ * session. The other login methods (NIP-07, bunker) don't use redirect at all
+ * and are unaffected by this option.
+ */
+export declare function login(opts: LoginOptions): Promise<SignetSession | null>;
+/**
+ * Try to restore a session from localStorage. Returns null if no session is
+ * stored or it's malformed/expired.
+ *
+ * For bunker sessions, attempts to reconnect using the stored URI + client SK.
+ * If the bunker is unreachable, returns null and clears the stored session.
+ */
+export declare function restoreSession(opts?: RestoreOptions): Promise<SignetSession | null>;
+/**
+ * Popup-style callback receiver. Use on the page that signet-app redirects
+ * a popup to. Parses URL params and posts them to `window.opener`, then
+ * closes the popup. Returns the raw params for non-popup contexts.
+ *
+ * For the same-tab redirect flow (`mode: 'redirect'` on `login()`), use
+ * `Signet.handleRedirectCallback()` instead — that one validates against the
+ * persisted pending state and returns a fully-formed `SignetSession`.
+ */
+export declare const handleCallback: typeof handlePopupCallback;
+/**
+ * Same-tab redirect callback receiver. Call once on app boot, before
+ * `restoreSession()`, to consume an incoming `?pubkey&signature&eventId`
+ * payload from signet-app.
+ *
+ * Behaviour:
+ *
+ *   - `'session'`: validates the round-trip against the pending state saved
+ *     by `login({ mode: 'redirect' })`, builds and persists a SignetSession
+ *     (so `restoreSession()` finds it next time), and strips the auth params
+ *     from the URL via `history.replaceState`. The returned session uses an
+ *     `EphemeralSigner` — `signer.capabilities.canSignEvents` is false. Pair
+ *     with NIP-07 / bunker if you need ongoing signing.
+ *
+ *   - `'denied'`: signet-app reported the user rejected the request.
+ *
+ *   - `'no-callback'`: no auth params on the URL — the typical case on most
+ *     page loads. Idempotent: a second call after success also returns this.
+ *
+ *   - `'invalid'`: params present but failed validation. `reason` is a
+ *     machine-readable token (`origin-mismatch`, `pending-stale`,
+ *     `pubkey-malformed`, …). Pending state is cleared either way so a stale
+ *     URL can't poison the next attempt.
+ *
+ * The returned shape is intentionally tagged so consumers can distinguish
+ * "user denied" from "no callback" without inspecting null. Persistence on
+ * success uses the same storage layer as relay-mode sessions, so downstream
+ * code that consumes `restoreSession()` doesn't need to care which path
+ * authenticated the user.
+ */
+export declare function handleRedirectCallback(): Promise<ConsumeCallbackResult>;
+/**
+ * Clear the stored session and close the active signer.
+ */
+export declare function logout(currentSession?: SignetSession): Promise<void>;