@oneaddress/setup 2.2.0 → 2.3.0

package/dist/index.js

@@ -828,7 +828,7 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
 };
 
 // src/prompts.ts
-var import_node_crypto5 = require("crypto");
+var import_node_crypto6 = require("crypto");
 var import_node_net = require("net");
 var import_node_fs3 = require("fs");
 var import_node_os2 = require("os");
@@ -856,7 +856,7 @@ var _R = ["\u2588\u2588\u2588\u2588\u2588\u2588 ", "\u2588\u2588   \u2588\u2588"
 var _S = [" \u2588\u2588\u2588\u2588\u2588\u2588", "\u2588\u2588     ", "\u2588\u2588     ", " \u2588\u2588\u2588\u2588\u2588 ", "     \u2588\u2588", "     \u2588\u2588", "\u2588\u2588\u2588\u2588\u2588\u2588 "];
 var ONE_ROWS = Array.from({ length: 7 }, (_3, i) => [_O[i], _N[i], _E[i]].join(" "));
 var ADDR_ROWS = Array.from({ length: 7 }, (_3, i) => [_A[i], _D2[i], _D2[i], _R[i], _E[i], _S[i], _S[i]].join(" "));
-var WIZARD_VERSION = true ? "2.2.0" : "?";
+var WIZARD_VERSION = true ? "2.3.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -909,6 +909,7 @@ function stripAnsi(s) {
 
 // src/scaffold.ts
 var import_promises = require("fs/promises");
+var import_node_crypto = require("crypto");
 var import_node_fs = require("fs");
 var import_node_path = require("path");
 
@@ -1006,10 +1007,11 @@ data.db-shm
     {
       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).",
+  "//": "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 / RECEIVER_MODE).",
   "partnerId": "%%PARTNER_ID%%",
   "oneAddressApi": "%%ONEADDRESS_API%%",
-  "verifiesAccountReference": %%VERIFIES_ACCOUNT_REFERENCE%%
+  "verifiesAccountReference": %%VERIFIES_ACCOUNT_REFERENCE%%,
+  "mode": "%%RECEIVER_MODE%%"
 }
 `
     },
@@ -1231,6 +1233,34 @@ export { PassphraseRequiredError, WrongPassphraseError };
  */
 export { isEncrypted };
 
+/**
+ * Read a timestamp out of this database, whichever of the two formats it is in.
+ *
+ * THIS DATABASE HOLDS TWO, AND NOTHING DECLARED WHICH WAS WHICH.
+ *
+ *   a SQL default, \`datetime('now')\`   ->  "2026-09-14 22:39:52"   UTC, no zone
+ *   a JS write, \`toISOString()\`        ->  "2026-09-14T22:39:52.695Z"
+ *
+ * Both appear in the SAME table: \`quarantine.received_at\` is the first and
+ * \`quarantine.replayed_at\` is the second.
+ *
+ * The first is not valid ISO-8601, so \`new Date(...)\` falls to implementation
+ * -defined parsing and V8 reads it as LOCAL time. A row written a minute ago
+ * therefore reads as an hour old for every hour the machine is from UTC. It
+ * reported \`8h ago\` for a two-minute-old row on a partner's machine in Perth,
+ * which is exactly UTC+8 and is how it was found.
+ *
+ * TOLERANT RATHER THAN MIGRATING, deliberately: a receiver that has been
+ * running has rows in the old shape and rewriting somebody's database to fix a
+ * display bug is the wrong trade. This is the same shape as the transition
+ * -tolerant blind-index reads elsewhere in this project.
+ */
+export function parseStoredTime(value: string): Date {
+  // Zone-less \`YYYY-MM-DD HH:MM:SS\` is SQLite's, and SQLite's \`now\` is UTC.
+  const sqlite = /^(\\d{4}-\\d{2}-\\d{2}) (\\d{2}:\\d{2}:\\d{2})$/.exec(value.trim());
+  return new Date(sqlite ? \`\${sqlite[1]}T\${sqlite[2]}Z\` : value);
+}
+
 /**
  * Add a column to an existing table if it is not already there.
  *
@@ -1680,7 +1710,6 @@ import { formatLine, report, type ReportLine } from './report.js';
 // One import, same as server.ts. Swapping the store swaps what the dashboard
 // reads, with nothing here to change.
 import { store } from './store.js';
-import type { StoredCustomer } from './customer-store.js';
 import { pendingConfirmCount } from './confirm-queue.js';
 import { exportHeld, heldCount, heldSummary } from './quarantine.js';
 
@@ -1701,7 +1730,7 @@ export interface TuiOptions {
    * Re-apply everything the receiver could not open, bound to [r].
    *
    * Passed IN rather than imported: \`server.ts\` already imports this file for
-   * \`notePreviousAddress\`, so importing it back would be a cycle. Optional so
+   * \`noteChange\`, so importing it back would be a cycle. Optional so
    * the dashboard still renders for a caller that has no replay to offer.
    */
   onReplay?: () => Promise<{ applied: number; failed: number }>;
@@ -1722,10 +1751,26 @@ export interface TuiOptions {
   };
 }
 
-/** 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)';
+/**
+ * What the server reports about a dispatch it applied.
+ *
+ * DELIBERATELY CARRIES NO ADDRESS AND NO NAME. This is the whole interface
+ * between the protocol layer and the screen, so anything absent from this type
+ * is something the dashboard cannot render however it is rewritten later. The
+ * address-formatting helper that used to live here went with it: a function
+ * that turns an address into a display string, sitting in the UI module, is an
+ * invitation.
+ */
+export interface ChangeFacts {
+  /** The partner's own identifier for their own record. Never the consumer's name. */
+  accountNumber: string;
+  /** Did the account-reference guard run and pass? False means you do not verify them. */
+  accountChecked: boolean;
+  /** Did the record actually move, or was it already current? */
+  changed: boolean;
+  /** Proof of consent, for your audit trail. */
+  loaRef: string | null;
+  dispatchId: string | null;
 }
 
 export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: TuiOptions): void {
@@ -1808,13 +1853,13 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
   });
 
   // \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 lastChange: { customer: StoredCustomer; previous: Record<string, unknown> } | null = null;
-  let pendingPrevious: Record<string, unknown> = {};
+  let lastChange: ChangeFacts | null = null;
 
-  // 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; };
+  // The server hands over FACTS about a dispatch, never the address. See
+  // \`ChangeFacts\` and the note at the call site in server.ts: this module is
+  // the screen, and a screen is the one place a consumer's home address is
+  // most likely to be photographed.
+  setChange = (facts) => { lastChange = facts; redraw(); };
 
   function renderStatus(): void {
     // Both states are shown, and the unprotected one is the loud colour. A
@@ -1846,31 +1891,36 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     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.{/}\`,
+        \`  {\${DIM}-fg}When one arrives, what happened to it appears here.{/}\\n\` +
+        \`  {\${DIM}-fg}The address itself never does \u2014 see below.{/}\`,
       );
       return;
     }
-    const { customer, previous } = lastChange;
-    let now: Record<string, unknown> = {};
-    try { now = JSON.parse(customer.address) as Record<string, unknown>; } catch { /* keep empty */ }
-    // COMPACT, AND THAT IS A BUG FIX RATHER THAN A TIDY-UP.
+    const f = lastChange;
+    // WHAT HAPPENED, NOT WHAT IT SAYS.
     //
-    // This used to space the lines out with blanks, which needed eight rows.
-    // The faults band takes seven rows off this panel when it appears, so on a
-    // real terminal the last line fell off the bottom - and the last line is
-    // \`now\`, the one thing the panel exists to show. blessed clips silently, so
-    // it read as a dispatch that had half worked.
+    // Every line here is a fact about the dispatch and none of them is content.
+    // An operator watching this can tell that the envelope opened, that the
+    // account was one of theirs, and whether the record actually moved - which
+    // is everything the panel was ever for. To read the address itself, look in
+    // your own database, which is where it lives and which is a deliberate act
+    // rather than a screen left open.
     //
-    // It cost a real end-to-end run an hour of doubt: the address had been
-    // applied, confirmed and acknowledged by OneAddress, and the screen showed
-    // only what it used to be. Adjacent is better anyway, because comparing two
-    // lines a blank apart is harder than comparing two lines.
+    // COMPACT ON PURPOSE. The faults band takes rows off this panel when it
+    // appears and blessed clips silently, so a tall panel loses its last line
+    // and reads as a dispatch that half worked. That cost a real end-to-end run
+    // an hour of doubt.
+    const check = f.accountChecked
+      ? \`{green-fg}account matched{/}\`
+      : \`{\${DIM}-fg}account not checked{/}\`;
+    const moved = f.changed
+      ? \`{green-fg}address changed{/}\`
+      : \`{\${AMBER}-fg}already current{/}\`;
     changeBox.setContent(
-      \`\\n  {bold}\${esc(customer.name)}{/bold}\` +
-      \`  {\${DIM}-fg}account{/} {\${AMBER}-fg}\${esc(customer.account_number)}{/}\\n\\n\` +
-      \`  {red-fg}was{/}  \${esc(oneLine(previous))}\\n\` +
-      \`  {green-fg}now{/}  {\${CREAM}-fg}\${esc(oneLine(now))}{/}\`,
+      \`\\n  {\${DIM}-fg}account{/} {\${AMBER}-fg}{bold}\${esc(f.accountNumber)}{/}{/}\\n\\n\` +
+      \`  {green-fg}decrypted{/}  \${check}  \${moved}\\n\\n\` +
+      \`  {\${DIM}-fg}loa_ref{/}   {\${CREAM}-fg}\${esc(f.loaRef ?? '(none)')}{/}\\n\` +
+      \`  {\${DIM}-fg}dispatch{/}  {\${CREAM}-fg}\${esc(f.dispatchId ?? '(none)')}{/}\`,
     );
   }
 
@@ -1979,22 +2029,12 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     const colour = line.level === 'error' ? 'red' : line.level === 'warn' ? 'yellow' : CREAM;
     const time = new Date(line.at).toTimeString().slice(0, 8);
 
-    if (/\\[store\\] saved address for /.test(text)) {
-      // 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];
-      // An indexed lookup of the one customer, not a decrypt of the whole
-      // roster to find them. Invisible at three rows and absurd at four
-      // million, which is the scale a real store is pointed at.
-      const prev = pendingPrevious;
-      if (acct) {
-        void Promise.resolve(store.find(acct)).then((customer) => {
-          if (!customer) return;
-          lastChange = { customer, previous: prev };
-          redraw();
-        });
-      }
-    }
+    // NOTHING IS PARSED OUT OF A LOG LINE HERE ANY MORE, and nothing is looked
+    // up from the store. The panel used to scrape the account out of \`[store]
+    // saved address for ...\` and then fetch that customer's record to render
+    // it, which is how a customer's name and address reached the screen. The
+    // server calls \`noteChange\` with facts instead, so this module has no path
+    // to a customer record at all.
 
     logBox.log(\`{\${DIM}-fg}\${time}{/} {\${colour}-fg}\${esc(text)}{/}\`);
     redraw();
@@ -2065,10 +2105,10 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
  * reason \`report\` has a default sink: \`--headless\` must not need a second code
  * path through the handler.
  */
-let setPrevious: (prev: Record<string, unknown>) => void = () => {};
+let setChange: (facts: ChangeFacts) => void = () => {};
 
-export function notePreviousAddress(prev: Record<string, unknown>): void {
-  setPrevious(prev);
+export function noteChange(facts: ChangeFacts): void {
+  setChange(facts);
 }
 `
     },
