@oneaddress/setup 1.6.1 → 2.0.0

package/dist/index.js

@@ -160,7 +160,7 @@ var require_picocolors = __commonJS({
 });
 
 // src/index.ts
-var import_node_fs7 = require("fs");
+var import_node_fs5 = require("fs");
 
 // node_modules/@clack/prompts/dist/index.mjs
 var import_node_util = require("util");
@@ -830,9 +830,9 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
 // src/prompts.ts
 var import_node_crypto5 = require("crypto");
 var import_node_net = require("net");
-var import_node_fs5 = require("fs");
+var import_node_fs3 = require("fs");
 var import_node_os2 = require("os");
-var import_node_path5 = require("path");
+var import_node_path4 = require("path");
 
 // src/header.ts
 var R2 = "\x1B[0m";
@@ -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.1" : "?";
+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.6.3",
+    "@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 built-in \`node:sqlite\` module (Node 22.5+), so there is nothing to
+ * compile and nothing extra to install.
  *
- * Uses the Node.js built-in \`node:sqlite\` module (available in Node 22.5+).
- * No extra packages or native compilation required.
+ * 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.
  *
- * 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.
+ * ## Where the passphrase comes from
  *
- * The database file lives at DB_PATH (default: data.db in the project root).
- * Change the location with the DB_PATH environment variable.
+ * \`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');
 
-// WAL mode \u2014 better performance for concurrent reads
-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);
+}
 
-console.log(\`[db] SQLite database ready \u2192 \${DB_PATH}\`);
+/**
+ * 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;
+
+  const keys = deriveKeys(passphrase, saltForThisDatabase());
+
+  // 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,22 +2495,30 @@ 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);
   }
 }
 
 const app = express();
 app.disable('x-powered-by'); // don't fingerprint the framework
 
+// Trust the reverse proxy / tunnel in front of this server (Cloudflare Tunnel,
+// nginx, a load balancer). It sets X-Forwarded-For, and without this the rate
+// limiter below cannot read the real client IP: express-rate-limit throws
+// ERR_ERL_UNEXPECTED_X_FORWARDED_FOR on the first proxied request. '1' trusts a
+// single hop, which is the usual setup; raise it if you run more proxies in
+// front, or set specific proxy addresses for stricter handling.
+app.set('trust proxy', 1);
+
 // DoS backstop on the public webhook. The endpoint already rejects anything
 // without a valid HMAC (401), but a signature check still costs CPU, so a flood
 // of junk requests is worth bounding. The ceiling is deliberately GENEROUS \u2014
@@ -1590,9 +2533,13 @@ const webhookLimiter = rateLimit({
   legacyHeaders: false,
   message: { error: 'Too many requests' },
 });
+// The limiter is attached ONCE, here on the route's middleware chain (the form
+// CodeQL's missing-rate-limiting query recognises). Do NOT also pass it to
+// app.post below: two references to the same limiter instance count every
+// request twice and silently halve the ceiling.
 app.use('/webhook', webhookLimiter, express.text({ type: 'application/json', limit: '1mb' }));
 
-app.post('/webhook', webhookLimiter, async (req: Request, res: Response) => {
+app.post('/webhook', async (req: Request, res: Response) => {
   const rawBody   = req.body    as string;
   const signature = req.headers['x-oneaddress-signature'] as string ?? '';
   const timestamp = req.headers['x-oneaddress-timestamp'] as string ?? '';
@@ -1641,7 +2588,7 @@ app.post('/webhook', webhookLimiter, 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 });
     }
 
@@ -1654,7 +2601,7 @@ app.post('/webhook', webhookLimiter, 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' });
     }
 
@@ -1663,7 +2610,7 @@ app.post('/webhook', webhookLimiter, 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 });
   }
 
@@ -1675,7 +2622,7 @@ app.post('/webhook', webhookLimiter, 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 });
   }
 
@@ -1714,7 +2661,7 @@ app.post('/webhook', webhookLimiter, 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) {
@@ -1724,7 +2671,7 @@ app.post('/webhook', webhookLimiter, 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 {
@@ -1746,7 +2693,7 @@ app.post('/webhook', webhookLimiter, 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);
     }
   }
 
@@ -1764,8 +2711,48 @@ app.post('/webhook', webhookLimiter, 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).
@@ -1787,13 +2774,13 @@ app.post('/webhook', webhookLimiter, 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',
@@ -1829,21 +2816,26 @@ app.post('/webhook', webhookLimiter, 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';
 `
     },
     {
@@ -2051,6 +3043,20 @@ the \`ONEADDRESS_CUSTOMERS\` env var, or point \`loadRoster\` at your real datab
       content: `OA_PARTNER_ID=%%PARTNER_ID%%
 OA_WEBHOOK_SECRET=%%WEBHOOK_SECRET%%
 OA_PRIVATE_KEY_PEM="%%PRIVATE_KEY%%"
+
+# Where the confirm callback is POSTed after you apply an address update. This is
+# the CUSTOMER app (oneaddress.io), NOT the partner portal \u2014 /api/confirm lives
+# on the former. Written by the setup wizard.
+ONEADDRESS_API=%%ONEADDRESS_API%%
+
+# Secret that signs the /api/confirm callback. Leave BLANK to reuse
+# OA_WEBHOOK_SECRET (correct for most partners); set it only if your partner has
+# a separate confirm secret in the portal Webhook screen.
+CONFIRM_SECRET=
+
+# Whether this receiver answers the pre-payment account.verify check. The wizard
+# writes your portal declaration here; set "true"/"false" to override.
+VERIFIES_ACCOUNT_REFERENCE=%%VERIFIES_ACCOUNT_REFERENCE%%
 `
     },
     {
@@ -2079,6 +3085,7 @@ Quick start:
   uvicorn app:app --port 3001
 """
 
+import asyncio
 import base64
 import hashlib
 import hmac as hmac_lib
@@ -2111,77 +3118,164 @@ WEBHOOK_SECRET = os.environ["OA_WEBHOOK_SECRET"]
 PRIVATE_KEY    = os.environ["OA_PRIVATE_KEY_PEM"].replace("\\\\n", "\\n")
 DB_PATH        = os.environ.get("DB_PATH", str(Path.cwd() / "data.db"))
 
+# Confirm-callback config. ONEADDRESS_API is the CUSTOMER app (/api/confirm lives
+# there, NOT the partner portal); CONFIRM_SECRET signs the callback and falls
+# back to the webhook secret, which is correct for most partners.
+ONEADDRESS_API = (os.environ.get("ONEADDRESS_API") or "https://oneaddress.io").rstrip("/")
+CONFIRM_SECRET = os.environ.get("CONFIRM_SECRET") or WEBHOOK_SECRET
+
+# Whether this receiver answers the pre-payment account.verify check. The setup
+# wizard bakes your portal declaration into the default below (the %% token
+# renders to the string "true"/"false"); the env var overrides it at runtime.
+_DEFAULT_VERIFIES_ACCOUNT_REFERENCE = ("%%VERIFIES_ACCOUNT_REFERENCE%%" == "true")
+VERIFIES_ACCOUNT_REFERENCE = (
+    os.environ["VERIFIES_ACCOUNT_REFERENCE"].strip().lower() == "true"
+    if os.environ.get("VERIFIES_ACCOUNT_REFERENCE")
+    else _DEFAULT_VERIFIES_ACCOUNT_REFERENCE
+)
+
 app = FastAPI()
 seen_dispatches: set[str] = set()
+# Keeps a reference to fire-and-forget confirm tasks so they aren't garbage-
+# collected before they run (asyncio only holds a weak reference to a task).
+_background_tasks: set[asyncio.Task[Any]] = set()
 
 # \u2500\u2500 SQLite store \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
 #
-# Uses Python's stdlib sqlite3 \u2014 no extra package install needed. Two tables
-# mirror the TypeScript scaffold layout exactly so partners with mixed-stack
-# integrations can run the same query against either DB:
+# ROSTER-BASED, mirroring the Go / Java / TypeScript scaffolds. The handler calls
+# _verify_account (pre-payment account check), _verify_address (is your on-file
+# address current?) and _save_address (apply an update) with the identity it
+# DECRYPTED from the payload \u2014 under D5 there is NO cleartext customer block on
+# the wire, so we key on the decrypted account number / verified name, never a
+# cleartext email.
+#
+# Two tables:
 #
-#   addresses        \u2014 one row per customer (UNIQUE on email); latest address only
+#   customers        \u2014 your roster: account number, name, and the address you
+#                      hold on file today. Replace with YOUR customer table.
 #   address_history  \u2014 append-only audit trail of every address.updated event
 #
-# Replace these with your real database (Postgres, MySQL, internal API)
-# when ready to ship. The webhook handler below only calls _save_address()
-# and _verify_address() \u2014 point those at your DB and the rest stays the same.
+# Replace these with your real database (Postgres, MySQL, internal API) when
+# ready to ship. Uses Python's stdlib sqlite3 \u2014 no extra package to install.
 
 _db = sqlite3.connect(DB_PATH, check_same_thread=False, isolation_level=None)
 _db.execute("PRAGMA journal_mode = WAL")
 _db.execute("""
-    CREATE TABLE IF NOT EXISTS addresses (
-        email       TEXT PRIMARY KEY,
-        name        TEXT NOT NULL DEFAULT '',
-        address     TEXT NOT NULL DEFAULT '{}',
-        dispatch_id TEXT,
-        updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    CREATE TABLE IF NOT EXISTS customers (
+        account_number TEXT PRIMARY KEY,
+        name           TEXT NOT NULL DEFAULT '',
+        address        TEXT NOT NULL DEFAULT '{}',
+        updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
     )
 """)
 _db.execute("""
     CREATE TABLE IF NOT EXISTS address_history (
-        id          INTEGER PRIMARY KEY AUTOINCREMENT,
-        email       TEXT NOT NULL,
-        name        TEXT NOT NULL DEFAULT '',
-        address     TEXT NOT NULL DEFAULT '{}',
-        dispatch_id TEXT,
-        recorded_at TEXT NOT NULL DEFAULT (datetime('now'))
+        id             INTEGER PRIMARY KEY AUTOINCREMENT,
+        account_number TEXT NOT NULL,
+        address        TEXT NOT NULL DEFAULT '{}',
+        dispatch_id    TEXT,
+        recorded_at    TEXT NOT NULL DEFAULT (datetime('now'))
     )
 """)
 print(f"[db] SQLite database ready -> {DB_PATH}")
 
-def _save_address(email: str, name: str, address: dict[str, Any], dispatch_id: str) -> None:
-    """Persist on address.updated. Upserts addresses + appends history."""
+# Seed a demo roster the first time, so a first update from OneAddress shows as a
+# real change (mismatch -> update -> match) rather than magically already
+# matching. Edit this to your customers, or point _find_customer at your real DB.
+_DEFAULT_ROSTER = [
+    {"account_number": "DEMO-0001", "name": "Test Customer",
+     "address": {"street": "1 Example Street", "suburb": "Sydney", "state": "NSW", "postcode": "2000"}},
+]
+if _db.execute("SELECT COUNT(*) FROM customers").fetchone()[0] == 0:
+    for _c in _DEFAULT_ROSTER:
+        _db.execute(
+            "INSERT INTO customers (account_number, name, address) VALUES (?, ?, ?)",
+            (_c["account_number"], _c["name"], json.dumps(_c["address"], sort_keys=True)))
+    print(f"[store] seeded {len(_DEFAULT_ROSTER)} demo customer(s)")
+
+def _canonical_address(a: dict[str, Any]) -> str:
+    """Order- and case-insensitive canonical form, so two addresses compare equal
+    iff they mean the same thing regardless of key order or casing."""
+    items = sorted(
+        (str(k).lower(), " ".join(str(v).strip().lower().split()))
+        for k, v in a.items()
+        if isinstance(v, str) and v.strip() != ""
+    )
+    return json.dumps(items)
+
+def _find_customer(account_number: str, name: str):
+    """Match on account number first (authoritative), then name. Returns the row
+    (account_number, name, address) or None."""
+    acct = (account_number or "").strip()
+    if acct:
+        row = _db.execute(
+            "SELECT account_number, name, address FROM customers WHERE account_number = ?", (acct,)
+        ).fetchone()
+        if row:
+            return row
+    n = (name or "").strip().lower()
+    if n:
+        row = _db.execute(
+            "SELECT account_number, name, address FROM customers WHERE LOWER(name) = ?", (n,)
+        ).fetchone()
+        if row:
+            return row
+    return None
+
+def _verify_account(account_number: str, name: str, known_names: list[str]) -> str:
+    """Pre-payment account check behind account.verify.
+      'match'      account number found and the name (or a known name) agrees
+      'no_match'   account number found but the name does not agree
+      'no_account' no such account number
+    """
+    acct = (account_number or "").strip()
+    if not acct:
+        return "no_account"
+    row = _db.execute("SELECT name FROM customers WHERE account_number = ?", (acct,)).fetchone()
+    if not row:
+        return "no_account"
+    stored = (row[0] or "").strip().lower()
+    candidates = [c for c in ((v or "").strip().lower() for v in [name, *known_names]) if c]
+    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 + 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("""
-        INSERT INTO addresses (email, name, address, dispatch_id, updated_at)
-        VALUES (?, ?, ?, ?, datetime('now'))
-        ON CONFLICT(email) DO UPDATE SET
-            name        = excluded.name,
-            address     = excluded.address,
-            dispatch_id = excluded.dispatch_id,
-            updated_at  = excluded.updated_at
-    """, (email, name, address_json, dispatch_id))
+        INSERT INTO customers (account_number, name, address, updated_at)
+        VALUES (?, ?, ?, datetime('now'))
+        ON CONFLICT(account_number) DO UPDATE SET
+            name       = excluded.name,
+            address    = excluded.address,
+            updated_at = excluded.updated_at
+    """, (acct, name, address_json))
     _db.execute("""
-        INSERT INTO address_history (email, name, address, dispatch_id, recorded_at)
-        VALUES (?, ?, ?, ?, datetime('now'))
-    """, (email, name, address_json, dispatch_id))
-
-def _verify_address(email: str, address: dict[str, Any]) -> str:
-    """Returns 'match' | 'mismatch' | 'not_found' for an address.verify event."""
-    row = _db.execute("SELECT address FROM addresses WHERE email = ?", (email,)).fetchone()
+        INSERT INTO address_history (account_number, address, dispatch_id, recorded_at)
+        VALUES (?, ?, ?, datetime('now'))
+    """, (acct, address_json, dispatch_id))
+
+def _verify_address(account_number: str, name: str, address: dict[str, Any]) -> str:
+    """Returns 'match' | 'mismatch' | 'not_found' for an address.verify event.
+    Compares the WHOLE address canonically against the on-file record. A customer
+    on your roster you have never updated returns 'mismatch' \u2014 you know them, you
+    just don't hold THIS address yet."""
+    row = _find_customer(account_number, name)
     if not row:
         return "not_found"
     try:
-        stored = json.loads(row[0])
+        stored = json.loads(row[2])
     except (json.JSONDecodeError, TypeError):
-        return "not_found"
-    # Compare all address fields the partner cares about. Address.verify
-    # ignores fields the consumer didn't supply (e.g. country missing on the
-    # incoming check is treated as "any country acceptable") \u2014 partners that
-    # need stricter matching should adjust this comparison.
-    matches = all(stored.get(k) == v for k, v in address.items())
-    return "match" if matches else "mismatch"
+        stored = {}
+    return "match" if _canonical_address(stored) == _canonical_address(address) else "mismatch"
 
 # \u2500\u2500 Crypto helpers \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
 
@@ -2303,6 +3397,61 @@ def _decrypt_session(share: dict[str, Any], envelope_b64: str,
     plaintext = AESGCM(sk).decrypt(session_iv, session_ct, None)
     return json.loads(plaintext)  # type: ignore[return-value]
 
+# \u2500\u2500 Confirm callback \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
+
+async def _confirm_to_oneaddress(dispatch: str, status: str) -> None:
+    """Close the loop after an address.updated apply, so the consumer's dashboard
+    flips the service to 'Confirmed'. Scheduled as a background task
+    (fire-and-forget) so a slow confirm never delays the webhook's own 200 \u2014 a
+    slow confirm must not make OneAddress time the DISPATCH out and mark it failed.
+
+    Only real dispatches carry a POSITIVE-INTEGER id in X-OneAddress-Dispatch;
+    probes (the go-live 'address.test') carry a non-numeric id and have nothing to
+    confirm, so they are skipped.
+
+    Auth for /api/confirm (all three required):
+      Authorization: Bearer <secret>
+      X-OneAddress-Timestamp: <unix seconds>
+      X-OneAddress-Signature: HMAC-SHA256(secret, "<timestamp>.<rawBody>")
+    The same secret signs the Bearer and the body, over the EXACT bytes POSTed.
+    """
+    d = (dispatch or "").strip()
+    if not d.isdigit() or int(d) <= 0:
+        return
+    dispatch_id = int(d)
+    body_str = json.dumps({
+        "dispatch_id": dispatch_id,
+        "partner_id":  PARTNER_ID,
+        "status":      status,
+        "note":        "Applied by the OneAddress webhook receiver",
+    })
+    ts  = str(int(time.time()))
+    sig = hmac_lib.new(CONFIRM_SECRET.encode(), f"{ts}.{body_str}".encode(), hashlib.sha256).hexdigest()
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            # content= sends these exact bytes \u2014 the ones we signed. Do NOT use
+            # json=, which would re-serialise and break the signature.
+            resp = await client.post(
+                f"{ONEADDRESS_API}/api/confirm",
+                content=body_str,
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {CONFIRM_SECRET}",
+                    "X-OneAddress-Timestamp": ts,
+                    "X-OneAddress-Signature": sig,
+                },
+            )
+        if resp.status_code // 100 == 2:
+            print(f"[confirm] dispatch {dispatch_id} -> {status}: acknowledged by OneAddress")
+        else:
+            print(f"[confirm] dispatch {dispatch_id} confirm FAILED \u2014 HTTP {resp.status_code}")
+            if resp.status_code == 401:
+                print("[confirm] 401 means the wrong secret. If your partner has a separate "
+                      "confirm secret, set CONFIRM_SECRET to it (from the portal Webhook screen); "
+                      "otherwise your webhook signing secret should work.")
+    except Exception as e:
+        print(f"[confirm] confirm request error: {e}")
+
 # \u2500\u2500 Webhook handler \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
 
 @app.post("/webhook")
@@ -2325,8 +3474,38 @@ async def webhook(request: Request) -> Response:
 
     if dispatch and dispatch in seen_dispatches:
         return Response(content='{"ok":true,"duplicate":true}', media_type="application/json")
-    if dispatch:
-        seen_dispatches.add(dispatch)
+    # A dispatch is remembered only AFTER it has been fully handled (see the
+    # success paths below), never here. Remembering on arrival would mark a
+    # dispatch that then fails to decrypt (422) as "seen", so OneAddress's retry
+    # after you fix the key would be dismissed as a duplicate and the update lost.
+    # The address.test probe is never remembered, so re-running go-live re-tests.
+
+    # \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
+    # Carries an encrypted CUSTOMER block { name, known_names, account_number } \u2014
+    # no address, no session envelope \u2014 handled HERE, ABOVE the payload-less
+    # acknowledge below (account.verify is not a dispatch event, so it would
+    # otherwise be acknowledged as "no payload" and never actually check).
+    if event == "account.verify":
+        if not VERIFIES_ACCOUNT_REFERENCE:
+            print("[webhook] account.verify -> skipped (VERIFIES_ACCOUNT_REFERENCE is false)")
+            return Response(content='{"ok":true,"skipped":true}', media_type="application/json")
+        enc_cust = body.get("customer_encrypted")
+        if not isinstance(enc_cust, dict):
+            return Response(status_code=400, content='{"error":"Missing customer_encrypted"}',
+                            media_type="application/json")
+        try:
+            cust = _decrypt_address(enc_cust, PRIVATE_KEY, PARTNER_ID)
+        except Exception as e:
+            print(f"[webhook] account.verify decryption failed \u2014 check OA_PRIVATE_KEY_PEM: {e}")
+            return Response(status_code=422, content='{"ok":false,"error":"decryption_failed"}',
+                            media_type="application/json")
+        acct  = str(cust.get("account_number") or "")
+        cname = str(cust.get("name") or "")
+        ckn   = cust.get("known_names") or []
+        ckn   = [str(k) for k in ckn] if isinstance(ckn, list) else []
+        status = _verify_account(acct, cname, ckn)
+        print(f"[webhook] account.verify -> {status} for account {acct or '(none)'}")
+        return Response(content=json.dumps({"status": status}), media_type="application/json")
 
     # A valid signed request that carries no address payload \u2014 a conformance
     # ping, or any event added after this receiver was generated \u2014 has already
@@ -2346,15 +3525,20 @@ async def webhook(request: Request) -> Response:
     session_share    = body.get("session_key_share")
     legacy_enc       = body.get("address_encrypted")
 
-    # Decrypted display name, captured for the connection-verification probe
-    # below. Identity comes ONLY from decryption, never a cleartext wire field.
+    # Identity comes ONLY from decryption, never a cleartext wire field: under D5
+    # the name / account number / known names live INSIDE the decrypted payload.
     verified_name = ""
+    account_number = ""
+    known_names: list[str] = []
 
     if isinstance(session_envelope, str) and isinstance(session_share, dict):
         try:
             data = _decrypt_session(session_share, session_envelope, PRIVATE_KEY, PARTNER_ID)
             address = data.get("new_address", {})
             verified_name = data.get("verified_name", "") or ""
+            account_number = data.get("account_number", "") or ""
+            _kn = data.get("known_names", [])
+            known_names = [str(x) for x in _kn] if isinstance(_kn, list) else []
         except Exception as e:
             print(f"[webhook] D5 decryption failed \u2014 check OA_PRIVATE_KEY_PEM matches key_id "
                   f"{session_share.get('key_id', '?')}: {e}")
@@ -2364,6 +3548,9 @@ async def webhook(request: Request) -> Response:
         try:
             address = _decrypt_address(legacy_enc, PRIVATE_KEY, PARTNER_ID)
             verified_name = address.get("fullName", "") or ""
+            account_number = address.get("accountReference", "") or ""
+            _kn = address.get("knownNames", [])
+            known_names = [str(x) for x in _kn] if isinstance(_kn, list) else []
         except Exception as e:
             print(f"[webhook] Decryption error (check OA_PRIVATE_KEY_PEM): {e}")
             return Response(content='{"ok":false,"error":"decryption failed - partner key mismatch"}',
@@ -2373,18 +3560,57 @@ async def webhook(request: Request) -> Response:
                         media_type="application/json")
 
     if event == "address.updated":
-        customer = body.get("customer", {})
-        email = customer.get("email", "")
-        name  = customer.get("name", "")
-        # Log metadata only \u2014 never the decrypted address. stdout is captured
-        # by uvicorn / Docker / systemd-journal in production and writing PII
-        # to those streams turns every log reader into a data-exposure surface.
-        print(f"[webhook] address.updated for {email or '?'} (dispatch={dispatch})")
-        if email:
-            _save_address(email, name, address, dispatch)
+        # Identity comes ONLY from decryption \u2014 there is no cleartext customer
+        # block on the wire under D5. Log metadata only \u2014 never the decrypted
+        # address. stdout is captured by uvicorn / Docker / systemd-journal in
+        # 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
+        # Close the loop back to OneAddress so the service flips to "Confirmed".
+        # Fire-and-forget so it never delays this 200 (keep a reference so the
+        # task isn't garbage-collected before it runs).
+        _t = asyncio.create_task(_confirm_to_oneaddress(dispatch, "confirmed"))
+        _background_tasks.add(_t)
+        _t.add_done_callback(_background_tasks.discard)
+        return Response(content='{"ok":true}', media_type="application/json")
 
     elif event == "address.verify":
-        customer      = body.get("customer", {})
         callback_url  = body["callback_url"]
         callback_token= body["callback_token"]
         batch_id      = body["batch_id"]
@@ -2400,17 +3626,16 @@ async def webhook(request: Request) -> Response:
                             content='{"error":"Invalid callback_url host"}',
                             media_type="application/json")
 
-        # Real DB lookup \u2014 mirrors the TypeScript scaffold's verifyAddress.
-        # Returns "not_found" for a fresh DB (no prior address.updated for
-        # this email), "match" / "mismatch" once the customer is on file.
-        email  = customer.get("email", "")
-        result = _verify_address(email, address) if email else "not_found"
-        print(f"[webhook] address.verify -> {result} for {email or '?'}")
+        # Real roster lookup \u2014 identity comes ONLY from decryption. "not_found"
+        # for a customer not on your roster, "match" / "mismatch" otherwise.
+        result = _verify_address(account_number, verified_name, address)
+        print(f"[webhook] address.verify -> {result} for {account_number or verified_name or '?'}")
 
         payload = {
+            # 2026.2 \u2014 no member_name echo; OneAddress keys the result on
+            # (batch_id, partner_id) and validates the opaque token alone.
             "batch_id":    batch_id,
             "partner_id":  PARTNER_ID,
-            "member_name": customer.get("name", ""),
             "result":      result,
             "token":       callback_token,
         }
@@ -2419,6 +3644,8 @@ async def webhook(request: Request) -> Response:
                 await client.post(callback_url, json=payload)
         except Exception as e:
             print(f"[webhook] Callback POST failed: {e}")
+        if dispatch:
+            seen_dispatches.add(dispatch)  # remember only after the callback posted
 
     elif event in ("address.test", "address.test-dispatch"):
         # OneAddress connection-verification probe. Reaching here means the D5
@@ -2466,24 +3693,27 @@ Your webhook endpoint: \`POST http://localhost:3001/webhook\`
 
 ## Events handled
 
+### account.verify (pre-payment account check)
+Receive \u2192 verify HMAC \u2192 decrypt the customer block \u2192 \`_verify_account\` \u2192
+answer \`match\` / \`no_match\` / \`no_account\`. Gated on \`VERIFIES_ACCOUNT_REFERENCE\`
+(the wizard writes your portal declaration): when off, the receiver answers
+\`{ "ok": true, "skipped": true }\` ("not checked").
+
 ### address.updated
-Receive \u2192 verify HMAC \u2192 decrypt \u2192 persist to your DB.
+Receive \u2192 verify HMAC \u2192 decrypt \u2192 \`_save_address\` (roster upsert + history) \u2192
+fire-and-forget \`/api/confirm\` callback so the consumer's dashboard flips the
+service to "Confirmed".
 
 ### address.verify
-Receive \u2192 verify HMAC \u2192 decrypt \u2192 compare to your records \u2192 POST callback_url.
+Receive \u2192 verify HMAC \u2192 decrypt \u2192 \`_verify_address\` against your roster \u2192 POST
+\`callback_url\`.
 
-The stub in \`app.py\` always returns \`"match"\`. Replace it with a real DB lookup:
-
-\`\`\`python
-# In the address.verify branch of app.py, replace:
-result = "match"
-
-# With something like:
-record = db.get_customer(customer.get("email"))
-result = "not_found" if not record else (
-    "match" if addresses_match(record.address, address) else "mismatch"
-)
-\`\`\`
+\`app.py\` ships a **working roster store** (SQLite, seeded with one demo
+customer), not a stub \u2014 \`_verify_address\` does a real lookup and returns
+\`"match"\` / \`"mismatch"\` / \`"not_found"\`, keyed on the account number and name
+the payload was **decrypted** to (there is no cleartext customer block on the
+wire under D5). Point \`_find_customer\` / \`_save_address\` at your real customer
+database when you outgrow the file.
 
 Valid results: \`"match"\` | \`"mismatch"\` | \`"not_found"\`
 
@@ -2495,7 +3725,17 @@ npx @oneaddress/conformance test %%WEBHOOK_URL%%
 
 ## Configuration
 
-Credentials are in \`.env\` (written by the setup wizard). Never commit \`.env\` to source control.
+Credentials and config are in \`.env\` (written by the setup wizard). Never commit
+\`.env\` to source control.
+
+| Env var | Description |
+|---------|-------------|
+| \`OA_PARTNER_ID\` | Your partner UUID |
+| \`OA_WEBHOOK_SECRET\` | HMAC-SHA256 webhook signing secret |
+| \`OA_PRIVATE_KEY_PEM\` | PKCS#8 PEM key \u2014 \`\\n\` between PEM lines |
+| \`ONEADDRESS_API\` | Confirm-callback target \u2014 the customer app (default \`https://oneaddress.io\`), NOT the partner portal |
+| \`CONFIRM_SECRET\` | Signs the \`/api/confirm\` callback. Leave blank to reuse \`OA_WEBHOOK_SECRET\` |
+| \`VERIFIES_ACCOUNT_REFERENCE\` | Whether the receiver answers \`account.verify\` (\`true\`/\`false\`) |
 `
     }
   ],
