@oneaddress/setup 2.3.0 → 2.4.0

package/dist/index.js

@@ -856,7 +856,7 @@ var _R = ["\u2588\u2588\u2588\u2588\u2588\u2588 ", "\u2588\u2588   \u2588\u2588"
 var _S = [" \u2588\u2588\u2588\u2588\u2588\u2588", "\u2588\u2588     ", "\u2588\u2588     ", " \u2588\u2588\u2588\u2588\u2588 ", "     \u2588\u2588", "     \u2588\u2588", "\u2588\u2588\u2588\u2588\u2588\u2588 "];
 var ONE_ROWS = Array.from({ length: 7 }, (_3, i) => [_O[i], _N[i], _E[i]].join(" "));
 var ADDR_ROWS = Array.from({ length: 7 }, (_3, i) => [_A[i], _D2[i], _D2[i], _R[i], _E[i], _S[i], _S[i]].join(" "));
-var WIZARD_VERSION = true ? "2.3.0" : "?";
+var WIZARD_VERSION = true ? "2.4.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -2136,6 +2136,11 @@ export function noteChange(facts: ChangeFacts): void {
  * \`--headless\` skips both: no prompt (a service has nobody to ask), no screen.
  */
 import { printBanner } from './brand.js';
+// Config only - NOT the server, the store or the database. Those derive keys on
+// import, which is the whole reason this file loads them dynamically below,
+// after the passphrase is resolved. \`config.js\` reads a JSON file and the
+// environment and touches neither.
+import { config } from './config.js';
 import { PassphraseRequiredError, WrongPassphraseError } from './vault.js';
 
 /**
@@ -2310,29 +2315,71 @@ async function resolvePassphrase(): Promise<string | null> {
     // Reported by exactly that partner: "there was no opportunity to set a
     // passphrase". Without this line the only options are guess or search the
     // internet, and the answer is one command.
-    process.stdout.write('\\n  This customer database is encrypted.\\n');
-    process.stdout.write('  If you do not know the passphrase, delete data.db and start\\n');
-    process.stdout.write('  again: it holds your demo roster and test dispatches, nothing\\n');
-    process.stdout.write('  OneAddress needs.\\n\\n');
-    const answer = await ask('  Passphrase to unlock: ');
+    process.stdout.write('\\n  This customer database is encrypted and needs its password.\\n\\n');
+    process.stdout.write('  It is the one you chose on this receiver. It is NOT your Webhook\\n');
+    process.stdout.write('  signing secret, NOT your ECDH private key, and NOT your\\n');
+    process.stdout.write('  OneAddress sign-in.\\n\\n');
+    process.stdout.write('  If you do not have it, delete data.db and start again: it holds\\n');
+    process.stdout.write('  your demo roster and test dispatches, nothing OneAddress needs.\\n\\n');
+    const answer = await ask('  Password to unlock: ');
     return answer || null;
   }
 
-  process.stdout.write('\\n  SET A PASSPHRASE to encrypt your customer records at rest.\\n');
-  process.stdout.write('  It is YOURS. It is not the OneAddress private key, and OneAddress\\n');
-  process.stdout.write('  never sees it and CANNOT RECOVER IT. Lose it and the records in\\n');
-  process.stdout.write('  data.db cannot be read again.\\n');
-  process.stdout.write('  Press Enter to skip and store records unencrypted.\\n\\n');
+  // SAYS WHAT IS BEING ASKED BEFORE IT WARNS ABOUT IT. The first version opened
+  // with SET A PASSPHRASE and four lines of consequence, which reads as an
+  // instruction to produce a passphrase you are assumed to already have - and
+  // this prompt arrives moments after the partner has pasted two real
+  // credentials, so assuming exactly that is the natural reading. Reported as
+  // confusing, and the confusion was ours.
+  //
+  // It therefore leads with the decision, says plainly that the answer is
+  // INVENTED HERE, and names the three secrets it is not, because those are the
+  // three things a partner at this point in setup might reach for.
+  // NOT ASKED IN INBOX MODE, because the honest answer to "protect your customer
+  // records" is that there are none here: the connector holds them. The
+  // database in this mode carries dispatch ciphertext - already encrypted to a
+  // key this process does not have - and a queue of dispatch ids. Asking anyway
+  // is the confusing-prompt problem twice over: a question about data that is
+  // absent, put to somebody who has just been told this receiver cannot read
+  // anything.
+  //
+  // The UNLOCK branch above is deliberately NOT skipped. A database encrypted
+  // while the receiver ran write-through is still encrypted after a switch to
+  // inbox, and skipping the question there would refuse to open a file whose
+  // owner has the password.
+  if (config.mode === 'inbox') {
+    process.stdout.write('\\n  No password needed: in inbox mode this receiver holds no customer records.\\n');
+    process.stdout.write('  Your connector holds them, and the key.\\n\\n');
+    return null;
+  }
+
+  process.stdout.write('\\n  \u2500\u2500 Protect this receiver\\'s customer database? \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\\n\\n');
+  process.stdout.write('  MAKE UP A NEW PASSWORD now. You are NOT being asked for anything\\n');
+  process.stdout.write('  you already have: not your Webhook signing secret, not your ECDH\\n');
+  process.stdout.write('  private key, not your OneAddress sign-in. This one is invented\\n');
+  process.stdout.write('  here and used only on this machine.\\n\\n');
+  process.stdout.write('  It encrypts the customer records this receiver keeps in data.db.\\n');
+  process.stdout.write('  OneAddress never sees it and cannot reset it, so if you lose it\\n');
+  process.stdout.write('  those records cannot be read again.\\n\\n');
+  process.stdout.write('  OPTIONAL. Press Enter to skip and leave the database readable.\\n');
+  // ACCURATE ABOUT "LATER", because the obvious reading is wrong. Setting a
+  // password afterwards works and the receiver reports itself encrypted, but
+  // rows written before it stay in the clear until something rewrites them -
+  // confirmed by finding a seeded customer name in the database file after
+  // exactly that sequence.
+  process.stdout.write('  You can set one later with ONEADDRESS_DB_PASSPHRASE, but records\\n');
+  process.stdout.write('  written before then stay readable until they change.\\n\\n');
 
   for (;;) {
-    const first = await ask('  New passphrase: ');
+    const first = await ask('  New password (or Enter to skip): ');
     if (!first) {
-      process.stdout.write('  Continuing WITHOUT encryption.\\n\\n');
+      process.stdout.write('  Continuing WITHOUT encryption: anyone who can read data.db can\\n');
+      process.stdout.write('  read your customer records.\\n\\n');
       return null;
     }
-    const again = await ask('  Confirm passphrase: ');
+    const again = await ask('  Type it again: ');
     if (first === again) {
-      process.stdout.write('  Passphrase set. Keep it somewhere you will still have it.\\n\\n');
+      process.stdout.write('  Password set. Keep it somewhere you will still have it.\\n\\n');
       return first;
     }
     process.stdout.write('  Those do not match. Try again.\\n\\n');
@@ -2471,6 +2518,22 @@ import type {
  * if anything awaited between the set and the read, which is why they are
  * adjacent and why this comment exists.
  */
+/**
+ * The connector could not be reached, so the question was never answered.
+ *
+ * A THROW RATHER THAN A VERDICT, because every value this function can return
+ * is a statement about the customer's record and none of them means "we could
+ * not ask". The handler turns this into a non-2xx, which the relay already
+ * classifies as \`unreachable\` and shows the consumer as a transient network
+ * problem rather than as a missing account.
+ */
+export class ConnectorUnreachableError extends Error {
+  constructor(public readonly kind: string) {
+    super(\`the connector could not be reached to answer \${kind}\`);
+    this.name = 'ConnectorUnreachableError';
+  }
+}
+
 let currentRawBody = '';
 
 export function setCurrentRawBody(raw: string): void {
@@ -2496,14 +2559,26 @@ export const connectorStore = {
   ): Promise<AccountVerdict> {
     const answer = await askConnector('account.verify', currentRawBody);
     if (!answer.reached) {
-      // NEVER GUESSED. A fabricated match authorises a stranger's address onto
-      // a customer's account. \`no_account\` is the safe answer and stops the
-      // consumer before they pay, which is the trade this design accepted.
+      // NEVER GUESSED: a fabricated match authorises a stranger's address onto
+      // a customer's account.
+      //
+      // BUT NOT \`no_account\` EITHER, which is what this returned. That is a
+      // POSITIVE CLAIM - the consumer is shown "\u2717 No account found / This
+      // service couldn't find an account with these details" and goes off to
+      // re-check an account number that was correct all along, or concludes
+      // they have no account with a provider they do.
+      //
+      // The trade was accepted for its safety, and the safety is real. What was
+      // missed is that it is available WITHOUT the false claim: the relay
+      // already classifies a failed check as \`unreachable\` and tells the
+      // consumer "we couldn't reach this service just now". That stops them
+      // before they pay AND is true. Throwing gets us there, because a
+      // non-2xx is exactly what the relay reads as unreachable.
       report.warn(
         \`[connector] account check for \${accountNumber ?? '(none)'} could not be answered; \` +
-        'refusing rather than guessing',
+        'reporting the service as unreachable rather than claiming no account exists',
       );
-      return 'no_account';
+      throw new ConnectorUnreachableError('account.verify');
     }
     const status = verdictOf(answer.body, 'status');
     if (status === 'match' || status === 'no_match' || status === 'no_account') return status;
@@ -2513,7 +2588,9 @@ export const connectorStore = {
 
   async verifyAddress(_customer: Customer, _incoming: Address): Promise<VerifyResult> {
     const answer = await askConnector('address.verify', currentRawBody);
-    if (!answer.reached) return 'not_found';
+    // Same reasoning as \`verifyAccount\`: \`not_found\` is a claim about the
+    // customer's record, and "we could not ask" is not that claim.
+    if (!answer.reached) throw new ConnectorUnreachableError('address.verify');
     const result = verdictOf(answer.body, 'result');
     if (result === 'match' || result === 'mismatch' || result === 'not_found') return result;
     report.warn(\`[connector] address.verify answered "\${result ?? '(nothing)'}", which is not a result\`);
@@ -4177,6 +4254,7 @@ export interface CustomerStore {
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { report } from './report.js';
+import { config } from './config.js';
 import db, { accountKey, dec, enc, encrypted, ensureColumn, isEncrypted, once } from './db.js';
 import type {
   AccountVerdict,
@@ -4356,8 +4434,30 @@ function loadRoster(): RosterEntry[] {
   }
 }
 
-const ROSTER = loadRoster();
-{
+/**
+ * IN INBOX MODE NOTHING IS SEEDED, and that is a privacy fix rather than a
+ * saving.
+ *
+ * This block runs on IMPORT, and \`server.ts\` imports this module in both modes
+ * because it picks the store at runtime. So an inbox receiver - the process that
+ * exists specifically so it cannot read what it holds - was writing a full
+ * customer roster to its own database on startup: names, account numbers and
+ * the address on file for each, in the clear.
+ *
+ * The dispatches were never the leak. Those are stored as the ciphertext they
+ * arrived as, and an end-to-end run confirms the new address appears nowhere in
+ * the receiver's database file. The ROSTER was, and it was there before a
+ * single dispatch arrived. Found by searching the receiver's database bytes for
+ * a customer name after that run, which is the only check that would have found
+ * it: every other one asks the receiver what it thinks it is holding.
+ *
+ * In inbox mode the connector owns the roster and answers every account
+ * question over the loopback channel, so the receiver needs none of it.
+ */
+const ROSTER = config.mode === 'inbox' ? [] : loadRoster();
+if (config.mode === 'inbox') {
+  report.info('[store] no roster held: in inbox mode your connector owns customer records');
+} else {
   const upsert = db.prepare(\`
     INSERT INTO customers (account_key, account_number, name, address)
     VALUES ($account_key, $account_number, $name, $address)
@@ -4623,7 +4723,7 @@ import {
 // exporting a \`CustomerStore\` (see src/customer-store.ts) and nothing else in
 // the protocol layer changes.
 import { store as writeThroughStore } from './store.js';
-import { connectorStore, setCurrentRawBody } from './connector-store.js';
+import { ConnectorUnreachableError, connectorStore, setCurrentRawBody } from './connector-store.js';
 import { noteChange } from './tui.js';
 import { config } from './config.js';
 import { safeOneAddressCallbackUrl } from './callback-url.js';
@@ -4761,12 +4861,22 @@ report.info(
 // lock out every install that has never set a passphrase - but choosing it by
 // not being asked is not a choice, so the absence is stated as loudly as the
 // presence.
+//
+// AND IN INBOX MODE IT SAYS SOMETHING ELSE, for the same reason the keys line
+// above does. There are no customer records in this mode - the connector holds
+// them - so "Customer records are readable by anyone who can read the file" was
+// alarming about data that is not here, and sent the partner to set a passphrase
+// protecting nothing. \`connectorStore.encrypted\` was already hardcoded false
+// with a comment saying exactly that; this line had simply never read it.
 report.info(
-  store.encrypted
-    ? \`[startup] store: \${store.name} (encrypted at rest)\`
-    : \`[startup] store: \${store.name} \u2014 NOT ENCRYPTED AT REST. \` +
-      'Customer records are readable by anyone who can read the file. ' +
-      'Set ONEADDRESS_DB_PASSPHRASE, or run \`npm start\` in a terminal to be asked.',
+  config.mode === 'inbox'
+    ? \`[startup] store: \${store.name} \u2014 no customer records here by design. This database holds \` +
+      'dispatch ciphertext your connector decrypts, and the confirm queue.'
+    : store.encrypted
+      ? \`[startup] store: \${store.name} (encrypted at rest)\`
+      : \`[startup] store: \${store.name} \u2014 NOT ENCRYPTED AT REST. \` +
+        'Customer records are readable by anyone who can read the file. ' +
+        'Set ONEADDRESS_DB_PASSPHRASE, or run \`npm start\` in a terminal to be asked.',
 );
 
 // In-memory dedup cache. Records a dispatch id only once it has been fully
@@ -4806,11 +4916,17 @@ async function confirmToOneAddress(dispatchId: number, status: ConfirmStatus): P
   // and it drops non-numeric dispatch ids, so by the time a row is drained it
   // is a real dispatch. Keeping a second copy of that rule would mean a probe
   // could be queued forever and silently skipped on every drain.
+  // REPORTED, not "Applied". The note is fixed text sent with EVERY confirm,
+  // including \`failed\` ones - so a dispatch the connector could not open, or
+  // one refused because the account reference matched nobody, arrived at
+  // OneAddress reading "Applied by the OneAddress webhook receiver". That is
+  // read by whoever is working out what happened, and it said the opposite of
+  // \`status\` sitting beside it.
   const bodyStr = JSON.stringify({
     dispatch_id: dispatchId,
     partner_id:  PARTNER_ID,
     status,
-    note:        'Applied by the OneAddress webhook receiver',
+    note:        'Reported by the OneAddress webhook receiver',
   });
   const ts  = String(Math.floor(Date.now() / 1000));
   const sig = createHmac('sha256', CONFIRM_SECRET).update(\`\${ts}.\${bodyStr}\`).digest('hex');
@@ -4961,7 +5077,19 @@ app.post('/webhook', async (req: Request, res: Response) => {
     // and the customer records, so it answers. \`connectorStore\` sends the raw
     // body; the arguments below are the contract's shape, not its source.
     if (config.mode === 'inbox') {
-      const status = await store.verifyAccount(null, '', []);
+      let status: Awaited<ReturnType<typeof store.verifyAccount>>;
+      try {
+        status = await store.verifyAccount(null, '', []);
+      } catch (err) {
+        // 503 RATHER THAN A VERDICT. Every verdict is a claim about the
+        // customer's record; "the connector is down" is not one of them. A
+        // non-2xx is what OneAddress reads as \`unreachable\`, which the consumer
+        // sees as a transient network problem instead of "no account found".
+        if (err instanceof ConnectorUnreachableError) {
+          return res.status(503).json({ ok: false, error: 'connector_unreachable' });
+        }
+        throw err;
+      }
       report.info(\`[webhook] account.verify \u2192 \${status} (answered by the connector)\`);
       return res.status(200).json({ status });
     }
@@ -5090,7 +5218,17 @@ app.post('/webhook', async (req: Request, res: Response) => {
   if (config.mode === 'inbox' && event === 'address.verify') {
     // The contract's arguments, not its source: \`connectorStore\` sends the raw
     // body it was parked with and ignores these.
-    const result = await store.verifyAddress({ email: null, name: '' }, {});
+    let result: Awaited<ReturnType<typeof store.verifyAddress>>;
+    try {
+      result = await store.verifyAddress({ email: null, name: '' }, {});
+    } catch (err) {
+      // As above, and the callback is deliberately NOT posted: a verdict posted
+      // here would be a claim about a record nobody read.
+      if (err instanceof ConnectorUnreachableError) {
+        return res.status(503).json({ ok: false, error: 'connector_unreachable' });
+      }
+      throw err;
+    }
     report.info(\`[webhook] address.verify \u2192 \${result} (answered by the connector)\`);
     const refused = await postVerifyVerdict(result);
     if (refused) return refused;
@@ -5554,6 +5692,7 @@ export const PARTNER_NAME = process.env.PARTNER_NAME?.trim() || 'Your receiver';
 import 'dotenv/config';
 import { createPrivateKey, createPublicKey } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 
 const secret    = process.env.WEBHOOK_SECRET          ?? '';
 const partnerId = process.env.PARTNER_ID              ?? '%%PARTNER_ID%%';
@@ -5561,21 +5700,73 @@ const keyPem    = (process.env.PARTNER_PRIVATE_KEY_PEM ?? '').replace(/\\\\n/g,
 const port      = process.env.PORT ?? '3001';
 const targetUrl = process.argv[2] ?? \`http://localhost:\${port}/webhook\`;
 
-if (!secret || !partnerId || !keyPem) {
-  console.error('[test] Missing required env vars. Check your .env file.');
+/**
+ * Which shape of receiver is this?
+ *
+ * Read from the same config file the server reads, so the two cannot disagree.
+ * An inbox receiver holds NO private key - that is the property it exists for -
+ * so this runner used to die on its own env gate with "Missing required env
+ * vars. Check your .env file", telling the partner to fix a file that was
+ * exactly as the wizard wrote it. It was never run in that mode.
+ */
+let receiverMode = 'write-through';
+try {
+  const cfg = JSON.parse(readFileSync(new URL('../oneaddress.config.json', import.meta.url), 'utf8'));
+  if (cfg && typeof cfg.mode === 'string') receiverMode = cfg.mode;
+} catch {
+  // No config, or unreadable: treat it as the default, which is what every
+  // scaffold before the mode existed was.
+}
+const isInbox = receiverMode === 'inbox';
+
+if (!secret || !partnerId) {
+  console.error('[test] Missing WEBHOOK_SECRET or PARTNER_ID. Check your .env file.');
   process.exit(1);
 }
 
-let publicKeyB64: string;
-try {
-  const priv = createPrivateKey({ key: keyPem, format: 'pem' });
-  const pub  = createPublicKey(priv);
-  publicKeyB64 = pub.export({ type: 'spki', format: 'der' }).toString('base64');
-} catch (err) {
-  console.error('[test] Failed to derive public key from PARTNER_PRIVATE_KEY_PEM:', err);
+/**
+ * The public key the conformance suite encrypts to.
+ *
+ * Write-through derives it from the private key it already holds. Inbox mode
+ * has no private key to derive from, so it takes the PUBLIC half directly:
+ * a public key is not a secret, and keeping one here does not give this process
+ * the ability to read anything.
+ *
+ * Copy it from partners.oneaddress.io -> My Profile.
+ */
+const publicKeyFromEnv = (process.env.PARTNER_PUBLIC_KEY_B64 ?? '').trim();
+
+if (isInbox && !publicKeyFromEnv) {
+  console.log('[test] Inbox mode: this receiver holds no private key, so the encrypted checks');
+  console.log('[test] cannot be built here. Two ways to run them:');
+  console.log('[test]');
+  console.log('[test]   1. Set PARTNER_PUBLIC_KEY_B64 in .env (copy it from My Profile in the');
+  console.log('[test]      portal). It is a public value and safe to keep on this machine.');
+  console.log('[test]   2. Or run conformance from your connector host, which has the key.');
+  console.log('[test]');
+  console.log('[test] Signing and replay are covered by the wizard\\'s own checks either way.');
+  process.exit(0);
+}
+
+if (!isInbox && !keyPem) {
+  console.error('[test] Missing PARTNER_PRIVATE_KEY_PEM. Check your .env file.');
   process.exit(1);
 }
 
+let publicKeyB64: string;
+if (publicKeyFromEnv) {
+  publicKeyB64 = publicKeyFromEnv;
+} else {
+  try {
+    const priv = createPrivateKey({ key: keyPem, format: 'pem' });
+    const pub  = createPublicKey(priv);
+    publicKeyB64 = pub.export({ type: 'spki', format: 'der' }).toString('base64');
+  } catch (err) {
+    console.error('[test] Failed to derive public key from PARTNER_PRIVATE_KEY_PEM:', err);
+    process.exit(1);
+  }
+}
+
 console.log(\`[test] Running conformance against \${targetUrl}\\n\`);
 
 /**
@@ -5596,9 +5787,14 @@ console.log(\`[test] Running conformance against \${targetUrl}\\n\`);
  * the check would be asking a question your code is not the one answering.
  */
 const verifiesAccountReference =
-  process.env.OA_VERIFIES_ACCOUNT_REFERENCE === '1' ||
-  process.env.OA_VERIFIES_ACCOUNT_REFERENCE === 'true' ||
-  %%VERIFIES_ACCOUNT_REFERENCE%%;
+  // NEVER in inbox mode. The receiver cannot read an account reference there,
+  // so check-14 asks it a question only the connector can answer, and a
+  // correctly built system fails a check it was never the subject of.
+  !isInbox && (
+    process.env.OA_VERIFIES_ACCOUNT_REFERENCE === '1' ||
+    process.env.OA_VERIFIES_ACCOUNT_REFERENCE === 'true' ||
+    %%VERIFIES_ACCOUNT_REFERENCE%%
+  );
 
 const result = spawnSync(
   'npx',
@@ -6310,7 +6506,7 @@ async def _confirm_to_oneaddress(dispatch: str, status: str) -> None:
         "dispatch_id": dispatch_id,
         "partner_id":  PARTNER_ID,
         "status":      status,
-        "note":        "Applied by the OneAddress webhook receiver",
+        "note":        "Reported 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()
@@ -7325,7 +7521,7 @@ public class OneAddressWebhookController {
                 confirmBody.put("dispatch_id", dispatchId);
                 confirmBody.put("partner_id", partnerId);
                 confirmBody.put("status", status);
-                confirmBody.put("note", "Applied by the OneAddress webhook receiver");
+                confirmBody.put("note", "Reported by the OneAddress webhook receiver");
                 String bodyStr = MAPPER.writeValueAsString(confirmBody);
                 String ts = String.valueOf(System.currentTimeMillis() / 1000L);
                 String sig = OneAddressVerifier.sign(ts + "." + bodyStr, confirmSecret);
@@ -8371,7 +8567,7 @@ async Task ConfirmToOneAddress(string oneAddressApi, string confirmSecret, strin
         dispatch_id = dispatchId,
         partner_id  = pid,
         status,
-        note        = "Applied by the OneAddress webhook receiver",
+        note        = "Reported by the OneAddress webhook receiver",
     });
     var ts  = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
     var sig = Convert.ToHexString(
@@ -9473,7 +9669,7 @@ func confirmToOneAddress(oneAddressAPI, confirmSecret, partnerID, dispatch, stat
 		"dispatch_id": dispatchID,
 		"partner_id":  partnerID,
 		"status":      status,
-		"note":        "Applied by the OneAddress webhook receiver",
+		"note":        "Reported by the OneAddress webhook receiver",
 	})
 	bodyStr := string(bodyBytes)
 	ts := strconv.FormatInt(time.Now().Unix(), 10)
@@ -10257,7 +10453,7 @@ function oaConfirmToOneAddress(string $oneAddressApi, string $confirmSecret, str
         'dispatch_id' => (int) $dispatch,
         'partner_id'  => $partnerId,
         'status'      => $status,
-        'note'        => 'Applied by the OneAddress webhook receiver',
+        'note'        => 'Reported by the OneAddress webhook receiver',
     ]);
     $ts  = (string) time();
     $sig = hash_hmac('sha256', $ts . '.' . $bodyStr, $confirmSecret);
@@ -10735,10 +10931,11 @@ npx @oneaddress/conformance test %%WEBHOOK_URL%%
 };
 
 // src/scaffold.ts
-function applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken) {
+function applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken, port) {
   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(
+  const withPort = applyPort(filled, port);
+  if (mode !== "inbox") return withPort;
+  const withReadme = withPort.replace(
     "## Architecture",
     `## Inbox mode
 
@@ -10773,11 +10970,17 @@ hand somebody your customers' addresses.
 CONNECTOR_TOKEN=${connectorToken || generateConnectorToken()}`
   );
 }
+function applyPort(content, port) {
+  if (!Number.isInteger(port) || port === DEFAULT_PORT) return content;
+  return content.replace(/^PORT=\d+$/m, `PORT=${port}`);
+}
+var DEFAULT_PORT = 3001;
+var RESERVED_PORTS = [3002, 3003];
 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", mode = "write-through", connectorToken = "") {
+async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUrl, privateKey = "", verifiesAccountReference = false, oneAddressApi = "https://oneaddress.io", mode = "write-through", connectorToken = "", port = DEFAULT_PORT) {
   const templates = TEMPLATES[platform];
   if (!templates) throw new Error(`Unknown platform: ${platform}`);
   const written = [];
@@ -10787,7 +10990,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, mode, connectorToken);
+    const filled = applyTokens(content, partnerId, webhookSecret, webhookUrl, privateKey, verifiesAccountReference, oneAddressApi, mode, connectorToken, port);
     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") {
@@ -10803,7 +11006,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.3.0" : "dev";
+var PKG_VERSION = true ? "2.4.0" : "dev";
 var REGISTER_URL = "https://partners.oneaddress.io/api/partner/installs";
 function hmacSha256(secret, message) {
   return (0, import_node_crypto2.createHmac)("sha256", secret).update(message).digest("hex");
@@ -11054,15 +11257,17 @@ Timed out after 5 minutes.`.trim(),
 
 // src/autostart.ts
 var import_node_child_process2 = require("child_process");
-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: "mvn", args: ["spring-boot:run"] }
-  // no mvnw wrapper is scaffolded
-};
+function commandsFor(port) {
+  return {
+    "ts-node": { cmd: "npx", args: ["tsx", "src/server.ts"] },
+    "python": { cmd: "uvicorn", args: ["app:app", "--port", String(port)] },
+    "go-http": { cmd: "go", args: ["run", "."] },
+    "php-laravel": { cmd: "php", args: ["artisan", "serve", `--port=${port}`] },
+    "csharp-aspnet": { cmd: "dotnet", args: ["run"] },
+    "java-spring": { cmd: "mvn", args: ["spring-boot:run"] }
+    // no mvnw wrapper is scaffolded
+  };
+}
 var DASHBOARD_COMMANDS = {
   "ts-node": { cmd: "npx", args: ["tsx", "src/index.ts"] }
 };
