bitlogin/docs/login-methods.md

BitLogin as the Single Login Surface — NIP-07 and NIP-46 Methods

Document version: 0.3 Status: §LM4 (NIP-07) and §LM5 (NIP-46, memory-only phase) are implemented (2026-08-04): signers/ in @bitlogin/widget, the NIP-46 client in @bitlogin/core's nostr/nip46.ts with the ephemeral key held in the crypto worker, both bunker:// paste and the nostrconnect QR (rendered as dot-style inline SVG), thin sessions per §LM7, password-first per §LM9.1. NIP-46 persistence (§LM5.3 phase two) remains gated on the external vault review. §LM6 records a settled rejection (nsec paste as a login method), kept on the record. Depends on: docs/spec.md (§ references point there unless marked §LM or §SF), docs/second-factor.md §SF10 (imported identities, implemented)

---

LM1. Purpose and scope

Today <bitlogin-auth> offers exactly one way in: a BitLogin login name and password. A site that wants to serve existing Nostr users — extension holders, bunker users — has to build its own login chooser and treat BitLogin as one button in that menu.

This proposal inverts that. The widget becomes the login menu: one embed, one host-facing surface, and the user picks their method behind it:

1. BitLogin login name + password — the existing derived-account flow, unchanged, and still the default presented to new users.
2. NIP-07 — delegate to a signer extension already installed in the browser (§LM4).
3. NIP-46 — connect to a remote signer ("bunker") over relays (§LM5).

§26.4 already names NIP-07 and NIP-46 as anticipated future signer support; this document is the design for that line.

Out of scope, permanently: accepting a pasted nsec as a login method (§LM6). Users holding a raw key are routed to the implemented §SF10 import flow instead, which wraps the key into a full BitLogin account once rather than handling it at every sign-in.

LM2. Why aggregate rather than be aggregated

The bottleneck for BitLogin is developer adoption, and a developer evaluating a login widget hears one objection immediately: my existing users have extensions and bunkers; a password-only widget doesn't cover them. Supporting all three methods behind one embed removes that objection, and every embed then distributes BitLogin's native method as the easy path for everyone who does not already have Nostr keys.

Prior art validates the shape: nostr-login (nostrband) is an embeddable widget aggregating extension, NIP-46, and other methods, and it occupies the "one login surface" niche today. BitLogin's differentiator is not the aggregator layer — that part is commodity — but the derived-account custody underneath it. The aggregator is worth building because it is the wedge that gets the custody in front of users, not because it is novel.

The positioning consequence is worth stating plainly: with this change, a site never needs a login UI other than BitLogin, and BitLogin's security story — no method ever puts a root key on the page — holds across every method it offers (§LM6).

