@oneaddress/setup 2.1.1 → 2.1.3

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.1" : "?";
+var WIZARD_VERSION = true ? "2.1.3" : "?";
 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
 `
@@ -964,8 +978,8 @@ data.db-shm
   "private": true,
   "scripts": {
     "dev":      "tsx watch src/index.ts",
-    "start":    "tsx src/index.ts",
-    "headless": "tsx src/index.ts -- --headless",
+    "start":    "node --disable-warning=ExperimentalWarning node_modules/tsx/dist/cli.mjs src/index.ts",
+    "headless": "node --disable-warning=ExperimentalWarning node_modules/tsx/dist/cli.mjs src/index.ts -- --headless",
     "build":    "tsup src/index.ts --format esm --no-dts --outDir dist",
     "type-check": "tsc --noEmit",
     "test":     "tsx scripts/test.ts"
@@ -1081,6 +1095,7 @@ import {
   encryptField,
   isEncrypted,
   newSalt,
+  PassphraseRequiredError,
   verifierMatches,
   WrongPassphraseError,
   type VaultKeys,
@@ -1128,14 +1143,36 @@ function saltForThisDatabase(): Buffer {
 }
 
 function openKeys(): VaultKeys | null {
+  // THE VERIFIER IS READ FIRST, and the order is the whole fix.
+  //
+  // This used to return null the moment no passphrase was set, without ever
+  // asking whether the database was encrypted. An encrypted store opened with
+  // no passphrase therefore ran IN THE CLEAR over the top of itself: it could
+  // not decrypt the existing rows, so their blind indexes never matched, so it
+  // seeded a SECOND copy of the roster in plaintext beside the first. The next
+  // unlock then tried to converge both copies onto one key and died on a
+  // UNIQUE constraint, permanently, with the correct passphrase in hand.
+  //
+  // Reported by a partner on 2.1.1 as "it is locking me out", and the lockout
+  // was the last step of three. Two things were wrong and the quiet one was
+  // worse: plaintext customer records written into a database its owner had
+  // encrypted.
+  const stored = readMeta('verifier');
   const passphrase = process.env.ONEADDRESS_DB_PASSPHRASE;
-  if (!passphrase || !passphrase.trim()) return null;
+
+  if (!passphrase || !passphrase.trim()) {
+    // Never silently. A database with no verifier has never been locked and
+    // running it in the clear is the documented, chosen behaviour; one WITH a
+    // verifier is somebody's encrypted store and this is not the process that
+    // gets to open it.
+    if (stored !== null) throw new PassphraseRequiredError();
+    return null;
+  }
 
   const keys = deriveKeys(passphrase, saltForThisDatabase());
 
   // Checked BEFORE anything is written. A mistyped passphrase must not be able
   // to write a single row of ciphertext that nothing can ever read back.
-  const stored = readMeta('verifier');
   if (stored === null) writeMeta('verifier', buildVerifier(keys));
   else if (!verifierMatches(keys, stored)) throw new WrongPassphraseError();
 
@@ -1182,7 +1219,16 @@ export function once(column: string, value: string | null): string | null {
   return isEncrypted(value) ? value : encryptField(keys, column, value);
 }
 
-export { WrongPassphraseError };
+export { PassphraseRequiredError, WrongPassphraseError };
+
+/**
+ * Is this stored value ciphertext? Exported for the repair pass in \`store.ts\`.
+ *
+ * The repair has to tell an encrypted row from a plaintext one written beside
+ * it by a run that had no passphrase, and that is the only question that
+ * separates them.
+ */
+export { isEncrypted };
 export default db;
 `
     },
@@ -1363,6 +1409,25 @@ export class WrongPassphraseError extends Error {
   }
 }
 
