@oneaddress/setup 2.5.0 → 2.7.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.5.0" : "?";
+var WIZARD_VERSION = true ? "2.7.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -1013,7 +1013,8 @@ data.db-shm
   "oneAddressApi": "%%ONEADDRESS_API%%",
   "verifiesAccountReference": %%VERIFIES_ACCOUNT_REFERENCE%%,
   "mode": "%%RECEIVER_MODE%%",
-  "publicUrl": "%%WEBHOOK_URL%%"
+  "publicUrl": "%%WEBHOOK_URL%%",
+  "exportDir": ""
 }
 `
     },
@@ -1713,7 +1714,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 { dismissHeld, exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { dismissHeld, drillCount, exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { config } from './config.js';
 import { reachability } from './reachable.js';
 
 /** blessed takes colours as strings; these mirror the site's palette. */
@@ -1874,6 +1876,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     // ciphertext it cannot open; the customers live in the partner's own
     // database, behind their own controls.
     const reach = reachability();
+    const drills = drillCount();
     const vault = inbox
       ? \`{\${AMBER}-fg}{bold}NONE (inbox){/}\`
       : store.encrypted
@@ -1892,6 +1895,11 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       // 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".
+      // DRILLS ARE NAMED, not hidden. A conformance run leaves a trace and the
+      // partner should be able to see it; what it must not do is look like a
+      // fault. Absent when there are none, because a permanent "drills 0" is a
+      // counter for a thing that has not happened.
+      + (drills > 0 ? \`   {\${DIM}-fg}conformance probes{/} {\${CREAM}-fg}\${drills}{/}\` : '')
       + (reach.state === 'unknown'
         ? ''
         : reach.state === 'reachable'
@@ -1939,6 +1947,16 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
 
   /** Shown while a replay is running, so [r] does not look like it did nothing. */
   let replayNote = '';
+  /**
+   * The export confirmation, kept apart from \`replayNote\`.
+   *
+   * They are both one-line notes under the fault panel and they answer
+   * different questions, so sharing a slot means a press of [r] silently wipes
+   * the only place the export path was written down. The PATH is the entire
+   * value of the message: a receiver started from a shortcut or a service
+   * manager has a working directory the partner has never seen.
+   */
+  let exportNote = '';
 
   /**
    * The customer count, refreshed out of band.
@@ -2075,6 +2093,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
   // nothing, which is indistinguishable from a wedged UI.
   let replaying = false;
   screen.key(['r'], () => {
+    if (promptOpen) return;
     if (!onReplay || replaying) return;
     replaying = true;
     replayNote = 'Replaying\u2026';
@@ -2091,23 +2110,84 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       .finally(() => { replaying = false; redraw(); });
   });
 
+  // A ONE-LINE PATH PROMPT DRAWN OVER THE DASHBOARD.
+  //
+  // \`screen.key\` handlers are GLOBAL in blessed and keep firing while a textbox
+  // has focus, so [r], [d] and [q] would all act on keystrokes meant for the
+  // path. \`promptOpen\` gates every one of them. Without it, typing a Windows
+  // path containing a \`d\` arms a dismissal behind the prompt, and the \`q\` in
+  // \`C:\\\\Users\\\\qmark\` quits the receiver mid-sentence.
+  let promptOpen = false;
+  function askForPath(initial: string, onAnswer: (dir: string) => void): void {
+    promptOpen = true;
+    const box = blessed.textbox({
+      parent: screen,
+      top: 'center', left: 'center', width: '80%', height: 3,
+      border: { type: 'line' },
+      style: { border: { fg: AMBER }, fg: CREAM },
+      label: ' Export to which folder?  Enter accepts, Esc cancels ',
+      inputOnFocus: true,
+      keys: true,
+    });
+    // PRE-FILLED WITH THE RESOLVED DEFAULT, not left empty. The answer to
+    // "where does this go" has to be visible BEFORE the write, and an empty box
+    // asks the partner to know something the dashboard never told them.
+    box.setValue(initial);
+    screen.render();
+    box.readInput((_err, value) => {
+      promptOpen = false;
+      box.destroy();
+      screen.render();
+      // Escape gives no value. Treated as cancel, NOT as "use the default":
+      // a partner who hits Esc has changed their mind about writing a file.
+      if (typeof value !== 'string') { exportNote = 'Export cancelled.'; redraw(); return; }
+      onAnswer(value.trim());
+    });
+  }
+
   // [e] EXPORTS THE FAULT LIST. Metadata only, no payloads: see exportHeld.
   // Bound unconditionally for the same reason [r] is, so pressing it on a clean
   // receiver says there is nothing to export rather than appearing to hang.
+  //
+  // IT ASKS WHERE, EVERY TIME (Tim's call). \`exportDir\` in
+  // \`oneaddress.config.json\` and \`ONEADDRESS_EXPORT_DIR\` still decide the
+  // DEFAULT, but they were the only ways to choose and neither is visible from
+  // the dashboard - reported from a real run as "it looks like export location
+  // cannot be picked". Pressing Enter on the pre-filled prompt is byte-for-byte
+  // the old behaviour, so nothing that worked before needs changing.
   screen.key(['e'], () => {
+    if (promptOpen) return;
     if (heldCount() === 0) {
       replayNote = 'Nothing held, so nothing to export.';
       redraw();
       return;
     }
+    askForPath(config.exportDir || process.cwd(), (dir) => { writeExport(dir); redraw(); });
+  });
+
+  /**
+   * Write the fault export, and say where it landed.
+   *
+   * Shared by [e] and [d] rather than duplicated, because [d] exports FIRST and
+   * the two must agree on the destination and on the message. Returns whether
+   * it succeeded, which is what lets [d] refuse to discard anything after a
+   * failed write.
+   */
+  function writeExport(dir: string): boolean {
     try {
-      const { path, count } = exportHeld(process.cwd());
-      replayNote = \`Exported \${count} to \${path}\`;
+      const { path, count } = exportHeld(dir);
+      exportNote = \`Saved \${count} to \${path}\`;
+      replayNote = '';
+      return true;
     } catch (err) {
-      replayNote = \`Export failed: \${err instanceof Error ? err.message : String(err)}\`;
+      // NAMES THE DIRECTORY IT TRIED. "EACCES" on its own sends a partner to
+      // search for a file that was never written.
+      exportNote = \`Export FAILED writing to \${dir || process.cwd()}: \` +
+        \`\${err instanceof Error ? err.message : String(err)}\`;
+      replayNote = '';
+      return false;
     }
-    redraw();
-  });
+  }
 
   // [d] DISMISSES. TWO PRESSES, and the first one only asks.
   //
@@ -2118,10 +2198,19 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
   // 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.
+  // THE RECEIVER DOES RECOGNISE THE PROBE NOW, AND THIS PARAGRAPH USED TO SAY
+  // OTHERWISE. It argued the receiver could not, because "everything that
+  // identifies one is chosen by the sender". That over-weighted the attacker:
+  // anyone able to forge a signed dispatch already holds the webhook secret and
+  // can make this receiver APPLY a bogus address change, so hiding a quarantine
+  // row is not the prize. The real question was signed versus unsigned, and
+  // \`conformance: true\` rides inside the signed body. A drill is classified, not
+  // suppressed - still written, still counted, drawn calmly rather than as an
+  // alarm - so [d] is no longer the only way to clear a passing run.
+  //
+  // IT STILL EXISTS, because a drill is not the only thing that gets held: a
+  // genuinely undecryptable dispatch from a key that has since been rotated is
+  // never going to replay, and without this the panel stays red forever.
   //
   // IRREVERSIBLE, SO IT IS CONFIRMED. Dismissal discards the held payload, which
   // is the point (see \`dismissHeld\`) and also means a mistaken press cannot be
@@ -2136,6 +2225,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
   // that was described makes the question and the action the same question.
   let dismissArmedFor: number | null = null;
   screen.key(['d'], () => {
+    if (promptOpen) return;
     const held = heldCount();
     if (held === 0) {
       dismissArmedFor = null;
@@ -2152,9 +2242,29 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       return;
     }
     dismissArmedFor = null;
+    // EXPORTED BEFORE IT IS DISCARDED, ALWAYS.
+    //
+    // \`exportHeld\` reads \`heldDispatches()\`, which filters out dismissed rows,
+    // so [d] then [e] exported NOTHING and the record was unrecoverable from the
+    // UI. The payload is meant to go - it is an encrypted consumer address on a
+    // third party's disk - but the metadata is the part you would send to
+    // support, and dismissing destroyed exactly that. Reported from a real run:
+    // "if they dismiss a fault, does that mean they cant export and record it?"
+    //
+    // WRITTEN WITHOUT ASKING, unlike [e]. The partner is one keypress from
+    // discarding the evidence and an extra prompt here is a prompt at the worst
+    // possible moment; the default destination is the right answer for a record
+    // nobody asked for. A FAILED write ABORTS the dismissal rather than
+    // proceeding, because "we could not save the record, so we destroyed it" is
+    // the one outcome nothing recovers from.
+    if (!writeExport(config.exportDir || process.cwd())) {
+      replayNote = 'Dismiss ABORTED: nothing was discarded because the record could not be saved.';
+      redraw();
+      return;
+    }
     try {
       const n = dismissHeld();
-      replayNote = \`Dismissed \${n}. Nothing left held.\`;
+      replayNote = \`Dismissed \${n}. Nothing left held - the record was exported first.\`;
     } catch (err) {
       replayNote = \`Dismiss failed: \${err instanceof Error ? err.message : String(err)}\`;
     }
@@ -2162,6 +2272,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
   });
 
   screen.key(['q', 'C-c'], () => {
+    if (promptOpen) return;
     detach();
     screen.destroy();
     onQuit();
@@ -3367,8 +3478,9 @@ export function resetTally(): void {
 import db, { ensureColumn, parseStoredTime } from './db.js';
 import { report } from './report.js';
 import { createHash } from 'node:crypto';
-import { writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { config } from './config.js';
 
 /**
  * Why a dispatch could not be applied. Shown verbatim on the dashboard.
@@ -3458,6 +3570,43 @@ ensureColumn('quarantine', 'attempts', 'INTEGER NOT NULL DEFAULT 0');
  */
 ensureColumn('quarantine', 'dismissed_at', 'TEXT');
 
+/**
+ * Was this a conformance DRILL rather than a real dispatch?
+ *
+ * ## The problem it solves
+ *
+ * Conformance check 11 sends a dispatch this receiver CANNOT open, on purpose,
+ * and passes it for refusing one. So a receiver that quarantines ends a
+ * SUCCESSFUL run with a red fault panel, a \`failed\` count that never returns to
+ * zero, and a \`decrypt_failed\` line naming the partner's real \`key_id\` - telling
+ * them to fix the one thing that is not broken. Reported from a real run.
+ *
+ * ## Why this is trusted and the dispatch id is not
+ *
+ * The flag comes from \`conformance: true\` in the body, and the HMAC covers
+ * \`\${timestamp}.\${rawBody}\`. The body is signed; the headers are not. The
+ * conformance dispatch also carries a recognisable \`X-OneAddress-Dispatch\`
+ * prefix, and keying off THAT would be a mistake: it sits outside the signature,
+ * so anything on the path could set it and change how an operator's fault panel
+ * behaves. Same reasoning as \`crossover_key_ids\`, which is already a signed-body
+ * field that tells a receiver how to treat a payload it cannot decrypt.
+ *
+ * ## Classified, NOT suppressed
+ *
+ * A drill is still recorded, still counted, still visible on the dashboard. It
+ * is drawn calmly instead of as an alarm. Suppression is what creates a silent
+ * failure; classification does not, and if the marker is ever wrong the operator
+ * still sees the event, in the wrong colour rather than not at all.
+ *
+ * ## A drill holds NO payload
+ *
+ * \`raw_body\` is empty for a drill, which is a property rather than a saving.
+ * The probe is sealed to a throwaway key pair the conformance run generated and
+ * discarded, so no key that will ever exist can open it: replay cannot succeed,
+ * and keeping the bytes would put an unopenable blob in the replay set forever.
+ */
+ensureColumn('quarantine', 'drill', 'INTEGER NOT NULL DEFAULT 0');
+
 export interface QuarantineInput {
   dispatchId: string | null;
   event: string;
@@ -3465,6 +3614,10 @@ export interface QuarantineInput {
   keyId: string | null;
   rawBody: string;
   detail: string;
+  /** A conformance probe rather than a consumer's dispatch. See the
+   *  \`drill\` column's docstring. Defaults to false, so a caller that does
+   *  not know about drills still records a real fault. */
+  drill?: boolean;
 }
 
 /**
@@ -3476,27 +3629,44 @@ export interface QuarantineInput {
  */
 export function quarantine(input: QuarantineInput): void {
   const id = dispatchKey(input.dispatchId, input.rawBody);
+  const drill = input.drill === true;
   try {
     db.prepare(
-      \`INSERT INTO quarantine (id, dispatch_id, event, reason, key_id, raw_body, detail)
-       VALUES (?, ?, ?, ?, ?, ?, ?)
+      \`INSERT INTO quarantine (id, dispatch_id, event, reason, key_id, raw_body, detail, drill)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(id) DO UPDATE SET
          reason = excluded.reason,
          key_id = excluded.key_id,
-         detail = excluded.detail\`,
+         detail = excluded.detail,
+         drill  = excluded.drill\`,
     ).run(
       id,
       input.dispatchId,
       input.event,
       input.reason,
       input.keyId,
-      input.rawBody,
+      // NO PAYLOAD FOR A DRILL. The probe is sealed to a throwaway key pair the
+      // conformance run generated and discarded, so nothing that will ever exist
+      // can open it. Keeping the bytes would put a permanently unopenable blob
+      // in the replay set.
+      drill ? '' : input.rawBody,
       input.detail.slice(0, 500),
+      drill ? 1 : 0,
     );
-    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.',
-    );
+    if (drill) {
+      // INFO, NOT WARN, and it says what happened rather than what to fix. The
+      // old line ended a PASSING conformance run by telling the partner to go
+      // and correct a key that is perfectly correct.
+      report.info(
+        \`[quarantine] \${input.event} was a conformance probe and was refused, which is how that \` +
+        'check is passed. Nothing is wrong with your key.',
+      );
+    } else {
+      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);
   }
@@ -3521,16 +3691,30 @@ 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 AND dismissed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0
       ORDER BY received_at
       LIMIT ?\`,
   ).all(limit) as unknown as HeldDispatch[];
 }
 
+/**
+ * How many conformance probes this receiver has refused.
+ *
+ * Its own figure rather than a slice of \`heldCount\`, because the two answer
+ * different questions. Held means "waiting on you". A drill means "a check ran
+ * and this receiver behaved correctly", which is not a queue and not work.
+ */
+export function drillCount(): number {
+  const row = db.prepare(
+    'SELECT count(*) AS n FROM quarantine WHERE drill = 1 AND dismissed_at IS NULL',
+  ).get() as { n: number };
+  return row.n;
+}
+
 /** 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 AND dismissed_at IS NULL',
+    'SELECT count(*) AS n FROM quarantine WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0',
   ).get() as { n: number };
   return row.n;
 }
@@ -3547,7 +3731,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 AND dismissed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0
       GROUP BY reason, key_id
       ORDER BY n DESC\`,
   ).all() as unknown as {
@@ -3611,7 +3795,7 @@ 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\`,
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0\`,
   ).run(new Date().toISOString());
   const n = Number(info.changes ?? 0);
   if (n > 0) {
@@ -3691,10 +3875,25 @@ export function purgeQuarantine(days: number): { replayed: number; unreplayed: n
  * what diagnoses a key problem, and it is safe to paste into a support ticket
  * or send to us, which is what an export is for.
  */
-export function exportHeld(directory: string): { path: string; count: number } {
+export function exportHeld(directory?: string): { path: string; count: number } {
   const rows = heldDispatches(500);
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const path = join(directory, \`oneaddress-faults-\${stamp}.json\`);
+  // RESOLVED TO AN ABSOLUTE PATH, ALWAYS, and that is the point of the change.
+  // "Exported 3 to oneaddress-faults-\u2026.json" is not an answer to "where is it";
+  // a receiver is routinely started by a shortcut or a service manager whose
+  // working directory is not where the partner thinks it is. Reported after a
+  // real run: the file was written and could not be found.
+  //
+  // The explicit argument still wins, so a caller (and every existing test) can
+  // name a directory; \`config.exportDir\` is the persistent choice and
+  // \`ONEADDRESS_EXPORT_DIR\` the one-run override. Empty resolves to the working
+  // directory, which is what this always did.
+  const target = resolve(directory ?? config.exportDir ?? '');
+  // Created rather than failed on. A partner who set \`exportDir\` to a folder
+  // they have not made yet wants the file, not a lecture, and a directory they
+  // named is one they have already consented to.
+  mkdirSync(target, { recursive: true });
+  const path = join(target, \`oneaddress-faults-\${stamp}.json\`);
   writeFileSync(path, JSON.stringify({
     exported_at: new Date().toISOString(),
     note: 'Metadata only. The held payloads are deliberately not included: they are encrypted consumer addresses and stay under the receiver retention window.',
@@ -3711,7 +3910,11 @@ export function exportHeld(directory: string): { path: string; count: number } {
       last_error: r.last_error,
     })),
   }, null, 2));
-  report.info(\`[quarantine] exported \${rows.length} held dispatch(es) to \${path}\`);
+  // THE PATH IS THE MESSAGE. Logged as well as shown on the dashboard, because
+  // the dashboard line is gone the next time anything is pressed while the log
+  // survives a scrollback, a \`npm start | tee\`, and a headless run where there
+  // is no dashboard at all.
+  report.info(\`[quarantine] exported \${rows.length} held dispatch(es) to \${path} - safe to send to support, no payloads inside\`);
   return { path, count: rows.length };
 }
 
@@ -4108,6 +4311,17 @@ export type ReceiverConfig = {
   oneAddressApi:            string;
   verifiesAccountReference: boolean;
   mode:                     ReceiverMode;
+  /**
+   * Where \`[e]\` writes the fault export.
+   *
+   * Empty means the working directory, which is what it always did. Named
+   * because "it saved a file" is useless if you cannot find it: the receiver is
+   * routinely started by a double-clicked shortcut or a service manager whose
+   * working directory is not where the partner thinks it is.
+   *
+   * \`ONEADDRESS_EXPORT_DIR\` overrides it for one run without editing the file.
+   */
+  exportDir:                string;
   /**
    * The webhook URL registered with OneAddress: where dispatches actually
    * arrive from the internet.
@@ -4134,6 +4348,9 @@ const DEFAULTS: ReceiverConfig = {
   mode: 'write-through',
   // No guess. See the field's docstring.
   publicUrl: '',
+  // Empty resolves to the working directory at use, not here, so a config file
+  // written on one machine does not pin an absolute path from another.
+  exportDir: '',
 };
 
 function parseMode(value: unknown): ReceiverMode | undefined {
@@ -4153,6 +4370,7 @@ function loadConfigFile(): Partial<ReceiverConfig> {
     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;
+    if (typeof parsed.exportDir === 'string')                 out.exportDir = parsed.exportDir;
     const mode = parseMode(parsed.mode);
     if (mode) out.mode = mode;
     return out;
@@ -4177,6 +4395,7 @@ export const config: ReceiverConfig = {
   // 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),
+  exportDir: process.env.ONEADDRESS_EXPORT_DIR || fromFile.exportDir || DEFAULTS.exportDir,
 };
 
 report.info(
@@ -5595,9 +5814,27 @@ app.post('/webhook', async (req: Request, res: Response) => {
    */
   const key = dispatchKey(dispatch || null, rawBody);
 
+  /**
+   * A DRILL, declared in the SIGNED body. See \`quarantine.ts\`'s \`drill\` column.
+   *
+   * Read from \`body\`, which the HMAC covers, and never from the dispatch-id
+   * header, which it does not. The conformance run already puts a recognisable
+   * prefix on that header and using it would let anything on the path decide
+   * whether this receiver raises an alarm.
+   */
+  const isDrill = (body as Record<string, unknown>).conformance === true;
+
   const hold = (reason: QuarantineReason, keyId: string | null, detail: string): void => {
-    quarantine({ dispatchId: dispatch || null, event, reason, keyId, rawBody, detail });
-    recordOutcome(key, 'failed');
+    quarantine({ dispatchId: dispatch || null, event, reason, keyId, rawBody, detail, drill: isDrill });
+    // NOT COUNTED AS A FAILURE WHEN IT IS A DRILL. \`failed\` on the footer is a
+    // figure about this partner's dispatches; a probe that was refused exactly
+    // as the check requires is not one of them, and leaving it in is what made a
+    // passing conformance run read as \`failed 1\` forever.
+    //
+    // Recorded as NOTHING rather than as a third outcome, deliberately:
+    // \`tally.ts\` holds \`received === applied + failed\` as an invariant and a
+    // drill is not a dispatch to this partner's business at all.
+    if (!isDrill) recordOutcome(key, 'failed');
   };
 
   /**
@@ -5754,11 +5991,24 @@ app.post('/webhook', async (req: Request, res: Response) => {
       decAccount    = typeof data.account_number === 'string' ? data.account_number : '';
       decKnownNames = Array.isArray(data.known_names) ? data.known_names : [];
     } catch (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);
+      // A DRILL SAYS SO INSTEAD OF SHOUTING. Conformance check 11 wraps its
+      // session key to a throwaway pair so that decryption MUST fail; the two
+      // lines below would then name the partner's real key_id, print a raw
+      // crypto error, and advise them to go and fix a key that is correct - at
+      // the end of a run that just passed. The refusal below is unchanged,
+      // because the refusal is what the check is testing.
+      if (isDrill) {
+        report.info(
+          \`[webhook] conformance probe for key_id \${keyId ?? '(none)'} could not be decrypted, which is \` +
+          'what that check requires. Your key is fine.',
+        );
+      } else {
+        // 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' });
     }
@@ -6290,8 +6540,9 @@ export async function ask(prompt: string): Promise<string> {
  * 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
+ *   npm run show          \u2014 a LIVE branded view, refreshing as changes land
+ *   npm run show 100      \u2014 keep 100 changes on screen instead of 20
+ *   npm run show > f.txt  \u2014 plain one-shot text, for a file or a pipe
  *
  * ## Why this script exists
  *
@@ -6302,6 +6553,23 @@ export async function ask(prompt: string): Promise<string> {
  * 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.
  *
+ * ## Why it STREAMS rather than printing once
+ *
+ * The first version printed a snapshot and exited, which answers "did it land"
+ * only if you already knew to run it again. Watching a dispatch arrive meant
+ * re-running it by hand and diffing two screenfuls in your head. It holds the
+ * screen now and polls, so a change appears as it is applied.
+ *
+ * POLLED, NOT SUBSCRIBED, and that is forced rather than lazy: this is a
+ * SEPARATE PROCESS from the receiver, so there is no event to listen to. SQLite
+ * readers do not block writers, so a poll costs the running receiver nothing.
+ * The screen is only redrawn when the rendered content actually CHANGES, so an
+ * idle receiver is not repainting a terminal once a second.
+ *
+ * NON-TTY FALLS BACK TO ONE-SHOT TEXT. \`npm run show > out.txt\`, a pipe, and a
+ * CI log have no terminal to hold, and a blessed screen drawn into a pipe
+ * produces escape-code soup. Same rule the dashboard itself follows.
+ *
  * 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.
@@ -6312,8 +6580,17 @@ export async function ask(prompt: string): Promise<string> {
  * in the connector's own store.
  */
 import 'dotenv/config';
+import blessed from 'blessed';
 import { config } from '../src/config.js';
 import { ask, databaseIsLocked } from '../src/unlock.js';
+import { HEX, ONE_ROWS, ADDRESS_ROWS, terminalFitsFullMark } from '../src/brand.js';
+
+const AMBER = HEX.amber.toLowerCase();
+const CREAM = HEX.cream.toLowerCase();
+const DIM = '#8a7f6a';
+
+/** Escape blessed's tag syntax so a customer's name can never inject markup. */
+const esc = (s: unknown): string => String(s ?? '').replace(/[{}]/g, '');
 
 function fmt(a: Record<string, string> | null): string {
   if (!a) return '(nothing on file)';
@@ -6329,18 +6606,32 @@ async function askPassword(): Promise<void> {
   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;
-  }
+type Store = typeof import('../src/store.js');
 
-  await askPassword();
+/** The roster, as display rows. */
+function rosterRows(store: Store): string[] {
+  return store.allCustomers().map((c) => {
+    let addr: Record<string, string> | null = null;
+    try { addr = JSON.parse(c.address) as Record<string, string>; } catch { addr = null; }
+    return \`  \${esc(c.account_number).padEnd(20)} \${esc(c.name).padEnd(24)} \${esc(fmt(addr))}\`;
+  });
+}
 
-  const limit = Number(process.argv[2]) > 0 ? Number(process.argv[2]) : 20;
-  const store = await import('../src/store.js');
+/** Applied changes, newest first, as display rows with both sides. */
+function changeRows(store: Store, limit: number): string[] {
+  const out: string[] = [];
+  for (const h of store.addressHistory(limit)) {
+    const prev = h.prev_address as unknown as Record<string, string> | null;
+    const now  = h.address as unknown as Record<string, string>;
+    out.push(\`  {\${DIM}-fg}\${esc(h.recorded_at)}{/}  {\${CREAM}-fg}\${esc(h.account_number)}{/}  \${esc(h.name)}\`);
+    out.push(\`      {\${DIM}-fg}was:{/} \${esc(fmt(prev))}\`);
+    out.push(\`      {\${AMBER}-fg}now:{/} \${esc(fmt(now))}\`);
+  }
+  return out;
+}
 
+/** One-shot plain text. The pipe, the file, the CI log. */
+function printOnce(store: Store, limit: number): void {
   const roster = store.allCustomers();
   console.log(\`\\n  ON FILE (\${roster.length})\\n\`);
   for (const c of roster) {
@@ -6348,7 +6639,6 @@ async function main(): Promise<void> {
     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) {
@@ -6363,6 +6653,86 @@ async function main(): Promise<void> {
   console.log('');
 }
 
+/** The live view: the mark, the roster, the changes, refreshed as they land. */
+function stream(store: Store, limit: number): void {
+  const screen = blessed.screen({ smartCSR: true, title: 'What this receiver holds \u2014 OneAddress' });
+
+  // Same rule as the dashboard: the pixel wordmark needs 88 columns, and below
+  // that it wraps and reads as broken rather than as large.
+  const wide = terminalFitsFullMark(Number(screen.width));
+  const markHeight = wide ? 9 : 3;
+  blessed.box({
+    parent: screen, top: 0, left: 0, width: '100%', height: markHeight,
+    tags: true, padding: { left: 2 },
+    content: wide
+      ? ONE_ROWS.map((row, i) => \`{\${CREAM}-fg}\${row}{/} {\${AMBER}-fg}\${ADDRESS_ROWS[i]}{/}\`).join('\\n')
+      : \`{\${CREAM}-fg}{bold}One{/bold}{/}{\${AMBER}-fg}{bold}Address{/bold}{/}\`,
+  });
+
+  const rosterBox = blessed.box({
+    parent: screen, top: markHeight, left: 0, width: '100%', height: 'shrink',
+    tags: true, padding: { left: 1, right: 1 },
+    border: { type: 'line' }, style: { border: { fg: AMBER } },
+    label: ' ON FILE ',
+  });
+
+  const changesBox = blessed.box({
+    parent: screen, top: markHeight + 3, left: 0, width: '100%', bottom: 1,
+    tags: true, padding: { left: 1, right: 1 }, scrollable: true, alwaysScroll: true,
+    border: { type: 'line' }, style: { border: { fg: AMBER } },
+    label: ' APPLIED CHANGES \u2014 newest first ',
+  });
+
+  blessed.box({
+    parent: screen, bottom: 0, left: 0, width: '100%', height: 1,
+    tags: true, padding: { left: 2 },
+    content: \`{\${DIM}-fg}live \u2014 updates as dispatches land{/}   {\${CREAM}-fg}[q]{/} quit\`,
+  });
+
+  // ONLY REDRAWN WHEN THE CONTENT CHANGES. A poll that repaints unconditionally
+  // makes an idle receiver flicker once a second and destroys any scrollback
+  // position the operator had.
+  let last = '';
+  const tick = (): void => {
+    const roster = rosterRows(store);
+    const changes = changeRows(store, limit);
+    const next = roster.join('\\n') + '\\u0000' + changes.join('\\n');
+    if (next === last) return;
+    last = next;
+    rosterBox.height = roster.length + 2;
+    rosterBox.setContent(roster.join('\\n') || '  (nobody on file yet)');
+    changesBox.top = markHeight + roster.length + 2;
+    changesBox.setContent(changes.join('\\n') || '  None yet. Send a dispatch and this fills in.');
+    screen.render();
+  };
+
+  screen.key(['q', 'C-c', 'escape'], () => { screen.destroy(); process.exit(0); });
+  tick();
+  screen.render();
+  // DELIBERATELY NOT unref'd. An unref'd timer does not hold the event loop
+  // open, and with the screen drawn there is nothing else pending, so the
+  // process would exit the instant it finished painting.
+  setInterval(tick, 1000);
+}
+
+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');
+
+  // A pipe, a file or a CI log has no terminal to hold, and a blessed screen
+  // drawn into one produces escape-code soup rather than output.
+  if (!process.stdout.isTTY) { printOnce(store, limit); return; }
+  stream(store, limit);
+}
+
 void main().catch((err: unknown) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);
@@ -6563,6 +6933,26 @@ customers(account_key, account_number, name, address JSON, updated_at)
 address_history(id, account_key, prev_address JSON, address JSON, recorded_at)
 \`\`\`
 
+### Where the fault export lands
+
+\`[e]\` on the dashboard writes a metadata-only file (no payloads) you can send
+straight to support. It goes to the working directory by default, which is not
+always where you think it is when the receiver was started by a shortcut or a
+service manager, so you can name somewhere:
+
+\`\`\`jsonc
+// oneaddress.config.json
+{ "exportDir": "/home/you/oneaddress-exports" }
+\`\`\`
+
+\`\`\`bash
+ONEADDRESS_EXPORT_DIR=/tmp npm start   # one run, without editing the file
+\`\`\`
+
+The directory is created if it does not exist. The confirmation on the dashboard
+and the line in the log both name the **full path**, and the dashboard keeps it
+in its own slot so pressing \`[r]\` does not wipe it.
+
 ### Seeing what changed
 
 \`\`\`bash
@@ -11717,7 +12107,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.5.0" : "dev";
+var PKG_VERSION = true ? "2.7.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");
@@ -12786,6 +13176,9 @@ OneAddress and a leak of either must not also hand somebody your customers' addr
       "No private key is collected for an inbox receiver. It belongs in your connector,\nwhich is the only process that decrypts. This one is meant never to hold one, and\nit refuses to start if it finds one in its environment."
     );
   } else {
+    M2.info(
+      "It looks like one of these:\n  -----BEGIN PRIVATE KEY-----      (a .pem file, paste the whole thing)\n  MIGHAgEAMB...                    (the base64 body, copied from My Profile)\n  C:\\keys\\oneaddress.pem            (or just the path to the file)\nThis is your PRIVATE key, not the public one shown next to it in the portal."
+    );
     const privateKeyRaw = await he({
       message: "Your ECDH Private Key",
       placeholder: "Paste the base64 key body from My Profile, or enter a path to the .pem file",

package/package.json

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