@@ -11164,13 +11369,13 @@ async function pollHealth(port, timeoutMs) {
   return false;
 }
 async function startServer(platform, outputDir, port = 3001, secrets = {}) {
-  const spec = COMMANDS2[platform];
+  const spec = commandsFor(port)[platform];
   if (!spec) {
     return { ok: false, output: `No start command defined for platform: ${platform}`, manualCommand: "" };
   }
   serverOutput = "";
   const manualCommand = `cd ${outputDir} && ${spec.cmd} ${spec.args.join(" ")}`;
-  serverProcess = spawnReceiver(spec, outputDir, ["ignore", "pipe", "pipe"], secrets);
+  serverProcess = spawnReceiver(spec, outputDir, ["ignore", "pipe", "pipe"], { ...secrets, PORT: String(port) });
   serverProcess.stdout?.on("data", (d3) => {
     serverOutput += d3.toString();
   });
@@ -11217,7 +11422,7 @@ async function handOverTerminal(platform, outputDir, port, secrets = {}) {
     }
   }
   process.stdin.pause();
-  const child = spawnReceiver(spec, outputDir, "inherit", secrets);
+  const child = spawnReceiver(spec, outputDir, "inherit", { ...secrets, PORT: String(port) });
   serverProcess = child;
   return new Promise((resolve2) => {
     child.once("error", (err) => {
@@ -11747,6 +11952,25 @@ function validatePrivateKey(pem) {
 function stripControlChars(line) {
   return line.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, "");
 }
+function validatePortChoice(v2) {
+  const raw = (v2 ?? "").trim();
+  if (!raw) return void 0;
+  if (!/^\d+$/.test(raw)) return `Enter a port number, or leave blank for ${DEFAULT_PORT}`;
+  const n = Number(raw);
+  if (n < 1024 || n > 65535) return "Choose a port between 1024 and 65535";
+  if (RESERVED_PORTS.includes(n)) {
+    return `${n} is used by the connector channel. Choose another port.`;
+  }
+  return void 0;
+}
+function childEnvForMode(mode, v2) {
+  return {
+    WEBHOOK_SECRET: v2.secret,
+    PARTNER_ID: v2.partnerId,
+    VERIFIES_ACCOUNT_REFERENCE: String(v2.verifiesAccountReference),
+    ...mode === "inbox" ? { CONNECTOR_TOKEN: v2.connectorToken } : { PARTNER_PRIVATE_KEY_PEM: v2.privateKey }
+  };
+}
 async function main() {
   printHeader();
   Ie("OneAddress Partner Setup");
@@ -11796,23 +12020,6 @@ async function main() {
       "The portal rejected that secret (HTTP 401): it does not match the one on your profile.\nRegenerate it at partners.oneaddress.io -> Webhook -> Webhook signing secret\n(use Revoke and regenerate, not Rotate), copy the value shown once, and paste it here."
     );
   }
-  const privateKeyRaw = await he({
-    message: "Your ECDH Private Key",
-    placeholder: "Paste the base64 key body from My Profile, or enter a path to the .pem file",
-    validate: (v2) => {
-      if (!v2.trim()) return "Private key is required";
-      const { pem, error } = normalisePrivateKey(v2);
-      if (error) return error;
-      return validatePrivateKey(pem);
-    }
-  });
-  assertNotCancelled(privateKeyRaw);
-  const normalised = normalisePrivateKey(privateKeyRaw.trim());
-  if (normalised.error) {
-    xe(`Private key parse failed unexpectedly: ${normalised.error}`);
-    process.exit(1);
-  }
-  const privateKey = normalised.pem;
   const platform = await ve({
     message: "Which platform?",
     options: [
@@ -11829,29 +12036,6 @@ async function main() {
     ]
   });
   assertNotCancelled(platform);
-  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_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
-    });
-    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) => {
-    accountRefReason = r2;
-  });
-  const verifiesAccountReference = accountRefDeclaration === true;
   const modeChoice = platform !== "ts-node" ? "write-through" : await ve({
     message: "How should this receiver handle updates?",
     options: [
@@ -11885,6 +12069,69 @@ not your webhook secret and not your confirm secret, because those are shared wi
 OneAddress and a leak of either must not also hand somebody your customers' addresses.`
     );
   }
+  let privateKey = "";
+  if (receiverMode === "inbox") {
+    M2.info(
+      "No private key is collected for an inbox receiver. It belongs in your connector,\nwhich is the only process that decrypts. This one is meant never to hold one, and\nit refuses to start if it finds one in its environment."
+    );
+  } else {
+    const privateKeyRaw = await he({
+      message: "Your ECDH Private Key",
+      placeholder: "Paste the base64 key body from My Profile, or enter a path to the .pem file",
+      validate: (v2) => {
+        if (!v2.trim()) return "Private key is required";
+        const { pem, error } = normalisePrivateKey(v2);
+        if (error) return error;
+        return validatePrivateKey(pem);
+      }
+    });
+    assertNotCancelled(privateKeyRaw);
+    const normalised = normalisePrivateKey(privateKeyRaw.trim());
+    if (normalised.error) {
+      xe(`Private key parse failed unexpectedly: ${normalised.error}`);
+      process.exit(1);
+    }
+    privateKey = normalised.pem;
+  }
+  const portAnswer = await he({
+    message: "Which port should the receiver listen on?",
+    placeholder: String(DEFAULT_PORT),
+    defaultValue: String(DEFAULT_PORT),
+    initialValue: String(DEFAULT_PORT),
+    validate: validatePortChoice
+  });
+  assertNotCancelled(portAnswer);
+  const chosenPort = Number(String(portAnswer).trim() || DEFAULT_PORT);
+  if (!await isPortFree(chosenPort)) {
+    M2.warn(
+      `Port ${chosenPort} looks busy. Free it (lsof -i :${chosenPort} on macOS or Linux,
+netstat -ano | findstr :${chosenPort} on Windows), or change PORT in the generated
+.env afterwards. Setup will carry on either way.`
+    );
+  }
+  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_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
+    });
+    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) => {
+    accountRefReason = r2;
+  });
+  const verifiesAccountReference = accountRefDeclaration === true;
   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."
