@oneaddress/setup 2.7.0 → 2.9.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.7.0" : "?";
+var WIZARD_VERSION = true ? "2.9.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -984,6 +984,7 @@ data.db-shm
     "build":    "tsup src/index.ts --format esm --no-dts --outDir dist",
     "type-check": "tsc --noEmit",
     "show":     "tsx scripts/show.ts",
+    "audit":    "tsx scripts/audit.ts",
     "test":     "tsx scripts/test.ts"
   },
   "dependencies": {
@@ -1023,9 +1024,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" } }
   ]
 }
 `
@@ -4903,6 +4925,24 @@ db.exec(\`
     -- rather than only what it became.
     prev_address   TEXT NOT NULL DEFAULT '{}',
     address        TEXT NOT NULL,
+    -- ON WHOSE AUTHORITY. The reference of the signed authorisation that
+    -- produced this change, and the dispatch it arrived under.
+    --
+    -- WHY THEY ARE HERE AND NOT ONLY ON THE DASHBOARD. Both were computed on
+    -- arrival and shown on the LAST CHANGE panel, and nowhere else: a second
+    -- dispatch overwrote the panel and a restart cleared it. So "on whose
+    -- authority did you change this customer's address on the 15th" could not
+    -- be answered from this receiver at all, which is the first question an
+    -- inspection asks about an applied change.
+    --
+    -- NOT ENCRYPTED, deliberately, unlike the addresses beside them. Neither is
+    -- personal information: the reference is a digest of an authorisation and
+    -- the dispatch id is an integer. Encrypting them would make the audit trail
+    -- unreadable without the password in exactly the situation it exists for,
+    -- and would buy nothing, since an attacker who can read this file can read
+    -- the addresses too once they have what they came for.
+    loa_ref        TEXT,
+    dispatch_id    TEXT,
     recorded_at    TEXT NOT NULL DEFAULT (datetime('now'))
   );
   CREATE INDEX IF NOT EXISTS idx_history_account ON address_history(account_key, id DESC);
@@ -4918,6 +4958,11 @@ ensureColumn('customers', 'updated_at', 'TEXT'); // nullable on migrate; set on
 ensureColumn('customers', 'account_key', 'TEXT');
 ensureColumn('address_history', 'account_key', 'TEXT');
 ensureColumn('address_history', 'prev_address', "TEXT NOT NULL DEFAULT '{}'");
+// NULLABLE WITH NO DEFAULT, because a row written before this column existed
+// genuinely has no authority recorded and must not claim one. Null reads as
+// "not recorded", which is the truth; a default would read as a value.
+ensureColumn('address_history', 'loa_ref', 'TEXT');
+ensureColumn('address_history', 'dispatch_id', 'TEXT');
 
 // A database written before at-rest encryption existed holds plaintext rows and
 // no account_key. Backfill the key and encrypt in place.
@@ -5010,9 +5055,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[] {
@@ -5145,6 +5211,10 @@ export interface AddressChange {
   name: string;
   prev_address: Address | null;
   address: Address;
+  /** The authorisation this change was made under. Null on an older row. */
+  loa_ref: string | null;
+  /** The dispatch it arrived under. Null on an older row. */
+  dispatch_id: string | null;
   recorded_at: string;
 }
 
@@ -5171,6 +5241,8 @@ export function addressHistory(limit = 20): AddressChange[] {
   const rows = db.prepare(
     \`SELECT h.prev_address AS prev_address,
             h.address      AS address,
+            h.loa_ref      AS loa_ref,
+            h.dispatch_id  AS dispatch_id,
             h.recorded_at  AS recorded_at,
             c.account_number AS account_number,
             c.name           AS name
@@ -5194,11 +5266,62 @@ export function addressHistory(limit = 20): AddressChange[] {
       name:           dec('name', r.name) ?? '(unknown)',
       prev_address:   prev,
       address:        JSON.parse(dec('address', r.address) ?? '{}') as Address,
+      // NOT decrypted, because they were never encrypted. See the schema.
+      loa_ref:        r.loa_ref ?? null,
+      dispatch_id:    r.dispatch_id ?? null,
       recorded_at:    r.recorded_at ?? '',
     };
   });
 }
 
+/**
+ * Drop applied-change history older than \`days\`. Returns how many rows went.
+ *
+ * ## Why this exists, and why it is NOT wired to a timer
+ *
+ * The quarantine and the confirm queue both age out on their own, because both
+ * hold work in progress and an unbounded hold is a retention decision made on
+ * a consumer's behalf by nobody. \`address_history\` is different: it is the
+ * AUDIT TRAIL, and the same argument runs the other way. Deleting the record
+ * of a change you applied is not hygiene, it is losing the answer to "on whose
+ * authority", which is the first thing an inspection asks.
+ *
+ * So the default is to keep it, and that default is now a DECISION rather than
+ * an omission - which is the only thing that changed here. Before this
+ * function existed, keeping it forever was simply what happened, and a partner
+ * whose own retention policy required deletion had no lever to pull at all.
+ *
+ * ## If you do call it
+ *
+ * Your retention obligation and your evidentiary one point in opposite
+ * directions and only you know which governs your business. Australian
+ * financial-services records commonly run seven years; APP 11.2 says destroy
+ * or de-identify personal information you no longer need. Those are compatible
+ * only once someone decides what "no longer need" means here, and that someone
+ * is not this file.
+ *
+ * Nothing calls this by default. Wire it to your own schedule, or run it by
+ * hand, deliberately.
+ */
+export function purgeAddressHistory(days: number): number {
+  if (!Number.isFinite(days) || days <= 0) return 0;
+  // THE COMPARISON HAPPENS INSIDE SQLITE, in SQLite's own datetime format,
+  // for the same reason \`purgeQuarantine\` does it: \`recorded_at\` is written by
+  // the column default \`datetime('now')\`, and comparing that to a JavaScript
+  // ISO string works right up until it does not.
+  const info = db.prepare(
+    \`DELETE FROM address_history WHERE recorded_at < datetime('now', ?)\`,
+  ).run(\`-\${Math.floor(days)} days\`);
+  const n = Number(info.changes ?? 0);
+  if (n > 0) {
+    report.warn(
+      \`[store] purged \${n} applied-change record(s) older than \${Math.floor(days)}d. \` +
+      'That is audit history and it is gone.',
+    );
+  }
+  return n;
+}
+
 /** Is the file on disk protected? Surfaced in the dashboard, in both states. */
 export const storeEncrypted = encrypted;
 
@@ -5259,7 +5382,18 @@ export async function verifyAddress(customer: Customer, incoming: Address): Prom
  * ours \u2014 but be aware two customers who share a name share a row. If that is
  * possible in your data, give this a key of your own instead.
  */
-export async function saveAddress(customer: Customer, incoming: Address): Promise<Address> {
+export async function saveAddress(
+  customer: Customer,
+  incoming: Address,
+  /**
+   * On whose authority, recorded ALONGSIDE the change rather than beside it.
+   *
+   * Optional so an existing caller compiles, and the absence is honest: a row
+   * written without it says "not recorded" rather than claiming an authority
+   * it never had.
+   */
+  provenance?: { loaRef?: string | null; dispatchId?: string | null },
+): Promise<Address> {
   const acct = (customer.accountNumber ?? '').trim() || customer.name.trim();
   const addressJson = JSON.stringify(incoming);
   const key = accountKey(acct);
@@ -5287,12 +5421,14 @@ export async function saveAddress(customer: Customer, incoming: Address): Promis
   });
 
   db.prepare(\`
-    INSERT INTO address_history (account_key, prev_address, address)
-    VALUES ($account_key, $prev_address, $address)
+    INSERT INTO address_history (account_key, prev_address, address, loa_ref, dispatch_id)
+    VALUES ($account_key, $prev_address, $address, $loa_ref, $dispatch_id)
   \`).run({
     account_key: key,
     prev_address: enc('address', JSON.stringify(previous)),
     address: enc('address', addressJson),
+    loa_ref: provenance?.loaRef ?? null,
+    dispatch_id: provenance?.dispatchId ?? null,
   });
 
   // Metadata only \u2014 the address itself is personal information, so the key is
@@ -5344,8 +5480,8 @@ export const store = {
   verifyAddress,
   saveAddress,
   find: findByAccount,
-  // Three rows, so a count is free. A store over a real customer table should
-  // return null here; the contract file says why.
+  // A demo roster, so a count is free. A store over a real customer table
+  // should return null here; the contract file says why.
   count: customerCount,
 } satisfies CustomerStore;
 `
