feat(machine): LNURL-withdraw executor for Bolt Card cash-out (LUD-03)

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