@oneaddress/setup 1.4.1 → 1.6.1

package/dist/index.js

@@ -856,7 +856,7 @@ var _R = ["\u2588\u2588\u2588\u2588\u2588\u2588 ", "\u2588\u2588   \u2588\u2588"
 var _S = [" \u2588\u2588\u2588\u2588\u2588\u2588", "\u2588\u2588     ", "\u2588\u2588     ", " \u2588\u2588\u2588\u2588\u2588 ", "     \u2588\u2588", "     \u2588\u2588", "\u2588\u2588\u2588\u2588\u2588\u2588 "];
 var ONE_ROWS = Array.from({ length: 7 }, (_3, i) => [_O[i], _N[i], _E[i]].join(" "));
 var ADDR_ROWS = Array.from({ length: 7 }, (_3, i) => [_A[i], _D2[i], _D2[i], _R[i], _E[i], _S[i], _S[i]].join(" "));
-var WIZARD_VERSION = true ? "1.4.1" : "?";
+var WIZARD_VERSION = true ? "1.6.1" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -950,6 +950,10 @@ PORT=3001
       content: `.env
 node_modules/
 dist/
+# The SQLite database holds customer addresses (PII) \u2014 never commit it.
+data.db
+data.db-wal
+data.db-shm
 `
     },
     {
@@ -968,7 +972,8 @@ dist/
   "dependencies": {
     "@oneaddress/partner-sdk": "^1.6.3",
     "dotenv":  "^16.0.0",
-    "express": "^4.18.0"
+    "express": "^4.18.0",
+    "express-rate-limit": "^8.6.2"
   },
   "devDependencies": {
     "@types/express": "^4.17.0",
@@ -979,6 +984,28 @@ dist/
   },
   "engines": { "node": ">=22.5" }
 }
