@oneaddress/setup 2.0.0 → 2.1.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.0.0" : "?";
+var WIZARD_VERSION = true ? "2.1.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -1598,8 +1598,8 @@ import { formatLine, report, type ReportLine } from './report.js';
 import { allCustomers, customerCount, storeEncrypted, type StoredCustomer } from './store.js';
 
 /** blessed takes colours as strings; these mirror the site's palette. */
-const AMBER = HEX.amber;
-const CREAM = HEX.cream;
+const AMBER = HEX.amber.toLowerCase();
+const CREAM = HEX.cream.toLowerCase();
 const DIM = '#8a7f6a';
 
 /** Escape blessed's tag syntax so a customer's name can never inject markup. */
@@ -1623,6 +1623,14 @@ export function startDashboard({ partnerName, port, onQuit }: TuiOptions): void
     smartCSR: true,
     title: \`\${partnerName} \u2014 OneAddress receiver\`,
     fullUnicode: true,
+    // WITHOUT THIS THE BRAND COMES OUT RED ON WINDOWS. blessed resolves a hex
+    // colour against whatever palette it believes the terminal has, and it
+    // infers that from TERM, which Windows does not set. With no TERM it
+    // assumes a tiny palette and snaps #e0a248 to the nearest thing it thinks
+    // exists, which is red. Windows Terminal and PowerShell both do 256 colours
+    // and more, so naming the capability is simply telling it the truth.
+    // Anything that DOES set TERM keeps its own value.
+    terminal: process.env.TERM || 'xterm-256color',
   });
 
   // \u2500\u2500 Masthead \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
@@ -1808,9 +1816,88 @@ export function notePreviousAddress(prev: Record<string, unknown>): void {
 import { printBanner } from './brand.js';
 import { WrongPassphraseError } from './vault.js';
 
+/**
+ * No dashboard without a terminal to draw it in.
+ *
+ * FOUND THE FIRST TIME A PARTNER RAN THIS, 14 Sep 2026. The setup wizard starts
+ * your receiver for you as a CHILD PROCESS with its output piped, so there is no
+ * TTY. The passphrase prompt already handled that correctly by skipping, but the
+ * dashboard went ahead and started anyway, drawing into a pipe: the server ran
+ * fine and conformance passed while the UI rendered to nobody.
+ *
+ * \`process.stdout.isTTY\` is the honest test. It is false under the wizard's
+ * autostart, under a systemd or pm2 unit, in CI, and behind any pipe \u2014 every
+ * case where a full-screen UI is the wrong answer and plain log lines are the
+ * right one. Run \`npm start\` yourself in a real terminal and you get the
+ * dashboard; anything else gets readable output instead of escape codes.
+ */
 const headless =
   process.argv.includes('--headless') ||
-  process.env.ONEADDRESS_HEADLESS === '1';
+  process.env.ONEADDRESS_HEADLESS === '1' ||
+  !process.stdout.isTTY;
+
+/**
+ * Has this database already been locked?
+ *
+ * Asked BEFORE the passphrase, and without one, so the prompt can say which of
+ * two completely different things it is doing. \`db_meta.verifier\` is written the
+ * first time a passphrase is set, so its presence is the whole answer.
+ *
+ * Read through its own connection rather than importing \`db.ts\`, which derives
+ * its keys the moment it is imported and would therefore have to run BEFORE we
+ * know what to ask for.
+ */
+async function databaseIsLocked(): Promise<boolean> {
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const { join } = await import('node:path');
+    const path = process.env.DB_PATH ?? join(process.cwd(), 'data.db');
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+      const row = db
+        .prepare("SELECT value FROM db_meta WHERE key = 'verifier'")
+        .get() as { value?: string } | undefined;
+      return Boolean(row?.value);
+    } finally {
+      db.close();
+    }
+  } catch {
+    // No file yet, or no db_meta table yet. Either way: not locked.
+    return false;
+  }
+}
+
+/**
+ * Ask for a passphrase without echoing it to the screen.
+ *
+ * A passphrase typed in clear on a shared screen, in a screen-share, or into a
+ * terminal that keeps scrollback is not much of a secret. readline echoes by
+ * default, so its output hook is replaced for the duration of the question.
+ *
+ * Degrades to a visible prompt rather than failing: on a terminal where the
+ * hook is not available, being asked in the clear beats not being asked.
+ */
+async function ask(prompt: string): Promise<string> {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  const hooked = rl as unknown as { _writeToOutput?: (s: string) => void };
+  const original = hooked._writeToOutput;
+  try {
+    hooked._writeToOutput = function (chunk: string): void {
+      // Echo the prompt itself, mask everything the user types.
+      if (chunk.includes(prompt)) process.stdout.write(chunk);
+      else process.stdout.write('*');
+    };
+  } catch { /* keep the visible prompt */ }
+  try {
+    const answer = await rl.question(prompt);
+    process.stdout.write('\\n');
+    return answer.trim();
+  } finally {
+    if (original) hooked._writeToOutput = original;
+    rl.close();
+  }
+}
 
 /**
  * Where the at-rest passphrase comes from.
@@ -1820,6 +1907,12 @@ const headless =
  * headless deployment or a piped stdin has nobody to answer, and blocking on a
  * prompt nobody can see is the worst of the three outcomes.
  *
+ * SETTING AND UNLOCKING ARE DIFFERENT QUESTIONS AND ARE ASKED DIFFERENTLY.
+ * Until 14 Sep 2026 both said the same thing, so the first run gave no way to
+ * tell whether a passphrase was being created or checked, and no confirmation.
+ * Getting a new passphrase wrong twice in agreement is recoverable; getting it
+ * wrong once, silently, means a database nothing can open.
+ *
  * An empty answer is legitimate, not a failure. It runs the database in the
  * clear, which is what this receiver did before at-rest encryption existed, and
  * the dashboard shows that state in red rather than letting it pass unnoticed.
@@ -1827,19 +1920,36 @@ const headless =
 async function resolvePassphrase(): Promise<string | null> {
   const fromEnv = process.env.ONEADDRESS_DB_PASSPHRASE;
   if (fromEnv && fromEnv.trim()) return fromEnv;
+  // Both streams are checked, and they are not the same question: output can be
+  // a pipe while input is still a terminal (\`npm start | tee log\`), and stdin
+  // can be closed while stdout is a terminal. Prompting needs stdin; drawing
+  // needs stdout.
   if (headless || !process.stdin.isTTY) return null;
 
-  const { createInterface } = await import('node:readline/promises');
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    process.stdout.write('  Your customer records can be encrypted at rest.\\n');
-    process.stdout.write('  This passphrase is YOURS. It is not the OneAddress private key,\\n');
-    process.stdout.write('  and OneAddress never sees it and cannot recover it.\\n');
-    process.stdout.write('  Leave blank to store records unencrypted.\\n\\n');
-    const answer = (await rl.question('  Passphrase: ')).trim();
+  if (await databaseIsLocked()) {
+    process.stdout.write('\\n  This customer database is encrypted.\\n\\n');
+    const answer = await ask('  Passphrase to unlock: ');
     return answer || null;
-  } finally {
-    rl.close();
+  }
+
+  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');
+
+  for (;;) {
+    const first = await ask('  New passphrase: ');
+    if (!first) {
+      process.stdout.write('  Continuing WITHOUT encryption.\\n\\n');
+      return null;
+    }
+    const again = await ask('  Confirm passphrase: ');
+    if (first === again) {
+      process.stdout.write('  Passphrase set. Keep it somewhere you will still have it.\\n\\n');
+      return first;
+    }
+    process.stdout.write('  Those do not match. Try again.\\n\\n');
   }
 }
 
@@ -1898,6 +2008,7 @@ main().catch((err) => {
  * 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 { report } from './report.js';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -1947,7 +2058,7 @@ export const config: ReceiverConfig = {
       : (fromFile.verifiesAccountReference ?? DEFAULTS.verifiesAccountReference),
 };
 
-console.log(
+report.info(
   '[config] loaded (oneAddressApi=' + config.oneAddressApi +
   ', verifiesAccountReference=' + config.verifiesAccountReference + ')',
 );
@@ -2005,6 +2116,7 @@ export function safeOneAddressCallbackUrl(raw: string): string | null {
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { report } from './report.js';
 import db, { accountKey, dec, enc, encrypted, once } from './db.js';
 
 export type Address = Record<string, unknown>;
@@ -2049,7 +2161,7 @@ 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}\`);
+    report.info(\`[store] migrated: added column \${table}.\${column}\`);
   }
 }
 ensureColumn('customers', 'address', "TEXT NOT NULL DEFAULT '{}'");
@@ -2134,7 +2246,7 @@ function loadRoster(): RosterEntry[] {
     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.\`);
+    report.warn(\`[store] customers.json not loaded (\${msg}) \u2014 using the built-in demo roster. Edit customers.json to set your customers.\`);
     return DEFAULT_ROSTER;
   }
 }
@@ -2154,7 +2266,7 @@ const ROSTER = loadRoster();
       address:        enc('address', JSON.stringify(c.address)),
     });
   }
-  console.log(\`[store] roster ready (\${ROSTER.length} customers)\`);
+  report.info(\`[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
@@ -2277,13 +2389,13 @@ export type VerifyResult = 'match' | 'mismatch' | 'not_found';
 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 (\${customer.accountNumber || customer.name || '(none)'})\`);
+    report.info(\`[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})\`);
+  report.info(\`[store] verifyAddress \u2192 \${result} (\${row.account_number})\`);
   return result;
 }
 
@@ -2340,7 +2452,7 @@ 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.
-  console.log(\`[store] saved address for \${acct}\${customer.loaRef ? \` (loa_ref \${customer.loaRef})\` : ''}\`);
+  report.info(\`[store] saved address for \${acct}\${customer.loaRef ? \` (loa_ref \${customer.loaRef})\` : ''}\`);
 
   return previous;
 }
@@ -7878,7 +7990,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto = require("crypto");
-var PKG_VERSION = true ? "2.0.0" : "dev";
+var PKG_VERSION = true ? "2.1.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");
@@ -8118,6 +8230,55 @@ var COMMANDS2 = {
 };
 var serverProcess = null;
 var serverOutput = "";
+var PASSTHROUGH_KEYS = [
+  "PATH",
+  // every runtime resolves binaries from PATH
+  "HOME",
+  // pip/npm/composer caches, ~/.m2 for Maven
+  "USERPROFILE",
+  // Windows equivalent of HOME
+  "APPDATA",
+  "LOCALAPPDATA",
+  // Windows config dirs
+  "SystemRoot",
+  "SYSTEMROOT",
+  "ComSpec",
+  "WINDIR",
+  // cmd.exe needs these
+  "TEMP",
+  "TMP",
+  "TMPDIR",
+  // tempdir resolution for tsx/uvicorn
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  // utf-8 in subprocess output
+  "JAVA_HOME",
+  "GOPATH",
+  "GOROOT",
+  // toolchain locations if set
+  "PORT"
+  // partner might override port via .env or shell
+];
+function buildChildEnv(secrets) {
+  const childEnv = {};
+  for (const key of PASSTHROUGH_KEYS) {
+    const v2 = process.env[key];
+    if (typeof v2 === "string") childEnv[key] = v2;
+  }
+  for (const [key, value] of Object.entries(secrets)) {
+    if (value) childEnv[key] = value;
+  }
+  return childEnv;
+}
+function spawnReceiver(spec, outputDir, stdio, secrets) {
+  const isWin = process.platform === "win32";
+  return (0, import_node_child_process2.spawn)(
+    isWin ? "cmd.exe" : spec.cmd,
+    isWin ? ["/c", spec.cmd, ...spec.args] : spec.args,
+    { cwd: outputDir, stdio, detached: false, shell: false, env: buildChildEnv(secrets) }
+  );
+}
 function stopServer() {
   if (serverProcess) {
     try {
@@ -8168,56 +8329,7 @@ async function startServer(platform, outputDir, port = 3001, secrets = {}) {
   }
   serverOutput = "";
   const manualCommand = `cd ${outputDir} && ${spec.cmd} ${spec.args.join(" ")}`;
-  const PASSTHROUGH_KEYS = [
-    "PATH",
-    // every runtime resolves binaries from PATH
-    "HOME",
-    // pip/npm/composer caches, ~/.m2 for Maven
-    "USERPROFILE",
-    // Windows equivalent of HOME
-    "APPDATA",
-    "LOCALAPPDATA",
-    // Windows config dirs
-    "SystemRoot",
-    "SYSTEMROOT",
-    "ComSpec",
-    "WINDIR",
-    // cmd.exe needs these
-    "TEMP",
-    "TMP",
-    "TMPDIR",
-    // tempdir resolution for tsx/uvicorn
-    "LANG",
-    "LC_ALL",
-    "LC_CTYPE",
-    // utf-8 in subprocess output
-    "JAVA_HOME",
-    "GOPATH",
-    "GOROOT",
-    // toolchain locations if set
-    "PORT"
-    // partner might override port via .env or shell
-  ];
-  const childEnv = {};
-  for (const key of PASSTHROUGH_KEYS) {
-    const v2 = process.env[key];
-    if (typeof v2 === "string") childEnv[key] = v2;
-  }
-  for (const [key, value] of Object.entries(secrets)) {
-    if (value) childEnv[key] = value;
-  }
-  const isWin = process.platform === "win32";
-  serverProcess = (0, import_node_child_process2.spawn)(
-    isWin ? "cmd.exe" : spec.cmd,
-    isWin ? ["/c", spec.cmd, ...spec.args] : spec.args,
-    {
-      cwd: outputDir,
-      stdio: ["ignore", "pipe", "pipe"],
-      detached: false,
-      shell: false,
-      env: childEnv
-    }
-  );
+  serverProcess = spawnReceiver(spec, outputDir, ["ignore", "pipe", "pipe"], secrets);
   serverProcess.stdout?.on("data", (d3) => {
     serverOutput += d3.toString();
   });
@@ -8231,6 +8343,49 @@ async function startServer(platform, outputDir, port = 3001, secrets = {}) {
   const ok = await pollHealth(port, 15e3);
   return { ok, output: serverOutput, manualCommand };
 }
+async function waitForPortFree(port, timeoutMs = 8e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await fetch(`http://localhost:${port}/health`, { signal: AbortSignal.timeout(1e3) });
+    } catch {
+      return true;
+    }
+    await new Promise((r2) => setTimeout(r2, 300));
+  }
+  return false;
+}
+async function handOverTerminal(platform, outputDir, port, secrets = {}) {
+  const spec = COMMANDS2[platform];
+  const manualCommand = spec ? `cd ${outputDir} && ${spec.cmd} ${spec.args.join(" ")}` : `cd ${outputDir} && npm start`;
+  if (!spec) return { ok: false, reason: `No start command defined for platform: ${platform}`, manualCommand };
+  stopServer();
+  if (!await waitForPortFree(port)) {
+    return {
+      ok: false,
+      reason: `Port ${port} is still in use, so the dashboard could not take it over.`,
+      manualCommand
+    };
+  }
+  if (process.stdin.isTTY) {
+    try {
+      process.stdin.setRawMode(false);
+    } catch {
+    }
+  }
+  process.stdin.pause();
+  const child = spawnReceiver(spec, outputDir, "inherit", secrets);
+  serverProcess = child;
+  return new Promise((resolve2) => {
+    child.once("error", (err) => {
+      resolve2({ ok: false, reason: err.message, manualCommand });
+    });
+    child.once("exit", () => {
+      serverProcess = null;
+      resolve2({ ok: true, manualCommand });
+    });
+  });
+}
 
 // src/tunnel.ts
 var import_node_child_process3 = require("child_process");
