@oneaddress/setup 2.6.0 → 2.8.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.6.0" : "?";
+var WIZARD_VERSION = true ? "2.8.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -1023,9 +1023,30 @@ data.db-shm
       content: `{
   "//": "YOUR CUSTOMER ROSTER \u2014 edit this file to your customers (account number, name, and the address you hold on file today). src/store.ts seeds from here on startup; point loadRoster at your real customer database when you outgrow the file. Override the path with the ONEADDRESS_CUSTOMERS env var.",
   "customers": [
-    { "account_number": "AUR-583920", "name": "Tim Hooper",      "address": { "street": "12 Old Mill Road",  "suburb": "Parramatta", "state": "NSW", "postcode": "2150" } },
-    { "account_number": "AUR-104772", "name": "Olivia Robinson", "address": { "street": "5 Rosewood Lane",    "suburb": "Brisbane",   "state": "QLD", "postcode": "4000" } },
-    { "account_number": "AUR-296815", "name": "Marcus Chen",     "address": { "street": "31 Goldfield Drive", "suburb": "Richmond",   "state": "VIC", "postcode": "3121" } }
+    { "account_number": "AUR-583920", "name": "Tim Hooper",       "address": { "street": "12 Old Mill Road",     "suburb": "Parramatta",      "state": "NSW", "postcode": "2150" } },
+    { "account_number": "AUR-104772", "name": "Olivia Robinson",  "address": { "street": "5 Rosewood Lane",      "suburb": "Brisbane",        "state": "QLD", "postcode": "4000" } },
+    { "account_number": "AUR-296815", "name": "Marcus Chen",      "address": { "street": "31 Goldfield Drive",   "suburb": "Richmond",        "state": "VIC", "postcode": "3121" } },
+    { "account_number": "AUR-337401", "name": "Priya Raghavan",   "address": { "street": "8 Kurrajong Street",   "suburb": "Newtown",         "state": "NSW", "postcode": "2042" } },
+    { "account_number": "AUR-418266", "name": "Daniel O'Sullivan", "address": { "street": "204/19 Marine Parade", "suburb": "Glenelg",         "state": "SA", "postcode": "5045" } },
+    { "account_number": "AUR-452093", "name": "Amara Okafor",     "address": { "street": "77 Beaufort Street",   "suburb": "Mount Lawley",    "state": "WA", "postcode": "6050" } },
+    { "account_number": "AUR-509118", "name": "Hannah Whitlock",  "address": { "street": "3 Tasman Close",       "suburb": "Sandy Bay",       "state": "TAS", "postcode": "7005" } },
+    { "account_number": "AUR-563740", "name": "Joshua Nguyen",    "address": { "street": "145 Given Terrace",    "suburb": "Paddington",      "state": "QLD", "postcode": "4064" } },
+    { "account_number": "AUR-617205", "name": "Isabella Moretti", "address": { "street": "62 Lygon Street",      "suburb": "Carlton",         "state": "VIC", "postcode": "3053" } },
+    { "account_number": "AUR-668931", "name": "Samuel Achterberg", "address": { "street": "11 Hutt Street",       "suburb": "Adelaide",        "state": "SA", "postcode": "5000" } },
+    { "account_number": "AUR-702884", "name": "Grace Tupou",      "address": { "street": "9 Kingsford Smith Way", "suburb": "Belconnen",       "state": "ACT", "postcode": "2617" } },
+    { "account_number": "AUR-745160", "name": "Ethan Marsh",      "address": { "street": "38 Smith Street",      "suburb": "Darwin City",     "state": "NT", "postcode": "0800" } },
+    { "account_number": "AUR-781422", "name": "Chloe Bennett",    "address": { "street": "26 Rundle Street",     "suburb": "Kent Town",       "state": "SA", "postcode": "5067" } },
+    { "account_number": "AUR-816559", "name": "Liam Fitzgerald",  "address": { "street": "410/88 Queen Street",  "suburb": "Melbourne",       "state": "VIC", "postcode": "3000" } },
+    { "account_number": "AUR-849073", "name": "Sofia Delgado",    "address": { "street": "17 Cavill Avenue",     "suburb": "Surfers Paradise", "state": "QLD", "postcode": "4217" } },
+    { "account_number": "AUR-873318", "name": "Noah Kirkwood",    "address": { "street": "54 Hunter Street",     "suburb": "Newcastle",       "state": "NSW", "postcode": "2300" } },
+    { "account_number": "AUR-905642", "name": "Mei Lin Tan",      "address": { "street": "2/33 Rokeby Road",     "suburb": "Subiaco",         "state": "WA", "postcode": "6008" } },
+    { "account_number": "AUR-938177", "name": "Jack Rasmussen",   "address": { "street": "6 Elizabeth Street",   "suburb": "Launceston",      "state": "TAS", "postcode": "7250" } },
+    { "account_number": "AUR-960845", "name": "Aaliyah Bennett",  "address": { "street": "82 Charles Street",    "suburb": "Northcote",       "state": "VIC", "postcode": "3070" } },
+    { "account_number": "AUR-984312", "name": "Oscar Petrov",     "address": { "street": "19 Macquarie Street",  "suburb": "Hobart",          "state": "TAS", "postcode": "7000" } },
+    { "account_number": "AUR-991026", "name": "Ruby Anderson",    "address": { "street": "301/5 Cordelia Street", "suburb": "South Brisbane",  "state": "QLD", "postcode": "4101" } },
+    { "account_number": "AUR-995518", "name": "Henry Abebe",      "address": { "street": "14 Wakefield Street",  "suburb": "Kent Town",       "state": "SA", "postcode": "5067" } },
+    { "account_number": "AUR-997430", "name": "Zoe Castellano",   "address": { "street": "67 Bay Street",        "suburb": "Port Melbourne",  "state": "VIC", "postcode": "3207" } },
+    { "account_number": "AUR-999201", "name": "Felix Nakamura",   "address": { "street": "23 Anzac Parade",      "suburb": "Kensington",      "state": "NSW", "postcode": "2033" } }
   ]
 }
 `