+`
+    },
+    {
+      name: "oneaddress.config.json",
+      content: `{
+  "//": "Written by npx @oneaddress/setup, read by src/config.ts. Non-secret config only \u2014 secrets live in .env. Any field can be overridden by an env var of the matching name (PARTNER_ID / ONEADDRESS_API / VERIFIES_ACCOUNT_REFERENCE).",
+  "partnerId": "%%PARTNER_ID%%",
+  "oneAddressApi": "%%ONEADDRESS_API%%",
+  "verifiesAccountReference": %%VERIFIES_ACCOUNT_REFERENCE%%
+}
+`
+    },
+    {
+      name: "customers.json",
+      content: `{
+  "//": "YOUR CUSTOMER ROSTER \u2014 edit this file to your customers (account number, name, and the address you hold on file today). src/store.ts seeds from here on startup; point loadRoster at your real customer database when you outgrow the file. Override the path with the ONEADDRESS_CUSTOMERS env var.",
+  "customers": [
+    { "account_number": "AUR-583920", "name": "Tim Hooper",      "address": { "street": "12 Old Mill Road",  "suburb": "Parramatta", "state": "NSW", "postcode": "2150" } },
+    { "account_number": "AUR-104772", "name": "Olivia Robinson", "address": { "street": "5 Rosewood Lane",    "suburb": "Brisbane",   "state": "QLD", "postcode": "4000" } },
+    { "account_number": "AUR-296815", "name": "Marcus Chen",     "address": { "street": "31 Goldfield Drive", "suburb": "Richmond",   "state": "VIC", "postcode": "3121" } }
+  ]
+}
 `
     },
     {
@@ -1019,9 +1046,10 @@ dist/
  * Uses the Node.js built-in \`node:sqlite\` module (available in Node 22.5+).
  * No extra packages or native compilation required.
  *
- * Two tables:
- *   addresses       \u2014 one row per customer, holds their latest address
- *   address_history \u2014 append-only audit trail of every change
+ * 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.
  *
  * The database file lives at DB_PATH (default: data.db in the project root).
  * Change the location with the DB_PATH environment variable.
@@ -1036,36 +1064,109 @@ const db = new DatabaseSync(DB_PATH);
 // WAL mode \u2014 better performance for concurrent reads
 db.exec("PRAGMA journal_mode = WAL");
 
-// customer_key is the row identity. The consumer's email never travels in the
-// clear on either path \u2014 identity comes from the decrypted payload, which
-// carries account_number and name but no email (2026.2 removed the last
-// cleartext block, on address.verify). So we key on account_number when
-// present, falling back to email only for legacy rows. email is kept as a
-// descriptive column, nullable, no longer the primary key.
-db.exec(\`
-  CREATE TABLE IF NOT EXISTS addresses (
-    customer_key TEXT PRIMARY KEY,
-    email        TEXT,
-    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 address_history (
-    id           INTEGER PRIMARY KEY AUTOINCREMENT,
-    customer_key TEXT NOT NULL,
-    email        TEXT,
-    name         TEXT NOT NULL DEFAULT '',
-    address      TEXT NOT NULL DEFAULT '{}',
-    dispatch_id  TEXT,
-    recorded_at  TEXT NOT NULL DEFAULT (datetime('now'))
-  );
-\`);
-
 console.log(\`[db] SQLite database ready \u2192 \${DB_PATH}\`);
 
 export default db;
+`
+    },
+    {
+      name: "src/config.ts",
+      content: `/**
+ * src/config.ts \u2014 the configuration you set in SETUP, read by the handler.
+ *
+ * \`npx @oneaddress/setup\` writes oneaddress.config.json next to your .env. This
+ * module is the ONE place the receiver reads it, so what you chose during setup
+ * drives the running handler with no code to edit. Secrets stay in .env; this
+ * file is non-secret behaviour only.
+ *
+ * Precedence for every field: an explicit environment variable wins (a one-off
+ * override), then oneaddress.config.json (what setup wrote), then a built-in
+ * default. A missing config file is not an error \u2014 the handler still runs.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export type ReceiverConfig = {
+  partnerId:                string;
+  oneAddressApi:            string;
+  verifiesAccountReference: boolean;
+};
+
+const DEFAULTS: ReceiverConfig = {
+  partnerId:     '',
+  oneAddressApi: 'https://oneaddress.io',
+  // A receiver that can match, matches. The wizard writes an EXPLICIT value here
+  // from your portal declaration, so this default only bites if the config file
+  // is missing entirely \u2014 in which case answering account.verify is the safer,
+  // more useful default than silently returning "not checked".
+  verifiesAccountReference: true,
+};
+
+function stripTrailingSlash(s: string): string {
+  return s.endsWith('/') ? s.slice(0, -1) : s;
+}
+
+function loadConfigFile(): Partial<ReceiverConfig> {
+  const path = process.env.ONEADDRESS_CONFIG ?? join(process.cwd(), 'oneaddress.config.json');
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+    const out: Partial<ReceiverConfig> = {};
+    if (typeof parsed.partnerId === 'string')                out.partnerId = parsed.partnerId;
+    if (typeof parsed.oneAddressApi === 'string')            out.oneAddressApi = parsed.oneAddressApi;
+    if (typeof parsed.verifiesAccountReference === 'boolean') out.verifiesAccountReference = parsed.verifiesAccountReference;
+    return out;
+  } catch {
+    // No config file (or unreadable / malformed): fall back to env + defaults.
+    return {};
+  }
+}
+
+const fromFile = loadConfigFile();
+
+export const config: ReceiverConfig = {
+  partnerId:     process.env.PARTNER_ID || fromFile.partnerId || DEFAULTS.partnerId,
+  oneAddressApi: stripTrailingSlash(process.env.ONEADDRESS_API || fromFile.oneAddressApi || DEFAULTS.oneAddressApi),
+  verifiesAccountReference:
+    process.env.VERIFIES_ACCOUNT_REFERENCE != null
+      ? process.env.VERIFIES_ACCOUNT_REFERENCE === 'true'
+      : (fromFile.verifiesAccountReference ?? DEFAULTS.verifiesAccountReference),
+};
+
+console.log(
+  '[config] loaded (oneAddressApi=' + config.oneAddressApi +
+  ', verifiesAccountReference=' + config.verifiesAccountReference + ')',
+);
+`
+    },
+    {
+      name: "src/callback-url.ts",
+      content: `/**
+ * src/callback-url.ts \u2014 the address.verify callback host allowlist.
+ *
+ * OneAddress sends the \`callback_url\` inside the signed webhook body, so HMAC
+ * verification already proves it came from OneAddress. This host allowlist is a
+ * belt-and-braces against a leaked-webhook-secret SSRF: an attacker who could
+ * forge a webhook must not be able to coerce this server into POSTing to an
+ * internal URL (a cloud metadata service, a database admin port, \u2026).
+ *
+ * It returns the validated URL string (or null) rather than a boolean on
+ * purpose: the caller fetches the RETURN VALUE, so the allowlist sits directly
+ * on the taint path and is a provable barrier for CodeQL's request-forgery
+ * query (see .github/codeql/extensions/oneaddress-js-models \u2014 the same shape as
+ * the redirect sanitiser). A boolean guard would leave the raw, still-tainted
+ * value flowing to fetch, which reads as an SSRF whether or not the guard runs.
+ */
+export function safeOneAddressCallbackUrl(raw: string): string | null {
+  try {
+    const u = new URL(raw);
+    if (u.protocol !== 'https:') return null;
+    const host = u.hostname.toLowerCase();
+    if (host === 'oneaddress.io' || host.endsWith('.oneaddress.io')) return raw;
+    return null;
+  } catch {
+    return null;
+  }
+}
 `
     },
     {
@@ -1074,109 +1175,241 @@ export default db;
  * \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
  * \u2551  src/store.ts  \u2014  DATABASE INTEGRATION                          \u2551
  * \u2551                                                                  \u2551
- * \u2551  Uses Node.js built-in SQLite (node:sqlite) \u2014 no install        \u2551
- * \u2551  or native compilation needed. Requires Node.js 22.5+.          \u2551
- * \u2551  The database file is created automatically as data.db           \u2551
+ * \u2551  A realistic partner-side store: a CUSTOMER ROSTER (who your      \u2551
+ * \u2551  customers are + the address you hold on file for each), and the \u2551
+ * \u2551  three hooks OneAddress calls:                                    \u2551
+ * \u2551    verifyAccount  \u2014 pre-payment account check  (account.verify)  \u2551
+ * \u2551    verifyAddress  \u2014 is your on-file address current? (address.verify)
+ * \u2551    saveAddress    \u2014 apply a new address        (address.updated)  \u2551
  * \u2551                                                                  \u2551
- * \u2551  To use a different database (Postgres, MySQL, etc.):            \u2551
- * \u2551  Replace the db calls in saveAddress and verifyAddress below.    \u2551
+ * \u2551  Swap the SQLite queries for your real customer database when     \u2551
+ * \u2551  you're ready \u2014 the shapes below are what OneAddress hands you.  \u2551
  * \u2551  server.ts calls these after verifying and decrypting each event \u2551
  * \u2551  \u2014 the protocol layer is handled for you, never touch it.        \u2551
  * \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
  */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import db from './db.js';
 
 export type Address = Record<string, unknown>;
 
-/**
- * Identity handed to the store after server.ts decrypts an event.
+// \u2500\u2500 Schema \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// \`customers\` is your roster: the account number, the customer's name, and the
+// address YOU currently hold on file for them. \`address_history\` logs every
+// change you apply, so you have an audit trail.
+db.exec(\`
+  CREATE TABLE IF NOT EXISTS customers (
+    account_number TEXT PRIMARY KEY,
+    name           TEXT NOT NULL,
+    address        TEXT NOT NULL DEFAULT '{}',
+    updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS address_history (
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    account_number TEXT NOT NULL,
+    address        TEXT NOT NULL,
+    recorded_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+\`);
+
+// Self-migrate. An older data.db may already hold a \`customers\` table WITHOUT the
+// newer columns, and \`CREATE TABLE IF NOT EXISTS\` never alters an existing table.
+// Add any missing columns here so the handler upgrades its own schema instead of
+// forcing you to delete the database on every change \u2014 the behaviour a
+// production integration needs.
+function ensureColumn(table: string, column: string, definition: string): void {
+  const cols = db.prepare(\`PRAGMA table_info(\${table})\`).all() as Array<{ name: string }>;
+  if (!cols.some((c) => c.name === column)) {
+    db.exec(\`ALTER TABLE \${table} ADD COLUMN \${column} \${definition}\`);
+    console.log(\`[store] migrated: added column \${table}.\${column}\`);
+  }
+}
+ensureColumn('customers', 'address', "TEXT NOT NULL DEFAULT '{}'");
+ensureColumn('customers', 'updated_at', 'TEXT'); // nullable on migrate; set on write
+
+/* \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\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)
  *
- * Identity comes from the decrypted payload on both paths: \`name\` +
- * \`accountNumber\` (+ optional \`knownNames\`). There is no cleartext email on
- * either path, so \`email\` is null (2026.2 removed the last cleartext block, on
- * address.verify).
+ *  Your customers live in customers.json (written by \`npx @oneaddress/setup\`),
+ *  so you EDIT THAT FILE \u2014 never this one \u2014 to change who you know. Each entry
+ *  is an account number, the customer's name, and the address you hold on file
+ *  today, so a first update from OneAddress shows as a real change (mismatch \u2192
+ *  update \u2192 match) rather than magically already matching. Point \`loadRoster\`
+ *  at your real customer database when you outgrow the file.
  *
- * The row is keyed on \`accountNumber || email\` (see \`customerKey\`); on the
- * verify path \`accountNumber\` is recovered from the decrypted blob.
- */
+ *  Seeding rule (deliberate): the NAME is refreshed on every start, but the
+ *  ADDRESS is only seeded the first time a customer is inserted \u2014 so an update
+ *  you actually RECEIVE survives a restart and is not clobbered back to the
+ *  seed. To reset a customer's on-file address for a fresh test, delete its row
+ *  (or delete data.db) and restart.
+ * \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+type RosterEntry = { account_number: string; name: string; address: Address };
+
+// Used only if customers.json is missing or unreadable, so the handler still
+// runs out of the box. The wizard writes customers.json with these same demo
+// customers \u2014 edit that file, not this list.
+const DEFAULT_ROSTER: RosterEntry[] = [
+  { account_number: 'AUR-583920', name: 'Tim Hooper',      address: { street: '12 Old Mill Road',   suburb: 'Parramatta', state: 'NSW', postcode: '2150' } },
+  { account_number: 'AUR-104772', name: 'Olivia Robinson', address: { street: '5 Rosewood Lane',     suburb: 'Brisbane',   state: 'QLD', postcode: '4000' } },
+  { account_number: 'AUR-296815', name: 'Marcus Chen',     address: { street: '31 Goldfield Drive',  suburb: 'Richmond',   state: 'VIC', postcode: '3121' } },
+];
+
+function loadRoster(): RosterEntry[] {
+  const path = process.env.ONEADDRESS_CUSTOMERS ?? join(process.cwd(), 'customers.json');
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+    const list = Array.isArray(parsed)
+      ? parsed
+      : (parsed && typeof parsed === 'object' && Array.isArray((parsed as { customers?: unknown }).customers))
+        ? (parsed as { customers: unknown[] }).customers
+        : null;
+    if (!list) throw new Error('expected an array or { "customers": [ ... ] }');
+    const roster = list
+      .map((c) => c as Record<string, unknown>)
+      .filter((c) => typeof c.account_number === 'string' && typeof c.name === 'string')
+      .map((c) => ({
+        account_number: String(c.account_number),
+        name:           String(c.name),
+        address:        (c.address && typeof c.address === 'object') ? c.address as Address : {},
+      }));
+    if (roster.length === 0) throw new Error('no valid customers in the file');
+    return roster;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(\`[store] customers.json not loaded (\${msg}) \u2014 using the built-in demo roster. Edit customers.json to set your customers.\`);
+    return DEFAULT_ROSTER;
+  }
+}
+
+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
+  \`);
+  for (const c of ROSTER) {
+    upsert.run({ account_number: c.account_number, name: c.name, address: JSON.stringify(c.address) });
+  }
+  console.log(\`[store] roster ready (\${ROSTER.length} customers)\`);
+}
+
+// \u2500\u2500 Identity handed in by server.ts after it verifies + decrypts \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 export type Customer = {
-  email:         string | null;
-  name:          string;
-  accountNumber: string;
-  knownNames?:   string[];
+  email:          string | null;
+  name:           string;
+  accountNumber?: string;
+  knownNames?:    string[];
   /**
    * D5 LOA reference \u2014 the base64url SHA-256 of the signed consent, recomputed
    * by server.ts after decrypting \`loa_encrypted\`. A production integration
    * echoes this in the \`/api/confirm\` callback so OneAddress can verify
    * proof-of-receipt. Null on legacy dispatches that carry no encrypted LOA.
+   * The store ignores it; it rides along on the identity object for convenience.
    */
-  loaRef?:       string | null;
+  loaRef?:        string | null;
 };
 
-export type VerifyResult = 'match' | 'mismatch' | 'not_found';
-
-/** Row identity: account number when we have one, else email. */
-function customerKey(customer: Customer): string {
-  return customer.accountNumber || customer.email || '';
-}
-
 /**
- * Called when a consumer updates their address (address.updated event).
- *
- * Upserts the address into the \`addresses\` table and appends a row
- * to \`address_history\` for the audit trail.
+ * Canonical, order- and case-insensitive form of an address, so two addresses
+ * compare equal iff they mean the same thing regardless of key order or casing.
+ * Compares the WHOLE object, so it works whatever fields OneAddress sends.
  */
-export async function saveAddress(customer: Customer, address: Address): Promise<void> {
-  const addressJson = JSON.stringify(address);
-  const key         = customerKey(customer);
+function canonicalAddress(a: Address): string {
+  const entries = Object.entries(a)
+    .filter(([, v]) => typeof v === 'string' && (v as string).trim() !== '')
+    .map(([k, v]) => [k.toLowerCase(), (v as string).trim().toLowerCase().replace(/\\s+/g, ' ')] as [string, string])
+    .sort((x, y) => x[0].localeCompare(y[0]));
+  return JSON.stringify(entries);
+}
 
-  db.prepare(\`
-    INSERT INTO addresses (customer_key, email, name, address, updated_at)
-    VALUES ($key, $email, $name, $address, datetime('now'))
-    ON CONFLICT(customer_key) DO UPDATE SET
-      email      = excluded.email,
-      name       = excluded.name,
-      address    = excluded.address,
-      updated_at = excluded.updated_at
-  \`).run({ key, email: customer.email, name: customer.name, address: addressJson });
+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);
+    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);
+    if (byName) return byName as { account_number: string; name: string; address: string };
+  }
+  return undefined;
+}
 
-  db.prepare(\`
-    INSERT INTO address_history (customer_key, email, name, address, recorded_at)
-    VALUES ($key, $email, $name, $address, datetime('now'))
-  \`).run({ key, email: customer.email, name: customer.name, address: addressJson });
+// \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
+export type AccountVerdict = 'match' | 'no_match' | 'no_account';
 
-  // Metadata only \u2014 address is PII. Centralised log aggregation tools turn
-  // every log line into a data-exposure surface for customer addresses.
-  console.log(\`[store] Saved address for \${key}\${customer.loaRef ? \` (loa_ref \${customer.loaRef})\` : ''}\`);
+/**
+ * Confirms 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'      \u2014 account number found and the name agrees
+ *   'no_match'   \u2014 account number found but the name does not agree
+ *   'no_account' \u2014 no such account number
+ */
+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;
+  if (!row) return 'no_account';
+  const stored     = row.name.trim().toLowerCase();
+  const candidates = [name, ...knownNames].map(v => (v ?? '').trim().toLowerCase()).filter(Boolean);
+  return candidates.includes(stored) ? 'match' : 'no_match';
 }
 
+// \u2500\u2500 address.verify: is your on-file address current? \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+export type VerifyResult = 'match' | 'mismatch' | 'not_found';
+
 /**
- * Called during an address verification check (address.verify event).
- *
- * Looks up the customer and compares the incoming (decrypted) address
- * against what is stored in the database.
- *
- * Return values:
- *   'match'     \u2014 the address matches your records exactly
- *   'mismatch'  \u2014 you have a record but the address differs
- *   'not_found' \u2014 you have no record for this customer at all
+ * Compares the consumer's current OneAddress address against what YOU hold.
+ *   'match'     \u2014 you already hold this exact address (no update needed)
+ *   'mismatch'  \u2014 you know the customer, but hold a different address (send me one)
+ *   'not_found' \u2014 this account is not one of yours at all
+ * A brand-new connection you have never updated returns 'mismatch', which is the
+ * honest answer: you know the customer, you just don't have THIS address yet.
  */
-export async function verifyAddress(customer: Customer, address: Address): Promise<VerifyResult> {
-  const key = customerKey(customer);
-  const row = db.prepare(\`SELECT address FROM addresses WHERE customer_key = ?\`)
-    .get(key) as { address: string } | undefined;
-
+export async function verifyAddress(customer: Customer, incoming: Address): Promise<VerifyResult> {
+  const row = findCustomer(customer.accountNumber, customer.name);
   if (!row) {
-    console.log(\`[store] verifyAddress \u2192 not_found (\${key} has no record)\`);
+    console.log(\`[store] verifyAddress \u2192 not_found (\${customer.accountNumber || customer.name || '(none)'})\`);
     return 'not_found';
   }
+  let stored: Address = {};
+  try { stored = JSON.parse(row.address) as Address; } catch { /* corrupt row \u2192 treat as empty */ }
+  const result: VerifyResult = canonicalAddress(stored) === canonicalAddress(incoming) ? 'match' : 'mismatch';
+  console.log(\`[store] verifyAddress \u2192 \${result} (\${row.account_number})\`);
+  return result;
+}
+
+// \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.
+ */
+export async function saveAddress(customer: Customer, incoming: Address): Promise<void> {
+  const acct = (customer.accountNumber ?? '').trim() || customer.name.trim();
+  const addressJson = JSON.stringify(incoming);
 
-  const stored  = JSON.parse(row.address) as Address;
-  const isMatch = Object.entries(address).every(([k, v]) => stored[k] === v);
-  const result  = isMatch ? 'match' : 'mismatch';
+  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
+      name       = excluded.name,
+      address    = excluded.address,
+      updated_at = excluded.updated_at
+  \`).run({ account_number: acct, name: customer.name, address: addressJson });
 
-  console.log(\`[store] verifyAddress \u2192 \${result} for \${key}\`);
-  return result;
+  db.prepare(\`
+    INSERT INTO address_history (account_number, address) VALUES ($account_number, $address)
+  \`).run({ account_number: acct, 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.
+  console.log(\`[store] saved address for \${acct}\${customer.loaRef ? \` (loa_ref \${customer.loaRef})\` : ''}\`);
 }
 `
     },
@@ -1204,7 +1437,8 @@ if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 5)) {
 
 import 'dotenv/config';
 import express, { Request, Response } from 'express';
-import { createPrivateKey } from 'node:crypto';
+import rateLimit from 'express-rate-limit';
+import { createPrivateKey, createHmac } from 'node:crypto';
 import {
   verifySignature,
   decryptAddress,
@@ -1215,7 +1449,9 @@ import {
   type SessionKeyShare,
   type OneAddressD5LOA,
 } from '@oneaddress/partner-sdk';
-import { saveAddress, verifyAddress } from './store.js';
+import { saveAddress, verifyAddress, verifyAccount } from './store.js';
+import { config } from './config.js';
+import { safeOneAddressCallbackUrl } from './callback-url.js';
 
 const WEBHOOK_SECRET      = process.env.WEBHOOK_SECRET          ?? '';
 const PARTNER_PRIVATE_KEY = process.env.PARTNER_PRIVATE_KEY_PEM ?? '';
@@ -1225,6 +1461,16 @@ const PARTNER_PRIVATE_KEY = process.env.PARTNER_PRIVATE_KEY_PEM ?? '';
 const PARTNER_ID          = process.env.PARTNER_ID              ?? '';
 const PORT                = Number(process.env.PORT ?? 3001);
 
+// The confirm-callback target and its signing secret.
+//   ONEADDRESS_API  \u2014 comes from oneaddress.config.json (what setup wrote); an
+//                     ONEADDRESS_API env var overrides it for a one-off.
+//   CONFIRM_SECRET  \u2014 authenticates /api/confirm. It is a SECRET, so it lives in
+//                     .env, never the config file: your separate confirm secret
+//                     if you have one, otherwise your webhook signing secret
+//                     (correct for most partners).
+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.');
   process.exit(1);
@@ -1274,29 +1520,79 @@ function rememberDispatch(id: string): void {
   seenDispatches.add(id);
 }
 
-const app = express();
-app.disable('x-powered-by'); // don't fingerprint the framework
-app.use('/webhook', express.text({ type: 'application/json', limit: '1mb' }));
-
 /**
- * True iff \`raw\` parses as an https URL whose hostname is exactly
- * oneaddress.io or *.oneaddress.io. Used for the address.verify callback
- * \u2014 the URL comes from inside the signed webhook body so HMAC already
- * gates it, but the host check is a cheap belt-and-braces against a
- * leaked-webhook-secret SSRF.
+ * Close the loop: tell OneAddress you have applied an update, so the consumer's
+ * dashboard flips the service to "Confirmed". Fire-and-forget so it never delays
+ * the webhook 200 (a slow confirm must not make OneAddress time the DISPATCH out
+ * and mark it failed). Logs its own outcome.
+ *
+ * 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.
  */
-function isOneAddressCallbackUrl(raw: string): boolean {
+async function confirmToOneAddress(dispatch: string, status: 'confirmed' | 'failed'): Promise<void> {
+  // Only real dispatches carry a numeric id in X-OneAddress-Dispatch. Probes
+  // (e.g. the go-live "address.test") carry a non-numeric id and have nothing to
+  // confirm, so skip them.
+  const dispatchId = Number(dispatch);
+  if (!Number.isInteger(dispatchId) || dispatchId <= 0) return;
+
+  const bodyStr = JSON.stringify({
+    dispatch_id: dispatchId,
+    partner_id:  PARTNER_ID,
+    status,
+    note:        'Applied by the OneAddress webhook receiver',
+  });
+  const ts  = String(Math.floor(Date.now() / 1000));
+  const sig = createHmac('sha256', CONFIRM_SECRET).update(\`\${ts}.\${bodyStr}\`).digest('hex');
+
   try {
-    const u = new URL(raw);
-    if (u.protocol !== 'https:') return false;
-    const host = u.hostname.toLowerCase();
-    return host === 'oneaddress.io' || host.endsWith('.oneaddress.io');
-  } catch {
-    return false;
+    const confirmRes = await fetch(\`\${ONEADDRESS_API}/api/confirm\`, {
+      method:  'POST',
+      headers: {
+        'Content-Type':           'application/json',
+        'Authorization':          \`Bearer \${CONFIRM_SECRET}\`,
+        'X-OneAddress-Timestamp': ts,
+        'X-OneAddress-Signature': sig,
+      },
+      body: bodyStr,
+    });
+    if (confirmRes.ok) {
+      console.log(\`[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}\`);
+      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.');
+      }
+    }
+  } catch (err) {
+    console.error('[confirm] confirm request error:', err);
   }
 }
 
-app.post('/webhook', async (req: Request, res: Response) => {
+const app = express();
+app.disable('x-powered-by'); // don't fingerprint the framework
+
+// 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
+// far above any real OneAddress dispatch volume to one partner \u2014 so legitimate
+// signed dispatches are never throttled; raise \`max\` (or disable this) if you
+// run a very high-volume integration, and prefer a shared store (Redis) if you
+// run more than one instance. Per-IP, fixed 1-minute window.
+const webhookLimiter = rateLimit({
+  windowMs: 60_000,
+  max: 300,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: 'Too many requests' },
+});
+app.use('/webhook', webhookLimiter, express.text({ type: 'application/json', limit: '1mb' }));
+
+app.post('/webhook', webhookLimiter, 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 ?? '';
@@ -1335,6 +1631,54 @@ app.post('/webhook', async (req: Request, res: Response) => {
 
   const event = body.event as 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\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 address-
+  // decrypt section below. Answer SYNCHRONOUSLY with { status }.
+  if (event === 'account.verify') {
+    // You told the portal whether you verify account references; the wizard
+    // wrote that into oneaddress.config.json. If you do NOT, answer "not
+    // 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)');
+      return res.status(200).json({ ok: true, skipped: true });
+    }
+
+    const enc = body.customer_encrypted as {
+      ephemeralPublicKey: string; iv: string; ciphertext: string; hkdfSalt?: string;
+    } | undefined;
+    if (!enc) return res.status(400).json({ error: 'Missing customer_encrypted' });
+
+    let cust: Record<string, unknown>;
+    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);
+      return res.status(422).json({ ok: false, error: 'decryption_failed' });
+    }
+
+    const accountNumber = typeof cust.account_number === 'string' ? cust.account_number : null;
+    const name          = typeof cust.name === 'string' ? cust.name : '';
+    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})\`);
+    return res.status(200).json({ status });
+  }
+
+  // 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 tests.
+  // Acknowledge it here; only the real dispatch events below require decryption.
+  // A real address.updated that arrives WITHOUT a payload still falls through to
+  // 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)\`);
+    return res.status(200).json({ ok: true, skipped: true });
+  }
+
   // 5. Decrypt the address payload. Two shapes possible, exactly one per event:
   //   (a) D5 (2026+): body.session_envelope + body.session_key_share. Under D5,
   //       address.updated no longer carries a cleartext \`customer\` block \u2014
@@ -1423,6 +1767,9 @@ app.post('/webhook', async (req: Request, res: Response) => {
     console.log(\`[webhook] address.updated for \${ctx.accountNumber || ctx.name}\`);
     await saveAddress(ctx, address);
     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).
+    void confirmToOneAddress(dispatch, 'confirmed');
     return res.status(200).json({ ok: true });
   }
 
@@ -1438,7 +1785,8 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // could otherwise coerce this server into POSTing to any internal
     // URL (database admin, cloud metadata service, \u2026) \u2014 turning the partner's
     // network position into an SSRF primitive.
-    if (!isOneAddressCallbackUrl(callbackUrl)) {
+    const safeCallbackUrl = safeOneAddressCallbackUrl(callbackUrl);
+    if (!safeCallbackUrl) {
       console.warn(\`[webhook] refusing callback to non-OneAddress host: \${callbackUrl}\`);
       return res.status(400).json({ error: 'Invalid callback_url host' });
     }
@@ -1447,7 +1795,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
     const result = await verifyAddress(ctx, address);
     console.log(\`[webhook] address.verify \u2192 \${result}\`);
 
-    await fetch(callbackUrl, {
+    await fetch(safeCallbackUrl, {
       method:  'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
@@ -1593,8 +1941,11 @@ To view it, open \`data.db\` with any SQLite client (e.g. [DB Browser for SQLite
 | File | Role |
 |------|------|
 | \`src/server.ts\` | **Protocol layer \u2014 do not edit.** HMAC verification, timestamp replay protection, D5 session + legacy ECDH decryption, LOA decryption, deduplication. |
-| \`src/db.ts\`     | **SQLite setup.** Opens (or creates) \`data.db\` and defines the schema. Change \`DB_PATH\` env var to move the file. |
-| \`src/store.ts\`  | **Your integration.** \`saveAddress\` and \`verifyAddress\` \u2014 wired to SQLite out of the box. Swap for Postgres/MySQL/etc. when ready. |
+| \`src/config.ts\` | **Reads \`oneaddress.config.json\`** (what the wizard wrote) so what you set in setup drives the handler. Non-secret config only; an env var of the matching name overrides for a one-off. |
+| \`src/db.ts\`     | **SQLite setup.** Opens (or creates) \`data.db\`. Change \`DB_PATH\` env var to move the file. |
+| \`src/store.ts\`  | **Your integration.** \`verifyAccount\`, \`verifyAddress\` and \`saveAddress\`, seeded from your \`customers.json\` roster. Swap for Postgres/MySQL/etc. when ready. |
+| \`oneaddress.config.json\` | **Config from setup** \u2014 \`partnerId\`, \`oneAddressApi\`, \`verifiesAccountReference\`. Edit and restart; no code change. |
+| \`customers.json\` | **Your customer roster as data** \u2014 account number, name, and the address you hold on file. Edit this, not \`src/store.ts\`. |
 
 ## Identity & the encrypted payload
 
@@ -1614,12 +1965,13 @@ computes the LOA reference with \`d5LoaRef\`, and hands it to your store as
 ## Database tables
 
 \`\`\`sql
--- Current address per customer (upserted on every address.updated event).
--- customer_key = account number (from the decrypted payload on both paths).
-addresses(customer_key, email, name, address JSON, updated_at)
+-- Your customer roster: who you know + the address you hold on file today.
+-- Keyed on the account number. Seeded on startup from customers.json (edit that
+-- file, or point loadRoster in src/store.ts at your real customer table).
+customers(account_number, name, address JSON, updated_at)
 
--- Full history of every address change (append-only audit trail)
-address_history(id, customer_key, email, name, address JSON, recorded_at)
+-- Full history of every address change you apply (append-only audit trail).
+address_history(id, account_number, address JSON, recorded_at)
 \`\`\`
 
 ## Swapping to a production database
@@ -1639,10 +1991,19 @@ await prisma.customer.upsert({
 
 | Event | What OneAddress sends | What you must do |
 |-------|-----------------------|------------------|
-| \`address.updated\` | Encrypted new address + encrypted identity + encrypted LOA | Decrypt \u2192 \`saveAddress()\` \u2192 return 200 |
+| \`account.verify\` | Encrypted \`{ name, known_names, account_number }\` \u2014 a **pre-payment** account check, no address | If \`verifiesAccountReference\` is true: decrypt \u2192 \`verifyAccount()\` \u2192 answer \`{ status }\`. If false: answer \`{ ok: true, skipped: true }\` ("not checked"). |
+| \`address.updated\` | Encrypted new address + encrypted identity + encrypted LOA | Decrypt \u2192 \`saveAddress()\` \u2192 return 200 \u2192 **confirm callback** to OneAddress |
 | \`address.verify\`  | Encrypted address + encrypted identity to check | Decrypt \u2192 \`verifyAddress()\` \u2192 POST result to \`callback_url\` |
 
-Valid verify results: \`"match"\` \xB7 \`"mismatch"\` \xB7 \`"not_found"\`
+Valid account-check results: \`"match"\` \xB7 \`"no_match"\` \xB7 \`"no_account"\`
+Valid address-verify results: \`"match"\` \xB7 \`"mismatch"\` \xB7 \`"not_found"\`
+
+### Confirm callback (closing the loop)
+
+After an \`address.updated\` is stored, the receiver POSTs to \`\${ONEADDRESS_API}/api/confirm\`
+(HMAC-SHA256 over \`\${timestamp}.\${rawBody}\`, Bearer + \`X-OneAddress-Signature\` headers)
+so the consumer's dashboard flips the service to **Confirmed**. It is
+fire-and-forget, so a slow confirm never delays the webhook \`200\`.
 
 ## Conformance check
 
@@ -1654,8 +2015,32 @@ npx @oneaddress/conformance test %%WEBHOOK_URL%%
 
 ## Configuration
 
-All credentials are in \`.env\` (written by the setup wizard \u2014 never commit it).
-Rotate keys and update your webhook URL at [partners.oneaddress.io](https://partners.oneaddress.io).
+There are three places, split by what belongs where \u2014 configure once, the
+handler reads it:
+
+**\`.env\` \u2014 secrets** (written by the wizard, never commit it): \`PARTNER_ID\`,
+\`WEBHOOK_SECRET\`, \`PARTNER_PRIVATE_KEY_PEM\`, \`PORT\`. Rotate keys and update your
+webhook URL at [partners.oneaddress.io](https://partners.oneaddress.io).
+
+**\`oneaddress.config.json\` \u2014 non-secret config** (written by the wizard, read by
+\`src/config.ts\`). What you set in setup, so the handler behaves accordingly:
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| \`partnerId\` | \`(from setup)\` | Your partner UUID (mirrors \`.env\`; informational). |
+| \`oneAddressApi\` | \`https://oneaddress.io\` | Base URL the confirm callback posts to. |
+| \`verifiesAccountReference\` | \`(your portal declaration)\` | Whether you answer \`account.verify\` with a real match, or reply "not checked". |
+
+Each field can be overridden for a one-off by an environment variable of the
+matching name (\`PARTNER_ID\` / \`ONEADDRESS_API\` / \`VERIFIES_ACCOUNT_REFERENCE\`).
+One secret has no config-file home because it must stay out of a non-secret
+file: \`CONFIRM_SECRET\` (the \`/api/confirm\` signing secret) lives in \`.env\`, and
+defaults to your \`WEBHOOK_SECRET\` \u2014 set it only if your partner has a separate
+confirm secret.
+
+**\`customers.json\` \u2014 your customer roster** (data, not code). Edit this file to
+your customers; \`src/store.ts\` seeds from it on startup. Override its path with
+the \`ONEADDRESS_CUSTOMERS\` env var, or point \`loadRoster\` at your real database.
 `
     }
   ],
@@ -1943,6 +2328,15 @@ async def webhook(request: Request) -> Response:
     if dispatch:
         seen_dispatches.add(dispatch)
 
+    # 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
+    # tests. Acknowledge it here; only the real dispatch events below require
+    # decryption. A real address.updated with no payload still 422s below.
+    if event not in ("address.updated", "address.verify", "address.test", "address.test-dispatch"):
+        print(f"[webhook] '{event}' acknowledged (no address payload to decrypt)")
+        return Response(content='{"ok":true,"skipped":true}', media_type="application/json")
+
     # Two possible payload shapes:
     #   (a) D5  \u2014 body.session_envelope (str) + body.session_key_share (dict)
     #   (b) Legacy \u2014 body.address_encrypted (dict)
@@ -4209,6 +4603,19 @@ func main() {
 
 		event, _ := parsed["event"].(string)
 
+		// 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
+		// tests. Acknowledge it here; only the real dispatch events below require
+		// decryption. A real address.updated with no payload still 422s below.
+		switch event {
+		case "address.updated", "address.verify", "address.test", "address.test-dispatch":
+		default:
+			log.Printf("[webhook] %q acknowledged (no address payload to decrypt)", event)
+			jsonResp(w, 200, map[string]any{"ok": true, "skipped": true})
+			return
+		}
+
 		// Two possible payload shapes \u2014 D5 takes precedence when both fields
 		// are present. Production deployments holding multiple key rotations
 		// should look up the right private key by session_key_share.key_id;
@@ -5379,11 +5786,11 @@ npx @oneaddress/conformance test %%WEBHOOK_URL%%
 };
 
 // src/scaffold.ts
-function applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference) {
-  return content.replaceAll("%%PARTNER_ID%%", partnerId).replaceAll("%%WEBHOOK_SECRET%%", webhookSecret).replaceAll("%%WEBHOOK_URL%%", webhookUrl || "<your-webhook-url>").replaceAll("%%PRIVATE_KEY%%", privateKey || "<paste your PKCS8 PEM private key here>").replaceAll("%%VERIFIES_ACCOUNT_REFERENCE%%", verifiesAccountReference ? "true" : "false");
+function applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi) {
+  return content.replaceAll("%%PARTNER_ID%%", partnerId).replaceAll("%%WEBHOOK_SECRET%%", webhookSecret).replaceAll("%%WEBHOOK_URL%%", webhookUrl || "<your-webhook-url>").replaceAll("%%PRIVATE_KEY%%", privateKey || "<paste your PKCS8 PEM private key here>").replaceAll("%%ONEADDRESS_API%%", oneAddressApi || "https://oneaddress.io").replaceAll("%%VERIFIES_ACCOUNT_REFERENCE%%", verifiesAccountReference ? "true" : "false");
 }
 var SENSITIVE_FILES = /* @__PURE__ */ new Set([".env"]);
-async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUrl, privateKey = "", verifiesAccountReference = false) {
+async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUrl, privateKey = "", verifiesAccountReference = false, oneAddressApi = "https://oneaddress.io") {
   const templates = TEMPLATES[platform];
   if (!templates) throw new Error(`Unknown platform: ${platform}`);
   const written = [];
@@ -5393,7 +5800,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
     if (!(0, import_node_fs.existsSync)(dir)) {
       await (0, import_promises.mkdir)(dir, { recursive: true });
     }
-    const filled = applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference);
+    const filled = applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi);
     const isSensitive = SENSITIVE_FILES.has((0, import_node_path.basename)(name));
     await (0, import_promises.writeFile)(dest, filled, { encoding: "utf8", mode: isSensitive ? 384 : 420 });
     if (isSensitive && process.platform !== "win32") {
@@ -5409,7 +5816,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto = require("crypto");
-var PKG_VERSION = true ? "1.4.1" : "dev";
+var PKG_VERSION = true ? "1.6.1" : "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");
@@ -6368,26 +6775,23 @@ async function main() {
     ]
   });
   assertNotCancelled(platform);
