signet-login

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

npm install signet-login

Or drop it in via CDN:

<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

<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.

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.

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:

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:

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:

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:

<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

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 — protocol, specs, docs
• signet-protocol — npm primitives
• signet-verify — age verification + cross-device auth primitives
• bark — NIP-07 browser extension that signs via NIP-46 to Heartwood
• Heartwood — self-hosted signing appliance