@@ -3118,7 +3158,7 @@ export function resetTally(): void {
  * replay would apply an address for an account they do not recognise. It stays
  * a refusal.
  */
-import db, { ensureColumn } from './db.js';
+import db, { ensureColumn, parseStoredTime } from './db.js';
 import { report } from './report.js';
 import { createHash } from 'node:crypto';
 import { writeFileSync } from 'node:fs';
@@ -3288,7 +3328,10 @@ export function heldSummary(): string[] {
 
 /** "3m ago", "2h ago". Coarse on purpose: nobody acts on seconds. */
 export function describeAge(iso: string): string {
-  const ms = Date.now() - new Date(iso).getTime();
+  // \`parseStoredTime\`, not \`new Date\`. See its docstring: this column is written
+  // by a SQL default in SQLite's zone-less UTC format, which V8 parses as local
+  // time, so a fresh row read as hours old by the machine's UTC offset.
+  const ms = Date.now() - parseStoredTime(iso).getTime();
   if (!Number.isFinite(ms) || ms < 0) return 'just now';
   const mins = Math.floor(ms / 60_000);
   if (mins < 1) return 'moments ago';
@@ -3324,13 +3367,27 @@ export function markReplayFailed(id: string, error: string): void {
  * is an update the partner never applied and is now no longer able to.
  */
 export function purgeQuarantine(days: number): { replayed: number; unreplayed: number } {
-  const cutoff = new Date(Date.now() - days * 86_400_000).toISOString();
+  // THE COMPARISON HAPPENS INSIDE SQLITE, IN SQLITE'S OWN FORMAT, and that is
+  // the fix rather than a tidy-up.
+  //
+  // It used to build an ISO cutoff in JS and compare it against a column
+  // written by a SQL default. SQLite compares those as STRINGS, and the two
+  // formats differ at the separator: ' ' is 0x20 and 'T' is 0x54. So on the
+  // boundary DAY a row still inside the window sorted BEFORE the cutoff and was
+  // deleted, up to about a day early. The table holds a consumer's encrypted
+  // address under a window we have written down, so "saved by the date prefix
+  // usually differing" is not good enough.
+  //
+  // \`datetime('now', ?)\` keeps both sides in one format and one clock. The
+  // modifier is a bound parameter rather than interpolated, so \`days\` cannot
+  // reach the SQL text.
+  const cutoffExpr = \`-\${Math.max(0, Math.floor(days))} days\`;
   const doomed = db.prepare(
-    'SELECT id, replayed_at FROM quarantine WHERE received_at < ?',
-  ).all(cutoff) as unknown as { id: string; replayed_at: string | null }[];
+    "SELECT id, replayed_at FROM quarantine WHERE received_at < datetime('now', ?)",
+  ).all(cutoffExpr) as unknown as { id: string; replayed_at: string | null }[];
   if (doomed.length === 0) return { replayed: 0, unreplayed: 0 };
 
-  db.prepare('DELETE FROM quarantine WHERE received_at < ?').run(cutoff);
+  db.prepare("DELETE FROM quarantine WHERE received_at < datetime('now', ?)").run(cutoffExpr);
 
   const unreplayed = doomed.filter((d) => d.replayed_at === null).length;
   const replayed = doomed.length - unreplayed;
@@ -3956,6 +4013,30 @@ export interface StoredCustomer {
   address: string;
 }
 
+/**
+ * Did this dispatch actually change anything?
+ *
+ * THE ONLY QUESTION THE RECEIVER MAY ASK ABOUT AN ADDRESS, and the reason it
+ * exists here rather than inside a store implementation is that the answer is
+ * a single boolean the dashboard can show, where the two addresses are a
+ * customer's home and must not travel any further than the apply.
+ *
+ * Order- and case-insensitive over the WHOLE object, so it keeps working
+ * whatever fields OneAddress adds. \`saveAddress\` returns the address it
+ * replaced; feed that and the incoming one in here, show the boolean, and let
+ * both go.
+ */
+export function sameAddress(a: Address, b: Address): boolean {
+  const canonical = (x: Address): string =>
+    JSON.stringify(
+      Object.entries(x)
+        .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((p, q) => p[0].localeCompare(q[0])),
+    );
+  return canonical(a) === canonical(b);
+}
+
 export type AccountVerdict = 'match' | 'no_match' | 'no_account';
 export type VerifyResult = 'match' | 'mismatch' | 'not_found';
 
@@ -4449,7 +4530,12 @@ export async function saveAddress(customer: Customer, incoming: Address): Promis
   // 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.
-  report.info(\`[store] saved address for \${acct}\${customer.loaRef ? \` (loa_ref \${customer.loaRef})\` : ''}\`);
+  // The ACCOUNT REFERENCE, or a marker - never the name \`acct\` may have fallen
+  // back to. The row is legitimately keyed on the name when you do not verify
+  // account references (see the docstring above); logging it is a different
+  // decision, and the wrong one.
+  const loggable = (customer.accountNumber ?? '').trim() || '(name-keyed record)';
+  report.info(\`[store] saved address for \${loggable}\${customer.loaRef ? \` (loa_ref \${customer.loaRef})\` : ''}\`);
 
   return previous;
 }
@@ -4538,9 +4624,10 @@ import {
 // the protocol layer changes.
 import { store as writeThroughStore } from './store.js';
 import { connectorStore, setCurrentRawBody } from './connector-store.js';
-import { notePreviousAddress } from './tui.js';
+import { noteChange } from './tui.js';
 import { config } from './config.js';
 import { safeOneAddressCallbackUrl } from './callback-url.js';
+import { sameAddress } from './customer-store.js';
 import { configuredKeyIds, describeKeys, keyFailureAdvice, resolvePrivateKey } from './keys.js';
 import {
   drainConfirms,
@@ -5157,7 +5244,12 @@ app.post('/webhook', async (req: Request, res: Response) => {
 
   // \u2500\u2500 address.updated: consumer changed their address \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   if (event === 'address.updated') {
-    report.info(\`[webhook] address.updated for \${ctx.accountNumber || ctx.name}\`);
+    // THE ACCOUNT, NEVER THE NAME. This used to fall back to \`ctx.name\`, so a
+    // partner who does not verify account references wrote a real consumer's
+    // name into every log line, and from there into whatever aggregates their
+    // logs. The account reference is the partner's own identifier for their own
+    // record; the name is the consumer's.
+    report.info(\`[webhook] address.updated for \${ctx.accountNumber || '(no account reference)'}\`);
 
     // AN ACCOUNT REFERENCE THAT MATCHES NOTHING MUST BE A HARD NO-MATCH.
     //
@@ -5196,12 +5288,32 @@ app.post('/webhook', async (req: Request, res: Response) => {
       }
     }
 
-    // \`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.
+    // THE DASHBOARD IS HANDED FACTS, NOT THE ADDRESS, and that is structural
+    // rather than a formatting choice.
+    //
+    // It used to receive the address this dispatch REPLACED and look the new
+    // one up from the store, and it painted both on a panel. Everything around
+    // here is careful that an address never reaches a log line - two comments
+    // one screen apart say so - and then it was drawn in large text on a screen
+    // that gets screenshotted, screen-shared and left open in an office.
+    //
+    // The receiver does not need to show an address to prove it works. It needs
+    // to show that the envelope opened, that the account was one of yours, and
+    // whether anything actually changed. Those are the facts below, and nothing
+    // that reaches \`tui.ts\` can be turned back into a consumer's home.
+    //
+    // There is nothing here to sneak past, either, which is why this is better
+    // than marking test dispatches as safe to display: a marker is something an
+    // attacker can try to forge onto a real dispatch, and a panel that never
+    // renders an address has nothing to forge it into.
     const replaced = await store.saveAddress(ctx, address);
-    notePreviousAddress(replaced);
+    noteChange({
+      accountNumber:  ctx.accountNumber || '(no account reference)',
+      accountChecked: config.verifiesAccountReference,
+      changed:        !sameAddress(replaced, address),
+      loaRef,
+      dispatchId:     dispatch || null,
+    });
     if (dispatch) rememberDispatch(dispatch); // remember only after it is stored
     // Close the loop back to OneAddress so the service flips to "Confirmed".
     // QUEUED, not sent: this is a local INSERT, so it cannot delay the 200 that
@@ -5214,7 +5326,7 @@ app.post('/webhook', async (req: Request, res: Response) => {
 
   // \u2500\u2500 address.verify: consumer is running an address check \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
   if (event === 'address.verify') {
-    report.info(\`[webhook] address.verify for \${ctx.accountNumber || ctx.name}\`);
+    report.info(\`[webhook] address.verify for \${ctx.accountNumber || '(no account reference)'}\`);
     const result = await store.verifyAddress(ctx, address);
     report.info(\`[webhook] address.verify \u2192 \${result}\`);
     const refused = await postVerifyVerdict(result);
@@ -10623,11 +10735,49 @@ npx @oneaddress/conformance test %%WEBHOOK_URL%%
 };
 
 // src/scaffold.ts
-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");
+function applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken) {
+  const filled = 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").replaceAll("%%RECEIVER_MODE%%", mode === "inbox" ? "inbox" : "write-through");
+  if (mode !== "inbox") return filled;
+  const withReadme = filled.replace(
+    "## Architecture",
+    `## Inbox mode
+
+This receiver holds dispatches as ciphertext and keeps **no private key** - it refuses to
+start with one - so it cannot read what it stores. A **connector** you run separately draws
+from it, decrypts, applies the change to your systems and acknowledges; only then does
+OneAddress confirm the update to the consumer.
+
+Until that connector runs, updates are held and the dashboard counts them as awaiting your
+systems. Nothing is lost and nothing is applied.
+
+| What | Where |
+|------|-------|
+| The decryption key | Your connector's environment, never this one |
+| \`CONNECTOR_TOKEN\` | \`.env\` here, and the same value in your connector |
+| The draw channel | \`http://127.0.0.1:3002\`, loopback only |
+
+\`CONNECTOR_TOKEN\` is its own credential: **not** your webhook secret and **not** your
+confirm secret. Those two are shared with OneAddress, and a leak of either must not also
+hand somebody your customers' addresses.
+
+## Architecture`
+  );
+  return withReadme.replace(
+    /^PARTNER_PRIVATE_KEY_PEM=.*$/m,
+    `# No PARTNER_PRIVATE_KEY_PEM here, on purpose: this receiver runs in inbox
+# mode and refuses to start with one. The key belongs in your connector.
+
+# The credential your connector presents to draw from this inbox. It must
+# match CONNECTOR_TOKEN in the connector's own environment, and it must not
+# be your webhook secret or your confirm secret.
+CONNECTOR_TOKEN=${connectorToken || generateConnectorToken()}`
+  );
+}
+function generateConnectorToken() {
+  return (0, import_node_crypto.randomBytes)(24).toString("hex");
 }
 var SENSITIVE_FILES = /* @__PURE__ */ new Set([".env"]);
-async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUrl, privateKey = "", verifiesAccountReference = false, oneAddressApi = "https://oneaddress.io") {
+async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUrl, privateKey = "", verifiesAccountReference = false, oneAddressApi = "https://oneaddress.io", mode = "write-through", connectorToken = "") {
   const templates = TEMPLATES[platform];
   if (!templates) throw new Error(`Unknown platform: ${platform}`);
   const written = [];
@@ -10637,7 +10787,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, oneAddressApi);
+    const filled = applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken);
     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") {
@@ -10652,11 +10802,11 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 }
 
 // src/register.ts