+/**
+ * The database is encrypted and nobody supplied a passphrase.
+ *
+ * NAMED SEPARATELY FROM \\\`WrongPassphraseError\\\` because the remedy is different:
+ * one means try again, the other means you have not been asked yet. Before this
+ * existed the case had no error at all - opening an encrypted database with no
+ * passphrase returned no keys and the receiver carried on IN THE CLEAR over the
+ * top of it, which cost a partner their database. See the refusal in db.ts.
+ */
+export class PassphraseRequiredError extends Error {
+  constructor() {
+    super(
+      'This database is encrypted. Set ONEADDRESS_DB_PASSPHRASE, or run \`npm start\` ' +
+      'in a terminal to be asked for it.',
+    );
+    this.name = 'PassphraseRequiredError';
+  }
+}
+
 export interface VaultKeys {
   /** AES-256-GCM key for the personal columns. */
   cipherKey: Buffer;
@@ -1595,7 +1660,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 { heldCount, heldSummary } from './quarantine.js';
 
 /** blessed takes colours as strings; these mirror the site's palette. */
 const AMBER = HEX.amber.toLowerCase();
@@ -1610,6 +1680,14 @@ 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 }>;
 }
 
 /** One address as a single line, the way the change panel shows it. */
@@ -1618,7 +1696,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 }: TuiOptions): void {
   const screen = blessed.screen({
     smartCSR: true,
     title: \`\${partnerName} \u2014 OneAddress receiver\`,
@@ -1671,6 +1749,23 @@ 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.
+  const FAULT_HEIGHT = 7;
+  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 },
@@ -1694,14 +1789,18 @@ 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
+    const vault = 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()}{/}\`,
     );
   }
 
@@ -1725,18 +1824,76 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
     );
   }
 
+  /** 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.
+   */
+  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, 3).map((l) => \`  {red-fg}\${esc(l)}{/}\`);
+    faultBox.setContent(
+      \`\\n  {bold}\${held}{/bold} dispatch(es) arrived that this receiver could not open.\\n\` +
+      \`  {\${DIM}-fg}They are held, encrypted, exactly as they arrived. Nothing is lost yet.{/}\\n\\n\` +
+      lines.join('\\n') + '\\n\\n' +
+      (replayNote
+        ? \`  {\${AMBER}-fg}\${esc(replayNote)}{/}\`
+        : \`  {\${DIM}-fg}Fix the cause (usually a key in .env), then press{/} {\${AMBER}-fg}[r]{/} {\${DIM}-fg}to apply them.{/}\`),
+    );
+  }
+
   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;
     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}   \` +
+      \`{\${awaitingColour}-fg}awaiting confirm{/} {bold}\${awaiting}{/bold}\` +
+      \`{|}{\${DIM}-fg}\${onReplay ? '[r] replay  ' : ''}[q] quit{/}  \`,
     );
   }
 
   function redraw(): void {
     renderStatus();
     renderChange();
+    renderFaults();
     renderFooter();
     screen.render();
   }
@@ -1750,21 +1907,64 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
     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++;
+    // COUNTED ON THE OUTCOME LINE, WHICHEVER IT IS.
+    //
+    // \`received\` used to increment only on \`address.updated for <account>\`,
+    // which is logged AFTER decryption because the account number comes out of
+    // the decrypted envelope. A dispatch that failed to decrypt returned 422
+    // before that line ran, so it was never counted as having arrived: a
+    // partner with a wrong key saw \`received 0 \xB7 failed 12\` and went looking at
+    // their tunnel and their webhook URL. Everything was arriving. The error
+    // line said "check your key" and the counter, louder, said "nothing here".
+    //
+    // Every dispatch produces exactly one of these, so counting either as an
+    // arrival makes received = applied + failed hold.
+    const failure = /REFUSED|decryption failed|Decryption failed|no private key for/.test(text);
+    if (/address\\.updated for /.test(text) || failure) received++;
+    if (failure) 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(); });
+  });
+
   screen.key(['q', 'C-c'], () => {
     detach();
     screen.destroy();
@@ -1772,6 +1972,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();
 }
 
@@ -1814,7 +2022,7 @@ export function notePreviousAddress(prev: Record<string, unknown>): void {
  * \`--headless\` skips both: no prompt (a service has nobody to ask), no screen.
  */
 import { printBanner } from './brand.js';
-import { WrongPassphraseError } from './vault.js';
+import { PassphraseRequiredError, WrongPassphraseError } from './vault.js';
 
 /**
  * No dashboard without a terminal to draw it in.
@@ -1878,25 +2086,79 @@ async function databaseIsLocked(): Promise<boolean> {
  * hook is not available, being asked in the clear beats not being asked.
  */
 async function ask(prompt: string): Promise<string> {
-  const { createInterface } = await import('node:readline/promises');
-  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
-  const hooked = rl as unknown as { _writeToOutput?: (s: string) => void };
-  const original = hooked._writeToOutput;
-  try {
-    hooked._writeToOutput = function (chunk: string): void {
-      // Echo the prompt itself, mask everything the user types.
-      if (chunk.includes(prompt)) process.stdout.write(chunk);
-      else process.stdout.write('*');
+  process.stdout.write(prompt);
+
+  // NO readline. Two versions of this used readline's \`_writeToOutput\` hook to
+  // mask the echo and BOTH ECHOED THE PASSPHRASE IN CLEAR, which was only found
+  // by driving a real terminal and reading what came back. The first filtered
+  // on whether the chunk contained the prompt, not knowing readline repaints
+  // prompt and input together on every keystroke, so the condition was always
+  // true. The second repainted the line and still leaked, because the echo was
+  // never coming from that hook at all.
+  //
+  // Reading the keys directly removes the guessing. Raw mode turns the
+  // terminal's own echo OFF, so the ONLY thing that can reach the screen is
+  // what is written below: one asterisk per character, which is what a partner
+  // asked for and what every other passphrase prompt does.
+  const stdin = process.stdin;
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') {
+    // No terminal to control. Being asked in the clear beats not being asked,
+    // and this path is only reached where nothing is watching anyway.
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: stdin, output: process.stdout });
+    try {
+      const answer = await rl.question('');
+      return answer.trim();
+    } finally { rl.close(); }
+  }
+
+  const wasRaw = stdin.isRaw === true;
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding('utf8');
+
+  return new Promise<string>((resolve) => {
+    let typed = '';
+    const restore = (): void => {
+      stdin.removeListener('data', onData);
+      stdin.setRawMode(wasRaw);
+      stdin.pause();
     };
-  } catch { /* keep the visible prompt */ }
-  try {
-    const answer = await rl.question(prompt);
-    process.stdout.write('\\n');
-    return answer.trim();
-  } finally {
-    if (original) hooked._writeToOutput = original;
-    rl.close();
-  }
+    const onData = (chunk: string): void => {
+      for (const ch of chunk) {
+        if (ch === '\\r' || ch === '\\n') {
+          restore();
+          process.stdout.write('\\n');
+          resolve(typed.trim());
+          return;
+        }
+        if (ch === '\\u0003') {            // Ctrl+C
+          restore();
+          process.stdout.write('\\n');
+          process.exit(130);
+        }
+        if (ch === '\\u0004') {            // Ctrl+D on an empty line ends it
+          restore();
+          process.stdout.write('\\n');
+          resolve(typed.trim());
+          return;
+        }
+        if (ch === '\\u007f' || ch === '\\b') {
+          // Backspace has to move the asterisks too, or the mask stops matching
+          // what is actually in the buffer and the count misleads.
+          if (typed.length > 0) {
+            typed = typed.slice(0, -1);
+            process.stdout.write('\\b \\b');
+          }
+          continue;
+        }
+        if (ch < ' ') continue;          // ignore the rest of the control range
+        typed += ch;
+        process.stdout.write('*');
+      }
+    };
+    stdin.on('data', onData);
+  });
 }
 
 /**
@@ -1927,7 +2189,17 @@ async function resolvePassphrase(): Promise<string | null> {
   if (headless || !process.stdin.isTTY) return null;
 
   if (await databaseIsLocked()) {
-    process.stdout.write('\\n  This customer database is encrypted.\\n\\n');
+    // NAMES THE WAY OUT, because a partner can arrive here having never
+    // knowingly set a passphrase. Versions before 2.0.1 asked for one with a
+    // prompt that did not say whether it was creating or checking, so a
+    // database can carry a verifier its owner does not remember agreeing to.
+    // Reported by exactly that partner: "there was no opportunity to set a
+    // passphrase". Without this line the only options are guess or search the
+    // internet, and the answer is one command.
+    process.stdout.write('\\n  This customer database is encrypted.\\n');
+    process.stdout.write('  If you do not know the passphrase, delete data.db and start\\n');
+    process.stdout.write('  again: it holds your demo roster and test dispatches, nothing\\n');
+    process.stdout.write('  OneAddress needs.\\n\\n');
     const answer = await ask('  Passphrase to unlock: ');
     return answer || null;
   }
@@ -1962,11 +2234,32 @@ 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 }>;
+  };
   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,
+    };
   } catch (err) {
+    if (err instanceof PassphraseRequiredError) {
+      // Reached when nobody could be asked: a service unit, a piped stdin, or
+      // the setup wizard's own health-check autostart. Before the refusal in
+      // db.ts this case ran in the clear and corrupted the database instead.
+      console.error('\\n  This database is encrypted and no passphrase was supplied.');
+      console.error('  Run \`npm start\` in a terminal to be asked for it, or set');
+      console.error('  ONEADDRESS_DB_PASSPHRASE for an unattended start.\\n');
+      process.exit(1);
+    }
     if (err instanceof WrongPassphraseError) {
       // Named for what it is. Without this the first symptom is a decryption
       // error on a live dispatch, which reads as a corrupt database and sends
@@ -1984,6 +2277,7 @@ async function main(): Promise<void> {
   startDashboard({
     partnerName: config.partnerName,
     port: config.port,
+    onReplay: config.replay,
     onQuit: () => { /* the process exits; the OS closes the socket */ },
   });
 }
@@ -1992,6 +2286,581 @@ main().catch((err) => {
   console.error('[startup]', err instanceof Error ? err.message : err);
   process.exit(1);
 });
+`
+    },
+    {
+      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 from './db.js';
+import { report } from './report.js';
+import { createHash } from 'node:crypto';
+
+/**
+ * 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.
+ */
+function rowId(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)}\`;
+}
+
+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 = rowId(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;
+}
+
+/** 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
+       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
+       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 }[];
+  return rows.map((r) =>
+    \`\${r.n} \xD7 \${r.reason}\${r.key_id ? \` (key_id \${r.key_id})\` : ''}\`,
+  );
+}
+
+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 = ? 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 };
+}
+
+/**
+ * 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) => Promise<void>,
+  limit = 50,
+): Promise<{ applied: number; failed: number }> {
+  let applied = 0;
+  let failed = 0;
+  for (const row of heldDispatches(limit)) {
+    try {
+      await apply(row.raw_body);
+      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(' ');
+}
 `
     },
     {
@@ -2093,6 +2962,194 @@ export function safeOneAddressCallbackUrl(raw: string): string | null {
     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;
+}
 `
     },
     {
@@ -2101,25 +3158,45 @@ export function safeOneAddressCallbackUrl(raw: string): string | null {
  * \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  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  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
+ * \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, once } from './db.js';
-
-export type Address = Record<string, unknown>;
+import db, { accountKey, dec, enc, encrypted, 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
@@ -2178,6 +3255,48 @@ ensureColumn('address_history', 'prev_address', "TEXT NOT NULL DEFAULT '{}'");
 // pass produces the same key rather than hashing a ciphertext and orphaning the
 // row. A row orphaned that way still reads fine in a listing and is invisible
 // to every dispatch, which is the worst kind of broken.
+// REPAIR FIRST, because a database can already be in the state the refusal in
+// db.ts now prevents. Before that refusal existed, a run with no passphrase
+// against an encrypted store could not decrypt the roster, so its blind indexes
+// never matched and it seeded a SECOND copy of every customer in plaintext. The
+// relabel below then maps both copies onto one key and dies on UNIQUE, with the
+// correct passphrase in hand and no way forward but deleting the file.
+//
+// So the plaintext twin is dropped. WHICH ONE GOES IS NOT A GUESS: the
+// encrypted row is the one the owner's passphrase wrote, the plaintext row was
+// written by a process that could not read it. Only the second is discarded,
+// and only when an encrypted row for the same account exists.
+//
+// Scoped to an encrypted database. With no keys there is nothing to compare,
+// every row is plaintext, and there is no duplicate to find.
+if (encrypted) {
+  const all = db.prepare('SELECT rowid AS rid, account_number FROM customers').all() as Array<
+    { rid: number; account_number: string }
+  >;
+  const seen = new Map<string, boolean>();   // plain account -> has an encrypted row
+  for (const r of all) {
+    if (isEncrypted(r.account_number)) {
+      const plain = dec('account_number', r.account_number);
+      if (plain) seen.set(plain, true);
+    }
+  }
+  const drop = db.prepare('DELETE FROM customers WHERE rowid = ?');
+  let dropped = 0;
+  for (const r of all) {
+    if (isEncrypted(r.account_number)) continue;
+    if (!seen.get(r.account_number)) continue;
+    drop.run(r.rid);
+    dropped += 1;
+  }
+  if (dropped > 0) {
+    // Said out loud. A silent repair of somebody's customer table is the kind
+    // of thing they should hear about from us rather than notice later.
+    report.warn(
+      \`[store] repaired \${dropped} plaintext duplicate customer row(s) left by a run with no passphrase\`,
+    );
+  }
+}
+
 {
   const rows = db.prepare('SELECT rowid AS rid, account_number, name, address FROM customers').all() as Array<
     { rid: number; account_number: string; name: string; address: string }
@@ -2269,22 +3388,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.
@@ -2319,13 +3422,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;
@@ -2352,8 +3448,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
@@ -2376,8 +3470,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)
@@ -2456,6 +3548,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;
 `
     },
     {
@@ -2495,10 +3628,28 @@ 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 } from './store.js';
 import { notePreviousAddress } from './tui.js';
 import { config } from './config.js';
 import { safeOneAddressCallbackUrl } from './callback-url.js';
+import { describeKeys, keyFailureAdvice, resolvePrivateKey } from './keys.js';
+import {
+  drainConfirms,
+  enqueueConfirm,
+  pendingConfirmCount,
+  purgeDelivered,
+  type ConfirmStatus,
+} from './confirm-queue.js';
+import {
+  heldCount,
+  purgeQuarantine,
+  quarantine,
+  replayHeld,
+  type QuarantineReason,
+} from './quarantine.js';
 
 const WEBHOOK_SECRET      = process.env.WEBHOOK_SECRET          ?? '';
 const PARTNER_PRIVATE_KEY = process.env.PARTNER_PRIVATE_KEY_PEM ?? '';
@@ -2548,6 +3699,33 @@ 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.
+report.info(\`[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
@@ -2569,9 +3747,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>
@@ -2579,13 +3758,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,
@@ -2595,7 +3772,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: {
@@ -2608,18 +3785,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
 
@@ -2721,7 +3911,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 });
   }
@@ -2732,6 +3922,23 @@ 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.
+   */
+  const hold = (reason: QuarantineReason, keyId: string | null, detail: string): void =>
+    quarantine({ dispatchId: dispatch || null, event, reason, keyId, rawBody, detail });
+
   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)\`);
@@ -2765,25 +3972,47 @@ 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 {
@@ -2851,10 +4080,10 @@ 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');
         return res.status(200).json({ ok: false, error: 'account_not_matched', verdict });
       }
     }
@@ -2863,12 +4092,14 @@ 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');
     return res.status(200).json({ ok: true });
   }
 
@@ -2891,7 +4122,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
     }
 
     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, {
@@ -2938,12 +4169,131 @@ 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): Promise<void> {
+  const ts  = String(Math.floor(Date.now() / 1000));
+  const sig = createHmac('sha256', WEBHOOK_SECRET).update(\`\${ts}.\${rawBody}\`).digest('hex');
+  let dispatchId = '';
+  try {
+    dispatchId = String((JSON.parse(rawBody) as { dispatch_id?: unknown }).dispatch_id ?? '');
+  } catch { /* the handler will reject it as bad JSON, which is the right answer */ }
+
+  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.
+ */
+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. Read by the dashboard. */
+export { pendingConfirmCount };
+
 // 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 };
@@ -3106,8 +4456,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
 
@@ -3135,6 +4651,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
@@ -7990,7 +9523,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto = require("crypto");
-var PKG_VERSION = true ? "2.1.1" : "dev";
+var PKG_VERSION = true ? "2.1.3" : "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");