@oneaddress/setup 2.1.2 → 2.2.0

package/dist/index.js

@@ -856,7 +856,7 @@ var _R = ["\u2588\u2588\u2588\u2588\u2588\u2588 ", "\u2588\u2588   \u2588\u2588"
 var _S = [" \u2588\u2588\u2588\u2588\u2588\u2588", "\u2588\u2588     ", "\u2588\u2588     ", " \u2588\u2588\u2588\u2588\u2588 ", "     \u2588\u2588", "     \u2588\u2588", "\u2588\u2588\u2588\u2588\u2588\u2588 "];
 var ONE_ROWS = Array.from({ length: 7 }, (_3, i) => [_O[i], _N[i], _E[i]].join(" "));
 var ADDR_ROWS = Array.from({ length: 7 }, (_3, i) => [_A[i], _D2[i], _D2[i], _R[i], _E[i], _S[i], _S[i]].join(" "));
-var WIZARD_VERSION = true ? "2.1.2" : "?";
+var WIZARD_VERSION = true ? "2.2.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -941,6 +941,20 @@ WEBHOOK_SECRET=your-webhook-secret-here
 # -----BEGIN PRIVATE KEY-----\\nMIGHAgEA...\\n-----END PRIVATE KEY-----
 PARTNER_PRIVATE_KEY_PEM=
 
+# ROTATING A KEY? Every dispatch names the key it was encrypted to, and both
+# keys are valid during the overlap window. Set one variable per key, named for
+# its key_id with dashes as underscores, upper-cased, and keep the OLD one set
+# until the window closes:
+#
+#   PARTNER_PRIVATE_KEY_PEM_04032299_4B04_4842_AA29_5095500C8ECE=...
+#
+# PARTNER_PRIVATE_KEY_PEM above is then a fallback, used for any key_id with no
+# variable of its own. Convenient with one key and risky with two, because it
+# answers for an id it does not hold and the failure looks like corruption
+# rather than like a rotation. Set PARTNER_KEYS_STRICT=1 to turn it off once you
+# have more than one key.
+PARTNER_KEYS_STRICT=
+
 # HTTP port for the local webhook server
 PORT=3001
 `
@@ -1073,6 +1087,7 @@ data.db-shm
  */
 import { DatabaseSync } from 'node:sqlite';
 import { join } from 'node:path';
+import { report } from './report.js';
 import {
   accountIndex,
   buildVerifier,
@@ -1215,6 +1230,22 @@ export { PassphraseRequiredError, WrongPassphraseError };
  * separates them.
  */
 export { isEncrypted };
+
+/**
+ * Add a column to an existing table if it is not already there.
+ *
+ * SQLite has no \`ADD COLUMN IF NOT EXISTS\`, and a receiver that has been
+ * running since before a column existed still has to start. Lives here rather
+ * than in one of the two files that needs it, because the second copy is how
+ * the two drift.
+ */
+export function ensureColumn(table: string, column: string, definition: string): void {
+  const cols = db.prepare(\`PRAGMA table_info(\${table})\`).all() as Array<{ name: string }>;
+  if (cols.some((c) => c.name === column)) return;
+  db.exec(\`ALTER TABLE \${table} ADD COLUMN \${column} \${definition}\`);
+  report.info(\`[db] migrated: added column \${table}.\${column}\`);
+}
+
 export default db;
 `
     },