@@ -9098,7 +9253,7 @@ tunnel needing this wizard to stay open. Re-run once that URL loads in a browser
   ].join("\n");
   const nextSteps = [
     "1. Trigger a live event: update your address at oneaddress.io\n   \u2192 src/store.ts will save it to data.db automatically",
-    "2. View your database: open data.db with DB Browser for SQLite\n   (free download at sqlitebrowser.org)",
+    "2. Watch it arrive: the dashboard shows each dispatch and the old-to-new change.\n   Set a passphrase there and data.db is encrypted at rest, which also means\n   DB Browser for SQLite will show you ciphertext rather than addresses.\n   Skip the passphrase and the file stays readable in any SQLite viewer.",
     "3. For production: swap src/store.ts for your real database (Postgres, MySQL, etc.)\n   then deploy and update the webhook URL in the portal",
     "4. Questions? partners.oneaddress.io  or  partners@oneaddress.io"
   ].join("\n\n");
@@ -9106,12 +9261,34 @@ tunnel needing this wizard to stay open. Re-run once that URL loads in a browser
   Me(nextSteps, "Next steps");
   Se("Setup complete! Welcome to the OneAddress Partner Network.");
   if (serverRunning) {
+    const openDashboard = await ye({
+      message: "Open the receiver dashboard now?",
+      initialValue: true
+    });
+    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)
+      });
+      if (!handover.ok) {
+        M2.warn(
+          `${handover.reason ?? "The dashboard could not start."}
+Your receiver is set up and working. Start it yourself with:
+  ${handover.manualCommand}`
+        );
+      }
+      runCleanup();
+      process.exit(0);
+    }
     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}`,
       `  ${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}`
+      `     ${MID2}Press Ctrl+C to stop the server and exit.${R3}`,
+      `     ${MID2}Run ${CRM2}npm start${R3} ${MID2}here any time for the dashboard.${R3}`
     ]) {
       console.log(boxRow(inner, BOX_WIDTH, DIM2, R3));
     }

package/package.json

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