feat(machine): Bolt Card (NFC) tap-to-receive on cash-in

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.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)
+}