@oneaddress/setup 2.4.0 → 2.5.0

package/dist/index.js

@@ -856,7 +856,7 @@ var _R = ["\u2588\u2588\u2588\u2588\u2588\u2588 ", "\u2588\u2588   \u2588\u2588"
 var _S = [" \u2588\u2588\u2588\u2588\u2588\u2588", "\u2588\u2588     ", "\u2588\u2588     ", " \u2588\u2588\u2588\u2588\u2588 ", "     \u2588\u2588", "     \u2588\u2588", "\u2588\u2588\u2588\u2588\u2588\u2588 "];
 var ONE_ROWS = Array.from({ length: 7 }, (_3, i) => [_O[i], _N[i], _E[i]].join(" "));
 var ADDR_ROWS = Array.from({ length: 7 }, (_3, i) => [_A[i], _D2[i], _D2[i], _R[i], _E[i], _S[i], _S[i]].join(" "));
-var WIZARD_VERSION = true ? "2.4.0" : "?";
+var WIZARD_VERSION = true ? "2.5.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -983,6 +983,7 @@ data.db-shm
     "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",
+    "show":     "tsx scripts/show.ts",
     "test":     "tsx scripts/test.ts"
   },
   "dependencies": {
@@ -1011,7 +1012,8 @@ data.db-shm
   "partnerId": "%%PARTNER_ID%%",
   "oneAddressApi": "%%ONEADDRESS_API%%",
   "verifiesAccountReference": %%VERIFIES_ACCOUNT_REFERENCE%%,
-  "mode": "%%RECEIVER_MODE%%"
+  "mode": "%%RECEIVER_MODE%%",
+  "publicUrl": "%%WEBHOOK_URL%%"
 }
 `
     },
@@ -1711,7 +1713,8 @@ import { formatLine, report, type ReportLine } from './report.js';
 // reads, with nothing here to change.
 import { store } from './store.js';
 import { pendingConfirmCount } from './confirm-queue.js';
-import { exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { dismissHeld, exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { reachability } from './reachable.js';
 
 /** blessed takes colours as strings; these mirror the site's palette. */
 const AMBER = HEX.amber.toLowerCase();
@@ -1870,6 +1873,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     // nor UNENCRYPTED is true and both would mislead. The receiver holds
     // ciphertext it cannot open; the customers live in the partner's own
     // database, behind their own controls.
+    const reach = reachability();
     const vault = inbox
       ? \`{\${AMBER}-fg}{bold}NONE (inbox){/}\`
       : store.encrypted
@@ -1883,7 +1887,16 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       // 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()}{/}\`,
+      \`{\${DIM}-fg}on file{/} {\${CREAM}-fg}\${onFile === null ? '\u2014' : onFile.toLocaleString()}{/}\`
+      // REACHABLE IS DRAWN ONLY WHEN IT IS KNOWN, and that is the point of the
+      // third state. A receiver with no publicUrl configured cannot answer the
+      // question, and a green tick or a red cross would both be inventing an
+      // answer. Silence is the honest rendering of "not checked".
+      + (reach.state === 'unknown'
+        ? ''
+        : reach.state === 'reachable'
+          ? \`   {\${DIM}-fg}reachable{/} {green-fg}{bold}YES{/}\`
+          : \`   {\${DIM}-fg}reachable{/} {red-fg}{bold}NO{/}\`),
     );
   }
 
@@ -1947,7 +1960,14 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
 
   function renderFaults(): void {
     const held = heldCount();
-    const show = held > 0;
+    const reach = reachability();
+    // UNREACHABLE IS A FAULT, and it belongs in this panel rather than only in
+    // the status bar, because it is the one failure where NOTHING ELSE MOVES.
+    // A wrong key at least produces held dispatches to look at; a stopped
+    // tunnel produces a receiver that looks perfectly healthy and simply never
+    // hears from anyone again.
+    const unreachable = reach.state === 'unreachable';
+    const show = held > 0 || unreachable;
     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
@@ -1962,6 +1982,15 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     // 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.
+    if (unreachable && held === 0) {
+      faultBox.setContent(
+        \`\\n  {bold}Nothing on the internet is reaching this receiver.{/bold}\\n\` +
+        \`  {red-fg}\${esc(reach.state === 'unreachable' ? reach.detail : '')}{/}\\n\` +
+        \`  {\${DIM}-fg}Dispatches cannot arrive while this is true. Check your tunnel is still running.{/}\`,
+      );
+      return;
+    }
+
     const lines = heldSummary().slice(0, 2).map((l) => \`  {red-fg}\${esc(l)}{/}\`);
     faultBox.setContent(
       \`\\n  {bold}\${held}{/bold} dispatch(es) arrived that this receiver could not open. \` +
@@ -1969,7 +1998,8 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       lines.join('\\n') + '\\n' +
       (replayNote
         ? \`  {\${AMBER}-fg}\${esc(replayNote)}{/}\`
-        : \`  {\${DIM}-fg}Fix the cause, then{/} {\${AMBER}-fg}[r]{/} {\${DIM}-fg}to apply,{/} {\${AMBER}-fg}[e]{/} {\${DIM}-fg}to export the list.{/}\`),
+        : \`  {\${DIM}-fg}Fix the cause, then{/} {\${AMBER}-fg}[r]{/} {\${DIM}-fg}to apply,{/} {\${AMBER}-fg}[e]{/} {\${DIM}-fg}to export,{/} \` +
+          \`{\${AMBER}-fg}[d]{/} {\${DIM}-fg}to dismiss.{/}\`),
     );
   }
 
@@ -2003,7 +2033,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       \`{red-fg}failed{/} {bold}\${failed}{/bold}   \` +
       awaitingYou +
       \`{\${awaitingColour}-fg}awaiting confirm{/} {bold}\${awaiting}{/bold}\` +
-      \`{|}{\${DIM}-fg}\${onReplay ? '[r] replay  ' : ''}[e] export  [q] quit{/}  \`,
+      \`{|}{\${DIM}-fg}\${onReplay ? '[r] replay  ' : ''}[e] export  [d] dismiss  [q] quit{/}  \`,
     );
   }
 
@@ -2079,6 +2109,58 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     redraw();
   });
 
+  // [d] DISMISSES. TWO PRESSES, and the first one only asks.
+  //
+  // WHY THIS KEY EXISTS AT ALL. The conformance suite deliberately sends a
+  // dispatch this receiver cannot open (check-11: a session key wrapped to a
+  // throwaway key pair) and passes the receiver for HOLDING it. So passing
+  // conformance leaves a red fault panel up permanently, on a receiver that is
+  // working correctly, with nothing on screen that clears it. Reported from a
+  // real run: "I do wish the conformance wouldn't come up as a fault."
+  //
+  // WHY THE RECEIVER DOES NOT JUST RECOGNISE THE PROBE. Everything that
+  // identifies one is chosen by the sender. See the \`dismissed_at\` docstring in
+  // \`quarantine.ts\`: suppressing a fault panel on a sender-supplied value hides
+  // real held dispatches from the one person whose job is to notice them.
+  //
+  // IRREVERSIBLE, SO IT IS CONFIRMED. Dismissal discards the held payload, which
+  // is the point (see \`dismissHeld\`) and also means a mistaken press cannot be
+  // undone by pressing [r]. The count is named in the question rather than after
+  // it, because "dismiss 47" and "dismiss 1" are different decisions.
+  //
+  // THE ARM REMEMBERS A COUNT, NOT A BOOLEAN, and that is the load-bearing part
+  // rather than a nicety. A boolean armed at 14:02 is still armed at 16:30, so a
+  // partner who armed it against one conformance probe and wandered off would
+  // come back and dismiss whatever real backlog had arrived in between - with a
+  // single keystroke, discarding the payloads. Confirming only the exact set
+  // that was described makes the question and the action the same question.
+  let dismissArmedFor: number | null = null;
+  screen.key(['d'], () => {
+    const held = heldCount();
+    if (held === 0) {
+      dismissArmedFor = null;
+      replayNote = 'Nothing held, so nothing to dismiss.';
+      redraw();
+      return;
+    }
+    if (dismissArmedFor !== held) {
+      const changed = dismissArmedFor !== null;
+      dismissArmedFor = held;
+      replayNote = (changed ? \`That changed: \${held} held now. \` : '') +
+        \`Press [d] again to dismiss \${held}: not applied, payloads discarded, cannot be undone.\`;
+      redraw();
+      return;
+    }
+    dismissArmedFor = null;
+    try {
+      const n = dismissHeld();
+      replayNote = \`Dismissed \${n}. Nothing left held.\`;
+    } catch (err) {
+      replayNote = \`Dismiss failed: \${err instanceof Error ? err.message : String(err)}\`;
+    }
+    redraw();
+  });
+
   screen.key(['q', 'C-c'], () => {
     detach();
     screen.destroy();
@@ -2141,6 +2223,10 @@ import { printBanner } from './brand.js';
 // after the passphrase is resolved. \`config.js\` reads a JSON file and the
 // environment and touches neither.
 import { config } from './config.js';
+// Same rule as \`config.js\`: \`unlock.js\` deliberately does not import the
+// database, so it can be loaded statically here and still run before the keys
+// are derived. See its own header.
+import { ask, databaseIsLocked } from './unlock.js';
 import { PassphraseRequiredError, WrongPassphraseError } from './vault.js';
 
 /**
@@ -2163,122 +2249,6 @@ const headless =
   process.env.ONEADDRESS_HEADLESS === '1' ||
   !process.stdout.isTTY;
 
-/**
- * Has this database already been locked?
- *
- * Asked BEFORE the passphrase, and without one, so the prompt can say which of
- * two completely different things it is doing. \`db_meta.verifier\` is written the
- * first time a passphrase is set, so its presence is the whole answer.
- *
- * Read through its own connection rather than importing \`db.ts\`, which derives
- * its keys the moment it is imported and would therefore have to run BEFORE we
- * know what to ask for.
- */
-async function databaseIsLocked(): Promise<boolean> {
-  try {
-    const { DatabaseSync } = await import('node:sqlite');
-    const { join } = await import('node:path');
-    const path = process.env.DB_PATH ?? join(process.cwd(), 'data.db');
-    const db = new DatabaseSync(path, { readOnly: true });
-    try {
-      const row = db
-        .prepare("SELECT value FROM db_meta WHERE key = 'verifier'")
-        .get() as { value?: string } | undefined;
-      return Boolean(row?.value);
-    } finally {
-      db.close();
-    }
-  } catch {
-    // No file yet, or no db_meta table yet. Either way: not locked.
-    return false;
-  }
-}
-
-/**
- * Ask for a passphrase without echoing it to the screen.
- *
- * A passphrase typed in clear on a shared screen, in a screen-share, or into a
- * terminal that keeps scrollback is not much of a secret. readline echoes by
- * default, so its output hook is replaced for the duration of the question.
- *
- * Degrades to a visible prompt rather than failing: on a terminal where the
- * hook is not available, being asked in the clear beats not being asked.
- */
-async function ask(prompt: string): Promise<string> {
-  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();
-    };
-    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);
-  });
-}
 
 /**
  * Where the at-rest passphrase comes from.
@@ -2332,9 +2302,14 @@ async function resolvePassphrase(): Promise<string | null> {
   // credentials, so assuming exactly that is the natural reading. Reported as
   // confusing, and the confusion was ours.
   //
-  // It therefore leads with the decision, says plainly that the answer is
-  // INVENTED HERE, and names the three secrets it is not, because those are the
-  // three things a partner at this point in setup might reach for.
+  // It therefore leads with the decision and says plainly that the answer is
+  // INVENTED HERE. It used to go on to name the three secrets it is NOT, which
+  // was accurate and was four more lines of denial in a prompt that is already
+  // the longest question in setup; reported as over-explained, and cut back to
+  // the three facts an answer depends on (new, what it protects, unrecoverable).
+  // The UNLOCK branch keeps its version of that list, because there the partner
+  // is being asked for a password they may not remember choosing and naming the
+  // wrong candidates is the whole help.
   // NOT ASKED IN INBOX MODE, because the honest answer to "protect your customer
   // records" is that there are none here: the connector holds them. The
   // database in this mode carries dispatch ciphertext - already encrypted to a
@@ -2354,14 +2329,10 @@ async function resolvePassphrase(): Promise<string | null> {
   }
 
   process.stdout.write('\\n  \u2500\u2500 Protect this receiver\\'s customer database? \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\n\\n');
-  process.stdout.write('  MAKE UP A NEW PASSWORD now. You are NOT being asked for anything\\n');
-  process.stdout.write('  you already have: not your Webhook signing secret, not your ECDH\\n');
-  process.stdout.write('  private key, not your OneAddress sign-in. This one is invented\\n');
-  process.stdout.write('  here and used only on this machine.\\n\\n');
-  process.stdout.write('  It encrypts the customer records this receiver keeps in data.db.\\n');
-  process.stdout.write('  OneAddress never sees it and cannot reset it, so if you lose it\\n');
-  process.stdout.write('  those records cannot be read again.\\n\\n');
-  process.stdout.write('  OPTIONAL. Press Enter to skip and leave the database readable.\\n');
+  process.stdout.write('  MAKE UP A NEW PASSWORD. Invented here, not one you already\\n');
+  process.stdout.write('  hold. It encrypts the customer records this receiver keeps in\\n');
+  process.stdout.write('  data.db. OneAddress never sees it and cannot reset it.\\n\\n');
+  process.stdout.write('  Optional. Press Enter to skip and leave the database readable.\\n');
   // ACCURATE ABOUT "LATER", because the obvious reading is wrong. Setting a
   // password afterwards works and the receiver reports itself encrypted, but
   // rows written before it stay in the clear until something rewrites them -
@@ -2758,7 +2729,7 @@ import express, { type Request, type Response } from 'express';
 import rateLimit from 'express-rate-limit';
 import { timingSafeEqual } from 'node:crypto';
 import { report } from './report.js';
-import { acknowledge, drawable, markDrawn, type InboxOutcome } from './inbox.js';
+import { acknowledge, drawable, hold, markDrawn, type InboxOutcome } from './inbox.js';
 
 const TOKEN = process.env.CONNECTOR_TOKEN ?? '';
 /**
@@ -2851,18 +2822,41 @@ export function startDrawApi(): { port: number } | null {
    * confirm, which is the honest answer when the partner's own system refused
    * the change: the consumer is told it did not land rather than being told it
    * did.
+   *
+   * \`held\` QUEUES NOTHING, and that is the whole point of it. It means the
+   * connector could not OPEN the dispatch, which is a fact about a key rather
+   * than about the consumer's record - and a \`failed\` confirm is read as the
+   * latter all the way down: \`partner_failed\`, terminal, refund denied. The
+   * item stays unacknowledged so the next draw retries it once the key is
+   * fixed. See \`hold\` in inbox.ts for why nothing else recovers this.
    */
   app.post('/ack', (req: Request, res: Response) => {
     if (!authorised(req, res)) return;
     const body = req.body as { id?: unknown; outcome?: unknown; detail?: unknown };
     const id = typeof body.id === 'string' ? body.id : '';
-    const outcome: InboxOutcome | null =
-      body.outcome === 'applied' || body.outcome === 'failed' ? body.outcome : null;
+    const outcome: InboxOutcome | 'held' | null =
+      body.outcome === 'applied' || body.outcome === 'failed' || body.outcome === 'held'
+        ? body.outcome
+        : null;
     if (!id || !outcome) {
-      return res.status(400).json({ error: 'id and outcome (applied|failed) are required' });
+      return res.status(400).json({ error: 'id and outcome (applied|failed|held) are required' });
     }
     const detail = typeof body.detail === 'string' ? body.detail : null;
 
+    // HELD RETURNS BEFORE \`acknowledge\`, so there is no path from here to a
+    // confirm. Ordering rather than a flag: a held item that fell through to
+    // the code below would be stamped terminal and reported to OneAddress as
+    // the consumer's problem, which is the defect this exists to remove.
+    if (outcome === 'held') {
+      const heldResult = hold(id, detail, LEASE_SECONDS);
+      if (!heldResult) return res.status(404).json({ error: 'unknown or already acknowledged id' });
+      return res.json({
+        ok: true, held: true,
+        attempts: heldResult.attempts,
+        retryInSeconds: heldResult.retryInSeconds,
+      });
+    }
+
     const result = acknowledge(id, outcome, detail);
     if (!result) return res.status(404).json({ error: 'unknown id' });
     if (result.alreadyAcknowledged) {
@@ -2962,9 +2956,16 @@ export function setAcknowledgementHandler(
  * the claim has to become atomic, the way \`confirm-queue.ts\` already does it.
  * Written down because a lease LOOKS like it handles concurrency and does not.
  */
-import db from './db.js';
+import db, { ensureColumn } from './db.js';
 import { report } from './report.js';
 
+/**
+ * The connector's TERMINAL verdicts. Both end the item and both tell OneAddress.
+ *
+ * \`held\` is deliberately NOT one of these, and lives in its own function. See
+ * \`hold\` below for why a dispatch the connector could not OPEN must never
+ * become one of these two.
+ */
 export type InboxOutcome = 'applied' | 'failed';
 
 db.exec(\`
@@ -2983,6 +2984,30 @@ db.exec(\`
     ON inbox(applied_at, drawn_at, received_at);
 \`);
 
+/**
+ * Why a held item needs its own two columns, matching \`quarantine\`'s.
+ *
+ * A dispatch the connector cannot OPEN is not finished with, so it keeps
+ * \`applied_at IS NULL\` and stays in the undrawn count. But an operator then
+ * needs to know it is BLOCKED rather than merely queued, and by what: without
+ * these the dashboard can say a number and nothing else, and the connector's
+ * message - which names the exact environment variable to set - is only in a
+ * log somebody has to still have.
+ *
+ * Same names as the quarantine's, because it is the same idea one process over
+ * and a second vocabulary for it would be a second thing to learn.
+ */
+ensureColumn('inbox', 'attempts', 'INTEGER NOT NULL DEFAULT 0');
+ensureColumn('inbox', 'last_error', 'TEXT');
+
+/**
+ * First retry for a held item, multiplied by the attempt count and capped at
+ * the lease. Thirty seconds because the overwhelming case is a partner who has
+ * just corrected a key and restarted the connector, and making them wait out a
+ * lease built for crash recovery would be answering a question nobody asked.
+ */
+const HELD_RETRY_BASE_SECONDS = 30;
+
 export interface AcceptInput {
   key: string;
   dispatchId: string | null;
@@ -3064,6 +3089,110 @@ export function acknowledge(
   return { dispatchId: row.dispatch_id, alreadyAcknowledged: false };
 }
 
+/**
+ * The connector could not OPEN this one, so it is not finished with.
+ *
+ * ## Why this is not \`failed\`
+ *
+ * \`failed\` is a statement about the CONSUMER'S RECORD - the partner's system
+ * received the change and refused it - and OneAddress reads it exactly that
+ * way. \`/api/confirm\` resolves every non-success to \`partner_failed\`, that row
+ * is terminal (a later SUCCESSFUL confirm cannot overwrite it), and the refund
+ * classifier maps it to \`no_match\`: "the partner received it and said no", so
+ * the refund is DENIED and the consumer is emailed that it did not land.
+ *
+ * "I could not read it" is not that statement. It is a fact about the
+ * partner's key configuration and has nothing to do with the consumer. Sending
+ * it as \`failed\` charged a consumer five dollars, told them a provider had
+ * rejected them, and refused them a refund, because a key was wrong in a
+ * process they have never heard of.
+ *
+ * ## Why there is no retry to fall back on
+ *
+ * \`draw-loop.ts\` used to reason that "OneAddress's own retry of the dispatch is
+ * the recovery path". That is true in write-through, where an unopenable
+ * dispatch answers 422 and the dispatch row stays \`failed\` for the retry cron
+ * to pick up. It is FALSE here, for the reason this mode exists: the receiver
+ * already answered 200 at arrival, so the dispatch row is \`delivered\`, and
+ * \`retry-webhooks\` only ever re-sends rows that are \`pending\` or \`failed\`.
+ * Nothing retries. The confirm was the only remaining signal and it was being
+ * spent on a verdict that was not true.
+ *
+ * ## What happens instead
+ *
+ * The item stays unacknowledged, so it stays in the undrawn count, which the
+ * dashboard already reports as a fault - and that is the behaviour recorded in
+ * the new-matter register for this mode: an undrawn update is held INDEFINITELY
+ * and reported as a fault, deliberately unlike the quarantine's 30-day purge,
+ * because an undrawn update is a consumer whose address did not land and ageing
+ * it out loses it silently.
+ *
+ * Re-stamping \`drawn_at\` is the backoff and costs no new mechanism: \`drawable\`
+ * re-offers an item once its stamp is older than the lease, so the next attempt
+ * is one lease away and the poll loop cannot spin on a key that is still wrong.
+ * When the key is fixed the next draw applies it, with no operator command -
+ * which is the half that \`[r]\` has to be pressed for in write-through.
+ *
+ * Returns null for an unknown id or one already terminally acknowledged, the
+ * same tolerance \`acknowledge\` has and for the same reason.
+ */
+export function hold(
+  id: string,
+  detail: string | null,
+  leaseSeconds: number,
+): { attempts: number; retryInSeconds: number } | null {
+  const row = db.prepare(
+    'SELECT applied_at, attempts FROM inbox WHERE id = ?',
+  ).get(id) as { applied_at: string | null; attempts: number } | undefined;
+  if (!row) return null;
+  if (row.applied_at !== null) return null;
+
+  const attempts = (row.attempts ?? 0) + 1;
+  // \u2500\u2500 THE BACKOFF IS NOT THE LEASE, AND THAT IS THE POINT \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  //
+  // The lease is 300s and is generous ON PURPOSE: re-offering a DRAWN item too
+  // early risks applying the same update twice. A held item carries none of
+  // that risk, because nothing was applied - it could not even be opened. So
+  // reusing the lease would make a partner who has just fixed their key wait
+  // five minutes for a safety property that is not in play.
+  //
+  // \`drawable\` re-offers a row once \`drawn_at < now - lease\`, so a stamp of
+  // \`now - lease + backoff\` becomes drawable in exactly \`backoff\` seconds.
+  // That is the whole mechanism: no column, no second query, no timer. Pinned
+  // by a test that checks it is NOT drawable before the backoff and IS after,
+  // because arithmetic written backwards still produces a plausible timestamp.
+  //
+  // Capped at the lease so a repeatedly-failing item can never retry FASTER
+  // than a crashed connector's item, which would be the wrong way round.
+  const retryInSeconds = Math.min(HELD_RETRY_BASE_SECONDS * attempts, leaseSeconds);
+  const stamp = new Date(Date.now() - leaseSeconds * 1000 + retryInSeconds * 1000).toISOString();
+  db.prepare(
+    'UPDATE inbox SET attempts = ?, last_error = ?, drawn_at = ? WHERE id = ?',
+  ).run(attempts, detail?.slice(0, 500) ?? null, stamp, id);
+  report.warn(
+    \`[inbox] \${id} HELD after \${attempts} attempt(s), retrying in \${retryInSeconds}s, not failed: \` +
+    \`\${detail ?? 'the connector could not open it'}\`,
+  );
+  return { attempts, retryInSeconds };
+}
+
+/**
+ * The held items, for the dashboard's faults band.
+ *
+ * Separate from \`undrawnCount\` because the two mean different things to an
+ * operator: undrawn is "your connector has not got to it yet", held is "your
+ * connector tried and cannot". Only the second one needs somebody to do
+ * something, and it is the one carrying the message that says what.
+ */
+export function heldItems(): { id: string; attempts: number; lastError: string | null }[] {
+  return db.prepare(
+    \`SELECT id, attempts, last_error AS lastError
+       FROM inbox
+      WHERE applied_at IS NULL AND attempts > 0
+      ORDER BY received_at\`,
+  ).all() as unknown as { id: string; attempts: number; lastError: string | null }[];
+}
+
 /** How many updates are sitting here unapplied. Shown as a fault when non-zero. */
 export function undrawnCount(): number {
   const row = db.prepare(
@@ -3297,6 +3426,38 @@ export function dispatchKey(dispatchId: string | null, rawBody: string): string
  */
 ensureColumn('quarantine', 'attempts', 'INTEGER NOT NULL DEFAULT 0');
 
+/**
+ * When the operator decided this one is not going to be applied.
+ *
+ * ## Why a dashboard needs this at all
+ *
+ * The conformance suite sends a dispatch that CANNOT be opened, deliberately:
+ * check-11 wraps a session key to a throwaway key pair and passes only if the
+ * receiver reports the failure instead of answering \`200 { ok: true }\`. Holding
+ * it is the correct behaviour and is how the check is passed. The receiver then
+ * draws a red FAULTS panel about it for the rest of the database's life, and a
+ * partner who has just been told they passed is looking at a permanent fault
+ * they cannot clear. Reported from a real run.
+ *
+ * ## Why the receiver does NOT recognise the probe itself
+ *
+ * The tempting fix is to spot the probe and not count it. Everything that
+ * identifies one comes from the SENDER: the dispatch id is a header, and the
+ * ciphertext is opaque by construction. Suppressing an operator's fault panel on
+ * a value the sender chose is a way to hide a real held dispatch from the person
+ * whose job is to notice it, and it would be reachable by anyone holding the
+ * webhook secret. The signal stays; the OPERATOR gets a way to answer it.
+ *
+ * ## Why the payload goes with it
+ *
+ * Dismissing says "I am not applying this". A held payload is a consumer's
+ * encrypted address sitting on a third party's disk, kept only because applying
+ * it later is still on the table. Once it is not, the reason to keep it is gone,
+ * so \`raw_body\` is emptied in the same statement. That also makes dismissal
+ * mean what it says: \`[r]\` cannot quietly bring it back.
+ */
+ensureColumn('quarantine', 'dismissed_at', 'TEXT');
+
 export interface QuarantineInput {
   dispatchId: string | null;
   event: string;
@@ -3360,7 +3521,7 @@ export function heldDispatches(limit = 50): HeldDispatch[] {
     \`SELECT id, dispatch_id, event, reason, key_id, raw_body, detail,
             received_at, last_error, attempts
        FROM quarantine
-      WHERE replayed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL
       ORDER BY received_at
       LIMIT ?\`,
   ).all(limit) as unknown as HeldDispatch[];
@@ -3369,7 +3530,7 @@ export function heldDispatches(limit = 50): 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',
+    'SELECT count(*) AS n FROM quarantine WHERE replayed_at IS NULL AND dismissed_at IS NULL',
   ).get() as { n: number };
   return row.n;
 }
@@ -3386,7 +3547,7 @@ export function heldSummary(): string[] {
     \`SELECT reason, key_id, count(*) AS n,
             max(attempts) AS tries, min(received_at) AS oldest
        FROM quarantine
-      WHERE replayed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL
       GROUP BY reason, key_id
       ORDER BY n DESC\`,
   ).all() as unknown as {
@@ -3430,6 +3591,38 @@ export function markReplayFailed(id: string, error: string): void {
     .run(error.slice(0, 500), id);
 }
 
+/**
+ * The operator's answer to the fault panel: not applying these, stop counting them.
+ *
+ * Takes everything currently held rather than one row, because the panel groups
+ * by cause and offers no way to point at a single dispatch. The realistic use is
+ * one decision about one cause, which is the shape the panel already shows.
+ *
+ * \`raw_body\` is emptied in the same statement. See the \`dismissed_at\` docstring
+ * for why: once the operator has said it will not be applied, a consumer's
+ * encrypted address is being kept for no reason, and a dismissal that leaves the
+ * payload behind is one \`[r]\` away from not being a dismissal.
+ *
+ * The row itself STAYS. It is the record that a dispatch arrived and was
+ * consciously dropped, which is the fact an audit wants, and \`purgeQuarantine\`
+ * ages it out on the same window as everything else.
+ */
+export function dismissHeld(): number {
+  const info = db.prepare(
+    \`UPDATE quarantine
+        SET dismissed_at = ?, raw_body = ''
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL\`,
+  ).run(new Date().toISOString());
+  const n = Number(info.changes ?? 0);
+  if (n > 0) {
+    report.warn(
+      \`[quarantine] dismissed \${n} held dispatch(es). They will NOT be applied and their \` +
+      'payloads have been discarded. OneAddress was already told each one failed.',
+    );
+  }
+  return n;
+}
+
 /**
  * Drop held payloads past the retention window, replayed or not.
  *
@@ -3915,6 +4108,16 @@ export type ReceiverConfig = {
   oneAddressApi:            string;
   verifiesAccountReference: boolean;
   mode:                     ReceiverMode;
+  /**
+   * The webhook URL registered with OneAddress: where dispatches actually
+   * arrive from the internet.
+   *
+   * Written by the wizard, which is the only thing that knows it - the receiver
+   * binds a local port and has no idea what hostname reaches it. Empty disables
+   * the reachability check rather than guessing, because a wrong URL here would
+   * report a healthy receiver as unreachable, which is worse than silence.
+   */
+  publicUrl:                string;
 };
 
 const DEFAULTS: ReceiverConfig = {
@@ -3929,6 +4132,8 @@ const DEFAULTS: ReceiverConfig = {
   // running and a key living somewhere else; a receiver that silently switched
   // into it would accept dispatches nothing ever collects.
   mode: 'write-through',
+  // No guess. See the field's docstring.
+  publicUrl: '',
 };
 
 function parseMode(value: unknown): ReceiverMode | undefined {
@@ -3947,6 +4152,7 @@ function loadConfigFile(): Partial<ReceiverConfig> {
     if (typeof parsed.partnerId === 'string')                out.partnerId = parsed.partnerId;
     if (typeof parsed.oneAddressApi === 'string')            out.oneAddressApi = parsed.oneAddressApi;
     if (typeof parsed.verifiesAccountReference === 'boolean') out.verifiesAccountReference = parsed.verifiesAccountReference;
+    if (typeof parsed.publicUrl === 'string')                 out.publicUrl = parsed.publicUrl;
     const mode = parseMode(parsed.mode);
     if (mode) out.mode = mode;
     return out;
@@ -3970,6 +4176,7 @@ export const config: ReceiverConfig = {
   // up as "not the mode I asked for" rather than as a receiver that will not
   // start. Silent is the thing to avoid, not strict.
   mode: parseMode(process.env.RECEIVER_MODE) ?? fromFile.mode ?? DEFAULTS.mode,
+  publicUrl: stripTrailingSlash(process.env.PUBLIC_URL || fromFile.publicUrl || DEFAULTS.publicUrl),
 };
 
 report.info(
@@ -3977,6 +4184,188 @@ report.info(
   ', oneAddressApi=' + config.oneAddressApi +
   ', verifiesAccountReference=' + config.verifiesAccountReference + ')',
 );
+`
+    },
+    {
+      name: "src/reachable.ts",
+      content: `/**
+ * IS ANYTHING ON THE INTERNET STILL REACHING THIS RECEIVER?
+ *
+ * ## The problem, and why the receiver cannot simply notice
+ *
+ * A partner running behind a tunnel stops the tunnel - closes the laptop, ends
+ * the terminal, lets the trial lapse - and the receiver notices nothing. That is
+ * not an oversight: the tunnel DIALS IN to this process. Nothing here holds a
+ * connection outward, so from inside, "the tunnel is down" and "nobody sent me
+ * anything" are the same observation, which is silence. And silence is not a
+ * fault: a small partner legitimately goes days between dispatches, so a
+ * watchdog that fired on quiet would cry wolf at exactly the partners least able
+ * to tell the difference.
+ *
+ * Meanwhile OneAddress is failing to deliver, marking the endpoint unhealthy,
+ * and the only place that says so is a portal nobody has open.
+ *
+ * ## How this answers it
+ *
+ * The receiver fetches ITS OWN PUBLIC URL and checks that a nonce minted at
+ * startup comes back. Only this running process knows that value, which is what
+ * makes the answer unambiguous.
+ *
+ * "DID ANYTHING ANSWER" IS NOT GOOD ENOUGH, and that is the whole reason for
+ * the nonce. A stopped Cloudflare tunnel does not refuse the connection: the
+ * edge is still there and serves an error page (1033, or a 502). That is a
+ * perfectly valid HTTP response, so a check written \`if (res.ok)\` - or even
+ * \`if (res.status < 500)\` - reports a dead tunnel as healthy. A check that
+ * demands the nonce cannot be satisfied by anything except this process.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not fail the receiver, retry aggressively, or call OneAddress. It is
+ * a statement on the dashboard and a log line. A receiver that shut itself down
+ * because it could not see itself would turn a DNS blip into an outage, and the
+ * failure it is reporting is one only a human can fix.
+ *
+ * It is also not a security control. The nonce proves identity of the process,
+ * not authorisation: the endpoint returns it to anyone who asks. It is a random
+ * value with no meaning outside this check, and knowing it grants nothing - the
+ * webhook still requires a valid HMAC.
+ */
+import { randomBytes } from 'node:crypto';
+import { config } from './config.js';
+import { report } from './report.js';
+
+/** Minted once per process. See the header: this is what makes the answer
+ *  unambiguous, and it is deliberately not a secret. */
+export const ALIVE_NONCE = randomBytes(16).toString('hex');
+
+/** The path the check hits. Deliberately NOT \`/webhook\`: that is POST-only and
+ *  would 404 or 405 through a perfectly healthy tunnel. */
+export const ALIVE_PATH = '/oa-receiver-alive';
+
+export type Reachability =
+  | { state: 'unknown';     detail: string }
+  | { state: 'reachable';   checkedAt: string }
+  | { state: 'unreachable'; detail: string; since: string };
+
+let current: Reachability = { state: 'unknown', detail: 'not checked yet' };
+
+/** What the dashboard renders. Never throws. */
+export function reachability(): Reachability {
+  return current;
+}
+
+/**
+ * The ORIGIN to probe, or null when there is nothing usable to probe.
+ *
+ * TWO THINGS THIS FIXES, both found by reading the value the wizard actually
+ * writes rather than the one this function wanted.
+ *
+ * 1. \`publicUrl\` is the REGISTERED WEBHOOK URL, so it ends in \`/webhook\`.
+ *    Appending the probe path to it gives \`\u2026/webhook/oa-receiver-alive\`, which
+ *    404s through a perfectly healthy tunnel and would report every working
+ *    receiver as unreachable. The origin is what is wanted.
+ * 2. The scaffold substitutes a PLACEHOLDER (\`<your-webhook-url>\`) when setup
+ *    ran without a registered URL. Probing that fails forever, so a partner who
+ *    skipped registration would get a permanent red panel about a fault they do
+ *    not have.
+ *
+ * Anything that is not an absolute http(s) URL therefore reads as NOT
+ * CONFIGURED rather than as unreachable: the failure mode to avoid here is
+ * crying wolf, since the whole value of the check is that it is believed.
+ */
+export function probeOrigin(raw: string): string | null {
+  if (!raw) return null;
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+    return u.origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One check. Returns the new state rather than only setting it, so a test can
+ * drive it directly without reaching into module state.
+ */
+export async function checkReachable(fetchImpl: typeof fetch = fetch): Promise<Reachability> {
+  const origin = probeOrigin(config.publicUrl);
+  if (!origin) {
+    current = {
+      state: 'unknown',
+      detail: config.publicUrl
+        ? 'publicUrl in oneaddress.config.json is not a usable http(s) URL'
+        : 'no publicUrl in oneaddress.config.json',
+    };
+    return current;
+  }
+
+  const url = \`\${origin}\${ALIVE_PATH}\`;
+  const since = current.state === 'unreachable' ? current.since : new Date().toISOString();
+
+  try {
+    const res = await fetchImpl(url, {
+      method: 'GET',
+      // Short: this is a liveness probe, not a download. A tunnel that takes
+      // longer than this to answer is already failing dispatches, which time
+      // out on OneAddress's side too.
+      signal: AbortSignal.timeout(10_000),
+      headers: { 'cache-control': 'no-cache' },
+    });
+    const body = await res.text().catch(() => '');
+    // THE NONCE, not the status. See the header: a stopped tunnel answers with
+    // a real HTTP response carrying an error page.
+    if (body.trim() === ALIVE_NONCE) {
+      current = { state: 'reachable', checkedAt: new Date().toISOString() };
+      return current;
+    }
+    current = {
+      state: 'unreachable',
+      detail: \`\${url} answered HTTP \${res.status} but not from this receiver (tunnel down, or the URL points elsewhere)\`,
+      since,
+    };
+  } catch (err) {
+    current = {
+      state: 'unreachable',
+      detail: \`\${url} could not be reached: \${err instanceof Error ? err.message : String(err)}\`,
+      since,
+    };
+  }
+  return current;
+}
+
+/**
+ * Check on a timer, and say so ONCE per transition rather than every tick.
+ *
+ * A line every five minutes for a tunnel that has been down all night is how a
+ * log stops being read. The transition is the news.
+ */
+export function startReachabilityWatch(everyMs = 5 * 60_000): NodeJS.Timeout | null {
+  if (!probeOrigin(config.publicUrl)) {
+    report.info('[reachable] no usable publicUrl configured, so this receiver cannot check whether the internet can reach it.');
+    return null;
+  }
+  let last: Reachability['state'] = 'unknown';
+  const tick = (): void => {
+    void checkReachable().then((r) => {
+      if (r.state === last) return;
+      last = r.state;
+      if (r.state === 'unreachable') {
+        report.error(\`[reachable] NOTHING IS REACHING THIS RECEIVER. \${r.detail}. Dispatches cannot arrive while this is true.\`);
+      } else if (r.state === 'reachable') {
+        report.info('[reachable] your public URL reaches this receiver.');
+      }
+    });
+  };
+  // A first check soon after startup, not immediately: a tunnel started
+  // alongside the receiver needs a moment before it answers, and reporting it
+  // down on second one would be wrong every single time.
+  const first = setTimeout(tick, 15_000);
+  first.unref?.();
+  const timer = setInterval(tick, everyMs);
+  timer.unref?.();
+  return timer;
+}
 `
     },
     {
@@ -4531,6 +4920,66 @@ export function customerCount(): number {
   return (db.prepare('SELECT COUNT(*) AS n FROM customers').get() as { n: number }).n;
 }
 
+/** One applied change: what this receiver held before, and what it holds now. */
+export interface AddressChange {
+  account_number: string;
+  name: string;
+  prev_address: Address | null;
+  address: Address;
+  recorded_at: string;
+}
+
+/**
+ * The applied changes, newest first, decrypted and joined back to the customer.
+ *
+ * ## Why this is exported rather than left to \`sqlite3\`
+ *
+ * Because \`sqlite3 data.db\` cannot answer it. Every text column here is
+ * AES-GCM ciphertext whenever the database has a password, which is the state
+ * this receiver asks for on its first run and reports in green on the
+ * dashboard. So the one question a partner has after their first real dispatch
+ * - "show me it actually changed" - had no answer short of writing code against
+ * the store. The dashboard's LAST CHANGE panel shows the most recent one and
+ * nothing shows the rest.
+ *
+ * \`prev_address\` is NULL for a row written before the column existed
+ * (\`ensureColumn\` defaults it to \`'{}'\`, which decodes to an empty object, not
+ * to an address) and for the first change on an account that had no address on
+ * file. Those are different facts and both are honestly "nothing to compare
+ * against", so both come back as null rather than as an empty address.
+ */
+export function addressHistory(limit = 20): AddressChange[] {
+  const rows = db.prepare(
+    \`SELECT h.prev_address AS prev_address,
+            h.address      AS address,
+            h.recorded_at  AS recorded_at,
+            c.account_number AS account_number,
+            c.name           AS name
+       FROM address_history h
+       LEFT JOIN customers c ON c.account_key = h.account_key
+      ORDER BY h.id DESC
+      LIMIT ?\`,
+  ).all(limit) as unknown[];
+
+  return rows.map((raw) => {
+    const r = raw as Record<string, string | null>;
+    const prevJson = dec('address', r.prev_address);
+    let prev: Address | null = null;
+    try {
+      const parsed = prevJson ? JSON.parse(prevJson) as Address : null;
+      // \`{}\` is the column default, not an address anyone held.
+      prev = parsed && Object.keys(parsed).length > 0 ? parsed : null;
+    } catch { prev = null; }
+    return {
+      account_number: dec('account_number', r.account_number) ?? '(unknown)',
+      name:           dec('name', r.name) ?? '(unknown)',
+      prev_address:   prev,
+      address:        JSON.parse(dec('address', r.address) ?? '{}') as Address,
+      recorded_at:    r.recorded_at ?? '',
+    };
+  });
+}
+
 /** Is the file on disk protected? Surfaced in the dashboard, in both states. */
 export const storeEncrypted = encrypted;
 
@@ -4723,6 +5172,7 @@ import {
 // exporting a \`CustomerStore\` (see src/customer-store.ts) and nothing else in
 // the protocol layer changes.
 import { store as writeThroughStore } from './store.js';
+import { ALIVE_NONCE, ALIVE_PATH, startReachabilityWatch } from './reachable.js';
 import { ConnectorUnreachableError, connectorStore, setCurrentRawBody } from './connector-store.js';
 import { noteChange } from './tui.js';
 import { config } from './config.js';
@@ -5518,9 +5968,26 @@ app.get('/health', (_req, res) => res.json({
   encryptedAtRest: store.encrypted,
 }));
 
-app.listen(PORT, () =>
-  report.info(\`[server] OneAddress webhook server \u2192 http://localhost:\${PORT}/webhook\`),
-);
+/**
+ * The reachability probe's target. Returns this process's startup nonce as
+ * plain text, and nothing else.
+ *
+ * WHY A NONCE AND NOT \`/health\`. A stopped Cloudflare tunnel still ANSWERS -
+ * the edge serves a 1033 or a 502 error page - so a check that accepts any HTTP
+ * response reports a dead tunnel as healthy. Only this running process knows
+ * this value, so receiving it back is proof the whole path is open. See
+ * \`src/reachable.ts\`.
+ *
+ * NOT A SECRET, and nothing is gated on it: it proves which process answered,
+ * not who asked. The webhook still requires a valid HMAC.
+ */
+app.get(ALIVE_PATH, (_req, res) => res.type('text/plain').send(ALIVE_NONCE));
+
+app.listen(PORT, () => {
+  report.info(\`[server] OneAddress webhook server \u2192 http://localhost:\${PORT}/webhook\`);
+  // Started AFTER listen, or the first probe races the server it is probing.
+  startReachabilityWatch();
+});
 
 /**
  * Drain the confirm queue, forever.
@@ -5678,6 +6145,228 @@ export function dashboardStats(): {
 // there, so the port the UI claims is the port the server actually bound.
 export { PORT };
 export const PARTNER_NAME = process.env.PARTNER_NAME?.trim() || 'Your receiver';
+`
+    },
+    {
+      name: "src/unlock.ts",
+      content: `/**
+ * Opening a locked database: is it locked, and asking for the password.
+ *
+ * ## Why these two live in their own file
+ *
+ * Both are needed by \`src/index.ts\` (which prompts before starting the
+ * receiver) and by \`scripts/show.ts\` (which prompts before reading the roster),
+ * and a second copy of a masked-input routine is the last thing this codebase
+ * needs: the comment inside \`ask\` records TWO earlier versions that echoed the
+ * passphrase in clear, neither of which was caught by reading the code. One
+ * implementation, driven by one test.
+ *
+ * NOTHING HERE IMPORTS \`db.ts\`, and that is a constraint rather than tidiness.
+ * Importing the database derives its keys on import, so anything asking WHICH
+ * QUESTION TO PUT has to run first. \`databaseIsLocked\` therefore opens its own
+ * read-only connection.
+ */
+/**
+ * Has this database already been locked?
+ *
+ * Asked BEFORE the passphrase, and without one, so the prompt can say which of
+ * two completely different things it is doing. \`db_meta.verifier\` is written the
+ * first time a passphrase is set, so its presence is the whole answer.
+ *
+ * Read through its own connection rather than importing \`db.ts\`, which derives
+ * its keys the moment it is imported and would therefore have to run BEFORE we
+ * know what to ask for.
+ */
+export async function databaseIsLocked(): Promise<boolean> {
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const { join } = await import('node:path');
+    const path = process.env.DB_PATH ?? join(process.cwd(), 'data.db');
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+      const row = db
+        .prepare("SELECT value FROM db_meta WHERE key = 'verifier'")
+        .get() as { value?: string } | undefined;
+      return Boolean(row?.value);
+    } finally {
+      db.close();
+    }
+  } catch {
+    // No file yet, or no db_meta table yet. Either way: not locked.
+    return false;
+  }
+}
+
+/**
+ * Ask for a passphrase without echoing it to the screen.
+ *
+ * A passphrase typed in clear on a shared screen, in a screen-share, or into a
+ * terminal that keeps scrollback is not much of a secret. readline echoes by
+ * default, so its output hook is replaced for the duration of the question.
+ *
+ * Degrades to a visible prompt rather than failing: on a terminal where the
+ * hook is not available, being asked in the clear beats not being asked.
+ */
+export async function ask(prompt: string): Promise<string> {
+  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();
+    };
+    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);
+  });
+}
+`
+    },
+    {
+      name: "scripts/show.ts",
+      content: `/**
+ * Show what this receiver holds: the roster, and every change it has applied.
+ *
+ * Usage:
+ *   npm run show          \u2014 the roster and the last 20 changes
+ *   npm run show 100      \u2014 the last 100 changes
+ *
+ * ## Why this script exists
+ *
+ * The obvious way to check that a dispatch really landed is \`sqlite3 data.db\`,
+ * and it does not work: the roster and the history are AES-GCM ciphertext
+ * whenever the database has a password, which is what this receiver asks for on
+ * its first run. Reported from a real run, immediately after a first successful
+ * dispatch: "where do I look to prove it end to end?" The dashboard's LAST
+ * CHANGE panel shows one change and nothing showed the rest.
+ *
+ * It prompts for the password for the same reason \`src/index.ts\` does, and for
+ * the same reason it must do so BEFORE importing the store: the database
+ * derives its keys on import.
+ *
+ * IN INBOX MODE THERE IS NOTHING HERE TO SHOW, and saying so is the answer
+ * rather than printing an empty table. This receiver holds no key and no
+ * customer records in that mode; the connector holds both, and the change is
+ * in the connector's own store.
+ */
+import 'dotenv/config';
+import { config } from '../src/config.js';
+import { ask, databaseIsLocked } from '../src/unlock.js';
+
+function fmt(a: Record<string, string> | null): string {
+  if (!a) return '(nothing on file)';
+  const parts = [a.street, a.suburb, a.state, a.postcode, a.country].filter(Boolean);
+  return parts.join(', ') || '(empty)';
+}
+
+async function askPassword(): Promise<void> {
+  if (process.env.ONEADDRESS_DB_PASSPHRASE?.trim()) return;
+  if (!process.stdin.isTTY) return;
+  if (!(await databaseIsLocked())) return;
+  const answer = await ask('  Password to unlock: ');
+  if (answer) process.env.ONEADDRESS_DB_PASSPHRASE = answer;
+}
+
+async function main(): Promise<void> {
+  if (config.mode === 'inbox') {
+    console.log('\\n  This receiver is in inbox mode: it holds no customer records and no key.');
+    console.log('  Your connector applied the change and holds the result. Look there.\\n');
+    return;
+  }
+
+  await askPassword();
+
+  const limit = Number(process.argv[2]) > 0 ? Number(process.argv[2]) : 20;
+  const store = await import('../src/store.js');
+
+  const roster = store.allCustomers();
+  console.log(\`\\n  ON FILE (\${roster.length})\\n\`);
+  for (const c of roster) {
+    let addr: Record<string, string> | null = null;
+    try { addr = JSON.parse(c.address) as Record<string, string>; } catch { addr = null; }
+    console.log(\`  \${c.account_number.padEnd(14)} \${c.name.padEnd(24)} \${fmt(addr)}\`);
+  }
+
+  const changes = store.addressHistory(limit);
+  console.log(\`\\n  APPLIED CHANGES (\${changes.length}, newest first)\\n\`);
+  if (changes.length === 0) {
+    console.log('  None yet. Send a dispatch and run this again.\\n');
+    return;
+  }
+  for (const h of changes) {
+    console.log(\`  \${h.recorded_at}  \${h.account_number}  \${h.name}\`);
+    console.log(\`      was: \${fmt(h.prev_address as unknown as Record<string, string> | null)}\`);
+    console.log(\`      now: \${fmt(h.address as unknown as Record<string, string>)}\`);
+  }
+  console.log('');
+}
+
+void main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});
 `
     },
     {
@@ -5858,14 +6547,36 @@ computes the LOA reference with \`d5LoaRef\`, and hands it to your store as
 
 \`\`\`sql
 -- Your customer roster: who you know + the address you hold on file today.
--- Keyed on the account number. Seeded on startup from customers.json (edit that
--- file, or point loadRoster in src/store.ts at your real customer table).
-customers(account_number, name, address JSON, updated_at)
+-- Seeded on startup from customers.json (edit that file, or point loadRoster in
+-- src/store.ts at your real customer table).
+--
+-- account_key is how a row is FOUND: a blind index of the account number when
+-- the database has a password, the lower-cased number when it does not. It is
+-- the key rather than the number itself because AES-GCM uses a fresh IV per
+-- write, so two encryptions of one account number differ and a primary key over
+-- the ciphertext would enforce nothing while looking like it did.
+customers(account_key, account_number, name, address JSON, updated_at)
 
 -- Full history of every address change you apply (append-only audit trail).
-address_history(id, account_number, address JSON, recorded_at)
+-- BOTH SIDES of each change, so you can show what an address REPLACED and not
+-- only what it became.
+address_history(id, account_key, prev_address JSON, address JSON, recorded_at)
 \`\`\`
 
+### Seeing what changed
+
+\`\`\`bash
+npm run show        # the roster, and the last 20 changes (was: / now:)
+npm run show 100    # the last 100
+\`\`\`
+
+\`sqlite3 data.db\` will NOT answer this once the database has a password: every
+text column is ciphertext, which is the point. \`npm run show\` prompts for the
+same password \`npm start\` does and prints the decrypted rows.
+
+In **inbox mode** there is nothing here to show. This receiver holds no key and
+no customer records; your connector applied the change and holds the result.
+
 ## Swapping to a production database
 
 Open \`src/store.ts\` and replace the \`db\` calls with your ORM/driver of choice:
@@ -11006,7 +11717,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.4.0" : "dev";
+var PKG_VERSION = true ? "2.5.0" : "dev";
 var REGISTER_URL = "https://partners.oneaddress.io/api/partner/installs";
 function hmacSha256(secret, message) {
   return (0, import_node_crypto2.createHmac)("sha256", secret).update(message).digest("hex");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneaddress/setup",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Interactive setup wizard for OneAddress partner webhook integrations",
   "main": "dist/index.js",
   "bin": {