signet-login 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,234 @@
+# signet-login
+
+[![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:
+
+- **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)
+
+Returns a unified `SignetSigner` your code can use to sign Nostr events going forward.
+
+## Install
+
+```bash
+npm install signet-login
+```
+
+Or drop it in via CDN:
+
+```html
+<script src="https://cdn.signet.forgesworn.dev/signet-login.iife.js"></script>
+```
+
+The IIFE bundle additively extends `window.Signet` — it coexists with `signet-verify` on the same page in either load order.
+
+## Quick start
+
+```html
+<button id="login">Sign in</button>
+
+<script src="https://cdn.signet.forgesworn.dev/signet-login.iife.js"></script>
+<script>
+  document.getElementById('login').addEventListener('click', async () => {
+    const session = await Signet.login({ appName: 'My Game' });
+    if (!session) return;  // user cancelled
+
+    // Sign a Nostr event with the user's chosen signer:
+    const signed = await session.signer.signEvent({
+      kind: 30762,
+      content: '',
+      tags: [
+        ['game', 'my-game'],
+        ['score', '12350'],
+        ['p', session.pubkey],
+      ],
+    });
+    console.log('signed:', signed);
+  });
+</script>
+```
+
+## API
+
+### `Signet.login(options)`
+
+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)
+}
+
+interface SignetSession {
+  pubkey: string;                  // hex
+  method: 'nip07' | 'redirect' | 'bunker';
+  signer: SignetSigner;
+  authEvent: SignetAuthEvent;      // signed kind-21236 challenge proof
+  expiresAt?: number;
+  displayName?: string;
+}
+```
+
+### `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.
+
+```js
+const session = await Signet.restoreSession();
+if (session?.signer.capabilities.canSignEvents) {
+  // we have ongoing signing capability
+}
+```
+
+### `Signet.logout(currentSession?)`
+
+Clear stored session and close the active signer.
+
+### `Signet.handleCallback(opts?)`
+
+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
+
+All three implement `SignetSigner`:
+
+```ts
+interface SignetSigner {
+  readonly pubkey: string;
+  readonly method: 'nip07' | 'redirect' | 'bunker';
+  readonly capabilities: { canSignEvents: boolean; hasNip44: boolean };
+  signEvent(template: EventTemplate): Promise<NostrEvent>;
+  nip44?: { encrypt, decrypt };
+  close(): Promise<void>;
+}
+```
+
+| Signer | `canSignEvents` | Source |
+|---|---|---|
+| `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` |
+
+`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:
+
+```js
+if (session.signer.capabilities.canSignEvents) {
+  enableLeaderboardPublish();
+} else {
+  promptUserToInstallExtensionOrPasteBunkerURI();
+}
+```
+
+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.
+
+## Server-side verification
+
+The client sends `session.authEvent` to your server. Verify it before granting any privileges or paying out sats:
+
+```ts
+import { verifyLogin } from 'signet-login/verify';
+
+const result = verifyLogin(authEvent, {
+  expectedChallenge: theChallengeYouIssued,
+  expectedOrigin: 'https://my-game.example',
+  expectedAppName: 'My Game',          // optional
+  maxAgeSeconds: 300,                  // default 300
+});
+
+if (result.valid) {
+  // result.pubkey is the authenticated user
+} else {
+  // result.error: 'invalid-signature' | 'challenge-mismatch' | 'too-old' | …
+}
+```
+
+The verifier checks: schnorr signature, canonical event ID, kind=21236, challenge tag match, origin tag match, optional app tag match, freshness window (5-min default + 60s skew tolerance).
+
+## Storage
+
+Session data is stored in localStorage under `signet:login.*`:
+
+| Key | Purpose |
+|---|---|
+| `signet:login.pubkey` | Authenticated pubkey |
+| `signet:login.method` | `nip07` / `redirect` / `bunker` |
+| `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) |
+| `signet:login.expiresAt` | Optional expiry |
+| `signet:login.displayName` | Optional persona handle |
+
+Storage namespace is `signet:login.*` so it doesn't collide with `signet:verify.*`. `Signet.logout()` clears all login keys without touching other Signet SDKs.
+
+## Coexistence with signet-verify
+
+Both SDKs attach to `window.Signet` additively — load order doesn't matter:
+
+```html
+<script src=".../signet-verify.iife.js"></script>
+<script src=".../signet-login.iife.js"></script>
+
+<script>
+  // age verification
+  const ageResult = await Signet.verifyAge('18+');
+  // login
+  const session = await Signet.login({ appName: 'My App' });
+</script>
+```
+
+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.
+
+## Browser support
+
+ES2020 baseline. Tested on modern Chrome / Firefox / Safari. Requires `localStorage`, `crypto.subtle`, `WebSocket`, and the native `<dialog>` element.
+
+## Development
+
+```bash
+npm install
+npm run build       # dist/signet-login.js (ESM) + dist/signet-login.iife.js (browser)
+npm run typecheck
+npm test            # vitest in jsdom
+```
+
+Examples in `examples/`:
+- `basic.html` — full demo with login / sign / logout / restore
+- `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`.
+
+## Out of scope
+
+| Excluded | Where it lives |
+|---|---|
+| Age verification | `signet-verify` |
+| Per-game persona derivation | Heartwood RPC (reserved scope) |
+| Sign-time policy clauses | Reserved (G34 NLnet Jun) |
+| Generating bunker URIs | Heartwood / bark |
+| Lightning, payments | Out of scope |
+
+## License
+
+MIT
+
+## Related
+
+- [signet](https://github.com/forgesworn/signet) — protocol, specs, docs
+- [signet-protocol](https://www.npmjs.com/package/signet-protocol) — npm primitives
+- [signet-verify](https://github.com/forgesworn/signet-verify) — age verification + cross-device auth primitives
+- [bark](https://github.com/forgesworn/bark) — NIP-07 browser extension that signs via NIP-46 to Heartwood
+- [Heartwood](https://github.com/forgesworn/heartwood) — self-hosted signing appliance

package/dist/callback.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Callback-page helper.
+ *
+ * This is for consumers who want to support same-device redirect (signet-app
+ * redirects back to their callback page after signing). The cross-device QR
+ * path used by `Signet.login()` does NOT need this — it returns directly via
+ * a NIP-17 gift-wrapped relay event.
+ *
+ * v0.1 limitation: full same-device redirect support requires reconstruction
+ * of the signed kind-21236 event from URL params. signet-app's exact redirect-
+ * back parameter shape will determine this implementation. Until that's pinned
+ * down, this helper just relays the raw URL params back to the opener via
+ * postMessage and lets the consumer decide what to do.
+ */
+export interface CallbackResult {
+    /** Raw URL parameters from the redirect-back. */
+    params: Record<string, string>;
+    /** True if this page was opened as a popup (window.opener present). */
+    isPopup: boolean;
+}
+/**
+ * Parse the current page's URL parameters and post them to the opener (if any).
+ * Optionally close the popup.
+ */
+export declare function handleCallback(options?: {
+    closeAfterPost?: boolean;
+}): CallbackResult;

package/dist/callback.js

@@ -0,0 +1,46 @@
+/**
+ * Callback-page helper.
+ *
+ * This is for consumers who want to support same-device redirect (signet-app
+ * redirects back to their callback page after signing). The cross-device QR
+ * path used by `Signet.login()` does NOT need this — it returns directly via
+ * a NIP-17 gift-wrapped relay event.
+ *
+ * v0.1 limitation: full same-device redirect support requires reconstruction
+ * of the signed kind-21236 event from URL params. signet-app's exact redirect-
+ * back parameter shape will determine this implementation. Until that's pinned
+ * down, this helper just relays the raw URL params back to the opener via
+ * postMessage and lets the consumer decide what to do.
+ */
+/**
+ * Parse the current page's URL parameters and post them to the opener (if any).
+ * Optionally close the popup.
+ */
+export function handleCallback(options) {
+    const params = {};
+    if (typeof window !== 'undefined') {
+        const search = new URLSearchParams(window.location.search);
+        search.forEach((value, key) => {
+            params[key] = value;
+        });
+    }
+    const isPopup = typeof window !== 'undefined' && !!window.opener && window.opener !== window;
+    if (isPopup) {
+        try {
+            window.opener.postMessage({ type: 'signet-login-callback', params }, 
+            // Restrict target origin to opener's origin if known; fall back to '*' so
+            // cross-origin popups still deliver. Consumers must validate origin.
+            '*');
+        }
+        catch {
+            // postMessage failed — ignore
+        }
+        if (options?.closeAfterPost ?? true) {
+            try {
+                window.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return { params, isPopup };
+}

package/dist/modal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The login modal — picker → method-specific UI → resolved session.
+ *
+ * Mirrors signet-verify's <dialog>-based pattern: native focus trap,
+ * top-layer placement, theme-aware colours, no third-party UI deps.
+ */
+import type { LoginOptions, SignetSession } from './types.js';
+/**
+ * Entry point — show the modal, route to the chosen method, return a session.
+ *
+ * Returns null when the user cancels or the flow times out.
+ */
+export declare function showLoginModal(opts: LoginOptions): Promise<SignetSession | null>;