From a0c2f38ef0e9820c5d5e7b1027088420a62725f8 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 12 Jun 2026 17:36:19 +0200
Subject: [PATCH 01/82] fix(machine): add 6 new themes to electron VALID_THEMES
 allowlist

db074e2 added countrysidecastle/darkmatter/emeraldforest/lightgreen/
neobrut/starrynight to the renderer's ThemeId union and style.css but
not to the electron main-process branding allowlist. branding.json
'theme' values outside the allowlist were silently dropped (theme=null),
so the renderer fell through to the localStorage theme (cyberpunk).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/electron/main.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index 59cbcd5..2ed9b12 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -88,6 +88,12 @@ const VALID_THEMES = new Set([
   'dracula',
   'nord',
   'tokyo-night',
+  'countrysidecastle',
+  'darkmatter',
+  'emeraldforest',
+  'lightgreen',
+  'neobrut',
+  'starrynight',
   'custom',
 ])
 

From 52eb37ceaf126bde963555f87ae2bb20c6921da1 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 12 Jun 2026 18:09:02 +0200
Subject: [PATCH 02/82] refactor(machine): drop electron theme allowlist, defer
 to renderer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The VALID_THEMES set in electron/main.ts duplicated the renderer's
ThemeId list and silently coerced any unlisted branding.json theme to
null — which is how darkmatter regressed to the localStorage theme after
db074e2 added themes to the renderer but not this allowlist (fixed in
a0c2f38). Remove the second list entirely: pass raw.theme through and
let useTheme's applyBrandingTheme (themes[] + the 'custom' branch) be
the single validation point. Unknown values are ignored downstream, so
nothing reaches the DOM unvetted.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/electron/main.ts | 21 ++++-----------------
 1 file changed, 4 insertions(+), 17 deletions(-)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index 2ed9b12..fb5c84b 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -81,22 +81,6 @@ type BrandingConfig = {
   logoDarkDataUrl: string | null
 }
 
-const VALID_THEMES = new Set([
-  'gruvbox',
-  'catppuccin',
-  'cyberpunk',
-  'dracula',
-  'nord',
-  'tokyo-night',
-  'countrysidecastle',
-  'darkmatter',
-  'emeraldforest',
-  'lightgreen',
-  'neobrut',
-  'starrynight',
-  'custom',
-])
-
 function loadBranding(): BrandingConfig | null {
   const brandingDir = path.join(
     fs.existsSync('/var/lib/bitspire') ? '/var/lib/bitspire' : process.cwd(),
@@ -116,7 +100,10 @@ function loadBranding(): BrandingConfig | null {
     try {
       const raw = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'))
       if (typeof raw.title === 'string') title = raw.title
-      if (typeof raw.theme === 'string' && VALID_THEMES.has(raw.theme)) theme = raw.theme
+      // No theme-name validation here: the renderer's `themes` list (plus its
+      // 'custom' branch) is the single source of truth. Pass the string through
+      // and let useTheme's applyBrandingTheme ignore anything it doesn't know.
+      if (typeof raw.theme === 'string') theme = raw.theme
       if (raw.custom_colors && typeof raw.custom_colors === 'object') {
         const { dark, ...flat } = raw.custom_colors as Record<string, unknown>
         const colors = Object.fromEntries(

From 627d5e63e5ac1b8400d6618e291becdf0251cd1f Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 14 Jun 2026 11:17:02 +0200
Subject: [PATCH 03/82] =?UTF-8?q?docs(adr):=20ADR-002=20remote=20access=20?=
 =?UTF-8?q?&=20fleet=20management=20=E2=80=94=20three=20planes,=20NetBird?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Separate payment (Nostr↔LNbits, SaaS-operator-owned), fleet control
(Nostr #42, machine-operator-owned), and access/recovery (SSH) planes
by trust owner. Recovery access is provisioned at install and
app-independent. Adopt NetBird for the access plane (scale + fully FOSS
self-hostable control plane; rejects Tailscale's closed control plane).

Reject a dashboard 'revoke SaaS-operator access' toggle as a false
promise — the SaaS operator controls LNbits and the default control
plane, so exclusion is by ownership (operator self-hosts), not by
toggle.
---
 .../002-remote-access-and-fleet-management.md | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docs/adr/002-remote-access-and-fleet-management.md

diff --git a/docs/adr/002-remote-access-and-fleet-management.md b/docs/adr/002-remote-access-and-fleet-management.md
new file mode 100644
index 0000000..4931daa
--- /dev/null
+++ b/docs/adr/002-remote-access-and-fleet-management.md
@@ -0,0 +1,114 @@
+# ADR-002: Remote Access & Fleet Management — Three Planes, Operator-Owned Access via NetBird
+
+**Status:** Accepted
+**Date:** 2026-06-14
+**Context:** Multi-operator bitSpire fleet — separating the payment, control, and recovery planes by who owns them.
+
+## Decision
+
+1. **Separate three planes by trust owner**, and never conflate them:
+   - **Payment plane** — ATM ↔ LNbits over the nostr-native-transport. Owned by the **SaaS operator**. Implies *no* machine access.
+   - **Fleet control plane** — routine ops/telemetry/enrollment over Nostr (see [#42](https://git.atitlan.io/aiolabs/bitspire/issues/42)). Authorized by the **machine operator's** key.
+   - **Access / recovery plane** — SSH for the unanticipated and the broken. Owned by the **machine operator**.
+
+2. **The machine operator's own recovery access is provisioned at install and is app-independent.** Their SSH key and their VPN/NetBird enrollment are established when the machine is set up, so they can always reach a box even when the bitSpire app or OS is broken. Access for *anyone else* is runtime-granted, scoped, and revocable — never the owner's own path.
+
+3. **Adopt NetBird as the standard access/recovery plane**, chosen for fleet scale and a **self-hostable, fully FOSS control plane**. The platform may provide a default NetBird setup as a convenience; a machine operator who does not wish to trust whoever runs that control plane **disables it and provisions their own access plane** (self-hosted NetBird, or their own WireGuard hub).
+
+4. **We will NOT build a "revoke SaaS-operator access" toggle in the operator dashboard.** It is a false promise of security: the SaaS operator runs LNbits (and, in the default deployment, the NetBird control plane), so a toggle they ultimately control cannot protect a machine operator against them. The honest boundary is **exclusion-by-ownership, not exclusion-by-toggle** — an operator who wants to exclude the SaaS operator takes ownership of the access plane.
+
+## Context
+
+### The players
+
+A deployed bitSpire machine sits between two distinct principals:
+
+- **SaaS operator** — runs the LNbits instance and provides the Lightning backend as a service.
+- **Machine operator** — owns the physical ATM(s) and is identified by a Nostr key (the operator pubkey in the [#42](https://git.atitlan.io/aiolabs/bitspire/issues/42) allow-list).
+
+These are different parties with different interests. A machine operator will want to SSH to their own machine for support and recovery, and **may or may not want to grant the SaaS operator that same access.**
+
+### Why the SaaS operator needs zero box access by design
+
+The whole nostr-native architecture (no admin tokens on the kiosk, no inbound network surface, payment over Nostr) means the SaaS operator can deliver the full service **without ever touching the machine**. So "the machine operator may refuse the SaaS operator access" is not a constraint to engineer around — it is the **default that costs nothing**. SaaS-operator box access is a *support convenience*, never a service requirement. The natural posture is therefore **default-deny for the SaaS operator**.
+
+### Why SSH can't be replaced by the Nostr control plane
+
+The Nostr control plane (#42) is a fixed menu of structured, capability-scoped commands dispatched by a handler *inside the app*. It is excellent for routine, auditable, fleet-wide ops on **healthy** machines, and strictly better than SSH for those (signed, scoped, logged, fan-out). But:
+
+- It can only do what a handler was written for; incidents are by definition unanticipated.
+- The listener lives in the app, so it dies exactly when the app dies — the case you most need recovery for.
+
+SSH (arbitrary, interactive, app-independent) is therefore irreducible as the **recovery plane**. The two are complements, not substitutes.
+
+### Why the recovery path must be app-independent
+
+The whole point of a recovery path is to survive the failure of the thing it recovers. So it must not be gated by the bitSpire app, nor by a Nostr command the app dispatches. The kernel/agent that carries the tunnel and `sshd` must come up at boot independent of the app. (`allowedTCPPorts = []` already means `sshd` is unreachable except across the tunnel — the VPN handshake is the outer lock, the SSH key the inner one.)
+
+### Why the single shared hub had to change
+
+The pre-existing design used one WireGuard hub (`170.75.161.21`) run by platform infra. Whoever runs that hub has a standing network path to every enrolled box — i.e. the SaaS operator having access to machines they don't own. Multi-tenancy requires the access plane to be **per-operator or policy-isolated**, rooted in the machine operator, not the platform.
+
+## Options Considered
+
+### Access-plane mechanism
+
+#### Option A: Always-up minimal WireGuard hub
+
+**Pros:** After boot, zero userspace dependency — the kernel holds the tunnel, nothing can crash it short of a kernel/networking fault; smallest, most battle-tested trusted-code surface; simplest possible recovery floor.
+**Cons:** Manual peer management; no policy/ACL/enrollment ergonomics; a single shared hub re-creates the multi-tenant trust problem (must be run per-operator to avoid it); does not scale operationally to many operators × many machines.
+
+#### Option B: NetBird (Selected)
+
+**Pros:** Policy/ACL-based, revocable, per-peer access control; enrollment + audit out of the box; **self-hostable, fully FOSS control plane** — we retain the ability to run and modify every layer; scales to the many-operators × many-machines world #42 anticipates.
+**Cons:** The NetBird agent is a userspace daemon, so the recovery path depends on that daemon being up (less bulletproof than kernel-level always-up WG) — mitigated by it being independent of the bitSpire app, mature, and systemd-restarted; running a control plane is operational weight (acceptable: the platform provides a default; sovereignty-seeking operators self-host).
+
+#### Option C: Tailscale
+
+**Pros:** Best-in-class ergonomics and NAT traversal.
+**Cons:** **Control plane is closed source with no FOSS alternative** (headscale only reimplements the coordination server, chasing an upstream we don't control). Fails the hard requirement that we can always self-host and modify any software we depend on. Rejected on that basis alone.
+
+#### Option D: On-demand tunnel toggled by the Nostr control plane
+
+**Pros:** No standing reachability; every access window is a signed, audited, time-boxed event.
+**Cons:** If the toggle is handled by the app, it fails in the exact recovery scenario (listener died with the app). If handled by a separate daemon, it reintroduces a privileged userspace listener into the recovery path and grows, rather than shrinks, the trusted-code surface. Acceptable only as an **audited convenience layer on top of** an always-available floor (and designed to fail open), never as the load-bearing gate. Not adopted as the primary mechanism.
+
+### Trust model for excluding the SaaS operator
+
+#### Option 1: Dashboard toggle to revoke SaaS-operator access (Rejected)
+
+The SaaS operator controls LNbits (the machine's wallet/account is an LNbits user they can administer) and, in the default deployment, the NetBird control plane. A toggle whose enforcement they ultimately control gives the machine operator no real protection against them — it is security theater. **Rejected as a false promise.**
+
+#### Option 2: Exclusion by ownership (Selected)
+
+The only honest way for a machine operator to exclude the SaaS operator is to **own the access plane**: disable the default (platform-provided) NetBird enrollment and stand up their own — self-hosted NetBird, or their own WireGuard hub. The default deployment trusts whoever runs the control plane *and says so plainly*; operators who won't extend that trust take ownership. Control = ownership; we do not pretend otherwise.
+
+## Consequences
+
+### Positive
+
+- Honest trust boundaries: the SaaS operator has no standing box access by default, and the limits of platform-provided convenience are stated rather than faked.
+- Scales to many operators × many machines via NetBird policy/enrollment, while preserving a self-hosting escape hatch for sovereignty.
+- The recovery plane survives app and OS failure because it is provisioned at install and independent of the runtime.
+- Every dependency remains FOSS and self-hostable — no closed control plane anywhere in the stack.
+
+### Negative
+
+- The NetBird agent is a standing userspace daemon; a box where *both* the app and the agent are down falls to the physical/LAN floor (same floor as any remote scheme — only pure kernel-WG narrows it, at the cost of NetBird's ergonomics). Operators who weight reliability over ergonomics can choose self-hosted plain WireGuard.
+- Sovereignty for a distrusting operator costs them operational work (running their own access plane). This is inherent to "control = ownership," not incidental.
+- Two enrollment surfaces at provisioning: app/payment identity (#42 seed URL) and system/access identity (this plane). They must be kept conceptually distinct.
+
+### Future Considerations
+
+- An **audited convenience layer** (Nostr `OpenAccess`/`CloseAccess` that opens a time-boxed SSH window and logs it as a signed event) may be added *on top of* the always-available floor, designed to fail open, for the routine "let me in" case. It is explicitly not the recovery gate.
+- The machine operator's Nostr key can become the single root of trust across all three planes — SSH `authorized_keys` + VPN enrollment at install, `AddOperator`/`RevokeOperator` (#42) for delegation — so granting/revoking any party (including the SaaS operator) is one scoped, revocable capability model.
+- `sshd` posture should be tightened to key-only for deployed boxes (password auth is currently forced on for installed configs for first-boot provisioning; scope it to the LAN/first-boot window). Tracks with [#51](https://git.atitlan.io/aiolabs/bitspire/issues/51).
+
+## References
+
+- [#41](https://git.atitlan.io/aiolabs/bitspire/issues/41) — Multi-location deployment: runtime site config (the access plane's per-machine identity is provisioned here, not baked into the closure).
+- [#42](https://git.atitlan.io/aiolabs/bitspire/issues/42) — Fleet management: Nostr-native remote control & telemetry (the control plane this ADR sits beside).
+- [#51](https://git.atitlan.io/aiolabs/bitspire/issues/51) — NixOS systemd hardening (sshd posture tightening).
+- [#52](https://git.atitlan.io/aiolabs/bitspire/issues/52) — Sidecar bunker for the ATM key (related key-handling direction).
+- `deploy/nixos/configuration.nix` — current WireGuard hub + `sshd` config (to be reworked per this decision).
+- NetBird — <https://github.com/netbirdio/netbird> (self-hostable, FOSS control plane).

From d6b22e1156b86f723b785a8d86de943895aa962e Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 18 Jun 2026 19:56:35 +0200
Subject: [PATCH 04/82] refactor(nostr): route signing + encryption through a
 Signer abstraction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce a Signer interface (signEvent / nip44Encrypt / nip44Decrypt +
sync pubkey) with an in-process LocalSigner backed by an nsec, and route
every signing/encryption call site through it. Behaviour is unchanged —
LocalSigner wraps the same MachineIdentity the code used directly before.

This is Phase A of the bunker migration (aiolabs/bitspire#52): it puts the
seam in place so Phase B can drop in a NIP-46 BunkerSigner at the bootstrap
without touching any call site. The whole chain becomes async (the bunker
path is a relay round-trip; LocalSigner resolves immediately).

Sites moved onto the signer:
- packages/nostr-client: createSignedEvent / createAuthEvent (now async),
  NostrClient config (signer not identity), AUTH challenge handler.
- packages/lnbits: LnbitsClient.initialize(nostr, signer); kind-21000 RPC
  encrypt + sign + reply-decrypt; handleReply is now async (event-id dedup
  still runs synchronously before the awaited decrypt, so replay safety and
  per-subscription hash dedup are preserved).
- apps/machine: lightning.ts builds a LocalSigner and exposes it on
  LightningServices; operator-config / operator-fees / availability beacon /
  maintenance beacon / fund-atm all sign + encrypt via the signer.

NIP-42 auth (kind 22242) is included — under the bunker it must be in the
spire policy (aiolabs/spirekeeper#26, already merged).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/electron/fund-atm.ts             |  8 +-
 apps/machine/src/App.vue                      | 14 ++--
 .../composables/useAvailabilityBroadcast.ts   |  8 +-
 apps/machine/src/services/lightning.ts        | 15 +++-
 apps/machine/src/services/operator-config.ts  | 20 ++---
 apps/machine/src/services/operator-fees.ts    | 15 ++--
 apps/machine/src/stores/atm.ts                | 22 ++---
 packages/lnbits/src/__tests__/client.test.ts  | 63 +++++++-------
 packages/lnbits/src/client.ts                 | 58 +++++++------
 .../nostr-client/src/__tests__/events.test.ts | 51 +++--------
 .../nostr-client/src/__tests__/signer.test.ts | 58 +++++++++++++
 packages/nostr-client/src/client.ts           | 24 +++---
 packages/nostr-client/src/events.ts           | 84 ++++---------------
 packages/nostr-client/src/index.ts            | 50 +++++------
 packages/nostr-client/src/signer.ts           | 64 ++++++++++++++
 packages/nostr-client/src/types.ts            |  8 +-
 16 files changed, 301 insertions(+), 261 deletions(-)
 create mode 100644 packages/nostr-client/src/__tests__/signer.test.ts
 create mode 100644 packages/nostr-client/src/signer.ts

diff --git a/apps/machine/electron/fund-atm.ts b/apps/machine/electron/fund-atm.ts
index ce8b1e0..bce6b4c 100644
--- a/apps/machine/electron/fund-atm.ts
+++ b/apps/machine/electron/fund-atm.ts
@@ -13,7 +13,7 @@
  */
 
 import { readFileSync } from 'node:fs'
-import { NostrClient, loadIdentityFromHex } from '@bitSpire/nostr-client'
+import { NostrClient, LocalSigner, loadIdentityFromHex } from '@bitSpire/nostr-client'
 import { LnbitsClient } from '@bitSpire/lnbits'
 
 // @ts-ignore — qrcode is a transitive dep (via qrcode.vue), no types needed
@@ -64,11 +64,11 @@ async function main() {
 
   console.error(`Generating invoice for ${amountSats} sats...`)
 
-  const identity = loadIdentityFromHex(atmPrivateKey)
+  const signer = new LocalSigner(loadIdentityFromHex(atmPrivateKey))
 
   const nostrClient = new NostrClient({
     relays: [{ url: relayUrl }],
-    identity,
+    signer,
   })
   await nostrClient.connect()
 
@@ -76,7 +76,7 @@ async function main() {
     serverPubkey: lnbitsServerPubkey,
     relays: [relayUrl],
   })
-  lnbits.initialize(nostrClient, identity)
+  lnbits.initialize(nostrClient, signer)
 
   const wallets = await lnbits.listWallets()
   const wallet = wallets[0]
diff --git a/apps/machine/src/App.vue b/apps/machine/src/App.vue
index c5730e3..37882ba 100644
--- a/apps/machine/src/App.vue
+++ b/apps/machine/src/App.vue
@@ -51,18 +51,18 @@ onMounted(async () => {
     atmStore.initError = 'maintenance'
     // Publish maintenance beacon — minimal Nostr connection only (no Lightning.Pub)
     try {
-      const { NostrClient, loadIdentityFromHex, createSignedEvent } = await import(
+      const { NostrClient, LocalSigner, loadIdentityFromHex, createSignedEvent } = await import(
         '@bitSpire/nostr-client'
       )
       const secrets = isElectron ? await window.electronAPI?.getAtmSecrets() : null
       const privKey = secrets?.atmPrivateKey || import.meta.env.VITE_ATM_PRIVATE_KEY
       const relayUrl = config?.relayUrl || import.meta.env.VITE_RELAY_URL
       if (privKey && relayUrl) {
-        const identity = loadIdentityFromHex(privKey)
-        const client = new NostrClient({ relays: [{ url: relayUrl }], identity })
+        const signer = new LocalSigner(loadIdentityFromHex(privKey))
+        const client = new NostrClient({ relays: [{ url: relayUrl }], signer })
         await client.connect()
-        const publishBeacon = () => {
-          const event = createSignedEvent(identity, {
+        const publishBeacon = async () => {
+          const event = await createSignedEvent(signer, {
             kind: 30078,
             created_at: Math.floor(Date.now() / 1000),
             tags: [['d', 'atm-availability']],
@@ -77,8 +77,8 @@ onMounted(async () => {
           })
           client.publish(event).catch(() => {})
         }
-        publishBeacon()
-        setInterval(publishBeacon, 5 * 60 * 1000)
+        void publishBeacon()
+        setInterval(() => void publishBeacon(), 5 * 60 * 1000)
       }
     } catch (e) {
       console.warn('[App] Failed to start maintenance beacon:', e)
diff --git a/apps/machine/src/composables/useAvailabilityBroadcast.ts b/apps/machine/src/composables/useAvailabilityBroadcast.ts
index b36f6f2..a4968f7 100644
--- a/apps/machine/src/composables/useAvailabilityBroadcast.ts
+++ b/apps/machine/src/composables/useAvailabilityBroadcast.ts
@@ -13,7 +13,7 @@
 
 import { watch, type Ref } from 'vue'
 import { useDebounceFn } from '@vueuse/core'
-import type { NostrClient, MachineIdentity } from '@bitSpire/nostr-client'
+import type { NostrClient, Signer } from '@bitSpire/nostr-client'
 import { createSignedEvent } from '@bitSpire/nostr-client'
 
 type CashLevel = 'none' | 'low' | 'good' | 'full'
@@ -26,7 +26,7 @@ interface AvailabilitySnapshot {
 
 interface UseAvailabilityBroadcastOptions {
   nostrClient: NostrClient
-  identity: MachineIdentity
+  signer: Signer
   /** Reactive inventory: denomination -> count */
   inventory: Ref<Record<number, number>>
   /** Reactive Lightning.Pub balance in sats (null = unknown) */
@@ -38,7 +38,7 @@ interface UseAvailabilityBroadcastOptions {
 }
 
 export function useAvailabilityBroadcast(options: UseAvailabilityBroadcastOptions) {
-  const { nostrClient, identity, inventory, balanceSats, fiatCode, model } = options
+  const { nostrClient, signer, inventory, balanceSats, fiatCode, model } = options
 
   let lastSnapshot: AvailabilitySnapshot | null = null
 
@@ -73,7 +73,7 @@ export function useAvailabilityBroadcast(options: UseAvailabilityBroadcastOption
       model,
     })
 
-    const event = createSignedEvent(identity, {
+    const event = await createSignedEvent(signer, {
       kind: 30078,
       created_at: Math.floor(Date.now() / 1000),
       tags: [['d', 'atm-availability']],
diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index 1466e20..8154d4b 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -14,8 +14,10 @@
 
 import {
   NostrClient,
+  LocalSigner,
   generateIdentity,
   loadIdentityFromHex,
+  type Signer,
   type MachineIdentity,
 } from '@bitSpire/nostr-client'
 import { LnbitsClient } from '@bitSpire/lnbits'
@@ -234,7 +236,7 @@ interface LightningServices {
   nostrClient: NostrClient
   lightningPub: LightningBackend
   clink: CLINKClient
-  identity: MachineIdentity
+  signer: Signer
   /** Operator pubkeys (hex) authorized for kind-21003 management + operator-config events. */
   operatorPubkeys: string[]
   atmServices: ATMServices
@@ -451,10 +453,15 @@ export async function initializeLightningServices(options?: {
   }
   console.log('[Lightning] ATM pubkey:', identity.publicKey)
 
+  // Wrap the identity in a signer. Phase A always uses LocalSigner (in-process
+  // nsec); Phase B swaps in a BunkerSigner here without touching the call
+  // sites below. See aiolabs/bitspire#52.
+  const signer: Signer = new LocalSigner(identity)
+
   // Create Nostr client
   const nostrClient = new NostrClient({
     relays: [{ url: CONFIG.relayUrl }],
-    identity,
+    signer,
   })
 
   await nostrClient.connect()
@@ -465,7 +472,7 @@ export async function initializeLightningServices(options?: {
     serverPubkey: CONFIG.lnbitsServerPubkey,
     relays: [CONFIG.relayUrl],
   })
-  lnbits.initialize(nostrClient, identity)
+  lnbits.initialize(nostrClient, signer)
   _lnbitsRef = lnbits
   console.log('[Lightning] LNbits client initialized')
 
@@ -588,7 +595,7 @@ export async function initializeLightningServices(options?: {
     nostrClient,
     lightningPub,
     clink,
-    identity,
+    signer,
     operatorPubkeys: CONFIG.operatorPubkeys,
     atmServices,
     onOfferRequest: (callback: OfferRequestCallback) => {
diff --git a/apps/machine/src/services/operator-config.ts b/apps/machine/src/services/operator-config.ts
index c9b26f8..ba9ddcb 100644
--- a/apps/machine/src/services/operator-config.ts
+++ b/apps/machine/src/services/operator-config.ts
@@ -23,12 +23,10 @@
  */
 
 import {
-  type MachineIdentity,
+  type Signer,
   type NostrClient,
   type Event,
   createSignedEvent,
-  decryptContentV2,
-  encryptContentV2,
   validateEvent,
 } from '@bitSpire/nostr-client'
 
@@ -47,11 +45,11 @@ const isElectron = typeof window !== 'undefined' && window.electronAPI !== undef
 export interface OperatorConfigServiceConfig {
   /** Connected NostrClient — shared with the Lightning service. */
   nostrClient: NostrClient
-  /** ATM's nostr identity. Used to decrypt operator events + sign the bootstrap. */
-  identity: MachineIdentity
+  /** Signer for the ATM identity. Decrypts operator events + signs the bootstrap. */
+  signer: Signer
   /** Operator pubkeys (hex) authorized to publish cassette config. From VITE_OPERATOR_PUBKEYS. */
   operatorPubkeys: string[]
-  /** Machine identifier for the d-tag. Defaults to identity.publicKey when omitted. */
+  /** Machine identifier for the d-tag. Defaults to signer.pubkey when omitted. */
   machineId?: string
 }
 
@@ -72,7 +70,7 @@ export async function startOperatorConfigService(
     return { stop: () => {} }
   }
   const api = window.electronAPI
-  const machineId = cfg.machineId ?? cfg.identity.publicKey
+  const machineId = cfg.machineId ?? cfg.signer.pubkey
 
   // Bootstrap hello-event on first boot (best-effort — failure leaves the
   // gate null so the next boot retries).
@@ -88,7 +86,7 @@ export async function startOperatorConfigService(
     [
       {
         kinds: [KIND_NIP78],
-        '#p': [cfg.identity.publicKey],
+        '#p': [cfg.signer.pubkey],
         '#d': [dTag],
         authors: cfg.operatorPubkeys,
       },
@@ -150,7 +148,7 @@ async function handleOperatorConfigEvent(
   // 4. Decrypt content (NIP-44 v2).
   let parsed: { positions: Record<string, { denomination: number; count: number }> }
   try {
-    const plaintext = decryptContentV2(cfg.identity, event.pubkey, event.content)
+    const plaintext = await cfg.signer.nip44Decrypt(event.pubkey, event.content)
     parsed = JSON.parse(plaintext) as typeof parsed
   } catch (err) {
     console.error('[OperatorConfig] Decrypt/parse failed:', err)
@@ -223,10 +221,10 @@ async function maybePublishBootstrap(
   for (const c of cassettes) {
     positions[String(c.position)] = { denomination: c.denomination, count: c.count }
   }
-  const ciphertext = encryptContentV2(cfg.identity, operatorPubkey, { positions })
+  const ciphertext = await cfg.signer.nip44Encrypt(operatorPubkey, JSON.stringify({ positions }))
 
   const dTag = atmStateDTag(machineId)
-  const event = createSignedEvent(cfg.identity, {
+  const event = await createSignedEvent(cfg.signer, {
     kind: KIND_NIP78,
     content: ciphertext,
     tags: [
diff --git a/apps/machine/src/services/operator-fees.ts b/apps/machine/src/services/operator-fees.ts
index 8581ce8..4e699a3 100644
--- a/apps/machine/src/services/operator-fees.ts
+++ b/apps/machine/src/services/operator-fees.ts
@@ -56,10 +56,9 @@
  */
 
 import {
-  type MachineIdentity,
+  type Signer,
   type NostrClient,
   type Event,
-  decryptContentV2,
   validateEvent,
 } from '@bitSpire/nostr-client'
 
@@ -80,11 +79,11 @@ const isElectron = typeof window !== 'undefined' && window.electronAPI !== undef
 export interface OperatorFeesServiceConfig {
   /** Connected NostrClient — shared with the Lightning service. */
   nostrClient: NostrClient
-  /** ATM's nostr identity. Used to decrypt operator events. */
-  identity: MachineIdentity
+  /** Signer for the ATM identity. Decrypts operator events. */
+  signer: Signer
   /** Operator pubkeys (hex) authorized to publish fee config. From VITE_OPERATOR_PUBKEYS. */
   operatorPubkeys: string[]
-  /** Machine identifier for the d-tag. Defaults to identity.publicKey when omitted. */
+  /** Machine identifier for the d-tag. Defaults to signer.pubkey when omitted. */
   machineId?: string
   /**
    * Called when a valid fee-config event is applied. Renderer should
@@ -112,7 +111,7 @@ export async function startOperatorFeesService(
     return { stop: () => {} }
   }
   const api = window.electronAPI
-  const machineId = cfg.machineId ?? cfg.identity.publicKey
+  const machineId = cfg.machineId ?? cfg.signer.pubkey
 
   // Subscribe to operator-published fee config events.
   const dTag = feeConfigDTag(machineId)
@@ -120,7 +119,7 @@ export async function startOperatorFeesService(
     [
       {
         kinds: [KIND_NIP78],
-        '#p': [cfg.identity.publicKey],
+        '#p': [cfg.signer.pubkey],
         '#d': [dTag],
         authors: cfg.operatorPubkeys,
       },
@@ -189,7 +188,7 @@ async function handleFeeConfigEvent(
   //    fields (v2 forward-compat — future promo payloads).
   let parsed: ParsedFeePayload
   try {
-    const plaintext = decryptContentV2(cfg.identity, event.pubkey, event.content)
+    const plaintext = await cfg.signer.nip44Decrypt(event.pubkey, event.content)
     const raw = JSON.parse(plaintext) as Record<string, unknown>
     parsed = parseV1Payload(raw)
   } catch (err) {
diff --git a/apps/machine/src/stores/atm.ts b/apps/machine/src/stores/atm.ts
index d0e2005..efc80cf 100644
--- a/apps/machine/src/stores/atm.ts
+++ b/apps/machine/src/stores/atm.ts
@@ -676,14 +676,14 @@ export const useAtmStore = defineStore('atm', () => {
       initialize(servicesWithInventory)
 
       // Start broadcasting availability (Kind 30078) with 5-minute heartbeat
-      startAvailabilityBroadcast(services.nostrClient, services.identity, machineModel.value)
+      startAvailabilityBroadcast(services.nostrClient, services.signer, machineModel.value)
 
       // Start operator-config consumer (aiolabs/lamassu-next#56) — subscribes
       // to kind-30078 cassette config events + publishes one-shot bootstrap
       operatorConfigSvc?.stop()
       operatorConfigSvc = await startOperatorConfigService({
         nostrClient: services.nostrClient,
-        identity: services.identity,
+        signer: services.signer,
         operatorPubkeys: services.operatorPubkeys,
       })
 
@@ -692,7 +692,7 @@ export const useAtmStore = defineStore('atm', () => {
       operatorFeesSvc?.stop()
       operatorFeesSvc = await startOperatorFeesService({
         nostrClient: services.nostrClient,
-        identity: services.identity,
+        signer: services.signer,
         operatorPubkeys: services.operatorPubkeys,
         onApply: applyFeeConfig,
       })
@@ -989,13 +989,13 @@ export const useAtmStore = defineStore('atm', () => {
       })
 
       // Start broadcasting availability (Kind 30078)
-      startAvailabilityBroadcast(lightning.nostrClient, lightning.identity, machineModel.value)
+      startAvailabilityBroadcast(lightning.nostrClient, lightning.signer, machineModel.value)
 
       // Operator-config consumer (aiolabs/lamassu-next#56)
       operatorConfigSvc?.stop()
       operatorConfigSvc = await startOperatorConfigService({
         nostrClient: lightning.nostrClient,
-        identity: lightning.identity,
+        signer: lightning.signer,
         operatorPubkeys: lightning.operatorPubkeys,
       })
 
@@ -1003,7 +1003,7 @@ export const useAtmStore = defineStore('atm', () => {
       operatorFeesSvc?.stop()
       operatorFeesSvc = await startOperatorFeesService({
         nostrClient: lightning.nostrClient,
-        identity: lightning.identity,
+        signer: lightning.signer,
         operatorPubkeys: lightning.operatorPubkeys,
         onApply: applyFeeConfig,
       })
@@ -1295,13 +1295,13 @@ export const useAtmStore = defineStore('atm', () => {
       // Real hardware connected — disable mock bill simulator
       debugMode.value = false
       // Start broadcasting availability (Kind 30078)
-      startAvailabilityBroadcast(lightning.nostrClient, lightning.identity, machineModel.value)
+      startAvailabilityBroadcast(lightning.nostrClient, lightning.signer, machineModel.value)
 
       // Operator-config consumer (aiolabs/lamassu-next#56)
       operatorConfigSvc?.stop()
       operatorConfigSvc = await startOperatorConfigService({
         nostrClient: lightning.nostrClient,
-        identity: lightning.identity,
+        signer: lightning.signer,
         operatorPubkeys: lightning.operatorPubkeys,
       })
 
@@ -1309,7 +1309,7 @@ export const useAtmStore = defineStore('atm', () => {
       operatorFeesSvc?.stop()
       operatorFeesSvc = await startOperatorFeesService({
         nostrClient: lightning.nostrClient,
-        identity: lightning.identity,
+        signer: lightning.signer,
         operatorPubkeys: lightning.operatorPubkeys,
         onApply: applyFeeConfig,
       })
@@ -1437,7 +1437,7 @@ export const useAtmStore = defineStore('atm', () => {
   /** Start broadcasting ATM availability (Kind 30078) with 5-minute heartbeat */
   let stopAvailabilityBroadcast: (() => void) | null = null
 
-  async function startAvailabilityBroadcast(nostrClient: any, identity: any, model: string) {
+  async function startAvailabilityBroadcast(nostrClient: any, signer: any, model: string) {
     if (stopAvailabilityBroadcast) return
 
     // Ensure persisted inventory is loaded before first broadcast
@@ -1445,7 +1445,7 @@ export const useAtmStore = defineStore('atm', () => {
 
     const { stop } = useAvailabilityBroadcast({
       nostrClient,
-      identity,
+      signer,
       inventory: persistedInventory,
       balanceSats,
       fiatCode: fiatCode.value,
diff --git a/packages/lnbits/src/__tests__/client.test.ts b/packages/lnbits/src/__tests__/client.test.ts
index 187e948..903bcb7 100644
--- a/packages/lnbits/src/__tests__/client.test.ts
+++ b/packages/lnbits/src/__tests__/client.test.ts
@@ -17,6 +17,7 @@ import {
 } from 'nostr-tools'
 import {
   encryptContentV2,
+  LocalSigner,
   type MachineIdentity,
   type NostrClient,
 } from '@bitSpire/nostr-client'
@@ -152,7 +153,7 @@ describe('isAuthenticServerEvent', () => {
 describe('LnbitsClient.handleReply wiring', () => {
   function makeMockNostr(): {
     nostr: NostrClient
-    triggerEvent: (ev: NostrEvent) => void
+    triggerEvent: (ev: NostrEvent) => Promise<void>
   } {
     let captured: ((ev: NostrEvent) => void) | null = null
     const nostr = {
@@ -168,9 +169,12 @@ describe('LnbitsClient.handleReply wiring', () => {
     } as unknown as NostrClient
     return {
       nostr,
-      triggerEvent: (ev) => {
+      // `handleReply` is async (the signer's nip44Decrypt is a promise),
+      // so flush microtasks + a macrotask tick before the caller asserts.
+      triggerEvent: async (ev) => {
         if (!captured) throw new Error('handleReply not wired yet')
         captured(ev)
+        await new Promise<void>((resolve) => setTimeout(resolve, 0))
       },
     }
   }
@@ -188,7 +192,7 @@ describe('LnbitsClient.handleReply wiring', () => {
     client: LnbitsClient
     serverIdentity: MachineIdentity
     recipientIdentity: MachineIdentity
-    triggerEvent: (ev: NostrEvent) => void
+    triggerEvent: (ev: NostrEvent) => Promise<void>
   } {
     const serverIdentity = makeIdentity()
     const recipientIdentity = makeIdentity()
@@ -197,11 +201,11 @@ describe('LnbitsClient.handleReply wiring', () => {
       serverPubkey: serverIdentity.publicKey,
       relays: ['ws://test/'],
     })
-    client.initialize(nostr, recipientIdentity)
+    client.initialize(nostr, new LocalSigner(recipientIdentity))
     return { client, serverIdentity, recipientIdentity, triggerEvent }
   }
 
-  it('drops a forged event without resolving any pending RPC', () => {
+  it('drops a forged event without resolving any pending RPC', async () => {
     const { client, serverIdentity, triggerEvent } = setupClient()
 
     // Pre-register a pending entry as `sendRpc` would have.
@@ -233,7 +237,7 @@ describe('LnbitsClient.handleReply wiring', () => {
       attackerKey,
     )
 
-    triggerEvent(forged)
+    await triggerEvent(forged)
 
     expect(resolveCalls).toBe(0)
     expect(rejectCalls).toBe(0)
@@ -241,7 +245,7 @@ describe('LnbitsClient.handleReply wiring', () => {
     expect((client as any).pending.has('req-forged')).toBe(true)
   })
 
-  it('processes a legitimate server-signed reply (positive sanity)', () => {
+  it('processes a legitimate server-signed reply (positive sanity)', async () => {
     const { client, serverIdentity, recipientIdentity, triggerEvent } =
       setupClient()
 
@@ -277,7 +281,7 @@ describe('LnbitsClient.handleReply wiring', () => {
       serverIdentity.privateKey,
     )
 
-    triggerEvent(reply)
+    await triggerEvent(reply)
 
     expect(resolved).toMatchObject({
       status: 'OK',
@@ -290,7 +294,7 @@ describe('LnbitsClient.handleReply wiring', () => {
     // fine, we only need to assert resolve fired with the right payload.
   })
 
-  it('does not poison the seenEventIds cache with a forged event', () => {
+  it('does not poison the seenEventIds cache with a forged event', async () => {
     // This is the test scenario where the #49 guard's contribution
     // actually shows up: ev.id is the dedup key for the client-global
     // exact-replay cache. WITHOUT the guard, an attacker could publish
@@ -320,7 +324,7 @@ describe('LnbitsClient.handleReply wiring', () => {
       attackerKey,
     )
 
-    triggerEvent(forged)
+    await triggerEvent(forged)
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     expect((client as any).seenEventIds.size).toBe(0)
@@ -345,7 +349,7 @@ describe('LnbitsClient.handleReply wiring', () => {
 describe('LnbitsClient subscribe-payments dedup (#50)', () => {
   function makeMockNostr(): {
     nostr: NostrClient
-    triggerEvent: (ev: NostrEvent) => void
+    triggerEvent: (ev: NostrEvent) => Promise<void>
   } {
     let captured: ((ev: NostrEvent) => void) | null = null
     const nostr = {
@@ -361,9 +365,12 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
     } as unknown as NostrClient
     return {
       nostr,
-      triggerEvent: (ev) => {
+      // `handleReply` is async (the signer's nip44Decrypt is a promise),
+      // so flush microtasks + a macrotask tick before the caller asserts.
+      triggerEvent: async (ev) => {
         if (!captured) throw new Error('handleReply not wired yet')
         captured(ev)
+        await new Promise<void>((resolve) => setTimeout(resolve, 0))
       },
     }
   }
@@ -436,7 +443,7 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
     )
   }
 
-  it('fires onPush once when the same event is injected twice (exact-replay dedup)', () => {
+  it('fires onPush once when the same event is injected twice (exact-replay dedup)', async () => {
     const serverIdentity = makeIdentity()
     const recipientIdentity = makeIdentity()
     const { nostr, triggerEvent } = makeMockNostr()
@@ -444,7 +451,7 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       serverPubkey: serverIdentity.publicKey,
       relays: ['ws://test/'],
     })
-    client.initialize(nostr, recipientIdentity)
+    client.initialize(nostr, new LocalSigner(recipientIdentity))
 
     const { received } = preregisterSub(client, 'sub-1')
 
@@ -455,14 +462,14 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       paymentHash: 'hash-aaa',
     })
     // Same bytes both times — same ev.id, same payment_hash.
-    triggerEvent(ev)
-    triggerEvent(ev)
+    await triggerEvent(ev)
+    await triggerEvent(ev)
 
     expect(received).toHaveLength(1)
     expect(received[0]!.payment_hash).toBe('hash-aaa')
   })
 
-  it('fires onPush once when two distinct ev.ids carry the same payment_hash', () => {
+  it('fires onPush once when two distinct ev.ids carry the same payment_hash', async () => {
     const serverIdentity = makeIdentity()
     const recipientIdentity = makeIdentity()
     const { nostr, triggerEvent } = makeMockNostr()
@@ -470,7 +477,7 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       serverPubkey: serverIdentity.publicKey,
       relays: ['ws://test/'],
     })
-    client.initialize(nostr, recipientIdentity)
+    client.initialize(nostr, new LocalSigner(recipientIdentity))
 
     const { received } = preregisterSub(client, 'sub-1')
 
@@ -493,14 +500,14 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       createdAt: now + 1,
     })
     expect(ev1.id).not.toBe(ev2.id) // sanity: ev.id dedup would NOT catch this
-    triggerEvent(ev1)
-    triggerEvent(ev2)
+    await triggerEvent(ev1)
+    await triggerEvent(ev2)
 
     expect(received).toHaveLength(1)
     expect(received[0]!.payment_hash).toBe('hash-bbb')
   })
 
-  it('fires onPush for each distinct payment_hash (negative dedup case)', () => {
+  it('fires onPush for each distinct payment_hash (negative dedup case)', async () => {
     const serverIdentity = makeIdentity()
     const recipientIdentity = makeIdentity()
     const { nostr, triggerEvent } = makeMockNostr()
@@ -508,7 +515,7 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       serverPubkey: serverIdentity.publicKey,
       relays: ['ws://test/'],
     })
-    client.initialize(nostr, recipientIdentity)
+    client.initialize(nostr, new LocalSigner(recipientIdentity))
 
     const { received } = preregisterSub(client, 'sub-1')
 
@@ -525,14 +532,14 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       paymentHash: 'hash-2',
       createdAt: Math.floor(Date.now() / 1000) + 2,
     })
-    triggerEvent(ev1)
-    triggerEvent(ev2)
+    await triggerEvent(ev1)
+    await triggerEvent(ev2)
 
     expect(received).toHaveLength(2)
     expect(received.map((p) => p.payment_hash)).toEqual(['hash-1', 'hash-2'])
   })
 
-  it('keeps dedup state per-subscription (one sub seeing a hash does not silence another)', () => {
+  it('keeps dedup state per-subscription (one sub seeing a hash does not silence another)', async () => {
     const serverIdentity = makeIdentity()
     const recipientIdentity = makeIdentity()
     const { nostr, triggerEvent } = makeMockNostr()
@@ -540,7 +547,7 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       serverPubkey: serverIdentity.publicKey,
       relays: ['ws://test/'],
     })
-    client.initialize(nostr, recipientIdentity)
+    client.initialize(nostr, new LocalSigner(recipientIdentity))
 
     const a = preregisterSub(client, 'sub-A')
     const b = preregisterSub(client, 'sub-B')
@@ -561,8 +568,8 @@ describe('LnbitsClient subscribe-payments dedup (#50)', () => {
       paymentHash: 'hash-shared',
       createdAt: Math.floor(Date.now() / 1000) + 1,
     })
-    triggerEvent(evA)
-    triggerEvent(evB)
+    await triggerEvent(evA)
+    await triggerEvent(evB)
 
     // Each subscription sees its own push exactly once.
     expect(a.received).toHaveLength(1)
diff --git a/packages/lnbits/src/client.ts b/packages/lnbits/src/client.ts
index b30f469..76b796e 100644
--- a/packages/lnbits/src/client.ts
+++ b/packages/lnbits/src/client.ts
@@ -22,12 +22,10 @@
 
 import {
   type NostrClient,
-  type MachineIdentity,
+  type Signer,
   type Event as NostrEvent,
-  encryptContentV2,
-  decryptContentV2,
 } from '@bitSpire/nostr-client'
-import { finalizeEvent, verifyEvent } from 'nostr-tools'
+import { verifyEvent } from 'nostr-tools'
 
 import type {
   LnbitsConfig,
@@ -121,7 +119,7 @@ const SEEN_PAYMENT_HASHES_MAX = 500
 export class LnbitsClient {
   private readonly config: Required<LnbitsConfig>
   private nostr: NostrClient | null = null
-  private identity: MachineIdentity | null = null
+  private signer: Signer | null = null
   private requestCounter = 0
   private readonly pending = new Map<
     string,
@@ -150,9 +148,9 @@ export class LnbitsClient {
     }
   }
 
-  initialize(nostr: NostrClient, identity: MachineIdentity): void {
+  initialize(nostr: NostrClient, signer: Signer): void {
     this.nostr = nostr
-    this.identity = identity
+    this.signer = signer
     this.startReplyListener()
   }
 
@@ -240,7 +238,7 @@ export class LnbitsClient {
     onPush: PaymentPushCallback,
     onClose?: SubscriptionCloseCallback,
   ): Promise<string> {
-    if (!this.nostr || !this.identity) {
+    if (!this.nostr || !this.signer) {
       throw new Error('LnbitsClient.subscribePayments: client not initialized')
     }
     const requestId = this.nextRequestId('sub')
@@ -431,7 +429,7 @@ export class LnbitsClient {
       requestId?: string
     },
   ): Promise<T> {
-    if (!this.nostr || !this.identity) {
+    if (!this.nostr || !this.signer) {
       throw new Error(`LnbitsClient.${rpcName}: client not initialized`)
     }
     const requestId = args.requestId ?? this.nextRequestId(rpcName)
@@ -444,10 +442,10 @@ export class LnbitsClient {
     if (args.query !== undefined) request.query = args.query as Record<string, unknown>
 
     const plaintext = JSON.stringify(request)
-    const encrypted = encryptContentV2(this.identity, this.config.serverPubkey, plaintext)
+    const encrypted = await this.signer.nip44Encrypt(this.config.serverPubkey, plaintext)
 
-    // Build + sign the kind-21000 event ourselves. The server reads our
-    // pubkey directly off the signature, so there's no separate
+    // Build + sign the kind-21000 event via the signer. The server reads
+    // our pubkey directly off the signature, so there's no separate
     // authIdentifier in the envelope (unlike LightningPubClient).
     //
     // NIP-40 expiration: 5 minutes past now. Defence-in-depth at the
@@ -457,18 +455,15 @@ export class LnbitsClient {
     // attacker can't bypass this by stripping the tag; the tag just
     // lets the relay short-circuit earlier.
     const now = Math.floor(Date.now() / 1000)
-    const event = finalizeEvent(
-      {
-        kind: LNBITS_KIND_RPC,
-        content: encrypted,
-        tags: [
-          ['p', this.config.serverPubkey],
-          ['expiration', String(now + 300)],
-        ],
-        created_at: now,
-      },
-      this.identity.privateKey,
-    )
+    const event = await this.signer.signEvent({
+      kind: LNBITS_KIND_RPC,
+      content: encrypted,
+      tags: [
+        ['p', this.config.serverPubkey],
+        ['expiration', String(now + 300)],
+      ],
+      created_at: now,
+    })
 
     // The pending entry MUST be registered before publish so we don't race
     // an extremely fast reply.
@@ -508,8 +503,8 @@ export class LnbitsClient {
    * based on `request_id` and `subscription_id`.
    */
   private startReplyListener(): void {
-    if (!this.nostr || !this.identity) return
-    const myPubkey = this.identity.publicKey
+    if (!this.nostr || !this.signer) return
+    const myPubkey = this.signer.pubkey
     const since = Math.floor(Date.now() / 1000) - 5
 
     this.relaySubIdForReplies = this.nostr.subscribe(
@@ -522,25 +517,28 @@ export class LnbitsClient {
         },
       ],
       {
-        onEvent: (ev: NostrEvent) => this.handleReply(ev),
+        onEvent: (ev: NostrEvent) => void this.handleReply(ev),
       },
     )
   }
 
-  private handleReply(ev: NostrEvent): void {
-    if (!this.identity) return
+  private async handleReply(ev: NostrEvent): Promise<void> {
+    const signer = this.signer
+    if (!signer) return
     if (!isAuthenticServerEvent(ev, this.config.serverPubkey)) return
     // Exact-replay dedup. Skip if we've already processed this event id.
     // Safe to trust `ev.id` here because `isAuthenticServerEvent` just
     // Schnorr-verified the event (`verifyEvent` recomputes the id and
     // confirms it matches the signed pubkey + body). Without that
     // guarantee an attacker could pre-poison this set with chosen ids.
+    // Runs before the async decrypt so concurrent re-deliveries of the
+    // same id still dedup synchronously.
     if (this.seenEventIds.has(ev.id)) return
     this.recordSeenEventId(ev.id)
 
     let plaintext: string
     try {
-      plaintext = decryptContentV2(this.identity, this.config.serverPubkey, ev.content)
+      plaintext = await signer.nip44Decrypt(this.config.serverPubkey, ev.content)
     } catch {
       return // not our peer or wrong key
     }
diff --git a/packages/nostr-client/src/__tests__/events.test.ts b/packages/nostr-client/src/__tests__/events.test.ts
index 7f1d2ea..f072788 100644
--- a/packages/nostr-client/src/__tests__/events.test.ts
+++ b/packages/nostr-client/src/__tests__/events.test.ts
@@ -1,19 +1,15 @@
 import { describe, it, expect } from 'vitest'
 import { generateIdentity } from '../identity.js'
-import {
-  createSignedEvent,
-  createMachineStatusEvent,
-  createAuthEvent,
-  validateEvent,
-  generateTxId,
-} from '../events.js'
-import { LamassuEventKind, type MachineStatus } from '../types.js'
+import { LocalSigner } from '../signer.js'
+import { createSignedEvent, createAuthEvent, validateEvent, generateTxId } from '../events.js'
+import { LamassuEventKind } from '../types.js'
 
 describe('events', () => {
   describe('createSignedEvent', () => {
-    it('should create a properly signed event', () => {
+    it('should create a properly signed event via the signer', async () => {
       const identity = generateIdentity()
-      const event = createSignedEvent(identity, {
+      const signer = new LocalSigner(identity)
+      const event = await createSignedEvent(signer, {
         kind: 1,
         content: 'test',
         tags: [],
@@ -25,48 +21,23 @@ describe('events', () => {
       expect(event.content).toBe('test')
       expect(event.id).toMatch(/^[0-9a-f]{64}$/)
       expect(event.sig).toMatch(/^[0-9a-f]{128}$/)
-    })
-  })
-
-  describe('createMachineStatusEvent', () => {
-    it('should create encrypted status event', () => {
-      const machine = generateIdentity()
-      const operator = generateIdentity()
-
-      const status: MachineStatus = {
-        online: true,
-        lastTransaction: Date.now(),
-        cashLevels: {
-          validator: 1000,
-          dispenser: [{ denomination: 20, count: 100, capacity: 500 }],
-        },
-        errors: [],
-        version: '1.0.0',
-      }
-
-      const event = createMachineStatusEvent(machine, operator.publicKey, status)
-
-      expect(event.kind).toBe(LamassuEventKind.MachineStatus)
-      expect(event.pubkey).toBe(machine.publicKey)
-      expect(event.tags).toContainEqual(['d', 'status'])
-      expect(event.tags).toContainEqual(['p', operator.publicKey])
-      // Content should be encrypted (not readable JSON)
-      expect(() => JSON.parse(event.content)).toThrow()
+      expect(validateEvent(event)).toBe(true)
     })
   })
 
   describe('createAuthEvent', () => {
-    it('should create NIP-42 auth event', () => {
-      const identity = generateIdentity()
+    it('should create a signed NIP-42 auth event (kind 22242)', async () => {
+      const signer = new LocalSigner(generateIdentity())
       const relayUrl = 'wss://relay.test.com'
       const challenge = 'random-challenge-string'
 
-      const event = createAuthEvent(identity, relayUrl, challenge)
+      const event = await createAuthEvent(signer, relayUrl, challenge)
 
       expect(event.kind).toBe(LamassuEventKind.Auth)
       expect(event.content).toBe('')
       expect(event.tags).toContainEqual(['relay', relayUrl])
       expect(event.tags).toContainEqual(['challenge', challenge])
+      expect(event.pubkey).toBe(signer.pubkey)
     })
   })
 
diff --git a/packages/nostr-client/src/__tests__/signer.test.ts b/packages/nostr-client/src/__tests__/signer.test.ts
new file mode 100644
index 0000000..120346f
--- /dev/null
+++ b/packages/nostr-client/src/__tests__/signer.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { finalizeEvent, verifyEvent } from 'nostr-tools'
+import { generateIdentity } from '../identity.js'
+import { LocalSigner } from '../signer.js'
+import { encryptContentV2, decryptContentV2 } from '../encryption.js'
+
+describe('LocalSigner', () => {
+  it('exposes the identity pubkey synchronously', () => {
+    const identity = generateIdentity()
+    const signer = new LocalSigner(identity)
+    expect(signer.pubkey).toBe(identity.publicKey)
+  })
+
+  it('signEvent produces a valid signature equivalent to finalizeEvent', async () => {
+    const identity = generateIdentity()
+    const signer = new LocalSigner(identity)
+    const template = {
+      kind: 21000,
+      content: 'rpc',
+      tags: [['p', identity.publicKey]],
+      created_at: 1_700_000_000,
+    }
+
+    const signed = await signer.signEvent(template)
+    const reference = finalizeEvent(template, identity.privateKey)
+
+    expect(verifyEvent(signed)).toBe(true)
+    expect(signed.pubkey).toBe(identity.publicKey)
+    // Same template + same key ⇒ same id (id is deterministic over content).
+    expect(signed.id).toBe(reference.id)
+  })
+
+  it('nip44Encrypt round-trips with the counterparty signer', async () => {
+    const alice = generateIdentity()
+    const bob = generateIdentity()
+    const aliceSigner = new LocalSigner(alice)
+    const bobSigner = new LocalSigner(bob)
+
+    const ciphertext = await aliceSigner.nip44Encrypt(bob.publicKey, 'secret')
+    const plaintext = await bobSigner.nip44Decrypt(alice.publicKey, ciphertext)
+
+    expect(plaintext).toBe('secret')
+  })
+
+  it('nip44 output interops with the standalone encryptContentV2 helper', async () => {
+    const alice = generateIdentity()
+    const bob = generateIdentity()
+    const aliceSigner = new LocalSigner(alice)
+
+    const viaSigner = await aliceSigner.nip44Encrypt(bob.publicKey, 'hello')
+    // The helper and the signer share NIP-44 v2 conversation-key derivation,
+    // so each can decrypt the other's ciphertext.
+    expect(decryptContentV2(bob, alice.publicKey, viaSigner)).toBe('hello')
+
+    const viaHelper = encryptContentV2(alice, bob.publicKey, 'hello')
+    expect(await aliceSigner.nip44Decrypt(bob.publicKey, viaHelper)).toBe('hello')
+  })
+})
diff --git a/packages/nostr-client/src/client.ts b/packages/nostr-client/src/client.ts
index 0d35b4d..e9067be 100644
--- a/packages/nostr-client/src/client.ts
+++ b/packages/nostr-client/src/client.ts
@@ -7,14 +7,7 @@
  * - Automatic reconnection
  */
 
-import {
-  type Event,
-  type Filter,
-  type VerifiedEvent,
-  Relay,
-  SimplePool,
-  verifyEvent,
-} from 'nostr-tools'
+import { type Event, type Filter, Relay, SimplePool, verifyEvent, nip19 } from 'nostr-tools'
 import { createAuthEvent } from './events.js'
 import type {
   NostrClientConfig,
@@ -156,10 +149,15 @@ export class NostrClient {
           // We need to extract the challenge and create our auth response
           const challenge =
             evt.tags?.find((t): t is [string, string] => t[0] === 'challenge')?.[1] ?? ''
-          const authEvent = createAuthEvent(this.config.identity, connection.config.url, challenge)
-          // Verify the event to get a VerifiedEvent type
+          const authEvent = await createAuthEvent(
+            this.config.signer,
+            connection.config.url,
+            challenge
+          )
+          // The signer returns a fully-signed event; re-verify defensively
+          // (a remote bunker could in principle return a malformed reply).
           if (verifyEvent(authEvent)) {
-            return authEvent as VerifiedEvent
+            return authEvent
           }
           throw new Error('Failed to create valid auth event')
         })
@@ -393,13 +391,13 @@ export class NostrClient {
    * Get the machine's public key
    */
   get publicKey(): string {
-    return this.config.identity.publicKey
+    return this.config.signer.pubkey
   }
 
   /**
    * Get the machine's npub
    */
   get npub(): string {
-    return this.config.identity.npub
+    return nip19.npubEncode(this.config.signer.pubkey)
   }
 }
diff --git a/packages/nostr-client/src/events.ts b/packages/nostr-client/src/events.ts
index 7b04d2f..82cc604 100644
--- a/packages/nostr-client/src/events.ts
+++ b/packages/nostr-client/src/events.ts
@@ -2,87 +2,33 @@
  * Event creation utilities for Lamassu ATM
  */
 
-import { type Event, type UnsignedEvent, finalizeEvent, getEventHash } from 'nostr-tools'
-import { encryptContent } from './encryption.js'
-import {
-  type MachineIdentity,
-  type MachineStatus,
-  type TransactionRecord,
-  LamassuEventKind,
-} from './types.js'
+import { type Event, type EventTemplate, type VerifiedEvent, getEventHash } from 'nostr-tools'
+import type { Signer } from './signer.js'
+import { LamassuEventKind } from './types.js'
 
 /**
- * Create a signed event
- */
-export function createSignedEvent(
-  identity: MachineIdentity,
-  event: Omit<UnsignedEvent, 'pubkey'>
-): Event {
-  const unsigned: UnsignedEvent = {
-    ...event,
-    pubkey: identity.publicKey,
-  }
-
-  return finalizeEvent(unsigned, identity.privateKey)
-}
-
-/**
- * Create a machine status event (Kind 30078)
+ * Sign an event template with the given signer.
  *
- * This is a replaceable event that represents the current machine state.
- * Content is encrypted with NIP-44 for the operator.
+ * Thin async wrapper over `Signer.signEvent` — the signer sets `pubkey`,
+ * `id` and `sig`. With a `BunkerSigner` this is a relay round-trip.
  */
-export function createMachineStatusEvent(
-  identity: MachineIdentity,
-  operatorPubkey: string,
-  status: MachineStatus
-): Event {
-  const encryptedContent = encryptContent(identity, operatorPubkey, status)
-
-  return createSignedEvent(identity, {
-    kind: LamassuEventKind.MachineStatus,
-    content: encryptedContent,
-    tags: [
-      ['d', 'status'],
-      ['p', operatorPubkey],
-    ],
-    created_at: Math.floor(Date.now() / 1000),
-  })
+export function createSignedEvent(signer: Signer, template: EventTemplate): Promise<VerifiedEvent> {
+  return signer.signEvent(template)
 }
 
 /**
- * Create a transaction record event (Kind 30079)
+ * Create a NIP-42 auth event for relay authentication.
  *
- * Replaceable event for each transaction, identified by txid.
- * Content is encrypted with NIP-44 for the operator.
- */
-export function createTransactionEvent(
-  identity: MachineIdentity,
-  operatorPubkey: string,
-  transaction: TransactionRecord
-): Event {
-  const encryptedContent = encryptContent(identity, operatorPubkey, transaction)
-
-  return createSignedEvent(identity, {
-    kind: LamassuEventKind.TransactionRecord,
-    content: encryptedContent,
-    tags: [
-      ['d', `tx:${transaction.txid}`],
-      ['p', operatorPubkey],
-    ],
-    created_at: Math.floor(Date.now() / 1000),
-  })
-}
-
-/**
- * Create a NIP-42 auth event for relay authentication
+ * Signed as the spire identity (kind 22242). Under the bunker this kind
+ * must be present in the signer policy (`SPIRE_POLICY_RULES`) or the sign
+ * request is rejected — see aiolabs/spirekeeper#26.
  */
 export function createAuthEvent(
-  identity: MachineIdentity,
+  signer: Signer,
   relayUrl: string,
   challenge: string
-): Event {
-  return createSignedEvent(identity, {
+): Promise<VerifiedEvent> {
+  return signer.signEvent({
     kind: LamassuEventKind.Auth,
     content: '',
     tags: [
diff --git a/packages/nostr-client/src/index.ts b/packages/nostr-client/src/index.ts
index 417f666..eb16f5f 100644
--- a/packages/nostr-client/src/index.ts
+++ b/packages/nostr-client/src/index.ts
@@ -15,30 +15,32 @@
  * import {
  *   NostrClient,
  *   generateIdentity,
- *   createMachineStatusEvent
+ *   LocalSigner,
+ *   createSignedEvent
  * } from '@bitSpire/nostr-client'
  *
- * // Create or load identity
- * const identity = generateIdentity()
+ * // Create or load identity, wrap it in a signer
+ * const signer = new LocalSigner(generateIdentity())
  *
  * // Create client
  * const client = new NostrClient({
  *   relays: [
  *     { url: 'wss://relay.youratm.company', requiresAuth: true }
  *   ],
- *   identity
+ *   signer
  * })
  *
  * // Connect
  * await client.connect()
  *
- * // Publish machine status
- * const statusEvent = createMachineStatusEvent(
- *   identity,
- *   operatorPubkey,
- *   { online: true, ... }
- * )
- * await client.publish(statusEvent)
+ * // Sign + publish an event
+ * const event = await createSignedEvent(signer, {
+ *   kind: 30078,
+ *   created_at: Math.floor(Date.now() / 1000),
+ *   tags: [['d', 'status']],
+ *   content: '...'
+ * })
+ * await client.publish(event)
  * ```
  */
 
@@ -55,25 +57,15 @@ export {
   bytesToHex,
 } from './identity.js'
 
-// Event creation
-export {
-  createSignedEvent,
-  createMachineStatusEvent,
-  createTransactionEvent,
-  createAuthEvent,
-  validateEvent,
-  generateTxId,
-} from './events.js'
+// Signing abstraction
+export { LocalSigner } from './signer.js'
+export type { Signer } from './signer.js'
 
-// Encryption
-export {
-  encryptContent,
-  decryptContent,
-  decryptJSON,
-  // NIP-44 v2 (standard, for CLINK protocol)
-  encryptContentV2,
-  decryptContentV2,
-} from './encryption.js'
+// Event creation
+export { createSignedEvent, createAuthEvent, validateEvent, generateTxId } from './events.js'
+
+// Encryption — NIP-44 v2 (used by the dormant CLINK client + tests)
+export { encryptContentV2, decryptContentV2 } from './encryption.js'
 
 // Types
 export type {
diff --git a/packages/nostr-client/src/signer.ts b/packages/nostr-client/src/signer.ts
new file mode 100644
index 0000000..3d3571b
--- /dev/null
+++ b/packages/nostr-client/src/signer.ts
@@ -0,0 +1,64 @@
+/**
+ * Signing + NIP-44 abstraction.
+ *
+ * Decouples every signing / encryption call site from the concrete key
+ * material. Two implementations:
+ *
+ * - `LocalSigner` holds an nsec in-process. Used for dev / ephemeral
+ *   identities and as the transitional fallback when no bunker pairing
+ *   exists. The underlying crypto is synchronous.
+ * - `BunkerSigner` (Phase B, aiolabs/bitspire#52) routes to a remote
+ *   NIP-46 nsecbunkerd so no operator key ever lives on the ATM.
+ *
+ * `pubkey` is the *signing* identity and is always known synchronously —
+ * from the local nsec, or from the spire seed before the bunker connects —
+ * so subscription filters and `p` tags need no refactor when the backing
+ * implementation changes.
+ *
+ * All methods are async: the bunker path is a relay round-trip. The local
+ * path satisfies the contract with immediately-resolved promises so call
+ * sites are bunker-ready without further change.
+ */
+
+import { type EventTemplate, type VerifiedEvent, finalizeEvent, nip44 } from 'nostr-tools'
+import type { MachineIdentity } from './types.js'
+
+export interface Signer {
+  /** Hex pubkey of the signing identity. */
+  readonly pubkey: string
+  /** Sign an unsigned event template, returning a fully-signed event. */
+  signEvent(template: EventTemplate): Promise<VerifiedEvent>
+  /** NIP-44 v2 encrypt `plaintext` for `peerPubkey`. */
+  nip44Encrypt(peerPubkey: string, plaintext: string): Promise<string>
+  /** NIP-44 v2 decrypt `ciphertext` from `peerPubkey`. */
+  nip44Decrypt(peerPubkey: string, ciphertext: string): Promise<string>
+}
+
+/**
+ * In-process signer backed by a local nsec. The crypto is synchronous;
+ * the async surface is satisfied by immediately-resolved promises so call
+ * sites are identical whether the signer is local or a remote bunker.
+ */
+export class LocalSigner implements Signer {
+  readonly pubkey: string
+  readonly #privateKey: Uint8Array
+
+  constructor(identity: MachineIdentity) {
+    this.pubkey = identity.publicKey
+    this.#privateKey = identity.privateKey
+  }
+
+  signEvent(template: EventTemplate): Promise<VerifiedEvent> {
+    return Promise.resolve(finalizeEvent(template, this.#privateKey))
+  }
+
+  nip44Encrypt(peerPubkey: string, plaintext: string): Promise<string> {
+    const conversationKey = nip44.v2.utils.getConversationKey(this.#privateKey, peerPubkey)
+    return Promise.resolve(nip44.v2.encrypt(plaintext, conversationKey))
+  }
+
+  nip44Decrypt(peerPubkey: string, ciphertext: string): Promise<string> {
+    const conversationKey = nip44.v2.utils.getConversationKey(this.#privateKey, peerPubkey)
+    return Promise.resolve(nip44.v2.decrypt(ciphertext, conversationKey))
+  }
+}
diff --git a/packages/nostr-client/src/types.ts b/packages/nostr-client/src/types.ts
index 068a9e2..43b44bc 100644
--- a/packages/nostr-client/src/types.ts
+++ b/packages/nostr-client/src/types.ts
@@ -2,7 +2,8 @@
  * Nostr client type definitions for Lamassu ATM
  */
 
-import type { Event, UnsignedEvent } from 'nostr-tools'
+import type { Event } from 'nostr-tools'
+import type { Signer } from './signer.js'
 
 /** Connection states for relay */
 export type ConnectionState =
@@ -25,6 +26,7 @@ export interface RelayConfig {
 
 /** Machine identity configuration */
 export interface MachineIdentity {
+  // pragma: allowlist secret
   /** Private key in hex format */
   privateKey: Uint8Array
   /** Public key in hex format */
@@ -37,8 +39,8 @@ export interface MachineIdentity {
 export interface NostrClientConfig {
   /** Relays to connect to */
   relays: RelayConfig[]
-  /** Machine identity (keypair) */
-  identity: MachineIdentity
+  /** Signer for the machine identity (local nsec or remote bunker) */
+  signer: Signer
   /** Connection timeout in ms (default: 10000) */
   connectionTimeout?: number
   /** Reconnect automatically on disconnect */

From 787de5bff1f1c7a41d714098f7fe57ac8c5ba596 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 18 Jun 2026 19:57:02 +0200
Subject: [PATCH 05/82] refactor(nostr-client): retire dead NIP-44 v1 /
 Lightning.Pub path

Drop encryptContent / decryptContent / decryptJSON and the hand-rolled
XChaCha20 + v1 conversation-key machinery they depended on (~230 lines).
The only callers were createMachineStatusEvent / createTransactionEvent,
which had no callers in apps/ and were removed in the Signer migration.

This closes the open question carried in aiolabs/bitspire#52: every live
encryption path is NIP-44 v2, and the nsecbunkerd signer is v2-only, so
there is nothing to keep v1 for. encryptContentV2 / decryptContentV2 stay
as the v2 helpers used by the dormant CLINK client + tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/__tests__/encryption.test.ts          |  31 +-
 packages/nostr-client/src/encryption.ts       | 271 +-----------------
 2 files changed, 17 insertions(+), 285 deletions(-)

diff --git a/packages/nostr-client/src/__tests__/encryption.test.ts b/packages/nostr-client/src/__tests__/encryption.test.ts
index 7595332..d684841 100644
--- a/packages/nostr-client/src/__tests__/encryption.test.ts
+++ b/packages/nostr-client/src/__tests__/encryption.test.ts
@@ -1,46 +1,33 @@
 import { describe, it, expect } from 'vitest'
 import { generateIdentity } from '../identity.js'
-import { encryptContent, decryptContent, decryptJSON } from '../encryption.js'
+import { encryptContentV2, decryptContentV2 } from '../encryption.js'
 
-describe('encryption', () => {
-  describe('encryptContent / decryptContent', () => {
+describe('encryption (NIP-44 v2)', () => {
+  describe('encryptContentV2 / decryptContentV2', () => {
     it('should encrypt and decrypt string content', () => {
       const sender = generateIdentity()
       const recipient = generateIdentity()
       const message = 'Hello, Nostr!'
 
-      const encrypted = encryptContent(sender, recipient.publicKey, message)
+      const encrypted = encryptContentV2(sender, recipient.publicKey, message)
 
       expect(encrypted).not.toBe(message)
       expect(typeof encrypted).toBe('string')
 
-      const decrypted = decryptContent(recipient, sender.publicKey, encrypted)
+      const decrypted = decryptContentV2(recipient, sender.publicKey, encrypted)
 
       expect(decrypted).toBe(message)
     })
 
-    it('should encrypt and decrypt object content', () => {
+    it('should encrypt and decrypt object content (serialized to JSON)', () => {
       const sender = generateIdentity()
       const recipient = generateIdentity()
-      const data = { amount: 1000, currency: 'USD', timestamp: Date.now() }
+      const data = { amount: 1000, currency: 'USD', timestamp: 1_700_000_000 }
 
-      const encrypted = encryptContent(sender, recipient.publicKey, data)
-      const decrypted = decryptContent(recipient, sender.publicKey, encrypted)
+      const encrypted = encryptContentV2(sender, recipient.publicKey, data)
+      const decrypted = decryptContentV2(recipient, sender.publicKey, encrypted)
 
       expect(JSON.parse(decrypted)).toEqual(data)
     })
   })
-
-  describe('decryptJSON', () => {
-    it('should decrypt and parse JSON directly', () => {
-      const sender = generateIdentity()
-      const recipient = generateIdentity()
-      const data = { test: true, nested: { value: 42 } }
-
-      const encrypted = encryptContent(sender, recipient.publicKey, data)
-      const decrypted = decryptJSON<typeof data>(recipient, sender.publicKey, encrypted)
-
-      expect(decrypted).toEqual(data)
-    })
-  })
 })
diff --git a/packages/nostr-client/src/encryption.ts b/packages/nostr-client/src/encryption.ts
index 8d6a1d3..7b0980f 100644
--- a/packages/nostr-client/src/encryption.ts
+++ b/packages/nostr-client/src/encryption.ts
@@ -1,274 +1,19 @@
 /**
- * NIP-44 Encryption utilities
+ * NIP-44 v2 encryption helpers.
  *
- * Supports both:
- * - v1: Lightning.Pub's custom format (xchacha20, used for kind 21000)
- * - v2: Standard NIP-44 v2 (used for other kinds)
+ * Thin wrappers over nostr-tools `nip44.v2`, used for operator-directed
+ * kind-30078 content and by the dormant CLINK client. Kind-21000 RPC and
+ * the availability/cassette paths route through the `Signer` abstraction
+ * (`signer.ts`) instead.
  *
- * NOTE: Lightning.Pub currently only supports NIP-44 v1 for kind 21000 RPC.
- * A contribution to support v2 would be welcome:
- * https://github.com/shocknet/Lightning.Pub
+ * The legacy NIP-44 v1 / Lightning.Pub XChaCha20 format was retired with
+ * the LNbits migration (aiolabs/bitspire#52): the nsecbunkerd signer is
+ * NIP-44 v2 only and nothing live used v1.
  */
 
 import { nip44 } from 'nostr-tools'
-import { bytesToHex, hexToBytes } from 'nostr-tools/utils'
-import { secp256k1 } from '@noble/curves/secp256k1.js'
-import { sha256 } from '@noble/hashes/sha2.js'
 import type { MachineIdentity } from './types.js'
 
-const V1_ENCRYPTION_VERSION = 1
-
-// Base64 utilities that work in both browser and Node
-function base64Encode(bytes: Uint8Array): string {
-  if (typeof btoa !== 'undefined') {
-    let binary = ''
-    for (let i = 0; i < bytes.length; i++) {
-      binary += String.fromCharCode(bytes[i]!)
-    }
-    return btoa(binary)
-  }
-  return Buffer.from(bytes).toString('base64')
-}
-
-function base64Decode(str: string): Uint8Array {
-  if (typeof atob !== 'undefined') {
-    const binary = atob(str)
-    const bytes = new Uint8Array(binary.length)
-    for (let i = 0; i < binary.length; i++) {
-      bytes[i] = binary.charCodeAt(i)
-    }
-    return bytes
-  }
-  return new Uint8Array(Buffer.from(str, 'base64'))
-}
-
-// Crypto random bytes
-function getRandomBytes(length: number): Uint8Array {
-  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-    return crypto.getRandomValues(new Uint8Array(length))
-  }
-  // Node.js fallback
-  const { randomBytes } = require('crypto') as typeof import('crypto')
-  return new Uint8Array(randomBytes(length))
-}
-
-// XChaCha20 implementation
-function rotl(a: number, b: number): number {
-  return ((a << b) | (a >>> (32 - b))) >>> 0
-}
-
-function quarterRound(state: Uint32Array, a: number, b: number, c: number, d: number): void {
-  state[a] = (state[a]! + state[b]!) >>> 0
-  state[d] = rotl(state[d]! ^ state[a]!, 16)
-  state[c] = (state[c]! + state[d]!) >>> 0
-  state[b] = rotl(state[b]! ^ state[c]!, 12)
-  state[a] = (state[a]! + state[b]!) >>> 0
-  state[d] = rotl(state[d]! ^ state[a]!, 8)
-  state[c] = (state[c]! + state[d]!) >>> 0
-  state[b] = rotl(state[b]! ^ state[c]!, 7)
-}
-
-function chacha20Block(key: Uint8Array, nonce: Uint8Array, counter: number): Uint8Array {
-  const state = new Uint32Array(16)
-  const keyBuf = new ArrayBuffer(32)
-  new Uint8Array(keyBuf).set(key)
-  const nonceBuf = new ArrayBuffer(12)
-  new Uint8Array(nonceBuf).set(nonce)
-  const view = new DataView(keyBuf)
-  const nonceView = new DataView(nonceBuf)
-
-  // "expand 32-byte k"
-  state[0] = 0x61707865
-  state[1] = 0x3320646e
-  state[2] = 0x79622d32
-  state[3] = 0x6b206574
-
-  for (let i = 0; i < 8; i++) {
-    state[4 + i] = view.getUint32(i * 4, true)
-  }
-
-  state[12] = counter >>> 0
-  for (let i = 0; i < 3; i++) {
-    state[13 + i] = nonceView.getUint32(i * 4, true)
-  }
-
-  const working = new Uint32Array(state)
-
-  for (let i = 0; i < 10; i++) {
-    quarterRound(working, 0, 4, 8, 12)
-    quarterRound(working, 1, 5, 9, 13)
-    quarterRound(working, 2, 6, 10, 14)
-    quarterRound(working, 3, 7, 11, 15)
-    quarterRound(working, 0, 5, 10, 15)
-    quarterRound(working, 1, 6, 11, 12)
-    quarterRound(working, 2, 7, 8, 13)
-    quarterRound(working, 3, 4, 9, 14)
-  }
-
-  const output = new Uint8Array(64)
-  const outView = new DataView(output.buffer)
-  for (let i = 0; i < 16; i++) {
-    outView.setUint32(i * 4, (working[i]! + state[i]!) >>> 0, true)
-  }
-
-  return output
-}
-
-function hchacha20(key: Uint8Array, nonce: Uint8Array): Uint8Array {
-  const state = new Uint32Array(16)
-  const keyBuf = new ArrayBuffer(32)
-  new Uint8Array(keyBuf).set(key)
-  const nonceBuf = new ArrayBuffer(16)
-  new Uint8Array(nonceBuf).set(nonce)
-  const keyView = new DataView(keyBuf)
-  const nonceView = new DataView(nonceBuf)
-
-  state[0] = 0x61707865
-  state[1] = 0x3320646e
-  state[2] = 0x79622d32
-  state[3] = 0x6b206574
-
-  for (let i = 0; i < 8; i++) {
-    state[4 + i] = keyView.getUint32(i * 4, true)
-  }
-
-  for (let i = 0; i < 4; i++) {
-    state[12 + i] = nonceView.getUint32(i * 4, true)
-  }
-
-  for (let i = 0; i < 10; i++) {
-    quarterRound(state, 0, 4, 8, 12)
-    quarterRound(state, 1, 5, 9, 13)
-    quarterRound(state, 2, 6, 10, 14)
-    quarterRound(state, 3, 7, 11, 15)
-    quarterRound(state, 0, 5, 10, 15)
-    quarterRound(state, 1, 6, 11, 12)
-    quarterRound(state, 2, 7, 8, 13)
-    quarterRound(state, 3, 4, 9, 14)
-  }
-
-  const result = new Uint8Array(32)
-  const resultView = new DataView(result.buffer)
-  resultView.setUint32(0, state[0]!, true)
-  resultView.setUint32(4, state[1]!, true)
-  resultView.setUint32(8, state[2]!, true)
-  resultView.setUint32(12, state[3]!, true)
-  resultView.setUint32(16, state[12]!, true)
-  resultView.setUint32(20, state[13]!, true)
-  resultView.setUint32(24, state[14]!, true)
-  resultView.setUint32(28, state[15]!, true)
-
-  return result
-}
-
-function xchacha20Encrypt(key: Uint8Array, nonce: Uint8Array, data: Uint8Array): Uint8Array {
-  const subkey = hchacha20(key, nonce.subarray(0, 16))
-  const chacha20Nonce = new Uint8Array(12)
-  chacha20Nonce.set(nonce.subarray(16, 24), 4)
-
-  const result = new Uint8Array(data.length)
-  let counter = 0
-
-  for (let offset = 0; offset < data.length; offset += 64) {
-    const block = chacha20Block(subkey, chacha20Nonce, counter++)
-    const remaining = Math.min(64, data.length - offset)
-    for (let i = 0; i < remaining; i++) {
-      result[offset + i] = data[offset + i]! ^ block[i]!
-    }
-  }
-
-  return result
-}
-
-/**
- * Get shared secret for v1 encryption (Lightning.Pub format)
- *
- * NIP-44 v1 key derivation:
- *   sha256(secp256k1.getSharedSecret(privKey, "02" + pubKey).slice(1, 33))
- *
- * This differs from v2 which uses HKDF instead of plain SHA-256.
- */
-function getConversationKeyV1(privateKey: Uint8Array, publicKey: string): Uint8Array {
-  // Compute ECDH shared point with compressed pubkey (02 prefix for even y)
-  const compressedPubkey = hexToBytes('02' + publicKey)
-  const sharedPoint = secp256k1.getSharedSecret(privateKey, compressedPubkey)
-  // Take x-coordinate only (skip the 0x04 prefix byte) and hash with SHA-256
-  return sha256(sharedPoint.slice(1, 33))
-}
-
-/**
- * Encrypt content using v1 format (Lightning.Pub's format for kind 21000)
- */
-export function encryptV1(content: string, sharedSecret: Uint8Array): string {
-  const nonce = getRandomBytes(24)
-  const plaintext = new TextEncoder().encode(content)
-  const ciphertext = xchacha20Encrypt(sharedSecret, nonce, plaintext)
-
-  const payload = new Uint8Array(1 + nonce.length + ciphertext.length)
-  payload[0] = V1_ENCRYPTION_VERSION
-  payload.set(nonce, 1)
-  payload.set(ciphertext, 25)
-
-  return base64Encode(payload)
-}
-
-/**
- * Decrypt content using v1 format (Lightning.Pub's format)
- */
-export function decryptV1(content: string, sharedSecret: Uint8Array): string {
-  const buf = base64Decode(content)
-
-  if (buf[0] !== V1_ENCRYPTION_VERSION) {
-    throw new Error('Encryption version unsupported')
-  }
-
-  const nonce = buf.subarray(1, 25)
-  const ciphertext = buf.subarray(25)
-  const plaintext = xchacha20Encrypt(sharedSecret, nonce, ciphertext) // XChaCha20 is symmetric
-
-  return new TextDecoder().decode(plaintext)
-}
-
-/**
- * Encrypt content for Lightning.Pub RPC (kind 21000)
- * Uses v1 format that Lightning.Pub expects
- */
-export function encryptContent(
-  identity: MachineIdentity,
-  recipientPubkey: string,
-  content: unknown
-): string {
-  const plaintext = typeof content === 'string' ? content : JSON.stringify(content)
-  const sharedSecret = getConversationKeyV1(identity.privateKey, recipientPubkey)
-  return encryptV1(plaintext, sharedSecret)
-}
-
-/**
- * Decrypt content from Lightning.Pub RPC (kind 21000)
- * Uses v1 format
- */
-export function decryptContent(
-  identity: MachineIdentity,
-  senderPubkey: string,
-  ciphertext: string
-): string {
-  const sharedSecret = getConversationKeyV1(identity.privateKey, senderPubkey)
-  return decryptV1(ciphertext, sharedSecret)
-}
-
-/**
- * Decrypt and parse JSON content
- */
-export function decryptJSON<T = unknown>(
-  identity: MachineIdentity,
-  senderPubkey: string,
-  ciphertext: string
-): T {
-  const plaintext = decryptContent(identity, senderPubkey, ciphertext)
-  return JSON.parse(plaintext) as T
-}
-
-// Also export v2 functions for other use cases (non-RPC encrypted messages)
 export const encryptContentV2 = (
   identity: MachineIdentity,
   recipientPubkey: string,

From 9c9009af315a92def8f305346ea76384bc3aec1b Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 18 Jun 2026 23:24:22 +0200
Subject: [PATCH 06/82] feat(nostr-client): NIP-46 bunker signer + spire
 pairing seed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase B of aiolabs/bitspire#52 — the consumer surface for routing signing
to the operator's nsecbunkerd (model A1: the ATM holds only its own NIP-46
transport key; the signing identity lives in the bunker).

- seed.ts: parseSpireSeed for the `spire-seed:v1:<base64url>` contract from
  spirekeeper pairing.py — re-pads stripped base64url, validates
  {v, spire_pubkey, bunker_url, relays}, leaves percent-decoding of the
  bunker URL to parseBunkerInput. seedFingerprint() detects a re-pair.
- bunker-signer.ts: BunkerSigner implements Signer by delegating
  sign_event / nip44_* to nostr-tools' nip46 over the bunker relay. pubkey
  is the spire identity, known synchronously from the seed. connectNewSeed
  redeems the one-shot connect secret; resumeFromBinding reuses the
  persisted transport key WITHOUT re-redeeming (the binding is
  server-persistent). Per-RPC timeout + typed BunkerRejectedError /
  BunkerTimeoutError so callers can distinguish revoked-binding (re-pair)
  from a transient outage.

Unit-tested against a fake inner client (delegation, sync pubkey, timeout,
error mapping) + seed round-trip/validation fixtures. Live-relay wiring is
Phase C; live bunker integration is Phase F.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/__tests__/bunker-signer.test.ts       |  89 +++++++++
 .../nostr-client/src/__tests__/seed.test.ts   |  76 ++++++++
 packages/nostr-client/src/bunker-signer.ts    | 174 ++++++++++++++++++
 packages/nostr-client/src/index.ts            |  13 ++
 packages/nostr-client/src/seed.ts             | 105 +++++++++++
 5 files changed, 457 insertions(+)
 create mode 100644 packages/nostr-client/src/__tests__/bunker-signer.test.ts
 create mode 100644 packages/nostr-client/src/__tests__/seed.test.ts
 create mode 100644 packages/nostr-client/src/bunker-signer.ts
 create mode 100644 packages/nostr-client/src/seed.ts

diff --git a/packages/nostr-client/src/__tests__/bunker-signer.test.ts b/packages/nostr-client/src/__tests__/bunker-signer.test.ts
new file mode 100644
index 0000000..c72dc4e
--- /dev/null
+++ b/packages/nostr-client/src/__tests__/bunker-signer.test.ts
@@ -0,0 +1,89 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { EventTemplate, VerifiedEvent } from 'nostr-tools'
+import {
+  BunkerSigner,
+  BunkerRejectedError,
+  BunkerTimeoutError,
+  generateClientTransportKey,
+  connectNewSeed,
+  resumeFromBinding,
+  type Nip46Inner,
+} from '../bunker-signer.js'
+
+const SPIRE_PUBKEY = 'b'.repeat(64)
+
+function fakeInner(overrides: Partial<Nip46Inner> = {}): Nip46Inner {
+  return {
+    connect: vi.fn(async () => {}),
+    signEvent: vi.fn(async (t: EventTemplate) => ({ ...t, id: 'id', sig: 'sig', pubkey: SPIRE_PUBKEY }) as unknown as VerifiedEvent),
+    nip44Encrypt: vi.fn(async (_pk: string, pt: string) => `enc(${pt})`),
+    nip44Decrypt: vi.fn(async (_pk: string, ct: string) => ct.replace(/^enc\((.*)\)$/, '$1')),
+    ...overrides,
+  }
+}
+
+describe('BunkerSigner', () => {
+  it('exposes the spire pubkey synchronously', () => {
+    const signer = new BunkerSigner(SPIRE_PUBKEY, fakeInner())
+    expect(signer.pubkey).toBe(SPIRE_PUBKEY)
+  })
+
+  it('delegates sign / encrypt / decrypt to the inner client', async () => {
+    const inner = fakeInner()
+    const signer = new BunkerSigner(SPIRE_PUBKEY, inner)
+
+    const tmpl: EventTemplate = { kind: 21000, tags: [], content: 'x', created_at: 1 }
+    await signer.signEvent(tmpl)
+    expect(inner.signEvent).toHaveBeenCalledWith(tmpl)
+
+    expect(await signer.nip44Encrypt('peer', 'hi')).toBe('enc(hi)')
+    expect(inner.nip44Encrypt).toHaveBeenCalledWith('peer', 'hi')
+
+    expect(await signer.nip44Decrypt('peer', 'enc(hi)')).toBe('hi')
+  })
+
+  it('maps an inner rejection to BunkerRejectedError (revoked / off-policy)', async () => {
+    const inner = fakeInner({
+      signEvent: vi.fn(async () => {
+        throw new Error('not authorized to sign kind 9999')
+      }),
+    })
+    const signer = new BunkerSigner(SPIRE_PUBKEY, inner)
+    await expect(signer.signEvent({ kind: 9999, tags: [], content: '', created_at: 1 })).rejects.toBeInstanceOf(
+      BunkerRejectedError
+    )
+  })
+
+  it('times out a non-responding bunker with BunkerTimeoutError', async () => {
+    vi.useFakeTimers()
+    const inner = fakeInner({ signEvent: vi.fn(() => new Promise<VerifiedEvent>(() => {})) })
+    const signer = new BunkerSigner(SPIRE_PUBKEY, inner, { timeoutMs: 50 })
+
+    const p = signer.signEvent({ kind: 21000, tags: [], content: '', created_at: 1 })
+    const assertion = expect(p).rejects.toBeInstanceOf(BunkerTimeoutError)
+    await vi.advanceTimersByTimeAsync(60)
+    await assertion
+    vi.useRealTimers()
+  })
+})
+
+describe('transport key + factory guards', () => {
+  it('generates a hex transport keypair', () => {
+    const key = generateClientTransportKey()
+    expect(key.secretHex).toMatch(/^[0-9a-f]{64}$/)
+    expect(key.publicHex).toMatch(/^[0-9a-f]{64}$/)
+    expect(key.secretHex).not.toBe(key.publicHex)
+  })
+
+  it('connectNewSeed rejects an unparseable bunker_url', async () => {
+    await expect(
+      connectNewSeed({ spirePubkey: SPIRE_PUBKEY, bunkerUrl: 'not-a-bunker-url', clientSecretHex: 'a'.repeat(64) })
+    ).rejects.toThrow(/unparseable bunker_url/)
+  })
+
+  it('resumeFromBinding rejects an unparseable bunker_url', async () => {
+    await expect(
+      resumeFromBinding({ spirePubkey: SPIRE_PUBKEY, bunkerUrl: 'not-a-bunker-url', clientSecretHex: 'a'.repeat(64) })
+    ).rejects.toThrow(/unparseable bunker_url/)
+  })
+})
diff --git a/packages/nostr-client/src/__tests__/seed.test.ts b/packages/nostr-client/src/__tests__/seed.test.ts
new file mode 100644
index 0000000..0deef80
--- /dev/null
+++ b/packages/nostr-client/src/__tests__/seed.test.ts
@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest'
+import { parseSpireSeed, seedFingerprint, SPIRE_SEED_SCHEME } from '../seed.js'
+
+/** Mirror of spirekeeper pairing.py: urlsafe base64, padding stripped. */
+function makeSeed(json: unknown): string {
+  const b64 = Buffer.from(JSON.stringify(json), 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+  return SPIRE_SEED_SCHEME + b64
+}
+
+const SPIRE_PUBKEY = 'a'.repeat(64)
+const BUNKER_URL = `bunker://${SPIRE_PUBKEY}?relay=wss%3A%2F%2Fbunker.relay%2F&secret=deadbeef`
+
+const VALID = {
+  v: 1,
+  spire_npub: 'npub1example',
+  spire_pubkey: SPIRE_PUBKEY,
+  bunker_url: BUNKER_URL,
+  relays: ['wss://events.relay/'],
+}
+
+describe('parseSpireSeed', () => {
+  it('parses a well-formed seed (snake_case → camelCase)', () => {
+    const seed = parseSpireSeed(makeSeed(VALID))
+    expect(seed).toEqual({
+      v: 1,
+      spirePubkey: SPIRE_PUBKEY,
+      bunkerUrl: BUNKER_URL,
+      relays: ['wss://events.relay/'],
+    })
+  })
+
+  it('re-pads stripped base64url of any residue length', () => {
+    // Vary a field so the encoded payload lands on each mod-4 residue.
+    for (const suffix of ['', 'a', 'ab', 'abc']) {
+      const seed = makeSeed({ ...VALID, spire_npub: `npub1${suffix}` })
+      expect(() => parseSpireSeed(seed)).not.toThrow()
+    }
+  })
+
+  it('keeps bunker_url verbatim (percent-decoding is parseBunkerInput’s job)', () => {
+    const seed = parseSpireSeed(makeSeed(VALID))
+    expect(seed.bunkerUrl).toContain('relay=wss%3A%2F%2F')
+    expect(seed.bunkerUrl).toContain('secret=deadbeef')
+  })
+
+  it.each([
+    ['wrong scheme', 'spire-seed:v2:abc'],
+    ['not a seed', 'bunker://whatever'],
+  ])('rejects %s', (_label, url) => {
+    expect(() => parseSpireSeed(url)).toThrow()
+  })
+
+  it.each([
+    ['bad version', { ...VALID, v: 2 }],
+    ['short pubkey', { ...VALID, spire_pubkey: 'abc' }],
+    ['non-bunker url', { ...VALID, bunker_url: 'https://evil/' }],
+    ['empty relays', { ...VALID, relays: [] }],
+    ['non-string relay', { ...VALID, relays: [123] }],
+  ])('rejects %s', (_label, json) => {
+    expect(() => parseSpireSeed(makeSeed(json))).toThrow()
+  })
+})
+
+describe('seedFingerprint', () => {
+  it('is stable for the same seed and differs across seeds', () => {
+    const a = makeSeed(VALID)
+    const b = makeSeed({ ...VALID, relays: ['wss://other.relay/'] })
+    expect(seedFingerprint(a)).toBe(seedFingerprint(a))
+    expect(seedFingerprint(a)).not.toBe(seedFingerprint(b))
+    expect(seedFingerprint(a)).toMatch(/^[0-9a-f]{64}$/)
+  })
+})
diff --git a/packages/nostr-client/src/bunker-signer.ts b/packages/nostr-client/src/bunker-signer.ts
new file mode 100644
index 0000000..ed80f02
--- /dev/null
+++ b/packages/nostr-client/src/bunker-signer.ts
@@ -0,0 +1,174 @@
+/**
+ * NIP-46 (nsecbunkerd) signer.
+ *
+ * Implements the `Signer` contract by delegating sign / nip44 to a remote
+ * bunker over NIP-46, so no operator key lives on the ATM. The ATM holds
+ * only its own *transport* keypair (`client_nsec`); the signing identity
+ * (`spire_pubkey`) is held by the operator's nsecbunkerd. See
+ * aiolabs/bitspire#52 (model A1) and lnbits `nip46_bunker_client.py`.
+ *
+ * Two lifecycle entry points:
+ * - `connectNewSeed` — first pairing: generate a transport key, redeem the
+ *   one-shot connect secret, bind `client_pubkey → spire_key` on the bunker.
+ * - `resumeFromBinding` — restart: reuse the persisted transport key. The
+ *   binding is server-persistent, so we do NOT re-redeem (the secret is
+ *   spent); we just re-open the relay subscription.
+ *
+ * `pubkey` is the spire identity, known synchronously from the seed/binding,
+ * so subscription filters and `p` tags work before any round-trip.
+ */
+
+import { BunkerSigner as Nip46BunkerSigner, parseBunkerInput } from 'nostr-tools/nip46'
+import { generateSecretKey, getPublicKey } from 'nostr-tools'
+import { bytesToHex, hexToBytes } from 'nostr-tools/utils'
+import type { EventTemplate, VerifiedEvent } from 'nostr-tools'
+import type { Signer } from './signer.js'
+
+/** Default per-RPC timeout. nostr-tools' nip46 sendRequest has none — a dead
+ *  bunker would hang forever — so we race every call against this. */
+const DEFAULT_BUNKER_TIMEOUT_MS = 10_000
+
+/**
+ * Raised when the bunker actively rejects a request (e.g. the operator
+ * revoked the spire's binding, or a kind/method is outside the policy).
+ * Callers should treat this as "unpaired" and surface a re-pair prompt.
+ */
+export class BunkerRejectedError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'BunkerRejectedError'
+  }
+}
+
+/** Raised when the bunker does not answer within the timeout (transient). */
+export class BunkerTimeoutError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'BunkerTimeoutError'
+  }
+}
+
+/** The subset of nostr-tools' nip46 BunkerSigner this wrapper drives. */
+export interface Nip46Inner {
+  connect(): Promise<void>
+  signEvent(event: EventTemplate): Promise<VerifiedEvent>
+  nip44Encrypt(thirdPartyPubkey: string, plaintext: string): Promise<string>
+  nip44Decrypt(thirdPartyPubkey: string, ciphertext: string): Promise<string>
+}
+
+export interface BunkerSignerOptions {
+  /** Per-RPC timeout in ms (default 10000). */
+  timeoutMs?: number
+}
+
+export class BunkerSigner implements Signer {
+  readonly pubkey: string
+  readonly #inner: Nip46Inner
+  readonly #timeoutMs: number
+
+  constructor(spirePubkey: string, inner: Nip46Inner, opts: BunkerSignerOptions = {}) {
+    this.pubkey = spirePubkey
+    this.#inner = inner
+    this.#timeoutMs = opts.timeoutMs ?? DEFAULT_BUNKER_TIMEOUT_MS
+  }
+
+  signEvent(template: EventTemplate): Promise<VerifiedEvent> {
+    return this.#call('sign_event', () => this.#inner.signEvent(template))
+  }
+
+  nip44Encrypt(peerPubkey: string, plaintext: string): Promise<string> {
+    return this.#call('nip44_encrypt', () => this.#inner.nip44Encrypt(peerPubkey, plaintext))
+  }
+
+  nip44Decrypt(peerPubkey: string, ciphertext: string): Promise<string> {
+    return this.#call('nip44_decrypt', () => this.#inner.nip44Decrypt(peerPubkey, ciphertext))
+  }
+
+  /**
+   * Wrap a bunker RPC with a timeout and normalize failures. nostr-tools'
+   * nip46 rejects with the bunker's `error` string (a rejection) — mapped to
+   * `BunkerRejectedError`; a non-response surfaces as `BunkerTimeoutError`.
+   */
+  async #call<T>(label: string, fn: () => Promise<T>): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(new BunkerTimeoutError(`bunker ${label}: no response in ${this.#timeoutMs}ms`)),
+        this.#timeoutMs
+      )
+    })
+    try {
+      return await Promise.race([fn(), timeout])
+    } catch (err) {
+      if (err instanceof BunkerTimeoutError) throw err
+      throw new BunkerRejectedError(`bunker ${label}: ${(err as Error).message ?? String(err)}`)
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+}
+
+/** A freshly-generated NIP-46 transport keypair (the ATM's `client_nsec`). */
+export interface ClientTransportKey {
+  /** 64-char hex secret key — persist this to state.db. */
+  secretHex: string
+  /** 64-char hex public key — what the bunker binds to the spire identity. */
+  publicHex: string
+}
+
+/** Generate the ATM's own NIP-46 transport keypair. */
+export function generateClientTransportKey(): ClientTransportKey {
+  const sk = generateSecretKey()
+  return { secretHex: bytesToHex(sk), publicHex: getPublicKey(sk) }
+}
+
+/** Persisted bunker binding — everything needed to resume without re-pairing. */
+export interface BunkerBinding {
+  /** Hex transport secret key (`client_nsec`). */
+  clientSecretHex: string
+  /** The spire's signing pubkey (hex). */
+  spirePubkey: string
+  /** `bunker://…` URL, re-parsed into a pointer on resume. */
+  bunkerUrl: string
+}
+
+/**
+ * First pairing: build a transport-keyed bunker signer, redeem the one-shot
+ * connect secret, and bind `client_pubkey → spire_key`. The returned signer
+ * is live; the caller persists `clientSecretHex` so a restart can resume.
+ *
+ * `bunkerUrl` is the seed's `bunker_url`; `spirePubkey` is the seed's
+ * `spire_pubkey`.
+ */
+export async function connectNewSeed(
+  args: { spirePubkey: string; bunkerUrl: string; clientSecretHex: string },
+  opts: BunkerSignerOptions = {}
+): Promise<BunkerSigner> {
+  const pointer = await parseBunkerInput(args.bunkerUrl)
+  if (!pointer) {
+    throw new Error(`connectNewSeed: unparseable bunker_url`)
+  }
+  const inner = Nip46BunkerSigner.fromBunker(hexToBytes(args.clientSecretHex), pointer)
+  await inner.connect() // redeems the one-shot secret; eager-binds on the bunker
+  return new BunkerSigner(args.spirePubkey, inner, opts)
+}
+
+/**
+ * Restart: reuse the persisted transport key. The bunker binding is
+ * server-persistent, so we do NOT call `connect()` (the secret is spent);
+ * `fromBunker` opens the relay subscription and `sign_event` works against
+ * the existing binding.
+ */
+export async function resumeFromBinding(
+  binding: BunkerBinding,
+  opts: BunkerSignerOptions = {}
+): Promise<BunkerSigner> {
+  const pointer = await parseBunkerInput(binding.bunkerUrl)
+  if (!pointer) {
+    throw new Error(`resumeFromBinding: unparseable bunker_url`)
+  }
+  // The connect secret is already spent; drop it so nothing re-redeems.
+  pointer.secret = null
+  const inner = Nip46BunkerSigner.fromBunker(hexToBytes(binding.clientSecretHex), pointer)
+  return new BunkerSigner(binding.spirePubkey, inner, opts)
+}
diff --git a/packages/nostr-client/src/index.ts b/packages/nostr-client/src/index.ts
index eb16f5f..bb821b4 100644
--- a/packages/nostr-client/src/index.ts
+++ b/packages/nostr-client/src/index.ts
@@ -61,6 +61,19 @@ export {
 export { LocalSigner } from './signer.js'
 export type { Signer } from './signer.js'
 
+// NIP-46 bunker signer + pairing seed (aiolabs/bitspire#52)
+export {
+  BunkerSigner,
+  BunkerRejectedError,
+  BunkerTimeoutError,
+  generateClientTransportKey,
+  connectNewSeed,
+  resumeFromBinding,
+} from './bunker-signer.js'
+export type { BunkerBinding, BunkerSignerOptions, ClientTransportKey } from './bunker-signer.js'
+export { parseSpireSeed, seedFingerprint, SPIRE_SEED_SCHEME } from './seed.js'
+export type { SpireSeed } from './seed.js'
+
 // Event creation
 export { createSignedEvent, createAuthEvent, validateEvent, generateTxId } from './events.js'
 
diff --git a/packages/nostr-client/src/seed.ts b/packages/nostr-client/src/seed.ts
new file mode 100644
index 0000000..e2ab902
--- /dev/null
+++ b/packages/nostr-client/src/seed.ts
@@ -0,0 +1,105 @@
+/**
+ * Spire pairing seed-URL parser.
+ *
+ * The operator dashboard (aiolabs/spirekeeper `pairing.py`) hands each ATM a
+ * one-time seed URL that encodes the bunker connection + the spire's signing
+ * identity. Wire contract (model A1):
+ *
+ *   spire-seed:v1:<base64url(json, no padding)>
+ *   json = {
+ *     "v": 1,
+ *     "spire_npub":   "npub1…",   // informational, ignored here
+ *     "spire_pubkey": "<64-hex>", // the spire's bunker-held signing identity
+ *     "bunker_url":   "bunker://<spire_pubkey_hex>?relay=<url>&secret=<sec>",
+ *     "relays":       ["wss://…"] // relays for the spire's OWN events (21000/30078)
+ *   }
+ *
+ * - base64url is `urlsafe_b64encode(...).rstrip("=")` → re-pad to a multiple
+ *   of 4 before decoding.
+ * - `relay` / `secret` inside `bunker_url` are percent-encoded; decoding them
+ *   is left to nostr-tools `parseBunkerInput` (see bunker-signer.ts), so we
+ *   keep `bunker_url` verbatim.
+ * - `bunker_url`'s relay is the BUNKER relay; `relays[]` is where the spire
+ *   publishes its own events. They may differ — both must be spire-reachable.
+ */
+
+import { sha256 } from '@noble/hashes/sha2.js'
+import { bytesToHex } from 'nostr-tools/utils'
+
+export const SPIRE_SEED_SCHEME = 'spire-seed:v1:'
+
+export interface SpireSeed {
+  /** Seed format version (always 1 for this scheme). */
+  v: number
+  /** The spire's signing identity — 64-char hex. Every event is signed as this. */
+  spirePubkey: string
+  /** `bunker://<pubkey>?relay=&secret=` — handed to nostr-tools parseBunkerInput. */
+  bunkerUrl: string
+  /** Relays where the spire publishes its own events (kind 21000 / 30078). */
+  relays: string[]
+}
+
+const HEX64 = /^[0-9a-f]{64}$/
+
+/** Decode an unpadded base64url string in both browser and Node. */
+function base64urlDecode(input: string): string {
+  const padded = input.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(input.length / 4) * 4, '=')
+  if (typeof atob !== 'undefined') {
+    return atob(padded)
+  }
+  return Buffer.from(padded, 'base64').toString('binary')
+}
+
+/**
+ * Parse + validate a `spire-seed:v1:` URL. Throws on any malformation —
+ * the seed is a trust root, so we fail closed rather than connect to a
+ * half-understood bunker.
+ */
+export function parseSpireSeed(seedUrl: string): SpireSeed {
+  if (typeof seedUrl !== 'string' || !seedUrl.startsWith(SPIRE_SEED_SCHEME)) {
+    throw new Error(`parseSpireSeed: not a ${SPIRE_SEED_SCHEME} URL`)
+  }
+
+  const payload = seedUrl.slice(SPIRE_SEED_SCHEME.length)
+  let raw: unknown
+  try {
+    raw = JSON.parse(base64urlDecode(payload))
+  } catch (err) {
+    throw new Error(`parseSpireSeed: undecodable payload (${(err as Error).message})`)
+  }
+
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('parseSpireSeed: payload is not an object')
+  }
+  const obj = raw as Record<string, unknown>
+
+  if (obj.v !== 1) {
+    throw new Error(`parseSpireSeed: unsupported version ${String(obj.v)}`)
+  }
+
+  const spirePubkey = obj.spire_pubkey
+  if (typeof spirePubkey !== 'string' || !HEX64.test(spirePubkey)) {
+    throw new Error('parseSpireSeed: spire_pubkey must be 64-char hex')
+  }
+
+  const bunkerUrl = obj.bunker_url
+  if (typeof bunkerUrl !== 'string' || !bunkerUrl.startsWith('bunker://')) {
+    throw new Error('parseSpireSeed: bunker_url must be a bunker:// URL')
+  }
+
+  const relays = obj.relays
+  if (!Array.isArray(relays) || relays.length === 0 || !relays.every((r) => typeof r === 'string')) {
+    throw new Error('parseSpireSeed: relays must be a non-empty string array')
+  }
+
+  return { v: 1, spirePubkey, bunkerUrl, relays: relays as string[] }
+}
+
+/**
+ * Stable fingerprint of a seed URL, used to detect a re-pair (operator/relay
+ * change). A different seed ⇒ a different fingerprint ⇒ the ATM re-binds and
+ * resets its bootstrap gate (aiolabs/bitspire#56).
+ */
+export function seedFingerprint(seedUrl: string): string {
+  return bytesToHex(sha256(new TextEncoder().encode(seedUrl)))
+}

From 2b8e951de55172597bf7b587f9fa1b2c483d687f Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 18 Jun 2026 23:24:32 +0200
Subject: [PATCH 07/82] feat(machine): persist NIP-46 bunker binding (state.db
 schema v11)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a bunker_binding singleton table + get/save/clearBunkerBinding
accessors holding the ATM's own NIP-46 transport key (client_nsec), the
spire signing pubkey, the bunker URL, and the seed fingerprint. Persisted
so a restart resumes the bunker session without re-redeeming the one-shot
connect secret; a changed fingerprint signals a re-pair.

The v10→v11 migration is idempotent (CREATE TABLE IF NOT EXISTS), and the
v9→v10 block now advances existing.value so a v9 install chains straight
through to v11 in one boot (matching the v6→v8 blocks).

Phase B of aiolabs/bitspire#52. The IPC bridge + bootstrap resolution that
consume these accessors land in Phase C.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/electron/state-store.ts | 104 ++++++++++++++++++++++++++-
 1 file changed, 103 insertions(+), 1 deletion(-)

diff --git a/apps/machine/electron/state-store.ts b/apps/machine/electron/state-store.ts
index fcf83e5..8705aec 100644
--- a/apps/machine/electron/state-store.ts
+++ b/apps/machine/electron/state-store.ts
@@ -15,7 +15,7 @@ import fs from 'node:fs'
 
 let db: Database.Database | null = null
 
-const SCHEMA_VERSION = '10'
+const SCHEMA_VERSION = '11'
 
 function getDbPath(): string {
   const prodDir = '/var/lib/bitspire'
@@ -114,6 +114,15 @@ export function initDatabase(dbPath?: string): void {
       event_created_at INTEGER NOT NULL,
       applied_at INTEGER NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS bunker_binding (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      client_secret_hex TEXT NOT NULL,
+      spire_pubkey TEXT NOT NULL,
+      bunker_url TEXT NOT NULL,
+      seed_fingerprint TEXT NOT NULL,
+      paired_at INTEGER NOT NULL
+    );
   `)
 
   // Seed meta + cashbox if first run, or run migrations
@@ -320,6 +329,29 @@ export function initDatabase(dbPath?: string): void {
     )
     db.prepare('UPDATE meta SET value = ? WHERE key = ?').run('10', 'schema_version')
     console.log('[StateStore] Migrated schema v9 → v10 (added fee_config + watermark)')
+    existing.value = '10'
+  }
+
+  if (existing && existing.value === '10') {
+    // Migration v10 → v11: NIP-46 bunker binding (aiolabs/bitspire#52).
+    //   - bunker_binding singleton — the ATM's own NIP-46 transport key
+    //     (client_nsec) plus the spire signing identity, bunker URL, and a
+    //     fingerprint of the seed it was paired from. Persisted so a restart
+    //     resumes the bunker session without re-redeeming the one-shot connect
+    //     secret. A new/changed seed_fingerprint signals a re-pair (which also
+    //     resets bootstrapPublishedAt — see lightning.ts / bitspire#56).
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS bunker_binding (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        client_secret_hex TEXT NOT NULL,
+        spire_pubkey TEXT NOT NULL,
+        bunker_url TEXT NOT NULL,
+        seed_fingerprint TEXT NOT NULL,
+        paired_at INTEGER NOT NULL
+      );
+    `)
+    db.prepare('UPDATE meta SET value = ? WHERE key = ?').run('11', 'schema_version')
+    console.log('[StateStore] Migrated schema v10 → v11 (added bunker_binding)')
   }
 
   // Defensive: a fresh install at SCHEMA_VERSION skips all migrations.
@@ -381,6 +413,76 @@ export function markBootstrapPublished(unixTimestamp: number): void {
   )
 }
 
+// ---------------------------------------------------------------------------
+// Bunker binding — NIP-46 transport key + spire identity (aiolabs/bitspire#52)
+// ---------------------------------------------------------------------------
+
+export interface StoredBunkerBinding {
+  /** The ATM's own NIP-46 transport secret key (`client_nsec`), hex. */
+  clientSecretHex: string
+  /** The spire's signing pubkey (hex) — the identity events are signed as. */
+  spirePubkey: string
+  /** `bunker://…` URL, re-parsed into a pointer on resume. */
+  bunkerUrl: string
+  /** Fingerprint of the seed this binding was paired from (re-pair detection). */
+  seedFingerprint: string
+  /** Unix seconds when the pairing was redeemed. */
+  pairedAt: number
+}
+
+/** Read the persisted bunker binding, or null if the ATM is unpaired. */
+export function getBunkerBinding(): StoredBunkerBinding | null {
+  if (!db) throw new Error('Database not initialized')
+  const row = db
+    .prepare(
+      'SELECT client_secret_hex, spire_pubkey, bunker_url, seed_fingerprint, paired_at FROM bunker_binding WHERE id = 1'
+    )
+    .get() as
+    | {
+        client_secret_hex: string
+        spire_pubkey: string
+        bunker_url: string
+        seed_fingerprint: string
+        paired_at: number
+      }
+    | undefined
+  if (!row) return null
+  return {
+    clientSecretHex: row.client_secret_hex,
+    spirePubkey: row.spire_pubkey,
+    bunkerUrl: row.bunker_url,
+    seedFingerprint: row.seed_fingerprint,
+    pairedAt: row.paired_at,
+  }
+}
+
+/** Upsert the bunker binding after a successful (re-)pairing. */
+export function saveBunkerBinding(binding: StoredBunkerBinding): void {
+  if (!db) throw new Error('Database not initialized')
+  db.prepare(
+    `INSERT INTO bunker_binding (id, client_secret_hex, spire_pubkey, bunker_url, seed_fingerprint, paired_at)
+     VALUES (1, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       client_secret_hex = excluded.client_secret_hex,
+       spire_pubkey      = excluded.spire_pubkey,
+       bunker_url        = excluded.bunker_url,
+       seed_fingerprint  = excluded.seed_fingerprint,
+       paired_at         = excluded.paired_at`
+  ).run(
+    binding.clientSecretHex,
+    binding.spirePubkey,
+    binding.bunkerUrl,
+    binding.seedFingerprint,
+    binding.pairedAt
+  )
+}
+
+/** Drop the bunker binding (e.g. after an operator revoke → force re-pair). */
+export function clearBunkerBinding(): void {
+  if (!db) throw new Error('Database not initialized')
+  db.prepare('DELETE FROM bunker_binding WHERE id = 1').run()
+}
+
 export type OperatorCassettesPayload = {
   positions: Record<string, { denomination: number; count: number }>
 }

From 40239aa0758c8441e37d422ef73b922148e30d12 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 19 Jun 2026 00:15:17 +0200
Subject: [PATCH 08/82] refactor(clink): route CLINK signing + encryption
 through the Signer

Swap CLINKClient's MachineIdentity for the Signer abstraction: sign_event /
nip44 now go through the signer (async), so the spire identity can live in a
NIP-46 bunker. The kind-21003 management path (operator-driven manual
dispense, the one live CLINK path on dev) decrypts as the spire via the
bunker; the dormant offer/debit paths are migrated too so they're
bunker-ready when CLINK is re-implemented for the upcoming ndebit/k1 spec
(shocknet/CLINK#7, #8).

Part of Phase C, aiolabs/bitspire#52.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/clink/src/client.ts | 91 ++++++++++++++++--------------------
 1 file changed, 41 insertions(+), 50 deletions(-)

diff --git a/packages/clink/src/client.ts b/packages/clink/src/client.ts
index 333461f..e2b2e88 100644
--- a/packages/clink/src/client.ts
+++ b/packages/clink/src/client.ts
@@ -10,34 +10,30 @@
  * Uses NIP-44v2 encryption for all messages.
  */
 
-import type { Event, UnsignedEvent } from 'nostr-tools'
-import { finalizeEvent } from 'nostr-tools'
-import type { MachineIdentity, NostrClient } from '@bitSpire/nostr-client'
-import { encryptContentV2, decryptContentV2 } from '@bitSpire/nostr-client'
+import type { Event, EventTemplate } from 'nostr-tools'
+import type { NostrClient, Signer } from '@bitSpire/nostr-client'
 
 /** CLINK protocol version tag (mandatory per CLINK spec) */
 const CLINK_VERSION_TAG: [string, string] = ['clink_version', '1']
 
 /**
- * Encrypt content using NIP-44 v2 (required for CLINK events)
+ * Encrypt content using NIP-44 v2 (required for CLINK events).
+ * Routes through the Signer so the spire identity can live in a bunker.
  */
-function encryptCLINK(
-  identity: MachineIdentity,
-  recipientPubkey: string,
-  content: unknown
-): string {
-  return encryptContentV2(identity, recipientPubkey, content)
+function encryptCLINK(signer: Signer, recipientPubkey: string, content: unknown): Promise<string> {
+  const plaintext = typeof content === 'string' ? content : JSON.stringify(content)
+  return signer.nip44Encrypt(recipientPubkey, plaintext)
 }
 
 /**
- * Decrypt and parse JSON content using NIP-44 v2
+ * Decrypt and parse JSON content using NIP-44 v2.
  */
-function decryptCLINKJSON<T = unknown>(
-  identity: MachineIdentity,
+async function decryptCLINKJSON<T = unknown>(
+  signer: Signer,
   senderPubkey: string,
   ciphertext: string
-): T {
-  const plaintext = decryptContentV2(identity, senderPubkey, ciphertext)
+): Promise<T> {
+  const plaintext = await signer.nip44Decrypt(senderPubkey, ciphertext)
   return JSON.parse(plaintext) as T
 }
 import {
@@ -67,8 +63,8 @@ import { encodeNoffer, decodeNoffer } from './noffer.js'
 export interface CLINKClientOptions {
   /** Nostr client for communication */
   nostrClient: NostrClient
-  /** Machine identity */
-  identity: MachineIdentity
+  /** Signer for the spire identity (local nsec or remote bunker) */
+  signer: Signer
   /** Operator pubkey(s) for management commands */
   operatorPubkey: string | string[]
   /** Relays to use for offers */
@@ -102,7 +98,7 @@ export type ManagementHandler = (
  */
 export class CLINKClient {
   private nostrClient: NostrClient
-  private identity: MachineIdentity
+  private signer: Signer
   private operatorPubkeys: string[]
   private relays: string[]
   private generateInvoice?: GenerateInvoice
@@ -120,7 +116,7 @@ export class CLINKClient {
 
   constructor(options: CLINKClientOptions) {
     this.nostrClient = options.nostrClient
-    this.identity = options.identity
+    this.signer = options.signer
     this.operatorPubkeys = Array.isArray(options.operatorPubkey)
       ? options.operatorPubkey
       : [options.operatorPubkey]
@@ -144,7 +140,7 @@ export class CLINKClient {
     currency?: string
   }): string {
     const offer: CLINKOffer = {
-      pubkey: this.identity.publicKey,
+      pubkey: this.signer.pubkey,
       relays: this.relays,
       priceType: options.priceType,
       offerId: options.offerId,
@@ -193,7 +189,7 @@ export class CLINKClient {
       [
         {
           kinds: [CLINKEventKind.Offer, CLINKEventKind.Debit, CLINKEventKind.Manage],
-          '#p': [this.identity.publicKey],
+          '#p': [this.signer.pubkey],
         },
       ],
       {
@@ -234,9 +230,9 @@ export class CLINKClient {
       expires_in_seconds: options?.expiresInSeconds,
     }
 
-    const content = encryptCLINK(this.identity, offer.pubkey, request)
+    const content = await encryptCLINK(this.signer, offer.pubkey, request)
 
-    const event = this.createSignedEvent({
+    const event = await this.createSignedEvent({
       kind: CLINKEventKind.Offer,
       content,
       tags: [['p', offer.pubkey], CLINK_VERSION_TAG],
@@ -269,9 +265,9 @@ export class CLINKClient {
       description: options?.description,
     }
 
-    const content = encryptCLINK(this.identity, targetPubkey, request)
+    const content = await encryptCLINK(this.signer, targetPubkey, request)
 
-    const event = this.createSignedEvent({
+    const event = await this.createSignedEvent({
       kind: CLINKEventKind.Debit,
       content,
       tags: [['p', targetPubkey], CLINK_VERSION_TAG],
@@ -303,9 +299,9 @@ export class CLINKClient {
       description: options?.description,
     }
 
-    const content = encryptCLINK(this.identity, targetPubkey, request)
+    const content = await encryptCLINK(this.signer, targetPubkey, request)
 
-    const event = this.createSignedEvent({
+    const event = await this.createSignedEvent({
       kind: CLINKEventKind.Debit,
       content,
       tags: [['p', targetPubkey], CLINK_VERSION_TAG],
@@ -324,9 +320,9 @@ export class CLINKClient {
     targetPubkey: string,
     request: ManagementRequest
   ): Promise<ManagementResponse> {
-    const content = encryptCLINK(this.identity, targetPubkey, request)
+    const content = await encryptCLINK(this.signer, targetPubkey, request)
 
-    const event = this.createSignedEvent({
+    const event = await this.createSignedEvent({
       kind: CLINKEventKind.Manage,
       content,
       tags: [['p', targetPubkey], CLINK_VERSION_TAG],
@@ -394,15 +390,15 @@ export class CLINKClient {
       return
     }
 
-    const request = decryptCLINKJSON<OfferRequest>(this.identity, event.pubkey, event.content)
+    const request = await decryptCLINKJSON<OfferRequest>(this.signer, event.pubkey, event.content)
 
     const response = await this.offerHandler(request, event.pubkey)
     if (!response) return
 
     // Send encrypted response with clink_version tag
-    const content = encryptCLINK(this.identity, event.pubkey, response)
+    const content = await encryptCLINK(this.signer, event.pubkey, response)
 
-    const responseEvent = this.createSignedEvent({
+    const responseEvent = await this.createSignedEvent({
       kind: CLINKEventKind.Offer,
       content,
       tags: [['p', event.pubkey], ['e', event.id], CLINK_VERSION_TAG],
@@ -425,14 +421,14 @@ export class CLINKClient {
       return
     }
 
-    const request = decryptCLINKJSON<DebitRequest>(this.identity, event.pubkey, event.content)
+    const request = await decryptCLINKJSON<DebitRequest>(this.signer, event.pubkey, event.content)
 
     const response = await this.debitHandler(request, event.pubkey)
 
     // Send encrypted response with clink_version tag
-    const content = encryptCLINK(this.identity, event.pubkey, response)
+    const content = await encryptCLINK(this.signer, event.pubkey, response)
 
-    const responseEvent = this.createSignedEvent({
+    const responseEvent = await this.createSignedEvent({
       kind: CLINKEventKind.Debit,
       content,
       tags: [['p', event.pubkey], ['e', event.id], CLINK_VERSION_TAG],
@@ -491,15 +487,15 @@ export class CLINKClient {
       if (first) this.processedManageEvents.delete(first)
     }
 
-    const request = decryptCLINKJSON<ManagementRequest>(this.identity, event.pubkey, event.content)
+    const request = await decryptCLINKJSON<ManagementRequest>(this.signer, event.pubkey, event.content)
 
     const response = await this.managementHandler(request, event.pubkey)
     if (!response) return
 
     // Send encrypted response with clink_version tag
-    const content = encryptCLINK(this.identity, event.pubkey, response)
+    const content = await encryptCLINK(this.signer, event.pubkey, response)
 
-    const responseEvent = this.createSignedEvent({
+    const responseEvent = await this.createSignedEvent({
       kind: CLINKEventKind.Manage,
       content,
       tags: [['p', event.pubkey], ['e', event.id], CLINK_VERSION_TAG],
@@ -524,7 +520,7 @@ export class CLINKClient {
           {
             kinds: [kind],
             authors: [fromPubkey],
-            '#p': [this.identity.publicKey],
+            '#p': [this.signer.pubkey],
             '#e': [requestEventId],
             since: Math.floor(Date.now() / 1000) - 5,
           },
@@ -540,12 +536,7 @@ export class CLINKClient {
 
             clearTimeout(timeout)
             this.nostrClient.unsubscribe(subId)
-            try {
-              const response = decryptCLINKJSON<T>(this.identity, fromPubkey, event.content)
-              resolve(response)
-            } catch (e) {
-              reject(e)
-            }
+            decryptCLINKJSON<T>(this.signer, fromPubkey, event.content).then(resolve).catch(reject)
           },
         }
       )
@@ -553,11 +544,11 @@ export class CLINKClient {
   }
 
   /**
-   * Create a signed event
+   * Create a signed event via the signer (sets pubkey/id/sig). Async because
+   * a BunkerSigner is a relay round-trip.
    */
-  private createSignedEvent(event: Omit<UnsignedEvent, 'pubkey'>): Event {
-    // finalizeEvent derives pubkey from the secret key
-    return finalizeEvent(event, this.identity.privateKey)
+  private createSignedEvent(template: EventTemplate): Promise<Event> {
+    return this.signer.signEvent(template)
   }
 }
 

From 209e4c3e20e1fa1f8eaf64be90db742fc1294388 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 19 Jun 2026 00:15:31 +0200
Subject: [PATCH 09/82] feat(machine): seed + bunker-binding IPC bridge

get-atm-secrets now returns { spireSeed, bunkerBinding } instead of the raw
nsec (one-shot semantics kept). Adds IPC handlers + preload bindings for
saveBunkerBinding / clearBunkerBinding / resetBootstrapGate so the renderer
can persist a pairing and re-arm the cassette-state hello on re-pair (#56).
resetBootstrapGate added to state-store. Types mirrored in electron.d.ts.

Part of Phase C, aiolabs/bitspire#52.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/electron/main.ts        | 26 ++++++++++++++++++++++++--
 apps/machine/electron/preload.ts     | 28 +++++++++++++++++++++++++---
 apps/machine/electron/state-store.ts | 10 ++++++++++
 apps/machine/src/types/electron.d.ts | 19 ++++++++++++++++---
 4 files changed, 75 insertions(+), 8 deletions(-)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index fb5c84b..c35382d 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -26,14 +26,19 @@ import {
   getLastKnownConfigCreatedAt,
   getBootstrapPublishedAt,
   markBootstrapPublished,
+  resetBootstrapGate,
   applyOperatorCassettesConfig,
   getFeeConfig,
   getLastKnownFeeConfigCreatedAt,
   applyFeeConfig,
+  getBunkerBinding,
+  saveBunkerBinding,
+  clearBunkerBinding,
   type OperatorCassettesPayload,
   type FeeConfigPayload,
   type FeeConfigRow,
   type ApplyResult,
+  type StoredBunkerBinding,
 } from './state-store.js'
 import { initializeHal, type HalInstance } from './hal-service.js'
 
@@ -323,14 +328,31 @@ let secretsConsumed = false
 ipcMain.handle('get-atm-secrets', () => {
   if (secretsConsumed) {
     console.warn('[Electron] SECURITY: get-atm-secrets called after secrets already consumed')
-    return { atmPrivateKey: '' }
+    return { spireSeed: '', bunkerBinding: null }
   }
   secretsConsumed = true
+  // The spire pairing seed (one-shot connect token inside) + the persisted
+  // bunker binding (transport key). The renderer resolves these into a
+  // BunkerSigner; see services/signer-resolver.ts (aiolabs/bitspire#52).
   return {
-    atmPrivateKey: process.env.VITE_ATM_PRIVATE_KEY || '',
+    spireSeed: process.env.VITE_SPIRE_SEED || '',
+    bunkerBinding: getBunkerBinding(),
   }
 })
 
+// Bunker binding persistence — the renderer writes the binding after a
+// successful pairing (connectNewSeed), and resets the bootstrap gate so the
+// new operator receives the spire's hello-event (aiolabs/bitspire#52 / #56).
+ipcMain.handle('state:save-bunker-binding', (_event, binding: StoredBunkerBinding): void => {
+  saveBunkerBinding(binding)
+})
+ipcMain.handle('state:clear-bunker-binding', (): void => {
+  clearBunkerBinding()
+})
+ipcMain.handle('state:reset-bootstrap-gate', (): void => {
+  resetBootstrapGate()
+})
+
 // State persistence IPC handlers
 ipcMain.handle('state:load-cassettes', () => loadCassettes())
 ipcMain.handle('state:set-cassettes', (_event, cassettes) => setCassettes(cassettes))
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index 836b98d..f439de9 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -42,13 +42,25 @@ export interface BrandingConfig {
   logoDarkDataUrl: string | null
 }
 
+/**
+ * Persisted NIP-46 bunker binding (mirror of state-store's StoredBunkerBinding).
+ */
+export interface BunkerBindingRecord {
+  clientSecretHex: string
+  spirePubkey: string
+  bunkerUrl: string
+  seedFingerprint: string
+  pairedAt: number
+}
+
 /**
  * ATM secrets — returned once by getAtmSecrets(), then empty on subsequent calls.
+ * The spire pairing seed (carries the one-shot connect token) plus the persisted
+ * bunker binding; the renderer resolves these into a signer.
  */
 export interface AtmSecrets {
-  atmPrivateKey: string
-  /** Legacy LP admin token — retained until 3d removes the LP backend. */
-  adminToken?: string
+  spireSeed: string
+  bunkerBinding: BunkerBindingRecord | null
 }
 
 // Expose protected methods to renderer
@@ -100,6 +112,13 @@ contextBridge.exposeInMainWorld('electronAPI', {
     ipcRenderer.invoke('state:get-bootstrap-published-at'),
   markBootstrapPublished: (unixTimestamp: number): Promise<void> =>
     ipcRenderer.invoke('state:mark-bootstrap-published', unixTimestamp),
+
+  // Bunker binding persistence (aiolabs/bitspire#52)
+  saveBunkerBinding: (binding: BunkerBindingRecord): Promise<void> =>
+    ipcRenderer.invoke('state:save-bunker-binding', binding),
+  clearBunkerBinding: (): Promise<void> => ipcRenderer.invoke('state:clear-bunker-binding'),
+  resetBootstrapGate: (): Promise<void> => ipcRenderer.invoke('state:reset-bootstrap-gate'),
+
   applyOperatorCassettesConfig: (
     payload: {
       positions: Record<string, { denomination: number; count: number }>
@@ -212,6 +231,9 @@ declare global {
       getLastKnownConfigCreatedAt: () => Promise<number>
       getBootstrapPublishedAt: () => Promise<number | null>
       markBootstrapPublished: (unixTimestamp: number) => Promise<void>
+      saveBunkerBinding: (binding: BunkerBindingRecord) => Promise<void>
+      clearBunkerBinding: () => Promise<void>
+      resetBootstrapGate: () => Promise<void>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number
diff --git a/apps/machine/electron/state-store.ts b/apps/machine/electron/state-store.ts
index 8705aec..d9282ac 100644
--- a/apps/machine/electron/state-store.ts
+++ b/apps/machine/electron/state-store.ts
@@ -483,6 +483,16 @@ export function clearBunkerBinding(): void {
   db.prepare('DELETE FROM bunker_binding WHERE id = 1').run()
 }
 
+/**
+ * Reset the bootstrap-publish gate so the ATM re-publishes its
+ * `bitspire-cassettes-state` hello-event. Called on a re-pair (new seed) so
+ * the new operator receives the spire's current state (aiolabs/bitspire#56).
+ */
+export function resetBootstrapGate(): void {
+  if (!db) throw new Error('Database not initialized')
+  db.prepare('UPDATE meta SET value = ? WHERE key = ?').run('', 'bootstrapPublishedAt')
+}
+
 export type OperatorCassettesPayload = {
   positions: Record<string, { denomination: number; count: number }>
 }
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index 7830360..17fe9af 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -39,10 +39,20 @@ export interface BrandingConfig {
   logoDarkDataUrl: string | null
 }
 
+/** Persisted NIP-46 bunker binding (mirror of state-store's StoredBunkerBinding). */
+export interface BunkerBindingRecord {
+  clientSecretHex: string
+  spirePubkey: string
+  bunkerUrl: string
+  seedFingerprint: string
+  pairedAt: number
+}
+
 export interface AtmSecrets {
-  atmPrivateKey: string
-  /** Legacy LP admin token — retained until 3d removes the LP backend. */
-  adminToken?: string
+  /** Spire pairing seed URL (`spire-seed:v1:…`); carries the one-shot connect token. */
+  spireSeed: string
+  /** Persisted bunker binding, or null when the ATM is unpaired. */
+  bunkerBinding: BunkerBindingRecord | null
 }
 
 declare global {
@@ -85,6 +95,9 @@ declare global {
       getLastKnownConfigCreatedAt: () => Promise<number>
       getBootstrapPublishedAt: () => Promise<number | null>
       markBootstrapPublished: (unixTimestamp: number) => Promise<void>
+      saveBunkerBinding: (binding: BunkerBindingRecord) => Promise<void>
+      clearBunkerBinding: () => Promise<void>
+      resetBootstrapGate: () => Promise<void>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number

From 82a9e79d0ec5d2ebba33d345cfb610e3ea531207 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 19 Jun 2026 00:15:45 +0200
Subject: [PATCH 10/82] feat(machine): resolve signer from spire seed / bunker
 binding at bootstrap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New signer-resolver.ts turns the ATM's pairing state into a Signer:
 - seed present, fingerprint differs from stored binding → pair: generate a
   transport key, redeem the one-shot connect secret, persist the binding,
   reset the bootstrap gate (re-publish hello to the new operator, #56);
 - seed matches binding, or binding-only → resume (no re-redeem);
 - neither → ephemeral LocalSigner (dev) or throw (strict/prod).

lightning.ts drops the atmPrivateKey plumbing and calls resolveSigner; the
Phase-A Signer seam means nothing downstream changes. App.vue's maintenance
beacon resolves the same way (best-effort, skips if unpaired).

Part of Phase C, aiolabs/bitspire#52.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/src/App.vue                     |  13 +--
 apps/machine/src/services/lightning.ts       |  56 +++------
 apps/machine/src/services/signer-resolver.ts | 116 +++++++++++++++++++
 3 files changed, 138 insertions(+), 47 deletions(-)
 create mode 100644 apps/machine/src/services/signer-resolver.ts

diff --git a/apps/machine/src/App.vue b/apps/machine/src/App.vue
index 37882ba..652f708 100644
--- a/apps/machine/src/App.vue
+++ b/apps/machine/src/App.vue
@@ -51,14 +51,13 @@ onMounted(async () => {
     atmStore.initError = 'maintenance'
     // Publish maintenance beacon — minimal Nostr connection only (no Lightning.Pub)
     try {
-      const { NostrClient, LocalSigner, loadIdentityFromHex, createSignedEvent } = await import(
-        '@bitSpire/nostr-client'
-      )
-      const secrets = isElectron ? await window.electronAPI?.getAtmSecrets() : null
-      const privKey = secrets?.atmPrivateKey || import.meta.env.VITE_ATM_PRIVATE_KEY
+      const { NostrClient, createSignedEvent } = await import('@bitSpire/nostr-client')
+      const { resolveSigner } = await import('@/services/signer-resolver')
       const relayUrl = config?.relayUrl || import.meta.env.VITE_RELAY_URL
-      if (privKey && relayUrl) {
-        const signer = new LocalSigner(loadIdentityFromHex(privKey))
+      // Best-effort: resolve a signer (bunker resume / pairing, or dev nsec).
+      // If the ATM isn't paired yet, skip the beacon rather than fail the screen.
+      const signer = await resolveSigner({ allowEphemeral: true }).catch(() => null)
+      if (signer && relayUrl) {
         const client = new NostrClient({ relays: [{ url: relayUrl }], signer })
         await client.connect()
         const publishBeacon = async () => {
diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index 8154d4b..e975277 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -12,14 +12,8 @@
  * the customer's invoice.
  */
 
-import {
-  NostrClient,
-  LocalSigner,
-  generateIdentity,
-  loadIdentityFromHex,
-  type Signer,
-  type MachineIdentity,
-} from '@bitSpire/nostr-client'
+import { NostrClient, type Signer } from '@bitSpire/nostr-client'
+import { resolveSigner } from './signer-resolver.js'
 import { LnbitsClient } from '@bitSpire/lnbits'
 import { CLINKClient } from '@bitSpire/clink'
 import type { OfferRequest, ManagementRequest, ManagementResponse } from '@bitSpire/clink'
@@ -39,14 +33,12 @@ const isElectron = typeof window !== 'undefined' && window.electronAPI !== undef
  *
  * Environment variables:
  * - VITE_RELAY_URL: Nostr relay WebSocket URL
- * - VITE_LIGHTNING_PUB_PUBKEY: Lightning.Pub's Nostr pubkey (hex or npub)
- * - VITE_LIGHTNING_PUB_API_URL: Lightning.Pub HTTP API URL
- * - VITE_ATM_PRIVATE_KEY: ATM's Nostr private key (hex or nsec)   // pragma: allowlist secret
- * - VITE_ADMIN_TOKEN: Lightning.Pub admin token (dev only)
+ * - VITE_LNBITS_SERVER_PUBKEY: LNbits nostr-transport server pubkey (hex)
+ * - VITE_SPIRE_SEED: spire pairing seed (NIP-46 bunker); see signer-resolver.ts
+ * - VITE_OPERATOR_PUBKEYS: comma-separated operator pubkeys (hex)
  */
 interface LightningConfig {
   relayUrl: string
-  atmPrivateKey: string
   appId: string
   operatorPubkeys: string[]
   /** LNbits nostr-transport server pubkey (hex, 64 chars). */
@@ -63,7 +55,6 @@ interface LightningConfig {
 async function loadLightningConfig(): Promise<LightningConfig> {
   const defaults: LightningConfig = {
     relayUrl: 'ws://localhost:7777',
-    atmPrivateKey: '',
     appId: '30270e761f2e30b1737f34ce661df45f521352b408b8ed18fcc09f3f0dec5097', // bitSpire ATM app ID
     operatorPubkeys: [],
     lnbitsServerPubkey: '',
@@ -72,10 +63,8 @@ async function loadLightningConfig(): Promise<LightningConfig> {
   if (isElectron && window.electronAPI) {
     try {
       const rc = await window.electronAPI.getConfig()
-      const sec = await window.electronAPI.getAtmSecrets()
       return {
         relayUrl: rc.relayUrl || defaults.relayUrl,
-        atmPrivateKey: sec.atmPrivateKey || defaults.atmPrivateKey,
         appId: rc.appId || defaults.appId,
         operatorPubkeys: rc.operatorPubkeys
           ? rc.operatorPubkeys
@@ -92,7 +81,6 @@ async function loadLightningConfig(): Promise<LightningConfig> {
 
   return {
     relayUrl: import.meta.env.VITE_RELAY_URL || defaults.relayUrl,
-    atmPrivateKey: import.meta.env.VITE_ATM_PRIVATE_KEY || defaults.atmPrivateKey,
     appId: import.meta.env.VITE_APP_ID || defaults.appId,
     lnbitsServerPubkey:
       (import.meta.env.VITE_LNBITS_SERVER_PUBKEY as string | undefined) ||
@@ -416,15 +404,14 @@ export async function initializeLightningServices(options?: {
   console.log('[Lightning] Relay URL:', CONFIG.relayUrl)
   console.log('[Lightning] LNbits server pubkey:', CONFIG.lnbitsServerPubkey || '(not configured)')
 
-  // Strict mode: validate config is production-ready (no localhost, no ephemeral identity)
+  // Strict mode: validate config is production-ready (no localhost). The
+  // signing-identity check (a bunker pairing must exist) is enforced by
+  // resolveSigner below via allowEphemeral=false.
   if (options?.strict) {
     const errors: string[] = []
     if (/localhost|127\.0\.0\.1/.test(CONFIG.relayUrl)) {
       errors.push('VITE_RELAY_URL contains localhost')
     }
-    if (!CONFIG.atmPrivateKey) {
-      errors.push('VITE_ATM_PRIVATE_KEY is not set (ephemeral identity not allowed in production)')
-    }
     if (!CONFIG.lnbitsServerPubkey) {
       errors.push('VITE_LNBITS_SERVER_PUBKEY is not set')
     }
@@ -441,22 +428,13 @@ export async function initializeLightningServices(options?: {
     )
   }
 
-  // Load or generate ATM identity
-  let identity: MachineIdentity
-  if (CONFIG.atmPrivateKey) {
-    identity = loadIdentityFromHex(CONFIG.atmPrivateKey)
-    console.log('[Lightning] Loaded ATM identity from config')
-  } else {
-    identity = generateIdentity()
-    console.warn('[Lightning] No VITE_ATM_PRIVATE_KEY configured - generated ephemeral identity')
-    console.warn('[Lightning] Set VITE_ATM_PRIVATE_KEY for persistent identity across restarts')
-  }
-  console.log('[Lightning] ATM pubkey:', identity.publicKey)
-
-  // Wrap the identity in a signer. Phase A always uses LocalSigner (in-process
-  // nsec); Phase B swaps in a BunkerSigner here without touching the call
-  // sites below. See aiolabs/bitspire#52.
-  const signer: Signer = new LocalSigner(identity)
+  // Resolve the signing identity. In production this is a BunkerSigner over
+  // NIP-46 (the ATM holds only a transport key; the operator's nsecbunkerd
+  // holds the signing key); in dev it falls back to an in-process LocalSigner.
+  // The Phase-A Signer seam means nothing downstream changes. See
+  // aiolabs/bitspire#52.
+  const signer: Signer = await resolveSigner({ allowEphemeral: !options?.strict })
+  console.log('[Lightning] ATM pubkey:', signer.pubkey)
 
   // Create Nostr client
   const nostrClient = new NostrClient({
@@ -491,7 +469,7 @@ export async function initializeLightningServices(options?: {
   // commands; it has no Lightning.Pub dependency.
   const clink = new CLINKClient({
     nostrClient,
-    identity,
+    signer,
     operatorPubkey: CONFIG.operatorPubkeys,
     relays: [CONFIG.relayUrl],
   })
@@ -581,7 +559,6 @@ export async function initializeLightningServices(options?: {
   }
 
   const atmServices = createATMServices(
-    identity,
     (preimage) => {
       if (paymentReceivedCallback) {
         paymentReceivedCallback(preimage)
@@ -624,7 +601,6 @@ export async function initializeLightningServices(options?: {
  * Create ATMServices implementation using the LNbits nostr-transport.
  */
 function createATMServices(
-  _identity: MachineIdentity,
   onPaymentSuccess: (preimage: string) => void,
   lnbits: LnbitsClient,
   lnbitsWalletId: string,
diff --git a/apps/machine/src/services/signer-resolver.ts b/apps/machine/src/services/signer-resolver.ts
new file mode 100644
index 0000000..9bd0d5b
--- /dev/null
+++ b/apps/machine/src/services/signer-resolver.ts
@@ -0,0 +1,116 @@
+/**
+ * Signer resolution — turns the ATM's pairing state into a live `Signer`.
+ *
+ * Three outcomes, in priority order (aiolabs/bitspire#52, model A1):
+ *  1. A seed is present whose fingerprint differs from the stored binding
+ *     (first pair or re-pair) → generate a fresh NIP-46 transport key, redeem
+ *     the one-shot connect secret, persist the binding, and reset the
+ *     bootstrap gate so the (possibly new) operator gets a hello-event (#56).
+ *  2. A seed is present matching the stored binding, OR no seed but a stored
+ *     binding exists → resume the bunker session with the persisted transport
+ *     key (no re-redeem — the binding is server-persistent).
+ *  3. Neither → ephemeral LocalSigner, dev only. In strict (production) mode
+ *     this throws instead: no pairing means no signing identity.
+ *
+ * Runs in the renderer (where the relay I/O lives); state.db reads/writes go
+ * through the one-shot get-atm-secrets channel + the binding IPC handlers.
+ */
+
+import {
+  LocalSigner,
+  connectNewSeed,
+  resumeFromBinding,
+  generateClientTransportKey,
+  generateIdentity,
+  loadIdentityFromHex,
+  parseSpireSeed,
+  seedFingerprint,
+  type Signer,
+} from '@bitSpire/nostr-client'
+import type { BunkerBindingRecord } from '@/types/electron'
+
+const isElectron = typeof window !== 'undefined' && window.electronAPI !== undefined
+
+export interface ResolveSignerOptions {
+  /** Allow an ephemeral LocalSigner when no seed/binding exists (dev only). */
+  allowEphemeral: boolean
+}
+
+interface PairingState {
+  spireSeed: string
+  binding: BunkerBindingRecord | null
+}
+
+/** Gather the seed + persisted binding from Electron, or env in browser dev. */
+async function loadPairingState(): Promise<PairingState> {
+  if (isElectron && window.electronAPI) {
+    const secrets = await window.electronAPI.getAtmSecrets()
+    return { spireSeed: secrets.spireSeed || '', binding: secrets.bunkerBinding ?? null }
+  }
+  return { spireSeed: (import.meta.env.VITE_SPIRE_SEED as string | undefined) || '', binding: null }
+}
+
+export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer> {
+  const { spireSeed, binding } = await loadPairingState()
+
+  if (spireSeed) {
+    const seed = parseSpireSeed(spireSeed)
+    const fingerprint = seedFingerprint(spireSeed)
+
+    if (binding && binding.seedFingerprint === fingerprint) {
+      console.log('[Signer] Resuming bunker session for spire', seed.spirePubkey)
+      return resumeFromBinding({
+        clientSecretHex: binding.clientSecretHex,
+        spirePubkey: binding.spirePubkey,
+        bunkerUrl: binding.bunkerUrl,
+      })
+    }
+
+    // First pair or re-pair: redeem the one-shot connect secret.
+    console.log('[Signer] Pairing to bunker for spire', seed.spirePubkey)
+    const transport = generateClientTransportKey()
+    const signer = await connectNewSeed({
+      spirePubkey: seed.spirePubkey,
+      bunkerUrl: seed.bunkerUrl,
+      clientSecretHex: transport.secretHex,
+    })
+    if (isElectron && window.electronAPI) {
+      await window.electronAPI.saveBunkerBinding({
+        clientSecretHex: transport.secretHex,
+        spirePubkey: seed.spirePubkey,
+        bunkerUrl: seed.bunkerUrl,
+        seedFingerprint: fingerprint,
+        pairedAt: Math.floor(Date.now() / 1000),
+      })
+      // Re-pair → re-publish the cassette-state hello to the new operator (#56).
+      await window.electronAPI.resetBootstrapGate()
+    }
+    return signer
+  }
+
+  // No seed in this boot but a binding survives → resume.
+  if (binding) {
+    console.log('[Signer] Resuming bunker session from stored binding (no seed this boot)')
+    return resumeFromBinding({
+      clientSecretHex: binding.clientSecretHex,
+      spirePubkey: binding.spirePubkey,
+      bunkerUrl: binding.bunkerUrl,
+    })
+  }
+
+  if (opts.allowEphemeral) {
+    // Dev-only: a hex key gives a stable dev identity; otherwise ephemeral.
+    const devKey = !isElectron ? (import.meta.env.VITE_ATM_PRIVATE_KEY as string | undefined) : ''
+    if (devKey) {
+      console.warn('[Signer] No bunker pairing — using LocalSigner from VITE_ATM_PRIVATE_KEY (dev)')
+      return new LocalSigner(loadIdentityFromHex(devKey))
+    }
+    console.warn('[Signer] No bunker pairing — generated ephemeral LocalSigner (dev only)')
+    return new LocalSigner(generateIdentity())
+  }
+
+  throw new Error(
+    '[Signer] No spire seed and no bunker binding — cannot resolve a signing identity (strict mode). ' +
+      'Set VITE_SPIRE_SEED or pair the ATM.'
+  )
+}

From 0391dbaeb029fad707d2632cfb26b15c32623ddf Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 19 Jun 2026 00:15:59 +0200
Subject: [PATCH 11/82] chore(machine): fund-atm resumes from binding;
 VITE_SPIRE_SEED docs/env
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

fund-atm resolves its signer by resuming the bunker binding from state.db
(the connect token is already spent by the main app, so it can't re-pair);
falls back to a dev nsec via VITE_ATM_PRIVATE_KEY. better-sqlite3 marked
external in the esbuild bundle. .env.example + CLAUDE.md document
VITE_SPIRE_SEED as the prod identity, VITE_ATM_PRIVATE_KEY as dev-only.

(fund-atm is slated for deprecation in favour of the operator funding the
wallet directly via the LNbits UI — kept working for now.)

Part of Phase C, aiolabs/bitspire#52.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                         |  5 +++--
 apps/machine/.env.example         | 19 +++++++++++------
 apps/machine/electron/fund-atm.ts | 34 +++++++++++++++++++++++++++----
 apps/machine/package.json         |  2 +-
 4 files changed, 47 insertions(+), 13 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 20ba0df..4f86331 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -84,7 +84,8 @@ Renderer reads (Electron IPC or Vite `import.meta.env`):
 |---|---|---|
 | `VITE_RELAY_URL` | yes | `ws://...` of the relay both ATM and LNbits subscribe to. Dev: `ws://localhost:5001/nostrrelay/test` (LNbits's bundled `nostrrelay` extension — no separate strfry container) |
 | `VITE_LNBITS_SERVER_PUBKEY` | yes | 64-char hex pubkey LNbits prints on startup (`docker logs lnbits \| grep 'Public key (share this)'`) |
-| `VITE_ATM_PRIVATE_KEY` | yes (prod) | 64-char hex. The ATM's nostr identity. Generates ephemeral on first boot if unset (dev only) |
+| `VITE_SPIRE_SEED` | yes (prod) | Spire pairing seed (`spire-seed:v1:<base64url>`) from spirekeeper. Carries a one-shot NIP-46 connect token + the spire signing pubkey + bunker URL. First boot redeems it and persists the binding to `state.db`; later boots resume by fingerprint. A changed seed re-pairs. See aiolabs/bitspire#52. |
+| `VITE_ATM_PRIVATE_KEY` | dev only | 64-char hex raw nsec fallback for running without a bunker. Ignored when `VITE_SPIRE_SEED` or a stored binding exists. |
 | `VITE_OPERATOR_PUBKEYS` | optional | Comma-separated hex pubkeys allowed to send kind-21003 management commands |
 
 The LP-era vars (`VITE_LIGHTNING_PUB_PUBKEY`, `VITE_LIGHTNING_PUB_API_URL`, `VITE_EXTENSION_API_URL`, `VITE_ADMIN_TOKEN`) are gone from the dev branch's `.env.example` and `LightningConfig` interface.
@@ -188,7 +189,7 @@ UP Board enumerates its eMMC controller via ACPI, not PCI. `upboard.nix` force-l
 
 ## Security priorities
 
-1. **Private keys** — Never log nsec. The ATM's `VITE_ATM_PRIVATE_KEY` lives in `/var/lib/bitspire/.env` with mode 0600, owned by `bitspire:bitspire`.
+1. **Private keys** — Never log nsec. In production the ATM holds no signing nsec: `VITE_SPIRE_SEED` (in `/var/lib/bitspire/.env`, mode 0600) carries a one-shot connect token, and the ATM's own NIP-46 *transport* key (`client_secret_hex`) lives in `state.db` (`bunker_binding`). The operator's signing key stays in the bunker. The legacy `VITE_ATM_PRIVATE_KEY` is a dev-only fallback.
 2. **Payments** — Validate the bolt11 amount on cash-out before exposing the QR. Decode `payment_hash` from the bolt11 (cheap, avoids a roundtrip) and use it as the `subscribe_payments` filter.
 3. **Replay** — LNURL-withdraw links use `uses:1` and are deleted on session abort.
 4. **Encryption** — All RPC content is NIP-44 v2. NIP-04 is forbidden.
diff --git a/apps/machine/.env.example b/apps/machine/.env.example
index 73b6281..e691e46 100644
--- a/apps/machine/.env.example
+++ b/apps/machine/.env.example
@@ -36,16 +36,23 @@ VITE_LNBITS_SERVER_PUBKEY=
 # aiolabs/withdraw#1 / commit e9d911e.)
 
 # =============================================================================
-# ATM Identity
+# ATM Identity — spire pairing seed (NIP-46 bunker; aiolabs/bitspire#52)
 # =============================================================================
 
+# The spire pairing seed produced by the operator dashboard (spirekeeper):
+#   spire-seed:v1:<base64url>
+# It carries a one-shot NIP-46 connect token + the spire's signing pubkey +
+# the bunker URL. On first boot the ATM redeems the token, generates its own
+# transport key, and persists the binding to state.db; thereafter it resumes
+# from the binding (the seed can stay set — it's matched by fingerprint).
+# A changed seed re-pairs (and re-publishes the cassette-state hello).
+VITE_SPIRE_SEED=
+
 # pragma: allowlist secret
-# ATM's Nostr private key (hex format, 64 characters). This signing
-# key IS the credential — LNbits derives the account from it on first
-# contact (issue aiolabs/lnbits#9 alignment).
+# DEV ONLY fallback — a raw Nostr private key (hex, 64 chars) for running
+# without a bunker. Ignored when VITE_SPIRE_SEED or a stored binding exists.
 # Generate with: openssl rand -hex 32
-# If not set, generates ephemeral identity on each restart (dev only).
-VITE_ATM_PRIVATE_KEY=
+# VITE_ATM_PRIVATE_KEY=
 
 # =============================================================================
 # Operator Identity
diff --git a/apps/machine/electron/fund-atm.ts b/apps/machine/electron/fund-atm.ts
index bce6b4c..cd0f901 100644
--- a/apps/machine/electron/fund-atm.ts
+++ b/apps/machine/electron/fund-atm.ts
@@ -13,8 +13,15 @@
  */
 
 import { readFileSync } from 'node:fs'
-import { NostrClient, LocalSigner, loadIdentityFromHex } from '@bitSpire/nostr-client'
+import {
+  NostrClient,
+  LocalSigner,
+  loadIdentityFromHex,
+  resumeFromBinding,
+  type Signer,
+} from '@bitSpire/nostr-client'
 import { LnbitsClient } from '@bitSpire/lnbits'
+import { initDatabase, getBunkerBinding } from './state-store.js'
 
 // @ts-ignore — qrcode is a transitive dep (via qrcode.vue), no types needed
 import QRCode from 'qrcode'
@@ -56,15 +63,34 @@ async function main() {
   const lnbitsServerPubkey = env['VITE_LNBITS_SERVER_PUBKEY']
   const atmPrivateKey = env['VITE_ATM_PRIVATE_KEY']
 
-  if (!relayUrl || !lnbitsServerPubkey || !atmPrivateKey) {
+  if (!relayUrl || !lnbitsServerPubkey) {
     console.error('Missing required config in', envPath)
-    console.error('Need: VITE_RELAY_URL, VITE_LNBITS_SERVER_PUBKEY, VITE_ATM_PRIVATE_KEY')
+    console.error('Need: VITE_RELAY_URL, VITE_LNBITS_SERVER_PUBKEY')
     process.exit(1)
   }
 
   console.error(`Generating invoice for ${amountSats} sats...`)
 
-  const signer = new LocalSigner(loadIdentityFromHex(atmPrivateKey))
+  // Resolve the signer. Prod: resume the bunker binding from state.db (the
+  // ATM's transport key — the connect token was already redeemed by the main
+  // app, so we can't re-pair here). Dev: a local nsec via VITE_ATM_PRIVATE_KEY.
+  let signer: Signer
+  if (atmPrivateKey) {
+    signer = new LocalSigner(loadIdentityFromHex(atmPrivateKey))
+  } else {
+    initDatabase()
+    const binding = getBunkerBinding()
+    if (!binding) {
+      console.error('ATM is not paired (no bunker binding in state.db) and no')
+      console.error('VITE_ATM_PRIVATE_KEY set. Pair the ATM via the main app first.')
+      process.exit(1)
+    }
+    signer = await resumeFromBinding({
+      clientSecretHex: binding.clientSecretHex,
+      spirePubkey: binding.spirePubkey,
+      bunkerUrl: binding.bunkerUrl,
+    })
+  }
 
   const nostrClient = new NostrClient({
     relays: [{ url: relayUrl }],
diff --git a/apps/machine/package.json b/apps/machine/package.json
index dfc3336..844211c 100644
--- a/apps/machine/package.json
+++ b/apps/machine/package.json
@@ -14,7 +14,7 @@
     "dev": "concurrently -n vite,electron \"vite\" \"pnpm run electron:dev\"",
     "dev:vite": "vite",
     "electron:dev": "tsc -p electron/tsconfig.json && tsc -p electron/tsconfig.preload.json && electron dist-electron/main.js",
-    "build": "vue-tsc --noEmit && vite build && tsc -p electron/tsconfig.json && tsc -p electron/tsconfig.preload.json && npx esbuild electron/fund-atm.ts --bundle --platform=node --format=cjs --outfile=dist-electron/fund-atm.bundle.cjs",
+    "build": "vue-tsc --noEmit && vite build && tsc -p electron/tsconfig.json && tsc -p electron/tsconfig.preload.json && npx esbuild electron/fund-atm.ts --bundle --platform=node --format=cjs --external:better-sqlite3 --outfile=dist-electron/fund-atm.bundle.cjs",
     "build:electron": "pnpm build && electron-builder",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",

From 09ed5e95deb94fea224d88e4a1ffebee2c4af42f Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 19 Jun 2026 23:19:58 +0200
Subject: [PATCH 12/82] docs(nostr-client): TTL expiry is now a post-bind
 deauth cause
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

nsecbunkerd#27 enforces token lifecycle at sign time (Option D): an expired
token (`expiresAt`) now stops signing post-bind, not just at connect —
reversing the earlier #24 "TTL is connect-window-only" note. A lapsed TTL
now surfaces as the same BunkerRejectedError as a revoke, so the Phase D
re-pair handling covers both. Docstring corrected to say so.

refs nsecbunkerd#27/#24/#25, aiolabs/bitspire#52

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/nostr-client/src/bunker-signer.ts | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/nostr-client/src/bunker-signer.ts b/packages/nostr-client/src/bunker-signer.ts
index ed80f02..642b570 100644
--- a/packages/nostr-client/src/bunker-signer.ts
+++ b/packages/nostr-client/src/bunker-signer.ts
@@ -29,9 +29,11 @@ import type { Signer } from './signer.js'
 const DEFAULT_BUNKER_TIMEOUT_MS = 10_000
 
 /**
- * Raised when the bunker actively rejects a request (e.g. the operator
- * revoked the spire's binding, or a kind/method is outside the policy).
- * Callers should treat this as "unpaired" and surface a re-pair prompt.
+ * Raised when the bunker actively rejects a request. Post-bind causes
+ * (nsecbunkerd#27, sign-time lifecycle enforcement): the operator revoked the
+ * binding (`KeyUser`/`Token.revokedAt`), the token's TTL (`expiresAt`) lapsed,
+ * or the requested kind/method is outside the policy. Callers should treat
+ * this as "unpaired" and surface a re-pair prompt.
  */
 export class BunkerRejectedError extends Error {
   constructor(message: string) {

From b0ac34ee01a70fc10311c3d21db3c2d2f5e62b49 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 19 Jun 2026 23:29:50 +0200
Subject: [PATCH 13/82] feat(lnbits): typed nostr-transport error codes + retry
 policy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements the error-handling layer agreed in the 2026-05-26 cross-session
handshake (aiolabs/bitspire#52). LnbitsClient now rejects ERROR responses
with a typed LnbitsRpcError carrying the machine-readable code + its retry
disposition, so callers (and the state machine, Phase D.3) branch on
disposition rather than string-matching the human-readable message.

- error-codes.ts: LnbitsErrorCode (14 codes, signer/transport/app classes)
  mirroring the lnbits canonical enum; retryPolicyFor() classifier;
  LnbitsRpcError.fromResponse().
- error_code is optional-additive on the wire: an absent or unknown code
  maps to internal_error (retry-once), so this is safe to land before lnbits
  emits codes — no string-matching, no special parser paths.
- invoice_already_paid is flagged terminal-idempotent (isIdempotentSuccess)
  for the cash-out resume-after-reboot case.

Part of Phase D, aiolabs/bitspire#52.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../lnbits/src/__tests__/error-codes.test.ts  |  79 ++++++++++
 packages/lnbits/src/client.ts                 |   3 +-
 packages/lnbits/src/error-codes.ts            | 143 ++++++++++++++++++
 packages/lnbits/src/index.ts                  |   7 +
 packages/lnbits/src/types.ts                  |   5 +
 5 files changed, 236 insertions(+), 1 deletion(-)
 create mode 100644 packages/lnbits/src/__tests__/error-codes.test.ts
 create mode 100644 packages/lnbits/src/error-codes.ts

diff --git a/packages/lnbits/src/__tests__/error-codes.test.ts b/packages/lnbits/src/__tests__/error-codes.test.ts
new file mode 100644
index 0000000..7420810
--- /dev/null
+++ b/packages/lnbits/src/__tests__/error-codes.test.ts
@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest'
+import {
+  LnbitsErrorCode,
+  LnbitsRpcError,
+  parseErrorCode,
+  retryPolicyFor,
+} from '../error-codes.js'
+
+describe('parseErrorCode', () => {
+  it('recognizes every canonical code', () => {
+    for (const code of Object.values(LnbitsErrorCode)) {
+      expect(parseErrorCode(code)).toBe(code)
+    }
+  })
+
+  it('returns null for unknown / absent codes', () => {
+    expect(parseErrorCode('made_up_code')).toBeNull()
+    expect(parseErrorCode(undefined)).toBeNull()
+    expect(parseErrorCode(null)).toBeNull()
+    expect(parseErrorCode('')).toBeNull()
+  })
+})
+
+describe('retryPolicyFor', () => {
+  it('classifies the signer + transport + app codes as agreed', () => {
+    expect(retryPolicyFor(LnbitsErrorCode.OperatorSignerUnavailable)).toBe('retry-backoff')
+    expect(retryPolicyFor(LnbitsErrorCode.OperatorSignerRejected)).toBe('terminal')
+    expect(retryPolicyFor(LnbitsErrorCode.RateLimited)).toBe('retry-long-backoff')
+    expect(retryPolicyFor(LnbitsErrorCode.InternalError)).toBe('retry-once')
+    expect(retryPolicyFor(LnbitsErrorCode.InvoiceAlreadyPaid)).toBe('terminal-idempotent')
+    expect(retryPolicyFor(LnbitsErrorCode.InsufficientBalance)).toBe('terminal')
+  })
+
+  it('has a policy for every code (exhaustive map)', () => {
+    for (const code of Object.values(LnbitsErrorCode)) {
+      expect(retryPolicyFor(code)).toBeTruthy()
+    }
+  })
+})
+
+describe('LnbitsRpcError.fromResponse', () => {
+  it('maps a known error_code through', () => {
+    const err = LnbitsRpcError.fromResponse('pay_invoice', {
+      request_id: 'pay-1',
+      error_code: 'insufficient_balance',
+      error: 'not enough sats',
+    })
+    expect(err).toBeInstanceOf(LnbitsRpcError)
+    expect(err.code).toBe(LnbitsErrorCode.InsufficientBalance)
+    expect(err.rpcName).toBe('pay_invoice')
+    expect(err.requestId).toBe('pay-1')
+    expect(err.message).toBe('not enough sats')
+    expect(err.retryPolicy).toBe('terminal')
+    expect(err.isRetryable).toBe(false)
+  })
+
+  it('treats an ABSENT error_code as internal_error (retry-once)', () => {
+    const err = LnbitsRpcError.fromResponse('get_wallet', { request_id: 'w-1' })
+    expect(err.code).toBe(LnbitsErrorCode.InternalError)
+    expect(err.retryPolicy).toBe('retry-once')
+    expect(err.isRetryable).toBe(true)
+  })
+
+  it('treats an UNKNOWN error_code as internal_error', () => {
+    const err = LnbitsRpcError.fromResponse('get_wallet', {
+      request_id: 'w-2',
+      error_code: 'brand_new_code_we_dont_know',
+    })
+    expect(err.code).toBe(LnbitsErrorCode.InternalError)
+  })
+
+  it('flags invoice_already_paid as idempotent-success', () => {
+    const err = LnbitsRpcError.fromResponse('pay_invoice', {
+      request_id: 'p-1',
+      error_code: 'invoice_already_paid',
+    })
+    expect(err.isIdempotentSuccess).toBe(true)
+  })
+})
diff --git a/packages/lnbits/src/client.ts b/packages/lnbits/src/client.ts
index 76b796e..946df5d 100644
--- a/packages/lnbits/src/client.ts
+++ b/packages/lnbits/src/client.ts
@@ -26,6 +26,7 @@ import {
   type Event as NostrEvent,
 } from '@bitSpire/nostr-client'
 import { verifyEvent } from 'nostr-tools'
+import { LnbitsRpcError } from './error-codes.js'
 
 import type {
   LnbitsConfig,
@@ -478,7 +479,7 @@ export class LnbitsClient {
           clearTimeout(timer)
           this.pending.delete(requestId)
           if (response.status === 'ERROR') {
-            reject(new Error(response.error ?? `${rpcName}: server returned ERROR`))
+            reject(LnbitsRpcError.fromResponse(rpcName, response))
             return
           }
           resolve(response.data as T)
diff --git a/packages/lnbits/src/error-codes.ts b/packages/lnbits/src/error-codes.ts
new file mode 100644
index 0000000..1944664
--- /dev/null
+++ b/packages/lnbits/src/error-codes.ts
@@ -0,0 +1,143 @@
+/**
+ * LNbits nostr-transport error taxonomy.
+ *
+ * Machine-readable discriminators for kind-21000 ERROR responses. Mirror of
+ * the lnbits canonical enum (`core/services/nostr_transport/error_codes.py`)
+ * and the vocabulary table in `docs/devs/nostr-transport.md`. Drift detection
+ * = diff this enum against that table. Agreed in the 2026-05-26 cross-session
+ * handshake on aiolabs/bitspire#52.
+ *
+ * Wire shape (additive to the existing envelope):
+ *   { "status": "ERROR", "request_id": "...", "error_code": "...", "error": "..." }
+ *
+ * `error_code` is optional-additive for one lnbits release, then required.
+ * An ABSENT `error_code` is treated as `internal_error` (retry-once) — we do
+ * not string-match the human-readable `error`. So un-migrated handlers get a
+ * safe retry-then-surface default with no special parser paths.
+ */
+
+export enum LnbitsErrorCode {
+  // signer class — the operator's signer (bunker) on the LNbits side
+  OperatorSignerUnavailable = 'operator_signer_unavailable',
+  OperatorSignerRejected = 'operator_signer_rejected',
+  OperatorSignerUnconfigured = 'operator_signer_unconfigured',
+  // transport class
+  Unauthorized = 'unauthorized',
+  RateLimited = 'rate_limited',
+  UnknownMethod = 'unknown_method',
+  InvalidParams = 'invalid_params',
+  InternalError = 'internal_error',
+  // app class
+  WalletNotFound = 'wallet_not_found',
+  InsufficientBalance = 'insufficient_balance',
+  InvoiceAlreadyPaid = 'invoice_already_paid',
+  InvoiceExpired = 'invoice_expired',
+  PaymentFailed = 'payment_failed',
+  AccountNotFound = 'account_not_found',
+}
+
+/**
+ * Retry disposition for an error code:
+ * - `retry-backoff` — transient; retry with short exponential backoff.
+ * - `retry-long-backoff` — rate-limited; retry with a longer backoff.
+ * - `retry-once` — retry exactly once, then surface (the `internal_error` default).
+ * - `terminal` — do not retry; surface to the user.
+ * - `terminal-idempotent` — terminal, but the operation already took effect
+ *   (e.g. `invoice_already_paid` — a cash-out watcher treats it as settled).
+ */
+export type RetryPolicy =
+  | 'retry-backoff'
+  | 'retry-long-backoff'
+  | 'retry-once'
+  | 'terminal'
+  | 'terminal-idempotent'
+
+const RETRY_POLICIES: Record<LnbitsErrorCode, RetryPolicy> = {
+  [LnbitsErrorCode.OperatorSignerUnavailable]: 'retry-backoff',
+  [LnbitsErrorCode.OperatorSignerRejected]: 'terminal',
+  [LnbitsErrorCode.OperatorSignerUnconfigured]: 'terminal',
+  [LnbitsErrorCode.Unauthorized]: 'terminal',
+  [LnbitsErrorCode.RateLimited]: 'retry-long-backoff',
+  [LnbitsErrorCode.UnknownMethod]: 'terminal',
+  [LnbitsErrorCode.InvalidParams]: 'terminal',
+  [LnbitsErrorCode.InternalError]: 'retry-once',
+  [LnbitsErrorCode.WalletNotFound]: 'terminal',
+  [LnbitsErrorCode.InsufficientBalance]: 'terminal',
+  [LnbitsErrorCode.InvoiceAlreadyPaid]: 'terminal-idempotent',
+  [LnbitsErrorCode.InvoiceExpired]: 'terminal',
+  // payment_failed is terminal-with-detail: the sub-reason rides in `error`.
+  [LnbitsErrorCode.PaymentFailed]: 'terminal',
+  [LnbitsErrorCode.AccountNotFound]: 'terminal',
+}
+
+const RETRYABLE: ReadonlySet<RetryPolicy> = new Set<RetryPolicy>([
+  'retry-backoff',
+  'retry-long-backoff',
+  'retry-once',
+])
+
+/** Parse a wire string into a known code, or null if unrecognized. */
+export function parseErrorCode(raw: string | undefined | null): LnbitsErrorCode | null {
+  if (!raw) return null
+  return (Object.values(LnbitsErrorCode) as string[]).includes(raw)
+    ? (raw as LnbitsErrorCode)
+    : null
+}
+
+/** Retry disposition for a code. */
+export function retryPolicyFor(code: LnbitsErrorCode): RetryPolicy {
+  return RETRY_POLICIES[code]
+}
+
+/**
+ * Typed error thrown by `LnbitsClient` on an ERROR response. Carries the
+ * machine-readable `code` + its `retryPolicy` so callers (and the state
+ * machine) branch on disposition rather than string-matching `message`.
+ */
+export class LnbitsRpcError extends Error {
+  readonly code: LnbitsErrorCode
+  readonly rpcName: string
+  readonly requestId: string
+  readonly retryPolicy: RetryPolicy
+
+  constructor(args: {
+    code: LnbitsErrorCode
+    rpcName: string
+    requestId: string
+    message?: string
+  }) {
+    super(args.message ?? `${args.rpcName}: ${args.code}`)
+    this.name = 'LnbitsRpcError'
+    this.code = args.code
+    this.rpcName = args.rpcName
+    this.requestId = args.requestId
+    this.retryPolicy = retryPolicyFor(args.code)
+  }
+
+  /**
+   * Build from a wire ERROR response. An absent/unknown `error_code` maps to
+   * `internal_error` (retry-once) per the deprecation-window contract.
+   */
+  static fromResponse(
+    rpcName: string,
+    response: { request_id: string; error_code?: string | null; error?: string }
+  ): LnbitsRpcError {
+    const code = parseErrorCode(response.error_code) ?? LnbitsErrorCode.InternalError
+    return new LnbitsRpcError({
+      code,
+      rpcName,
+      requestId: response.request_id,
+      message: response.error ?? `${rpcName}: server returned ERROR (${code})`,
+    })
+  }
+
+  /** True when the disposition permits a retry (any backoff/once policy). */
+  get isRetryable(): boolean {
+    return RETRYABLE.has(this.retryPolicy)
+  }
+
+  /** True when the operation already took effect despite the error. */
+  get isIdempotentSuccess(): boolean {
+    return this.retryPolicy === 'terminal-idempotent'
+  }
+}
diff --git a/packages/lnbits/src/index.ts b/packages/lnbits/src/index.ts
index 34463dc..10e0f05 100644
--- a/packages/lnbits/src/index.ts
+++ b/packages/lnbits/src/index.ts
@@ -49,6 +49,13 @@
  */
 
 export { LnbitsClient } from './client.js'
+export {
+  LnbitsErrorCode,
+  LnbitsRpcError,
+  parseErrorCode,
+  retryPolicyFor,
+} from './error-codes.js'
+export type { RetryPolicy } from './error-codes.js'
 export type {
   LnbitsConfig,
   LnbitsRpcRequest,
diff --git a/packages/lnbits/src/types.ts b/packages/lnbits/src/types.ts
index 6372182..c040b3c 100644
--- a/packages/lnbits/src/types.ts
+++ b/packages/lnbits/src/types.ts
@@ -39,7 +39,12 @@ export interface LnbitsRpcResponse<T = unknown> {
   /** Non-null on subscription push events. Null on regular acks. */
   subscription_id?: string | null
   data?: T
+  /** Human-readable error detail (ERROR status only). */
   error?: string
+  /** Machine-readable error discriminator (ERROR status). Optional-additive
+   *  for one lnbits release, then required; absent → internal_error. See
+   *  error-codes.ts (aiolabs/bitspire#52). */
+  error_code?: string
 }
 
 // ============================================================================

From 78d54cdc94a7539eadafc831c7af365d408c0bfe Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 19 Jun 2026 23:34:07 +0200
Subject: [PATCH 14/82] feat(machine): re-pair UX on bunker deauth at boot

A revoked / TTL-expired / off-policy bunker binding now surfaces a dedicated
"Pairing Required" screen instead of a raw error, and a signer/relay timeout
shows "Signer Unreachable" (transient). Shared classifyInitError() maps the
typed BunkerRejectedError / BunkerTimeoutError (by name, so it survives bundle
boundaries) to maintenance-screen sentinels, used at every store init catch +
the App.vue fallback. App.vue's nested-ternary screen copy refactored to a
keyed map (cleaner, and the new screens drop in).

Scope: boot-time detection (covers the dominant restart-after-revoke case).
Mid-session re-pair detection (flipping the screen when a sign fails during a
live flow) is a deliberate follow-up.

Part of Phase D, aiolabs/bitspire#52.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/src/App.vue                      | 65 +++++++++++++------
 .../src/services/__tests__/init-error.test.ts | 30 +++++++++
 apps/machine/src/services/init-error.ts       | 17 +++++
 apps/machine/src/stores/atm.ts                |  7 +-
 4 files changed, 96 insertions(+), 23 deletions(-)
 create mode 100644 apps/machine/src/services/__tests__/init-error.test.ts
 create mode 100644 apps/machine/src/services/init-error.ts

diff --git a/apps/machine/src/App.vue b/apps/machine/src/App.vue
index 652f708..48cfc8a 100644
--- a/apps/machine/src/App.vue
+++ b/apps/machine/src/App.vue
@@ -4,6 +4,7 @@ import { useRoute } from 'vue-router'
 import { useAtmStore } from '@/stores/atm'
 import { useTheme } from '@/composables/useTheme'
 import { setBranding } from '@/composables/useBranding'
+import { classifyInitError } from '@/services/init-error'
 import { Badge } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { Sun, Moon } from 'lucide-vue-next'
@@ -20,6 +21,46 @@ function formatSats(sats: number): string {
   return sats.toLocaleString()
 }
 
+/**
+ * Maintenance-screen copy keyed by the `initError` sentinel. Falls back to a
+ * generic out-of-service message (the raw error text shows under debug only).
+ */
+const MAINTENANCE_SCREENS: Record<string, { title: string; message: string }> = {
+  maintenance: {
+    title: 'Under Service',
+    message: 'This machine is currently being serviced. We will be back shortly.',
+  },
+  'awaiting-fees': {
+    title: 'Awaiting Configuration',
+    message:
+      'Awaiting fee configuration from operator. Contact operator to publish initial fee config.',
+  },
+  unpaired: {
+    title: 'Pairing Required',
+    message:
+      'This machine needs to be re-paired by the operator before it can accept transactions.',
+  },
+  'signer-unreachable': {
+    title: 'Signer Unreachable',
+    message: 'Cannot reach the signing service right now. This usually resolves shortly.',
+  },
+}
+
+const GENERIC_SCREEN = {
+  title: 'ATM Unavailable',
+  message:
+    'This machine is temporarily out of service. Please try again later or use another machine.',
+}
+
+const maintenanceScreen = computed(() =>
+  atmStore.initError ? (MAINTENANCE_SCREENS[atmStore.initError] ?? GENERIC_SCREEN) : GENERIC_SCREEN
+)
+
+/** True when the screen is a known sentinel (hide the raw debug error line). */
+const isKnownMaintenanceScreen = computed(
+  () => !!atmStore.initError && atmStore.initError in MAINTENANCE_SCREENS
+)
+
 const formattedBtcPrice = computed(() => {
   if (atmStore.btcPrice === null) return null
   const local = `${atmStore.fiatCode}/BTC: ${atmStore.fiatSymbol}${Math.round(atmStore.btcPrice).toLocaleString()}`
@@ -96,7 +137,7 @@ onMounted(async () => {
     atmStore.startPricePolling()
   } catch (error) {
     console.error('[App] Initialization failed:', error)
-    atmStore.initError = error instanceof Error ? error.message : 'Initialization failed'
+    atmStore.initError = classifyInitError(error)
   }
 })
 
@@ -141,29 +182,13 @@ function toggleLiveServices() {
         <line x1="12" y1="17" x2="12.01" y2="17" />
       </svg>
       <h1 class="text-2xl lg:text-[3.5rem] font-bold">
-        {{
-          atmStore.initError === 'maintenance'
-            ? 'Under Service'
-            : atmStore.initError === 'awaiting-fees'
-              ? 'Awaiting Configuration'
-              : 'ATM Unavailable'
-        }}
+        {{ maintenanceScreen.title }}
       </h1>
       <p class="max-w-md text-center text-base lg:text-2xl text-muted-foreground">
-        {{
-          atmStore.initError === 'maintenance'
-            ? 'This machine is currently being serviced. We will be back shortly.'
-            : atmStore.initError === 'awaiting-fees'
-              ? 'Awaiting fee configuration from operator. Contact operator to publish initial fee config.'
-              : 'This machine is temporarily out of service. Please try again later or use another machine.'
-        }}
+        {{ maintenanceScreen.message }}
       </p>
       <p
-        v-if="
-          atmStore.debugMode &&
-          atmStore.initError !== 'maintenance' &&
-          atmStore.initError !== 'awaiting-fees'
-        "
+        v-if="atmStore.debugMode && !isKnownMaintenanceScreen"
         class="max-w-lg text-center font-mono text-sm text-destructive"
       >
         {{ atmStore.initError }}
diff --git a/apps/machine/src/services/__tests__/init-error.test.ts b/apps/machine/src/services/__tests__/init-error.test.ts
new file mode 100644
index 0000000..fc4215b
--- /dev/null
+++ b/apps/machine/src/services/__tests__/init-error.test.ts
@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+import { BunkerRejectedError, BunkerTimeoutError } from '@bitSpire/nostr-client'
+import { classifyInitError } from '../init-error.js'
+
+describe('classifyInitError', () => {
+  it('maps a bunker rejection (revoke / TTL / off-policy) to "unpaired"', () => {
+    expect(classifyInitError(new BunkerRejectedError('revoked'))).toBe('unpaired')
+  })
+
+  it('maps a bunker timeout to "signer-unreachable"', () => {
+    expect(classifyInitError(new BunkerTimeoutError('no response'))).toBe('signer-unreachable')
+  })
+
+  it('classifies by error name across bundle boundaries (no instanceof)', () => {
+    // A structurally-equivalent error from a different module copy still maps.
+    const lookalike = Object.assign(new Error('x'), { name: 'BunkerRejectedError' })
+    expect(classifyInitError(lookalike)).toBe('unpaired')
+  })
+
+  it('surfaces a generic error message unchanged', () => {
+    expect(classifyInitError(new Error('relay down'))).toBe('relay down')
+  })
+
+  it('uses the fallback for non-Error throws', () => {
+    expect(classifyInitError('boom', 'Lightning initialization failed')).toBe(
+      'Lightning initialization failed'
+    )
+    expect(classifyInitError(undefined)).toBe('Initialization failed')
+  })
+})
diff --git a/apps/machine/src/services/init-error.ts b/apps/machine/src/services/init-error.ts
new file mode 100644
index 0000000..f9b0c84
--- /dev/null
+++ b/apps/machine/src/services/init-error.ts
@@ -0,0 +1,17 @@
+/**
+ * Classify an initialization failure into a maintenance-screen sentinel
+ * (see App.vue's MAINTENANCE_SCREENS).
+ *
+ * Bunker failures (aiolabs/bitspire#52) get dedicated screens:
+ * - `BunkerRejectedError` (revoked / TTL-expired / off-policy binding) →
+ *   `unpaired` — the operator must re-pair the machine.
+ * - `BunkerTimeoutError` (signer/relay unreachable) → `signer-unreachable`,
+ *   a transient condition.
+ * Everything else surfaces its raw message (or the caller's fallback).
+ */
+export function classifyInitError(error: unknown, fallback = 'Initialization failed'): string {
+  const name = (error as { name?: string } | null)?.name
+  if (name === 'BunkerRejectedError') return 'unpaired'
+  if (name === 'BunkerTimeoutError') return 'signer-unreachable'
+  return error instanceof Error ? error.message : fallback
+}
diff --git a/apps/machine/src/stores/atm.ts b/apps/machine/src/stores/atm.ts
index efc80cf..ca22847 100644
--- a/apps/machine/src/stores/atm.ts
+++ b/apps/machine/src/stores/atm.ts
@@ -10,6 +10,7 @@ import {
   type ATMMachine,
 } from '@bitSpire/state-machine'
 import { initializeLightningServices, fetchBtcPrice } from '@/services/lightning'
+import { classifyInitError } from '@/services/init-error'
 import {
   startOperatorConfigService,
   type OperatorConfigService,
@@ -706,7 +707,7 @@ export const useAtmStore = defineStore('atm', () => {
         useLiveServices.value = false
         initialize(mockServices)
       } else {
-        initError.value = error instanceof Error ? error.message : 'Lightning initialization failed'
+        initError.value = classifyInitError(error, 'Lightning initialization failed')
       }
     }
   }
@@ -1019,7 +1020,7 @@ export const useAtmStore = defineStore('atm', () => {
         useLiveServices.value = false
         initialize(mockServices)
       } else {
-        initError.value = error instanceof Error ? error.message : 'HAL initialization failed'
+        initError.value = classifyInitError(error, 'HAL initialization failed')
       }
     }
   }
@@ -1330,7 +1331,7 @@ export const useAtmStore = defineStore('atm', () => {
           initialize(mockServices)
         }
       } else {
-        initError.value = error instanceof Error ? error.message : 'Hardware initialization failed'
+        initError.value = classifyInitError(error, 'Hardware initialization failed')
       }
     }
   }

From 8a02d72bd1b68d23a891001493058dab93785fdc Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 21 Jun 2026 09:56:00 +0200
Subject: [PATCH 15/82] feat(deploy): provision VITE_SPIRE_SEED for bunker
 pairing (Phase E)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

provision-atm.sh now writes VITE_SPIRE_SEED (the spire-seed:v1: pairing seed
from spirekeeper) as the production identity, validating the scheme prefix;
the generated nsec path is kept only as a dev fallback when SPIRE_SEED is
unset. Relay default moved to the LNbits bundled nostrrelay
(ws://$HOST_IP:5001/nostrrelay/test). .env templates (live.nix + the flake's
installed-default) swap VITE_ATM_PRIVATE_KEY → VITE_SPIRE_SEED and drop the
dead LP-era vars. README notes state.db now also holds the bunker binding
(keep it or re-pair).

Part of Phase E, aiolabs/bitspire#52. Unblocks the Sintra live-pairing smoke.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 deploy/nixos/README.md        |  4 ++--
 deploy/nixos/live.nix         | 13 +++++------
 deploy/nixos/provision-atm.sh | 41 +++++++++++++++++++++++++----------
 flake.nix                     |  2 +-
 4 files changed, 39 insertions(+), 21 deletions(-)

diff --git a/deploy/nixos/README.md b/deploy/nixos/README.md
index 794c471..af00ed6 100644
--- a/deploy/nixos/README.md
+++ b/deploy/nixos/README.md
@@ -59,7 +59,7 @@ scp bitspire@<sintra-ip>:/var/lib/bitspire/.env       ~/sintra-backup-$(date +%Y
 scp bitspire@<sintra-ip>:/var/lib/bitspire/state.db   ~/sintra-backup-$(date +%Y%m%d)/
 ```
 
-The `.env` is the load-bearing one — it contains `VITE_ATM_PRIVATE_KEY` plus the LNbits / relay URLs. `state.db` is transaction history (cheap to keep, fine to drop on dev units). Reuse these in step 7 instead of regenerating.
+The `.env` is the load-bearing one — it contains `VITE_SPIRE_SEED` (the NIP-46 bunker pairing seed; or the dev-only `VITE_ATM_PRIVATE_KEY` fallback) plus the LNbits / relay URLs. Note the persisted bunker binding (the ATM's transport key) lives in `state.db` once paired — so on a bunker-backed unit, keep `state.db` too or you'll need to re-pair. `state.db` also holds transaction history. Reuse these in step 7 instead of regenerating.
 
 Also before powering off the Sintra: make sure any unpushed commits on `dev` have been pushed AND `./deploy/push-cache.sh sintra` has run. Otherwise the next 04:00 auto-upgrade on the freshly-flashed unit will fail to substitute the new closure (or silently downgrade to whatever `origin/dev` HEAD points at).
 
@@ -202,7 +202,7 @@ Production ATMs on `main` continue to read `main`'s flake (no `?ref=` pin → re
 | Path | Owner | Purpose |
 |------|-------|---------|
 | `/var/lib/bitspire/` | bitspire:bitspire, 0750 | Service data directory |
-| `/var/lib/bitspire/.env` | bitspire:bitspire, 0600 | Runtime config — `VITE_RELAY_URL`, `VITE_LNBITS_SERVER_PUBKEY`, `VITE_ATM_PRIVATE_KEY`, … |
+| `/var/lib/bitspire/.env` | bitspire:bitspire, 0600 | Runtime config — `VITE_RELAY_URL`, `VITE_LNBITS_SERVER_PUBKEY`, `VITE_SPIRE_SEED` (or dev `VITE_ATM_PRIVATE_KEY`), … |
 | `/var/lib/bitspire/state.db` | bitspire:bitspire | SQLite — cassette inventory, cashbox state, transaction history |
 | `/var/lib/bitspire/logs/` | bitspire:bitspire, 0750 | Service logs (if app writes them) |
 | `/var/lib/bitspire/branding/` | bitspire:bitspire, 0755 | Operator branding override (logo.png + branding.json) — see issue #47 |
diff --git a/deploy/nixos/live.nix b/deploy/nixos/live.nix
index 6b72fbc..07fe161 100644
--- a/deploy/nixos/live.nix
+++ b/deploy/nixos/live.nix
@@ -22,16 +22,15 @@ let
   }.${machineModel} or "USD";
 
   # .env template — runtime secrets are provisioned later via provision-atm.sh.
-  # Only non-secret defaults and display vars go here.
+  # Only non-secret defaults and display vars go here. VITE_SPIRE_SEED (the
+  # NIP-46 bunker pairing seed) is written at provision time; the dev-only
+  # VITE_ATM_PRIVATE_KEY fallback is omitted here on purpose.
   envTemplate = pkgs.writeText "bitspire-env" ''
     VITE_RELAY_URL=
-    VITE_LIGHTNING_PUB_PUBKEY=
-    VITE_LIGHTNING_PUB_API_URL=
-    VITE_ADMIN_TOKEN=
-    VITE_ATM_PRIVATE_KEY=
-    VITE_EXTENSION_API_URL=
+    VITE_LNBITS_SERVER_PUBKEY=
+    VITE_SPIRE_SEED=
     VITE_APP_ID=
-    VITE_LNDCONNECT_URL=
+    VITE_OPERATOR_PUBKEYS=
     VITE_LAMASSU_MACHINE_MODEL=${machineModel}
     VITE_LAMASSU_FIAT_CODE=${fiatCodeForModel}
     ELECTRON_FORCE_PROD=1
diff --git a/deploy/nixos/provision-atm.sh b/deploy/nixos/provision-atm.sh
index 5b4c55b..74f4229 100755
--- a/deploy/nixos/provision-atm.sh
+++ b/deploy/nixos/provision-atm.sh
@@ -11,9 +11,15 @@
 #   LNBITS_HTTP_URL        Origin LNbits is reachable at over HTTP, used only
 #                          to compose the LNURL-withdraw callback URL that
 #                          customer wallets dereference. Default: http://10.0.2.2:5000
-#   RELAY_URL              Nostr relay LNbits subscribes on. Default uses host gateway.
-#   ATM_PRIVATE_KEY        32-byte hex key, ATM's nostr identity. If unset, a
-#                          fresh key is generated and saved in the .env.
+#   RELAY_URL              Nostr relay LNbits + the bunker subscribe on.
+#                          Default: ws://$HOST_IP:5001/nostrrelay/test (LNbits
+#                          bundled nostrrelay). Override for a separate relay.
+#   SPIRE_SEED             The spire pairing seed (`spire-seed:v1:<base64url>`)
+#                          minted by spirekeeper. THIS is the production
+#                          identity under the NIP-46 bunker (aiolabs/bitspire#52).
+#   ATM_PRIVATE_KEY        DEV-ONLY 32-byte hex nsec fallback, used only when
+#                          SPIRE_SEED is unset (no bunker). Generated if unset
+#                          AND no SPIRE_SEED is provided.
 #
 # Usage:
 #   bash provision-atm.sh                    # defaults: SSH to localhost:2222 (QEMU)
@@ -74,14 +80,28 @@ echo "LNbits server pubkey: ${LNBITS_SERVER_PUBKEY:0:16}..."
 # Step 3: Pin LNbits HTTP origin.
 LNBITS_HTTP_URL="${LNBITS_HTTP_URL:-http://$HOST_IP:5000}"
 
-# Step 4: Relay URL.
-RELAY_URL="${RELAY_URL:-ws://$HOST_IP:7777}"
+# Step 4: Relay URL. Defaults to the LNbits bundled nostrrelay.
+RELAY_URL="${RELAY_URL:-ws://$HOST_IP:5001/nostrrelay/test}"
 
-# Step 5: ATM identity. Generate if unset.
-if [ -z "${ATM_PRIVATE_KEY:-}" ]; then
-    ATM_PRIVATE_KEY=$(openssl rand -hex 32)
+# Step 5: Signing identity. Prefer the spire pairing seed (bunker). Only fall
+# back to a generated dev nsec when no seed is supplied.
+if [ -n "${SPIRE_SEED:-}" ]; then
     echo ""
-    echo "--- Generated fresh ATM_PRIVATE_KEY (save this if you want it persisted) ---"
+    echo "--- Using spire pairing seed (bunker-backed identity) ---"
+    case "$SPIRE_SEED" in
+        spire-seed:v1:*) : ;;
+        *) echo "ERROR: SPIRE_SEED must start with 'spire-seed:v1:'"; exit 1 ;;
+    esac
+    IDENTITY_LINES="# Spire pairing seed — bunker-backed identity (aiolabs/bitspire#52)
+VITE_SPIRE_SEED=$SPIRE_SEED"
+else
+    if [ -z "${ATM_PRIVATE_KEY:-}" ]; then
+        ATM_PRIVATE_KEY=$(openssl rand -hex 32)
+        echo ""
+        echo "--- No SPIRE_SEED; generated a DEV-ONLY ATM_PRIVATE_KEY (no bunker) ---"
+    fi
+    IDENTITY_LINES="# DEV-ONLY local nsec (no bunker pairing)  # pragma: allowlist secret
+VITE_ATM_PRIVATE_KEY=$ATM_PRIVATE_KEY"
 fi
 
 # Step 6: Write .env to the ATM via SSH.
@@ -95,8 +115,7 @@ VITE_RELAY_URL=$RELAY_URL
 VITE_LNBITS_SERVER_PUBKEY=$LNBITS_SERVER_PUBKEY
 VITE_LNBITS_HTTP_URL=$LNBITS_HTTP_URL
 
-# ATM identity (signing key IS the credential under nostr-transport)
-VITE_ATM_PRIVATE_KEY=$ATM_PRIVATE_KEY
+$IDENTITY_LINES
 
 # Machine configuration
 VITE_LAMASSU_MACHINE_MODEL=$MODEL
diff --git a/flake.nix b/flake.nix
index dc69891..9ceb5dd 100644
--- a/flake.nix
+++ b/flake.nix
@@ -200,7 +200,7 @@
                   cp ${pkgs.writeText "bitspire-env-default" ''
                     VITE_RELAY_URL=${config.services.bitspire.relayUrl}
                     VITE_LNBITS_SERVER_PUBKEY=
-                    VITE_ATM_PRIVATE_KEY=
+                    VITE_SPIRE_SEED=
                     VITE_APP_ID=
                     VITE_OPERATOR_PUBKEYS=
                     VITE_LAMASSU_MACHINE_MODEL=${machineModel}

From 2a64b42cde83937e8ed463a82dbb9913714dabf8 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 21 Jun 2026 15:35:35 +0200
Subject: [PATCH 16/82] feat(lnbits): retry-policy switch for idempotent reads
 (Phase D)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The retry half of the 2026-05-26 error-handling agreement (aiolabs/bitspire#52).
`withRetry` retries an operation per the disposition of the error it throws —
LnbitsRpcError.retryPolicy (operator_signer_unavailable/rate_limited →
backoff, internal_error → retry-once) plus transport timeouts — and rethrows
terminal/unknown errors immediately.

Applied ONLY to idempotent reads (getWallet/getBalance/listWallets/getPayment/
decodePayment + the lnurlw read methods). create_invoice / pay_invoice /
lnurlw_create_link are deliberately NOT wrapped — a blind retry would mint a
duplicate or double-pay; their errors surface for flow-level handling. This is
why the switch lives at the per-call read layer, not as a blanket client retry.

Safe to land before lnbits emits error_code: an absent code already maps to
internal_error (retry-once), so reads get one transparent retry on a transient
blip with no behaviour change otherwise. 10 tests (backoff/terminal/timeout/
unknown/onRetry).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/lnbits/src/__tests__/retry.test.ts | 96 +++++++++++++++++++++
 packages/lnbits/src/client.ts               | 68 ++++++++++-----
 packages/lnbits/src/index.ts                |  2 +
 packages/lnbits/src/retry.ts                | 79 +++++++++++++++++
 4 files changed, 225 insertions(+), 20 deletions(-)
 create mode 100644 packages/lnbits/src/__tests__/retry.test.ts
 create mode 100644 packages/lnbits/src/retry.ts

diff --git a/packages/lnbits/src/__tests__/retry.test.ts b/packages/lnbits/src/__tests__/retry.test.ts
new file mode 100644
index 0000000..8a57b45
--- /dev/null
+++ b/packages/lnbits/src/__tests__/retry.test.ts
@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest'
+import { withRetry } from '../retry.js'
+import { LnbitsErrorCode, LnbitsRpcError } from '../error-codes.js'
+
+const noSleep = () => Promise.resolve()
+
+function rpcErr(code: LnbitsErrorCode): LnbitsRpcError {
+  return new LnbitsRpcError({ code, rpcName: 'get_wallet', requestId: 'r1' })
+}
+
+/** A fn that throws `err` the first `failTimes` calls, then returns `value`. */
+function failingFn<T>(failTimes: number, err: unknown, value: T): { fn: () => Promise<T>; calls: () => number } {
+  let calls = 0
+  return {
+    fn: async () => {
+      calls++
+      if (calls <= failTimes) throw err
+      return value
+    },
+    calls: () => calls,
+  }
+}
+
+describe('withRetry', () => {
+  it('returns immediately on success (one call)', async () => {
+    const { fn, calls } = failingFn(0, rpcErr(LnbitsErrorCode.InternalError), 'ok')
+    expect(await withRetry(fn, { sleep: noSleep })).toBe('ok')
+    expect(calls()).toBe(1)
+  })
+
+  it('retries a transient operator_signer_unavailable, then succeeds', async () => {
+    const { fn, calls } = failingFn(1, rpcErr(LnbitsErrorCode.OperatorSignerUnavailable), 'ok')
+    expect(await withRetry(fn, { sleep: noSleep })).toBe('ok')
+    expect(calls()).toBe(2)
+  })
+
+  it('retries rate_limited (long backoff) up to maxAttempts then throws', async () => {
+    const err = rpcErr(LnbitsErrorCode.RateLimited)
+    const { fn, calls } = failingFn(99, err, 'never')
+    await expect(withRetry(fn, { sleep: noSleep, maxAttempts: 3 })).rejects.toBe(err)
+    expect(calls()).toBe(3)
+  })
+
+  it('internal_error (retry-once) retries exactly once', async () => {
+    const err = rpcErr(LnbitsErrorCode.InternalError)
+    const { fn, calls } = failingFn(99, err, 'never')
+    await expect(withRetry(fn, { sleep: noSleep, maxAttempts: 5 })).rejects.toBe(err)
+    expect(calls()).toBe(2) // initial + one retry, then null delay stops it
+  })
+
+  it('throws a terminal error immediately (no retry)', async () => {
+    const err = rpcErr(LnbitsErrorCode.InsufficientBalance)
+    const { fn, calls } = failingFn(99, err, 'never')
+    await expect(withRetry(fn, { sleep: noSleep })).rejects.toBe(err)
+    expect(calls()).toBe(1)
+  })
+
+  it('treats unauthorized as terminal (no retry)', async () => {
+    const err = rpcErr(LnbitsErrorCode.Unauthorized)
+    const { fn, calls } = failingFn(99, err, 'never')
+    await expect(withRetry(fn, { sleep: noSleep })).rejects.toBe(err)
+    expect(calls()).toBe(1)
+  })
+
+  it('retries a transport timeout error', async () => {
+    const timeout = new Error('LnbitsClient.get_wallet: timeout after 30000ms')
+    const { fn, calls } = failingFn(1, timeout, 'ok')
+    expect(await withRetry(fn, { sleep: noSleep })).toBe('ok')
+    expect(calls()).toBe(2)
+  })
+
+  it('does NOT retry an unknown error (rethrows immediately)', async () => {
+    const boom = new Error('relay socket closed')
+    const { fn, calls } = failingFn(99, boom, 'never')
+    await expect(withRetry(fn, { sleep: noSleep })).rejects.toBe(boom)
+    expect(calls()).toBe(1)
+  })
+
+  it('backs off with increasing delay per attempt (retry-backoff)', async () => {
+    const delays: number[] = []
+    const err = rpcErr(LnbitsErrorCode.OperatorSignerUnavailable)
+    const { fn } = failingFn(99, err, 'never')
+    await expect(
+      withRetry(fn, { sleep: (ms) => { delays.push(ms); return Promise.resolve() }, maxAttempts: 3 })
+    ).rejects.toBe(err)
+    expect(delays).toEqual([200, 400]) // before attempt 2 and 3; attempt 3 is last → no 3rd sleep
+  })
+
+  it('invokes onRetry with attempt/delay/error', async () => {
+    const onRetry = vi.fn()
+    const { fn } = failingFn(1, rpcErr(LnbitsErrorCode.OperatorSignerUnavailable), 'ok')
+    await withRetry(fn, { sleep: noSleep, onRetry })
+    expect(onRetry).toHaveBeenCalledOnce()
+    expect(onRetry.mock.calls[0]![0]).toMatchObject({ attempt: 1, delayMs: 200 })
+  })
+})
diff --git a/packages/lnbits/src/client.ts b/packages/lnbits/src/client.ts
index 946df5d..de408a1 100644
--- a/packages/lnbits/src/client.ts
+++ b/packages/lnbits/src/client.ts
@@ -27,6 +27,7 @@ import {
 } from '@bitSpire/nostr-client'
 import { verifyEvent } from 'nostr-tools'
 import { LnbitsRpcError } from './error-codes.js'
+import { withRetry } from './retry.js'
 
 import type {
   LnbitsConfig,
@@ -155,6 +156,22 @@ export class LnbitsClient {
     this.startReplyListener()
   }
 
+  /**
+   * Retry-policy switch for IDEMPOTENT reads only (aiolabs/bitspire#52, Phase D).
+   * Transient failures (operator_signer_unavailable / rate_limited /
+   * internal_error / transport timeout) back off and retry; terminal errors
+   * surface immediately. Never used for pay/create — those would double-pay or
+   * duplicate on retry.
+   */
+  private idempotent<T>(fn: () => Promise<T>): Promise<T> {
+    return withRetry(fn, {
+      onRetry: ({ attempt, delayMs, error }) => {
+        const code = error instanceof LnbitsRpcError ? error.code : 'timeout'
+        console.warn(`[LnbitsClient] transient ${code} — retry ${attempt} in ${delayMs}ms`)
+      },
+    })
+  }
+
   // ============================================================================
   // Wallet
   // ============================================================================
@@ -166,8 +183,7 @@ export class LnbitsClient {
    */
   async getWallet(walletId?: string): Promise<WalletInfo> {
     if (walletId) {
-      const data = await this.sendRpc<WalletInfo>('get_wallet', { walletId })
-      return data
+      return this.idempotent(() => this.sendRpc<WalletInfo>('get_wallet', { walletId }))
     }
     const wallets = await this.listWallets()
     if (wallets.length === 0) {
@@ -188,7 +204,7 @@ export class LnbitsClient {
 
   /** Enumerate every wallet owned by the calling account. */
   async listWallets(): Promise<WalletInfo[]> {
-    const data = await this.sendRpc<WalletInfo[]>('list_wallets', {})
+    const data = await this.idempotent(() => this.sendRpc<WalletInfo[]>('list_wallets', {}))
     return data ?? []
   }
 
@@ -196,6 +212,10 @@ export class LnbitsClient {
   // Invoices
   // ============================================================================
 
+  // NOTE: create_invoice / pay_invoice / lnurlw_create_link are NOT wrapped in
+  // `idempotent()` — a retry would mint a duplicate invoice/link or double-pay.
+  // Their errors surface for flow-level handling (state machine / operator).
+
   async createInvoice(walletId: string, body: CreateInvoiceBody): Promise<LnbitsPayment> {
     const data = await this.sendRpc<LnbitsPayment>('create_invoice', { walletId, body })
     return data
@@ -208,17 +228,20 @@ export class LnbitsClient {
 
   /** Point-lookup of a payment by hash. AUTH_NONE — hashes are hard to guess. */
   async getPayment(paymentHash: string): Promise<LnbitsPayment | null> {
-    const data = await this.sendRpc<LnbitsPayment | null>('get_payment', {
-      body: { payment_hash: paymentHash },
-    })
+    const data = await this.idempotent(() =>
+      this.sendRpc<LnbitsPayment | null>('get_payment', {
+        body: { payment_hash: paymentHash },
+      }),
+    )
     return data ?? null
   }
 
   async decodePayment(paymentRequest: string): Promise<Record<string, unknown>> {
-    const data = await this.sendRpc<Record<string, unknown>>('decode_payment', {
-      body: { payment_request: paymentRequest },
-    })
-    return data
+    return this.idempotent(() =>
+      this.sendRpc<Record<string, unknown>>('decode_payment', {
+        body: { payment_request: paymentRequest },
+      }),
+    )
   }
 
   // ============================================================================
@@ -366,18 +389,21 @@ export class LnbitsClient {
   }
 
   async getWithdrawLink(walletId: string, id: string): Promise<LnbitsWithdrawLink> {
-    const data = await this.sendRpc<LnbitsWithdrawLink>('lnurlw_get_link', { walletId, body: { id } })
-    return data
+    return this.idempotent(() =>
+      this.sendRpc<LnbitsWithdrawLink>('lnurlw_get_link', { walletId, body: { id } }),
+    )
   }
 
   async listWithdrawLinks(
     walletId: string | undefined,
     body: { limit?: number; offset?: number } = {},
   ): Promise<{ data: LnbitsWithdrawLink[]; total: number }> {
-    return this.sendRpc<{ data: LnbitsWithdrawLink[]; total: number }>('lnurlw_list_links', {
-      walletId,
-      body,
-    })
+    return this.idempotent(() =>
+      this.sendRpc<{ data: LnbitsWithdrawLink[]; total: number }>('lnurlw_list_links', {
+        walletId,
+        body,
+      }),
+    )
   }
 
   /**
@@ -387,10 +413,12 @@ export class LnbitsClient {
    * — the URL a customer wallet GETs to redeem that specific sub-link.
    */
   async getWithdrawLinkUniqueHashes(walletId: string, id: string): Promise<UniqueHashesResponse> {
-    return this.sendRpc<UniqueHashesResponse>('lnurlw_unique_hashes', {
-      walletId,
-      body: { id },
-    })
+    return this.idempotent(() =>
+      this.sendRpc<UniqueHashesResponse>('lnurlw_unique_hashes', {
+        walletId,
+        body: { id },
+      }),
+    )
   }
 
   async updateWithdrawLink(
diff --git a/packages/lnbits/src/index.ts b/packages/lnbits/src/index.ts
index 10e0f05..2085593 100644
--- a/packages/lnbits/src/index.ts
+++ b/packages/lnbits/src/index.ts
@@ -56,6 +56,8 @@ export {
   retryPolicyFor,
 } from './error-codes.js'
 export type { RetryPolicy } from './error-codes.js'
+export { withRetry } from './retry.js'
+export type { WithRetryOptions } from './retry.js'
 export type {
   LnbitsConfig,
   LnbitsRpcRequest,
diff --git a/packages/lnbits/src/retry.ts b/packages/lnbits/src/retry.ts
new file mode 100644
index 0000000..0495859
--- /dev/null
+++ b/packages/lnbits/src/retry.ts
@@ -0,0 +1,79 @@
+/**
+ * Retry policy switch for the nostr-transport (aiolabs/bitspire#52, Phase D).
+ *
+ * Retries an operation according to the *disposition* of the error it throws —
+ * the machine-readable `retryPolicy` carried by `LnbitsRpcError` (which mirrors
+ * the lnbits canonical enum). Transient conditions back off and retry;
+ * terminal ones throw immediately.
+ *
+ * ⚠️ ONLY wrap IDEMPOTENT operations. A blind retry of `pay_invoice` could
+ * double-pay, and of `create_invoice` / `lnurlw_create_link` would mint
+ * duplicates — those surface their error for flow-level handling (the state
+ * machine / operator) instead. See LnbitsClient for which methods opt in.
+ */
+
+import { LnbitsRpcError, type RetryPolicy } from './error-codes.js'
+
+export interface WithRetryOptions {
+  /** Max total attempts (default 3). */
+  maxAttempts?: number
+  /** Injectable sleep (tests pass a fake-timer-friendly version). */
+  sleep?: (ms: number) => Promise<void>
+  /** Called before each backoff wait — useful for logging. */
+  onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void
+}
+
+const DEFAULT_MAX_ATTEMPTS = 3
+
+/** Backoff (ms) for the Nth attempt (1-based), or null if the policy is terminal. */
+function backoffMs(policy: RetryPolicy, attempt: number): number | null {
+  switch (policy) {
+    case 'retry-backoff':
+      return 200 * 2 ** (attempt - 1) // 200, 400, 800…
+    case 'retry-long-backoff':
+      return 1_000 * 2 ** (attempt - 1) // 1s, 2s, 4s… (rate_limited)
+    case 'retry-once':
+      return attempt === 1 ? 0 : null // exactly one retry (internal_error / absent code)
+    case 'terminal':
+    case 'terminal-idempotent':
+      return null
+  }
+}
+
+/** Retry delay for an error, or null if it must not be retried. */
+function delayForError(error: unknown, attempt: number): number | null {
+  if (error instanceof LnbitsRpcError) {
+    return backoffMs(error.retryPolicy, attempt)
+  }
+  // A transport timeout from sendRpc ("…: timeout after <n>ms") is transient.
+  if (error instanceof Error && /timeout after \d+ms/.test(error.message)) {
+    return 200 * 2 ** (attempt - 1)
+  }
+  // Unknown error (programming bug, network teardown) — don't mask it.
+  return null
+}
+
+/**
+ * Run `fn`, retrying transient failures per the error's `retryPolicy` (or a
+ * transport timeout) with backoff, up to `maxAttempts`. Terminal errors and
+ * unknown errors throw immediately; the last error is rethrown on exhaustion.
+ */
+export async function withRetry<T>(fn: () => Promise<T>, opts: WithRetryOptions = {}): Promise<T> {
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS
+  const sleep = opts.sleep ?? ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+
+  let lastError: unknown
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+      if (attempt === maxAttempts) break
+      const delayMs = delayForError(error, attempt)
+      if (delayMs === null) throw error
+      opts.onRetry?.({ attempt, delayMs, error })
+      await sleep(delayMs)
+    }
+  }
+  throw lastError
+}

From 762b0def5c77d2efcb6fa18f7809bfa5999ed6fe Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 22 Jun 2026 11:08:29 +0200
Subject: [PATCH 17/82] fix(machine): republish cassettes-state after dispense
 + on reload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The cassette-state beacon was published only once at bootstrap, so after a
cash-out dispense the operator's view stayed frozen at the bootstrap snapshot
(still 20x4/50x7 after dispensing) — the ATM decremented its local HAL counts
but never told the operator. Coord 2026-06-21 (post cash-out leg).

- operator-config.ts: extract publishCassettesState() (the live, ungated
  publish) out of the one-shot bootstrap; expose it on OperatorConfigService;
  also fire it after an operator-config apply (the "on reload" case).
- atm.ts: republish after each cash-out dispense (complete + partial), once the
  decremented counts are persisted. kind-30078 is replaceable (latest wins) and
  the operator already consumes every update — no operator-side change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/src/services/operator-config.ts | 87 +++++++++++++++-----
 apps/machine/src/stores/atm.ts               | 11 ++-
 2 files changed, 76 insertions(+), 22 deletions(-)

diff --git a/apps/machine/src/services/operator-config.ts b/apps/machine/src/services/operator-config.ts
index ba9ddcb..d853114 100644
--- a/apps/machine/src/services/operator-config.ts
+++ b/apps/machine/src/services/operator-config.ts
@@ -56,6 +56,17 @@ export interface OperatorConfigServiceConfig {
 export interface OperatorConfigService {
   /** Unsubscribe from operator events and free resources. */
   stop(): void
+  /**
+   * Republish the current cassette state (kind-30078, replaceable). Call after
+   * a dispense and on a cassette reload so the operator's view tracks reality.
+   * Best-effort — logs and swallows errors.
+   */
+  publishCassettesState(): Promise<void>
+}
+
+const NOOP_SERVICE: OperatorConfigService = {
+  stop: () => {},
+  publishCassettesState: async () => {},
 }
 
 export async function startOperatorConfigService(
@@ -63,11 +74,11 @@ export async function startOperatorConfigService(
 ): Promise<OperatorConfigService> {
   if (cfg.operatorPubkeys.length === 0) {
     console.log('[OperatorConfig] No operator pubkeys configured — service disabled')
-    return { stop: () => {} }
+    return NOOP_SERVICE
   }
   if (!isElectron || !window.electronAPI) {
     console.log('[OperatorConfig] Not in Electron — service disabled (browser dev mode)')
-    return { stop: () => {} }
+    return NOOP_SERVICE
   }
   const api = window.electronAPI
   const machineId = cfg.machineId ?? cfg.signer.pubkey
@@ -103,6 +114,12 @@ export async function startOperatorConfigService(
 
   return {
     stop: () => cfg.nostrClient.unsubscribe(subscriptionId),
+    publishCassettesState: () =>
+      publishCassettesState(cfg, api, machineId)
+        .then(() => {})
+        .catch((err) => {
+          console.warn('[OperatorConfig] cassettes-state republish failed:', err)
+        }),
   }
 }
 
@@ -193,29 +210,35 @@ async function handleOperatorConfigEvent(
   console.log(
     `[OperatorConfig] Applied — created_at=${event.created_at}, positions=${Object.keys(parsed.positions).join(',')}`
   )
+
+  // Republish our resulting cassette state so the operator's view reflects the
+  // applied config (the "on cassette reload" case). Different d-tag from the
+  // operator's config event, so no echo loop. Best-effort.
+  const machineId = cfg.machineId ?? cfg.signer.pubkey
+  await publishCassettesState(cfg, api, machineId).catch((err) =>
+    console.warn('[OperatorConfig] post-apply cassettes-state republish failed:', err)
+  )
 }
 
-async function maybePublishBootstrap(
+/**
+ * Publish the ATM's current cassette state as a replaceable kind-30078 event
+ * (`bitspire-cassettes-state:<machineId>`), NIP-44-encrypted to the operator.
+ * Replaceable → latest wins; the operator consumes every update. Call after a
+ * dispense and on a cassette reload so the operator view tracks reality, not
+ * the frozen bootstrap snapshot (coord 2026-06-21 / lamassu-next#56).
+ *
+ * NOT gated on the bootstrap flag — this is the live update. Returns whether an
+ * event was published (false when there are no cassettes / no operator).
+ */
+async function publishCassettesState(
   cfg: OperatorConfigServiceConfig,
   api: NonNullable<typeof window.electronAPI>,
   machineId: string
-): Promise<void> {
-  const already = await api.getBootstrapPublishedAt()
-  if (already !== null) {
-    console.log('[OperatorConfig] Bootstrap already published at unix', already)
-    return
-  }
+): Promise<boolean> {
   const cassettes = await api.loadCassettes()
-  if (cassettes.length === 0) {
-    console.log('[OperatorConfig] state.db.cassettes empty — skipping bootstrap')
-    return
-  }
-
+  if (cassettes.length === 0) return false
   const operatorPubkey = cfg.operatorPubkeys[0]
-  if (!operatorPubkey) {
-    console.log('[OperatorConfig] No operator pubkey — skipping bootstrap')
-    return
-  }
+  if (!operatorPubkey) return false
 
   const positions: Record<string, { denomination: number; count: number }> = {}
   for (const c of cassettes) {
@@ -235,6 +258,30 @@ async function maybePublishBootstrap(
   })
 
   await cfg.nostrClient.publish(event)
-  await api.markBootstrapPublished(Math.floor(Date.now() / 1000))
-  console.log('[OperatorConfig] Bootstrap hello-event published:', { dTag, eventId: event.id })
+  console.log('[OperatorConfig] cassettes-state published:', { dTag, eventId: event.id })
+  return true
+}
+
+/**
+ * First-boot hello: publish the cassette state once and mark the gate. The
+ * gate (lamassu-next#56) prevents re-emitting the *bootstrap* on every boot;
+ * live updates after dispenses go through `publishCassettesState` directly.
+ */
+async function maybePublishBootstrap(
+  cfg: OperatorConfigServiceConfig,
+  api: NonNullable<typeof window.electronAPI>,
+  machineId: string
+): Promise<void> {
+  const already = await api.getBootstrapPublishedAt()
+  if (already !== null) {
+    console.log('[OperatorConfig] Bootstrap already published at unix', already)
+    return
+  }
+  const published = await publishCassettesState(cfg, api, machineId)
+  if (published) {
+    await api.markBootstrapPublished(Math.floor(Date.now() / 1000))
+    console.log('[OperatorConfig] Bootstrap hello-event published')
+  } else {
+    console.log('[OperatorConfig] No cassettes/operator — skipping bootstrap')
+  }
 }
diff --git a/apps/machine/src/stores/atm.ts b/apps/machine/src/stores/atm.ts
index ca22847..2bfaeea 100644
--- a/apps/machine/src/stores/atm.ts
+++ b/apps/machine/src/stores/atm.ts
@@ -521,7 +521,10 @@ export const useAtmStore = defineStore('atm', () => {
             bills,
             cassettes: dr?.cassettes,
             error: dr?.error ?? ctx.error,
-          }).then(() => reloadPersistedInventory())
+          })
+            .then(() => reloadPersistedInventory())
+            // Republish cassette state — a partial dispense changed counts.
+            .then(() => operatorConfigSvc?.publishCassettesState())
         }
       }
 
@@ -551,7 +554,11 @@ export const useAtmStore = defineStore('atm', () => {
             bills,
             cassettes: dr?.cassettes,
             error: dr?.error,
-          }).then(() => reloadPersistedInventory())
+          })
+            .then(() => reloadPersistedInventory())
+            // Republish cassette state after a cash-out dispense (counts
+            // decremented); harmless no-op echo for a cash-in complete.
+            .then(() => (isCashInTx ? undefined : operatorConfigSvc?.publishCassettesState()))
         }
       }
 

From 9c74a28a06539a4abc4b218e8314b990f7ca0947 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 22 Jun 2026 12:31:24 +0200
Subject: [PATCH 18/82] feat(machine): secure cash-in via server-stamped
 create_withdraw RPC

Replaces the cash-in LNURL-withdraw creation with the secure create_withdraw
RPC (aiolabs/spirekeeper#31/#32). The ATM now sends only the hardware-attested
gross principal_sats; the operator side verifies the signer, derives fee + NET,
and stamps the link's attribution (source/nostr_sender_pubkey) from the VERIFIED
sender. Closes the dev-stack weakness where the ATM set the withdraw amount +
extra itself (could understate the fee / forge attribution).

- LnbitsClient.createWithdraw(walletId, {principal_sats, fiat_amount?, fiat_code?,
  title?, wait_time?, client_ref?}) -> {link_id, lnurl, net_sats, principal_sats,
  fee_sats}. Non-idempotent (mints a link) -> not retry-wrapped.
- lightning.ts generateLnurlWithdraw: createWithdrawLink -> createWithdraw; the
  ATM no longer computes amount/fee/extra. LNURL-session map re-keyed on link_id
  (the secure response carries no unique_hash); settlement-watch half unchanged
  (subscribe_payments tag:'withdraw', link_id).

Server RPC is live on the dev stack (spirekeeper#32 registered create_withdraw),
so this is ready for the joint cash-in test. typecheck 12/12, full suite + prod
build green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/machine/src/services/lightning.ts | 81 +++++++++++++-------------
 packages/lnbits/src/client.ts          | 15 +++++
 packages/lnbits/src/index.ts           |  2 +
 packages/lnbits/src/types.ts           | 39 +++++++++++++
 4 files changed, 95 insertions(+), 42 deletions(-)

diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index e975277..5b60b2f 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -109,33 +109,27 @@ const SESSION_SAFETY_TIMEOUT_MS = 15 * 60 * 1000
 /** Active LNURL-withdraw session */
 interface LnurlSession {
   sessionId: string
-  /** Link ID for management operations (delete/update) */
+  /** Link ID — the management + settlement-watch key (delete/subscribe). */
   linkId: string
-  uniqueHash: string
   satsAmount: number
   status: 'active' | 'claimed' | 'expired'
   createdAt: number
   cleanup?: () => void
 }
 
-/** Map of uniqueHash -> LNURL session data */
+/** Map of linkId -> LNURL session data. Keyed on link_id since the secure
+ *  `create_withdraw` response (spirekeeper#31) carries no `unique_hash`. */
 const lnurlSessions = new Map<string, LnurlSession>()
 
 /**
- * Register a new LNURL-withdraw session
+ * Register a new LNURL-withdraw session, keyed by linkId.
  */
-function registerLnurlSession(
-  sessionId: string,
-  linkId: string,
-  uniqueHash: string,
-  satsAmount: number,
-): void {
-  console.log('[LNURL Session] Registering:', uniqueHash, 'for', satsAmount, 'sats')
+function registerLnurlSession(sessionId: string, linkId: string, satsAmount: number): void {
+  console.log('[LNURL Session] Registering:', linkId, 'for', satsAmount, 'sats')
 
-  lnurlSessions.set(uniqueHash, {
+  lnurlSessions.set(linkId, {
     sessionId,
     linkId,
-    uniqueHash,
     satsAmount,
     status: 'active',
     createdAt: Date.now(),
@@ -143,10 +137,10 @@ function registerLnurlSession(
 
   // Safety timeout — normally cleaned up by state machine on idle transition.
   setTimeout(() => {
-    const session = lnurlSessions.get(uniqueHash)
+    const session = lnurlSessions.get(linkId)
     if (session && session.status === 'active') {
-      console.warn('[LNURL Session] Safety timeout reached, expiring:', uniqueHash)
-      expireLnurlSession(uniqueHash)
+      console.warn('[LNURL Session] Safety timeout reached, expiring:', linkId)
+      expireLnurlSession(linkId)
     }
   }, SESSION_SAFETY_TIMEOUT_MS)
 }
@@ -154,23 +148,23 @@ function registerLnurlSession(
 /** Invalidate an active LNURL session by cash-in sessionId. The session's
  * cleanup closure unsubscribes from LNbits and deletes the link. */
 function invalidateLnurlSessionBySessionId(sessionId: string): void {
-  for (const [hash, session] of lnurlSessions.entries()) {
+  for (const [linkId, session] of lnurlSessions.entries()) {
     if (session.sessionId === sessionId && session.status === 'active') {
-      console.log('[LNURL Session] Invalidating previous session:', hash)
-      expireLnurlSession(hash)
+      console.log('[LNURL Session] Invalidating previous session:', linkId)
+      expireLnurlSession(linkId)
     }
   }
 }
 
 /** Expire a single LNURL session via its cleanup closure. */
-function expireLnurlSession(uniqueHash: string): void {
-  const session = lnurlSessions.get(uniqueHash)
+function expireLnurlSession(linkId: string): void {
+  const session = lnurlSessions.get(linkId)
   if (!session || session.status !== 'active') return
 
-  console.log('[LNURL Session] Expiring:', uniqueHash)
+  console.log('[LNURL Session] Expiring:', linkId)
   session.status = 'expired'
   if (session.cleanup) session.cleanup()
-  setTimeout(() => lnurlSessions.delete(uniqueHash), 60000)
+  setTimeout(() => lnurlSessions.delete(linkId), 60000)
 }
 
 let _lnbitsRef: LnbitsClient | null = null
@@ -651,50 +645,53 @@ function createATMServices(
           invalidateLnurlSessionBySessionId(context.cashInSessionId)
         }
 
-        const link = await lnbits.createWithdrawLink(lnbitsWalletId, {
+        // Secure cash-in: the ATM sends only the hardware-attested gross
+        // principal; the operator side verifies the signer, derives fee + NET,
+        // and stamps attribution (spirekeeper#31/#32). The ATM no longer sets
+        // the amount or extra. We display the returned LNURL (for NET) and
+        // watch link_id for settlement.
+        const link = await lnbits.createWithdraw(lnbitsWalletId, {
+          principal_sats: context.satsAmount,
+          fiat_amount: context.fiatCents / 100,
+          fiat_code: context.currency,
           title: `bitSpire Cash-In ${context.cashInSessionId?.slice(0, 8) || 'session'}`,
-          min_withdrawable: context.satsAmount,
-          max_withdrawable: context.satsAmount,
-          uses: 1,
-          wait_time: 1,
-          is_unique: false,
+          client_ref: context.txid ?? context.cashInSessionId ?? undefined,
         })
 
         if (!link.lnurl) {
           throw new Error(
-            '[ATM Service] LNbits returned link.lnurl=null — check LNBITS_BASEURL on the server (aiolabs/withdraw#1)'
+            '[ATM Service] create_withdraw returned no lnurl — check withdraw#3 / LNBITS_BASEURL on the server'
           )
         }
         const lnurl = link.lnurl.toUpperCase()
+        console.log(
+          `[ATM Service] create_withdraw: principal=${link.principal_sats} fee=${link.fee_sats} net=${link.net_sats} link=${link.link_id}`
+        )
 
         if (context.cashInSessionId) {
-          registerLnurlSession(
-            context.cashInSessionId,
-            link.id,
-            link.unique_hash,
-            context.satsAmount,
-          )
+          // Track the NET (what the customer withdraws); keyed by link_id.
+          registerLnurlSession(context.cashInSessionId, link.link_id, link.net_sats)
           const subId = await lnbits.subscribePayments(
             lnbitsWalletId,
-            { tag: 'withdraw', link_id: link.id, max_seconds: 600 },
+            { tag: 'withdraw', link_id: link.link_id, max_seconds: 600 },
             (push) => {
               console.log('[ATM Service] LNURL-withdraw claimed (LNbits push)!')
-              const session = lnurlSessions.get(link.unique_hash)
+              const session = lnurlSessions.get(link.link_id)
               if (session) {
                 session.status = 'claimed'
-                lnurlSessions.delete(link.unique_hash)
+                lnurlSessions.delete(link.link_id)
               }
               if (onPaymentCallback) {
-                onPaymentCallback(push.preimage ?? `lnurl-withdraw-${link.unique_hash}`)
+                onPaymentCallback(push.preimage ?? `lnurl-withdraw-${link.link_id}`)
               }
             },
           )
           // Wire per-session cleanup so abort/expiry tears it down cleanly.
-          const session = lnurlSessions.get(link.unique_hash)
+          const session = lnurlSessions.get(link.link_id)
           if (session) {
             session.cleanup = () => {
               void lnbits.unsubscribe(lnbitsWalletId, subId).catch(() => {})
-              void lnbits.deleteWithdrawLink(lnbitsWalletId, link.id).catch(() => {})
+              void lnbits.deleteWithdrawLink(lnbitsWalletId, link.link_id).catch(() => {})
             }
           }
         }
diff --git a/packages/lnbits/src/client.ts b/packages/lnbits/src/client.ts
index de408a1..f75db3f 100644
--- a/packages/lnbits/src/client.ts
+++ b/packages/lnbits/src/client.ts
@@ -42,6 +42,8 @@ import type {
   PaymentPushCallback,
   SubscriptionCloseCallback,
   CreateWithdrawLinkBody,
+  CreateWithdrawBody,
+  CreateWithdrawResult,
   LnbitsWithdrawLink,
   UniqueHashesResponse,
 } from './types.js'
@@ -388,6 +390,19 @@ export class LnbitsClient {
     return data
   }
 
+  /**
+   * Cash-in: create a SERVER-STAMPED LNURL-withdraw via the secure
+   * `create_withdraw` RPC (aiolabs/spirekeeper#31 / #32). The ATM sends only the
+   * hardware-attested `principal_sats`; the operator side verifies the signer,
+   * derives fee + NET, and stamps the link's attribution from the verified
+   * sender — the machine cannot understate the fee or forge attribution. NOT
+   * idempotent (mints a link) → not retry-wrapped; supersedes the direct,
+   * client-amount `createWithdrawLink` for cash-in.
+   */
+  async createWithdraw(walletId: string, body: CreateWithdrawBody): Promise<CreateWithdrawResult> {
+    return this.sendRpc<CreateWithdrawResult>('create_withdraw', { walletId, body })
+  }
+
   async getWithdrawLink(walletId: string, id: string): Promise<LnbitsWithdrawLink> {
     return this.idempotent(() =>
       this.sendRpc<LnbitsWithdrawLink>('lnurlw_get_link', { walletId, body: { id } }),
diff --git a/packages/lnbits/src/index.ts b/packages/lnbits/src/index.ts
index 2085593..9618a2f 100644
--- a/packages/lnbits/src/index.ts
+++ b/packages/lnbits/src/index.ts
@@ -73,6 +73,8 @@ export type {
   PaymentPushCallback,
   SubscriptionCloseCallback,
   CreateWithdrawLinkBody,
+  CreateWithdrawBody,
+  CreateWithdrawResult,
   LnbitsWithdrawLink,
   UniqueHashEntry,
   UniqueHashesResponse,
diff --git a/packages/lnbits/src/types.ts b/packages/lnbits/src/types.ts
index c040b3c..17af86f 100644
--- a/packages/lnbits/src/types.ts
+++ b/packages/lnbits/src/types.ts
@@ -146,6 +146,45 @@ export interface SubscribeClose {
 // LNURL-withdraw (the `withdraw` extension's transport surface)
 // ============================================================================
 
+/**
+ * Cash-in request for the SECURE `create_withdraw` RPC (aiolabs/spirekeeper#31).
+ * The ATM supplies only the hardware-attested gross principal; the operator
+ * side derives fee + NET and stamps attribution from the *verified* signer, so
+ * the machine cannot understate the fee or forge attribution. Contrast with
+ * `CreateWithdrawLinkBody`, where the amount + extra were client-supplied.
+ */
+export interface CreateWithdrawBody {
+  /** Gross principal in sats — the fiat value the ATM measured. REQUIRED. */
+  principal_sats: number
+  /** Fiat amount for the settlement row + display. */
+  fiat_amount?: number
+  /** Fiat code; defaults to the machine's configured currency server-side. */
+  fiat_code?: string
+  /** Link display title. */
+  title?: string
+  /** Seconds between withdraws (default 1). */
+  wait_time?: number
+  /** Audit ref → settlement.nostr_event_id (use the ATM tx id). */
+  client_ref?: string
+}
+
+/** Response from `create_withdraw` — server-derived amounts + the LNURL to show. */
+export interface CreateWithdrawResult {
+  /** Settlement-watch key — `subscribe_payments { tag:'withdraw', link_id }`. */
+  link_id: string
+  /** bech32 LNURL — the QR the ATM displays. */
+  lnurl: string
+  /** Raw callback URL (alternative for QR generation). */
+  lnurl_url?: string
+  /** NET sats the customer receives (principal − fee). */
+  net_sats: number
+  /** Gross principal echoed back. */
+  principal_sats: number
+  /** Fee withheld (server-computed). */
+  fee_sats: number
+  k1?: string
+}
+
 export interface CreateWithdrawLinkBody {
   title: string
   min_withdrawable: number

From a762a7ea401096deded2afc876fa681fe50893ad Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 22 Jun 2026 15:43:09 +0200
Subject: [PATCH 19/82] fix(machine): guard the availability beacon sign
 against bunker blips
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The beacon's createSignedEvent (a bunker round-trip) sat OUTSIDE its try/catch,
and publish() is fire-and-forget — so a transient BunkerTimeoutError /
BunkerRejectedError during the periodic sign surfaced as an uncaught promise
rejection (seen on the Sintra after a bunker watchdog blip during the cash-in
smoke). Move the sign inside the try; the beacon re-publishes every interval, so
swallow + log is correct.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../composables/useAvailabilityBroadcast.ts   | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/apps/machine/src/composables/useAvailabilityBroadcast.ts b/apps/machine/src/composables/useAvailabilityBroadcast.ts
index a4968f7..20517e9 100644
--- a/apps/machine/src/composables/useAvailabilityBroadcast.ts
+++ b/apps/machine/src/composables/useAvailabilityBroadcast.ts
@@ -73,19 +73,22 @@ export function useAvailabilityBroadcast(options: UseAvailabilityBroadcastOption
       model,
     })
 
-    const event = await createSignedEvent(signer, {
-      kind: 30078,
-      created_at: Math.floor(Date.now() / 1000),
-      tags: [['d', 'atm-availability']],
-      content,
-    })
-
+    // Signing goes through the bunker, so it can throw BunkerTimeoutError /
+    // BunkerRejectedError — keep it INSIDE the try so a transient signer blip
+    // is swallowed (the beacon re-publishes every interval) rather than
+    // surfacing as an uncaught rejection. `publish()` is fire-and-forget.
     try {
+      const event = await createSignedEvent(signer, {
+        kind: 30078,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [['d', 'atm-availability']],
+        content,
+      })
       await nostrClient.publish(event)
       lastSnapshot = snap
       console.log('[Availability] Published:', content)
     } catch (e) {
-      console.warn('[Availability] Failed to publish:', e)
+      console.warn('[Availability] Publish failed (sign or relay):', e)
     }
   }
 

From 9935807f8c98aa985b1b1ef0ca6f5a09d310525f Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Tue, 23 Jun 2026 23:07:18 +0200
Subject: [PATCH 20/82] feat(machine): persist scanned spire-seed + signal
 unpaired state for wizard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foundation for the on-machine QR-pairing wizard (aiolabs/bitspire#52). An
unpaired ATM can now have a seed planted at runtime rather than only via
provisioning:

- electron IPC `state:save-spire-seed` writes VITE_SPIRE_SEED into the runtime
  .env (0600), and `app:relaunch` restarts the kiosk so the normal boot path
  (signer-resolver → connectNewSeed) does the actual bunker pairing. We
  deliberately do NOT pair in-renderer — persist + relaunch reuses the single,
  hardware-tested pairing path.
- signer-resolver throws a typed `NoPairingError` (distinct `.name`, survives
  the bundle boundary) when there's no seed and no binding, instead of a
  generic Error.
- init-error maps NoPairingError → `unpaired`, so the renderer can route a
  fresh machine to the interactive wizard (next commit) rather than a
  dead-end fault screen. Revoked/TTL bindings already map there too — re-pair
  is the same scan-a-fresh-seed flow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/main.ts                | 44 ++++++++++++++++++++
 apps/machine/electron/preload.ts             |  7 ++++
 apps/machine/src/services/init-error.ts      |  5 ++-
 apps/machine/src/services/signer-resolver.ts | 19 +++++++--
 apps/machine/src/types/electron.d.ts         |  2 +
 5 files changed, 72 insertions(+), 5 deletions(-)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index c35382d..516f32a 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -353,6 +353,50 @@ ipcMain.handle('state:reset-bootstrap-gate', (): void => {
   resetBootstrapGate()
 })
 
+// QR-pairing wizard (aiolabs/bitspire#52): an unpaired machine scans a
+// spire-seed off its camera, and we persist it as VITE_SPIRE_SEED in the
+// runtime .env so the next boot's signer-resolver redeems it (connectNewSeed)
+// exactly as if it had been provisioned. We deliberately do NOT pair here —
+// persisting + relaunching reuses the single, tested pairing path rather than
+// duplicating it in the renderer.
+function runtimeEnvPath(): string {
+  const base = fs.existsSync('/var/lib/bitspire') ? '/var/lib/bitspire' : process.cwd()
+  return path.join(base, '.env')
+}
+
+ipcMain.handle('state:save-spire-seed', (_event, seed: string): void => {
+  const trimmed = (seed || '').trim()
+  if (!trimmed) throw new Error('save-spire-seed: empty seed')
+  const envPath = runtimeEnvPath()
+  const line = `VITE_SPIRE_SEED=${trimmed}`
+  let lines: string[] = []
+  if (fs.existsSync(envPath)) {
+    lines = fs.readFileSync(envPath, 'utf8').split('\n')
+  }
+  const idx = lines.findIndex((l) => l.startsWith('VITE_SPIRE_SEED='))
+  if (idx >= 0) {
+    lines[idx] = line
+  } else {
+    // Drop a trailing empty element so we don't accumulate blank lines.
+    if (lines.length && lines[lines.length - 1] === '') lines.pop()
+    lines.push(line)
+  }
+  fs.writeFileSync(envPath, lines.join('\n') + '\n', { mode: 0o600 })
+  // Keep this process's view in sync so get-atm-secrets reflects the new seed
+  // even before relaunch (belt-and-suspenders; relaunch re-reads from disk).
+  process.env.VITE_SPIRE_SEED = trimmed
+  console.log('[Pairing] Spire seed persisted to', envPath)
+})
+
+// Relaunch the kiosk so the new seed is picked up by a clean boot. Under
+// systemd (bitspire.service) the exit triggers an automatic restart; in dev
+// Electron's relaunch re-spawns the process.
+ipcMain.handle('app:relaunch', (): void => {
+  console.log('[Pairing] Relaunching to apply new pairing')
+  app.relaunch()
+  app.exit(0)
+})
+
 // State persistence IPC handlers
 ipcMain.handle('state:load-cassettes', () => loadCassettes())
 ipcMain.handle('state:set-cassettes', (_event, cassettes) => setCassettes(cassettes))
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index f439de9..f1320fb 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -119,6 +119,11 @@ contextBridge.exposeInMainWorld('electronAPI', {
   clearBunkerBinding: (): Promise<void> => ipcRenderer.invoke('state:clear-bunker-binding'),
   resetBootstrapGate: (): Promise<void> => ipcRenderer.invoke('state:reset-bootstrap-gate'),
 
+  // QR-pairing wizard (aiolabs/bitspire#52): persist a scanned spire-seed,
+  // then relaunch so the normal boot flow pairs it.
+  saveSpireSeed: (seed: string): Promise<void> => ipcRenderer.invoke('state:save-spire-seed', seed),
+  relaunchApp: (): Promise<void> => ipcRenderer.invoke('app:relaunch'),
+
   applyOperatorCassettesConfig: (
     payload: {
       positions: Record<string, { denomination: number; count: number }>
@@ -234,6 +239,8 @@ declare global {
       saveBunkerBinding: (binding: BunkerBindingRecord) => Promise<void>
       clearBunkerBinding: () => Promise<void>
       resetBootstrapGate: () => Promise<void>
+      saveSpireSeed: (seed: string) => Promise<void>
+      relaunchApp: () => Promise<void>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number
diff --git a/apps/machine/src/services/init-error.ts b/apps/machine/src/services/init-error.ts
index f9b0c84..bbeb117 100644
--- a/apps/machine/src/services/init-error.ts
+++ b/apps/machine/src/services/init-error.ts
@@ -3,14 +3,17 @@
  * (see App.vue's MAINTENANCE_SCREENS).
  *
  * Bunker failures (aiolabs/bitspire#52) get dedicated screens:
+ * - `NoPairingError` (fresh machine, never paired) → `unpaired` — render the
+ *   interactive QR-pairing wizard so the operator can scan a spire-seed.
  * - `BunkerRejectedError` (revoked / TTL-expired / off-policy binding) →
- *   `unpaired` — the operator must re-pair the machine.
+ *   `unpaired` too — re-pairing is the same scan-a-fresh-seed flow.
  * - `BunkerTimeoutError` (signer/relay unreachable) → `signer-unreachable`,
  *   a transient condition.
  * Everything else surfaces its raw message (or the caller's fallback).
  */
 export function classifyInitError(error: unknown, fallback = 'Initialization failed'): string {
   const name = (error as { name?: string } | null)?.name
+  if (name === 'NoPairingError') return 'unpaired'
   if (name === 'BunkerRejectedError') return 'unpaired'
   if (name === 'BunkerTimeoutError') return 'signer-unreachable'
   return error instanceof Error ? error.message : fallback
diff --git a/apps/machine/src/services/signer-resolver.ts b/apps/machine/src/services/signer-resolver.ts
index 9bd0d5b..44aa4b5 100644
--- a/apps/machine/src/services/signer-resolver.ts
+++ b/apps/machine/src/services/signer-resolver.ts
@@ -31,6 +31,20 @@ import type { BunkerBindingRecord } from '@/types/electron'
 
 const isElectron = typeof window !== 'undefined' && window.electronAPI !== undefined
 
+/**
+ * Thrown in strict mode when the machine has no seed and no binding — it is
+ * genuinely unpaired, not misconfigured. The renderer catches this to show the
+ * QR-pairing wizard (camera scan of a spire-seed) rather than a fault screen.
+ * Distinct `.name` so it survives the bundle boundary (instanceof is fragile
+ * across the electron/renderer split). See services/init-error.ts.
+ */
+export class NoPairingError extends Error {
+  override readonly name = 'NoPairingError'
+  constructor() {
+    super('[Signer] Machine is unpaired — no spire seed and no bunker binding.')
+  }
+}
+
 export interface ResolveSignerOptions {
   /** Allow an ephemeral LocalSigner when no seed/binding exists (dev only). */
   allowEphemeral: boolean
@@ -109,8 +123,5 @@ export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer>
     return new LocalSigner(generateIdentity())
   }
 
-  throw new Error(
-    '[Signer] No spire seed and no bunker binding — cannot resolve a signing identity (strict mode). ' +
-      'Set VITE_SPIRE_SEED or pair the ATM.'
-  )
+  throw new NoPairingError()
 }
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index 17fe9af..64af629 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -98,6 +98,8 @@ declare global {
       saveBunkerBinding: (binding: BunkerBindingRecord) => Promise<void>
       clearBunkerBinding: () => Promise<void>
       resetBootstrapGate: () => Promise<void>
+      saveSpireSeed: (seed: string) => Promise<void>
+      relaunchApp: () => Promise<void>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number

From d22157b40c40dc716195d6676669607ffcadb94e Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Tue, 23 Jun 2026 23:07:31 +0200
Subject: [PATCH 21/82] feat(machine): pairing-source abstraction + QR/NFC
 capture + seed ingest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The capture half of the QR-pairing wizard (aiolabs/bitspire#52), behind a
`PairingSource` seam so the wizard UI stays agnostic to how the seed arrives:

- `QrPairingSource` — camera capture + decode via `qr` (paulmillr). Chosen
  over the dormant, unmaintained `jsqr`: `qr` is zero-dependency, auditable,
  dual MIT/Apache, actively maintained, and authored by the same person as the
  `@noble`/`@scure` crypto our nostr stack already trusts. Its `qr/dom.js`
  helper wraps getUserMedia + the per-frame decode loop.
- `NfcPairingSource` — Web NFC scaffold; `isAvailable()` is false on the
  Sintra's Linux Electron, so it's inert until real NFC hardware lands (the
  user flagged NFC as a plausible future pairing method).
- `ingestScannedSeed` — validates the scan parses as a spire-seed (rejecting a
  stray QR), persists it, and relaunches. Covered by unit tests
  (invalid-seed / no-bridge / persist-failed / happy path).
- `availablePairingSources()` probes each source and returns the runnable ones
  in preference order (camera first).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/package.json                     |   1 +
 .../services/pairing/__tests__/ingest.test.ts |  80 +++++
 apps/machine/src/services/pairing/index.ts    |  30 ++
 apps/machine/src/services/pairing/ingest.ts   |  63 ++++
 .../src/services/pairing/nfc-source.ts        |  67 +++++
 .../machine/src/services/pairing/qr-source.ts |  61 ++++
 apps/machine/src/services/pairing/types.ts    |  42 +++
 pnpm-lock.yaml                                | 279 +-----------------
 8 files changed, 354 insertions(+), 269 deletions(-)
 create mode 100644 apps/machine/src/services/pairing/__tests__/ingest.test.ts
 create mode 100644 apps/machine/src/services/pairing/index.ts
 create mode 100644 apps/machine/src/services/pairing/ingest.ts
 create mode 100644 apps/machine/src/services/pairing/nfc-source.ts
 create mode 100644 apps/machine/src/services/pairing/qr-source.ts
 create mode 100644 apps/machine/src/services/pairing/types.ts

diff --git a/apps/machine/package.json b/apps/machine/package.json
index 844211c..de432cb 100644
--- a/apps/machine/package.json
+++ b/apps/machine/package.json
@@ -37,6 +37,7 @@
     "marked": "^17.0.5",
     "nostr-tools": "^2.10.0",
     "pinia": "^2.2.0",
+    "qr": "^0.6.0",
     "qrcode.vue": "^3.6.0",
     "reka-ui": "^2.7.0",
     "tailwind-merge": "^3.4.0",
diff --git a/apps/machine/src/services/pairing/__tests__/ingest.test.ts b/apps/machine/src/services/pairing/__tests__/ingest.test.ts
new file mode 100644
index 0000000..7392de3
--- /dev/null
+++ b/apps/machine/src/services/pairing/__tests__/ingest.test.ts
@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { ingestScannedSeed } from '../ingest'
+import { SPIRE_SEED_SCHEME } from '@bitSpire/nostr-client'
+
+/** Mirror of spirekeeper pairing.py: urlsafe base64, padding stripped. */
+function makeSeed(json: unknown): string {
+  const b64 = Buffer.from(JSON.stringify(json), 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+  return SPIRE_SEED_SCHEME + b64
+}
+
+const SPIRE_PUBKEY = 'a'.repeat(64)
+const VALID_SEED = makeSeed({
+  v: 1,
+  spire_npub: 'npub1example',
+  spire_pubkey: SPIRE_PUBKEY,
+  bunker_url: `bunker://${SPIRE_PUBKEY}?relay=wss%3A%2F%2Fbunker.relay%2F&secret=deadbeef`,
+  relays: ['wss://events.relay/'],
+})
+
+describe('ingestScannedSeed', () => {
+  const originalWindow = globalThis.window
+
+  afterEach(() => {
+    globalThis.window = originalWindow
+    vi.restoreAllMocks()
+  })
+
+  it('rejects a non-seed scan without touching the bridge', async () => {
+    const saveSpireSeed = vi.fn()
+    globalThis.window = { electronAPI: { saveSpireSeed } } as unknown as Window & typeof globalThis
+
+    const result = await ingestScannedSeed('https://example.com/not-a-seed')
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('invalid-seed')
+    expect(saveSpireSeed).not.toHaveBeenCalled()
+  })
+
+  it('reports no-bridge when Electron is absent', async () => {
+    globalThis.window = {} as unknown as Window & typeof globalThis
+    const result = await ingestScannedSeed(VALID_SEED)
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('no-bridge')
+  })
+
+  it('persists the seed and relaunches on a valid scan', async () => {
+    const saveSpireSeed = vi.fn().mockResolvedValue(undefined)
+    const relaunchApp = vi.fn().mockResolvedValue(undefined)
+    globalThis.window = {
+      electronAPI: { saveSpireSeed, relaunchApp },
+    } as unknown as Window & typeof globalThis
+
+    const result = await ingestScannedSeed(`  ${VALID_SEED}  `) // tolerate whitespace
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.spirePubkey).toBe(SPIRE_PUBKEY)
+    expect(saveSpireSeed).toHaveBeenCalledWith(VALID_SEED)
+    expect(relaunchApp).toHaveBeenCalledOnce()
+  })
+
+  it('surfaces persist-failed when saveSpireSeed throws', async () => {
+    const saveSpireSeed = vi.fn().mockRejectedValue(new Error('EACCES'))
+    globalThis.window = { electronAPI: { saveSpireSeed } } as unknown as Window & typeof globalThis
+
+    const result = await ingestScannedSeed(VALID_SEED)
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('persist-failed')
+  })
+})
+
+describe('ingest does not pair in-renderer', () => {
+  it('never imports connect logic — persistence + relaunch only', () => {
+    // Guard: the design intentionally reuses the boot-time pairing path.
+    // If someone wires connectNewSeed here, this comment + the ingest source
+    // should be revisited together.
+    expect(ingestScannedSeed).toBeTypeOf('function')
+  })
+})
diff --git a/apps/machine/src/services/pairing/index.ts b/apps/machine/src/services/pairing/index.ts
new file mode 100644
index 0000000..67e3ade
--- /dev/null
+++ b/apps/machine/src/services/pairing/index.ts
@@ -0,0 +1,30 @@
+/**
+ * Pairing module surface (aiolabs/bitspire#52).
+ *
+ * `availablePairingSources()` probes each known source and returns those the
+ * current device can actually run, in preference order (camera first, NFC if
+ * present). The wizard renders the first available source and offers the rest
+ * as alternates.
+ */
+
+import { QrPairingSource } from './qr-source'
+import { NfcPairingSource } from './nfc-source'
+import type { PairingSource } from './types'
+
+export type { PairingSource, PairingSourceKind, PairingSourceStartOptions, StopCapture } from './types'
+export { QrPairingSource } from './qr-source'
+export { NfcPairingSource } from './nfc-source'
+export { ingestScannedSeed } from './ingest'
+export type { IngestResult } from './ingest'
+
+/** All sources in preference order, regardless of availability. */
+export function allPairingSources(): PairingSource[] {
+  return [new QrPairingSource(), new NfcPairingSource()]
+}
+
+/** Only the sources this device can run, in preference order. */
+export async function availablePairingSources(): Promise<PairingSource[]> {
+  const sources = allPairingSources()
+  const flags = await Promise.all(sources.map((s) => s.isAvailable()))
+  return sources.filter((_, i) => flags[i])
+}
diff --git a/apps/machine/src/services/pairing/ingest.ts b/apps/machine/src/services/pairing/ingest.ts
new file mode 100644
index 0000000..a758f1e
--- /dev/null
+++ b/apps/machine/src/services/pairing/ingest.ts
@@ -0,0 +1,63 @@
+/**
+ * Seed ingest pipeline (aiolabs/bitspire#52).
+ *
+ * Turns a raw scanned payload into a paired machine. The wizard captures a
+ * string off some PairingSource and hands it here; we:
+ *   1. validate it parses as a spire-seed (reject anything else — a QR on the
+ *      counter, a URL, a different protocol),
+ *   2. persist it as VITE_SPIRE_SEED via the Electron bridge,
+ *   3. relaunch so the normal boot path (signer-resolver → connectNewSeed)
+ *      performs the actual bunker pairing.
+ *
+ * We do NOT pair in-renderer here: persisting + relaunching reuses the single,
+ * hardware-tested pairing path rather than duplicating connect/redeem logic in
+ * the wizard. The trade-off is a ~kiosk-restart of latency, which is fine for a
+ * one-time provisioning step.
+ */
+
+import { parseSpireSeed, seedFingerprint } from '@bitSpire/nostr-client'
+
+export type IngestResult =
+  | { ok: true; spirePubkey: string; fingerprint: string; relays: string[] }
+  | { ok: false; reason: 'invalid-seed' | 'no-bridge' | 'persist-failed'; message: string }
+
+export async function ingestScannedSeed(raw: string): Promise<IngestResult> {
+  const trimmed = (raw || '').trim()
+
+  let spirePubkey: string
+  let relays: string[]
+  try {
+    const seed = parseSpireSeed(trimmed)
+    spirePubkey = seed.spirePubkey
+    relays = seed.relays
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'invalid-seed',
+      message: e instanceof Error ? e.message : 'Not a valid pairing code',
+    }
+  }
+
+  if (typeof window === 'undefined' || !window.electronAPI) {
+    return {
+      ok: false,
+      reason: 'no-bridge',
+      message: 'Pairing must run on the machine (no kiosk bridge available).',
+    }
+  }
+
+  try {
+    await window.electronAPI.saveSpireSeed(trimmed)
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'persist-failed',
+      message: e instanceof Error ? e.message : 'Could not save the pairing.',
+    }
+  }
+
+  // Fire-and-forget: the relaunch tears this process down.
+  void window.electronAPI.relaunchApp()
+
+  return { ok: true, spirePubkey, fingerprint: seedFingerprint(trimmed), relays }
+}
diff --git a/apps/machine/src/services/pairing/nfc-source.ts b/apps/machine/src/services/pairing/nfc-source.ts
new file mode 100644
index 0000000..5291b3c
--- /dev/null
+++ b/apps/machine/src/services/pairing/nfc-source.ts
@@ -0,0 +1,67 @@
+/**
+ * NFC pairing source — SCAFFOLD (aiolabs/bitspire#52).
+ *
+ * The user flagged NFC as a plausible future pairing method (tap a tag/phone
+ * carrying the spire-seed). This wires the seam against the Web NFC API
+ * (`NDEFReader`) so a future build can light it up without reworking the
+ * wizard. It is NOT active on current hardware: Web NFC ships only on Chrome
+ * for Android, so `isAvailable()` returns false on the Sintra's Linux Electron
+ * and the wizard simply won't offer it.
+ *
+ * When real NFC hardware lands (likely a HAL peripheral rather than Web NFC),
+ * replace the body of `start()` with that driver — the PairingSource contract
+ * stays the same.
+ */
+
+import type { PairingSource, PairingSourceStartOptions, StopCapture } from './types'
+
+// Minimal structural type for the Web NFC API (not in lib.dom for Electron).
+interface NDEFReaderLike {
+  scan(): Promise<void>
+  addEventListener(
+    type: 'reading',
+    listener: (event: { message: { records: Array<{ recordType: string; data?: BufferSource }> } }) => void
+  ): void
+  addEventListener(type: 'readingerror', listener: (event: unknown) => void): void
+}
+
+function getNDEFReaderCtor(): (new () => NDEFReaderLike) | null {
+  const ctor = (globalThis as { NDEFReader?: new () => NDEFReaderLike }).NDEFReader
+  return ctor ?? null
+}
+
+export class NfcPairingSource implements PairingSource {
+  readonly kind = 'nfc' as const
+  readonly label = 'NFC tap'
+
+  async isAvailable(): Promise<boolean> {
+    return getNDEFReaderCtor() !== null
+  }
+
+  async start(opts: PairingSourceStartOptions): Promise<StopCapture> {
+    const Ctor = getNDEFReaderCtor()
+    if (!Ctor) throw new Error('Web NFC unavailable on this device')
+
+    const reader = new Ctor()
+    const decoder = new TextDecoder()
+    let stopped = false
+
+    reader.addEventListener('reading', (event) => {
+      if (stopped) return
+      for (const record of event.message.records) {
+        if (record.recordType === 'text' && record.data) {
+          const raw = decoder.decode(record.data).trim()
+          if (raw) opts.onScan(raw)
+        }
+      }
+    })
+    reader.addEventListener('readingerror', (e) => opts.onError?.(e))
+
+    await reader.scan()
+    // Web NFC has no explicit stop; the AbortController form would, but the
+    // scaffold just flips a guard so late events are ignored after teardown.
+    return () => {
+      stopped = true
+    }
+  }
+}
diff --git a/apps/machine/src/services/pairing/qr-source.ts b/apps/machine/src/services/pairing/qr-source.ts
new file mode 100644
index 0000000..9dbfe92
--- /dev/null
+++ b/apps/machine/src/services/pairing/qr-source.ts
@@ -0,0 +1,61 @@
+/**
+ * Camera-based QR pairing source (aiolabs/bitspire#52).
+ *
+ * Decodes with `qr` (paulmillr) — a zero-dependency, auditable, dual
+ * MIT/Apache library from the same author as the `@noble`/`@scure` crypto our
+ * nostr stack already trusts (chosen over the dormant `jsqr` for that ethos +
+ * active maintenance). Its `qr/dom.js` browser helper wraps getUserMedia and
+ * the per-frame decode loop, so this source is a thin adapter onto the
+ * PairingSource contract.
+ *
+ * The first successful decode wins; the loop then stops itself so a single
+ * seed isn't ingested repeatedly.
+ */
+
+import { QRCanvas, frontalCamera, frameLoop } from 'qr/dom.js'
+import type { PairingSource, PairingSourceStartOptions, StopCapture } from './types'
+
+export class QrPairingSource implements PairingSource {
+  readonly kind = 'qr' as const
+  readonly label = 'Camera'
+
+  async isAvailable(): Promise<boolean> {
+    return (
+      typeof navigator !== 'undefined' &&
+      !!navigator.mediaDevices &&
+      typeof navigator.mediaDevices.getUserMedia === 'function'
+    )
+  }
+
+  async start(opts: PairingSourceStartOptions): Promise<StopCapture> {
+    const { onScan, onError, video } = opts
+    if (!video) throw new Error('QrPairingSource requires a <video> element')
+
+    const camera = await frontalCamera(video)
+    const canvas = new QRCanvas() // decode-only; no overlay canvases needed
+
+    let stopped = false
+    let cancel: (() => void) | null = null
+    const stop: StopCapture = () => {
+      if (stopped) return
+      stopped = true
+      cancel?.()
+      camera.stop()
+    }
+
+    cancel = frameLoop(() => {
+      if (stopped) return
+      try {
+        const result = camera.readFrame(canvas)
+        if (result) {
+          stop()
+          onScan(result)
+        }
+      } catch (e) {
+        onError?.(e)
+      }
+    })
+
+    return stop
+  }
+}
diff --git a/apps/machine/src/services/pairing/types.ts b/apps/machine/src/services/pairing/types.ts
new file mode 100644
index 0000000..725eb9c
--- /dev/null
+++ b/apps/machine/src/services/pairing/types.ts
@@ -0,0 +1,42 @@
+/**
+ * Pairing-source abstraction (aiolabs/bitspire#52).
+ *
+ * A fresh ATM is paired by getting a `spire-seed:v1:…` onto the device. The
+ * operator's spirekeeper mints that seed and renders it as a QR (and, later,
+ * possibly an NFC tag). The machine ingests it via whatever capture hardware
+ * it has — today a camera, tomorrow maybe an NFC reader or a HAL barcode
+ * scanner. `PairingSource` is the seam that keeps the wizard UI and the
+ * ingest pipeline agnostic to *how* the seed arrived.
+ *
+ * Implementations live next to this file: `qr-source.ts` (camera + jsQR),
+ * `nfc-source.ts` (Web NFC scaffold). A HAL-scanner source can be added the
+ * same way without touching the wizard.
+ */
+
+export type PairingSourceKind = 'qr' | 'nfc'
+
+export interface PairingSourceStartOptions {
+  /** Invoked with each decoded payload (the raw seed string). */
+  onScan: (raw: string) => void
+  /** Invoked on a non-fatal capture error (e.g. a frame decode glitch). */
+  onError?: (error: unknown) => void
+  /**
+   * The <video> element the camera preview renders into. Required by
+   * camera-based sources; ignored by sources that don't show a viewfinder
+   * (e.g. NFC).
+   */
+  video?: HTMLVideoElement
+}
+
+/** Releases capture hardware (camera stream, NFC reader). Idempotent. */
+export type StopCapture = () => void
+
+export interface PairingSource {
+  readonly kind: PairingSourceKind
+  /** Short label for the wizard's source picker (e.g. "Camera", "NFC tap"). */
+  readonly label: string
+  /** Whether this source can run in the current environment. */
+  isAvailable(): Promise<boolean>
+  /** Begin capturing; resolves once hardware is live. */
+  start(opts: PairingSourceStartOptions): Promise<StopCapture>
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3218ae5..0fe2b33 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -65,6 +65,9 @@ importers:
       pinia:
         specifier: ^2.2.0
         version: 2.3.1(typescript@5.9.3)(vue@3.5.27(typescript@5.9.3))
+      qr:
+        specifier: ^0.6.0
+        version: 0.6.0
       qrcode.vue:
         specifier: ^3.6.0
         version: 3.6.0(vue@3.5.27(typescript@5.9.3))
@@ -353,12 +356,6 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
-  '@esbuild/aix-ppc64@0.27.2':
-    resolution: {integrity: sha512-GZMB+a0mOMZs4MpDbj8RJp4cw+w1WV5NYD6xzgvzUJ5Ek2jerwfO2eADyI6ExDSUED+1X8aMbegahsJi+8mgpw==}
-    engines: {node: '>=18'}
-    cpu: [ppc64]
-    os: [aix]
-
   '@esbuild/aix-ppc64@0.27.4':
     resolution: {integrity: sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==}
     engines: {node: '>=18'}
@@ -377,12 +374,6 @@ packages:
     cpu: [arm64]
     os: [android]
 
-  '@esbuild/android-arm64@0.27.2':
-    resolution: {integrity: sha512-pvz8ZZ7ot/RBphf8fv60ljmaoydPU12VuXHImtAs0XhLLw+EXBi2BLe3OYSBslR4rryHvweW5gmkKFwTiFy6KA==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [android]
-
   '@esbuild/android-arm64@0.27.4':
     resolution: {integrity: sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==}
     engines: {node: '>=18'}
@@ -401,12 +392,6 @@ packages:
     cpu: [arm]
     os: [android]
 
-  '@esbuild/android-arm@0.27.2':
-    resolution: {integrity: sha512-DVNI8jlPa7Ujbr1yjU2PfUSRtAUZPG9I1RwW4F4xFB1Imiu2on0ADiI/c3td+KmDtVKNbi+nffGDQMfcIMkwIA==}
-    engines: {node: '>=18'}
-    cpu: [arm]
-    os: [android]
-
   '@esbuild/android-arm@0.27.4':
     resolution: {integrity: sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==}
     engines: {node: '>=18'}
@@ -425,12 +410,6 @@ packages:
     cpu: [x64]
     os: [android]
 
-  '@esbuild/android-x64@0.27.2':
-    resolution: {integrity: sha512-z8Ank4Byh4TJJOh4wpz8g2vDy75zFL0TlZlkUkEwYXuPSgX8yzep596n6mT7905kA9uHZsf/o2OJZubl2l3M7A==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [android]
-
   '@esbuild/android-x64@0.27.4':
     resolution: {integrity: sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==}
     engines: {node: '>=18'}
@@ -449,12 +428,6 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
-  '@esbuild/darwin-arm64@0.27.2':
-    resolution: {integrity: sha512-davCD2Zc80nzDVRwXTcQP/28fiJbcOwvdolL0sOiOsbwBa72kegmVU0Wrh1MYrbuCL98Omp5dVhQFWRKR2ZAlg==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [darwin]
-
   '@esbuild/darwin-arm64@0.27.4':
     resolution: {integrity: sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==}
     engines: {node: '>=18'}
@@ -473,12 +446,6 @@ packages:
     cpu: [x64]
     os: [darwin]
 
-  '@esbuild/darwin-x64@0.27.2':
-    resolution: {integrity: sha512-ZxtijOmlQCBWGwbVmwOF/UCzuGIbUkqB1faQRf5akQmxRJ1ujusWsb3CVfk/9iZKr2L5SMU5wPBi1UWbvL+VQA==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [darwin]
-
   '@esbuild/darwin-x64@0.27.4':
     resolution: {integrity: sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==}
     engines: {node: '>=18'}
@@ -497,12 +464,6 @@ packages:
     cpu: [arm64]
     os: [freebsd]
 
-  '@esbuild/freebsd-arm64@0.27.2':
-    resolution: {integrity: sha512-lS/9CN+rgqQ9czogxlMcBMGd+l8Q3Nj1MFQwBZJyoEKI50XGxwuzznYdwcav6lpOGv5BqaZXqvBSiB/kJ5op+g==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [freebsd]
-
   '@esbuild/freebsd-arm64@0.27.4':
     resolution: {integrity: sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==}
     engines: {node: '>=18'}
@@ -521,12 +482,6 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
-  '@esbuild/freebsd-x64@0.27.2':
-    resolution: {integrity: sha512-tAfqtNYb4YgPnJlEFu4c212HYjQWSO/w/h/lQaBK7RbwGIkBOuNKQI9tqWzx7Wtp7bTPaGC6MJvWI608P3wXYA==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [freebsd]
-
   '@esbuild/freebsd-x64@0.27.4':
     resolution: {integrity: sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==}
     engines: {node: '>=18'}
@@ -545,12 +500,6 @@ packages:
     cpu: [arm64]
     os: [linux]
 
-  '@esbuild/linux-arm64@0.27.2':
-    resolution: {integrity: sha512-hYxN8pr66NsCCiRFkHUAsxylNOcAQaxSSkHMMjcpx0si13t1LHFphxJZUiGwojB1a/Hd5OiPIqDdXONia6bhTw==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [linux]
-
   '@esbuild/linux-arm64@0.27.4':
     resolution: {integrity: sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==}
     engines: {node: '>=18'}
@@ -569,12 +518,6 @@ packages:
     cpu: [arm]
     os: [linux]
 
-  '@esbuild/linux-arm@0.27.2':
-    resolution: {integrity: sha512-vWfq4GaIMP9AIe4yj1ZUW18RDhx6EPQKjwe7n8BbIecFtCQG4CfHGaHuh7fdfq+y3LIA2vGS/o9ZBGVxIDi9hw==}
-    engines: {node: '>=18'}
-    cpu: [arm]
-    os: [linux]
-
   '@esbuild/linux-arm@0.27.4':
     resolution: {integrity: sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==}
     engines: {node: '>=18'}
@@ -593,12 +536,6 @@ packages:
     cpu: [ia32]
     os: [linux]
 
-  '@esbuild/linux-ia32@0.27.2':
-    resolution: {integrity: sha512-MJt5BRRSScPDwG2hLelYhAAKh9imjHK5+NE/tvnRLbIqUWa+0E9N4WNMjmp/kXXPHZGqPLxggwVhz7QP8CTR8w==}
-    engines: {node: '>=18'}
-    cpu: [ia32]
-    os: [linux]
-
   '@esbuild/linux-ia32@0.27.4':
     resolution: {integrity: sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==}
     engines: {node: '>=18'}
@@ -617,12 +554,6 @@ packages:
     cpu: [loong64]
     os: [linux]
 
-  '@esbuild/linux-loong64@0.27.2':
-    resolution: {integrity: sha512-lugyF1atnAT463aO6KPshVCJK5NgRnU4yb3FUumyVz+cGvZbontBgzeGFO1nF+dPueHD367a2ZXe1NtUkAjOtg==}
-    engines: {node: '>=18'}
-    cpu: [loong64]
-    os: [linux]
-
   '@esbuild/linux-loong64@0.27.4':
     resolution: {integrity: sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==}
     engines: {node: '>=18'}
@@ -641,12 +572,6 @@ packages:
     cpu: [mips64el]
     os: [linux]
 
-  '@esbuild/linux-mips64el@0.27.2':
-    resolution: {integrity: sha512-nlP2I6ArEBewvJ2gjrrkESEZkB5mIoaTswuqNFRv/WYd+ATtUpe9Y09RnJvgvdag7he0OWgEZWhviS1OTOKixw==}
-    engines: {node: '>=18'}
-    cpu: [mips64el]
-    os: [linux]
-
   '@esbuild/linux-mips64el@0.27.4':
     resolution: {integrity: sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==}
     engines: {node: '>=18'}
@@ -665,12 +590,6 @@ packages:
     cpu: [ppc64]
     os: [linux]
 
-  '@esbuild/linux-ppc64@0.27.2':
-    resolution: {integrity: sha512-C92gnpey7tUQONqg1n6dKVbx3vphKtTHJaNG2Ok9lGwbZil6DrfyecMsp9CrmXGQJmZ7iiVXvvZH6Ml5hL6XdQ==}
-    engines: {node: '>=18'}
-    cpu: [ppc64]
-    os: [linux]
-
   '@esbuild/linux-ppc64@0.27.4':
     resolution: {integrity: sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==}
     engines: {node: '>=18'}
@@ -689,12 +608,6 @@ packages:
     cpu: [riscv64]
     os: [linux]
 
-  '@esbuild/linux-riscv64@0.27.2':
-    resolution: {integrity: sha512-B5BOmojNtUyN8AXlK0QJyvjEZkWwy/FKvakkTDCziX95AowLZKR6aCDhG7LeF7uMCXEJqwa8Bejz5LTPYm8AvA==}
-    engines: {node: '>=18'}
-    cpu: [riscv64]
-    os: [linux]
-
   '@esbuild/linux-riscv64@0.27.4':
     resolution: {integrity: sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==}
     engines: {node: '>=18'}
@@ -713,12 +626,6 @@ packages:
     cpu: [s390x]
     os: [linux]
 
-  '@esbuild/linux-s390x@0.27.2':
-    resolution: {integrity: sha512-p4bm9+wsPwup5Z8f4EpfN63qNagQ47Ua2znaqGH6bqLlmJ4bx97Y9JdqxgGZ6Y8xVTixUnEkoKSHcpRlDnNr5w==}
-    engines: {node: '>=18'}
-    cpu: [s390x]
-    os: [linux]
-
   '@esbuild/linux-s390x@0.27.4':
     resolution: {integrity: sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==}
     engines: {node: '>=18'}
@@ -737,12 +644,6 @@ packages:
     cpu: [x64]
     os: [linux]
 
-  '@esbuild/linux-x64@0.27.2':
-    resolution: {integrity: sha512-uwp2Tip5aPmH+NRUwTcfLb+W32WXjpFejTIOWZFw/v7/KnpCDKG66u4DLcurQpiYTiYwQ9B7KOeMJvLCu/OvbA==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [linux]
-
   '@esbuild/linux-x64@0.27.4':
     resolution: {integrity: sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==}
     engines: {node: '>=18'}
@@ -755,12 +656,6 @@ packages:
     cpu: [arm64]
     os: [netbsd]
 
-  '@esbuild/netbsd-arm64@0.27.2':
-    resolution: {integrity: sha512-Kj6DiBlwXrPsCRDeRvGAUb/LNrBASrfqAIok+xB0LxK8CHqxZ037viF13ugfsIpePH93mX7xfJp97cyDuTZ3cw==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [netbsd]
-
   '@esbuild/netbsd-arm64@0.27.4':
     resolution: {integrity: sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==}
     engines: {node: '>=18'}
@@ -779,12 +674,6 @@ packages:
     cpu: [x64]
     os: [netbsd]
 
-  '@esbuild/netbsd-x64@0.27.2':
-    resolution: {integrity: sha512-HwGDZ0VLVBY3Y+Nw0JexZy9o/nUAWq9MlV7cahpaXKW6TOzfVno3y3/M8Ga8u8Yr7GldLOov27xiCnqRZf0tCA==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [netbsd]
-
   '@esbuild/netbsd-x64@0.27.4':
     resolution: {integrity: sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==}
     engines: {node: '>=18'}
@@ -797,12 +686,6 @@ packages:
     cpu: [arm64]
     os: [openbsd]
 
-  '@esbuild/openbsd-arm64@0.27.2':
-    resolution: {integrity: sha512-DNIHH2BPQ5551A7oSHD0CKbwIA/Ox7+78/AWkbS5QoRzaqlev2uFayfSxq68EkonB+IKjiuxBFoV8ESJy8bOHA==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [openbsd]
-
   '@esbuild/openbsd-arm64@0.27.4':
     resolution: {integrity: sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==}
     engines: {node: '>=18'}
@@ -821,12 +704,6 @@ packages:
     cpu: [x64]
     os: [openbsd]
 
-  '@esbuild/openbsd-x64@0.27.2':
-    resolution: {integrity: sha512-/it7w9Nb7+0KFIzjalNJVR5bOzA9Vay+yIPLVHfIQYG/j+j9VTH84aNB8ExGKPU4AzfaEvN9/V4HV+F+vo8OEg==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [openbsd]
-
   '@esbuild/openbsd-x64@0.27.4':
     resolution: {integrity: sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==}
     engines: {node: '>=18'}
@@ -839,12 +716,6 @@ packages:
     cpu: [arm64]
     os: [openharmony]
 
-  '@esbuild/openharmony-arm64@0.27.2':
-    resolution: {integrity: sha512-LRBbCmiU51IXfeXk59csuX/aSaToeG7w48nMwA6049Y4J4+VbWALAuXcs+qcD04rHDuSCSRKdmY63sruDS5qag==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [openharmony]
-
   '@esbuild/openharmony-arm64@0.27.4':
     resolution: {integrity: sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==}
     engines: {node: '>=18'}
@@ -863,12 +734,6 @@ packages:
     cpu: [x64]
     os: [sunos]
 
-  '@esbuild/sunos-x64@0.27.2':
-    resolution: {integrity: sha512-kMtx1yqJHTmqaqHPAzKCAkDaKsffmXkPHThSfRwZGyuqyIeBvf08KSsYXl+abf5HDAPMJIPnbBfXvP2ZC2TfHg==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [sunos]
-
   '@esbuild/sunos-x64@0.27.4':
     resolution: {integrity: sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==}
     engines: {node: '>=18'}
@@ -887,12 +752,6 @@ packages:
     cpu: [arm64]
     os: [win32]
 
-  '@esbuild/win32-arm64@0.27.2':
-    resolution: {integrity: sha512-Yaf78O/B3Kkh+nKABUF++bvJv5Ijoy9AN1ww904rOXZFLWVc5OLOfL56W+C8F9xn5JQZa3UX6m+IktJnIb1Jjg==}
-    engines: {node: '>=18'}
-    cpu: [arm64]
-    os: [win32]
-
   '@esbuild/win32-arm64@0.27.4':
     resolution: {integrity: sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==}
     engines: {node: '>=18'}
@@ -911,12 +770,6 @@ packages:
     cpu: [ia32]
     os: [win32]
 
-  '@esbuild/win32-ia32@0.27.2':
-    resolution: {integrity: sha512-Iuws0kxo4yusk7sw70Xa2E2imZU5HoixzxfGCdxwBdhiDgt9vX9VUCBhqcwY7/uh//78A1hMkkROMJq9l27oLQ==}
-    engines: {node: '>=18'}
-    cpu: [ia32]
-    os: [win32]
-
   '@esbuild/win32-ia32@0.27.4':
     resolution: {integrity: sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==}
     engines: {node: '>=18'}
@@ -935,12 +788,6 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@esbuild/win32-x64@0.27.2':
-    resolution: {integrity: sha512-sRdU18mcKf7F+YgheI/zGf5alZatMUTKj/jNS6l744f9u3WFu4v7twcUI9vu4mknF4Y9aDlblIie0IM+5xxaqQ==}
-    engines: {node: '>=18'}
-    cpu: [x64]
-    os: [win32]
-
   '@esbuild/win32-x64@0.27.4':
     resolution: {integrity: sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==}
     engines: {node: '>=18'}
@@ -2049,11 +1896,6 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
-  esbuild@0.27.2:
-    resolution: {integrity: sha512-HyNQImnsOC7X9PMNaCIeAm4ISCQXs5a5YasTXVliKv4uuBo1dKrG0A+uQS8M5eXjVMnLg3WgXaKvprHlFJQffw==}
-    engines: {node: '>=18'}
-    hasBin: true
-
   esbuild@0.27.4:
     resolution: {integrity: sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==}
     engines: {node: '>=18'}
@@ -2860,6 +2702,10 @@ packages:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
 
+  qr@0.6.0:
+    resolution: {integrity: sha512-P23VoX7SipHALdiIYG+D+LT/6n22dNKwV92FAb3d+Nlki/5WisSsfLt0UDFz2XEBtuwrECTznvu+chKKFCSYhA==}
+    engines: {node: '>= 20.19.0'}
+
   qrcode.vue@3.6.0:
     resolution: {integrity: sha512-vQcl2fyHYHMjDO1GguCldJxepq2izQjBkDEEu9NENgfVKP6mv/e2SU62WbqYHGwTgWXLhxZ1NCD1dAZKHQq1fg==}
     peerDependencies:
@@ -3579,9 +3425,6 @@ snapshots:
   '@esbuild/aix-ppc64@0.25.12':
     optional: true
 
-  '@esbuild/aix-ppc64@0.27.2':
-    optional: true
-
   '@esbuild/aix-ppc64@0.27.4':
     optional: true
 
@@ -3591,9 +3434,6 @@ snapshots:
   '@esbuild/android-arm64@0.25.12':
     optional: true
 
-  '@esbuild/android-arm64@0.27.2':
-    optional: true
-
   '@esbuild/android-arm64@0.27.4':
     optional: true
 
@@ -3603,9 +3443,6 @@ snapshots:
   '@esbuild/android-arm@0.25.12':
     optional: true
 
-  '@esbuild/android-arm@0.27.2':
-    optional: true
-
   '@esbuild/android-arm@0.27.4':
     optional: true
 
@@ -3615,9 +3452,6 @@ snapshots:
   '@esbuild/android-x64@0.25.12':
     optional: true
 
-  '@esbuild/android-x64@0.27.2':
-    optional: true
-
   '@esbuild/android-x64@0.27.4':
     optional: true
 
@@ -3627,9 +3461,6 @@ snapshots:
   '@esbuild/darwin-arm64@0.25.12':
     optional: true
 
-  '@esbuild/darwin-arm64@0.27.2':
-    optional: true
-
   '@esbuild/darwin-arm64@0.27.4':
     optional: true
 
@@ -3639,9 +3470,6 @@ snapshots:
   '@esbuild/darwin-x64@0.25.12':
     optional: true
 
-  '@esbuild/darwin-x64@0.27.2':
-    optional: true
-
   '@esbuild/darwin-x64@0.27.4':
     optional: true
 
@@ -3651,9 +3479,6 @@ snapshots:
   '@esbuild/freebsd-arm64@0.25.12':
     optional: true
 
-  '@esbuild/freebsd-arm64@0.27.2':
-    optional: true
-
   '@esbuild/freebsd-arm64@0.27.4':
     optional: true
 
@@ -3663,9 +3488,6 @@ snapshots:
   '@esbuild/freebsd-x64@0.25.12':
     optional: true
 
-  '@esbuild/freebsd-x64@0.27.2':
-    optional: true
-
   '@esbuild/freebsd-x64@0.27.4':
     optional: true
 
@@ -3675,9 +3497,6 @@ snapshots:
   '@esbuild/linux-arm64@0.25.12':
     optional: true
 
-  '@esbuild/linux-arm64@0.27.2':
-    optional: true
-
   '@esbuild/linux-arm64@0.27.4':
     optional: true
 
@@ -3687,9 +3506,6 @@ snapshots:
   '@esbuild/linux-arm@0.25.12':
     optional: true
 
-  '@esbuild/linux-arm@0.27.2':
-    optional: true
-
   '@esbuild/linux-arm@0.27.4':
     optional: true
 
@@ -3699,9 +3515,6 @@ snapshots:
   '@esbuild/linux-ia32@0.25.12':
     optional: true
 
-  '@esbuild/linux-ia32@0.27.2':
-    optional: true
-
   '@esbuild/linux-ia32@0.27.4':
     optional: true
 
@@ -3711,9 +3524,6 @@ snapshots:
   '@esbuild/linux-loong64@0.25.12':
     optional: true
 
-  '@esbuild/linux-loong64@0.27.2':
-    optional: true
-
   '@esbuild/linux-loong64@0.27.4':
     optional: true
 
@@ -3723,9 +3533,6 @@ snapshots:
   '@esbuild/linux-mips64el@0.25.12':
     optional: true
 
-  '@esbuild/linux-mips64el@0.27.2':
-    optional: true
-
   '@esbuild/linux-mips64el@0.27.4':
     optional: true
 
@@ -3735,9 +3542,6 @@ snapshots:
   '@esbuild/linux-ppc64@0.25.12':
     optional: true
 
-  '@esbuild/linux-ppc64@0.27.2':
-    optional: true
-
   '@esbuild/linux-ppc64@0.27.4':
     optional: true
 
@@ -3747,9 +3551,6 @@ snapshots:
   '@esbuild/linux-riscv64@0.25.12':
     optional: true
 
-  '@esbuild/linux-riscv64@0.27.2':
-    optional: true
-
   '@esbuild/linux-riscv64@0.27.4':
     optional: true
 
@@ -3759,9 +3560,6 @@ snapshots:
   '@esbuild/linux-s390x@0.25.12':
     optional: true
 
-  '@esbuild/linux-s390x@0.27.2':
-    optional: true
-
   '@esbuild/linux-s390x@0.27.4':
     optional: true
 
@@ -3771,18 +3569,12 @@ snapshots:
   '@esbuild/linux-x64@0.25.12':
     optional: true
 
-  '@esbuild/linux-x64@0.27.2':
-    optional: true
-
   '@esbuild/linux-x64@0.27.4':
     optional: true
 
   '@esbuild/netbsd-arm64@0.25.12':
     optional: true
 
-  '@esbuild/netbsd-arm64@0.27.2':
-    optional: true
-
   '@esbuild/netbsd-arm64@0.27.4':
     optional: true
 
@@ -3792,18 +3584,12 @@ snapshots:
   '@esbuild/netbsd-x64@0.25.12':
     optional: true
 
-  '@esbuild/netbsd-x64@0.27.2':
-    optional: true
-
   '@esbuild/netbsd-x64@0.27.4':
     optional: true
 
   '@esbuild/openbsd-arm64@0.25.12':
     optional: true
 
-  '@esbuild/openbsd-arm64@0.27.2':
-    optional: true
-
   '@esbuild/openbsd-arm64@0.27.4':
     optional: true
 
@@ -3813,18 +3599,12 @@ snapshots:
   '@esbuild/openbsd-x64@0.25.12':
     optional: true
 
-  '@esbuild/openbsd-x64@0.27.2':
-    optional: true
-
   '@esbuild/openbsd-x64@0.27.4':
     optional: true
 
   '@esbuild/openharmony-arm64@0.25.12':
     optional: true
 
-  '@esbuild/openharmony-arm64@0.27.2':
-    optional: true
-
   '@esbuild/openharmony-arm64@0.27.4':
     optional: true
 
@@ -3834,9 +3614,6 @@ snapshots:
   '@esbuild/sunos-x64@0.25.12':
     optional: true
 
-  '@esbuild/sunos-x64@0.27.2':
-    optional: true
-
   '@esbuild/sunos-x64@0.27.4':
     optional: true
 
@@ -3846,9 +3623,6 @@ snapshots:
   '@esbuild/win32-arm64@0.25.12':
     optional: true
 
-  '@esbuild/win32-arm64@0.27.2':
-    optional: true
-
   '@esbuild/win32-arm64@0.27.4':
     optional: true
 
@@ -3858,9 +3632,6 @@ snapshots:
   '@esbuild/win32-ia32@0.25.12':
     optional: true
 
-  '@esbuild/win32-ia32@0.27.2':
-    optional: true
-
   '@esbuild/win32-ia32@0.27.4':
     optional: true
 
@@ -3870,9 +3641,6 @@ snapshots:
   '@esbuild/win32-x64@0.25.12':
     optional: true
 
-  '@esbuild/win32-x64@0.27.2':
-    optional: true
-
   '@esbuild/win32-x64@0.27.4':
     optional: true
 
@@ -5133,35 +4901,6 @@ snapshots:
       '@esbuild/win32-ia32': 0.25.12
       '@esbuild/win32-x64': 0.25.12
 
-  esbuild@0.27.2:
-    optionalDependencies:
-      '@esbuild/aix-ppc64': 0.27.2
-      '@esbuild/android-arm': 0.27.2
-      '@esbuild/android-arm64': 0.27.2
-      '@esbuild/android-x64': 0.27.2
-      '@esbuild/darwin-arm64': 0.27.2
-      '@esbuild/darwin-x64': 0.27.2
-      '@esbuild/freebsd-arm64': 0.27.2
-      '@esbuild/freebsd-x64': 0.27.2
-      '@esbuild/linux-arm': 0.27.2
-      '@esbuild/linux-arm64': 0.27.2
-      '@esbuild/linux-ia32': 0.27.2
-      '@esbuild/linux-loong64': 0.27.2
-      '@esbuild/linux-mips64el': 0.27.2
-      '@esbuild/linux-ppc64': 0.27.2
-      '@esbuild/linux-riscv64': 0.27.2
-      '@esbuild/linux-s390x': 0.27.2
-      '@esbuild/linux-x64': 0.27.2
-      '@esbuild/netbsd-arm64': 0.27.2
-      '@esbuild/netbsd-x64': 0.27.2
-      '@esbuild/openbsd-arm64': 0.27.2
-      '@esbuild/openbsd-x64': 0.27.2
-      '@esbuild/openharmony-arm64': 0.27.2
-      '@esbuild/sunos-x64': 0.27.2
-      '@esbuild/win32-arm64': 0.27.2
-      '@esbuild/win32-ia32': 0.27.2
-      '@esbuild/win32-x64': 0.27.2
-
   esbuild@0.27.4:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.27.4
@@ -5982,6 +5721,8 @@ snapshots:
 
   punycode@2.3.1: {}
 
+  qr@0.6.0: {}
+
   qrcode.vue@3.6.0(vue@3.5.27(typescript@5.9.3)):
     dependencies:
       vue: 3.5.27(typescript@5.9.3)
@@ -6346,7 +6087,7 @@ snapshots:
 
   tsx@4.21.0:
     dependencies:
-      esbuild: 0.27.2
+      esbuild: 0.27.4
       get-tsconfig: 4.13.0
     optionalDependencies:
       fsevents: 2.3.3

From aca6aebcb6974a057615f189a54999affcb43238 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Tue, 23 Jun 2026 23:07:43 +0200
Subject: [PATCH 22/82] feat(machine): render QR-pairing wizard for unpaired
 machines

Wires the capture + ingest pieces into a screen (aiolabs/bitspire#52). When
the machine boots `unpaired` (fresh, or binding revoked/expired) and runs
under Electron, App.vue renders `PairingWizard` in place of the static
"Pairing Required" card.

The wizard probes available sources, shows the camera viewfinder, and on a
valid scan persists + relaunches. A stray/non-seed QR is rejected with a hint
and scanning resumes. NFC (when present) appears as an alternate source
button. Browser dev (no Electron bridge) still falls back to the static card.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/App.vue                      |  14 +-
 apps/machine/src/components/PairingWizard.vue | 160 ++++++++++++++++++
 2 files changed, 173 insertions(+), 1 deletion(-)
 create mode 100644 apps/machine/src/components/PairingWizard.vue

diff --git a/apps/machine/src/App.vue b/apps/machine/src/App.vue
index 48cfc8a..f28b639 100644
--- a/apps/machine/src/App.vue
+++ b/apps/machine/src/App.vue
@@ -8,6 +8,7 @@ import { classifyInitError } from '@/services/init-error'
 import { Badge } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { Sun, Moon } from 'lucide-vue-next'
+import PairingWizard from '@/components/PairingWizard.vue'
 
 const atmStore = useAtmStore()
 const route = useRoute()
@@ -61,6 +62,14 @@ const isKnownMaintenanceScreen = computed(
   () => !!atmStore.initError && atmStore.initError in MAINTENANCE_SCREENS
 )
 
+/**
+ * `unpaired` is interactive, not a dead-end: render the QR-pairing wizard so
+ * the operator can scan a spire-seed on-machine (aiolabs/bitspire#52). The
+ * wizard only works under Electron (needs the seed-persist + relaunch bridge);
+ * in browser dev it falls back to the static card.
+ */
+const showPairingWizard = computed(() => atmStore.initError === 'unpaired' && isElectron)
+
 const formattedBtcPrice = computed(() => {
   if (atmStore.btcPrice === null) return null
   const local = `${atmStore.fiatCode}/BTC: ${atmStore.fiatSymbol}${Math.round(atmStore.btcPrice).toLocaleString()}`
@@ -160,9 +169,12 @@ function toggleLiveServices() {
   <div
     class="flex min-h-dvh lg:h-dvh w-screen flex-col overflow-y-auto lg:overflow-hidden bg-background font-sans text-foreground"
   >
+    <!-- Unpaired: interactive QR-pairing wizard (aiolabs/bitspire#52) -->
+    <PairingWizard v-if="showPairingWizard" />
+
     <!-- Maintenance screen: shown when initialization fails in production -->
     <div
-      v-if="atmStore.initError"
+      v-else-if="atmStore.initError"
       class="flex flex-1 flex-col items-center justify-center gap-6 p-8"
     >
       <svg
diff --git a/apps/machine/src/components/PairingWizard.vue b/apps/machine/src/components/PairingWizard.vue
new file mode 100644
index 0000000..f34409e
--- /dev/null
+++ b/apps/machine/src/components/PairingWizard.vue
@@ -0,0 +1,160 @@
+<script setup lang="ts">
+/**
+ * QR-pairing wizard (aiolabs/bitspire#52).
+ *
+ * Shown in place of the "Pairing Required" maintenance screen when the machine
+ * is unpaired. The operator displays the spire-seed QR (minted by spirekeeper)
+ * to the machine's camera; we decode it, persist it as VITE_SPIRE_SEED, and
+ * relaunch so the normal boot path performs the bunker pairing.
+ *
+ * Capture is abstracted behind PairingSource, so NFC (or a HAL scanner) can be
+ * offered later without changing this view.
+ */
+import { onMounted, onUnmounted, ref, shallowRef } from 'vue'
+import {
+  availablePairingSources,
+  ingestScannedSeed,
+  type PairingSource,
+  type StopCapture,
+} from '@/services/pairing'
+
+type Phase = 'probing' | 'scanning' | 'no-source' | 'pairing' | 'error'
+
+const phase = ref<Phase>('probing')
+const errorMessage = ref('')
+const videoEl = ref<HTMLVideoElement | null>(null)
+
+const sources = shallowRef<PairingSource[]>([])
+const activeSource = shallowRef<PairingSource | null>(null)
+let stopCapture: StopCapture | null = null
+
+async function startWith(source: PairingSource) {
+  await teardown()
+  activeSource.value = source
+  errorMessage.value = ''
+  phase.value = 'scanning'
+  try {
+    stopCapture = await source.start({
+      video: source.kind === 'qr' ? (videoEl.value ?? undefined) : undefined,
+      onScan: handleScan,
+      onError: (e) => console.warn('[Pairing] capture glitch:', e),
+    })
+  } catch (e) {
+    phase.value = 'error'
+    errorMessage.value =
+      e instanceof Error ? e.message : 'Could not start the camera. Check permissions.'
+  }
+}
+
+let handling = false
+async function handleScan(raw: string) {
+  if (handling) return
+  handling = true
+  const result = await ingestScannedSeed(raw)
+  if (result.ok) {
+    // saveSpireSeed succeeded; relaunch is in flight — hold a friendly screen.
+    phase.value = 'pairing'
+    return
+  }
+  // Reject non-seed scans (a stray QR) and resume scanning.
+  console.warn('[Pairing] rejected scan:', result.reason, result.message)
+  errorMessage.value =
+    result.reason === 'invalid-seed'
+      ? 'That code is not a pairing code. Show the operator pairing QR.'
+      : result.message
+  handling = false
+  if (activeSource.value) await startWith(activeSource.value)
+}
+
+async function teardown() {
+  if (stopCapture) {
+    try {
+      stopCapture()
+    } catch {
+      /* idempotent */
+    }
+    stopCapture = null
+  }
+}
+
+onMounted(async () => {
+  const available = await availablePairingSources()
+  sources.value = available
+  const first = available[0]
+  if (!first) {
+    phase.value = 'no-source'
+    return
+  }
+  await startWith(first)
+})
+
+onUnmounted(teardown)
+</script>
+
+<template>
+  <div class="flex flex-1 flex-col items-center justify-center gap-6 p-8">
+    <h1 class="text-2xl lg:text-[3.5rem] font-bold">Pair This Machine</h1>
+
+    <!-- Camera viewfinder -->
+    <div
+      v-show="phase === 'scanning' && activeSource?.kind === 'qr'"
+      class="relative overflow-hidden rounded-2xl border-4 border-primary/40 bg-black"
+      style="width: min(80vw, 28rem); aspect-ratio: 1 / 1"
+    >
+      <video ref="videoEl" class="h-full w-full object-cover" muted autoplay playsinline></video>
+      <!-- Reticle -->
+      <div class="pointer-events-none absolute inset-6 rounded-xl border-2 border-white/70"></div>
+    </div>
+
+    <p
+      v-if="phase === 'scanning'"
+      class="max-w-md text-center text-base lg:text-2xl text-muted-foreground"
+    >
+      Hold the operator's pairing QR up to the camera.
+    </p>
+
+    <p v-if="phase === 'probing'" class="text-base lg:text-2xl text-muted-foreground">
+      Starting camera…
+    </p>
+
+    <div v-if="phase === 'pairing'" class="flex flex-col items-center gap-4">
+      <p class="text-base lg:text-2xl text-muted-foreground">Pairing accepted — restarting…</p>
+    </div>
+
+    <p
+      v-if="phase === 'no-source'"
+      class="max-w-md text-center text-base lg:text-2xl text-muted-foreground"
+    >
+      No camera or NFC reader is available on this machine. Pair by provisioning
+      <span class="font-mono">VITE_SPIRE_SEED</span> instead.
+    </p>
+
+    <p
+      v-if="phase === 'error'"
+      class="max-w-md text-center text-base lg:text-xl text-destructive"
+    >
+      {{ errorMessage }}
+    </p>
+
+    <!-- Transient rejected-scan hint while still scanning -->
+    <p
+      v-if="phase === 'scanning' && errorMessage"
+      class="max-w-md text-center text-sm lg:text-base text-warning"
+    >
+      {{ errorMessage }}
+    </p>
+
+    <!-- Alternate sources (e.g. NFC) when more than one is available -->
+    <div v-if="sources.length > 1" class="flex gap-3">
+      <button
+        v-for="source in sources"
+        :key="source.kind"
+        class="rounded-lg border border-border px-4 py-2 text-sm"
+        :class="activeSource?.kind === source.kind ? 'bg-primary text-primary-foreground' : ''"
+        @click="startWith(source)"
+      >
+        {{ source.label }}
+      </button>
+    </div>
+  </div>
+</template>

From b9340f775466b2d81cdae371c260b3e043c61da6 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Tue, 23 Jun 2026 23:08:24 +0200
Subject: [PATCH 23/82] docs(machine): document the on-machine QR-pairing
 wizard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Note the wizard flow next to VITE_SPIRE_SEED + a dedicated Pairing section
(aiolabs/bitspire#52): unpaired → scan seed off camera → persist + relaunch →
normal boot pairs. Records the qr-over-jsqr choice rationale by reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CLAUDE.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 4f86331..a1a5691 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -84,12 +84,32 @@ Renderer reads (Electron IPC or Vite `import.meta.env`):
 |---|---|---|
 | `VITE_RELAY_URL` | yes | `ws://...` of the relay both ATM and LNbits subscribe to. Dev: `ws://localhost:5001/nostrrelay/test` (LNbits's bundled `nostrrelay` extension — no separate strfry container) |
 | `VITE_LNBITS_SERVER_PUBKEY` | yes | 64-char hex pubkey LNbits prints on startup (`docker logs lnbits \| grep 'Public key (share this)'`) |
-| `VITE_SPIRE_SEED` | yes (prod) | Spire pairing seed (`spire-seed:v1:<base64url>`) from spirekeeper. Carries a one-shot NIP-46 connect token + the spire signing pubkey + bunker URL. First boot redeems it and persists the binding to `state.db`; later boots resume by fingerprint. A changed seed re-pairs. See aiolabs/bitspire#52. |
+| `VITE_SPIRE_SEED` | yes (prod) | Spire pairing seed (`spire-seed:v1:<base64url>`) from spirekeeper. Carries a one-shot NIP-46 connect token + the spire signing pubkey + bunker URL. First boot redeems it and persists the binding to `state.db`; later boots resume by fingerprint. A changed seed re-pairs. Provisioning it up front is optional — an unpaired machine renders an on-screen QR-pairing wizard that scans the seed off the camera (see below). See aiolabs/bitspire#52. |
 | `VITE_ATM_PRIVATE_KEY` | dev only | 64-char hex raw nsec fallback for running without a bunker. Ignored when `VITE_SPIRE_SEED` or a stored binding exists. |
 | `VITE_OPERATOR_PUBKEYS` | optional | Comma-separated hex pubkeys allowed to send kind-21003 management commands |
 
 The LP-era vars (`VITE_LIGHTNING_PUB_PUBKEY`, `VITE_LIGHTNING_PUB_API_URL`, `VITE_EXTENSION_API_URL`, `VITE_ADMIN_TOKEN`) are gone from the dev branch's `.env.example` and `LightningConfig` interface.
 
+## Pairing (on-machine QR wizard)
+
+A machine with no seed **and** no stored binding boots `unpaired` and, under
+Electron, renders an interactive wizard (`src/components/PairingWizard.vue`)
+instead of a dead-end fault screen. The operator displays the `spire-seed`
+QR (minted by spirekeeper's `/pair`) to the machine's camera; the wizard:
+
+1. captures + decodes via a `PairingSource` (`src/services/pairing/`) — camera
+   today (decode through `qr`, paulmillr's zero-dep lib), NFC scaffolded;
+2. validates the scan parses as a spire-seed (`ingestScannedSeed`), rejecting
+   a stray QR;
+3. persists it as `VITE_SPIRE_SEED` via the `state:save-spire-seed` IPC and
+   relaunches (`app:relaunch`).
+
+Pairing itself is **not** done in the wizard — relaunch lets the normal boot
+path (`signer-resolver` → `connectNewSeed`) redeem the one-shot token, so
+there's one tested pairing path. A revoked/expired binding lands on the same
+wizard (re-pair = scan a fresh seed). Provisioning `VITE_SPIRE_SEED` up front
+still works and skips the wizard.
+
 ## Commands
 
 ```bash

From d32ddc806ac6a81657ab0242bbcf704b961dd508 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Tue, 23 Jun 2026 23:21:10 +0200
Subject: [PATCH 24/82] build(nix): bump pnpmDeps hash for the qr dependency

Adding `qr` (and dropping `jsqr`) changed pnpm-lock.yaml, invalidating the
fixed-output hash for the vendored pnpm store. Without this the NixOS build
of the ATM app fails at the FOD before activation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 nix/mkAtmApp.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nix/mkAtmApp.nix b/nix/mkAtmApp.nix
index 5568794..630faf3 100644
--- a/nix/mkAtmApp.nix
+++ b/nix/mkAtmApp.nix
@@ -38,7 +38,7 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     inherit (finalAttrs) pname version src pnpmWorkspaces;
     inherit pnpm;
     fetcherVersion = 3;
-    hash = "sha256-Jv5p62E40DtCSZvN/+LTzkhRYJBTyyUOVSBlQyxzcEw=";
+    hash = "sha256-03ANBQ7bHJwsqlX2ScA1+1LFuO8njiuU7O4VGOb6cMM=";
   };
 
   nativeBuildInputs = [

From fd4f69826d8bb087cdcbeeb09a3410ac9ee3d31d Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Wed, 24 Jun 2026 23:27:09 +0200
Subject: [PATCH 25/82] fix(machine): decode QR at intrinsic frame + tuned
 capture resolution

The camera pairing source decoded frames at the <video> element's CSS box
size (qr's readFrame default) rather than the intrinsic frame, and let the
stream stay at the panel-bound ~720p that frontalCamera negotiates from the
screen size. On the 1280x800 kiosk with a fixed-focus 5MP scan camera that
left far too few pixels-per-module for a dense spire-seed QR, so a centered,
in-square code never decoded.

Decode the intrinsic frame (readFrame fullSize=true) and pin a deliberate
1280x960 capture via applyConstraints. lamassu-machine caps QR scanning at
640x480 for decode speed (megapixels only slow the per-frame decode); our
seed QR is denser than a lightning invoice, so 1280x960 balances
pixels-per-module against latency and keeps auto-exposure from blowing out a
frame-filling phone screen.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../machine/src/services/pairing/qr-source.ts | 31 ++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/apps/machine/src/services/pairing/qr-source.ts b/apps/machine/src/services/pairing/qr-source.ts
index 9dbfe92..1628a4b 100644
--- a/apps/machine/src/services/pairing/qr-source.ts
+++ b/apps/machine/src/services/pairing/qr-source.ts
@@ -32,6 +32,31 @@ export class QrPairingSource implements PairingSource {
     if (!video) throw new Error('QrPairingSource requires a <video> element')
 
     const camera = await frontalCamera(video)
+
+    // `frontalCamera` requests `ideal: screen.{width,height}`, so on the kiosk's
+    // 1280x800 panel it otherwise streams at ~720p — and `decodeQR` then
+    // center-crops to a square, leaving too few pixels-per-module for a dense
+    // spire-seed QR on this fixed-focus lens. Pin a deliberate 1280x960 capture
+    // instead: lamassu-machine caps QR scanning at 640x480 for decode speed
+    // (megapixels just slow the per-frame decode), but our seed QR is denser
+    // than a lightning invoice, so 1280x960 is the balance — ~14-18px/module at
+    // frame-fill, still fast, and it meters exposure better than maxing the
+    // sensor (a frame-filling QR keeps auto-exposure from blowing out on a
+    // bright phone screen). The stream lives on the <video>'s srcObject
+    // (QRCamera.stream is private); soft `ideal` so a camera that can't honor
+    // it degrades to its closest mode instead of throwing.
+    try {
+      const stream = video.srcObject
+      if (stream instanceof MediaStream) {
+        await stream.getVideoTracks()[0]?.applyConstraints({
+          width: { ideal: 1280 },
+          height: { ideal: 960 },
+        })
+      }
+    } catch (e) {
+      onError?.(e)
+    }
+
     const canvas = new QRCanvas() // decode-only; no overlay canvases needed
 
     let stopped = false
@@ -46,7 +71,11 @@ export class QrPairingSource implements PairingSource {
     cancel = frameLoop(() => {
       if (stopped) return
       try {
-        const result = camera.readFrame(canvas)
+        // `fullSize: true` decodes the camera's intrinsic frame (videoWidth ×
+        // videoHeight) rather than the <video> element's CSS box — the default
+        // (`false`) was decoding the few-hundred-px on-screen preview, which
+        // (compounded by `object-cover` cropping) starved the decoder.
+        const result = camera.readFrame(canvas, true)
         if (result) {
           stop()
           onScan(result)

From 962214ec159dd2b4dbad58bb37e7d4a0131bb4e4 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Fri, 26 Jun 2026 11:40:46 +0200
Subject: [PATCH 26/82] fix(deploy): point Sintra autoUpgrade at
 aiolabs/bitspire, not lamassu-next
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dev autoUpgrade flake URL still referenced the pre-migration repo
(aiolabs/lamassu-next), so the Sintra test unit would auto-pull
lamassu-next/dev at 04:00 — which lacks all the bitspire work (the
QR-pairing wizard, etc.) and would revert the box to the old no-seed
build. Repoint it at aiolabs/bitspire?ref=dev, the post-migration home
of this code. lamassu-next still feeds the not-yet-converted production
ATMs (batm3, douro) until they migrate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 flake.nix | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/flake.nix b/flake.nix
index 9ceb5dd..6b02763 100644
--- a/flake.nix
+++ b/flake.nix
@@ -169,17 +169,18 @@
               };
 
               # Auto-upgrade: pulls latest flake and runs nixos-rebuild switch.
-              # NOTE: this branch (dev) pins the upgrade source to ?ref=dev so
-              # any ATM flashed from `dev` stays on `dev`. Without the explicit
-              # ref, nix would resolve to the repo's default branch (main),
-              # which would silently regress a dev-deployed Sintra back to the
-              # lamassu-next production code at 04:00. The `main` branch's
-              # flake.nix continues to omit ?ref= so production ATMs (batm3,
-              # douro) keep pulling main HEAD as before.
-              # To update manually: sudo nixos-rebuild switch --flake git+ssh://forgejo@git.atitlan.io/aiolabs/lamassu-next.git?ref=dev#<model>-installed
+              # NOTE: bitSpire machines pull from the `aiolabs/bitspire` repo —
+              # the post-migration home of this code. This branch (dev) pins the
+              # upgrade source to ?ref=dev so any ATM flashed from `dev` stays on
+              # `dev`. Without the explicit ?ref=dev, nix would resolve the repo's
+              # default branch and could silently change a dev-deployed Sintra at
+              # 04:00. The legacy `aiolabs/lamassu-next` repo still feeds the
+              # not-yet-converted production ATMs (batm3, douro) from its own
+              # branches; it is retired once those machines migrate to bitspire.
+              # To update manually: sudo nixos-rebuild switch --flake git+ssh://forgejo@git.atitlan.io/aiolabs/bitspire.git?ref=dev#<model>-installed
               system.autoUpgrade = {
                 enable = true;
-                flake = "git+ssh://forgejo@git.atitlan.io/aiolabs/lamassu-next.git?ref=dev#${machineModel}-installed";
+                flake = "git+ssh://forgejo@git.atitlan.io/aiolabs/bitspire.git?ref=dev#${machineModel}-installed";
                 flags = [ "--refresh" ];
                 dates = "04:00"; # daily at 4am
                 allowReboot = false;

From 482e0549b97aeb0c7ecb8f87e8162ea1152b4707 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 29 Jun 2026 22:12:28 +0200
Subject: [PATCH 27/82] fix(deploy): make live ISOs USB-bootable
 (isoImage.makeUsbBootable)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The live ISO config set makeEfiBootable + makeBiosBootable but omitted
makeUsbBootable, so the image got BIOS+UEFI El Torito boot catalogs but
no isohybrid MBR/GPT — i.e. no partition table. dd'd to a USB stick it
shows iso9660 on the whole device with no ESP, and picky firmware (the
Sintra's Aaeon UP Board) won't recognise it as bootable, falling back to
its android-ia entry. Enabling makeUsbBootable applies the isohybrid MBR
(isohdpfx.bin) + GPT/ESP. Fixes USB boot for every model's live ISO.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/live.nix | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/deploy/nixos/live.nix b/deploy/nixos/live.nix
index 07fe161..00baabc 100644
--- a/deploy/nixos/live.nix
+++ b/deploy/nixos/live.nix
@@ -55,6 +55,12 @@ in
   isoImage = {
     makeEfiBootable = true;
     makeBiosBootable = true;
+    # Apply the isohybrid MBR + GPT/ESP so the image boots when dd'd to a USB
+    # stick — not just from optical media via El Torito. Without this the ISO
+    # has BIOS+UEFI El Torito boot catalogs but no partition table, and picky
+    # firmware (e.g. the Sintra's Aaeon UP Board) won't recognise the USB as
+    # bootable. Requires makeBiosBootable (isohdpfx.bin), set above.
+    makeUsbBootable = true;
     squashfsCompression = "zstd -Xcompression-level 6";
   };
 

From ce649947f6a86c69a54d825dc0a66a75ba9438a7 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 29 Jun 2026 23:47:18 +0200
Subject: [PATCH 28/82] feat(deploy): add disk-image-sintra-usb with distinct
 partition labels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A USB-bootable Sintra image variant for booting on a machine whose eMMC
already holds a nixos/ESP-labelled install. make-disk-image hardcodes the
root/ESP labels (nixos/ESP); booting the standard image from USB next to
the eMMC races stage-1's by-label/nixos between the two roots and likely
mounts the eMMC. This variant labels root nixos-usb (via make-disk-image
-L) and relabels the ESP to ESP-USB in a post-step (mtools), with
fileSystems pointed at the new labels. Auto-upgrade is disabled — it's a
portable test / hand-off image, and that also removes scheduled bootloader
writes that could land on the eMMC's ESP.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 flake.nix | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/flake.nix b/flake.nix
index 6b02763..a09ffdd 100644
--- a/flake.nix
+++ b/flake.nix
@@ -326,6 +326,51 @@
           diskSize = "auto";
         };
 
+        # USB-bootable Sintra image with DISTINCT partition labels
+        # (nixos-usb / ESP-USB) so the stick can be booted on a Sintra whose
+        # eMMC already holds a nixos/ESP-labelled install without a by-label
+        # collision — stage-1 would otherwise race between the two roots and
+        # likely mount the eMMC. Auto-upgrade is disabled: this is a portable
+        # test / hand-off image, not a managed fleet member, and disabling it
+        # also removes the scheduled bootloader writes that could otherwise
+        # land on the eMMC's ESP.
+        disk-image-sintra-usb =
+          let
+            cfg = self.nixosConfigurations.sintra-installed.extendModules {
+              modules = [
+                ({ lib, ... }: {
+                  fileSystems."/".device = lib.mkForce "/dev/disk/by-label/nixos-usb";
+                  fileSystems."/boot".device = lib.mkForce "/dev/disk/by-label/ESP-USB";
+                  system.autoUpgrade.enable = lib.mkForce false;
+                })
+              ];
+            };
+            baseImage = import (nixpkgs + "/nixos/lib/make-disk-image.nix") {
+              inherit pkgs lib;
+              config = cfg.config;
+              format = "raw";
+              partitionTableType = "efi";
+              diskSize = "auto";
+              label = "nixos-usb"; # ext4 root label (make-disk-image -L)
+            };
+          in
+          pkgs.runCommand "nixos-disk-image-sintra-usb"
+            { nativeBuildInputs = [ pkgs.parted pkgs.mtools ]; }
+            ''
+              mkdir -p $out
+              cp --sparse=always ${baseImage}/nixos.img $out/nixos.img
+              chmod +w $out/nixos.img
+              # make-disk-image hardcodes the ESP FAT label to "ESP"; relabel the
+              # volume to ESP-USB so /boot (by-label/ESP-USB) doesn't collide with
+              # the eMMC's ESP. Volume label only — bootloader files are untouched,
+              # and UEFI loads /EFI/BOOT/BOOTX64.EFI regardless of the label.
+              espStart=$(parted -sm "$out/nixos.img" unit B print | awk -F: '$1==1 {gsub("B","",$2); print $2}')
+              echo "ESP partition starts at byte $espStart — relabelling to ESP-USB"
+              export MTOOLS_SKIP_CHECK=1
+              mlabel -i "$out/nixos.img@@$espStart" ::ESP-USB
+              printf 'verify ESP label: '; mlabel -i "$out/nixos.img@@$espStart" -s :: || true
+            '';
+
         # Backwards compat
         iso = self.nixosConfigurations.douro.config.system.build.isoImage;
       };

From b2099c7d489ff19d031c6dbb504771f36dd72e0b Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 29 Jun 2026 23:47:31 +0200
Subject: [PATCH 29/82] fix(deploy): make the live ISO boot cleanly
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fresh live boots hit a cascade of activation/unit failures because live.nix
shared installed-system config that assumes persistent state:

- bitspire-env chowned /var/lib/bitspire/.env to bitspire:bitspire in the
  default activation order, before `users` runs, so on a fresh boot (no .env
  yet) it failed with 'invalid user'. Move to the attrset form with
  deps=["users"]. (Installed systems skip the block since .env exists.)
- swapDevices=/var/swapfile lives in the live tmpfs and fails to init —
  replace with zramSwap for the low-RAM models' OOM cushion.
- wg0 needs a provisioned key the live boot lacks; it failed and dragged
  network-setup down. Drop the interface on live.
- display-reset runs `xrandr --output eDP-1`, but the Sintra drives HDMI-1
  (no eDP-1) — gate the service off for sintra.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/live.nix | 49 ++++++++++++++++++++++++++++---------------
 1 file changed, 32 insertions(+), 17 deletions(-)

diff --git a/deploy/nixos/live.nix b/deploy/nixos/live.nix
index 00baabc..7f0a190 100644
--- a/deploy/nixos/live.nix
+++ b/deploy/nixos/live.nix
@@ -172,19 +172,29 @@ in
     };
   };
 
-  # Install the .env on first boot
-  system.activationScripts.bitspire-env = ''
-    mkdir -p /var/lib/bitspire
-    if [ ! -f /var/lib/bitspire/.env ]; then
-      cp ${envTemplate} /var/lib/bitspire/.env
-      chmod 600 /var/lib/bitspire/.env
-      chown bitspire:bitspire /var/lib/bitspire/.env
-    fi
-  '';
+  # Install the .env on first boot. Attrset form with deps=["users"] so the
+  # chown runs AFTER the bitspire user is created. Otherwise on a fresh live
+  # boot (where /var/lib/bitspire/.env doesn't exist yet) the chown runs in the
+  # default activation order — before `users` — and fails with
+  # "chown: invalid user: 'bitspire:bitspire'". The installed system skips this
+  # block because its .env already exists, which is why only live boots tripped.
+  system.activationScripts.bitspire-env = {
+    deps = [ "users" ];
+    text = ''
+      mkdir -p /var/lib/bitspire
+      if [ ! -f /var/lib/bitspire/.env ]; then
+        cp ${envTemplate} /var/lib/bitspire/.env
+        chmod 600 /var/lib/bitspire/.env
+        chown bitspire:bitspire /var/lib/bitspire/.env
+      fi
+    '';
+  };
 
   # Reset display output after X starts (required for kexec boots where
-  # the GPU wasn't reinitialized by BIOS firmware)
-  systemd.services.display-reset = {
+  # the GPU wasn't reinitialized by BIOS firmware). Only the eDP-panel models
+  # (Douro/Tejo) have an eDP-1 output; the Sintra drives HDMI-1, so the
+  # `xrandr --output eDP-1` here just errors out — skip it there.
+  systemd.services.display-reset = lib.mkIf (machineModel != "sintra") {
     description = "Reset eDP display output";
     after = [ "display-manager.service" ];
     requires = [ "display-manager.service" ];
@@ -198,12 +208,17 @@ in
     };
   };
 
-  # Swap file — Douro/Tejo have only 2GB RAM; without swap the system
-  # hard-freezes under memory pressure instead of gracefully OOM-killing.
-  swapDevices = [{
-    device = "/var/swapfile";
-    size = 1024; # MB
-  }];
+  # Low-RAM models (Douro/Tejo, 2GB) need a swap cushion or they hard-freeze
+  # under memory pressure. The live system is RAM-rooted, so a /var/swapfile
+  # lives in tmpfs — pointless, and its init fails on a fresh boot. Use
+  # compressed RAM swap (zram) instead; no on-disk file required.
+  zramSwap.enable = true;
+
+  # The wg0 VPN tunnel (declared in configuration.nix) needs a provisioned key
+  # at /var/lib/wireguard/wg0.key, which a fresh live boot doesn't have — it
+  # fails and drags network-setup down with it. A live test image doesn't need
+  # the VPN, so drop the interface entirely.
+  networking.wireguard.interfaces = lib.mkForce { };
 
   # Clean /tmp on boot to prevent stale Nix build artifacts from filling disk
   boot.tmp.cleanOnBoot = true;

From 334cb867712ed1edaf0898e21d80287c70a1394f Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Tue, 30 Jun 2026 12:06:34 +0200
Subject: [PATCH 30/82] fix(machine): resolve signer before LNbits config so an
 unpaired machine reaches the pairing wizard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

initializeLightningServices() validated VITE_LNBITS_SERVER_PUBKEY (and, in
strict mode, rejected a localhost relay) *before* calling resolveSigner. An
unpaired machine — no seed, no binding, blank .env — therefore threw a generic
config Error that classifyInitError surfaces as the static "ATM Unavailable"
screen, never the NoPairingError that routes to the QR-pairing wizard.

Pairing is what's meant to provide the transport config, so the pairing check
must come first. Move resolveSigner ahead of the strict + server-pubkey
validation: an unpaired machine now throws NoPairingError → 'unpaired' →
wizard regardless of relay/pubkey provisioning, while a paired machine still
hits the config validation it legitimately needs.

Surfaced testing the freshly-built Sintra images (live ISO + USB disk image),
both of which ship a blank .env by design and booted straight to "ATM
Unavailable". bitspire-#70 (part 1 of 2; part 2 = seed carries the LNbits
server pubkey).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/services/lightning.ts | 31 ++++++++++++++++----------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index 5b60b2f..f673b24 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -398,9 +398,22 @@ export async function initializeLightningServices(options?: {
   console.log('[Lightning] Relay URL:', CONFIG.relayUrl)
   console.log('[Lightning] LNbits server pubkey:', CONFIG.lnbitsServerPubkey || '(not configured)')
 
-  // Strict mode: validate config is production-ready (no localhost). The
-  // signing-identity check (a bunker pairing must exist) is enforced by
-  // resolveSigner below via allowEphemeral=false.
+  // Resolve the signing identity BEFORE validating the LNbits transport
+  // config. An unpaired machine must reach the QR-pairing wizard regardless
+  // of relay/server-pubkey provisioning — pairing is what provides those — so
+  // resolveSigner (which throws NoPairingError → 'unpaired' → wizard for a
+  // machine with no seed and no binding) has to run ahead of the config
+  // checks below. The relay/pubkey validation then only gates a *paired*
+  // machine that's actually trying to talk to LNbits. See aiolabs/bitspire#70.
+  //
+  // In production this is a BunkerSigner over NIP-46 (the ATM holds only a
+  // transport key; the operator's nsecbunkerd holds the signing key); in dev
+  // it falls back to an in-process LocalSigner. The Phase-A Signer seam means
+  // nothing downstream changes. See aiolabs/bitspire#52.
+  const signer: Signer = await resolveSigner({ allowEphemeral: !options?.strict })
+  console.log('[Lightning] ATM pubkey:', signer.pubkey)
+
+  // Strict mode: validate config is production-ready (no localhost).
   if (options?.strict) {
     const errors: string[] = []
     if (/localhost|127\.0\.0\.1/.test(CONFIG.relayUrl)) {
@@ -414,7 +427,9 @@ export async function initializeLightningServices(options?: {
     }
   }
 
-  // Validate required configuration
+  // Validate required configuration. Reached only for a paired machine (an
+  // unpaired one threw NoPairingError above) — it needs the LNbits server
+  // pubkey to talk to the transport.
   if (!CONFIG.lnbitsServerPubkey) {
     throw new Error(
       '[Lightning] VITE_LNBITS_SERVER_PUBKEY is required. ' +
@@ -422,14 +437,6 @@ export async function initializeLightningServices(options?: {
     )
   }
 
-  // Resolve the signing identity. In production this is a BunkerSigner over
-  // NIP-46 (the ATM holds only a transport key; the operator's nsecbunkerd
-  // holds the signing key); in dev it falls back to an in-process LocalSigner.
-  // The Phase-A Signer seam means nothing downstream changes. See
-  // aiolabs/bitspire#52.
-  const signer: Signer = await resolveSigner({ allowEphemeral: !options?.strict })
-  console.log('[Lightning] ATM pubkey:', signer.pubkey)
-
   // Create Nostr client
   const nostrClient = new NostrClient({
     relays: [{ url: CONFIG.relayUrl }],

From 5a420119df486e9db110a9f29faccbff4cd98708 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Wed, 1 Jul 2026 22:42:49 +0200
Subject: [PATCH 31/82] perf(deploy): slim the kiosk closure (disable TTS, Qt,
 docs)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The disk image was ~6.2 GiB of closure, largely desktop/multimedia baggage a
single-purpose Electron kiosk never uses. Cut the clearly-unused stacks:

- services.speechd off → drops speech-dispatcher's espeak-ng + mbrola voices
  (~1 GB text-to-speech). An ATM does not talk.
- v4l-utils built withGUI=false → drops the entire Qt6 stack (~0.5 GB) that only
  backed the qv4l2 GUI; the v4l2-ctl CLI we actually use for the camera stays.
- documentation off (man/info/NixOS manual) — nobody reads them on a kiosk.

Closure 6.2 → 5.0 GiB. The remaining bulk is electron's own runtime (gtk4/
gstreamer/pipewire, unavoidable), mesa+llvm (GPU), and linux-firmware — those
need heavier / riskier work to touch. Distribute the image as .img.zst.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/configuration.nix | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/deploy/nixos/configuration.nix b/deploy/nixos/configuration.nix
index d473a42..2306f5a 100644
--- a/deploy/nixos/configuration.nix
+++ b/deploy/nixos/configuration.nix
@@ -7,6 +7,16 @@
   # System basics
   system.stateVersion = "24.05";
 
+  # ── Image slimming (bitspire#70 sizing) ──────────────────────────────
+  # This is a single-purpose Electron kiosk; strip the desktop/multimedia
+  # baggage NixOS pulls in by default so the disk image stays lean.
+  # - speechd: text-to-speech (speech-dispatcher → espeak-ng → mbrola, ~1GB).
+  #   An ATM does not talk.
+  # - documentation: man/info/NixOS manual — no one reads them on a kiosk.
+  services.speechd.enable = lib.mkForce false;
+  documentation.enable = false;
+  documentation.nixos.enable = false;
+
   # Networking
   networking = {
     hostName = "bitspire";
@@ -121,8 +131,10 @@
     # Node.js for the application
     pkgs-unstable.nodejs_22
 
-    # Camera support
-    v4l-utils
+    # Camera support. v4l-utils' default build drags in the whole Qt6 stack
+    # for its qv4l2 GUI (~0.5GB) — we only ever use the v4l2-ctl CLI, so drop
+    # the GUI.
+    (v4l-utils.override { withGUI = false; })
     fswebcam
 
     # ATM operations

From c8745addbcba816e8327d17dac610f249c15c372 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 14:49:27 +0200
Subject: [PATCH 32/82] fix(deploy): make disk-image-sintra-usb BIOS+UEFI
 bootable (GRUB)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The USB disk image was systemd-boot (UEFI-only) with make-disk-image's "efi"
table (pure GPT + ESP, protective MBR). The Sintra's Aaeon UP Board firmware
USB-boots in Legacy/BIOS mode — it boots the live ISO via that ISO's isolinux
(BIOS) El Torito image, not the UEFI ESP — so a dd'd systemd-boot image has no
BIOS boot code to execute and the firmware won't list it (a hand-added hybrid
MBR didn't help: nothing to run).

Switch the USB target to GRUB with BIOS + UEFI on make-disk-image's "hybrid"
table: it adds a bios_grub partition, GRUB writes its BIOS stage to the MBR AND
a removable /EFI/BOOT/BOOTX64.EFI — mirroring the live ISO's dual boot. The
Aaeon now lists it (as two "ia android" entries, BIOS + UEFI) and boots it.
Scoped to disk-image-sintra-usb only; the eMMC install keeps systemd-boot.
ESP stays partition 1 so the ESP-USB relabel step is unchanged.

Verified on hardware: booted from USB into the wizard with the full upboard.nix
hardware config.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 flake.nix | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/flake.nix b/flake.nix
index a09ffdd..3a678da 100644
--- a/flake.nix
+++ b/flake.nix
@@ -342,6 +342,25 @@
                   fileSystems."/".device = lib.mkForce "/dev/disk/by-label/nixos-usb";
                   fileSystems."/boot".device = lib.mkForce "/dev/disk/by-label/ESP-USB";
                   system.autoUpgrade.enable = lib.mkForce false;
+
+                  # The Sintra's Aaeon firmware USB-boots in Legacy/BIOS mode — it
+                  # boots the live ISO via its isolinux (BIOS) El Torito image, not
+                  # the UEFI ESP. systemd-boot is UEFI-only, so a dd'd systemd-boot
+                  # image isn't recognised as bootable. Switch THIS USB image to
+                  # GRUB with BOTH BIOS (MBR + bios_grub partition, via the "hybrid"
+                  # table below) and UEFI (removable /EFI/BOOT/BOOTX64.EFI) — mirroring
+                  # the live ISO's dual boot — so it boots on Legacy and UEFI alike.
+                  # Scoped to the USB image; the eMMC install keeps systemd-boot.
+                  boot.loader.systemd-boot.enable = lib.mkForce false;
+                  boot.loader.efi.canTouchEfiVariables = lib.mkForce false;
+                  boot.loader.grub = {
+                    enable = lib.mkForce true;
+                    efiSupport = true;
+                    efiInstallAsRemovable = true;
+                    # make-disk-image's build VM exposes the image as /dev/vda;
+                    # GRUB installs its BIOS stage to that disk's MBR.
+                    devices = lib.mkForce [ "/dev/vda" ];
+                  };
                 })
               ];
             };
@@ -349,7 +368,8 @@
               inherit pkgs lib;
               config = cfg.config;
               format = "raw";
-              partitionTableType = "efi";
+              # hybrid = GPT + bios_grub partition + ESP → BIOS + UEFI bootable.
+              partitionTableType = "hybrid";
               diskSize = "auto";
               label = "nixos-usb"; # ext4 root label (make-disk-image -L)
             };

From 7e90719508e17bf0c7385e9d4a8edd797ac0ef47 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 18:40:12 +0200
Subject: [PATCH 33/82] refactor(deploy): share UP Board serial hardware
 between installed + live ISO
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sintra live ISO (live.nix) had no serial support — ftdi_sio and the
ttyJ5/ttyJ7 udev symlinks were only in hardware/upboard.nix (installed), so
booting iso-sintra on real hardware failed on the validator + F56 dispenser
while the disk image worked. The two definitions had already drifted (live's
tejo block lacked ttyS4).

Extract the UP Board serial peripherals (usbserial/ftdi_sio/cp210x, the
ttyJ4/ttyJ5/ttyJ7 udev symlinks + permissions, console=tty0) into
hardware/upboard-serial.nix and import it from both upboard.nix (installed
tejo + sintra) and live.nix (sintra only). Single source of truth — the two
artifacts can't drift again. Named upboard-serial (not sintra-serial) since
upboard.nix serves both tejo-installed and sintra-installed.

Camera + LED/SPI rules stay inline in upboard.nix (installed-specific; the
pairing camera works via getUserMedia without the scanner symlink). Verified
by eval: live sintra now carries ftdi_sio + console=tty0 + ttyJ7; installed
sintra/tejo unchanged (serial present, camera present, no console dupe).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/hardware/upboard-serial.nix | 61 ++++++++++++++++++++++++
 deploy/nixos/hardware/upboard.nix        | 52 ++++----------------
 deploy/nixos/live.nix                    |  7 ++-
 3 files changed, 75 insertions(+), 45 deletions(-)
 create mode 100644 deploy/nixos/hardware/upboard-serial.nix

diff --git a/deploy/nixos/hardware/upboard-serial.nix b/deploy/nixos/hardware/upboard-serial.nix
new file mode 100644
index 0000000..dfbf947
--- /dev/null
+++ b/deploy/nixos/hardware/upboard-serial.nix
@@ -0,0 +1,61 @@
+# UP Board serial peripherals — the validator / dispenser / printer wiring
+# shared by the INSTALLED configs (hardware/upboard.nix, used by both
+# tejo-installed and sintra-installed) AND the sintra live ISO (live.nix).
+# Single source of truth so the two artifacts can't drift — the earlier bug
+# was exactly this drift (the sintra live ISO lacked ftdi_sio + the ttyJ7
+# symlink, so the F56 dispenser failed while the installed image worked).
+#
+# Sintra IS a UP Board, so these are the UP Board rules; ttyS1/ttyS5 cover the
+# older UP Board / UP4000 (Tejo) dispenser nodes and ttyS4 covers the Sintra
+# (Apollo Lake) where the F56 is on the SoC MMIO UART. Only the device that
+# actually exists at runtime gets the symlink, so all three coexist safely.
+#
+# Serial port mapping:
+#   ttyJ4 = Printer (Nippon NP-2511D-2)
+#   ttyJ5 = Validator (iVIZION, ID003)
+#   ttyJ7 = Dispenser (Fujitsu F53/F56)
+{ lib, ... }:
+
+{
+  boot.kernelModules = [
+    "usbserial" # USB-to-serial adapters
+    "ftdi_sio" # FTDI USB serial (the iVIZION validator bridge)
+    "cp210x" # CP210x USB serial (alternative adapter)
+  ];
+
+  boot.kernelParams = [
+    # Do NOT route the kernel console through ttyS4 on Sintra. ttyS4 is the
+    # SoC's MMIO 16550A (the only real UART besides the legacy ttyS0 at I/O
+    # 0x3f8) and is wired to the Fujitsu F56 dispenser's RS-232 header. Holding
+    # it as console prevents userspace opening it at 9600 baud and HAL fails
+    # with "Input/output error setting custom baud rate of 9600". For serial
+    # debug, point console at ttyS0 instead.
+    "console=tty0"
+  ];
+
+  services.udev.extraRules = lib.mkAfter ''
+    # Generic serial port permissions (so the non-root HAL user can open them)
+    KERNEL=="ttyS[0-9]*", MODE="0666"
+    KERNEL=="ttyUSB[0-9]*", MODE="0666"
+    KERNEL=="ttyACM[0-9]*", MODE="0666"
+
+    # Printer (ttyJ4)
+    KERNELS=="1-7.2:1.0", SYMLINK+="ttyJ4"
+    KERNEL=="ttyUSB0", SYMLINK+="ttyJ4"
+
+    # Validator (ttyJ5)
+    KERNELS=="1-7.3:1.0", SYMLINK+="ttyJ5"
+    KERNEL=="ttyUSB1", SYMLINK+="ttyJ5"
+
+    # Dispenser (ttyJ7). ttyS1/ttyS5 = older UP Board / UP4000; ttyS4 = Sintra.
+    KERNEL=="ttyS1", SYMLINK+="ttyJ7"
+    KERNEL=="ttyS4", SYMLINK+="ttyJ7"
+    KERNEL=="ttyS5", SYMLINK+="ttyJ7"
+
+    # Legacy ttyAMA0 alias
+    SUBSYSTEM=="tty", KERNEL=="ttyS1", SYMLINK+="ttyAMA0", GROUP="dialout"
+
+    # Disable USB autosuspend (prevents serial adapters from sleeping)
+    ACTION=="add", SUBSYSTEM=="usb", TEST=="power/control", ATTR{power/control}="on"
+  '';
+}
diff --git a/deploy/nixos/hardware/upboard.nix b/deploy/nixos/hardware/upboard.nix
index b3fe1f3..d213ff7 100644
--- a/deploy/nixos/hardware/upboard.nix
+++ b/deploy/nixos/hardware/upboard.nix
@@ -11,6 +11,10 @@
 { config, lib, pkgs, ... }:
 
 {
+  # Serial peripherals (validator/dispenser/printer modules + udev symlinks +
+  # console=tty0) are shared with the live ISO via ./upboard-serial.nix.
+  imports = [ ./upboard-serial.nix ];
+
   boot = {
     loader = {
       systemd-boot.enable = true;
@@ -42,21 +46,12 @@
       "kvm-intel"
       "i2c-dev"
       "spi-dev"
-      "usbserial" # USB-to-serial adapters
-      "ftdi_sio" # FTDI USB serial
-      "cp210x" # CP210x USB serial
+      # Serial modules (usbserial/ftdi_sio/cp210x) → ./upboard-serial.nix.
     ];
 
     kernelParams = [
       "i915.enable_psr=0"
-      # NOTE: do NOT route the kernel console through ttyS4 on Sintra.
-      # ttyS4 is the SoC's MMIO 16550A (the only real UART besides the
-      # legacy ttyS0 at I/O 0x3f8) and is wired to the Fujitsu F56
-      # dispenser's RS-232 header on Sintra. Holding it as console
-      # prevents userspace from opening it at 9600 baud and HAL fails
-      # with "Input/output error setting custom baud rate of 9600".
-      # If you want serial debug, point console at ttyS0 instead.
-      "console=tty0"
+      # console=tty0 (keeps ttyS4 free for the F56) → ./upboard-serial.nix.
       "quiet"
       "splash"
     ];
@@ -104,37 +99,9 @@
     hybrid-sleep.enable = false;
   };
 
-  # Serial port permissions + tejo-specific symlinks
+  # Camera + LED/SPI peripherals. The serial rules (validator/dispenser/printer
+  # symlinks + permissions) are shared with the live ISO in ./upboard-serial.nix.
   services.udev.extraRules = lib.mkAfter ''
-    # Generic serial port permissions
-    KERNEL=="ttyS[0-9]*", MODE="0666"
-    KERNEL=="ttyUSB[0-9]*", MODE="0666"
-    KERNEL=="ttyACM[0-9]*", MODE="0666"
-
-    # ── Tejo serial port symlinks ──────────────────────────────────────
-    # Both UP Board and UP4000 rules included (match different kernel paths)
-
-    # Printer (ttyJ4)
-    KERNELS=="1-7.2:1.0", SYMLINK+="ttyJ4"
-    KERNEL=="ttyUSB0", SYMLINK+="ttyJ4"
-
-    # Validator (ttyJ5)
-    KERNELS=="1-7.3:1.0", SYMLINK+="ttyJ5"
-    KERNEL=="ttyUSB1", SYMLINK+="ttyJ5"
-
-    # Dispenser (ttyJ7).
-    # ttyS1 / ttyS5 cover earlier UP Board variants where the dispenser
-    # lands on those kernel-enumerated serial nodes; ttyS4 covers the
-    # Sintra (UP Board Atom/Apollo Lake) where the dispenser is wired
-    # to the SoC's MMIO UART. Whichever device actually exists at
-    # runtime gets the ttyJ7 symlink.
-    KERNEL=="ttyS1", SYMLINK+="ttyJ7"
-    KERNEL=="ttyS4", SYMLINK+="ttyJ7"
-    KERNEL=="ttyS5", SYMLINK+="ttyJ7"
-
-    # Legacy ttyAMA0 alias
-    SUBSYSTEM=="tty", KERNEL=="ttyS1", SYMLINK+="ttyAMA0", GROUP="dialout"
-
     # ── Camera devices ─────────────────────────────────────────────────
     SUBSYSTEM=="video4linux", ATTR{index}=="0", KERNELS=="1-5", ATTRS{idVendor}=="0ac8", ATTRS{idProduct}=="0345", SYMLINK+="video-scan"
     SUBSYSTEM=="video4linux", ATTR{index}=="0", KERNELS=="1-2", ATTRS{idVendor}=="0ac8", ATTRS{idProduct}=="0345", SYMLINK+="video-scan"
@@ -147,8 +114,5 @@
     SUBSYSTEM=="spidev", GROUP="spi", MODE="0660"
     SUBSYSTEM=="i2c-dev", GROUP="i2c", MODE="0660"
     SUBSYSTEM=="leds", KERNEL=="upboard:*", ACTION=="add|change", RUN+="${pkgs.findutils}/bin/find /sys$devpath -type f -exec ${pkgs.coreutils}/bin/chmod g+u {} + -exec ${pkgs.coreutils}/bin/chown :leds {} +"
-
-    # Disable USB autosuspend (prevents serial adapters from sleeping)
-    ACTION=="add", SUBSYSTEM=="usb", TEST=="power/control", ATTR{power/control}="on"
   '';
 }
diff --git a/deploy/nixos/live.nix b/deploy/nixos/live.nix
index 7f0a190..44255e9 100644
--- a/deploy/nixos/live.nix
+++ b/deploy/nixos/live.nix
@@ -48,7 +48,12 @@ in
 
     # Reuse ATM systemd service module
     ./bitspire-atm.nix
-  ];
+  ]
+  # Sintra: share the UP Board serial hardware (validator/dispenser/printer
+  # modules + udev symlinks + console=tty0) with the installed image so the
+  # live ISO drives the same hardware. Safe to import here — unlike upboard.nix
+  # it declares no fileSystems, so there's no live-boot mount conflict.
+  ++ lib.optionals (machineModel == "sintra") [ ./hardware/upboard-serial.nix ];
 
   # ISO image settings
   image.fileName = "bitspire-${machineModel}-live.iso";

From 98bdd92044aa3873d0c3d8d0a931f02df303a0f0 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Wed, 1 Jul 2026 13:14:59 +0200
Subject: [PATCH 34/82] refactor(nostr-client): slim the spire-seed to carry
 the pubkey once, add lnbits_npub
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The v1 seed spelled the spire pubkey three times — spire_npub, spire_pubkey
(hex), and again inside a full bunker_url — which bloats a QR that's already
hard to scan off the machine's camera. Carry it once, as an npub, and derive
the rest:

- spire_pubkey (hex) ← decode(spire_npub). npub is ~the same length as hex but
  carries a bech32 checksum, so a mis-scanned character is caught instead of
  yielding a wrong-but-valid-looking key.
- bunker_url ← reconstructed from spire_pubkey + bunker_secret + bunker_relay.
- bunker_relay is OPTIONAL, defaulting to relays[0] (option 3): minimal in the
  common case where the bunker shares the event relay, explicit when it differs.
- lnbits_npub is NEW — gives a paired machine its LNbits transport server pubkey
  from the seed itself, so nothing else needs provisioning (bitspire-#70 part 2).

Kept as v: 1 (redefined in place, no compat shim): the seed is a one-shot
pairing token, no bitspire machine has shipped, and a paired machine resumes
from its stored binding, not by re-parsing the seed. Roughly a third smaller
encoded — ~180-200 fewer chars in the QR.

Lockstep: aiolabs/spirekeeper pairing.py must emit the new shape (spire_npub +
lnbits_npub + bunker_secret, drop spire_pubkey/bunker_url) before a new seed can
be minted. Consumer wiring (relays + lnbitsServerPubkey into LightningConfig)
and a resolver-resilience guard for machines holding an old-shape seed land
separately.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../services/pairing/__tests__/ingest.test.ts |  7 +-
 .../nostr-client/src/__tests__/seed.test.ts   | 51 +++++++----
 packages/nostr-client/src/seed.ts             | 89 ++++++++++++++-----
 3 files changed, 107 insertions(+), 40 deletions(-)

diff --git a/apps/machine/src/services/pairing/__tests__/ingest.test.ts b/apps/machine/src/services/pairing/__tests__/ingest.test.ts
index 7392de3..f6c069e 100644
--- a/apps/machine/src/services/pairing/__tests__/ingest.test.ts
+++ b/apps/machine/src/services/pairing/__tests__/ingest.test.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, afterEach } from 'vitest'
 import { ingestScannedSeed } from '../ingest'
 import { SPIRE_SEED_SCHEME } from '@bitSpire/nostr-client'
+import { npubEncode } from 'nostr-tools/nip19'
 
 /** Mirror of spirekeeper pairing.py: urlsafe base64, padding stripped. */
 function makeSeed(json: unknown): string {
@@ -15,9 +16,9 @@ function makeSeed(json: unknown): string {
 const SPIRE_PUBKEY = 'a'.repeat(64)
 const VALID_SEED = makeSeed({
   v: 1,
-  spire_npub: 'npub1example',
-  spire_pubkey: SPIRE_PUBKEY,
-  bunker_url: `bunker://${SPIRE_PUBKEY}?relay=wss%3A%2F%2Fbunker.relay%2F&secret=deadbeef`,
+  spire_npub: npubEncode(SPIRE_PUBKEY),
+  lnbits_npub: npubEncode('b'.repeat(64)),
+  bunker_secret: 'deadbeef',
   relays: ['wss://events.relay/'],
 })
 
diff --git a/packages/nostr-client/src/__tests__/seed.test.ts b/packages/nostr-client/src/__tests__/seed.test.ts
index 0deef80..3e3bba7 100644
--- a/packages/nostr-client/src/__tests__/seed.test.ts
+++ b/packages/nostr-client/src/__tests__/seed.test.ts
@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest'
+import { npubEncode } from 'nostr-tools/nip19'
 import { parseSpireSeed, seedFingerprint, SPIRE_SEED_SCHEME } from '../seed.js'
 
 /** Mirror of spirekeeper pairing.py: urlsafe base64, padding stripped. */
@@ -12,41 +13,56 @@ function makeSeed(json: unknown): string {
 }
 
 const SPIRE_PUBKEY = 'a'.repeat(64)
-const BUNKER_URL = `bunker://${SPIRE_PUBKEY}?relay=wss%3A%2F%2Fbunker.relay%2F&secret=deadbeef`
+const LNBITS_PUBKEY = 'b'.repeat(64)
+const SPIRE_NPUB = npubEncode(SPIRE_PUBKEY)
+const LNBITS_NPUB = npubEncode(LNBITS_PUBKEY)
 
 const VALID = {
   v: 1,
-  spire_npub: 'npub1example',
-  spire_pubkey: SPIRE_PUBKEY,
-  bunker_url: BUNKER_URL,
+  spire_npub: SPIRE_NPUB,
+  lnbits_npub: LNBITS_NPUB,
+  bunker_secret: 'deadbeef',
   relays: ['wss://events.relay/'],
 }
 
 describe('parseSpireSeed', () => {
-  it('parses a well-formed seed (snake_case → camelCase)', () => {
+  it('derives hex pubkeys from npubs and reconstructs the bunker URL', () => {
     const seed = parseSpireSeed(makeSeed(VALID))
     expect(seed).toEqual({
       v: 1,
       spirePubkey: SPIRE_PUBKEY,
-      bunkerUrl: BUNKER_URL,
+      lnbitsServerPubkey: LNBITS_PUBKEY,
+      bunkerUrl: `bunker://${SPIRE_PUBKEY}?relay=${encodeURIComponent('wss://events.relay/')}&secret=deadbeef`,
       relays: ['wss://events.relay/'],
     })
   })
 
-  it('re-pads stripped base64url of any residue length', () => {
-    // Vary a field so the encoded payload lands on each mod-4 residue.
-    for (const suffix of ['', 'a', 'ab', 'abc']) {
-      const seed = makeSeed({ ...VALID, spire_npub: `npub1${suffix}` })
-      expect(() => parseSpireSeed(seed)).not.toThrow()
-    }
+  it('defaults the bunker relay to relays[0] when bunker_relay is absent', () => {
+    const seed = parseSpireSeed(makeSeed(VALID))
+    expect(seed.bunkerUrl).toContain(`relay=${encodeURIComponent('wss://events.relay/')}`)
   })
 
-  it('keeps bunker_url verbatim (percent-decoding is parseBunkerInput’s job)', () => {
+  it('uses an explicit bunker_relay when present (distinct from event relays)', () => {
+    const seed = parseSpireSeed(makeSeed({ ...VALID, bunker_relay: 'wss://bunker.relay/' }))
+    expect(seed.bunkerUrl).toContain(`relay=${encodeURIComponent('wss://bunker.relay/')}`)
+    // event relays are unchanged
+    expect(seed.relays).toEqual(['wss://events.relay/'])
+  })
+
+  it('percent-encodes relay + secret for parseBunkerInput to decode', () => {
     const seed = parseSpireSeed(makeSeed(VALID))
     expect(seed.bunkerUrl).toContain('relay=wss%3A%2F%2F')
     expect(seed.bunkerUrl).toContain('secret=deadbeef')
   })
 
+  it('re-pads stripped base64url of any residue length', () => {
+    // Vary the secret so the encoded payload lands on each mod-4 residue.
+    for (const suffix of ['', 'a', 'ab', 'abc']) {
+      const seed = makeSeed({ ...VALID, bunker_secret: `deadbeef${suffix}` })
+      expect(() => parseSpireSeed(seed)).not.toThrow()
+    }
+  })
+
   it.each([
     ['wrong scheme', 'spire-seed:v2:abc'],
     ['not a seed', 'bunker://whatever'],
@@ -56,10 +72,15 @@ describe('parseSpireSeed', () => {
 
   it.each([
     ['bad version', { ...VALID, v: 2 }],
-    ['short pubkey', { ...VALID, spire_pubkey: 'abc' }],
-    ['non-bunker url', { ...VALID, bunker_url: 'https://evil/' }],
+    ['missing spire_npub', { ...VALID, spire_npub: undefined }],
+    ['non-npub spire_npub', { ...VALID, spire_npub: 'a'.repeat(64) }],
+    ['missing lnbits_npub', { ...VALID, lnbits_npub: undefined }],
+    ['non-npub lnbits_npub', { ...VALID, lnbits_npub: 'notanpub' }],
+    ['empty bunker_secret', { ...VALID, bunker_secret: '' }],
+    ['missing bunker_secret', { ...VALID, bunker_secret: undefined }],
     ['empty relays', { ...VALID, relays: [] }],
     ['non-string relay', { ...VALID, relays: [123] }],
+    ['empty bunker_relay', { ...VALID, bunker_relay: '' }],
   ])('rejects %s', (_label, json) => {
     expect(() => parseSpireSeed(makeSeed(json))).toThrow()
   })
diff --git a/packages/nostr-client/src/seed.ts b/packages/nostr-client/src/seed.ts
index e2ab902..482d6b9 100644
--- a/packages/nostr-client/src/seed.ts
+++ b/packages/nostr-client/src/seed.ts
@@ -3,40 +3,52 @@
  *
  * The operator dashboard (aiolabs/spirekeeper `pairing.py`) hands each ATM a
  * one-time seed URL that encodes the bunker connection + the spire's signing
- * identity. Wire contract (model A1):
+ * identity. Wire contract (model A1, minimal encoding):
  *
  *   spire-seed:v1:<base64url(json, no padding)>
  *   json = {
  *     "v": 1,
- *     "spire_npub":   "npub1…",   // informational, ignored here
- *     "spire_pubkey": "<64-hex>", // the spire's bunker-held signing identity
- *     "bunker_url":   "bunker://<spire_pubkey_hex>?relay=<url>&secret=<sec>",
- *     "relays":       ["wss://…"] // relays for the spire's OWN events (21000/30078)
+ *     "spire_npub":    "npub1…",     // spire signing identity (bech32; hex derived)
+ *     "lnbits_npub":   "npub1…",     // LNbits nostr-transport server identity
+ *     "bunker_secret": "<sec>",      // one-shot NIP-46 connect token
+ *     "relays":        ["wss://…"],  // relays the spire's OWN events use (21000/30078)
+ *     "bunker_relay":  "wss://…"     // OPTIONAL — NIP-46 relay; defaults to relays[0]
  *   }
  *
- * - base64url is `urlsafe_b64encode(...).rstrip("=")` → re-pad to a multiple
- *   of 4 before decoding.
- * - `relay` / `secret` inside `bunker_url` are percent-encoded; decoding them
- *   is left to nostr-tools `parseBunkerInput` (see bunker-signer.ts), so we
- *   keep `bunker_url` verbatim.
- * - `bunker_url`'s relay is the BUNKER relay; `relays[]` is where the spire
- *   publishes its own events. They may differ — both must be spire-reachable.
+ * Design (see aiolabs/bitspire#70): the pubkey is carried ONCE, as an npub.
+ * The old shape spelled it three times (spire_npub + spire_pubkey hex + inside
+ * a full bunker_url), which bloats a QR that's already hard to scan. Here:
+ *
+ * - `spire_pubkey` (hex) is derived from `spire_npub` (npub is ~the same length
+ *   as hex but carries a bech32 checksum — real error-detection for a value
+ *   read off a camera).
+ * - `bunker_url` is RECONSTRUCTED from `spire_pubkey`, `bunker_relay` (or
+ *   `relays[0]`), and `bunker_secret`, then handed verbatim to nostr-tools
+ *   `parseBunkerInput` (see bunker-signer.ts).
+ * - `lnbits_npub` gives the ATM its LNbits transport server pubkey so a paired
+ *   machine needs nothing else provisioned to reach the backend (#70 part 2).
+ *
+ * base64url is `urlsafe_b64encode(...).rstrip("=")` → re-pad to a multiple of 4
+ * before decoding.
  */
 
 import { sha256 } from '@noble/hashes/sha2.js'
 import { bytesToHex } from 'nostr-tools/utils'
+import { decode as nip19Decode } from 'nostr-tools/nip19'
 
 export const SPIRE_SEED_SCHEME = 'spire-seed:v1:'
 
 export interface SpireSeed {
   /** Seed format version (always 1 for this scheme). */
   v: number
-  /** The spire's signing identity — 64-char hex. Every event is signed as this. */
+  /** The spire's signing identity — 64-char hex, derived from `spire_npub`. */
   spirePubkey: string
-  /** `bunker://<pubkey>?relay=&secret=` — handed to nostr-tools parseBunkerInput. */
+  /** `bunker://<pubkey>?relay=&secret=` — reconstructed, handed to parseBunkerInput. */
   bunkerUrl: string
   /** Relays where the spire publishes its own events (kind 21000 / 30078). */
   relays: string[]
+  /** LNbits nostr-transport server pubkey — 64-char hex, derived from `lnbits_npub`. */
+  lnbitsServerPubkey: string
 }
 
 const HEX64 = /^[0-9a-f]{64}$/
@@ -50,6 +62,23 @@ function base64urlDecode(input: string): string {
   return Buffer.from(padded, 'base64').toString('binary')
 }
 
+/** Decode an `npub1…` to its 64-char hex pubkey, failing closed. */
+function hexFromNpub(value: unknown, field: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`parseSpireSeed: ${field} must be a string`)
+  }
+  let decoded: ReturnType<typeof nip19Decode>
+  try {
+    decoded = nip19Decode(value)
+  } catch (err) {
+    throw new Error(`parseSpireSeed: ${field} is not a valid npub (${(err as Error).message})`)
+  }
+  if (decoded.type !== 'npub' || typeof decoded.data !== 'string' || !HEX64.test(decoded.data)) {
+    throw new Error(`parseSpireSeed: ${field} must be an npub`)
+  }
+  return decoded.data
+}
+
 /**
  * Parse + validate a `spire-seed:v1:` URL. Throws on any malformation —
  * the seed is a trust root, so we fail closed rather than connect to a
@@ -77,14 +106,12 @@ export function parseSpireSeed(seedUrl: string): SpireSeed {
     throw new Error(`parseSpireSeed: unsupported version ${String(obj.v)}`)
   }
 
-  const spirePubkey = obj.spire_pubkey
-  if (typeof spirePubkey !== 'string' || !HEX64.test(spirePubkey)) {
-    throw new Error('parseSpireSeed: spire_pubkey must be 64-char hex')
-  }
+  const spirePubkey = hexFromNpub(obj.spire_npub, 'spire_npub')
+  const lnbitsServerPubkey = hexFromNpub(obj.lnbits_npub, 'lnbits_npub')
 
-  const bunkerUrl = obj.bunker_url
-  if (typeof bunkerUrl !== 'string' || !bunkerUrl.startsWith('bunker://')) {
-    throw new Error('parseSpireSeed: bunker_url must be a bunker:// URL')
+  const bunkerSecret = obj.bunker_secret
+  if (typeof bunkerSecret !== 'string' || bunkerSecret.length === 0) {
+    throw new Error('parseSpireSeed: bunker_secret must be a non-empty string')
   }
 
   const relays = obj.relays
@@ -92,7 +119,25 @@ export function parseSpireSeed(seedUrl: string): SpireSeed {
     throw new Error('parseSpireSeed: relays must be a non-empty string array')
   }
 
-  return { v: 1, spirePubkey, bunkerUrl, relays: relays as string[] }
+  // Optional bunker relay; default to the first event relay. Keeps the common
+  // case (bunker on the same relay) one field lighter, while still allowing a
+  // distinct NIP-46 relay when the operator runs one.
+  let bunkerRelay = relays[0] as string
+  if (obj.bunker_relay !== undefined) {
+    if (typeof obj.bunker_relay !== 'string' || obj.bunker_relay.length === 0) {
+      throw new Error('parseSpireSeed: bunker_relay, if present, must be a non-empty string')
+    }
+    bunkerRelay = obj.bunker_relay
+  }
+
+  // Reconstruct the bunker URL nostr-tools expects. relay + secret are
+  // percent-encoded here; parseBunkerInput decodes them downstream.
+  const bunkerUrl =
+    `bunker://${spirePubkey}` +
+    `?relay=${encodeURIComponent(bunkerRelay)}` +
+    `&secret=${encodeURIComponent(bunkerSecret)}`
+
+  return { v: 1, spirePubkey, bunkerUrl, relays: relays as string[], lnbitsServerPubkey }
 }
 
 /**

From 786789f5170cd1e8c3523498afa499bb14cd01f8 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Wed, 1 Jul 2026 13:16:16 +0200
Subject: [PATCH 35/82] fix(machine): resume from binding when a stored spire
 seed won't parse
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

resolveSigner parses the stored VITE_SPIRE_SEED on every boot before it checks
the binding, so a machine whose .env still holds a legacy-shape seed would
throw on the new parser (bitspire-#70) and surface "ATM Unavailable" on the
next auto-pull — even though it has a perfectly good, server-persistent binding
to resume from.

Guard the parse: an unparseable stored seed with a binding present falls back
to resuming the binding (authoritative); with no binding it still fails closed,
since the seed is then the only pairing input. Also dedupes the three
resume-from-binding call sites behind a small local.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/services/signer-resolver.ts | 42 ++++++++++++++------
 1 file changed, 30 insertions(+), 12 deletions(-)

diff --git a/apps/machine/src/services/signer-resolver.ts b/apps/machine/src/services/signer-resolver.ts
index 44aa4b5..65f1647 100644
--- a/apps/machine/src/services/signer-resolver.ts
+++ b/apps/machine/src/services/signer-resolver.ts
@@ -26,6 +26,7 @@ import {
   parseSpireSeed,
   seedFingerprint,
   type Signer,
+  type SpireSeed,
 } from '@bitSpire/nostr-client'
 import type { BunkerBindingRecord } from '@/types/electron'
 
@@ -67,17 +68,38 @@ async function loadPairingState(): Promise<PairingState> {
 export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer> {
   const { spireSeed, binding } = await loadPairingState()
 
+  const resume = (b: BunkerBindingRecord): Promise<Signer> =>
+    resumeFromBinding({
+      clientSecretHex: b.clientSecretHex,
+      spirePubkey: b.spirePubkey,
+      bunkerUrl: b.bunkerUrl,
+    })
+
   if (spireSeed) {
-    const seed = parseSpireSeed(spireSeed)
-    const fingerprint = seedFingerprint(spireSeed)
+    let seed: SpireSeed
+    let fingerprint: string
+    try {
+      seed = parseSpireSeed(spireSeed)
+      fingerprint = seedFingerprint(spireSeed)
+    } catch (err) {
+      // A stored seed we can't parse — e.g. a legacy-shape seed left in .env
+      // after the seed format changed (bitspire-#70). If we already hold a
+      // binding it's authoritative (server-persistent), so resume from it
+      // rather than bricking a paired machine on the next boot. With no
+      // binding the seed is our only pairing input, so fail closed.
+      if (binding) {
+        console.warn(
+          '[Signer] Stored spire seed is unparseable; resuming from existing binding:',
+          (err as Error).message,
+        )
+        return resume(binding)
+      }
+      throw err
+    }
 
     if (binding && binding.seedFingerprint === fingerprint) {
       console.log('[Signer] Resuming bunker session for spire', seed.spirePubkey)
-      return resumeFromBinding({
-        clientSecretHex: binding.clientSecretHex,
-        spirePubkey: binding.spirePubkey,
-        bunkerUrl: binding.bunkerUrl,
-      })
+      return resume(binding)
     }
 
     // First pair or re-pair: redeem the one-shot connect secret.
@@ -105,11 +127,7 @@ export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer>
   // No seed in this boot but a binding survives → resume.
   if (binding) {
     console.log('[Signer] Resuming bunker session from stored binding (no seed this boot)')
-    return resumeFromBinding({
-      clientSecretHex: binding.clientSecretHex,
-      spirePubkey: binding.spirePubkey,
-      bunkerUrl: binding.bunkerUrl,
-    })
+    return resume(binding)
   }
 
   if (opts.allowEphemeral) {

From 883c599835f9cccf00cbe6cd2ad293981cbf3b38 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Wed, 1 Jul 2026 21:09:50 +0200
Subject: [PATCH 36/82] feat(machine): source LNbits transport from the pairing
 seed, not just env
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Completes the consumer half of bitspire-#70: a paired machine gets its LNbits
transport relay(s) + server pubkey from the pairing, so a blank-.env unit reaches
the backend after scanning a seed — no VITE_RELAY_URL / VITE_LNBITS_SERVER_PUBKEY
provisioning.

- resolveSigner now returns { signer, transport }. transport (relays +
  lnbitsServerPubkey) comes from the seed on a fresh pair / seeded resume, and
  from the binding on a seedless resume. It's threaded out of resolveSigner
  rather than re-parsed in loadLightningConfig because the seed arrives over the
  one-shot get-atm-secrets IPC — a second consumer would break that contract.
- bunker_binding persists relays + lnbits_server_pubkey (state.db v11→v12,
  nullable so pre-#70 bindings resume and fall back to env). Mirrored into
  BunkerBindingRecord (preload + electron.d.ts).
- initializeLightningServices resolves effective transport with env-wins
  precedence (explicit env override for dev, else pairing, else a dev-only
  localhost relay), mutating CONFIG to a single source of truth and building the
  Nostr/LNbits/CLINK clients from the full relay list. Strict + required-config
  validation now run on the resolved values.

state.db round-trip test covers the new columns + their absence on a pre-#70
binding. Renderer + electron typechecks and all 38 machine tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../__tests__/state-store-bunker.test.ts      | 69 +++++++++++++++++++
 apps/machine/electron/preload.ts              |  4 ++
 apps/machine/electron/state-store.ts          | 69 ++++++++++++++++---
 apps/machine/src/App.vue                      |  3 +-
 apps/machine/src/services/lightning.ts        | 57 +++++++++++----
 apps/machine/src/services/signer-resolver.ts  | 51 ++++++++++++--
 apps/machine/src/types/electron.d.ts          |  4 ++
 7 files changed, 224 insertions(+), 33 deletions(-)
 create mode 100644 apps/machine/electron/__tests__/state-store-bunker.test.ts

diff --git a/apps/machine/electron/__tests__/state-store-bunker.test.ts b/apps/machine/electron/__tests__/state-store-bunker.test.ts
new file mode 100644
index 0000000..a668059
--- /dev/null
+++ b/apps/machine/electron/__tests__/state-store-bunker.test.ts
@@ -0,0 +1,69 @@
+/**
+ * Tests for bunker-binding persistence in state-store (aiolabs/bitspire#52,
+ * transport config added in #70).
+ *
+ * Validates the round-trip of the binding singleton, including the v11→v12
+ * transport columns (relays JSON + lnbits_server_pubkey) and their absence on
+ * a pre-#70 binding.
+ *
+ * Uses an in-memory SQLite database — fresh per test, no on-disk artifacts.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import {
+  clearBunkerBinding,
+  closeDatabase,
+  getBunkerBinding,
+  initDatabase,
+  saveBunkerBinding,
+  type StoredBunkerBinding,
+} from '../state-store.js'
+
+const BASE: StoredBunkerBinding = {
+  clientSecretHex: 'aa'.repeat(32),
+  spirePubkey: 'bb'.repeat(32),
+  bunkerUrl: 'bunker://bb?relay=wss%3A%2F%2Fr%2F&secret=deadbeef',
+  seedFingerprint: 'cc'.repeat(32),
+  pairedAt: 1_780_000_000,
+}
+
+beforeEach(() => {
+  initDatabase(':memory:')
+})
+afterEach(() => {
+  closeDatabase()
+})
+
+describe('bunker binding persistence', () => {
+  it('round-trips a binding carrying transport config (#70)', () => {
+    const binding: StoredBunkerBinding = {
+      ...BASE,
+      relays: ['wss://one.relay/', 'wss://two.relay/'],
+      lnbitsServerPubkey: 'dd'.repeat(32),
+    }
+    saveBunkerBinding(binding)
+    expect(getBunkerBinding()).toEqual(binding)
+  })
+
+  it('round-trips a pre-#70 binding (no transport config) as undefined fields', () => {
+    saveBunkerBinding(BASE)
+    const got = getBunkerBinding()
+    expect(got).toEqual(BASE)
+    expect(got?.relays).toBeUndefined()
+    expect(got?.lnbitsServerPubkey).toBeUndefined()
+  })
+
+  it('upserts transport config in place (re-pair overwrites)', () => {
+    saveBunkerBinding({ ...BASE, relays: ['wss://old/'], lnbitsServerPubkey: 'ee'.repeat(32) })
+    saveBunkerBinding({ ...BASE, relays: ['wss://new/'], lnbitsServerPubkey: 'ff'.repeat(32) })
+    const got = getBunkerBinding()
+    expect(got?.relays).toEqual(['wss://new/'])
+    expect(got?.lnbitsServerPubkey).toBe('ff'.repeat(32))
+  })
+
+  it('returns null after clear', () => {
+    saveBunkerBinding(BASE)
+    clearBunkerBinding()
+    expect(getBunkerBinding()).toBeNull()
+  })
+})
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index f1320fb..5483e46 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -51,6 +51,10 @@ export interface BunkerBindingRecord {
   bunkerUrl: string
   seedFingerprint: string
   pairedAt: number
+  /** LNbits transport relays from the seed (#70); absent on pre-#70 bindings. */
+  relays?: string[]
+  /** LNbits nostr-transport server pubkey (hex) from the seed (#70). */
+  lnbitsServerPubkey?: string
 }
 
 /**
diff --git a/apps/machine/electron/state-store.ts b/apps/machine/electron/state-store.ts
index d9282ac..7ea3e16 100644
--- a/apps/machine/electron/state-store.ts
+++ b/apps/machine/electron/state-store.ts
@@ -15,7 +15,7 @@ import fs from 'node:fs'
 
 let db: Database.Database | null = null
 
-const SCHEMA_VERSION = '11'
+const SCHEMA_VERSION = '12'
 
 function getDbPath(): string {
   const prodDir = '/var/lib/bitspire'
@@ -121,7 +121,9 @@ export function initDatabase(dbPath?: string): void {
       spire_pubkey TEXT NOT NULL,
       bunker_url TEXT NOT NULL,
       seed_fingerprint TEXT NOT NULL,
-      paired_at INTEGER NOT NULL
+      paired_at INTEGER NOT NULL,
+      relays TEXT,
+      lnbits_server_pubkey TEXT
     );
   `)
 
@@ -352,6 +354,21 @@ export function initDatabase(dbPath?: string): void {
     `)
     db.prepare('UPDATE meta SET value = ? WHERE key = ?').run('11', 'schema_version')
     console.log('[StateStore] Migrated schema v10 → v11 (added bunker_binding)')
+    existing.value = '11'
+  }
+
+  if (existing && existing.value === '11') {
+    // Migration v11 → v12: carry the LNbits transport config in the binding
+    // (aiolabs/bitspire#70). relays (JSON array) + lnbits_server_pubkey let a
+    // paired machine reach the backend from the pairing alone — no VITE_RELAY_URL
+    // / VITE_LNBITS_SERVER_PUBKEY provisioning. Nullable: bindings written before
+    // this (the seed didn't carry them) resume fine and fall back to env.
+    db.exec(`
+      ALTER TABLE bunker_binding ADD COLUMN relays TEXT;
+      ALTER TABLE bunker_binding ADD COLUMN lnbits_server_pubkey TEXT;
+    `)
+    db.prepare('UPDATE meta SET value = ? WHERE key = ?').run('12', 'schema_version')
+    console.log('[StateStore] Migrated schema v11 → v12 (bunker_binding transport config)')
   }
 
   // Defensive: a fresh install at SCHEMA_VERSION skips all migrations.
@@ -428,6 +445,14 @@ export interface StoredBunkerBinding {
   seedFingerprint: string
   /** Unix seconds when the pairing was redeemed. */
   pairedAt: number
+  /**
+   * LNbits transport relays from the pairing seed (aiolabs/bitspire#70). Lets a
+   * resumed (seedless) boot reach the backend without env provisioning.
+   * Undefined for bindings written before the seed carried them.
+   */
+  relays?: string[]
+  /** LNbits nostr-transport server pubkey (hex) from the seed (#70). */
+  lnbitsServerPubkey?: string
 }
 
 /** Read the persisted bunker binding, or null if the ATM is unpaired. */
@@ -435,7 +460,7 @@ export function getBunkerBinding(): StoredBunkerBinding | null {
   if (!db) throw new Error('Database not initialized')
   const row = db
     .prepare(
-      'SELECT client_secret_hex, spire_pubkey, bunker_url, seed_fingerprint, paired_at FROM bunker_binding WHERE id = 1'
+      'SELECT client_secret_hex, spire_pubkey, bunker_url, seed_fingerprint, paired_at, relays, lnbits_server_pubkey FROM bunker_binding WHERE id = 1'
     )
     .get() as
     | {
@@ -444,6 +469,8 @@ export function getBunkerBinding(): StoredBunkerBinding | null {
         bunker_url: string
         seed_fingerprint: string
         paired_at: number
+        relays: string | null
+        lnbits_server_pubkey: string | null
       }
     | undefined
   if (!row) return null
@@ -453,27 +480,47 @@ export function getBunkerBinding(): StoredBunkerBinding | null {
     bunkerUrl: row.bunker_url,
     seedFingerprint: row.seed_fingerprint,
     pairedAt: row.paired_at,
+    relays: parseRelaysColumn(row.relays),
+    lnbitsServerPubkey: row.lnbits_server_pubkey ?? undefined,
   }
 }
 
+/** Decode the JSON-array `relays` column, tolerating null/legacy/garbage. */
+function parseRelaysColumn(value: string | null): string[] | undefined {
+  if (!value) return undefined
+  try {
+    const parsed = JSON.parse(value)
+    if (Array.isArray(parsed) && parsed.every((r) => typeof r === 'string')) {
+      return parsed as string[]
+    }
+  } catch {
+    // fall through
+  }
+  return undefined
+}
+
 /** Upsert the bunker binding after a successful (re-)pairing. */
 export function saveBunkerBinding(binding: StoredBunkerBinding): void {
   if (!db) throw new Error('Database not initialized')
   db.prepare(
-    `INSERT INTO bunker_binding (id, client_secret_hex, spire_pubkey, bunker_url, seed_fingerprint, paired_at)
-     VALUES (1, ?, ?, ?, ?, ?)
+    `INSERT INTO bunker_binding (id, client_secret_hex, spire_pubkey, bunker_url, seed_fingerprint, paired_at, relays, lnbits_server_pubkey)
+     VALUES (1, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(id) DO UPDATE SET
-       client_secret_hex = excluded.client_secret_hex,
-       spire_pubkey      = excluded.spire_pubkey,
-       bunker_url        = excluded.bunker_url,
-       seed_fingerprint  = excluded.seed_fingerprint,
-       paired_at         = excluded.paired_at`
+       client_secret_hex    = excluded.client_secret_hex,
+       spire_pubkey         = excluded.spire_pubkey,
+       bunker_url           = excluded.bunker_url,
+       seed_fingerprint     = excluded.seed_fingerprint,
+       paired_at            = excluded.paired_at,
+       relays               = excluded.relays,
+       lnbits_server_pubkey = excluded.lnbits_server_pubkey`
   ).run(
     binding.clientSecretHex,
     binding.spirePubkey,
     binding.bunkerUrl,
     binding.seedFingerprint,
-    binding.pairedAt
+    binding.pairedAt,
+    binding.relays ? JSON.stringify(binding.relays) : null,
+    binding.lnbitsServerPubkey ?? null
   )
 }
 
diff --git a/apps/machine/src/App.vue b/apps/machine/src/App.vue
index f28b639..c7e1537 100644
--- a/apps/machine/src/App.vue
+++ b/apps/machine/src/App.vue
@@ -106,7 +106,8 @@ onMounted(async () => {
       const relayUrl = config?.relayUrl || import.meta.env.VITE_RELAY_URL
       // Best-effort: resolve a signer (bunker resume / pairing, or dev nsec).
       // If the ATM isn't paired yet, skip the beacon rather than fail the screen.
-      const signer = await resolveSigner({ allowEphemeral: true }).catch(() => null)
+      const resolved = await resolveSigner({ allowEphemeral: true }).catch(() => null)
+      const signer = resolved?.signer ?? null
       if (signer && relayUrl) {
         const client = new NostrClient({ relays: [{ url: relayUrl }], signer })
         await client.connect()
diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index f673b24..039cf01 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -54,7 +54,10 @@ interface LightningConfig {
  */
 async function loadLightningConfig(): Promise<LightningConfig> {
   const defaults: LightningConfig = {
-    relayUrl: 'ws://localhost:7777',
+    // Empty when unset (not the dev relay) so initializeLightningServices can
+    // tell "operator gave us a relay" from "fall back to the pairing seed". See
+    // aiolabs/bitspire#70 and DEV_DEFAULT_RELAY.
+    relayUrl: '',
     appId: '30270e761f2e30b1737f34ce661df45f521352b408b8ed18fcc09f3f0dec5097', // bitSpire ATM app ID
     operatorPubkeys: [],
     lnbitsServerPubkey: '',
@@ -97,6 +100,9 @@ async function loadLightningConfig(): Promise<LightningConfig> {
 // Config is loaded async now - will be set in initializeLightningServices
 let CONFIG: LightningConfig
 
+/** Dev-only relay used when neither env nor the pairing supplies one. */
+const DEV_DEFAULT_RELAY = 'ws://localhost:7777'
+
 /** Safety timeout in ms (15 minutes) — absolute maximum LNURL session lifetime.
  * Sessions are normally cleaned up by the state machine on idle transition.
  * This is a safety net in case the state machine doesn't clean up properly. */
@@ -395,9 +401,6 @@ export async function initializeLightningServices(options?: {
   // Load configuration (async for Electron runtime config)
   CONFIG = await loadLightningConfig()
 
-  console.log('[Lightning] Relay URL:', CONFIG.relayUrl)
-  console.log('[Lightning] LNbits server pubkey:', CONFIG.lnbitsServerPubkey || '(not configured)')
-
   // Resolve the signing identity BEFORE validating the LNbits transport
   // config. An unpaired machine must reach the QR-pairing wizard regardless
   // of relay/server-pubkey provisioning — pairing is what provides those — so
@@ -410,17 +413,43 @@ export async function initializeLightningServices(options?: {
   // transport key; the operator's nsecbunkerd holds the signing key); in dev
   // it falls back to an in-process LocalSigner. The Phase-A Signer seam means
   // nothing downstream changes. See aiolabs/bitspire#52.
-  const signer: Signer = await resolveSigner({ allowEphemeral: !options?.strict })
+  const { signer, transport } = await resolveSigner({ allowEphemeral: !options?.strict })
   console.log('[Lightning] ATM pubkey:', signer.pubkey)
 
-  // Strict mode: validate config is production-ready (no localhost).
+  // Resolve the effective LNbits transport. Precedence: explicit env wins (dev
+  // + operator override), else the pairing (seed/binding) supplies it (#70) so
+  // a blank-.env paired machine reaches the backend from the seed alone, else a
+  // dev-only localhost fallback. CONFIG is mutated to the resolved values so
+  // downstream (and the exported CONFIG) see a single source of truth.
+  const envRelay = CONFIG.relayUrl
+  const envPubkey = CONFIG.lnbitsServerPubkey
+  const relays: string[] = envRelay
+    ? [envRelay]
+    : transport && transport.relays.length > 0
+      ? transport.relays
+      : [DEV_DEFAULT_RELAY]
+  CONFIG.relayUrl = relays[0]!
+  CONFIG.lnbitsServerPubkey = envPubkey || transport?.lnbitsServerPubkey || ''
+  console.log(
+    '[Lightning] Relay(s):',
+    relays.join(', '),
+    envRelay ? '(env)' : transport?.relays.length ? '(pairing)' : '(default)',
+  )
+  console.log(
+    '[Lightning] LNbits server pubkey:',
+    CONFIG.lnbitsServerPubkey || '(not configured)',
+    envPubkey ? '(env)' : transport?.lnbitsServerPubkey ? '(pairing)' : '',
+  )
+
+  // Strict mode: validate the RESOLVED config is production-ready (no
+  // localhost). Values may come from env or the pairing seed (#70).
   if (options?.strict) {
     const errors: string[] = []
     if (/localhost|127\.0\.0\.1/.test(CONFIG.relayUrl)) {
-      errors.push('VITE_RELAY_URL contains localhost')
+      errors.push('relay resolves to localhost (VITE_RELAY_URL / seed relays)')
     }
     if (!CONFIG.lnbitsServerPubkey) {
-      errors.push('VITE_LNBITS_SERVER_PUBKEY is not set')
+      errors.push('no LNbits server pubkey (VITE_LNBITS_SERVER_PUBKEY / seed lnbits_npub)')
     }
     if (errors.length > 0) {
       throw new Error('[Lightning] Production config validation failed:\n- ' + errors.join('\n- '))
@@ -429,17 +458,17 @@ export async function initializeLightningServices(options?: {
 
   // Validate required configuration. Reached only for a paired machine (an
   // unpaired one threw NoPairingError above) — it needs the LNbits server
-  // pubkey to talk to the transport.
+  // pubkey to talk to the transport, from either env or the pairing seed.
   if (!CONFIG.lnbitsServerPubkey) {
     throw new Error(
-      '[Lightning] VITE_LNBITS_SERVER_PUBKEY is required. ' +
-        'Get it from: docker logs lnbits | grep nostr_transport pubkey',
+      '[Lightning] LNbits server pubkey is required — set VITE_LNBITS_SERVER_PUBKEY ' +
+        'or pair with a seed that carries lnbits_npub (aiolabs/bitspire#70).',
     )
   }
 
   // Create Nostr client
   const nostrClient = new NostrClient({
-    relays: [{ url: CONFIG.relayUrl }],
+    relays: relays.map((url) => ({ url })),
     signer,
   })
 
@@ -449,7 +478,7 @@ export async function initializeLightningServices(options?: {
   // LNbits nostr-transport client.
   const lnbits = new LnbitsClient({
     serverPubkey: CONFIG.lnbitsServerPubkey,
-    relays: [CONFIG.relayUrl],
+    relays,
   })
   lnbits.initialize(nostrClient, signer)
   _lnbitsRef = lnbits
@@ -472,7 +501,7 @@ export async function initializeLightningServices(options?: {
     nostrClient,
     signer,
     operatorPubkey: CONFIG.operatorPubkeys,
-    relays: [CONFIG.relayUrl],
+    relays,
   })
 
   // Callbacks for events
diff --git a/apps/machine/src/services/signer-resolver.ts b/apps/machine/src/services/signer-resolver.ts
index 65f1647..2d29ab6 100644
--- a/apps/machine/src/services/signer-resolver.ts
+++ b/apps/machine/src/services/signer-resolver.ts
@@ -51,6 +51,25 @@ export interface ResolveSignerOptions {
   allowEphemeral: boolean
 }
 
+/** LNbits transport config carried by the pairing (aiolabs/bitspire#70). */
+export interface TransportConfig {
+  /** LNbits transport relays (kind-21000 / 30078). */
+  relays: string[]
+  /** LNbits nostr-transport server pubkey (hex). */
+  lnbitsServerPubkey: string
+}
+
+export interface ResolvedSigner {
+  signer: Signer
+  /**
+   * Transport config sourced from the pairing — the seed on a fresh pair /
+   * seeded resume, the binding on a seedless resume. Null when unavailable (an
+   * ephemeral dev signer, or a pre-#70 binding that never stored it); the
+   * caller then falls back to env provisioning.
+   */
+  transport: TransportConfig | null
+}
+
 interface PairingState {
   spireSeed: string
   binding: BunkerBindingRecord | null
@@ -65,7 +84,7 @@ async function loadPairingState(): Promise<PairingState> {
   return { spireSeed: (import.meta.env.VITE_SPIRE_SEED as string | undefined) || '', binding: null }
 }
 
-export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer> {
+export async function resolveSigner(opts: ResolveSignerOptions): Promise<ResolvedSigner> {
   const { spireSeed, binding } = await loadPairingState()
 
   const resume = (b: BunkerBindingRecord): Promise<Signer> =>
@@ -75,6 +94,18 @@ export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer>
       bunkerUrl: b.bunkerUrl,
     })
 
+  // Transport config from a binding — present only when the pairing seed
+  // carried it (post-#70) and it was persisted. Null on pre-#70 bindings.
+  const transportFromBinding = (b: BunkerBindingRecord): TransportConfig | null =>
+    b.relays && b.relays.length > 0 && b.lnbitsServerPubkey
+      ? { relays: b.relays, lnbitsServerPubkey: b.lnbitsServerPubkey }
+      : null
+
+  const transportFromSeed = (s: SpireSeed): TransportConfig => ({
+    relays: s.relays,
+    lnbitsServerPubkey: s.lnbitsServerPubkey,
+  })
+
   if (spireSeed) {
     let seed: SpireSeed
     let fingerprint: string
@@ -92,14 +123,16 @@ export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer>
           '[Signer] Stored spire seed is unparseable; resuming from existing binding:',
           (err as Error).message,
         )
-        return resume(binding)
+        return { signer: await resume(binding), transport: transportFromBinding(binding) }
       }
       throw err
     }
 
     if (binding && binding.seedFingerprint === fingerprint) {
       console.log('[Signer] Resuming bunker session for spire', seed.spirePubkey)
-      return resume(binding)
+      // Seed present + parsed → prefer its (fresh) transport config over the
+      // binding's, which may predate the seed carrying transport (pre-#70).
+      return { signer: await resume(binding), transport: transportFromSeed(seed) }
     }
 
     // First pair or re-pair: redeem the one-shot connect secret.
@@ -111,23 +144,27 @@ export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer>
       clientSecretHex: transport.secretHex,
     })
     if (isElectron && window.electronAPI) {
+      // Persist the seed's transport config alongside the binding so a later
+      // seedless resume still reaches the backend without env provisioning.
       await window.electronAPI.saveBunkerBinding({
         clientSecretHex: transport.secretHex,
         spirePubkey: seed.spirePubkey,
         bunkerUrl: seed.bunkerUrl,
         seedFingerprint: fingerprint,
         pairedAt: Math.floor(Date.now() / 1000),
+        relays: seed.relays,
+        lnbitsServerPubkey: seed.lnbitsServerPubkey,
       })
       // Re-pair → re-publish the cassette-state hello to the new operator (#56).
       await window.electronAPI.resetBootstrapGate()
     }
-    return signer
+    return { signer, transport: transportFromSeed(seed) }
   }
 
   // No seed in this boot but a binding survives → resume.
   if (binding) {
     console.log('[Signer] Resuming bunker session from stored binding (no seed this boot)')
-    return resume(binding)
+    return { signer: await resume(binding), transport: transportFromBinding(binding) }
   }
 
   if (opts.allowEphemeral) {
@@ -135,10 +172,10 @@ export async function resolveSigner(opts: ResolveSignerOptions): Promise<Signer>
     const devKey = !isElectron ? (import.meta.env.VITE_ATM_PRIVATE_KEY as string | undefined) : ''
     if (devKey) {
       console.warn('[Signer] No bunker pairing — using LocalSigner from VITE_ATM_PRIVATE_KEY (dev)')
-      return new LocalSigner(loadIdentityFromHex(devKey))
+      return { signer: new LocalSigner(loadIdentityFromHex(devKey)), transport: null }
     }
     console.warn('[Signer] No bunker pairing — generated ephemeral LocalSigner (dev only)')
-    return new LocalSigner(generateIdentity())
+    return { signer: new LocalSigner(generateIdentity()), transport: null }
   }
 
   throw new NoPairingError()
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index 64af629..3b17d0e 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -46,6 +46,10 @@ export interface BunkerBindingRecord {
   bunkerUrl: string
   seedFingerprint: string
   pairedAt: number
+  /** LNbits transport relays from the seed (#70); absent on pre-#70 bindings. */
+  relays?: string[]
+  /** LNbits nostr-transport server pubkey (hex) from the seed (#70). */
+  lnbitsServerPubkey?: string
 }
 
 export interface AtmSecrets {

From 5179a21da6350f46e92c2739b4148787bf491269 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Wed, 1 Jul 2026 23:43:28 +0200
Subject: [PATCH 37/82] fix(nostr-client): reject non-ws(s):// relays in the
 spire seed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The npubs in the seed are bech32-checksummed, so a mis-scanned character is
caught — but the relay strings are raw inside the base64. A QR misread silently
turned `ws://192.168.0.32:5001/...` into `As://192.168.0.32:5001/...`, which
parsed fine and then crash-looped the machine on an unreachable NIP-46 relay.

Validate every `relays[]` entry (and `bunker_relay`) is a `ws://`/`wss://` URL
at parse time, so a garbled scan is rejected as an invalid seed instead of
persisted. Part of bitspire-#70 pairing robustness.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/nostr-client/src/__tests__/seed.test.ts |  3 +++
 packages/nostr-client/src/seed.ts                | 16 ++++++++++++++++
 2 files changed, 19 insertions(+)

diff --git a/packages/nostr-client/src/__tests__/seed.test.ts b/packages/nostr-client/src/__tests__/seed.test.ts
index 3e3bba7..6e38159 100644
--- a/packages/nostr-client/src/__tests__/seed.test.ts
+++ b/packages/nostr-client/src/__tests__/seed.test.ts
@@ -80,7 +80,10 @@ describe('parseSpireSeed', () => {
     ['missing bunker_secret', { ...VALID, bunker_secret: undefined }],
     ['empty relays', { ...VALID, relays: [] }],
     ['non-string relay', { ...VALID, relays: [123] }],
+    ['non-ws relay (scan corruption ws://→As://)', { ...VALID, relays: ['As://events.relay/'] }],
+    ['non-ws relay (http)', { ...VALID, relays: ['http://events.relay/'] }],
     ['empty bunker_relay', { ...VALID, bunker_relay: '' }],
+    ['non-ws bunker_relay', { ...VALID, bunker_relay: 'As://bunker.relay/' }],
   ])('rejects %s', (_label, json) => {
     expect(() => parseSpireSeed(makeSeed(json))).toThrow()
   })
diff --git a/packages/nostr-client/src/seed.ts b/packages/nostr-client/src/seed.ts
index 482d6b9..02a6470 100644
--- a/packages/nostr-client/src/seed.ts
+++ b/packages/nostr-client/src/seed.ts
@@ -53,6 +53,20 @@ export interface SpireSeed {
 
 const HEX64 = /^[0-9a-f]{64}$/
 
+/**
+ * A relay must be a `ws://` or `wss://` URL. Unlike the npubs (bech32-checksummed,
+ * so a mis-scanned character is caught), the relay strings are raw inside the
+ * seed's base64 — a QR misread can silently corrupt `ws://` into e.g. `As://`
+ * and the pairing then crash-loops on an unreachable relay. Reject at parse time
+ * so the wizard refuses a garbled scan instead of persisting it (bitspire#70).
+ */
+const WS_URL = /^wss?:\/\/[^\s]+$/
+function assertRelayUrl(value: string, field: string): void {
+  if (!WS_URL.test(value)) {
+    throw new Error(`parseSpireSeed: ${field} must be a ws:// or wss:// URL (got "${value}")`)
+  }
+}
+
 /** Decode an unpadded base64url string in both browser and Node. */
 function base64urlDecode(input: string): string {
   const padded = input.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(input.length / 4) * 4, '=')
@@ -118,6 +132,7 @@ export function parseSpireSeed(seedUrl: string): SpireSeed {
   if (!Array.isArray(relays) || relays.length === 0 || !relays.every((r) => typeof r === 'string')) {
     throw new Error('parseSpireSeed: relays must be a non-empty string array')
   }
+  relays.forEach((r, i) => assertRelayUrl(r as string, `relays[${i}]`))
 
   // Optional bunker relay; default to the first event relay. Keeps the common
   // case (bunker on the same relay) one field lighter, while still allowing a
@@ -127,6 +142,7 @@ export function parseSpireSeed(seedUrl: string): SpireSeed {
     if (typeof obj.bunker_relay !== 'string' || obj.bunker_relay.length === 0) {
       throw new Error('parseSpireSeed: bunker_relay, if present, must be a non-empty string')
     }
+    assertRelayUrl(obj.bunker_relay, 'bunker_relay')
     bunkerRelay = obj.bunker_relay
   }
 

From 0bc57dc754405b03a5c851241a84151bd74defa0 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Wed, 1 Jul 2026 23:43:28 +0200
Subject: [PATCH 38/82] feat(machine): pairing review step with a
 relay-reachability test

A well-formed but unreachable relay (localhost baked into a seed for a remote
machine, a wrong LAN IP, a relay that's down) parses fine and only fails later
as a NIP-46 connect crash-loop. Give the operator a way to catch it on-machine
before committing (bitspire-#70).

The wizard no longer commits immediately on a good scan: it now parses (without
persisting) and shows a review step with the decoded spire + relay(s), a "Test
relay" button (opens a WebSocket + NIP-01 REQ, reports reachable/latency or
unreachable), and Pair / Rescan. Only on "Pair" does it persist + relaunch into
the real pairing path.

- parseScannedSeed: validate-only split of ingestScannedSeed (no persist).
- testRelay: WebSocket reachability probe.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/components/PairingWizard.vue | 141 ++++++++++++++++--
 apps/machine/src/services/pairing/index.ts    |   6 +-
 apps/machine/src/services/pairing/ingest.ts   |  31 ++++
 .../src/services/pairing/relay-test.ts        |  69 +++++++++
 4 files changed, 233 insertions(+), 14 deletions(-)
 create mode 100644 apps/machine/src/services/pairing/relay-test.ts

diff --git a/apps/machine/src/components/PairingWizard.vue b/apps/machine/src/components/PairingWizard.vue
index f34409e..fb343e1 100644
--- a/apps/machine/src/components/PairingWizard.vue
+++ b/apps/machine/src/components/PairingWizard.vue
@@ -10,15 +10,18 @@
  * Capture is abstracted behind PairingSource, so NFC (or a HAL scanner) can be
  * offered later without changing this view.
  */
-import { onMounted, onUnmounted, ref, shallowRef } from 'vue'
+import { computed, onMounted, onUnmounted, ref, shallowRef } from 'vue'
 import {
   availablePairingSources,
   ingestScannedSeed,
+  parseScannedSeed,
+  testRelay,
   type PairingSource,
+  type RelayTestResult,
   type StopCapture,
 } from '@/services/pairing'
 
-type Phase = 'probing' | 'scanning' | 'no-source' | 'pairing' | 'error'
+type Phase = 'probing' | 'scanning' | 'review' | 'no-source' | 'pairing' | 'error'
 
 const phase = ref<Phase>('probing')
 const errorMessage = ref('')
@@ -28,6 +31,19 @@ const sources = shallowRef<PairingSource[]>([])
 const activeSource = shallowRef<PairingSource | null>(null)
 let stopCapture: StopCapture | null = null
 
+// Review-step state: the scanned-but-not-yet-committed seed + relay tests.
+const scannedRaw = ref('')
+const previewSpire = ref('')
+const previewRelays = ref<string[]>([])
+type RelayState = { status: 'idle' | 'testing' | 'done'; result?: RelayTestResult }
+const relayTests = ref<Record<string, RelayState>>({})
+const testingRelays = ref(false)
+const committing = ref(false)
+
+const anyRelayFailed = computed(() =>
+  Object.values(relayTests.value).some((s) => s.status === 'done' && s.result != null && !s.result.ok),
+)
+
 async function startWith(source: PairingSource) {
   await teardown()
   activeSource.value = source
@@ -50,18 +66,58 @@ let handling = false
 async function handleScan(raw: string) {
   if (handling) return
   handling = true
-  const result = await ingestScannedSeed(raw)
-  if (result.ok) {
-    // saveSpireSeed succeeded; relaunch is in flight — hold a friendly screen.
-    phase.value = 'pairing'
+  // Validate only — don't commit yet. Show a review step with the decoded
+  // relay + a "test relay" button so a well-formed but unreachable relay is
+  // caught before we relaunch into a pairing crash-loop (aiolabs/bitspire#70).
+  const preview = parseScannedSeed(raw)
+  if (preview.ok) {
+    await teardown() // camera off during review
+    scannedRaw.value = raw.trim()
+    previewSpire.value = preview.spirePubkey
+    previewRelays.value = preview.relays
+    relayTests.value = Object.fromEntries(preview.relays.map((r) => [r, { status: 'idle' }]))
+    errorMessage.value = ''
+    phase.value = 'review'
     return
   }
-  // Reject non-seed scans (a stray QR) and resume scanning.
-  console.warn('[Pairing] rejected scan:', result.reason, result.message)
-  errorMessage.value =
-    result.reason === 'invalid-seed'
-      ? 'That code is not a pairing code. Show the operator pairing QR.'
-      : result.message
+  // Reject non-seed / malformed scans (a stray QR, a corrupted relay) and resume.
+  console.warn('[Pairing] rejected scan:', preview.reason, preview.message)
+  errorMessage.value = 'That code is not a valid pairing code. Show the operator pairing QR.'
+  handling = false
+  if (activeSource.value) await startWith(activeSource.value)
+}
+
+/** Probe every relay in the scanned seed and record reachability. */
+async function testRelays() {
+  testingRelays.value = true
+  await Promise.all(
+    previewRelays.value.map(async (url) => {
+      relayTests.value[url] = { status: 'testing' }
+      const result = await testRelay(url)
+      relayTests.value[url] = { status: 'done', result }
+    }),
+  )
+  testingRelays.value = false
+}
+
+/** Commit the reviewed seed: persist + relaunch into the real pairing path. */
+async function confirmPair() {
+  committing.value = true
+  const result = await ingestScannedSeed(scannedRaw.value)
+  if (result.ok) {
+    phase.value = 'pairing' // relaunch in flight
+    return
+  }
+  committing.value = false
+  errorMessage.value = result.message
+  phase.value = 'error'
+}
+
+/** Discard the scan and go back to scanning. */
+async function rescan() {
+  scannedRaw.value = ''
+  previewRelays.value = []
+  relayTests.value = {}
   handling = false
   if (activeSource.value) await startWith(activeSource.value)
 }
@@ -121,6 +177,67 @@ onUnmounted(teardown)
       <p class="text-base lg:text-2xl text-muted-foreground">Pairing accepted — restarting…</p>
     </div>
 
+    <!-- Review: confirm the scanned relay is reachable before committing -->
+    <div v-if="phase === 'review'" class="flex w-full max-w-md flex-col items-center gap-5">
+      <p class="text-base lg:text-2xl text-muted-foreground">
+        Pairing code scanned. Test the relay, then pair.
+      </p>
+      <div class="w-full rounded-xl border border-border p-4 text-left">
+        <p class="text-xs uppercase text-muted-foreground">Spire</p>
+        <p class="mb-3 break-all font-mono text-sm">{{ previewSpire.slice(0, 16) }}…</p>
+        <p class="text-xs uppercase text-muted-foreground">Relay(s)</p>
+        <ul class="flex flex-col gap-2">
+          <li
+            v-for="url in previewRelays"
+            :key="url"
+            class="flex items-center justify-between gap-3"
+          >
+            <span class="break-all font-mono text-xs">{{ url }}</span>
+            <span class="shrink-0 text-sm">
+              <template v-if="relayTests[url]?.status === 'testing'">
+                <span class="text-muted-foreground">testing…</span>
+              </template>
+              <template v-else-if="relayTests[url]?.status === 'done'">
+                <span v-if="relayTests[url]?.result?.ok" class="text-green-500"
+                  >✓ {{ relayTests[url]?.result?.ms }}ms</span
+                >
+                <span v-else class="text-destructive">✗ unreachable</span>
+              </template>
+            </span>
+          </li>
+        </ul>
+      </div>
+
+      <div class="flex flex-wrap justify-center gap-3">
+        <button
+          class="rounded-lg border border-border px-4 py-2 text-sm disabled:opacity-50"
+          :disabled="testingRelays || committing"
+          @click="testRelays"
+        >
+          {{ testingRelays ? 'Testing…' : 'Test relay' }}
+        </button>
+        <button
+          class="rounded-lg border border-border px-4 py-2 text-sm disabled:opacity-50"
+          :disabled="committing"
+          @click="rescan"
+        >
+          Rescan
+        </button>
+        <button
+          class="rounded-lg bg-primary px-4 py-2 text-sm text-primary-foreground disabled:opacity-50"
+          :disabled="committing"
+          @click="confirmPair"
+        >
+          {{ committing ? 'Pairing…' : 'Pair this machine' }}
+        </button>
+      </div>
+
+      <p v-if="anyRelayFailed" class="max-w-md text-center text-sm text-warning">
+        A relay looks unreachable from this machine — pairing will fail unless it can reach the
+        relay. Check the URL/network, or rescan a corrected code.
+      </p>
+    </div>
+
     <p
       v-if="phase === 'no-source'"
       class="max-w-md text-center text-base lg:text-2xl text-muted-foreground"
diff --git a/apps/machine/src/services/pairing/index.ts b/apps/machine/src/services/pairing/index.ts
index 67e3ade..faaad95 100644
--- a/apps/machine/src/services/pairing/index.ts
+++ b/apps/machine/src/services/pairing/index.ts
@@ -14,8 +14,10 @@ import type { PairingSource } from './types'
 export type { PairingSource, PairingSourceKind, PairingSourceStartOptions, StopCapture } from './types'
 export { QrPairingSource } from './qr-source'
 export { NfcPairingSource } from './nfc-source'
-export { ingestScannedSeed } from './ingest'
-export type { IngestResult } from './ingest'
+export { ingestScannedSeed, parseScannedSeed } from './ingest'
+export type { IngestResult, SeedPreview } from './ingest'
+export { testRelay } from './relay-test'
+export type { RelayTestResult } from './relay-test'
 
 /** All sources in preference order, regardless of availability. */
 export function allPairingSources(): PairingSource[] {
diff --git a/apps/machine/src/services/pairing/ingest.ts b/apps/machine/src/services/pairing/ingest.ts
index a758f1e..dc22ad2 100644
--- a/apps/machine/src/services/pairing/ingest.ts
+++ b/apps/machine/src/services/pairing/ingest.ts
@@ -21,6 +21,37 @@ export type IngestResult =
   | { ok: true; spirePubkey: string; fingerprint: string; relays: string[] }
   | { ok: false; reason: 'invalid-seed' | 'no-bridge' | 'persist-failed'; message: string }
 
+export type SeedPreview =
+  | { ok: true; spirePubkey: string; fingerprint: string; relays: string[] }
+  | { ok: false; reason: 'invalid-seed'; message: string }
+
+/**
+ * Validate-only: parse a scanned payload as a spire-seed WITHOUT persisting or
+ * relaunching. The wizard uses this to show a review step (decoded relay + a
+ * "test relay" button) before committing, so a well-formed but unreachable
+ * relay is caught before the machine relaunches into a pairing crash-loop.
+ * `parseSpireSeed` already rejects a malformed relay (e.g. a QR misread of
+ * `ws://` → `As://`); this surfaces that as an invalid-seed rejection.
+ */
+export function parseScannedSeed(raw: string): SeedPreview {
+  const trimmed = (raw || '').trim()
+  try {
+    const seed = parseSpireSeed(trimmed)
+    return {
+      ok: true,
+      spirePubkey: seed.spirePubkey,
+      fingerprint: seedFingerprint(trimmed),
+      relays: seed.relays,
+    }
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'invalid-seed',
+      message: e instanceof Error ? e.message : 'Not a valid pairing code',
+    }
+  }
+}
+
 export async function ingestScannedSeed(raw: string): Promise<IngestResult> {
   const trimmed = (raw || '').trim()
 
diff --git a/apps/machine/src/services/pairing/relay-test.ts b/apps/machine/src/services/pairing/relay-test.ts
new file mode 100644
index 0000000..338c983
--- /dev/null
+++ b/apps/machine/src/services/pairing/relay-test.ts
@@ -0,0 +1,69 @@
+/**
+ * Relay reachability probe for the pairing wizard (aiolabs/bitspire#70).
+ *
+ * `parseSpireSeed` catches a MALFORMED relay (e.g. a QR misread of `ws://` into
+ * `As://`), but a well-formed-yet-unreachable relay — `ws://localhost:…` baked
+ * into a seed for a remote machine, a wrong LAN IP, or a relay that's simply
+ * down — still parses fine and would only fail later as a NIP-46 connect
+ * crash-loop. This opens a WebSocket to the relay (and sends a NIP-01 REQ so a
+ * real relay answers) so the operator can confirm reachability on-machine,
+ * before committing the pairing.
+ */
+
+export interface RelayTestResult {
+  url: string
+  ok: boolean
+  /** Round-trip time to open (ms), when reachable. */
+  ms?: number
+  /** True when the relay answered our REQ — i.e. it's actually a nostr relay. */
+  answered?: boolean
+  error?: string
+}
+
+/** Open a WebSocket to `url` and report whether it connects within `timeoutMs`. */
+export function testRelay(url: string, timeoutMs = 6000): Promise<RelayTestResult> {
+  return new Promise((resolve) => {
+    const start = Date.now()
+    let ws: WebSocket | null = null
+    let settled = false
+
+    const finish = (r: Omit<RelayTestResult, 'url'>): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try {
+        ws?.close()
+      } catch {
+        /* already closing */
+      }
+      resolve({ url, ...r })
+    }
+
+    const timer = setTimeout(
+      () => finish({ ok: false, error: `timed out after ${timeoutMs}ms` }),
+      timeoutMs,
+    )
+
+    try {
+      ws = new WebSocket(url)
+    } catch (e) {
+      finish({ ok: false, error: e instanceof Error ? e.message : 'invalid relay URL' })
+      return
+    }
+
+    ws.onopen = () => {
+      // Connected. Probe it as a nostr relay; a genuine relay replies (EOSE /
+      // notice). If it stays silent we still count the open as reachable.
+      try {
+        ws?.send(JSON.stringify(['REQ', 'bitspire-relay-test', { limit: 0 }]))
+      } catch {
+        /* send failed, but the socket opened → still reachable */
+      }
+      const graceMs = Math.min(600, timeoutMs)
+      setTimeout(() => finish({ ok: true, ms: Date.now() - start, answered: false }), graceMs)
+    }
+    ws.onmessage = () => finish({ ok: true, ms: Date.now() - start, answered: true })
+    ws.onerror = () =>
+      finish({ ok: false, error: 'connection failed (unreachable or not a relay)' })
+  })
+}

From eaa7cbe33c4c12b368791934630ec481650e828e Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 00:29:10 +0200
Subject: [PATCH 39/82] fix(machine): don't inject a localhost relay default in
 get-config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Electron main's get-config returned relayUrl = VITE_RELAY_URL ||
'ws://localhost:7777'. On an unprovisioned (blank-.env) machine that non-empty
localhost default reached the renderer and, via the env-first precedence, won
over the pairing seed's relay — then failed strict validation as localhost.
That defeated #70's "the seed provides the relay": the Sintra paired fine but
booted with ws://localhost:7777 instead of the seed's nostrclient endpoint.

Return '' when unset so the renderer falls through to the seed's transport
relay (its own ws://localhost:7777 dev fallback only applies when neither env
nor pairing supplies one). Mirror of the renderer default fixed in e578680.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/main.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index 516f32a..faedf2b 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -278,8 +278,11 @@ ipcMain.handle('watchdog:pong', () => {
 // pragma: allowlist secret end
 ipcMain.handle('get-config', () => {
   return {
-    // LNbits nostr-transport connection (public info only)
-    relayUrl: process.env.VITE_RELAY_URL || 'ws://localhost:7777',
+    // LNbits nostr-transport connection (public info only). Empty when
+    // unprovisioned — the renderer then falls through to the pairing seed's
+    // relay (aiolabs/bitspire#70). A non-empty default here would win via the
+    // env-first precedence and override the seed.
+    relayUrl: process.env.VITE_RELAY_URL || '',
     lnbitsServerPubkey: process.env.VITE_LNBITS_SERVER_PUBKEY || '',
     appId: process.env.VITE_APP_ID || '',
 

From 7896c122dae1c97c92ae826a6fead669b3d0d12e Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 15:38:14 +0200
Subject: [PATCH 40/82] fix(deploy): relay + LNbits pubkey are seed-provided,
 not env-pinned (#70)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bitspire-env activation seeded VITE_RELAY_URL from the relayUrl option
(default wss://relay.aiolabs.dev). Because env wins over the pairing seed, every
fresh machine pinned itself to that relay — which is dead — so a scanned seed's
relay was ignored ("No connected relays"; hit live on the aio-demo USB). Default
relayUrl to "" so both relay and server pubkey come from the seed; a non-empty
option now pins a machine (an explicit override) rather than being the default.
Descriptions updated to match.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/bitspire-atm.nix | 32 +++++++++++++++++---------------
 flake.nix                     |  9 +++++----
 2 files changed, 22 insertions(+), 19 deletions(-)

diff --git a/deploy/nixos/bitspire-atm.nix b/deploy/nixos/bitspire-atm.nix
index 43f4d3c..a46e9b4 100644
--- a/deploy/nixos/bitspire-atm.nix
+++ b/deploy/nixos/bitspire-atm.nix
@@ -20,18 +20,17 @@ in
 
     relayUrl = mkOption {
       type = types.str;
-      default = "wss://relay.aiolabs.dev";
+      default = "";
       description = ''
-        Nostr relay URL the ATM and LNbits both subscribe to.
-
-        On a fresh-boot disk image this value is seeded into
-        `/var/lib/bitspire/.env` as `VITE_RELAY_URL=…` (see flake.nix
-        `bitspire-env` activation script). The operator can override
-        the seeded value at runtime by editing `.env` directly or by
-        re-running `deploy/nixos/provision-atm.sh` with a different
-        `RELAY_URL`. The renderer's resolution order is:
-        `/var/lib/bitspire/.env` → this NixOS default → renderer
-        hardcoded fallback (`ws://localhost:7777`).
+        Optional override for the Nostr relay the ATM uses. Empty by
+        default (aiolabs/bitspire#70): the relay comes from the pairing
+        SEED, not from provisioning — a fresh machine boots blank, scans a
+        spire-seed, and the seed's relay drives the connection. A non-empty
+        value here is seeded into `/var/lib/bitspire/.env` as
+        `VITE_RELAY_URL=…` and WINS over the seed (env-first precedence), so
+        only set it to pin a machine to a specific relay. The renderer's
+        resolution order is: `VITE_RELAY_URL` (this / .env) → the pairing
+        seed's relay → a dev-only `ws://localhost:7777` fallback.
       '';
     };
 
@@ -39,10 +38,13 @@ in
       type = types.str;
       default = "";
       description = ''
-        LNbits nostr-transport server pubkey (hex, 64 chars). Published
-        by the LNbits server on startup. Required for the ATM to talk
-        to its wallet. Provisioned by provision-atm.sh; can be left
-        empty on disk-image builds.
+        Optional override for the LNbits nostr-transport server pubkey
+        (hex, 64 chars). Empty by default (aiolabs/bitspire#70): the
+        pubkey comes from the pairing SEED (the seed's `lnbits_npub`), so
+        a seed-paired machine needs nothing here. A non-empty value is
+        seeded into `.env` as `VITE_LNBITS_SERVER_PUBKEY=…` and WINS over
+        the seed (env-first precedence) — set it only to pin a machine to
+        a specific server. Mirrors `relayUrl`.
       '';
     };
 
diff --git a/flake.nix b/flake.nix
index 3a678da..c717719 100644
--- a/flake.nix
+++ b/flake.nix
@@ -191,10 +191,11 @@
               # boots cleanly into the "needs provisioning" state; provision-
               # atm.sh SSHes in and overwrites with real values.
               #
-              # VITE_RELAY_URL seeds from `config.services.bitspire.relayUrl`
-              # so the NixOS module's `relayUrl` option becomes the default
-              # without losing the operator's ability to override via .env
-              # (edit the file or re-run provision-atm.sh).
+              # VITE_RELAY_URL + VITE_LNBITS_SERVER_PUBKEY seed EMPTY by default
+              # (relayUrl defaults to ""), so the pairing seed drives the relay
+              # + server pubkey (aiolabs/bitspire#70). A non-empty `relayUrl`
+              # option pins a machine to a specific relay (seeded here, wins over
+              # the seed via env-first precedence) — otherwise leave it blank.
               system.activationScripts.bitspire-env = ''
                 mkdir -p /var/lib/bitspire
                 if [ ! -f /var/lib/bitspire/.env ]; then

From 20dbc8ca80cd20b630d5717ec3541f2cab8d4054 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 15:38:14 +0200
Subject: [PATCH 41/82] fix(deploy): provision-atm.sh writes relay/pubkey only
 on explicit override (#70)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The script unconditionally wrote VITE_RELAY_URL + VITE_LNBITS_SERVER_PUBKEY (and
hard-exited if it couldn't scrape the pubkey), env-pinning every provisioned
machine and defeating the seed — the same bug as the activation default. Make it
seed-first: with a SPIRE_SEED, relay + pubkey come from the seed and are written
only when the operator explicitly passes RELAY_URL / LNBITS_SERVER_PUBKEY as a
deliberate pin. The no-seed dev-nsec path still scrapes/defaults them. Also drops
the unused VITE_LNBITS_HTTP_URL line.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/provision-atm.sh | 100 +++++++++++++++++++---------------
 1 file changed, 57 insertions(+), 43 deletions(-)

diff --git a/deploy/nixos/provision-atm.sh b/deploy/nixos/provision-atm.sh
index 74f4229..31e08e8 100755
--- a/deploy/nixos/provision-atm.sh
+++ b/deploy/nixos/provision-atm.sh
@@ -4,19 +4,22 @@
 # kind-21000 NIP-44 v2 events on a relay — there is no out-of-band token,
 # the ATM's nostr private key IS the credential.  # pragma: allowlist secret
 #
-# Required environment variables (or edit defaults below):
-#   LNBITS_SERVER_PUBKEY   Hex pubkey published by the LNbits server at startup.
-#                          From the LNbits compose:
-#                            docker logs lnbits | grep 'nostr_transport pubkey'
-#   LNBITS_HTTP_URL        Origin LNbits is reachable at over HTTP, used only
-#                          to compose the LNURL-withdraw callback URL that
-#                          customer wallets dereference. Default: http://10.0.2.2:5000
-#   RELAY_URL              Nostr relay LNbits + the bunker subscribe on.
-#                          Default: ws://$HOST_IP:5001/nostrrelay/test (LNbits
-#                          bundled nostrrelay). Override for a separate relay.
-#   SPIRE_SEED             The spire pairing seed (`spire-seed:v1:<base64url>`)
-#                          minted by spirekeeper. THIS is the production
-#                          identity under the NIP-46 bunker (aiolabs/bitspire#52).
+# The primary input is SPIRE_SEED — the pairing seed carries the relay, the
+# LNbits server pubkey AND the signing identity, so a seed-provisioned machine
+# needs nothing else (aiolabs/bitspire#70).
+#
+# Environment variables:
+#   SPIRE_SEED             RECOMMENDED. The spire pairing seed
+#                          (`spire-seed:v1:<base64url>`) minted by spirekeeper.
+#                          Carries relay + LNbits server pubkey + the production
+#                          identity under the NIP-46 bunker (aiolabs/bitspire#52 / #70).
+#   RELAY_URL              OPTIONAL override — pins VITE_RELAY_URL and WINS over the
+#                          seed's relay (env-first precedence). Leave unset to let the
+#                          seed drive it. Required only on the no-seed dev path
+#                          (default there: ws://$HOST_IP:5001/nostrrelay/test).
+#   LNBITS_SERVER_PUBKEY   OPTIONAL override (hex). Leave unset with a seed. On the
+#                          no-seed dev path it's scraped from
+#                          `docker logs lnbits | grep 'nostr_transport pubkey'`.
 #   ATM_PRIVATE_KEY        DEV-ONLY 32-byte hex nsec fallback, used only when
 #                          SPIRE_SEED is unset (no bunker). Generated if unset
 #                          AND no SPIRE_SEED is provided.
@@ -61,40 +64,51 @@ else
     echo "--- LAN ATM: using $HOST_IP as dev machine address ---"
 fi
 
-# Step 2: Resolve the LNbits server pubkey. Prefer the env override; else
-# fall back to scraping the local docker compose stack.
-if [ -z "${LNBITS_SERVER_PUBKEY:-}" ]; then
-    echo ""
-    echo "--- Step 1: Extracting LNbits nostr-transport pubkey from docker logs ---"
-    LNBITS_SERVER_PUBKEY=$(docker logs lnbits 2>&1 \
-        | grep -oP 'nostr_transport pubkey:?\s*\K[a-f0-9]{64}' \
-        | tail -1 || true)
-    if [ -z "$LNBITS_SERVER_PUBKEY" ]; then
-        echo "ERROR: Could not extract LNbits pubkey. Set LNBITS_SERVER_PUBKEY explicitly"
-        echo "or start the LNbits stack first (docker compose -f docker/docker-compose.dev.yml up lnbits)."
-        exit 1
-    fi
-fi
-echo "LNbits server pubkey: ${LNBITS_SERVER_PUBKEY:0:16}..."
+# Steps 2-4: transport config (relay + LNbits server pubkey) + signing identity.
+#
+# Under aiolabs/bitspire#70 the relay + server pubkey come from the pairing SEED,
+# so a seed-provisioned machine needs NEITHER in .env. We only pin them when the
+# operator EXPLICITLY passes RELAY_URL / LNBITS_SERVER_PUBKEY (a deliberate
+# override that WINS over the seed via env-first precedence), or when there is no
+# seed (the dev-nsec fallback has nothing else to supply them, so we scrape/default).
+TRANSPORT_LINES=""
 
-# Step 3: Pin LNbits HTTP origin.
-LNBITS_HTTP_URL="${LNBITS_HTTP_URL:-http://$HOST_IP:5000}"
-
-# Step 4: Relay URL. Defaults to the LNbits bundled nostrrelay.
-RELAY_URL="${RELAY_URL:-ws://$HOST_IP:5001/nostrrelay/test}"
-
-# Step 5: Signing identity. Prefer the spire pairing seed (bunker). Only fall
-# back to a generated dev nsec when no seed is supplied.
 if [ -n "${SPIRE_SEED:-}" ]; then
-    echo ""
-    echo "--- Using spire pairing seed (bunker-backed identity) ---"
     case "$SPIRE_SEED" in
         spire-seed:v1:*) : ;;
         *) echo "ERROR: SPIRE_SEED must start with 'spire-seed:v1:'"; exit 1 ;;
     esac
+    echo ""
+    echo "--- Spire pairing seed: relay + LNbits pubkey come from the seed ---"
+    if [ -n "${RELAY_URL:-}" ]; then
+        echo "    (pinning VITE_RELAY_URL=$RELAY_URL — overrides the seed's relay)"
+        TRANSPORT_LINES="VITE_RELAY_URL=$RELAY_URL"
+    fi
+    if [ -n "${LNBITS_SERVER_PUBKEY:-}" ]; then
+        TRANSPORT_LINES="${TRANSPORT_LINES:+$TRANSPORT_LINES
+}VITE_LNBITS_SERVER_PUBKEY=$LNBITS_SERVER_PUBKEY"
+    fi
     IDENTITY_LINES="# Spire pairing seed — bunker-backed identity (aiolabs/bitspire#52)
 VITE_SPIRE_SEED=$SPIRE_SEED"
 else
+    # No seed → DEV-ONLY nsec fallback. Nothing else supplies the relay + pubkey,
+    # so scrape/default them.
+    if [ -z "${LNBITS_SERVER_PUBKEY:-}" ]; then
+        echo ""
+        echo "--- No seed: extracting LNbits nostr-transport pubkey from docker logs ---"
+        LNBITS_SERVER_PUBKEY=$(docker logs lnbits 2>&1 \
+            | grep -oP 'nostr_transport pubkey:?\s*\K[a-f0-9]{64}' \
+            | tail -1 || true)
+        if [ -z "$LNBITS_SERVER_PUBKEY" ]; then
+            echo "ERROR: no SPIRE_SEED, and could not extract the LNbits pubkey."
+            echo "Provide a SPIRE_SEED (recommended — the seed carries relay + pubkey),"
+            echo "or set LNBITS_SERVER_PUBKEY explicitly."
+            exit 1
+        fi
+    fi
+    RELAY_URL="${RELAY_URL:-ws://$HOST_IP:5001/nostrrelay/test}"
+    TRANSPORT_LINES="VITE_RELAY_URL=$RELAY_URL
+VITE_LNBITS_SERVER_PUBKEY=$LNBITS_SERVER_PUBKEY"
     if [ -z "${ATM_PRIVATE_KEY:-}" ]; then
         ATM_PRIVATE_KEY=$(openssl rand -hex 32)
         echo ""
@@ -110,10 +124,10 @@ echo "--- Step 2: Writing .env to ATM ---"
 ENV_CONTENT="# bitSpire Configuration
 # Auto-generated by provision-atm.sh on $(date -Iseconds)
 
-# LNbits nostr-transport connection
-VITE_RELAY_URL=$RELAY_URL
-VITE_LNBITS_SERVER_PUBKEY=$LNBITS_SERVER_PUBKEY
-VITE_LNBITS_HTTP_URL=$LNBITS_HTTP_URL
+# LNbits nostr-transport. Relay + server pubkey come from the pairing seed
+# (aiolabs/bitspire#70); present below only as an explicit override or the
+# no-seed dev fallback.
+$TRANSPORT_LINES
 
 $IDENTITY_LINES
 
@@ -132,6 +146,6 @@ echo ""
 echo "=== ATM provisioned successfully ==="
 echo ""
 echo "Credentials written to /var/lib/bitspire/.env"
-echo "ATM service restarted. It should connect to LNbits via relay $RELAY_URL."
+echo "ATM service restarted. Relay: ${RELAY_URL:-from the pairing seed}."
 echo ""
 echo "To check status:  ssh -p $ATM_SSH_PORT $ATM_USER@$ATM_HOST 'sudo journalctl -u bitspire -f'"

From ce87f85a7387378c7d120c385c05794dc66a3d9f Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 15:38:14 +0200
Subject: [PATCH 42/82] fix(machine): maintenance beacon uses the pairing
 seed's relay (#70)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The maintenance-mode beacon resolved the relay from env only (config.relayUrl ||
VITE_RELAY_URL), so on a blank-.env seed-driven machine it was undefined and the
beacon was skipped — a paired ATM in maintenance never broadcast. It already
resolves the signer (which carries the transport); fall back to
resolved.transport.relays[0], mirroring lightning.ts's env → pairing precedence.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/App.vue | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/apps/machine/src/App.vue b/apps/machine/src/App.vue
index c7e1537..2b89eb7 100644
--- a/apps/machine/src/App.vue
+++ b/apps/machine/src/App.vue
@@ -103,11 +103,16 @@ onMounted(async () => {
     try {
       const { NostrClient, createSignedEvent } = await import('@bitSpire/nostr-client')
       const { resolveSigner } = await import('@/services/signer-resolver')
-      const relayUrl = config?.relayUrl || import.meta.env.VITE_RELAY_URL
       // Best-effort: resolve a signer (bunker resume / pairing, or dev nsec).
       // If the ATM isn't paired yet, skip the beacon rather than fail the screen.
       const resolved = await resolveSigner({ allowEphemeral: true }).catch(() => null)
       const signer = resolved?.signer ?? null
+      // Same env → pairing-seed precedence as lightning.ts: on a blank-.env
+      // seed-driven machine the relay comes from the pairing transport, not env.
+      const relayUrl =
+        config?.relayUrl ||
+        import.meta.env.VITE_RELAY_URL ||
+        resolved?.transport?.relays?.[0]
       if (signer && relayUrl) {
         const client = new NostrClient({ relays: [{ url: relayUrl }], signer })
         await client.connect()

From e99628ef845cbda1e3a5bae089d47499259ea930 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 15:38:14 +0200
Subject: [PATCH 43/82] docs: relay + LNbits pubkey are seed-provided, not
 required (#70)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Env table (CLAUDE.md), .env.example, and the deploy README still framed
VITE_RELAY_URL / VITE_LNBITS_SERVER_PUBKEY as required/provisioned; they now come
from the pairing seed and are env overrides only. Also refresh the slimmed seed
shape, the relayUrl/pubkey module examples ("" not wss://relay.aiolabs.dev), and
the stale lamassu-next autoUpgrade flake URL (→ aiolabs/bitspire).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CLAUDE.md                 |  6 +++---
 apps/machine/.env.example | 10 +++++++---
 deploy/nixos/README.md    |  6 +++---
 3 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a1a5691..1a068ad 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -82,9 +82,9 @@ Renderer reads (Electron IPC or Vite `import.meta.env`):
 
 | Var | Required | Notes |
 |---|---|---|
-| `VITE_RELAY_URL` | yes | `ws://...` of the relay both ATM and LNbits subscribe to. Dev: `ws://localhost:5001/nostrrelay/test` (LNbits's bundled `nostrrelay` extension — no separate strfry container) |
-| `VITE_LNBITS_SERVER_PUBKEY` | yes | 64-char hex pubkey LNbits prints on startup (`docker logs lnbits \| grep 'Public key (share this)'`) |
-| `VITE_SPIRE_SEED` | yes (prod) | Spire pairing seed (`spire-seed:v1:<base64url>`) from spirekeeper. Carries a one-shot NIP-46 connect token + the spire signing pubkey + bunker URL. First boot redeems it and persists the binding to `state.db`; later boots resume by fingerprint. A changed seed re-pairs. Provisioning it up front is optional — an unpaired machine renders an on-screen QR-pairing wizard that scans the seed off the camera (see below). See aiolabs/bitspire#52. |
+| `VITE_RELAY_URL` | no (seed-provided) | Relay both ATM and LNbits subscribe to. **Comes from the pairing seed** (aiolabs/bitspire#70); set this only as an override — it WINS over the seed via env-first precedence. Dev override: `ws://localhost:5001/nostrrelay/test` (LNbits's bundled `nostrrelay` extension — no separate strfry container) |
+| `VITE_LNBITS_SERVER_PUBKEY` | no (seed-provided) | 64-char hex transport pubkey. **Comes from the seed's `lnbits_npub`** (#70); env override only. LNbits prints it on startup (`docker logs lnbits \| grep 'Public key (share this)'`) |
+| `VITE_SPIRE_SEED` | yes (prod) | Spire pairing seed (`spire-seed:v1:<base64url>`) from spirekeeper. Carries the relay(s), the LNbits transport pubkey (`lnbits_npub`), the spire signing pubkey (`spire_npub`), and a one-shot NIP-46 connect token (#70 slimmed the shape). First boot redeems it and persists the binding to `state.db`; later boots resume by fingerprint. A changed seed re-pairs. Provisioning it up front is optional — an unpaired machine renders an on-screen QR-pairing wizard that scans the seed off the camera (see below). See aiolabs/bitspire#52. |
 | `VITE_ATM_PRIVATE_KEY` | dev only | 64-char hex raw nsec fallback for running without a bunker. Ignored when `VITE_SPIRE_SEED` or a stored binding exists. |
 | `VITE_OPERATOR_PUBKEYS` | optional | Comma-separated hex pubkeys allowed to send kind-21003 management commands |
 
diff --git a/apps/machine/.env.example b/apps/machine/.env.example
index e691e46..66541dc 100644
--- a/apps/machine/.env.example
+++ b/apps/machine/.env.example
@@ -19,11 +19,15 @@ VITE_LAMASSU_FIAT_CODE=USD
 # VITE_LAMASSU_CASSETTES='[{"denomination":20,"count":100}]'
 
 # =============================================================================
-# LNbits Connection (Required) — nostr-native-transport
+# LNbits Connection (dev override — normally seed-provided) — nostr-native-transport
 # =============================================================================
+# On a real machine the pairing SEED (VITE_SPIRE_SEED) carries the relay AND the
+# server pubkey (aiolabs/bitspire#70), so leave both blank there. Set them here
+# only for browser dev without a seed/bunker — they WIN over the seed.
 
-# Nostr relay WebSocket URL — relay LNbits is subscribed to.
-VITE_RELAY_URL=ws://localhost:7777
+# Nostr relay WebSocket URL. Dev stack uses LNbits's bundled nostrrelay:
+# VITE_RELAY_URL=ws://localhost:5001/nostrrelay/test
+VITE_RELAY_URL=
 
 # LNbits nostr-transport server pubkey (hex, 64 chars).
 # Printed by the LNbits server on startup:
diff --git a/deploy/nixos/README.md b/deploy/nixos/README.md
index af00ed6..2bfc333 100644
--- a/deploy/nixos/README.md
+++ b/deploy/nixos/README.md
@@ -187,7 +187,7 @@ The `dev`-branch `flake.nix` pins the auto-upgrade source to `?ref=dev` so any A
 ```nix
 system.autoUpgrade = {
   enable = true;
-  flake = "git+ssh://forgejo@git.atitlan.io/aiolabs/lamassu-next.git?ref=dev#${machineModel}-installed";
+  flake = "git+ssh://forgejo@git.atitlan.io/aiolabs/bitspire.git?ref=dev#${machineModel}-installed";
   dates = "04:00";
   allowReboot = false;
 };
@@ -262,8 +262,8 @@ ls -la /dev/serial/by-id/
 {
   services.bitspire = {
     enable                    = true;
-    relayUrl                  = "wss://relay.aiolabs.dev";              # ATM ↔ LNbits relay
-    lnbitsServerPubkey        = "<64-hex>";                              # LNbits transport pubkey
+    relayUrl                  = "";                                     # seed-provided (#70); set to PIN a relay
+    lnbitsServerPubkey        = "";                                     # seed-provided (#70); set to PIN a pubkey
     appDir                    = "/opt/bitspire";                         # rarely overridden — defaults via flake
     dataDir                   = "/var/lib/bitspire";                     # rarely overridden
     logLevel                  = "info";                                  # error | warn | info | debug

From 7abc2e3305009965c5c81314eb5653ed748b11b6 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 18:33:31 +0200
Subject: [PATCH 44/82] refactor(machine): remove dead Lightning.Pub nprofile
 UI (post-3d cutover)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The LP backend was deleted on dev, so VITE_LIGHTNING_PUB_PUBKEY /
config.lightningPubPubkey are never set — the "add this ATM's node to your
wallet" nprofile QR (IdleView dev button + overlay, SupportView ShockWallet
card + deep-link) rendered empty, and the LP fields in RuntimeConfig
(lightningPubPubkey/lightningPubApiUrl/extensionApiUrl) were never populated.
Remove them. The concept has no clean LNbits analog (the ATM is a cash↔LN
gateway, not a node customers peer with) — tracked as a fresh feature request
on lnbits. ShockWallet stays listed as a downloadable wallet (plain URL).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/preload.ts       |  4 --
 apps/machine/src/types/electron.d.ts   |  4 --
 apps/machine/src/views/IdleView.vue    | 43 +-------------
 apps/machine/src/views/SupportView.vue | 80 +-------------------------
 4 files changed, 3 insertions(+), 128 deletions(-)

diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index 5483e46..ba53b62 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -17,10 +17,6 @@ export interface RuntimeConfig {
   relayUrl: string
   /** LNbits nostr-transport server pubkey (hex, 64 chars). */
   lnbitsServerPubkey: string
-  /** Legacy LP fields — retained until 3d removes the LP backend. Optional. */
-  lightningPubPubkey?: string
-  lightningPubApiUrl?: string
-  extensionApiUrl?: string
   appId: string
   machineModel: string
   fiatCode: string
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index 3b17d0e..bca4d0f 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -6,10 +6,6 @@ export interface RuntimeConfig {
   relayUrl: string
   /** LNbits nostr-transport server pubkey (hex, 64 chars). */
   lnbitsServerPubkey: string
-  /** Legacy LP fields — retained until 3d removes the LP backend. Optional. */
-  lightningPubPubkey?: string
-  lightningPubApiUrl?: string
-  extensionApiUrl?: string
   appId: string
   machineModel: string
   fiatCode: string
diff --git a/apps/machine/src/views/IdleView.vue b/apps/machine/src/views/IdleView.vue
index f05d9a2..3465cc1 100644
--- a/apps/machine/src/views/IdleView.vue
+++ b/apps/machine/src/views/IdleView.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
-import { ref, computed, watch } from 'vue'
+import { ref, watch } from 'vue'
 import { useRouter } from 'vue-router'
-import { nip19 } from 'nostr-tools'
 import { useAtmStore } from '@/stores/atm'
 import { useBranding } from '@/composables/useBranding'
 import { initialContext } from '@bitSpire/state-machine'
@@ -15,18 +14,8 @@ const atmStore = useAtmStore()
 const { logoUrl, title: brandTitle } = useBranding()
 const lndconnectUrl = import.meta.env.VITE_LNDCONNECT_URL || ''
 const showZeusQR = ref(false)
-const showLpQR = ref(false)
 const copied = ref(false)
 
-// Build nprofile for Lightning.Pub (pubkey + relay hint)
-const lpNprofile = computed(() => {
-  const pubkey = import.meta.env.VITE_LIGHTNING_PUB_PUBKEY
-  if (!pubkey) return ''
-  const relayUrl = import.meta.env.VITE_RELAY_URL
-  const relays = relayUrl ? [relayUrl.replace('ws://', 'wss://')] : []
-  return nip19.nprofileEncode({ pubkey, relays })
-})
-
 async function copyToClipboard(value: string) {
   try {
     await navigator.clipboard.writeText(value)
@@ -157,15 +146,6 @@ function handleCashOut() {
       >
         Zeus QR (lnd-alice)
       </Button>
-      <Button
-        v-if="lpNprofile"
-        variant="ghost"
-        size="sm"
-        class="text-xs text-muted-foreground"
-        @click="showLpQR = true"
-      >
-        Lightning.Pub nprofile
-      </Button>
     </div>
 
     <!-- Zeus QR fullscreen overlay -->
@@ -193,27 +173,6 @@ function handleCashOut() {
       </div>
     </div>
 
-    <!-- Lightning.Pub nprofile QR fullscreen overlay -->
-    <div
-      v-if="showLpQR"
-      class="fixed inset-0 z-[100] flex flex-col items-center justify-center gap-4 bg-black/90 p-4"
-      @click.self="showLpQR = false"
-    >
-      <p class="text-sm text-white/70">Lightning.Pub nprofile</p>
-      <div class="rounded-2xl">
-        <QRCode :value="lpNprofile" :size="400" />
-      </div>
-      <code class="max-w-[90vw] truncate text-xs text-white/50">{{ lpNprofile }}</code>
-      <div class="flex items-center gap-2">
-        <Button variant="outline" size="sm" class="text-white" @click="copyToClipboard(lpNprofile)">
-          {{ copied ? 'Copied!' : 'Copy' }}
-        </Button>
-        <Button variant="outline" size="sm" class="text-white" @click="showLpQR = false">
-          Close
-        </Button>
-      </div>
-    </div>
-
     <!-- Help button (top-left) -->
     <Button
       variant="outline"
diff --git a/apps/machine/src/views/SupportView.vue b/apps/machine/src/views/SupportView.vue
index 89805f3..0762219 100644
--- a/apps/machine/src/views/SupportView.vue
+++ b/apps/machine/src/views/SupportView.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import { ref, computed, onMounted, onUnmounted } from 'vue'
 import { useRouter } from 'vue-router'
-import { nip19 } from 'nostr-tools'
 import { marked } from 'marked'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent } from '@/components/ui/card'
@@ -23,35 +22,6 @@ import { QrCode, ExternalLink } from 'lucide-vue-next'
 const router = useRouter()
 const isElectron = typeof window !== 'undefined' && window.electronAPI !== undefined
 
-// Lightning.Pub config loaded at runtime from Electron main process
-const lpPubkey = ref('')
-const relayUrl = ref('')
-
-onMounted(async () => {
-  if (isElectron && window.electronAPI) {
-    const config = await window.electronAPI.getConfig()
-    lpPubkey.value = config.lightningPubPubkey || ''
-    relayUrl.value = config.relayUrl || ''
-  } else {
-    // Dev fallback: use Vite env vars
-    lpPubkey.value = import.meta.env.VITE_LIGHTNING_PUB_PUBKEY || ''
-    relayUrl.value = import.meta.env.VITE_RELAY_URL || ''
-  }
-})
-
-// Build nprofile for Lightning.Pub (pubkey + relay hint)
-const lpNprofile = computed(() => {
-  if (!lpPubkey.value) return ''
-  const relays = relayUrl.value ? [relayUrl.value.replace('ws://', 'wss://')] : []
-  return nip19.nprofileEncode({ pubkey: lpPubkey.value, relays })
-})
-
-// Deep link URL: opens ShockWallet with this ATM's Lightning.Pub pre-filled
-const shockwalletDeepLink = computed(() => {
-  if (!lpNprofile.value) return ''
-  return `https://wallet.aiolabs.dev/sources/add?nprofile=${encodeURIComponent(lpNprofile.value)}`
-})
-
 interface SupportPage {
   id: string
   title: string
@@ -74,17 +44,11 @@ const defaultPages: SupportPage[] = [
 | Blink | No | Partial | Yes | Yes | https://www.blink.sv |
 | Zeus | Yes | Yes | Yes | Yes | https://zeusln.com |
 | Breez | Yes | Yes | Yes | Yes | https://breez.technology |
-| ShockWallet | No | Yes | Yes | Yes | [shockwallet-deep-link] |
+| ShockWallet | No | Yes | Yes | Yes | https://shockwallet.app |
 
 Tap a QR icon to scan and download a wallet.
 
-**Non-custodial** means you hold your own keys and have full control of your Bitcoin. **KYC-free** means no identity verification is required. Partial (~) means limits apply without verification.
-
-## Using ShockWallet with this ATM
-
-Scan the QR code below to add this ATM's Lightning node to your ShockWallet. This lets you send and receive sats directly through the ATM's payment system.
-
-[lp-nprofile]`,
+**Non-custodial** means you hold your own keys and have full control of your Bitcoin. **KYC-free** means no identity verification is required. Partial (~) means limits apply without verification.`,
   },
   {
     id: 'faq',
@@ -153,7 +117,6 @@ type Segment =
   | { type: 'qr'; content: string }
   | { type: 'table'; table: ParsedTable }
   | { type: 'qr-placeholder' }
-  | { type: 'lp-nprofile' }
 
 /** Parse markdown table into structured data */
 function parseMarkdownTable(tableLines: string[]): ParsedTable | null {
@@ -176,17 +139,8 @@ function parseMarkdownTable(tableLines: string[]): ParsedTable | null {
   return { headers, rows }
 }
 
-/** Resolve dynamic placeholders in markdown content */
-function resolvePlaceholders(md: string): string {
-  return md.replace(
-    '[shockwallet-deep-link]',
-    shockwalletDeepLink.value || 'https://wallet.aiolabs.dev'
-  )
-}
-
 /** Parse content into segments: html, qr, or table */
 function parseContent(md: string): Segment[] {
-  md = resolvePlaceholders(md)
   const segments: Segment[] = []
   const lines = md.split('\n')
   let htmlBlock = ''
@@ -235,9 +189,6 @@ function parseContent(md: string): Segment[] {
       } else if (trimmed === '[operator-qr-placeholder]') {
         flushHtml()
         segments.push({ type: 'qr-placeholder' })
-      } else if (trimmed === '[lp-nprofile]') {
-        flushHtml()
-        segments.push({ type: 'lp-nprofile' })
       } else {
         htmlBlock += line + '\n'
       }
@@ -375,33 +326,6 @@ onUnmounted(() => {
             </CardContent>
           </Card>
 
-          <!-- Lightning.Pub nprofile QR (scannable by ShockWallet) -->
-          <Card v-else-if="seg.type === 'lp-nprofile'" class="my-6 mx-auto max-w-xs">
-            <CardContent class="flex flex-col items-center gap-3 p-6">
-              <template v-if="lpNprofile">
-                <div class="rounded-xl bg-white p-3">
-                  <QrcodeVue
-                    :value="lpNprofile"
-                    :size="180"
-                    level="L"
-                    render-as="svg"
-                    background="#ffffff"
-                    foreground="#000000"
-                  />
-                </div>
-                <span class="text-xs text-muted-foreground text-center px-2">
-                  Scan with ShockWallet to connect
-                </span>
-              </template>
-              <template v-else>
-                <QrCode class="h-16 w-16 text-muted-foreground/30" />
-                <span class="text-sm text-muted-foreground/50 text-center">
-                  Lightning.Pub not configured
-                </span>
-              </template>
-            </CardContent>
-          </Card>
-
           <!-- Table with inline QR codes -->
           <div v-else-if="seg.type === 'table'" class="mb-8">
             <Table class="text-sm sm:text-base lg:text-xl w-full">

From 06f73b2d7626beda9f2438e45363fc37be53e2f8 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 18:33:31 +0200
Subject: [PATCH 45/82] fix(machine): point DEV_DEFAULT_RELAY at the real dev
 relay
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The last-ditch dev fallback (used only when neither env nor the pairing seed
supplies a relay) was ws://localhost:7777 — a standalone strfry we no longer
run. Align it to the dev stack's LNbits bundled nostrrelay
(ws://localhost:5001/nostrrelay/test) so the fallback points at a relay that
actually exists.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/services/lightning.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index 039cf01..1f5f6fc 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -100,8 +100,9 @@ async function loadLightningConfig(): Promise<LightningConfig> {
 // Config is loaded async now - will be set in initializeLightningServices
 let CONFIG: LightningConfig
 
-/** Dev-only relay used when neither env nor the pairing supplies one. */
-const DEV_DEFAULT_RELAY = 'ws://localhost:7777'
+/** Dev-only relay used when neither env nor the pairing supplies one. Matches
+ * the dev stack — LNbits's bundled nostrrelay (no separate strfry container). */
+const DEV_DEFAULT_RELAY = 'ws://localhost:5001/nostrrelay/test'
 
 /** Safety timeout in ms (15 minutes) — absolute maximum LNURL session lifetime.
  * Sessions are normally cleaned up by the state machine on idle transition.

From 7bc718f9e3104e7f21015ee746774e3056dc1cab Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 19:28:20 +0200
Subject: [PATCH 46/82] =?UTF-8?q?fix(machine):=20rotate=20pairing=20camera?=
 =?UTF-8?q?=20preview=2090=C2=B0=20CCW=20for=20the=20Sintra=20mount?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Sintra's camera is physically mounted rotated, so the wizard's viewfinder
showed a sideways image — hard to aim at the spire-seed QR. Rotate the preview
90° CCW (-rotate-90). Preview-only: qr-source decodes the raw frame (CSS
transforms don't touch canvas drawImage) and QR decoding is rotation-invariant,
so scanning is unaffected. The viewfinder is a square, overflow-hidden container,
so the rotated square stays in the box.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/components/PairingWizard.vue | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/apps/machine/src/components/PairingWizard.vue b/apps/machine/src/components/PairingWizard.vue
index fb343e1..7057730 100644
--- a/apps/machine/src/components/PairingWizard.vue
+++ b/apps/machine/src/components/PairingWizard.vue
@@ -157,7 +157,17 @@ onUnmounted(teardown)
       class="relative overflow-hidden rounded-2xl border-4 border-primary/40 bg-black"
       style="width: min(80vw, 28rem); aspect-ratio: 1 / 1"
     >
-      <video ref="videoEl" class="h-full w-full object-cover" muted autoplay playsinline></video>
+      <!-- The Sintra's camera is mounted rotated, so rotate the preview 90° CCW
+           for an upright image. Preview-only: qr-source decodes the raw (un-
+           rotated) frame and QR decoding is rotation-invariant. The container is
+           square + overflow-hidden, so the rotated square stays in the box. -->
+      <video
+        ref="videoEl"
+        class="h-full w-full -rotate-90 object-cover"
+        muted
+        autoplay
+        playsinline
+      ></video>
       <!-- Reticle -->
       <div class="pointer-events-none absolute inset-6 rounded-xl border-2 border-white/70"></div>
     </div>

From 42c0d3e9cae98e57ddc9206f665a7d0fd42b9c3e Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 21:13:40 +0200
Subject: [PATCH 47/82] =?UTF-8?q?chore(deploy):=20seed=20a=20minimal=20.en?=
 =?UTF-8?q?v=20=E2=80=94=20stop=20pre-seeding=20maskable=20vars=20(#70)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bitspire-env activation seeds .env only when ABSENT (never refreshes on
redeploy), and env WINS over the pairing seed — so any value written at first
boot is frozen for the disk's life and silently masks the seed's source. That's
how a dead relay.aiolabs.dev and a provisioned VITE_OPERATOR_PUBKEYS made stale
installs "work" while a fresh machine broke.

Seed ONLY image-baked, non-maskable values (model, fiat, ELECTRON_FORCE_PROD,
DISPLAY, empty VITE_SPIRE_SEED placeholder). Relay + server pubkey come from the
seed; operator pubkey + fee config come from LNbits over the transport — so those
keys are no longer pre-seeded at all. VITE_RELAY_URL / VITE_LNBITS_SERVER_PUBKEY
are emitted only when the operator deliberately pins them via the Nix options (an
explicit override). Also drops the inert RELAY_URL/LNBITS_SERVER_PUBKEY lines from
/etc/bitspire/config.env (never loaded — EnvironmentFile is forced to .env).

Verified: built sintra-installed .env template is 5 lines, 0 maskable vars.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/bitspire-atm.nix | 11 +++++++----
 deploy/nixos/live.nix         | 17 ++++++++---------
 flake.nix                     | 36 +++++++++++++++++++----------------
 3 files changed, 35 insertions(+), 29 deletions(-)

diff --git a/deploy/nixos/bitspire-atm.nix b/deploy/nixos/bitspire-atm.nix
index a46e9b4..fffb92e 100644
--- a/deploy/nixos/bitspire-atm.nix
+++ b/deploy/nixos/bitspire-atm.nix
@@ -143,11 +143,14 @@ in
       "d ${cfg.dataDir}/branding 0755 bitspire bitspire -"
     ];
 
-    # Environment file for ATM configuration
+    # Descriptive-only ATM info at /etc/bitspire/config.env. NOTE: this is NOT
+    # the runtime environment — the systemd service's EnvironmentFile is
+    # mkForce'd to /var/lib/bitspire/.env, and the renderer reads only VITE_*
+    # vars. Relay + server pubkey are deliberately omitted here: they come from
+    # the pairing seed (aiolabs/bitspire#70), and duplicating them as non-VITE
+    # RELAY_URL/LNBITS_SERVER_PUBKEY only invited "looks authoritative" confusion.
     environment.etc."bitspire/config.env".text = ''
-      # bitSpire ATM Configuration
-      RELAY_URL=${cfg.relayUrl}
-      LNBITS_SERVER_PUBKEY=${cfg.lnbitsServerPubkey}
+      # bitSpire ATM Configuration (descriptive; not the runtime env)
       LOG_LEVEL=${cfg.logLevel}
       DATA_DIR=${cfg.dataDir}
 
diff --git a/deploy/nixos/live.nix b/deploy/nixos/live.nix
index 44255e9..7c5682f 100644
--- a/deploy/nixos/live.nix
+++ b/deploy/nixos/live.nix
@@ -21,18 +21,17 @@ let
     batm3 = "USD";
   }.${machineModel} or "USD";
 
-  # .env template — runtime secrets are provisioned later via provision-atm.sh.
-  # Only non-secret defaults and display vars go here. VITE_SPIRE_SEED (the
-  # NIP-46 bunker pairing seed) is written at provision time; the dev-only
-  # VITE_ATM_PRIVATE_KEY fallback is omitted here on purpose.
+  # Minimal .env template (aiolabs/bitspire#70 remnant hygiene). Seed ONLY
+  # image-baked, non-maskable values. Relay + server pubkey come from the pairing
+  # SEED, operator pubkey + fee config come from LNbits over the transport — so we
+  # deliberately do NOT pre-seed those keys (a present-but-empty VITE_RELAY_URL /
+  # VITE_LNBITS_SERVER_PUBKEY / VITE_OPERATOR_PUBKEYS would win over the seed and
+  # mask its source). VITE_SPIRE_SEED is written by the wizard / provision-atm.sh;
+  # the dev-only VITE_ATM_PRIVATE_KEY fallback is omitted on purpose.
   envTemplate = pkgs.writeText "bitspire-env" ''
-    VITE_RELAY_URL=
-    VITE_LNBITS_SERVER_PUBKEY=
-    VITE_SPIRE_SEED=
-    VITE_APP_ID=
-    VITE_OPERATOR_PUBKEYS=
     VITE_LAMASSU_MACHINE_MODEL=${machineModel}
     VITE_LAMASSU_FIAT_CODE=${fiatCodeForModel}
+    VITE_SPIRE_SEED=
     ELECTRON_FORCE_PROD=1
     DISPLAY=:0
   '';
diff --git a/flake.nix b/flake.nix
index c717719..63296c0 100644
--- a/flake.nix
+++ b/flake.nix
@@ -186,30 +186,34 @@
                 allowReboot = false;
               };
 
-              # Env template — runtime secrets provisioned via provision-atm.sh.
-              # Identity fields are intentionally empty so a fresh disk image
-              # boots cleanly into the "needs provisioning" state; provision-
-              # atm.sh SSHes in and overwrites with real values.
+              # Minimal env template (aiolabs/bitspire#70 remnant hygiene).
+              # Seed ONLY image-baked, non-maskable values. Everything else the
+              # ATM needs comes from the pairing SEED (relay, lnbits_npub, bunker)
+              # or from LNbits over the transport (operator pubkey, fee config) —
+              # so we must NOT pre-seed those keys. A present-but-empty
+              # VITE_RELAY_URL / VITE_LNBITS_SERVER_PUBKEY / VITE_OPERATOR_PUBKEYS
+              # is a masking hazard: env WINS over the seed, and this activation
+              # only writes when .env is ABSENT, so any value written at first
+              # boot is frozen for the life of the disk. Leaving the keys out
+              # entirely lets the seed/transport be the sole source.
               #
-              # VITE_RELAY_URL + VITE_LNBITS_SERVER_PUBKEY seed EMPTY by default
-              # (relayUrl defaults to ""), so the pairing seed drives the relay
-              # + server pubkey (aiolabs/bitspire#70). A non-empty `relayUrl`
-              # option pins a machine to a specific relay (seeded here, wins over
-              # the seed via env-first precedence) — otherwise leave it blank.
+              # VITE_RELAY_URL / VITE_LNBITS_SERVER_PUBKEY are emitted ONLY when
+              # the operator deliberately pins them via the Nix options (non-empty
+              # default ""), which is an explicit override that wins over the seed.
               system.activationScripts.bitspire-env = ''
                 mkdir -p /var/lib/bitspire
                 if [ ! -f /var/lib/bitspire/.env ]; then
-                  cp ${pkgs.writeText "bitspire-env-default" ''
-                    VITE_RELAY_URL=${config.services.bitspire.relayUrl}
-                    VITE_LNBITS_SERVER_PUBKEY=
-                    VITE_SPIRE_SEED=
-                    VITE_APP_ID=
-                    VITE_OPERATOR_PUBKEYS=
+                  cp ${pkgs.writeText "bitspire-env-default" (''
                     VITE_LAMASSU_MACHINE_MODEL=${machineModel}
                     VITE_LAMASSU_FIAT_CODE=${fiatCode}
+                    VITE_SPIRE_SEED=
                     ELECTRON_FORCE_PROD=1
                     DISPLAY=:0
-                  ''} /var/lib/bitspire/.env
+                  '' + pkgs.lib.optionalString (config.services.bitspire.relayUrl != "") ''
+                    VITE_RELAY_URL=${config.services.bitspire.relayUrl}
+                  '' + pkgs.lib.optionalString (config.services.bitspire.lnbitsServerPubkey != "") ''
+                    VITE_LNBITS_SERVER_PUBKEY=${config.services.bitspire.lnbitsServerPubkey}
+                  '')} /var/lib/bitspire/.env
                   chmod 600 /var/lib/bitspire/.env
                   chown bitspire:bitspire /var/lib/bitspire/.env
                 fi

From 78592d89f7262aeb437a594ce47868019fd23977 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 21:13:40 +0200
Subject: [PATCH 48/82] fix(machine): re-pair wipes the prior operator's config
 + watermarks (#70)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A new-seed re-pair UPSERTed the bunker binding but left fee_config, cassettes,
and the created_at replay watermarks intact. The watermarks are the trap: a new
backend whose first config event has a lower created_at than the old operator's
last event is silently dropped as a replay, so re-pairing a long-lived install
to a fresh backend appears to pair but never picks up new config.

Add resetForRepair() (main-process state-store): in one transaction it clears
fee_config and resets both replay watermarks to 0. Wired function → IPC
(state:reset-for-repair) → preload → renderer, and called from the re-pair branch
in signer-resolver, gated on an existing binding (re-pair only; a first pair has
nothing to reset). Deliberately preserves cassettes/cashbox/transactions — those
track PHYSICAL cash that survives an operator handover; a full wipe is the
factory-reset path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/main.ts                |  4 +++
 apps/machine/electron/preload.ts             |  2 ++
 apps/machine/electron/state-store.ts         | 26 ++++++++++++++++++++
 apps/machine/src/services/signer-resolver.ts |  9 +++++++
 apps/machine/src/types/electron.d.ts         |  1 +
 5 files changed, 42 insertions(+)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index faedf2b..9107951 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -27,6 +27,7 @@ import {
   getBootstrapPublishedAt,
   markBootstrapPublished,
   resetBootstrapGate,
+  resetForRepair,
   applyOperatorCassettesConfig,
   getFeeConfig,
   getLastKnownFeeConfigCreatedAt,
@@ -355,6 +356,9 @@ ipcMain.handle('state:clear-bunker-binding', (): void => {
 ipcMain.handle('state:reset-bootstrap-gate', (): void => {
   resetBootstrapGate()
 })
+ipcMain.handle('state:reset-for-repair', (): void => {
+  resetForRepair()
+})
 
 // QR-pairing wizard (aiolabs/bitspire#52): an unpaired machine scans a
 // spire-seed off its camera, and we persist it as VITE_SPIRE_SEED in the
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index ba53b62..a811eab 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -118,6 +118,7 @@ contextBridge.exposeInMainWorld('electronAPI', {
     ipcRenderer.invoke('state:save-bunker-binding', binding),
   clearBunkerBinding: (): Promise<void> => ipcRenderer.invoke('state:clear-bunker-binding'),
   resetBootstrapGate: (): Promise<void> => ipcRenderer.invoke('state:reset-bootstrap-gate'),
+  resetForRepair: (): Promise<void> => ipcRenderer.invoke('state:reset-for-repair'),
 
   // QR-pairing wizard (aiolabs/bitspire#52): persist a scanned spire-seed,
   // then relaunch so the normal boot flow pairs it.
@@ -239,6 +240,7 @@ declare global {
       saveBunkerBinding: (binding: BunkerBindingRecord) => Promise<void>
       clearBunkerBinding: () => Promise<void>
       resetBootstrapGate: () => Promise<void>
+      resetForRepair: () => Promise<void>
       saveSpireSeed: (seed: string) => Promise<void>
       relaunchApp: () => Promise<void>
       applyOperatorCassettesConfig: (
diff --git a/apps/machine/electron/state-store.ts b/apps/machine/electron/state-store.ts
index 7ea3e16..a274565 100644
--- a/apps/machine/electron/state-store.ts
+++ b/apps/machine/electron/state-store.ts
@@ -540,6 +540,32 @@ export function resetBootstrapGate(): void {
   db.prepare('UPDATE meta SET value = ? WHERE key = ?').run('', 'bootstrapPublishedAt')
 }
 
+/**
+ * Wipe operator-scoped CONFIG/TRUST state on a re-pair to a new operator/backend,
+ * so stale policy from the previous pairing can't linger or silently reject the
+ * new operator's config.
+ *
+ * Clears the fee config and resets BOTH replay watermarks to 0. The watermark
+ * reset is the load-bearing part: without it, a new backend whose first config
+ * event has a lower `created_at` than the old operator's last event is silently
+ * dropped as a replay — the exact remnant trap where re-pairing a long-lived
+ * install to a fresh backend appears to "work" but never picks up new config.
+ *
+ * Deliberately does NOT touch cassettes / cashbox / transactions: those track
+ * PHYSICAL cash, which survives an operator handover. A full wipe (decommission
+ * or a truly-fresh test) is the factory-reset path, not this.
+ */
+export function resetForRepair(): void {
+  if (!db) throw new Error('Database not initialized')
+  const database = db
+  database.transaction(() => {
+    database.prepare('DELETE FROM fee_config').run()
+    const setWatermark = database.prepare('UPDATE meta SET value = ? WHERE key = ?')
+    setWatermark.run('0', 'lastKnownFeeConfigCreatedAt')
+    setWatermark.run('0', 'lastKnownConfigCreatedAt')
+  })()
+}
+
 export type OperatorCassettesPayload = {
   positions: Record<string, { denomination: number; count: number }>
 }
diff --git a/apps/machine/src/services/signer-resolver.ts b/apps/machine/src/services/signer-resolver.ts
index 2d29ab6..f830073 100644
--- a/apps/machine/src/services/signer-resolver.ts
+++ b/apps/machine/src/services/signer-resolver.ts
@@ -144,6 +144,15 @@ export async function resolveSigner(opts: ResolveSignerOptions): Promise<Resolve
       clientSecretHex: transport.secretHex,
     })
     if (isElectron && window.electronAPI) {
+      // Re-pair (a NEW seed replacing a prior binding) → wipe the previous
+      // operator's config/trust state (fee config + replay watermarks) so it
+      // can't linger or silently replay-block the new operator's config. A
+      // first pair (no prior binding) has nothing to reset. Cash accounting is
+      // preserved — see resetForRepair; a full wipe is the factory-reset path.
+      if (binding) {
+        console.log('[Signer] Re-pair (new seed fingerprint) — clearing prior operator config state')
+        await window.electronAPI.resetForRepair()
+      }
       // Persist the seed's transport config alongside the binding so a later
       // seedless resume still reaches the backend without env provisioning.
       await window.electronAPI.saveBunkerBinding({
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index bca4d0f..b018a39 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -98,6 +98,7 @@ declare global {
       saveBunkerBinding: (binding: BunkerBindingRecord) => Promise<void>
       clearBunkerBinding: () => Promise<void>
       resetBootstrapGate: () => Promise<void>
+      resetForRepair: () => Promise<void>
       saveSpireSeed: (seed: string) => Promise<void>
       relaunchApp: () => Promise<void>
       applyOperatorCassettesConfig: (

From 5cf39a05eea0b00a5f5bea5654154721dfef1b2a Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 21:13:41 +0200
Subject: [PATCH 49/82] chore(machine): log operator-pubkey provenance so the
 config gap is loud (#70)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Relay + server pubkey already log (env)/(pairing)/(default) provenance; operator
pubkeys did not. An empty operator set silently disables the fees/operator-config
services → the machine sits at "awaiting configuration" with no signal why. Log
the resolved operator pubkey(s) and their source, and flag the empty case
explicitly (pending the #70 P1 server-delivered operator pubkey).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/services/lightning.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index 1f5f6fc..6509031 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -441,6 +441,16 @@ export async function initializeLightningServices(options?: {
     CONFIG.lnbitsServerPubkey || '(not configured)',
     envPubkey ? '(env)' : transport?.lnbitsServerPubkey ? '(pairing)' : '',
   )
+  // Operator pubkey provenance. Today the ONLY source is VITE_OPERATOR_PUBKEYS
+  // (env). An empty set disables the fees/operator-config services → the machine
+  // sits at "awaiting configuration" — so log it loudly rather than fail silent.
+  // (aiolabs/bitspire#70 P1 will source this from LNbits over the transport.)
+  console.log(
+    '[Lightning] Operator pubkey(s):',
+    CONFIG.operatorPubkeys.length
+      ? CONFIG.operatorPubkeys.join(', ') + ' (env)'
+      : '(none — fee/operator config gated until a server-delivered operator pubkey; #70 P1)',
+  )
 
   // Strict mode: validate the RESOLVED config is production-ready (no
   // localhost). Values may come from env or the pairing seed (#70).

From 936fc9fb464a5b2ae54ca1e4efcb2ae90d7c6044 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 21:13:41 +0200
Subject: [PATCH 50/82] feat(deploy): add factory-reset-atm.sh for a
 truly-fresh machine (#70)

Deterministically reproduce a brand-new machine so tests aren't masked by
leftover env/db values: stops bitspire, deletes state.db (+ WAL/SHM), truncates
.env to the minimal image-baked template (preserving model + fiat), restarts.
The ATM then boots unpaired into the wizard exactly like a fresh disk image.
Confirmation-gated (FORCE=1 to skip; ATM_USER= to override the SSH user).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/factory-reset-atm.sh | 73 +++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100755 deploy/nixos/factory-reset-atm.sh

diff --git a/deploy/nixos/factory-reset-atm.sh b/deploy/nixos/factory-reset-atm.sh
new file mode 100755
index 0000000..b46e7a3
--- /dev/null
+++ b/deploy/nixos/factory-reset-atm.sh
@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Factory-reset a bitSpire ATM to a truly-fresh state — the deterministic way to
+# reproduce a brand-new machine so tests aren't masked by leftover env/db values
+# (aiolabs/bitspire#70 remnant hygiene).
+#
+# WIPES:
+#   - /var/lib/bitspire/state.db  (bunker binding, fee config, cassettes, cashbox,
+#     transactions, operator commands, replay watermarks — recreated on next boot)
+#   - /var/lib/bitspire/.env      (truncated to the minimal image-baked template:
+#     machine model + fiat + display; drops relay, server pubkey, operator pubkey
+#     and any stored spire seed)
+#
+# After this the ATM boots UNPAIRED into the pairing wizard, exactly like a fresh
+# disk image — so a scanned seed is the sole source of truth.
+#
+# Usage:
+#   bash factory-reset-atm.sh                  # SSH to localhost:2222 (QEMU)
+#   bash factory-reset-atm.sh 192.168.1.50     # a real ATM on the LAN
+#   bash factory-reset-atm.sh 192.168.1.50 22  # custom SSH port
+#   FORCE=1 bash factory-reset-atm.sh …        # skip the confirmation prompt
+#   ATM_USER=root bash factory-reset-atm.sh …  # override SSH user (default: bitspire)
+set -euo pipefail
+
+ATM_HOST="${1:-localhost}"
+ATM_SSH_PORT="${2:-2222}"
+ATM_USER="${ATM_USER:-bitspire}"
+
+echo "=== Factory-reset bitSpire ATM at $ATM_USER@$ATM_HOST:$ATM_SSH_PORT ==="
+echo "This WIPES state.db and truncates .env to the minimal template (keeps only"
+echo "machine model + fiat). ALL pairing, cash accounting, and transaction history"
+echo "on the ATM will be lost."
+if [ "${FORCE:-}" != "1" ]; then
+    read -r -p "Type 'yes' to proceed: " confirm
+    [ "$confirm" = "yes" ] || { echo "Aborted."; exit 1; }
+fi
+
+ssh -o StrictHostKeyChecking=no -p "$ATM_SSH_PORT" "$ATM_USER@$ATM_HOST" 'sudo bash -s' <<'REMOTE'
+set -euo pipefail
+ENV=/var/lib/bitspire/.env
+DB=/var/lib/bitspire/state.db
+
+# Preserve model + fiat from the existing .env (fall back to sintra/EUR).
+model=$(grep -E '^VITE_LAMASSU_MACHINE_MODEL=' "$ENV" 2>/dev/null | cut -d= -f2- || true)
+fiat=$(grep -E '^VITE_LAMASSU_FIAT_CODE=' "$ENV" 2>/dev/null | cut -d= -f2- || true)
+model=${model:-sintra}
+fiat=${fiat:-EUR}
+
+systemctl stop bitspire 2>/dev/null || true
+
+# Wipe persisted state (db + WAL/SHM sidecars).
+rm -f "$DB" "$DB-wal" "$DB-shm"
+
+# Truncate .env to the minimal image-baked template.
+cat > "$ENV" <<EOF
+VITE_LAMASSU_MACHINE_MODEL=$model
+VITE_LAMASSU_FIAT_CODE=$fiat
+VITE_SPIRE_SEED=
+ELECTRON_FORCE_PROD=1
+DISPLAY=:0
+EOF
+chmod 600 "$ENV"
+chown bitspire:bitspire "$ENV" 2>/dev/null || true
+
+systemctl start bitspire 2>/dev/null || true
+
+echo "--- .env is now (values blanked) ---"
+sed -E 's/=.*/=/' "$ENV"
+echo "--- state.db removed (recreated fresh on next boot) ---"
+REMOTE
+
+echo ""
+echo "=== ATM factory-reset. It boots UNPAIRED → the pairing wizard. ==="
+echo "Watch:  ssh -p $ATM_SSH_PORT $ATM_USER@$ATM_HOST 'sudo journalctl -u bitspire -f'"

From fdb9a507c2f2288d8dfa3f5de99bf077bb15285c Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Thu, 2 Jul 2026 22:00:49 +0200
Subject: [PATCH 51/82] feat(machine): consume get_machine_config over the
 transport (#71)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Source the operator pubkey + fee config from LNbits via the get_machine_config
kind-21000 RPC (spirekeeper#41) right after list_wallets, instead of the
operator pubkey coming only from VITE_OPERATOR_PUBKEYS (env). A seed-only
machine (blank .env) had an empty operator allowlist → the fees/operator-config
services disabled themselves → permanent "awaiting configuration". Now it pulls
its config over the already-authenticated channel and configures itself with
zero per-machine provisioning — closing bitspire#70 P1.

- LnbitsClient.getMachineConfig() → sendRpc('get_machine_config') + the
  MachineConfigResponse / FeeConfigWire types.
- lightning.ts, only when VITE_OPERATOR_PUBKEYS is empty (env override still
  wins): set CONFIG.operatorPubkeys from operator_pubkey (re-enables the
  services), and persist fee_config via the existing applyFeeConfig IPC (mapping
  snake_case → camelCase) so atm.ts's awaiting-fees gate clears immediately —
  robust to the replaceable kind-30078 not being fetchable from the relay. The
  live kind-30078 subscription still handles mid-run fee updates.
- Soft-fail: older spirekeeper (no RPC) or a transport error falls back to the
  env/kind-30078 path.

lnbits + machine typecheck clean; lnbits suite 29 pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/services/lightning.ts | 40 ++++++++++++++++++++++++++
 packages/lnbits/src/client.ts          | 12 ++++++++
 packages/lnbits/src/types.ts           | 27 +++++++++++++++++
 3 files changed, 79 insertions(+)

diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index 6509031..4eca3e2 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -505,6 +505,46 @@ export async function initializeLightningServices(options?: {
   }
   console.log('[Lightning] LNbits wallet:', lnbitsWalletId)
 
+  // #70 P1: pull operator pubkey + fee config from LNbits over the authenticated
+  // transport (spirekeeper#41 `get_machine_config`). A seed-only machine has no
+  // VITE_OPERATOR_PUBKEYS, so without this it can't trust its fee config and sits
+  // at "awaiting configuration". Only for the seed-only case — an explicit
+  // VITE_OPERATOR_PUBKEYS override keeps the env/kind-30078 path untouched.
+  // Soft-fail: an older spirekeeper (no RPC) or a transport error falls back to
+  // whatever the operator services can pull from kind-30078.
+  if (CONFIG.operatorPubkeys.length === 0) {
+    try {
+      const mc = await lnbits.getMachineConfig()
+      if (mc.operator_pubkey) {
+        CONFIG.operatorPubkeys = [mc.operator_pubkey]
+        console.log('[Lightning] Operator pubkey(s):', mc.operator_pubkey, '(server-delivered, #70 P1)')
+      }
+      if (mc.fee_config && isElectron && window.electronAPI) {
+        // Persist the server-delivered fee config so atm.ts's awaiting-fees gate
+        // (getFeeConfig) clears immediately — robust to the replaceable kind-30078
+        // event not being fetchable from the relay. The live kind-30078
+        // subscription still handles mid-run fee updates.
+        const applied = await window.electronAPI.applyFeeConfig(
+          {
+            cashInFeeFraction: mc.fee_config.cash_in_fee_fraction,
+            cashOutFeeFraction: mc.fee_config.cash_out_fee_fraction,
+            schemaVersion: mc.fee_config.schema_version,
+          },
+          mc.created_at,
+        )
+        console.log(
+          '[Lightning] Server-delivered fee config:',
+          applied.applied ? 'applied' : `skipped (${applied.reason})`,
+        )
+      }
+    } catch (e) {
+      console.warn(
+        '[Lightning] get_machine_config unavailable; falling back to env/kind-30078 for operator config:',
+        (e as Error).message,
+      )
+    }
+  }
+
   // CLINK client — kept in tree but not actively wired into LNbits flows.
   // operatorPubkey is the operator allowlist for kind-21003 management
   // commands; it has no Lightning.Pub dependency.
diff --git a/packages/lnbits/src/client.ts b/packages/lnbits/src/client.ts
index f75db3f..cb3645d 100644
--- a/packages/lnbits/src/client.ts
+++ b/packages/lnbits/src/client.ts
@@ -37,6 +37,7 @@ import type {
   CreateInvoiceBody,
   PayInvoiceBody,
   WalletInfo,
+  MachineConfigResponse,
   SubscribePaymentsBody,
   SubscribeAck,
   PaymentPushCallback,
@@ -210,6 +211,17 @@ export class LnbitsClient {
     return data ?? []
   }
 
+  /** Pull server-delivered machine config (operator pubkey + fee config) over
+   * the authenticated transport — spirekeeper's `get_machine_config` RPC
+   * (bitspire#70 P1). Lets a seed-only ATM configure itself with no per-machine
+   * env provisioning. Rejects (LnbitsRpcError) if the server hasn't registered
+   * the RPC (older spirekeeper) — callers should soft-fall-back. */
+  async getMachineConfig(): Promise<MachineConfigResponse> {
+    return this.idempotent(() =>
+      this.sendRpc<MachineConfigResponse>('get_machine_config', {}),
+    )
+  }
+
   // ============================================================================
   // Invoices
   // ============================================================================
diff --git a/packages/lnbits/src/types.ts b/packages/lnbits/src/types.ts
index 17af86f..dd5e7a9 100644
--- a/packages/lnbits/src/types.ts
+++ b/packages/lnbits/src/types.ts
@@ -274,3 +274,30 @@ export type PaymentPushCallback = (payment: LnbitsPayment) => void
 
 /** Called when the subscription has been closed (by TTL or explicit unsubscribe). */
 export type SubscriptionCloseCallback = (reason: 'ttl' | 'unsubscribed') => void
+
+// ============================================================================
+// get_machine_config RPC (spirekeeper#41 / bitspire#70 P1)
+// ============================================================================
+
+/** Fee-config wire shape inside `get_machine_config` — mirrors spirekeeper's
+ * `FeeConfigPayload.to_wire_dict()` (snake_case). */
+export interface FeeConfigWire {
+  schema_version: number
+  cash_in_fee_fraction: number
+  cash_out_fee_fraction: number
+  components?: Record<string, number>
+}
+
+/** Response of the `get_machine_config` RPC: the operator pubkey + fee config
+ * (+ fiat, ids) LNbits delivers to a paired ATM over the authenticated
+ * transport, so a seed-only machine needs no per-machine env provisioning.
+ * `fee_config` is null until the operator has a super-config. */
+export interface MachineConfigResponse {
+  operator_pubkey: string
+  fee_config: FeeConfigWire | null
+  fiat_code: string
+  machine_npub: string
+  wallet_id: string
+  /** Freshness watermark (unix s) for the consumer's fee-config replay guard. */
+  created_at: number
+}

From 79e1823cc5e05321abe4cff485b2b3463bee9368 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sat, 4 Jul 2026 00:28:24 +0200
Subject: [PATCH 52/82] fix(machine): decrement cassettes by position, not
 denomination, on cash-out
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

recordTransaction() updated cassette counts with WHERE denomination = ?,
but the v9 migration made position the PK precisely so duplicate
denominations across bays are legal (and the HAL dispense path already
returns authoritative per-position results). On any machine with two
bays of the same denomination, a single dispense drained every matching
bay row — silently corrupting inventory, the operator cassette-state
publish, and out-of-money gating.

- cassettes branch: decrement by c.position
- mock-only fallback (no per-bay results): drain matching bays greedily
  in position order, mirroring the dispenser's own fill order
- regression tests with a duplicate-denomination layout (3 of 5 fail
  against the old code)

Found during the dev-branch architecture review.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../state-store-transactions.test.ts          | 170 ++++++++++++++++++
 apps/machine/electron/state-store.ts          |  31 +++-
 2 files changed, 195 insertions(+), 6 deletions(-)
 create mode 100644 apps/machine/electron/__tests__/state-store-transactions.test.ts

diff --git a/apps/machine/electron/__tests__/state-store-transactions.test.ts b/apps/machine/electron/__tests__/state-store-transactions.test.ts
new file mode 100644
index 0000000..fbb9a87
--- /dev/null
+++ b/apps/machine/electron/__tests__/state-store-transactions.test.ts
@@ -0,0 +1,170 @@
+/**
+ * Tests for recordTransaction inventory accounting.
+ *
+ * Regression coverage for the position-vs-denomination decrement bug:
+ * position is the cassettes PK (v9) and duplicate denominations across
+ * bays are legal, so cash-out decrements MUST address bays by position.
+ * A denomination-keyed UPDATE would drain every matching bay at once.
+ *
+ * Uses an in-memory SQLite database — fresh per test, no on-disk
+ * artifacts, no parallel-test interference.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import {
+  closeDatabase,
+  getCashbox,
+  initDatabase,
+  loadCassettes,
+  recordTransaction,
+  setCassettes,
+} from '../state-store.js'
+
+const TX_BASE = {
+  fiatCents: 4000,
+  sats: 100_000,
+  feeSats: 5_000,
+  feeFraction: 0.05,
+  exchangeRate: 2500,
+  currency: 'USD',
+}
+
+/** Two $20 bays plus one $50 bay — the duplicate-denomination layout. */
+function seedDuplicateDenomBays() {
+  setCassettes([
+    { position: 1, denomination: 20, count: 50 },
+    { position: 2, denomination: 20, count: 50 },
+    { position: 3, denomination: 50, count: 30 },
+  ])
+}
+
+function countsByPosition(): Record<number, number> {
+  const out: Record<number, number> = {}
+  for (const row of loadCassettes()) out[row.position] = row.count
+  return out
+}
+
+beforeEach(() => {
+  initDatabase(':memory:')
+  seedDuplicateDenomBays()
+})
+afterEach(() => {
+  closeDatabase()
+})
+
+describe('state-store: recordTransaction cash_out inventory', () => {
+  it('decrements only the bay that actually dispensed (duplicate denominations)', () => {
+    recordTransaction({
+      ...TX_BASE,
+      txid: 'tx-single-bay',
+      type: 'cash_out',
+      status: 'complete',
+      bills: [{ denomination: 20, count: 3 }],
+      cassettes: [
+        {
+          name: 'cassette1',
+          position: 1,
+          denomination: 20,
+          provisioned: 3,
+          dispensed: 3,
+          rejected: 0,
+        },
+        {
+          name: 'cassette2',
+          position: 2,
+          denomination: 20,
+          provisioned: 0,
+          dispensed: 0,
+          rejected: 0,
+        },
+      ],
+    })
+
+    expect(countsByPosition()).toEqual({ 1: 47, 2: 50, 3: 30 })
+  })
+
+  it('decrements each bay by its own dispensed count on a split dispense', () => {
+    recordTransaction({
+      ...TX_BASE,
+      txid: 'tx-split-bays',
+      type: 'cash_out',
+      status: 'complete',
+      bills: [{ denomination: 20, count: 60 }],
+      cassettes: [
+        {
+          name: 'cassette1',
+          position: 1,
+          denomination: 20,
+          provisioned: 50,
+          dispensed: 50,
+          rejected: 0,
+        },
+        {
+          name: 'cassette2',
+          position: 2,
+          denomination: 20,
+          provisioned: 10,
+          dispensed: 10,
+          rejected: 0,
+        },
+      ],
+    })
+
+    expect(countsByPosition()).toEqual({ 1: 0, 2: 40, 3: 30 })
+  })
+
+  it('fallback without cassette results drains matching bays greedily by position', () => {
+    recordTransaction({
+      ...TX_BASE,
+      txid: 'tx-fallback',
+      type: 'cash_out',
+      status: 'complete',
+      bills: [{ denomination: 20, count: 60 }],
+    })
+
+    // Bay 1 (50 bills) drains fully, bay 2 covers the remaining 10.
+    expect(countsByPosition()).toEqual({ 1: 0, 2: 40, 3: 30 })
+  })
+
+  it('never drives a bay count below zero', () => {
+    recordTransaction({
+      ...TX_BASE,
+      txid: 'tx-overdispense',
+      type: 'cash_out',
+      status: 'complete',
+      bills: [{ denomination: 50, count: 35 }],
+      cassettes: [
+        {
+          name: 'cassette3',
+          position: 3,
+          denomination: 50,
+          provisioned: 35,
+          dispensed: 35,
+          rejected: 0,
+        },
+      ],
+    })
+
+    expect(countsByPosition()).toEqual({ 1: 50, 2: 50, 3: 0 })
+  })
+})
+
+describe('state-store: recordTransaction cash_in cashbox', () => {
+  it('adds inserted bills to the cashbox and leaves cassettes untouched', () => {
+    recordTransaction({
+      ...TX_BASE,
+      txid: 'tx-cash-in',
+      type: 'cash_in',
+      status: 'complete',
+      bills: [
+        { denomination: 20, count: 2 },
+        { denomination: 50, count: 1 },
+      ],
+    })
+
+    const cashbox = getCashbox()
+    expect(cashbox.totalBills).toBe(3)
+    expect(cashbox.totalFiatCents).toBe(TX_BASE.fiatCents)
+    expect(countsByPosition()).toEqual({ 1: 50, 2: 50, 3: 30 })
+  })
+})
diff --git a/apps/machine/electron/state-store.ts b/apps/machine/electron/state-store.ts
index a274565..cfbfd71 100644
--- a/apps/machine/electron/state-store.ts
+++ b/apps/machine/electron/state-store.ts
@@ -982,8 +982,11 @@ export function recordTransaction(tx: TransactionInput): void {
   const insertCassetteBill = db.prepare(
     'INSERT INTO cassette_bills (txid, name, position, denomination, provisioned, dispensed, rejected) VALUES (?, ?, ?, ?, ?, ?, ?)'
   )
-  const updateCassette = db.prepare(
-    'UPDATE cassettes SET count = MAX(0, count + ?) WHERE denomination = ?'
+  const updateCassetteByPosition = db.prepare(
+    'UPDATE cassettes SET count = MAX(0, count + ?) WHERE position = ?'
+  )
+  const selectBaysByDenom = db.prepare(
+    'SELECT position, count FROM cassettes WHERE denomination = ? ORDER BY position'
   )
   const updateCashboxStmt = db.prepare(
     'UPDATE cashbox SET total_bills = total_bills + ?, total_fiat_cents = total_fiat_cents + ? WHERE id = 1'
@@ -1024,17 +1027,33 @@ export function recordTransaction(tx: TransactionInput): void {
     }
 
     if (t.type === 'cash_out') {
-      // Decrement cassettes by ACTUALLY dispensed count (not requested)
+      // Decrement cassettes by ACTUALLY dispensed count (not requested).
+      // Position is the addressable unit (v9): duplicate denominations
+      // across bays are legal, so a denomination-keyed UPDATE would
+      // decrement every matching bay.
       if (t.cassettes) {
         for (const c of t.cassettes) {
           if (c.dispensed > 0) {
-            updateCassette.run(-c.dispensed, c.denomination)
+            updateCassetteByPosition.run(-c.dispensed, c.position)
           }
         }
       } else {
-        // Fallback: use bill counts (backward compat for mocks without cassette data)
+        // Fallback: per-denomination bill counts (mocks without per-bay
+        // results). Drain matching bays greedily in position order —
+        // the dispenser's own fill order.
         for (const bill of t.bills) {
-          updateCassette.run(-bill.count, bill.denomination)
+          let remaining = bill.count
+          const bays = selectBaysByDenom.all(bill.denomination) as {
+            position: number
+            count: number
+          }[]
+          for (const bay of bays) {
+            if (remaining <= 0) break
+            const take = Math.min(remaining, bay.count)
+            if (take <= 0) continue
+            updateCassetteByPosition.run(-take, bay.position)
+            remaining -= take
+          }
         }
       }
     }

From 47151ebe8cb2fa972edc96b04bba9204edd03f78 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sat, 4 Jul 2026 01:00:12 +0200
Subject: [PATCH 53/82] docs: correct the lamassu-machine licensing boundary to
 commit c0b69d1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The provenance section claimed v8.1.5 was the last fully-open release.
GitHub history says otherwise: a9234d124d ("chore: add LICENSE",
2023-09-19) removed UNLICENSE and added the proprietary Appendix A SLA,
and the v8.1.5 tag (2023-09-21) already ships it. The true public-domain
boundary is that commit's parent, c0b69d1 ("chore: v8.6.0-beta.9") —
which is further along than 8.1.5 feature-wise.

lamassu-server's own boundary is unverified; flagged in the doc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1a068ad..1b2e8a0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,9 +15,11 @@ Core principles:
 
 ## Provenance + legal status
 
-The HAL drivers (validators / dispensers / printers) and the cash-flow state machine derive from Lamassu Industries AG's open-source `lamassu-machine` and `lamassu-server` repositories, **only up to v8.1.5** — the last release published under a fully-open license. Lamassu transitioned to a proprietary, source-available license (their custom "Appendix A SLA") on 2024-01-26 and gated v8.1.6+ behind a paid OSA subscription.
+The HAL drivers (validators / dispensers / printers) and the cash-flow state machine derive from Lamassu Industries AG's `lamassu-machine` repository, **only up to commit `c0b69d1ed196d396c5f057478c2ea290babd58ab`** ("chore: v8.6.0-beta.9", 2023-09-19) — the last commit published into the public domain (`UNLICENSE` in tree). The very next commit, `a9234d124d` ("chore: add LICENSE (#1019)", 2023-09-19), removed `UNLICENSE` and added Lamassu's proprietary "Appendix A SLA". **The `v8.1.5` tag (2023-09-21) already ships the Appendix A license** — the previously documented "8.1.5 is the open boundary" was wrong (verified against GitHub history 2026-07-04). Note the public-domain boundary sits on the 8.6-beta line, which is *further along* than 8.1.5 feature-wise.
 
-**Hard rule when working in this repo:** do not pull, port, or copy code from lamassu-machine / lamassu-server at v8.1.6 or later. If a HAL bug fix or feature exists upstream past 8.1.5, either (a) reimplement from protocol docs / hardware specs without looking at v8.1.6+ source, or (b) raise the question with the maintainer first. The 8.1.5 tree is fair game; everything after is licensed code we have no rights to.
+**Hard rule when working in this repo:** do not pull, port, or copy lamassu-machine code from `a9234d124d` or later (which includes every 8.1.5+ tag). Reference only `c0b69d1` or earlier. If a HAL bug fix or feature exists upstream past that commit, either (a) reimplement from protocol docs / hardware specs without looking at the licensed source, or (b) raise the question with the maintainer first. To fetch the open tree safely: `git fetch --depth 1 origin c0b69d1ed196d396c5f057478c2ea290babd58ab` — never check out a tag.
+
+The `lamassu-server` boundary has not been re-verified against its own history and may differ — check its license-change commit before referencing it.
 
 bitSpire is an independent project under AGPL-3.0 and is not affiliated with Lamassu Industries AG.
 

From 7a67c2182f52085e599f156c753027fef200a1a7 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sat, 4 Jul 2026 01:07:58 +0200
Subject: [PATCH 54/82] fix(machine): credit bills on stacked-confirmation, not
 stack command (#58)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backports the legacy brain.js escrow interlock (from the public-domain
lamassu-machine tree at c0b69d1, see CLAUDE.md provenance):

- The id003/ebds drivers' `billsValid` event (bill physically reached
  the stacker) is now the credit trigger. hal-service tracks
  escrow → in-flight and fires onBillInserted only on confirmation;
  hal:stack-bill no longer synthesizes the credit at command time.
- New BILL_PENDING machine event marks the in-flight bill;
  FINISH_INSERTING is guard-blocked while one is pending, so "done"
  pressed mid-stack can no longer mint an LNURL that includes a bill
  still sitting in escrow (the aiolabs/bitspire#58 loss).
- BILL_INSERTED now requires a matching pending bill (stray or
  out-of-state confirmations are never credited) and BILL_REJECTED
  clears the in-flight marker — a failed/returned stack was never
  credited, so nothing to unwind.
- Escrow decision is fail-closed (legacy _billsRead parity): bill read
  outside insertingBills, or with unknown rate/balance, is returned to
  the customer instead of stacked-and-swallowed (closes the #35 gap at
  the decision point that physically takes the money).
- CashInView disables "Done" and shows a processing hint while a bill
  is in flight; the dev simulator drives the same guarded two-event
  path.

Both loss directions verified against the legacy semantics:
operator-pays-for-unstacked-cash and customer-bill-swallowed-uncredited.

6 new state-machine interlock tests; 27 state-machine + 43 machine-app
tests pass; full build (vue-tsc + vite + electron tsc) clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/machine/electron/hal-service.ts          |  47 +++++++-
 apps/machine/electron/main.ts                 |   6 +-
 apps/machine/src/services/hal.ts              |  40 ++++++-
 apps/machine/src/stores/atm.ts                |  49 ++++++--
 apps/machine/src/views/CashInView.vue         |  12 +-
 .../src/__tests__/machine.test.ts             | 111 ++++++++++++++++++
 packages/state-machine/src/machine.ts         |  44 ++++++-
 packages/state-machine/src/types.ts           |   9 ++
 8 files changed, 294 insertions(+), 24 deletions(-)

diff --git a/apps/machine/electron/hal-service.ts b/apps/machine/electron/hal-service.ts
index 27508b0..72f3480 100644
--- a/apps/machine/electron/hal-service.ts
+++ b/apps/machine/electron/hal-service.ts
@@ -36,6 +36,11 @@ export interface HalConfig {
 export interface ValidatorCallbacks {
   shouldAcceptBill: (denomination: number) => boolean | 'hold'
   onBillRead?: (denomination: number) => void
+  /**
+   * Fires on the validator's stacked-confirmation (`billsValid`) — the
+   * bill physically reached the stacker. This is the CREDIT event; it is
+   * NOT emitted at stack-command time (a stack can still fail/return).
+   */
   onBillInserted: (denomination: number) => void
   onBillRejected: (reason: string) => void
   onError: (error: string) => void
@@ -142,6 +147,14 @@ export async function initializeHal(config: HalConfig): Promise<HalInstance> {
       count: c.count ?? 0,
     }))
 
+  // Escrow / in-flight bookkeeping (legacy brain.js `billsRead` interlock):
+  // `escrowDenomination` = bill held in escrow awaiting a stack/reject
+  // decision; `inFlightDenomination` = stack commanded, awaiting the
+  // validator's `billsValid` stacked-confirmation. onBillInserted (the
+  // credit event) fires only on that confirmation.
+  let escrowDenomination: number | null = null
+  let inFlightDenomination: number | null = null
+
   return {
     connectValidator: (callbacks: ValidatorCallbacks) => {
       if (!validator) {
@@ -153,10 +166,11 @@ export async function initializeHal(config: HalConfig): Promise<HalInstance> {
           const decision = callbacks.shouldAcceptBill(data.denomination)
           if (decision === 'hold') {
             console.log('[HAL] Bill in escrow:', data.denomination)
+            escrowDenomination = data.denomination
             callbacks.onBillRead?.(data.denomination)
           } else if (decision) {
+            inFlightDenomination = data.denomination
             validator.stack()
-            callbacks.onBillInserted(data.denomination)
           } else {
             console.log('[HAL] Bill rejected: insufficient balance for', data.denomination)
             validator.reject()
@@ -168,7 +182,23 @@ export async function initializeHal(config: HalConfig): Promise<HalInstance> {
         }
       })
 
+      // Stacked-confirmation → the credit event.
+      validator.on('billsValid', () => {
+        if (inFlightDenomination === null) {
+          console.warn('[HAL] billsValid with no bill in flight — ignoring')
+          return
+        }
+        const denomination = inFlightDenomination
+        inFlightDenomination = null
+        console.log('[HAL] Bill stacked (confirmed):', denomination)
+        callbacks.onBillInserted(denomination)
+      })
+
       validator.on('billsRejected', (data?: { reason: string; code: number | null }) => {
+        // Covers both an escrow refusal and a failed/returned stack —
+        // either way nothing was credited and nothing is in flight.
+        escrowDenomination = null
+        inFlightDenomination = null
         callbacks.onBillRejected(data?.reason ?? 'unknown')
       })
 
@@ -195,8 +225,19 @@ export async function initializeHal(config: HalConfig): Promise<HalInstance> {
       validator?.lightOff()
     },
 
-    stackBill: () => validator?.stack(),
-    rejectBill: () => validator?.reject(),
+    stackBill: () => {
+      if (escrowDenomination === null) {
+        console.warn('[HAL] stackBill with no bill in escrow — ignoring')
+        return
+      }
+      inFlightDenomination = escrowDenomination
+      escrowDenomination = null
+      validator?.stack()
+    },
+    rejectBill: () => {
+      escrowDenomination = null
+      validator?.reject()
+    },
 
     dispenseCash: async (amounts): Promise<DispenseResult> => {
       console.log('[HAL] Dispensing:', amounts)
diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index 9107951..fc48d87 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -585,10 +585,12 @@ ipcMain.handle('hal:stack-bill', () => {
     console.warn('[Electron] hal:stack-bill called with no bill in escrow — ignoring')
     return
   }
-  const denomination = pendingBillDenomination
   pendingBillDenomination = null
+  // Credit is NOT sent here. hal-service fires onBillInserted (forwarded
+  // as 'hal:bill-inserted') only on the validator's `billsValid`
+  // stacked-confirmation — a stack command can still fail or return the
+  // bill (aiolabs/bitspire#58).
   halInstance.stackBill()
-  mainWindow?.webContents.send('hal:bill-inserted', denomination)
 })
 
 ipcMain.handle('hal:reject-bill', () => {
diff --git a/apps/machine/src/services/hal.ts b/apps/machine/src/services/hal.ts
index 1e20cc3..f48fda8 100644
--- a/apps/machine/src/services/hal.ts
+++ b/apps/machine/src/services/hal.ts
@@ -109,6 +109,12 @@ export async function initializeHalServices(config: HalConfig): Promise<HalServi
   })
   console.log('[HAL] Validator started')
 
+  // Escrow / in-flight bookkeeping: credit (onBillInserted) fires only on
+  // the validator's `billsValid` stacked-confirmation, never at
+  // stack-command time (mirrors electron/hal-service.ts).
+  let escrowDenomination: number | null = null
+  let inFlightDenomination: number | null = null
+
   // Track inventory (decremented on dispense)
   const inventory: Record<number, number> = {}
   for (const cassette of dispConfig.cassettes) {
@@ -206,10 +212,13 @@ export async function initializeHalServices(config: HalConfig): Promise<HalServi
           if (decision === 'hold') {
             // Hold in escrow — caller will call stackBill() or rejectBill()
             console.log('[HAL] Bill in escrow:', data.denomination)
+            escrowDenomination = data.denomination
             callbacks.onBillRead?.(data.denomination)
           } else if (decision) {
+            // Credit waits for the validator's stacked-confirmation
+            // (`billsValid`) — see the handler below.
+            inFlightDenomination = data.denomination
             validator.stack()
-            callbacks.onBillInserted(data.denomination)
           } else {
             console.log('[HAL] Bill rejected: insufficient ATM balance for', data.denomination)
             validator.reject()
@@ -221,7 +230,21 @@ export async function initializeHalServices(config: HalConfig): Promise<HalServi
         }
       })
 
+      // Stacked-confirmation → the credit event.
+      validator.on('billsValid', () => {
+        if (inFlightDenomination === null) {
+          console.warn('[HAL] billsValid with no bill in flight — ignoring')
+          return
+        }
+        const denomination = inFlightDenomination
+        inFlightDenomination = null
+        console.log('[HAL] Bill stacked (confirmed):', denomination)
+        callbacks.onBillInserted(denomination)
+      })
+
       validator.on('billsRejected', (data?: { reason: string; code: number | null }) => {
+        escrowDenomination = null
+        inFlightDenomination = null
         callbacks.onBillRejected(data?.reason ?? 'unknown')
       })
 
@@ -248,8 +271,19 @@ export async function initializeHalServices(config: HalConfig): Promise<HalServi
       validator.lightOff()
     },
 
-    stackBill: () => validator.stack(),
-    rejectBill: () => validator.reject(),
+    stackBill: () => {
+      if (escrowDenomination === null) {
+        console.warn('[HAL] stackBill with no bill in escrow — ignoring')
+        return
+      }
+      inFlightDenomination = escrowDenomination
+      escrowDenomination = null
+      validator.stack()
+    },
+    rejectBill: () => {
+      escrowDenomination = null
+      validator.reject()
+    },
 
     cleanup: async () => {
       return new Promise<void>((resolve) => {
diff --git a/apps/machine/src/stores/atm.ts b/apps/machine/src/stores/atm.ts
index 2bfaeea..a770dae 100644
--- a/apps/machine/src/stores/atm.ts
+++ b/apps/machine/src/stores/atm.ts
@@ -949,11 +949,20 @@ export const useAtmStore = defineStore('atm', () => {
       // Wire validator events to state machine
       hal.connectValidator({
         shouldAcceptBill: (denomination) => {
-          // Check if accepting this bill would exceed available balance
           const ctx = context.value
-          if (!ctx || ctx.exchangeRate === 0) {
-            console.warn('[ATM] Cannot check balance: no exchange rate')
-            return true // Allow if we don't have rate yet (shouldn't happen)
+
+          // Fail closed: no rate/balance, or not in the accepting state →
+          // return the bill (legacy _billsRead parity).
+          if (
+            nestedState.value !== 'insertingBills' ||
+            !ctx ||
+            ctx.exchangeRate <= 0 ||
+            ctx.availableBalance <= 0
+          ) {
+            console.log(
+              `[ATM] Rejecting $${denomination} bill: not accepting (state/rate/balance unknown)`
+            )
+            return false
           }
 
           // Calculate what the new sats amount would be
@@ -971,6 +980,9 @@ export const useAtmStore = defineStore('atm', () => {
             return false
           }
 
+          // Accepting: mark the bill in flight. The HAL service issues the
+          // stack command; BILL_INSERTED follows on stacked-confirmation.
+          send({ type: 'BILL_PENDING', denomination })
           return true
         },
         onBillInserted: (denomination) => {
@@ -1249,11 +1261,22 @@ export const useAtmStore = defineStore('atm', () => {
       // Wire validator events from main process via IPC
       api.onHalBillRead((denomination) => {
         console.log('[ATM] Bill in escrow:', denomination)
-        // Check if we should accept this bill
         const ctx = context.value
-        if (!ctx || ctx.exchangeRate === 0) {
-          // No rate yet, accept anyway
-          api.halStackBill()
+
+        // Fail closed (legacy _billsRead parity): only stack while the
+        // machine is accepting bills AND rate + balance are known.
+        // Anything else returns the bill to the customer — stacking here
+        // would swallow cash the machine can't (or won't) credit.
+        if (
+          nestedState.value !== 'insertingBills' ||
+          !ctx ||
+          ctx.exchangeRate <= 0 ||
+          ctx.availableBalance <= 0
+        ) {
+          console.log(
+            `[ATM] Rejecting $${denomination} bill: not accepting (state=${nestedState.value}, rate=${ctx?.exchangeRate ?? 'n/a'}, balance=${ctx?.availableBalance ?? 'n/a'})`
+          )
+          api.halRejectBill()
           return
         }
 
@@ -1272,7 +1295,10 @@ export const useAtmStore = defineStore('atm', () => {
           return
         }
 
-        // Accept the bill
+        // Accept the bill: mark it in flight, then command the stack.
+        // Credit (BILL_INSERTED) arrives via onHalBillInserted once the
+        // validator confirms the bill reached the stacker.
+        send({ type: 'BILL_PENDING', denomination })
         api.halStackBill()
       })
 
@@ -1366,6 +1392,11 @@ export const useAtmStore = defineStore('atm', () => {
   }
 
   function insertBill(denomination: number) {
+    // Dev simulator: a real validator goes escrow → stack command →
+    // stacked-confirmation. Emit both halves so the simulated bill runs
+    // the same guarded path (BILL_PENDING is balance-gated; a refused
+    // pending drops the credit too).
+    send({ type: 'BILL_PENDING', denomination })
     send({ type: 'BILL_INSERTED', denomination })
   }
 
diff --git a/apps/machine/src/views/CashInView.vue b/apps/machine/src/views/CashInView.vue
index 16ee6be..5210c86 100644
--- a/apps/machine/src/views/CashInView.vue
+++ b/apps/machine/src/views/CashInView.vue
@@ -242,7 +242,10 @@ const isProcessing = computed(() => atmStore.isPayingInvoice)
             </p>
 
             <!-- Status -->
-            <p v-if="balanceLimitReached" class="text-sm lg:text-xl text-muted-foreground">
+            <p v-if="context?.billPending" class="text-sm lg:text-xl text-muted-foreground">
+              ⏳ Processing bill…
+            </p>
+            <p v-else-if="balanceLimitReached" class="text-sm lg:text-xl text-muted-foreground">
               Maximum amount reached — press Done to continue
             </p>
             <p v-else class="text-sm lg:text-xl text-muted-foreground">
@@ -269,11 +272,14 @@ const isProcessing = computed(() => atmStore.isPayingInvoice)
               </AlertDescription>
             </Alert>
 
-            <!-- Done button -->
+            <!-- Done button — also blocked while a bill is between the
+                 stack command and the validator's stacked-confirmation
+                 (the machine guard drops FINISH_INSERTING regardless;
+                 this keeps the UI honest about it) -->
             <Button
               class="w-full bg-gradient-to-r from-orange-500 to-yellow-400 text-black hover:from-orange-600 hover:to-yellow-500"
               size="kiosk-lg"
-              :disabled="!context || context.billsInserted.length === 0"
+              :disabled="!context || context.billsInserted.length === 0 || context.billPending !== null"
               @click="finishInserting"
             >
               Done Inserting
diff --git a/packages/state-machine/src/__tests__/machine.test.ts b/packages/state-machine/src/__tests__/machine.test.ts
index 00d742a..9b9bf91 100644
--- a/packages/state-machine/src/__tests__/machine.test.ts
+++ b/packages/state-machine/src/__tests__/machine.test.ts
@@ -130,12 +130,17 @@ describe('ATM State Machine', () => {
       // Wait for rate fetch
       await new Promise((resolve) => setTimeout(resolve, 50))
 
+      // Real hardware flow: escrow accepted (stack commanded) →
+      // stacked-confirmation credits the bill.
+      actor.send({ type: 'BILL_PENDING', denomination: 20 })
       actor.send({ type: 'BILL_INSERTED', denomination: 20 })
+      actor.send({ type: 'BILL_PENDING', denomination: 10 })
       actor.send({ type: 'BILL_INSERTED', denomination: 10 })
 
       const context = actor.getSnapshot().context
       expect(context.billsInserted).toEqual([20, 10])
       expect(context.fiatCents).toBe(3000) // $30 in cents
+      expect(context.billPending).toBeNull()
     })
 
     it('should return to idle on CANCEL', async () => {
@@ -152,6 +157,112 @@ describe('ATM State Machine', () => {
     })
   })
 
+  describe('cash-in escrow credit interlock (aiolabs/bitspire#58)', () => {
+    // Legacy brain.js parity: a bill is credited only on the validator's
+    // stacked-confirmation, and the insert phase cannot finish while a
+    // bill is between the stack command and that confirmation.
+
+    async function startInserting() {
+      const machine = createATMMachine(mockServices)
+      const actor = createActor(machine)
+      actor.start()
+      actor.send({ type: 'SELECT_CASH_IN' })
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      expect(actor.getSnapshot().value).toEqual({ cashIn: 'insertingBills' })
+      return actor
+    }
+
+    it('blocks FINISH_INSERTING while a bill is in flight', async () => {
+      const actor = await startInserting()
+
+      actor.send({ type: 'BILL_PENDING', denomination: 20 })
+      actor.send({ type: 'BILL_INSERTED', denomination: 20 })
+      // Second bill enters flight; user mashes "done" before it settles.
+      actor.send({ type: 'BILL_PENDING', denomination: 1 })
+      actor.send({ type: 'FINISH_INSERTING' })
+
+      // Still inserting — the in-flight bill holds the door.
+      const snap = actor.getSnapshot()
+      expect(snap.value).toEqual({ cashIn: 'insertingBills' })
+      expect(snap.context.billPending).toBe(1)
+      // Nothing was credited for the in-flight bill.
+      expect(snap.context.fiatCents).toBe(2000)
+    })
+
+    it('allows FINISH_INSERTING once the in-flight bill is confirmed', async () => {
+      const actor = await startInserting()
+
+      actor.send({ type: 'BILL_PENDING', denomination: 1 })
+      actor.send({ type: 'FINISH_INSERTING' }) // blocked
+      actor.send({ type: 'BILL_INSERTED', denomination: 1 }) // confirmation lands
+      actor.send({ type: 'FINISH_INSERTING' })
+      await new Promise((resolve) => setTimeout(resolve, 50))
+
+      const snap = actor.getSnapshot()
+      expect(snap.value).not.toEqual({ cashIn: 'insertingBills' })
+      expect(snap.context.fiatCents).toBe(100)
+      expect(snap.context.billPending).toBeNull()
+    })
+
+    it('BILL_REJECTED clears the in-flight bill without crediting', async () => {
+      const actor = await startInserting()
+
+      actor.send({ type: 'BILL_PENDING', denomination: 20 })
+      actor.send({ type: 'BILL_INSERTED', denomination: 20 })
+      actor.send({ type: 'BILL_PENDING', denomination: 10 })
+      // Stack failed — validator returned the bill.
+      actor.send({ type: 'BILL_REJECTED', reason: 'returned' })
+
+      const snap = actor.getSnapshot()
+      expect(snap.context.billPending).toBeNull()
+      expect(snap.context.fiatCents).toBe(2000) // only the confirmed bill
+      expect(snap.context.billsInserted).toEqual([20])
+
+      // And the door is open again.
+      actor.send({ type: 'FINISH_INSERTING' })
+      await new Promise((resolve) => setTimeout(resolve, 50))
+      expect(actor.getSnapshot().value).not.toEqual({ cashIn: 'insertingBills' })
+    })
+
+    it('does not credit a BILL_INSERTED with no matching pending bill', async () => {
+      const actor = await startInserting()
+
+      // Stray stacked-confirmation (no stack was commanded).
+      actor.send({ type: 'BILL_INSERTED', denomination: 20 })
+
+      const snap = actor.getSnapshot()
+      expect(snap.context.fiatCents).toBe(0)
+      expect(snap.context.billsInserted).toEqual([])
+    })
+
+    it('drops the credit too when BILL_PENDING was refused (over balance)', async () => {
+      const actor = await startInserting()
+
+      // Mock balance is 1M sats @ 2500 sats/USD → $400 ceiling. $500 bill
+      // exceeds it: pending is guard-refused, so its confirmation (which a
+      // correctly-driven validator would never send) is not credited either.
+      actor.send({ type: 'BILL_PENDING', denomination: 500 })
+      actor.send({ type: 'BILL_INSERTED', denomination: 500 })
+
+      const snap = actor.getSnapshot()
+      expect(snap.context.billPending).toBeNull()
+      expect(snap.context.fiatCents).toBe(0)
+    })
+
+    it('CANCEL with a bill in flight lands in confirmAbandon with pending cleared', async () => {
+      const actor = await startInserting()
+
+      actor.send({ type: 'BILL_PENDING', denomination: 20 })
+      actor.send({ type: 'BILL_INSERTED', denomination: 20 })
+      actor.send({ type: 'BILL_PENDING', denomination: 10 })
+      actor.send({ type: 'CANCEL' })
+
+      const snap = actor.getSnapshot()
+      expect(snap.value).toEqual({ cashIn: 'confirmAbandon' })
+      expect(snap.context.billPending).toBeNull()
+    })
+  })
+
   describe('cash-out flow (ATM-driven amount selection)', () => {
     it('should transition to cashOut on SELECT_CASH_OUT', async () => {
       const machine = createATMMachine(mockServices)
diff --git a/packages/state-machine/src/machine.ts b/packages/state-machine/src/machine.ts
index de0cb90..c889127 100644
--- a/packages/state-machine/src/machine.ts
+++ b/packages/state-machine/src/machine.ts
@@ -181,6 +181,15 @@ export function createATMMachine(
       setCashOutFee: assign({
         feeFraction: ({ context }) => context.cashOutFeeFraction,
       }),
+      setBillPending: assign({
+        billPending: ({ context, event }) => {
+          if (event.type !== 'BILL_PENDING') return context.billPending
+          return event.denomination
+        },
+      }),
+      clearBillPending: assign({
+        billPending: null,
+      }),
       addBill: assign({
         billsInserted: ({ context, event }) => {
           if (event.type !== 'BILL_INSERTED') return context.billsInserted
@@ -190,6 +199,7 @@ export function createATMMachine(
           if (event.type !== 'BILL_INSERTED') return context.fiatCents
           return context.fiatCents + event.denomination * 100
         },
+        billPending: null,
       }),
       calculateSats: assign({
         satsAmount: ({ context }) => {
@@ -367,13 +377,26 @@ export function createATMMachine(
     },
     guards: {
       hasInsertedBills: ({ context }) => context.billsInserted.length > 0,
+      // Legacy brain.js parity: "send coins" is a no-op while a bill is
+      // between the stack command and the validator's stacked-confirmation.
+      canFinishInserting: ({ context }) =>
+        context.billsInserted.length > 0 && context.billPending === null,
+      // A credit event must correspond to the bill we commanded to stack —
+      // a stray stacked-confirmation with no pending bill is not credited.
+      billMatchesPending: ({ context, event }) => {
+        if (event.type !== 'BILL_INSERTED') return false
+        return context.billPending === event.denomination
+      },
       hasSufficientAmount: ({ context }) => context.fiatCents >= 100, // $1 minimum
       hasExchangeRate: ({ context }) => context.exchangeRate > 0,
       canRetry: ({ context }) => context.retryCount < 3,
       hasUserNpub: ({ context }) => context.userNpub !== null,
       hasOfferRequest: ({ context }) => context.pendingOfferRequest !== null,
+      // Gate at the PENDING (pre-stack) decision, matching legacy
+      // _billsRead: balance/rate checks happen before the bill is
+      // physically committed. Once stacked, credit is unconditional.
       billWithinBalance: ({ context, event }) => {
-        if (event.type !== 'BILL_INSERTED') return false
+        if (event.type !== 'BILL_PENDING') return false
         // Reject bills if balance or rate is unknown — don't risk accepting
         // cash we can't cover with sats
         if (context.availableBalance <= 0 || context.exchangeRate === 0) return false
@@ -476,15 +499,25 @@ export function createATMMachine(
               ],
             },
             on: {
-              BILL_INSERTED: {
+              // Escrow accepted → stack commanded. Marks the bill in
+              // flight; credit waits for the stacked-confirmation.
+              BILL_PENDING: {
                 guard: 'billWithinBalance',
+                actions: 'setBillPending',
+              },
+              // Validator confirmed the bill reached the stacker. The
+              // cash is physically in the box — credit unconditionally.
+              BILL_INSERTED: {
+                guard: 'billMatchesPending',
                 actions: ['addBill', 'calculateSats'],
               },
               BILL_REJECTED: {
-                // Stay in state, maybe show message
+                // Bill returned to customer (stack failed or refused) —
+                // it was never credited; just clear the in-flight marker.
+                actions: 'clearBillPending',
               },
               FINISH_INSERTING: {
-                guard: 'hasInsertedBills',
+                guard: 'canFinishInserting',
                 target: 'generatingNdebit',
               },
               CANCEL: [
@@ -549,6 +582,9 @@ export function createATMMachine(
           confirmAbandon: {
             // Warning: cash is in the machine, abandoning forfeits it.
             // Auto-clear after 60s so the machine self-recovers if customer walked away.
+            // A bill still in flight when the user bails is forfeited
+            // like the rest — clear the marker so nothing blocks on it.
+            entry: 'clearBillPending',
             after: {
               60000: '#atm.idle',
             },
diff --git a/packages/state-machine/src/types.ts b/packages/state-machine/src/types.ts
index 6be35af..3a2810e 100644
--- a/packages/state-machine/src/types.ts
+++ b/packages/state-machine/src/types.ts
@@ -91,6 +91,13 @@ export interface ATMContext {
   // Hardware state
   /** Bills inserted during cash-in */
   billsInserted: number[]
+  /**
+   * Bill in flight: stack commanded, awaiting the validator's
+   * stacked-confirmation. Credit (BILL_INSERTED) only lands once the
+   * bill physically reached the stacker; FINISH_INSERTING is blocked
+   * while a bill is in flight (legacy brain.js 'billsRead' interlock).
+   */
+  billPending: number | null
   /** Whether cash has been dispensed */
   cashDispensed: boolean
   /** Dispense amounts for cash-out */
@@ -140,6 +147,7 @@ export type ATMEvent =
   | { type: 'CLEAR_SELECTION' }
   | { type: 'CONFIRM_AMOUNT' }
   // Hardware events
+  | { type: 'BILL_PENDING'; denomination: number }
   | { type: 'BILL_INSERTED'; denomination: number }
   | { type: 'BILL_REJECTED'; reason: string }
   | { type: 'CASH_DISPENSED' }
@@ -187,6 +195,7 @@ export const initialContext: ATMContext = {
   paymentMethod: null,
   pendingOfferRequest: null,
   billsInserted: [],
+  billPending: null,
   cashDispensed: false,
   dispenseAmounts: [],
   cashOutSelection: [],

From f70105e8fff0d5f5ef3df8f70f5c2584363e741a Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Mon, 27 Jul 2026 17:58:22 +0200
Subject: [PATCH 55/82] feat(deploy): add self-growing disk-image-batm3 target
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

batm3-installed existed as a nixosConfiguration but had no dd-able disk
image (only the live ISO, which is tmpfs — no persistent state.db/.env).
Mirrors the douro/sintra make-disk-image blocks, with one improvement:
boot.growPartition + fileSystems."/".autoResize so the root partition
and ext4 expand to fill the target drive on first boot. Flashing is
dd-and-done — no manual parted/resize2fs — and the full drive is
available to the nix store from day one (the #55 headroom lesson).

Image-only override via extendModules: the running system's
batm3-installed config (what auto-upgrade rebuilds against) is
unchanged.

Build: nix build .#disk-image-batm3  → result/nixos.img

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 flake.nix | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/flake.nix b/flake.nix
index 63296c0..3aa61e9 100644
--- a/flake.nix
+++ b/flake.nix
@@ -331,6 +331,34 @@
           diskSize = "auto";
         };
 
+        # BATM3 (OptiPlex 9030 AIO board-swap) installed image, dd-able to
+        # its SATA drive. Unlike the douro/sintra images, this one grows
+        # itself: growPartition expands the root partition to fill whatever
+        # drive it lands on (16GB today) at first boot and autoResize
+        # stretches the ext4 to match — no manual parted/resize2fs step
+        # after flashing, and all the drive's headroom is available to the
+        # nix store from day one (cf. #55). Image-only override: once
+        # grown, subsequent nixos-rebuilds against plain batm3-installed
+        # are unaffected.
+        disk-image-batm3 =
+          let
+            cfg = self.nixosConfigurations.batm3-installed.extendModules {
+              modules = [
+                {
+                  boot.growPartition = true;
+                  fileSystems."/".autoResize = true;
+                }
+              ];
+            };
+          in
+          import (nixpkgs + "/nixos/lib/make-disk-image.nix") {
+            inherit pkgs lib;
+            config = cfg.config;
+            format = "raw";
+            partitionTableType = "efi";
+            diskSize = "auto";
+          };
+
         # USB-bootable Sintra image with DISTINCT partition labels
         # (nixos-usb / ESP-USB) so the stick can be booted on a Sintra whose
         # eMMC already holds a nixos/ESP-labelled install without a by-label

From 4d0e42f2898c67e690630e5f83d88079ac7bd884 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Thu, 30 Jul 2026 00:40:06 +0200
Subject: [PATCH 56/82] fix(hal): EBDS escrow stack/return latch +
 return-on-disable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cash-in stalled on the batm3: a note reached escrow and was read, but the
acceptor never stacked or returned it, and the customer was never
credited. Root cause: EBDS carries the stack/return decision as bits in
the omnibus *poll* command, but the driver sent stack()/reject() as a
single one-shot frame while a free-running 100ms poller kept sending
plain polls. The lone stack frame races/collides with the poller (or its
ack desyncs), gets dropped, and the device holds the note in escrow
indefinitely.

- ebds-rs232: latch the escrow decision (`pendingAction`) into the poll
  command byte and re-assert it on every poll until the device leaves
  escrow (cleared in _process when `!escrowed`). A dropped frame is now
  simply retried on the next poll.
- hal-service: return an escrowed note on disableValidator() — disable
  alone does not release it on EBDS, so an inactivity timeout / cancel
  previously stranded the bill in the transport (observed on the batm3).
- atm store: stringify the `[ATM] Sending event` / `[ATM] State` logs —
  they were printing `[object Object]`, which blinded the cash-in trace.

Verified: hal builds, machine app typechecks. Hardware behaviour to be
confirmed on the batm3 (no unit tests exist for this serial driver).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/hal-service.ts          |  9 ++++
 apps/machine/src/stores/atm.ts                |  4 +-
 .../hal/src/validators/ebds/ebds-rs232.ts     | 42 +++++++++++++++----
 3 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/apps/machine/electron/hal-service.ts b/apps/machine/electron/hal-service.ts
index 72f3480..2ec863b 100644
--- a/apps/machine/electron/hal-service.ts
+++ b/apps/machine/electron/hal-service.ts
@@ -221,6 +221,15 @@ export async function initializeHal(config: HalConfig): Promise<HalInstance> {
     },
 
     disableValidator: () => {
+      // If a note is sitting in escrow when we disable (inactivity timeout,
+      // cancel, or leaving the insert screen), return it to the customer.
+      // Disabling alone does NOT release an escrowed note on EBDS — it would
+      // be stranded in the transport until the next power cycle.
+      if (escrowDenomination !== null) {
+        console.log('[HAL] Returning escrowed bill on disable:', escrowDenomination)
+        escrowDenomination = null
+        validator?.reject()
+      }
       validator?.disable()
       validator?.lightOff()
     },
diff --git a/apps/machine/src/stores/atm.ts b/apps/machine/src/stores/atm.ts
index a770dae..7119500 100644
--- a/apps/machine/src/stores/atm.ts
+++ b/apps/machine/src/stores/atm.ts
@@ -458,7 +458,7 @@ export const useAtmStore = defineStore('atm', () => {
     actor.value.subscribe((newSnapshot: SnapshotFrom<ATMMachine>) => {
       const prevSnapshot = snapshot.value
       snapshot.value = newSnapshot
-      console.log('[ATM] State:', newSnapshot.value)
+      console.log('[ATM] State:', JSON.stringify(newSnapshot.value))
 
       // Detect transition into a complete state
       const state = newSnapshot.value
@@ -1374,7 +1374,7 @@ export const useAtmStore = defineStore('atm', () => {
       console.error('[ATM] Cannot send event: machine not initialized')
       return
     }
-    console.log('[ATM] Sending event:', event)
+    console.log('[ATM] Sending event:', event.type, JSON.stringify(event))
     actor.value.send(event)
   }
 
diff --git a/packages/hal/src/validators/ebds/ebds-rs232.ts b/packages/hal/src/validators/ebds/ebds-rs232.ts
index 6673a25..07820b1 100644
--- a/packages/hal/src/validators/ebds/ebds-rs232.ts
+++ b/packages/hal/src/validators/ebds/ebds-rs232.ts
@@ -313,6 +313,13 @@ export class EbdsRs232 extends EventEmitter {
   private serial: SerialPort | null = null
   private ack: number = 0x0
   private enabledDenominations: number = 0x00
+  // Latched escrow decision. In EBDS the stack/return choice is NOT a one-shot
+  // message — it's carried as bits in the omnibus poll command, and the device
+  // holds the escrowed note until a poll asserts stack or return. We keep the
+  // action set and re-assert it on every poll until the device leaves escrow
+  // (cleared in _process), so a single dropped/collided frame no longer strands
+  // the note in escrow forever.
+  private pendingAction: 'none' | 'stack' | 'return' = 'none'
   private lastStatusFlags: string | null = null
   private firmwareLogged: boolean = false
 
@@ -405,23 +412,38 @@ export class EbdsRs232 extends EventEmitter {
 
   // -- Commands (Appendix D, Controller Message) ---------------------------
 
-  /** Send an Omnibus poll command with current denomination mask */
+  /**
+   * Command byte 1 for the omnibus poll, encoding any latched escrow action.
+   * `stack` (0x3f) and `return` (0x5f) differ from the plain poll (0x1b) only
+   * in the stack/return bits; while an action is latched every poll re-asserts
+   * it until the device acts.
+   */
+  private commandByte(): number {
+    if (this.pendingAction === 'stack') return 0x3f
+    if (this.pendingAction === 'return') return 0x5f
+    return 0x1b
+  }
+
+  /** Send an Omnibus poll command with the current mask + latched action */
   poll(): void {
-    this._dispatch([this.enabledDenominations, 0x1b, 0x10])
+    this._dispatch([this.enabledDenominations, this.commandByte(), 0x10])
   }
 
-  /** Stack the bill currently in escrow */
+  /** Latch "stack the escrowed note"; re-asserted each poll until it takes. */
   stack(): void {
-    this._dispatch([this.enabledDenominations, 0x3f, 0x10])
+    this.pendingAction = 'stack'
+    this.poll()
   }
 
-  /** Reject/return the bill currently in escrow */
+  /** Latch "return the escrowed note"; re-asserted each poll until it takes. */
   reject(): void {
-    this._dispatch([this.enabledDenominations, 0x5f, 0x10])
+    this.pendingAction = 'return'
+    this.poll()
   }
 
   /** Send initial setup command (disable all, reset state) */
   reset(): void {
+    this.pendingAction = 'none'
     this._dispatch([0x00, 0x1b, 0x10])
   }
 
@@ -470,7 +492,13 @@ export class EbdsRs232 extends EventEmitter {
       validatePacket(packet)
       const result = interpret(packet)
       if (result) {
-        if (result.destructedData) this._logStatusOnChange(result.destructedData)
+        if (result.destructedData) {
+          // Clear a latched stack/return once the device has left escrow — it
+          // is now stacking/returning/idle, so we must stop asserting the
+          // action or it would leak onto the next note.
+          if (!result.destructedData[0].escrowed) this.pendingAction = 'none'
+          this._logStatusOnChange(result.destructedData)
+        }
         this.emit('message', result)
       }
     } catch (ex) {

From eafdce36b6627ae48946238fbcc4c141b4949762 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Thu, 30 Jul 2026 00:57:48 +0200
Subject: [PATCH 57/82] fix(config): point batm3 validator at /dev/ttyMEI (was
 nonexistent ttyACM0)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The batm3 preset defaulted the EBDS validator to /dev/ttyACM0, assuming a
CDC-ACM BNR Advance. The actual MEI acceptor enumerates as a USB-serial
device (ttyUSB*), exposed via the stable udev symlink /dev/ttyMEI
(batm3.nix). Because /dev/ttyACM0 never existed, hal-service skipped the
validator entirely and logged "[HAL] No validator — cash-in disabled", so
Buy Bitcoin silently ignored inserted bills.

Verified on hardware: with the correct device the validator starts, and
(with the EBDS latch fix) a bill escrows → stacks → credits. Removes the
need for the VITE_LAMASSU_VALIDATOR_DEVICE=/dev/ttyMEI per-box override.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/config/device.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/apps/machine/src/config/device.ts b/apps/machine/src/config/device.ts
index 9a22ab8..ae4ac00 100644
--- a/apps/machine/src/config/device.ts
+++ b/apps/machine/src/config/device.ts
@@ -139,7 +139,12 @@ export const MACHINE_PRESETS: Record<MachineModel, Omit<DeviceConfig, 'fiatCode'
     model: 'batm3',
     validator: {
       type: 'ebds',
-      device: '/dev/ttyACM0',
+      // MEI bill acceptor (EBDS) on a USB-serial bridge, exposed via the
+      // stable udev symlink /dev/ttyMEI (batm3.nix, serial A9YW78OC). The old
+      // /dev/ttyACM0 default assumed a CDC-ACM BNR; this hardware enumerates as
+      // ttyUSB* instead, so ACM0 never existed and cash-in was silently
+      // disabled ("[HAL] No validator"). Per-box override: VITE_LAMASSU_VALIDATOR_DEVICE.
+      device: '/dev/ttyMEI',
     },
     dispenser: {
       type: 'f56',

From 2c71d9d823a1c25a2e4e54e8daba37eb9044f0c2 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Thu, 30 Jul 2026 01:14:11 +0200
Subject: [PATCH 58/82] fix(config): use stable /dev/ttyF56 symlink for batm3
 dispenser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The batm3 dispenser used the raw /dev/ttyUSB0, which is
enumeration-order dependent — a re-plug or reboot could reassign
ttyUSB0 to a different adapter. Switch to the stable udev symlink
/dev/ttyF56 (batm3.nix, serial DDDLb103Y23), matching the validator's
/dev/ttyMEI, so both peripherals bind by identity and survive
re-enumeration (incl. on an internal-SATA flash). Per-box override:
VITE_LAMASSU_DISPENSER_DEVICE.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/config/device.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/apps/machine/src/config/device.ts b/apps/machine/src/config/device.ts
index ae4ac00..cffdaa3 100644
--- a/apps/machine/src/config/device.ts
+++ b/apps/machine/src/config/device.ts
@@ -148,7 +148,12 @@ export const MACHINE_PRESETS: Record<MachineModel, Omit<DeviceConfig, 'fiatCode'
     },
     dispenser: {
       type: 'f56',
-      device: '/dev/ttyUSB0',
+      // Fujitsu F56 on a USB-serial bridge, via the stable udev symlink
+      // /dev/ttyF56 (batm3.nix, serial DDDLb103Y23). Avoids the raw
+      // /dev/ttyUSB0, which is enumeration-order dependent and could point at
+      // the wrong adapter after a re-plug/reboot. Per-box override:
+      // VITE_LAMASSU_DISPENSER_DEVICE.
+      device: '/dev/ttyF56',
       cassettes: [
         { denomination: 20, count: 400 },
         { denomination: 1, count: 400 },

From 6edcb8b96dafbbe8dc16f57fcd74d19fa92044af Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 29 Jul 2026 17:47:00 +0200
Subject: [PATCH 59/82] feat(deploy): USB-bootable batm3 test image
 (disk-image-batm3-usb)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a USB-bootable BATM3 disk-image target plus the batm3 hardware
changes that make a dd'd USB stick boot reliably on the Dell 9030 AIO.

flake.nix — new `disk-image-batm3-usb` target:
- Distinct partition labels (nixos-usb / ESP-USB) so stage-1 by-label
  resolution can't latch onto an internal SATA drive that already holds
  a generic nixos/ESP-labelled install. Post-build mlabel relabels the
  ESP FAT volume to ESP-USB (bootloader files untouched; UEFI still
  loads /EFI/BOOT/BOOTX64.EFI).
- /boot mounted nofail + short device-timeout: the firmware already
  loaded the bootloader before Linux; without nofail a slow/late ESP-USB
  enumeration drops to emergency mode with root locked — a dead end.
- NO growPartition/autoResize on the USB image: sfdisk rewriting the
  partition table on first boot is the single most bus-stressing write,
  and flaky USB bridges drop off the bus mid-rewrite (sfdisk wedges in
  uninterruptible D-state and ESP-USB vanishes with the device, so /boot
  times out too). Persistent state is a few MB and the image already
  ships ~2GB free in root. The internal-SATA disk-image-batm3 keeps
  growPartition — a real AHCI SSD won't drop the bus.
- autoUpgrade off (test image, not a managed fleet member).

batm3.nix — USB-boot reliability:
- Add usb_storage to initrd.availableKernelModules so stage-1 binds the
  stick and /dev/disk/by-label/* appears.
- Blacklist uas + usbcore.autosuspend=-1: force the slower-but-reliable
  Bulk-Only Transport path and stop the boot medium being power-suspended
  mid-I/O — both were causing "device offline error" bus drops.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/hardware/batm3.nix | 17 ++++++++
 flake.nix                       | 77 +++++++++++++++++++++++++++++++++
 2 files changed, 94 insertions(+)

diff --git a/deploy/nixos/hardware/batm3.nix b/deploy/nixos/hardware/batm3.nix
index 2a83f2d..ce8e1fe 100644
--- a/deploy/nixos/hardware/batm3.nix
+++ b/deploy/nixos/hardware/batm3.nix
@@ -17,8 +17,22 @@
       "ahci"
       "usbhid"
       "sd_mod"
+      # USB mass-storage: required to boot the dd'd image from a USB stick
+      # (stage-1 must bind the flash drive as a SCSI disk so
+      # /dev/disk/by-label/nixos appears). Harmless on the internal-SATA
+      # install, where ahci+sd_mod already cover the root device.
+      #
+      # NOTE: deliberately NO "uas" here. Many USB sticks/bridges advertise
+      # UAS but drop off the bus ("device offline error, dev sdb") under the
+      # sustained write load of first-boot growPartition/journal/swapfile.
+      # Blacklisting uas below forces the slower-but-reliable usb-storage
+      # (Bulk-Only Transport) path. SATA/eMMC installs don't use uas anyway.
+      "usb_storage"
     ];
 
+    # Keep the USB flash drive off the flaky UAS driver (see note above).
+    blacklistedKernelModules = [ "uas" ];
+
     kernelModules = [
       "kvm-intel"
       "usbtouchscreen"
@@ -27,6 +41,9 @@
     kernelParams = [
       "quiet"
       "splash"
+      # Disable USB autosuspend so the boot medium (and kiosk peripherals)
+      # aren't power-suspended mid-I/O — another cause of "device offline".
+      "usbcore.autosuspend=-1"
     ];
   };
 
diff --git a/flake.nix b/flake.nix
index 3aa61e9..3fe1bba 100644
--- a/flake.nix
+++ b/flake.nix
@@ -424,6 +424,83 @@
               printf 'verify ESP label: '; mlabel -i "$out/nixos.img@@$espStart" -s :: || true
             '';
 
+        # USB-bootable BATM3 TEST image with DISTINCT partition labels
+        # (nixos-usb / ESP-USB). The plain disk-image-batm3 reuses the generic
+        # nixos/ESP labels, so a USB stick carrying it, booted on a batm3 whose
+        # internal SATA drive ALREADY holds a nixos/ESP-labelled install, makes
+        # stage-1's by-label/nixos resolve to the internal drive (larger fs,
+        # journal recovers) instead of the stick — the stage-2 init path baked
+        # into the USB's boot entry isn't on that root, so stage 1 aborts.
+        # Distinct labels make stage-1 pick the stick unambiguously WITHOUT
+        # touching the internal drive. Unlike disk-image-sintra-usb this keeps
+        # systemd-boot: the batm3 firmware UEFI-USB-boots fine via the ESP's
+        # /EFI/BOOT/BOOTX64.EFI removable fallback, so no GRUB/hybrid-table
+        # change is needed — only the label disambiguation here plus the
+        # usb_storage/uas initrd modules (in batm3.nix). Does NOT grow to fill
+        # the stick (see the growPartition note below — sfdisk on first boot
+        # wedges flaky USB bridges); auto-upgrade off (test image, not a managed
+        # fleet member — also stops scheduled bootloader writes landing on the
+        # internal drive's ESP).
+        disk-image-batm3-usb =
+          let
+            cfg = self.nixosConfigurations.batm3-installed.extendModules {
+              modules = [
+                ({ lib, ... }: {
+                  fileSystems."/".device = lib.mkForce "/dev/disk/by-label/nixos-usb";
+                  fileSystems."/boot".device = lib.mkForce "/dev/disk/by-label/ESP-USB";
+                  # /boot must NOT be a hard boot dependency on the USB test
+                  # image. The firmware already loaded the bootloader from the
+                  # ESP before Linux started; /boot is only remounted so the OS
+                  # can *update* the bootloader — which this image never does
+                  # (autoUpgrade off, no nixos-rebuild on the stick). Without
+                  # nofail, a slow/late ESP-USB enumeration (BOT is slower than
+                  # UAS) blows past systemd's 90s device-timeout and drops to
+                  # emergency mode — with root locked, an unrecoverable dead end.
+                  # nofail + a short timeout lets the (already-mounted) root carry
+                  # the boot to completion; /boot mounts if/when the ESP shows up.
+                  fileSystems."/boot".options = [ "nofail" "x-systemd.device-timeout=10s" ];
+                  # DELIBERATELY NO growPartition/autoResize on the USB image.
+                  # growPartition runs sfdisk to rewrite the stick's partition
+                  # table on first boot — the single most bus-stressing write of
+                  # the boot. Flaky USB bridges drop off the bus mid-rewrite
+                  # (sfdisk hangs forever as an uninterruptible D-state task) and,
+                  # worse, partition 1 (ESP-USB) vanishes with the device, so
+                  # /boot times out too. The kiosk's persistent state (state.db,
+                  # .env, wifi.conf, logs) is a few MB and the built image already
+                  # carries ~2GB free inside root — growing to fill the stick buys
+                  # nothing and costs reliability. The internal-SATA target
+                  # (disk-image-batm3) keeps growPartition: a real AHCI SSD won't
+                  # drop the bus and there filling the disk is worth it.
+                  system.autoUpgrade.enable = lib.mkForce false;
+                })
+              ];
+            };
+            baseImage = import (nixpkgs + "/nixos/lib/make-disk-image.nix") {
+              inherit pkgs lib;
+              config = cfg.config;
+              format = "raw";
+              partitionTableType = "efi";
+              diskSize = "auto";
+              label = "nixos-usb"; # ext4 root label (make-disk-image -L)
+            };
+          in
+          pkgs.runCommand "nixos-disk-image-batm3-usb"
+            { nativeBuildInputs = [ pkgs.parted pkgs.mtools ]; }
+            ''
+              mkdir -p $out
+              cp --sparse=always ${baseImage}/nixos.img $out/nixos.img
+              chmod +w $out/nixos.img
+              # make-disk-image hardcodes the ESP FAT label to "ESP"; relabel the
+              # volume to ESP-USB so /boot (by-label/ESP-USB) can't resolve to an
+              # internal drive's ESP. Volume label only — bootloader files are
+              # untouched, and UEFI loads /EFI/BOOT/BOOTX64.EFI regardless.
+              espStart=$(parted -sm "$out/nixos.img" unit B print | awk -F: '$1==1 {gsub("B","",$2); print $2}')
+              echo "ESP partition starts at byte $espStart — relabelling to ESP-USB"
+              export MTOOLS_SKIP_CHECK=1
+              mlabel -i "$out/nixos.img@@$espStart" ::ESP-USB
+              printf 'verify ESP label: '; mlabel -i "$out/nixos.img@@$espStart" -s :: || true
+            '';
+
         # Backwards compat
         iso = self.nixosConfigurations.douro.config.system.build.isoImage;
       };

From f52d942e577be41c16a1db58eb7652f159698aeb Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 29 Jul 2026 17:48:53 +0200
Subject: [PATCH 60/82] fix(deploy): eGalax touchscreen on batm3 (kernel 6.6 +
 calibration)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Dell 9030 AIO's built-in eGalax SAW panel (0eef:0001) was unusable:
touches either didn't register or landed in the wrong place. Full fix:

- Pin linuxPackages_6_6. On 25.11's default 6.12 kernel hid-multitouch
  grabs the controller and mis-parses its HID report (axes read stuck)
  and usbtouchscreen refuses to bind. On 6.6 usbtouchscreen binds and
  produces a clean single-touch ABS device (the known-good internal-SATA
  install runs 6.6.68). Mirrors douro.nix's per-hardware kernel pin.

- udev rule now modprobes usbtouchscreen ITSELF before unbinding usbhid
  and handing over via new_id. On a USB boot systemd-udev-trigger fires
  this rule (~2s) before systemd-modules-load loads usbtouchscreen
  (~12s), so new_id previously hit a not-yet-loaded driver and the panel
  bound to nothing. Loading it inline removes the boot-ordering race.

- Add an X evdev InputClass (99-egalax.conf) so X uses evdev + the
  transformation matrix rather than libinput. Mirrors the working
  internal-SATA install.

- egalax-calibrate: add XAUTHORITY (=/home/bitspire/.Xauthority) — the
  actual boot-time bug. Without the auth cookie xinput died with
  "Invalid MIT-MAGIC-COOKIE-1 key / Unable to connect to X server", so
  the coordinate-transformation matrix was never applied and touches
  landed in the wrong place. Also replace the fixed ExecStartPre sleep
  with a 30s retry loop on the eGalax X device appearing — more robust
  to boot timing than a race against display-manager.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/hardware/batm3.nix | 70 +++++++++++++++++++++++++++++----
 1 file changed, 62 insertions(+), 8 deletions(-)

diff --git a/deploy/nixos/hardware/batm3.nix b/deploy/nixos/hardware/batm3.nix
index ce8e1fe..a92159e 100644
--- a/deploy/nixos/hardware/batm3.nix
+++ b/deploy/nixos/hardware/batm3.nix
@@ -12,6 +12,15 @@
       timeout = 3;
     };
 
+    # Pin the 6.6 LTS kernel. The Dell 9030 AIO's eGalax SAW touch panel
+    # (0eef:0001) works with the usbtouchscreen driver on 6.6 (the known-good
+    # internal-SATA install runs 6.6.68). On 25.11's default 6.12 kernel this
+    # old controller regressed: hid-multitouch grabs it and mis-parses the HID
+    # report ("failed to fetch feature 7", axes read stuck), usbtouchscreen
+    # refuses it, and touch is unusable regardless of udev/X config. Matching
+    # douro.nix's per-hardware kernel pin. Re-test touch before bumping this.
+    kernelPackages = pkgs.linuxPackages_6_6;
+
     initrd.availableKernelModules = [
       "xhci_pci"
       "ahci"
@@ -122,10 +131,20 @@
   '';
 
   # eGalax touchscreen (Dell 9030 AIO built-in panel)
-  # The eGalax HID descriptor confuses libinput (treats it as touchpad).
-  # Fix: unbind from usbhid at boot, bind to usbtouchscreen kernel module,
-  # then apply calibration matrix after X11 starts.
-  # Unbind eGalax from usbhid, bind to usbtouchscreen
+  # By default usbhid/hid-multitouch claim the eGalax and mis-parse its
+  # HID report descriptor (X axis reads as stuck), so touch is unusable.
+  # Fix: hand the device to the usbtouchscreen kernel driver, which parses
+  # the raw eGalax protocol into a clean single-touch ABS device that the
+  # X evdev driver + calibration matrix (below) map correctly. This mirrors
+  # the known-good internal-SATA install.
+  #
+  # The RUN command modprobes usbtouchscreen ITSELF before unbinding usbhid
+  # and handing over via new_id. usbtouchscreen is also in boot.kernelModules
+  # (systemd-modules-load), but on a USB boot systemd-udev-trigger fires this
+  # rule (~2s) BEFORE modules-load gets usbtouchscreen in (~12s) — so the
+  # new_id write hit a not-yet-loaded driver and the panel was left bound to
+  # nothing. Loading it inline here makes the handoff independent of that
+  # boot-ordering race (on internal-SATA boot the order happened to work).
   services.udev.extraRules = lib.mkAfter ''
     KERNEL=="ttyS[0-9]*", MODE="0666"
     KERNEL=="ttyUSB[0-9]*", MODE="0666"
@@ -133,7 +152,25 @@
     SUBSYSTEM=="tty", ATTRS{serial}=="DDDLb103Y23", SYMLINK+="ttyF56", MODE="0666"
     SUBSYSTEM=="tty", ATTRS{serial}=="A9YW78OC", SYMLINK+="ttyMEI", MODE="0666"
     SUBSYSTEM=="tty", ATTRS{serial}=="A9ZF8ELY", SYMLINK+="ttyNFC", MODE="0666"
-    ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0eef", ATTRS{idProduct}=="0001", RUN+="${pkgs.bash}/bin/bash -c 'echo ''$kernel:1.0 > /sys/bus/usb/drivers/usbhid/unbind 2>/dev/null; echo 0eef 0001 > /sys/bus/usb/drivers/usbtouchscreen/new_id 2>/dev/null'"
+    ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0eef", ATTRS{idProduct}=="0001", RUN+="${pkgs.bash}/bin/bash -c '${pkgs.kmod}/bin/modprobe usbtouchscreen 2>/dev/null; echo ''$kernel:1.0 > /sys/bus/usb/drivers/usbhid/unbind 2>/dev/null; echo 0eef 0001 > /sys/bus/usb/drivers/usbtouchscreen/new_id 2>/dev/null'"
+  '';
+
+  # Force the X evdev driver on the eGalax (not libinput). The usbtouchscreen
+  # node is a plain single-touch absolute device; evdev + the transformation
+  # matrix in egalax-calibrate below give correct orientation. Mirrors the
+  # working internal-SATA install's /etc/X11/xorg.conf.d/99-egalax.conf.
+  environment.etc."X11/xorg.conf.d/99-egalax.conf".text = ''
+    Section "InputClass"
+        Identifier "eGalax Touchscreen"
+        MatchVendor "0eef"
+        MatchProduct "0001"
+        MatchDevicePath "/dev/input/event*"
+        Driver "evdev"
+        Option "InvertY" "false"
+        Option "InvertX" "false"
+        Option "SwapAxes" "false"
+        Option "Calibration" ""
+    EndSection
   '';
 
   # Apply touchscreen calibration after X11 starts
@@ -147,9 +184,26 @@
       Type = "oneshot";
       RemainAfterExit = true;
       User = "bitspire";
-      Environment = "DISPLAY=:0";
-      ExecStartPre = "${pkgs.coreutils}/bin/sleep 3";
-      ExecStart = "${pkgs.xorg.xinput}/bin/xinput set-prop 'eGalax Inc. USB TouchController' 'Coordinate Transformation Matrix' 0 -1.268 1.147 -1.224 0 1.118 0 0 1";
+      # DISPLAY *and* XAUTHORITY — without the auth cookie xinput dies with
+      # "Invalid MIT-MAGIC-COOKIE-1 key / Unable to connect to X server" and
+      # the matrix is never applied, so touches register but land in the wrong
+      # place (the panel then feels dead). This was the actual boot-time bug.
+      Environment = [ "DISPLAY=:0" "XAUTHORITY=/home/bitspire/.Xauthority" ];
+      # Wait for the eGalax X device to appear (usbtouchscreen binds a little
+      # after display-manager on a USB boot) and retry, instead of a fixed
+      # sleep — more robust to boot timing. Matrix: swap X/Y + invert + scale
+      # to the active panel area (matches the known-good internal install).
+      ExecStart = pkgs.writeShellScript "egalax-calibrate" ''
+        for i in $(${pkgs.coreutils}/bin/seq 1 30); do
+          if ${pkgs.xorg.xinput}/bin/xinput list --name-only 2>/dev/null | ${pkgs.gnugrep}/bin/grep -qx 'eGalax Inc. USB TouchController'; then
+            exec ${pkgs.xorg.xinput}/bin/xinput set-prop 'eGalax Inc. USB TouchController' \
+              'Coordinate Transformation Matrix' 0 -1.268 1.147 -1.224 0 1.118 0 0 1
+          fi
+          ${pkgs.coreutils}/bin/sleep 1
+        done
+        echo "egalax-calibrate: eGalax device not found after 30s" >&2
+        exit 1
+      '';
     };
   };
 

From 8fbe6df5c338017ebf938e89d61371a548f5b20d Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Thu, 30 Jul 2026 02:36:46 +0200
Subject: [PATCH 61/82] fix(lightning): cash-in double-charged commission (send
 gross, not net)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Buy Bitcoin short-changed the customer: a $5 buy at 1564 sats/USD with a
12% commission paid out 6056 sats instead of 6882 — an effective ~22.6%.
The commission was applied twice.

`calculateSats` already subtracts the fee (7820 gross → 6882 net) into
`context.satsAmount`. But `generateLnurlWithdraw` then passed that
already-net value as `principal_sats` to the server's create_withdraw,
which derives fee + net from the principal and subtracted 12% AGAIN:

  [ATM Service] create_withdraw: principal=6882 fee=826 net=6056

This contradicted the function's own contract ("the ATM sends only the
hardware-attested gross principal; the operator side derives fee + NET").
The quote, the recorded transaction (sats=6882, fee_fraction=0.12), and
the on-screen commission (12%) all read a single fee — only the delivered
LNURL-withdraw amount was double-charged.

Fix: send the GROSS principal (fiat × rate, before commission), so the
server applies the fee exactly once. Now 7820 → server 12% → net 6882,
matching the quote/receipt. Exchange rate itself was always correct.

Verified: vue-tsc typechecks; math checks (gross=7820 fee=938 net=6882).
Hardware retest (one $5 buy → 6882) recommended before relying in prod.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/services/lightning.ts | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index 4eca3e2..eb2e1c7 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -725,7 +725,17 @@ function createATMServices(
      *    over nostr, we trigger dispense.
      */
     generateLnurlWithdraw: async (context: ATMContext): Promise<string> => {
-      console.log('[ATM Service] Generating LNURL-withdraw for', context.satsAmount, 'sats')
+      // GROSS principal (fiat × rate, BEFORE commission). The server derives
+      // fee + NET from this, so we must NOT send the already-fee'd
+      // context.satsAmount — doing so double-applies the commission (client
+      // subtracts it in calculateSats, then the server subtracts it again,
+      // e.g. 12% → 22.6% effective; the customer is short-changed while the
+      // quote/receipt still read 12%). Mirror calculateSats's principal.
+      const grossPrincipalSats = Math.floor((context.fiatCents / 100) * context.exchangeRate)
+      console.log(
+        `[ATM Service] Generating LNURL-withdraw: gross principal=${grossPrincipalSats} sats ` +
+          `(net after ${(context.feeFraction * 100).toFixed(2)}% ≈ ${context.satsAmount})`
+      )
 
       try {
         if (context.cashInSessionId) {
@@ -738,7 +748,7 @@ function createATMServices(
         // the amount or extra. We display the returned LNURL (for NET) and
         // watch link_id for settlement.
         const link = await lnbits.createWithdraw(lnbitsWalletId, {
-          principal_sats: context.satsAmount,
+          principal_sats: grossPrincipalSats,
           fiat_amount: context.fiatCents / 100,
           fiat_code: context.currency,
           title: `bitSpire Cash-In ${context.cashInSessionId?.slice(0, 8) || 'session'}`,

From 44f5c0dbcf4ac4b9edde895cbcb646ee6c504b9c Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Tue, 4 Aug 2026 18:11:40 +0200
Subject: [PATCH 62/82] =?UTF-8?q?docs(adr):=20amend=20ADR-002=20=E2=80=94?=
 =?UTF-8?q?=20app=20recovery=20is=20first-line,=20SSH/NetBird=20last-resor?=
 =?UTF-8?q?t?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The access/recovery plane (SSH/NetBird) stands and may carry recovery
procedures, but it is explicitly NOT the only or first-line recovery. Add
a layered, cheapest-first recovery model: (1) app auto-recovery of its own
relay/Lightning connectivity, (2) an on-screen Retry for an operator at the
kiosk, (3) SSH/NetBird as the last-resort remote plane for genuine app/OS
failure. A public kiosk must not need remote shell access to recover from a
transient/boot-before-network outage.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../002-remote-access-and-fleet-management.md | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/docs/adr/002-remote-access-and-fleet-management.md b/docs/adr/002-remote-access-and-fleet-management.md
index 4931daa..a518930 100644
--- a/docs/adr/002-remote-access-and-fleet-management.md
+++ b/docs/adr/002-remote-access-and-fleet-management.md
@@ -104,6 +104,36 @@ The only honest way for a machine operator to exclude the SaaS operator is to **
 - The machine operator's Nostr key can become the single root of trust across all three planes — SSH `authorized_keys` + VPN enrollment at install, `AddOperator`/`RevokeOperator` (#42) for delegation — so granting/revoking any party (including the SaaS operator) is one scoped, revocable capability model.
 - `sshd` posture should be tightened to key-only for deployed boxes (password auth is currently forced on for installed configs for first-boot provisioning; scope it to the LAN/first-boot window). Tracks with [#51](https://git.atitlan.io/aiolabs/bitspire/issues/51).
 
+## Amendment (2026-08-04): the access/recovery plane is not the *only* recovery
+
+**Status:** Accepted · **Context:** the ATM app had no way to recover its own
+connectivity — a machine that booted with no internet (or whose init otherwise
+failed) sat on "ATM Unavailable" until a manual `systemctl restart bitspire`,
+even after the network came back.
+
+This ADR's SSH/NetBird recovery plane stands — it is the operator's
+**app-and-OS-independent** path for the unanticipated and the broken, and may
+carry recovery *procedures* (restart the service, inspect logs, re-provision).
+But it is explicitly **not the first-line and not the only recovery method.**
+Recovery is layered, cheapest-first:
+
+1. **App auto-recovery (first-line, no human).** The ATM app recovers its own
+   relay/Lightning connectivity when possible: the nostr client already
+   reconnects with backoff, and the app now re-initializes when connectivity
+   returns (a fresh renderer reload — HAL is preserved in the main process),
+   so "internet came back" self-heals without anyone touching the machine.
+2. **On-screen manual retry (operator at the machine).** The maintenance
+   ("ATM Unavailable") screen carries a **Retry** button so a person standing
+   at the kiosk can force an immediate recovery attempt without shell access.
+3. **SSH/NetBird (operator remote, last resort).** This plane — for when the
+   app *can't* self-heal or the box is genuinely broken. Unchanged by this
+   amendment beyond the reframing: it is the floor, not the front line.
+
+Rationale: the common failure (transient network / boot-before-network) must
+not require remote shell access to a public kiosk. Reserve the heavyweight
+recovery plane for genuine app/OS failure. Implemented on branch
+`feat/connection-recovery`.
+
 ## References
 
 - [#41](https://git.atitlan.io/aiolabs/bitspire/issues/41) — Multi-location deployment: runtime site config (the access plane's per-machine identity is provisioned here, not baked into the closure).

From 6a833d357e1675bd6d933afa3125d0dd82e007ba Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Tue, 4 Aug 2026 18:11:40 +0200
Subject: [PATCH 63/82] feat(machine): connectivity auto-recovery + on-screen
 Retry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A connectivity-type init failure (e.g. "No connected relays" when the box
boots before the network) landed on "ATM Unavailable" permanently: init is
one-shot and the nostr reconnect only helps after a first successful
connect, so a machine never self-healed when internet returned.

Recover by reloading the renderer, which re-runs init from a clean JS
context (no leaked actors/subscriptions) while the main process keeps HAL:
- main.ts: new `app:recover` IPC → reloadRenderer() (resets secretsConsumed).
- hal:init is now idempotent (reuse the existing instance) so the reload —
  and the pre-existing watchdog crash-reload — can't double-open serial ports.
- App.vue: when initError is a connectivity type (not the operator/
  self-clearing states unpaired/awaiting-fees/maintenance), watch for the
  `online` event (recover immediately) plus a 45s backoff safety net, and
  render a kiosk-sized Retry button for a person at the machine.

Preserves pairing + /var/lib state (renderer reload, not a process restart).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/main.ts        | 22 ++++++++
 apps/machine/electron/preload.ts     |  3 ++
 apps/machine/src/App.vue             | 78 +++++++++++++++++++++++++++-
 apps/machine/src/types/electron.d.ts |  2 +
 4 files changed, 104 insertions(+), 1 deletion(-)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index fc48d87..ac31a6a 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -404,6 +404,17 @@ ipcMain.handle('app:relaunch', (): void => {
   app.exit(0)
 })
 
+// Connectivity recovery: reload the renderer to re-run init from a clean slate
+// (fresh JS context → no leaked actors/subscriptions), while preserving HAL in
+// this main process (reloadRenderer resets secretsConsumed so get-atm-secrets
+// works again, and hal:init is idempotent). The renderer calls this when it's
+// stuck on a connectivity-type "ATM Unavailable" and the network returns, or
+// when the operator taps the on-screen Retry (ADR-002 amendment 2026-08-04).
+ipcMain.handle('app:recover', (): void => {
+  console.log('[Recovery] Reloading renderer to re-attempt initialization')
+  reloadRenderer()
+})
+
 // State persistence IPC handlers
 ipcMain.handle('state:load-cassettes', () => loadCassettes())
 ipcMain.handle('state:set-cassettes', (_event, cassettes) => setCassettes(cassettes))
@@ -480,6 +491,17 @@ let pendingBillDenomination: number | null = null
 
 ipcMain.handle('hal:init', async (_event, config) => {
   try {
+    // Idempotent: HAL lives in this (long-lived) main process, but the renderer
+    // re-runs full init on every reload — the watchdog's crash-recovery reload
+    // and the connectivity-recovery reload (app:recover) both re-invoke this.
+    // initializeHal opens serial ports without closing prior handles, so
+    // re-entering it would double-open the validator/dispenser. Reuse the
+    // existing instance instead; its validator event wiring already targets the
+    // (reloaded) mainWindow, so the reloaded renderer keeps receiving bill events.
+    if (halInstance) {
+      console.log('[Electron] HAL already initialized — reusing existing instance')
+      return { success: true }
+    }
     // Override cassette config with DB values (operator may have changed them via atm-tui
     // or via an operator-config publish from satmachineadmin). Pass per-position so the
     // HAL knows about every bay including duplicates of the same denomination — real
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index a811eab..41c54df 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -124,6 +124,8 @@ contextBridge.exposeInMainWorld('electronAPI', {
   // then relaunch so the normal boot flow pairs it.
   saveSpireSeed: (seed: string): Promise<void> => ipcRenderer.invoke('state:save-spire-seed', seed),
   relaunchApp: (): Promise<void> => ipcRenderer.invoke('app:relaunch'),
+  // Reload the renderer to re-attempt initialization (connectivity recovery).
+  recoverApp: (): Promise<void> => ipcRenderer.invoke('app:recover'),
 
   applyOperatorCassettesConfig: (
     payload: {
@@ -243,6 +245,7 @@ declare global {
       resetForRepair: () => Promise<void>
       saveSpireSeed: (seed: string) => Promise<void>
       relaunchApp: () => Promise<void>
+      recoverApp: () => Promise<void>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number
diff --git a/apps/machine/src/App.vue b/apps/machine/src/App.vue
index 2b89eb7..d9bce92 100644
--- a/apps/machine/src/App.vue
+++ b/apps/machine/src/App.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { onMounted, onUnmounted, ref, computed } from 'vue'
+import { onMounted, onUnmounted, ref, computed, watch } from 'vue'
 import { useRoute } from 'vue-router'
 import { useAtmStore } from '@/stores/atm'
 import { useTheme } from '@/composables/useTheme'
@@ -158,8 +158,71 @@ onMounted(async () => {
 
 onUnmounted(() => {
   atmStore.stopPricePolling()
+  stopRecoveryWatch()
 })
 
+// ── Connectivity recovery (ADR-002 amendment 2026-08-04) ──────────────────
+// A connectivity-type init failure lands on "ATM Unavailable" and, without
+// this, stays there forever (init is one-shot; the nostr reconnect only helps
+// AFTER a first successful connect). We recover by reloading the renderer —
+// which re-runs this whole init from a clean JS context while the main process
+// keeps HAL (see main.ts app:recover). Not for the operator/self-clearing
+// states: `unpaired` shows the pairing wizard, `awaiting-fees` clears itself on
+// the operator's fee-config event, `maintenance` is operator-set.
+const NON_RECOVERABLE = new Set(['maintenance', 'awaiting-fees', 'unpaired'])
+const isRecoverable = computed(
+  () => !!atmStore.initError && !NON_RECOVERABLE.has(atmStore.initError)
+)
+const recovering = ref(false)
+const RECOVERY_RETRY_MS = 45_000
+let recoveryTimer: ReturnType<typeof setInterval> | null = null
+
+function triggerRecovery() {
+  if (recovering.value) return
+  recovering.value = true
+  console.log('[App] Attempting connectivity recovery (renderer reload)')
+  if (window.electronAPI?.recoverApp) {
+    void window.electronAPI.recoverApp() // main reloads renderer → fresh init
+  } else {
+    location.reload() // browser-dev fallback
+  }
+}
+
+function onOnline() {
+  // Network came back — recover immediately rather than waiting for the timer.
+  triggerRecovery()
+}
+
+function startRecoveryWatch() {
+  stopRecoveryWatch()
+  window.addEventListener('online', onOnline)
+  // Safety net for the online-but-relay-unreachable case (navigator.onLine only
+  // reflects a local route, not relay reachability).
+  recoveryTimer = setInterval(triggerRecovery, RECOVERY_RETRY_MS)
+}
+
+function stopRecoveryWatch() {
+  window.removeEventListener('online', onOnline)
+  if (recoveryTimer !== null) {
+    clearInterval(recoveryTimer)
+    recoveryTimer = null
+  }
+}
+
+/** Operator-facing "Retry" button on the maintenance screen. */
+function retryNow() {
+  triggerRecovery()
+}
+
+watch(
+  isRecoverable,
+  (recoverable) => {
+    if (recoverable) startRecoveryWatch()
+    else stopRecoveryWatch()
+  },
+  { immediate: true }
+)
+
 function toggleLiveServices() {
   if (atmStore.useLiveServices) {
     // Switch to mock
@@ -211,6 +274,19 @@ function toggleLiveServices() {
       >
         {{ atmStore.initError }}
       </p>
+
+      <!-- Manual recovery for a connectivity failure; auto-recovery also runs
+           in the background (online event + backoff). Not shown for operator/
+           self-clearing states (maintenance / awaiting-fees / unpaired). -->
+      <Button
+        v-if="isRecoverable"
+        size="kiosk"
+        :disabled="recovering"
+        class="mt-4"
+        @click="retryNow"
+      >
+        {{ recovering ? 'Retrying…' : 'Retry' }}
+      </Button>
     </div>
 
     <template v-else>
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index b018a39..4c8faa8 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -101,6 +101,8 @@ declare global {
       resetForRepair: () => Promise<void>
       saveSpireSeed: (seed: string) => Promise<void>
       relaunchApp: () => Promise<void>
+      /** Reload the renderer to re-attempt initialization (connectivity recovery). */
+      recoverApp: () => Promise<void>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number

From f8f20371008daf3acbe5ece16970042b6c482afc Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Tue, 4 Aug 2026 18:49:59 +0200
Subject: [PATCH 64/82] refactor(deploy): expose batm3-usb as a named
 nixosConfiguration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lift the USB-variant config (distinct fs labels, nofail /boot, no
growPartition, autoUpgrade off) out of the inline disk-image-batm3-usb
`let` into `nixosConfigurations.batm3-usb`, and build the disk-image from
that same config. Enables in-place app deploys to a running stick via
`nix copy` + `switch-to-configuration` (build the toplevel, copy the
closure, activate) — no reflash, preserving pairing + /var/lib state.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 flake.nix | 68 ++++++++++++++++++++++++++++---------------------------
 1 file changed, 35 insertions(+), 33 deletions(-)

diff --git a/flake.nix b/flake.nix
index 3fe1bba..29f44b1 100644
--- a/flake.nix
+++ b/flake.nix
@@ -292,6 +292,37 @@
         # at ttyJ5, dispenser at ttyJ7 layout) — reuse the same hw module.
         sintra-installed = mkInstalledConfig "sintra" ./deploy/nixos/hardware/upboard.nix;
         batm3-installed = mkInstalledConfig "batm3" ./deploy/nixos/hardware/batm3.nix;
+
+        # USB-bootable variant of batm3-installed. This is the config the
+        # flashed USB stick actually runs — distinct fs labels so stage-1 can't
+        # latch the internal drive, nofail /boot, no growPartition, autoUpgrade
+        # off. Exposed as a named config (not just inline in the disk-image
+        # target) so its system closure can be built here and deployed in-place
+        # with `nix copy` + `switch-to-configuration` — updating the app on a
+        # running stick WITHOUT reflashing (preserves pairing + /var/lib state).
+        # disk-image-batm3-usb builds its filesystem image from this same config.
+        batm3-usb = self.nixosConfigurations.batm3-installed.extendModules {
+          modules = [
+            ({ lib, ... }: {
+              fileSystems."/".device = lib.mkForce "/dev/disk/by-label/nixos-usb";
+              fileSystems."/boot".device = lib.mkForce "/dev/disk/by-label/ESP-USB";
+              # /boot must NOT be a hard boot dependency on the USB image. The
+              # firmware already loaded the bootloader before Linux; without
+              # nofail, a slow/late ESP-USB enumeration (BOT is slower than UAS)
+              # blows past systemd's 90s device-timeout into emergency mode with
+              # root locked — a dead end. nofail + short timeout lets the
+              # already-mounted root carry the boot; /boot mounts if/when it shows.
+              fileSystems."/boot".options = [ "nofail" "x-systemd.device-timeout=10s" ];
+              # NO growPartition/autoResize: sfdisk rewriting the partition table
+              # on first boot is the single most bus-stressing write, and flaky
+              # USB bridges drop off the bus mid-rewrite (sfdisk wedges in D-state
+              # and ESP-USB vanishes with the device). Persistent state is a few
+              # MB and the image ships ~2GB free. The internal-SATA disk-image-
+              # batm3 keeps growPartition (a real AHCI SSD won't drop the bus).
+              system.autoUpgrade.enable = lib.mkForce false;
+            })
+          ];
+        };
       };
 
       # ── Standalone NixOS module ───────────────────────────────────
@@ -443,41 +474,12 @@
         # internal drive's ESP).
         disk-image-batm3-usb =
           let
-            cfg = self.nixosConfigurations.batm3-installed.extendModules {
-              modules = [
-                ({ lib, ... }: {
-                  fileSystems."/".device = lib.mkForce "/dev/disk/by-label/nixos-usb";
-                  fileSystems."/boot".device = lib.mkForce "/dev/disk/by-label/ESP-USB";
-                  # /boot must NOT be a hard boot dependency on the USB test
-                  # image. The firmware already loaded the bootloader from the
-                  # ESP before Linux started; /boot is only remounted so the OS
-                  # can *update* the bootloader — which this image never does
-                  # (autoUpgrade off, no nixos-rebuild on the stick). Without
-                  # nofail, a slow/late ESP-USB enumeration (BOT is slower than
-                  # UAS) blows past systemd's 90s device-timeout and drops to
-                  # emergency mode — with root locked, an unrecoverable dead end.
-                  # nofail + a short timeout lets the (already-mounted) root carry
-                  # the boot to completion; /boot mounts if/when the ESP shows up.
-                  fileSystems."/boot".options = [ "nofail" "x-systemd.device-timeout=10s" ];
-                  # DELIBERATELY NO growPartition/autoResize on the USB image.
-                  # growPartition runs sfdisk to rewrite the stick's partition
-                  # table on first boot — the single most bus-stressing write of
-                  # the boot. Flaky USB bridges drop off the bus mid-rewrite
-                  # (sfdisk hangs forever as an uninterruptible D-state task) and,
-                  # worse, partition 1 (ESP-USB) vanishes with the device, so
-                  # /boot times out too. The kiosk's persistent state (state.db,
-                  # .env, wifi.conf, logs) is a few MB and the built image already
-                  # carries ~2GB free inside root — growing to fill the stick buys
-                  # nothing and costs reliability. The internal-SATA target
-                  # (disk-image-batm3) keeps growPartition: a real AHCI SSD won't
-                  # drop the bus and there filling the disk is worth it.
-                  system.autoUpgrade.enable = lib.mkForce false;
-                })
-              ];
-            };
+            # Filesystem image of the batm3-usb config (defined in
+            # nixosConfigurations). Same config that in-place deploys target, so
+            # a reflash and a `switch-to-configuration` converge on one system.
             baseImage = import (nixpkgs + "/nixos/lib/make-disk-image.nix") {
               inherit pkgs lib;
-              config = cfg.config;
+              config = self.nixosConfigurations.batm3-usb.config;
               format = "raw";
               partitionTableType = "efi";
               diskSize = "auto";

From 457761719f034c151b4dca6372d7e98f2792c70b Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 04:24:00 +0200
Subject: [PATCH 65/82] feat(machine): LNURL-withdraw executor for Bolt Card
 cash-out (LUD-03)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First, hardware-independent piece of Bolt Card tap-to-pay on the cash-out
flow. When a customer taps a Bolt Card, the ATM (which already has its
cash-out BOLT11) becomes the LNURL-*withdrawing* party: GET the card's
lnurlw voucher → GET callback?k1=…&pr=<invoice> so the card's wallet pays
the invoice. Settlement is still observed via the existing invoice watcher
(a returned ok=true means "card accepted the pull", not "cash dispensed").

- electron/lnurl-withdraw.ts: executeLnurlWithdraw() + lnurlwToHttps().
  Runs in the main process (Node fetch) to avoid renderer CORS, since LNURL
  endpoints send no CORS headers. Fully injectable fetch for testing.
- electron/lnurl-withdraw.test.ts: 12 tests (scheme mapping, two-step happy
  path passing k1+pr, ERROR surfacing, non-withdraw tag, amount-over-limit
  short-circuit, callback decline, network failure).
- IPC `lnurl:withdraw` (main) + preload + electron.d.ts.

Next: pcscd + an nfc-pcsc reader driver (reads the NTAG424 NDEF lnurlw),
then wire the tap into the cashOut displayingInvoice state + "tap or scan" UI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/lnurl-withdraw.test.ts | 103 +++++++++++++++
 apps/machine/electron/lnurl-withdraw.ts      | 127 +++++++++++++++++++
 apps/machine/electron/main.ts                |  15 +++
 apps/machine/electron/preload.ts             |  12 ++
 apps/machine/src/types/electron.d.ts         |   6 +
 5 files changed, 263 insertions(+)
 create mode 100644 apps/machine/electron/lnurl-withdraw.test.ts
 create mode 100644 apps/machine/electron/lnurl-withdraw.ts

diff --git a/apps/machine/electron/lnurl-withdraw.test.ts b/apps/machine/electron/lnurl-withdraw.test.ts
new file mode 100644
index 0000000..4d14611
--- /dev/null
+++ b/apps/machine/electron/lnurl-withdraw.test.ts
@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from 'vitest'
+import { executeLnurlWithdraw, lnurlwToHttps } from './lnurl-withdraw'
+
+const BOLT11 = 'lnbc10u1p3xyz...'
+const LNURLW =
+  'lnurlw://lnbits.l484.com/boltcards/api/v1/scan/abc123?p=DEADBEEFDEADBEEFDEADBEEFDEADBEEF&c=1122334455667788'
+
+/** Build a mock fetch that returns the given JSON bodies per call, in order. */
+function mockFetch(bodies: unknown[]) {
+  const calls: string[] = []
+  const impl = vi.fn(async (url: string | URL) => {
+    calls.push(url.toString())
+    const body = bodies[calls.length - 1]
+    return { json: async () => body } as Response
+  })
+  return { impl: impl as unknown as typeof fetch, calls }
+}
+
+describe('lnurlwToHttps', () => {
+  it('maps lnurlw:// and lnurl:// to https://', () => {
+    expect(lnurlwToHttps('lnurlw://host/p?x=1')).toBe('https://host/p?x=1')
+    expect(lnurlwToHttps('lnurl://host/p')).toBe('https://host/p')
+  })
+  it('strips a lightning: prefix', () => {
+    expect(lnurlwToHttps('lightning:lnurlw://host/p')).toBe('https://host/p')
+  })
+  it('passes https:// through and trims', () => {
+    expect(lnurlwToHttps('  https://host/p  ')).toBe('https://host/p')
+  })
+  it('rejects http://, bech32 lnurl1…, and empty', () => {
+    expect(lnurlwToHttps('http://host/p')).toBeNull()
+    expect(lnurlwToHttps('LNURL1DP68GURN8GHJ7')).toBeNull()
+    expect(lnurlwToHttps('')).toBeNull()
+  })
+})
+
+describe('executeLnurlWithdraw', () => {
+  const withdrawReq = {
+    tag: 'withdrawRequest',
+    callback: 'https://lnbits.l484.com/boltcards/api/v1/scan/cb',
+    k1: 'K1TOKEN',
+    minWithdrawable: 1000,
+    maxWithdrawable: 5_000_000,
+  }
+
+  it('completes the two-step withdraw and passes k1 + pr to the callback', async () => {
+    const { impl, calls } = mockFetch([withdrawReq, { status: 'OK' }])
+    const res = await executeLnurlWithdraw(LNURLW, BOLT11, { fetchImpl: impl })
+    expect(res).toEqual({ ok: true })
+    // First call = the lnurlw as https; second = callback with k1 + pr.
+    expect(calls[0]).toContain('https://lnbits.l484.com/boltcards/api/v1/scan/abc123')
+    expect(calls[1]).toContain('k1=K1TOKEN')
+    expect(calls[1]).toContain(`pr=${encodeURIComponent(BOLT11)}`)
+  })
+
+  it('rejects a non-lnurlw tag', async () => {
+    const { impl } = mockFetch([])
+    const res = await executeLnurlWithdraw('http://nope', BOLT11, { fetchImpl: impl })
+    expect(res.ok).toBe(false)
+    expect(res.reason).toMatch(/not a valid Bolt Card/i)
+  })
+
+  it('rejects when there is no invoice', async () => {
+    const { impl } = mockFetch([])
+    const res = await executeLnurlWithdraw(LNURLW, '', { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'no invoice to charge' })
+  })
+
+  it('surfaces an ERROR from the withdraw request', async () => {
+    const { impl } = mockFetch([{ status: 'ERROR', reason: 'spent today limit' }])
+    const res = await executeLnurlWithdraw(LNURLW, BOLT11, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'spent today limit' })
+  })
+
+  it('rejects a response that is not a withdrawRequest', async () => {
+    const { impl } = mockFetch([{ tag: 'payRequest', callback: 'x' }])
+    const res = await executeLnurlWithdraw(LNURLW, BOLT11, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false })
+    expect(res.reason).toMatch(/withdraw voucher/i)
+  })
+
+  it('rejects (without calling the callback) when the amount exceeds the card limit', async () => {
+    const { impl, calls } = mockFetch([{ ...withdrawReq, maxWithdrawable: 2000 }])
+    const res = await executeLnurlWithdraw(LNURLW, BOLT11, { fetchImpl: impl, amountMsat: 5000 })
+    expect(res).toMatchObject({ ok: false, reason: 'card limit is below this amount' })
+    expect(calls).toHaveLength(1) // callback never hit
+  })
+
+  it('surfaces an ERROR from the callback (card declined)', async () => {
+    const { impl } = mockFetch([withdrawReq, { status: 'ERROR', reason: 'insufficient funds' }])
+    const res = await executeLnurlWithdraw(LNURLW, BOLT11, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'insufficient funds' })
+  })
+
+  it('handles a network failure gracefully', async () => {
+    const impl = vi.fn(async () => {
+      throw new Error('ECONNREFUSED')
+    }) as unknown as typeof fetch
+    const res = await executeLnurlWithdraw(LNURLW, BOLT11, { fetchImpl: impl })
+    expect(res.ok).toBe(false)
+    expect(res.reason).toMatch(/could not reach the card/i)
+  })
+})
diff --git a/apps/machine/electron/lnurl-withdraw.ts b/apps/machine/electron/lnurl-withdraw.ts
new file mode 100644
index 0000000..eb93c08
--- /dev/null
+++ b/apps/machine/electron/lnurl-withdraw.ts
@@ -0,0 +1,127 @@
+/**
+ * LNURL-withdraw executor (LUD-03) — the ATM as the *withdrawing* party.
+ *
+ * Bolt Card tap-to-pay for the cash-out flow: a Bolt Card presents an
+ * `lnurlw://…?p=…&c=…` voucher (NTAG424 SUN — fresh p/c per tap). The ATM has
+ * already generated its cash-out BOLT11; here it asks the card's wallet to pay
+ * that invoice:
+ *   1. GET the lnurlw URL → a `withdrawRequest` (callback, k1, max/min).
+ *   2. GET `callback?k1=…&pr=<our bolt11>` → the card's wallet pays it.
+ * Settlement itself is observed elsewhere (the existing invoice watcher over
+ * nostr), so a returned `{ ok: true }` means "the card accepted the pull", not
+ * "cash dispensed" — the state machine still waits for PAYMENT_RECEIVED.
+ *
+ * Runs in the MAIN process (Node fetch) to avoid renderer CORS: LNURL
+ * endpoints don't send CORS headers, so a renderer fetch to the card's host
+ * would be blocked.
+ */
+
+export interface LnurlWithdrawResult {
+  ok: boolean
+  /** Human-readable reason when ok is false (safe to surface on-screen). */
+  reason?: string
+}
+
+/** LUD-03 withdrawRequest (subset we consume) + LUD-06 error shape. */
+interface WithdrawRequest {
+  tag?: string
+  callback?: string
+  k1?: string
+  minWithdrawable?: number
+  maxWithdrawable?: number
+  defaultDescription?: string
+  status?: string
+  reason?: string
+}
+
+type FetchLike = typeof fetch
+
+export interface ExecuteLnurlWithdrawOptions {
+  /** Injected for tests; defaults to global fetch. */
+  fetchImpl?: FetchLike
+  /**
+   * Our invoice amount in millisats. When set, we reject early if it exceeds
+   * the voucher's maxWithdrawable (defensive; the callback would reject anyway).
+   */
+  amountMsat?: number
+  /** Per-request timeout (default 15s). */
+  timeoutMs?: number
+}
+
+/**
+ * Normalize a Bolt Card / LNURL-withdraw pointer to an https URL.
+ * Bolt Cards emit `lnurlw://host/path?query`; we also accept `lnurl://` and a
+ * bare `https://`. Bech32 `LNURL1…` is intentionally unsupported (Bolt Cards
+ * never use it) and rejected with a clear reason.
+ */
+export function lnurlwToHttps(raw: string): string | null {
+  let s = raw.trim()
+  if (!s) return null
+  if (s.toLowerCase().startsWith('lightning:')) s = s.slice('lightning:'.length)
+  const lower = s.toLowerCase()
+  if (lower.startsWith('lnurlw://')) return 'https://' + s.slice('lnurlw://'.length)
+  if (lower.startsWith('lnurl://')) return 'https://' + s.slice('lnurl://'.length)
+  if (lower.startsWith('https://')) return s
+  // Reject http:// (must be TLS) and bech32 lnurl1… (not a Bolt Card).
+  return null
+}
+
+function appendQuery(url: string, params: Record<string, string>): string {
+  const u = new URL(url)
+  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v)
+  return u.toString()
+}
+
+function errMsg(e: unknown): string {
+  if (e instanceof Error) return e.name === 'TimeoutError' || e.name === 'AbortError' ? 'timed out' : e.message
+  return String(e)
+}
+
+export async function executeLnurlWithdraw(
+  lnurlw: string,
+  bolt11: string,
+  opts: ExecuteLnurlWithdrawOptions = {}
+): Promise<LnurlWithdrawResult> {
+  const doFetch = opts.fetchImpl ?? fetch
+  const timeoutMs = opts.timeoutMs ?? 15_000
+
+  const paramsUrl = lnurlwToHttps(lnurlw)
+  if (!paramsUrl) return { ok: false, reason: 'not a valid Bolt Card (lnurlw) tag' }
+  if (!bolt11 || !/^ln[a-z0-9]/i.test(bolt11.trim())) {
+    return { ok: false, reason: 'no invoice to charge' }
+  }
+
+  // 1) Fetch the withdraw request.
+  let params: WithdrawRequest
+  try {
+    const res = await doFetch(paramsUrl, { signal: AbortSignal.timeout(timeoutMs) })
+    params = (await res.json()) as WithdrawRequest
+  } catch (e) {
+    return { ok: false, reason: `could not reach the card: ${errMsg(e)}` }
+  }
+  if (params.status === 'ERROR') {
+    return { ok: false, reason: params.reason || 'card rejected the tap' }
+  }
+  if (params.tag !== 'withdrawRequest' || !params.callback || !params.k1) {
+    return { ok: false, reason: 'card did not return a withdraw voucher' }
+  }
+  if (
+    opts.amountMsat != null &&
+    typeof params.maxWithdrawable === 'number' &&
+    opts.amountMsat > params.maxWithdrawable
+  ) {
+    return { ok: false, reason: 'card limit is below this amount' }
+  }
+
+  // 2) Hand our invoice to the callback — the card's wallet pays it.
+  const cbUrl = appendQuery(params.callback, { k1: params.k1, pr: bolt11.trim() })
+  let cb: { status?: string; reason?: string }
+  try {
+    const res = await doFetch(cbUrl, { signal: AbortSignal.timeout(timeoutMs) })
+    cb = (await res.json()) as { status?: string; reason?: string }
+  } catch (e) {
+    return { ok: false, reason: `card payment failed: ${errMsg(e)}` }
+  }
+  if (cb.status === 'OK') return { ok: true }
+  return { ok: false, reason: cb.reason || 'card declined the payment' }
+}
diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index ac31a6a..9b4815d 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -42,6 +42,7 @@ import {
   type StoredBunkerBinding,
 } from './state-store.js'
 import { initializeHal, type HalInstance } from './hal-service.js'
+import { executeLnurlWithdraw } from './lnurl-withdraw.js'
 
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url)
@@ -415,6 +416,20 @@ ipcMain.handle('app:recover', (): void => {
   reloadRenderer()
 })
 
+// Bolt Card cash-out: pull payment for the current invoice from a tapped card
+// via LNURL-withdraw. Runs in the main process (Node fetch) to dodge renderer
+// CORS. Returns once the card accepts; settlement arrives via the invoice
+// watcher. See lnurl-withdraw.ts.
+ipcMain.handle(
+  'lnurl:withdraw',
+  async (
+    _event,
+    args: { lnurlw: string; bolt11: string; amountMsat?: number }
+  ): Promise<{ ok: boolean; reason?: string }> => {
+    return executeLnurlWithdraw(args.lnurlw, args.bolt11, { amountMsat: args.amountMsat })
+  }
+)
+
 // State persistence IPC handlers
 ipcMain.handle('state:load-cassettes', () => loadCassettes())
 ipcMain.handle('state:set-cassettes', (_event, cassettes) => setCassettes(cassettes))
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index 41c54df..d65cb80 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -127,6 +127,13 @@ contextBridge.exposeInMainWorld('electronAPI', {
   // Reload the renderer to re-attempt initialization (connectivity recovery).
   recoverApp: (): Promise<void> => ipcRenderer.invoke('app:recover'),
 
+  // Bolt Card cash-out: pull payment for the current invoice from a tapped card.
+  lnurlWithdraw: (args: {
+    lnurlw: string
+    bolt11: string
+    amountMsat?: number
+  }): Promise<{ ok: boolean; reason?: string }> => ipcRenderer.invoke('lnurl:withdraw', args),
+
   applyOperatorCassettesConfig: (
     payload: {
       positions: Record<string, { denomination: number; count: number }>
@@ -246,6 +253,11 @@ declare global {
       saveSpireSeed: (seed: string) => Promise<void>
       relaunchApp: () => Promise<void>
       recoverApp: () => Promise<void>
+      lnurlWithdraw: (args: {
+        lnurlw: string
+        bolt11: string
+        amountMsat?: number
+      }) => Promise<{ ok: boolean; reason?: string }>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index 4c8faa8..b77f850 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -103,6 +103,12 @@ declare global {
       relaunchApp: () => Promise<void>
       /** Reload the renderer to re-attempt initialization (connectivity recovery). */
       recoverApp: () => Promise<void>
+      /** Bolt Card cash-out: pull payment for the current invoice from a tapped card. */
+      lnurlWithdraw: (args: {
+        lnurlw: string
+        bolt11: string
+        amountMsat?: number
+      }) => Promise<{ ok: boolean; reason?: string }>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number

From 74c420fbd3112791e652cd763514c9a871872643 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 04:27:00 +0200
Subject: [PATCH 66/82] feat(deploy): enable pcscd on batm3 for the Bolt Card
 reader

The Feitian KP382 (096e:0608) is a CCID contactless reader; PC/SC must be
running for the CCID driver to bind it. The app will talk to pcscd's socket
via nfc-pcsc. Idle/harmless when no reader is attached.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 deploy/nixos/hardware/batm3.nix | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/deploy/nixos/hardware/batm3.nix b/deploy/nixos/hardware/batm3.nix
index a92159e..a03c830 100644
--- a/deploy/nixos/hardware/batm3.nix
+++ b/deploy/nixos/hardware/batm3.nix
@@ -85,6 +85,13 @@
     cpuFreqGovernor = "performance";
   };
 
+  # PC/SC daemon for the Feitian KP382 contactless reader (096e:0608, a CCID
+  # smart-card reader) used for Bolt Card tap-to-pay on cash-out. Enabling it
+  # binds the CCID driver to the reader; the app talks to pcscd's socket (via
+  # nfc-pcsc) rather than the USB device directly. Harmless if no reader is
+  # attached — pcscd just idles.
+  services.pcscd.enable = true;
+
   # Disable suspend/hibernate for kiosk
   systemd.targets = {
     sleep.enable = false;

From 84d746a0dae8ddf2656b6b99d103f2388a60f86a Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 04:42:07 +0200
Subject: [PATCH 67/82] feat(machine): NFC Bolt Card reader driver + IPC (main
 process)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Main-process driver over nfc-pcsc (PC/SC). On tap it reads the NTAG424
Type-4 NDEF file via ISO7816 APDUs (select NDEF app D2760000850101 →
select file → ReadBinary NLEN + message) and extracts the lnurlw voucher
(fresh SUN p/c per tap), forwarding it to the renderer on `nfc:card-tapped`
(+ `nfc:status`). Lazy, guarded import — a missing reader/pcscd just
reports 'unavailable', never breaking the cash-out QR path. Preload
removeAllListeners guards against a double payment-trigger on renderer reload.

- electron/nfc-service.ts: startNfcReader() + readNdefLnurlw()/extractLnurlw().
- electron/nfc-service.test.ts: 7 tests (NDEF URI extraction, Type-4 read
  sequence incl. AID select, empty-file + select-fail handling).
- main.ts start + IPC forward; preload + electron.d.ts listeners.
- add nfc-pcsc dep (native @pokusew/pcsclite; nix build handling next).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/main.ts             |   9 ++
 apps/machine/electron/nfc-service.test.ts |  66 +++++++++
 apps/machine/electron/nfc-service.ts      | 157 ++++++++++++++++++++++
 apps/machine/electron/preload.ts          |  18 +++
 apps/machine/package.json                 |   1 +
 apps/machine/src/types/electron.d.ts      |   6 +
 pnpm-lock.yaml                            |  25 +++-
 7 files changed, 281 insertions(+), 1 deletion(-)
 create mode 100644 apps/machine/electron/nfc-service.test.ts
 create mode 100644 apps/machine/electron/nfc-service.ts

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index 9b4815d..ac15f6e 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -43,6 +43,7 @@ import {
 } from './state-store.js'
 import { initializeHal, type HalInstance } from './hal-service.js'
 import { executeLnurlWithdraw } from './lnurl-withdraw.js'
+import { startNfcReader, type NfcStatus } from './nfc-service.js'
 
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url)
@@ -828,6 +829,14 @@ app.whenReady().then(() => {
   startWatchdog()
   startCommandPoller()
 
+  // Bolt Card reader — forwards taps (lnurlw) + status to the renderer. Fully
+  // best-effort: if the reader/pcscd is absent it just reports 'unavailable'
+  // and the cash-out QR path is unaffected.
+  void startNfcReader(
+    (lnurlw) => mainWindow?.webContents.send('nfc:card-tapped', lnurlw),
+    (status) => mainWindow?.webContents.send('nfc:status', status)
+  )
+
   app.on('activate', () => {
     // macOS: re-create window when dock icon clicked
     if (BrowserWindow.getAllWindows().length === 0) {
diff --git a/apps/machine/electron/nfc-service.test.ts b/apps/machine/electron/nfc-service.test.ts
new file mode 100644
index 0000000..3023d36
--- /dev/null
+++ b/apps/machine/electron/nfc-service.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect, vi } from 'vitest'
+import { extractLnurlw, readNdefLnurlw } from './nfc-service'
+
+const LNURLW =
+  'lnurlw://lnbits.l484.com/boltcards/api/v1/scan/abc123?p=DEADBEEFDEADBEEFDEADBEEFDEADBEEF&c=1122334455667788'
+
+/** Build a Type-4 NDEF message with a single URI record carrying `uri`. */
+function ndefUriMessage(uri: string): Buffer {
+  const uriBytes = Buffer.from(uri, 'ascii')
+  const payload = Buffer.concat([Buffer.from([0x00]), uriBytes]) // 0x00 = no prefix
+  // D1 = MB|ME|SR, TNF=well-known; type length 1; payload length; 'U'
+  return Buffer.concat([Buffer.from([0xd1, 0x01, payload.length, 0x55]), payload])
+}
+
+describe('extractLnurlw', () => {
+  it('pulls an lnurlw:// URI out of an NDEF record', () => {
+    expect(extractLnurlw(ndefUriMessage(LNURLW))).toBe(LNURLW)
+  })
+  it('pulls a boltcards https scan URL', () => {
+    const https = 'https://lnbits.l484.com/boltcards/api/v1/scan/x?p=aa&c=bb'
+    expect(extractLnurlw(ndefUriMessage(https))).toBe(https)
+  })
+  it('stops at the record boundary (no trailing binary)', () => {
+    const msg = Buffer.concat([ndefUriMessage(LNURLW), Buffer.from([0x00, 0xfe, 0x01])])
+    expect(extractLnurlw(msg)).toBe(LNURLW)
+  })
+  it('returns null when there is no lnurl', () => {
+    expect(extractLnurlw(Buffer.from('just some text', 'ascii'))).toBeNull()
+  })
+})
+
+describe('readNdefLnurlw', () => {
+  const SW_OK = Buffer.from([0x90, 0x00])
+
+  it('runs the Type-4 read sequence and returns the lnurlw', async () => {
+    const msg = ndefUriMessage(LNURLW)
+    const nlen = msg.length
+    const transmit = vi
+      .fn()
+      .mockResolvedValueOnce(SW_OK) // select NDEF app
+      .mockResolvedValueOnce(SW_OK) // select NDEF file
+      .mockResolvedValueOnce(Buffer.concat([Buffer.from([(nlen >> 8) & 0xff, nlen & 0xff]), SW_OK])) // NLEN
+      .mockResolvedValueOnce(Buffer.concat([msg, SW_OK])) // NDEF message
+
+    const out = await readNdefLnurlw(transmit)
+    expect(out).toBe(LNURLW)
+    // First APDU selects the NDEF application (AID D2760000850101).
+    expect(Buffer.from((transmit.mock.calls[0][0] as Buffer)).toString('hex')).toContain(
+      'd2760000850101'
+    )
+  })
+
+  it('returns null if selecting the NDEF app fails', async () => {
+    const transmit = vi.fn().mockResolvedValue(Buffer.from([0x6a, 0x82])) // file not found SW
+    expect(await readNdefLnurlw(transmit)).toBeNull()
+  })
+
+  it('returns null on an empty NDEF file', async () => {
+    const transmit = vi
+      .fn()
+      .mockResolvedValueOnce(SW_OK)
+      .mockResolvedValueOnce(SW_OK)
+      .mockResolvedValueOnce(Buffer.concat([Buffer.from([0x00, 0x00]), SW_OK])) // NLEN = 0
+    expect(await readNdefLnurlw(transmit)).toBeNull()
+  })
+})
diff --git a/apps/machine/electron/nfc-service.ts b/apps/machine/electron/nfc-service.ts
new file mode 100644
index 0000000..e7e3f00
--- /dev/null
+++ b/apps/machine/electron/nfc-service.ts
@@ -0,0 +1,157 @@
+/**
+ * NFC reader driver (main process) for Bolt Card tap-to-pay.
+ *
+ * Wraps `nfc-pcsc` (PC/SC via the Feitian KP382 CCID reader). On each card
+ * tap it reads the NTAG424 Type-4 NDEF file over ISO7816 APDUs and extracts
+ * the `lnurlw://…?p=…&c=…` voucher (the card computes fresh SUN p/c per tap),
+ * then hands it to the renderer over IPC. The renderer, when showing a
+ * cash-out invoice, pays it via LNURL-withdraw (see lnurl-withdraw.ts).
+ *
+ * Everything here is best-effort and lazy: `nfc-pcsc` is a native addon, so it
+ * is dynamically imported and every failure is swallowed into a status
+ * callback. If the reader/library is absent, NFC is simply unavailable and the
+ * QR path keeps working — cash-out never depends on this.
+ */
+
+export type NfcState = 'ready' | 'reading' | 'error' | 'card-removed' | 'unavailable'
+export interface NfcStatus {
+  state: NfcState
+  reader?: string
+  message?: string
+}
+
+type CardHandler = (lnurlw: string) => void
+type StatusHandler = (status: NfcStatus) => void
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e)
+}
+
+/** Pull the lnurlw (or a boltcards https scan URL) out of a Type-4 NDEF blob. */
+export function extractLnurlw(ndef: Buffer): string | null {
+  // Robust to record framing: the URI record embeds the literal string; grab
+  // it directly, bounded to URL-safe characters so we stop at the record end.
+  const text = ndef.toString('latin1')
+  const urlChars = "[A-Za-z0-9._~:/?#\\[\\]@!$&'()*+,;=%-]+"
+  const m =
+    text.match(new RegExp('lnurlw://' + urlChars, 'i')) ||
+    text.match(new RegExp('https://' + urlChars + '/boltcards/' + urlChars, 'i'))
+  return m ? m[0] : null
+}
+
+/**
+ * Read the NDEF file of a Type-4 tag and return the extracted lnurlw, or null.
+ * `transmit(apdu, maxLen) => Buffer` including the trailing SW1 SW2.
+ */
+export async function readNdefLnurlw(
+  transmit: (apdu: Buffer, maxLen: number) => Promise<Buffer>
+): Promise<string | null> {
+  const send = (bytes: number[]) => transmit(Buffer.from(bytes), 256)
+  const ok = (r: Buffer) => r.length >= 2 && r[r.length - 2] === 0x90 && r[r.length - 1] === 0x00
+
+  // 1) Select the NDEF Tag Application (AID D2760000850101).
+  if (!ok(await send([0x00, 0xa4, 0x04, 0x00, 0x07, 0xd2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x01, 0x00]))) {
+    return null
+  }
+  // 2) Select the NDEF file (EF 0x0004).
+  if (!ok(await send([0x00, 0xa4, 0x00, 0x0c, 0x02, 0x00, 0x04]))) return null
+  // 3) Read the 2-byte NLEN header.
+  const lenResp = await send([0x00, 0xb0, 0x00, 0x00, 0x02])
+  if (!ok(lenResp)) return null
+  const nlen = (lenResp[0] << 8) | lenResp[1]
+  if (nlen <= 0 || nlen > 0x2000) return null
+  // 4) Read the NDEF message (starts at offset 2), in <=250-byte chunks.
+  const chunks: Buffer[] = []
+  let offset = 2
+  let remaining = nlen
+  while (remaining > 0) {
+    const toRead = Math.min(remaining, 0xfa)
+    const resp = await send([0x00, 0xb0, (offset >> 8) & 0xff, offset & 0xff, toRead])
+    if (!ok(resp)) break
+    const data = resp.subarray(0, resp.length - 2)
+    if (data.length === 0) break
+    chunks.push(data)
+    offset += data.length
+    remaining -= data.length
+  }
+  return extractLnurlw(Buffer.concat(chunks))
+}
+
+let stopFn: (() => void) | null = null
+
+/**
+ * Start listening for Bolt Card taps. Idempotent. Returns a stop function.
+ * Never throws — failures surface via onStatus.
+ */
+export async function startNfcReader(
+  onCard: CardHandler,
+  onStatus: StatusHandler
+): Promise<() => void> {
+  if (stopFn) return stopFn
+
+  let mod: unknown
+  try {
+    // Non-literal specifier: nfc-pcsc ships no types; keep it `any` to tsc
+    // while resolving normally at runtime.
+    const pkg = 'nfc-pcsc'
+    mod = (await import(pkg)) as unknown
+  } catch (e) {
+    onStatus({ state: 'unavailable', message: `NFC library unavailable: ${errMsg(e)}` })
+    return () => {}
+  }
+  const NFC =
+    (mod as { NFC?: unknown }).NFC ?? (mod as { default?: { NFC?: unknown } }).default?.NFC
+  if (typeof NFC !== 'function') {
+    onStatus({ state: 'unavailable', message: 'NFC library has no NFC export' })
+    return () => {}
+  }
+
+  let nfc: { on: (e: string, cb: (...a: unknown[]) => void) => void; close?: () => void }
+  try {
+    nfc = new (NFC as new () => typeof nfc)()
+  } catch (e) {
+    onStatus({ state: 'unavailable', message: `NFC init failed: ${errMsg(e)}` })
+    return () => {}
+  }
+
+  nfc.on('reader', (reader: unknown) => {
+    const r = reader as {
+      name?: string
+      reader?: { name?: string }
+      autoProcessing?: boolean
+      on: (e: string, cb: (...a: unknown[]) => void) => void
+      transmit: (data: Buffer, maxLen: number) => Promise<Buffer>
+    }
+    const name = r.name ?? r.reader?.name ?? 'reader'
+    // We do our own NDEF APDU read, not nfc-pcsc's UID auto-processing.
+    r.autoProcessing = false
+    onStatus({ state: 'ready', reader: name })
+
+    r.on('card', async () => {
+      onStatus({ state: 'reading', reader: name })
+      try {
+        const lnurlw = await readNdefLnurlw((apdu, maxLen) => r.transmit(apdu, maxLen))
+        if (lnurlw) onCard(lnurlw)
+        else onStatus({ state: 'error', reader: name, message: 'not a Bolt Card' })
+      } catch (e) {
+        onStatus({ state: 'error', reader: name, message: errMsg(e) })
+      }
+    })
+    r.on('card.off', () => onStatus({ state: 'card-removed', reader: name }))
+    r.on('error', (err: unknown) =>
+      onStatus({ state: 'error', reader: name, message: errMsg(err) })
+    )
+    r.on('end', () => onStatus({ state: 'unavailable', reader: name, message: 'reader disconnected' }))
+  })
+  nfc.on('error', (err: unknown) => onStatus({ state: 'error', message: errMsg(err) }))
+
+  stopFn = () => {
+    try {
+      nfc.close?.()
+    } catch {
+      /* idempotent */
+    }
+    stopFn = null
+  }
+  return stopFn
+}
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index d65cb80..8be0ed8 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -195,6 +195,20 @@ contextBridge.exposeInMainWorld('electronAPI', {
     ipcRenderer.on('hal:error', (_event, error) => callback(error))
   },
 
+  // Bolt Card reader (main process → renderer). removeAllListeners first: a
+  // renderer reload re-runs this, and a duplicated card-tap listener would
+  // trigger the LNURL-withdraw twice.
+  onNfcCardTapped: (callback: (lnurlw: string) => void) => {
+    ipcRenderer.removeAllListeners('nfc:card-tapped')
+    ipcRenderer.on('nfc:card-tapped', (_event, lnurlw) => callback(lnurlw))
+  },
+  onNfcStatus: (
+    callback: (status: { state: string; reader?: string; message?: string }) => void
+  ) => {
+    ipcRenderer.removeAllListeners('nfc:status')
+    ipcRenderer.on('nfc:status', (_event, status) => callback(status))
+  },
+
   // Watchdog heartbeat (main process → renderer → main process)
   onWatchdogPing: (callback: () => void) => {
     ipcRenderer.on('watchdog:ping', () => callback())
@@ -295,6 +309,10 @@ declare global {
       onHalBillInserted: (callback: (denomination: number) => void) => void
       onHalBillRejected: (callback: (reason: string) => void) => void
       onHalError: (callback: (error: string) => void) => void
+      onNfcCardTapped: (callback: (lnurlw: string) => void) => void
+      onNfcStatus: (
+        callback: (status: { state: string; reader?: string; message?: string }) => void
+      ) => void
       onWatchdogPing: (callback: () => void) => void
       watchdogPong: () => Promise<void>
       platform: NodeJS.Platform
diff --git a/apps/machine/package.json b/apps/machine/package.json
index de432cb..7f68db8 100644
--- a/apps/machine/package.json
+++ b/apps/machine/package.json
@@ -35,6 +35,7 @@
     "clsx": "^2.1.1",
     "lucide-vue-next": "^0.563.0",
     "marked": "^17.0.5",
+    "nfc-pcsc": "^0.8.1",
     "nostr-tools": "^2.10.0",
     "pinia": "^2.2.0",
     "qr": "^0.6.0",
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index b77f850..d391944 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -146,6 +146,12 @@ declare global {
       onHalBillInserted: (callback: (denomination: number) => void) => void
       onHalBillRejected: (callback: (reason: string) => void) => void
       onHalError: (callback: (error: string) => void) => void
+      /** Bolt Card reader: a tapped card's lnurlw voucher. */
+      onNfcCardTapped: (callback: (lnurlw: string) => void) => void
+      /** Bolt Card reader status (ready / reading / error / unavailable). */
+      onNfcStatus: (
+        callback: (status: { state: string; reader?: string; message?: string }) => void
+      ) => void
       onWatchdogPing: (callback: () => void) => void
       watchdogPong: () => Promise<void>
       platform: NodeJS.Platform
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0fe2b33..3f91de1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -59,6 +59,9 @@ importers:
       marked:
         specifier: ^17.0.5
         version: 17.0.5
+      nfc-pcsc:
+        specifier: ^0.8.1
+        version: 0.8.1
       nostr-tools:
         specifier: ^2.10.0
         version: 2.19.4(typescript@5.9.3)
@@ -897,6 +900,9 @@ packages:
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
 
+  '@pokusew/pcsclite@0.6.0':
+    resolution: {integrity: sha512-jX7zRXM2Or5Pms1AFjNtawsXDjLiZOzOUo7Sf0put7Pnq/EKIR9g0KvTx62HtwdPpVP6hWHGydUTHgIi9PxodQ==}
+
   '@rollup/rollup-android-arm-eabi@4.56.0':
     resolution: {integrity: sha512-LNKIPA5k8PF1+jAFomGe3qN3bbIgJe/IlpDBwuVjrDKrJhVWywgnJvflMt/zkbVNLFtF1+94SljYQS6e99klnw==}
     cpu: [arm]
@@ -2484,6 +2490,9 @@ packages:
   muggle-string@0.4.1:
     resolution: {integrity: sha512-VNTrAak/KhO2i8dqqnqnAHOa3cYBwXEZe9h+D5h/1ZqFSTEFHdM65lR7RoIqq3tBBYavsOXV84NoHXZ0AkPyqQ==}
 
+  nan@2.28.0:
+    resolution: {integrity: sha512-fTsDz99OTq2sVePhGdp4qQhggZFtKr64ZNVyVajRKtMOkJxYekplBh577PiJB12v/D3s2E5cGtOI45LWp6rnLQ==}
+
   nanoid@3.3.11:
     resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -2496,6 +2505,9 @@ packages:
     resolution: {integrity: sha512-myRT3DiWPHqho5PrJaIRyaMv2kgYf0mUVgBNOYMuCH5Ki1yEiQaf/ZJuQ62nvpc44wL5WDbTX7yGJi1Neevw8w==}
     engines: {node: '>= 0.6'}
 
+  nfc-pcsc@0.8.1:
+    resolution: {integrity: sha512-wEfacG0dwPVZOG/WY28Mk3P4Q+yz6q7LnjpnZvdFddx3iXavEXiGhftRZXBtudr0NrzH1MrGWSkWq77tef7BMA==}
+
   node-abi@3.87.0:
     resolution: {integrity: sha512-+CGM1L1CgmtheLcBuleyYOn7NWPVu0s0EJH2C4puxgEZb9h8QpR9G2dBfZJOAUhi7VQxuBPMd0hiISWcTyiYyQ==}
     engines: {node: '>=10'}
@@ -2966,7 +2978,7 @@ packages:
   tar@6.2.1:
     resolution: {integrity: sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==}
     engines: {node: '>=10'}
-    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exhorbitant rates) by contacting i@izs.me
 
   temp-file@3.4.0:
     resolution: {integrity: sha512-C5tjlC/HCtVUOi3KWVokd4vHVViOmGjtLwIh4MuzPo/nMYTV/p1urt3RnMz2IWXDdKEGJH3k5+KPxtqRsUYGtg==}
@@ -3760,6 +3772,11 @@ snapshots:
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
+  '@pokusew/pcsclite@0.6.0':
+    dependencies:
+      bindings: 1.5.0
+      nan: 2.28.0
+
   '@rollup/rollup-android-arm-eabi@4.56.0':
     optional: true
 
@@ -5506,12 +5523,18 @@ snapshots:
 
   muggle-string@0.4.1: {}
 
+  nan@2.28.0: {}
+
   nanoid@3.3.11: {}
 
   napi-build-utils@2.0.0: {}
 
   negotiator@0.6.4: {}
 
+  nfc-pcsc@0.8.1:
+    dependencies:
+      '@pokusew/pcsclite': 0.6.0
+
   node-abi@3.87.0:
     dependencies:
       semver: 7.7.3

From 07978a8de12fba10f9cce2ba96e85700b5c76c35 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 04:45:51 +0200
Subject: [PATCH 68/82] feat(machine): wire Bolt Card tap into cash-out
 displayingInvoice + UI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renderer side of tap-to-pay. The store subscribes to the main-process
reader (onNfcCardTapped/onNfcStatus); a tap during displayingInvoice pulls
payment for the shown invoice via lnurlWithdraw (amount in msats), guarded
against double-taps. Settlement still flows through the existing invoice
watcher → PAYMENT_RECEIVED → dispensingCash, so the state machine is
unchanged. Bolt Card state clears when leaving the invoice screen.

CashOutView: "Tap Card or Scan to Pay" + live reader/processing/declined
status on the invoice screen, plus a dev input to simulate a tap with a
pasted lnurlw. Exposes nfcStatus / boltCardProcessing / simulateBoltCardTap.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/src/stores/atm.ts         | 69 ++++++++++++++++++++++++++
 apps/machine/src/views/CashOutView.vue | 52 +++++++++++++++++--
 2 files changed, 116 insertions(+), 5 deletions(-)

diff --git a/apps/machine/src/stores/atm.ts b/apps/machine/src/stores/atm.ts
index 7119500..06dea22 100644
--- a/apps/machine/src/stores/atm.ts
+++ b/apps/machine/src/stores/atm.ts
@@ -291,6 +291,11 @@ export const useAtmStore = defineStore('atm', () => {
   const debugMode = ref(true)
   const allowMockFallback = ref(true) // default true for browser dev
   const initError = ref<string | null>(null) // fatal error → maintenance screen
+  // Bolt Card cash-out (NFC tap-to-pay). nfcStatus surfaces reader state on the
+  // invoice screen; boltCardProcessing gates against double-taps while a pull
+  // is in flight (settlement still arrives via the normal invoice watcher).
+  const nfcStatus = ref<{ state: string; message?: string } | null>(null)
+  const boltCardProcessing = ref(false)
   const fiatCode = ref('USD')
   // Defaults are 0 — the operator's fee config (received via Nostr
   // kind-30078 `bitspire-fees:<atm_pubkey>` envelope from satmachineadmin)
@@ -562,14 +567,73 @@ export const useAtmStore = defineStore('atm', () => {
         }
       }
 
+      // Clear Bolt Card state whenever we leave the invoice screen (dispensed,
+      // timed out, or cancelled) so a stale "processing"/error can't linger.
+      if (currentNested !== 'displayingInvoice' && prevNestedState === 'displayingInvoice') {
+        boltCardProcessing.value = false
+        nfcStatus.value = null
+      }
+
       prevNestedState = currentNested
     })
 
     // Start the machine
     actor.value.start()
+    setupNfcListener()
     console.log('[ATM] State machine initialized')
   }
 
+  // ── Bolt Card cash-out (NFC tap-to-pay) ───────────────────────────────────
+
+  /**
+   * A tapped Bolt Card during the cash-out invoice screen: pull payment for
+   * the shown invoice via LNURL-withdraw (main process). Settlement still
+   * arrives through the invoice watcher → PAYMENT_RECEIVED → dispensingCash;
+   * ok here only means the card accepted the pull.
+   */
+  async function handleBoltCardTap(lnurlw: string) {
+    if (nestedState.value !== 'displayingInvoice') return
+    const invoice = context.value?.invoice
+    if (!invoice) return
+    if (boltCardProcessing.value) return // one pull at a time
+    boltCardProcessing.value = true
+    nfcStatus.value = { state: 'processing', message: 'Reading card…' }
+    try {
+      const amountMsat = (context.value?.satsAmount ?? 0) * 1000
+      const res = await window.electronAPI!.lnurlWithdraw({ lnurlw, bolt11: invoice, amountMsat })
+      if (res.ok) {
+        nfcStatus.value = { state: 'accepted', message: 'Card accepted — confirming payment…' }
+      } else {
+        boltCardProcessing.value = false
+        nfcStatus.value = { state: 'declined', message: res.reason ?? 'Card declined' }
+      }
+    } catch (e) {
+      console.warn('[ATM] Bolt Card withdraw failed:', e)
+      boltCardProcessing.value = false
+      nfcStatus.value = { state: 'error', message: 'Card payment failed' }
+    }
+  }
+
+  /** Wire the main-process reader once (idempotent via preload removeAllListeners). */
+  function setupNfcListener() {
+    if (!isElectron || !window.electronAPI?.onNfcCardTapped) return
+    window.electronAPI.onNfcCardTapped((lnurlw) => {
+      void handleBoltCardTap(lnurlw)
+    })
+    window.electronAPI.onNfcStatus?.((status) => {
+      // Only surface reader status on the invoice screen, and don't clobber an
+      // in-flight pull's message.
+      if (nestedState.value === 'displayingInvoice' && !boltCardProcessing.value) {
+        nfcStatus.value = status
+      }
+    })
+  }
+
+  /** Dev/mock: simulate a tap with a pasted lnurlw (test without a card). */
+  function simulateBoltCardTap(lnurlw: string) {
+    void handleBoltCardTap(lnurlw)
+  }
+
   /**
    * Group an array of inserted bill denominations into { denomination, count } pairs.
    */
@@ -1522,6 +1586,11 @@ export const useAtmStore = defineStore('atm', () => {
     isCashOut,
     nestedState,
 
+    // Bolt Card cash-out (NFC)
+    nfcStatus,
+    boltCardProcessing,
+    simulateBoltCardTap,
+
     // Actions
     initialize,
     initializeWithLightning,
diff --git a/apps/machine/src/views/CashOutView.vue b/apps/machine/src/views/CashOutView.vue
index 4b4a4d2..6257882 100644
--- a/apps/machine/src/views/CashOutView.vue
+++ b/apps/machine/src/views/CashOutView.vue
@@ -15,6 +15,10 @@ const isElectron = typeof window !== 'undefined' && window.electronAPI !== undef
 
 const cashOutSteps = ['Select', 'Pay', 'Collect']
 
+// Dev-only: paste a real card's lnurlw to exercise the Bolt Card pull without
+// the reader (single-use, so a live tap each time).
+const mockLnurlw = ref('')
+
 const currentStepIndex = computed(() => {
   switch (nestedState.value) {
     case 'fetchingRate':
@@ -284,7 +288,9 @@ function formatFiat(cents: number): string {
           <div
             class="flex w-full lg:w-[52%] flex-col items-center justify-center gap-3 lg:gap-5 px-4 lg:px-[4vw] py-4 lg:py-0"
           >
-            <p class="text-lg lg:text-[2rem] font-semibold text-warning">Scan to Pay</p>
+            <p class="text-lg lg:text-[2rem] font-semibold text-warning">
+              {{ isElectron ? 'Tap Card or Scan to Pay' : 'Scan to Pay' }}
+            </p>
             <p class="text-3xl lg:text-[7vh] font-bold text-bitcoin leading-tight">
               {{ context ? formatSats(context.satsAmount) : 0 }} sats
             </p>
@@ -295,10 +301,31 @@ function formatFiat(cents: number): string {
               </Badge>
             </p>
 
-            <!-- Waiting indicator -->
-            <div class="flex items-center gap-3 pt-2 lg:pt-4">
-              <PickaxeIcon :size="32" />
-              <p class="text-sm lg:text-xl text-muted-foreground">Waiting for payment...</p>
+            <!-- Waiting indicator + Bolt Card status -->
+            <div class="flex flex-col items-center gap-2 pt-2 lg:pt-4">
+              <div class="flex items-center gap-3">
+                <PickaxeIcon :size="32" />
+                <p class="text-sm lg:text-xl text-muted-foreground">
+                  {{
+                    atmStore.boltCardProcessing
+                      ? 'Processing card…'
+                      : isElectron
+                        ? 'Tap your card or scan the QR'
+                        : 'Waiting for payment...'
+                  }}
+                </p>
+              </div>
+              <p
+                v-if="atmStore.nfcStatus?.message"
+                class="text-sm lg:text-lg"
+                :class="
+                  atmStore.nfcStatus.state === 'declined' || atmStore.nfcStatus.state === 'error'
+                    ? 'text-destructive'
+                    : 'text-muted-foreground'
+                "
+              >
+                {{ atmStore.nfcStatus.message }}
+              </p>
             </div>
 
             <!-- Invoice info with copy button (web-ui only) -->
@@ -322,6 +349,21 @@ function formatFiat(cents: number): string {
                 >
                   Simulate Payment
                 </Button>
+                <div class="mt-2 flex items-center gap-2">
+                  <input
+                    v-model="mockLnurlw"
+                    placeholder="lnurlw://… (paste to simulate a card tap)"
+                    class="w-56 rounded border border-input bg-background px-2 py-1 text-xs"
+                  />
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    :disabled="!mockLnurlw"
+                    @click="atmStore.simulateBoltCardTap(mockLnurlw)"
+                  >
+                    Tap
+                  </Button>
+                </div>
               </AlertDescription>
             </Alert>
           </div>

From 51dcf0d6f639163798ab0dc2e0bd1fce9bc95cfa Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 04:55:30 +0200
Subject: [PATCH 69/82] feat(deploy): build nfc-pcsc's native pcsclite addon
 for Electron (mkAtmApp)

Rebuild @pokusew/pcsclite (V8 C++ addon) against Electron headers like
better-sqlite3, and package nfc-pcsc + @pokusew/pcsclite into the runtime
node_modules. Its binding.gyp hardcodes Debian /usr/include/PCSC + /usr/lib,
so point the compiler/linker at nixpkgs pcsclite via CPATH/LIBRARY_PATH
(winscard.h lives under include/PCSC); pcsclite.lib in buildInputs lets
autoPatchelf wire libpcsclite.so.1 into the .node RPATH. Bumps the pnpmDeps
hash for the added nfc-pcsc dependency.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 nix/mkAtmApp.nix | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/nix/mkAtmApp.nix b/nix/mkAtmApp.nix
index 630faf3..68a4c37 100644
--- a/nix/mkAtmApp.nix
+++ b/nix/mkAtmApp.nix
@@ -38,7 +38,7 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     inherit (finalAttrs) pname version src pnpmWorkspaces;
     inherit pnpm;
     fetcherVersion = 3;
-    hash = "sha256-03ANBQ7bHJwsqlX2ScA1+1LFuO8njiuU7O4VGOb6cMM=";
+    hash = "sha256-XqpQpFL3PqnFltb4ujAmmnnV0LOqTHKV/bo3riFu9pY=";
   };
 
   nativeBuildInputs = [
@@ -57,6 +57,11 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     pkgs.sqlite.dev # better-sqlite3
     pkgs.libudev-zero # serialport
     pkgs.stdenv.cc.cc.lib # libstdc++
+    # @pokusew/pcsclite (nfc-pcsc): the `lib` output carries libpcsclite.so so
+    # autoPatchelf wires it into the .node RPATH at runtime. Compile/link paths
+    # are injected via CPATH/LIBRARY_PATH in buildPhase (its binding.gyp
+    # hardcodes Debian /usr paths instead of using pkg-config).
+    pkgs.pcsclite.lib
   ];
 
   env = {
@@ -83,6 +88,19 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
       --arch=x64
     popd
 
+    # @pokusew/pcsclite (nfc-pcsc's native addon) — also V8 C++ API, so it too
+    # must be rebuilt against Electron's headers. Its binding.gyp hardcodes
+    # /usr/include/PCSC + /usr/lib, so point the compiler/linker at nixpkgs'
+    # pcsclite explicitly (winscard.h lives under include/PCSC).
+    echo "=== Rebuilding @pokusew/pcsclite against Electron ${electron.version} headers ==="
+    pushd node_modules/.pnpm/@pokusew+pcsclite@*/node_modules/@pokusew/pcsclite
+    CPATH="${pkgs.pcsclite.dev}/include/PCSC''${CPATH:+:$CPATH}" \
+    LIBRARY_PATH="${pkgs.pcsclite.lib}/lib''${LIBRARY_PATH:+:$LIBRARY_PATH}" \
+    HOME=$TMPDIR ${nodejs}/bin/npx --yes node-gyp rebuild \
+      --nodedir="$electron_nodedir" \
+      --arch=x64
+    popd
+
     # Build the Electron app (turbo builds all workspace deps + app)
     pnpm --filter="@bitSpire/machine..." build
 
@@ -95,7 +113,7 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
   installPhase = ''
     runHook preInstall
 
-    mkdir -p $out/node_modules/{@lamassu,@serialport}
+    mkdir -p $out/node_modules/{@lamassu,@serialport,@pokusew}
 
     # Helper: find a package dir inside the pnpm virtual store.
     # pnpm store dirs look like: node_modules/.pnpm/<name>@<ver>[_<peer-suffix>]/node_modules/<name>
@@ -132,6 +150,12 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     copy_pnpm_pkg bindings $out/node_modules/bindings
     copy_pnpm_pkg file-uri-to-path $out/node_modules/file-uri-to-path
 
+    # nfc-pcsc + @pokusew/pcsclite (Bolt Card reader). The compiled
+    # pcsclite.node (from the rebuild above) rides along in the package dir and
+    # loads via `bindings` (already copied). autoPatchelf wires libpcsclite.
+    copy_pnpm_pkg nfc-pcsc $out/node_modules/nfc-pcsc
+    copy_pnpm_pkg @pokusew/pcsclite $out/node_modules/@pokusew/pcsclite
+
     # @bitSpire/hal (workspace package, dynamically imported for hardware access)
     mkdir -p $out/node_modules/@bitSpire/hal/dist
     cp -rL packages/hal/dist/* $out/node_modules/@bitSpire/hal/dist/

From 0a3156855cf2a3f395343d93b9c33715a707fd7b Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 05:01:08 +0200
Subject: [PATCH 70/82] feat(deploy): authorize bitspire for pcscd (polkit) +
 NFC diagnostics
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pcscd gates clients via polkit; the sandboxed bitspire user was "Rejected
unauthorized PC/SC client", so add a polkit rule granting it
access_pcsc/access_card. Also log NFC reader status + taps from the main
process to journald (value redacted — it carries the card's SUN p/c) so
reader detection and taps are observable during testing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/main.ts   | 13 +++++++++++--
 deploy/nixos/hardware/batm3.nix | 13 +++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index ac15f6e..81676cf 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -833,8 +833,17 @@ app.whenReady().then(() => {
   // best-effort: if the reader/pcscd is absent it just reports 'unavailable'
   // and the cash-out QR path is unaffected.
   void startNfcReader(
-    (lnurlw) => mainWindow?.webContents.send('nfc:card-tapped', lnurlw),
-    (status) => mainWindow?.webContents.send('nfc:status', status)
+    (lnurlw) => {
+      // Don't log the value — it carries the card's single-use SUN p/c.
+      console.log(`[NFC] card tapped — lnurlw (${lnurlw.length} chars) → renderer`)
+      mainWindow?.webContents.send('nfc:card-tapped', lnurlw)
+    },
+    (status: NfcStatus) => {
+      console.log(
+        `[NFC] status=${status.state}${status.reader ? ` reader="${status.reader}"` : ''}${status.message ? ` — ${status.message}` : ''}`
+      )
+      mainWindow?.webContents.send('nfc:status', status)
+    }
   )
 
   app.on('activate', () => {
diff --git a/deploy/nixos/hardware/batm3.nix b/deploy/nixos/hardware/batm3.nix
index a03c830..40983c9 100644
--- a/deploy/nixos/hardware/batm3.nix
+++ b/deploy/nixos/hardware/batm3.nix
@@ -92,6 +92,19 @@
   # attached — pcscd just idles.
   services.pcscd.enable = true;
 
+  # pcscd gates client access via polkit; without a rule the sandboxed
+  # `bitspire` service user is "Rejected unauthorized PC/SC client". Authorize
+  # it to talk to the daemon and the card.
+  security.polkit.extraConfig = ''
+    polkit.addRule(function(action, subject) {
+      if ((action.id == "org.debian.pcsc-lite.access_pcsc" ||
+           action.id == "org.debian.pcsc-lite.access_card") &&
+          subject.user == "bitspire") {
+        return polkit.Result.YES;
+      }
+    });
+  '';
+
   # Disable suspend/hibernate for kiosk
   systemd.targets = {
     sleep.enable = false;

From ea736dfab06365f777597e952256f58944d6a820 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 20:02:26 +0200
Subject: [PATCH 71/82] fix(machine): read NTAG424 NDEF via Capability
 Container (Bolt Card FileID)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First real-card tap read the NDEF file with id 0004 and got "not a Bolt
Card" — NTAG424 (Bolt Cards) use FileID E104. Read the Capability Container
(EF E103) after selecting the NDEF app to learn the advertised NDEF FileID,
then read that file; fall back to E104/0004. Tolerates a transient transmit
error (surfaced as a retryable status; the next tap re-reads).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/nfc-service.test.ts | 50 +++++++++--------
 apps/machine/electron/nfc-service.ts      | 66 ++++++++++++++++-------
 2 files changed, 76 insertions(+), 40 deletions(-)

diff --git a/apps/machine/electron/nfc-service.test.ts b/apps/machine/electron/nfc-service.test.ts
index 3023d36..f694758 100644
--- a/apps/machine/electron/nfc-service.test.ts
+++ b/apps/machine/electron/nfc-service.test.ts
@@ -31,36 +31,44 @@ describe('extractLnurlw', () => {
 
 describe('readNdefLnurlw', () => {
   const SW_OK = Buffer.from([0x90, 0x00])
+  const SW_NOTFOUND = Buffer.from([0x6a, 0x82])
+  // Capability Container advertising the NDEF file id E104 (TLV 04 06 at [7,8]).
+  const CC = Buffer.from([
+    0x00, 0x0f, 0x20, 0x00, 0x3b, 0x00, 0x34, 0x04, 0x06, 0xe1, 0x04, 0x00, 0xff, 0x00, 0xff,
+  ])
 
-  it('runs the Type-4 read sequence and returns the lnurlw', async () => {
-    const msg = ndefUriMessage(LNURLW)
+  /** Route APDUs by content so the CC-read + fallback loop is exercised. */
+  function cardMock(opts: { noApp?: boolean; nlen0?: boolean; uri?: string } = {}) {
+    const msg = ndefUriMessage(opts.uri ?? LNURLW)
     const nlen = msg.length
-    const transmit = vi
-      .fn()
-      .mockResolvedValueOnce(SW_OK) // select NDEF app
-      .mockResolvedValueOnce(SW_OK) // select NDEF file
-      .mockResolvedValueOnce(Buffer.concat([Buffer.from([(nlen >> 8) & 0xff, nlen & 0xff]), SW_OK])) // NLEN
-      .mockResolvedValueOnce(Buffer.concat([msg, SW_OK])) // NDEF message
+    return vi.fn(async (apdu: Buffer) => {
+      const hex = apdu.toString('hex')
+      if (hex.includes('d2760000850101')) return opts.noApp ? SW_NOTFOUND : SW_OK // select app
+      if (hex.startsWith('00a4000c02e103')) return SW_OK // select CC
+      if (hex.startsWith('00b000000f')) return Buffer.concat([CC, SW_OK]) // read CC
+      if (hex.startsWith('00a4000c02e104')) return SW_OK // select NDEF file (E104)
+      if (hex.startsWith('00a4000c020004')) return SW_NOTFOUND // fallback file id: absent
+      if (hex.startsWith('00b0000002'))
+        return opts.nlen0
+          ? Buffer.concat([Buffer.from([0x00, 0x00]), SW_OK])
+          : Buffer.concat([Buffer.from([(nlen >> 8) & 0xff, nlen & 0xff]), SW_OK]) // NLEN
+      if (hex.startsWith('00b0')) return Buffer.concat([msg, SW_OK]) // read message
+      return SW_NOTFOUND
+    })
+  }
 
-    const out = await readNdefLnurlw(transmit)
-    expect(out).toBe(LNURLW)
+  it('reads CC → NDEF file (E104) and returns the lnurlw', async () => {
+    const transmit = cardMock()
+    expect(await readNdefLnurlw(transmit)).toBe(LNURLW)
     // First APDU selects the NDEF application (AID D2760000850101).
-    expect(Buffer.from((transmit.mock.calls[0][0] as Buffer)).toString('hex')).toContain(
-      'd2760000850101'
-    )
+    expect((transmit.mock.calls[0][0] as Buffer).toString('hex')).toContain('d2760000850101')
   })
 
   it('returns null if selecting the NDEF app fails', async () => {
-    const transmit = vi.fn().mockResolvedValue(Buffer.from([0x6a, 0x82])) // file not found SW
-    expect(await readNdefLnurlw(transmit)).toBeNull()
+    expect(await readNdefLnurlw(cardMock({ noApp: true }))).toBeNull()
   })
 
   it('returns null on an empty NDEF file', async () => {
-    const transmit = vi
-      .fn()
-      .mockResolvedValueOnce(SW_OK)
-      .mockResolvedValueOnce(SW_OK)
-      .mockResolvedValueOnce(Buffer.concat([Buffer.from([0x00, 0x00]), SW_OK])) // NLEN = 0
-    expect(await readNdefLnurlw(transmit)).toBeNull()
+    expect(await readNdefLnurlw(cardMock({ nlen0: true }))).toBeNull()
   })
 })
diff --git a/apps/machine/electron/nfc-service.ts b/apps/machine/electron/nfc-service.ts
index e7e3f00..ecafc07 100644
--- a/apps/machine/electron/nfc-service.ts
+++ b/apps/machine/electron/nfc-service.ts
@@ -39,35 +39,27 @@ export function extractLnurlw(ndef: Buffer): string | null {
   return m ? m[0] : null
 }
 
-/**
- * Read the NDEF file of a Type-4 tag and return the extracted lnurlw, or null.
- * `transmit(apdu, maxLen) => Buffer` including the trailing SW1 SW2.
- */
-export async function readNdefLnurlw(
-  transmit: (apdu: Buffer, maxLen: number) => Promise<Buffer>
-): Promise<string | null> {
-  const send = (bytes: number[]) => transmit(Buffer.from(bytes), 256)
-  const ok = (r: Buffer) => r.length >= 2 && r[r.length - 2] === 0x90 && r[r.length - 1] === 0x00
+const swOk = (r: Buffer) => r.length >= 2 && r[r.length - 2] === 0x90 && r[r.length - 1] === 0x00
 
-  // 1) Select the NDEF Tag Application (AID D2760000850101).
-  if (!ok(await send([0x00, 0xa4, 0x04, 0x00, 0x07, 0xd2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x01, 0x00]))) {
-    return null
-  }
-  // 2) Select the NDEF file (EF 0x0004).
-  if (!ok(await send([0x00, 0xa4, 0x00, 0x0c, 0x02, 0x00, 0x04]))) return null
-  // 3) Read the 2-byte NLEN header.
+/** Select an EF by its 2-byte file id and read + parse its NDEF message. */
+async function readNdefFile(
+  send: (bytes: number[]) => Promise<Buffer>,
+  fid: [number, number]
+): Promise<string | null> {
+  if (!swOk(await send([0x00, 0xa4, 0x00, 0x0c, 0x02, fid[0], fid[1]]))) return null
+  // 2-byte NLEN header at offset 0.
   const lenResp = await send([0x00, 0xb0, 0x00, 0x00, 0x02])
-  if (!ok(lenResp)) return null
+  if (!swOk(lenResp)) return null
   const nlen = (lenResp[0] << 8) | lenResp[1]
   if (nlen <= 0 || nlen > 0x2000) return null
-  // 4) Read the NDEF message (starts at offset 2), in <=250-byte chunks.
+  // NDEF message starts at offset 2; read in <=250-byte chunks.
   const chunks: Buffer[] = []
   let offset = 2
   let remaining = nlen
   while (remaining > 0) {
     const toRead = Math.min(remaining, 0xfa)
     const resp = await send([0x00, 0xb0, (offset >> 8) & 0xff, offset & 0xff, toRead])
-    if (!ok(resp)) break
+    if (!swOk(resp)) break
     const data = resp.subarray(0, resp.length - 2)
     if (data.length === 0) break
     chunks.push(data)
@@ -77,6 +69,42 @@ export async function readNdefLnurlw(
   return extractLnurlw(Buffer.concat(chunks))
 }
 
+/**
+ * Read the NDEF of a Type-4 tag and return the extracted lnurlw, or null.
+ * `transmit(apdu, maxLen) => Buffer` including the trailing SW1 SW2.
+ *
+ * Select the NDEF Tag Application, read the Capability Container to learn the
+ * real NDEF FileID (NTAG424 Bolt Cards use E104, not the 0004 some tags use),
+ * then read that file. Falls back to E104/0004 if the CC read is unavailable.
+ */
+export async function readNdefLnurlw(
+  transmit: (apdu: Buffer, maxLen: number) => Promise<Buffer>
+): Promise<string | null> {
+  const send = (bytes: number[]) => transmit(Buffer.from(bytes), 256)
+
+  // Select the NDEF Tag Application (AID D2760000850101).
+  if (!swOk(await send([0x00, 0xa4, 0x04, 0x00, 0x07, 0xd2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x01, 0x00]))) {
+    return null
+  }
+
+  // Prefer the FileID advertised by the Capability Container (EF E103).
+  const candidates: Array<[number, number]> = []
+  if (swOk(await send([0x00, 0xa4, 0x00, 0x0c, 0x02, 0xe1, 0x03]))) {
+    const cc = await send([0x00, 0xb0, 0x00, 0x00, 0x0f])
+    // CC layout: …[07]=TLV tag 0x04, [08]=len, [09..10]=NDEF FileID.
+    if (swOk(cc) && cc.length >= 13 && cc[7] === 0x04) candidates.push([cc[9], cc[10]])
+  }
+  for (const fid of [[0xe1, 0x04] as [number, number], [0x00, 0x04] as [number, number]]) {
+    if (!candidates.some((c) => c[0] === fid[0] && c[1] === fid[1])) candidates.push(fid)
+  }
+
+  for (const fid of candidates) {
+    const found = await readNdefFile(send, fid)
+    if (found) return found
+  }
+  return null
+}
+
 let stopFn: (() => void) | null = null
 
 /**

From ed04c63b2fed6d973f4b5073e11757105524267c Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 20:16:50 +0200
Subject: [PATCH 72/82] perf(machine): fewer NFC APDUs (E104-first) +
 single-attempt read
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Retrying a read hammered the cheap CCID reader into a stuck present↔empty
loop (only cleared by a reboot), so drop the retry: a read is a single
attempt and the user re-taps if the RF link drops mid-read. Also skip the
Capability-Container round-trip in the common case — NTAG424 Bolt Cards use
NDEF FileID E104, so try E104/0004 directly and only read the CC to discover
the id if both fail. Fewer APDUs → a read completes inside a shorter stable
window.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/nfc-service.ts | 35 +++++++++++++++++-----------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/apps/machine/electron/nfc-service.ts b/apps/machine/electron/nfc-service.ts
index ecafc07..970d17d 100644
--- a/apps/machine/electron/nfc-service.ts
+++ b/apps/machine/electron/nfc-service.ts
@@ -87,20 +87,20 @@ export async function readNdefLnurlw(
     return null
   }
 
-  // Prefer the FileID advertised by the Capability Container (EF E103).
-  const candidates: Array<[number, number]> = []
+  // NTAG424 Bolt Cards use NDEF FileID E104. Try it (and 0004) directly to
+  // minimise APDU round-trips over a flaky RF link; only fall back to reading
+  // the Capability Container to discover the id if both direct reads fail.
+  for (const fid of [[0xe1, 0x04] as [number, number], [0x00, 0x04] as [number, number]]) {
+    const found = await readNdefFile(send, fid)
+    if (found) return found
+  }
   if (swOk(await send([0x00, 0xa4, 0x00, 0x0c, 0x02, 0xe1, 0x03]))) {
     const cc = await send([0x00, 0xb0, 0x00, 0x00, 0x0f])
     // CC layout: …[07]=TLV tag 0x04, [08]=len, [09..10]=NDEF FileID.
-    if (swOk(cc) && cc.length >= 13 && cc[7] === 0x04) candidates.push([cc[9], cc[10]])
-  }
-  for (const fid of [[0xe1, 0x04] as [number, number], [0x00, 0x04] as [number, number]]) {
-    if (!candidates.some((c) => c[0] === fid[0] && c[1] === fid[1])) candidates.push(fid)
-  }
-
-  for (const fid of candidates) {
-    const found = await readNdefFile(send, fid)
-    if (found) return found
+    if (swOk(cc) && cc.length >= 13 && cc[7] === 0x04) {
+      const found = await readNdefFile(send, [cc[9], cc[10]])
+      if (found) return found
+    }
   }
   return null
 }
@@ -157,12 +157,19 @@ export async function startNfcReader(
 
     r.on('card', async () => {
       onStatus({ state: 'reading', reader: name })
+      // Single attempt: hammering a flaky RF link with retries wedges these
+      // cheap CCID readers. A read is a few APDU round-trips; if the card
+      // shifts mid-read the transmit fails and the user simply re-taps.
       try {
         const lnurlw = await readNdefLnurlw((apdu, maxLen) => r.transmit(apdu, maxLen))
-        if (lnurlw) onCard(lnurlw)
-        else onStatus({ state: 'error', reader: name, message: 'not a Bolt Card' })
+        if (lnurlw) {
+          onCard(lnurlw)
+        } else {
+          onStatus({ state: 'error', reader: name, message: 'not a Bolt Card' })
+        }
       } catch (e) {
-        onStatus({ state: 'error', reader: name, message: errMsg(e) })
+        onStatus({ state: 'error', reader: name, message: 'card read failed — hold steady & retap' })
+        void e
       }
     })
     r.on('card.off', () => onStatus({ state: 'card-removed', reader: name }))

From 73376a6c68b79bdd7ba57ea19a1b399c159dcad2 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Wed, 5 Aug 2026 20:46:18 +0200
Subject: [PATCH 73/82] fix(machine): cooldown after failed NFC read to prevent
 reader wedge
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hammering a flaky CCID reader with rapid re-reads wedges it into a
present↔empty storm (only a USB replug clears it). After a failed read,
ignore card re-detections for 1.5s; successful reads don't cool down.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/nfc-service.ts | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/apps/machine/electron/nfc-service.ts b/apps/machine/electron/nfc-service.ts
index 970d17d..ca9ace1 100644
--- a/apps/machine/electron/nfc-service.ts
+++ b/apps/machine/electron/nfc-service.ts
@@ -155,22 +155,28 @@ export async function startNfcReader(
     r.autoProcessing = false
     onStatus({ state: 'ready', reader: name })
 
+    // Cooldown after a failed read: these cheap CCID readers can get wedged into
+    // a present↔empty storm when hammered, so ignore re-detections for a beat
+    // after a failure. Successful reads don't cool down.
+    let cooldownUntil = 0
     r.on('card', async () => {
+      if (Date.now() < cooldownUntil) return
       onStatus({ state: 'reading', reader: name })
-      // Single attempt: hammering a flaky RF link with retries wedges these
-      // cheap CCID readers. A read is a few APDU round-trips; if the card
-      // shifts mid-read the transmit fails and the user simply re-taps.
+      // Single attempt: retrying hammers a flaky RF link. A read is a few APDU
+      // round-trips; if the card shifts mid-read the transmit fails and the
+      // user simply re-taps.
       try {
         const lnurlw = await readNdefLnurlw((apdu, maxLen) => r.transmit(apdu, maxLen))
         if (lnurlw) {
           onCard(lnurlw)
-        } else {
-          onStatus({ state: 'error', reader: name, message: 'not a Bolt Card' })
+          return
         }
+        onStatus({ state: 'error', reader: name, message: 'not a Bolt Card' })
       } catch (e) {
         onStatus({ state: 'error', reader: name, message: 'card read failed — hold steady & retap' })
         void e
       }
+      cooldownUntil = Date.now() + 1500
     })
     r.on('card.off', () => onStatus({ state: 'card-removed', reader: name }))
     r.on('error', (err: unknown) =>

From 64582e7fe65a1775abdca4b15e84bcfa9fb15526 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Thu, 6 Aug 2026 00:30:13 +0200
Subject: [PATCH 74/82] feat(machine): Bolt Card (NFC) tap-to-receive on
 cash-in
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tap-to-receive for the buy flow, the receive counterpart to #83's
cash-out tap-to-pay. A Bolt Card only emits an lnurlw withdraw voucher
(wrong direction to deposit into it), so the tap is used as an
authenticated identity (external_id + SUN p/c) to resolve the card
wallet's lnurlp/Lightning Address; the ATM then pays an invoice for the
payout over its existing nostr transport.

- electron/lnurl-pay.ts: resolveCardInvoice() — resolve card -> pay
  target -> LUD-16/LUD-06 -> BOLT11. scanUrlToResolver() is the single
  HTTPS-today / nostr-tomorrow transport seam. 13 tests.
- IPC lnurl:pay-card (main-process HTTPS to dodge renderer CORS) +
  preload/electron.d.ts surface.
- stores/atm.ts: handleBoltCardReceive() settles via the existing
  payInvoice -> PAYMENT_RECEIVED path; the one NFC listener now routes
  the same tap by flow (cash-out pulls, cash-in receives).
- CashInView.vue: NFC status + dev tap input.
- docs/boltcard-receive-resolver.md: spec for the custom LNbits
  /boltcards/api/v1/pay/<id> resolver endpoint (omni-private side).

Card issuance is unchanged — same NDEF/keys/external_id; receive is a
server-side reading of the same tap.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/lnurl-pay.test.ts | 120 +++++++++++++
 apps/machine/electron/lnurl-pay.ts      | 226 ++++++++++++++++++++++++
 apps/machine/electron/main.ts           |  23 ++-
 apps/machine/electron/preload.ts        |  11 ++
 apps/machine/src/stores/atm.ts          |  86 +++++++--
 apps/machine/src/types/electron.d.ts    |   5 +
 apps/machine/src/views/CashInView.vue   |  55 +++++-
 docs/boltcard-receive-resolver.md       | 110 ++++++++++++
 8 files changed, 605 insertions(+), 31 deletions(-)
 create mode 100644 apps/machine/electron/lnurl-pay.test.ts
 create mode 100644 apps/machine/electron/lnurl-pay.ts
 create mode 100644 docs/boltcard-receive-resolver.md

diff --git a/apps/machine/electron/lnurl-pay.test.ts b/apps/machine/electron/lnurl-pay.test.ts
new file mode 100644
index 0000000..165688f
--- /dev/null
+++ b/apps/machine/electron/lnurl-pay.test.ts
@@ -0,0 +1,120 @@
+import { describe, it, expect, vi } from 'vitest'
+import { resolveCardInvoice, scanUrlToResolver, lnAddressToLnurlp } from './lnurl-pay'
+
+const LNURLW =
+  'lnurlw://lnbits.l484.com/boltcards/api/v1/scan/abc123?p=DEADBEEFDEADBEEFDEADBEEFDEADBEEF&c=1122334455667788'
+const BOLT11 = 'lnbc10u1p3xyz...'
+
+/** Mock fetch that returns the given JSON bodies per call, in order. */
+function mockFetch(bodies: unknown[]) {
+  const calls: string[] = []
+  const impl = vi.fn(async (url: string | URL) => {
+    calls.push(url.toString())
+    const body = bodies[calls.length - 1]
+    return { json: async () => body } as Response
+  })
+  return { impl: impl as unknown as typeof fetch, calls }
+}
+
+describe('scanUrlToResolver', () => {
+  it('rewrites /scan/ to /pay/ and preserves p + c', () => {
+    const r = scanUrlToResolver(LNURLW)
+    expect(r).toContain('https://lnbits.l484.com/boltcards/api/v1/pay/abc123')
+    expect(r).toContain('p=DEADBEEFDEADBEEFDEADBEEFDEADBEEF')
+    expect(r).toContain('c=1122334455667788')
+  })
+  it('returns null for a non-scan URL', () => {
+    expect(scanUrlToResolver('lnurlw://host/somethingelse?p=1&c=2')).toBeNull()
+    expect(scanUrlToResolver('http://host/boltcards/api/v1/scan/x')).toBeNull()
+  })
+})
+
+describe('lnAddressToLnurlp', () => {
+  it('maps name@host to the well-known lnurlp URL', () => {
+    expect(lnAddressToLnurlp('cardname@l484.com')).toBe(
+      'https://l484.com/.well-known/lnurlp/cardname'
+    )
+  })
+  it('rejects non-addresses', () => {
+    expect(lnAddressToLnurlp('not-an-address')).toBeNull()
+    expect(lnAddressToLnurlp('')).toBeNull()
+  })
+})
+
+describe('resolveCardInvoice', () => {
+  const payReq = {
+    tag: 'payRequest',
+    callback: 'https://lnbits.l484.com/lnurlp/api/v1/lnurl/cb',
+    minSendable: 1000,
+    maxSendable: 100_000_000,
+    metadata: '[["text/plain","bolt card top-up"]]',
+  }
+
+  it('resolver returns a payRequest inline → fetches the invoice', async () => {
+    const { impl, calls } = mockFetch([payReq, { pr: BOLT11 }])
+    const res = await resolveCardInvoice(LNURLW, 21_000, { fetchImpl: impl })
+    expect(res).toEqual({ ok: true, bolt11: BOLT11 })
+    // 1st call = the /pay resolver; 2nd = the callback with amount in msat.
+    expect(calls[0]).toContain('/boltcards/api/v1/pay/abc123')
+    expect(calls[1]).toContain('amount=21000')
+  })
+
+  it('resolver returns a Lightning Address → LUD-16 → invoice', async () => {
+    const { impl, calls } = mockFetch([
+      { lightningAddress: 'cardname@l484.com' },
+      payReq,
+      { pr: BOLT11 },
+    ])
+    const res = await resolveCardInvoice(LNURLW, 21_000, { fetchImpl: impl })
+    expect(res).toEqual({ ok: true, bolt11: BOLT11 })
+    expect(calls[1]).toBe('https://l484.com/.well-known/lnurlp/cardname')
+    expect(calls[2]).toContain('amount=21000')
+  })
+
+  it('rejects a non-lnurlw tag', async () => {
+    const { impl } = mockFetch([])
+    const res = await resolveCardInvoice('http://nope', 21_000, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false })
+    expect(res.reason).toMatch(/not a valid Bolt Card/i)
+  })
+
+  it('rejects a zero amount', async () => {
+    const { impl } = mockFetch([])
+    const res = await resolveCardInvoice(LNURLW, 0, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'no amount to send' })
+  })
+
+  it('surfaces an ERROR from the resolver (bad SUN)', async () => {
+    const { impl } = mockFetch([{ status: 'ERROR', reason: 'invalid card' }])
+    const res = await resolveCardInvoice(LNURLW, 21_000, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'invalid card' })
+  })
+
+  it('rejects (without calling the callback) when the amount exceeds maxSendable', async () => {
+    const { impl, calls } = mockFetch([{ ...payReq, maxSendable: 5000 }])
+    const res = await resolveCardInvoice(LNURLW, 21_000, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'amount is above the card wallet maximum' })
+    expect(calls).toHaveLength(1) // callback never hit
+  })
+
+  it('surfaces an ERROR from the pay callback', async () => {
+    const { impl } = mockFetch([payReq, { status: 'ERROR', reason: 'wallet frozen' }])
+    const res = await resolveCardInvoice(LNURLW, 21_000, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'wallet frozen' })
+  })
+
+  it('rejects when the card wallet has no receive address', async () => {
+    const { impl } = mockFetch([{ foo: 'bar' }])
+    const res = await resolveCardInvoice(LNURLW, 21_000, { fetchImpl: impl })
+    expect(res).toMatchObject({ ok: false, reason: 'card wallet has no receive address' })
+  })
+
+  it('handles a network failure gracefully', async () => {
+    const impl = vi.fn(async () => {
+      throw new Error('ECONNREFUSED')
+    }) as unknown as typeof fetch
+    const res = await resolveCardInvoice(LNURLW, 21_000, { fetchImpl: impl })
+    expect(res.ok).toBe(false)
+    expect(res.reason).toMatch(/could not reach the card/i)
+  })
+})
diff --git a/apps/machine/electron/lnurl-pay.ts b/apps/machine/electron/lnurl-pay.ts
new file mode 100644
index 0000000..91da90c
--- /dev/null
+++ b/apps/machine/electron/lnurl-pay.ts
@@ -0,0 +1,226 @@
+/**
+ * LNURL-pay resolver (LUD-06 / LUD-16) — the ATM as the *paying* party.
+ *
+ * Bolt Card tap-to-RECEIVE for the cash-in (buy) flow. A Bolt Card only ever
+ * emits its `lnurlw://…?p=…&c=…` voucher — a *withdraw* (spend) credential — so
+ * we can't push sats into it directly. Instead the tap is used as an
+ * authenticated identity (external_id + SUN p/c) to look up the card wallet's
+ * *pay* target, then the ATM fetches an invoice for the payout amount:
+ *   1. resolveCardPayTarget — GET the boltcards `/pay/<id>?p=&c=` resolver
+ *      (a sibling of `/scan`); it verifies the same SUN and returns the card
+ *      wallet's Lightning Address / lnurlp (or a LUD-06 payRequest directly).
+ *   2. toPayRequest → LUD-16 (Lightning Address) or LUD-06 fetch → payRequest.
+ *   3. requestInvoice — GET `callback?amount=<msat>` → a BOLT11 for the amount.
+ * The returned BOLT11 is handed back to the renderer, which pays it over the
+ * ATM's existing LNbits/nostr transport (stores/atm.ts `payInvoice`), so
+ * settlement + PAYMENT_RECEIVED reuse the tested cash-in completion path.
+ *
+ * Runs in the MAIN process (Node fetch) to avoid renderer CORS, exactly like
+ * lnurl-withdraw.ts.
+ *
+ * Transport seam: `resolveCardPayTarget()` is the single HTTPS-today /
+ * Nostr-tomorrow swap point. The rest is standard LNURL-pay against whatever
+ * pay target it returns and is transport-independent.
+ */
+
+import { lnurlwToHttps } from './lnurl-withdraw.js'
+
+export interface ResolveCardInvoiceResult {
+  ok: boolean
+  /** BOLT11 to pay when ok; the renderer settles it over the nostr transport. */
+  bolt11?: string
+  /** Human-readable reason when ok is false (safe to surface on-screen). */
+  reason?: string
+}
+
+type FetchLike = typeof fetch
+
+export interface ResolveCardInvoiceOptions {
+  /** Injected for tests; defaults to global fetch. */
+  fetchImpl?: FetchLike
+  /** Per-request timeout (default 15s). */
+  timeoutMs?: number
+}
+
+/** Resolver response — any of these shapes is accepted (see the spec doc). */
+interface CardPayTarget {
+  status?: string
+  reason?: string
+  // (a) a LUD-06 payRequest, inline
+  tag?: string
+  callback?: string
+  minSendable?: number
+  maxSendable?: number
+  metadata?: string
+  // (b) a Lightning Address, e.g. "cardname@l484.com"
+  lightningAddress?: string
+  // (c) an lnurlp pointer (https or lnurl://)
+  lnurlp?: string
+  lnurl?: string
+}
+
+/** LUD-06 payRequest (subset) + error shape. */
+interface PayRequest {
+  tag?: string
+  callback?: string
+  minSendable?: number
+  maxSendable?: number
+  metadata?: string
+  status?: string
+  reason?: string
+}
+
+/** LUD-06 second-response (the callback body). */
+interface PayValues {
+  pr?: string
+  status?: string
+  reason?: string
+}
+
+interface Ctx {
+  doFetch: FetchLike
+  timeoutMs: number
+}
+
+function errMsg(e: unknown): string {
+  if (e instanceof Error)
+    return e.name === 'TimeoutError' || e.name === 'AbortError' ? 'timed out' : e.message
+  return String(e)
+}
+
+function appendQuery(url: string, params: Record<string, string>): string {
+  const u = new URL(url)
+  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v)
+  return u.toString()
+}
+
+/**
+ * Derive the boltcards *pay* resolver URL from a tapped card's `lnurlw`.
+ * The card presents `…/boltcards/api/v1/scan/<id>?p=&c=` (a withdraw voucher);
+ * the receive resolver is its sibling `…/boltcards/api/v1/pay/<id>?p=&c=`,
+ * carrying the same SUN p/c. This is the HTTPS transport seam — a future
+ * nostr-native card would resolve the same identity over nostr instead.
+ */
+export function scanUrlToResolver(lnurlw: string): string | null {
+  const https = lnurlwToHttps(lnurlw)
+  if (!https) return null
+  const u = new URL(https)
+  if (!u.pathname.includes('/scan/')) return null
+  u.pathname = u.pathname.replace('/scan/', '/pay/')
+  return u.toString()
+}
+
+/** LUD-16: map a Lightning Address `name@host` to its lnurlp URL. */
+export function lnAddressToLnurlp(addr: string): string | null {
+  const m = addr.trim().match(/^([a-z0-9._%+-]+)@([a-z0-9.-]+)$/i)
+  if (!m) return null
+  return `https://${m[2]}/.well-known/lnurlp/${m[1]}`
+}
+
+async function fetchPayRequest(
+  url: string,
+  ctx: Ctx
+): Promise<{ ok: true; payRequest: PayRequest } | { ok: false; reason: string }> {
+  let body: PayRequest
+  try {
+    const res = await ctx.doFetch(url, { signal: AbortSignal.timeout(ctx.timeoutMs) })
+    body = (await res.json()) as PayRequest
+  } catch (e) {
+    return { ok: false, reason: `could not reach the card wallet: ${errMsg(e)}` }
+  }
+  if (body.status === 'ERROR') {
+    return { ok: false, reason: body.reason || 'card wallet rejected the request' }
+  }
+  if (body.tag !== 'payRequest' || !body.callback) {
+    return { ok: false, reason: 'card wallet did not return a pay request' }
+  }
+  return { ok: true, payRequest: body }
+}
+
+/** Turn a resolver response into a LUD-06 payRequest (fetching if needed). */
+async function toPayRequest(
+  target: CardPayTarget,
+  ctx: Ctx
+): Promise<{ ok: true; payRequest: PayRequest } | { ok: false; reason: string }> {
+  // (a) resolver returned a LUD-06 payRequest inline.
+  if (target.tag === 'payRequest' && target.callback) {
+    return { ok: true, payRequest: target }
+  }
+  // (b) resolver returned a Lightning Address (the common case here).
+  if (typeof target.lightningAddress === 'string') {
+    const url = lnAddressToLnurlp(target.lightningAddress)
+    if (!url) return { ok: false, reason: 'card wallet address is invalid' }
+    return fetchPayRequest(url, ctx)
+  }
+  // (c) resolver returned an lnurlp pointer.
+  const pointer = target.lnurlp ?? target.lnurl
+  if (typeof pointer === 'string') {
+    const url = lnurlwToHttps(pointer)
+    if (!url) return { ok: false, reason: 'card wallet lnurlp is invalid' }
+    return fetchPayRequest(url, ctx)
+  }
+  return { ok: false, reason: 'card wallet has no receive address' }
+}
+
+async function requestInvoice(
+  pr: PayRequest,
+  amountMsat: number,
+  ctx: Ctx
+): Promise<ResolveCardInvoiceResult> {
+  if (typeof pr.minSendable === 'number' && amountMsat < pr.minSendable) {
+    return { ok: false, reason: 'amount is below the card wallet minimum' }
+  }
+  if (typeof pr.maxSendable === 'number' && amountMsat > pr.maxSendable) {
+    return { ok: false, reason: 'amount is above the card wallet maximum' }
+  }
+  const cbUrl = appendQuery(pr.callback!, { amount: String(amountMsat) })
+  let vals: PayValues
+  try {
+    const res = await ctx.doFetch(cbUrl, { signal: AbortSignal.timeout(ctx.timeoutMs) })
+    vals = (await res.json()) as PayValues
+  } catch (e) {
+    return { ok: false, reason: `could not fetch the invoice: ${errMsg(e)}` }
+  }
+  if (vals.status === 'ERROR') {
+    return { ok: false, reason: vals.reason || 'card wallet declined' }
+  }
+  if (!vals.pr || !/^ln[a-z0-9]/i.test(vals.pr.trim())) {
+    return { ok: false, reason: 'card wallet returned no invoice' }
+  }
+  return { ok: true, bolt11: vals.pr.trim() }
+}
+
+/**
+ * Resolve a tapped Bolt Card + a payout amount to a BOLT11 the ATM can pay.
+ * Never throws — every failure returns `{ ok: false, reason }`.
+ */
+export async function resolveCardInvoice(
+  lnurlw: string,
+  amountMsat: number,
+  opts: ResolveCardInvoiceOptions = {}
+): Promise<ResolveCardInvoiceResult> {
+  const ctx: Ctx = { doFetch: opts.fetchImpl ?? fetch, timeoutMs: opts.timeoutMs ?? 15_000 }
+
+  const resolverUrl = scanUrlToResolver(lnurlw)
+  if (!resolverUrl) return { ok: false, reason: 'not a valid Bolt Card (lnurlw) tag' }
+  if (!(amountMsat > 0)) return { ok: false, reason: 'no amount to send' }
+
+  // 1) Resolve card → pay target (the transport seam: HTTPS today).
+  let target: CardPayTarget
+  try {
+    const res = await ctx.doFetch(resolverUrl, { signal: AbortSignal.timeout(ctx.timeoutMs) })
+    target = (await res.json()) as CardPayTarget
+  } catch (e) {
+    return { ok: false, reason: `could not reach the card: ${errMsg(e)}` }
+  }
+  if (target.status === 'ERROR') {
+    return { ok: false, reason: target.reason || 'card rejected the tap' }
+  }
+
+  // 2) Normalize to a LUD-06 payRequest.
+  const pr = await toPayRequest(target, ctx)
+  if (!pr.ok) return pr
+
+  // 3) Ask for an invoice for the payout amount.
+  return requestInvoice(pr.payRequest, amountMsat, ctx)
+}
diff --git a/apps/machine/electron/main.ts b/apps/machine/electron/main.ts
index 81676cf..6cfcb20 100644
--- a/apps/machine/electron/main.ts
+++ b/apps/machine/electron/main.ts
@@ -43,6 +43,7 @@ import {
 } from './state-store.js'
 import { initializeHal, type HalInstance } from './hal-service.js'
 import { executeLnurlWithdraw } from './lnurl-withdraw.js'
+import { resolveCardInvoice } from './lnurl-pay.js'
 import { startNfcReader, type NfcStatus } from './nfc-service.js'
 
 // ESM equivalent of __dirname
@@ -120,9 +121,7 @@ function loadBranding(): BrandingConfig | null {
         if (Object.keys(colors).length > 0) customColors = colors
         if (dark && typeof dark === 'object') {
           const darkColors = Object.fromEntries(
-            Object.entries(dark as Record<string, unknown>).filter(
-              ([, v]) => typeof v === 'string'
-            )
+            Object.entries(dark as Record<string, unknown>).filter(([, v]) => typeof v === 'string')
           ) as Record<string, string>
           if (Object.keys(darkColors).length > 0) customColorsDark = darkColors
         }
@@ -431,6 +430,20 @@ ipcMain.handle(
   }
 )
 
+// Bolt Card cash-in (receive): resolve a tapped card + payout amount to a
+// BOLT11 on the card wallet, which the renderer then pays over the nostr
+// transport (stores/atm.ts payInvoice). HTTPS to the card host runs here in the
+// main process to dodge renderer CORS. See lnurl-pay.ts.
+ipcMain.handle(
+  'lnurl:pay-card',
+  async (
+    _event,
+    args: { lnurlw: string; amountMsat: number }
+  ): Promise<{ ok: boolean; bolt11?: string; reason?: string }> => {
+    return resolveCardInvoice(args.lnurlw, args.amountMsat)
+  }
+)
+
 // State persistence IPC handlers
 ipcMain.handle('state:load-cassettes', () => loadCassettes())
 ipcMain.handle('state:set-cassettes', (_event, cassettes) => setCassettes(cassettes))
@@ -447,9 +460,7 @@ ipcMain.handle('state:remediate-transaction', (_event, txid: string, remediatedB
 ipcMain.handle('state:get-last-known-config-created-at', (): number =>
   getLastKnownConfigCreatedAt()
 )
-ipcMain.handle('state:get-bootstrap-published-at', (): number | null =>
-  getBootstrapPublishedAt()
-)
+ipcMain.handle('state:get-bootstrap-published-at', (): number | null => getBootstrapPublishedAt())
 ipcMain.handle('state:mark-bootstrap-published', (_event, unixTimestamp: number): void => {
   markBootstrapPublished(unixTimestamp)
 })
diff --git a/apps/machine/electron/preload.ts b/apps/machine/electron/preload.ts
index 8be0ed8..8ced2d5 100644
--- a/apps/machine/electron/preload.ts
+++ b/apps/machine/electron/preload.ts
@@ -134,6 +134,13 @@ contextBridge.exposeInMainWorld('electronAPI', {
     amountMsat?: number
   }): Promise<{ ok: boolean; reason?: string }> => ipcRenderer.invoke('lnurl:withdraw', args),
 
+  // Bolt Card cash-in: resolve a tapped card + amount to a BOLT11 to pay.
+  resolveCardInvoice: (args: {
+    lnurlw: string
+    amountMsat: number
+  }): Promise<{ ok: boolean; bolt11?: string; reason?: string }> =>
+    ipcRenderer.invoke('lnurl:pay-card', args),
+
   applyOperatorCassettesConfig: (
     payload: {
       positions: Record<string, { denomination: number; count: number }>
@@ -272,6 +279,10 @@ declare global {
         bolt11: string
         amountMsat?: number
       }) => Promise<{ ok: boolean; reason?: string }>
+      resolveCardInvoice: (args: {
+        lnurlw: string
+        amountMsat: number
+      }) => Promise<{ ok: boolean; bolt11?: string; reason?: string }>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number
diff --git a/apps/machine/src/stores/atm.ts b/apps/machine/src/stores/atm.ts
index 06dea22..db1a124 100644
--- a/apps/machine/src/stores/atm.ts
+++ b/apps/machine/src/stores/atm.ts
@@ -11,14 +11,8 @@ import {
 } from '@bitSpire/state-machine'
 import { initializeLightningServices, fetchBtcPrice } from '@/services/lightning'
 import { classifyInitError } from '@/services/init-error'
-import {
-  startOperatorConfigService,
-  type OperatorConfigService,
-} from '@/services/operator-config'
-import {
-  startOperatorFeesService,
-  type OperatorFeesService,
-} from '@/services/operator-fees'
+import { startOperatorConfigService, type OperatorConfigService } from '@/services/operator-config'
+import { startOperatorFeesService, type OperatorFeesService } from '@/services/operator-fees'
 import type { HalConfig, HalServices } from '@/services/hal'
 import type { MachineModel } from '@/config'
 import type { LightningBackend } from '@/services/lightning'
@@ -52,7 +46,8 @@ function computeFeeSats(ctx: ATMContext, isCashIn: boolean): number {
         `Unit fraction expected (0.05 = 5%), not a percentage.`
     )
   }
-  const principalSats = ctx.exchangeRate > 0 ? Math.floor((ctx.fiatCents / 100) * ctx.exchangeRate) : 0
+  const principalSats =
+    ctx.exchangeRate > 0 ? Math.floor((ctx.fiatCents / 100) * ctx.exchangeRate) : 0
   const feeSats = isCashIn
     ? principalSats - ctx.satsAmount // cash-in: customer receives less than principal
     : ctx.satsAmount - principalSats // cash-out: customer pays more than principal
@@ -567,9 +562,13 @@ export const useAtmStore = defineStore('atm', () => {
         }
       }
 
-      // Clear Bolt Card state whenever we leave the invoice screen (dispensed,
-      // timed out, or cancelled) so a stale "processing"/error can't linger.
-      if (currentNested !== 'displayingInvoice' && prevNestedState === 'displayingInvoice') {
+      // Clear Bolt Card state whenever we leave a tap screen — the cash-out
+      // invoice ('displayingInvoice') or the cash-in QR ('displayingQR') — so a
+      // stale "processing"/error can't linger into the next flow.
+      const leftBoltCardScreen =
+        (prevNestedState === 'displayingInvoice' && currentNested !== 'displayingInvoice') ||
+        (prevNestedState === 'displayingQR' && currentNested !== 'displayingQR')
+      if (leftBoltCardScreen) {
         boltCardProcessing.value = false
         nfcStatus.value = null
       }
@@ -614,26 +613,76 @@ export const useAtmStore = defineStore('atm', () => {
     }
   }
 
+  /**
+   * A tapped Bolt Card during the cash-in QR screen: RECEIVE sats to the card.
+   * The card's lnurlw is only a spend voucher, so we resolve it to the card
+   * wallet's lnurlp (main process), fetch an invoice for the payout, and pay it
+   * over the nostr transport via the normal `payInvoice` → PAYMENT_RECEIVED
+   * path. Settlement + completion reuse the tested cash-in flow.
+   */
+  async function handleBoltCardReceive(lnurlw: string) {
+    if (!(isCashIn.value && nestedState.value === 'displayingQR')) return
+    const amountSats = context.value?.satsAmount ?? 0
+    if (amountSats <= 0) return
+    if (boltCardProcessing.value) return // one at a time
+    boltCardProcessing.value = true
+    nfcStatus.value = { state: 'processing', message: 'Reading card…' }
+    try {
+      const amountMsat = amountSats * 1000
+      const res = await window.electronAPI!.resolveCardInvoice({ lnurlw, amountMsat })
+      if (!res.ok || !res.bolt11) {
+        boltCardProcessing.value = false
+        nfcStatus.value = { state: 'declined', message: res.reason ?? 'Card could not receive' }
+        return
+      }
+      nfcStatus.value = { state: 'accepted', message: 'Card found — sending sats…' }
+      const paid = await payInvoice(res.bolt11)
+      if (!paid) {
+        boltCardProcessing.value = false
+        nfcStatus.value = { state: 'error', message: paymentError.value ?? 'Payment failed' }
+      }
+      // On success payInvoice fires PAYMENT_RECEIVED; state leaves displayingQR
+      // and the subscribe-cleanup above resets nfcStatus/boltCardProcessing.
+    } catch (e) {
+      console.warn('[ATM] Bolt Card receive failed:', e)
+      boltCardProcessing.value = false
+      nfcStatus.value = { state: 'error', message: 'Card payment failed' }
+    }
+  }
+
   /** Wire the main-process reader once (idempotent via preload removeAllListeners). */
   function setupNfcListener() {
     if (!isElectron || !window.electronAPI?.onNfcCardTapped) return
     window.electronAPI.onNfcCardTapped((lnurlw) => {
-      void handleBoltCardTap(lnurlw)
+      // Route the same physical tap by flow: cash-out pulls, cash-in receives.
+      if (isCashOut.value && nestedState.value === 'displayingInvoice') {
+        void handleBoltCardTap(lnurlw)
+      } else if (isCashIn.value && nestedState.value === 'displayingQR') {
+        void handleBoltCardReceive(lnurlw)
+      }
     })
     window.electronAPI.onNfcStatus?.((status) => {
-      // Only surface reader status on the invoice screen, and don't clobber an
-      // in-flight pull's message.
-      if (nestedState.value === 'displayingInvoice' && !boltCardProcessing.value) {
+      // Only surface reader status on a tap screen, and don't clobber an
+      // in-flight tap's message.
+      const onTapScreen =
+        (isCashOut.value && nestedState.value === 'displayingInvoice') ||
+        (isCashIn.value && nestedState.value === 'displayingQR')
+      if (onTapScreen && !boltCardProcessing.value) {
         nfcStatus.value = status
       }
     })
   }
 
-  /** Dev/mock: simulate a tap with a pasted lnurlw (test without a card). */
+  /** Dev/mock: simulate a cash-out tap with a pasted lnurlw (test without a card). */
   function simulateBoltCardTap(lnurlw: string) {
     void handleBoltCardTap(lnurlw)
   }
 
+  /** Dev/mock: simulate a cash-in (receive) tap with a pasted lnurlw. */
+  function simulateBoltCardReceive(lnurlw: string) {
+    void handleBoltCardReceive(lnurlw)
+  }
+
   /**
    * Group an array of inserted bill denominations into { denomination, count } pairs.
    */
@@ -1586,10 +1635,11 @@ export const useAtmStore = defineStore('atm', () => {
     isCashOut,
     nestedState,
 
-    // Bolt Card cash-out (NFC)
+    // Bolt Card (NFC): cash-out pulls, cash-in receives
     nfcStatus,
     boltCardProcessing,
     simulateBoltCardTap,
+    simulateBoltCardReceive,
 
     // Actions
     initialize,
diff --git a/apps/machine/src/types/electron.d.ts b/apps/machine/src/types/electron.d.ts
index d391944..0e5846d 100644
--- a/apps/machine/src/types/electron.d.ts
+++ b/apps/machine/src/types/electron.d.ts
@@ -109,6 +109,11 @@ declare global {
         bolt11: string
         amountMsat?: number
       }) => Promise<{ ok: boolean; reason?: string }>
+      /** Bolt Card cash-in: resolve a tapped card + amount to a BOLT11 to pay. */
+      resolveCardInvoice: (args: {
+        lnurlw: string
+        amountMsat: number
+      }) => Promise<{ ok: boolean; bolt11?: string; reason?: string }>
       applyOperatorCassettesConfig: (
         payload: { positions: Record<string, { denomination: number; count: number }> },
         eventCreatedAt: number
diff --git a/apps/machine/src/views/CashInView.vue b/apps/machine/src/views/CashInView.vue
index 5210c86..915c113 100644
--- a/apps/machine/src/views/CashInView.vue
+++ b/apps/machine/src/views/CashInView.vue
@@ -48,6 +48,9 @@ const showCancelButton = computed(() => {
 // Invoice input for manual payment
 const invoiceInput = ref('')
 
+// Dev: paste an lnurlw to simulate a Bolt Card tap-to-receive
+const mockLnurlw = ref('')
+
 // Copy state for ndebit URI
 const copied = ref(false)
 
@@ -279,7 +282,9 @@ const isProcessing = computed(() => atmStore.isPayingInvoice)
             <Button
               class="w-full bg-gradient-to-r from-orange-500 to-yellow-400 text-black hover:from-orange-600 hover:to-yellow-500"
               size="kiosk-lg"
-              :disabled="!context || context.billsInserted.length === 0 || context.billPending !== null"
+              :disabled="
+                !context || context.billsInserted.length === 0 || context.billPending !== null
+              "
               @click="finishInserting"
             >
               Done Inserting
@@ -331,10 +336,31 @@ const isProcessing = computed(() => atmStore.isPayingInvoice)
               {{ atmStore.fiatSymbol }}{{ ((context?.fiatCents || 0) / 100).toFixed(2) }}
             </p>
 
-            <!-- Waiting indicator -->
-            <div class="flex items-center gap-3 pt-2 lg:pt-4">
-              <PickaxeIcon :size="32" />
-              <p class="text-sm lg:text-xl text-muted-foreground">Waiting for wallet scan...</p>
+            <!-- Waiting indicator + Bolt Card tap-to-receive status -->
+            <div class="flex flex-col items-center gap-2 pt-2 lg:pt-4">
+              <div class="flex items-center gap-3">
+                <PickaxeIcon :size="32" />
+                <p class="text-sm lg:text-xl text-muted-foreground">
+                  {{
+                    atmStore.boltCardProcessing
+                      ? 'Processing card…'
+                      : isElectron
+                        ? 'Tap your card or scan to receive'
+                        : 'Waiting for wallet scan...'
+                  }}
+                </p>
+              </div>
+              <p
+                v-if="atmStore.nfcStatus?.message"
+                class="text-sm lg:text-lg"
+                :class="
+                  atmStore.nfcStatus.state === 'declined' || atmStore.nfcStatus.state === 'error'
+                    ? 'text-destructive'
+                    : 'text-muted-foreground'
+                "
+              >
+                {{ atmStore.nfcStatus.message }}
+              </p>
             </div>
 
             <!-- LNURL URI (web-ui only) -->
@@ -353,8 +379,8 @@ const isProcessing = computed(() => atmStore.isPayingInvoice)
               </div>
             </div>
 
-            <!-- Debug: Simulate payment button -->
-            <div v-if="atmStore.debugMode" class="pt-2">
+            <!-- Debug: simulate payment / Bolt Card tap-to-receive -->
+            <div v-if="atmStore.debugMode" class="pt-2 flex flex-col items-center gap-2">
               <Button
                 variant="ghost"
                 size="sm"
@@ -363,6 +389,21 @@ const isProcessing = computed(() => atmStore.isPayingInvoice)
               >
                 Dev: Skip to Success
               </Button>
+              <div class="flex items-center gap-2">
+                <input
+                  v-model="mockLnurlw"
+                  placeholder="lnurlw://… (paste to simulate a card tap)"
+                  class="w-56 rounded border border-input bg-background px-2 py-1 text-xs"
+                />
+                <Button
+                  variant="outline"
+                  size="sm"
+                  :disabled="!mockLnurlw"
+                  @click="atmStore.simulateBoltCardReceive(mockLnurlw)"
+                >
+                  Tap
+                </Button>
+              </div>
             </div>
           </div>
 
diff --git a/docs/boltcard-receive-resolver.md b/docs/boltcard-receive-resolver.md
new file mode 100644
index 0000000..d505d3c
--- /dev/null
+++ b/docs/boltcard-receive-resolver.md
@@ -0,0 +1,110 @@
+# Bolt Card tap-to-receive — LNbits resolver endpoint
+
+Spec for the small **custom endpoint** the ATM needs on the LNbits `boltcards`
+extension to support **tap-to-receive** (the cash-in / buy flow). The ATM side
+(`apps/machine/electron/lnurl-pay.ts`) is already built against this contract;
+this document is what to implement in the `omni-private` LNbits fork.
+
+## Why a new endpoint
+
+A Bolt Card only ever emits its `lnurlw://…/scan/<external_id>?p=&c=` voucher —
+a **withdraw** (spend) credential. You cannot push sats _into_ the card with it.
+To deposit to the card's wallet, the ATM uses the same tap as an **authenticated
+identity** (the `external_id` + the SUN `p`/`c`, verified exactly as `/scan`
+does) and needs the wallet's **pay** target back. Stock `boltcards` is
+withdraw-only, so we add a `pay` sibling of `scan`.
+
+The card is **not re-written** — same NDEF, same keys, same `external_id`. Only
+the server learns a new way to answer the same tap.
+
+## Endpoint
+
+```
+GET /boltcards/api/v1/pay/{external_id}?p={p}&c={c}
+```
+
+- Same URL shape as `GET /boltcards/api/v1/scan/{external_id}?p=&c=`, with the
+  path segment `scan` → `pay`. The ATM derives it by string-substitution on the
+  tapped `lnurlw` (`scanUrlToResolver()` in `lnurl-pay.ts`).
+- **Verify `p`/`c` exactly like `/scan`**: decrypt the PICC (`p`) with the
+  card's `k1`, recompute the CMAC (`c`) with `k2`, check the read counter is
+  fresh (monotonic). Reject replays. Reuse the boltcards SUN verification path —
+  do not fork it. A valid `p`/`c` is the authorization: it proves card
+  possession and prevents a cloned UID from misdirecting a deposit.
+- No auth key/header — like `/scan`, this is a public LNURL-style endpoint
+  gated solely by the SUN.
+
+## Response
+
+Return **one** of the following JSON shapes (the ATM accepts all three). Since
+each card wallet has a Lightning Address, either of the first two is simplest.
+
+### (a) Lightning Address (recommended)
+
+```json
+{ "lightningAddress": "cardname@l484.com" }
+```
+
+The ATM resolves it via LUD-16 (`/.well-known/lnurlp/cardname`) → LUD-06 pay.
+
+### (b) LUD-06 payRequest, inline
+
+```json
+{
+  "tag": "payRequest",
+  "callback": "https://lnbits.l484.com/lnurlp/api/v1/lnurl/<id>",
+  "minSendable": 1000,
+  "maxSendable": 100000000,
+  "metadata": "[[\"text/plain\",\"bolt card top-up\"]]"
+}
+```
+
+Hand back the card wallet's existing `lnurlp` payRequest directly (no extra
+round-trip for the ATM).
+
+### (c) lnurlp pointer
+
+```json
+{ "lnurlp": "https://lnbits.l484.com/lnurlp/<id>" }
+```
+
+An `https://` (or `lnurl://`) URL the ATM will fetch to get the payRequest.
+
+### Error
+
+```json
+{ "status": "ERROR", "reason": "invalid card" }
+```
+
+Use for a failed SUN check, a disabled/unknown card, or a wallet with no pay
+target. `reason` is surfaced verbatim on the ATM screen, so keep it terse and
+non-sensitive.
+
+## Flow, end to end
+
+```
+customer inserts cash → ATM owes N sats → customer taps Bolt Card
+  → ATM reads lnurlw (external_id + fresh p/c)
+  → GET /boltcards/api/v1/pay/<external_id>?p=&c=      ← THIS ENDPOINT
+  → { lightningAddress | payRequest | lnurlp }
+  → ATM: LUD-16/LUD-06 → GET callback?amount=<N*1000 msat> → BOLT11
+  → ATM pays the BOLT11 over its own nostr transport → card wallet credited
+  → PAYMENT_RECEIVED → cash-in completes
+```
+
+Amounts are in **millisatoshis** on the LUD-06 callback (`amount=<msat>`), per
+spec. Make sure each card wallet's `minSendable`/`maxSendable` span the ATM's
+payout range or the tap will be declined with "amount is above/below the card
+wallet …".
+
+## Notes
+
+- **Double-payout:** the cash-in screen still shows the LNURL-withdraw QR as a
+  fallback (customer _pulls_). A tap _pays_ instead. The ATM gates re-entry
+  while a tap is in flight and leaves `displayingQR` on success; the withdraw
+  link is `uses:1`. A customer would have to both tap and pull near-simultaneously
+  to double-collect — acceptable for now, revisit if it bites.
+- **Future nostr transport:** `resolveCardPayTarget` (the `/pay` GET) is the one
+  HTTPS-today / nostr-tomorrow seam. A nostr-native boltcard would answer the
+  same `external_id + SUN` identity over the ATM's existing nostr connection,
+  dropping the clearnet HTTPS call. The rest (standard LNURL-pay) is unchanged.

From d00f3c0bbdeced72e2dad8c71c988ca6cde875cc Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Thu, 6 Aug 2026 18:52:33 +0200
Subject: [PATCH 75/82] fix(batm3): make touch calibration immune to USB-boot
 timing race
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

egalax-calibrate polls 30s for the eGalax X device then gives up; on a
slow USB boot usbtouchscreen binds the panel later than that, so the
calibration matrix is never applied and touch registers in the wrong
place ("dead" panel). Seen on cold boots (2/2 today), fine on others —
a nondeterministic race, not a regression.

- Add a udev rule that (re)starts egalax-calibrate the instant the eGalax
  input node appears (SYSTEMD_WANTS) — device-driven, can't lose the race.
- Widen the calibrate poll window 30s -> 120s as a fallback.

Recovery when it does strand: `systemctl restart egalax-calibrate`, or
apply the matrix live via xinput set-prop.
---
 deploy/nixos/hardware/batm3.nix | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/deploy/nixos/hardware/batm3.nix b/deploy/nixos/hardware/batm3.nix
index 40983c9..1d6af0b 100644
--- a/deploy/nixos/hardware/batm3.nix
+++ b/deploy/nixos/hardware/batm3.nix
@@ -173,6 +173,13 @@
     SUBSYSTEM=="tty", ATTRS{serial}=="A9YW78OC", SYMLINK+="ttyMEI", MODE="0666"
     SUBSYSTEM=="tty", ATTRS{serial}=="A9ZF8ELY", SYMLINK+="ttyNFC", MODE="0666"
     ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0eef", ATTRS{idProduct}=="0001", RUN+="${pkgs.bash}/bin/bash -c '${pkgs.kmod}/bin/modprobe usbtouchscreen 2>/dev/null; echo ''$kernel:1.0 > /sys/bus/usb/drivers/usbhid/unbind 2>/dev/null; echo 0eef 0001 > /sys/bus/usb/drivers/usbtouchscreen/new_id 2>/dev/null'"
+    # Belt-and-suspenders for touch calibration: on a slow USB boot the
+    # usbtouchscreen panel can bind AFTER egalax-calibrate's poll window, which
+    # leaves the panel uncalibrated and unresponsive ("dead"). (Re)start the
+    # calibration the instant the eGalax input node actually appears — this is
+    # device-driven, so it cannot lose a boot-timing race no matter how late the
+    # driver hands over. Pairs with egalax-calibrate's own (widened) poll loop.
+    ACTION=="add", SUBSYSTEM=="input", KERNEL=="event*", ATTRS{name}=="eGalax Inc. USB TouchController", TAG+="systemd", ENV{SYSTEMD_WANTS}+="egalax-calibrate.service"
   '';
 
   # Force the X evdev driver on the eGalax (not libinput). The usbtouchscreen
@@ -211,17 +218,21 @@
       Environment = [ "DISPLAY=:0" "XAUTHORITY=/home/bitspire/.Xauthority" ];
       # Wait for the eGalax X device to appear (usbtouchscreen binds a little
       # after display-manager on a USB boot) and retry, instead of a fixed
-      # sleep — more robust to boot timing. Matrix: swap X/Y + invert + scale
-      # to the active panel area (matches the known-good internal install).
+      # sleep — more robust to boot timing. 120s window: on a slow USB boot the
+      # panel has bound as late as ~30-60s after display-manager, so a 30s cap
+      # gave up before the device appeared and left touch dead (this service is
+      # ALSO re-triggered by a udev rule when the input node shows up, so this
+      # loop is the fallback, not the only path). Matrix: swap X/Y + invert +
+      # scale to the active panel area (matches the known-good internal install).
       ExecStart = pkgs.writeShellScript "egalax-calibrate" ''
-        for i in $(${pkgs.coreutils}/bin/seq 1 30); do
+        for i in $(${pkgs.coreutils}/bin/seq 1 120); do
           if ${pkgs.xorg.xinput}/bin/xinput list --name-only 2>/dev/null | ${pkgs.gnugrep}/bin/grep -qx 'eGalax Inc. USB TouchController'; then
             exec ${pkgs.xorg.xinput}/bin/xinput set-prop 'eGalax Inc. USB TouchController' \
               'Coordinate Transformation Matrix' 0 -1.268 1.147 -1.224 0 1.118 0 0 1
           fi
           ${pkgs.coreutils}/bin/sleep 1
         done
-        echo "egalax-calibrate: eGalax device not found after 30s" >&2
+        echo "egalax-calibrate: eGalax device not found after 120s" >&2
         exit 1
       '';
     };

From ffbacafe3958443a845190f97a9eb5fb3dd8e3e1 Mon Sep 17 00:00:00 2001
From: Patrick Mulligan <patjmulligan@protonmail.com>
Date: Thu, 6 Aug 2026 19:51:39 +0200
Subject: [PATCH 76/82] fix(nfc): auto-recover a wedged CCID reader via USB
 power-cycle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Feitian R502-CL (and cheap CCID readers generally) can wedge: it keeps
detecting a card but every APDU returns "card absent or mute", and ONLY a
USB power-cycle clears it — restarting pcscd or the app does not (confirmed
on-device). Until now that left cash-out/cash-in taps dead until a manual
replug.

- nfc-service.ts: count consecutive read failures; after 3 (gated by a 30s
  cooldown so a still-wedged reader can't reset-loop) trigger
  nfc-reader-reset.service. nfc-pcsc then re-detects the reader on USB
  hotplug with no app restart (verified live).
- batm3.nix: nfc-reader-reset.service (oneshot, root) re-binds the reader's
  USB device (a software replug); reader-agnostic via the CCID interface
  class (0x0B) so it also covers a future ACR1252U. A polkit rule lets the
  unprivileged `bitspire` app start just that one unit.

Hardware track (separate): the durable fix is a better reader (ACR1252U —
large antenna for behind-panel, firmware-upgradable). This change makes any
reader's wedge a ~2s self-heal in the meantime.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/machine/electron/nfc-service.ts | 58 ++++++++++++++++++++++++++--
 deploy/nixos/hardware/batm3.nix      | 42 +++++++++++++++++++-
 2 files changed, 96 insertions(+), 4 deletions(-)

diff --git a/apps/machine/electron/nfc-service.ts b/apps/machine/electron/nfc-service.ts
index ca9ace1..e94ddaf 100644
--- a/apps/machine/electron/nfc-service.ts
+++ b/apps/machine/electron/nfc-service.ts
@@ -13,6 +13,8 @@
  * QR path keeps working — cash-out never depends on this.
  */
 
+import { execFile } from 'node:child_process'
+
 export type NfcState = 'ready' | 'reading' | 'error' | 'card-removed' | 'unavailable'
 export interface NfcStatus {
   state: NfcState
@@ -83,7 +85,11 @@ export async function readNdefLnurlw(
   const send = (bytes: number[]) => transmit(Buffer.from(bytes), 256)
 
   // Select the NDEF Tag Application (AID D2760000850101).
-  if (!swOk(await send([0x00, 0xa4, 0x04, 0x00, 0x07, 0xd2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x01, 0x00]))) {
+  if (
+    !swOk(
+      await send([0x00, 0xa4, 0x04, 0x00, 0x07, 0xd2, 0x76, 0x00, 0x00, 0x85, 0x01, 0x01, 0x00])
+    )
+  ) {
     return null
   }
 
@@ -107,6 +113,29 @@ export async function readNdefLnurlw(
 
 let stopFn: (() => void) | null = null
 
+// ── Wedge auto-recovery ───────────────────────────────────────────────────
+// Cheap CCID readers (the Feitian R502-CL especially) occasionally wedge: they
+// keep detecting a card but every APDU returns "card absent or mute", and ONLY
+// a USB power-cycle clears it — pcscd/app restarts do NOT. When we see a run of
+// consecutive read failures we trigger nfc-reader-reset.service (a root oneshot
+// that re-binds the reader's USB device = a software replug); nfc-pcsc then
+// re-detects the reader on hotplug with no app restart. The trigger is gated by
+// a cooldown so a still-wedged reader can't reset-loop. A quality reader (e.g.
+// ACR1252U) wedges far less; this is belt-and-suspenders for any reader.
+const WEDGE_FAILURE_THRESHOLD = 3
+const RESET_COOLDOWN_MS = 30_000
+// Persist across reader re-enumerations (a reset spawns a fresh reader closure).
+let lastReaderResetAt = 0
+
+/** Trigger the privileged USB power-cycle of the reader. Best-effort. */
+function resetWedgedReader(): void {
+  // NixOS: the app runs unprivileged as `bitspire`; a polkit rule authorises it
+  // to start this one unit. systemctl lives at a stable path on the device.
+  execFile('/run/current-system/sw/bin/systemctl', ['start', 'nfc-reader-reset.service'], () => {
+    /* best-effort — if it fails the reader stays wedged until a manual reset */
+  })
+}
+
 /**
  * Start listening for Bolt Card taps. Idempotent. Returns a stop function.
  * Never throws — failures surface via onStatus.
@@ -159,6 +188,10 @@ export async function startNfcReader(
     // a present↔empty storm when hammered, so ignore re-detections for a beat
     // after a failure. Successful reads don't cool down.
     let cooldownUntil = 0
+    // Consecutive failed reads → wedge detection (see resetWedgedReader above).
+    // A completed read (Bolt Card or not) proves the reader is healthy and
+    // clears the count; only a run of thrown transmits trips the reset.
+    let consecutiveFailures = 0
     r.on('card', async () => {
       if (Date.now() < cooldownUntil) return
       onStatus({ state: 'reading', reader: name })
@@ -167,13 +200,30 @@ export async function startNfcReader(
       // user simply re-taps.
       try {
         const lnurlw = await readNdefLnurlw((apdu, maxLen) => r.transmit(apdu, maxLen))
+        consecutiveFailures = 0
         if (lnurlw) {
           onCard(lnurlw)
           return
         }
         onStatus({ state: 'error', reader: name, message: 'not a Bolt Card' })
       } catch (e) {
-        onStatus({ state: 'error', reader: name, message: 'card read failed — hold steady & retap' })
+        consecutiveFailures++
+        if (
+          consecutiveFailures >= WEDGE_FAILURE_THRESHOLD &&
+          Date.now() - lastReaderResetAt > RESET_COOLDOWN_MS
+        ) {
+          // Reader looks wedged — auto power-cycle it (only fix that works).
+          lastReaderResetAt = Date.now()
+          consecutiveFailures = 0
+          onStatus({ state: 'error', reader: name, message: 'reader stuck — auto-resetting…' })
+          resetWedgedReader()
+        } else {
+          onStatus({
+            state: 'error',
+            reader: name,
+            message: 'card read failed — hold steady & retap',
+          })
+        }
         void e
       }
       cooldownUntil = Date.now() + 1500
@@ -182,7 +232,9 @@ export async function startNfcReader(
     r.on('error', (err: unknown) =>
       onStatus({ state: 'error', reader: name, message: errMsg(err) })
     )
-    r.on('end', () => onStatus({ state: 'unavailable', reader: name, message: 'reader disconnected' }))
+    r.on('end', () =>
+      onStatus({ state: 'unavailable', reader: name, message: 'reader disconnected' })
+    )
   })
   nfc.on('error', (err: unknown) => onStatus({ state: 'error', message: errMsg(err) }))
 
diff --git a/deploy/nixos/hardware/batm3.nix b/deploy/nixos/hardware/batm3.nix
index 1d6af0b..79f1b4d 100644
--- a/deploy/nixos/hardware/batm3.nix
+++ b/deploy/nixos/hardware/batm3.nix
@@ -94,7 +94,8 @@
 
   # pcscd gates client access via polkit; without a rule the sandboxed
   # `bitspire` service user is "Rejected unauthorized PC/SC client". Authorize
-  # it to talk to the daemon and the card.
+  # it to talk to the daemon and the card. The second rule lets the app trigger
+  # the NFC reader wedge-recovery service (see nfc-reader-reset below).
   security.polkit.extraConfig = ''
     polkit.addRule(function(action, subject) {
       if ((action.id == "org.debian.pcsc-lite.access_pcsc" ||
@@ -103,8 +104,47 @@
         return polkit.Result.YES;
       }
     });
+    polkit.addRule(function(action, subject) {
+      if (action.id == "org.freedesktop.systemd1.manage-units" &&
+          action.lookup("unit") == "nfc-reader-reset.service" &&
+          subject.user == "bitspire") {
+        return polkit.Result.YES;
+      }
+    });
   '';
 
+  # NFC reader wedge-recovery. The Feitian R502-CL CCID reader (and, less often,
+  # any CCID reader) can wedge: it keeps detecting a card but every APDU returns
+  # "card absent or mute", and ONLY a USB power-cycle clears it — restarting
+  # pcscd or the app does not. This oneshot re-binds the reader's USB device (a
+  # software replug); pcscd + nfc-pcsc then re-detect it on hotplug with no app
+  # restart (verified on-device). The app (unprivileged `bitspire`) starts it via
+  # the polkit rule above when it sees repeated read failures. Reader-agnostic:
+  # it matches the USB CCID interface class (0x0B), so it also covers a future
+  # ACR1252U swap without a config change.
+  systemd.services.nfc-reader-reset = {
+    description = "Power-cycle a wedged CCID NFC reader (USB re-bind)";
+    serviceConfig = {
+      Type = "oneshot";
+      ExecStart = pkgs.writeShellScript "reset-nfc-reader" ''
+        set -u
+        found=0
+        for iface in /sys/bus/usb/devices/*:*/bInterfaceClass; do
+          [ -f "$iface" ] || continue
+          [ "$(${pkgs.coreutils}/bin/cat "$iface" 2>/dev/null)" = "0b" ] || continue
+          ifname=$(${pkgs.coreutils}/bin/basename "$(${pkgs.coreutils}/bin/dirname "$iface")")
+          dev=''${ifname%%:*}
+          echo "reset-nfc-reader: power-cycling CCID reader USB device $dev" >&2
+          echo -n "$dev" > /sys/bus/usb/drivers/usb/unbind 2>/dev/null || true
+          ${pkgs.coreutils}/bin/sleep 2
+          echo -n "$dev" > /sys/bus/usb/drivers/usb/bind 2>/dev/null || true
+          found=1
+        done
+        [ "$found" = 1 ] || { echo "reset-nfc-reader: no CCID reader found" >&2; exit 1; }
+      '';
+    };
+  };
+
   # Disable suspend/hibernate for kiosk
   systemd.targets = {
     sleep.enable = false;

From 1b671bf4075735ff8430e1ea24d561fb91f542f5 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 6 Sep 2026 19:24:15 +0200
Subject: [PATCH 77/82] build(machine): add a web-only build:web target
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The machine app's `build` script runs vue-tsc, the Vite build, two electron
tsc passes and an esbuild bundle. Serving the kiosk as a plain SPA needs only
the middle one, and the electron passes drag in native-addon typings that a
web build has no use for.

Add `build:web` (just `vite build`) with a turbo task that still builds the
workspace packages first via `dependsOn: ["^build"]`, so a consumer can run
`pnpm build:web` at the repo root and get `apps/machine/dist`.

`env: ["VITE_*"]` is declared on the task because the Vite vars are baked into
the bundle at build time — without it turbo would happily serve a cached
build produced under different env.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013A6683cCHnQxFUosx1krY4
---
 apps/machine/package.json | 1 +
 package.json              | 1 +
 turbo.json                | 5 +++++
 3 files changed, 7 insertions(+)

diff --git a/apps/machine/package.json b/apps/machine/package.json
index 7f68db8..cefc699 100644
--- a/apps/machine/package.json
+++ b/apps/machine/package.json
@@ -15,6 +15,7 @@
     "dev:vite": "vite",
     "electron:dev": "tsc -p electron/tsconfig.json && tsc -p electron/tsconfig.preload.json && electron dist-electron/main.js",
     "build": "vue-tsc --noEmit && vite build && tsc -p electron/tsconfig.json && tsc -p electron/tsconfig.preload.json && npx esbuild electron/fund-atm.ts --bundle --platform=node --format=cjs --external:better-sqlite3 --outfile=dist-electron/fund-atm.bundle.cjs",
+    "build:web": "vite build",
     "build:electron": "pnpm build && electron-builder",
     "preview": "vite preview",
     "typecheck": "vue-tsc --noEmit",
diff --git a/package.json b/package.json
index 1cf98b1..6499319 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,7 @@
   "scripts": {
     "dev": "turbo dev",
     "build": "turbo build",
+    "build:web": "turbo build:web",
     "test": "turbo test",
     "lint": "turbo lint",
     "format": "prettier --write .",
diff --git a/turbo.json b/turbo.json
index d6d2fb5..a5a9376 100644
--- a/turbo.json
+++ b/turbo.json
@@ -5,6 +5,11 @@
       "dependsOn": ["^build"],
       "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
     },
+    "build:web": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"],
+      "env": ["VITE_*"]
+    },
     "dev": {
       "cache": false,
       "persistent": true

From ac40ea9bb6e6244934990e4f941a74d0f0dd17e3 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 6 Sep 2026 19:24:15 +0200
Subject: [PATCH 78/82] feat(lnbits): wrap the create_wallet RPC
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The transport has exposed `create_wallet` (AUTH_ACCOUNT) since the RPC
registry was written, but LnbitsClient never wrapped it — the ATM only ever
needed the auto-created default wallet from `list_wallets`.

Add `createWallet(name)` plus its `CreatedWallet` reply type. Account-scoped,
so the envelope deliberately carries no `wallet_id`: that absence is what
makes the server resolve auth to the Account rather than a Wallet. Not
wrapped in `idempotent()` — a retry would mint a duplicate wallet, same
reasoning as create_invoice.

The reply carries the new wallet's adminkey/inkey, hence the type-level note
not to log it verbatim.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013A6683cCHnQxFUosx1krY4
---
 packages/lnbits/src/client.ts | 12 ++++++++++++
 packages/lnbits/src/index.ts  |  1 +
 packages/lnbits/src/types.ts  |  9 +++++++++
 3 files changed, 22 insertions(+)

diff --git a/packages/lnbits/src/client.ts b/packages/lnbits/src/client.ts
index cb3645d..ad212a8 100644
--- a/packages/lnbits/src/client.ts
+++ b/packages/lnbits/src/client.ts
@@ -37,6 +37,7 @@ import type {
   CreateInvoiceBody,
   PayInvoiceBody,
   WalletInfo,
+  CreatedWallet,
   MachineConfigResponse,
   SubscribePaymentsBody,
   SubscribeAck,
@@ -211,6 +212,17 @@ export class LnbitsClient {
     return data ?? []
   }
 
+  /**
+   * Create an additional wallet on the calling account (`create_wallet`).
+   *
+   * Account-scoped (AUTH_ACCOUNT): the envelope carries no `wallet_id`, which
+   * is what makes the server resolve auth to the Account rather than a Wallet.
+   * NOT wrapped in `idempotent()` — a retry would mint a duplicate wallet.
+   */
+  async createWallet(name: string): Promise<CreatedWallet> {
+    return this.sendRpc<CreatedWallet>('create_wallet', { body: { name } })
+  }
+
   /** Pull server-delivered machine config (operator pubkey + fee config) over
    * the authenticated transport — spirekeeper's `get_machine_config` RPC
    * (bitspire#70 P1). Lets a seed-only ATM configure itself with no per-machine
diff --git a/packages/lnbits/src/index.ts b/packages/lnbits/src/index.ts
index 9618a2f..e1e87c1 100644
--- a/packages/lnbits/src/index.ts
+++ b/packages/lnbits/src/index.ts
@@ -66,6 +66,7 @@ export type {
   CreateInvoiceBody,
   PayInvoiceBody,
   WalletInfo,
+  CreatedWallet,
   SubscribePaymentsBody,
   SubscribeAck,
   SubscribePush,
diff --git a/packages/lnbits/src/types.ts b/packages/lnbits/src/types.ts
index dd5e7a9..fdebb95 100644
--- a/packages/lnbits/src/types.ts
+++ b/packages/lnbits/src/types.ts
@@ -112,6 +112,15 @@ export interface WalletInfo {
   balance: number
 }
 
+/** Reply shape of the `create_wallet` RPC — unlike WalletInfo it carries the
+ * fresh wallet's keys, so never log it verbatim. */
+export interface CreatedWallet {
+  id: string
+  name: string
+  adminkey: string
+  inkey: string
+}
+
 // ============================================================================
 // Subscriptions
 // ============================================================================

From 8264dd7472886efb05069c30fc2335457016b2a8 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 6 Sep 2026 19:24:15 +0200
Subject: [PATCH 79/82] feat(machine): VITE_DEMO_TAG for the public web demo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The browser path (no electronAPI) is already a first-class code path:
initializeWithLightning() resolves an EPHEMERAL LocalSigner, allows mock
fallback and leaves debugMode on, so the bill simulator stands in for the
validator. That is what makes a hosted kiosk demo possible at all. Two
things still needed fixing for it.

1. Cursor. `cursor: none` was applied globally for the touchscreen, which in
   an ordinary browser reads as a broken page. Scope it to `.kiosk`, set on
   <html> by main.ts unless VITE_DEMO_TAG is present — so every real machine
   keeps today's behavior and only the demo build shows a pointer.

2. Cleanup. An ephemeral identity per page load is the right call (it isolates
   concurrent visitors, and each fresh account gets its own auto-credit under
   LNBITS_DEMO_MODE, whereas a single baked-in key would be credited once and
   then drain). The cost is a throwaway LNbits account per visit, and nothing
   in an auto-created row distinguishes one: pubkey-set/prvkey-NULL equally
   describes a real ATM.

   A nostr pubkey can't carry a marker — grinding a vanity prefix is far too
   slow to do on page load — and the account/wallet the server auto-creates
   isn't nameable by the client. So when VITE_DEMO_TAG is set the ATM mints
   one extra, never-used wallet whose NAME is the tag, turning the sweep into
   an exact string match instead of a heuristic about what looks disposable.

Both are inert on a real machine: the var is unset outside the demo build.
The marker call is fire-and-forget — losing it degrades cleanup, not the demo.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013A6683cCHnQxFUosx1krY4
---
 apps/machine/.env.example              | 12 ++++++++++++
 apps/machine/src/main.ts               |  7 +++++++
 apps/machine/src/services/lightning.ts | 25 +++++++++++++++++++++++++
 apps/machine/src/style.css             | 11 +++++++----
 4 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/apps/machine/.env.example b/apps/machine/.env.example
index 66541dc..ec66f81 100644
--- a/apps/machine/.env.example
+++ b/apps/machine/.env.example
@@ -73,6 +73,18 @@ VITE_SPIRE_SEED=
 # Show "Under Service" screen and block all transactions
 # VITE_MAINTENANCE_MODE=true
 
+# =============================================================================
+# Public Web Demo
+# =============================================================================
+
+# Set ONLY for the browser demo build (atm.demo.aiolabs.dev). Leave blank on
+# every real machine. When set it:
+#   - keeps the mouse cursor visible (kiosk builds hide it)
+#   - mints one extra, never-used LNbits wallet named with this exact string,
+#     so the throwaway accounts the demo creates (one per page load, each with
+#     its own ephemeral identity) can be swept by name instead of guessed at.
+# VITE_DEMO_TAG=bitspire-web-demo
+
 # =============================================================================
 # Mock Fallback (Production Safety)
 # =============================================================================
diff --git a/apps/machine/src/main.ts b/apps/machine/src/main.ts
index 5f39e0a..8679c87 100644
--- a/apps/machine/src/main.ts
+++ b/apps/machine/src/main.ts
@@ -24,6 +24,13 @@ const router = createRouter({
   ],
 })
 
+// Kiosk chrome (hidden cursor) is the default — every real machine is a
+// touchscreen. The public web demo (VITE_DEMO_TAG) runs in a normal browser,
+// where an invisible pointer just reads as broken.
+if (!import.meta.env.VITE_DEMO_TAG) {
+  document.documentElement.classList.add('kiosk')
+}
+
 // Create Pinia store
 const pinia = createPinia()
 
diff --git a/apps/machine/src/services/lightning.ts b/apps/machine/src/services/lightning.ts
index eb2e1c7..aa6b52c 100644
--- a/apps/machine/src/services/lightning.ts
+++ b/apps/machine/src/services/lightning.ts
@@ -505,6 +505,31 @@ export async function initializeLightningServices(options?: {
   }
   console.log('[Lightning] LNbits wallet:', lnbitsWalletId)
 
+  // ── Public web demo: stamp the throwaway account so it can be swept ──────
+  // The browser demo (atm.demo.aiolabs.dev) runs with an EPHEMERAL identity —
+  // a fresh keypair per page load — so LNbits mints a new account + a fresh
+  // auto-credited wallet for every visitor. That isolation is the point (a
+  // single baked-in key would be credited exactly once and then drain), but it
+  // leaves throwaway accounts behind, and nothing in an auto-created row says
+  // "demo": pubkey-set/prvkey-NULL also describes a real ATM.
+  //
+  // A nostr pubkey can't carry a marker (you'd have to grind a vanity prefix,
+  // far too slow to do on page load), and the account/wallet the server
+  // auto-creates isn't nameable by the client. So we mint one extra,
+  // never-used wallet whose NAME is the tag: sweeping is then an exact string
+  // match on wallet name rather than a heuristic about what looks disposable.
+  //
+  // Unset on every real machine, so this is inert outside the demo build. The
+  // call is fire-and-forget: losing the marker degrades cleanup, not the demo.
+  const demoTag = (import.meta.env.VITE_DEMO_TAG as string | undefined)?.trim()
+  if (demoTag) {
+    void lnbits
+      .createWallet(demoTag)
+      // Never log the reply — create_wallet returns adminkey/inkey.
+      .then(() => console.log('[Lightning] Demo marker wallet created:', demoTag))
+      .catch((e) => console.warn('[Lightning] Demo marker wallet failed:', e))
+  }
+
   // #70 P1: pull operator pubkey + fee config from LNbits over the authenticated
   // transport (spirekeeper#41 `get_machine_config`). A seed-only machine has no
   // VITE_OPERATOR_PUBKEYS, so without this it can't trust its fee config and sits
diff --git a/apps/machine/src/style.css b/apps/machine/src/style.css
index 621cf82..288f0dc 100644
--- a/apps/machine/src/style.css
+++ b/apps/machine/src/style.css
@@ -1,10 +1,13 @@
 @import 'tailwindcss';
 @import 'tw-animate-css';
 
-/* Hide cursor completely on touchscreen kiosk */
-*,
-*::before,
-*::after {
+/* Hide cursor completely on touchscreen kiosk.
+   Scoped to .kiosk (set on <html> by main.ts) so the public web demo, which
+   runs in an ordinary browser with a mouse, keeps a visible pointer. */
+.kiosk,
+.kiosk *,
+.kiosk *::before,
+.kiosk *::after {
   cursor: none !important;
 }
 

From 46e52f6598eb9e69aa637af069c62f247aaaafe4 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sat, 19 Sep 2026 09:58:42 +0200
Subject: [PATCH 80/82] chore: scrub "Lamassu" from shipped labels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The kiosk's <title> still read "Lamassu ATM" — visible as the browser tab
on the public demo, and inherited by the Electron window. The product has
been bitSpire since the rename; Lamassu belongs in the provenance credits
(README, the c0b69d1 boundary note), not on the artifact.

Rename the user-facing labels that ship: the page title, the flake
description (surfaces in `nix flake metadata`), the ISO build banner, the
header comments on the live-USB config / udev rules / app derivation that
land on the machine image, and the workspace packages' descriptions.

Deliberately NOT touched, because they are identifiers rather than labels
and renaming them has deployed-machine consequences:
- VITE_LAMASSU_MACHINE_MODEL / VITE_LAMASSU_FIAT_CODE (provisioned .env)
- LamassuEventKind (exported enum)
- localStorage keys lamassu-theme / lamassu-color-mode (would reset
  every machine's stored theme)
- docker container names + devenv scripts (dev-only)
- the packages/hal Cargo crate name
Hardware names in HAL driver comments ("Lamassu Sintra", "Douro", "Tejo")
stay: those are the physical machines' real names — that IS the credit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013A6683cCHnQxFUosx1krY4
---
 apps/machine/index.html                      | 2 +-
 deploy/nixos/build-iso.sh                    | 2 +-
 deploy/nixos/live.nix                        | 2 +-
 deploy/nixos/udev/99-bitspire-hardware.rules | 2 +-
 flake.nix                                    | 2 +-
 nix/mkAtmApp.nix                             | 2 +-
 packages/hal/package.json                    | 4 ++--
 packages/hal/src/index.ts                    | 2 +-
 packages/nostr-client/package.json           | 2 +-
 packages/nostr-client/src/client.ts          | 2 +-
 packages/nostr-client/src/events.ts          | 2 +-
 packages/nostr-client/src/index.ts           | 2 +-
 packages/nostr-client/src/types.ts           | 2 +-
 packages/ui-shared/package.json              | 2 +-
 packages/ui-shared/src/index.ts              | 2 +-
 15 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/apps/machine/index.html b/apps/machine/index.html
index cc57859..e461ca2 100644
--- a/apps/machine/index.html
+++ b/apps/machine/index.html
@@ -18,7 +18,7 @@
       http-equiv="Content-Security-Policy"
       content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' ws: wss: http: https:; img-src 'self' data: blob:; font-src 'self'; frame-src 'none'; object-src 'none'"
     />
-    <title>Lamassu ATM</title>
+    <title>bitSpire ATM</title>
     <style>
       /* Prevent text selection and context menu on kiosk */
       * {
diff --git a/deploy/nixos/build-iso.sh b/deploy/nixos/build-iso.sh
index 6202414..ccb8048 100755
--- a/deploy/nixos/build-iso.sh
+++ b/deploy/nixos/build-iso.sh
@@ -33,7 +33,7 @@ esac
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-echo "=== Building Lamassu ATM Live USB ISO (model: $MODEL) ==="
+echo "=== Building bitSpire ATM Live USB ISO (model: $MODEL) ==="
 echo ""
 echo "This is a pure Nix build — no local pnpm required."
 echo ""
diff --git a/deploy/nixos/live.nix b/deploy/nixos/live.nix
index 7c5682f..c7882cc 100644
--- a/deploy/nixos/live.nix
+++ b/deploy/nixos/live.nix
@@ -1,4 +1,4 @@
-# Lamassu ATM Live USB Configuration
+# bitSpire ATM Live USB Configuration
 # Bootable ISO for testing on physical hardware without installing to disk.
 #
 # Parameterized by machineModel (passed via specialArgs from flake.nix):
diff --git a/deploy/nixos/udev/99-bitspire-hardware.rules b/deploy/nixos/udev/99-bitspire-hardware.rules
index 214e788..7ecc019 100644
--- a/deploy/nixos/udev/99-bitspire-hardware.rules
+++ b/deploy/nixos/udev/99-bitspire-hardware.rules
@@ -1,4 +1,4 @@
-# Lamassu ATM Hardware udev Rules
+# bitSpire ATM Hardware udev Rules
 # Place in /etc/udev/rules.d/ or use services.udev.extraRules in NixOS
 
 # ============================================
diff --git a/flake.nix b/flake.nix
index 29f44b1..194ca55 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1,5 +1,5 @@
 {
-  description = "Lamassu Next - Nostr-Native Lightning ATM";
+  description = "bitSpire - Nostr-Native Lightning ATM";
 
   inputs = {
     # Stable NixOS for the ATM OS base
diff --git a/nix/mkAtmApp.nix b/nix/mkAtmApp.nix
index 68a4c37..527d259 100644
--- a/nix/mkAtmApp.nix
+++ b/nix/mkAtmApp.nix
@@ -1,4 +1,4 @@
-# Pure Nix derivation for the Lamassu ATM Electron app.
+# Pure Nix derivation for the bitSpire ATM Electron app.
 #
 # Uses fetchPnpmDeps + pnpmConfigHook to build entirely inside the Nix sandbox,
 # eliminating the need for --impure or a local pnpm install.
diff --git a/packages/hal/package.json b/packages/hal/package.json
index d4d8e9b..6a09f20 100644
--- a/packages/hal/package.json
+++ b/packages/hal/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@bitSpire/hal",
   "version": "0.1.0",
-  "description": "Hardware Abstraction Layer for Lamassu ATM devices",
+  "description": "Hardware Abstraction Layer for bitSpire ATM devices",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,7 +44,7 @@
     "src"
   ],
   "keywords": [
-    "lamassu",
+    "bitspire",
     "atm",
     "hardware",
     "bill-validator",
diff --git a/packages/hal/src/index.ts b/packages/hal/src/index.ts
index 11db91c..dca91f5 100644
--- a/packages/hal/src/index.ts
+++ b/packages/hal/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * @bitSpire/hal - Hardware Abstraction Layer
  *
- * Provides drivers for Lamassu ATM hardware devices:
+ * Provides drivers for bitSpire ATM hardware devices:
  * - Bill validators (JCM iVIZION via ID003 protocol)
  * - Bill dispensers (Fujitsu F53/F56)
  *
diff --git a/packages/nostr-client/package.json b/packages/nostr-client/package.json
index de362ce..e235660 100644
--- a/packages/nostr-client/package.json
+++ b/packages/nostr-client/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@bitSpire/nostr-client",
   "version": "0.1.0",
-  "description": "Nostr client library for Lamassu ATM",
+  "description": "Nostr client library for bitSpire ATM",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
diff --git a/packages/nostr-client/src/client.ts b/packages/nostr-client/src/client.ts
index e9067be..0d86c73 100644
--- a/packages/nostr-client/src/client.ts
+++ b/packages/nostr-client/src/client.ts
@@ -1,5 +1,5 @@
 /**
- * Nostr client for Lamassu ATM
+ * Nostr client for bitSpire ATM
  *
  * Manages connections to Nostr relays with support for:
  * - NIP-42 authentication
diff --git a/packages/nostr-client/src/events.ts b/packages/nostr-client/src/events.ts
index 82cc604..a1ff928 100644
--- a/packages/nostr-client/src/events.ts
+++ b/packages/nostr-client/src/events.ts
@@ -1,5 +1,5 @@
 /**
- * Event creation utilities for Lamassu ATM
+ * Event creation utilities for bitSpire ATM
  */
 
 import { type Event, type EventTemplate, type VerifiedEvent, getEventHash } from 'nostr-tools'
diff --git a/packages/nostr-client/src/index.ts b/packages/nostr-client/src/index.ts
index bb821b4..e03b7f3 100644
--- a/packages/nostr-client/src/index.ts
+++ b/packages/nostr-client/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * @bitSpire/nostr-client
  *
- * Nostr client library for Lamassu ATM communication.
+ * Nostr client library for bitSpire ATM communication.
  *
  * Features:
  * - NIP-42 authentication for private relays
diff --git a/packages/nostr-client/src/types.ts b/packages/nostr-client/src/types.ts
index 43b44bc..90dbc78 100644
--- a/packages/nostr-client/src/types.ts
+++ b/packages/nostr-client/src/types.ts
@@ -1,5 +1,5 @@
 /**
- * Nostr client type definitions for Lamassu ATM
+ * Nostr client type definitions for bitSpire ATM
  */
 
 import type { Event } from 'nostr-tools'
diff --git a/packages/ui-shared/package.json b/packages/ui-shared/package.json
index c5acb10..bde410b 100644
--- a/packages/ui-shared/package.json
+++ b/packages/ui-shared/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@bitSpire/ui-shared",
   "version": "0.1.0",
-  "description": "Shared Vue 3 components for Lamassu ATM and dashboard",
+  "description": "Shared Vue 3 components for bitSpire ATM and dashboard",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
diff --git a/packages/ui-shared/src/index.ts b/packages/ui-shared/src/index.ts
index ea441f0..b5dfb94 100644
--- a/packages/ui-shared/src/index.ts
+++ b/packages/ui-shared/src/index.ts
@@ -1,7 +1,7 @@
 /**
  * @bitSpire/ui-shared
  *
- * Shared Vue 3 components for Lamassu ATM and dashboard.
+ * Shared Vue 3 components for bitSpire ATM and dashboard.
  * This package will contain common UI components like:
  * - QR code display
  * - Number pad

From cb236703d631487988c8dff24520e0934fad0e13 Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sat, 19 Sep 2026 09:58:50 +0200
Subject: [PATCH 81/82] fix(machine): point the favicon at logo.png
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

index.html still linked Vite's scaffold favicon at /vite.svg, which does
not exist in public/ — so every browser tab (the public demo included)
showed a broken icon next to the title. Use the bitSpire logo that is
already shipped for the idle screen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013A6683cCHnQxFUosx1krY4
---
 apps/machine/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/machine/index.html b/apps/machine/index.html
index e461ca2..7b3a983 100644
--- a/apps/machine/index.html
+++ b/apps/machine/index.html
@@ -2,7 +2,7 @@
 <html lang="en" class="dark">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/png" href="/logo.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
     <!--
       Content Security Policy:

From 7e59951fcc45c91167123dd7f9cef2717781b50c Mon Sep 17 00:00:00 2001
From: Padreug <padreug@aiolabs.dev>
Date: Sun, 20 Sep 2026 11:17:41 +0200
Subject: [PATCH 82/82] =?UTF-8?q?wip(rpi4):=20park=20the=20Pi=204=20sketch?=
 =?UTF-8?q?=20=E2=80=94=20superseded=20by=20the=20Pi=205=20machinery=20in?=
 =?UTF-8?q?=20#87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Never-committed working tree state found in the dev worktree: a Pi 4 hardware
module, a setup walkthrough, an upboard-serial refactor, and flake wiring that
does not evaluate (aarch64 packages block nested inside packages.x86_64-linux;
pkgs-aarch64 built with `inherit aarch64` instead of `system`, so it is really
x86; references a nixosConfigurations.rpi4-installed that is never defined).

Parked verbatim for reference. The real Pi 4 target is rebuilt on top of #87's
mkPiInstalled/mkPiImage shape in feat/rpi4-target.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013A6683cCHnQxFUosx1krY4
---
 .envrc                                  |   1 +
 deploy/nixos/README.md                  | 107 ++++++++++-
 deploy/nixos/hardware/raspberry-pi4.nix | 124 +++++++++++++
 deploy/nixos/upboard-serial.nix         |  32 ++++
 docs/raspberry-pi4-setup.md             | 225 ++++++++++++++++++++++++
 flake.lock                              |  17 ++
 flake.nix                               |  31 +++-
 7 files changed, 533 insertions(+), 4 deletions(-)
 create mode 100644 .envrc
 create mode 100644 deploy/nixos/hardware/raspberry-pi4.nix
 create mode 100644 deploy/nixos/upboard-serial.nix
 create mode 100644 docs/raspberry-pi4-setup.md

diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..3550a30
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+use flake
diff --git a/deploy/nixos/README.md b/deploy/nixos/README.md
index 2bfc333..2bce12f 100644
--- a/deploy/nixos/README.md
+++ b/deploy/nixos/README.md
@@ -14,7 +14,8 @@ deploy/nixos/
 ├── hardware/
 │   ├── douro.nix           # Dell OptiPlex 9030 AIO (stock Douro motherboard; SATA SSD, eGalax touch)
 │   ├── batm3.nix           # GeneralBytes BATM3 chassis with a Dell OptiPlex 9030 AIO grafted in (custom mod; WireGuard wired in)
-│   └── upboard.nix         # Aaeon UP Board (Sintra + tejo; eMMC root via sdhci-acpi + mmc_block)
+│   ├── upboard.nix         # Aaeon UP Board (Sintra + tejo; eMMC root via sdhci-acpi + mmc_block)
+│   └── raspberry-pi4.nix   # Raspberry Pi 4 (aarch64) hardware configuration
 ├── udev/
 │   └── 99-bitspire-hardware.rules   # additional udev rules (loaded via configuration.nix)
 ├── provision-atm.sh        # Push LNbits credentials to a deployed ATM via SSH
@@ -34,7 +35,7 @@ Each ATM model has two flake outputs:
 | `packages.x86_64-linux.iso-<model>` | ISO | ISO image of the live variant |
 | `packages.x86_64-linux.disk-image-<model>` | raw image | dd-able full disk image of the installed variant |
 
-Models: `douro`, `tejo`, `sintra`, `batm3`.
+Models: `douro`, `tejo`, `sintra`, `batm3`, `rpi4`.
 
 ```bash
 # Build a Sintra disk image
@@ -43,11 +44,111 @@ nix build .#disk-image-sintra
 
 # Build a live ISO for tejo
 nix build .#iso-tejo
+
+# Build a Raspberry Pi 4 disk image (aarch64)
+nix build .#disk-image-rpi4
+# → result/nixos.img  (Raspberry Pi firmware bootloader, GPT+ESP)
 ```
 
 ## Deploying to Sintra (full walkthrough)
 
-The Sintra ships from the factory with whatever its previous OS was — Android, vendor Linux, or wiped. You need an Alpine live USB to act as your installer.
+The Sintra ships from the factory with whatever its previous OS was — Android, vendor Linux, or wiped.
+
+## Deploying to Raspberry Pi 4 (full walkthrough)
+
+The Raspberry Pi 4 uses an SD card as primary storage and boots via the Raspberry Pi firmware bootloader (rpi-bootloader). Unlike Intel-based ATMs that use systemd-boot, the RPi4 config uses the native Raspberry Pi bootloader.
+
+### Prerequisites
+
+- Raspberry Pi 4 board (4GB or 8GB RAM recommended for Electron)
+- 32GB+ SD card (or external SSD for better reliability)
+- Network connection (ethernet recommended for stability)
+- SSH access or a serial console (UART) for first-boot provisioning
+
+### Build the disk image
+
+```bash
+nix build .#disk-image-rpi4
+# → result/nixos.img (raw disk image, aarch64)
+```
+
+### Flash to SD card
+
+```bash
+# Replace /dev/sdX with your SD card device
+sudo dd if=result/nixos.img of=/dev/sdX bs=4M status=progress conv=fsync && sync
+```
+
+**Important:** Verify the target is the SD card, not your main disk:
+```bash
+lsblk -f /dev/sdX
+# Should show 'SD_CARD' or similar, not a hard drive name
+```
+
+### Boot and provision
+
+1. Insert the SD card into the Raspberry Pi 4.
+2. Connect Ethernet and power on.
+3. Wait for boot (you should see Raspberry Pi firmware loading messages).
+4. The kiosk screen should show "ATM unavailable — needs provisioning".
+
+From your dev box, provision LNbits credentials:
+
+```bash
+LNBITS_SERVER_PUBKEY=$(docker logs <lnbits-container> 2>&1 | \
+  grep -oP 'Public key \(share this\):\s*\K[a-f0-9]{64}' | tail -1)
+
+RELAY_URL=ws://<dev-lan-ip>:5001/nostrrelay/test \
+LNBITS_SERVER_PUBKEY="$LNBITS_SERVER_PUBKEY" \
+ATM_PRIVATE_KEY=$(openssl rand -hex 32) \
+bash deploy/nixos/provision-atm.sh <rpi4-ip> 22
+```
+
+The script SSHes to `bitspire@<rpi4-ip>:22`, writes `/var/lib/bitspire/.env`, and restarts `bitspire.service`. After a few seconds the kiosk connects to LNbits over nostr-transport and shows the live UI.
+
+### First-time deploy
+
+**Save the generated `ATM_PRIVATE_KEY`.** LNbits identifies this ATM by its public key; if you regenerate the key on re-provision, LNbits will auto-create a fresh wallet and the old wallet's balance becomes inaccessible.
+
+### Re-flash
+
+To preserve the ATM's identity and transaction history, backup the `.env` and `state.db` from the running Raspberry Pi before reflashing:
+
+```bash
+# From the Raspberry Pi
+mkdir -p ~/rpi4-backup-$(date +%Y%m%d)
+cp /var/lib/bitspire/.env ~/rpi4-backup-$(date +%Y%m%d)/
+cp /var/lib/bitspire/state.db ~/rpi4-backup-$(date +%Y%m%d)/
+
+# Copy to dev box
+scp bitspire@<rpi4-ip>:~/rpi4-backup-*/.env ~/rpi4-backup-*/
+scp bitspire@<rpi4-ip>:~/rpi4-backup-*/state.db ~/rpi4-backup-*/
+```
+
+On re-flash, source the backup values:
+
+```bash
+set -a; source ~/rpi4-backup-<date>/.env; set +a
+ATM_PRIVATE_KEY=$VITE_ATM_PRIVATE_KEY \
+LNBITS_SERVER_PUBKEY=$VITE_LNBITS_SERVER_PUBKEY \
+RELAY_URL=$VITE_RELAY_URL \
+bash deploy/nixos/provision-atm.sh <rpi4-ip> 22
+```
+
+### Hardware-specific notes
+
+- **Storage:** SD cards are slower and have limited write cycles compared to SSDs. Consider using a high-quality card and avoid frequent rewrites. For production, an external SSD via USB 3.0 is recommended for better reliability.
+- **Power:** The Raspberry Pi 4 can draw up to 3A at 5V. Use a reliable power supply rated for at least 5V 3A.
+- **Thermal:** The Pi 4 runs warm. Ensure adequate cooling (passive heatsinks or a fan) for 24/7 operation.
+- **Console:** The serial console is available at `/dev/ttyAMA0` (PL011 UART) at 115200 baud, useful for debugging.
+- **Swap:** A 2GB swapfile is enabled by default to prevent hard-freeze under memory pressure. Consider increasing this on 4GB models.
+
+### Troubleshooting
+
+- **Boot fails:** Check the SD card is properly flashed and inserted. Try rebuilding the image with a fresh `nix build .#disk-image-rpi4`.
+- **No network:** Verify the Ethernet cable is connected and the Pi's lights show activity. Check `/etc/resolv.conf` after boot.
+- **ATM doesn't connect to LNbits:** Verify `VITE_RELAY_URL` and `VITE_LNBITS_SERVER_PUBKEY` are set in `/var/lib/bitspire/.env` via SSH: `ssh bitspire@<rpi4-ip> 'cat /var/lib/bitspire/.env'`.
+- **Electron fails to start:** Check memory usage (`free -h`). On 4GB models, close other processes to free up RAM. You need an Alpine live USB to act as your installer.
 
 ### 0. (Re-flash only) Preserve state from the existing Sintra
 
diff --git a/deploy/nixos/hardware/raspberry-pi4.nix b/deploy/nixos/hardware/raspberry-pi4.nix
new file mode 100644
index 0000000..2a381d9
--- /dev/null
+++ b/deploy/nixos/hardware/raspberry-pi4.nix
@@ -0,0 +1,124 @@
+# Raspberry Pi 4 Hardware Configuration
+# For bitSpire deployments on Raspberry Pi 4
+# Requires: 4GB+ RAM (8GB recommended for Electron + kiosk)
+# Storage: SD card or external SSD/eMMC (minimum 32GB)
+#
+# Note: Import shared serial peripheral configuration for consistency
+# with other bitSpire hardware (useful for future extensions).
+
+{ config, lib, pkgs, ... }:
+
+{
+  # Import shared serial peripheral configuration (useful for future hardware extensions)
+  imports = [ ./upboard-serial.nix ];
+
+  # Raspberry Pi 4 uses aarch64 architecture
+  boot.kernelPackages = pkgs.linuxPackages_rpi4;
+
+  boot = {
+    loader = {
+      # Raspberry Pi 4 uses the Raspberry Pi firmware bootloader (rpi-bootloader)
+      grub.enable = lib.mkForce false;
+      # raspberryPi.enable has been removed in recent nixpkgs
+      # rpi-bootloader is now built into rpi4 kernel packages
+    };
+
+    initrd.availableKernelModules = [
+      "xhci_pci"
+      "usb_storage"
+      "sdhci_pci"
+      "sdhci"
+      "sd_mod"
+      "brcmmac"
+      "brcmfmac"
+      "mmc_block"
+      "cma"
+    ];
+
+    initrd.kernelModules = [
+      "sdhci_pci"
+      "sdhci"
+      "mmc_block"
+      "brcmmac"
+      "brcmfmac"
+      "cma"
+    ];
+
+    kernelModules = [
+      "kvm-arm"
+      "uas"
+    ];
+
+    kernelParams = [
+      "console=tty1"
+      "console=ttyAMA0,115200n8"
+      "console=ttyS0,115200n8"
+      "root=/dev/mmcblk0p2"
+      "rootfstype=ext4"
+      "rootwait"
+      "rw"
+      # Disable PCIe to save power (optional - uncomment if needed)
+      # "pcie_aspm=off"
+    ];
+  };
+
+  # Filesystem layout: SD card with GPT partition table
+  # Partition 1: EFI System Partition (FAT32)
+  # Partition 2: Root filesystem (ext4)
+  fileSystems."/" = {
+    device = "/dev/disk/by-label/nixos";
+    fsType = "ext4";
+    options = [ "noatime" ];
+  };
+
+  fileSystems."/boot" = {
+    device = "/dev/disk/by-label/ESP";
+    fsType = "vfat";
+    options = [ "defaults" "nofail" ];
+  };
+
+  # Swap configuration for better reliability on SD cards
+  swapDevices = [{
+    device = "/swapfile";
+    size = 2048; # 2GB swap
+  }];
+
+  # Power management for Raspberry Pi
+  powerManagement = {
+    enable = true;
+    cpuFreqGovernor = "ondemand";
+  };
+
+  # Disable suspend/hibernate for kiosk stability
+  systemd.targets = {
+    sleep.enable = false;
+    suspend.enable = false;
+    hibernate.enable = false;
+    hybrid-sleep.enable = false;
+  };
+
+  # Hardware-specific settings
+  hardware = {
+    # Raspberry Pi 4 has no discrete GPU (uses VideoCore)
+    graphics = {
+      enable = true;
+    };
+
+    # USB mass storage drivers (not applicable for ARM - handled by kernel modules)
+    # usb.enable = true;
+    # usb.enableUSBHub = true;
+
+    # RPi4-specific tweaks
+    enableRedistributableFirmware = true;
+    # CPU firmware (not applicable for ARM - no x86 microcode)
+    # cpu.amd64.updateMicrocode = false; # Not applicable for ARM
+  };
+
+  # USB configuration (not applicable for ARM)
+  # hardware.usb.enable = true;
+  # hardware.usb.enableUSBHub = true;
+
+  # Network configuration
+  # useDHCP is set in configuration.nix (base config)
+  networking.interfaces.eth0.useDHCP = true;
+}
diff --git a/deploy/nixos/upboard-serial.nix b/deploy/nixos/upboard-serial.nix
new file mode 100644
index 0000000..46b2274
--- /dev/null
+++ b/deploy/nixos/upboard-serial.nix
@@ -0,0 +1,32 @@
+# Shared serial peripheral configuration for UP Board hardware
+# (Sintra, tejo, and any other systems with similar UART layout)
+#
+# Serial ports used by bitSpire ATM:
+#   ttyJ4 = Printer (Nippon NP-2511D-2) - optional on some configs
+#   ttyJ5 = Validator (iVizion, ID003 protocol)
+#   ttyJ7 = Dispenser (Fujitsu F53/F56)
+#
+# These symlinks + udev rules are shared between live.nix (for testing)
+# and hardware-specific modules (upboard.nix, douro.nix).
+
+{ config, lib, pkgs, ... }:
+
+{
+  # Serial peripheral symlinks
+  services.udev.extraRules = ''
+    # ── Validator (iVizion ID003) ─────────────────────────────────────
+    # ttyJ5 on UP Board (FTDI USB bridge) → /dev/ttyJ5
+    KERNEL=="ttyJ5", SYMLINK+="validator-device"
+    SUBSYSTEM=="tty", GROUP="uucp", MODE="0666"
+
+    # ── Dispenser (Fujitsu F56) ───────────────────────────────────────
+    # ttyJ7 on UP Board (SoC MMIO UART) → /dev/ttyJ7
+    KERNEL=="ttyJ7", SYMLINK+="dispenser-device"
+    SUBSYSTEM=="tty", GROUP="uucp", MODE="0666"
+
+    # ── Printer (Nippon NP-2511D-2) ───────────────────────────────────
+    # ttyJ4 on UP Board (optional - not all configs use it)
+    KERNEL=="ttyJ4", SYMLINK+="printer-device", OPTIONS+="static_node=ttyJ4"
+    SUBSYSTEM=="tty", GROUP="uucp", MODE="0666"
+  '';
+}
diff --git a/docs/raspberry-pi4-setup.md b/docs/raspberry-pi4-setup.md
new file mode 100644
index 0000000..cb909f5
--- /dev/null
+++ b/docs/raspberry-pi4-setup.md
@@ -0,0 +1,225 @@
+# Raspberry Pi 4 bitSpire Setup Guide
+
+This document describes how to build and deploy bitSpire to a Raspberry Pi 4.
+
+## Hardware Requirements
+
+- **Board**: Raspberry Pi 4 (4GB or 8GB RAM recommended for Electron)
+- **Storage**: 32GB+ SD card (or external SSD via USB for better reliability)
+- **Power**: 5V 3A+ power supply (Pi 4 can draw up to 3A at 5V)
+- **Cooling**: Passive heatsinks or active fan for 24/7 operation
+- **Network**: Ethernet connection recommended for stability
+
+## Building the Disk Image
+
+```bash
+cd /home/padreug/dev/bitspire/bitspire/dev
+
+# Build the Raspberry Pi 4 disk image (aarch64)
+nix build .#disk-image-rpi4
+
+# The image will be at: result/nixos.img
+```
+
+## Flashing to SD Card
+
+```bash
+# Replace /dev/sdX with your SD card device (NOT your main disk!)
+# Verify first: lsblk -f /dev/sdX
+
+sudo dd if=result/nixos.img of=/dev/sdX bs=4M status=progress conv=fsync && sync
+
+# Sync to ensure all writes are flushed
+sync
+```
+
+**Important**: Always verify the target device before flashing!
+
+## First-Time Deployment
+
+### 1. Boot the Raspberry Pi 4
+
+1. Insert the SD card into the Raspberry Pi 4.
+2. Connect Ethernet cable.
+3. Power on the device.
+4. You should see Raspberry Pi firmware boot messages.
+5. The kiosk screen shows "ATM unavailable — needs provisioning".
+
+### 2. Provision LNbits Credentials
+
+From your development machine:
+
+```bash
+LNBITS_SERVER_PUBKEY=$(docker logs <lnbits-container> 2>&1 | \
+  grep -oP 'Public key \(share this\):\s*\K[a-f0-9]{64}' | tail -1)
+
+RELAY_URL=ws://<dev-lan-ip>:5001/nostrrelay/test \
+LNBITS_SERVER_PUBKEY="$LNBITS_SERVER_PUBKEY" \
+ATM_PRIVATE_KEY=$(openssl rand -hex 32) \
+bash deploy/nixos/provision-atm.sh <rpi4-ip> 22
+```
+
+**Important**: Save the generated `ATM_PRIVATE_KEY` — it's required to preserve the ATM's identity and wallet balance.
+
+### 3. Verify Connection
+
+After provisioning completes:
+
+```bash
+ssh bitspire@<rpi4-ip> 'cat /var/lib/bitspire/.env'
+```
+
+You should see the environment variables are set correctly. The kiosk should connect to LNbits over nostr-transport and show the live UI after a few seconds.
+
+## Re-Flashing (Preserving Identity)
+
+To preserve the ATM's identity and transaction history when reflashing:
+
+1. **Backup from the running Raspberry Pi**:
+
+```bash
+# From the Raspberry Pi
+mkdir -p ~/rpi4-backup-$(date +%Y%m%d)
+cp /var/lib/bitspire/.env ~/rpi4-backup-$(date +%Y%m%d)/
+cp /var/lib/bitspire/state.db ~/rpi4-backup-$(date +%Y%m%d)/
+```
+
+2. **Copy backups to dev box**:
+
+```bash
+scp bitspire@<rpi4-ip>:~/rpi4-backup-*/.env ~/rpi4-backup-*/
+scp bitspire@<rpi4-ip>:~/rpi4-backup-*/state.db ~/rpi4-backup-*/
+```
+
+3. **Re-flash the SD card**:
+
+```bash
+nix build .#disk-image-rpi4
+sudo dd if=result/nixos.img of=/dev/sdX bs=4M status=progress conv=fsync && sync
+```
+
+4. **Re-provision from backups**:
+
+```bash
+set -a; source ~/rpi4-backup-<date>/.env; set +a
+
+ATM_PRIVATE_KEY=$VITE_ATM_PRIVATE_KEY \
+LNBITS_SERVER_PUBKEY=$VITE_LNBITS_SERVER_PUBKEY \
+RELAY_URL=$VITE_RELAY_URL \
+bash deploy/nixos/provision-atm.sh <rpi4-ip> 22
+```
+
+## Hardware-Specific Notes
+
+### Storage
+- **SD cards** are slower and have limited write cycles. For production, consider an external SSD via USB 3.0 for better reliability.
+- Use high-quality SD cards with good endurance ratings.
+- Avoid frequent rewrites to the same sectors.
+
+### Power
+- The Raspberry Pi 4 can draw up to 3A at 5V during heavy load (Electron startup).
+- Use a reliable power supply rated for at least 5V 3A.
+- Avoid using USB hubs that don't provide sufficient power.
+
+### Thermal
+- The Pi 4 runs warm, especially under load with Electron.
+- Ensure adequate cooling for 24/7 operation:
+  - Passive heatsinks on the SoC and RAM
+  - Or a small active fan blowing air over the board
+- Consider removing the metal case for better airflow in hot environments.
+
+### Console
+- The serial console is available at `/dev/ttyAMA0` (PL011 UART) at 115200 baud.
+- Useful for debugging boot issues.
+- Not required for normal operation.
+
+### Swap
+- A 2GB swapfile is enabled by default to prevent hard-freeze under memory pressure.
+- Consider increasing this on 4GB models if you expect heavy load.
+
+## Troubleshooting
+
+### Boot fails
+
+**Symptoms**: Pi doesn't boot or shows errors.
+
+**Solutions**:
+1. Verify SD card is properly flashed:
+   ```bash
+   lsblk -f /dev/sdX
+   # Should show GPT partition table with ESP and nixos partitions
+   ```
+2. Try rebuilding the image:
+   ```bash
+   nix build .#disk-image-rpi4
+   ```
+3. Check power supply and connections.
+
+### No network connectivity
+
+**Symptoms**: Cannot SSH to the Pi or connect to LAN.
+
+**Solutions**:
+1. Verify Ethernet cable is connected and the Pi's lights show activity.
+2. Check `/etc/resolv.conf` after boot:
+   ```bash
+   ssh bitspire@<rpi4-ip> 'cat /etc/resolv.conf'
+   ```
+3. Check network interface status:
+   ```bash
+   ssh bitspire@<rpi4-ip> 'ip a'
+   ```
+
+### ATM doesn't connect to LNbits
+
+**Symptoms**: Kiosk shows "ATM unavailable" or no connection.
+
+**Solutions**:
+1. Verify environment variables are set:
+   ```bash
+   ssh bitspire@<rpi4-ip> 'cat /var/lib/bitspire/.env'
+   ```
+2. Check for typos in `VITE_RELAY_URL` and `VITE_LNBITS_SERVER_PUBKEY`.
+3. Verify LNbits is running and accessible:
+   ```bash
+   curl <lnbits-url>/api/v1/settings
+   ```
+4. Check ATM service logs:
+   ```bash
+   ssh bitspire@<rpi4-ip> 'sudo journalctl -u bitspire -n 50'
+   ```
+
+### Electron fails to start
+
+**Symptoms**: Service logs show Electron crash or OOM (out of memory).
+
+**Solutions**:
+1. Check memory usage:
+   ```bash
+   ssh bitspire@<rpi4-ip> 'free -h'
+   ```
+2. On 4GB models, close other processes to free up RAM.
+3. Consider increasing the swapfile size in `/var/lib/bitspire/.env`.
+
+## Building Live ISO for Testing
+
+To build a live USB bootable ISO for testing (without installing):
+
+```bash
+nix build .#iso-rpi4
+
+# The ISO will be at: result/*.iso
+```
+
+## Configuration Files
+
+- **Hardware config**: `deploy/nixos/hardware/raspberry-pi4.nix`
+- **Base config**: `deploy/nixos/configuration.nix`
+- **Service module**: `deploy/nixos/bitspire-atm.nix`
+- **Provisioning script**: `deploy/nixos/provision-atm.sh`
+
+## References
+
+- [NixOS on Raspberry Pi](https://nixos.org/manual/nixos/stable/index.html#sec-architecture-raspberry-pi)
+- [bitSpire README](../README.md)
+- [NixOS Hardware Configuration](https://nixos.org/manual/nixos/stable/index.html#ch-configuring-hardware)
diff --git a/flake.lock b/flake.lock
index 7ea214a..9bd3e3d 100644
--- a/flake.lock
+++ b/flake.lock
@@ -435,6 +435,22 @@
         "type": "github"
       }
     },
+    "nixpkgs-aarch64": {
+      "locked": {
+        "lastModified": 1782847189,
+        "narHash": "sha256-twXPFqFsrrY5r28Zh7Homgcp2gUMBgQ6WDS98Q/3xFI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "b6018f87da91d19d0ab4cf979885689b469cdd41",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
     "nixpkgs-regression": {
       "locked": {
         "lastModified": 1643052045,
@@ -504,6 +520,7 @@
         "devenv": "devenv",
         "flake-utils": "flake-utils",
         "nixpkgs": "nixpkgs_3",
+        "nixpkgs-aarch64": "nixpkgs-aarch64",
         "nixpkgs-unstable": "nixpkgs-unstable",
         "rust-overlay": "rust-overlay"
       }
diff --git a/flake.nix b/flake.nix
index 194ca55..b012a0b 100644
--- a/flake.nix
+++ b/flake.nix
@@ -5,6 +5,9 @@
     # Stable NixOS for the ATM OS base
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
 
+    # Stable NixOS for the ATM OS base (aarch64) — Raspberry Pi 4
+    nixpkgs-aarch64.url = "github:NixOS/nixpkgs/nixos-25.11";
+
     # Unstable for Electron, Node.js, pnpm (latest versions)
     nixpkgs-unstable.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
 
@@ -38,15 +41,22 @@
     };
   };
 
-  outputs = { self, nixpkgs, nixpkgs-unstable, flake-utils, rust-overlay, devenv, determinate, atm-tui }:
+  outputs = { self, nixpkgs, nixpkgs-unstable, nixpkgs-aarch64, flake-utils, rust-overlay, devenv, determinate, atm-tui }:
     let
       system = "x86_64-linux";
 
+      aarch64 = "aarch64-linux";
+
       pkgs = import nixpkgs {
         inherit system;
         config.allowUnfree = true;
       };
 
+      pkgs-aarch64 = import nixpkgs-aarch64 {
+        inherit aarch64;
+        config.allowUnfree = true;
+      };
+
       pkgs-unstable = import nixpkgs-unstable {
         inherit system;
         config.allowUnfree = true;
@@ -504,6 +514,25 @@
             '';
 
         # Backwards compat
+
+      # aarch64-linux packages (Raspberry Pi 4)
+      packages.${aarch64} = {
+        # ATM app derivation for Raspberry Pi 4
+        atm-app-rpi4 = mkAtmApp { model = "rpi4"; fiatCode = "USD"; };
+
+        # Raspberry Pi 4 disk image (aarch64)
+        # Note: Raspberry Pi 4 uses the Raspberry Pi firmware bootloader,
+        # not systemd-boot. The image is built for aarch64 and booted via
+        # the rpi-bootloader (rpi-firmware). Requires an SD card with GPT
+        # partition table (ESP + ext4 root).
+        disk-image-rpi4 = import (nixpkgs-aarch64 + "/nixos/lib/make-disk-image.nix") { 
+          pkgs = pkgs-aarch64; inherit lib;
+          config = self.nixosConfigurations.rpi4-installed.config;
+          format = "raw";
+          partitionTableType = "efi";
+          diskSize = "auto";
+        };
+      };
         iso = self.nixosConfigurations.douro.config.system.build.isoImage;
       };
     }