@@ -2625,6 +3865,27 @@ public final class OneAddressVerifier {
         }
     }
 
+    /**
+     * HMAC-SHA256 of {@code payload} under {@code secret}, lowercase hex. Used to
+     * SIGN the /api/confirm callback, over "&lt;timestamp&gt;.&lt;rawBody&gt;" \u2014 the
+     * same construction {@link #verify} checks on the way in.
+     */
+    public static String sign(String payload, String secret) {
+        try {
+            Mac mac = Mac.getInstance("HmacSHA256");
+            mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
+            byte[] out = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
+            StringBuilder sb = new StringBuilder(out.length * 2);
+            for (byte b : out) {
+                sb.append(Character.forDigit((b >> 4) & 0xF, 16));
+                sb.append(Character.forDigit(b & 0xF, 16));
+            }
+            return sb.toString();
+        } catch (Exception e) {
+            throw new IllegalStateException("HMAC signing failed", e);
+        }
+    }
+
     private static byte[] hexToBytes(String hex) {
         int len = hex.length();
         byte[] out = new byte[len / 2];
@@ -2882,9 +4143,19 @@ public class OneAddressWebhookController {
         this.store = store;
     }
 
+    // Baked in by the setup wizard from your portal declaration
+    // (partners.verifies_account_reference). Decides whether this receiver
+    // ANSWERS the pre-payment account.verify check. Override with the
+    // VERIFIES_ACCOUNT_REFERENCE env var ("true"/"false").
+    private static final boolean DEFAULT_VERIFIES_ACCOUNT_REFERENCE = %%VERIFIES_ACCOUNT_REFERENCE%%;
+
     private String webhookSecret;
     private String privateKeyPem;
     private String partnerId;
+    // Confirm-callback config.
+    private String oneAddressApi;
+    private String confirmSecret;
+    private boolean verifiesAccountReference;
 
     @PostConstruct
     void init() {
@@ -2900,6 +4171,22 @@ public class OneAddressWebhookController {
         partnerId = System.getenv("ONEADDRESS_PARTNER_ID");
         if (partnerId == null || partnerId.isBlank())
             throw new IllegalStateException("ONEADDRESS_PARTNER_ID is required");
+
+        // ONEADDRESS_API is the CUSTOMER app (/api/confirm lives there, NOT the
+        // partner portal); default to production.
+        String api = System.getenv("ONEADDRESS_API");
+        oneAddressApi = (api == null || api.isBlank()) ? "https://oneaddress.io" : api.trim();
+        while (oneAddressApi.endsWith("/")) oneAddressApi = oneAddressApi.substring(0, oneAddressApi.length() - 1);
+
+        // CONFIRM_SECRET signs the callback; falls back to the webhook secret,
+        // which is correct for most partners.
+        String cs = System.getenv("CONFIRM_SECRET");
+        confirmSecret = (cs == null || cs.isBlank()) ? webhookSecret : cs;
+
+        String vr = System.getenv("VERIFIES_ACCOUNT_REFERENCE");
+        verifiesAccountReference = (vr == null || vr.isBlank())
+            ? DEFAULT_VERIFIES_ACCOUNT_REFERENCE
+            : vr.equals("true");
     }
 
     @PostMapping("/oneaddress")
@@ -2924,6 +4211,44 @@ public class OneAddressWebhookController {
             Map<String, Object> body = MAPPER.readValue(rawBody, Map.class);
             String event = (String) body.get("event");
 
+            // \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
+            // Carries an encrypted CUSTOMER block { name, known_names,
+            // account_number } \u2014 no address, no session envelope \u2014 handled HERE,
+            // before the address-decrypt section below (account.verify carries no
+            // address_encrypted, so it would otherwise fall to the "no encrypted
+            // payload" acknowledge and never actually check the account).
+            if ("account.verify".equals(event)) {
+                // Your portal declaration, baked in by the wizard. If you do not
+                // verify account references, answer "not checked".
+                if (!verifiesAccountReference) {
+                    log.info("[OneAddress] account.verify -> skipped (VERIFIES_ACCOUNT_REFERENCE is false)");
+                    return ResponseEntity.ok("{\\"ok\\":true,\\"skipped\\":true}");
+                }
+                @SuppressWarnings("unchecked")
+                Map<String, Object> custEnc = (body.get("customer_encrypted") instanceof Map cm)
+                    ? (Map<String, Object>) cm : null;
+                if (custEnc == null)
+                    return ResponseEntity.badRequest().body("{\\"error\\":\\"Missing customer_encrypted\\"}");
+                Map<String, Object> cust;
+                try {
+                    cust = OneAddressDecryptor.decrypt(custEnc, privateKeyPem, partnerId);
+                } catch (Exception e) {
+                    log.error("[OneAddress] account.verify decryption failed \u2014 check ONEADDRESS_PRIVATE_KEY", e);
+                    return ResponseEntity.unprocessableEntity().body("{\\"ok\\":false,\\"error\\":\\"decryption_failed\\"}");
+                }
+                String acct = cust.get("account_number") instanceof String an2 ? an2 : null;
+                String acctName = cust.get("name") instanceof String nm2 ? nm2 : "";
+                java.util.List<String> acctKnownNames = java.util.List.of();
+                if (cust.get("known_names") instanceof java.util.List<?> aknl) {
+                    java.util.ArrayList<String> tmp = new java.util.ArrayList<>();
+                    for (Object o : aknl) if (o != null) tmp.add(String.valueOf(o));
+                    acctKnownNames = tmp;
+                }
+                String accountStatus = store.verifyAccount(acct, acctName, acctKnownNames);
+                log.info("[OneAddress] account.verify -> {} for account {}", accountStatus, acct == null ? "(none)" : acct);
+                return ResponseEntity.ok("{\\"status\\":\\"" + accountStatus + "\\"}");
+            }
+
             // Two possible payload shapes:
             //   (a) D5  \u2014 body.session_envelope (String) + body.session_key_share (Map)
             //   (b) Legacy \u2014 body.address_encrypted (Map)
@@ -2992,7 +4317,18 @@ public class OneAddressWebhookController {
                 // will never retry.
                 String outcome = store.applyAddress(accountNumber, verifiedName, knownNames, address);
                 if (dispatchId != null && !dispatchId.isBlank()) store.markProcessed(dispatchId, outcome);
-                return ResponseEntity.ok("{\\"ok\\":true,\\"outcome\\":\\"" + outcome + "\\"}");
+                // 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.
+                // \`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");
@@ -3070,6 +4406,67 @@ public class OneAddressWebhookController {
         }
     }
 
+    /**
+     * Close the loop after an address.updated is applied, so the consumer's
+     * dashboard flips the service to "Confirmed". Runs on a background thread
+     * (CompletableFuture.runAsync) so a slow confirm never delays the webhook's
+     * own 200 \u2014 a slow confirm must not make OneAddress time the DISPATCH out and
+     * mark it failed.
+     *
+     * Only real dispatches carry a POSITIVE-INTEGER id in X-OneAddress-Dispatch;
+     * probes (the go-live "address.test") carry a non-numeric id and have nothing
+     * to confirm, so they are skipped.
+     *
+     * Auth for /api/confirm (all three required):
+     *   Authorization: Bearer &lt;secret&gt;
+     *   X-OneAddress-Timestamp: &lt;unix seconds&gt;
+     *   X-OneAddress-Signature: HMAC-SHA256(secret, "&lt;timestamp&gt;.&lt;rawBody&gt;")
+     * The same secret signs the Bearer and the body, over the EXACT bytes POSTed.
+     */
+    private void confirmToOneAddress(String dispatch, String status) {
+        final long dispatchId;
+        try {
+            dispatchId = Long.parseLong(dispatch == null ? "" : dispatch.trim());
+        } catch (NumberFormatException e) {
+            return; // probe or non-numeric id \u2014 nothing to confirm
+        }
+        if (dispatchId <= 0) return;
+
+        java.util.concurrent.CompletableFuture.runAsync(() -> {
+            try {
+                java.util.Map<String, Object> confirmBody = new java.util.LinkedHashMap<>();
+                confirmBody.put("dispatch_id", dispatchId);
+                confirmBody.put("partner_id", partnerId);
+                confirmBody.put("status", status);
+                confirmBody.put("note", "Applied by the OneAddress webhook receiver");
+                String bodyStr = MAPPER.writeValueAsString(confirmBody);
+                String ts = String.valueOf(System.currentTimeMillis() / 1000L);
+                String sig = OneAddressVerifier.sign(ts + "." + bodyStr, confirmSecret);
+
+                HttpResponse<String> resp = HttpClient.newHttpClient().send(
+                    HttpRequest.newBuilder()
+                        .uri(URI.create(oneAddressApi + "/api/confirm"))
+                        .header("Content-Type", "application/json")
+                        .header("Authorization", "Bearer " + confirmSecret)
+                        .header("X-OneAddress-Timestamp", ts)
+                        .header("X-OneAddress-Signature", sig)
+                        .POST(HttpRequest.BodyPublishers.ofString(bodyStr))
+                        .build(),
+                    HttpResponse.BodyHandlers.ofString()
+                );
+                if (resp.statusCode() >= 200 && resp.statusCode() < 300) {
+                    log.info("[confirm] dispatch {} -> {}: acknowledged by OneAddress", dispatchId, status);
+                } else {
+                    log.error("[confirm] dispatch {} confirm FAILED \u2014 HTTP {}", dispatchId, resp.statusCode());
+                    if (resp.statusCode() == 401)
+                        log.error("[confirm] 401 means the wrong secret. If your partner has a separate confirm secret, set CONFIRM_SECRET to it (from the portal Webhook screen); otherwise your webhook signing secret should work.");
+                }
+            } catch (Exception e) {
+                log.error("[confirm] confirm request error", e);
+            }
+        });
+    }
+
     private static String getHeader(Map<String, String> headers, String name) {
         for (Map.Entry<String, String> entry : headers.entrySet())
             if (entry.getKey().equalsIgnoreCase(name)) return entry.getValue();
@@ -3274,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());
@@ -3311,6 +4718,24 @@ public class OneAddressStore {
         return same ? "match" : "mismatch";
     }
 
+    /**
+     * Pre-payment account check behind account.verify: confirm the typed
+     * account number is really one of yours and the name agrees, BEFORE the
+     * consumer pays.
+     *   "match"      account number found and the name (or a known name) agrees
+     *   "no_match"   account number found but the name does not agree
+     *   "no_account" no such account number
+     */
+    public String verifyAccount(String accountNumber, String verifiedName, List<String> knownNames) {
+        if (accountNumber == null || accountNumber.isBlank()) return "no_account";
+        List<Map<String, Object>> rows = jdbc.queryForList(
+            "SELECT full_name FROM customers WHERE account_number = ?", accountNumber.trim());
+        if (rows.isEmpty()) return "no_account";
+        String storedName = String.valueOf(rows.get(0).get("full_name"));
+        List<String> candidates = allNames(verifiedName, knownNames);
+        return candidates.stream().anyMatch(c -> c.equalsIgnoreCase(storedName)) ? "match" : "no_match";
+    }
+
     // \u2500\u2500 helpers \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
 
     private static List<String> allNames(String verifiedName, List<String> knownNames) {
@@ -3435,6 +4860,23 @@ name matching needs maiden names, initials and word order \u2014 see
 | \`ONEADDRESS_WEBHOOK_SECRET\` | Webhook secret from the Partner Portal |
 | \`ONEADDRESS_PRIVATE_KEY\` | PKCS#8 PEM private key (use \`\\n\` between lines) |
 | \`ONEADDRESS_PARTNER_ID\` | Your partner UUID |
+| \`ONEADDRESS_API\` | Confirm-callback target \u2014 the customer app (default \`https://oneaddress.io\`), NOT the partner portal |
+| \`CONFIRM_SECRET\` | Signs the \`/api/confirm\` callback. Leave unset to reuse the webhook secret (correct for most partners) |
+| \`VERIFIES_ACCOUNT_REFERENCE\` | Override the wizard's baked-in \`account.verify\` declaration (\`true\`/\`false\`) |
+
+### account.verify
+
+If you verify account references, the receiver decrypts the pre-payment
+\`account.verify\` probe and answers \`match\` / \`no_match\` / \`no_account\` from your
+roster. If not, it answers \`{ "ok": true, "skipped": true }\` ("not checked").
+The setup wizard bakes your portal declaration in; \`VERIFIES_ACCOUNT_REFERENCE\`
+overrides it.
+
+### Confirm callback
+
+After applying an \`address.updated\`, the receiver POSTs \`/api/confirm\` on
+\`ONEADDRESS_API\` (fire-and-forget, HMAC-signed with \`CONFIRM_SECRET\`) so the
+consumer's dashboard flips the service to "Confirmed".
 
 ## Run conformance check
 
@@ -3660,6 +5102,32 @@ public sealed class OneAddressStore
         return same ? "match" : "mismatch";
     }
 
+    /// <summary>
+    /// Pre-payment account check behind account.verify: confirm the typed
+    /// account number is really one of yours and the name agrees, BEFORE the
+    /// consumer pays.
+    ///   "match"      account number found and the name (or a known name) agrees
+    ///   "no_match"   account number found but the name does not agree
+    ///   "no_account" no such account number
+    /// </summary>
+    public string VerifyAccount(string? accountNumber, string verifiedName, List<string> knownNames)
+    {
+        if (string.IsNullOrWhiteSpace(accountNumber)) return "no_account";
+        using var conn = Open();
+        using var cmd = conn.CreateCommand();
+        cmd.CommandText = "SELECT full_name FROM customers WHERE account_number = $a";
+        cmd.Parameters.AddWithValue("$a", accountNumber.Trim());
+        var v = cmd.ExecuteScalar();
+        if (v is null or DBNull) return "no_account";
+        var storedName = Convert.ToString(v) ?? "";
+
+        var candidates = new List<string>();
+        if (!string.IsNullOrWhiteSpace(verifiedName)) candidates.Add(verifiedName.Trim());
+        candidates.AddRange(knownNames.Where(n => !string.IsNullOrWhiteSpace(n)).Select(n => n.Trim()));
+        return candidates.Any(c => string.Equals(c, storedName, StringComparison.OrdinalIgnoreCase))
+            ? "match" : "no_match";
+    }
+
     /// <summary>
     /// Account number first (authoritative), then name.
     ///
@@ -3681,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();
@@ -3750,6 +5228,22 @@ var privateKeyPem = (Environment.GetEnvironmentVariable("ONEADDRESS_PRIVATE_KEY"
     .Replace("\\\\n", "\\n");
 var partnerId = Environment.GetEnvironmentVariable("ONEADDRESS_PARTNER_ID") ?? "";
 
+// Confirm-callback config. ONEADDRESS_API is the CUSTOMER app (/api/confirm
+// lives there, NOT the partner portal); CONFIRM_SECRET signs the callback and
+// falls back to the webhook secret, which is correct for most partners.
+var oneAddressApiRaw = Environment.GetEnvironmentVariable("ONEADDRESS_API");
+var oneAddressApi = string.IsNullOrEmpty(oneAddressApiRaw) ? "https://oneaddress.io" : oneAddressApiRaw.TrimEnd('/');
+var confirmSecret = Environment.GetEnvironmentVariable("CONFIRM_SECRET");
+if (string.IsNullOrEmpty(confirmSecret)) confirmSecret = webhookSecret;
+
+// Whether this receiver answers the pre-payment account.verify check. The setup
+// wizard bakes your portal declaration into the default below; override it at
+// runtime with the VERIFIES_ACCOUNT_REFERENCE env var ("true"/"false").
+const bool DefaultVerifiesAccountReference = %%VERIFIES_ACCOUNT_REFERENCE%%;
+var verifiesAccountReference = Environment.GetEnvironmentVariable("VERIFIES_ACCOUNT_REFERENCE") is { } vr
+    ? vr == "true"
+    : DefaultVerifiesAccountReference;
+
 var builder = WebApplication.CreateBuilder(args);
 var app = builder.Build();
 
@@ -3784,6 +5278,45 @@ app.MapPost("/webhooks/oneaddress", async (HttpRequest request) =>
 
     var eventType = body.TryGetProperty("event", out var evtEl) ? evtEl.GetString() : null;
 
+    // \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
+    // Carries an encrypted CUSTOMER block { name, known_names, account_number } \u2014
+    // no address, no session envelope \u2014 handled HERE, ABOVE the payload-less
+    // acknowledge below (account.verify is not a dispatch event, so it would
+    // otherwise be acknowledged as "no payload" and never checked). Answer
+    // synchronously with { status }.
+    if (eventType == "account.verify")
+    {
+        // You told the portal whether you verify account references; the wizard
+        // baked that into DefaultVerifiesAccountReference. If you do NOT, answer
+        // "not checked" rather than a match/no_match you don't compute.
+        if (!verifiesAccountReference)
+        {
+            app.Logger.LogInformation("[OneAddress] account.verify \u2192 skipped (VERIFIES_ACCOUNT_REFERENCE is false)");
+            return Results.Json(new { ok = true, skipped = true });
+        }
+        if (!body.TryGetProperty("customer_encrypted", out var custEnc) || custEnc.ValueKind != JsonValueKind.Object)
+            return Results.Json(new { error = "Missing customer_encrypted" }, statusCode: 400);
+        byte[] custPlain;
+        try { custPlain = DecryptAddress(custEnc, privateKeyPem, partnerId); }
+        catch (Exception ex)
+        {
+            app.Logger.LogError(ex, "[OneAddress] account.verify decryption failed \u2014 check ONEADDRESS_PRIVATE_KEY");
+            return Results.Json(new { ok = false, error = "decryption_failed" }, statusCode: 422);
+        }
+        var cust = JsonSerializer.Deserialize<JsonElement>(custPlain);
+        string? acct = cust.TryGetProperty("account_number", out var acctEl) && acctEl.ValueKind == JsonValueKind.String
+            ? acctEl.GetString() : null;
+        var acctName = cust.TryGetProperty("name", out var anmEl) && anmEl.ValueKind == JsonValueKind.String
+            ? anmEl.GetString() ?? "" : "";
+        var acctKnownNames = new List<string>();
+        if (cust.TryGetProperty("known_names", out var aknEl) && aknEl.ValueKind == JsonValueKind.Array)
+            foreach (var n in aknEl.EnumerateArray())
+                if (n.ValueKind == JsonValueKind.String) acctKnownNames.Add(n.GetString()!);
+        var accountStatus = store.VerifyAccount(acct, acctName, acctKnownNames);
+        app.Logger.LogInformation("[OneAddress] account.verify \u2192 {Status} for account {Acct}", accountStatus, acct ?? "(none)");
+        return Results.Json(new { status = accountStatus });
+    }
+
     // address.test / address.test-dispatch (the connection-verification probe)
     // must pass this guard so it reaches the decrypt below; a wrong key then
     // returns 422 and only a real decrypt reaches the verification answer.
@@ -3896,7 +5429,17 @@ app.MapPost("/webhooks/oneaddress", async (HttpRequest request) =>
         // marks the dispatch delivered on a failure that is never retried.
         var outcome = store.ApplyAddress(accountNumber, verifiedName, knownNames, address);
         if (!string.IsNullOrEmpty(dispatchId)) store.MarkProcessed(dispatchId, outcome);
-        return Results.Json(new { ok = true, outcome });
+        // 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.
+        // \`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
     {
@@ -3909,7 +5452,68 @@ app.MapPost("/webhooks/oneaddress", async (HttpRequest request) =>
 
 app.MapGet("/health", () => Results.Ok(new { status = "ok" }));
 
-app.Run("http://localhost:3001");
+// PORT is read from the environment (default 3001) rather than hardcoded, so
+// the same build runs behind whatever port your tunnel / process manager sets.
+var port = Environment.GetEnvironmentVariable("PORT");
+if (string.IsNullOrEmpty(port)) port = "3001";
+app.Run($"http://localhost:{port}");
+
+// \u2500\u2500 Confirm callback \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
+
+// Close the loop after an address.updated is applied, so the consumer's
+// dashboard flips the service to "Confirmed". Called with the Task discarded
+// (fire-and-forget) so a slow confirm never delays the webhook's own 200 \u2014 a
+// slow confirm must not make OneAddress time the DISPATCH out and mark it
+// failed.
+//
+// Only real dispatches carry a POSITIVE-INTEGER id in X-OneAddress-Dispatch.
+// Probes (the go-live "address.test") carry a non-numeric id and have nothing
+// to confirm, so they are skipped.
+//
+// Auth for /api/confirm (all three required):
+//   Authorization: Bearer <secret>
+//   X-OneAddress-Timestamp: <unix seconds>
+//   X-OneAddress-Signature: HMAC-SHA256(secret, "<timestamp>.<rawBody>")
+// The same secret signs the Bearer and the body, over the EXACT bytes POSTed.
+async Task ConfirmToOneAddress(string oneAddressApi, string confirmSecret, string pid,
+                               string? dispatch, string status, ILogger logger)
+{
+    if (!long.TryParse((dispatch ?? "").Trim(), out var dispatchId) || dispatchId <= 0) return;
+
+    var bodyStr = JsonSerializer.Serialize(new {
+        dispatch_id = dispatchId,
+        partner_id  = pid,
+        status,
+        note        = "Applied by the OneAddress webhook receiver",
+    });
+    var ts  = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
+    var sig = Convert.ToHexString(
+        HMACSHA256.HashData(Encoding.UTF8.GetBytes(confirmSecret), Encoding.UTF8.GetBytes($"{ts}.{bodyStr}"))
+    ).ToLowerInvariant();
+
+    try
+    {
+        using var http = new HttpClient();
+        using var content = new StringContent(bodyStr, Encoding.UTF8, "application/json");
+        using var req = new HttpRequestMessage(HttpMethod.Post, $"{oneAddressApi}/api/confirm") { Content = content };
+        req.Headers.TryAddWithoutValidation("Authorization", $"Bearer {confirmSecret}");
+        req.Headers.TryAddWithoutValidation("X-OneAddress-Timestamp", ts);
+        req.Headers.TryAddWithoutValidation("X-OneAddress-Signature", sig);
+        using var resp = await http.SendAsync(req);
+        if (resp.IsSuccessStatusCode)
+            logger.LogInformation("[confirm] dispatch {Id} \u2192 {Status}: acknowledged by OneAddress", dispatchId, status);
+        else
+        {
+            logger.LogError("[confirm] dispatch {Id} confirm FAILED \u2014 HTTP {Code}", dispatchId, (int)resp.StatusCode);
+            if ((int)resp.StatusCode == 401)
+                logger.LogError("[confirm] 401 means the wrong secret. If your partner has a separate confirm secret, set CONFIRM_SECRET to it (from the portal Webhook screen); otherwise your webhook signing secret should work.");
+        }
+    }
+    catch (Exception ex)
+    {
+        logger.LogError(ex, "[confirm] confirm request error");
+    }
+}
 
 // \u2500\u2500 Crypto helpers \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
 
@@ -4176,6 +5780,24 @@ name matching needs maiden names, initials and word order \u2014 see
 | \`ONEADDRESS_WEBHOOK_SECRET\` | Webhook secret from the Partner Portal |
 | \`ONEADDRESS_PRIVATE_KEY\` | PKCS#8 PEM key \u2014 use \`\\n\` between PEM lines |
 | \`ONEADDRESS_PARTNER_ID\` | Your partner UUID |
+| \`ONEADDRESS_API\` | Confirm-callback target \u2014 the customer app (default \`https://oneaddress.io\`), NOT the partner portal |
+| \`CONFIRM_SECRET\` | Signs the \`/api/confirm\` callback. Leave unset to reuse the webhook secret (correct for most partners) |
+| \`VERIFIES_ACCOUNT_REFERENCE\` | Override the wizard's baked-in \`account.verify\` declaration (\`true\`/\`false\`) |
+| \`PORT\` | HTTP port (default \`3001\`) |
+
+### account.verify
+
+If you verify account references, the receiver decrypts the pre-payment
+\`account.verify\` probe and answers \`match\` / \`no_match\` / \`no_account\` from your
+roster. If not, it answers \`{ ok: true, skipped: true }\` ("not checked"). The
+setup wizard bakes your portal declaration in; \`VERIFIES_ACCOUNT_REFERENCE\`
+overrides it.
+
+### Confirm callback
+
+After applying an \`address.updated\`, the receiver POSTs \`/api/confirm\` on
+\`ONEADDRESS_API\` (fire-and-forget, HMAC-signed with \`CONFIRM_SECRET\`) so the
+consumer's dashboard flips the service to "Confirmed".
 
 ## Run conformance check
 
@@ -4193,6 +5815,21 @@ npx @oneaddress/conformance test http://localhost:3001/webhooks/oneaddress
 WEBHOOK_SECRET=%%WEBHOOK_SECRET%%
 PARTNER_PRIVATE_KEY_PEM="%%PRIVATE_KEY%%"
 PORT=3001
+
+# Where the confirm callback is POSTed after you apply an address update. This
+# is the CUSTOMER app (oneaddress.io), NOT the partner portal \u2014 /api/confirm
+# lives on the former. Written by the setup wizard.
+ONEADDRESS_API=%%ONEADDRESS_API%%
+
+# Secret that signs the /api/confirm callback. Leave BLANK to reuse
+# WEBHOOK_SECRET (correct for most partners); set it only if your partner has a
+# separate confirm secret in the portal Webhook screen.
+CONFIRM_SECRET=
+
+# Whether this receiver answers the pre-payment account.verify check. The wizard
+# bakes your portal declaration into a default in main.go; set this to
+# "true"/"false" only to override that at runtime.
+# VERIFIES_ACCOUNT_REFERENCE=
 `
     },
     {
@@ -4213,6 +5850,15 @@ PARTNER_PRIVATE_KEY_PEM=
 
 # HTTP port (default 3001)
 PORT=3001
+
+# Confirm-callback target \u2014 the customer app, not the partner portal.
+ONEADDRESS_API=https://oneaddress.io
+
+# Secret signing the /api/confirm callback. Blank = reuse WEBHOOK_SECRET.
+CONFIRM_SECRET=
+
+# Override the wizard's baked-in account.verify declaration ("true"/"false").
+# VERIFIES_ACCOUNT_REFERENCE=
 `
     },
     {
@@ -4429,6 +6075,38 @@ func (s *Store) VerifyAddress(accountNumber, verifiedName string, knownNames []s
 	return "mismatch"
 }
 
+// VerifyAccount is the pre-payment account check behind account.verify: confirm
+// the typed account number is really one of yours and the name agrees, BEFORE
+// the consumer pays. The boundary that stops someone pushing an update to an
+// account that isn't theirs.
+//
+//	"match"      account number found and the name (or a known name) agrees
+//	"no_match"   account number found but the name does not agree
+//	"no_account" no such account number
+func (s *Store) VerifyAccount(accountNumber, verifiedName string, knownNames []string) string {
+	acct := strings.TrimSpace(accountNumber)
+	if acct == "" {
+		return "no_account"
+	}
+	var fullName string
+	err := s.db.QueryRow("SELECT full_name FROM customers WHERE account_number = ?", acct).Scan(&fullName)
+	if err != nil {
+		// sql.ErrNoRows or any read failure \u2192 we cannot confirm the account.
+		return "no_account"
+	}
+	candidates := []string{}
+	if strings.TrimSpace(verifiedName) != "" {
+		candidates = append(candidates, verifiedName)
+	}
+	candidates = append(candidates, knownNames...)
+	for _, c := range candidates {
+		if strings.TrimSpace(c) != "" && strings.EqualFold(strings.TrimSpace(c), strings.TrimSpace(fullName)) {
+			return "match"
+		}
+	}
+	return "no_match"
+}
+
 // findCustomerID matches on account number first (authoritative), then name.
 //
 // The name pass is deliberately simple. Real matching needs maiden names,
@@ -4452,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
@@ -4548,6 +6235,12 @@ import (
 
 // \u2500\u2500 Config \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
 
+// defaultVerifiesAccountReference is baked in by the setup wizard from your
+// portal declaration (partners.verifies_account_reference). It decides whether
+// this receiver ANSWERS the pre-payment account.verify check or replies "not
+// checked". Override it at runtime with the VERIFIES_ACCOUNT_REFERENCE env var.
+const defaultVerifiesAccountReference = %%VERIFIES_ACCOUNT_REFERENCE%%
+
 func main() {
 	webhookSecret := os.Getenv("WEBHOOK_SECRET")
 	privateKeyPEM := strings.ReplaceAll(os.Getenv("PARTNER_PRIVATE_KEY_PEM"), \`\\n\`, "\\n")
@@ -4561,6 +6254,23 @@ func main() {
 		log.Fatal("[startup] Missing required env vars: WEBHOOK_SECRET, PARTNER_PRIVATE_KEY_PEM, PARTNER_ID")
 	}
 
+	// Confirm-callback config. ONEADDRESS_API is the customer app (/api/confirm
+	// lives there, NOT on the partner portal); CONFIRM_SECRET signs the callback
+	// and falls back to the webhook secret, which is correct for most partners.
+	oneAddressAPI := strings.TrimRight(os.Getenv("ONEADDRESS_API"), "/")
+	if oneAddressAPI == "" {
+		oneAddressAPI = "https://oneaddress.io"
+	}
+	confirmSecret := os.Getenv("CONFIRM_SECRET")
+	if confirmSecret == "" {
+		confirmSecret = webhookSecret
+	}
+	// Whether we answer account.verify \u2014 the wizard's default, env-overridable.
+	verifiesAccountReference := defaultVerifiesAccountReference
+	if v := os.Getenv("VERIFIES_ACCOUNT_REFERENCE"); v != "" {
+		verifiesAccountReference = v == "true"
+	}
+
 	// Durable store: schema, seed data, and the delivery log. Replaces the
 	// in-memory dedup map this scaffold used to carry \u2014 that was per-process
 	// (useless behind a load balancer), lost on restart, and marked on arrival,
@@ -4603,6 +6313,48 @@ func main() {
 
 		event, _ := parsed["event"].(string)
 
+		// \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
+		// Carries an encrypted CUSTOMER block { name, known_names, account_number }
+		// \u2014 no address, no session envelope \u2014 so it is handled HERE, ABOVE the
+		// payload-less acknowledge switch below (account.verify is not a dispatch
+		// event, so it would otherwise fall through to "no payload \u2192 skipped" and
+		// never actually check the account). Answer synchronously with { status }.
+		if event == "account.verify" {
+			// You told the portal whether you verify account references; the wizard
+			// baked that into defaultVerifiesAccountReference. If you do NOT, answer
+			// "not checked" rather than a match/no_match you don't compute.
+			if !verifiesAccountReference {
+				log.Print("[webhook] account.verify \u2192 skipped (VERIFIES_ACCOUNT_REFERENCE is false)")
+				jsonResp(w, 200, map[string]any{"ok": true, "skipped": true})
+				return
+			}
+			encCust, ok := parsed["customer_encrypted"].(map[string]any)
+			if !ok {
+				jsonResp(w, 400, map[string]any{"error": "Missing customer_encrypted"})
+				return
+			}
+			cust, derr := decryptAddress(encCust, privateKeyPEM, partnerID)
+			if derr != nil {
+				log.Printf("[webhook] account.verify decryption failed \u2014 check PARTNER_PRIVATE_KEY_PEM: %v", derr)
+				jsonResp(w, 422, map[string]any{"ok": false, "error": "decryption_failed"})
+				return
+			}
+			acct, _ := cust["account_number"].(string)
+			name, _ := cust["name"].(string)
+			var knownNames []string
+			if raw, ok := cust["known_names"].([]any); ok {
+				for _, n := range raw {
+					if s, ok := n.(string); ok {
+						knownNames = append(knownNames, s)
+					}
+				}
+			}
+			status := store.VerifyAccount(acct, name, knownNames)
+			log.Printf("[webhook] account.verify \u2192 %s for account %s (%s)", status, acct, name)
+			jsonResp(w, 200, map[string]any{"status": status})
+			return
+		}
+
 		// A valid signed request that carries no address payload \u2014 a conformance
 		// ping, or any event added after this receiver was generated \u2014 has already
 		// passed timestamp + signature above, which is exactly what such a probe
@@ -4702,7 +6454,20 @@ func main() {
 			if dispatch != "" {
 				_ = store.MarkProcessed(dispatch, outcome)
 			}
-			jsonResp(w, 200, map[string]any{"ok": true, "outcome": outcome})
+			// 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.
+			// \`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": applied, "outcome": outcome})
 			return
 
 		case "address.verify":
@@ -4794,6 +6559,67 @@ func main() {
 	log.Fatal(http.ListenAndServe(":"+port, nil))
 }
 
+// \u2500\u2500 Confirm callback \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
+
+// confirmToOneAddress closes the loop after an address.updated is applied, so
+// the consumer's dashboard flips the service to "Confirmed". Called in a
+// goroutine (fire-and-forget) so it never delays the webhook's own 200 \u2014 a slow
+// confirm must not make OneAddress time the DISPATCH out and mark it failed.
+//
+// Only real dispatches carry a POSITIVE-INTEGER id in X-OneAddress-Dispatch.
+// Probes (the go-live "address.test") carry a non-numeric id and have nothing
+// to confirm, so they are skipped.
+//
+// Auth for /api/confirm (all three required):
+//
+//	Authorization: Bearer <secret>
+//	X-OneAddress-Timestamp: <unix seconds>
+//	X-OneAddress-Signature: HMAC-SHA256(secret, "<timestamp>.<rawBody>")
+//
+// The same secret signs the Bearer and the body, over the EXACT bytes POSTed.
+func confirmToOneAddress(oneAddressAPI, confirmSecret, partnerID, dispatch, status string) {
+	dispatchID, err := strconv.ParseInt(strings.TrimSpace(dispatch), 10, 64)
+	if err != nil || dispatchID <= 0 {
+		return
+	}
+	bodyBytes, _ := json.Marshal(map[string]any{
+		"dispatch_id": dispatchID,
+		"partner_id":  partnerID,
+		"status":      status,
+		"note":        "Applied by the OneAddress webhook receiver",
+	})
+	bodyStr := string(bodyBytes)
+	ts := strconv.FormatInt(time.Now().Unix(), 10)
+	mac := hmac.New(sha256.New, []byte(confirmSecret))
+	mac.Write([]byte(ts + "." + bodyStr))
+	sig := hex.EncodeToString(mac.Sum(nil))
+
+	req, err := http.NewRequest(http.MethodPost, oneAddressAPI+"/api/confirm", strings.NewReader(bodyStr))
+	if err != nil {
+		log.Printf("[confirm] request build error: %v", err)
+		return
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+confirmSecret)
+	req.Header.Set("X-OneAddress-Timestamp", ts)
+	req.Header.Set("X-OneAddress-Signature", sig)
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		log.Printf("[confirm] confirm request error: %v", err)
+		return
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+		log.Printf("[confirm] dispatch %d \u2192 %s: acknowledged by OneAddress", dispatchID, status)
+		return
+	}
+	log.Printf("[confirm] dispatch %d confirm FAILED \u2014 HTTP %d", dispatchID, resp.StatusCode)
+	if resp.StatusCode == 401 {
+		log.Print("[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.")
+	}
+}
+
 // \u2500\u2500 Crypto \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
 
 func verifyHMAC(rawBody, signature, timestamp, secret string) bool {
@@ -5178,6 +7004,20 @@ Credentials are in \`.env\` (written by the setup wizard). Never commit \`.env\`
 OA_PARTNER_ID=%%PARTNER_ID%%
 OA_WEBHOOK_SECRET=%%WEBHOOK_SECRET%%
 OA_PRIVATE_KEY_PEM="%%PRIVATE_KEY%%"
+
+# Where the confirm callback is POSTed after you apply an address update. This is
+# the CUSTOMER app (oneaddress.io), NOT the partner portal \u2014 /api/confirm lives
+# on the former. Written by the setup wizard.
+ONEADDRESS_API=%%ONEADDRESS_API%%
+
+# Secret that signs the /api/confirm callback. Leave BLANK to reuse
+# OA_WEBHOOK_SECRET (correct for most partners); set it only if your partner has
+# a separate confirm secret in the portal Webhook screen.
+CONFIRM_SECRET=
+
+# Whether this receiver answers the pre-payment account.verify check. The wizard
+# writes your portal declaration here; set true/false to override.
+VERIFIES_ACCOUNT_REFERENCE=%%VERIFIES_ACCOUNT_REFERENCE%%
 `
     },
     {
@@ -5343,6 +7183,31 @@ class OneAddressStore
         return $same ? 'match' : 'mismatch';
     }
 
+    /**
+     * Pre-payment account check behind account.verify: confirm the typed account
+     * number is really one of yours and the name agrees, BEFORE the consumer pays.
+     *   'match'      account number found and the name (or a known name) agrees
+     *   'no_match'   account number found but the name does not agree
+     *   'no_account' no such account number
+     */
+    public function verifyAccount(?string $accountNumber, string $verifiedName, array $knownNames): string
+    {
+        if ($accountNumber === null || trim($accountNumber) === '') {
+            return 'no_account';
+        }
+        $row = DB::table('customers')->where('account_number', trim($accountNumber))->first();
+        if (!$row) {
+            return 'no_account';
+        }
+        $candidates = array_filter(array_merge([$verifiedName], $knownNames), fn ($n) => is_string($n) && trim($n) !== '');
+        foreach ($candidates as $name) {
+            if (strcasecmp(trim($name), $row->full_name) === 0) {
+                return 'match';
+            }
+        }
+        return 'no_match';
+    }
+
     /**
      * Account number first (authoritative), then name.
      *
@@ -5361,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) {
@@ -5412,11 +7287,135 @@ class OneAddressStore
     }
 }
 
+/**
+ * Load a partner private key from a PEM (or bare base64 DER) string.
+ * Returns an OpenSSL key resource/object, or false on failure.
+ */
+function oaLoadPrivateKey(string $raw)
+{
+    $keyStr = trim($raw);
+    if (strpos($keyStr, '-----') === false) {
+        $keyStr = "-----BEGIN PRIVATE KEY-----\\n"
+            . chunk_split($keyStr, 64, "\\n")
+            . "-----END PRIVATE KEY-----";
+    }
+    return openssl_pkey_get_private($keyStr);
+}
+
+/**
+ * Legacy (non-D5) ECDH + HKDF-SHA256 + AES-256-GCM decrypt of a { ephemeralPublicKey,
+ * iv, ciphertext, hkdfSalt } block \u2014 the same primitive address_encrypted uses, and
+ * the shape account.verify's customer_encrypted block arrives in. Returns the decoded
+ * object, or null on any failure.
+ */
+function oaDecryptLegacy(array $enc, $privateKey, string $partnerId): ?array
+{
+    $b64 = fn (string $s): string => base64_decode(strtr($s, '-_', '+/'));
+    $spkiPrefix = "\\x30\\x59\\x30\\x13\\x06\\x07\\x2a\\x86\\x48\\xce\\x3d\\x02\\x01"
+                . "\\x06\\x08\\x2a\\x86\\x48\\xce\\x3d\\x03\\x01\\x07\\x03\\x42\\x00";
+
+    $ephRaw = $b64($enc['ephemeralPublicKey'] ?? '');
+    if (strlen($ephRaw) !== 65 || ord($ephRaw[0]) !== 0x04) {
+        return null;
+    }
+    $ephPem = "-----BEGIN PUBLIC KEY-----\\n"
+        . chunk_split(base64_encode($spkiPrefix . $ephRaw), 64, "\\n")
+        . "-----END PUBLIC KEY-----";
+    $ephKey = openssl_pkey_get_public($ephPem);
+    if (!$ephKey) {
+        return null;
+    }
+    $shared = openssl_pkey_derive($ephKey, $privateKey);
+    if ($shared === false) {
+        return null;
+    }
+    $saltB64 = $enc['hkdfSalt'] ?? null;
+    $salt    = $saltB64 ? $b64($saltB64) : str_repeat("\\x00", 32);
+    $aesKey  = hash_hkdf('sha256', $shared, 32, 'oneaddress:' . $partnerId, $salt);
+
+    $ctFull = $b64($enc['ciphertext'] ?? '');
+    $tag    = substr($ctFull, -16);
+    $ct     = substr($ctFull, 0, -16);
+    $plaintext = openssl_decrypt($ct, 'aes-256-gcm', $aesKey, OPENSSL_RAW_DATA, $b64($enc['iv'] ?? ''), $tag);
+    if ($plaintext === false) {
+        return null;
+    }
+    $data = json_decode($plaintext, true);
+    return is_array($data) ? $data : null;
+}
+
+/**
+ * Close the loop after an address.updated is applied, so the consumer's dashboard
+ * flips the service to "Confirmed".
+ *
+ * Only real dispatches carry a POSITIVE-INTEGER id in X-OneAddress-Dispatch;
+ * probes (the go-live "address.test") carry a non-numeric id and have nothing to
+ * confirm, so they are skipped. Never throws and never affects the webhook's own
+ * 200 \u2014 a confirm failure is logged, not surfaced. PHP-FPM has no true
+ * fire-and-forget without a queue; for high volume move this into a queued job
+ * (dispatch(...)->afterResponse()).
+ *
+ * Auth for /api/confirm (all three required):
+ *   Authorization: Bearer <secret>
+ *   X-OneAddress-Timestamp: <unix seconds>
+ *   X-OneAddress-Signature: HMAC-SHA256(secret, "<timestamp>.<rawBody>")
+ * The same secret signs the Bearer and the body, over the EXACT bytes POSTed.
+ */
+function oaConfirmToOneAddress(string $oneAddressApi, string $confirmSecret, string $partnerId, string $dispatch, string $status): void
+{
+    if (!ctype_digit($dispatch) || (int) $dispatch <= 0) {
+        return;
+    }
+    $bodyStr = json_encode([
+        'dispatch_id' => (int) $dispatch,
+        'partner_id'  => $partnerId,
+        'status'      => $status,
+        'note'        => 'Applied by the OneAddress webhook receiver',
+    ]);
+    $ts  = (string) time();
+    $sig = hash_hmac('sha256', $ts . '.' . $bodyStr, $confirmSecret);
+
+    $ch = curl_init($oneAddressApi . '/api/confirm');
+    curl_setopt_array($ch, [
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_POST           => true,
+        CURLOPT_POSTFIELDS     => $bodyStr,
+        CURLOPT_HTTPHEADER     => [
+            'Content-Type: application/json',
+            'Authorization: Bearer ' . $confirmSecret,
+            'X-OneAddress-Timestamp: ' . $ts,
+            'X-OneAddress-Signature: ' . $sig,
+        ],
+        CURLOPT_TIMEOUT        => 10,
+    ]);
+    curl_exec($ch);
+    $code = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
+    curl_close($ch);
+
+    if ($code >= 200 && $code < 300) {
+        \\Log::info('[confirm] acknowledged by OneAddress', ['dispatch_id' => (int) $dispatch, 'status' => $status]);
+    } else {
+        \\Log::error('[confirm] confirm FAILED', ['dispatch_id' => (int) $dispatch, 'http' => $code]);
+        if ($code === 401) {
+            \\Log::error('[confirm] 401 means the wrong secret. If your partner has a separate confirm secret, set CONFIRM_SECRET to it (from the portal Webhook screen); otherwise your webhook signing secret should work.');
+        }
+    }
+}
+
 Route::post('/webhook', function (Request $request): Response {
     $partnerId     = env('OA_PARTNER_ID',      '%%PARTNER_ID%%');
     $webhookSecret = env('OA_WEBHOOK_SECRET',  '');
     $privateKeyB64 = env('OA_PRIVATE_KEY_PEM', '');
 
+    // Confirm-callback config. ONEADDRESS_API is the CUSTOMER app (/api/confirm
+    // lives there, NOT the partner portal); CONFIRM_SECRET signs the callback and
+    // falls back to the webhook secret, which is correct for most partners.
+    $oneAddressApi = rtrim(env('ONEADDRESS_API', 'https://oneaddress.io'), '/');
+    $confirmSecret = env('CONFIRM_SECRET') ?: $webhookSecret;
+    // Whether this receiver answers the pre-payment account.verify check. The
+    // wizard bakes your portal declaration into the default; env overrides it.
+    $verifiesAccountReference = filter_var(env('VERIFIES_ACCOUNT_REFERENCE', %%VERIFIES_ACCOUNT_REFERENCE%%), FILTER_VALIDATE_BOOLEAN);
+
     $rawBody   = $request->getContent();
     $timestamp = $request->header('X-OneAddress-Timestamp', '');
     $signature = $request->header('X-OneAddress-Signature', '');
@@ -5441,6 +7440,40 @@ Route::post('/webhook', function (Request $request): Response {
 
     $eventType = $body['event'] ?? '';
 
+    // \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
+    // Carries an encrypted CUSTOMER block { name, known_names, account_number } \u2014
+    // no address, no session envelope \u2014 handled HERE, ABOVE the payload-less
+    // acknowledge below (account.verify is not a dispatch event, so it would
+    // otherwise be acknowledged as "no payload" and never actually check).
+    if ($eventType === 'account.verify') {
+        // Your portal declaration, baked in by the wizard. If you do not verify
+        // account references, answer "not checked".
+        if (!$verifiesAccountReference) {
+            \\Log::info('[OneAddress] account.verify -> skipped (VERIFIES_ACCOUNT_REFERENCE is false)');
+            return response()->json(['ok' => true, 'skipped' => true]);
+        }
+        $custEnc = $body['customer_encrypted'] ?? null;
+        if (!is_array($custEnc)) {
+            return response()->json(['error' => 'Missing customer_encrypted'], 400);
+        }
+        $accountKey = oaLoadPrivateKey($privateKeyB64);
+        if (!$accountKey) {
+            \\Log::error('[OneAddress] account.verify: failed to load private key');
+            return response()->json(['ok' => false, 'error' => 'decryption_failed'], 422);
+        }
+        $cust = oaDecryptLegacy($custEnc, $accountKey, $partnerId);
+        if ($cust === null) {
+            \\Log::error('[OneAddress] account.verify decryption failed \u2014 check OA_PRIVATE_KEY_PEM');
+            return response()->json(['ok' => false, 'error' => 'decryption_failed'], 422);
+        }
+        $acct  = is_string($cust['account_number'] ?? null) ? $cust['account_number'] : null;
+        $name  = is_string($cust['name'] ?? null) ? $cust['name'] : '';
+        $known = is_array($cust['known_names'] ?? null) ? $cust['known_names'] : [];
+        $accountStatus = (new OneAddressStore())->verifyAccount($acct, $name, $known);
+        \\Log::info('[OneAddress] account.verify', ['status' => $accountStatus, 'account' => $acct ?? '(none)']);
+        return response()->json(['status' => $accountStatus]);
+    }
+
     // address.test / address.test-dispatch (the connection-verification probe)
     // must pass this guard so it reaches the decrypt below; a wrong key then
     // returns 422 and only a real decrypt reaches the verification answer.
@@ -5645,7 +7678,16 @@ Route::post('/webhook', function (Request $request): Response {
             'partner_id' => $partnerId,
             'outcome'    => $outcome,
         ]);
-        return response()->json(['ok' => true, 'outcome' => $outcome]);
+        // Close the loop back to OneAddress so the service flips to "Confirmed",
+        // but only when we actually applied the update. Never affects this 200.
+        // \`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'] ?? '';
@@ -5700,6 +7742,15 @@ Route::get('/health', function (): \\Illuminate\\Http\\JsonResponse {
 OA_PARTNER_ID=your-partner-uuid-here
 OA_WEBHOOK_SECRET=your-webhook-secret-here
 OA_PRIVATE_KEY_PEM=<paste PKCS8 PEM private key here - use \\n between lines>
+
+# Confirm-callback target \u2014 the customer app, NOT the partner portal.
+ONEADDRESS_API=https://oneaddress.io
+
+# Signs the /api/confirm callback. Blank = reuse OA_WEBHOOK_SECRET.
+CONFIRM_SECRET=
+
+# Whether the receiver answers the pre-payment account.verify check (true/false).
+VERIFIES_ACCOUNT_REFERENCE=false
 `
     },
     {
@@ -5729,8 +7780,16 @@ Your webhook endpoint: \`POST http://localhost:3001/api/webhook\`
 
 ## Events handled
 
+### account.verify (pre-payment account check)
+Receive \u2192 verify HMAC \u2192 decrypt the customer block \u2192 \`verifyAccount\` \u2192
+answer \`match\` / \`no_match\` / \`no_account\`. Gated on \`VERIFIES_ACCOUNT_REFERENCE\`
+(the wizard writes your portal declaration): when off, the receiver answers
+\`{ "ok": true, "skipped": true }\` ("not checked").
+
 ### address.updated
-Receive \u2192 verify HMAC \u2192 decrypt \u2192 persist to your DB.
+Receive \u2192 verify HMAC \u2192 decrypt \u2192 persist to your DB \u2192 POST \`/api/confirm\` on
+\`ONEADDRESS_API\` (HMAC-signed with \`CONFIRM_SECRET\`) so the consumer's dashboard
+flips the service to "Confirmed".
 
 ### address.verify
 Receive \u2192 verify HMAC \u2192 decrypt \u2192 compare to records \u2192 POST callback_url.
@@ -5780,6 +7839,9 @@ npx @oneaddress/conformance test %%WEBHOOK_URL%%
 | \`OA_PARTNER_ID\` | Your partner UUID |
 | \`OA_WEBHOOK_SECRET\` | HMAC-SHA256 signing secret |
 | \`OA_PRIVATE_KEY_PEM\` | PKCS#8 PEM private key (use \`\\\\n\` between lines) |
+| \`ONEADDRESS_API\` | Confirm-callback target \u2014 the customer app (default \`https://oneaddress.io\`), NOT the partner portal |
+| \`CONFIRM_SECRET\` | Signs the \`/api/confirm\` callback. Blank = reuse \`OA_WEBHOOK_SECRET\` |
+| \`VERIFIES_ACCOUNT_REFERENCE\` | Whether the receiver answers \`account.verify\` (\`true\`/\`false\`) |
 `
     }
   ]
@@ -5816,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.1" : "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");
@@ -6007,7 +8069,6 @@ async function runDecryptCheck(webhookSecret, partnerId) {
 
 // src/install.ts
 var import_node_child_process = require("child_process");
-var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
 var COMMANDS = {
   "ts-node": { cmd: "npm", args: ["install"] },
@@ -6015,22 +8076,17 @@ var COMMANDS = {
   "go-http": { cmd: "go", args: ["mod", "tidy"] },
   "php-laravel": { cmd: "composer", args: ["install"] },
   "csharp-aspnet": { cmd: "dotnet", args: ["restore"] },
-  "java-spring": { cmd: "./mvnw", args: ["dependency:resolve", "-q"] }
+  // Use `mvn`, not `./mvnw` — the Java scaffold ships no Maven wrapper, so
+  // `./mvnw` fails ENOENT for every Java partner. A missing `mvn` on PATH is
+  // reported cleanly (ok=false) with the manual command, which is the honest
+  // failure rather than a cryptic one.
+  "java-spring": { cmd: "mvn", args: ["dependency:resolve", "-q"] }
 };
 function installDependencies(platform, outputDir) {
   const spec = COMMANDS[platform];
   if (!spec) {
     return { ok: true, output: "", manualCommand: "" };
   }
-  if (platform === "java-spring") {
-    const mvnw = (0, import_node_path2.join)(outputDir, "mvnw");
-    if ((0, import_node_fs2.existsSync)(mvnw)) {
-      try {
-        (0, import_node_fs2.chmodSync)(mvnw, 493);
-      } catch {
-      }
-    }
-  }
   const cwd = spec.cwd ? (0, import_node_path2.join)(outputDir, spec.cwd) : outputDir;
   const manualCommand = `cd ${outputDir} && ${spec.cmd} ${spec.args.join(" ")}`;
   const result = (0, import_node_child_process.spawnSync)(spec.cmd, spec.args, {
@@ -6051,15 +8107,14 @@ function installDependencies(platform, outputDir) {
 
 // src/autostart.ts
 var import_node_child_process2 = require("child_process");
-var import_node_path3 = require("path");
-var import_node_fs3 = require("fs");
 var COMMANDS2 = {
   "ts-node": { cmd: "npx", args: ["tsx", "src/server.ts"] },
   "python": { cmd: "uvicorn", args: ["app:app", "--port", "3001"] },
   "go-http": { cmd: "go", args: ["run", "."] },
   "php-laravel": { cmd: "php", args: ["artisan", "serve", "--port=3001"] },
   "csharp-aspnet": { cmd: "dotnet", args: ["run"] },
-  "java-spring": { cmd: "./mvnw", args: ["spring-boot:run"] }
+  "java-spring": { cmd: "mvn", args: ["spring-boot:run"] }
+  // no mvnw wrapper is scaffolded
 };
 var serverProcess = null;
 var serverOutput = "";
@@ -6106,20 +8161,11 @@ async function pollHealth(port, timeoutMs) {
   }
   return false;
 }
-async function startServer(platform, outputDir, port = 3001) {
+async function startServer(platform, outputDir, port = 3001, secrets = {}) {
   const spec = COMMANDS2[platform];
   if (!spec) {
     return { ok: false, output: `No start command defined for platform: ${platform}`, manualCommand: "" };
   }
-  if (platform === "java-spring") {
-    const mvnw = (0, import_node_path3.join)(outputDir, "mvnw");
-    if ((0, import_node_fs3.existsSync)(mvnw)) {
-      try {
-        (0, import_node_fs3.chmodSync)(mvnw, 493);
-      } catch {
-      }
-    }
-  }
   serverOutput = "";
   const manualCommand = `cd ${outputDir} && ${spec.cmd} ${spec.args.join(" ")}`;
   const PASSTHROUGH_KEYS = [
@@ -6157,6 +8203,9 @@ async function startServer(platform, outputDir, port = 3001) {
     const v2 = process.env[key];
     if (typeof v2 === "string") childEnv[key] = v2;
   }
+  for (const [key, value] of Object.entries(secrets)) {
+    if (value) childEnv[key] = value;
+  }
   const isWin = process.platform === "win32";
   serverProcess = (0, import_node_child_process2.spawn)(
     isWin ? "cmd.exe" : spec.cmd,
@@ -6186,9 +8235,9 @@ async function startServer(platform, outputDir, port = 3001) {
 // src/tunnel.ts
 var import_node_child_process3 = require("child_process");
 var import_promises2 = require("fs/promises");
-var import_node_fs4 = require("fs");
+var import_node_fs2 = require("fs");
 var import_node_crypto3 = require("crypto");
-var import_node_path4 = require("path");
+var import_node_path3 = require("path");
 var import_node_os = __toESM(require("os"));
 var tunnelProcess = null;
 function stopTunnel() {
@@ -6236,19 +8285,19 @@ async function downloadCloudflared() {
   if (!spec) {
     throw new Error(`No cloudflared asset known for ${key}. Install cloudflared manually or provide your own HTTPS URL when prompted.`);
   }
-  const cacheDir = (0, import_node_path4.join)(import_node_os.default.tmpdir(), `oneaddress-cloudflared-${CLOUDFLARED_VERSION}`);
+  const cacheDir = (0, import_node_path3.join)(import_node_os.default.tmpdir(), `oneaddress-cloudflared-${CLOUDFLARED_VERSION}`);
   const binaryName = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
-  const finalPath = (0, import_node_path4.join)(cacheDir, binaryName);
-  if (!spec.archive && (0, import_node_fs4.existsSync)(finalPath)) {
+  const finalPath = (0, import_node_path3.join)(cacheDir, binaryName);
+  if (!spec.archive && (0, import_node_fs2.existsSync)(finalPath)) {
     try {
       const cachedHash = await sha256File(finalPath);
       if (cachedHash === spec.sha256) return finalPath;
     } catch {
     }
   }
-  if (spec.archive && (0, import_node_fs4.existsSync)(finalPath)) return finalPath;
+  if (spec.archive && (0, import_node_fs2.existsSync)(finalPath)) return finalPath;
   await (0, import_promises2.mkdir)(cacheDir, { recursive: true });
-  const downloadPath = (0, import_node_path4.join)(cacheDir, spec.asset);
+  const downloadPath = (0, import_node_path3.join)(cacheDir, spec.asset);
   const url = `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/${spec.asset}`;
   const res = await fetch(url, { signal: AbortSignal.timeout(6e4) });
   if (!res.ok) throw new Error(`Failed to download cloudflared from ${url}: HTTP ${res.status}`);
@@ -6282,7 +8331,7 @@ Refusing to execute. Try re-running setup, or install cloudflared manually.`
       `cloudflared archive extraction failed (tar exit ${tarResult.status}): ${tarResult.stderr || tarResult.stdout || "no output"}`
     );
   }
-  if (!(0, import_node_fs4.existsSync)(finalPath)) {
+  if (!(0, import_node_fs2.existsSync)(finalPath)) {
     throw new Error(`cloudflared archive extracted but ${finalPath} not found \u2014 Cloudflare may have changed the tarball layout.`);
   }
   try {
@@ -6471,6 +8520,7 @@ async function registerWebhookUrl(partnerId, webhookSecret, webhookUrl) {
 
 // src/cli-gate.ts
 var MAX_ATTEMPTS = 3;
+var MAX_TRANSIENT_FAILURES = 5;
 var AUTH_URL = "https://partners.oneaddress.io/api/cli/auth";
 async function checkToken(token) {
   try {
@@ -6504,6 +8554,7 @@ async function checkToken(token) {
   }
 }
 async function cliGate() {
+  let transientFailures = 0;
   for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
     const token = await ge({
       message: attempt === 1 ? "OneAddress CLI token  (Profile \u2192 CLI Access in the portal)" : `OneAddress CLI token  (attempt ${attempt}/${MAX_ATTEMPTS})`,
@@ -6516,6 +8567,11 @@ async function cliGate() {
     const result = await checkToken(token);
     if (result.ok) return { partnerId: result.partnerId };
     if (result.retryable) {
+      transientFailures++;
+      if (transientFailures >= MAX_TRANSIENT_FAILURES) {
+        console.error("\n  \x1B[38;2;240;80;80m\u2717\x1B[0m  Could not reach the portal after several tries. Check your connection to partners.oneaddress.io and re-run.\n");
+        process.exit(1);
+      }
       M2.warn(`  ${result.reason}, retry the same token.`);
       attempt--;
       continue;
@@ -6614,9 +8670,9 @@ function normalisePrivateKey(raw) {
   const trimmed = raw.trim();
   const isPath = /^(\/|\.\/|\.\.\/|~\/|[A-Za-z]:[/\\])/.test(trimmed) || trimmed.endsWith(".pem");
   if (isPath) {
-    const abs = trimmed.startsWith("~/") ? (0, import_node_path5.resolve)((0, import_node_os2.homedir)(), trimmed.slice(2)) : (0, import_node_path5.resolve)(trimmed);
-    if (!(0, import_node_fs5.existsSync)(abs)) return { pem: "", error: `File not found: ${abs}` };
-    return normalisePrivateKey((0, import_node_fs5.readFileSync)(abs, "utf8"));
+    const abs = trimmed.startsWith("~/") ? (0, import_node_path4.resolve)((0, import_node_os2.homedir)(), trimmed.slice(2)) : (0, import_node_path4.resolve)(trimmed);
+    if (!(0, import_node_fs3.existsSync)(abs)) return { pem: "", error: `File not found: ${abs}` };
+    return normalisePrivateKey((0, import_node_fs3.readFileSync)(abs, "utf8"));
   }
   const unescaped = trimmed.replaceAll("\\n", "\n");
   if (unescaped.includes("-----BEGIN PRIVATE KEY-----")) {
@@ -6784,7 +8840,7 @@ async function main() {
     });
     assertNotCancelled(outputDir);
     outDir = outputDir.trim() || "./oneaddress-webhook";
-    if (!(0, import_node_fs5.existsSync)(outDir) || (0, import_node_fs5.readdirSync)(outDir).length === 0) break;
+    if (!(0, import_node_fs3.existsSync)(outDir) || (0, import_node_fs3.readdirSync)(outDir).length === 0) break;
     const overwrite = await ye({
       message: `${outDir} already has files \u2014 overwrite?`,
       initialValue: false
@@ -6862,7 +8918,12 @@ async function main() {
   const s3 = Y2();
   s3.start(`Starting server (waiting up to 15 s for /health on :${SERVER_PORT})`);
   onCleanup(stopServer);
-  const start = await startServer(platform, outDir, SERVER_PORT);
+  const start = await startServer(platform, outDir, SERVER_PORT, {
+    WEBHOOK_SECRET: secret,
+    PARTNER_ID: pid,
+    PARTNER_PRIVATE_KEY_PEM: privateKey,
+    VERIFIES_ACCOUNT_REFERENCE: String(verifiesAccountReference)
+  });
   let serverRunning = false;
   if (start.ok) {
     s3.stop(`Server is healthy on port ${SERVER_PORT}`);
@@ -7083,7 +9144,7 @@ ${DIM2}  Stopped.${R3}
 }
 
 // src/non-interactive.ts
-var import_node_fs6 = require("fs");
+var import_node_fs4 = require("fs");
 var PLATFORMS = [
   "ts-node",
   "python",
@@ -7136,7 +9197,7 @@ function parseArgs(argv2) {
   }
   return out;
 }
-function resolveConfig(args, env, normalisePrivateKey2, readFile2 = (p2) => (0, import_node_fs6.readFileSync)(p2, "utf8")) {
+function resolveConfig(args, env, normalisePrivateKey2, readFile2 = (p2) => (0, import_node_fs4.readFileSync)(p2, "utf8")) {
   const errors = [];
   for (const flag of args.secretFlagsUsed) {
     errors.push(
@@ -7238,7 +9299,7 @@ ${usage()}`);
     process.exit(1);
   }
   const { partnerId, secret, privateKey, platform, outDir, webhookUrl, force } = resolved.config;
-  if ((0, import_node_fs7.existsSync)(outDir) && (0, import_node_fs7.readdirSync)(outDir).length > 0 && !force) {
+  if ((0, import_node_fs5.existsSync)(outDir) && (0, import_node_fs5.readdirSync)(outDir).length > 0 && !force) {
     console.error(`[oneaddress/setup] ${outDir} is not empty. Pass --force to overwrite.`);
     process.exit(1);
   }