A fourth method — passkey sign-in, where a WebAuthn PRF-capable passkey (synced by the user's Google/Apple account) deterministically derives the credential of a standard capsule account with zero site setup and zero servers — is designed in passkey-login.md. The OAuth on-ramps considered before it are superseded and kept on the record in centralized-onramps.md.

LM3. Architecture: one facade, pluggable signers

The widget already exposes a NIP-07-shaped provider — installed as window.nostr (element.ts installs and releases it, taking over from an extension where configurable) and mirrored as an element-scoped API. Hosts program against that facade, not against the derivation machinery. That boundary is exactly where the abstraction goes.

host page ── window.nostr / <bitlogin-auth> API   (unchanged surface)
                     │
             provider facade
                     │
              active Signer
              ┌──────┼──────────────┐
        DerivedSigner  Nip07Signer  Nip46Signer
        (existing       (delegates   (bunker client
         worker path)    to the       over relays)
                         extension's
                         provider)

A Signer implements the calls the facade already promises — getPublicKey, signEvent, NIP-44 and NIP-04 encrypt/decrypt — plus metadata:

• method: "bitlogin" | "nip07" | "nip46", surfaced to the host in the sign-in event so applications can adapt (e.g. hide password-rotation UI for non-BitLogin sessions).
• capabilities: which optional calls this signer actually supports. Extensions vary — some lack nip44 — and the facade must report honestly rather than throw surprises (§LM4).

Rules that hold for every signer:

• No silent hangs. Every facade call has a timeout and a typed failure. This restates the Tier 1 rule from the 2026-07-30 audit for a world where a signature may wait on a phone that is asleep (§LM5).
• The facade is the only surface. No signer leaks its backend (extension provider object, bunker connection, worker handle) to the host page.
• One active signer per element. Method choice happens at sign-in; switching methods is a sign-out and sign-in, composing with (not complicating) the account-switching design.

LM4. NIP-07: delegate to an installed extension

The cheapest method: no key custody, no new stored secrets, no relay traffic. The widget detects an injected window.nostr that is not its own, offers "Sign in with extension," and the Nip07Signer passes facade calls through to the extension's provider.

Design points:

1. Arbitration inverts, not disappears. The current element takes over window.nostr at sign-in and warns when an extension's property is non-configurable. With a NIP-07 session the widget must not fight the extension — the extension's provider is the backend. The existing install/release logic stays for BitLogin-method sessions; NIP-07 sessions leave window.nostr alone (or install a passthrough only where the extension injected late). The detection must also snapshot the extension's provider before the widget's own install, so the two never confuse each other.
2. Capability probing. nip44 presence is checked on the extension object and reported in capabilities; absent calls reject with a typed "unsupported by this signer" error rather than a TypeError from an undefined property.
3. User-visible identity. After getPublicKey, the widget shows the npub it got, so the user can notice a wrong-profile extension state before the host application acts on it.
4. No session material of its own. A NIP-07 session persists nothing — on reload the extension is simply asked again. This makes NIP-07 the right first shipping increment (§LM8).

LM5. NIP-46: connect to a remote signer

The user's key lives in a bunker (nsecBunker, Amber, or similar); the widget holds only a client keypair and a connection secret, and requests signatures over relays. This is the method most aligned with BitLogin's security story — the widget custodies a revocable credential, never the key. If a compromised host exfiltrates the connection, the user revokes it at the signer; contrast a stolen nsec, which is unrotatable (§LM6).

Design points:

1. Connect flow. Accept a bunker:// URI or nostrconnect handshake; surface the signer's auth_url approval ceremony inside the widget UI (open in a new tab, show pending state, resume on approval). The connect ceremony is widget UI work of the same kind as the NWC REVEAL flow that shipped 2026-07-30.
2. Latency is a feature of the method, not a bug to hide. Every signEvent is a relay round trip to a device that may be offline. The facade shows a pending state, applies a timeout, and fails with a typed, retryable error. A host that got instant signatures from the derived path must not discover NIP-46 latency as a hang.
3. Persistence of the connection secret — deliberately phased.
   • Phase one: memory-only. The connection lives for the session; a reload means reconnecting. Nothing new is stored anywhere, so nothing new needs review.
   • Phase two: a Connection Vault record. A NIP-46 connection is shaped like the NWC credentials the vault already models — relay URLs plus a secret, revocable at the far end, scoped in authority. Persisting it as a vault record profile falls squarely under the standing gate: external security review before the vault holds anything beyond a budget-capped NWC connection. Phase two therefore waits on that review; phase one does not.
4. Client keypair hygiene. The ephemeral client key for the NIP-46 conversation is generated by the CSPRNG chokepoint like every other key in the codebase, and lives in the worker, not the DOM thread.

LM6. Rejected: nsec paste as a login method

Considered and rejected, on the record.

A paste box for nsec on an embedded, same-origin widget means the root key transits every host page that embeds BitLogin, at every sign-in, forever. An XSS on any embedding site exfiltrates a key that Nostr provides no way to rotate. §SF10 already states the principle: the paste is the risk — entering an nsec into a web page is the most dangerous single action in Nostr use. A login method institutionalizes that action as a habit; it also breaks the claim §LM2 leans on, that no BitLogin method ever puts a root key on the page.

The sanctioned path for a user holding a raw key is the implemented §SF10 import flow: paste once, on a build you trust, and the key is wrapped into a full BitLogin account — capsules built around the imported key, a fresh recovery phrase, password sign-in from then on. The login surface should route to it: an "I have an nsec" affordance that opens the import flow, so the user's need is met without the recurring paste.

The distinction in one line: import custodies the key once, under the account's full protections; a login method would handle it on every sign-in, under none of them.

LM7. Sessions are thin for non-BitLogin methods

Everything in the portable account layer — Connection Vault, portable app state, entitlements, second factor — is built on capsule custody. A NIP-07 or NIP-46 session has no capsule, so in this design those sessions are signer sessions only: the host gets window.nostr, the sign-in event with method and capabilities, and nothing else. No vault, no portable state, no second factor.

This is deliberate:

• It keeps the aggregator commodity-cheap — the expensive, review-gated machinery stays exclusive to derived accounts.
• It creates the honest upsell: "create a BitLogin password to get your settings and connections on every device." The widget may offer this to a signed-in NIP-07/NIP-46 user; note that upgrading an extension or bunker identity to a full account requires the private key BitLogin never sees for those methods, so the upsell mints a derived account (new identity) or, for a user who separately holds their key, points at §SF10 import.

Extending capsule-backed features to non-derived identities is possible in principle but is a protocol-surface expansion this document explicitly does not propose.

LM8. Phasing

1. NIP-07 — smallest increment: detection, delegation, capability probing, arbitration inversion. No new secrets, no relay traffic, no review gate touched. Shipped 2026-08-04.
2. NIP-46, memory-only — connect ceremony (bunker:// paste and a nostrconnect QR), pending/timeout UX, typed errors. Still nothing persisted. Shipped 2026-08-04. Transport is NIP-44 only, per the current NIP-46 spec; legacy NIP-04-only bunkers are not supported.
3. NIP-46 persistence as a vault profile — after the external security review the vault is already gated on.

Each step ships independently; the login UI grows one option at a time.

LM9. Open questions

1. Resolved 2026-08-04 (owner decision): username/password stays the primary presentation; alternative methods appear as secondary affordances below it, never promoted above the password path even when an extension is detected. Pinned by securityPolicy.test.ts.
2. Should a NIP-07 session survive reload by silently re-asking the extension, or require an explicit click each visit (extension prompt fatigue vs. surprise sessions)?
3. Does the sign-in event schema need versioning now that method and capabilities are added to it?
4. Whether the widget should expose "which methods are enabled" as element attributes so a host can, e.g., disable NIP-46 (methods="bitlogin,nip07").