@@ -6144,7 +6280,10 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // than marking test dispatches as safe to display: a marker is something an
     // attacker can try to forge onto a real dispatch, and a panel that never
     // renders an address has nothing to forge it into.
-    const replaced = await store.saveAddress(ctx, address);
+    // PROVENANCE GOES IN WITH THE CHANGE. Both values were already computed
+    // here and went only to the dashboard panel, which one more dispatch or one
+    // restart wiped.
+    const replaced = await store.saveAddress(ctx, address, { loaRef, dispatchId: dispatch || null });
     noteChange({
       accountNumber:  ctx.accountNumber || '(no account reference)',
       accountChecked: config.verifiesAccountReference,
@@ -6532,6 +6671,135 @@ export async function ask(prompt: string): Promise<string> {
     stdin.on('data', onData);
   });
 }
+`
+    },
+    {
+      name: "scripts/audit.ts",
+      content: `/**
+ * Export the applied-change record: what changed, when, and on whose authority.
+ *
+ * Usage:
+ *   npm run audit                          \u2014 every applied change, as CSV
+ *   npm run audit -- --json                \u2014 the same as JSON
+ *   npm run audit -- --from 2026-07-01 --to 2026-09-30
+ *   npm run audit -- --out C:\\reports\\q3.csv
+ *
+ * ## Why this exists
+ *
+ * \`npm run show\` answers "did it land", for a person, now. This answers "show
+ * me every address change you applied last quarter and what authorised each
+ * one", for somebody who is not you and is not at your desk. Those are
+ * different questions and the second one is the one an inspection asks.
+ *
+ * ## What is in it, and what deliberately is not
+ *
+ * The account reference, the name, both sides of the change, the timestamp, the
+ * LOA reference and the dispatch id. That is the full record of a change this
+ * receiver applied.
+ *
+ * It is NOT redacted, unlike \`npm run show\`, and that is the point: this file
+ * is the thing you hand to an auditor, and a redacted audit trail is not one.
+ * It therefore contains personal information in cleartext the moment it is
+ * written, which is why it writes where you tell it, says where it went, and
+ * says so out loud.
+ *
+ * ## The one thing it cannot do
+ *
+ * It cannot prove the authority is genuine. \`loa_ref\` is recomputed by THIS
+ * receiver from the LOA it decrypted, so it is evidence this receiver saw a
+ * valid authorisation, not a signature anybody else can re-verify from the CSV.
+ * Verifying it independently needs OneAddress's LOA public key, which is a
+ * different exercise and is not what this file claims to be.
+ */
+import 'dotenv/config';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { config } from '../src/config.js';
+import { ask, databaseIsLocked } from '../src/unlock.js';
+
+function arg(name: string): string | null {
+  const i = process.argv.indexOf(\`--\${name}\`);
+  return i >= 0 && process.argv[i + 1] ? String(process.argv[i + 1]) : null;
+}
+
+/** CSV with the quoting rules that stop a comma in a street name shifting every column. */
+function csvCell(v: unknown): string {
+  const s = String(v ?? '');
+  return /[",\\n]/.test(s) ? \`"\${s.replace(/"/g, '""')}"\` : s;
+}
+
+function fmtAddress(a: Record<string, string> | null): string {
+  if (!a) return '';
+  return [a.street, a.suburb, a.state, a.postcode, a.country].filter(Boolean).join(', ');
+}
+
+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: your connector applies changes and holds the record.');
+    console.log('  Export from there instead.\\n');
+    return;
+  }
+
+  await askPassword();
+  const store = await import('../src/store.js');
+
+  const from = arg('from');
+  const to   = arg('to');
+  // EVERY row, then filtered here. The store's reader takes a limit rather than
+  // a date range, and a range that silently truncated at 20 would be worse than
+  // useless in an audit file.
+  const all = store.addressHistory(Number.MAX_SAFE_INTEGER);
+  const rows = all.filter((h) => {
+    const at = String(h.recorded_at ?? '');
+    if (from && at < from) return false;
+    // Inclusive of the whole end day: a --to of 2026-09-30 must include changes
+    // applied at 14:00 that day, and 'YYYY-MM-DD HH:MM:SS' > 'YYYY-MM-DD'.
+    if (to && at > \`\${to} 99\`) return false;
+    return true;
+  });
+
+  const asJson = process.argv.includes('--json');
+  const body = asJson
+    ? JSON.stringify({
+        exported_at: new Date().toISOString(),
+        range: { from: from ?? null, to: to ?? null },
+        note: 'Applied address changes recorded by this receiver. loa_ref is recomputed by this receiver from the authorisation it decrypted; verifying it independently needs the OneAddress LOA public key.',
+        changes: rows,
+      }, null, 2)
+    : [
+        ['recorded_at', 'account_number', 'name', 'previous_address', 'new_address', 'loa_ref', 'dispatch_id']
+          .join(','),
+        ...rows.map((h) => [
+          h.recorded_at, h.account_number, h.name,
+          fmtAddress(h.prev_address as unknown as Record<string, string> | null),
+          fmtAddress(h.address as unknown as Record<string, string>),
+          h.loa_ref ?? '', h.dispatch_id ?? '',
+        ].map(csvCell).join(',')),
+      ].join('\\n');
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const target = resolve(arg('out') ?? config.exportDir ?? '', arg('out')
+    ? ''
+    : \`oneaddress-audit-\${stamp}.\${asJson ? 'json' : 'csv'}\`);
+  writeFileSync(target, body);
+
+  console.log(\`\\n  Exported \${rows.length} applied change(s) to\\n  \${target}\\n\`);
+  console.log('  THIS FILE CONTAINS CUSTOMER ADDRESSES IN CLEARTEXT. It is the audit record,');
+  console.log('  so it is deliberately not redacted. Store and send it accordingly.\\n');
+}
+
+void main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});
 `
     },
     {
@@ -6540,9 +6808,11 @@ 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 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
+ *   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 -- --reveal \u2014 show street lines (hidden by default)
+ *   npm run show > f.txt    \u2014 plain one-shot text, for a file or a pipe
+ *   npm run audit           \u2014 export the applied-change record (see scripts/audit.ts)
  *
  * ## Why this script exists
  *
@@ -6592,10 +6862,32 @@ 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, '');
 
+/**
+ * REDACTED BY DEFAULT, revealed on purpose.
+ *
+ * This script's whole job is to show what the receiver holds, so refusing to
+ * print addresses would defeat it. But the default run prints EVERY customer's
+ * address into a terminal, where it lands in scrollback, in a \`| tee\` file and
+ * in any screen recording, and the commonest reason to run it is to check one
+ * record or prove one dispatch landed - neither of which needs the other 23.
+ *
+ * So the default shows enough to recognise a record (suburb, state, postcode)
+ * and withholds the street line, and \`--reveal\` prints the lot. The suburb is
+ * deliberately NOT withheld: an audit row you cannot tell apart from the next
+ * one is not an audit row, and the suburb is what makes a change legible as a
+ * change.
+ */
+const REVEAL = process.argv.includes('--reveal') || process.env.ONEADDRESS_SHOW_REVEAL === '1';
+
 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)';