-  const outputDir = await he({
-    message: "Where to write the files?",
-    placeholder: "./oneaddress-webhook",
-    defaultValue: "./oneaddress-webhook"
-  });
-  assertNotCancelled(outputDir);
-  const outDir = outputDir.trim() || "./oneaddress-webhook";
-  if ((0, import_node_fs5.existsSync)(outDir)) {
-    const entries = (0, import_node_fs5.readdirSync)(outDir);
-    if (entries.length > 0) {
-      const overwrite = await ye({
-        message: `${outDir} already has files \u2014 overwrite?`,
-        initialValue: false
-      });
-      assertNotCancelled(overwrite);
-      if (!overwrite) {
-        xe("Choose a different output directory and run again.");
-        process.exit(0);
-      }
-    }
+  let outDir;
+  for (; ; ) {
+    const outputDir = await he({
+      message: "Where to write the files?",
+      placeholder: "./oneaddress-webhook",
+      defaultValue: "./oneaddress-webhook"
+    });
+    assertNotCancelled(outputDir);
+    outDir = outputDir.trim() || "./oneaddress-webhook";
+    if (!(0, import_node_fs5.existsSync)(outDir) || (0, import_node_fs5.readdirSync)(outDir).length === 0) break;
+    const overwrite = await ye({
+      message: `${outDir} already has files \u2014 overwrite?`,
+      initialValue: false
+    });
+    assertNotCancelled(overwrite);
+    if (overwrite) break;
+    M2.info(`Keeping the files in ${outDir}. Enter a different directory to write into.`);
   }
   let accountRefReason = "";
   const accountRefDeclaration = await getVerifiesAccountReference(pid, secret, (r2) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneaddress/setup",
-  "version": "1.4.1",
+  "version": "1.6.1",
   "description": "Interactive setup wizard for OneAddress partner webhook integrations",
   "main": "dist/index.js",
   "bin": {