@@ -2093,6 +2114,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';
@@ -2109,32 +2131,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 {
-      // NO ARGUMENT. \`exportHeld\` resolves \`config.exportDir\`, then
-      // \`ONEADDRESS_EXPORT_DIR\`, then the working directory, and returns an
-      // ABSOLUTE path. Passing \`process.cwd()\` here is what made the setting
-      // unreachable from the one key that uses it.
-      const { path, count } = exportHeld();
+      const { path, count } = exportHeld(dir);
       exportNote = \`Saved \${count} to \${path}\`;
       replayNote = '';
+      return true;
     } catch (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 \${config.exportDir || process.cwd()}: \` +
+      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.
   //
@@ -2145,10 +2219,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
@@ -2163,6 +2246,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;
@@ -2179,9 +2263,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)}\`;
     }
@@ -2189,6 +2293,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
   });
 
   screen.key(['q', 'C-c'], () => {
+    if (promptOpen) return;
     detach();
     screen.destroy();
     onQuit();
@@ -4926,9 +5031,30 @@ type RosterEntry = { account_number: string; name: string; address: Address };
 // runs out of the box. The wizard writes customers.json with these same demo
 // customers \u2014 edit that file, not this list.
 const DEFAULT_ROSTER: RosterEntry[] = [
-  { account_number: 'AUR-583920', name: 'Tim Hooper',      address: { street: '12 Old Mill Road',   suburb: 'Parramatta', state: 'NSW', postcode: '2150' } },
-  { account_number: 'AUR-104772', name: 'Olivia Robinson', address: { street: '5 Rosewood Lane',     suburb: 'Brisbane',   state: 'QLD', postcode: '4000' } },
-  { account_number: 'AUR-296815', name: 'Marcus Chen',     address: { street: '31 Goldfield Drive',  suburb: 'Richmond',   state: 'VIC', postcode: '3121' } },
+  { account_number: 'AUR-583920', name: 'Tim Hooper',        address: { street: '12 Old Mill Road',      suburb: 'Parramatta',       state: 'NSW', postcode: '2150' } },
+  { account_number: 'AUR-104772', name: 'Olivia Robinson',   address: { street: '5 Rosewood Lane',       suburb: 'Brisbane',         state: 'QLD', postcode: '4000' } },
+  { account_number: 'AUR-296815', name: 'Marcus Chen',       address: { street: '31 Goldfield Drive',    suburb: 'Richmond',         state: 'VIC', postcode: '3121' } },
+  { account_number: 'AUR-337401', name: 'Priya Raghavan',    address: { street: '8 Kurrajong Street',    suburb: 'Newtown',          state: 'NSW', postcode: '2042' } },
+  { account_number: 'AUR-418266', name: 'Daniel O\\'Sullivan', address: { street: '204/19 Marine Parade',  suburb: 'Glenelg',          state: 'SA', postcode: '5045' } },
+  { account_number: 'AUR-452093', name: 'Amara Okafor',      address: { street: '77 Beaufort Street',    suburb: 'Mount Lawley',     state: 'WA', postcode: '6050' } },
+  { account_number: 'AUR-509118', name: 'Hannah Whitlock',   address: { street: '3 Tasman Close',        suburb: 'Sandy Bay',        state: 'TAS', postcode: '7005' } },
+  { account_number: 'AUR-563740', name: 'Joshua Nguyen',     address: { street: '145 Given Terrace',     suburb: 'Paddington',       state: 'QLD', postcode: '4064' } },
+  { account_number: 'AUR-617205', name: 'Isabella Moretti',  address: { street: '62 Lygon Street',       suburb: 'Carlton',          state: 'VIC', postcode: '3053' } },
+  { account_number: 'AUR-668931', name: 'Samuel Achterberg', address: { street: '11 Hutt Street',        suburb: 'Adelaide',         state: 'SA', postcode: '5000' } },
+  { account_number: 'AUR-702884', name: 'Grace Tupou',       address: { street: '9 Kingsford Smith Way', suburb: 'Belconnen',        state: 'ACT', postcode: '2617' } },
+  { account_number: 'AUR-745160', name: 'Ethan Marsh',       address: { street: '38 Smith Street',       suburb: 'Darwin City',      state: 'NT', postcode: '0800' } },
+  { account_number: 'AUR-781422', name: 'Chloe Bennett',     address: { street: '26 Rundle Street',      suburb: 'Kent Town',        state: 'SA', postcode: '5067' } },
+  { account_number: 'AUR-816559', name: 'Liam Fitzgerald',   address: { street: '410/88 Queen Street',   suburb: 'Melbourne',        state: 'VIC', postcode: '3000' } },
+  { account_number: 'AUR-849073', name: 'Sofia Delgado',     address: { street: '17 Cavill Avenue',      suburb: 'Surfers Paradise', state: 'QLD', postcode: '4217' } },
+  { account_number: 'AUR-873318', name: 'Noah Kirkwood',     address: { street: '54 Hunter Street',      suburb: 'Newcastle',        state: 'NSW', postcode: '2300' } },
+  { account_number: 'AUR-905642', name: 'Mei Lin Tan',       address: { street: '2/33 Rokeby Road',      suburb: 'Subiaco',          state: 'WA', postcode: '6008' } },
+  { account_number: 'AUR-938177', name: 'Jack Rasmussen',    address: { street: '6 Elizabeth Street',    suburb: 'Launceston',       state: 'TAS', postcode: '7250' } },
+  { account_number: 'AUR-960845', name: 'Aaliyah Bennett',   address: { street: '82 Charles Street',     suburb: 'Northcote',        state: 'VIC', postcode: '3070' } },
+  { account_number: 'AUR-984312', name: 'Oscar Petrov',      address: { street: '19 Macquarie Street',   suburb: 'Hobart',           state: 'TAS', postcode: '7000' } },
+  { account_number: 'AUR-991026', name: 'Ruby Anderson',     address: { street: '301/5 Cordelia Street', suburb: 'South Brisbane',   state: 'QLD', postcode: '4101' } },
+  { account_number: 'AUR-995518', name: 'Henry Abebe',       address: { street: '14 Wakefield Street',   suburb: 'Kent Town',        state: 'SA', postcode: '5067' } },
+  { account_number: 'AUR-997430', name: 'Zoe Castellano',    address: { street: '67 Bay Street',         suburb: 'Port Melbourne',   state: 'VIC', postcode: '3207' } },
+  { account_number: 'AUR-999201', name: 'Felix Nakamura',    address: { street: '23 Anzac Parade',       suburb: 'Kensington',       state: 'NSW', postcode: '2033' } },
 ];
 
 function loadRoster(): RosterEntry[] {
@@ -6456,8 +6582,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
  *
@@ -6468,6 +6595,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.
@@ -6478,8 +6622,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)';
@@ -6495,18 +6648,48 @@ 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();
+/**
+ * Does this row answer the filter?
+ *
+ * NAME OR ACCOUNT NUMBER, because a partner checking whether a dispatch landed
+ * knows the person either way round, and typing "hoop" is faster than finding
+ * the account number to type it exactly.
+ */
+function matches(query: string, name: string, account: string): boolean {
+  if (!query) return true;
+  const q = query.toLowerCase();
+  return name.toLowerCase().includes(q) || account.toLowerCase().includes(q);
+}
+
+/** The roster, as display rows, optionally filtered. */
+function rosterRows(store: Store, query: string): string[] {
+  return store.allCustomers()
+    .filter((c) => matches(query, c.name, c.account_number))
+    .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(14)} \${esc(c.name).padEnd(20)} \${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, query: string): string[] {
+  const out: string[] = [];
+  for (const h of store.addressHistory(limit)) {
+    if (!matches(query, h.name, h.account_number)) continue;
+    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) {
@@ -6514,7 +6697,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) {
@@ -6529,6 +6711,167 @@ async function main(): Promise<void> {
   console.log('');
 }
 
+/**
+ * The live view: the mark, the roster, the changes, refreshed as they land.
+ *
+ * SEARCH IS THE REASON THIS IS NOT JUST A PRINT. A roster of three fits on a
+ * screen and a realistic one does not, so "is my own record right" stopped
+ * being answerable by looking. \`/\` filters both panels at once on name or
+ * account number, because a partner checking a dispatch landed knows the person
+ * either way round.
+ */
+function stream(store: Store, limit: number): void {
+  const screen = blessed.screen({
+    smartCSR: true,
+    title: 'What this receiver holds \u2014 OneAddress',
+    fullUnicode: true,
+    // WITHOUT THIS THE BRAND COMES OUT RED, and it came out red here for a
+    // whole release because this is the SECOND blessed screen in the scaffold
+    // and the fix lived only in the first. blessed resolves a hex colour
+    // against the palette it infers from TERM, which Windows does not set, so
+    // it assumes a tiny palette and snaps #e0a248 to the nearest thing it
+    // believes exists. Naming the capability is telling it the truth.
+    // \`scripts/__tests__\` pins that EVERY screen we open carries this.
+    terminal: process.env.TERM || 'xterm-256color',
+  });
+
+  const wide = terminalFitsFullMark(Number(screen.width));
+  // THE MARK, PLUS A LINE SAYING WHICH SCREEN THIS IS. The dashboard and this
+  // viewer open with the same wordmark, so without a subheader a screenshot of
+  // one is indistinguishable from the other - and they answer different
+  // questions. The dashboard is "is it running"; this is "what does it hold".
+  const markHeight = (wide ? 9 : 3) + 1;
+  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}{/}\`)
+      + \`\\n{\${DIM}-fg}WHAT THIS RECEIVER HOLDS{/}\`,
+  });
+
+  // THE ROSTER IS BOUNDED AND SCROLLS. It used to size itself to its contents,
+  // which was fine for three customers and pushes the changes panel off the
+  // bottom of the screen for a realistic roster.
+  const usable = Math.max(8, Number(screen.height) - markHeight - 1);
+  const rosterHeight = Math.max(5, Math.min(Math.floor(usable * 0.45), usable - 5));
+
+  const rosterBox = blessed.box({
+    parent: screen, top: markHeight, left: 0, width: '100%', height: rosterHeight,
+    tags: true, padding: { left: 1, right: 1 }, scrollable: true, alwaysScroll: true,
+    border: { type: 'line' }, style: { border: { fg: AMBER } },
+    label: ' ON FILE ',
+  });
+
+  const changesBox = blessed.box({
+    parent: screen, top: markHeight + rosterHeight, 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 ',
+  });
+
+  const footer = blessed.box({
+    parent: screen, bottom: 0, left: 0, width: '100%', height: 1,
+    tags: true, padding: { left: 2 },
+  });
+
+  let query = '';
+  let last = '';
+
+  const drawFooter = (): void => {
+    footer.setContent(query
+      ? \`{\${AMBER}-fg}filter: \${esc(query)}{/}   {\${CREAM}-fg}[/]{/} change  {\${CREAM}-fg}[esc]{/} clear  {\${CREAM}-fg}[q]{/} quit\`
+      : \`{\${DIM}-fg}live \u2014 updates as dispatches land{/}   {\${CREAM}-fg}[/]{/} search  {\${CREAM}-fg}[q]{/} quit\`);
+  };
+
+  const tick = (force = false): void => {
+    const all      = rosterRows(store, '');
+    const roster   = rosterRows(store, query);
+    const changes  = changeRows(store, limit, query);
+    const next = \`\${query}\\u0000\${roster.join('\\n')}\\u0000\${changes.join('\\n')}\`;
+    if (next === last && !force) return;
+    last = next;
+
+    rosterBox.setLabel(query
+      ? \` ON FILE \u2014 \${roster.length} of \${all.length} matching "\${esc(query)}" \`
+      : \` ON FILE \u2014 \${all.length} \`);
+    rosterBox.setContent(roster.join('\\n') ||
+      (query ? \`  Nobody matching "\${esc(query)}".\` : '  (nobody on file yet)'));
+
+    changesBox.setLabel(query
+      ? \` APPLIED CHANGES \u2014 matching "\${esc(query)}", newest first \`
+      : ' APPLIED CHANGES \u2014 newest first ');
+    changesBox.setContent(changes.join('\\n') || (query
+      ? \`  No applied change for "\${esc(query)}" yet.\`
+      : '  None yet. Send a dispatch and this fills in.'));
+
+    drawFooter();
+    screen.render();
+  };
+
+  // \`/\` OPENS A LIVE FILTER. It filters as you type rather than on Enter,
+  // because the question being asked is "is my record in here", and the answer
+  // is usually visible three characters in.
+  let searching = false;
+  const openSearch = (): void => {
+    searching = true;
+    const box = blessed.textbox({
+      parent: screen, bottom: 0, left: 0, width: '100%', height: 1,
+      style: { fg: CREAM }, inputOnFocus: true, keys: true,
+    });
+    box.setValue(query);
+    // The filter must update on every keystroke, and \`readInput\` only reports
+    // the final value, so the live half is driven off keypress.
+    box.on('keypress', () => {
+      setImmediate(() => { query = String(box.getValue() ?? '').trim(); tick(); });
+    });
+    screen.render();
+    box.readInput(() => {
+      searching = false;
+      query = String(box.getValue() ?? '').trim();
+      box.destroy();
+      tick(true);
+    });
+  };
+
+  screen.key(['/'], () => { if (!searching) openSearch(); });
+  screen.key(['escape'], () => {
+    if (searching) return;
+    if (!query) return;
+    query = '';
+    tick(true);
+  });
+  screen.key(['q', 'C-c'], () => {
+    if (searching) return;
+    screen.destroy();
+    process.exit(0);
+  });
+
+  tick(true);
+  // 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);
@@ -11903,7 +12246,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.6.0" : "dev";
+var PKG_VERSION = true ? "2.8.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");
@@ -12972,6 +13315,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.6.0",
+  "version": "2.8.0",
   "description": "Interactive setup wizard for OneAddress partner webhook integrations",
   "main": "dist/index.js",
   "bin": {