+  const rest = [a.suburb, a.state, a.postcode, a.country].filter(Boolean).join(', ');
+  if (REVEAL) {
+    const parts = [a.street, a.suburb, a.state, a.postcode, a.country].filter(Boolean);
+    return parts.join(', ') || '(empty)';
+  }
+  if (!a.street) return rest || '(empty)';
+  return \`[street hidden], \${rest}\` || '(empty)';
 }
 
 async function askPassword(): Promise<void> {
@@ -6608,24 +6900,46 @@ async function askPassword(): Promise<void> {
 
 type Store = typeof import('../src/store.js');
 
-/** 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))}\`;
-  });
+/**
+ * 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))}\`;
+    });
 }
 
 /** Applied changes, newest first, as display rows with both sides. */
-function changeRows(store: Store, limit: number): string[] {
+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))}\`);
+    // ON WHOSE AUTHORITY, on its own line. Null means the row predates the
+    // column, which is not the same as a change nobody authorised, so it says
+    // so rather than printing an empty field.
+    out.push(h.loa_ref
+      ? \`      {\${DIM}-fg}auth:{/} \${esc(h.loa_ref)}\${h.dispatch_id ? \`  {\${DIM}-fg}dispatch{/} \${esc(h.dispatch_id)}\` : ''}\`
+      : \`      {\${DIM}-fg}auth: not recorded (applied before this receiver kept it){/}\`);
   }
   return out;
 }
@@ -6653,66 +6967,147 @@ function printOnce(store: Store, limit: number): void {
   console.log('');
 }
 
-/** The live view: the mark, the roster, the changes, refreshed as they land. */
+/**
+ * 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' });
+  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',
+  });
 
-  // 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;
+  // 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
+    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}{/}\`,
+      : \`{\${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: 'shrink',
-    tags: true, padding: { left: 1, right: 1 },
+    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 + 3, left: 0, width: '100%', bottom: 1,
+    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 ',
   });
 
-  blessed.box({
+  const footer = 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 query = '';
   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;
+
+  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\${REVEAL ? '' : ' \u2014 streets hidden, --reveal to show'}{/}   {\${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.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.');
+
+    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();
   };
 
-  screen.key(['q', 'C-c', 'escape'], () => { screen.destroy(); process.exit(0); });
-  tick();
-  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);
+  setInterval(() => tick(), 1000);
 }
 
 async function main(): Promise<void> {
@@ -12107,7 +12502,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.7.0" : "dev";
+var PKG_VERSION = true ? "2.9.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.7.0",
+  "version": "2.9.0",
   "description": "Interactive setup wizard for OneAddress partner webhook integrations",
   "main": "dist/index.js",
   "bin": {