@@ -1646,7 +1677,12 @@ export function formatLine(line: ReportLine): string {
 import blessed from 'blessed';
 import { HEX, ONE_ROWS, ADDRESS_ROWS, terminalFitsFullMark } from './brand.js';
 import { formatLine, report, type ReportLine } from './report.js';
-import { allCustomers, customerCount, storeEncrypted, type StoredCustomer } from './store.js';
+// One import, same as server.ts. Swapping the store swaps what the dashboard
+// reads, with nothing here to change.
+import { store } from './store.js';
+import type { StoredCustomer } from './customer-store.js';
+import { pendingConfirmCount } from './confirm-queue.js';
+import { exportHeld, heldCount, heldSummary } from './quarantine.js';
 
 /** blessed takes colours as strings; these mirror the site's palette. */
 const AMBER = HEX.amber.toLowerCase();
@@ -1661,6 +1697,29 @@ export interface TuiOptions {
   port: number;
   /** Called when the operator quits, so the caller can close the server. */
   onQuit: () => void;
+  /**
+   * Re-apply everything the receiver could not open, bound to [r].
+   *
+   * Passed IN rather than imported: \`server.ts\` already imports this file for
+   * \`notePreviousAddress\`, so importing it back would be a cycle. Optional so
+   * the dashboard still renders for a caller that has no replay to offer.
+   */
+  onReplay?: () => Promise<{ applied: number; failed: number }>;
+  /**
+   * How the dispatches went, asked of the receiver rather than counted here.
+   *
+   * Same reason as \`onReplay\`: \`server.ts\` already imports this file, so this
+   * file cannot import it back. Optional, and a caller that omits it gets
+   * zeroes, which is honest for a dashboard driving nothing.
+   */
+  stats?: () => {
+    received: number;
+    applied: number;
+    failed: number;
+    mode: string;
+    awaitingConnector: number;
+    oldestUndrawn: string | null;
+  };
 }
 
 /** One address as a single line, the way the change panel shows it. */
@@ -1669,7 +1728,7 @@ function oneLine(a: Record<string, unknown>): string {
   return parts.length > 0 ? parts.join(', ') : '(empty)';
 }
 
-export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void {
+export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: TuiOptions): void {
   const screen = blessed.screen({
     smartCSR: true,
     title: \`\${partnerName} \u2014 OneAddress receiver\`,
@@ -1722,6 +1781,25 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
     style: { border: { fg: DIM }, label: { fg: DIM } },
   });
 
+  // \u2500\u2500 The faults band: dispatches that arrived and could not be opened \u2500\u2500\u2500\u2500\u2500\u2500
+  //
+  // HIDDEN WHEN THERE IS NOTHING WRONG, and that is a deliberate departure from
+  // how the rest of this screen works. The other panels are always drawn,
+  // including the ENCRYPTED/UNENCRYPTED line, because a property you only
+  // mention when it holds is one nobody notices the absence of. A faults panel
+  // is the other case: a permanent empty box teaches the eye to skip that
+  // region, which is precisely the region that has to be noticed the one day it
+  // fills. So it appears, and the two panels above give up the rows.
+  // Six, not seven. Every row this takes comes off the two panels above it, and
+  // the one above left cannot afford to lose any: see renderChange.
+  const FAULT_HEIGHT = 6;
+  const faultBox = blessed.box({
+    parent: screen, bottom: 3, left: 0, width: '100%', height: FAULT_HEIGHT,
+    label: ' FAULTS ', tags: true, padding: { left: 1, right: 1 }, hidden: true,
+    border: { type: 'line' } as never,
+    style: { border: { fg: 'red' }, label: { fg: 'red' } },
+  });
+
   const footer = blessed.box({
     parent: screen, bottom: 0, left: 0, width: '100%', height: 3,
     tags: true, padding: { left: 2 },
@@ -1730,9 +1808,6 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
   });
 
   // \u2500\u2500 State \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-  let received = 0;
-  let applied = 0;
-  let failed = 0;
   let lastChange: { customer: StoredCustomer; previous: Record<string, unknown> } | null = null;
   let pendingPrevious: Record<string, unknown> = {};
 
@@ -1745,14 +1820,25 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
     // Both states are shown, and the unprotected one is the loud colour. A
     // security property mentioned only when it holds is one nobody notices the
     // absence of.
-    const vault = storeEncrypted
-      ? \`{green-fg}{bold}ENCRYPTED{/}\`
-      : \`{red-fg}{bold}UNENCRYPTED{/}\`;
+    const inbox = statsMode() === 'inbox';
+    // IN INBOX MODE THERE IS NO CUSTOMER FILE HERE AT ALL, so neither ENCRYPTED
+    // nor UNENCRYPTED is true and both would mislead. The receiver holds
+    // ciphertext it cannot open; the customers live in the partner's own
+    // database, behind their own controls.
+    const vault = inbox
+      ? \`{\${AMBER}-fg}{bold}NONE (inbox){/}\`
+      : store.encrypted
+        ? \`{green-fg}{bold}ENCRYPTED{/}\`
+        : \`{red-fg}{bold}UNENCRYPTED{/}\`;
     status.setContent(
       \`{\${AMBER}-fg}{bold}\${esc(partnerName)}{/}   \` +
       \`{\${DIM}-fg}listening{/} {\${CREAM}-fg}:\${port}/webhook{/}   \` +
       \`{\${DIM}-fg}customer file{/} \${vault}   \` +
-      \`{\${DIM}-fg}on file{/} {\${CREAM}-fg}\${customerCount().toLocaleString()}{/}\`,
+      // A DASH RATHER THAN A ZERO when the store declines to count. Zero is a
+      // claim ("you have no customers") and would be a lie on a receiver
+      // pointed at a real customer table, where counting every row forty times
+      // a minute is the thing the store is right to refuse.
+      \`{\${DIM}-fg}on file{/} {\${CREAM}-fg}\${onFile === null ? '\u2014' : onFile.toLocaleString()}{/}\`,
     );
   }
 
@@ -1768,54 +1854,191 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
     const { customer, previous } = lastChange;
     let now: Record<string, unknown> = {};
     try { now = JSON.parse(customer.address) as Record<string, unknown>; } catch { /* keep empty */ }
+    // COMPACT, AND THAT IS A BUG FIX RATHER THAN A TIDY-UP.
+    //
+    // This used to space the lines out with blanks, which needed eight rows.
+    // The faults band takes seven rows off this panel when it appears, so on a
+    // real terminal the last line fell off the bottom - and the last line is
+    // \`now\`, the one thing the panel exists to show. blessed clips silently, so
+    // it read as a dispatch that had half worked.
+    //
+    // It cost a real end-to-end run an hour of doubt: the address had been
+    // applied, confirmed and acknowledged by OneAddress, and the screen showed
+    // only what it used to be. Adjacent is better anyway, because comparing two
+    // lines a blank apart is harder than comparing two lines.
     changeBox.setContent(
-      \`\\n  {bold}\${esc(customer.name)}{/bold}\\n\` +
+      \`\\n  {bold}\${esc(customer.name)}{/bold}\` +
       \`  {\${DIM}-fg}account{/} {\${AMBER}-fg}\${esc(customer.account_number)}{/}\\n\\n\` +
-      \`  {red-fg}was{/}  \${esc(oneLine(previous))}\\n\\n\` +
-      \`  {green-fg}now{/}  {\${CREAM}-fg}\${esc(oneLine(now))}{/}\\n\`,
+      \`  {red-fg}was{/}  \${esc(oneLine(previous))}\\n\` +
+      \`  {green-fg}now{/}  {\${CREAM}-fg}\${esc(oneLine(now))}{/}\`,
+    );
+  }
+
+  /** Shown while a replay is running, so [r] does not look like it did nothing. */
+  let replayNote = '';
+
+  /**
+   * The customer count, refreshed out of band.
+   *
+   * CACHED RATHER THAN READ DURING RENDER, because \`count()\` may be async and a
+   * render cannot await. It starts null, which is also what a store that
+   * declines to count returns forever, so the dash below is the honest initial
+   * state rather than a placeholder that happens to look the same.
+   */
+  const statsMode = (): string => stats?.().mode ?? 'write-through';
+
+  let onFile: number | null = null;
+  function refreshCount(): void {
+    void Promise.resolve(store.count())
+      .then((n) => { onFile = n; })
+      .catch(() => { onFile = null; });
+  }
+  refreshCount();
+
+  function renderFaults(): void {
+    const held = heldCount();
+    const show = held > 0;
+    if (show === Boolean(faultBox.hidden)) {
+      // Visibility is changing, so the panels above have to give back or take
+      // back the rows. Assigning \`bottom\` is how blessed re-lays-out; it reads
+      // the value on the next render rather than caching a computed box.
+      if (show) faultBox.show(); else faultBox.hide();
+      const edge = show ? 3 + FAULT_HEIGHT : 3;
+      (changeBox as unknown as { bottom: number }).bottom = edge;
+      (logBox    as unknown as { bottom: number }).bottom = edge;
+    }
+    if (!show) return;
+
+    // Grouped, never one line per dispatch. The realistic shape of this table
+    // is forty rows with ONE cause between them, and forty identical lines hide
+    // the single fact that matters.
+    const lines = heldSummary().slice(0, 2).map((l) => \`  {red-fg}\${esc(l)}{/}\`);
+    faultBox.setContent(
+      \`\\n  {bold}\${held}{/bold} dispatch(es) arrived that this receiver could not open. \` +
+      \`{\${DIM}-fg}Held, encrypted, exactly as they arrived.{/}\\n\` +
+      lines.join('\\n') + '\\n' +
+      (replayNote
+        ? \`  {\${AMBER}-fg}\${esc(replayNote)}{/}\`
+        : \`  {\${DIM}-fg}Fix the cause, then{/} {\${AMBER}-fg}[r]{/} {\${DIM}-fg}to apply,{/} {\${AMBER}-fg}[e]{/} {\${DIM}-fg}to export the list.{/}\`),
     );
   }
 
   function renderFooter(): void {
+    // AWAITING IS THE ONE AN OPERATOR CANNOT AFFORD TO MISS, so it is drawn
+    // whether or not it is zero. A dispatch that was applied here but never
+    // acknowledged back to OneAddress shows the consumer a FAILED delivery for
+    // an update that in fact succeeded, and the auto-refund cron treats a
+    // terminal failure as refundable: the work is done and the money goes back.
+    // Read from the queue rather than counted here, so a receiver restarted
+    // with a backlog shows the backlog instead of zero.
+    const awaiting = pendingConfirmCount();
+    const awaitingColour = awaiting > 0 ? AMBER : DIM;
+    // ASKED, not accumulated. The server counts per dispatch, so a redelivery
+    // updates a record rather than adding one.
+    const s = stats?.() ?? {
+      received: 0, applied: 0, failed: 0,
+      mode: 'write-through', awaitingConnector: 0, oldestUndrawn: null,
+    };
+    const { received, applied, failed } = s;
+    // AWAITING YOUR SYSTEMS, in inbox mode only. Drawn whether or not it is
+    // zero there, and absent entirely in write-through, because a counter for a
+    // thing that cannot happen is noise that teaches the eye to skip the row.
+    const awaitingYou = s.mode === 'inbox'
+      ? \`{\${s.awaitingConnector > 0 ? AMBER : DIM}-fg}awaiting your systems{/} \` +
+        \`{bold}\${s.awaitingConnector}{/bold}   \`
+      : '';
     footer.setContent(
       \`{\${DIM}-fg}received{/} {bold}\${received}{/bold}   \` +
       \`{green-fg}applied{/} {bold}\${applied}{/bold}   \` +
-      \`{red-fg}failed{/} {bold}\${failed}{/bold}\` +
-      \`{|}{\${DIM}-fg}[q] quit{/}  \`,
+      \`{red-fg}failed{/} {bold}\${failed}{/bold}   \` +
+      awaitingYou +
+      \`{\${awaitingColour}-fg}awaiting confirm{/} {bold}\${awaiting}{/bold}\` +
+      \`{|}{\${DIM}-fg}\${onReplay ? '[r] replay  ' : ''}[e] export  [q] quit{/}  \`,
     );
   }
 
   function redraw(): void {
     renderStatus();
     renderChange();
+    renderFaults();
     renderFooter();
     screen.render();
   }
 
   // \u2500\u2500 The feed \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-  // Counters are derived from the reported lines rather than from a second
-  // channel the server would have to remember to update. One source, so the
-  // footer cannot disagree with the log beside it.
+  // NARRATION ONLY. It used to derive the footer's counters from these lines
+  // too, on the reasoning that one source cannot disagree with itself. That
+  // held until replay shipped: a replay produces exactly the lines an arrival
+  // does, so pressing [r] against a key that could never work drove \`received\`
+  // from 5 to 67 while nothing arrived. A log line says what happened and not
+  // what it happened TO, so two lines about one dispatch are indistinguishable
+  // from two dispatches. The counters key on the dispatch now; see
+  // \`src/tally.ts\`.
   const detach = report.attach((line: ReportLine) => {
     const text = formatLine(line);
     const colour = line.level === 'error' ? 'red' : line.level === 'warn' ? 'yellow' : CREAM;
     const time = new Date(line.at).toTimeString().slice(0, 8);
 
-    if (/address\\.updated for /.test(text)) received++;
-    if (/REFUSED|decryption failed|Decryption failed/.test(text)) failed++;
     if (/\\[store\\] saved address for /.test(text)) {
-      applied++;
       // The store logs the account key and never the address, so the panel is
       // refreshed from the DATABASE rather than parsed out of the log line.
       const acct = /saved address for (\\S+)/.exec(text)?.[1];
-      const customer = allCustomers().find((c) => c.account_number === acct);
-      if (customer) lastChange = { customer, previous: pendingPrevious };
+      // An indexed lookup of the one customer, not a decrypt of the whole
+      // roster to find them. Invisible at three rows and absurd at four
+      // million, which is the scale a real store is pointed at.
+      const prev = pendingPrevious;
+      if (acct) {
+        void Promise.resolve(store.find(acct)).then((customer) => {
+          if (!customer) return;
+          lastChange = { customer, previous: prev };
+          redraw();
+        });
+      }
     }
 
     logBox.log(\`{\${DIM}-fg}\${time}{/} {\${colour}-fg}\${esc(text)}{/}\`);
     redraw();
   });
 
+  // [r] REPLAYS. Bound unconditionally rather than only while faults exist, so
+  // pressing it on a clean receiver says "nothing held" instead of doing
+  // nothing, which is indistinguishable from a wedged UI.
+  let replaying = false;
+  screen.key(['r'], () => {
+    if (!onReplay || replaying) return;
+    replaying = true;
+    replayNote = 'Replaying\u2026';
+    redraw();
+    void onReplay()
+      .then(({ applied, failed }) => {
+        replayNote = failed > 0
+          ? \`Applied \${applied}, \${failed} still failing \u2014 the cause is not fixed yet.\`
+          : \`Applied \${applied}. Nothing left held.\`;
+      })
+      .catch((err: unknown) => {
+        replayNote = \`Replay failed: \${err instanceof Error ? err.message : String(err)}\`;
+      })
+      .finally(() => { replaying = false; redraw(); });
+  });
+
+  // [e] EXPORTS THE FAULT LIST. Metadata only, no payloads: see exportHeld.
+  // Bound unconditionally for the same reason [r] is, so pressing it on a clean
+  // receiver says there is nothing to export rather than appearing to hang.
+  screen.key(['e'], () => {
+    if (heldCount() === 0) {
+      replayNote = 'Nothing held, so nothing to export.';
+      redraw();
+      return;
+    }
+    try {
+      const { path, count } = exportHeld(process.cwd());
+      replayNote = \`Exported \${count} to \${path}\`;
+    } catch (err) {
+      replayNote = \`Export failed: \${err instanceof Error ? err.message : String(err)}\`;
+    }
+    redraw();
+  });
+
   screen.key(['q', 'C-c'], () => {
     detach();
     screen.destroy();
@@ -1823,6 +2046,14 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
     process.exit(0);
   });
 
+  // EVERY OTHER REDRAW IS TRIGGERED BY A REPORTED LINE, and the awaiting count
+  // is the one number that can change without one. The confirm backoff caps at
+  // an hour, so a confirm stuck against a wrong secret would sit on screen at
+  // its hour-old value and read as settled. Cheap: one indexed COUNT, and only
+  // while a terminal is attached.
+  const tick = setInterval(() => { refreshCount(); redraw(); }, 2_000);
+  tick.unref();
+
   redraw();
 }
 
@@ -2077,10 +2308,31 @@ async function main(): Promise<void> {
   // Dynamic, and this is the whole point of the file: importing the server
   // pulls in the store, which pulls in the database, which derives its keys on
   // import. The passphrase has to be set before that chain starts.
-  let config: { partnerName: string; port: number };
+  let config: {
+    partnerName: string;
+    port: number;
+    replay: () => Promise<{ applied: number; failed: number }>;
+    stats: () => {
+      received: number;
+      applied: number;
+      failed: number;
+      mode: string;
+      awaitingConnector: number;
+      oldestUndrawn: string | null;
+    };
+  };
   try {
     const server = await import('./server.js');
-    config = { partnerName: server.PARTNER_NAME, port: server.PORT };
+    config = {
+      partnerName: server.PARTNER_NAME,
+      port:        server.PORT,
+      // Handed through rather than imported by the dashboard, because the
+      // server already imports the dashboard (for notePreviousAddress) and a
+      // second edge the other way is a cycle. This file is the one place that
+      // holds both.
+      replay:      server.replayQuarantined,
+      stats:       server.dashboardStats,
+    };
   } catch (err) {
     if (err instanceof PassphraseRequiredError) {
       // Reached when nobody could be asked: a service unit, a piped stdin, or
@@ -2108,6 +2360,8 @@ async function main(): Promise<void> {
   startDashboard({
     partnerName: config.partnerName,
     port: config.port,
+    onReplay: config.replay,
+    stats: config.stats,
     onQuit: () => { /* the process exits; the OS closes the socket */ },
   });
 }
@@ -2119,175 +2373,1779 @@ main().catch((err) => {
 `
     },
     {
-      name: "src/config.ts",
+      name: "src/connector-store.ts",
       content: `/**
- * src/config.ts \u2014 the configuration you set in SETUP, read by the handler.
+ * A \`CustomerStore\` whose answers come from the connector.
  *
- * \`npx @oneaddress/setup\` writes oneaddress.config.json next to your .env. This
- * module is the ONE place the receiver reads it, so what you chose during setup
- * drives the running handler with no code to edit. Secrets stay in .env; this
- * file is non-secret behaviour only.
+ * ## Why the mode swaps the STORE rather than branching the handler
  *
- * Precedence for every field: an explicit environment variable wins (a one-off
- * override), then oneaddress.config.json (what setup wrote), then a built-in
- * default. A missing config file is not an error \u2014 the handler still runs.
+ * The obvious way to build inbox mode is an \`if (mode === 'inbox')\` beside each
+ * verify event in \`server.ts\`. That works and it puts the mode into the middle
+ * of the protocol layer, where it has to be got right twice and stay right
+ * every time either handler changes.
+ *
+ * The contract in \`customer-store.ts\` already says exactly what the receiver
+ * needs from a partner: verify an account, verify an address, apply a change.
+ * In inbox mode the answers come from a different place. That is an
+ * IMPLEMENTATION of the contract, not a special case in the caller, so the
+ * handler is untouched and there is one place the mode lives.
+ *
+ * ## Three methods answer, two deliberately refuse
+ *
+ * \`verifyAccount\` and \`verifyAddress\` ask the connector and wait, because a
+ * consumer is mid-payment on the other end of the first one.
+ *
+ * \`saveAddress\` THROWS. In inbox mode an \`address.updated\` never reaches the
+ * store at all: it is held for the connector to draw, and the connector applies
+ * it against the partner's own database. If this is ever called, the mode
+ * switch has been bypassed and the right answer is a loud failure rather than a
+ * quiet write into a store that should not exist.
+ *
+ * \`find\` and \`count\` return nothing, honestly, because this receiver holds no
+ * customer records in this mode. The dashboard draws a dash rather than a zero,
+ * which is the difference between "not asked" and "none".
  */
 import { report } from './report.js';
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { askConnector } from './connector-client.js';
+import type {
+  AccountVerdict,
+  Address,
+  Customer,
+  CustomerStore,
+  StoredCustomer,
+  VerifyResult,
+} from './customer-store.js';
 
-export type ReceiverConfig = {
-  partnerId:                string;
-  oneAddressApi:            string;
-  verifiesAccountReference: boolean;
-};
-
-const DEFAULTS: ReceiverConfig = {
-  partnerId:     '',
-  oneAddressApi: 'https://oneaddress.io',
-  // A receiver that can match, matches. The wizard writes an EXPLICIT value here
-  // from your portal declaration, so this default only bites if the config file
-  // is missing entirely \u2014 in which case answering account.verify is the safer,
-  // more useful default than silently returning "not checked".
-  verifiesAccountReference: true,
-};
-
-function stripTrailingSlash(s: string): string {
-  return s.endsWith('/') ? s.slice(0, -1) : s;
-}
-
-function loadConfigFile(): Partial<ReceiverConfig> {
-  const path = process.env.ONEADDRESS_CONFIG ?? join(process.cwd(), 'oneaddress.config.json');
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
-    const out: Partial<ReceiverConfig> = {};
-    if (typeof parsed.partnerId === 'string')                out.partnerId = parsed.partnerId;
-    if (typeof parsed.oneAddressApi === 'string')            out.oneAddressApi = parsed.oneAddressApi;
-    if (typeof parsed.verifiesAccountReference === 'boolean') out.verifiesAccountReference = parsed.verifiesAccountReference;
-    return out;
-  } catch {
-    // No config file (or unreadable / malformed): fall back to env + defaults.
-    return {};
-  }
-}
+/**
+ * The raw body of the request currently being handled.
+ *
+ * SET BY THE HANDLER, read here. The contract passes a decoded \`Customer\`,
+ * which is exactly what this store does not have and cannot produce: the
+ * receiver holds no private key in this mode, so the only thing it can send the
+ * connector is the ciphertext that arrived. Rather than widen the contract for
+ * one implementation, the handler parks the bytes here for the length of the
+ * request.
+ *
+ * Safe because Node runs one request's synchronous path at a time and this is
+ * read immediately, in the same tick the handler sets it. It would NOT be safe
+ * if anything awaited between the set and the read, which is why they are
+ * adjacent and why this comment exists.
+ */
+let currentRawBody = '';
+
+export function setCurrentRawBody(raw: string): void {
+  currentRawBody = raw;
+}
+
+function verdictOf(body: Record<string, unknown> | undefined, key: string): string | null {
+  const value = body?.[key];
+  return typeof value === 'string' ? value : null;
+}
+
+export const connectorStore = {
+  name: 'connector',
+  // The receiver holds no customer records in this mode, so "is the customer
+  // file encrypted" has no true answer. False is the honest one: there is no
+  // protected customer store here, because there is no customer store here.
+  encrypted: false,
+
+  async verifyAccount(
+    accountNumber: string | null,
+    _name: string,
+    _knownNames: string[] = [],
+  ): Promise<AccountVerdict> {
+    const answer = await askConnector('account.verify', currentRawBody);
+    if (!answer.reached) {
+      // NEVER GUESSED. A fabricated match authorises a stranger's address onto
+      // a customer's account. \`no_account\` is the safe answer and stops the
+      // consumer before they pay, which is the trade this design accepted.
+      report.warn(
+        \`[connector] account check for \${accountNumber ?? '(none)'} could not be answered; \` +
+        'refusing rather than guessing',
+      );
+      return 'no_account';
+    }
+    const status = verdictOf(answer.body, 'status');
+    if (status === 'match' || status === 'no_match' || status === 'no_account') return status;
+    report.warn(\`[connector] account.verify answered "\${status ?? '(nothing)'}", which is not a verdict\`);
+    return 'no_account';
+  },
 
-const fromFile = loadConfigFile();
+  async verifyAddress(_customer: Customer, _incoming: Address): Promise<VerifyResult> {
+    const answer = await askConnector('address.verify', currentRawBody);
+    if (!answer.reached) return 'not_found';
+    const result = verdictOf(answer.body, 'result');
+    if (result === 'match' || result === 'mismatch' || result === 'not_found') return result;
+    report.warn(\`[connector] address.verify answered "\${result ?? '(nothing)'}", which is not a result\`);
+    return 'not_found';
+  },
 
-export const config: ReceiverConfig = {
-  partnerId:     process.env.PARTNER_ID || fromFile.partnerId || DEFAULTS.partnerId,
-  oneAddressApi: stripTrailingSlash(process.env.ONEADDRESS_API || fromFile.oneAddressApi || DEFAULTS.oneAddressApi),
-  verifiesAccountReference:
-    process.env.VERIFIES_ACCOUNT_REFERENCE != null
-      ? process.env.VERIFIES_ACCOUNT_REFERENCE === 'true'
-      : (fromFile.verifiesAccountReference ?? DEFAULTS.verifiesAccountReference),
-};
+  saveAddress(_customer: Customer, _incoming: Address): Promise<Address> {
+    // Unreachable by design: see the header. Loud rather than quiet.
+    return Promise.reject(new Error(
+      'saveAddress was called in inbox mode. Updates are held for the connector to draw and ' +
+      'apply against your own database; nothing should write through this receiver.',
+    ));
+  },
 
-report.info(
-  '[config] loaded (oneAddressApi=' + config.oneAddressApi +
-  ', verifiesAccountReference=' + config.verifiesAccountReference + ')',
-);
+  find(_accountNumber: string): StoredCustomer | null { return null; },
+  count(): null { return null; },
+} satisfies CustomerStore;
 `
     },
     {
-      name: "src/callback-url.ts",
+      name: "src/connector-client.ts",
       content: `/**
- * src/callback-url.ts \u2014 the address.verify callback host allowlist.
+ * Asking the connector a question that cannot wait.
  *
- * OneAddress sends the \`callback_url\` inside the signed webhook body, so HMAC
- * verification already proves it came from OneAddress. This host allowlist is a
- * belt-and-braces against a leaked-webhook-secret SSRF: an attacker who could
- * forge a webhook must not be able to coerce this server into POSTing to an
- * internal URL (a cloud metadata service, a database admin port, \u2026).
+ * ## Why this direction exists at all
  *
- * It returns the validated URL string (or null) rather than a boolean on
- * purpose: the caller fetches the RETURN VALUE, so the allowlist sits directly
- * on the taint path and is a provable barrier for CodeQL's request-forgery
- * query (see .github/codeql/extensions/oneaddress-js-models \u2014 the same shape as
- * the redirect sanitiser). A boolean guard would leave the raw, still-tainted
- * value flowing to fetch, which reads as an SSRF whether or not the guard runs.
+ * Everything else between the receiver and the connector is a PULL: the
+ * connector draws work when it is ready. That is the right shape, because the
+ * partner's system should control its own pace.
+ *
+ * The two verify events cannot work that way. \`account.verify\` runs BEFORE the
+ * consumer pays and has to answer in the same request with match, no match, or
+ * no account; \`address.verify\` is the same shape. Both need a decrypt and a
+ * customer lookup, and in inbox mode both of those live in the connector. So
+ * for these, and only these, the receiver calls out and waits.
+ *
+ * ## A CORRECTION TO THE DESIGN DOCUMENT, recorded where it matters
+ *
+ * \`docs/architecture/receiver-connector-design.md\` says the connector "accepts
+ * no inbound connections". That is not achievable alongside a synchronous
+ * verify, and the verify decision is the one that was taken deliberately. So
+ * the connector DOES listen, on loopback only, and the honest form of the
+ * property is: no inbound port reachable from any NETWORK. The difference
+ * matters the day a partner puts the two on separate hosts, which is what the
+ * transport configuration below exists for.
+ *
+ * ## What happens when the connector is down
+ *
+ * The receiver tells OneAddress honestly that it could not check, and the
+ * consumer is stopped BEFORE they pay rather than after. That is the cost of
+ * choosing this over a verify-only key in the receiver: such a key would keep
+ * answers flowing during an outage and would make "the receiver cannot read
+ * addresses" untrue, which is the whole point of the split.
+ *
+ * It is NEVER answered with a guess. A fabricated match authorises a stranger's
+ * address onto a customer's account; a fabricated no-match costs a support
+ * call. Neither is ours to invent.
  */
-export function safeOneAddressCallbackUrl(raw: string): string | null {
+import { report } from './report.js';
+
+/**
+ * Where the connector listens.
+ *
+ * 3003, NOT 3002. Two loopback listeners exist in this design and swapping them
+ * is silent: the receiver's own draw channel is on 3002, so a receiver pointed
+ * at 3002 for verify asks ITSELF the question and gets a 404 that reads exactly
+ * like a connector that is down.
+ */
+const CONNECTOR_URL = process.env.CONNECTOR_URL ?? 'http://127.0.0.1:3003';
+const TOKEN = process.env.CONNECTOR_TOKEN ?? '';
+/**
+ * Short, because a consumer is watching a spinner on the other end of this.
+ * A verify that takes eight seconds has already failed as far as they are
+ * concerned, and an honest "could not check" beats a long hang.
+ */
+const TIMEOUT_MS = Number(process.env.CONNECTOR_TIMEOUT_MS ?? 5000);
+
+export type VerifyKind = 'account.verify' | 'address.verify';
+
+export interface ConnectorVerdict {
+  reached: boolean;
+  /** Whatever the connector answered. Passed through untouched. */
+  body?: Record<string, unknown>;
+  error?: string;
+}
+
+/**
+ * Hand the connector an encrypted verify event and wait for its answer.
+ *
+ * The RAW BODY goes over, not anything decoded: the receiver holds no private
+ * key in this mode and has nothing to decode it with. The connector decrypts,
+ * looks the customer up in the partner's database, and answers.
+ */
+export async function askConnector(kind: VerifyKind, rawBody: string): Promise<ConnectorVerdict> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
   try {
-    const u = new URL(raw);
-    if (u.protocol !== 'https:') return null;
-    const host = u.hostname.toLowerCase();
-    if (host === 'oneaddress.io' || host.endsWith('.oneaddress.io')) return raw;
-    return null;
-  } catch {
-    return null;
+    const res = await fetch(\`\${CONNECTOR_URL}/verify\`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': \`Bearer \${TOKEN}\`,
+        'X-OneAddress-Verify-Kind': kind,
+      },
+      body: rawBody,
+      signal: controller.signal,
+    });
+    const text = await res.text().catch(() => '');
+    if (!res.ok) {
+      report.error(\`[connector] \${kind} refused: HTTP \${res.status} \${text.slice(0, 200)}\`);
+      return { reached: false, error: \`HTTP \${res.status}\` };
+    }
+    try {
+      return { reached: true, body: JSON.parse(text) as Record<string, unknown> };
+    } catch {
+      report.error(\`[connector] \${kind} answered with something that is not JSON\`);
+      return { reached: false, error: 'bad response' };
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // NAMES THE REMEDY. This is the failure a partner will actually see, and
+    // "fetch failed" on its own sends them looking at OneAddress.
+    report.error(
+      \`[connector] could not reach the connector for \${kind} (\${message}). \` +
+      \`Account checks will fail until it is back. Is it running, and is CONNECTOR_URL (\${CONNECTOR_URL}) right?\`,
+    );
+    return { reached: false, error: message };
+  } finally {
+    clearTimeout(timer);
   }
 }
 `
     },
     {
-      name: "src/store.ts",
+      name: "src/draw-api.ts",
       content: `/**
- * \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
- * \u2551  src/store.ts  \u2014  DATABASE INTEGRATION                          \u2551
- * \u2551                                                                  \u2551
- * \u2551  A realistic partner-side store: a CUSTOMER ROSTER (who your      \u2551
- * \u2551  customers are + the address you hold on file for each), and the \u2551
- * \u2551  three hooks OneAddress calls:                                    \u2551
- * \u2551    verifyAccount  \u2014 pre-payment account check  (account.verify)  \u2551
- * \u2551    verifyAddress  \u2014 is your on-file address current? (address.verify)
- * \u2551    saveAddress    \u2014 apply a new address        (address.updated)  \u2551
- * \u2551                                                                  \u2551
- * \u2551  Swap the SQLite queries for your real customer database when     \u2551
- * \u2551  you're ready \u2014 the shapes below are what OneAddress hands you.  \u2551
- * \u2551  server.ts calls these after verifying and decrypting each event \u2551
- * \u2551  \u2014 the protocol layer is handled for you, never touch it.        \u2551
- * \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+ * The channel your connector draws from.
+ *
+ * ## The most dangerous surface in this receiver
+ *
+ * Everything else here handles ciphertext. This hands out dispatches a
+ * connector will decrypt, and takes its word for what was applied. An exposed
+ * or unauthenticated version of it is precisely the oracle the whole
+ * architecture exists to prevent, so three things are not configurable:
+ *
+ *   1. **It binds to 127.0.0.1 and nothing else.** There is deliberately no
+ *      option to bind it to an interface. A partner who needs the connector on
+ *      another host needs a transport with mutual authentication, not this one
+ *      with a wider bind, and giving them a knob that looks like it does the
+ *      job is how that ends up on a LAN.
+ *   2. **It runs on a SEPARATE PORT from the webhook.** Same process, different
+ *      listener, so nothing routed from the internet can reach these paths even
+ *      by mistake in a reverse proxy.
+ *   3. **It needs its own credential.** \`CONNECTOR_TOKEN\`, not the webhook
+ *      secret and not the confirm secret. Those are shared with OneAddress; a
+ *      leak of either must not also hand somebody your customers' addresses.
+ *      Compared in constant time, and the API refuses to start without it.
+ *
+ * ## What it does NOT decrypt
+ *
+ * Nothing. It hands over \`raw_body\`, the bytes as they arrived. The private key
+ * lives in the connector, which is the only component that can read any of it.
  */
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import express, { type Request, type Response } from 'express';
+import rateLimit from 'express-rate-limit';
+import { timingSafeEqual } from 'node:crypto';
 import { report } from './report.js';
-import db, { accountKey, dec, enc, encrypted, isEncrypted, once } from './db.js';
+import { acknowledge, drawable, markDrawn, type InboxOutcome } from './inbox.js';
 
-export type Address = Record<string, unknown>;
+const TOKEN = process.env.CONNECTOR_TOKEN ?? '';
+/**
+ * The RECEIVER's loopback listener, which is not the connector's.
+ *
+ * Named \`DRAW_PORT\` rather than \`CONNECTOR_PORT\` because the connector has a
+ * listener of its own, on \`CONNECTOR_PORT\` (3003), for the verify questions
+ * that cannot wait for a draw. One name for two ports on one host is a
+ * misconfiguration nobody would find: each end would bind or dial the other's.
+ */
+const DRAW_PORT = Number(process.env.DRAW_PORT ?? 3002);
+/**
+ * How long a drawn item stays claimed before it is offered again.
+ *
+ * Crash recovery for ONE connector, not concurrency for two. See \`inbox.ts\`.
+ * Generous, because the cost of re-offering too early is a duplicate apply and
+ * the cost of re-offering too late is a delay nobody dies of.
+ */
+const LEASE_SECONDS = Number(process.env.CONNECTOR_LEASE_SECONDS ?? 300);
+
+/** Constant time, and length-safe: \`timingSafeEqual\` throws on a length mismatch. */
+function tokenMatches(presented: string): boolean {
+  const a = Buffer.from(presented);
+  const b = Buffer.from(TOKEN);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+function authorised(req: Request, res: Response): boolean {
+  const header = req.headers.authorization ?? '';
+  const presented = header.startsWith('Bearer ') ? header.slice(7) : '';
+  if (presented && tokenMatches(presented)) return true;
+  // No detail, deliberately. This endpoint should tell an unauthorised caller
+  // nothing at all about whether it exists or what it holds.
+  res.status(401).json({ error: 'Unauthorised' });
+  return false;
+}
 
-// \u2500\u2500 Schema \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-// \`customers\` is your roster: the account number, the customer's name, and the
-// address YOU currently hold on file for them. \`address_history\` logs every
-// change you apply, so you have an audit trail.
-db.exec(\`
-  CREATE TABLE IF NOT EXISTS customers (
-    -- How a row is FOUND. A blind index of the account number when the database
-    -- is locked, the lower-cased number when it is not. It is the key rather
-    -- than the number itself because AES-GCM uses a fresh IV per write, so two
-    -- encryptions of one account number differ and a primary key over the
-    -- ciphertext would enforce nothing while looking like it did.
-    account_key    TEXT PRIMARY KEY,
-    -- What is DISPLAYED. Ciphertext when locked.
-    account_number TEXT NOT NULL,
-    name           TEXT NOT NULL,
-    address        TEXT NOT NULL DEFAULT '{}',
-    updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
+export function startDrawApi(): { port: number } | null {
+  if (connectorTokenMissing()) return null;
+
+  const app = express();
+  app.disable('x-powered-by');
+
+  // A BACKSTOP, AND NOT WHAT KEEPS THIS SHUT.
+  //
+  // What keeps it shut is the loopback bind and the credential, compared in
+  // constant time. This bounds what an attacker who is already on the box can
+  // spend, and it is deliberately far above any real connector: a draw every
+  // two seconds plus an acknowledgement per item is a few hundred a minute at
+  // worst, so a legitimate connector never meets this and a partner who tunes
+  // \`CONNECTOR_POLL_MS\` down still has room.
+  //
+  // No \`trust proxy\` here, unlike the webhook app. There is no proxy in front
+  // of a loopback listener, so \`X-Forwarded-For\` is somebody trying it on, and
+  // trusting it would let them key the limiter on an address of their choosing.
+  //
+  // Attached ONCE, on the app rather than per route. Two references to the same
+  // limiter instance count a request twice and silently halve the ceiling.
+  app.use(rateLimit({
+    windowMs: 60_000,
+    max: 2000,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: 'Too many requests' },
+  }));
+
+  app.use(express.json({ limit: '2mb' }));
+
+  /**
+   * Take the next batch of work.
+   *
+   * A GET with no side effects would be tidier and would be wrong: drawing has
+   * to stamp the lease, or a connector that asks twice gets the same items and
+   * applies them twice.
+   */
+  app.post('/draw', (req: Request, res: Response) => {
+    if (!authorised(req, res)) return;
+    const limit = Math.min(Number((req.body as { limit?: unknown }).limit ?? 20) || 20, 100);
+    const items = drawable(limit, LEASE_SECONDS);
+    markDrawn(items.map((i) => i.id));
+    if (items.length > 0) report.info(\`[draw] connector took \${items.length} dispatch(es)\`);
+    return res.json({ items });
+  });
+
+  /**
+   * What the connector did with one item.
+   *
+   * \`applied\` queues the confirm to OneAddress. \`failed\` queues a failed
+   * confirm, which is the honest answer when the partner's own system refused
+   * the change: the consumer is told it did not land rather than being told it
+   * did.
+   */
+  app.post('/ack', (req: Request, res: Response) => {
+    if (!authorised(req, res)) return;
+    const body = req.body as { id?: unknown; outcome?: unknown; detail?: unknown };
+    const id = typeof body.id === 'string' ? body.id : '';
+    const outcome: InboxOutcome | null =
+      body.outcome === 'applied' || body.outcome === 'failed' ? body.outcome : null;
+    if (!id || !outcome) {
+      return res.status(400).json({ error: 'id and outcome (applied|failed) are required' });
+    }
+    const detail = typeof body.detail === 'string' ? body.detail : null;
+
+    const result = acknowledge(id, outcome, detail);
+    if (!result) return res.status(404).json({ error: 'unknown id' });
+    if (result.alreadyAcknowledged) {
+      // NOT AN ERROR. A connector that is unsure its acknowledgement landed
+      // should retry, and punishing that is how an update ends up applied and
+      // never confirmed.
+      return res.json({ ok: true, duplicate: true });
+    }
+
+    if (result.dispatchId) onAcknowledged(result.dispatchId, outcome);
+    return res.json({ ok: true });
+  });
+
+  /** Enough for the connector to know it is talking to the right receiver. */
+  app.get('/connector/health', (req: Request, res: Response) => {
+    if (!authorised(req, res)) return;
+    return res.json({ status: 'ok', mode: 'inbox' });
+  });
+
+  app.listen(DRAW_PORT, '127.0.0.1', () =>
+    report.info(\`[draw] connector channel \u2192 http://127.0.0.1:\${DRAW_PORT} (loopback only)\`),
   );
+  return { port: DRAW_PORT };
+}
 
-  CREATE TABLE IF NOT EXISTS address_history (
-    id             INTEGER PRIMARY KEY AUTOINCREMENT,
-    account_key    TEXT NOT NULL,
-    -- Both sides of the change, so you can show what an address REPLACED
-    -- rather than only what it became.
-    prev_address   TEXT NOT NULL DEFAULT '{}',
-    address        TEXT NOT NULL,
-    recorded_at    TEXT NOT NULL DEFAULT (datetime('now'))
+/**
+ * Refuse to open the channel without a credential, and say why.
+ *
+ * Returning null rather than throwing, because a receiver in write-through mode
+ * has no connector and must start perfectly well without one. In inbox mode the
+ * caller turns this into a hard failure, since an inbox with no way to drain it
+ * is worse than a receiver that will not start.
+ */
+function connectorTokenMissing(): boolean {
+  if (TOKEN.trim().length >= 16) return false;
+  report.error(
+    '[draw] CONNECTOR_TOKEN is missing or shorter than 16 characters, so the connector ' +
+    'channel was NOT opened. This is its own credential on purpose: it must not be your ' +
+    'webhook secret or your confirm secret, because those are shared with OneAddress and a ' +
+    'leak of either must not also hand somebody your customers\\' addresses.',
   );
-  CREATE INDEX IF NOT EXISTS idx_history_account ON address_history(account_key, id DESC);
-\`);
+  return true;
+}
 
-// Self-migrate. An older data.db may already hold a \`customers\` table WITHOUT the
-// newer columns, and \`CREATE TABLE IF NOT EXISTS\` never alters an existing table.
-// Add any missing columns here so the handler upgrades its own schema instead of
-// forcing you to delete the database on every change \u2014 the behaviour a
-// production integration needs.
-function ensureColumn(table: string, column: string, definition: string): void {
-  const cols = db.prepare(\`PRAGMA table_info(\${table})\`).all() as Array<{ name: string }>;
-  if (!cols.some((c) => c.name === column)) {
-    db.exec(\`ALTER TABLE \${table} ADD COLUMN \${column} \${definition}\`);
-    report.info(\`[store] migrated: added column \${table}.\${column}\`);
-  }
+/**
+ * Told when an item is acknowledged, so the receiver can confirm to OneAddress.
+ *
+ * A setter rather than an import, because \`server.ts\` owns the confirm queue
+ * and already imports this module: importing it back would be a cycle.
+ */
+let onAcknowledged: (dispatchId: string, outcome: InboxOutcome) => void = () => {};
+
+export function setAcknowledgementHandler(
+  handler: (dispatchId: string, outcome: InboxOutcome) => void,
+): void {
+  onAcknowledged = handler;
 }
+`
+    },
+    {
+      name: "src/inbox.ts",
+      content: `/**
+ * Dispatches waiting for YOUR system to collect them.
+ *
+ * ## What this is, and why it is not the quarantine
+ *
+ * Both tables hold a signature-verified dispatch as the ciphertext that
+ * arrived. They mean opposite things.
+ *
+ * A QUARANTINED dispatch is one the receiver could not open: something is
+ * wrong, usually a key, and it is purged on a window because holding a
+ * consumer's encrypted address forever is a retention decision nobody made.
+ *
+ * An INBOX dispatch is one nothing is wrong with. It arrived intact and is
+ * waiting for the partner's own systems to draw it, apply it in their database
+ * and say so. **It is NEVER aged out**, and that asymmetry is deliberate: an
+ * undrawn update is a consumer whose address has not landed, and deleting it on
+ * a timer loses it silently. The dashboard reports a growing undrawn count as a
+ * fault instead, which is the honest way to make an operator deal with it.
+ *
+ * ## Nothing here is readable
+ *
+ * The rows hold the bytes as they arrived. In inbox mode the receiver holds no
+ * private key at all, so it could not decrypt these if it wanted to. That is
+ * the property the whole split exists for: the component reachable from the
+ * internet cannot read what it stores.
+ *
+ * ## The lease, and what it is NOT for
+ *
+ * A connector that draws a batch and then crashes must not strand it. So a draw
+ * stamps \`drawn_at\`, and an item becomes drawable again once that stamp is
+ * older than the lease. That is CRASH RECOVERY for one connector.
+ *
+ * It is not a design for two connectors drawing at once. Two would each get
+ * their own view of what is drawable between leases, and nothing here stops
+ * them applying the same update twice. If a second connector is ever wanted,
+ * the claim has to become atomic, the way \`confirm-queue.ts\` already does it.
+ * Written down because a lease LOOKS like it handles concurrency and does not.
+ */
+import db from './db.js';
+import { report } from './report.js';
+
+export type InboxOutcome = 'applied' | 'failed';
+
+db.exec(\`
+  CREATE TABLE IF NOT EXISTS inbox (
+    id          TEXT PRIMARY KEY,
+    dispatch_id TEXT,
+    event       TEXT NOT NULL,
+    raw_body    TEXT NOT NULL,
+    received_at TEXT NOT NULL DEFAULT (datetime('now')),
+    drawn_at    TEXT,
+    applied_at  TEXT,
+    outcome     TEXT,
+    detail      TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_inbox_open
+    ON inbox(applied_at, drawn_at, received_at);
+\`);
+
+export interface AcceptInput {
+  key: string;
+  dispatchId: string | null;
+  event: string;
+  rawBody: string;
+}
+
+/**
+ * Take a dispatch for the connector to collect.
+ *
+ * \`INSERT OR IGNORE\`, keyed on the same dispatch identity everything else here
+ * uses, so a OneAddress retry of a delivery we already hold does not queue the
+ * same update twice.
+ */
+export function accept(input: AcceptInput): void {
+  db.prepare(
+    \`INSERT OR IGNORE INTO inbox (id, dispatch_id, event, raw_body)
+     VALUES (?, ?, ?, ?)\`,
+  ).run(input.key, input.dispatchId, input.event, input.rawBody);
+}
+
+export interface InboxItem {
+  id: string;
+  dispatch_id: string | null;
+  event: string;
+  raw_body: string;
+  received_at: string;
+}
+
+/**
+ * What the connector may take now.
+ *
+ * Anything never drawn, plus anything drawn longer ago than the lease and still
+ * unacknowledged, which is the crashed-connector case.
+ */
+export function drawable(limit: number, leaseSeconds: number): InboxItem[] {
+  const cutoff = new Date(Date.now() - leaseSeconds * 1000).toISOString();
+  return db.prepare(
+    \`SELECT id, dispatch_id, event, raw_body, received_at
+       FROM inbox
+      WHERE applied_at IS NULL
+        AND (drawn_at IS NULL OR drawn_at < ?)
+      ORDER BY received_at
+      LIMIT ?\`,
+  ).all(cutoff, limit) as unknown as InboxItem[];
+}
+
+export function markDrawn(ids: string[]): void {
+  if (ids.length === 0) return;
+  const stamp = new Date().toISOString();
+  const stmt = db.prepare('UPDATE inbox SET drawn_at = ? WHERE id = ?');
+  for (const id of ids) stmt.run(stamp, id);
+}
+
+/**
+ * The connector's verdict on one item.
+ *
+ * Returns the dispatch id to confirm, or null when there is nothing to tell
+ * OneAddress: an unknown id, or one already acknowledged. Deliberately not an
+ * error, because a connector retrying an acknowledgement it is unsure landed is
+ * doing the right thing and must not be punished for it.
+ */
+export function acknowledge(
+  id: string,
+  outcome: InboxOutcome,
+  detail: string | null,
+): { dispatchId: string | null; alreadyAcknowledged: boolean } | null {
+  const row = db.prepare(
+    'SELECT dispatch_id, applied_at FROM inbox WHERE id = ?',
+  ).get(id) as { dispatch_id: string | null; applied_at: string | null } | undefined;
+  if (!row) return null;
+  if (row.applied_at !== null) {
+    return { dispatchId: row.dispatch_id, alreadyAcknowledged: true };
+  }
+  db.prepare(
+    'UPDATE inbox SET applied_at = ?, outcome = ?, detail = ? WHERE id = ?',
+  ).run(new Date().toISOString(), outcome, detail?.slice(0, 500) ?? null, id);
+  report.info(\`[inbox] \${id} acknowledged by the connector: \${outcome}\`);
+  return { dispatchId: row.dispatch_id, alreadyAcknowledged: false };
+}
+
+/** How many updates are sitting here unapplied. Shown as a fault when non-zero. */
+export function undrawnCount(): number {
+  const row = db.prepare(
+    'SELECT count(*) AS n FROM inbox WHERE applied_at IS NULL',
+  ).get() as { n: number };
+  return row.n;
+}
+
+/** When the oldest unapplied item arrived, for the age on the dashboard. */
+export function oldestUndrawn(): string | null {
+  const row = db.prepare(
+    'SELECT min(received_at) AS oldest FROM inbox WHERE applied_at IS NULL',
+  ).get() as { oldest: string | null };
+  return row.oldest;
+}
+
+/**
+ * NOTHING PURGES THIS TABLE, and the absence is the design.
+ *
+ * \`purgeQuarantine\` and \`purgeDelivered\` both exist one file over. There is no
+ * \`purgeInbox\`, and there should not be: every row here is an address change a
+ * consumer paid for that has not reached the partner's system yet. Ageing one
+ * out would delete the only copy anybody still has.
+ *
+ * Rows that HAVE been applied are kept too, because they are the partner's own
+ * record of what they were sent and when they acted on it. If that ever needs
+ * bounding, bound the APPLIED rows and never the open ones.
+ */
+export function appliedCount(): number {
+  const row = db.prepare(
+    'SELECT count(*) AS n FROM inbox WHERE applied_at IS NOT NULL',
+  ).get() as { n: number };
+  return row.n;
+}
+`
+    },
+    {
+      name: "src/tally.ts",
+      content: `/**
+ * How many dispatches arrived, landed, and did not.
+ *
+ * ## THE BUG THIS REPLACES, WHICH A PARTNER FOUND IN ABOUT A MINUTE
+ *
+ * The dashboard used to derive these by reading its own log feed: a line
+ * matching a failure pattern counted as one arrival and one failure. The
+ * comment beside it asserted the invariant that made that sound: "every
+ * dispatch produces exactly one of these".
+ *
+ * Then replay shipped. A replay produces exactly the same lines an arrival
+ * does, because it IS a delivery, back in through the front door. Somebody
+ * pressed [r] sixty times against a key that was never going to work and
+ * watched \`received\` climb from 5 to 67 and \`failed\` from 1 to 63. Nothing was
+ * arriving. The receiver was counting its own attempts to fix itself.
+ *
+ * The same fault was always there for a cause nobody had to trigger by hand:
+ * OneAddress RETRIES a 422, so a wrong key inflated these counters on its own,
+ * quietly, every few minutes.
+ *
+ * ## Why counting here fixes the class rather than the instance
+ *
+ * Narration is the wrong source. A log line says what happened, not what it
+ * happened TO, so two lines about one dispatch are indistinguishable from two
+ * dispatches. This keys on the DISPATCH, so every re-delivery of it - a
+ * replay, a OneAddress retry, a partner curling the same body twice - lands on
+ * the entry that is already there.
+ *
+ * That also makes a replay that finally WORKS do the right thing on its own:
+ * the entry flips from failed to applied, and the totals move without anything
+ * having to know a replay was involved.
+ *
+ * ## What is counted, stated because the footer does not have room to
+ *
+ * An \`address.updated\` that was stored is \`applied\`. Anything that could not be
+ * opened, or was refused, is \`failed\`. \`received\` is how many distinct
+ * dispatches reached one of those two, so \`received = applied + failed\` holds
+ * by construction rather than by hoping.
+ *
+ * An \`address.verify\` is deliberately none of them: it answers a question and
+ * changes nothing, so counting it as an application would overstate what this
+ * receiver has done. It still shows in the activity log.
+ *
+ * Since boot, like every other figure on that footer. The held count beside
+ * them is not: the quarantine is on disk and survives a restart.
+ */
+
+export type Outcome = 'applied' | 'failed';
+
+/**
+ * Bounded, because this is memory and a busy receiver runs for months.
+ *
+ * At the cap the oldest entry goes, exactly as \`seenDispatches\` does, and the
+ * totals then describe the most recent 5000 dispatches rather than all of them.
+ * That is the honest trade for a footer: an operator reads it to see whether
+ * things are working now, and nobody audits from it.
+ */
+const MAX_TRACKED = 5000;
+const outcomes = new Map<string, Outcome>();
+
+export function recordOutcome(dispatchKey: string, outcome: Outcome): void {
+  if (!outcomes.has(dispatchKey) && outcomes.size >= MAX_TRACKED) {
+    const oldest = outcomes.keys().next().value;
+    if (oldest !== undefined) outcomes.delete(oldest);
+  }
+  // \`set\` on an existing key overwrites in place and keeps its insertion order,
+  // which is what makes a replay that succeeds flip failed to applied rather
+  // than adding a second entry.
+  outcomes.set(dispatchKey, outcome);
+}
+
+export interface Tally {
+  received: number;
+  applied: number;
+  failed: number;
+}
+
+export function tally(): Tally {
+  let applied = 0;
+  for (const outcome of outcomes.values()) if (outcome === 'applied') applied += 1;
+  return { received: outcomes.size, applied, failed: outcomes.size - applied };
+}
+
+/** Test seam. Never called by the receiver. */
+export function resetTally(): void {
+  outcomes.clear();
+}
+`
+    },
+    {
+      name: "src/quarantine.ts",
+      content: `/**
+ * Dispatches that arrived intact and could not be opened.
+ *
+ * ## What this is for
+ *
+ * A dispatch whose signature verifies but whose payload will not decrypt used
+ * to get an HTTP 422 and a log line, and nothing was kept. OneAddress retries a
+ * 422, so the update survived exactly as long as its retry window. A partner
+ * who worked out on Thursday that the wrong key was installed on Monday had
+ * lost it, with nothing local to point at.
+ *
+ * So the bytes are kept. Fix the key, replay, and the same handler runs against
+ * the same request it already received.
+ *
+ * ## THREE PROPERTIES THAT ARE THE DESIGN, NOT DECORATION
+ *
+ * **Nothing is decrypted here.** The row holds exactly the ciphertext that
+ * arrived. It cannot contain a plaintext address, because at the moment it is
+ * written the receiver does not have one - that is the entire reason the row
+ * exists. Replay decrypts in memory in the handler, the same as a live dispatch.
+ *
+ * **Only a SIGNATURE-VERIFIED request is ever quarantined.** The call sites are
+ * all below the HMAC check. Quarantining before it would let anyone who can
+ * reach the webhook fill the disk, which turns a diagnostic into a
+ * denial-of-service surface.
+ *
+ * **The retention rule is the OPPOSITE of the confirm queue's, deliberately.**
+ * A confirm record is content-free, so keeping an outstanding one forever costs
+ * nothing and dropping it loses an update; nothing ages those out. A
+ * quarantined payload is a consumer's encrypted address on a partner's disk,
+ * and keeping it indefinitely is a retention nobody agreed to. These are purged
+ * on a window (30 days by default), replayed or not, and purging one that was
+ * never replayed says so out loud rather than quietly.
+ *
+ * ## What is NOT quarantined, and why
+ *
+ * An \`address.updated\` refused because the account reference matches no
+ * customer is a DECISION, not a fault. It is already reported to OneAddress as
+ * a failed confirm, the partner's data is exactly as they intended, and a
+ * replay would apply an address for an account they do not recognise. It stays
+ * a refusal.
+ */
+import db, { ensureColumn } from './db.js';
+import { report } from './report.js';
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Why a dispatch could not be applied. Shown verbatim on the dashboard.
+ *
+ * TWO VALUES, AND THE DISTINCTION IS THE DIAGNOSIS. \`no_key\` is a line missing
+ * from \`.env\`; \`decrypt_failed\` is a key that is present and wrong. AES-GCM
+ * cannot tell a wrong key from a tampered ciphertext, so this record of which
+ * branch refused is the only thing that separates them afterwards.
+ *
+ * There is deliberately no \`handler_error\`. A fault inside the handler is a
+ * bug in code the partner can edit, not a dispatch waiting on a configuration
+ * change, and holding a payload for it would suggest replaying is the remedy.
+ */
+export type QuarantineReason = 'no_key' | 'decrypt_failed';
+
+db.exec(\`
+  CREATE TABLE IF NOT EXISTS quarantine (
+    id           TEXT PRIMARY KEY,
+    dispatch_id  TEXT,
+    event        TEXT NOT NULL,
+    reason       TEXT NOT NULL,
+    key_id       TEXT,
+    raw_body     TEXT NOT NULL,
+    detail       TEXT,
+    received_at  TEXT NOT NULL DEFAULT (datetime('now')),
+    replayed_at  TEXT,
+    last_error   TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_quarantine_open
+    ON quarantine(replayed_at, received_at);
+\`);
+
+/**
+ * One row per dispatch, not one per delivery attempt.
+ *
+ * OneAddress retries a 422, so the SAME broken dispatch arrives again every few
+ * minutes while the key is still wrong. Without a stable id a single
+ * misconfigured key would write a row a minute until someone noticed. Keyed on
+ * the dispatch header where there is one, and on a hash of the body where there
+ * is not, so a retry updates the existing row instead of adding to a pile.
+ */
+export function dispatchKey(dispatchId: string | null, rawBody: string): string {
+  if (dispatchId && dispatchId.trim()) return \`d:\${dispatchId.trim()}\`;
+  return \`h:\${createHash('sha256').update(rawBody).digest('hex').slice(0, 32)}\`;
+}
+
+/**
+ * Attempts, so the panel can say how hard this has been tried.
+ *
+ * Added after the quarantine shipped, hence the migration: a partner already
+ * running 2.1.3 has the table without it. Somebody pressed [r] sixty times
+ * against a key that could never work, and the only figure that moved was one
+ * the dashboard was computing wrongly. An attempt count on the row would have
+ * said so immediately.
+ */
+ensureColumn('quarantine', 'attempts', 'INTEGER NOT NULL DEFAULT 0');
+
+export interface QuarantineInput {
+  dispatchId: string | null;
+  event: string;
+  reason: QuarantineReason;
+  keyId: string | null;
+  rawBody: string;
+  detail: string;
+}
+
+/**
+ * Keep a dispatch that could not be applied.
+ *
+ * Best-effort by design: this runs on a path that is ALREADY failing, and a
+ * quarantine write that throws would turn a recoverable 422 into a 500. The
+ * caller must be able to answer OneAddress whatever happens here.
+ */
+export function quarantine(input: QuarantineInput): void {
+  const id = dispatchKey(input.dispatchId, input.rawBody);
+  try {
+    db.prepare(
+      \`INSERT INTO quarantine (id, dispatch_id, event, reason, key_id, raw_body, detail)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         reason = excluded.reason,
+         key_id = excluded.key_id,
+         detail = excluded.detail\`,
+    ).run(
+      id,
+      input.dispatchId,
+      input.event,
+      input.reason,
+      input.keyId,
+      input.rawBody,
+      input.detail.slice(0, 500),
+    );
+    report.warn(
+      \`[quarantine] \${input.event} held (\${input.reason}\${input.keyId ? \`, key_id \${input.keyId}\` : ''}). \` +
+      'Fix the cause and press [r] on the dashboard, or run \`npm run replay\`, to apply it.',
+    );
+  } catch (err) {
+    report.error('[quarantine] could not hold this dispatch:', err instanceof Error ? err.message : err);
+  }
+}
+
+export interface HeldDispatch {
+  id: string;
+  dispatch_id: string | null;
+  event: string;
+  reason: QuarantineReason;
+  key_id: string | null;
+  raw_body: string;
+  detail: string | null;
+  received_at: string;
+  last_error: string | null;
+  attempts: number;
+}
+
+/** Everything still held, oldest first. */
+export function heldDispatches(limit = 50): HeldDispatch[] {
+  return db.prepare(
+    \`SELECT id, dispatch_id, event, reason, key_id, raw_body, detail,
+            received_at, last_error, attempts
+       FROM quarantine
+      WHERE replayed_at IS NULL
+      ORDER BY received_at
+      LIMIT ?\`,
+  ).all(limit) as unknown as HeldDispatch[];
+}
+
+/** How many dispatches are held. Shown on the dashboard. */
+export function heldCount(): number {
+  const row = db.prepare(
+    'SELECT count(*) AS n FROM quarantine WHERE replayed_at IS NULL',
+  ).get() as { n: number };
+  return row.n;
+}
+
+/**
+ * A one-line summary per held dispatch, grouped by cause.
+ *
+ * Grouped because the realistic shape of this table is fifty rows with ONE
+ * cause between them: a key was wrong for an afternoon. Fifty identical lines
+ * hide that; "47 held: no key for key_id 0403\u2026" is the whole diagnosis.
+ */
+export function heldSummary(): string[] {
+  const rows = db.prepare(
+    \`SELECT reason, key_id, count(*) AS n,
+            max(attempts) AS tries, min(received_at) AS oldest
+       FROM quarantine
+      WHERE replayed_at IS NULL
+      GROUP BY reason, key_id
+      ORDER BY n DESC\`,
+  ).all() as unknown as {
+    reason: string; key_id: string | null; n: number; tries: number; oldest: string;
+  }[];
+  return rows.map((r) => {
+    const cause = \`\${r.n} \xD7 \${r.reason}\${r.key_id ? \` (key_id \${r.key_id})\` : ''}\`;
+    // TRIED AND AGE, because the count alone does not say whether anything is
+    // being done about it. A partner watching "1 \xD7 decrypt_failed" with no
+    // other figure moving cannot tell a replay that is working from one that
+    // is not; "61 tries" answers that without reading the log.
+    const tried = r.tries > 0 ? \`, \${r.tries} \${r.tries === 1 ? 'try' : 'tries'}\` : '';
+    return \`\${cause}\${tried}, first seen \${describeAge(r.oldest)}\`;
+  });
+}
+
+/** "3m ago", "2h ago". Coarse on purpose: nobody acts on seconds. */
+export function describeAge(iso: string): string {
+  const ms = Date.now() - new Date(iso).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return 'just now';
+  const mins = Math.floor(ms / 60_000);
+  if (mins < 1) return 'moments ago';
+  if (mins < 60) return \`\${mins}m ago\`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 48) return \`\${hours}h ago\`;
+  return \`\${Math.floor(hours / 24)}d ago\`;
+}
+
+export function markReplayed(id: string): void {
+  db.prepare(
+    'UPDATE quarantine SET replayed_at = ?, last_error = NULL WHERE id = ?',
+  ).run(new Date().toISOString(), id);
+}
+
+/** A replay that failed the same way stays held, with the new reason recorded. */
+export function markReplayFailed(id: string, error: string): void {
+  db.prepare('UPDATE quarantine SET last_error = ?, attempts = attempts + 1 WHERE id = ?')
+    .run(error.slice(0, 500), id);
+}
+
+/**
+ * Drop held payloads past the retention window, replayed or not.
+ *
+ * DELIBERATELY UNLIKE \`purgeDelivered\` IN THE CONFIRM QUEUE, which never ages
+ * out an outstanding row. The difference is what the row contains. A confirm
+ * record names a dispatch and an outcome and nothing else, so holding it costs
+ * a consumer nothing. A quarantined payload is that consumer's address,
+ * encrypted, on a third party's disk: an unbounded hold is a retention decision
+ * made on their behalf by nobody.
+ *
+ * An unreplayed row going out is reported separately and loudly, because that
+ * is an update the partner never applied and is now no longer able to.
+ */
+export function purgeQuarantine(days: number): { replayed: number; unreplayed: number } {
+  const cutoff = new Date(Date.now() - days * 86_400_000).toISOString();
+  const doomed = db.prepare(
+    'SELECT id, replayed_at FROM quarantine WHERE received_at < ?',
+  ).all(cutoff) as unknown as { id: string; replayed_at: string | null }[];
+  if (doomed.length === 0) return { replayed: 0, unreplayed: 0 };
+
+  db.prepare('DELETE FROM quarantine WHERE received_at < ?').run(cutoff);
+
+  const unreplayed = doomed.filter((d) => d.replayed_at === null).length;
+  const replayed = doomed.length - unreplayed;
+  if (replayed > 0) {
+    report.info(\`[quarantine] purged \${replayed} replayed payload(s) older than \${days}d\`);
+  }
+  if (unreplayed > 0) {
+    report.warn(
+      \`[quarantine] purged \${unreplayed} payload(s) older than \${days}d that were NEVER APPLIED. \` +
+      'Those address updates are gone from this receiver. Raise them with OneAddress if you need them re-sent.',
+    );
+  }
+  return { replayed, unreplayed };
+}
+
+/**
+ * Write the held list to a file, WITHOUT the payloads.
+ *
+ * ## Why the ciphertext is not in here
+ *
+ * The obvious export carries the payload so the fault can be replayed
+ * somewhere else. It also puts a copy of a consumer's encrypted address in a
+ * file that the retention window cannot reach: the quarantine purges its rows,
+ * and nothing purges an export somebody emailed to support and left in a
+ * downloads folder. The whole point of the retention rule is that a held
+ * address does not sit anywhere indefinitely, and an export that leaks past it
+ * quietly undoes that.
+ *
+ * Nothing in here is personal. A dispatch id, what kind of event it was, why it
+ * could not be opened, which key it asked for, and when. That is the whole of
+ * what diagnoses a key problem, and it is safe to paste into a support ticket
+ * or send to us, which is what an export is for.
+ */
+export function exportHeld(directory: string): { path: string; count: number } {
+  const rows = heldDispatches(500);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const path = join(directory, \`oneaddress-faults-\${stamp}.json\`);
+  writeFileSync(path, JSON.stringify({
+    exported_at: new Date().toISOString(),
+    note: 'Metadata only. The held payloads are deliberately not included: they are encrypted consumer addresses and stay under the receiver retention window.',
+    held: rows.map((r) => ({
+      id: r.id,
+      dispatch_id: r.dispatch_id,
+      event: r.event,
+      reason: r.reason,
+      key_id: r.key_id,
+      received_at: r.received_at,
+      age: describeAge(r.received_at),
+      attempts: r.attempts,
+      detail: r.detail,
+      last_error: r.last_error,
+    })),
+  }, null, 2));
+  report.info(\`[quarantine] exported \${rows.length} held dispatch(es) to \${path}\`);
+  return { path, count: rows.length };
+}
+
+/**
+ * Re-run every held dispatch through the handler.
+ *
+ * Takes the handler rather than importing it, for the same reason \`drainConfirms\`
+ * takes its sender: this module then needs no knowledge of Express, decryption
+ * or keys, and a test can drive it with a function that fails once and succeeds
+ * on the second call.
+ */
+export async function replayHeld(
+  apply: (rawBody: string, dispatchId: string | null) => Promise<void>,
+  limit = 50,
+): Promise<{ applied: number; failed: number }> {
+  let applied = 0;
+  let failed = 0;
+  for (const row of heldDispatches(limit)) {
+    try {
+      // THE ROW'S OWN DISPATCH ID, not one re-derived from the body.
+      //
+      // \`redeliver\` used to parse \`dispatch_id\` out of the JSON and send that
+      // as the header. A dispatch that arrived WITHOUT the header was keyed on
+      // a hash of its body; the replay then supplied a header from the body,
+      // so the re-arrival was keyed by id instead, landed in a DIFFERENT row,
+      // and one held dispatch became two. Seen on a real receiver: \`1 \xD7
+      // decrypt_failed\` became \`2 \xD7\` on the first press of [r].
+      //
+      // Identity has to come from one place. This row already knows what it
+      // arrived as.
+      await apply(row.raw_body, row.dispatch_id);
+      markReplayed(row.id);
+      applied += 1;
+      report.info(\`[replay] applied \${row.event} \${row.dispatch_id ?? row.id}\`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      markReplayFailed(row.id, message);
+      failed += 1;
+      report.warn(\`[replay] \${row.dispatch_id ?? row.id} still failing: \${message}\`);
+    }
+  }
+  if (applied === 0 && failed === 0) report.info('[replay] nothing held');
+  return { applied, failed };
+}
+`
+    },
+    {
+      name: "src/confirm-queue.ts",
+      content: `/**
+ * Telling OneAddress you applied an update, durably.
+ *
+ * ## The bug this replaces, which cost real money
+ *
+ * The confirm callback used to be one \`fetch\` with a \`catch\` that logged. If
+ * \`/api/confirm\` was unreachable for thirty seconds, the address was applied
+ * here and OneAddress never learned. The consumer was shown a failed delivery,
+ * and the auto-refund cron could refund a dispatch that had in fact succeeded.
+ * Nothing retried, nothing surfaced, and the receiver's own log said "applied".
+ *
+ * So the confirm is now a queued, durable fact rather than a best-effort call:
+ * it survives a restart, retries with backoff, and is visible while it is
+ * outstanding.
+ *
+ * ## Why the queue is keyed on dispatch_id
+ *
+ * One row per dispatch, \`INSERT OR IGNORE\`. OneAddress retries a dispatch it
+ * has not heard about, so the same id can arrive more than once; enqueuing
+ * twice would confirm twice. The primary key makes that impossible rather than
+ * making it something every caller has to remember.
+ *
+ * ## Why a failing confirm is retried forever rather than given up on
+ *
+ * The commonest cause of a 401 here is a wrong or stale CONFIRM_SECRET, which
+ * is fixed by editing \`.env\` and restarting. Abandoning the row would mean the
+ * partner fixes the secret and the update stays lost. The backoff caps at an
+ * hour, so a permanently-broken secret costs one request an hour and stays
+ * visible in the queue depth, which is the signal that something needs a human.
+ */
+import db from './db.js';
+import { report } from './report.js';
+
+export type ConfirmStatus = 'confirmed' | 'failed';
+
+db.exec(\`
+  CREATE TABLE IF NOT EXISTS confirm_queue (
+    dispatch_id     INTEGER PRIMARY KEY,
+    status          TEXT NOT NULL,
+    attempts        INTEGER NOT NULL DEFAULT 0,
+    next_attempt_at TEXT NOT NULL,
+    last_error      TEXT,
+    delivered_at    TEXT,
+    created_at      TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_confirm_due
+    ON confirm_queue(delivered_at, next_attempt_at);
+\`);
+
+/**
+ * Backoff, in seconds, by attempt number.
+ *
+ * Fast at first because the overwhelming majority of failures are a blip and
+ * clear on the second try; then long, because the ones that do not clear are
+ * configuration and need a person, not a tighter loop.
+ */
+const BACKOFF_SECONDS = [5, 15, 60, 300, 900, 3600];
+
+function delayFor(attempts: number): number {
+  return BACKOFF_SECONDS[Math.min(attempts, BACKOFF_SECONDS.length - 1)];
+}
+
+function isoIn(seconds: number): string {
+  return new Date(Date.now() + seconds * 1000).toISOString();
+}
+
+/**
+ * Record that this dispatch needs confirming. Safe to call twice.
+ *
+ * Deliberately synchronous and local: the webhook handler must not wait on a
+ * network round trip to OneAddress before answering the dispatch, or a slow
+ * confirm turns into a timed-out webhook and a pointless redelivery.
+ */
+export function enqueueConfirm(dispatchId: number, status: ConfirmStatus): void {
+  db.prepare(
+    \`INSERT OR IGNORE INTO confirm_queue (dispatch_id, status, next_attempt_at)
+     VALUES (?, ?, ?)\`,
+  ).run(dispatchId, status, new Date().toISOString());
+}
+
+export interface PendingConfirm {
+  dispatch_id: number;
+  status: ConfirmStatus;
+  attempts: number;
+}
+
+/** Everything due to be sent now, oldest first. */
+export function dueConfirms(limit = 20): PendingConfirm[] {
+  return db.prepare(
+    \`SELECT dispatch_id, status, attempts
+       FROM confirm_queue
+      WHERE delivered_at IS NULL
+        AND next_attempt_at <= ?
+      ORDER BY created_at
+      LIMIT ?\`,
+  ).all(new Date().toISOString(), limit) as unknown as PendingConfirm[];
+}
+
+/** How many confirms are still outstanding. Shown on the dashboard. */
+export function pendingConfirmCount(): number {
+  const row = db.prepare(
+    'SELECT count(*) AS n FROM confirm_queue WHERE delivered_at IS NULL',
+  ).get() as { n: number };
+  return row.n;
+}
+
+export function markDelivered(dispatchId: number): void {
+  db.prepare(
+    \`UPDATE confirm_queue SET delivered_at = ?, last_error = NULL WHERE dispatch_id = ?\`,
+  ).run(new Date().toISOString(), dispatchId);
+}
+
+/** Back off and record why, so the queue explains itself without a log dig. */
+export function markFailed(dispatchId: number, attempts: number, error: string): void {
+  const next = delayFor(attempts);
+  db.prepare(
+    \`UPDATE confirm_queue
+        SET attempts = attempts + 1, next_attempt_at = ?, last_error = ?
+      WHERE dispatch_id = ?\`,
+  ).run(isoIn(next), error.slice(0, 500), dispatchId);
+}
+
+/**
+ * Drop delivered rows older than the retention window.
+ *
+ * Delivered ONLY. An outstanding confirm is never purged on age: a receiver
+ * that was off for a month must still tell OneAddress what it applied, and
+ * silently dropping those is the original bug with extra steps.
+ */
+export function purgeDelivered(days: number): number {
+  const cutoff = new Date(Date.now() - days * 86_400_000).toISOString();
+  const res = db.prepare(
+    \`DELETE FROM confirm_queue WHERE delivered_at IS NOT NULL AND delivered_at < ?\`,
+  ).run(cutoff);
+  return Number(res.changes ?? 0);
+}
+
+/**
+ * Drain the queue once.
+ *
+ * Takes the sender so this module needs no knowledge of HTTP, secrets or
+ * signing, which is what lets it be tested without a server: the test passes a
+ * function that fails twice and then succeeds, and asserts the row survives.
+ */
+export async function drainConfirms(
+  send: (dispatchId: number, status: ConfirmStatus) => Promise<void>,
+  limit = 20,
+): Promise<{ delivered: number; failed: number }> {
+  let delivered = 0;
+  let failed = 0;
+  for (const row of dueConfirms(limit)) {
+    try {
+      await send(row.dispatch_id, row.status);
+      markDelivered(row.dispatch_id);
+      delivered += 1;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      markFailed(row.dispatch_id, row.attempts, message);
+      failed += 1;
+      // Said once per attempt rather than once per drain, because the attempt
+      // count and the reason are what tell a partner whether to wait or act.
+      report.warn(
+        \`[confirm] dispatch \${row.dispatch_id} not acknowledged (attempt \${row.attempts + 1}): \${message}\`,
+      );
+    }
+  }
+  return { delivered, failed };
+}
+`
+    },
+    {
+      name: "src/keys.ts",
+      content: `/**
+ * Which private key opens this dispatch.
+ *
+ * ## Why this file exists
+ *
+ * OneAddress supports key rotation: a new key is registered, both are valid for
+ * an overlap window, and every dispatch names the key it was encrypted to in
+ * \`session_key_share.key_id\`. A receiver holding ONE key therefore has a window
+ * where perfectly good dispatches arrive that it cannot open.
+ *
+ * Until this existed the scaffold read a single \`PARTNER_PRIVATE_KEY_PEM\` and
+ * used it for every dispatch whatever key id was named. That fails in the worst
+ * possible way: AES-GCM cannot tell "wrong key" from "tampered ciphertext", so
+ * the error is an authentication-tag failure that reads like corruption. A real
+ * partner hit exactly this and had no way to tell which of the two it was.
+ *
+ * ## The convention, and why it matches the production receiver
+ *
+ *   PARTNER_PRIVATE_KEY_PEM_<KEY_ID>   dashes to underscores, upper-cased
+ *   PARTNER_PRIVATE_KEY_PEM            the single-key fallback
+ *
+ * This is the same shape \`@oneaddress/receiver\` uses for \`OA_PRIVATE_KEY_<ID>\`,
+ * deliberately: a partner who outgrows this scaffold and moves to the
+ * production receiver should not have to learn a second way of naming keys.
+ *
+ * ## The fallback is convenient and slightly dangerous
+ *
+ * It answers for ANY key id, which is what made a rotation look like corruption.
+ * It is kept because removing it would break every existing single-key partner
+ * on upgrade, but two things now make it safe to hold:
+ *
+ *   - \`PARTNER_KEYS_STRICT=1\` disables it, and any partner holding more than one
+ *     key should set that
+ *   - when it answers and the decrypt then fails, the error SAYS it was the
+ *     fallback and names the key id it was asked for, so the next step is
+ *     obvious rather than a guess
+ */
+
+/** Where a key came from. Carried into the error message when a decrypt fails. */
+export type KeySource = 'exact' | 'fallback';
+
+export interface ResolvedKey {
+  pem: string;
+  source: KeySource;
+}
+
+const PREFIX = 'PARTNER_PRIVATE_KEY_PEM';
+
+/** \`04032299-4b04-...\` becomes \`04032299_4B04_...\`, matching the env convention. */
+function envSuffix(keyId: string): string {
+  return keyId.replace(/-/g, '_').toUpperCase();
+}
+
+/**
+ * A PEM written into \`.env\` on one line arrives with literal backslash-n.
+ * Both forms are accepted so a key pasted either way works.
+ */
+function unescapeNewlines(pem: string): string {
+  return pem.includes('\\\\n') ? pem.replace(/\\\\n/g, '\\n') : pem;
+}
+
+/** Every key id this receiver has a key for, lower-cased. */
+export function configuredKeyIds(env: NodeJS.ProcessEnv = process.env): string[] {
+  return Object.keys(env)
+    .filter((k) => k.startsWith(\`\${PREFIX}_\`) && (env[k] ?? '').trim() !== '')
+    .map((k) => k.slice(PREFIX.length + 1).toLowerCase().replaceAll('_', '-'));
+}
+
+/** Is the single-key fallback turned off? */
+export function strictKeys(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env.PARTNER_KEYS_STRICT ?? '').trim() === '1';
+}
+
+/**
+ * The key for this dispatch, or null when nothing can open it.
+ *
+ * Null is a real answer, not an error: it means "I do not hold this key", and
+ * the caller turns that into a message naming the key id, which is the one
+ * thing the partner needs in order to fix it.
+ */
+export function resolvePrivateKey(
+  keyId: string | null | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedKey | null {
+  if (keyId) {
+    const exact = env[\`\${PREFIX}_\${envSuffix(keyId)}\`];
+    if (exact && exact.trim()) return { pem: unescapeNewlines(exact), source: 'exact' };
+  }
+  if (strictKeys(env)) return null;
+  const fallback = env[PREFIX];
+  if (fallback && fallback.trim()) return { pem: unescapeNewlines(fallback), source: 'fallback' };
+  return null;
+}
+
+/**
+ * What to tell the partner when a decrypt fails, given which key answered.
+ *
+ * SEPARATE FROM THE CATCH so the wording is one thing rather than three copies
+ * drifting apart, and so it can be tested without staging a failed decrypt.
+ */
+export function keyFailureAdvice(keyId: string | null | undefined, resolved: ResolvedKey | null): string {
+  const named = keyId ?? '(none named)';
+  if (!resolved) {
+    return strictKeys()
+      ? \`no key configured for key_id \${named}. Set PARTNER_PRIVATE_KEY_PEM_\${keyId ? envSuffix(keyId) : '<KEY_ID>'} in .env. (PARTNER_KEYS_STRICT=1 is set, so the single-key fallback is off.)\`
+      : \`no key configured for key_id \${named}, and PARTNER_PRIVATE_KEY_PEM is empty. Set one in .env.\`;
+  }
+  if (resolved.source === 'fallback') {
+    return \`the single-key PARTNER_PRIVATE_KEY_PEM was used for key_id \${named} and could not open it. If you have rotated keys, set PARTNER_PRIVATE_KEY_PEM_\${keyId ? envSuffix(keyId) : '<KEY_ID>'} to the matching private key. Both old and new stay valid during the overlap window, so keep the previous one set too.\`;
+  }
+  return \`PARTNER_PRIVATE_KEY_PEM_\${keyId ? envSuffix(keyId) : '<KEY_ID>'} is set but does not open this dispatch. Check it is the private half of the public key registered for that key_id in the portal.\`;
+}
+
+/**
+ * A line for the startup log: what this receiver can open.
+ *
+ * Printed every boot because the commonest key problem is believing a variable
+ * is set when it is not, and the second commonest is holding one key after a
+ * rotation. Both are visible in one line.
+ */
+export function describeKeys(env: NodeJS.ProcessEnv = process.env): string {
+  const ids = configuredKeyIds(env);
+  const hasFallback = !strictKeys(env) && (env[PREFIX] ?? '').trim() !== '';
+  if (ids.length === 0 && !hasFallback) {
+    return 'NO private key configured \u2014 every dispatch will fail to decrypt';
+  }
+  const parts: string[] = [];
+  if (ids.length > 0) parts.push(\`\${ids.length} key id(s): \${ids.join(', ')}\`);
+  if (hasFallback) parts.push(ids.length > 0 ? 'plus the single-key fallback' : 'single-key fallback only');
+  return parts.join(' ');
+}
+`
+    },
+    {
+      name: "src/config.ts",
+      content: `/**
+ * src/config.ts \u2014 the configuration you set in SETUP, read by the handler.
+ *
+ * \`npx @oneaddress/setup\` writes oneaddress.config.json next to your .env. This
+ * module is the ONE place the receiver reads it, so what you chose during setup
+ * drives the running handler with no code to edit. Secrets stay in .env; this
+ * file is non-secret behaviour only.
+ *
+ * Precedence for every field: an explicit environment variable wins (a one-off
+ * override), then oneaddress.config.json (what setup wrote), then a built-in
+ * default. A missing config file is not an error \u2014 the handler still runs.
+ */
+import { report } from './report.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * WRITE-THROUGH or INBOX, and both are supported on purpose.
+ *
+ * \`write-through\` is what this receiver has always done: decrypt the dispatch,
+ * apply it through \`CustomerStore\`, confirm to OneAddress. Right for a sole
+ * trader and for anyone happy for the receiver to reach their data directly.
+ *
+ * \`inbox\` is for a company with change control over its customer master. The
+ * receiver verifies the signature, stores the dispatch AS IT ARRIVED, and holds
+ * no private key at all. The partner's own connector draws it, decrypts it,
+ * applies it in their database, and acknowledges; only then does the receiver
+ * confirm to OneAddress. The component reachable from the internet cannot read
+ * what it holds.
+ *
+ * Nothing on the wire differs between them. The protocol already separates
+ * delivery from application: the webhook 200 acknowledges delivery and the
+ * confirm reports application. Write-through simply collapses the two.
+ */
+export type ReceiverMode = 'write-through' | 'inbox';
+
+export type ReceiverConfig = {
+  partnerId:                string;
+  oneAddressApi:            string;
+  verifiesAccountReference: boolean;
+  mode:                     ReceiverMode;
+};
+
+const DEFAULTS: ReceiverConfig = {
+  partnerId:     '',
+  oneAddressApi: 'https://oneaddress.io',
+  // A receiver that can match, matches. The wizard writes an EXPLICIT value here
+  // from your portal declaration, so this default only bites if the config file
+  // is missing entirely \u2014 in which case answering account.verify is the safer,
+  // more useful default than silently returning "not checked".
+  verifiesAccountReference: true,
+  // DEFAULTS TO WHAT THE RECEIVER HAS ALWAYS DONE. Inbox mode needs a connector
+  // running and a key living somewhere else; a receiver that silently switched
+  // into it would accept dispatches nothing ever collects.
+  mode: 'write-through',
+};
+
+function parseMode(value: unknown): ReceiverMode | undefined {
+  return value === 'inbox' || value === 'write-through' ? value : undefined;
+}
+
+function stripTrailingSlash(s: string): string {
+  return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+
+function loadConfigFile(): Partial<ReceiverConfig> {
+  const path = process.env.ONEADDRESS_CONFIG ?? join(process.cwd(), 'oneaddress.config.json');
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+    const out: Partial<ReceiverConfig> = {};
+    if (typeof parsed.partnerId === 'string')                out.partnerId = parsed.partnerId;
+    if (typeof parsed.oneAddressApi === 'string')            out.oneAddressApi = parsed.oneAddressApi;
+    if (typeof parsed.verifiesAccountReference === 'boolean') out.verifiesAccountReference = parsed.verifiesAccountReference;
+    const mode = parseMode(parsed.mode);
+    if (mode) out.mode = mode;
+    return out;
+  } catch {
+    // No config file (or unreadable / malformed): fall back to env + defaults.
+    return {};
+  }
+}
+
+const fromFile = loadConfigFile();
+
+export const config: ReceiverConfig = {
+  partnerId:     process.env.PARTNER_ID || fromFile.partnerId || DEFAULTS.partnerId,
+  oneAddressApi: stripTrailingSlash(process.env.ONEADDRESS_API || fromFile.oneAddressApi || DEFAULTS.oneAddressApi),
+  verifiesAccountReference:
+    process.env.VERIFIES_ACCOUNT_REFERENCE != null
+      ? process.env.VERIFIES_ACCOUNT_REFERENCE === 'true'
+      : (fromFile.verifiesAccountReference ?? DEFAULTS.verifiesAccountReference),
+  // An UNRECOGNISED value falls back to write-through rather than failing, and
+  // the startup line below says which mode is live either way, so a typo shows
+  // up as "not the mode I asked for" rather than as a receiver that will not
+  // start. Silent is the thing to avoid, not strict.
+  mode: parseMode(process.env.RECEIVER_MODE) ?? fromFile.mode ?? DEFAULTS.mode,
+};
+
+report.info(
+  '[config] loaded (mode=' + config.mode +
+  ', oneAddressApi=' + config.oneAddressApi +
+  ', verifiesAccountReference=' + config.verifiesAccountReference + ')',
+);
+`
+    },
+    {
+      name: "src/callback-url.ts",
+      content: `/**
+ * src/callback-url.ts \u2014 the address.verify callback host allowlist.
+ *
+ * OneAddress sends the \`callback_url\` inside the signed webhook body, so HMAC
+ * verification already proves it came from OneAddress. This host allowlist is a
+ * belt-and-braces against a leaked-webhook-secret SSRF: an attacker who could
+ * forge a webhook must not be able to coerce this server into POSTing to an
+ * internal URL (a cloud metadata service, a database admin port, \u2026).
+ *
+ * It returns the validated URL string (or null) rather than a boolean on
+ * purpose: the caller fetches the RETURN VALUE, so the allowlist sits directly
+ * on the taint path and is a provable barrier for CodeQL's request-forgery
+ * query (see .github/codeql/extensions/oneaddress-js-models \u2014 the same shape as
+ * the redirect sanitiser). A boolean guard would leave the raw, still-tainted
+ * value flowing to fetch, which reads as an SSRF whether or not the guard runs.
+ */
+export function safeOneAddressCallbackUrl(raw: string): string | null {
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== 'https:') return null;
+    const host = u.hostname.toLowerCase();
+    if (host === 'oneaddress.io' || host.endsWith('.oneaddress.io')) return raw;
+    return null;
+  } catch {
+    return null;
+  }
+}
+`
+    },
+    {
+      name: "src/customer-store.ts",
+      content: `/**
+ * \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+ * \u2551  src/customer-store.ts  \u2014  THE CONTRACT                         \u2551
+ * \u2551                                                                  \u2551
+ * \u2551  Everything OneAddress needs from your systems, in one file you  \u2551
+ * \u2551  can hand to a DBA. \`src/store.ts\` implements it against the     \u2551
+ * \u2551  bundled SQLite file; you replace that with your own.            \u2551
+ * \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+ *
+ * ## Why this is a separate file from the implementation
+ *
+ * Until this existed, replacing the store meant reading \`store.ts\` and
+ * reverse-engineering the three functions \`server.ts\` happened to import, past
+ * a schema, a roster seeder, an encryption layer and a repair pass that exist
+ * for the DEMO and are no use to a company that already has a customer
+ * database. The contract was real but it was implied, and an implied contract
+ * is one you find out you got wrong in production.
+ *
+ * It is also the answer to the question a DBA asks first, which is not "how do
+ * I write an adapter" but "what is this thing going to do to my table". That is
+ * five methods and a paragraph each, and it is reviewable in ten minutes
+ * without reading any of our code.
+ *
+ * ## What you are NOT obliged to keep
+ *
+ * The SQLite file, the at-rest encryption, the blind index, \`customers.json\`,
+ * the repair pass and the address history are the DEFAULT implementation, not
+ * the contract. A company whose customer data already lives in its own database
+ * should delete every one of them: encrypting a copy of a record you already
+ * hold protects nothing and gives you a second thing to key-manage. Implement
+ * the five methods below against your own tables and your own controls.
+ *
+ * ## What the receiver still owns, and must keep owning
+ *
+ * The protocol half: signature verification, the replay window, decryption,
+ * the confirm callback, the quarantine. None of it is in here, and a store
+ * implementation is never given a chance to weaken any of it. By the time your
+ * code is called, the dispatch has been proven to come from OneAddress and has
+ * been decrypted in memory.
+ *
+ * Note that the receiver keeps a small local SQLite file even when your
+ * customers live elsewhere, for the confirm queue and the quarantine. Neither
+ * holds customer data: the confirm queue holds dispatch ids and outcomes, and
+ * the quarantine holds ciphertext the receiver could not open. Your DBA is
+ * entitled to ask, and that is the answer.
+ */
+
+/** An address as OneAddress sends it. Free-form so new fields are not lost. */
+export type Address = Record<string, unknown>;
+
+/**
+ * Who the dispatch is about, as \`server.ts\` recovered it.
+ *
+ * ALL OF THIS CAME OUT OF THE CIPHERTEXT, not off the wire. Under D5 there is
+ * no cleartext customer block on a dispatch, so nothing here can be set by
+ * anyone who has not proven they hold the key this partner registered.
+ */
+export interface Customer {
+  email:          string | null;
+  name:           string;
+  accountNumber?: string;
+  knownNames?:    string[];
+  /**
+   * D5 LOA reference \u2014 the base64url SHA-256 of the signed consent, recomputed
+   * after decrypting \`loa_encrypted\`. Echo it in your own audit trail if you
+   * want proof-of-consent alongside the change. Null on legacy dispatches.
+   */
+  loaRef?:        string | null;
+}
+
+/** One customer as the dashboard shows them. */
+export interface StoredCustomer {
+  account_number: string;
+  name: string;
+  /** The address as a JSON string, the way it was stored. */
+  address: string;
+}
+
+export type AccountVerdict = 'match' | 'no_match' | 'no_account';
+export type VerifyResult = 'match' | 'mismatch' | 'not_found';
+
+export interface CustomerStore {
+  /** Shown on \`/health\` and in the startup line, so a swap is visible. */
+  readonly name: string;
+
+  /**
+   * Are the personal columns YOU hold protected at rest?
+   *
+   * Reported on the dashboard in both states, and the unprotected one is drawn
+   * in red. A store backed by a database with its own encryption should return
+   * \`true\`; one writing plaintext to a file should return \`false\` and mean it.
+   * This is a claim the operator will read as true, so do not return \`true\`
+   * because it feels tidier.
+   */
+  readonly encrypted: boolean;
+
+  /**
+   * Pre-payment account check (\`account.verify\`). BEFORE the consumer pays.
+   *
+   * The boundary that stops somebody pushing an update to an account that is
+   * not theirs, and the only one of these three that runs before money moves.
+   *
+   *   'match'      \u2014 the account exists and the name agrees
+   *   'no_match'   \u2014 the account exists and the name does not
+   *   'no_account' \u2014 no such account
+   *
+   * \`knownNames\` carries the other names the consumer has verified under, so a
+   * married name on your record and a maiden name on their ID still match. Test
+   * each of them, not just \`name\`.
+   *
+   * RETURN 'no_match' RATHER THAN 'match' WHEN YOU ARE UNSURE. A false 'match'
+   * authorises a stranger's address onto a customer's account; a false
+   * 'no_match' costs a support call.
+   */
+  verifyAccount(
+    accountNumber: string | null,
+    name: string,
+    knownNames?: string[],
+  ): Promise<AccountVerdict> | AccountVerdict;
+
+  /**
+   * Is the address you hold the current one? (\`address.verify\`)
+   *
+   *   'match'     \u2014 you already hold exactly this address
+   *   'mismatch'  \u2014 you know the customer and hold something different
+   *   'not_found' \u2014 the account is not one of yours
+   *
+   * A customer you have never had an update for is 'mismatch', not 'match':
+   * you know them, you simply do not have THIS address yet.
+   *
+   * READ-ONLY. Nothing here may write.
+   */
+  verifyAddress(customer: Customer, incoming: Address): Promise<VerifyResult>;
+
+  /**
+   * Apply a new address (\`address.updated\`), and return the one it REPLACED.
+   *
+   * The return value is what the dashboard shows as "was", and it is the
+   * question an operator asks first when a change looks wrong. Read it before
+   * you write, because after the write nothing can reconstruct it. Return \`{}\`
+   * if there was nothing.
+   *
+   * ## Called only once the caller is satisfied
+   *
+   * When you declare that you verify account references, \`server.ts\` refuses
+   * anything that is not a 'match' before reaching here, so by this point the
+   * account is a real one of yours. **If you do NOT verify account references,
+   * that guard is not running and this is called with whatever identity the
+   * envelope carried.** Key on something you trust in that mode; the default
+   * implementation keys on the name, and two customers who share a name share a
+   * row.
+   *
+   * ## Throwing is meaningful
+   *
+   * Throw and the dispatch is answered as failed, and OneAddress retries it.
+   * That is the right thing to do if your database is unreachable. Do NOT
+   * swallow a write failure and return normally: the consumer is then told the
+   * address landed when it did not.
+   */
+  saveAddress(customer: Customer, incoming: Address): Promise<Address>;
+
+  /**
+   * One customer, for the dashboard's change panel. \`null\` if unknown.
+   *
+   * SEPARATE FROM THE THREE HOOKS because it is cosmetic: returning \`null\`
+   * always is a perfectly good implementation and costs you a panel, nothing
+   * more. It exists as a method rather than being derived from a list-everyone
+   * call BECAUSE of what that would mean at your scale - see \`count\` below.
+   */
+  find(accountNumber: string): Promise<StoredCustomer | null> | StoredCustomer | null;
+
+  /**
+   * How many customers are on file, or \`null\` for "not worth asking".
+   *
+   * **RETURN \`null\` IF THIS IS A COUNT OVER A REAL CUSTOMER TABLE.** The
+   * dashboard redraws every two seconds; a \`SELECT count(*)\` over four million
+   * rows, forty times a minute, forever, is a load-bearing decision somebody
+   * should make deliberately rather than inherit from a demo. The dashboard
+   * draws a dash and is otherwise identical.
+   *
+   * The bundled SQLite store answers it because its roster is three rows.
+   */
+  count(): Promise<number | null> | number | null;
+}
+`
+    },
+    {
+      name: "src/store.ts",
+      content: `/**
+ * \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+ * \u2551  src/store.ts  \u2014  DATABASE INTEGRATION                          \u2551
+ * \u2551                                                                  \u2551
+ * \u2551  THE DEFAULT implementation of \`CustomerStore\`, backed by the     \u2551
+ * \u2551  bundled SQLite file: a CUSTOMER ROSTER (who your customers are   \u2551
+ * \u2551  + the address you hold on file for each) and the three hooks     \u2551
+ * \u2551  OneAddress calls:                                                \u2551
+ * \u2551    verifyAccount  \u2014 pre-payment account check  (account.verify)  \u2551
+ * \u2551    verifyAddress  \u2014 is your on-file address current? (address.verify)
+ * \u2551    saveAddress    \u2014 apply a new address        (address.updated)  \u2551
+ * \u2551                                                                  \u2551
+ * \u2551  THE CONTRACT IS \`src/customer-store.ts\`, not this file. Read     \u2551
+ * \u2551  that one first: it is five methods and a paragraph each, with    \u2551
+ * \u2551  no schema, no seeding and no encryption in the way, and it is    \u2551
+ * \u2551  what you implement against your own database.                    \u2551
+ * \u2551                                                                  \u2551
+ * \u2551  Everything below the contract \u2014 the SQLite file, the at-rest     \u2551
+ * \u2551  encryption, the blind index, customers.json, the repair pass,    \u2551
+ * \u2551  the history table \u2014 is THIS implementation, not the contract.    \u2551
+ * \u2551  A company whose customers already live in its own database       \u2551
+ * \u2551  should delete all of it rather than port it.                     \u2551
+ * \u2551                                                                  \u2551
+ * \u2551  server.ts calls the hooks after verifying and decrypting each    \u2551
+ * \u2551  event \u2014 the protocol layer is handled for you, never touch it.  \u2551
+ * \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { report } from './report.js';
+import db, { accountKey, dec, enc, encrypted, ensureColumn, isEncrypted, once } from './db.js';
+import type {
+  AccountVerdict,
+  Address,
+  Customer,
+  CustomerStore,
+  StoredCustomer,
+  VerifyResult,
+} from './customer-store.js';
+
+// Re-exported so existing imports of these types from \`./store.js\` keep
+// working. They are DEFINED in the contract, which is the file to change.
+export type { AccountVerdict, Address, Customer, CustomerStore, StoredCustomer, VerifyResult };
+
+// \u2500\u2500 Schema \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// \`customers\` is your roster: the account number, the customer's name, and the
+// address YOU currently hold on file for them. \`address_history\` logs every
+// change you apply, so you have an audit trail.
+db.exec(\`
+  CREATE TABLE IF NOT EXISTS customers (
+    -- How a row is FOUND. A blind index of the account number when the database
+    -- is locked, the lower-cased number when it is not. It is the key rather
+    -- than the number itself because AES-GCM uses a fresh IV per write, so two
+    -- encryptions of one account number differ and a primary key over the
+    -- ciphertext would enforce nothing while looking like it did.
+    account_key    TEXT PRIMARY KEY,
+    -- What is DISPLAYED. Ciphertext when locked.
+    account_number TEXT NOT NULL,
+    name           TEXT NOT NULL,
+    address        TEXT NOT NULL DEFAULT '{}',
+    updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS address_history (
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    account_key    TEXT NOT NULL,
+    -- Both sides of the change, so you can show what an address REPLACED
+    -- rather than only what it became.
+    prev_address   TEXT NOT NULL DEFAULT '{}',
+    address        TEXT NOT NULL,
+    recorded_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_history_account ON address_history(account_key, id DESC);
+\`);
+
+// Self-migrate. An older data.db may already hold a \`customers\` table WITHOUT the
+// newer columns, and \`CREATE TABLE IF NOT EXISTS\` never alters an existing table.
+// Add any missing columns here so the handler upgrades its own schema instead of
+// forcing you to delete the database on every change \u2014 the behaviour a
+// production integration needs.
 ensureColumn('customers', 'address', "TEXT NOT NULL DEFAULT '{}'");
 ensureColumn('customers', 'updated_at', 'TEXT'); // nullable on migrate; set on write
 ensureColumn('customers', 'account_key', 'TEXT');
@@ -2435,22 +4293,6 @@ const ROSTER = loadRoster();
   report.info(\`[store] roster ready (\${ROSTER.length} customers)\`);
 }
 
-// \u2500\u2500 Identity handed in by server.ts after it verifies + decrypts \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-export type Customer = {
-  email:          string | null;
-  name:           string;
-  accountNumber?: string;
-  knownNames?:    string[];
-  /**
-   * D5 LOA reference \u2014 the base64url SHA-256 of the signed consent, recomputed
-   * by server.ts after decrypting \`loa_encrypted\`. A production integration
-   * echoes this in the \`/api/confirm\` callback so OneAddress can verify
-   * proof-of-receipt. Null on legacy dispatches that carry no encrypted LOA.
-   * The store ignores it; it rides along on the identity object for convenience.
-   */
-  loaRef?:        string | null;
-};
-
 /**
  * Canonical, order- and case-insensitive form of an address, so two addresses
  * compare equal iff they mean the same thing regardless of key order or casing.
@@ -2485,13 +4327,6 @@ function findCustomer(accountNumber: string | undefined, name: string): { accoun
 }
 
 // \u2500\u2500 account.verify: pre-payment account check \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-/** One stored row, with the personal columns decrypted. */
-export interface StoredCustomer {
-  account_number: string;
-  name: string;
-  address: string;
-}
-
 /** Decrypt a row read straight out of SQLite. */
 function decodeRow(raw: unknown): StoredCustomer | undefined {
   if (!raw) return undefined;
@@ -2518,8 +4353,6 @@ export function customerCount(): number {
 /** Is the file on disk protected? Surfaced in the dashboard, in both states. */
 export const storeEncrypted = encrypted;
 
-export type AccountVerdict = 'match' | 'no_match' | 'no_account';
-
 /**
  * Confirms the typed account number is really one of yours and the name agrees,
  * BEFORE the consumer pays. The boundary that stops someone pushing an update to
@@ -2542,8 +4375,6 @@ export function verifyAccount(accountNumber: string | null, name: string, knownN
 }
 
 // \u2500\u2500 address.verify: is your on-file address current? \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-export type VerifyResult = 'match' | 'mismatch' | 'not_found';
-
 /**
  * Compares the consumer's current OneAddress address against what YOU hold.
  *   'match'     \u2014 you already hold this exact address (no update needed)
@@ -2622,6 +4453,47 @@ export async function saveAddress(customer: Customer, incoming: Address): Promis
 
   return previous;
 }
+
+/**
+ * One customer by account number, for the dashboard.
+ *
+ * AN INDEXED LOOKUP, not a scan. The dashboard used to call \`allCustomers()\`
+ * and \`.find()\` the one it wanted, which is invisible at three rows and absurd
+ * at four million: decrypting an entire customer table to draw one panel. Doing
+ * it here also means a real store implements a lookup, which is what its own
+ * database is already good at, instead of being handed a list-everything
+ * method it has no safe way to answer.
+ */
+export function findByAccount(accountNumber: string): StoredCustomer | null {
+  const acct = (accountNumber ?? '').trim();
+  if (!acct) return null;
+  return decodeRow(
+    db.prepare('SELECT account_number, name, address FROM customers WHERE account_key = ?')
+      .get(accountKey(acct)),
+  ) ?? null;
+}
+
+/**
+ * THE OBJECT THE RECEIVER ACTUALLY TALKS TO.
+ *
+ * \`server.ts\` and \`tui.ts\` import this and nothing else from here, so pointing
+ * the receiver at your own systems is one import: write a module exporting a
+ * \`CustomerStore\` and change the two lines that name this one. The \`satisfies\`
+ * is the part that makes that safe \u2014 miss a method, or change a signature the
+ * receiver depends on, and this file stops compiling rather than failing on a
+ * live dispatch.
+ */
+export const store = {
+  name: 'sqlite',
+  encrypted: storeEncrypted,
+  verifyAccount,
+  verifyAddress,
+  saveAddress,
+  find: findByAccount,
+  // Three rows, so a count is free. A store over a real customer table should
+  // return null here; the contract file says why.
+  count: customerCount,
+} satisfies CustomerStore;
 `
     },
     {
@@ -2661,10 +4533,44 @@ import {
   type SessionKeyShare,
   type OneAddressD5LOA,
 } from '@oneaddress/partner-sdk';
-import { saveAddress, verifyAddress, verifyAccount } from './store.js';
+// THE ONLY LINE THAT NAMES AN IMPLEMENTATION. Point this at your own module
+// exporting a \`CustomerStore\` (see src/customer-store.ts) and nothing else in
+// the protocol layer changes.
+import { store as writeThroughStore } from './store.js';
+import { connectorStore, setCurrentRawBody } from './connector-store.js';
 import { notePreviousAddress } from './tui.js';
 import { config } from './config.js';
 import { safeOneAddressCallbackUrl } from './callback-url.js';
+import { configuredKeyIds, describeKeys, keyFailureAdvice, resolvePrivateKey } from './keys.js';
+import {
+  drainConfirms,
+  enqueueConfirm,
+  pendingConfirmCount,
+  purgeDelivered,
+  type ConfirmStatus,
+} from './confirm-queue.js';
+import {
+  dispatchKey,
+  heldCount,
+  purgeQuarantine,
+  quarantine,
+  replayHeld,
+  type QuarantineReason,
+} from './quarantine.js';
+import { recordOutcome, tally } from './tally.js';
+import { accept as acceptIntoInbox, oldestUndrawn, undrawnCount } from './inbox.js';
+import { setAcknowledgementHandler, startDrawApi } from './draw-api.js';
+
+/**
+ * WHICH STORE ANSWERS, chosen once at startup.
+ *
+ * Inbox mode does not branch the handler. It swaps the implementation of the
+ * contract in \`customer-store.ts\`, so every call site below is identical in
+ * both modes and the mode lives in exactly one place. \`connectorStore\` asks the
+ * partner's connector and refuses to write; \`writeThroughStore\` is the bundled
+ * SQLite one this receiver has always used.
+ */
+const store = config.mode === 'inbox' ? connectorStore : writeThroughStore;
 
 const WEBHOOK_SECRET      = process.env.WEBHOOK_SECRET          ?? '';
 const PARTNER_PRIVATE_KEY = process.env.PARTNER_PRIVATE_KEY_PEM ?? '';
@@ -2684,11 +4590,38 @@ const PORT                = Number(process.env.PORT ?? 3001);
 const ONEADDRESS_API = config.oneAddressApi;
 const CONFIRM_SECRET = process.env.CONFIRM_SECRET || WEBHOOK_SECRET;
 
-if (!WEBHOOK_SECRET || !PARTNER_PRIVATE_KEY || !PARTNER_ID) {
+if (!WEBHOOK_SECRET || !PARTNER_ID) {
   report.error('[startup] Missing required env vars. Check your .env file.');
   process.exit(1);
 }
 
+// THE KEY REQUIREMENT INVERTS WITH THE MODE, and this is the assertion that
+// makes inbox mode mean something.
+//
+// Write-through cannot open a single dispatch without a private key, so a
+// missing one is fatal and always was. Inbox mode's entire property is that the
+// component reachable from the internet CANNOT read what it holds, and a key
+// sitting in this process's environment makes that false \u2014 silently, while
+// every test still passes and every dispatch still lands. Nothing would ever
+// surface it, because in inbox mode nothing here attempts a decrypt to fail.
+//
+// So it refuses to start and names the fix. A partner moving from write-through
+// to inbox has one edit to make, and being told about it once beats believing a
+// property they do not have.
+if (config.mode === 'inbox') {
+  const strayKeys = configuredKeyIds();
+  if (PARTNER_PRIVATE_KEY || strayKeys.length > 0) {
+    report.error('[startup] mode is \`inbox\`, but this receiver has a private key in its environment.');
+    report.error('[startup] Inbox mode exists so the internet-facing process CANNOT read what it stores.');
+    report.error('[startup] Move PARTNER_PRIVATE_KEY_PEM' + (strayKeys.length > 0 ? ' (and the per-key-id variables)' : '') + ' to the connector\\'s .env and remove it here.');
+    process.exit(1);
+  }
+} else if (!PARTNER_PRIVATE_KEY) {
+  report.error('[startup] PARTNER_PRIVATE_KEY_PEM is missing. Check your .env file.');
+  report.error('[startup] (A receiver that should hold no key at all wants RECEIVER_MODE=inbox.)');
+  process.exit(1);
+}
+
 // Startup self-check. Two faults were historically INVISIBLE until a live
 // dispatch, and both read afterwards as "partner key mismatch" deep inside a
 // try/catch, which is a day of reading webhook logs. Assert them here so the
@@ -2714,6 +4647,41 @@ if (PARTNER_PRIVATE_KEY.includes('BEGIN')) {
   }
 }
 
+// SAID OUT LOUD ON EVERY BOOT, because the commonest key problem is believing a
+// variable is set when it is not, and the second commonest is still holding one
+// key after a rotation. Both are visible in this one line, and neither is
+// visible anywhere else until a dispatch fails.
+// In inbox mode "no key" is the CORRECT state, and \`describeKeys\` would report
+// it as "every dispatch will fail to decrypt", which is true of a write-through
+// receiver and alarming nonsense here. An operator who reads a red line every
+// boot stops reading the line.
+report.info(
+  config.mode === 'inbox'
+    ? '[startup] keys: none, by design \u2014 the connector holds them and this process cannot read a dispatch'
+    : \`[startup] keys: \${describeKeys()}\`,
+);
+// WHICH STORE IS LIVE, said out loud at every boot. A receiver pointed at a
+// partner's own database and one still writing to the bundled demo file behave
+// identically until the first dispatch, and the difference is where a customer's
+// address ends up. Naming it costs a line and removes the question.
+//
+// AND WHETHER IT IS PROTECTED, IN BOTH DIRECTIONS. The dashboard has always
+// drawn UNENCRYPTED in red, and a receiver running as a service has no
+// dashboard: stdin is not a terminal, so nobody is asked for a passphrase,
+// nobody answers, and it runs in the clear having said nothing. That is the
+// deployment most likely to hold real customers and the one least likely to
+// have a person looking at it. Encryption stays OPT-IN - requiring it would
+// lock out every install that has never set a passphrase - but choosing it by
+// not being asked is not a choice, so the absence is stated as loudly as the
+// presence.
+report.info(
+  store.encrypted
+    ? \`[startup] store: \${store.name} (encrypted at rest)\`
+    : \`[startup] store: \${store.name} \u2014 NOT ENCRYPTED AT REST. \` +
+      'Customer records are readable by anyone who can read the file. ' +
+      'Set ONEADDRESS_DB_PASSPHRASE, or run \`npm start\` in a terminal to be asked.',
+);
+
 // In-memory dedup cache. Records a dispatch id only once it has been fully
 // HANDLED, so a dispatch that failed to decrypt is NOT remembered and a later
 // retry re-runs it rather than being dismissed as a duplicate. Bounded so a
@@ -2735,9 +4703,10 @@ function rememberDispatch(id: string): void {
 
 /**
  * Close the loop: tell OneAddress you have applied an update, so the consumer's
- * dashboard flips the service to "Confirmed". Fire-and-forget so it never delays
- * the webhook 200 (a slow confirm must not make OneAddress time the DISPATCH out
- * and mark it failed). Logs its own outcome.
+ * dashboard flips the service to "Confirmed". Called ONLY by the confirm
+ * queue's drain, never from the webhook handler: a slow confirm must not delay
+ * the webhook 200 (OneAddress would time the DISPATCH out and mark it failed),
+ * and a failed one has to be retried rather than logged and lost.
  *
  * Auth for /api/confirm (all three required):
  *   Authorization: Bearer <secret>
@@ -2745,13 +4714,11 @@ function rememberDispatch(id: string): void {
  *   X-OneAddress-Signature: HMAC-SHA256(secret, \`\${timestamp}.\${rawBody}\`)
  * The same secret signs the Bearer and the body.
  */
-async function confirmToOneAddress(dispatch: string, status: 'confirmed' | 'failed'): Promise<void> {
-  // Only real dispatches carry a numeric id in X-OneAddress-Dispatch. Probes
-  // (e.g. the go-live "address.test") carry a non-numeric id and have nothing to
-  // confirm, so skip them.
-  const dispatchId = Number(dispatch);
-  if (!Number.isInteger(dispatchId) || dispatchId <= 0) return;
-
+async function confirmToOneAddress(dispatchId: number, status: ConfirmStatus): Promise<void> {
+  // No probe check here any more. queueConfirm is the only door into the queue
+  // and it drops non-numeric dispatch ids, so by the time a row is drained it
+  // is a real dispatch. Keeping a second copy of that rule would mean a probe
+  // could be queued forever and silently skipped on every drain.
   const bodyStr = JSON.stringify({
     dispatch_id: dispatchId,
     partner_id:  PARTNER_ID,
@@ -2761,7 +4728,7 @@ async function confirmToOneAddress(dispatch: string, status: 'confirmed' | 'fail
   const ts  = String(Math.floor(Date.now() / 1000));
   const sig = createHmac('sha256', CONFIRM_SECRET).update(\`\${ts}.\${bodyStr}\`).digest('hex');
 
-  try {
+  {
     const confirmRes = await fetch(\`\${ONEADDRESS_API}/api/confirm\`, {
       method:  'POST',
       headers: {
@@ -2774,18 +4741,31 @@ async function confirmToOneAddress(dispatch: string, status: 'confirmed' | 'fail
     });
     if (confirmRes.ok) {
       report.info(\`[confirm] dispatch \${dispatchId} \u2192 \${status}: acknowledged by OneAddress\`);
-    } else {
-      const detail = await confirmRes.text().catch(() => '');
-      report.error(\`[confirm] dispatch \${dispatchId} confirm FAILED \u2014 HTTP \${confirmRes.status} \${detail}\`);
-      if (confirmRes.status === 401) {
-        report.error('[confirm] 401 means the wrong secret. If your partner has a separate confirm secret, set CONFIRM_SECRET in .env to it (from the portal Webhook screen); otherwise your webhook signing secret should work.');
-      }
+      return;
     }
-  } catch (err) {
-    report.error('[confirm] confirm request error:', err);
+    const detail = (await confirmRes.text().catch(() => '')).slice(0, 200);
+    if (confirmRes.status === 401) {
+      report.error('[confirm] 401 means the wrong secret. If your partner has a separate confirm secret, set CONFIRM_SECRET in .env to it (from the portal Webhook screen); otherwise your webhook signing secret should work. The confirm stays queued, so fixing .env and restarting will deliver it.');
+    }
+    // THROWN, NOT LOGGED AND SWALLOWED. The queue is what decides to retry, and
+    // it can only do that if failure reaches it. Returning quietly here is the
+    // original bug: applied locally, never acknowledged, refunded upstream.
+    throw new Error(\`HTTP \${confirmRes.status} \${detail}\`);
   }
 }
 
+/**
+ * Hand a confirm to the queue.
+ *
+ * Probes (the go-live \`address.test\`) carry a non-numeric dispatch id and have
+ * nothing to confirm, so they are dropped here rather than queued forever.
+ */
+function queueConfirm(dispatch: string, status: ConfirmStatus): void {
+  const dispatchId = Number(dispatch);
+  if (!Number.isInteger(dispatchId) || dispatchId <= 0) return;
+  enqueueConfirm(dispatchId, status);
+}
+
 const app = express();
 app.disable('x-powered-by'); // don't fingerprint the framework
 
@@ -2856,6 +4836,21 @@ app.post('/webhook', async (req: Request, res: Response) => {
 
   const event = body.event as string;
 
+  // PARKED FOR THE CONNECTOR STORE, and read in the same tick it is set.
+  // In inbox mode the receiver holds no private key, so the only thing it can
+  // hand the connector for a verify is the ciphertext that arrived. The
+  // CustomerStore contract passes a decoded customer, which this process cannot
+  // produce, so the bytes travel out of band rather than widening the contract
+  // for one implementation. See connector-store.ts for why this is safe and
+  // what would make it unsafe.
+  //
+  // ABOVE EVERY HANDLER THAT READS IT, and that position is the fix rather than
+  // a tidy-up: this sat below \`account.verify\`, which returns long before it, so
+  // in inbox mode the connector was handed the PREVIOUS request's ciphertext, or
+  // an empty string on the first request of the process's life. It would have
+  // answered honestly about the wrong consumer.
+  setCurrentRawBody(rawBody);
+
   // \u2500\u2500 account.verify: pre-payment account check \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   // Carries an encrypted CUSTOMER block { name, known_names, account_number } \u2014
   // no address, no session envelope \u2014 so it is handled HERE, above the address-
@@ -2870,6 +4865,20 @@ app.post('/webhook', async (req: Request, res: Response) => {
       return res.status(200).json({ ok: true, skipped: true });
     }
 
+    // \u2500\u2500 INBOX MODE: the receiver cannot open this, and must not try \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    //
+    // The decrypt below is the reason this branch exists. In inbox mode there
+    // is no private key in this process, so \`decryptAddress\` would fail and
+    // answer 422 \u2014 and the consumer, who is mid-payment, would be told the
+    // account check failed when nothing is wrong. The connector holds the key
+    // and the customer records, so it answers. \`connectorStore\` sends the raw
+    // body; the arguments below are the contract's shape, not its source.
+    if (config.mode === 'inbox') {
+      const status = await store.verifyAccount(null, '', []);
+      report.info(\`[webhook] account.verify \u2192 \${status} (answered by the connector)\`);
+      return res.status(200).json({ status });
+    }
+
     const enc = body.customer_encrypted as {
       ephemeralPublicKey: string; iv: string; ciphertext: string; hkdfSalt?: string;
     } | undefined;
@@ -2887,7 +4896,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
     const name          = typeof cust.name === 'string' ? cust.name : '';
     const knownNames    = Array.isArray(cust.known_names) ? cust.known_names.map(String) : [];
 
-    const status = verifyAccount(accountNumber, name, knownNames);
+    const status = await store.verifyAccount(accountNumber, name, knownNames);
     report.info(\`[webhook] account.verify \u2192 \${status} for account \${accountNumber ?? '(none)'} (\${name})\`);
     return res.status(200).json({ status });
   }
@@ -2898,6 +4907,128 @@ app.post('/webhook', async (req: Request, res: Response) => {
   // Acknowledge it here; only the real dispatch events below require decryption.
   // A real address.updated that arrives WITHOUT a payload still falls through to
   // the 422 below, because it IS a dispatch event.
+  /**
+   * Keep this dispatch so it can be applied once the cause is fixed.
+   *
+   * A closure rather than four calls passing the same three values, because the
+   * value that must not be got wrong is \`rawBody\`: quarantine holds the bytes
+   * AS THEY ARRIVED and never a re-serialised \`body\`. \`JSON.stringify(body)\` is
+   * a different string with the same meaning, and replaying it would fail the
+   * signature check it is about to be re-signed under, for a reason nobody
+   * would find.
+   *
+   * Everything that calls this sits BELOW the HMAC check above. That is what
+   * stops the quarantine being a way for anyone who can reach this port to fill
+   * a partner's disk.
+   */
+  /**
+   * What this dispatch IS, for anything that has to recognise it again.
+   *
+   * The same value the quarantine keys on, so a re-delivery - a OneAddress
+   * retry of a 422, a press of [r], the same body posted twice - lands on the
+   * record that is already there instead of looking like a new arrival.
+   */
+  const key = dispatchKey(dispatch || null, rawBody);
+
+  const hold = (reason: QuarantineReason, keyId: string | null, detail: string): void => {
+    quarantine({ dispatchId: dispatch || null, event, reason, keyId, rawBody, detail });
+    recordOutcome(key, 'failed');
+  };
+
+  /**
+   * Post an \`address.verify\` verdict back to OneAddress.
+   *
+   * ONE IMPLEMENTATION, TWO CALLERS, and the second one is why it is a function.
+   * Write-through decrypts the envelope and asks its own store; inbox mode
+   * cannot decrypt anything and asks the connector. Everything from the verdict
+   * onward is identical, including the callback-host check, and a second copy of
+   * that check is a second place for it to be dropped.
+   *
+   * Returns a Response when it REFUSED to post and has already answered the
+   * caller, and null when the verdict went out. Deliberately does NOT remember
+   * the dispatch: the two callers differ on that, and burying the difference in
+   * here is how one of them would get it silently wrong.
+   */
+  const postVerifyVerdict = async (result: string): Promise<Response | null> => {
+    const callbackUrl   = body.callback_url   as string;
+    const callbackToken = body.callback_token as string;
+    const batchId       = body.batch_id       as string;
+
+    // Callback URL is signed inside the body, so HMAC verify already proves it
+    // came from OneAddress. We still validate the host as defence in depth:
+    // if the webhook secret ever leaks, an attacker who can forge a webhook
+    // could otherwise coerce this server into POSTing to any internal
+    // URL (database admin, cloud metadata service, \u2026) \u2014 turning the partner's
+    // network position into an SSRF primitive.
+    const safeCallbackUrl = safeOneAddressCallbackUrl(callbackUrl);
+    if (!safeCallbackUrl) {
+      report.warn(\`[webhook] refusing callback to non-OneAddress host: \${callbackUrl}\`);
+      return res.status(400).json({ error: 'Invalid callback_url host' });
+    }
+
+    await fetch(safeCallbackUrl, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        // 2026.2 \u2014 no member_name echo; OneAddress keys the result on
+        // (batch_id, partner_id) and validates the opaque token alone.
+        batch_id:    batchId,
+        partner_id:  PARTNER_ID,
+        result,
+        token:       callbackToken,
+      }),
+    });
+    return null;
+  };
+
+  // \u2500\u2500 INBOX MODE: hold it, do not open it \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  //
+  // An \`address.updated\` is stored exactly as it arrived and the connector is
+  // left to collect it. The 200 below is honest and is not a claim that anything
+  // was applied: the protocol already separates the two, and the CONFIRM is what
+  // reports application. It fires when the connector says so, which may be
+  // hours later, and \`user_services.state\` has carried \`awaiting_confirm\` for
+  // that gap since long before this mode existed.
+  //
+  // The verify events deliberately fall through to the code below, because they
+  // must be answered NOW, before a consumer pays. In inbox mode that answer
+  // comes from the connector.
+  // \u2500\u2500 INBOX MODE, the other half: a verify the receiver cannot open \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  //
+  // \`address.verify\` has to be answered now, like \`account.verify\` above, but it
+  // is answered by POSTing a callback rather than in the response body. The
+  // callback URL and token travel in the CLEARTEXT body, not the envelope, so
+  // this process can still post it; only the VERDICT needs a key, and that comes
+  // from the connector.
+  if (config.mode === 'inbox' && event === 'address.verify') {
+    // The contract's arguments, not its source: \`connectorStore\` sends the raw
+    // body it was parked with and ignores these.
+    const result = await store.verifyAddress({ email: null, name: '' }, {});
+    report.info(\`[webhook] address.verify \u2192 \${result} (answered by the connector)\`);
+    const refused = await postVerifyVerdict(result);
+    if (refused) return refused;
+    // DELIBERATELY NOT \`rememberDispatch\`, for the same reason as the inbox
+    // \`address.updated\` branch below: nothing was decrypted here, so there is
+    // no state a retry would duplicate. OneAddress keys a verify result on
+    // (batch_id, partner_id), so re-answering a retried check is a no-op \u2014 and
+    // NOT remembering is the safer half of the trade, because a check we failed
+    // to answer still gets answered on the retry instead of being dismissed.
+    return res.status(200).json({ ok: true });
+  }
+
+  if (config.mode === 'inbox' && event === 'address.updated') {
+    acceptIntoInbox({ key, dispatchId: dispatch || null, event, rawBody });
+    report.info(\`[inbox] held \${dispatch || key} for the connector\`);
+    // DELIBERATELY NOT \`rememberDispatch\`. A guard in templates.test.ts asserts
+    // that nothing is remembered before the decrypt is attempted, because a
+    // dispatch marked seen too early makes OneAddress's retry look like a
+    // duplicate and loses the update. Adding an exception here for a branch
+    // that happens not to decrypt would weaken the guard for the branch that
+    // does. It is not needed anyway: \`accept\` is INSERT OR IGNORE on the same
+    // dispatch identity, so a redelivery is already harmless.
+    return res.status(200).json({ ok: true, queued: true });
+  }
+
   const DISPATCH_EVENTS = ['address.updated', 'address.verify', 'address.test', 'address.test-dispatch'];
   if (!DISPATCH_EVENTS.includes(event)) {
     report.info(\`[webhook] "\${event}" acknowledged (no address payload to decrypt)\`);
@@ -2931,28 +5062,53 @@ app.post('/webhook', async (req: Request, res: Response) => {
 
   if (sessionEnvelope && sessionKeyShare) {
     // D5 \u2014 call decryptSession. Wrong key_id / wrong partner_id / tampered
-    // ciphertext all surface as an AES-GCM authentication-tag error.
+    // ciphertext all surface as an AES-GCM authentication-tag error, which is
+    // why the key is chosen BY key_id here rather than assumed: the failure
+    // cannot tell you which of those three it was, so the message has to.
+    const keyId    = sessionKeyShare.key_id ?? null;
+    const resolved = resolvePrivateKey(keyId);
+    if (!resolved) {
+      report.error(\`[webhook] no private key for key_id \${keyId ?? '(none)'} \u2014 \${keyFailureAdvice(keyId, null)}\`);
+      hold('no_key', keyId, keyFailureAdvice(keyId, null));
+      return res.status(422).json({ ok: false, error: 'no private key for this key_id' });
+    }
     try {
-      const data = await decryptSession(sessionKeyShare, sessionEnvelope, PARTNER_PRIVATE_KEY, PARTNER_ID);
+      const data = await decryptSession(sessionKeyShare, sessionEnvelope, resolved.pem, PARTNER_ID);
       address       = data.new_address as unknown as Record<string, unknown>;
       decName       = typeof data.verified_name === 'string' ? data.verified_name : '';
       decAccount    = typeof data.account_number === 'string' ? data.account_number : '';
       decKnownNames = Array.isArray(data.known_names) ? data.known_names : [];
     } catch (err) {
-      report.error('[webhook] D5 decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM matches key_id', sessionKeyShare.key_id, ':', err);
+      // Names WHICH key answered. A rotation used to surface here as an
+      // authentication-tag error indistinguishable from corruption, with the
+      // single-key fallback having silently answered for a key id it never held.
+      report.error(\`[webhook] D5 decryption failed for key_id \${keyId ?? '(none)'}: \${keyFailureAdvice(keyId, resolved)}\`);
+      report.error('[webhook] underlying error:', err);
+      hold('decrypt_failed', keyId, keyFailureAdvice(keyId, resolved));
       return res.status(422).json({ ok: false, error: 'D5 decryption failed \u2014 partner key mismatch' });
     }
   } else if (legacyPayload) {
+    // Pre-D5 dispatches name no key id, so only the fallback can apply.
+    const resolved = resolvePrivateKey(null);
+    if (!resolved) {
+      report.error(\`[webhook] no private key for a legacy dispatch \u2014 \${keyFailureAdvice(null, null)}\`);
+      hold('no_key', null, keyFailureAdvice(null, null));
+      return res.status(422).json({ ok: false, error: 'no private key configured' });
+    }
     try {
-      address       = await decryptAddress(legacyPayload, PARTNER_PRIVATE_KEY, PARTNER_ID);
+      address       = await decryptAddress(legacyPayload, resolved.pem, PARTNER_ID);
       decName       = typeof address.fullName === 'string' ? address.fullName : '';
       decAccount    = typeof address.accountReference === 'string' ? address.accountReference : '';
       decKnownNames = Array.isArray(address.knownNames) ? address.knownNames as string[] : [];
     } catch (err) {
       report.error('[webhook] Decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM in .env:', err);
+      hold('decrypt_failed', null, keyFailureAdvice(null, resolved));
       return res.status(422).json({ ok: false, error: 'Decryption failed \u2014 partner key mismatch' });
     }
   } else {
+    // No \`hold\` here: there is no payload to hold, so there is nothing a fix
+    // could later apply. It still counts as a dispatch that did not land.
+    recordOutcome(key, 'failed');
     return res.status(422).json({ ok: false, error: 'No encrypted payload on dispatch' });
   }
 
@@ -2967,11 +5123,23 @@ app.post('/webhook', async (req: Request, res: Response) => {
   const loaEncrypted = body.loa_encrypted as
     { session_envelope: string; session_key_share: SessionKeyShare } | null | undefined;
   if (loaEncrypted && typeof loaEncrypted === 'object') {
-    try {
-      const loa: OneAddressD5LOA = await decryptLoaEncrypted(loaEncrypted, PARTNER_PRIVATE_KEY, PARTNER_ID);
-      loaRef = d5LoaRef(loa);
-    } catch (err) {
-      report.error('[webhook] LOA decryption failed:', err instanceof Error ? err.message : err);
+    // RESOLVED BY THE LOA'S OWN key_id, not by the single PARTNER_PRIVATE_KEY_PEM.
+    // It is wrapped to the same key id as the address envelope, but it carries
+    // its own share, so that is what is read. Using the single key meant that
+    // after a rotation with PARTNER_KEYS_STRICT=1 the address opened and the LOA
+    // silently did not, losing the proof-of-consent on exactly the changes a
+    // partner most wants it for, with nothing anyone would see.
+    const loaKeyId = loaEncrypted.session_key_share?.key_id ?? null;
+    const loaKey   = resolvePrivateKey(loaKeyId);
+    if (!loaKey) {
+      report.warn(\`[webhook] no key for the LOA's key_id \${loaKeyId ?? '(none)'} \u2014 applying without a consent reference\`);
+    } else {
+      try {
+        const loa: OneAddressD5LOA = await decryptLoaEncrypted(loaEncrypted, loaKey.pem, PARTNER_ID);
+        loaRef = d5LoaRef(loa);
+      } catch (err) {
+        report.error('[webhook] LOA decryption failed:', err instanceof Error ? err.message : err);
+      }
     }
   }
 
@@ -3017,10 +5185,13 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // OneAddress conformance check "Refuses an account reference that matches
     // no record" tests exactly this.
     if (config.verifiesAccountReference) {
-      const verdict = verifyAccount(ctx.accountNumber, ctx.name ?? '', ctx.knownNames ?? []);
+      const verdict = await store.verifyAccount(ctx.accountNumber, ctx.name ?? '', ctx.knownNames ?? []);
       if (verdict !== 'match') {
         report.warn(\`[webhook] address.updated REFUSED (\${verdict}) for account \${ctx.accountNumber ?? '(none)'} \u2014 nothing applied\`);
-        void confirmToOneAddress(dispatch, 'failed');
+        queueConfirm(dispatch, 'failed');
+        // A refusal is not a fault and is never held, but it IS a dispatch that
+        // did not land, so it counts. See quarantine.ts for why the two differ.
+        recordOutcome(key, 'failed');
         return res.status(200).json({ ok: false, error: 'account_not_matched', verdict });
       }
     }
@@ -3029,49 +5200,25 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // it can show both halves; a no-op under --headless. Passed directly rather
     // than reported, because the previous address is a customer's address and
     // must never reach a log line.
-    const replaced = await saveAddress(ctx, address);
+    const replaced = await store.saveAddress(ctx, address);
     notePreviousAddress(replaced);
     if (dispatch) rememberDispatch(dispatch); // remember only after it is stored
     // Close the loop back to OneAddress so the service flips to "Confirmed".
-    // Fire-and-forget: it must not delay this 200 (which acks the delivery).
-    void confirmToOneAddress(dispatch, 'confirmed');
+    // QUEUED, not sent: this is a local INSERT, so it cannot delay the 200 that
+    // acks the delivery, and it survives a restart. The drain loop does the
+    // network part and retries it until OneAddress answers.
+    queueConfirm(dispatch, 'confirmed');
+    recordOutcome(key, 'applied');
     return res.status(200).json({ ok: true });
   }
 
   // \u2500\u2500 address.verify: consumer is running an address check \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   if (event === 'address.verify') {
-    const callbackUrl   = body.callback_url   as string;
-    const callbackToken = body.callback_token as string;
-    const batchId       = body.batch_id       as string;
-
-    // Callback URL is signed inside the body, so HMAC verify already proves it
-    // came from OneAddress. We still validate the host as defence in depth:
-    // if the webhook secret ever leaks, an attacker who can forge a webhook
-    // could otherwise coerce this server into POSTing to any internal
-    // URL (database admin, cloud metadata service, \u2026) \u2014 turning the partner's
-    // network position into an SSRF primitive.
-    const safeCallbackUrl = safeOneAddressCallbackUrl(callbackUrl);
-    if (!safeCallbackUrl) {
-      report.warn(\`[webhook] refusing callback to non-OneAddress host: \${callbackUrl}\`);
-      return res.status(400).json({ error: 'Invalid callback_url host' });
-    }
-
     report.info(\`[webhook] address.verify for \${ctx.accountNumber || ctx.name}\`);
-    const result = await verifyAddress(ctx, address);
+    const result = await store.verifyAddress(ctx, address);
     report.info(\`[webhook] address.verify \u2192 \${result}\`);
-
-    await fetch(safeCallbackUrl, {
-      method:  'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        // 2026.2 \u2014 no member_name echo; OneAddress keys the result on
-        // (batch_id, partner_id) and validates the opaque token alone.
-        batch_id:    batchId,
-        partner_id:  PARTNER_ID,
-        result,
-        token:       callbackToken,
-      }),
-    });
+    const refused = await postVerifyVerdict(result);
+    if (refused) return refused;
     if (dispatch) rememberDispatch(dispatch); // remember only after the callback posted
     return res.status(200).json({ ok: true });
   }
@@ -3104,12 +5251,179 @@ app.post('/webhook', async (req: Request, res: Response) => {
   return res.status(200).json({ ok: true, skipped: true });
 });
 
-app.get('/health', (_req, res) => res.json({ status: 'ok' }));
+/**
+ * Enough to answer "is this receiver healthy AND is it protected?" from a
+ * monitoring system, without a terminal and without reading the logs.
+ *
+ * \`encryptedAtRest\` is here rather than only on the dashboard because the
+ * deployment that most needs the answer is the one with no dashboard. Carrying
+ * it makes the unprotected state alertable instead of merely visible.
+ *
+ * Deliberately NO counts, no customer data and no key material: this endpoint
+ * is reachable by whatever can reach the webhook.
+ */
+app.get('/health', (_req, res) => res.json({
+  status: 'ok',
+  store: store.name,
+  encryptedAtRest: store.encrypted,
+}));
 
 app.listen(PORT, () =>
   report.info(\`[server] OneAddress webhook server \u2192 http://localhost:\${PORT}/webhook\`),
 );
 
+/**
+ * Drain the confirm queue, forever.
+ *
+ * STARTED AT BOOT, not only after a dispatch, because the queue survives a
+ * restart: a receiver that was down while OneAddress was unreachable comes back
+ * with confirms owed, and nobody is going to send a fresh dispatch to trigger
+ * them. On a healthy receiver this loop finds nothing and costs one indexed
+ * SELECT every few seconds.
+ */
+const CONFIRM_DRAIN_MS = Number(process.env.CONFIRM_DRAIN_MS ?? 5000);
+const CONFIRM_KEEP_DAYS = Number(process.env.CONFIRM_KEEP_DAYS ?? 30);
+
+let draining = false;
+setInterval(() => {
+  // Guarded rather than queued: a slow OneAddress must not start a second
+  // drain over the same rows, which would confirm each one twice.
+  if (draining) return;
+  draining = true;
+  void drainConfirms(confirmToOneAddress)
+    .catch((err: unknown) => report.error('[confirm] drain error:', err))
+    .finally(() => { draining = false; });
+}, CONFIRM_DRAIN_MS).unref();
+
+// Delivered rows only, so an outstanding confirm is never aged out. Hourly is
+// far more often than needed and costs one DELETE over an index.
+setInterval(() => {
+  const purged = purgeDelivered(CONFIRM_KEEP_DAYS);
+  if (purged > 0) report.info(\`[confirm] purged \${purged} delivered confirm record(s) older than \${CONFIRM_KEEP_DAYS}d\`);
+}, 3_600_000).unref();
+
+/**
+ * Re-deliver a held dispatch TO THIS SERVER, re-signed.
+ *
+ * A self-POST rather than a second code path into the handler. The handler is
+ * one 300-line route and the alternative is extracting it so replay can call it
+ * directly, which would give two ways in and, in time, two behaviours: the one
+ * partners hit and the one replay hits, differing in whichever branch was added
+ * to only one of them. Going back in through the front door means a replayed
+ * dispatch is verified, parsed, decrypted, applied and confirmed by exactly the
+ * code a live one is.
+ *
+ * The body is byte-for-byte what arrived; only the timestamp and signature are
+ * new, because the original pair is outside the \xB15-minute window by the time
+ * anyone has fixed anything. We hold the secret, so re-signing is not a bypass:
+ * it is the same proof, re-stated now.
+ */
+async function redeliver(rawBody: string, heldDispatchId: string | null): Promise<void> {
+  const ts  = String(Math.floor(Date.now() / 1000));
+  const sig = createHmac('sha256', WEBHOOK_SECRET).update(\`\${ts}.\${rawBody}\`).digest('hex');
+  // THE ID THE DISPATCH ARRIVED WITH, handed over by the row being replayed.
+  // Re-deriving it from the body is what made one held dispatch become two.
+  const dispatchId = (heldDispatchId ?? '').trim();
+
+  const res = await fetch(\`http://127.0.0.1:\${PORT}/webhook\`, {
+    method: 'POST',
+    headers: {
+      'Content-Type':           'application/json',
+      'X-OneAddress-Timestamp': ts,
+      'X-OneAddress-Signature': sig,
+      ...(dispatchId ? { 'X-OneAddress-Dispatch': dispatchId } : {}),
+    },
+    body: rawBody,
+  });
+  const text = (await res.text().catch(() => '')).slice(0, 200);
+  if (!res.ok) throw new Error(\`HTTP \${res.status} \${text}\`);
+  // A 200 is not on its own success here: the handler answers \`ok: false\` with
+  // 200 when it REFUSES a dispatch (an account reference matching nobody), and
+  // treating that as applied would clear the row for an update that was never
+  // stored.
+  if (!text.includes('"ok":true')) throw new Error(\`refused: \${text}\`);
+}
+
+/** Apply everything held. Bound to [r] on the dashboard and run once at boot. */
+export async function replayQuarantined(): Promise<{ applied: number; failed: number }> {
+  return replayHeld(redeliver);
+}
+
+/**
+ * Try the backlog once, a moment after boot.
+ *
+ * Because the realistic sequence is: a key is wrong, dispatches pile up, the
+ * partner edits \`.env\`, the partner restarts. Making them find a command after
+ * that is making the recovery depend on reading documentation at the exact
+ * moment they are least inclined to. The delay lets \`listen\` settle, since this
+ * goes back in through the port.
+ */
+// \u2500\u2500 The connector channel, in inbox mode only \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+//
+// Wired here rather than in draw-api.ts because this file owns the confirm
+// queue: an acknowledgement from the connector is the moment OneAddress gets
+// told, and that has to go through the same durable queue every other confirm
+// uses so a failure to reach OneAddress is retried rather than lost.
+if (config.mode === 'inbox') {
+  setAcknowledgementHandler((dispatchId, outcome) => {
+    queueConfirm(dispatchId, outcome === 'applied' ? 'confirmed' : 'failed');
+    recordOutcome(\`d:\${dispatchId}\`, outcome === 'applied' ? 'applied' : 'failed');
+  });
+  const started = startDrawApi();
+  if (!started) {
+    // AN INBOX WITH NO WAY TO DRAIN IT IS WORSE THAN NOT STARTING. In
+    // write-through mode a missing connector token is irrelevant and the
+    // receiver runs; here it means every dispatch would be accepted and held
+    // with nothing able to collect it, and the consumer would be told nothing
+    // for as long as that lasted.
+    report.error('[startup] mode is \`inbox\` but the connector channel could not open. Refusing to start.');
+    process.exit(1);
+  }
+}
+
+setTimeout(() => {
+  if (heldCount() === 0) return;
+  void replayQuarantined().catch((err: unknown) =>
+    report.error('[replay] could not run at startup:', err),
+  );
+}, 1_500).unref();
+
+// Held payloads age out whether or not they were ever applied, which is the
+// opposite of the confirm queue one block up. The reason is what the row holds:
+// a confirm record names a dispatch, a quarantined payload is a consumer's
+// encrypted address on someone else's disk.
+const QUARANTINE_KEEP_DAYS = Number(process.env.QUARANTINE_KEEP_DAYS ?? 30);
+setInterval(() => { purgeQuarantine(QUARANTINE_KEEP_DAYS); }, 3_600_000).unref();
+
+/** How many confirms are still owed, and how the dispatches went. Read by the dashboard. */
+export { pendingConfirmCount, tally };
+
+/**
+ * Everything the dashboard footer needs, in one call.
+ *
+ * One hook rather than three, because three would be three chances for the
+ * footer to show figures from different moments.
+ */
+export function dashboardStats(): {
+  received: number;
+  applied: number;
+  failed: number;
+  mode: string;
+  awaitingConnector: number;
+  oldestUndrawn: string | null;
+} {
+  const t = tally();
+  const inbox = config.mode === 'inbox'
+    ? { count: undrawnCount(), oldest: oldestUndrawn() }
+    : { count: 0, oldest: null };
+  return {
+    ...t,
+    mode: config.mode,
+    awaitingConnector: inbox.count,
+    oldestUndrawn: inbox.oldest,
+  };
+}
+
 // Read by src/index.ts to label the dashboard. Exported rather than re-derived
 // there, so the port the UI claims is the port the server actually bound.
 export { PORT };
@@ -3272,8 +5586,174 @@ Valid address-verify results: \`"match"\` \xB7 \`"mismatch"\` \xB7 \`"not_found"
 
 After an \`address.updated\` is stored, the receiver POSTs to \`\${ONEADDRESS_API}/api/confirm\`
 (HMAC-SHA256 over \`\${timestamp}.\${rawBody}\`, Bearer + \`X-OneAddress-Signature\` headers)
-so the consumer's dashboard flips the service to **Confirmed**. It is
-fire-and-forget, so a slow confirm never delays the webhook \`200\`.
+so the consumer's dashboard flips the service to **Confirmed**.
+
+It is QUEUED, not fired and forgotten. The acknowledgement is a durable local
+row, retried with backoff and surviving a restart, so a local write is all the
+webhook waits on. That matters more than it sounds: an update OneAddress never
+hears about is shown to the consumer as a FAILED delivery, and a failed delivery
+can be refunded \u2014 so a thirty-second outage used to mean you did the work and the
+payment went back. The dashboard's \`awaiting confirm\` count is how many are still
+owed; a non-zero figure that will not come down is usually a wrong
+\`CONFIRM_SECRET\`, and the log says so.
+
+### When a dispatch will not decrypt
+
+If a dispatch arrives with a valid signature and cannot be opened \u2014 the wrong key,
+or a \`key_id\` you have no variable for \u2014 it is answered \`422\` (so OneAddress keeps
+treating it as undelivered) and the encrypted payload is HELD exactly as it
+arrived. Nothing is decrypted on the way in; the receiver could not, which is the
+whole reason the record exists.
+
+A \`FAULTS\` panel appears on the dashboard while anything is held and names the
+cause and the \`key_id\`. Fix the key and restart and the backlog applies itself,
+or press \`[r]\` without restarting.
+
+### Rotating a key
+
+Every dispatch names the key it was encrypted to, and both keys stay valid for an
+overlap window. Give each its own variable, named for its \`key_id\` with dashes as
+underscores, upper-cased:
+
+\`\`\`
+PARTNER_PRIVATE_KEY_PEM_04032299_4B04_4842_AA29_5095500C8ECE=...
+\`\`\`
+
+\`PARTNER_PRIVATE_KEY_PEM\` is then a fallback for any \`key_id\` without a variable
+of its own. Convenient with one key and a trap with two: it answers for an id it
+does not hold, and AES-GCM cannot tell a wrong key from a tampered ciphertext, so
+the failure reads like corruption rather than like a rotation. **Set
+\`PARTNER_KEYS_STRICT=1\` once you hold more than one key.** The startup line tells
+you which keys this receiver can open.
+
+## Pointing this at your own database
+
+Everything OneAddress needs from your systems is **five methods in
+\`src/customer-store.ts\`**. That file is the contract: no schema, no seeding, no
+encryption in the way, a paragraph per method. It is the file to hand a DBA, and
+it is readable in ten minutes without reading any of ours.
+
+\`src/store.ts\` is the DEFAULT implementation of it, backed by the bundled SQLite
+file. The SQLite schema, the at-rest encryption, the blind index,
+\`customers.json\`, the repair pass and the history table all belong to that
+implementation and **not** to the contract. If your customers already live in
+your own database, delete them rather than port them: encrypting a second copy
+of a record you already hold protects nothing and gives you another key to
+manage.
+
+Write a module exporting a \`CustomerStore\` and change one line:
+
+\`\`\`typescript
+// src/server.ts and src/tui.ts
+import { store } from './my-customer-store.js';
+\`\`\`
+
+The \`satisfies CustomerStore\` on your export is what keeps that safe \u2014 miss a
+method, or drift from a signature the receiver depends on, and it stops
+compiling rather than failing on a live dispatch. The receiver names the live
+store in its startup line, so you can see which one is running without reading
+code.
+
+### What it needs on your database
+
+Less than people expect. The receiver never reads a customer's address for its
+own purposes and never lists your table:
+
+| Method | Needs |
+|--------|-------|
+| \`verifyAccount\` | read the account number and the name |
+| \`verifyAddress\` | read the address you hold |
+| \`saveAddress\` | read the address, then write it; append your own audit row |
+| \`find\` | read one row by account number (optional, dashboard only) |
+| \`count\` | nothing \u2014 return \`null\` and it is never asked |
+
+A least-privilege PostgreSQL grant for that is short enough to review:
+
+\`\`\`sql
+CREATE ROLE oneaddress_receiver LOGIN PASSWORD '...';
+GRANT USAGE ON SCHEMA app TO oneaddress_receiver;
+GRANT SELECT (account_number, name, address) ON app.customers TO oneaddress_receiver;
+GRANT UPDATE (address, updated_at)           ON app.customers TO oneaddress_receiver;
+GRANT INSERT                                  ON app.address_history TO oneaddress_receiver;
+-- No DELETE, no DDL, no access to any other table.
+\`\`\`
+
+**No INSERT on \`customers\`.** The receiver has no business creating customers:
+a dispatch for an account you do not have is one you should refuse, and a role
+that cannot create a row cannot be talked into it by a bug in ours.
+
+### What stays ours
+
+The receiver keeps a small local SQLite file even when your customers live
+elsewhere, for the confirm queue and the quarantine. Neither holds customer
+data: the confirm queue holds dispatch ids and outcomes, the quarantine holds
+ciphertext the receiver could not open. Your DBA is entitled to ask, and that is
+the answer.
+
+The protocol half stays ours too, and a store implementation is never given a
+chance to weaken it: signature verification, the replay window, decryption and
+the confirm callback all run before your code is called. By then the dispatch
+has been proven to come from OneAddress and decrypted in memory.
+
+### One thing to get right at your scale
+
+\`count()\` is asked every two seconds while the dashboard is open. **Return
+\`null\` from it** if answering means a \`SELECT count(*)\` over a real customer
+table; the dashboard draws a dash and is otherwise identical. The bundled store
+answers it because its roster is three rows.
+
+The same reasoning is why there is no "list every customer" method. The
+dashboard asks for the ONE customer a dispatch just changed, by account number,
+so your database does the thing it is already good at.
+
+## What this is, and where it stops
+
+Honest limits, so you find them here rather than in production. Most are further
+away than people expect, and the last one is a hard edge rather than a slope.
+
+**It is a real receiver, not a toy.** It verifies signatures, enforces the
+replay window, decrypts per-partner envelopes, holds what it cannot open,
+retries its acknowledgements durably and refuses accounts you do not recognise.
+Nothing in the protocol layer is stubbed.
+
+**Throughput is not the constraint.** An address change is a rare event per
+customer. A single process on modest hardware handles far more than a consumer
+base generates, and the work per dispatch is one decrypt and one write.
+
+**Its own bookkeeping is a local SQLite file**, whatever your customers live in.
+The confirm queue holds dispatch ids and outcomes; the quarantine holds
+ciphertext it could not open. Neither holds customer data, and both stay local
+even after you implement \`CustomerStore\` against your own database.
+
+**The hard edge: run ONE of these.** Because that bookkeeping is a local file,
+two instances are not two workers sharing a queue - they are two separate
+receivers. Each acknowledges only what it received, and pressing \`[r]\` on one
+does nothing for the other's backlog. That is fine, and it is not a scaling
+problem at this event rate, but it is a thing to know before somebody sets
+\`replicas: 2\` and wonders why half the confirms never leave.
+
+If you genuinely need more than one instance, or a metrics endpoint, or a
+different database behind the receiver's own bookkeeping, talk to us before
+building around it: that is a different piece of software and we would rather
+give it to you than watch you rebuild it.
+
+### The order to do things in
+
+1. **Run it as generated.** Point the wizard at a tunnel, pass conformance, see
+   a real dispatch land in the demo roster.
+2. **Implement \`CustomerStore\` against your own database.** The contract is five
+   methods; the grant above is what your DBA needs to approve. Delete the SQLite
+   roster, \`customers.json\`, the at-rest encryption and the history table when
+   you do - they are ours, not the contract's.
+3. **Decide the two retention windows.** \`CONFIRM_KEEP_DAYS\` and
+   \`QUARANTINE_KEEP_DAYS\` both default to 30. The second one is holding your
+   customers' encrypted addresses, so it is a decision your privacy people
+   should make rather than inherit.
+4. **Run it where it will live**, with \`ONEADDRESS_DB_PASSPHRASE\` set if you kept
+   our store, and watch the startup line: it names which store is live and
+   whether it is encrypted at rest, in both directions. \`/health\` carries the
+   same two facts so you can alert on them.
+5. **Set \`PARTNER_KEYS_STRICT=1\`** the day you hold a second key.
 
 ## Conformance check
 
@@ -3301,6 +5781,23 @@ webhook URL at [partners.oneaddress.io](https://partners.oneaddress.io).
 | \`oneAddressApi\` | \`https://oneaddress.io\` | Base URL the confirm callback posts to. |
 | \`verifiesAccountReference\` | \`(your portal declaration)\` | Whether you answer \`account.verify\` with a real match, or reply "not checked". |
 
+**Three optional environment variables** tune what is kept, and most partners
+set none of them:
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| \`PARTNER_KEYS_STRICT\` | unset | \`1\` turns off the single-key fallback. Set it once you hold more than one key. |
+| \`CONFIRM_KEEP_DAYS\` | \`30\` | How long DELIVERED confirm records are kept. An OUTSTANDING one is never aged out. |
+| \`QUARANTINE_KEEP_DAYS\` | \`30\` | How long a held payload is kept, applied or not. |
+
+The last two are deliberately opposite rules, and the difference is what the row
+holds. A confirm record names a dispatch and an outcome, so keeping an unanswered
+one forever costs nobody anything and dropping it loses an update. A held payload
+is one of your customers' addresses, encrypted, sitting on your disk: keeping that
+indefinitely is a retention decision nobody made, so it has a window, and a
+payload that ages out without ever being applied is logged loudly rather than
+quietly.
+
 Each field can be overridden for a one-off by an environment variable of the
 matching name (\`PARTNER_ID\` / \`ONEADDRESS_API\` / \`VERIFIES_ACCOUNT_REFERENCE\`).
 One secret has no config-file home because it must stay out of a non-secret
@@ -8156,7 +10653,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto = require("crypto");
-var PKG_VERSION = true ? "2.1.2" : "dev";
+var PKG_VERSION = true ? "2.2.0" : "dev";
 var REGISTER_URL = "https://partners.oneaddress.io/api/partner/installs";
 function hmacSha256(secret, message) {
   return (0, import_node_crypto.createHmac)("sha256", secret).update(message).digest("hex");