From 6841d647c2ef32bef7dd1c4f2414c055a98dc040 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Thu, 30 Jul 2026 14:14:00 -0400 Subject: [PATCH] Site: document requestNwcConnection and the Connection Vault Integration guide gains the wallet-connection step (reveal-mode honesty, CSP requirement, legacy-account caveat), llms.txt gains the API entry and event, the landing page gains a "Wallets that follow you" feature, and the file-copy step now says five files. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01CMr9Yt8SYmZcfgrg3CV2G1 --- packages/demo/public/docs.html | 29 ++++++++++++++++++++++++++++- packages/demo/public/index.html | 4 ++++ packages/demo/public/llms.txt | 12 +++++++++++- 3 files changed, 43 insertions(+), 2 deletions(-) diff --git a/packages/demo/public/docs.html b/packages/demo/public/docs.html index 7526264..f4dd3cb 100644 --- a/packages/demo/public/docs.html +++ b/packages/demo/public/docs.html @@ -35,7 +35,7 @@

  1. Copy the widget files next to your site

    -

    Grab bitlogin.js and cryptoWorker.js (plus the shared chunk they both import) from a BitLogin release (or build @bitlogin/widget yourself) and drop them in a folder your site serves, e.g. /vendor/bitlogin/. All of them must live in the same directory — the main script loads the worker by a relative URL.

    +

    Grab bitlogin.js and cryptoWorker.js plus every bitlogin-shared-*.js chunk beside them (five files in a current build — two of the chunks are the lazily loaded wallet-connect flow, downloaded only when a user opens it) from a BitLogin release (or build @bitlogin/widget yourself) and drop them in a folder your site serves, e.g. /vendor/bitlogin/. All of them must live in the same directory — the main script resolves the others by relative URL.

  2. Include the script and the element

    @@ -110,6 +110,33 @@ const plain = await bl.nip44Decrypt(peerPubkeyHex, cipher); BitRoad's src/nostr/bitloginAdapter.mjs is a real example: its signer adapter calls these four methods directly and never touches window.nostr at all.

    3. +
  3. +

    Ask for a wallet connection (NWC, Connection Vault)

    +

    If your app takes Lightning payments, stop asking users to paste an NWC string on every device. + One call asks BitLogin for a wallet connection bound to your origin:

    + 
    const uri = await bl.requestNwcConnection({
+  appName: 'Satisfied',
+  reason: 'Pay for meal analysis',
+});
+if (uri) payWith(uri); // full nostr+walletconnect:// URI, or null if declined
    +

    The widget owns the whole ceremony: sign-in first if nobody is signed in, a one-tap approval + when the account already has a connection bound to your origin (the connection follows the user to + every new device), or a guided first-time import — Bitcoin Connect's wallet chooser, or a pasted URI — + stored as an encrypted record on the user's account. A bitlogin-connection-granted event + fires on the element after each share, and users manage or revoke grants from the widget dashboard's + "Wallet connections" screen.

    +
    + This is reveal mode, and the consent screen says so. Your origin receives the full + bearer credential and everything its wallet-side budget allows — an embedded same-origin widget is + not a security boundary against its host page, so BitLogin doesn't pretend to broker. Encourage + budget-capped connections: the budget the user's wallet enforces is the real security boundary. + Two practical requirements: the wallet-connect flow needs style-src-attr 'unsafe-inline' + in your CSP (Bitcoin Connect's components set inline style attributes; hashes can't cover those), and + accounts created before the Connection Vault existed must enable it once from the account manager + (recovery phrase required) before connections can be saved — the flow still hands your app the URI + either way, just labeled as unsaved. +
    +

  4. Supporting multiple signing methods (extensions, NIP-46, BitLogin)

    window.nostr is a single global slot — only one provider can occupy it at a time. If a user also diff --git a/packages/demo/public/index.html b/packages/demo/public/index.html index 82fd35d..8e7c4f2 100644 --- a/packages/demo/public/index.html +++ b/packages/demo/public/index.html @@ -163,6 +163,10 @@

    Works with existing Nostr apps

    Once unlocked, BitLogin quietly plugs into the same window.nostr interface browser extensions use — apps built for those work with zero code changes.

    +
    +

    Wallets that follow you

    +

    The Connection Vault stores wallet connections (NWC) as independently encrypted records on your account. Connect a wallet to an app once; on a new device it's one tap, not another paste. Apps ask with requestNwcConnection(), you approve, you revoke — and the budget your wallet enforces stays the real limit.

    +
    diff --git a/packages/demo/public/llms.txt b/packages/demo/public/llms.txt index f9b9762..bc0a154 100644 --- a/packages/demo/public/llms.txt +++ b/packages/demo/public/llms.txt @@ -47,10 +47,20 @@ deployment above. call either manually. Without this, `window.nostr` would stay pointed at a signed-out BitLogin provider forever, blocking a switch to another method without a page reload. +- `requestNwcConnection({ appName, reason })` on the element — asks the user + to share an NWC wallet connection with the page's origin and resolves the + full `nostr+walletconnect://` URI (or null if declined). Handles sign-in, + one-tap approval for an origin-bound stored connection (connections are + encrypted Connection Vault records that follow the user across devices), + or first-time import via Bitcoin Connect's chooser / a pasted URI. REVEAL + mode: the origin receives the full bearer credential — wallet-side budgets + are the real security boundary. Requires `style-src-attr 'unsafe-inline'` + in the host CSP. Fires `bitlogin-connection-granted` after each share. - Events on the element: `bitlogin-login` (`detail.publicKey`), `bitlogin-logout`, `bitlogin-signer-claimed`, `bitlogin-signer-released` (the last also fires on `window` when triggered via - `window.bitlogin.releaseSigner()`). + `window.bitlogin.releaseSigner()`), `bitlogin-connection-granted` + (`detail.origin`). - Private keys never leave a dedicated Web Worker; the main thread only ever sees public keys, signed events, and ciphertext.