-var import_node_crypto = require("crypto");
-var PKG_VERSION = true ? "2.2.0" : "dev";
+var import_node_crypto2 = require("crypto");
+var PKG_VERSION = true ? "2.3.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");
+  return (0, import_node_crypto2.createHmac)("sha256", secret).update(message).digest("hex");
 }
 async function registerInstall(installId, partnerId, webhookSecret, platform, webhookUrl) {
   try {
@@ -10689,10 +10839,10 @@ async function registerInstall(installId, partnerId, webhookSecret, platform, we
 }
 
 // src/conformance.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 async function runConformance(webhookUrl, _partnerId, webhookSecret) {
   function sign(ts, body) {
-    return (0, import_node_crypto2.createHmac)("sha256", webhookSecret).update(`${ts}.${body}`).digest("hex");
+    return (0, import_node_crypto3.createHmac)("sha256", webhookSecret).update(`${ts}.${body}`).digest("hex");
   }
   const validBody = JSON.stringify({ event: "conformance.ping", test: true });
   const now = String(Math.floor(Date.now() / 1e3));
@@ -10733,7 +10883,7 @@ async function runConformance(webhookUrl, _partnerId, webhookSecret) {
             // Unique per test run so a partner re-running `npm test` doesn't
             // hit the scaffolded server's dedup cache and short-circuit the
             // "accepted" assertion with { ok: true, duplicate: true }.
-            "X-OneAddress-Dispatch": `conformance-${(0, import_node_crypto2.randomUUID)()}`
+            "X-OneAddress-Dispatch": `conformance-${(0, import_node_crypto3.randomUUID)()}`
           },
           body: validBody,
           signal: AbortSignal.timeout(8e3)
@@ -10785,7 +10935,7 @@ async function runDecryptCheck(webhookSecret, partnerId) {
   async function callOnce() {
     try {
       const ts = String(Math.floor(Date.now() / 1e3));
-      const sig = (0, import_node_crypto2.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
+      const sig = (0, import_node_crypto3.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
       const res2 = await fetch(VERIFY_DECRYPT_API, {
         method: "POST",
         headers: {
@@ -10860,24 +11010,46 @@ var COMMANDS = {
 function installDependencies(platform, outputDir) {
   const spec = COMMANDS[platform];
   if (!spec) {
-    return { ok: true, output: "", manualCommand: "" };
+    return Promise.resolve({ ok: true, output: "", manualCommand: "" });
   }
   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, {
-    cwd,
-    stdio: "pipe",
-    encoding: "utf8",
-    timeout: 5 * 60 * 1e3,
-    // 5 min max
-    shell: process.platform === "win32"
+  return new Promise((resolve2) => {
+    const child = (0, import_node_child_process.spawn)(spec.cmd, spec.args, {
+      cwd,
+      stdio: "pipe",
+      shell: process.platform === "win32"
+    });
+    let output = "";
+    const collect = (chunk) => {
+      if (output.length < 64e3) output += chunk.toString("utf8");
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve2(result);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish({
+        ok: false,
+        output: `${output.trim()}
+
+Timed out after 5 minutes.`.trim(),
+        manualCommand
+      });
+    }, 5 * 60 * 1e3);
+    child.on("error", (err) => {
+      finish({ ok: false, output: `${output}${err.message}`.trim(), manualCommand });
+    });
+    child.on("close", (code) => {
+      finish({ ok: code === 0, output: output.trim(), manualCommand });
+    });
   });
-  const output = [result.stdout ?? "", result.stderr ?? ""].join("").trim();
-  return {
-    ok: result.status === 0 && !result.error,
-    output,
-    manualCommand
-  };
 }
 
 // src/autostart.ts
@@ -11062,7 +11234,7 @@ async function handOverTerminal(platform, outputDir, port, secrets = {}) {
 var import_node_child_process3 = require("child_process");
 var import_promises2 = require("fs/promises");
 var import_node_fs2 = require("fs");
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var import_node_path3 = require("path");
 var import_node_os = __toESM(require("os"));
 var tunnelProcess = null;
@@ -11101,7 +11273,7 @@ function platformKey() {
   return "linux-x64";
 }
 async function sha256File(path) {
-  const hash = (0, import_node_crypto3.createHash)("sha256");
+  const hash = (0, import_node_crypto4.createHash)("sha256");
   hash.update(await (0, import_promises2.readFile)(path));
   return hash.digest("hex");
 }
@@ -11235,7 +11407,7 @@ async function startTunnel(port) {
 }
 
 // src/register-url.ts
-var import_node_crypto4 = require("crypto");
+var import_node_crypto5 = require("crypto");
 var PORTAL_API = "https://partners.oneaddress.io/api/partner/webhook-url";
 function describeReadFailure(status) {
   if (status === 401) return "the portal rejected the signature (HTTP 401), which means your Webhook signing secret does not match the one on your profile. Copy it again from partners.oneaddress.io \u2192 Webhook \u2192 Webhook signing secret.";
@@ -11246,7 +11418,7 @@ function describeReadFailure(status) {
 async function getExistingWebhookUrl(partnerId, webhookSecret, onError) {
   try {
     const ts = String(Math.floor(Date.now() / 1e3));
-    const sig = (0, import_node_crypto4.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
+    const sig = (0, import_node_crypto5.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
     const res = await fetch(PORTAL_API, {
       method: "GET",
       headers: {
@@ -11270,7 +11442,7 @@ async function getExistingWebhookUrl(partnerId, webhookSecret, onError) {
 async function getVerifiesAccountReference(partnerId, webhookSecret, onError) {
   try {
     const ts = String(Math.floor(Date.now() / 1e3));
-    const sig = (0, import_node_crypto4.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
+    const sig = (0, import_node_crypto5.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
     const res = await fetch(PORTAL_API, {
       method: "GET",
       headers: {
@@ -11297,7 +11469,7 @@ async function getVerifiesAccountReference(partnerId, webhookSecret, onError) {
 async function verifyWebhookSecret(partnerId, webhookSecret) {
   try {
     const ts = String(Math.floor(Date.now() / 1e3));
-    const sig = (0, import_node_crypto4.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
+    const sig = (0, import_node_crypto5.createHmac)("sha256", webhookSecret).update(`${ts}.`).digest("hex");
     const res = await fetch(PORTAL_API, {
       method: "GET",
       headers: {
@@ -11318,7 +11490,7 @@ async function registerWebhookUrl(partnerId, webhookSecret, webhookUrl) {
   try {
     const body = JSON.stringify({ webhook_url: webhookUrl });
     const ts = String(Math.floor(Date.now() / 1e3));
-    const sig = (0, import_node_crypto4.createHmac)("sha256", webhookSecret).update(`${ts}.${body}`).digest("hex");
+    const sig = (0, import_node_crypto5.createHmac)("sha256", webhookSecret).update(`${ts}.${body}`).digest("hex");
     const res = await fetch(PORTAL_API, {
       method: "PATCH",
       headers: {
@@ -11515,7 +11687,7 @@ ${wrapped}
 -----END EC PRIVATE KEY-----
 `;
     try {
-      const pkcs8 = (0, import_node_crypto5.createPrivateKey)({ key: sec1Pem, format: "pem", type: "sec1" }).export({ type: "pkcs8", format: "pem" });
+      const pkcs8 = (0, import_node_crypto6.createPrivateKey)({ key: sec1Pem, format: "pem", type: "sec1" }).export({ type: "pkcs8", format: "pem" });
       return { pem: pkcs8 };
     } catch (err) {
       return { pem: "", error: translateKeyError(err) };
@@ -11559,7 +11731,7 @@ function translateKeyError(err) {
 function validatePrivateKey(pem) {
   let key;
   try {
-    key = (0, import_node_crypto5.createPrivateKey)({ key: pem, format: "pem", type: "pkcs8" });
+    key = (0, import_node_crypto6.createPrivateKey)({ key: pem, format: "pem", type: "pkcs8" });
   } catch (err) {
     return translateKeyError(err);
   }
@@ -11680,6 +11852,39 @@ async function main() {
     accountRefReason = r2;
   });
   const verifiesAccountReference = accountRefDeclaration === true;
+  const modeChoice = platform !== "ts-node" ? "write-through" : await ve({
+    message: "How should this receiver handle updates?",
+    options: [
+      {
+        value: "write-through",
+        label: "Apply them itself  (simplest)",
+        hint: "Decrypts and writes to a customer store on this machine. Right for a sole trader, or to try it out."
+      },
+      {
+        value: "inbox",
+        label: "Hold them for your own systems to collect",
+        hint: "Holds ciphertext and keeps NO private key, so this process cannot read what it stores. Needs a connector you run separately."
+      }
+    ],
+    initialValue: "write-through"
+  });
+  assertNotCancelled(modeChoice);
+  const receiverMode = modeChoice;
+  const connectorToken = receiverMode === "inbox" ? generateConnectorToken() : "";
+  if (receiverMode === "inbox") {
+    M2.warn(
+      "Inbox mode needs a second process. This receiver will hold dispatches as ciphertext and\nkeep NO private key \u2014 it refuses to start with one \u2014 so a connector of yours must draw,\ndecrypt and apply them, then acknowledge. Until that connector runs, updates are held and\nthe dashboard counts them as awaiting your systems."
+    );
+    M2.info(
+      `Your connector credential (also written to .env as CONNECTOR_TOKEN):
+
+  ${connectorToken}
+
+Set the same value as CONNECTOR_TOKEN in your connector. It is its own credential:
+not your webhook secret and not your confirm secret, because those are shared with
+OneAddress and a leak of either must not also hand somebody your customers' addresses.`
+    );
+  }
   if (accountRefDeclaration === void 0) {
     M2.warn(
       "Could not read your account-reference declaration from the portal.\n" + (accountRefReason ? "Reason: " + accountRefReason + "\n" : "") + "Conformance check-14 has been left out of the generated `npm test`, so a\npassing run does NOT mean your receiver matches account references correctly.\nSet it at partners.oneaddress.io \u2192 My Profile, then re-run this wizard."
@@ -11697,7 +11902,10 @@ async function main() {
       "",
       // webhookUrl — filled in after server starts
       privateKey,
-      verifiesAccountReference
+      verifiesAccountReference,
+      void 0,
+      receiverMode,
+      connectorToken
     );
     s1.stop(`Scaffolded ${written.length} files in ${outDir}`);
     for (const f of written) M2.success(`  ${f}`);
@@ -11709,7 +11917,7 @@ async function main() {
   for (; ; ) {
     const s2 = Y2();
     s2.start("Installing dependencies  (this can take 30\u201360 s)");
-    const install = installDependencies(platform, outDir);
+    const install = await installDependencies(platform, outDir);
     if (install.ok) {
       s2.stop("Dependencies installed");
       break;
@@ -11879,7 +12087,7 @@ one of two things, and neither is your server (it is running on :3001):
       );
     }
     registerInstall(
-      `OA-${(0, import_node_crypto5.randomUUID)()}`,
+      `OA-${(0, import_node_crypto6.randomUUID)()}`,
       pid,
       secret,
       platform,

package/package.json

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