From b1a1bbbf3b4bed55e4c441d646d018d745eb0e81 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Mon, 10 Aug 2026 11:32:07 -0400 Subject: [PATCH] Add additive browser-distribution and integrator-API roadmap --- docs/TODO.md | 144 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) diff --git a/docs/TODO.md b/docs/TODO.md index d027f03..abf005c 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -171,3 +171,147 @@ Carried from the 2026-07-30 audit; none are live defects. That gate is now **met** — the sudo key lives only in the phrase-gated recovery capsule — but the UI still needs a separately reviewed key ceremony before it ships. + +## Additive browser distribution and integrator API roadmap + +These are additive compatibility goals. The existing multi-file build, +`` behavior, `window.nostr` provider, derivation chain, session +formats, and current consuming applications are compatibility contracts. Do +not replace or silently alter them while adding standalone distribution or a +new public API. Every release must continue to produce and test the standard +build before the standalone build is considered successful. + +### Priority 1 — Distribution + +- [ ] Add a standalone browser build target: `npm run build:standalone`. +- [ ] Produce one self-contained `bitlogin.js` for standalone consumers. +- [ ] Keep the standard multi-file build unchanged and available alongside it: + `dist/standard/` and `dist/standalone/`. +- [ ] Remove standalone runtime dependence on external `cryptoWorker.js`, + hashed shared chunks, or other sibling files; preserve Web Worker + isolation internally where possible using a Blob/module worker. +- [ ] Support this minimal static-site integration: + `` and + ``. +- [ ] Verify standalone hosting from arbitrary static HTTPS origins, including + GitHub Pages, Cloudflare Pages, Netlify, Vercel, and ordinary nginx. +- [ ] Verify localhost development usage. +- [ ] Document `file://` limitations clearly, including the recommended local + HTTPS or local development-server path. +- [ ] Define CSP requirements for standalone Blob/module workers and report + incompatible policies instead of silently degrading crypto isolation. + +### Priority 2 — Developer API + +- [ ] Define and document one canonical signer interface with capability-based + methods: `getPublicKey()`, `signEvent()`, `getRelays()`, and supported + `nip04.encrypt/decrypt`, `nip44.encrypt/decrypt`, and NWC operations. +- [ ] Keep `window.nostr` compatibility, including its existing NIP-07-shaped + behavior, as an adapter over the canonical signer rather than a breaking + replacement. +- [ ] Expose a clean additive `window.bitlogin` API, including + `activeSession()`, `login()`, `logout()`, and `getSigner()`. +- [ ] Add and document stable lifecycle event aliases: `bitlogin:ready`, + `bitlogin:login`, `bitlogin:logout`, and `bitlogin:error`. Preserve the + existing hyphenated events (`bitlogin-login`, `bitlogin-logout`, and + related current event names) for compatibility; the colon-named events + must be additive and must not replace them silently. +- [ ] Version and test event payloads; preserve existing event names and + payload fields used by current apps while adding new fields additively. +- [ ] Expose capability detection, for example `signer.capabilities()`, for + `signEvent`, `nip04`, `nip44`, `nip46`, `nwc`, and `passkey`. +- [ ] Ensure capability reporting describes the active session and never + implies support for a method that the active signer cannot perform. + +### Priority 3 — Embedding and UI + +- [ ] Support a headless mode so applications can use BitLogin without + rendering ``. +- [ ] Keep `` as the default easy-to-integrate UI. +- [ ] Allow applications to open the login dialog programmatically, including + `await bitlogin.login()`. +- [ ] Allow configurable login methods, for example + ``. +- [ ] Add basic theming hooks: CSS custom properties, light/dark support, + accent color, and compact mode. +- [ ] Expose supported configuration through documented attributes/options; + do not require integrators to reach into widget internals or private DOM. +- [ ] Preserve current login-method defaults and existing method ordering unless + an explicit versioned compatibility decision says otherwise. + +### Priority 4 — Build, versioning, and releases + +- [ ] Give browser artifacts predictable filenames: `bitlogin.js` and, + if useful, `bitlogin.min.js`. +- [ ] Expose version information through `window.bitlogin.version` and the + module/API surface where applicable. +- [ ] Emit integrity/hash manifests for releases and document exactly which + artifact each hash covers. +- [ ] Create downloadable release artifacts: `bitlogin-standard.zip` and + `bitlogin-standalone.js`. +- [ ] Publish release notes specifically for integrators, including changed + browser requirements, CSP requirements, API additions, and compatibility + notes. +- [ ] Evaluate public package exports for the widget, standalone entry point, + and core package (for example `@bitlogin/widget`, + `@bitlogin/widget/standalone`, and `@bitlogin/core`) without exposing + unsupported private paths or weakening package encapsulation. + +### Priority 5 — Integration and compatibility testing + +- [ ] Add a minimal vanilla HTML integration test for both standard and + standalone builds. +- [ ] Test standalone flows for password account, passkey account, recovery + phrase, NIP-07 extension, and NIP-46 bunker. +- [ ] Test `getPublicKey()`, `signEvent()`, `logout()`, and session restore + through both the canonical signer and the compatibility adapter. +- [ ] Test signed kind-1 publication against real or mock relays. +- [ ] Test multiple BitLogin-enabled applications on separate origins and + confirm origin-scoped storage/session behavior remains isolated. +- [ ] Test CSP compatibility, including the documented Blob/module-worker + requirements and a fail-closed result when a required policy is absent. +- [ ] Test Blob Worker behavior across Chromium, Firefox, and Safari. +- [ ] Test passkeys on real platform authenticators in addition to the existing + virtual-authenticator coverage. +- [ ] Run the existing derivation-chain known-answer tests and regression suite + unchanged; never update expected values to make a compatibility failure + pass. +- [ ] Verify current consuming applications (including AdZap, Satisfied, + BitUnlock, BitRoad, and Bitvid where their checkouts are available) still + load the standard artifact and retain login, signing, logout, and session + restore behavior. +- [ ] Add a release gate that builds/tests the standard artifact before and + after standalone bundling, proving standalone work cannot replace or + mutate the standard output accidentally. + +### Priority 6 — Documentation + +- [ ] Put a "30-second integration" section at the top of the README. +- [ ] Provide a complete single-page standard and standalone example. +- [ ] Provide a headless example. +- [ ] Provide a Nostr publishing example: + `const signer = await bitlogin.getSigner();` followed by + `const event = await signer.signEvent(...);`. +- [ ] Provide a migration guide from the standard build to the standalone + build, with a rollback path that requires no application-code rewrite. +- [ ] Clearly explain the security tradeoff between the standard worker/chunk + build and the standalone bundled build. +- [ ] Clearly state that standalone is a distribution convenience, not a + stronger security boundary; an embedding host remains trusted and + same-origin with the widget unless a separate isolation architecture is + used. + +### Definition of done + +A developer can download one JavaScript file, add approximately 3–5 lines of +HTML/JavaScript, and obtain a real BitLogin-backed Nostr signer without npm, +Vite, React, or a backend. Existing standard-build consumers continue to work +without source changes, and the compatibility and security claims above are +backed by automated tests and release artifacts. + +### Context warnings to resolve + +- [ ] Replace unresolved package references such as `@file:bitlogin/widget`, + `@file:bitlogin/widget/standalone`, and `@file:bitlogin/core` with actual + documented package paths or mark them as examples only; do not publish + links to files or exports that do not exist.