@oneaddress/setup 1.6.2 → 2.0.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 ? "1.6.2" : "?";
+var WIZARD_VERSION = true ? "2.0.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -963,19 +963,22 @@ data.db-shm
   "version": "1.0.0",
   "private": true,
   "scripts": {
-    "dev":   "tsx watch src/server.ts",
-    "start": "node dist/server.js",
-    "build": "tsup src/server.ts --format cjs --no-dts --outDir dist",
+    "dev":      "tsx watch src/index.ts",
+    "start":    "tsx src/index.ts",
+    "headless": "tsx src/index.ts -- --headless",
+    "build":    "tsup src/index.ts --format esm --no-dts --outDir dist",
     "type-check": "tsc --noEmit",
-    "test":  "tsx scripts/test.ts"
+    "test":     "tsx scripts/test.ts"
   },
   "dependencies": {
     "@oneaddress/partner-sdk": "^1.8.0",
+    "blessed": "^0.1.81",
     "dotenv":  "^16.0.0",
     "express": "^4.18.0",
     "express-rate-limit": "^8.6.2"
   },
   "devDependencies": {
+    "@types/blessed": "^0.1.25",
     "@types/express": "^4.17.0",
     "@types/node":    "^22.5.0",
     "tsup":           "^8.0.0",
@@ -1041,32 +1044,844 @@ data.db-shm
     {
       name: "src/db.ts",
       content: `/**
- * SQLite database \u2014 initialised automatically on first run.
+ * SQLite database, and the at-rest encryption layer over it.
  *
- * Uses the Node.js built-in \`node:sqlite\` module (available in Node 22.5+).
- * No extra packages or native compilation required.
+ * Uses the built-in \`node:sqlite\` module (Node 22.5+), so there is nothing to
+ * compile and nothing extra to install.
  *
- * This module only OPENS the database and exports the handle. The schema \u2014 the
- * customer roster plus the append-only address-history audit trail \u2014 is created
- * by src/store.ts, which OWNS those tables, so everything about how your data is
- * shaped lives in the one file you are meant to edit.
+ * This module opens the file, derives the at-rest keys, and exports the helpers
+ * \`src/store.ts\` uses to encrypt on the way in and decrypt on the way out. The
+ * SCHEMA lives in store.ts, which owns your data shape, so everything you are
+ * meant to edit stays in the one file.
  *
- * The database file lives at DB_PATH (default: data.db in the project root).
- * Change the location with the DB_PATH environment variable.
+ * ## Where the passphrase comes from
+ *
+ * \`ONEADDRESS_DB_PASSPHRASE\`, read once when this module loads. \`src/index.ts\`
+ * prompts for it and sets it before importing anything that touches the
+ * database, so a service can supply it from the environment and a person can
+ * type it. Deliberately an environment variable rather than an argument
+ * threaded through every call: the store is a module-level singleton, and a
+ * half-initialised one is worse than either alternative.
+ *
+ * ## Unencrypted is a supported mode
+ *
+ * No passphrase means the database runs in the clear, exactly as it did before
+ * this existed. That keeps an existing install working and lets you try the
+ * receiver without deciding anything. The dashboard shows which mode you are
+ * in, and shows the unencrypted one in red, because a protection you only
+ * mention when it is present is one nobody notices the absence of.
  */
 import { DatabaseSync } from 'node:sqlite';
 import { join } from 'node:path';
+import {
+  accountIndex,
+  buildVerifier,
+  decryptField,
+  deriveKeys,
+  encryptField,
+  isEncrypted,
+  newSalt,
+  verifierMatches,
+  WrongPassphraseError,
+  type VaultKeys,
+} from './vault.js';
 
 const DB_PATH = process.env.DB_PATH ?? join(process.cwd(), 'data.db');
 
 const db = new DatabaseSync(DB_PATH);
+db.exec('PRAGMA journal_mode = WAL');
+
+// Holds the salt and the verifier. Created before anything else needs them.
+db.exec(\`
+  CREATE TABLE IF NOT EXISTS db_meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+\`);
+
+function readMeta(key: string): string | null {
+  const row = db.prepare('SELECT value FROM db_meta WHERE key = ?').get(key) as
+    | { value: string }
+    | undefined;
+  return row?.value ?? null;
+}
+
+function writeMeta(key: string, value: string): void {
+  db.prepare(
+    'INSERT INTO db_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
+  ).run(key, value);
+}
+
+/**
+ * The salt for this database file.
+ *
+ * Written once and thereafter only read. Derive from a different salt and the
+ * same passphrase produces different keys, which makes every existing row
+ * unreadable, so this must never be regenerated for a file that has data.
+ */
+function saltForThisDatabase(): Buffer {
+  const existing = readMeta('salt');
+  if (existing) return Buffer.from(existing, 'base64');
+  const salt = newSalt();
+  writeMeta('salt', salt.toString('base64'));
+  return salt;
+}
+
+function openKeys(): VaultKeys | null {
+  const passphrase = process.env.ONEADDRESS_DB_PASSPHRASE;
+  if (!passphrase || !passphrase.trim()) return null;
 
-// WAL mode \u2014 better performance for concurrent reads
-db.exec("PRAGMA journal_mode = WAL");
+  const keys = deriveKeys(passphrase, saltForThisDatabase());
 
-console.log(\`[db] SQLite database ready \u2192 \${DB_PATH}\`);
+  // Checked BEFORE anything is written. A mistyped passphrase must not be able
+  // to write a single row of ciphertext that nothing can ever read back.
+  const stored = readMeta('verifier');
+  if (stored === null) writeMeta('verifier', buildVerifier(keys));
+  else if (!verifierMatches(keys, stored)) throw new WrongPassphraseError();
+
+  return keys;
+}
+
+const keys = openKeys();
+
+/** True when the personal columns in this file are ciphertext. */
+export const encrypted = keys !== null;
+
+/** Encrypt one field for storage, or pass it through when running in the clear. */
+export function enc(column: string, value: string | null): string | null {
+  return keys ? encryptField(keys, column, value) : value;
+}
+
+/** Decrypt one stored field. Plaintext passes through, so a migrating file works. */
+export function dec(column: string, value: string | null): string | null {
+  return keys ? decryptField(keys, column, value) : value;
+}
+
+/**
+ * The value to store and query an account number by.
+ *
+ * A blind index when locked, the plain number otherwise. This is what keeps the
+ * account lookup an exact indexed hit rather than a table scan, which matters
+ * because every dispatch resolves on it.
+ */
+export function accountKey(accountNumber: string): string {
+  return keys ? accountIndex(keys, accountNumber) : accountNumber.trim().toLowerCase();
+}
+
+/**
+ * Encrypt a value unless it already is encrypted.
+ *
+ * \`encryptField\` cannot tell a ciphertext from a plaintext and will encrypt one
+ * twice if asked, leaving a row that decrypts to an envelope rather than to an
+ * address. Anything that re-writes existing rows must go through this, not
+ * through \`enc\`, and then re-running a migration is harmless by construction
+ * rather than by remembering to set a flag.
+ */
+export function once(column: string, value: string | null): string | null {
+  if (!keys) return value;
+  return isEncrypted(value) ? value : encryptField(keys, column, value);
+}
 
+export { WrongPassphraseError };
 export default db;
+`
+    },
+    {
+      name: "src/brand.ts",
+      content: `/**
+ * OneAddress brand for the terminal.
+ *
+ * The same wordmark, palette and geometry the setup wizard prints, so the
+ * receiver a partner ends up running looks like the tool that installed it and
+ * like the site they signed up on. One brand, three surfaces.
+ *
+ * ## Why the mark is pixel art rather than an image
+ *
+ * A terminal has no images. The wordmark is drawn from 7-row glyphs at 7
+ * columns each, which is the only representation that survives SSH, tmux, a
+ * Windows console and a CI log unchanged. It is the same glyph set the wizard
+ * uses, deliberately: a redrawn "close enough" version is how two marks that
+ * are supposed to be one start to drift.
+ *
+ * ## The width rule that is easy to get wrong
+ *
+ * The full banner is 88 columns. A default Git Bash window is 80, so the full
+ * mark wraps there and shows the logo half-cut, which looks broken rather than
+ * looking large. Under 88 columns we print a compact framed wordmark instead:
+ * it fits any real terminal and says the same thing. Check the width, never
+ * assume it.
+ */
+
+// \u2500\u2500 Palette \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Hex values are the design system's, not approximations: amber #E0A248 and
+// cream #F5EED8 are the same constants the web app's \`C\` object carries.
+export const HEX = {
+  amber: '#E0A248',
+  amberLight: '#F0C878',
+  cream: '#F5EED8',
+  ink: '#13151C',
+  faint: '#82642D',
+  dim: '#463A23',
+  mid: '#9B8764',
+} as const;
+
+// \u2500\u2500 ANSI, for the boot lines printed before the dashboard takes the screen \u2500\u2500\u2500
+const R = '\\x1b[0m';
+const B = '\\x1b[1m';
+const AMB = '\\x1b[38;2;224;162;72m';
+const CRM = '\\x1b[38;2;245;238;216m';
+const FNT = '\\x1b[38;2;130;100;45m';
+const DIM = '\\x1b[38;2;70;58;35m';
+
+export const amber = (s: string) => \`\${B}\${AMB}\${s}\${R}\`;
+export const cream = (s: string) => \`\${B}\${CRM}\${s}\${R}\`;
+export const faint = (s: string) => \`\${FNT}\${s}\${R}\`;
+export const dim = (s: string) => \`\${DIM}\${s}\${R}\`;
+
+// \u2500\u2500 Wordmark glyphs \u2014 7 rows, 7 columns each \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+/* eslint-disable no-multi-spaces */
+const _O = [' \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', ' \u2588\u2588\u2588\u2588\u2588 '];
+const _N = ['\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\u2588\u2588\u2588', '\u2588\u2588  \u2588\u2588\u2588', '\u2588\u2588   \u2588\u2588'];
+const _E = ['\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\u2588\u2588\u2588'];
+const _A = ['  \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\u2588', '\u2588\u2588   \u2588\u2588'];
+const _D = ['\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\u2588', '\u2588\u2588\u2588\u2588\u2588\u2588 '];
+const _RG = ['\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\u2588 \u2588\u2588  ', '\u2588\u2588  \u2588\u2588 '];
+const _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 '];
+/* eslint-enable no-multi-spaces */
+
+/** "ONE" in cream, 23 columns wide. */
+export const ONE_ROWS = Array.from({ length: 7 }, (_, i) => [_O[i], _N[i], _E[i]].join(' '));
+
+/** "ADDRESS" in amber, 55 columns wide. */
+export const ADDRESS_ROWS = Array.from(
+  { length: 7 },
+  (_, i) => [_A[i], _D[i], _D[i], _RG[i], _E[i], _S[i], _S[i]].join(' '),
+);
+
+/** Columns the full banner needs. Below this, use the compact mark. */
+export const FULL_BANNER_COLUMNS = 88;
+
+/** Does this terminal have room for the full wordmark? */
+export function terminalFitsFullMark(columns = process.stdout.columns ?? 80): boolean {
+  return columns >= FULL_BANNER_COLUMNS;
+}
+
+/**
+ * Print the boot banner to stdout, before any full-screen UI starts.
+ *
+ * Deliberately plain \`console.log\`: this runs while the terminal is still a
+ * terminal. Once the dashboard starts, blessed owns the screen and nothing may
+ * write to stdout behind its back.
+ */
+export function printBanner(subtitle: string): void {
+  const wide = terminalFitsFullMark();
+  console.log('');
+  if (wide) {
+    for (let i = 0; i < 7; i++) {
+      console.log('  ' + cream(ONE_ROWS[i]) + ' ' + amber(ADDRESS_ROWS[i]));
+    }
+  } else {
+    const INNER = 42;
+    console.log(' ' + faint('\u250C') + dim('\u2500'.repeat(INNER)) + faint('\u2510'));
+    const pad = (s: string, len: number) => s + ' '.repeat(Math.max(0, INNER - 2 - len));
+    const mark = cream('One') + amber('Address');
+    console.log(' ' + dim('\u2502') + '  ' + pad(mark, 10) + dim('\u2502'));
+    console.log(' ' + faint('\u2514') + dim('\u2500'.repeat(INNER)) + faint('\u2518'));
+  }
+  console.log('');
+  console.log('  ' + faint(subtitle));
+  console.log('');
+}
+`
+    },
+    {
+      name: "src/vault.ts",
+      content: `/**
+ * At-rest encryption for YOUR customer database.
+ *
+ * ## Two keys, and why they must not be one
+ *
+ * This receiver holds two secrets that do completely different jobs:
+ *
+ *   - PARTNER_PRIVATE_KEY_PEM is the ECDH key OneAddress holds the public half
+ *     of. It decrypts what ARRIVES. OneAddress chose to send to it.
+ *   - the key derived here is yours alone, from a passphrase OneAddress has
+ *     never seen and cannot ask you for. It protects what is STORED.
+ *
+ * Using one key for both would mean the credential you share with a counterparty
+ * is also the key to your own customer file. Keep them apart.
+ *
+ * ## Field-level, and what that leaves visible
+ *
+ * Whole-file encryption would need SQLCipher and a native build. This encrypts
+ * the personal columns using Node's built-in crypto, so it installs anywhere
+ * Node runs. Be clear-eyed about what the file still reveals:
+ *
+ *   - how many customers there are
+ *   - when each record changed, and how often
+ *   - a stable per-account index, so rows can be told apart and watched
+ *
+ * What it protects: every name, address, email and phone number. Someone who
+ * copies data.db off this machine gets none of those.
+ *
+ * ## It fails closed, and says why
+ *
+ * A known token is stored encrypted under the derived key, so a wrong passphrase
+ * is caught when the database opens rather than as decryption errors on your
+ * first real dispatch, which reads as data corruption instead of as a typo.
+ */
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHmac,
+  randomBytes,
+  scryptSync,
+  timingSafeEqual,
+} from 'node:crypto';
+
+/** Envelope version. A format change becomes detectable rather than silent. */
+const VERSION = 'v1';
+
+/** scrypt cost. Paid once when the database opens, never per row. */
+const SCRYPT_N = 32768;
+const SCRYPT_KEYLEN = 64;
+
+/**
+ * scrypt needs 128 * N * r bytes, which at N=32768 and the default r=8 is about
+ * 33.5 MB, just over Node's default 32 MB cap. Raised deliberately rather than
+ * lowering N, because N is the cost and reducing it to fit a default is
+ * weakening the protection on purpose.
+ */
+const SCRYPT_MAXMEM = 64 * 1024 * 1024;
+
+const VERIFIER_PLAINTEXT = 'oneaddress-receiver-at-rest-v1';
+
+export class WrongPassphraseError extends Error {
+  constructor() {
+    super('That passphrase does not open this database.');
+    this.name = 'WrongPassphraseError';
+  }
+}
+
+export interface VaultKeys {
+  /** AES-256-GCM key for the personal columns. */
+  cipherKey: Buffer;
+  /** HMAC key for the account blind index. Separate on purpose. */
+  macKey: Buffer;
+}
+
+/**
+ * Derive both keys from one passphrase.
+ *
+ * Two keys, not one used twice: an AES key doubling as an HMAC key is a
+ * cross-protocol mistake, and splitting costs nothing.
+ */
+export function deriveKeys(passphrase: string, salt: Buffer): VaultKeys {
+  const full = scryptSync(passphrase.normalize('NFKC'), salt, SCRYPT_KEYLEN, {
+    N: SCRYPT_N,
+    maxmem: SCRYPT_MAXMEM,
+  });
+  return { cipherKey: full.subarray(0, 32), macKey: full.subarray(32, 64) };
+}
+
+/** A fresh per-database salt. Stored alongside the data; not a secret. */
+export function newSalt(): Buffer {
+  return randomBytes(16);
+}
+
+/**
+ * Bind a ciphertext to the column it belongs in.
+ *
+ * AES-GCM authenticates bytes and has no opinion about where they were stored,
+ * so without this a postcode ciphertext moved into the street column decrypts
+ * cleanly and the row reads back wrong. With it, the tag check fails.
+ */
+function aad(column: string): Buffer {
+  return Buffer.from(\`oa-receiver|\${VERSION}|\${column}\`, 'utf8');
+}
+
+/**
+ * Encrypt one field.
+ *
+ * An absent value stays absent: encrypting null would give every missing phone
+ * number a distinct-looking ciphertext that then renders as garbage.
+ */
+export function encryptField(keys: VaultKeys, column: string, plaintext: string | null): string | null {
+  if (plaintext === null || plaintext === '') return plaintext;
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', keys.cipherKey, iv, { authTagLength: 16 });
+  cipher.setAAD(aad(column));
+  const ct = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  return [
+    VERSION,
+    iv.toString('base64url'),
+    cipher.getAuthTag().toString('base64url'),
+    ct.toString('base64url'),
+  ].join('.');
+}
+
+/** True when a stored value carries this module's envelope. */
+export function isEncrypted(value: string | null): boolean {
+  return typeof value === 'string' && value.startsWith(\`\${VERSION}.\`) && value.split('.').length === 4;
+}
+
+/**
+ * Decrypt one field.
+ *
+ * A value that is not in the envelope format is returned unchanged, so a
+ * database written before you set a passphrase keeps working while it migrates.
+ */
+export function decryptField(keys: VaultKeys, column: string, stored: string | null): string | null {
+  if (stored === null || stored === '') return stored;
+  if (!isEncrypted(stored)) return stored;
+
+  const [, ivB64, tagB64, ctB64] = stored.split('.');
+  const decipher = createDecipheriv('aes-256-gcm', keys.cipherKey, Buffer.from(ivB64, 'base64url'), {
+    authTagLength: 16,
+  });
+  decipher.setAAD(aad(column));
+  decipher.setAuthTag(Buffer.from(tagB64, 'base64url'));
+  return Buffer.concat([
+    decipher.update(Buffer.from(ctB64, 'base64url')),
+    decipher.final(),
+  ]).toString('utf8');
+}
+
+/**
+ * Deterministic index for the account-number lookup.
+ *
+ * The account number is the one column that must stay searchable by exact
+ * equality, because every dispatch resolves on it. An HMAC under a key an
+ * attacker does not hold keeps that lookup exact while leaving the number
+ * itself unreadable in the file. Lower-cased, matching the case-insensitive
+ * comparison it replaces.
+ */
+export function accountIndex(keys: VaultKeys, accountNumber: string): string {
+  return createHmac('sha256', keys.macKey)
+    .update(accountNumber.trim().toLowerCase(), 'utf8')
+    .digest('hex');
+}
+
+/** The token stored when a database is first locked. */
+export function buildVerifier(keys: VaultKeys): string {
+  return encryptField(keys, 'verifier', VERIFIER_PLAINTEXT)!;
+}
+
+/** Check a passphrase against the stored verifier before any row is touched. */
+export function verifierMatches(keys: VaultKeys, storedVerifier: string): boolean {
+  let decrypted: string | null;
+  try {
+    decrypted = decryptField(keys, 'verifier', storedVerifier);
+  } catch {
+    return false; // A tag failure is exactly what a wrong passphrase looks like.
+  }
+  if (decrypted === null) return false;
+  const a = Buffer.from(decrypted, 'utf8');
+  const b = Buffer.from(VERIFIER_PLAINTEXT, 'utf8');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+`
+    },
+    {
+      name: "src/report.ts",
+      content: `/**
+ * Where this receiver's narration goes.
+ *
+ * ## Why this exists instead of \`console.log\`
+ *
+ * The dashboard (\`src/tui.ts\`) takes over the terminal. Anything written to
+ * stdout while it is running lands on top of the drawn screen and corrupts it,
+ * so the protocol layer cannot simply print. It reports, and whoever is running
+ * decides where that goes: the dashboard renders it into the event log, and
+ * \`--headless\` writes it to stdout exactly as this receiver always did.
+ *
+ * ## The signature is console's on purpose
+ *
+ * \`info\`, \`warn\` and \`error\` take the same variadic arguments as \`console.log\`,
+ * \`console.warn\` and \`console.error\`, so a message reads identically at the call
+ * site and the default sink can hand them straight through. That is deliberate:
+ * the alternative is rewriting two dozen messages into some structured shape,
+ * which changes what a partner sees in their logs for no benefit and makes the
+ * diff impossible to review.
+ *
+ * ## Default is stdout, so nothing is ever silently swallowed
+ *
+ * With no sink attached this IS \`console\`. A receiver started without the
+ * dashboard, a script that imports the server, a crash before the UI is up:
+ * all of them print. The dashboard attaches a sink and detaches on exit.
+ */
+
+export type ReportLevel = 'info' | 'warn' | 'error';
+
+export interface ReportLine {
+  /** Unix ms, so a sink can render its own timestamp. */
+  at: number;
+  level: ReportLevel;
+  /** The arguments exactly as the call site passed them. */
+  args: unknown[];
+}
+
+type Sink = (line: ReportLine) => void;
+
+/** Write to stdout, matching what this receiver printed before the dashboard existed. */
+const consoleSink: Sink = ({ level, args }) => {
+  if (level === 'error') console.error(...args);
+  else if (level === 'warn') console.warn(...args);
+  else console.log(...args);
+};
+
+let sink: Sink = consoleSink;
+
+function emit(level: ReportLevel, args: unknown[]): void {
+  // A sink that throws must never take the server down with it. A broken UI is
+  // a broken UI; a dropped dispatch is a customer's address not arriving.
+  try {
+    sink({ at: Date.now(), level, args });
+  } catch {
+    consoleSink({ at: Date.now(), level, args });
+  }
+}
+
+export const report = {
+  info: (...args: unknown[]): void => emit('info', args),
+  warn: (...args: unknown[]): void => emit('warn', args),
+  error: (...args: unknown[]): void => emit('error', args),
+
+  /** Send lines somewhere else. Returns a function that restores stdout. */
+  attach(next: Sink): () => void {
+    const previous = sink;
+    sink = next;
+    return () => { sink = previous; };
+  },
+};
+
+/** Render one reported line the way the plain console would have. */
+export function formatLine(line: ReportLine): string {
+  return line.args
+    .map((a) => {
+      if (typeof a === 'string') return a;
+      if (a instanceof Error) return a.message;
+      try { return JSON.stringify(a); } catch { return String(a); }
+    })
+    .join(' ');
+}
+`
+    },
+    {
+      name: "src/tui.ts",
+      content: `/**
+ * The receiver's terminal dashboard.
+ *
+ * Watching a webhook receiver used to mean tailing a log and hoping. This shows
+ * the three things an operator actually wants while an integration is live:
+ * whether the server is up, whether the customer file is protected, and what
+ * the last dispatch changed, old address and new, side by side.
+ *
+ * ## It is a VIEW, and holds no logic of its own
+ *
+ * Every line it renders arrives through \`report\` (\`src/report.ts\`), which the
+ * protocol layer writes to. The dashboard never parses a webhook, never touches
+ * the database except to read counts, and never decides anything. Pull it out
+ * and the receiver behaves identically with its narration on stdout, which is
+ * exactly what \`--headless\` does.
+ *
+ * ## blessed owns the screen
+ *
+ * Once this starts, NOTHING may write to stdout: a stray \`console.log\` lands on
+ * top of the drawn screen and corrupts it. That is the whole reason \`report\`
+ * exists. On exit the sink is detached before the screen is destroyed, so a
+ * shutdown message still reaches the terminal.
+ */
+import blessed from 'blessed';
+import { HEX, ONE_ROWS, ADDRESS_ROWS, terminalFitsFullMark } from './brand.js';
+import { formatLine, report, type ReportLine } from './report.js';
+import { allCustomers, customerCount, storeEncrypted, type StoredCustomer } from './store.js';
+
+/** blessed takes colours as strings; these mirror the site's palette. */
+const AMBER = HEX.amber;
+const CREAM = HEX.cream;
+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, '');
+
+export interface TuiOptions {
+  partnerName: string;
+  port: number;
+  /** Called when the operator quits, so the caller can close the server. */
+  onQuit: () => void;
+}
+
+/** One address as a single line, the way the change panel shows it. */
+function oneLine(a: Record<string, unknown>): string {
+  const parts = [a.street, a.suburb, a.state, a.postcode].filter(Boolean).map(String);
+  return parts.length > 0 ? parts.join(', ') : '(empty)';
+}
+
+export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void {
+  const screen = blessed.screen({
+    smartCSR: true,
+    title: \`\${partnerName} \u2014 OneAddress receiver\`,
+    fullUnicode: true,
+  });
+
+  // \u2500\u2500 Masthead \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // The full pixel-art wordmark needs 88 columns. Below that it wraps and shows
+  // the logo half-cut, which looks broken rather than looking large, so a
+  // narrow terminal gets the compact lockup instead. Same rule as the wizard.
+  const wide = terminalFitsFullMark(Number(screen.width));
+  const markHeight = wide ? 9 : 3;
+
+  const mark = blessed.box({
+    parent: screen, top: 0, left: 0, width: '100%', height: markHeight,
+    tags: true, padding: { left: 2 },
+    content: wide
+      ? ONE_ROWS.map((row, i) => \`{\${CREAM}-fg}\${row}{/} {\${AMBER}-fg}\${ADDRESS_ROWS[i]}{/}\`).join('\\n')
+      : \`{\${CREAM}-fg}{bold}One{/bold}{/}{\${AMBER}-fg}{bold}Address{/bold}{/}\`,
+  });
+
+  const status = blessed.box({
+    parent: screen, top: markHeight, left: 0, width: '100%', height: 3,
+    tags: true, padding: { left: 2 },
+    border: { type: 'line' } as never,
+    style: { border: { fg: DIM } },
+  });
+
+  // \u2500\u2500 The change panel: what the last dispatch replaced \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  const changeBox = blessed.box({
+    parent: screen, top: markHeight + 3, left: 0, width: '50%', bottom: 3,
+    label: ' LAST CHANGE ', tags: true, padding: { left: 1, right: 1 },
+    border: { type: 'line' } as never,
+    style: { border: { fg: AMBER }, label: { fg: AMBER } },
+  });
+
+  const logBox = blessed.log({
+    parent: screen, top: markHeight + 3, left: '50%', width: '50%', bottom: 3,
+    label: ' ACTIVITY ', tags: true, scrollable: true, alwaysScroll: true,
+    padding: { left: 1, right: 1 },
+    border: { type: 'line' } as never,
+    style: { border: { fg: DIM }, label: { fg: DIM } },
+  });
+
+  const footer = blessed.box({
+    parent: screen, bottom: 0, left: 0, width: '100%', height: 3,
+    tags: true, padding: { left: 2 },
+    border: { type: 'line' } as never,
+    style: { border: { fg: DIM } },
+  });
+
+  // \u2500\u2500 State \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  let received = 0;
+  let applied = 0;
+  let failed = 0;
+  let lastChange: { customer: StoredCustomer; previous: Record<string, unknown> } | null = null;
+  let pendingPrevious: Record<string, unknown> = {};
+
+  // The server hands over the address a dispatch REPLACED. Kept as state here
+  // rather than pushed through \`report\`, because the previous address is data
+  // rather than narration and must never end up in a log line.
+  setPrevious = (prev) => { pendingPrevious = prev; };
+
+  function renderStatus(): void {
+    // Both states are shown, and the unprotected one is the loud colour. A
+    // security property mentioned only when it holds is one nobody notices the
+    // absence of.
+    const vault = storeEncrypted
+      ? \`{green-fg}{bold}ENCRYPTED{/}\`
+      : \`{red-fg}{bold}UNENCRYPTED{/}\`;
+    status.setContent(
+      \`{\${AMBER}-fg}{bold}\${esc(partnerName)}{/}   \` +
+      \`{\${DIM}-fg}listening{/} {\${CREAM}-fg}:\${port}/webhook{/}   \` +
+      \`{\${DIM}-fg}customer file{/} \${vault}   \` +
+      \`{\${DIM}-fg}on file{/} {\${CREAM}-fg}\${customerCount().toLocaleString()}{/}\`,
+    );
+  }
+
+  function renderChange(): void {
+    if (!lastChange) {
+      changeBox.setContent(
+        \`\\n  {\${DIM}-fg}Waiting for a dispatch.{/}\\n\\n\` +
+        \`  {\${DIM}-fg}When one arrives, the address it replaced{/}\\n\` +
+        \`  {\${DIM}-fg}and the address that replaced it appear here.{/}\`,
+      );
+      return;
+    }
+    const { customer, previous } = lastChange;
+    let now: Record<string, unknown> = {};
+    try { now = JSON.parse(customer.address) as Record<string, unknown>; } catch { /* keep empty */ }
+    changeBox.setContent(
+      \`\\n  {bold}\${esc(customer.name)}{/bold}\\n\` +
+      \`  {\${DIM}-fg}account{/} {\${AMBER}-fg}\${esc(customer.account_number)}{/}\\n\\n\` +
+      \`  {red-fg}was{/}  \${esc(oneLine(previous))}\\n\\n\` +
+      \`  {green-fg}now{/}  {\${CREAM}-fg}\${esc(oneLine(now))}{/}\\n\`,
+    );
+  }
+
+  function renderFooter(): void {
+    footer.setContent(
+      \`{\${DIM}-fg}received{/} {bold}\${received}{/bold}   \` +
+      \`{green-fg}applied{/} {bold}\${applied}{/bold}   \` +
+      \`{red-fg}failed{/} {bold}\${failed}{/bold}\` +
+      \`{|}{\${DIM}-fg}[q] quit{/}  \`,
+    );
+  }
+
+  function redraw(): void {
+    renderStatus();
+    renderChange();
+    renderFooter();
+    screen.render();
+  }
+
+  // \u2500\u2500 The feed \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // Counters are derived from the reported lines rather than from a second
+  // channel the server would have to remember to update. One source, so the
+  // footer cannot disagree with the log beside it.
+  const detach = report.attach((line: ReportLine) => {
+    const text = formatLine(line);
+    const colour = line.level === 'error' ? 'red' : line.level === 'warn' ? 'yellow' : CREAM;
+    const time = new Date(line.at).toTimeString().slice(0, 8);
+
+    if (/address\\.updated for /.test(text)) received++;
+    if (/REFUSED|decryption failed|Decryption failed/.test(text)) failed++;
+    if (/\\[store\\] saved address for /.test(text)) {
+      applied++;
+      // The store logs the account key and never the address, so the panel is
+      // refreshed from the DATABASE rather than parsed out of the log line.
+      const acct = /saved address for (\\S+)/.exec(text)?.[1];
+      const customer = allCustomers().find((c) => c.account_number === acct);
+      if (customer) lastChange = { customer, previous: pendingPrevious };
+    }
+
+    logBox.log(\`{\${DIM}-fg}\${time}{/} {\${colour}-fg}\${esc(text)}{/}\`);
+    redraw();
+  });
+
+  screen.key(['q', 'C-c'], () => {
+    detach();
+    screen.destroy();
+    onQuit();
+    process.exit(0);
+  });
+
+  redraw();
+}
+
+/**
+ * Handed the address a dispatch replaced, so the dashboard can show both halves.
+ *
+ * A no-op until the dashboard starts, which is what lets the protocol layer
+ * call it unconditionally without knowing whether a UI exists. That is the same
+ * reason \`report\` has a default sink: \`--headless\` must not need a second code
+ * path through the handler.
+ */
+let setPrevious: (prev: Record<string, unknown>) => void = () => {};
+
+export function notePreviousAddress(prev: Record<string, unknown>): void {
+  setPrevious(prev);
+}
+`
+    },
+    {
+      name: "src/index.ts",
+      content: `#!/usr/bin/env node
+/**
+ * Your OneAddress receiver.
+ *
+ *   npm start              the terminal dashboard
+ *   npm start -- --headless    log to stdout, for a service unit
+ *
+ * ## Why this file exists rather than starting the server directly
+ *
+ * Two things have to happen in a strict order, and both are easy to get wrong:
+ *
+ *  1. The at-rest passphrase must be known BEFORE anything opens the database.
+ *     \`src/db.ts\` derives its keys when it is first imported, so this prompts
+ *     and sets the environment variable, then imports the rest DYNAMICALLY.
+ *     A plain top-level import would open the database before the prompt ran.
+ *
+ *  2. The dashboard must own the terminal BEFORE the server narrates anything,
+ *     or the first log line lands on top of the drawn screen.
+ *
+ * \`--headless\` skips both: no prompt (a service has nobody to ask), no screen.
+ */
+import { printBanner } from './brand.js';
+import { WrongPassphraseError } from './vault.js';
+
+const headless =
+  process.argv.includes('--headless') ||
+  process.env.ONEADDRESS_HEADLESS === '1';
+
+/**
+ * Where the at-rest passphrase comes from.
+ *
+ * \`ONEADDRESS_DB_PASSPHRASE\` first, so a service unit or a repeat run never
+ * stops to ask. Otherwise prompt, but ONLY when a human is actually there: a
+ * headless deployment or a piped stdin has nobody to answer, and blocking on a
+ * prompt nobody can see is the worst of the three outcomes.
+ *
+ * An empty answer is legitimate, not a failure. It runs the database in the
+ * clear, which is what this receiver did before at-rest encryption existed, and
+ * the dashboard shows that state in red rather than letting it pass unnoticed.
+ */
+async function resolvePassphrase(): Promise<string | null> {
+  const fromEnv = process.env.ONEADDRESS_DB_PASSPHRASE;
+  if (fromEnv && fromEnv.trim()) return fromEnv;
+  if (headless || !process.stdin.isTTY) return null;
+
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    process.stdout.write('  Your customer records can be encrypted at rest.\\n');
+    process.stdout.write('  This passphrase is YOURS. It is not the OneAddress private key,\\n');
+    process.stdout.write('  and OneAddress never sees it and cannot recover it.\\n');
+    process.stdout.write('  Leave blank to store records unencrypted.\\n\\n');
+    const answer = (await rl.question('  Passphrase: ')).trim();
+    return answer || null;
+  } finally {
+    rl.close();
+  }
+}
+
+async function main(): Promise<void> {
+  printBanner(headless ? 'Partner receiver \u2014 headless' : 'Partner receiver');
+
+  const passphrase = await resolvePassphrase();
+  if (passphrase) process.env.ONEADDRESS_DB_PASSPHRASE = passphrase;
+
+  // Dynamic, and this is the whole point of the file: importing the server
+  // pulls in the store, which pulls in the database, which derives its keys on
+  // import. The passphrase has to be set before that chain starts.
+  let config: { partnerName: string; port: number };
+  try {
+    const server = await import('./server.js');
+    config = { partnerName: server.PARTNER_NAME, port: server.PORT };
+  } catch (err) {
+    if (err instanceof WrongPassphraseError) {
+      // Named for what it is. Without this the first symptom is a decryption
+      // error on a live dispatch, which reads as a corrupt database and sends
+      // people to delete a file that is perfectly intact.
+      console.error('\\n  That passphrase does not open this database.');
+      console.error('  Try again, or delete data.db to start fresh.\\n');
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  if (headless) return; // The server is listening and reporting to stdout.
+
+  const { startDashboard } = await import('./tui.js');
+  startDashboard({
+    partnerName: config.partnerName,
+    port: config.port,
+    onQuit: () => { /* the process exits; the OS closes the socket */ },
+  });
+}
+
+main().catch((err) => {
+  console.error('[startup]', err instanceof Error ? err.message : err);
+  process.exit(1);
+});
 `
     },
     {
@@ -1190,7 +2005,7 @@ export function safeOneAddressCallbackUrl(raw: string): string | null {
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import db from './db.js';
+import db, { accountKey, dec, enc, encrypted, once } from './db.js';
 
 export type Address = Record<string, unknown>;
 
@@ -1200,7 +2015,14 @@ export type Address = Record<string, unknown>;
 // change you apply, so you have an audit trail.
 db.exec(\`
   CREATE TABLE IF NOT EXISTS customers (
-    account_number TEXT PRIMARY KEY,
+    -- How a row is FOUND. A blind index of the account number when the database
+    -- is locked, the lower-cased number when it is not. It is the key rather
+    -- than the number itself because AES-GCM uses a fresh IV per write, so two
+    -- encryptions of one account number differ and a primary key over the
+    -- ciphertext would enforce nothing while looking like it did.
+    account_key    TEXT PRIMARY KEY,
+    -- What is DISPLAYED. Ciphertext when locked.
+    account_number TEXT NOT NULL,
     name           TEXT NOT NULL,
     address        TEXT NOT NULL DEFAULT '{}',
     updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
@@ -1208,10 +2030,14 @@ db.exec(\`
 
   CREATE TABLE IF NOT EXISTS address_history (
     id             INTEGER PRIMARY KEY AUTOINCREMENT,
-    account_number TEXT NOT NULL,
+    account_key    TEXT NOT NULL,
+    -- Both sides of the change, so you can show what an address REPLACED
+    -- rather than only what it became.
+    prev_address   TEXT NOT NULL DEFAULT '{}',
     address        TEXT NOT NULL,
     recorded_at    TEXT NOT NULL DEFAULT (datetime('now'))
   );
+  CREATE INDEX IF NOT EXISTS idx_history_account ON address_history(account_key, id DESC);
 \`);
 
 // Self-migrate. An older data.db may already hold a \`customers\` table WITHOUT the
@@ -1228,6 +2054,36 @@ function ensureColumn(table: string, column: string, definition: string): void {
 }
 ensureColumn('customers', 'address', "TEXT NOT NULL DEFAULT '{}'");
 ensureColumn('customers', 'updated_at', 'TEXT'); // nullable on migrate; set on write
+ensureColumn('customers', 'account_key', 'TEXT');
+ensureColumn('address_history', 'account_key', 'TEXT');
+ensureColumn('address_history', 'prev_address', "TEXT NOT NULL DEFAULT '{}'");
+
+// A database written before at-rest encryption existed holds plaintext rows and
+// no account_key. Backfill the key and encrypt in place.
+//
+// Safe to run on every start: \`once\` encrypts only what is not already
+// encrypted, and \`accountKey\` is derived from the DECRYPTED number, so a second
+// pass produces the same key rather than hashing a ciphertext and orphaning the
+// row. A row orphaned that way still reads fine in a listing and is invisible
+// to every dispatch, which is the worst kind of broken.
+{
+  const rows = db.prepare('SELECT rowid AS rid, account_number, name, address FROM customers').all() as Array<
+    { rid: number; account_number: string; name: string; address: string }
+  >;
+  const relabel = db.prepare(
+    'UPDATE customers SET account_key = ?, account_number = ?, name = ?, address = ? WHERE rowid = ?',
+  );
+  for (const r of rows) {
+    const plainAccount = dec('account_number', r.account_number) ?? r.account_number;
+    relabel.run(
+      accountKey(plainAccount),
+      once('account_number', r.account_number),
+      once('name', r.name),
+      once('address', r.address),
+      r.rid,
+    );
+  }
+}
 
 /* \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
  *  YOUR CUSTOMER ROSTER \u2014 data, not code (customers.json)
@@ -1286,11 +2142,17 @@ function loadRoster(): RosterEntry[] {
 const ROSTER = loadRoster();
 {
   const upsert = db.prepare(\`
-    INSERT INTO customers (account_number, name, address) VALUES ($account_number, $name, $address)
-    ON CONFLICT(account_number) DO UPDATE SET name = excluded.name
+    INSERT INTO customers (account_key, account_number, name, address)
+    VALUES ($account_key, $account_number, $name, $address)
+    ON CONFLICT(account_key) DO UPDATE SET name = excluded.name
   \`);
   for (const c of ROSTER) {
-    upsert.run({ account_number: c.account_number, name: c.name, address: JSON.stringify(c.address) });
+    upsert.run({
+      account_key:    accountKey(c.account_number),
+      account_number: enc('account_number', c.account_number),
+      name:           enc('name', c.name),
+      address:        enc('address', JSON.stringify(c.address)),
+    });
   }
   console.log(\`[store] roster ready (\${ROSTER.length} customers)\`);
 }
@@ -1327,18 +2189,57 @@ function canonicalAddress(a: Address): string {
 function findCustomer(accountNumber: string | undefined, name: string): { account_number: string; name: string; address: string } | undefined {
   const acct = (accountNumber ?? '').trim();
   if (acct) {
-    const byAcct = db.prepare('SELECT account_number, name, address FROM customers WHERE account_number = ?').get(acct);
+    const byAcct = decodeRow(
+      db.prepare('SELECT account_number, name, address FROM customers WHERE account_key = ?').get(accountKey(acct)),
+    );
     if (byAcct) return byAcct as { account_number: string; name: string; address: string };
   }
   const n = name.trim().toLowerCase();
   if (n) {
-    const byName = db.prepare('SELECT account_number, name, address FROM customers WHERE LOWER(name) = ?').get(n);
+    // Scanned and decrypted rather than matched in SQL: LOWER(name) cannot see
+    // inside a ciphertext, so an equality here would match nothing and quietly
+    // return "no such customer" forever. A roster is small; decrypting it is
+    // microseconds.
+    const byName = allCustomers().find((c) => c.name.trim().toLowerCase() === n);
     if (byName) return byName as { account_number: string; name: string; address: string };
   }
   return undefined;
 }
 
 // \u2500\u2500 account.verify: pre-payment account check \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+/** One stored row, with the personal columns decrypted. */
+export interface StoredCustomer {
+  account_number: string;
+  name: string;
+  address: string;
+}
+
+/** Decrypt a row read straight out of SQLite. */
+function decodeRow(raw: unknown): StoredCustomer | undefined {
+  if (!raw) return undefined;
+  const r = raw as StoredCustomer;
+  return {
+    account_number: dec('account_number', r.account_number)!,
+    name: dec('name', r.name)!,
+    address: dec('address', r.address)!,
+  };
+}
+
+/** Every customer, decrypted. Used where SQL cannot see inside the ciphertext. */
+export function allCustomers(): StoredCustomer[] {
+  return (db.prepare('SELECT account_number, name, address FROM customers').all() as unknown[])
+    .map((r) => decodeRow(r)!)
+    .filter(Boolean);
+}
+
+/** How many customers are on file. */
+export function customerCount(): number {
+  return (db.prepare('SELECT COUNT(*) AS n FROM customers').get() as { n: number }).n;
+}
+
+/** Is the file on disk protected? Surfaced in the dashboard, in both states. */
+export const storeEncrypted = encrypted;
+
 export type AccountVerdict = 'match' | 'no_match' | 'no_account';
 
 /**
@@ -1352,7 +2253,10 @@ export type AccountVerdict = 'match' | 'no_match' | 'no_account';
 export function verifyAccount(accountNumber: string | null, name: string, knownNames: string[] = []): AccountVerdict {
   const acct = (accountNumber ?? '').trim();
   if (!acct) return 'no_account';
-  const row = db.prepare('SELECT name FROM customers WHERE account_number = ?').get(acct) as { name: string } | undefined;
+  const onFile = db.prepare('SELECT name FROM customers WHERE account_key = ?').get(accountKey(acct)) as
+    | { name: string }
+    | undefined;
+  const row = onFile ? { name: dec('name', onFile.name)! } : undefined;
   if (!row) return 'no_account';
   const stored     = row.name.trim().toLowerCase();
   const candidates = [name, ...knownNames].map(v => (v ?? '').trim().toLowerCase()).filter(Boolean);
@@ -1385,31 +2289,60 @@ export async function verifyAddress(customer: Customer, incoming: Address): Prom
 
 // \u2500\u2500 address.updated: apply the new address \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 /**
- * Applies a new address to the customer's record and logs the change. Keyed on
- * the account number (falling back to name); this is called only after the
- * consumer paid and IDV passed, and only for an account that matched.
+ * Applies a new address to the customer's record and logs the change.
+ *
+ * Keyed on the account number, falling back to name. The caller enforces the
+ * part that makes that safe: when you verify account references, server.ts
+ * refuses anything that is not a \`match\` before reaching here, so the fallback
+ * is unreachable in that mode and the key is always a real account of yours.
+ *
+ * IF YOU DO NOT VERIFY ACCOUNT REFERENCES the fallback is live and the row is
+ * keyed on the customer's name, which is your identification scheme rather than
+ * 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<void> {
+export async function saveAddress(customer: Customer, incoming: Address): Promise<Address> {
   const acct = (customer.accountNumber ?? '').trim() || customer.name.trim();
   const addressJson = JSON.stringify(incoming);
+  const key = accountKey(acct);
+
+  // Read what we are about to replace. After the UPDATE nothing can reconstruct
+  // it, and "what did this address replace" is the question an operator asks
+  // first when a change looks wrong.
+  const existing = decodeRow(
+    db.prepare('SELECT account_number, name, address FROM customers WHERE account_key = ?').get(key),
+  );
+  const previous: Address = existing ? (JSON.parse(existing.address) as Address) : {};
 
   db.prepare(\`
-    INSERT INTO customers (account_number, name, address, updated_at)
-    VALUES ($account_number, $name, $address, datetime('now'))
-    ON CONFLICT(account_number) DO UPDATE SET
+    INSERT INTO customers (account_key, account_number, name, address, updated_at)
+    VALUES ($account_key, $account_number, $name, $address, datetime('now'))
+    ON CONFLICT(account_key) DO UPDATE SET
       name       = excluded.name,
       address    = excluded.address,
       updated_at = excluded.updated_at
-  \`).run({ account_number: acct, name: customer.name, address: addressJson });
+  \`).run({
+    account_key: key,
+    account_number: enc('account_number', acct),
+    name: enc('name', customer.name),
+    address: enc('address', addressJson),
+  });
 
   db.prepare(\`
-    INSERT INTO address_history (account_number, address) VALUES ($account_number, $address)
-  \`).run({ account_number: acct, address: addressJson });
+    INSERT INTO address_history (account_key, prev_address, address)
+    VALUES ($account_key, $prev_address, $address)
+  \`).run({
+    account_key: key,
+    prev_address: enc('address', JSON.stringify(previous)),
+    address: enc('address', addressJson),
+  });
 
-  // Metadata only \u2014 the address itself is PII, so we log the key, never the
-  // address. Centralised log aggregation turns every log line into a
-  // data-exposure surface for customer addresses.
+  // Metadata only \u2014 the address itself is personal information, so the key is
+  // logged and the address never is. Centralised log aggregation turns every
+  // log line into a place customer addresses can be read.
   console.log(\`[store] saved address for \${acct}\${customer.loaRef ? \` (loa_ref \${customer.loaRef})\` : ''}\`);
+
+  return previous;
 }
 `
     },
@@ -1430,12 +2363,13 @@ export async function saveAddress(customer: Customer, incoming: Address): Promis
 // Fail fast with a clear message rather than a cryptic ERR_UNSUPPORTED_FEATURE later.
 const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
 if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 5)) {
-  console.error(\`[startup] Node.js 22.5+ is required (you are running \${process.version}).\`);
-  console.error('[startup] Upgrade Node.js: https://nodejs.org/en/download');
+  report.error(\`[startup] Node.js 22.5+ is required (you are running \${process.version}).\`);
+  report.error('[startup] Upgrade Node.js: https://nodejs.org/en/download');
   process.exit(1);
 }
 
 import 'dotenv/config';
+import { report } from './report.js';
 import express, { Request, Response } from 'express';
 import rateLimit from 'express-rate-limit';
 import { createPrivateKey, createHmac } from 'node:crypto';
@@ -1450,6 +2384,7 @@ import {
   type OneAddressD5LOA,
 } from '@oneaddress/partner-sdk';
 import { saveAddress, verifyAddress, verifyAccount } from './store.js';
+import { notePreviousAddress } from './tui.js';
 import { config } from './config.js';
 import { safeOneAddressCallbackUrl } from './callback-url.js';
 
@@ -1472,7 +2407,7 @@ const ONEADDRESS_API = config.oneAddressApi;
 const CONFIRM_SECRET = process.env.CONFIRM_SECRET || WEBHOOK_SECRET;
 
 if (!WEBHOOK_SECRET || !PARTNER_PRIVATE_KEY || !PARTNER_ID) {
-  console.error('[startup] Missing required env vars. Check your .env file.');
+  report.error('[startup] Missing required env vars. Check your .env file.');
   process.exit(1);
 }
 
@@ -1485,8 +2420,8 @@ if (!WEBHOOK_SECRET || !PARTNER_PRIVATE_KEY || !PARTNER_ID) {
 //      fails only when the first payload arrives.
 //   2. A private key that does not parse (empty, truncated, or header stripped).
 if (typeof decryptSession !== 'function') {
-  console.error('[startup] @oneaddress/partner-sdk does not export decryptSession. Your installed SDK is too old for D5 dispatches.');
-  console.error('[startup] Fix: npm install "@oneaddress/partner-sdk@^1.8.0", then restart.');
+  report.error('[startup] @oneaddress/partner-sdk does not export decryptSession. Your installed SDK is too old for D5 dispatches.');
+  report.error('[startup] Fix: npm install "@oneaddress/partner-sdk@^1.8.0", then restart.');
   process.exit(1);
 }
 // Only PEM keys are parseable this way; a post-quantum key is a base64 secret,
@@ -1495,8 +2430,8 @@ if (PARTNER_PRIVATE_KEY.includes('BEGIN')) {
   try {
     createPrivateKey(PARTNER_PRIVATE_KEY);
   } catch {
-    console.error('[startup] PARTNER_PRIVATE_KEY_PEM does not parse as a private key.');
-    console.error('[startup] Paste the FULL PEM, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.');
+    report.error('[startup] PARTNER_PRIVATE_KEY_PEM does not parse as a private key.');
+    report.error('[startup] Paste the FULL PEM, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.');
     process.exit(1);
   }
 }
@@ -1560,16 +2495,16 @@ async function confirmToOneAddress(dispatch: string, status: 'confirmed' | 'fail
       body: bodyStr,
     });
     if (confirmRes.ok) {
-      console.log(\`[confirm] dispatch \${dispatchId} \u2192 \${status}: acknowledged by OneAddress\`);
+      report.info(\`[confirm] dispatch \${dispatchId} \u2192 \${status}: acknowledged by OneAddress\`);
     } else {
       const detail = await confirmRes.text().catch(() => '');
-      console.error(\`[confirm] dispatch \${dispatchId} confirm FAILED \u2014 HTTP \${confirmRes.status} \${detail}\`);
+      report.error(\`[confirm] dispatch \${dispatchId} confirm FAILED \u2014 HTTP \${confirmRes.status} \${detail}\`);
       if (confirmRes.status === 401) {
-        console.error('[confirm] 401 means the wrong secret. If your partner has a separate confirm secret, set CONFIRM_SECRET in .env to it (from the portal Webhook screen); otherwise your webhook signing secret should work.');
+        report.error('[confirm] 401 means the wrong secret. If your partner has a separate confirm secret, set CONFIRM_SECRET in .env to it (from the portal Webhook screen); otherwise your webhook signing secret should work.');
       }
     }
   } catch (err) {
-    console.error('[confirm] confirm request error:', err);
+    report.error('[confirm] confirm request error:', err);
   }
 }
 
@@ -1653,7 +2588,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // checked" rather than a match/no_match you don't actually compute \u2014 this is
     // the setup declaration reaching the running handler.
     if (!config.verifiesAccountReference) {
-      console.log('[webhook] account.verify \u2192 skipped (verifiesAccountReference is false in oneaddress.config.json)');
+      report.info('[webhook] account.verify \u2192 skipped (verifiesAccountReference is false in oneaddress.config.json)');
       return res.status(200).json({ ok: true, skipped: true });
     }
 
@@ -1666,7 +2601,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
     try {
       cust = await decryptAddress(enc, PARTNER_PRIVATE_KEY, PARTNER_ID);
     } catch (err) {
-      console.error('[webhook] account.verify decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM:', err);
+      report.error('[webhook] account.verify decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM:', err);
       return res.status(422).json({ ok: false, error: 'decryption_failed' });
     }
 
@@ -1675,7 +2610,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
     const knownNames    = Array.isArray(cust.known_names) ? cust.known_names.map(String) : [];
 
     const status = verifyAccount(accountNumber, name, knownNames);
-    console.log(\`[webhook] account.verify \u2192 \${status} for account \${accountNumber ?? '(none)'} (\${name})\`);
+    report.info(\`[webhook] account.verify \u2192 \${status} for account \${accountNumber ?? '(none)'} (\${name})\`);
     return res.status(200).json({ status });
   }
 
@@ -1687,7 +2622,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
   // the 422 below, because it IS a dispatch event.
   const DISPATCH_EVENTS = ['address.updated', 'address.verify', 'address.test', 'address.test-dispatch'];
   if (!DISPATCH_EVENTS.includes(event)) {
-    console.log(\`[webhook] "\${event}" acknowledged (no address payload to decrypt)\`);
+    report.info(\`[webhook] "\${event}" acknowledged (no address payload to decrypt)\`);
     return res.status(200).json({ ok: true, skipped: true });
   }
 
@@ -1726,7 +2661,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
       decAccount    = typeof data.account_number === 'string' ? data.account_number : '';
       decKnownNames = Array.isArray(data.known_names) ? data.known_names : [];
     } catch (err) {
-      console.error('[webhook] D5 decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM matches key_id', sessionKeyShare.key_id, ':', err);
+      report.error('[webhook] D5 decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM matches key_id', sessionKeyShare.key_id, ':', err);
       return res.status(422).json({ ok: false, error: 'D5 decryption failed \u2014 partner key mismatch' });
     }
   } else if (legacyPayload) {
@@ -1736,7 +2671,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
       decAccount    = typeof address.accountReference === 'string' ? address.accountReference : '';
       decKnownNames = Array.isArray(address.knownNames) ? address.knownNames as string[] : [];
     } catch (err) {
-      console.error('[webhook] Decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM in .env:', err);
+      report.error('[webhook] Decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM in .env:', err);
       return res.status(422).json({ ok: false, error: 'Decryption failed \u2014 partner key mismatch' });
     }
   } else {
@@ -1758,7 +2693,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
       const loa: OneAddressD5LOA = await decryptLoaEncrypted(loaEncrypted, PARTNER_PRIVATE_KEY, PARTNER_ID);
       loaRef = d5LoaRef(loa);
     } catch (err) {
-      console.error('[webhook] LOA decryption failed:', err instanceof Error ? err.message : err);
+      report.error('[webhook] LOA decryption failed:', err instanceof Error ? err.message : err);
     }
   }
 
@@ -1776,8 +2711,48 @@ app.post('/webhook', async (req: Request, res: Response) => {
 
   // \u2500\u2500 address.updated: consumer changed their address \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   if (event === 'address.updated') {
-    console.log(\`[webhook] address.updated for \${ctx.accountNumber || ctx.name}\`);
-    await saveAddress(ctx, address);
+    report.info(\`[webhook] address.updated for \${ctx.accountNumber || ctx.name}\`);
+
+    // AN ACCOUNT REFERENCE THAT MATCHES NOTHING MUST BE A HARD NO-MATCH.
+    //
+    // This runs BEFORE saveAddress, and it is the whole reason saveAddress can
+    // be trusted. Until 13 Sep 2026 this handler applied every dispatch it
+    // could decrypt, with no check that the account was one of yours: an
+    // account number matching nobody created a BRAND NEW customer row, and a
+    // dispatch with no account number at all was keyed on the customer's NAME,
+    // so two customers who share a name collapse onto one record and the
+    // second one's address overwrites the first's.
+    //
+    // Do not "simplify" this by falling back to a name match when the account
+    // number misses. A name matching a DIFFERENT customer's record is not
+    // evidence the two are the same person; it is the most likely way to write
+    // one customer's address onto another customer's account.
+    //
+    // Gated on your own portal declaration, exactly like account.verify above:
+    // if you told the portal you do not verify account references, you identify
+    // customers some other way and this check cannot speak for you.
+    //
+    // Refusing is reported two ways, and both matter. The \`ok: false\` tells
+    // OneAddress this delivery failed (a 200 carrying ok:true would be read as
+    // success and the consumer would be told their address had landed); the
+    // \`failed\` confirm callback puts the same answer on the record they see.
+    // OneAddress conformance check "Refuses an account reference that matches
+    // no record" tests exactly this.
+    if (config.verifiesAccountReference) {
+      const verdict = verifyAccount(ctx.accountNumber, ctx.name ?? '', ctx.knownNames ?? []);
+      if (verdict !== 'match') {
+        report.warn(\`[webhook] address.updated REFUSED (\${verdict}) for account \${ctx.accountNumber ?? '(none)'} \u2014 nothing applied\`);
+        void confirmToOneAddress(dispatch, 'failed');
+        return res.status(200).json({ ok: false, error: 'account_not_matched', verdict });
+      }
+    }
+
+    // \`saveAddress\` returns the address it replaced. Handed to the dashboard so
+    // it can show both halves; a no-op under --headless. Passed directly rather
+    // than reported, because the previous address is a customer's address and
+    // must never reach a log line.
+    const replaced = await saveAddress(ctx, address);
+    notePreviousAddress(replaced);
     if (dispatch) rememberDispatch(dispatch); // remember only after it is stored
     // Close the loop back to OneAddress so the service flips to "Confirmed".
     // Fire-and-forget: it must not delay this 200 (which acks the delivery).
@@ -1799,13 +2774,13 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // network position into an SSRF primitive.
     const safeCallbackUrl = safeOneAddressCallbackUrl(callbackUrl);
     if (!safeCallbackUrl) {
-      console.warn(\`[webhook] refusing callback to non-OneAddress host: \${callbackUrl}\`);
+      report.warn(\`[webhook] refusing callback to non-OneAddress host: \${callbackUrl}\`);
       return res.status(400).json({ error: 'Invalid callback_url host' });
     }
 
-    console.log(\`[webhook] address.verify for \${ctx.accountNumber || ctx.name}\`);
+    report.info(\`[webhook] address.verify for \${ctx.accountNumber || ctx.name}\`);
     const result = await verifyAddress(ctx, address);
-    console.log(\`[webhook] address.verify \u2192 \${result}\`);
+    report.info(\`[webhook] address.verify \u2192 \${result}\`);
 
     await fetch(safeCallbackUrl, {
       method:  'POST',
@@ -1841,21 +2816,26 @@ app.post('/webhook', async (req: Request, res: Response) => {
     const a = address as { street?: unknown; suburb?: unknown; state?: unknown; postcode?: unknown };
     const oneLine = [a.street, [a.suburb, a.state, a.postcode].filter(Boolean).join(' ')]
       .filter(Boolean).join(', ');
-    console.log(\`[webhook] \${event} verification probe decrypted OK\`);
-    console.log(\`[verification] \${index ?? '?'} | \${ctx.name} | \${oneLine}\`);
+    report.info(\`[webhook] \${event} verification probe decrypted OK\`);
+    report.info(\`[verification] \${index ?? '?'} | \${ctx.name} | \${oneLine}\`);
     return res.status(200).json({ verification: true, index });
   }
 
   // Unknown event \u2014 acknowledge (forward compatibility)
-  console.log(\`[webhook] Unknown event "\${event}" \u2014 acknowledged\`);
+  report.info(\`[webhook] Unknown event "\${event}" \u2014 acknowledged\`);
   return res.status(200).json({ ok: true, skipped: true });
 });
 
 app.get('/health', (_req, res) => res.json({ status: 'ok' }));
 
 app.listen(PORT, () =>
-  console.log(\`[server] OneAddress webhook server \u2192 http://localhost:\${PORT}/webhook\`),
+  report.info(\`[server] OneAddress webhook server \u2192 http://localhost:\${PORT}/webhook\`),
 );
+
+// Read by src/index.ts to label the dashboard. Exported rather than re-derived
+// there, so the port the UI claims is the port the server actually bound.
+export { PORT };
+export const PARTNER_NAME = process.env.PARTNER_NAME?.trim() || 'Your receiver';
 `
     },
     {
@@ -2259,8 +3239,15 @@ def _verify_account(account_number: str, name: str, known_names: list[str]) -> s
     return "match" if stored in candidates else "no_match"
 
 def _save_address(account_number: str, name: str, address: dict[str, Any], dispatch_id: str) -> None:
-    """Persist on address.updated. Upserts the customer's on-file address (keyed
-    on the decrypted account number, falling back to name) + appends history."""
+    """Persist on address.updated. Upserts the customer's on-file address + appends
+    history.
+
+    Keyed on the decrypted account number, falling back to name. The caller
+    enforces what makes that safe: when you verify account references, the
+    handler refuses anything that is not a 'match' before reaching here, so the
+    fallback is unreachable in that mode. If you do NOT verify account
+    references the fallback is live and the row is keyed on the customer's name
+    - be aware two customers sharing a name share a row."""
     acct = (account_number or "").strip() or (name or "").strip()
     address_json = json.dumps(address, sort_keys=True)
     _db.execute("""
@@ -2579,6 +3566,39 @@ async def webhook(request: Request) -> Response:
         # production and writing PII there turns every log reader into a
         # data-exposure surface.
         print(f"[webhook] address.updated for {account_number or verified_name or '?'} (dispatch={dispatch})")
+
+        # AN ACCOUNT REFERENCE THAT MATCHES NOTHING MUST BE A HARD NO-MATCH.
+        #
+        # Runs BEFORE _save_address, and it is what makes _save_address safe.
+        # Until 13 Sep 2026 this handler applied every dispatch it could
+        # decrypt with no check that the account was one of yours: an account
+        # number matching nobody created a BRAND NEW customer row, and a
+        # dispatch with no account number was keyed on the customer's NAME, so
+        # two customers sharing a name collapse onto one record.
+        #
+        # Do NOT fall back to a name match when the account number misses. A
+        # name matching a DIFFERENT customer's record is not evidence they are
+        # the same person; it is the likeliest way to write one customer's
+        # address onto another's account.
+        #
+        # Gated on your portal declaration, exactly like account.verify below.
+        # Refusing is reported twice and both matter: ok:false tells OneAddress
+        # the delivery failed (a 200 with ok:true is read as success and the
+        # consumer is told their address landed), and the "failed" confirm puts
+        # the same answer on the record they see.
+        if VERIFIES_ACCOUNT_REFERENCE:
+            verdict = _verify_account(account_number, verified_name, known_names)
+            if verdict != "match":
+                print(f"[webhook] address.updated REFUSED ({verdict}) for account "
+                      f"{account_number or '(none)'} - nothing applied")
+                _t = asyncio.create_task(_confirm_to_oneaddress(dispatch, "failed"))
+                _background_tasks.add(_t)
+                _t.add_done_callback(_background_tasks.discard)
+                return Response(
+                    content='{"ok":false,"error":"account_not_matched","verdict":"' + verdict + '"}',
+                    media_type="application/json",
+                )
+
         _save_address(account_number, verified_name, address, dispatch)
         if dispatch:
             seen_dispatches.add(dispatch)  # remember only after it is stored
@@ -3300,8 +4320,15 @@ public class OneAddressWebhookController {
                 // Close the loop back to OneAddress so the service flips to
                 // "Confirmed". Fire-and-forget (async) so a slow confirm never
                 // delays this 200. Only when we actually applied the update.
-                if ("applied".equals(outcome)) confirmToOneAddress(dispatchId, "confirmed");
-                return ResponseEntity.ok("{\\"ok\\":true,\\"outcome\\":\\"" + outcome + "\\"}");
+                // \`ok\` MUST REFLECT THE OUTCOME. Hardcoding true here (which it
+                // did until 13 Sep 2026) reports a no-match as a successful
+                // delivery: the matching above is correct and refuses to write,
+                // the confirm is correctly withheld, and then the wire says the
+                // opposite. OneAddress reads THIS, so the consumer was told
+                // their address had landed on an account that does not exist.
+                boolean applied = "applied".equals(outcome);
+                confirmToOneAddress(dispatchId, applied ? "confirmed" : "failed");
+                return ResponseEntity.ok("{\\"ok\\":" + applied + ",\\"outcome\\":\\"" + outcome + "\\"}");
             } else if ("address.verify".equals(event)) {
                 handleAddressVerify(body, address, accountNumber, verifiedName, knownNames);
                 if (dispatchId != null && !dispatchId.isBlank()) store.markProcessed(dispatchId, "verify");
@@ -3644,6 +4671,16 @@ public class OneAddressStore {
     private Long findCustomerId(String accountNumber, String verifiedName, List<String> knownNames) {
         List<String> candidates = allNames(verifiedName, knownNames);
 
+        // AN ACCOUNT NUMBER THAT MATCHES NOTHING IS A HARD NO-MATCH, and this
+        // function is where someone will try to make that more forgiving. Do not.
+        // When an account number is supplied it decides the answer alone: if no row
+        // carries it, or the row it carries disagrees with the name, this returns
+        // nothing and does NOT fall through to the name lookup below. A name
+        // matching a DIFFERENT customer's record is not evidence the two are the
+        // same person; it is the likeliest way to write one customer's address onto
+        // another customer's account. The name lookup exists only for partners who
+        // do not use account references at all.
+
         if (accountNumber != null && !accountNumber.isBlank()) {
             List<Map<String, Object>> rows = jdbc.queryForList(
                 "SELECT id, full_name FROM customers WHERE account_number = ?", accountNumber.trim());
@@ -4112,6 +5149,16 @@ public sealed class OneAddressStore
         if (!string.IsNullOrWhiteSpace(verifiedName)) candidates.Add(verifiedName.Trim());
         candidates.AddRange(knownNames.Where(n => !string.IsNullOrWhiteSpace(n)).Select(n => n.Trim()));
 
+        // AN ACCOUNT NUMBER THAT MATCHES NOTHING IS A HARD NO-MATCH, and this
+        // function is where someone will try to make that more forgiving. Do not.
+        // When an account number is supplied it decides the answer alone: if no row
+        // carries it, or the row it carries disagrees with the name, this returns
+        // nothing and does NOT fall through to the name lookup below. A name
+        // matching a DIFFERENT customer's record is not evidence the two are the
+        // same person; it is the likeliest way to write one customer's address onto
+        // another customer's account. The name lookup exists only for partners who
+        // do not use account references at all.
+
         if (!string.IsNullOrWhiteSpace(accountNumber))
         {
             using var byAcct = conn.CreateCommand();
@@ -4385,9 +5432,14 @@ app.MapPost("/webhooks/oneaddress", async (HttpRequest request) =>
         // Close the loop back to OneAddress so the service flips to "Confirmed".
         // Fire-and-forget (discard the Task) so a slow confirm never delays this
         // 200. Only when we actually applied the update.
-        if (outcome == "applied")
-            _ = ConfirmToOneAddress(oneAddressApi, confirmSecret, partnerId, dispatchId, "confirmed", app.Logger);
-        return Results.Json(new { ok = true, outcome });
+        // \`ok\` MUST REFLECT THE OUTCOME. Hardcoding true (which it did until
+        // 13 Sep 2026) reports a no-match as a successful delivery: the match
+        // above correctly refuses to write and correctly withholds the confirm,
+        // then the wire says the opposite. OneAddress reads THIS.
+        var applied = outcome == "applied";
+        _ = ConfirmToOneAddress(oneAddressApi, confirmSecret, partnerId, dispatchId,
+                                applied ? "confirmed" : "failed", app.Logger);
+        return Results.Json(new { ok = applied, outcome });
     }
     else // address.verify
     {
@@ -5078,6 +6130,15 @@ func (s *Store) findCustomerID(accountNumber, verifiedName string, knownNames []
 		}
 	}
 
+	// AN ACCOUNT NUMBER THAT MATCHES NOTHING IS A HARD NO-MATCH, and this
+	// function is where someone will try to make that more forgiving. Do not.
+	// When an account number is supplied it decides the answer alone: if no row
+	// carries it, or the row it carries disagrees with the name, this returns
+	// nothing and does NOT fall through to the name lookup below. A name
+	// matching a DIFFERENT customer's record is not evidence the two are the
+	// same person; it is the likeliest way to write one customer's address onto
+	// another customer's account. The name lookup exists only for partners who
+	// do not use account references at all.
 	if strings.TrimSpace(accountNumber) != "" {
 		var id int64
 		var fullName string
@@ -5396,10 +6457,17 @@ func main() {
 			// Close the loop back to OneAddress so the service flips to "Confirmed".
 			// Fire-and-forget in a goroutine: a slow confirm must not delay this 200
 			// (which acks the delivery). Only when we actually applied the update.
-			if outcome == "applied" {
+			// \`ok\` MUST REFLECT THE OUTCOME. Hardcoding true (which it did until
+			// 13 Sep 2026) reports a no-match as a successful delivery: the match
+			// above correctly refuses to write and correctly withholds the confirm,
+			// then the wire says the opposite. OneAddress reads THIS.
+			applied := outcome == "applied"
+			if applied {
 				go confirmToOneAddress(oneAddressAPI, confirmSecret, partnerID, dispatch, "confirmed")
+			} else {
+				go confirmToOneAddress(oneAddressAPI, confirmSecret, partnerID, dispatch, "failed")
 			}
-			jsonResp(w, 200, map[string]any{"ok": true, "outcome": outcome})
+			jsonResp(w, 200, map[string]any{"ok": applied, "outcome": outcome})
 			return
 
 		case "address.verify":
@@ -6158,6 +7226,16 @@ class OneAddressStore
     {
         $candidates = array_filter(array_merge([$verifiedName], $knownNames), fn ($n) => is_string($n) && trim($n) !== '');
 
+        // AN ACCOUNT NUMBER THAT MATCHES NOTHING IS A HARD NO-MATCH, and this
+        // function is where someone will try to make that more forgiving. Do not.
+        // When an account number is supplied it decides the answer alone: if no row
+        // carries it, or the row it carries disagrees with the name, this returns
+        // nothing and does NOT fall through to the name lookup below. A name
+        // matching a DIFFERENT customer's record is not evidence the two are the
+        // same person; it is the likeliest way to write one customer's address onto
+        // another customer's account. The name lookup exists only for partners who
+        // do not use account references at all.
+
         if ($accountNumber !== null && trim($accountNumber) !== '') {
             $row = DB::table('customers')->where('account_number', trim($accountNumber))->first();
             if (!$row) {
@@ -6602,10 +7680,14 @@ Route::post('/webhook', function (Request $request): Response {
         ]);
         // Close the loop back to OneAddress so the service flips to "Confirmed",
         // but only when we actually applied the update. Never affects this 200.
-        if ($outcome === 'applied') {
-            oaConfirmToOneAddress($oneAddressApi, $confirmSecret, $partnerId, $dispatchId, 'confirmed');
-        }
-        return response()->json(['ok' => true, 'outcome' => $outcome]);
+        // \`ok\` MUST REFLECT THE OUTCOME. Hardcoding true (which it did until
+        // 13 Sep 2026) reports a no-match as a successful delivery: the match
+        // above correctly refuses to write and correctly withholds the confirm,
+        // then the wire says the opposite. OneAddress reads THIS.
+        $applied = $outcome === 'applied';
+        oaConfirmToOneAddress($oneAddressApi, $confirmSecret, $partnerId, $dispatchId,
+                              $applied ? 'confirmed' : 'failed');
+        return response()->json(['ok' => $applied, 'outcome' => $outcome]);
     } elseif ($eventType === 'address.verify') {
         $callbackUrl  = $body['callback_url']  ?? '';
         $callbackToken= $body['callback_token'] ?? '';
@@ -6796,7 +7878,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto = require("crypto");
-var PKG_VERSION = true ? "1.6.2" : "dev";
+var PKG_VERSION = true ? "2.0.0" : "dev";
 var REGISTER_URL = "https://partners.oneaddress.io/api/partner/installs";
 function hmacSha256(secret, message) {
   return (0, import_node_crypto.createHmac)("sha256", secret).update(message).digest("hex");