@oneaddress/setup 2.8.0 → 2.10.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.8.0" : "?";
+var WIZARD_VERSION = true ? "2.10.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": {
@@ -1022,6 +1023,7 @@ data.db-shm
       name: "customers.json",
       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.",
+  "//plaintext": "THIS FILE IS PLAINTEXT AND IS NOT ENCRYPTED. It is a seed you author and control, so treat it like any other file of customer data in your repo: keep it out of version control if it holds real people. The receiver's ENCRYPTED/UNENCRYPTED banner refers to its own database (records at rest, under ONEADDRESS_DB_PASSPHRASE), not to this file. Addresses that ARRIVE from OneAddress land in that database, never here.",
   "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" } },
@@ -1906,7 +1908,14 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     status.setContent(
       \`{\${AMBER}-fg}{bold}\${esc(partnerName)}{/}   \` +
       \`{\${DIM}-fg}listening{/} {\${CREAM}-fg}:\${port}/webhook{/}   \` +
-      \`{\${DIM}-fg}customer file{/} \${vault}   \` +
+      // "customer file" WAS THE WRONG WORDS FOR THE RIGHT VALUE, and it
+      // misread exactly as you would expect. store.encrypted is about the
+      // personal columns of THIS RECEIVER'S DATABASE. The only file a partner
+      // has been told to open is customers.json, which is a plaintext SEED
+      // that src/store.ts inserts from on startup - so a header reading
+      // "customer file ENCRYPTED" above a cleartext customers.json looked
+      // like a false claim about encryption. It was never measuring that file.
+      \`{\${DIM}-fg}records at rest{/} \${vault}   \` +
       // A DASH RATHER THAN A ZERO when the store declines to count. Zero is a
       // claim ("you have no customers") and would be a lie on a receiver
       // pointed at a real customer table, where counting every row forty times
@@ -4924,6 +4933,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);
@@ -4939,6 +4966,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.
@@ -5187,6 +5219,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;
 }
 
@@ -5213,6 +5249,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
@@ -5236,11 +5274,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;
 
@@ -5301,7 +5390,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);
@@ -5329,12 +5429,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
@@ -5386,8 +5488,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;
 `
@@ -6186,7 +6288,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,
@@ -6574,6 +6679,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);
+});
 `
     },
     {
@@ -6582,9 +6816,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
  *
@@ -6634,10 +6870,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> {
@@ -6684,6 +6942,12 @@ function changeRows(store: Store, limit: number, query: 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;
 }
@@ -6781,7 +7045,7 @@ function stream(store: Store, limit: number): void {
   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\`);
+      : \`{\${DIM}-fg}live\${REVEAL ? '' : ' \u2014 streets hidden, --reveal to show'}{/}   {\${CREAM}-fg}[/]{/} search  {\${CREAM}-fg}[q]{/} quit\`);
   };
 
   const tick = (force = false): void => {
@@ -12246,7 +12510,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.8.0" : "dev";
+var PKG_VERSION = true ? "2.10.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.8.0",
+  "version": "2.10.0",
   "description": "Interactive setup wizard for OneAddress partner webhook integrations",
   "main": "dist/index.js",
   "bin": {