@@ -11905,7 +12152,8 @@ OneAddress and a leak of either must not also hand somebody your customers' addr
       verifiesAccountReference,
       void 0,
       receiverMode,
-      connectorToken
+      connectorToken,
+      chosenPort
     );
     s1.stop(`Scaffolded ${written.length} files in ${outDir}`);
     for (const f of written) M2.success(`  ${f}`);
@@ -11942,22 +12190,18 @@ OneAddress and a leak of either must not also hand somebody your customers' addr
     }
     if (choice === "skip") break;
   }
-  const SERVER_PORT = 3001;
-  const portFree = await isPortFree(SERVER_PORT);
-  if (!portFree) {
-    M2.warn(
-      `Port ${SERVER_PORT} is in use. Free it (lsof -i :${SERVER_PORT} on macOS/Linux, netstat -ano | findstr :${SERVER_PORT} on Windows) and re-run the wizard, or change the PORT in ${outDir}/.env after setup completes.`
-    );
-  }
+  const childSecrets = childEnvForMode(receiverMode, {
+    secret,
+    partnerId: pid,
+    verifiesAccountReference,
+    privateKey,
+    connectorToken
+  });
+  const SERVER_PORT = chosenPort;
   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, {
-    WEBHOOK_SECRET: secret,
-    PARTNER_ID: pid,
-    PARTNER_PRIVATE_KEY_PEM: privateKey,
-    VERIFIES_ACCOUNT_REFERENCE: String(verifiesAccountReference)
-  });
+  const start = await startServer(platform, outDir, SERVER_PORT, childSecrets);
   let serverRunning = false;
   if (start.ok) {
     s3.stop(`Server is healthy on port ${SERVER_PORT}`);
@@ -12031,7 +12275,7 @@ Continuing will overwrite it.`
       s4.start("Starting Cloudflare Tunnel");
       onCleanup(stopTunnel);
       try {
-        let tunnel = await startTunnel(3001);
+        let tunnel = await startTunnel(SERVER_PORT);
         webhookUrl = `${tunnel.url}/webhook`;
         tunnelBase = tunnel.url;
         s4.stop(`Tunnel active: ${tunnel.url}`);
@@ -12044,7 +12288,7 @@ Continuing will overwrite it.`
         if (!webhookReady) {
           s4b.stop("First tunnel is slow to route, trying a fresh one");
           stopTunnel();
-          tunnel = await startTunnel(3001);
+          tunnel = await startTunnel(SERVER_PORT);
           webhookUrl = `${tunnel.url}/webhook`;
           tunnelBase = tunnel.url;
           const s4c = Y2();
@@ -12057,7 +12301,7 @@ Continuing will overwrite it.`
         if (!webhookReady) {
           M2.warn(
             `The tunnel edge is still not routing after a retry. This is almost always
-one of two things, and neither is your server (it is running on :3001):
+one of two things, and neither is your server (it is running on :${SERVER_PORT}):
   1. Open ${tunnel.url}/health in a browser. If it never loads, your network
      is blocking cloudflared and no wait will fix it, so try a different network.
   2. The tunnel only lives while this wizard runs, so keep this window open.`
@@ -12067,7 +12311,8 @@ one of two things, and neither is your server (it is running on :3001):
         s4.stop("Tunnel setup failed");
         M2.warn(`Could not start tunnel: ${err instanceof Error ? err.message : String(err)}`);
         M2.warn(
-          "To get a public URL manually, try: npx cloudflared tunnel --url http://localhost:3001\nOr deploy to any server and set the URL in partners.oneaddress.io \u2192 My Profile."
+          `To get a public URL manually, try: npx cloudflared tunnel --url http://localhost:${SERVER_PORT}
+Or deploy to any server and set the URL in partners.oneaddress.io \u2192 My Profile.`
         );
       }
     }
@@ -12105,7 +12350,7 @@ one of two things, and neither is your server (it is running on :3001):
     if (!webhookReady) {
       M2.warn(
         `Skipping the conformance checks: the tunnel edge is not routing.
-Your server is fine, it is running on :3001. This is either your network
+Your server is fine, it is running on :${SERVER_PORT}. This is either your network
 blocking cloudflared (open ${tunnelBase}/health in a browser to check) or the
 tunnel needing this wizard to stay open. Re-run once that URL loads in a browser.`
       );
@@ -12116,18 +12361,28 @@ tunnel needing this wizard to stay open. Re-run once that URL loads in a browser
       await new Promise((r2) => setTimeout(r2, 200));
       s6.stop("Conformance checks:");
       await runConformance(webhookUrl, pid, secret);
-      await runDecryptCheck(secret, pid);
-      if (verifiesAccountReference) {
+      if (receiverMode === "inbox") {
+        M2.info(
+          "Decrypt check skipped: this receiver holds no private key, which is what inbox\nmode is for. Your connector is the process that decrypts, so prove the key there:\nstart it against this receiver and confirm it draws and applies a dispatch."
+        );
+      } else {
+        await runDecryptCheck(secret, pid);
+      }
+      if (verifiesAccountReference && receiverMode !== "inbox") {
         M2.info(
           "You have declared that your receiver matches the account reference itself.\nRun `npm test` to include check-14, which sends an account reference that matches\nnothing and fails a receiver that reports it as applied. The three checks above\ncover signing and replay only."
         );
+      } else if (verifiesAccountReference) {
+        M2.info(
+          "You have declared that your receiver matches the account reference itself.\nIn inbox mode your CONNECTOR does that, before it applies anything, and it\nrefuses a dispatch whose reference matches none of your records. The three checks\nabove cover signing and replay only."
+        );
       }
     }
   }
   const summary = [
     `Partner ID:   ${pid}`,
     `Webhook URL:  ${webhookUrl || "(not set \u2014 update in portal)"}`,
-    `Server port:  3001`,
+    `Server port:  ${SERVER_PORT}`,
     `Files in:     ${outDir}`
   ].join("\n");
   const nextSteps = [
@@ -12142,12 +12397,7 @@ tunnel needing this wizard to stay open. Re-run once that URL loads in a browser
   if (serverRunning) {
     const openDashboard = platformHasDashboard(platform) ? await ye({ message: "Open the receiver dashboard now?", initialValue: true }) : false;
     if (openDashboard === true) {
-      const handover = await handOverTerminal(platform, outDir, SERVER_PORT, {
-        WEBHOOK_SECRET: secret,
-        PARTNER_ID: pid,
-        PARTNER_PRIVATE_KEY_PEM: privateKey,
-        VERIFIES_ACCOUNT_REFERENCE: String(verifiesAccountReference)
-      });
+      const handover = await handOverTerminal(platform, outDir, SERVER_PORT, childSecrets);
       if (!handover.ok) {
         M2.warn(
           `${handover.reason ?? "The dashboard could not start."}
@@ -12161,7 +12411,7 @@ Your receiver is set up and working. Start it yourself with:
     console.log("");
     console.log(`  ${DIM2}\u250C${"\u2500".repeat(BOX_WIDTH)}\u2510${R3}`);
     for (const inner of [
-      `  ${GRN}\u25C8${R3}  ${CRM2}Server live${R3} ${MID2}on http://localhost:3001/webhook${R3}`,
+      `  ${GRN}\u25C8${R3}  ${CRM2}Server live${R3} ${MID2}on http://localhost:${SERVER_PORT}/webhook${R3}`,
       `  ${AMB2}\u25C8${R3}  ${MID2}Edit ${CRM2}src/store.ts${R3} ${MID2}to wire your database${R3}`,
       `     ${MID2}Press Ctrl+C to stop the server and exit.${R3}`,
       ...platformHasDashboard(platform) ? [`     ${MID2}Run ${CRM2}npm start${R3} ${MID2}here any time for the dashboard.${R3}`] : []

package/package.json

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