@oneaddress/setup 2.5.0 → 2.6.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.5.0" : "?";
+var WIZARD_VERSION = true ? "2.6.0" : "?";
 function printCompactHeader() {
   const INNER = 42;
   const TOP = fn("\u250C") + dm("\u2500".repeat(INNER)) + fn("\u2510");
@@ -1013,7 +1013,8 @@ data.db-shm
   "oneAddressApi": "%%ONEADDRESS_API%%",
   "verifiesAccountReference": %%VERIFIES_ACCOUNT_REFERENCE%%,
   "mode": "%%RECEIVER_MODE%%",
-  "publicUrl": "%%WEBHOOK_URL%%"
+  "publicUrl": "%%WEBHOOK_URL%%",
+  "exportDir": ""
 }
 `
     },
@@ -1713,7 +1714,8 @@ import { formatLine, report, type ReportLine } from './report.js';
 // reads, with nothing here to change.
 import { store } from './store.js';
 import { pendingConfirmCount } from './confirm-queue.js';
-import { dismissHeld, exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { dismissHeld, drillCount, exportHeld, heldCount, heldSummary } from './quarantine.js';
+import { config } from './config.js';
 import { reachability } from './reachable.js';
 
 /** blessed takes colours as strings; these mirror the site's palette. */
@@ -1874,6 +1876,7 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
     // ciphertext it cannot open; the customers live in the partner's own
     // database, behind their own controls.
     const reach = reachability();
+    const drills = drillCount();
     const vault = inbox
       ? \`{\${AMBER}-fg}{bold}NONE (inbox){/}\`
       : store.encrypted
@@ -1892,6 +1895,11 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       // third state. A receiver with no publicUrl configured cannot answer the
       // question, and a green tick or a red cross would both be inventing an
       // answer. Silence is the honest rendering of "not checked".
+      // DRILLS ARE NAMED, not hidden. A conformance run leaves a trace and the
+      // partner should be able to see it; what it must not do is look like a
+      // fault. Absent when there are none, because a permanent "drills 0" is a
+      // counter for a thing that has not happened.
+      + (drills > 0 ? \`   {\${DIM}-fg}conformance probes{/} {\${CREAM}-fg}\${drills}{/}\` : '')
       + (reach.state === 'unknown'
         ? ''
         : reach.state === 'reachable'
@@ -1939,6 +1947,16 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
 
   /** Shown while a replay is running, so [r] does not look like it did nothing. */
   let replayNote = '';
+  /**
+   * The export confirmation, kept apart from \`replayNote\`.
+   *
+   * They are both one-line notes under the fault panel and they answer
+   * different questions, so sharing a slot means a press of [r] silently wipes
+   * the only place the export path was written down. The PATH is the entire
+   * value of the message: a receiver started from a shortcut or a service
+   * manager has a working directory the partner has never seen.
+   */
+  let exportNote = '';
 
   /**
    * The customer count, refreshed out of band.
@@ -2101,10 +2119,19 @@ export function startDashboard({ partnerName, port, onQuit, onReplay, stats }: T
       return;
     }
     try {
-      const { path, count } = exportHeld(process.cwd());
-      replayNote = \`Exported \${count} to \${path}\`;
+      // NO ARGUMENT. \`exportHeld\` resolves \`config.exportDir\`, then
+      // \`ONEADDRESS_EXPORT_DIR\`, then the working directory, and returns an
+      // ABSOLUTE path. Passing \`process.cwd()\` here is what made the setting
+      // unreachable from the one key that uses it.
+      const { path, count } = exportHeld();
+      exportNote = \`Saved \${count} to \${path}\`;
+      replayNote = '';
     } catch (err) {
-      replayNote = \`Export failed: \${err instanceof Error ? err.message : String(err)}\`;
+      // NAMES THE DIRECTORY IT TRIED. "EACCES" on its own sends a partner to
+      // search for a file that was never written.
+      exportNote = \`Export FAILED writing to \${config.exportDir || process.cwd()}: \` +
+        \`\${err instanceof Error ? err.message : String(err)}\`;
+      replayNote = '';
     }
     redraw();
   });
@@ -3367,8 +3394,9 @@ export function resetTally(): void {
 import db, { ensureColumn, parseStoredTime } from './db.js';
 import { report } from './report.js';
 import { createHash } from 'node:crypto';
-import { writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { config } from './config.js';
 
 /**
  * Why a dispatch could not be applied. Shown verbatim on the dashboard.
@@ -3458,6 +3486,43 @@ ensureColumn('quarantine', 'attempts', 'INTEGER NOT NULL DEFAULT 0');
  */
 ensureColumn('quarantine', 'dismissed_at', 'TEXT');
 
+/**
+ * Was this a conformance DRILL rather than a real dispatch?
+ *
+ * ## The problem it solves
+ *
+ * Conformance check 11 sends a dispatch this receiver CANNOT open, on purpose,
+ * and passes it for refusing one. So a receiver that quarantines ends a
+ * SUCCESSFUL run with a red fault panel, a \`failed\` count that never returns to
+ * zero, and a \`decrypt_failed\` line naming the partner's real \`key_id\` - telling
+ * them to fix the one thing that is not broken. Reported from a real run.
+ *
+ * ## Why this is trusted and the dispatch id is not
+ *
+ * The flag comes from \`conformance: true\` in the body, and the HMAC covers
+ * \`\${timestamp}.\${rawBody}\`. The body is signed; the headers are not. The
+ * conformance dispatch also carries a recognisable \`X-OneAddress-Dispatch\`
+ * prefix, and keying off THAT would be a mistake: it sits outside the signature,
+ * so anything on the path could set it and change how an operator's fault panel
+ * behaves. Same reasoning as \`crossover_key_ids\`, which is already a signed-body
+ * field that tells a receiver how to treat a payload it cannot decrypt.
+ *
+ * ## Classified, NOT suppressed
+ *
+ * A drill is still recorded, still counted, still visible on the dashboard. It
+ * is drawn calmly instead of as an alarm. Suppression is what creates a silent
+ * failure; classification does not, and if the marker is ever wrong the operator
+ * still sees the event, in the wrong colour rather than not at all.
+ *
+ * ## A drill holds NO payload
+ *
+ * \`raw_body\` is empty for a drill, which is a property rather than a saving.
+ * The probe is sealed to a throwaway key pair the conformance run generated and
+ * discarded, so no key that will ever exist can open it: replay cannot succeed,
+ * and keeping the bytes would put an unopenable blob in the replay set forever.
+ */
+ensureColumn('quarantine', 'drill', 'INTEGER NOT NULL DEFAULT 0');
+
 export interface QuarantineInput {
   dispatchId: string | null;
   event: string;
@@ -3465,6 +3530,10 @@ export interface QuarantineInput {
   keyId: string | null;
   rawBody: string;
   detail: string;
+  /** A conformance probe rather than a consumer's dispatch. See the
+   *  \`drill\` column's docstring. Defaults to false, so a caller that does
+   *  not know about drills still records a real fault. */
+  drill?: boolean;
 }
 
 /**
@@ -3476,27 +3545,44 @@ export interface QuarantineInput {
  */
 export function quarantine(input: QuarantineInput): void {
   const id = dispatchKey(input.dispatchId, input.rawBody);
+  const drill = input.drill === true;
   try {
     db.prepare(
-      \`INSERT INTO quarantine (id, dispatch_id, event, reason, key_id, raw_body, detail)
-       VALUES (?, ?, ?, ?, ?, ?, ?)
+      \`INSERT INTO quarantine (id, dispatch_id, event, reason, key_id, raw_body, detail, drill)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(id) DO UPDATE SET
          reason = excluded.reason,
          key_id = excluded.key_id,
-         detail = excluded.detail\`,
+         detail = excluded.detail,
+         drill  = excluded.drill\`,
     ).run(
       id,
       input.dispatchId,
       input.event,
       input.reason,
       input.keyId,
-      input.rawBody,
+      // NO PAYLOAD FOR A DRILL. The probe is sealed to a throwaway key pair the
+      // conformance run generated and discarded, so nothing that will ever exist
+      // can open it. Keeping the bytes would put a permanently unopenable blob
+      // in the replay set.
+      drill ? '' : input.rawBody,
       input.detail.slice(0, 500),
+      drill ? 1 : 0,
     );
-    report.warn(
-      \`[quarantine] \${input.event} held (\${input.reason}\${input.keyId ? \`, key_id \${input.keyId}\` : ''}). \` +
-      'Fix the cause and press [r] on the dashboard, or run \`npm run replay\`, to apply it.',
-    );
+    if (drill) {
+      // INFO, NOT WARN, and it says what happened rather than what to fix. The
+      // old line ended a PASSING conformance run by telling the partner to go
+      // and correct a key that is perfectly correct.
+      report.info(
+        \`[quarantine] \${input.event} was a conformance probe and was refused, which is how that \` +
+        'check is passed. Nothing is wrong with your key.',
+      );
+    } else {
+      report.warn(
+        \`[quarantine] \${input.event} held (\${input.reason}\${input.keyId ? \`, key_id \${input.keyId}\` : ''}). \` +
+        'Fix the cause and press [r] on the dashboard, or run \`npm run replay\`, to apply it.',
+      );
+    }
   } catch (err) {
     report.error('[quarantine] could not hold this dispatch:', err instanceof Error ? err.message : err);
   }
@@ -3521,16 +3607,30 @@ export function heldDispatches(limit = 50): HeldDispatch[] {
     \`SELECT id, dispatch_id, event, reason, key_id, raw_body, detail,
             received_at, last_error, attempts
        FROM quarantine
-      WHERE replayed_at IS NULL AND dismissed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0
       ORDER BY received_at
       LIMIT ?\`,
   ).all(limit) as unknown as HeldDispatch[];
 }
 
+/**
+ * How many conformance probes this receiver has refused.
+ *
+ * Its own figure rather than a slice of \`heldCount\`, because the two answer
+ * different questions. Held means "waiting on you". A drill means "a check ran
+ * and this receiver behaved correctly", which is not a queue and not work.
+ */
+export function drillCount(): number {
+  const row = db.prepare(
+    'SELECT count(*) AS n FROM quarantine WHERE drill = 1 AND dismissed_at IS NULL',
+  ).get() as { n: number };
+  return row.n;
+}
+
 /** How many dispatches are held. Shown on the dashboard. */
 export function heldCount(): number {
   const row = db.prepare(
-    'SELECT count(*) AS n FROM quarantine WHERE replayed_at IS NULL AND dismissed_at IS NULL',
+    'SELECT count(*) AS n FROM quarantine WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0',
   ).get() as { n: number };
   return row.n;
 }
@@ -3547,7 +3647,7 @@ export function heldSummary(): string[] {
     \`SELECT reason, key_id, count(*) AS n,
             max(attempts) AS tries, min(received_at) AS oldest
        FROM quarantine
-      WHERE replayed_at IS NULL AND dismissed_at IS NULL
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0
       GROUP BY reason, key_id
       ORDER BY n DESC\`,
   ).all() as unknown as {
@@ -3611,7 +3711,7 @@ export function dismissHeld(): number {
   const info = db.prepare(
     \`UPDATE quarantine
         SET dismissed_at = ?, raw_body = ''
-      WHERE replayed_at IS NULL AND dismissed_at IS NULL\`,
+      WHERE replayed_at IS NULL AND dismissed_at IS NULL AND drill = 0\`,
   ).run(new Date().toISOString());
   const n = Number(info.changes ?? 0);
   if (n > 0) {
@@ -3691,10 +3791,25 @@ export function purgeQuarantine(days: number): { replayed: number; unreplayed: n
  * what diagnoses a key problem, and it is safe to paste into a support ticket
  * or send to us, which is what an export is for.
  */
-export function exportHeld(directory: string): { path: string; count: number } {
+export function exportHeld(directory?: string): { path: string; count: number } {
   const rows = heldDispatches(500);
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const path = join(directory, \`oneaddress-faults-\${stamp}.json\`);
+  // RESOLVED TO AN ABSOLUTE PATH, ALWAYS, and that is the point of the change.
+  // "Exported 3 to oneaddress-faults-\u2026.json" is not an answer to "where is it";
+  // a receiver is routinely started by a shortcut or a service manager whose
+  // working directory is not where the partner thinks it is. Reported after a
+  // real run: the file was written and could not be found.
+  //
+  // The explicit argument still wins, so a caller (and every existing test) can
+  // name a directory; \`config.exportDir\` is the persistent choice and
+  // \`ONEADDRESS_EXPORT_DIR\` the one-run override. Empty resolves to the working
+  // directory, which is what this always did.
+  const target = resolve(directory ?? config.exportDir ?? '');
+  // Created rather than failed on. A partner who set \`exportDir\` to a folder
+  // they have not made yet wants the file, not a lecture, and a directory they
+  // named is one they have already consented to.
+  mkdirSync(target, { recursive: true });
+  const path = join(target, \`oneaddress-faults-\${stamp}.json\`);
   writeFileSync(path, JSON.stringify({
     exported_at: new Date().toISOString(),
     note: 'Metadata only. The held payloads are deliberately not included: they are encrypted consumer addresses and stay under the receiver retention window.',
@@ -3711,7 +3826,11 @@ export function exportHeld(directory: string): { path: string; count: number } {
       last_error: r.last_error,
     })),
   }, null, 2));
-  report.info(\`[quarantine] exported \${rows.length} held dispatch(es) to \${path}\`);
+  // THE PATH IS THE MESSAGE. Logged as well as shown on the dashboard, because
+  // the dashboard line is gone the next time anything is pressed while the log
+  // survives a scrollback, a \`npm start | tee\`, and a headless run where there
+  // is no dashboard at all.
+  report.info(\`[quarantine] exported \${rows.length} held dispatch(es) to \${path} - safe to send to support, no payloads inside\`);
   return { path, count: rows.length };
 }
 
@@ -4108,6 +4227,17 @@ export type ReceiverConfig = {
   oneAddressApi:            string;
   verifiesAccountReference: boolean;
   mode:                     ReceiverMode;
+  /**
+   * Where \`[e]\` writes the fault export.
+   *
+   * Empty means the working directory, which is what it always did. Named
+   * because "it saved a file" is useless if you cannot find it: the receiver is
+   * routinely started by a double-clicked shortcut or a service manager whose
+   * working directory is not where the partner thinks it is.
+   *
+   * \`ONEADDRESS_EXPORT_DIR\` overrides it for one run without editing the file.
+   */
+  exportDir:                string;
   /**
    * The webhook URL registered with OneAddress: where dispatches actually
    * arrive from the internet.
@@ -4134,6 +4264,9 @@ const DEFAULTS: ReceiverConfig = {
   mode: 'write-through',
   // No guess. See the field's docstring.
   publicUrl: '',
+  // Empty resolves to the working directory at use, not here, so a config file
+  // written on one machine does not pin an absolute path from another.
+  exportDir: '',
 };
 
 function parseMode(value: unknown): ReceiverMode | undefined {
@@ -4153,6 +4286,7 @@ function loadConfigFile(): Partial<ReceiverConfig> {
     if (typeof parsed.oneAddressApi === 'string')            out.oneAddressApi = parsed.oneAddressApi;
     if (typeof parsed.verifiesAccountReference === 'boolean') out.verifiesAccountReference = parsed.verifiesAccountReference;
     if (typeof parsed.publicUrl === 'string')                 out.publicUrl = parsed.publicUrl;
+    if (typeof parsed.exportDir === 'string')                 out.exportDir = parsed.exportDir;
     const mode = parseMode(parsed.mode);
     if (mode) out.mode = mode;
     return out;
@@ -4177,6 +4311,7 @@ export const config: ReceiverConfig = {
   // start. Silent is the thing to avoid, not strict.
   mode: parseMode(process.env.RECEIVER_MODE) ?? fromFile.mode ?? DEFAULTS.mode,
   publicUrl: stripTrailingSlash(process.env.PUBLIC_URL || fromFile.publicUrl || DEFAULTS.publicUrl),
+  exportDir: process.env.ONEADDRESS_EXPORT_DIR || fromFile.exportDir || DEFAULTS.exportDir,
 };
 
 report.info(
@@ -5595,9 +5730,27 @@ app.post('/webhook', async (req: Request, res: Response) => {
    */
   const key = dispatchKey(dispatch || null, rawBody);
 
+  /**
+   * A DRILL, declared in the SIGNED body. See \`quarantine.ts\`'s \`drill\` column.
+   *
+   * Read from \`body\`, which the HMAC covers, and never from the dispatch-id
+   * header, which it does not. The conformance run already puts a recognisable
+   * prefix on that header and using it would let anything on the path decide
+   * whether this receiver raises an alarm.
+   */
+  const isDrill = (body as Record<string, unknown>).conformance === true;
+
   const hold = (reason: QuarantineReason, keyId: string | null, detail: string): void => {
-    quarantine({ dispatchId: dispatch || null, event, reason, keyId, rawBody, detail });
-    recordOutcome(key, 'failed');
+    quarantine({ dispatchId: dispatch || null, event, reason, keyId, rawBody, detail, drill: isDrill });
+    // NOT COUNTED AS A FAILURE WHEN IT IS A DRILL. \`failed\` on the footer is a
+    // figure about this partner's dispatches; a probe that was refused exactly
+    // as the check requires is not one of them, and leaving it in is what made a
+    // passing conformance run read as \`failed 1\` forever.
+    //
+    // Recorded as NOTHING rather than as a third outcome, deliberately:
+    // \`tally.ts\` holds \`received === applied + failed\` as an invariant and a
+    // drill is not a dispatch to this partner's business at all.
+    if (!isDrill) recordOutcome(key, 'failed');
   };
 
   /**
@@ -5754,11 +5907,24 @@ app.post('/webhook', async (req: Request, res: Response) => {
       decAccount    = typeof data.account_number === 'string' ? data.account_number : '';
       decKnownNames = Array.isArray(data.known_names) ? data.known_names : [];
     } catch (err) {
-      // Names WHICH key answered. A rotation used to surface here as an
-      // authentication-tag error indistinguishable from corruption, with the
-      // single-key fallback having silently answered for a key id it never held.
-      report.error(\`[webhook] D5 decryption failed for key_id \${keyId ?? '(none)'}: \${keyFailureAdvice(keyId, resolved)}\`);
-      report.error('[webhook] underlying error:', err);
+      // A DRILL SAYS SO INSTEAD OF SHOUTING. Conformance check 11 wraps its
+      // session key to a throwaway pair so that decryption MUST fail; the two
+      // lines below would then name the partner's real key_id, print a raw
+      // crypto error, and advise them to go and fix a key that is correct - at
+      // the end of a run that just passed. The refusal below is unchanged,
+      // because the refusal is what the check is testing.
+      if (isDrill) {
+        report.info(
+          \`[webhook] conformance probe for key_id \${keyId ?? '(none)'} could not be decrypted, which is \` +
+          'what that check requires. Your key is fine.',
+        );
+      } else {
+        // Names WHICH key answered. A rotation used to surface here as an
+        // authentication-tag error indistinguishable from corruption, with the
+        // single-key fallback having silently answered for a key id it never held.
+        report.error(\`[webhook] D5 decryption failed for key_id \${keyId ?? '(none)'}: \${keyFailureAdvice(keyId, resolved)}\`);
+        report.error('[webhook] underlying error:', err);
+      }
       hold('decrypt_failed', keyId, keyFailureAdvice(keyId, resolved));
       return res.status(422).json({ ok: false, error: 'D5 decryption failed \u2014 partner key mismatch' });
     }
@@ -6563,6 +6729,26 @@ customers(account_key, account_number, name, address JSON, updated_at)
 address_history(id, account_key, prev_address JSON, address JSON, recorded_at)
 \`\`\`
 
+### Where the fault export lands
+
+\`[e]\` on the dashboard writes a metadata-only file (no payloads) you can send
+straight to support. It goes to the working directory by default, which is not
+always where you think it is when the receiver was started by a shortcut or a
+service manager, so you can name somewhere:
+
+\`\`\`jsonc
+// oneaddress.config.json
+{ "exportDir": "/home/you/oneaddress-exports" }
+\`\`\`
+
+\`\`\`bash
+ONEADDRESS_EXPORT_DIR=/tmp npm start   # one run, without editing the file
+\`\`\`
+
+The directory is created if it does not exist. The confirmation on the dashboard
+and the line in the log both name the **full path**, and the dashboard keeps it
+in its own slot so pressing \`[r]\` does not wipe it.
+
 ### Seeing what changed
 
 \`\`\`bash
@@ -11717,7 +11903,7 @@ async function scaffold(platform, outputDir, partnerId, webhookSecret, webhookUr
 
 // src/register.ts
 var import_node_crypto2 = require("crypto");
-var PKG_VERSION = true ? "2.5.0" : "dev";
+var PKG_VERSION = true ? "2.6.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");

package/package.json

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