@vonpay/checkout-cli 0.16.0 → 0.18.0

package/dist/index.js

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-// src/index.ts
+// src/program.ts
 import { Command as Command13 } from "commander";
-import { readFileSync as readFileSync4 } from "fs";
-import { dirname as dirname2, join as join3 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/login.ts
 import { Command, Option } from "commander";
@@ -12,9 +9,9 @@ import { createInterface } from "readline";
 import chalk from "chalk";
 
 // src/config.ts
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
+import { chmodSync as chmodSync2, existsSync, mkdirSync as mkdirSync2, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
 
 // src/utils/json-errors.ts
 var jsonErrors = false;
@@ -50,9 +47,447 @@ function secretKeyMode(key) {
 }
 var NOT_A_SECRET_KEY_MESSAGE = "This is not a Von Payments secret key: it must start with vp_sk_test_ (sandbox) or vp_sk_live_ (live). Publishable keys (vp_pk_\u2026) and keys from other services cannot be used with this CLI.";
 
+// src/utils/audit-log.ts
+import {
+  chmodSync,
+  closeSync,
+  constants as FS,
+  fchmodSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  unlinkSync,
+  writeSync
+} from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { isErrorCode, stripHiddenCharacters } from "@vonpay/checkout-node";
+var AUDIT_FIELDS = [
+  "ts",
+  "surface",
+  "version",
+  "command",
+  "key_mode",
+  "key_fingerprint",
+  "outcome",
+  "error_code",
+  "request_id",
+  "amount",
+  "currency",
+  "target"
+];
+var AUDIT_OUTCOMES = [
+  "pending",
+  // a money command is about to send; the command's final line follows
+  "sent",
+  // an API command ran to the end (sent and answered); no person was asked
+  "local",
+  // a command that sends nothing to the API (login, logout, init, trigger) ran to the end
+  "approved",
+  // a person confirmed it at the terminal, and it ran to the end
+  "declined",
+  // the person did not type "confirm"
+  "budget_refused",
+  // (the MCP server's spending budget; the CLI has none)
+  "read_mode_blocked",
+  // (the MCP server's read-only mode; the CLI has none)
+  "withheld",
+  // a live action with no person at an interactive terminal to confirm it
+  "lookup_refused",
+  // the check before the confirmation failed (a refund's payment could not be looked up or did not match)
+  "refused_local",
+  // refused by the CLI before anything was sent (a flag, a key rule, an unsafe base URL, a command line it cannot parse, …)
+  "error"
+  // the API (or the network) answered with an error, the run was interrupted, or the CLI crashed (internal_error)
+];
+var LOCAL_ERROR_CODES = [
+  "auth_failed",
+  "budget",
+  "cancelled",
+  "confirm_live_required",
+  "currency_mismatch",
+  "declined",
+  "dismissed",
+  "excess_arguments",
+  "idempotency_key_required",
+  "internal_error",
+  "interrupted",
+  "invalid_argument",
+  "invalid_input",
+  "live_loopback_url",
+  "local_refusal",
+  "lookup_failed",
+  "missing_argument",
+  "network_error",
+  "no_approval_channel",
+  "no_terminal",
+  "not_ticked",
+  "prompt_failed",
+  "read_mode",
+  "unknown_command",
+  "unknown_option",
+  "unknown_tool",
+  "usage_error"
+];
+var LOCAL_CODES = new Set(LOCAL_ERROR_CODES);
+var AUDIT_DIR_ENV = "VONPAY_AUDIT_DIR";
+var AUDIT_SWITCH_ENV = "VONPAY_AUDIT_LOG";
+var AUDIT_RETENTION_ENV = "VONPAY_AUDIT_RETENTION_DAYS";
+var DEFAULT_RETENTION_DAYS = 30;
+var MAX_FILE_BYTES = 50 * 1024 * 1024;
+function auditText(s, max) {
+  const line = stripHiddenCharacters(s).replace(/[\p{Cc}\u{2028}\u{2029}]/gu, " ").trim();
+  return line.length > max ? line.slice(0, max) : line;
+}
+function keyFingerprint(key) {
+  if (key.length >= 24) return `${key.slice(0, 12)}\u2026${key.slice(-4)}`;
+  const head = Math.min(12, Math.floor(key.length / 3));
+  const tail = Math.min(4, Math.floor(key.length / 4));
+  return `${key.slice(0, head)}\u2026${key.slice(key.length - tail)}`;
+}
+var TARGET_ID = /^(vpi|vp_tx|vsub|vp_cs)_(live|test)_[A-Za-z0-9_-]{16}$/;
+var REQUEST_ID = /^[A-Za-z0-9_-]{12}$/;
+var CURRENCY = /^[A-Za-z]{3}$/;
+var COMMAND = /^[a-z0-9-]+( [a-z0-9-]+){0,3}$/;
+var UNKNOWN_COMMAND = "[unknown command]";
+var UNRECOGNISED_ID = "[unrecognised id]";
+var UNRECOGNISED_REQUEST_ID = "[unrecognised request id]";
+function knownErrorCode(code) {
+  return typeof code === "string" && (isErrorCode(code) || LOCAL_CODES.has(code));
+}
+function auditLine(record) {
+  const out = {};
+  for (const field of AUDIT_FIELDS) {
+    const v = record[field];
+    if (v === void 0 || v === null) continue;
+    switch (field) {
+      case "amount":
+        if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0) out[field] = v;
+        break;
+      case "currency":
+        if (typeof v === "string" && CURRENCY.test(v)) out[field] = v.toUpperCase();
+        break;
+      case "target":
+        if (typeof v === "string") out[field] = TARGET_ID.test(v) ? v : UNRECOGNISED_ID;
+        break;
+      case "error_code":
+        if (typeof v === "string") out[field] = knownErrorCode(v) ? v : "unrecognised_code";
+        break;
+      case "request_id":
+        if (typeof v === "string") out[field] = REQUEST_ID.test(v) ? v : UNRECOGNISED_REQUEST_ID;
+        break;
+      case "outcome":
+        if (typeof v === "string" && AUDIT_OUTCOMES.includes(v)) out[field] = v;
+        break;
+      case "key_mode":
+        if (v === "test" || v === "live") out[field] = v;
+        break;
+      case "command":
+        if (typeof v === "string") out[field] = COMMAND.test(v) ? v : UNKNOWN_COMMAND;
+        break;
+      default:
+        if (typeof v === "string") out[field] = auditText(v, field === "ts" ? 40 : 80);
+    }
+  }
+  return `${JSON.stringify(out)}
+`;
+}
+function auditSettingsFromEnv(env = process.env, warn = stderrWarn) {
+  const off = ["off", "0", "false", "no"].includes((env[AUDIT_SWITCH_ENV] ?? "").trim().toLowerCase());
+  const raw = (env[AUDIT_RETENTION_ENV] ?? "").trim();
+  let retentionDays = DEFAULT_RETENTION_DAYS;
+  if (raw !== "") {
+    const n = Number(raw);
+    if (/^[0-9]{1,3}$/.test(raw) && n >= 1 && n <= 365) retentionDays = n;
+    else warn(`[vonpay] ${AUDIT_RETENTION_ENV} must be a whole number from 1 to 365; keeping audit files ${DEFAULT_RETENTION_DAYS} days.`);
+  }
+  const dir = env[AUDIT_DIR_ENV]?.trim() ? resolve(env[AUDIT_DIR_ENV].trim()) : join(homedir(), ".vonpay", "audit");
+  return { dir: off ? null : dir, retentionDays };
+}
+function stderrWarn(m) {
+  try {
+    process.stderr.write(`${m}
+`);
+  } catch (err) {
+    void err;
+  }
+}
+function errorCodeOf(err) {
+  return err !== null && typeof err === "object" && typeof err.code === "string" ? err.code : "error";
+}
+var AuditPlaceRefused = class extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+  code;
+};
+function myUid() {
+  return typeof process.getuid === "function" ? process.getuid() : void 0;
+}
+function checkDir(dir, st) {
+  if (st.isSymbolicLink()) throw new AuditPlaceRefused("directory_is_a_symlink");
+  if (!st.isDirectory()) throw new AuditPlaceRefused("not_a_directory");
+  const uid = myUid();
+  if (uid !== void 0 && st.uid !== uid) throw new AuditPlaceRefused("directory_owned_by_another_user");
+  if (uid !== void 0 && (st.mode & 63) !== 0) chmodSync(dir, 448);
+}
+var FILE_NAME = /^cli-(\d{4})-(\d{2})-(\d{2})\.jsonl$/;
+var appendFlags = () => FS.O_APPEND | FS.O_CREAT | FS.O_WRONLY | (FS.O_NOFOLLOW ?? 0);
+var warned = false;
+var warnedFull = false;
+function warnOnce(dir, err, warn) {
+  if (warned) return;
+  warned = true;
+  warn(
+    `[vonpay] The local audit log cannot be written (${errorCodeOf(err)}) in ${dir}; the command went on without it. Set ${AUDIT_DIR_ENV} to a writable directory of your own, or ${AUDIT_SWITCH_ENV}=off.`
+  );
+}
+function pruneAuditFiles(dir, retentionDays, now = /* @__PURE__ */ new Date(), warn = stderrWarn) {
+  let names;
+  try {
+    checkDir(dir, lstatSync(dir));
+    names = readdirSync(dir);
+  } catch (err) {
+    if (errorCodeOf(err) !== "ENOENT") warnOnce(dir, err, warn);
+    return 0;
+  }
+  const today = Date.parse(`${now.toISOString().slice(0, 10)}T00:00:00Z`);
+  let removed = 0;
+  let skipped = 0;
+  for (const name of names) {
+    const m = FILE_NAME.exec(name);
+    if (!m) continue;
+    const day = Date.parse(`${m[1]}-${m[2]}-${m[3]}T00:00:00Z`);
+    if (!Number.isFinite(day) || (today - day) / 864e5 <= retentionDays) continue;
+    const path = join(dir, name);
+    try {
+      if (!lstatSync(path).isFile()) {
+        skipped++;
+        continue;
+      }
+      unlinkSync(path);
+      removed++;
+    } catch {
+      skipped++;
+    }
+  }
+  if (skipped > 0) warn(`[vonpay] ${skipped} old audit file(s) in ${dir} were not deleted (not a regular file, or could not be removed).`);
+  return removed;
+}
+function appendSecure(file, line, maxBytes, dir, warn) {
+  const fd = openSync(file, appendFlags(), 384);
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile()) throw new AuditPlaceRefused("not_a_regular_file");
+    const uid = myUid();
+    if (uid !== void 0 && st.uid !== uid) throw new AuditPlaceRefused("file_owned_by_another_user");
+    if (uid !== void 0 && (st.mode & 63) !== 0) fchmodSync(fd, 384);
+    if (st.size + Buffer.byteLength(line) > maxBytes) {
+      if (!warnedFull) {
+        warnedFull = true;
+        warn(`[vonpay] Today's audit file in ${dir} is full; no more lines are written to it today.`);
+      }
+      return;
+    }
+    writeSync(fd, line);
+  } finally {
+    closeSync(fd);
+  }
+}
+function writeAuditLine(dir, record, now = /* @__PURE__ */ new Date(), warn = stderrWarn, maxBytes = MAX_FILE_BYTES) {
+  const file = join(dir, `cli-${now.toISOString().slice(0, 10)}.jsonl`);
+  try {
+    const line = auditLine(record);
+    const attempt = () => {
+      mkdirSync(dir, { recursive: true, mode: 448 });
+      checkDir(dir, lstatSync(dir));
+      appendSecure(file, line, maxBytes, dir, warn);
+    };
+    try {
+      attempt();
+    } catch (err) {
+      if (errorCodeOf(err) !== "ENOENT") throw err;
+      attempt();
+    }
+    return true;
+  } catch (err) {
+    warnOnce(dir, err, warn);
+    return false;
+  }
+}
+var COMMAND_KIND = {
+  "checkout login": "local",
+  "checkout logout": "local",
+  "checkout init": "local",
+  "checkout trigger": "local",
+  // signs a synthetic event and sends it to YOUR endpoint, not the API
+  "checkout sessions create": "api",
+  "checkout sessions get": "api",
+  "checkout payment-intents create": "api",
+  "checkout payment-intents get": "api",
+  "checkout payment-intents capture": "api",
+  "checkout payment-intents void": "api",
+  "checkout payment-intents list": "api",
+  "checkout payment-intents summary": "api",
+  "checkout refunds create": "api",
+  "checkout refunds list": "api",
+  "checkout tokens create": "api",
+  "checkout capabilities": "api",
+  "checkout listen": "api",
+  "checkout health": "api",
+  "checkout doctor": "api"
+};
+var MONEY = {
+  "checkout payment-intents create": (o) => ({ amount: wholeNumber(o.amount), currency: o.currency, target: o.sessionId }),
+  "checkout payment-intents capture": (o, a) => ({ amount: wholeNumber(o.amountToCapture), target: a[0] }),
+  "checkout payment-intents void": (_o, a) => ({ target: a[0] }),
+  "checkout refunds create": (o) => ({ amount: wholeNumber(o.amount), currency: o.currency, target: o.paymentIntent ?? o.transaction }),
+  "checkout sessions create": (o) => ({ amount: wholeNumber(o.amount), currency: o.currency })
+};
+function wholeNumber(v) {
+  return typeof v === "string" && /^[0-9]{1,15}$/.test(v.trim()) ? Number(v.trim()) : typeof v === "number" ? v : void 0;
+}
+var pending = null;
+var hooked = false;
+var SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143 };
+var processHandlers = [];
+function keyFields(apiKey) {
+  return apiKey ? { key_mode: apiKey.startsWith("vp_sk_test_") ? "test" : "live", key_fingerprint: keyFingerprint(apiKey) } : {};
+}
+var signalsHandledByCommand = false;
+function auditSignalHandledByCommand() {
+  signalsHandledByCommand = true;
+}
+function hookProcess() {
+  if (hooked) return;
+  hooked = true;
+  const onExit = (code) => auditFinish(code);
+  const onCrash = () => auditNote({ crashed: true });
+  process.on("exit", onExit);
+  process.on("uncaughtExceptionMonitor", onCrash);
+  processHandlers.push(["exit", onExit], ["uncaughtExceptionMonitor", onCrash]);
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    const handler = () => {
+      if (signalsHandledByCommand) return;
+      auditNote({ interrupted: true });
+      auditFinish(SIGNAL_EXIT[sig]);
+      process.exit(SIGNAL_EXIT[sig]);
+    };
+    processHandlers.push([sig, handler]);
+    process.on(sig, handler);
+  }
+}
+function auditStart(command, version, opts = {}, args = []) {
+  const settings = auditSettingsFromEnv();
+  if (settings.dir === null) {
+    pending = null;
+    return;
+  }
+  pruneAuditFiles(settings.dir, settings.retentionDays);
+  let money = {};
+  try {
+    money = Object.prototype.hasOwnProperty.call(MONEY, command) ? MONEY[command](opts, args) : {};
+  } catch {
+    money = {};
+  }
+  pending = { command, money, settings, version, intentWritten: false, written: false };
+  if (typeof opts.apiKey === "string") pending.apiKey = opts.apiKey;
+  hookProcess();
+}
+function auditNote(note, onlyIfUnset = false) {
+  if (!pending) return;
+  if (onlyIfUnset && pending.outcome !== void 0 && note.outcome !== void 0) return;
+  Object.assign(pending, note);
+}
+function auditError(err) {
+  if (err === null || typeof err !== "object") return;
+  const e = err;
+  if (typeof e.status === "number" && typeof e.code === "string") {
+    auditNote({ apiCode: e.code, ...typeof e.requestId === "string" ? { requestId: e.requestId } : {} });
+  } else if (e.cause !== void 0 && err instanceof TypeError) {
+    auditNote({ networkError: true });
+  }
+}
+function auditIntent(now = /* @__PURE__ */ new Date()) {
+  const p = pending;
+  if (!p || p.intentWritten || p.settings.dir === null || !Object.prototype.hasOwnProperty.call(MONEY, p.command)) return;
+  p.intentWritten = true;
+  writeAuditLine(p.settings.dir, { command: p.command, ts: now.toISOString(), surface: "cli", version: p.version, ...keyFields(p.apiKey), outcome: "pending", ...p.money }, now);
+}
+function auditFinish(exitCode, now = /* @__PURE__ */ new Date()) {
+  const p = pending;
+  if (!p || p.written || p.settings.dir === null) return;
+  p.written = true;
+  try {
+    let outcome;
+    let code = p.code;
+    if (p.crashed) [outcome, code] = ["error", "internal_error"];
+    else if (p.interrupted) [outcome, code] = ["error", "interrupted"];
+    else if (p.outcome) outcome = p.outcome;
+    else if (p.apiCode) [outcome, code] = ["error", p.apiCode];
+    else if (p.networkError) [outcome, code] = ["error", "network_error"];
+    else if (exitCode === 0) outcome = p.approved ? "approved" : COMMAND_KIND[p.command] === "local" ? "local" : "sent";
+    else [outcome, code] = ["refused_local", code ?? "local_refusal"];
+    writeAuditLine(
+      p.settings.dir,
+      {
+        command: p.command,
+        ts: now.toISOString(),
+        surface: "cli",
+        version: p.version,
+        ...keyFields(p.apiKey),
+        outcome,
+        ...code ? { error_code: code } : {},
+        ...p.requestId ? { request_id: p.requestId } : {},
+        ...p.money
+      },
+      now
+    );
+  } catch (err) {
+    warnOnce(p.settings.dir, err, stderrWarn);
+  }
+}
+function usageReason(commanderCode) {
+  switch (commanderCode) {
+    case "commander.unknownCommand":
+      return "unknown_command";
+    case "commander.unknownOption":
+      return "unknown_option";
+    case "commander.missingArgument":
+    case "commander.optionMissingArgument":
+    case "commander.missingMandatoryOptionValue":
+      return "missing_argument";
+    case "commander.invalidArgument":
+      return "invalid_argument";
+    case "commander.excessArguments":
+      return "excess_arguments";
+    default:
+      return "usage_error";
+  }
+}
+function auditUsageError(command, version, commanderCode, exitCode, now = /* @__PURE__ */ new Date()) {
+  try {
+    if (exitCode === 0) return;
+    const reason = usageReason(commanderCode);
+    if (pending) {
+      auditNote({ outcome: "refused_local", code: reason }, true);
+      return;
+    }
+    const settings = auditSettingsFromEnv();
+    if (settings.dir === null) return;
+    const name = reason === "unknown_command" || command === "" ? UNKNOWN_COMMAND : command;
+    writeAuditLine(settings.dir, { command: name, ts: now.toISOString(), surface: "cli", version, outcome: "refused_local", error_code: reason }, now);
+  } catch (err) {
+    void err;
+  }
+}
+
 // src/config.ts
-var CONFIG_DIR = join(homedir(), ".vonpay");
-var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var CONFIG_DIR = join2(homedir2(), ".vonpay");
+var CONFIG_FILE = join2(CONFIG_DIR, "config.json");
 function loadConfig() {
   if (!existsSync(CONFIG_FILE)) return {};
   try {
@@ -79,13 +514,13 @@ function saveConfig(config) {
     warnStoredLiveKey();
   }
   if (!existsSync(CONFIG_DIR)) {
-    mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+    mkdirSync2(CONFIG_DIR, { recursive: true, mode: 448 });
   }
   writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", {
     encoding: "utf-8",
     mode: 384
   });
-  chmodSync(CONFIG_FILE, 384);
+  chmodSync2(CONFIG_FILE, 384);
 }
 function clearStoredApiKey() {
   const config = loadConfig();
@@ -124,6 +559,7 @@ function requireApiKey() {
   if (secretKeyMode(key) === null) {
     emitCliError({ error: NOT_A_SECRET_KEY_MESSAGE, code: null }, NOT_A_SECRET_KEY_MESSAGE);
   }
+  auditNote({ apiKey: key });
   return key;
 }
 
@@ -146,10 +582,10 @@ function evaluateKeyToSave(key) {
 }
 function readLine(prompt) {
   const rl = createInterface({ input: process.stdin, output: process.stderr });
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     rl.question(prompt, (answer) => {
       rl.close();
-      resolve2(answer.trim());
+      resolve3(answer.trim());
     });
   });
 }
@@ -222,8 +658,8 @@ function logoutCommand() {
 
 // src/commands/init.ts
 import { Command as Command3 } from "commander";
-import { appendFileSync, chmodSync as chmodSync2, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { resolve } from "path";
+import { appendFileSync, chmodSync as chmodSync3, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { resolve as resolve2 } from "path";
 import chalk3 from "chalk";
 var LIVE_KEY_NOT_WRITTEN_MESSAGE = "Refusing to write a live key (vp_sk_live_\u2026) to .env: live keys are never written to disk. Run `init` with a sandbox key (vp_sk_test_\u2026), and give your app its live key through your deployment's secret store or the environment when you go live.";
 function ensureGitignoreBlocksEnv() {
@@ -274,7 +710,7 @@ function initCommand() {
       process.exit(1);
     }
     const envFile = ".env";
-    const absPath = resolve(envFile);
+    const absPath = resolve2(envFile);
     if (existsSync2(envFile) && !opts.force) {
       console.error(
         chalk3.yellow(
@@ -299,7 +735,7 @@ function initCommand() {
       ""
     ].join("\n");
     writeFileSync2(envFile, content, { encoding: "utf-8", mode: 384 });
-    chmodSync2(envFile, 384);
+    chmodSync3(envFile, 384);
     console.log(chalk3.green(`\u2713 .env created (${mode} mode) \u2192 ${absPath}`));
     const gitignoreState = ensureGitignoreBlocksEnv();
     if (gitignoreState === "added") {
@@ -318,7 +754,7 @@ function initCommand() {
 
 // src/commands/sessions.ts
 import { Command as Command4 } from "commander";
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 
 // src/utils/spinner.ts
 import ora from "ora";
@@ -334,10 +770,10 @@ import { VonPayCheckout } from "@vonpay/checkout-node";
 
 // src/app-info.ts
 import { readFileSync as readFileSync3 } from "fs";
-import { dirname, join as join2 } from "path";
+import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
 var pkg = JSON.parse(
-  readFileSync3(join2(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")
+  readFileSync3(join3(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")
 );
 var CLI_VERSION = pkg.version;
 var CLI_APP_INFO = { name: "vonpay-cli", version: CLI_VERSION };
@@ -347,12 +783,18 @@ var SILENT_ERROR_REPORTER = () => {
 // src/utils/base-url.ts
 import { keyDestinationProblem as sdkKeyDestinationProblem } from "@vonpay/checkout-node";
 var ALLOW_CUSTOM_BASE_URL_ENV = "VONPAY_ALLOW_CUSTOM_BASE_URL";
-function customBaseUrlAllowed(env = process.env) {
-  return env[ALLOW_CUSTOM_BASE_URL_ENV] === "1";
+var ALLOW_CUSTOM_BASE_URL_FLAG = "--allow-custom-base-url";
+var flagGiven = false;
+function setAllowCustomBaseUrlFlag(given) {
+  flagGiven = given === true;
+}
+function customBaseUrlAllowed(env = process.env, flag = flagGiven) {
+  return env[ALLOW_CUSTOM_BASE_URL_ENV] === "1" && flag === true;
 }
 var UNSAFE_URL_CHARS = /[\s\x00-\x1f\x7f\\]/;
 var WHERE = "It comes from VONPAY_BASE_URL or baseUrl in ~/.vonpay/config.json; fix it, or unset it to use https://checkout.vonpay.com.";
-function keyDestinationProblem(apiKey, baseUrl, env = process.env) {
+var CLI_OPT_IN = `For a proxy you run yourself, set ${ALLOW_CUSTOM_BASE_URL_ENV}=1 AND pass ${ALLOW_CUSTOM_BASE_URL_FLAG} on the command; either alone is not enough.`;
+function keyDestinationProblem(apiKey, baseUrl, env = process.env, flag = flagGiven) {
   if (baseUrl === void 0) return null;
   if (UNSAFE_URL_CHARS.test(baseUrl)) {
     return `Refusing to use the base URL: it contains spaces, control characters or backslashes. ${WHERE}`;
@@ -366,11 +808,11 @@ function keyDestinationProblem(apiKey, baseUrl, env = process.env) {
   if (url.username !== "" || url.password !== "") {
     return `Refusing to use the base URL: it contains a user name or password, which would be sent with every request. ${WHERE}`;
   }
-  const problem = sdkKeyDestinationProblem(apiKey, baseUrl, { allowCustom: customBaseUrlAllowed(env) });
-  return problem === null ? null : `${problem} ${WHERE}`;
+  const problem = sdkKeyDestinationProblem(apiKey, baseUrl, { allowCustom: customBaseUrlAllowed(env, flag) });
+  return problem === null ? null : `${problem} ${WHERE} ${CLI_OPT_IN}`;
 }
-function allowCustomBaseUrl(env = process.env) {
-  return customBaseUrlAllowed(env);
+function allowCustomBaseUrl(env = process.env, flag = flagGiven) {
+  return customBaseUrlAllowed(env, flag);
 }
 
 // src/utils/errors.ts
@@ -404,10 +846,13 @@ function scrubSecrets(s) {
 }
 
 // src/utils/sanitize.ts
+import { stripHiddenCharacters as stripHiddenCharacters2 } from "@vonpay/checkout-node";
 var ANSI_PATTERN = /\x1B\[[0-9;?]*[A-Za-z]/g;
-var C0_CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+var C1_CSI_PATTERN = /\u{9B}[0-9;?]*[A-Za-z]/gu;
+var CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\u{80}-\u{9F}]/gu;
+var LINE_SEPARATOR_PATTERN = /[\u{2028}\u{2029}]/gu;
 function stripAnsi(s) {
-  return s.replace(ANSI_PATTERN, "").replace(C0_CONTROL_PATTERN, "");
+  return stripHiddenCharacters2(s.replace(ANSI_PATTERN, "").replace(C1_CSI_PATTERN, "").replace(CONTROL_PATTERN, ""));
 }
 function truncate(s, max) {
   if (s.length <= max) return s;
@@ -417,7 +862,7 @@ function safeDisplay(s, max = 200) {
   return truncate(stripAnsi(s), max);
 }
 function safeInline(s, max = 200) {
-  return safeDisplay(s.replace(/[\r\n]+/g, " "), max);
+  return safeDisplay(s.replace(/[\r\n]+/g, " ").replace(LINE_SEPARATOR_PATTERN, " "), max);
 }
 
 // src/utils/errors.ts
@@ -425,6 +870,11 @@ var CLI_READ_BACK = "From this CLI: `vonpay checkout payment-intents get <id>` (
 var READ_BACK_FIRST = "Check the payment first: read it back (`vonpay checkout payment-intents get <id>` for a charge, capture or void; `vonpay checkout refunds list --payment-intent <id>` (or `--transaction <id>`) for a refund; `sessions get <id>` for a checkout session) and act only on what it shows.";
 var UNKNOWN_OUTCOME_GUIDANCE = `${READ_BACK_FIRST} If you then retry, reuse the SAME --idempotency-key as the first attempt, never a new one: a new key is a new action and can move money twice.`;
 var str = (v) => v === void 0 || v === null ? null : String(v);
+var oneLine = (s) => safeInline(s, 2e3);
+function paramFlagHint(param) {
+  const flag = param.startsWith("metadata") ? "--metadata" : `--${param.replace(/\[(gte|lt)\]$/, "-$1").replace(/_/g, "-")}`;
+  return /^--[a-z-]+$/.test(flag) ? ` (the ${flag} flag)` : "";
+}
 var FIELD_PRINTERS = {
   code: (e) => `Code: ${str(e.code)}`,
   fix: (e) => `Fix:  ${str(e.fix)}`,
@@ -464,8 +914,8 @@ var FIELD_PRINTERS = {
   usedMinor: (e) => typeof e.usedMinor === "number" ? `Used in the last 24 hours: ${safeInline(String(e.usedMinor))} (minor units)` : null,
   limitCurrency: (e) => e.limitCurrency ? `Key limit currency: ${safeInline(String(e.limitCurrency))}` : null,
   refusedFields: (e) => Array.isArray(e.refusedFields) && e.refusedFields.length > 0 ? `Fields this key may not send: ${e.refusedFields.map((f) => safeInline(String(f), 128)).join(", ")}` : null,
-  // A refused payment-only settle (mirror_settle_only_*; built ahead of the
-  // API's production release): the charge asked for and the store order's
+  // A refused payment-only settle (mirror_settle_only_*; served in production
+  // since 2026-10-27): the charge asked for and the store order's
   // facts. Validated by the SDK, printed through safeInline all the same.
   chargeAmount: (e) => typeof e.chargeAmount === "number" ? `Charge asked for: ${safeInline(String(e.chargeAmount))} (minor units)` : null,
   chargeCurrency: (e) => e.chargeCurrency ? `Charge currency: ${safeInline(String(e.chargeCurrency))}` : null,
@@ -474,6 +924,34 @@ var FIELD_PRINTERS = {
   orderCurrency: (e) => e.orderCurrency ? `Store order currency: ${safeInline(String(e.orderCurrency))}` : null,
   orderStatus: (e) => e.orderStatus ? `Store order status: ${safeInline(String(e.orderStatus))}` : null,
   orderPaymentStatus: (e) => e.orderPaymentStatus ? `Store order payment status: ${safeInline(String(e.orderPaymentStatus))}` : null,
+  // A refused subscription change (served in production since 2026-10-30). Validated by
+  // the SDK, printed through safeInline all the same.
+  subscriptionStatus: (e) => e.subscriptionStatus ? `Subscription status: ${safeInline(String(e.subscriptionStatus))}` : null,
+  refusalReason: (e) => e.refusalReason ? `Refused because: ${safeInline(String(e.refusalReason))}` : null,
+  minDate: (e) => e.minDate ? `Earliest date allowed: ${safeInline(String(e.minDate))}` : null,
+  maxDate: (e) => e.maxDate ? `Latest date allowed: ${safeInline(String(e.maxDate))}` : null,
+  currentAmount: (e) => typeof e.currentAmount === "number" ? `Current highest renewal charge: ${safeInline(String(e.currentAmount))} (minor units)` : null,
+  maxAmount: (e) => typeof e.maxAmount === "number" ? `Most this key may make a renewal charge: ${safeInline(String(e.maxAmount))} (minor units)` : e.maxAmount === null ? "Most this key may make a renewal charge: none \u2014 this key may only lower the price" : null,
+  amountCurrency: (e) => e.amountCurrency ? `Renewal charge currency: ${safeInline(String(e.amountCurrency))}` : null,
+  pendingKind: (e) => e.pendingKind ? `Schedule change waiting for its customer notice: ${safeInline(String(e.pendingKind))}` : null,
+  nextChangeAllowedOn: (e) => e.nextChangeAllowedOn ? `Customer's next schedule change allowed from: ${safeInline(String(e.nextChangeAllowedOn))}` : null,
+  // A charge the payment provider refused before any money moved (served in
+  // production since 2026-10-30): the failed payment intent that records
+  // the attempt. The SDK has checked it is a vpi_* id; printed through
+  // safeInline all the same. The next step depends on the code: a card the
+  // processor is still storing (payment_method_unvaulted) is retried as is
+  // after a short wait; every other refusal needs the request or card fixed.
+  // Both under a NEW key: the refused record does not hold the key, and the
+  // processor may refuse a resend under the same one.
+  // A refused payment list / summary filter (`payment-intents list` / `summary`): the ONE
+  // query parameter at fault, a plain parameter name the SDK has checked. The flag that sets it
+  // is named alongside, so the fix is obvious.
+  param: (e) => e.param ? `Refused parameter: ${safeInline(String(e.param))}${paramFlagHint(String(e.param))}` : null,
+  // A payment report too large to answer (report_too_large): which limit refused it. The SDK
+  // validates both as positive whole numbers.
+  maxGroups: (e) => typeof e.maxGroups === "number" ? `Most groups one summary returns: ${e.maxGroups} \u2014 group by fewer dimensions or a coarser time unit, or add filters` : null,
+  timeoutMs: (e) => typeof e.timeoutMs === "number" ? `Time limit exceeded: ${e.timeoutMs} ms \u2014 use a shorter window or add filters (retrying unchanged fails the same way)` : null,
+  paymentIntentId: (e) => e.paymentIntentId ? `Refused attempt recorded as: ${safeInline(String(e.paymentIntentId))} (status failed, nothing was charged; ` + (e.code === "payment_method_unvaulted" ? "wait a few seconds, then send the same charge again with a NEW --idempotency-key)" : "fix the request or the card, then charge with a NEW --idempotency-key)") : null,
   // On a withheld retry the SDK sets this to RETRY_WITHHELD_HELP.llmHint — the
   // one wording for every surface — so it is printed as is.
   llmHint: (e) => e.llmHint ? `Hint: ${str(e.llmHint)}` : null,
@@ -488,12 +966,12 @@ function errorDetailLines(err) {
   const lines = [];
   for (const print of Object.values(FIELD_PRINTERS)) {
     const line = print(source);
-    if (line !== null) lines.push(`  ${scrubSecrets(line)}`);
+    if (line !== null) lines.push(`  ${scrubSecrets(oneLine(line))}`);
   }
   return lines;
 }
 function scrubDeep(value) {
-  if (typeof value === "string") return scrubSecrets(value);
+  if (typeof value === "string") return scrubSecrets(oneLine(value));
   if (Array.isArray(value)) return value.map(scrubDeep);
   if (value !== null && typeof value === "object") {
     const out = {};
@@ -513,23 +991,25 @@ function errorJson(err) {
     return scrubDeep(out);
   }
   const message = err instanceof Error ? err.message : String(err);
-  return { error: scrubSecrets(message), code: null };
+  return { error: scrubSecrets(oneLine(message)), code: null };
 }
 function exitWithCliError(message, text) {
+  auditNote({ outcome: "refused_local", code: "local_refusal" }, true);
   return emitCliError({ error: scrubSecrets(message), code: null }, text);
 }
 function handleError(err) {
+  auditError(err);
   if (jsonErrorsEnabled()) {
     printJsonError(errorJson(err));
     process.exit(1);
   }
   if (err instanceof VonPayError) {
-    console.error(chalk4.red(`Error: ${scrubSecrets(err.message)}`));
+    console.error(chalk4.red(`Error: ${scrubSecrets(oneLine(err.message))}`));
     for (const line of errorDetailLines(err)) console.error(chalk4.dim(line));
     process.exit(1);
   }
   const message = err instanceof Error ? err.message : String(err);
-  console.error(chalk4.red(`Error: ${scrubSecrets(message)}`));
+  console.error(chalk4.red(`Error: ${scrubSecrets(oneLine(message))}`));
   process.exit(1);
 }
 
@@ -554,11 +1034,30 @@ function apiHostDetail() {
   }
   return origin === "https://checkout.vonpay.com" ? [] : [["API host", origin]];
 }
+var MONEY_METHODS = {
+  paymentIntents: ["create", "capture", "void"],
+  refunds: ["create"],
+  sessions: ["create"]
+};
+function withAuditIntent(client) {
+  for (const [resource, methods] of Object.entries(MONEY_METHODS)) {
+    const target = client[resource];
+    for (const method of methods) {
+      const original = target?.[method];
+      if (typeof original !== "function") continue;
+      target[method] = (...args) => {
+        auditIntent();
+        return original.apply(target, args);
+      };
+    }
+  }
+  return client;
+}
 function makeCheckoutClient() {
   const apiKey = requireApiKey();
   const baseUrl = getBaseUrl();
   refuseUnsafeLiveDestination(apiKey);
-  return new VonPayCheckout({
+  return withAuditIntent(new VonPayCheckout({
     apiKey,
     ...baseUrl ? { baseUrl } : {},
     // The SDK applies the same host rule at construction; the opt-in is the
@@ -568,7 +1067,86 @@ function makeCheckoutClient() {
     // The CLI prints every error itself (handleError / --json). Without this the SDK's fallback
     // reporter adds its own `[vonpay] …` line to stderr on EVERY API error, live key included.
     errorReporter: SILENT_ERROR_REPORTER
-  });
+  }));
+}
+
+// src/utils/live-key.ts
+import { createInterface as createInterface2 } from "readline";
+import chalk5 from "chalk";
+import { Option as Option2 } from "commander";
+import { isLiveKey as isLiveKey2 } from "@vonpay/checkout-node";
+var CONFIRM_WORD = "confirm";
+var terminal = {
+  /**
+   * Both stdin and stdout are a terminal. A command run by a script, a CI job or
+   * an AI agent's shell tool has at least one of them piped.
+   */
+  isInteractive() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+  },
+  /** Ask one line on the terminal. End of input or Ctrl-C answers "" (cancel). */
+  ask(prompt) {
+    return new Promise((resolve3) => {
+      const rl = createInterface2({ input: process.stdin, output: process.stdout });
+      let answered = false;
+      rl.on("SIGINT", () => rl.close());
+      rl.on("close", () => {
+        if (!answered) resolve3("");
+      });
+      rl.question(prompt, (answer) => {
+        answered = true;
+        rl.close();
+        resolve3(answer);
+      });
+    });
+  }
+};
+function keyFingerprint2(key) {
+  const m = key.match(/^(vp_sk_live_)([A-Za-z0-9_-]{0,4})/);
+  return m ? `${m[1]}${m[2]}\u2026` : "a key that is not a sandbox key";
+}
+async function confirmLiveAction(key, summary, opts = {}) {
+  if (!requiresLiveConfirmation(key)) return;
+  if (!terminal.isInteractive()) {
+    const message = `Refusing to ${summary.action} with a live key: no person is at an interactive terminal to confirm it. A live-key action must be confirmed by a person typing at a terminal (stdin and stdout both a terminal); scripts, CI jobs and AI agents cannot confirm it, and --confirm-live is no longer enough. Use a sandbox key (vp_sk_test_\u2026) for automation, or run the command yourself in a terminal. Nothing was sent.`;
+    auditNote({ outcome: "withheld", code: "no_terminal" });
+    exitWithCliError(message, chalk5.red(message));
+  }
+  if (opts.confirmLive) {
+    console.warn(
+      chalk5.yellow(
+        "Note: --confirm-live no longer confirms a live action by itself. A person confirms it at the terminal."
+      )
+    );
+  }
+  const lines = [
+    chalk5.bold.red(`You are about to ${summary.action} with a LIVE key (${keyFingerprint2(key)}).`),
+    // At least one space after the label, however long it is.
+    ...(summary.details ?? []).map(([label, value]) => `  ${`${label}:`.padEnd(Math.max(17, label.length + 2))}${safeInline(value)}`),
+    chalk5.yellow(summary.consequence ?? "This moves real money and cannot be undone from here.")
+  ];
+  for (const line of lines) console.log(line);
+  const answer = await terminal.ask(`Type "${CONFIRM_WORD}" to proceed, anything else to cancel: `);
+  if (answer.trim() !== CONFIRM_WORD) {
+    auditNote({ outcome: "declined", code: "declined" });
+    const message = `Cancelled: you did not type "${CONFIRM_WORD}". Nothing was sent.`;
+    exitWithCliError(message, chalk5.red(message));
+  }
+  auditNote({ approved: true });
+}
+function retiredConfirmLiveOption() {
+  return new Option2(
+    "--confirm-live",
+    "No longer confirms anything: a live-key action is confirmed by a person at the terminal"
+  ).hideHelp();
+}
+function warnLiveSecretFlag(key, flag) {
+  if (!requiresLiveConfirmation(key)) return;
+  console.warn(
+    chalk5.yellow(
+      `Warning: passing ${flag} as a command argument with a live key exposes it to shell history and process-list (\`ps\`). Consider piping or env-injecting the value instead.`
+    )
+  );
 }
 
 // src/utils/amount.ts
@@ -612,18 +1190,18 @@ function sessionJson(session, showSecrets) {
 // src/commands/sessions.ts
 var makeClient = makeCheckoutClient;
 function sessionLines(session) {
-  const statusColor = session.status === "succeeded" ? chalk5.green : session.status === "failed" ? chalk5.red : session.status === "expired" ? chalk5.gray : chalk5.yellow;
+  const statusColor = session.status === "succeeded" ? chalk6.green : session.status === "failed" ? chalk6.red : session.status === "expired" ? chalk6.gray : chalk6.yellow;
   const lines = [
     `  ID:          ${session.id}`,
     `  Status:      ${statusColor(session.status)}`,
     `  Amount:      ${formatMinorUnits(session.amount, session.currency)}`
   ];
   if (session.paymentStatus) {
-    const paymentColor = session.paymentStatus === "paid" ? chalk5.green : session.paymentStatus === "held" ? chalk5.yellow : chalk5.gray;
+    const paymentColor = session.paymentStatus === "paid" ? chalk6.green : session.paymentStatus === "held" ? chalk6.yellow : chalk6.gray;
     lines.push(`  Payment:     ${paymentColor(session.paymentStatus)}`);
     if (session.paymentStatus === "held") {
       lines.push(
-        chalk5.yellow(
+        chalk6.yellow(
           "               Held, not taken: capture it to take the money, or void it. Do not ship on a hold alone."
         )
       );
@@ -642,7 +1220,7 @@ function sessionLines(session) {
     lines.push(`  Payments:    ${session.vp_tx_count}`);
     if (session.vp_tx_count >= 2) {
       lines.push(
-        chalk5.red(
+        chalk6.red(
           `  \u26A0 Charged ${session.vp_tx_count} times: there is no single refund id. Have a person check the payments before refunding or fulfilling.`
         )
       );
@@ -652,12 +1230,44 @@ function sessionLines(session) {
   lines.push(`  Expires:     ${session.expiresAt}`);
   return lines;
 }
+function redirectHost(url) {
+  if (url === void 0) return "none given (the account default)";
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return "[not a valid address]";
+  }
+  const host = parsed.hostname;
+  if (host === "") return "[not a web address]";
+  if (host.length > 253) return "[host too long]";
+  if (!/^([a-z0-9-]{1,63}\.)*[a-z0-9-]{1,63}$/.test(host) && !/^\[[0-9a-f:.]+\]$/.test(host)) return "[unrecognised host withheld]";
+  return parsed.port ? `${host}:${parsed.port}` : host;
+}
 function sessionsCommand() {
   const sessions = new Command4("sessions").description(
     "Create and manage checkout sessions"
   );
-  sessions.command("create").description("Create a new checkout session").requiredOption("--amount <cents>", "Amount in minor units, a whole number (e.g. 1499 = $14.99)").requiredOption("--currency <code>", "Currency code (e.g. USD)").option("--country <code>", "Country code (e.g. US)").option("--description <text>", "Session description").option("--success-url <url>", "Redirect URL on success").option("--cancel-url <url>", "Redirect URL on cancel").option("--idempotency-key <key>", "Idempotency key for safe retries").option("--dry-run", "Validate without creating a session").option("--json", "Output raw JSON (the session's client secret masked, see --show-secrets)").option("--show-secrets", SHOW_SECRETS_HELP).action(async (opts) => {
+  sessions.command("create").description("Create a new checkout session").requiredOption("--amount <cents>", "Amount in minor units, a whole number (e.g. 1499 = $14.99)").requiredOption("--currency <code>", "Currency code (e.g. USD)").option("--country <code>", "Country code (e.g. US)").option("--description <text>", "Session description").option("--success-url <url>", "Redirect URL on success").option("--cancel-url <url>", "Redirect URL on cancel").option("--idempotency-key <key>", "Idempotency key for safe retries").option("--dry-run", "Validate without creating a session").addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON (the session's client secret masked, see --show-secrets)").option("--show-secrets", SHOW_SECRETS_HELP).action(async (opts) => {
     const amount = minorUnitsOrExit(String(opts.amount), "--amount");
+    if (!opts.dryRun) {
+      const apiKey = requireApiKey();
+      refuseUnsafeLiveDestination(apiKey);
+      await confirmLiveAction(
+        apiKey,
+        {
+          action: "create a checkout session (a payment page a buyer can pay)",
+          details: [
+            ...apiHostDetail(),
+            ["Amount", formatMinorUnits(amount, String(opts.currency).toUpperCase())],
+            ["After paying, to", redirectHost(opts.successUrl)],
+            ["If cancelled, to", redirectHost(opts.cancelUrl)]
+          ],
+          consequence: "A buyer can pay real money on this page until it expires."
+        },
+        opts
+      );
+    }
     const client = makeClient();
     const spinner = startSpinner("Creating session...");
     try {
@@ -676,14 +1286,14 @@ function sessionsCommand() {
         if (opts.json) {
           console.log(JSON.stringify(result, null, 2));
         } else if (result.valid) {
-          console.log(chalk5.green("\u2713 Valid request"));
+          console.log(chalk6.green("\u2713 Valid request"));
           if (result.warnings.length > 0) {
             for (const w of result.warnings) {
-              console.log(chalk5.yellow(`  \u26A0 ${w}`));
+              console.log(chalk6.yellow(`  \u26A0 ${w}`));
             }
           }
         } else {
-          console.log(chalk5.red("\u2717 Invalid request"));
+          console.log(chalk6.red("\u2717 Invalid request"));
         }
         return;
       }
@@ -695,9 +1305,9 @@ function sessionsCommand() {
       if (opts.json) {
         console.log(sessionJson(session, opts.showSecrets));
       } else {
-        console.log(chalk5.green("\u2713 Session created"));
+        console.log(chalk6.green("\u2713 Session created"));
         console.log(`  ID:       ${session.id}`);
-        console.log(`  URL:      ${chalk5.cyan(session.checkoutUrl)}`);
+        console.log(`  URL:      ${chalk6.cyan(session.checkoutUrl)}`);
         console.log(`  Expires:  ${session.expiresAt}`);
       }
     } catch (err) {
@@ -726,28 +1336,37 @@ function sessionsCommand() {
 
 // src/commands/payment-intents.ts
 import { Command as Command5 } from "commander";
-import chalk8 from "chalk";
-import { formatMinorUnits as formatMinorUnits2 } from "@vonpay/checkout-node";
+import chalk9 from "chalk";
+import { formatMinorUnits as formatMinorUnits3 } from "@vonpay/checkout-node";
 
 // src/utils/idempotency.ts
 import { randomUUID } from "crypto";
-import chalk6 from "chalk";
+import chalk7 from "chalk";
 function resolveIdempotencyKey(flag) {
   const given = flag?.trim();
   if (given) return { key: given, generated: false };
   return { key: `cli-${randomUUID()}`, generated: true };
 }
-function idempotencyKeyFor(flag, what) {
+function idempotencyKeyFor(flag, what, apiKey) {
   const { key, generated } = resolveIdempotencyKey(flag);
+  if (generated && apiKey !== void 0 && requiresLiveConfirmation(apiKey)) {
+    const message = `Refusing to send this ${what} with a live key without --idempotency-key. Choose one key for this ${what} (for example your order id plus the action, such as "order_1042:${what}") and pass the SAME key if you ever run the command again: a new key is a new action and can move money twice. Nothing was sent.`;
+    auditNote({ outcome: "refused_local", code: "idempotency_key_required" });
+    exitWithCliError(message, chalk7.red(message));
+  }
   if (generated) {
     console.error(
-      chalk6.dim(
+      chalk7.dim(
         `Idempotency key: ${key} (to retry this same ${what}, re-run with --idempotency-key ${key})`
       )
     );
   }
   return key;
 }
+var DISPLAYABLE_KEY = /^[A-Za-z0-9_:.-]{1,64}$/;
+function displayIdempotencyKey(key) {
+  return DISPLAYABLE_KEY.test(key) ? key : "[custom key withheld]";
+}
 
 // src/utils/metadata.ts
 var MAX_LEN = 256;
@@ -788,80 +1407,268 @@ function parseMetadata(pairs) {
   }
   return out;
 }
-
-// src/utils/live-key.ts
-import { createInterface as createInterface2 } from "readline";
-import chalk7 from "chalk";
-import { Option as Option2 } from "commander";
-import { isLiveKey as isLiveKey2 } from "@vonpay/checkout-node";
-var CONFIRM_WORD = "confirm";
-var terminal = {
-  /**
-   * Both stdin and stdout are a terminal. A command run by a script, a CI job or
-   * an AI agent's shell tool has at least one of them piped.
-   */
-  isInteractive() {
-    return process.stdin.isTTY === true && process.stdout.isTTY === true;
-  },
-  /** Ask one line on the terminal. End of input or Ctrl-C answers "" (cancel). */
-  ask(prompt) {
-    return new Promise((resolve2) => {
-      const rl = createInterface2({ input: process.stdin, output: process.stdout });
-      let answered = false;
-      rl.on("SIGINT", () => rl.close());
-      rl.on("close", () => {
-        if (!answered) resolve2("");
-      });
-      rl.question(prompt, (answer) => {
-        answered = true;
-        rl.close();
-        resolve2(answer);
-      });
-    });
+var METADATA_FILTER_KEY = /^[A-Za-z0-9_.:-]{1,64}$/;
+var METADATA_FILTER_VALUE_MAX = 500;
+function assertMetadataFilterKey(key, flag) {
+  if (!METADATA_FILTER_KEY.test(key)) {
+    throw new Error(
+      `${flag}: the metadata key must be 1-64 letters, digits, _ . : or - (the API's pattern ^[A-Za-z0-9_.:-]{1,64}$); got ${JSON.stringify(key.slice(0, 80))}.`
+    );
   }
-};
-function keyFingerprint(key) {
-  const m = key.match(/^(vp_sk_live_)([A-Za-z0-9_-]{0,4})/);
-  return m ? `${m[1]}${m[2]}\u2026` : "a key that is not a sandbox key";
+  return key;
 }
-async function confirmLiveAction(key, summary, opts = {}) {
-  if (!requiresLiveConfirmation(key)) return;
-  if (!terminal.isInteractive()) {
-    const message = `Refusing to ${summary.action} with a live key: no person is at an interactive terminal to confirm it. A live-key action must be confirmed by a person typing at a terminal (stdin and stdout both a terminal); scripts, CI jobs and AI agents cannot confirm it, and --confirm-live is no longer enough. Use a sandbox key (vp_sk_test_\u2026) for automation, or run the command yourself in a terminal. Nothing was sent.`;
-    exitWithCliError(message, chalk7.red(message));
+function parseMetadataFilter(raw, flag) {
+  const idx = raw.indexOf("=");
+  if (idx === -1) throw new Error(`${flag}: expected key=value (ONE tag); got ${JSON.stringify(raw.slice(0, 80))}.`);
+  const key = assertMetadataFilterKey(raw.slice(0, idx), flag);
+  const value = raw.slice(idx + 1);
+  if (value.length < 1 || value.length > METADATA_FILTER_VALUE_MAX) {
+    throw new Error(`${flag}: the value must be 1-${METADATA_FILTER_VALUE_MAX} characters; got ${value.length}.`);
   }
-  if (opts.confirmLive) {
-    console.warn(
-      chalk7.yellow(
-        "Note: --confirm-live no longer confirms a live action by itself. A person confirms it at the terminal."
-      )
+  return { [key]: value };
+}
+
+// src/commands/payment-reports.ts
+import chalk8 from "chalk";
+import { formatMinorUnits as formatMinorUnits2 } from "@vonpay/checkout-node";
+
+// src/utils/list-flag.ts
+function parseListFlag(raw, flag, options = {}) {
+  const items = raw.split(",").map((s) => options.lowercase ? s.trim().toLowerCase() : s.trim());
+  if (items.length === 0 || items.some((s) => s.length === 0)) {
+    throw new Error(`${flag} must be a comma-separated list with no empty items; got ${JSON.stringify(raw)}.`);
+  }
+  return [...new Set(items)];
+}
+
+// src/commands/payment-reports.ts
+function buildFilters(opts) {
+  const filters = {};
+  if (opts.createdGte !== void 0) filters.createdGte = opts.createdGte;
+  if (opts.createdLt !== void 0) filters.createdLt = opts.createdLt;
+  if (opts.outcome !== void 0) filters.outcome = parseListFlag(opts.outcome, "--outcome", { lowercase: true });
+  if (opts.store !== void 0) filters.store = opts.store;
+  if (opts.metadata !== void 0) filters.metadata = parseMetadataFilter(opts.metadata, "--metadata");
+  if (opts.cardBrand !== void 0) {
+    filters.cardBrand = parseListFlag(opts.cardBrand, "--card-brand", { lowercase: true });
+  }
+  if (opts.currency !== void 0) filters.currency = opts.currency.toUpperCase();
+  if (opts.initiator !== void 0) {
+    const initiator = opts.initiator.toLowerCase();
+    if (initiator !== "customer" && initiator !== "merchant") {
+      throw new Error(`--initiator must be customer or merchant; got ${JSON.stringify(opts.initiator)}.`);
+    }
+    filters.initiator = initiator;
+  }
+  if (opts.declineCode !== void 0) {
+    filters.declineCode = parseListFlag(opts.declineCode, "--decline-code", { lowercase: true });
+  }
+  return filters;
+}
+function wholeNumber2(raw, flag) {
+  const parsed = parseMinorUnits(raw, flag);
+  if (!parsed.ok || parsed.value < 1) throw new Error(`${flag} must be a whole number of at least 1; got ${JSON.stringify(raw)}.`);
+  return parsed.value;
+}
+var PAYMENT_LIST_JSON_FIELDS = [
+  "id",
+  "status",
+  "outcome",
+  "failureClass",
+  "amount",
+  "currency",
+  "captureMethod",
+  "createdAt",
+  "updatedAt",
+  "store",
+  "card",
+  "declineCode",
+  "action",
+  "ruleCode",
+  "networkAdvice"
+];
+function listItemJson(pi, includeMetadata) {
+  if (includeMetadata) return pi;
+  const src = pi;
+  return Object.fromEntries(PAYMENT_LIST_JSON_FIELDS.filter((k) => src[k] !== void 0).map((k) => [k, src[k]]));
+}
+var ALL_JSON_DEFAULT_MAX_ITEMS = 1e4;
+function buildListParams(opts) {
+  const params = buildFilters(opts);
+  if (opts.status !== void 0) {
+    params.status = parseListFlag(opts.status, "--status", { lowercase: true });
+  }
+  if (opts.limit !== void 0) params.limit = wholeNumber2(opts.limit, "--limit");
+  if (opts.startingAfter !== void 0) params.startingAfter = opts.startingAfter;
+  if (opts.maxItems !== void 0 && !opts.all) throw new Error("--max-items is used with --all.");
+  if (opts.includeMetadata && !opts.json) throw new Error("--include-metadata is used with --json.");
+  const maxItems = opts.maxItems !== void 0 ? wholeNumber2(opts.maxItems, "--max-items") : opts.all && opts.json ? ALL_JSON_DEFAULT_MAX_ITEMS : void 0;
+  return { params, ...maxItems !== void 0 ? { maxItems } : {} };
+}
+function buildSummaryParams(opts) {
+  const params = buildFilters(opts);
+  if (opts.groupBy !== void 0) {
+    params.groupBy = parseListFlag(opts.groupBy, "--group-by", { lowercase: true });
+  }
+  if (opts.groupByMetadataKey !== void 0) {
+    params.groupByMetadataKey = assertMetadataFilterKey(opts.groupByMetadataKey, "--group-by-metadata-key");
+  }
+  if (opts.timeZone !== void 0) params.timeZone = opts.timeZone;
+  return params;
+}
+function outcomeTone(outcome) {
+  if (outcome === "approved") return chalk8.green(outcome);
+  if (outcome === "authorized" || outcome === "in_progress" || outcome === "voided") return chalk8.yellow(outcome);
+  return chalk8.red(outcome);
+}
+function paymentListItemLine(pi) {
+  const card = pi.card.brand || pi.card.last4 ? `  ${safeInline(pi.card.brand ?? "card")} ${pi.card.last4 ? `\u2022\u2022\u2022\u2022 ${safeInline(pi.card.last4)}` : ""}`.trimEnd() : "";
+  return `  ${safeInline(pi.id)}  ${outcomeTone(safeInline(pi.outcome))}  ${safeInline(formatMinorUnits2(pi.amount, pi.currency))}  ${safeInline(pi.createdAt)}` + (pi.store ? `  ${safeInline(pi.store)}` : "") + card + (pi.declineCode ? `  ${safeInline(pi.declineCode)}` : "");
+}
+function paymentListLines(page) {
+  const lines = [`  Window: ${safeInline(page.created.gte)} to ${safeInline(page.created.lt)} (end exclusive)`];
+  if (page.data.length === 0) lines.push("  No payments match.");
+  for (const pi of page.data) lines.push(paymentListItemLine(pi));
+  if (page.hasMore && page.nextCursor) {
+    lines.push(
+      `  More: re-run with exactly the same filters (and window, or none if you gave none) and --starting-after ${safeInline(page.nextCursor, 1100)} \u2014 the cursor lasts 24 hours; or use --all`
     );
   }
+  return lines;
+}
+function formatRate(rate) {
+  return rate === null ? "no data" : `${(rate * 100).toFixed(1)}%`;
+}
+function metricsLine(m) {
+  return `attempts ${m.counts.attempts}  approved ${m.counts.approved}  declined ${m.counts.declined}  approval ${formatRate(m.rates.approvalRate)}  bank decline ${formatRate(m.rates.bankDeclineRate)}  decline ${formatRate(m.rates.declineRate)}`;
+}
+function summaryLines(s) {
+  const age = typeof s.ageSeconds === "number" ? `, ${s.ageSeconds} s ago` : "";
   const lines = [
-    chalk7.bold.red(`You are about to ${summary.action} with a LIVE key (${keyFingerprint(key)}).`),
-    ...(summary.details ?? []).map(([label, value]) => `  ${`${label}:`.padEnd(17)}${safeDisplay(value)}`),
-    chalk7.yellow(summary.consequence ?? "This moves real money and cannot be undone from here.")
+    `  Payment attempts (as the dashboard counts them), ${safeInline(s.created.gte)} to ${safeInline(s.created.lt)}, time zone ${safeInline(s.timeZone)}`,
+    `  Computed at ${safeInline(s.generatedAt)}${age} (a summary is kept 45 s: for fresh numbers change the window or wait)`,
+    `  Total: ${metricsLine(s.totals)}`
   ];
-  for (const line of lines) console.log(line);
-  const answer = await terminal.ask(`Type "${CONFIRM_WORD}" to proceed, anything else to cancel: `);
-  if (answer.trim() !== CONFIRM_WORD) {
-    const message = `Cancelled: you did not type "${CONFIRM_WORD}". Nothing was sent.`;
-    exitWithCliError(message, chalk7.red(message));
+  for (const a of s.totals.amounts) {
+    lines.push(
+      `    ${safeInline(a.currency)}: approved ${safeInline(formatMinorUnits2(a.approved, a.currency))}, declined ${safeInline(formatMinorUnits2(a.declined, a.currency))}`
+    );
   }
+  for (const g of s.groups) {
+    const key = Object.entries(g.key).map(([dimension, value]) => `${safeInline(dimension)}=${value === null ? "(none)" : safeInline(value, 80)}`).join(" ");
+    lines.push(`  ${key}: ${metricsLine(g)}`);
+  }
+  if (s.groupBy.length > 0) lines.push("  Only groups with at least one attempt are shown. Add counts to combine groups; never average rates.");
+  return lines;
 }
-function retiredConfirmLiveOption() {
-  return new Option2(
-    "--confirm-live",
-    "No longer confirms anything: a live-key action is confirmed by a person at the terminal"
-  ).hideHelp();
+var FILTER_HELP = {
+  createdGte: "Start of the window, inclusive: Unix seconds or an ISO-8601 time with a zone (default: 31 days before the end; 7 with summary --group-by hour)",
+  createdLt: "End of the window, exclusive (default: now). At most 31 days after the start (7 with summary --group-by hour)",
+  outcome: "Only these outcomes, comma-separated (e.g. bank_declined,refused_before_bank)",
+  store: "Only payments for this connected store hostname (e.g. shop.example.com)",
+  metadata: "Only payments with this metadata tag, key=value (ONE tag; key 1-64 of letters, digits, _ . : -; value 1-500 characters)",
+  cardBrand: "Only these card brands, comma-separated (visa, mastercard, amex, discover, unionpay, jcb, diners, unknown)",
+  currency: "Only payments in this currency (e.g. USD)",
+  initiator: "merchant (merchant-initiated charges on a saved card) or customer",
+  declineCode: "Only declined payments with these decline codes, comma-separated (e.g. insufficient_funds)"
+};
+function addFilterOptions(cmd) {
+  return cmd.option("--created-gte <time>", FILTER_HELP.createdGte).option("--created-lt <time>", FILTER_HELP.createdLt).option("--outcome <list>", FILTER_HELP.outcome).option("--store <hostname>", FILTER_HELP.store).option("--metadata <key=value>", FILTER_HELP.metadata).option("--card-brand <list>", FILTER_HELP.cardBrand).option("--currency <code>", FILTER_HELP.currency).option("--initiator <who>", FILTER_HELP.initiator).option("--decline-code <list>", FILTER_HELP.declineCode);
 }
-function warnLiveSecretFlag(key, flag) {
-  if (!requiresLiveConfirmation(key)) return;
-  console.warn(
-    chalk7.yellow(
-      `Warning: passing ${flag} as a command argument with a live key exposes it to shell history and process-list (\`ps\`). Consider piping or env-injecting the value instead.`
+function exitOnBadFlag(err) {
+  const message = err.message;
+  exitWithCliError(message, chalk8.red(`Error: ${message}`));
+}
+function addPaymentReportCommands(intents) {
+  addFilterOptions(
+    intents.command("list").description(
+      "List payment intents, newest first, with filters \u2014 raw data. For approval and decline rates use `payment-intents summary`"
     )
-  );
+  ).option("--status <list>", "Only these statuses, comma-separated (e.g. failed,succeeded)").option("--limit <n>", "Page size, up to 100 per page (default 25; larger values are treated as 100)").option(
+    "--starting-after <cursor>",
+    "The next-page cursor printed by a previous run, unchanged, with exactly the same filters and window (it lasts 24 hours)"
+  ).option("--all", "Read every page, one request at a time (text: printed as each payment arrives)").option("--max-items <n>", `With --all: stop after this many payments (with --json, default ${ALL_JSON_DEFAULT_MAX_ITEMS})`).option(
+    "--json",
+    "Output JSON: each payment's status, outcome, amount, card, store and decline fields \u2014 not your metadata (with --all: one JSON array)"
+  ).option("--include-metadata", "With --json: print every field of each payment, your metadata included").action(async (opts) => {
+    let built;
+    try {
+      built = buildListParams(opts);
+    } catch (err) {
+      exitOnBadFlag(err);
+    }
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Listing payment intents...");
+    try {
+      if (opts.all) {
+        const pager = client.paymentIntents.listAutoPaging({
+          ...built.params,
+          ...built.maxItems ? { maxItems: built.maxItems } : {}
+        });
+        if (opts.json) {
+          const items = [];
+          for await (const pi of pager) items.push(listItemJson(pi, opts.includeMetadata));
+          spinner.stop();
+          console.log(JSON.stringify(items, null, 2));
+          if (opts.maxItems === void 0 && items.length >= ALL_JSON_DEFAULT_MAX_ITEMS) {
+            console.error(
+              `Stopped at ${ALL_JSON_DEFAULT_MAX_ITEMS} payments (the --all --json default). Pass --max-items to read more, or narrow the window.`
+            );
+          }
+          return;
+        }
+        let count = 0;
+        for await (const pi of pager) {
+          if (count === 0) spinner.stop();
+          console.log(paymentListItemLine(pi));
+          count += 1;
+        }
+        spinner.stop();
+        if (count === 0) console.log("  No payments match.");
+        console.log(`  ${count} payment(s).`);
+        return;
+      }
+      const page = await client.paymentIntents.list(built.params);
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify({ ...page, data: page.data.map((pi) => listItemJson(pi, opts.includeMetadata)) }, null, 2));
+        return;
+      }
+      for (const line of paymentListLines(page)) console.log(line);
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+  addFilterOptions(
+    intents.command("summary").description(
+      "Approval and decline rates, counts and amounts for a window, as the dashboard counts payment attempts. A rate with no traffic shows as no data, never 0%. A summary is kept 45 s: for fresh numbers, change the window or wait"
+    )
+  ).option("--group-by <list>", "Up to 3 of hour, day, week, store, metadata, card_brand, currency, outcome, decline_code (one time unit)").option(
+    "--group-by-metadata-key <key>",
+    "With --group-by metadata: the metadata key whose values become groups (1-64 of letters, digits, _ . : -)"
+  ).option("--time-zone <iana>", "Time zone for hour / day / week buckets (default UTC), e.g. America/New_York").option("--json", "Output raw JSON").action(async (opts) => {
+    let params;
+    try {
+      params = buildSummaryParams(opts);
+    } catch (err) {
+      exitOnBadFlag(err);
+    }
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Summarizing payments...");
+    try {
+      const summary = await client.paymentIntents.summary(params);
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+      }
+      for (const line of summaryLines(summary)) console.log(line);
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
 }
 
 // src/commands/payment-intents.ts
@@ -940,28 +1747,28 @@ function statusTone(status) {
   return "gray";
 }
 function printPaymentIntent(intent) {
-  const statusColor = chalk8[statusTone(intent.status)];
+  const statusColor = chalk9[statusTone(intent.status)];
   console.log(`  ID:           ${intent.id}`);
   console.log(`  Status:       ${statusColor(intent.status)}`);
   console.log(
-    `  Amount:       ${formatMinorUnits2(intent.amount, intent.currency)}`
+    `  Amount:       ${formatMinorUnits3(intent.amount, intent.currency)}`
   );
   console.log(`  Capture:      ${intent.captureMethod}`);
   if (intent.nextAction) {
     console.log(
-      `  Next action:  ${chalk8.yellow(safeDisplay(intent.nextAction.type))}`
+      `  Next action:  ${chalk9.yellow(safeDisplay(intent.nextAction.type))}`
     );
     if (intent.nextAction.type === "redirect_to_url") {
       console.log(
-        `  Redirect:     ${chalk8.yellow(safeDisplay(intent.nextAction.redirectToUrl.url))}`
+        `  Redirect:     ${chalk9.yellow(safeDisplay(intent.nextAction.redirectToUrl.url))}`
       );
     }
   }
   if (intent.declineCode) {
-    console.log(`  Decline code: ${chalk8.red(safeDisplay(intent.declineCode))}`);
+    console.log(`  Decline code: ${chalk9.red(safeDisplay(intent.declineCode))}`);
   }
   if (intent.networkAdvice) {
-    console.log(`  Network advice: ${chalk8.red(safeInline(intent.networkAdvice))}`);
+    console.log(`  Network advice: ${chalk9.red(safeInline(intent.networkAdvice))}`);
     if (typeof intent.networkAdviceRetryAfterMs === "number") {
       console.log(`  Retry after:  ${intent.networkAdviceRetryAfterMs} ms (earliest)`);
     }
@@ -999,14 +1806,14 @@ function paymentIntentsCommand() {
     "Your customer reference. Send on EVERY saved-card charge \u2014 it is what makes the server reject a charge against the wrong customer's stored card"
   ).option("--buyer-email <email>", "Buyer email for this charge").option(
     "--idempotency-key <key>",
-    "Idempotency key for this charge. Reuse the SAME key to retry the same charge safely. Generated (and printed) when omitted"
+    "Idempotency key for this charge. Reuse the SAME key to retry the same charge safely. REQUIRED on a live key; on a sandbox key generated (and printed) when omitted"
   ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(async (raw) => {
     const apiKey = requireApiKey();
     const opts = { ...raw, amount: minorUnitsOrExit(raw.amount, "--amount") };
     const captureMethod = opts.captureMethod?.toLowerCase();
     if (captureMethod !== void 0 && captureMethod !== "automatic" && captureMethod !== "manual") {
       const message = `Invalid --capture-method "${opts.captureMethod}". Expected automatic or manual.`;
-      exitWithCliError(message, chalk8.red(message));
+      exitWithCliError(message, chalk9.red(message));
     }
     let params;
     try {
@@ -1017,19 +1824,19 @@ function paymentIntentsCommand() {
       handleError(err);
     }
     refuseUnsafeLiveDestination(apiKey);
-    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "charge");
+    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "charge", apiKey);
     await confirmLiveAction(
       apiKey,
       {
         action: "create a payment intent (charge a payment)",
         details: [
           ...apiHostDetail(),
-          ["Amount", formatMinorUnits2(params.amount, params.currency)],
+          ["Amount", formatMinorUnits3(params.amount, params.currency)],
           ["Capture", params.captureMethod ?? "automatic"],
           ...params.paymentMethod ? [["Saved card", params.paymentMethod.id]] : [],
           ...params.buyerId ? [["Buyer", params.buyerId]] : [],
           ...params.sessionId ? [["Session", params.sessionId]] : [],
-          ["Idempotency key", idempotencyKey]
+          ["Idempotency key", displayIdempotencyKey(idempotencyKey)]
         ]
       },
       opts
@@ -1044,7 +1851,7 @@ function paymentIntentsCommand() {
       if (opts.json) {
         console.log(JSON.stringify(intent, null, 2));
       } else {
-        console.log(chalk8.green("\u2713 Payment intent created"));
+        console.log(chalk9.green("\u2713 Payment intent created"));
         printPaymentIntent(intent);
       }
     } catch (err) {
@@ -1075,7 +1882,7 @@ function paymentIntentsCommand() {
     "Partial capture amount in minor units, a whole number (omit for full)"
   ).option(
     "--idempotency-key <key>",
-    "Idempotency key. Reuse the SAME key to retry safely. Generated (and printed) when omitted"
+    "Idempotency key. Reuse the SAME key to retry safely. REQUIRED on a live key; on a sandbox key generated (and printed) when omitted"
   ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(
     async (id, opts) => {
       const apiKey = requireApiKey();
@@ -1084,7 +1891,7 @@ function paymentIntentsCommand() {
         "--amount-to-capture"
       );
       refuseUnsafeLiveDestination(apiKey);
-      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "capture");
+      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "capture", apiKey);
       await confirmLiveAction(
         apiKey,
         {
@@ -1096,7 +1903,7 @@ function paymentIntentsCommand() {
               "Amount",
               amountToCapture !== void 0 ? `${amountToCapture} in minor units (partial capture)` : "the full authorized amount"
             ],
-            ["Idempotency key", idempotencyKey]
+            ["Idempotency key", displayIdempotencyKey(idempotencyKey)]
           ]
         },
         opts
@@ -1113,8 +1920,8 @@ function paymentIntentsCommand() {
         if (opts.json) {
           console.log(JSON.stringify(intent, null, 2));
         } else {
-          const captureLabel = amountToCapture !== void 0 ? ` (partial: ${formatMinorUnits2(amountToCapture, intent.currency)})` : "";
-          console.log(chalk8.green(`\u2713 Payment intent captured${captureLabel}`));
+          const captureLabel = amountToCapture !== void 0 ? ` (partial: ${formatMinorUnits3(amountToCapture, intent.currency)})` : "";
+          console.log(chalk9.green(`\u2713 Payment intent captured${captureLabel}`));
           printPaymentIntent(intent);
         }
       } catch (err) {
@@ -1125,12 +1932,12 @@ function paymentIntentsCommand() {
   );
   intents.command("void").description("Void an authorized (uncaptured) payment intent").argument("<id>", "Payment intent ID (vpi_*)").option(
     "--idempotency-key <key>",
-    "Idempotency key. Reuse the SAME key to retry safely. Generated (and printed) when omitted"
+    "Idempotency key. Reuse the SAME key to retry safely. REQUIRED on a live key; on a sandbox key generated (and printed) when omitted"
   ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(
     async (id, opts) => {
       const apiKey = requireApiKey();
       refuseUnsafeLiveDestination(apiKey);
-      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "void");
+      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "void", apiKey);
       await confirmLiveAction(
         apiKey,
         {
@@ -1138,7 +1945,7 @@ function paymentIntentsCommand() {
           details: [
             ...apiHostDetail(),
             ["Payment intent", id],
-            ["Idempotency key", idempotencyKey]
+            ["Idempotency key", displayIdempotencyKey(idempotencyKey)]
           ],
           consequence: "A voided payment cannot be captured afterwards; this cannot be undone from here."
         },
@@ -1152,7 +1959,7 @@ function paymentIntentsCommand() {
         if (opts.json) {
           console.log(JSON.stringify(intent, null, 2));
         } else {
-          console.log(chalk8.green("\u2713 Payment intent voided"));
+          console.log(chalk9.green("\u2713 Payment intent voided"));
           printPaymentIntent(intent);
         }
       } catch (err) {
@@ -1161,13 +1968,14 @@ function paymentIntentsCommand() {
       }
     }
   );
+  addPaymentReportCommands(intents);
   return intents;
 }
 
 // src/commands/refunds.ts
 import { Command as Command6 } from "commander";
-import chalk9 from "chalk";
-import { formatMinorUnits as formatMinorUnits3 } from "@vonpay/checkout-node";
+import chalk10 from "chalk";
+import { formatMinorUnits as formatMinorUnits4, VonPayError as VonPayError2 } from "@vonpay/checkout-node";
 function present(v) {
   return v !== void 0 && v.trim() !== "";
 }
@@ -1195,8 +2003,83 @@ function buildRefundParams(opts, metadata) {
   if (metadata !== void 0) params.metadata = metadata;
   return params;
 }
+var TRANSACTION_NEEDS_SESSION_MESSAGE = "Refusing a live-key refund by --transaction without --session-id: the transaction is checked against the session it belongs to (it must be that session's single payment) before you are asked to confirm. Prefer --payment-intent when the payment has one. Nothing was sent.";
+var SESSION_WITH_PAYMENT_INTENT_MESSAGE = "--session-id is only used with --transaction. Refund a payment intent with --payment-intent alone. Nothing was sent.";
+function refundSessionProblem(target, sessionId, live) {
+  const hasSession = present(sessionId);
+  if ("paymentIntent" in target && hasSession) return SESSION_WITH_PAYMENT_INTENT_MESSAGE;
+  if ("transaction" in target && live && !hasSession) return TRANSACTION_NEEDS_SESSION_MESSAGE;
+  return null;
+}
+function errorCodeSuffix(err) {
+  const code = err instanceof VonPayError2 ? err.code : void 0;
+  return typeof code === "string" && /^[a-z_]{1,64}$/.test(code) ? ` (error code: ${code})` : "";
+}
+function refuseLookup(message) {
+  auditNote({ outcome: "lookup_refused", code: "lookup_failed" });
+  return exitWithCliError(message, chalk10.red(message));
+}
+async function refundLookupDetails(client, target, sessionId, amount, namedCurrency) {
+  const lines = [];
+  let currency;
+  if ("paymentIntent" in target) {
+    let intent;
+    try {
+      intent = await client.paymentIntents.retrieve(target.paymentIntent);
+    } catch (err) {
+      refuseLookup(`Refusing the refund: the payment intent could not be looked up${errorCodeSuffix(err)}, so it cannot be shown to you before you confirm. Nothing was sent.`);
+    }
+    currency = intent.currency;
+    lines.push(
+      ["Original payment", formatMinorUnits4(intent.amount, intent.currency)],
+      ["Status", String(intent.status)],
+      ["Created", String(intent.createdAt)]
+    );
+  } else {
+    let session;
+    try {
+      session = await client.sessions.get(sessionId);
+    } catch (err) {
+      refuseLookup(`Refusing the refund: the session could not be looked up${errorCodeSuffix(err)}, so the transaction cannot be checked against it. Nothing was sent.`);
+    }
+    if (session.vp_tx_count !== 1) {
+      refuseLookup(
+        typeof session.vp_tx_count === "number" && session.vp_tx_count >= 2 ? "Refusing the refund: this session has more than one payment \u2014 the buyer may have been charged more than once. Do not refund anything; have a person check the payments. Nothing was sent." : "Refusing the refund: the session does not show exactly one captured payment, so the transaction cannot be checked against it. Nothing was sent."
+      );
+    }
+    if (session.vp_tx_id !== target.transaction) {
+      refuseLookup("Refusing the refund: that transaction is not this session's payment. Check the order in your own records. Nothing was sent.");
+    }
+    currency = session.currency;
+    lines.push(
+      ["Session total", formatMinorUnits4(session.amount, session.currency)],
+      ["Payment", String(session.paymentStatus ?? "not reported")],
+      ["Created", String(session.createdAt)]
+    );
+  }
+  let totals;
+  try {
+    totals = await client.refunds.list(target, { limit: 1 });
+  } catch (err) {
+    refuseLookup(`Refusing the refund: the payment's earlier refunds could not be looked up${errorCodeSuffix(err)}, so what was already refunded cannot be shown to you. Nothing was sent.`);
+  }
+  lines.push(
+    ["Already refunded", formatMinorUnits4(totals.amountRefunded, currency)],
+    [
+      "Still refundable",
+      `${formatMinorUnits4(totals.remainingRefundable, currency)}${totals.refundable ? "" : " \u2014 Von Payments says this payment cannot be refunded now"}`
+    ]
+  );
+  if (amount !== void 0 && amount > totals.remainingRefundable) {
+    lines.push(["\u26A0 Check", "the amount to refund is MORE than what is still refundable"]);
+  }
+  if (namedCurrency !== void 0 && typeof currency === "string" && namedCurrency.toUpperCase() !== currency.toUpperCase()) {
+    lines.push(["\u26A0 Check", "the currency named for this refund is NOT the payment's currency looked up above"]);
+  }
+  return lines;
+}
 function printRefund(refund) {
-  const statusColor = refund.status === "succeeded" ? chalk9.green : refund.status === "failed" ? chalk9.red : chalk9.yellow;
+  const statusColor = refund.status === "succeeded" ? chalk10.green : refund.status === "failed" ? chalk10.red : chalk10.yellow;
   console.log(`  ID:             ${refund.id}`);
   if (refund.transaction !== null) {
     console.log(`  Transaction:    ${refund.transaction}`);
@@ -1205,7 +2088,7 @@ function printRefund(refund) {
   }
   console.log(`  Status:         ${statusColor(refund.status)}`);
   console.log(
-    `  Amount:         ${formatMinorUnits3(refund.amount, refund.currency)}`
+    `  Amount:         ${formatMinorUnits4(refund.amount, refund.currency)}`
   );
   if (refund.reason) {
     console.log(`  Reason:         ${safeDisplay(refund.reason)}`);
@@ -1229,15 +2112,18 @@ function refundsCommand() {
   ).option("--currency <code>", "ISO 4217 currency code").option("--reason <text>", "Free-form reason (mirrored back on the record)").option(
     "--metadata <pair...>",
     "Metadata key=value (repeat flag for multiple pairs)"
+  ).option(
+    "--session-id <id>",
+    "With --transaction: the checkout session this payment belongs to (vp_cs_*). REQUIRED with --transaction on a live key: the transaction is checked against it (the session's single payment) before you are asked to confirm"
   ).option(
     "--idempotency-key <key>",
-    "Idempotency key. Reuse the SAME key to retry safely. Generated (and printed) when omitted"
+    "Idempotency key. Reuse the SAME key to retry safely. REQUIRED on a live key; on a sandbox key generated (and printed) when omitted"
   ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(async (raw) => {
     try {
       resolveRefundTarget(raw);
     } catch (err) {
       const message = err.message;
-      exitWithCliError(message, chalk9.red(`Error: ${message}`));
+      exitWithCliError(message, chalk10.red(`Error: ${message}`));
     }
     const apiKey = requireApiKey();
     const opts = {
@@ -1251,8 +2137,11 @@ function refundsCommand() {
       handleError(err);
     }
     const target = resolveRefundTarget(opts);
+    const sessionProblem = refundSessionProblem(target, opts.sessionId, requiresLiveConfirmation(apiKey));
+    if (sessionProblem) exitWithCliError(sessionProblem, chalk10.red(sessionProblem));
     refuseUnsafeLiveDestination(apiKey);
-    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "refund");
+    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "refund", apiKey);
+    const lookedUp = requiresLiveConfirmation(apiKey) && terminal.isInteractive() ? await refundLookupDetails(makeCheckoutClient(), target, opts.sessionId?.trim(), params.amount, params.currency) : [];
     await confirmLiveAction(
       apiKey,
       {
@@ -1262,9 +2151,10 @@ function refundsCommand() {
           "transaction" in target ? ["Transaction", target.transaction] : ["Payment intent", target.paymentIntent],
           [
             "Amount",
-            params.amount === void 0 ? "the full remaining balance" : params.currency ? formatMinorUnits3(params.amount, params.currency) : `${params.amount} in minor units`
+            params.amount === void 0 ? "the full remaining balance" : params.currency ? formatMinorUnits4(params.amount, params.currency) : `${params.amount} in minor units`
           ],
-          ["Idempotency key", idempotencyKey]
+          ...lookedUp,
+          ["Idempotency key", displayIdempotencyKey(idempotencyKey)]
         ],
         consequence: "This pays money back out of the merchant's balance and cannot be reversed once settled."
       },
@@ -1278,7 +2168,7 @@ function refundsCommand() {
       if (opts.json) {
         console.log(JSON.stringify(refund, null, 2));
       } else {
-        console.log(chalk9.green("\u2713 Refund created"));
+        console.log(chalk10.green("\u2713 Refund created"));
         printRefund(refund);
       }
     } catch (err) {
@@ -1295,14 +2185,14 @@ function refundsCommand() {
         target = resolveRefundTarget(opts);
       } catch (err) {
         const message = err.message.replace("A refund target is required", "A payment is required");
-        exitWithCliError(message, chalk9.red(`Error: ${message}`));
+        exitWithCliError(message, chalk10.red(`Error: ${message}`));
       }
       let limit;
       if (opts.limit !== void 0) {
         const parsed = parseMinorUnits(opts.limit, "--limit");
         if (!parsed.ok || parsed.value < 1) {
           const message = `--limit must be a whole number from 1 to 100; got ${JSON.stringify(opts.limit)}.`;
-          exitWithCliError(message, chalk9.red(`Error: ${message}`));
+          exitWithCliError(message, chalk10.red(`Error: ${message}`));
         }
         limit = parsed.value;
       }
@@ -1329,7 +2219,7 @@ function refundsCommand() {
 }
 function refundListLines(list) {
   const currency = list.data[0]?.currency;
-  const money = (n) => currency ? formatMinorUnits3(n, currency) : `${n} in minor units`;
+  const money = (n) => currency ? formatMinorUnits4(n, currency) : `${n} in minor units`;
   const lines = [
     `  Refunded so far:  ${money(list.amountRefunded)} (succeeded + still in progress)`,
     `  Still refundable: ${money(list.remainingRefundable)}${list.refundable ? "" : " \u2014 this payment cannot be refunded now"}`
@@ -1338,13 +2228,13 @@ function refundListLines(list) {
     lines.push("  No refunds on this payment.");
   }
   for (const r of list.data) {
-    const status = r.status === "succeeded" ? chalk9.green(r.status) : r.status === "failed" ? chalk9.red(r.status) : chalk9.yellow(r.status);
+    const status = r.status === "succeeded" ? chalk10.green(r.status) : r.status === "failed" ? chalk10.red(r.status) : chalk10.yellow(r.status);
     lines.push(
-      `  ${r.id}  ${status}  ${formatMinorUnits3(r.amount, r.currency)}` + (r.createdAt ? `  ${r.createdAt}` : "") + (r.idempotencyKey ? `  key ${safeDisplay(r.idempotencyKey)}` : "")
+      `  ${r.id}  ${status}  ${formatMinorUnits4(r.amount, r.currency)}` + (r.createdAt ? `  ${r.createdAt}` : "") + (r.idempotencyKey ? `  key ${safeDisplay(r.idempotencyKey)}` : "")
     );
   }
   if (list.data.some((r) => r.status === "requested")) {
-    lines.push(chalk9.yellow("  A refund marked requested is still in progress and can still fail: do not refund again."));
+    lines.push(chalk10.yellow("  A refund marked requested is still in progress and can still fail: do not refund again."));
   }
   if (list.hasMore && list.nextCursor) {
     lines.push(`  More: re-run with --starting-after ${safeDisplay(list.nextCursor)}`);
@@ -1354,9 +2244,9 @@ function refundListLines(list) {
 
 // src/commands/tokens.ts
 import { Command as Command7 } from "commander";
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 function printToken(token) {
-  const statusColor = token.status === "active" ? chalk10.green : token.status === "expired" ? chalk10.yellow : chalk10.red;
+  const statusColor = token.status === "active" ? chalk11.green : token.status === "expired" ? chalk11.yellow : chalk11.red;
   console.log(`  ID:        ${token.id}`);
   console.log(`  Status:    ${statusColor(token.status)}`);
   const card = formatTokenCard(token.card);
@@ -1378,7 +2268,7 @@ function tokensCommand() {
       const apiKey = requireApiKey();
       if (!opts.buyerId && !opts.providerReference) {
         console.warn(
-          chalk10.yellow(
+          chalk11.yellow(
             "Warning: no --buyer-id or --provider-reference supplied. Providers with an iframe vault (sandbox and live alike) will fail with a 422 validation_error."
           )
         );
@@ -1404,7 +2294,7 @@ function tokensCommand() {
         if (opts.json) {
           console.log(JSON.stringify(token, null, 2));
         } else {
-          console.log(chalk10.green("\u2713 Token created"));
+          console.log(chalk11.green("\u2713 Token created"));
           printToken(token);
         }
       } catch (err) {
@@ -1423,33 +2313,33 @@ function formatTokenCard(card) {
 
 // src/commands/capabilities.ts
 import { Command as Command8 } from "commander";
-import chalk11 from "chalk";
+import chalk12 from "chalk";
 function fmtBool(v) {
-  return v ? chalk11.green("yes") : chalk11.dim("no");
+  return v ? chalk12.green("yes") : chalk12.dim("no");
 }
 function fmtVoidPolicy(v) {
   switch (v) {
     case "supported":
-      return chalk11.green(v);
+      return chalk12.green(v);
     case "rerouted_to_refund":
-      return chalk11.yellow(v);
+      return chalk12.yellow(v);
     case "not_supported":
-      return chalk11.dim(v);
+      return chalk12.dim(v);
     default:
-      return chalk11.dim(String(v));
+      return chalk12.dim(String(v));
   }
 }
 function fmtDisputeReporting(v) {
-  return v === "tracked" ? chalk11.green(v) : chalk11.yellow(v);
+  return v === "tracked" ? chalk12.green(v) : chalk12.yellow(v);
 }
 function fmtSubscriptionBilling(v) {
-  if (v === true) return chalk11.yellow("yes");
-  if (v === false) return chalk11.green("no");
-  return chalk11.yellow("unknown");
+  if (v === true) return chalk12.yellow("yes");
+  if (v === false) return chalk12.green("no");
+  return chalk12.yellow("unknown");
 }
 function printCapabilities(caps) {
   const ops = caps.supportedOperations;
-  console.log(chalk11.bold("Supported operations"));
+  console.log(chalk12.bold("Supported operations"));
   console.log(`  auth/capture separation:  ${fmtBool(ops.authCaptureSeparation)}`);
   console.log(`  partial capture:          ${fmtBool(ops.partialCapture)}`);
   console.log(`  partial refund:           ${fmtBool(ops.partialRefund)}`);
@@ -1464,17 +2354,17 @@ function printCapabilities(caps) {
   console.log();
   if (ops.disputeReporting !== "tracked") {
     console.log(
-      chalk11.yellow(
+      chalk12.yellow(
         "  \u26A0 Chargebacks on this connection do NOT reach Von Payments.\n    A `succeeded` payment is not evidence it was never disputed.\n    Monitor and answer disputes in your processor's own dashboard \u2014\n    they carry a deadline we cannot see or report."
       )
     );
     console.log();
   }
-  console.log(chalk11.bold("Subscription billing"));
+  console.log(chalk12.bold("Subscription billing"));
   console.log(`  Von Pay renews for you:   ${fmtSubscriptionBilling(caps.subscriptionBilling?.enabled)}`);
   if (caps.subscriptionBilling?.enabled !== false) {
     console.log(
-      chalk11.yellow(
+      chalk12.yellow(
         `  \u26A0 Do not run renewals from your own system while this is not "no":
     Von Pay may be charging these customers' renewals itself, and both
     would charge them. Check again at the moment you renew.`
@@ -1482,12 +2372,12 @@ function printCapabilities(caps) {
     );
   }
   console.log();
-  console.log(chalk11.bold("Settlement currencies"));
+  console.log(chalk12.bold("Settlement currencies"));
   console.log(
-    `  ${caps.settlementCurrencies.length ? caps.settlementCurrencies.join(", ") : chalk11.dim("(none reported)")}`
+    `  ${caps.settlementCurrencies.length ? caps.settlementCurrencies.join(", ") : chalk12.dim("(none reported)")}`
   );
   console.log();
-  console.log(chalk11.bold("Rate limits"));
+  console.log(chalk12.bold("Rate limits"));
   console.log(
     `  payment intents / minute: ${caps.rateLimits.paymentIntentsPerMinute}`
   );
@@ -1514,9 +2404,41 @@ function capabilitiesCommand() {
 // src/commands/trigger.ts
 import { Command as Command9 } from "commander";
 import { createHmac as createHmac2, randomUUID as randomUUID2 } from "crypto";
-import chalk12 from "chalk";
+import chalk13 from "chalk";
 import ora2 from "ora";
 
+// src/utils/signing-secret.ts
+import { randomBytes } from "crypto";
+var SIGNING_SECRET_ENV = "VONPAY_CLI_SIGNING_SECRET";
+var SIGNING_SECRET_FLAG = "--signing-secret <secret>";
+function generateSigningSecret() {
+  return `whsec_${randomBytes(32).toString("base64url")}`;
+}
+function pinnedSecretProblem(value, from, apiKey) {
+  if (apiKey !== void 0 && apiKey !== "" && value === apiKey || /^(vp_sk_|vp_pk_|vp_key_|sk_|rk_)/.test(value)) {
+    return `${from} looks like an API key. Local deliveries are never signed with an API key: use a separate secret (for example the one this command prints when you leave ${from} out).`;
+  }
+  if (value.length < 16 || /[\s\x00-\x1f\x7f]/.test(value)) {
+    return `${from} must be at least 16 characters with no spaces or control characters.`;
+  }
+  return null;
+}
+function resolveSigningSecret(flag, env = process.env, apiKey) {
+  if (flag !== void 0) {
+    const problem = pinnedSecretProblem(flag, "--signing-secret", apiKey);
+    return problem ? { error: problem } : { secret: flag, source: "flag" };
+  }
+  const fromEnv = env[SIGNING_SECRET_ENV];
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    const problem = pinnedSecretProblem(fromEnv, SIGNING_SECRET_ENV, apiKey);
+    return problem ? { error: problem } : { secret: fromEnv, source: "env" };
+  }
+  return { secret: generateSigningSecret(), source: "generated" };
+}
+function signingSecretNotice(s) {
+  return s.source === "generated" ? `Signing secret for this run: ${s.secret} \u2014 verify the events with it (constructEvent(rawBody, signatureHeader, secret)). It changes every run; to keep one, pass --signing-secret or set ${SIGNING_SECRET_ENV}.` : `Signing with the secret from ${s.source === "flag" ? "--signing-secret" : SIGNING_SECRET_ENV} \u2014 verify the events with the same value.`;
+}
+
 // src/utils/forward-to.ts
 var LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
   "localhost",
@@ -1680,6 +2602,15 @@ var SUPPORTED_EVENTS = [
   "payment_intent.failed",
   "payment_intent.cancelled",
   "mirror.order.created",
+  // Opt-in events (an endpoint gets them only when it lists each by name).
+  // Payloads follow checkout's own "Send test event" samples, which are built
+  // by the same code as the real events.
+  "subscription.created",
+  "subscription.renewed",
+  "subscription.payment_failed",
+  "subscription.cancelled",
+  "subscription.updated",
+  "merchant.card_testing_suspected",
   "session.succeeded",
   "session.failed"
 ];
@@ -1691,7 +2622,7 @@ function warnIfUnsubscribable(event, write = (m) => console.warn(m)) {
   if (!UNSUBSCRIBABLE_EVENTS.includes(event)) return false;
   const suggestion = event === "session.succeeded" ? "charge.succeeded" : "charge.failed";
   write(
-    chalk12.yellow(
+    chalk13.yellow(
       `\u26A0  ${event} is emitted internally but is NOT subscribable.
    The subscription API accepts the key, stores nothing and returns success, so a
    real endpoint receives this event NEVER \u2014 a handler tested only against it is
@@ -1701,6 +2632,57 @@ function warnIfUnsubscribable(event, write = (m) => console.warn(m)) {
   return true;
 }
 var PROCESSOR_CONNECTION = null;
+function subscriptionEventData(event, paymentIntentId, amount, currency) {
+  const now = Math.floor(Date.now() / 1e3);
+  const inAMonth = now + 30 * 24 * 60 * 60;
+  const base = {
+    subscription_id: `vsub_test_${randomUUID2().replace(/-/g, "").slice(0, 16)}`,
+    status: "active",
+    billing_cycle: null,
+    next_bill_at: inAMonth,
+    amount: null,
+    renewal_amount: amount,
+    currency,
+    payment_intent_id: null,
+    action: null,
+    decline_message: null,
+    decline_code: null,
+    cancel_reason: null,
+    changed_fields: null,
+    // Who made the change (served since checkout's production release of 2026-10-30): an API key
+    // with no id or label on these samples. Set on every event.
+    actor: { type: "api_key", api_key_id: null, label: null },
+    // A cancel scheduled for the end of the paid period, and the discount on future
+    // renewals (served since 2026-10-30): none on these samples.
+    cancel_at_period_end: false,
+    discount: null,
+    // The merchant's own sign-up metadata; `{}` when none was sent.
+    metadata: {}
+  };
+  switch (event) {
+    case "subscription.created":
+      return { ...base, billing_cycle: 1, amount, payment_intent_id: paymentIntentId };
+    case "subscription.renewed":
+      return { ...base, billing_cycle: 2, amount, payment_intent_id: paymentIntentId };
+    case "subscription.payment_failed":
+      return {
+        ...base,
+        status: "past_due",
+        billing_cycle: 2,
+        next_bill_at: now + 3 * 24 * 60 * 60,
+        amount,
+        payment_intent_id: paymentIntentId,
+        // The same three values `charge.failed` carries for this code.
+        action: "soft",
+        decline_message: "The card was declined for insufficient funds.",
+        decline_code: "insufficient_funds"
+      };
+    case "subscription.cancelled":
+      return { ...base, status: "cancelled", next_bill_at: null, cancel_reason: "too_expensive" };
+    case "subscription.updated":
+      return { ...base, renewal_amount: Math.max(1, Math.floor(amount * 0.9)), changed_fields: ["renewal_amount"] };
+  }
+}
 function buildEventData(event, ids, amount, currency) {
   const base = {
     session_id: ids.sessionId,
@@ -1709,13 +2691,14 @@ function buildEventData(event, ids, amount, currency) {
     amount,
     currency
   };
+  const notARenewal = { subscription_id: null, billing_cycle: null };
   switch (event) {
     case "session.succeeded":
       return base;
     case "payment_intent.succeeded":
-      return { ...base, processor_connection: PROCESSOR_CONNECTION };
+      return { ...base, processor_connection: PROCESSOR_CONNECTION, ...notARenewal };
     case "charge.succeeded":
-      return { ...base, vp_tx_id: ids.transactionId, card: null, processor_connection: PROCESSOR_CONNECTION };
+      return { ...base, vp_tx_id: ids.transactionId, card: null, processor_connection: PROCESSOR_CONNECTION, ...notARenewal };
     case "session.failed":
     case "payment_intent.failed":
       return {
@@ -1727,8 +2710,8 @@ function buildEventData(event, ids, amount, currency) {
         // could be read (as on this ordinary decline) — never permission to retry.
         network_advice: null,
         network_advice_retry_after_ms: null,
-        // payment_intent.failed only: session.failed does not send it.
-        ...event === "payment_intent.failed" ? { processor_connection: PROCESSOR_CONNECTION } : {}
+        // payment_intent.failed only: session.failed sends neither.
+        ...event === "payment_intent.failed" ? { processor_connection: PROCESSOR_CONNECTION, ...notARenewal } : {}
       };
     case "charge.failed":
       return {
@@ -1744,7 +2727,8 @@ function buildEventData(event, ids, amount, currency) {
         // Same two fields and values as payment_intent.failed / session.failed.
         network_advice: null,
         network_advice_retry_after_ms: null,
-        processor_connection: PROCESSOR_CONNECTION
+        processor_connection: PROCESSOR_CONNECTION,
+        ...notARenewal
       };
     case "mirror.order.created":
       return {
@@ -1753,7 +2737,28 @@ function buildEventData(event, ids, amount, currency) {
         order_status_url: null
       };
     case "payment_intent.cancelled":
-      return { ...base, cancellation_reason: "buyer_abandoned", processor_connection: PROCESSOR_CONNECTION };
+      return { ...base, cancellation_reason: "buyer_abandoned", processor_connection: PROCESSOR_CONNECTION, ...notARenewal };
+    case "subscription.created":
+    case "subscription.renewed":
+    case "subscription.payment_failed":
+    case "subscription.cancelled":
+    case "subscription.updated":
+      return subscriptionEventData(event, ids.paymentIntentId, amount, currency);
+    case "merchant.card_testing_suspected": {
+      const now = Math.floor(Date.now() / 1e3);
+      return {
+        patterns: ["expiry_enumeration", "refusal_burst"],
+        window_start: now - 60 * 60,
+        window_end: now,
+        attempts: 30,
+        refused: 24,
+        accepted: 3,
+        distinct_cards: 12,
+        card: { brand: "visa", last4: "4242" },
+        expiry_variants: 9,
+        blocked: false
+      };
+    }
     case "charge.refunded":
       return {
         ...base,
@@ -1768,7 +2773,8 @@ function buildEventData(event, ids, amount, currency) {
         is_partial: false,
         original_charge_amount: amount,
         card: null,
-        processor_connection: PROCESSOR_CONNECTION
+        processor_connection: PROCESSOR_CONNECTION,
+        ...notARenewal
       };
     case "refund.failed":
       return {
@@ -1814,10 +2820,13 @@ function triggerCommand() {
   return new Command9("trigger").description("Send a test webhook event to a local URL").argument("<event>", `Event type (${SUPPORTED_EVENTS.join(", ")})`).requiredOption("--url <url>", "Local webhook URL (e.g. http://localhost:3000/webhooks)").option("--session-id <id>", "Custom session ID").option("--amount <cents>", "Amount in minor units, a whole number").option("--currency <code>", "Currency code").option(
     "--url-tunnel",
     "Allow a non-loopback --url (ngrok / Cloudflare Tunnel). Without it, --url must be this machine"
+  ).option(
+    SIGNING_SECRET_FLAG,
+    `Sign the event with this secret instead of a new random one for this run (or set ${SIGNING_SECRET_ENV}); your handler verifies with the same value`
   ).addOption(retiredConfirmLiveOption()).action(async (event, opts) => {
     if (!SUPPORTED_EVENTS.includes(event)) {
       console.error(
-        chalk12.red(
+        chalk13.red(
           `Unknown event: ${event}
 Supported: ${SUPPORTED_EVENTS.join(", ")}`
         )
@@ -1831,15 +2840,20 @@ Supported: ${SUPPORTED_EVENTS.join(", ")}`
       tunnelFlag: "--url-tunnel"
     });
     if (!destination.ok) {
-      console.error(chalk12.red(destination.reason));
+      console.error(chalk13.red(destination.reason));
       process.exit(1);
     }
-    if (destination.warning) console.warn(chalk12.yellow(destination.warning));
+    if (destination.warning) console.warn(chalk13.yellow(destination.warning));
     const amount = optionalMinorUnitsOrExit(
       opts.amount === void 0 ? void 0 : String(opts.amount),
       "--amount"
     );
     const apiKey = requireApiKey();
+    const signing = resolveSigningSecret(opts.signingSecret, process.env, apiKey);
+    if ("error" in signing) {
+      console.error(chalk13.red(signing.error));
+      process.exit(1);
+    }
     await confirmLiveAction(
       apiKey,
       {
@@ -1848,14 +2862,15 @@ Supported: ${SUPPORTED_EVENTS.join(", ")}`
           ["Event", event],
           ["Sent to", String(opts.url)]
         ],
-        consequence: "The event is signed with your LIVE key: a receiver that verifies with that key will accept it as a genuine event."
+        consequence: "A synthetic event is sent to this URL, signed with this run's signing secret (never your API key)."
       },
       opts
     );
     const payload = buildPayload(event, { ...opts, amount });
     const body = JSON.stringify(payload);
+    console.log(chalk13.dim(signingSecretNotice(signing)));
     const t = Math.floor(Date.now() / 1e3);
-    const v1 = createHmac2("sha256", apiKey).update(`${t}.${body}`).digest("hex");
+    const v1 = createHmac2("sha256", signing.secret).update(`${t}.${body}`).digest("hex");
     const signatureHeader = `t=${t},v1=${v1}`;
     const spinner = ora2(`Sending ${event} to ${opts.url}...`).start();
     try {
@@ -1875,45 +2890,45 @@ Supported: ${SUPPORTED_EVENTS.join(", ")}`
       spinner.stop();
       if (isRedirect(response)) {
         console.error(
-          chalk12.red(
+          chalk13.red(
             `\u2717 ${event} not delivered: ${safeDisplay(String(opts.url))} answered with a redirect (HTTP ${response.status}). It was not followed, and the signed event was not sent anywhere else. Point --url at the endpoint itself.`
           )
         );
         process.exit(1);
       }
       if (response.ok) {
-        console.log(chalk12.green(`\u2713 ${event} delivered \u2192 ${response.status}`));
+        console.log(chalk13.green(`\u2713 ${event} delivered \u2192 ${response.status}`));
       } else {
         console.log(
-          chalk12.yellow(
+          chalk13.yellow(
             `\u26A0 ${event} delivered but got ${response.status} response`
           )
         );
       }
-      console.log(chalk12.dim(`  Event:   ${payload.id} (${payload.type})`));
+      console.log(chalk13.dim(`  Event:   ${payload.id} (${payload.type})`));
       console.log(
-        chalk12.dim(
+        chalk13.dim(
           `  Amount:  ${payload.data.amount} ${payload.data.currency}`
         )
       );
       console.log(
-        chalk12.dim(
+        chalk13.dim(
           `
   Verify with: vonpay.webhooks.constructEvent(rawBody, signatureHeader, secret)`
         )
       );
       console.log(
-        chalk12.dim(
-          `  (local dev: 'secret' is your API key here \u2014 production webhooks are signed with your endpoint's whsec_\u2026 secret, NOT your API key)`
+        chalk13.dim(
+          `  ('secret' is this run's signing secret, printed above \u2014 production webhooks are signed with your endpoint's whsec_\u2026 secret, and never with your API key)`
         )
       );
     } catch (err) {
       spinner.stop();
       if (err instanceof Error && err.name === "TimeoutError") {
-        console.error(chalk12.red(`Timeout: ${opts.url} did not respond within 10s`));
+        console.error(chalk13.red(`Timeout: ${opts.url} did not respond within 10s`));
       } else {
         console.error(
-          chalk12.red(
+          chalk13.red(
             `Failed to deliver: ${err instanceof Error ? err.message : err}`
           )
         );
@@ -2025,9 +3040,9 @@ function resumeId(lastId) {
 async function* consumeSse(opts) {
   const initialBackoffMs = opts.initialBackoffMs ?? 1e3;
   const maxBackoffMs = opts.maxBackoffMs ?? 3e4;
-  const pending = [];
+  const pending2 = [];
   const parser = new SseParser(
-    (type, data) => pending.push({ type, data, lastEventId: parser.lastId || void 0 }),
+    (type, data) => pending2.push({ type, data, lastEventId: parser.lastId || void 0 }),
     { maxPending: MAX_PENDING_CHARS, maxIdLength: MAX_EVENT_ID_LENGTH }
   );
   let backoffMs = initialBackoffMs;
@@ -2050,7 +3065,10 @@ async function* consumeSse(opts) {
       response = await fetch(opts.url, {
         method: "GET",
         headers,
-        signal: opts.signal
+        signal: opts.signal,
+        // Never follow a redirect: the request carries the API key, and a 3xx
+        // would re-send it to wherever the answer points.
+        redirect: "manual"
       });
     } catch (err) {
       if (opts.signal.aborted) return;
@@ -2060,6 +3078,11 @@ async function* consumeSse(opts) {
       backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
       continue;
     }
+    if (response.status >= 300 && response.status < 400) {
+      const error = new SseRedirectError(response.status);
+      onLifecycle({ kind: "fatal", error });
+      throw error;
+    }
     if (response.status === 401 || response.status === 403) {
       const body = await safeReadText(response);
       onLifecycle({ kind: "auth_failed", status: response.status, body });
@@ -2103,7 +3126,7 @@ async function* consumeSse(opts) {
         } catch (err) {
           feedError = err;
         }
-        for (const ev of pending.splice(0)) {
+        for (const ev of pending2.splice(0)) {
           if (ev.type === "timeout") {
             serverInitiatedReconnect = true;
           } else {
@@ -2171,15 +3194,25 @@ var SseAuthError = class extends Error {
   status;
   body;
 };
+var SseRedirectError = class extends Error {
+  constructor(status) {
+    super(
+      `The event stream answered with a redirect (HTTP ${status}). It was not followed, so your API key was not sent anywhere else. Check VONPAY_BASE_URL.`
+    );
+    this.status = status;
+    this.name = "SseRedirectError";
+  }
+  status;
+};
 function sleep(ms, signal) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const timer = setTimeout(() => {
       signal.removeEventListener("abort", onAbort);
-      resolve2();
+      resolve3();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
-      resolve2();
+      resolve3();
     };
     signal.addEventListener("abort", onAbort, { once: true });
   });
@@ -2198,24 +3231,38 @@ function noop() {
 }
 
 // src/utils/listen-output.ts
-import chalk13 from "chalk";
+import chalk14 from "chalk";
+function parseAttemptPayload(data) {
+  let raw;
+  try {
+    raw = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw;
+  const str2 = (k) => typeof r[k] === "string";
+  const num = (k) => typeof r[k] === "number" && Number.isFinite(r[k]);
+  const ok = str2("event_id") && str2("event_type") && str2("subscription_id") && str2("timestamp") && num("attempt") && num("latency_ms") && typeof r["succeeded"] === "boolean" && typeof r["livemode"] === "boolean" && (r["response_status"] === null || num("response_status"));
+  return ok ? r : null;
+}
 function formatAttemptHuman(payload, forward) {
   const ts = formatTimestamp(payload.timestamp);
-  const eventType = chalk13.cyan(payload.event_type.padEnd(24));
-  const eventId = chalk13.gray(payload.event_id.padEnd(28));
-  const attempt = chalk13.gray(`attempt ${payload.attempt}`);
-  const arrow = chalk13.gray("\u2192");
+  const eventType = chalk14.cyan(safeInline(payload.event_type, 64).padEnd(24));
+  const eventId = chalk14.gray(safeInline(payload.event_id, 64).padEnd(28));
+  const attempt = chalk14.gray(`attempt ${payload.attempt}`);
+  const arrow = chalk14.gray("\u2192");
   const upstream = formatUpstream(payload);
-  const latency = chalk13.gray(`${payload.latency_ms}ms`);
-  const liveBadge = payload.livemode ? chalk13.red(" [LIVE]") : "";
+  const latency = chalk14.gray(`${payload.latency_ms}ms`);
+  const liveBadge = payload.livemode ? chalk14.red(" [LIVE]") : "";
   let line = `[${ts}] ${eventType} ${eventId} ${attempt}  ${arrow} ${upstream}  ${latency}${liveBadge}`;
   if (forward && forward.attempted) {
-    const fwdArrow = chalk13.gray("\u2192 local");
+    const fwdArrow = chalk14.gray("\u2192 local");
     if (forward.error) {
-      line += `  ${fwdArrow} ${chalk13.red(forward.error)}`;
+      line += `  ${fwdArrow} ${chalk14.red(safeInline(forward.error))}`;
     } else if (forward.status !== null) {
       const fwdStatus = formatStatus(forward.status);
-      const fwdLatency = chalk13.gray(`${forward.latencyMs}ms`);
+      const fwdLatency = chalk14.gray(`${forward.latencyMs}ms`);
       line += `  ${fwdArrow} ${fwdStatus} ${fwdLatency}`;
     }
   }
@@ -2224,47 +3271,47 @@ function formatAttemptHuman(payload, forward) {
 function formatAttemptJson(payload, forward) {
   const body = {
     type: "webhook.attempt",
-    event_id: payload.event_id,
-    event_type: payload.event_type,
-    subscription_id: payload.subscription_id,
+    event_id: safeInline(payload.event_id, 200),
+    event_type: safeInline(payload.event_type, 200),
+    subscription_id: safeInline(payload.subscription_id, 200),
     attempt: payload.attempt,
     succeeded: payload.succeeded,
     response_status: payload.response_status,
     latency_ms: payload.latency_ms,
-    timestamp: payload.timestamp,
+    timestamp: safeInline(payload.timestamp, 64),
     livemode: payload.livemode
   };
   if (forward && forward.attempted) {
     body.forward = {
       status: forward.status,
       latency_ms: forward.latencyMs,
-      error: forward.error
+      error: forward.error === null ? null : safeInline(forward.error)
     };
   }
   return JSON.stringify(body);
 }
 function formatLifecycleHuman(message, kind) {
-  const tag = kind === "info" ? chalk13.cyan("[vonpay]") : kind === "warn" ? chalk13.yellow("[vonpay]") : chalk13.red("[vonpay]");
+  const tag = kind === "info" ? chalk14.cyan("[vonpay]") : kind === "warn" ? chalk14.yellow("[vonpay]") : chalk14.red("[vonpay]");
   return `${tag} ${message}`;
 }
 function formatLifecycleJson(kind, extra = {}) {
   return JSON.stringify({ type: `cli.${kind}`, ...extra, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
 }
 function formatStatus(status) {
-  if (status >= 200 && status < 300) return chalk13.green(String(status));
-  if (status >= 400 && status < 500) return chalk13.yellow(String(status));
-  if (status >= 500) return chalk13.red(String(status));
-  return chalk13.gray(String(status));
+  if (status >= 200 && status < 300) return chalk14.green(String(status));
+  if (status >= 400 && status < 500) return chalk14.yellow(String(status));
+  if (status >= 500) return chalk14.red(String(status));
+  return chalk14.gray(String(status));
 }
 function formatUpstream(payload) {
   if (payload.response_status === null) {
-    return chalk13.red("timeout");
+    return chalk14.red("timeout");
   }
   return formatStatus(payload.response_status);
 }
 function formatTimestamp(iso) {
   const date = new Date(iso);
-  if (isNaN(date.getTime())) return iso.slice(0, 19);
+  if (isNaN(date.getTime())) return safeInline(iso, 19);
   const h = String(date.getHours()).padStart(2, "0");
   const m = String(date.getMinutes()).padStart(2, "0");
   const s = String(date.getSeconds()).padStart(2, "0");
@@ -2285,7 +3332,10 @@ function listenCommand() {
     "--events <type>",
     "Only stream attempts for the given event type. Repeat the flag for multiple types.",
     (value, prev) => prev ? [...prev, value] : [value]
-  ).option("--json", "Emit one JSON object per line on stdout instead of the colored transcript").option("--api-key <key>", "Override the API key from env / config").addOption(retiredConfirmLiveOption()).action(async (opts) => {
+  ).option("--json", "Emit one JSON object per line on stdout instead of the colored transcript").option("--api-key <key>", "Override the API key from env / config").option(
+    SIGNING_SECRET_FLAG,
+    `With --forward-to: sign forwarded events with this secret instead of a new random one for this run (or set ${SIGNING_SECRET_ENV})`
+  ).addOption(retiredConfirmLiveOption()).action(async (opts) => {
     const apiKey = opts.apiKey ?? requireApiKey();
     if (opts.apiKey !== void 0) warnLiveSecretFlag(opts.apiKey, "--api-key");
     const refuse = (message) => {
@@ -2308,6 +3358,12 @@ function listenCommand() {
       forwardUrl = verdict.url;
       forwardWarning = verdict.warning;
     }
+    let signing;
+    if (forwardUrl) {
+      const resolved = resolveSigningSecret(opts.signingSecret, process.env, apiKey);
+      if ("error" in resolved) refuse(resolved.error);
+      signing = resolved;
+    }
     const configuredBaseUrl = getBaseUrl();
     const destinationProblem = keyDestinationProblem(apiKey, configuredBaseUrl);
     if (destinationProblem) refuse(destinationProblem);
@@ -2323,7 +3379,7 @@ function listenCommand() {
           ["Stream from", baseUrl],
           ...forwardUrl ? [["Forward to", forwardUrl.toString()]] : []
         ],
-        consequence: forwardUrl ? "Live payment events, with buyer and order details, will be shown here, and each one is signed with your LIVE key and sent to the forward URL." : "Live payment events, with buyer and order details, will be shown here."
+        consequence: forwardUrl ? "Live payment events, with buyer and order details, will be shown here, and each one is sent to the forward URL (signed with this run's signing secret, never your API key)." : "Live payment events, with buyer and order details, will be shown here."
       },
       opts
     );
@@ -2362,6 +3418,7 @@ function listenCommand() {
       }
       controller.abort();
     };
+    auditSignalHandledByCommand();
     process.once("SIGINT", () => onSignal("SIGINT"));
     process.once("SIGTERM", () => onSignal("SIGTERM"));
     const onLifecycle = (event) => {
@@ -2384,12 +3441,16 @@ function listenCommand() {
       process.stderr.write(
         formatLifecycleHuman(`Ready! Listening for webhook delivery attempts${filterNote}${fwdNote}.`, "info") + "\n"
       );
+      if (signing) process.stderr.write(formatLifecycleHuman(signingSecretNotice(signing), "info") + "\n");
     } else {
       process.stderr.write(
         formatLifecycleJson("ready", {
           base_url: baseUrl,
           filter: opts.events ?? null,
-          forward_to: forwardUrl?.toString() ?? null
+          forward_to: forwardUrl?.toString() ?? null,
+          // The generated secret in full (the local receiver needs it); a pinned one by source only.
+          signing_secret: signing?.source === "generated" ? signing.secret : null,
+          signing_secret_source: signing?.source ?? null
         }) + "\n"
       );
     }
@@ -2411,12 +3472,8 @@ function listenCommand() {
         if (sseEvent.type !== "webhook.attempt") {
           continue;
         }
-        let payload;
-        try {
-          payload = JSON.parse(sseEvent.data);
-        } catch {
-          continue;
-        }
+        const payload = parseAttemptPayload(sseEvent.data);
+        if (payload === null) continue;
         eventCount += 1;
         let forwardOutcome = null;
         if (forwardUrl && sdk) {
@@ -2424,7 +3481,7 @@ function listenCommand() {
             const eventRecord = await sdk.webhookEvents.retrieve(payload.event_id);
             forwardOutcome = await forwardPayload(eventRecord.payload, {
               url: forwardUrl,
-              signingSecret: apiKey,
+              signingSecret: signing.secret,
               signal: controller.signal
             });
           } catch (err) {
@@ -2445,6 +3502,7 @@ function listenCommand() {
       }
     } catch (err) {
       if (err instanceof SseAuthError) {
+        auditNote({ outcome: "error", code: "auth_failed" });
         if (mode === "human") {
           process.stderr.write(
             formatLifecycleHuman(
@@ -2459,6 +3517,10 @@ function listenCommand() {
         }
         process.exit(1);
       }
+      if (err instanceof SseRedirectError) {
+        if (jsonErrorsEnabled()) exitWithCliError(err.message, err.message);
+        process.exit(1);
+      }
       if (jsonErrorsEnabled()) handleError(err);
       throw err;
     }
@@ -2467,29 +3529,29 @@ function listenCommand() {
 function lifecyclePayload(event) {
   switch (event.kind) {
     case "connecting":
-      return { last_event_id: event.lastEventId ?? null };
+      return { last_event_id: event.lastEventId === void 0 ? null : safeInline(event.lastEventId, 200) };
     case "connected":
       return {};
     case "disconnected":
-      return { reason: event.reason, will_retry_in_ms: event.willRetryInMs };
+      return { reason: safeInline(event.reason, 400), will_retry_in_ms: event.willRetryInMs };
     case "auth_failed":
       return { status: event.status };
     case "fatal":
-      return { error: event.error.message };
+      return { error: safeInline(event.error.message, 400) };
   }
 }
 function lifecycleHumanMessage(event) {
   switch (event.kind) {
     case "connecting":
-      return event.lastEventId ? `Reconnecting (resume from ${event.lastEventId})` : "Connecting...";
+      return event.lastEventId ? `Reconnecting (resume from ${safeInline(event.lastEventId, 200)})` : "Connecting...";
     case "connected":
       return "Connected.";
     case "disconnected":
-      return `Disconnected: ${event.reason}. Retrying in ${event.willRetryInMs}ms.`;
+      return `Disconnected: ${safeInline(event.reason, 400)}. Retrying in ${event.willRetryInMs}ms.`;
     case "auth_failed":
       return `Authentication failed (HTTP ${event.status}).`;
     case "fatal":
-      return `Fatal: ${event.error.message}`;
+      return `Fatal: ${safeInline(event.error.message, 400)}`;
   }
 }
 function lifecycleSeverity(kind) {
@@ -2507,8 +3569,8 @@ function lifecycleSeverity(kind) {
 
 // src/commands/health.ts
 import { Command as Command11 } from "commander";
-import chalk14 from "chalk";
-import { VonPayError as VonPayError2 } from "@vonpay/checkout-node";
+import chalk15 from "chalk";
+import { VonPayError as VonPayError3 } from "@vonpay/checkout-node";
 function healthCommand() {
   return new Command11("health").description("Check checkout API health").option("--json", "Output raw JSON").action(async (opts) => {
     const client = makeCheckoutClient();
@@ -2519,23 +3581,24 @@ function healthCommand() {
       if (opts.json) {
         console.log(JSON.stringify(health, null, 2));
       } else {
-        const statusColor = health.status === "ok" ? chalk14.green : health.status === "degraded" ? chalk14.yellow : chalk14.red;
-        console.log(`  Status:   ${statusColor(health.status)}`);
-        console.log(`  Latency:  ${health.latencyMs}ms`);
+        const statusColor = health.status === "ok" ? chalk15.green : health.status === "degraded" ? chalk15.yellow : chalk15.red;
+        console.log(`  Status:   ${statusColor(safeInline(String(health.status)))}`);
+        console.log(`  Latency:  ${safeInline(String(health.latencyMs))}ms`);
         if (health.version) {
-          console.log(`  Version:  ${health.version}`);
+          console.log(`  Version:  ${safeInline(String(health.version))}`);
         }
       }
     } catch (err) {
       spinner.stop();
+      auditError(err);
       if (jsonErrorsEnabled()) handleError(err);
-      if (err instanceof VonPayError2) {
-        console.error(chalk14.red(`API error: ${scrubSecrets(err.message)}`));
-        console.error(chalk14.dim(`  Code: ${err.code}`));
+      if (err instanceof VonPayError3) {
+        console.error(chalk15.red(`API error: ${scrubSecrets(safeInline(err.message, 2e3))}`));
+        console.error(chalk15.dim(`  Code: ${safeInline(String(err.code))}`));
       } else {
         console.error(
-          chalk14.red(
-            `Cannot reach API: ${scrubSecrets(err instanceof Error ? err.message : String(err))}`
+          chalk15.red(
+            `Cannot reach API: ${scrubSecrets(safeInline(err instanceof Error ? err.message : String(err), 2e3))}`
           )
         );
       }
@@ -2546,13 +3609,13 @@ function healthCommand() {
 
 // src/commands/doctor.ts
 import { Command as Command12 } from "commander";
-import chalk15 from "chalk";
+import chalk16 from "chalk";
 import ora3 from "ora";
-import { homedir as homedir2 } from "os";
+import { homedir as homedir3 } from "os";
 import { existsSync as existsSync3 } from "fs";
 import {
   VonPayCheckout as VonPayCheckout3,
-  VonPayError as VonPayError3,
+  VonPayError as VonPayError4,
   helpFor
 } from "@vonpay/checkout-node";
 var RELEVANT_ENV_VARS = [
@@ -2564,7 +3627,7 @@ var RELEVANT_ENV_VARS = [
   "NEXT_PUBLIC_BASE_URL"
 ];
 function redactHome(p) {
-  const home = homedir2();
+  const home = homedir3();
   if (home && p.startsWith(home)) {
     return "~" + p.slice(home.length);
   }
@@ -2699,7 +3762,7 @@ async function gather() {
         );
       }
     } catch (err) {
-      if (err instanceof VonPayError3) {
+      if (err instanceof VonPayError4) {
         const help = helpFor(err.code);
         report.validateProbe = {
           ok: false,
@@ -2730,47 +3793,47 @@ async function gather() {
 }
 function renderHuman(r) {
   const lines = [];
-  lines.push(chalk15.bold.blue("vonpay doctor \u2014 diagnostic report"));
-  lines.push(chalk15.dim(`generated ${r.generatedAt}`));
+  lines.push(chalk16.bold.blue("vonpay doctor \u2014 diagnostic report"));
+  lines.push(chalk16.dim(`generated ${r.generatedAt}`));
   lines.push("");
-  lines.push(chalk15.bold("Runtime"));
+  lines.push(chalk16.bold("Runtime"));
   lines.push(`  CLI:       ${r.cli.version}`);
   lines.push(`  Node:      ${r.runtime.node}`);
   lines.push(`  Platform:  ${r.runtime.platform} (${r.runtime.arch})`);
   lines.push(`  CWD:       ${r.runtime.cwd}`);
   lines.push("");
-  lines.push(chalk15.bold("API key"));
+  lines.push(chalk16.bold("API key"));
   if (r.apiKeyPrefix) {
     lines.push(`  Prefix:    ${r.apiKeyPrefix}`);
     lines.push(`  Mode:      ${r.apiKeyMode}`);
   } else {
-    lines.push(chalk15.dim("  (no key found in env or ~/.vonpay/config.json)"));
+    lines.push(chalk16.dim("  (no key found in env or ~/.vonpay/config.json)"));
   }
   lines.push("");
-  lines.push(chalk15.bold("Env vars present (names only)"));
+  lines.push(chalk16.bold("Env vars present (names only)"));
   if (r.envVarsPresent.length === 0) {
-    lines.push(chalk15.dim("  (none of the expected vonpay env vars are set)"));
+    lines.push(chalk16.dim("  (none of the expected vonpay env vars are set)"));
   } else {
     for (const n of r.envVarsPresent) lines.push(`  \u2713 ${n}`);
   }
   lines.push("");
-  lines.push(chalk15.bold("Health probe"));
+  lines.push(chalk16.bold("Health probe"));
   if (r.health.reachable) {
-    const statusColor = r.health.status === "ok" ? chalk15.green : r.health.status === "degraded" ? chalk15.yellow : chalk15.red;
-    lines.push(`  Reachable: ${chalk15.green("yes")}`);
+    const statusColor = r.health.status === "ok" ? chalk16.green : r.health.status === "degraded" ? chalk16.yellow : chalk16.red;
+    lines.push(`  Reachable: ${chalk16.green("yes")}`);
     lines.push(`  Status:    ${statusColor(r.health.status ?? "?")}`);
     lines.push(`  Latency:   ${r.health.latencyMs}ms`);
   } else {
-    lines.push(`  Reachable: ${chalk15.red("no")}`);
+    lines.push(`  Reachable: ${chalk16.red("no")}`);
     lines.push(`  Error:     ${r.health.error}`);
   }
   lines.push("");
   if (r.validateProbe) {
-    lines.push(chalk15.bold("sessions.validate probe ($14.99 USD dry-run)"));
+    lines.push(chalk16.bold("sessions.validate probe ($14.99 USD dry-run)"));
     if (r.validateProbe.ok) {
-      lines.push(`  Result:    ${chalk15.green("valid")}`);
+      lines.push(`  Result:    ${chalk16.green("valid")}`);
     } else {
-      lines.push(`  Result:    ${chalk15.red("invalid")}`);
+      lines.push(`  Result:    ${chalk16.red("invalid")}`);
       if (r.validateProbe.error) {
         lines.push(`  Code:      ${r.validateProbe.error.code}`);
         lines.push(`  Action:    ${r.validateProbe.error.nextAction}`);
@@ -2783,7 +3846,7 @@ function renderHuman(r) {
     lines.push("");
   }
   if (r.hints.length > 0) {
-    lines.push(chalk15.bold("Hints"));
+    lines.push(chalk16.bold("Hints"));
     for (const h of r.hints) lines.push(`  \u2022 ${h}`);
     lines.push("");
   }
@@ -2885,8 +3948,8 @@ function doctorCommand() {
 }
 
 // src/commands/checkout.ts
-function registerCheckout(program2) {
-  const checkout = program2.command("checkout").description("Checkout integration tools");
+function registerCheckout(program) {
+  const checkout = program.command("checkout").description("Checkout integration tools");
   checkout.hook("preAction", (_checkout, actionCommand) => {
     setJsonErrors(actionCommand.opts().json === true);
   });
@@ -2904,12 +3967,32 @@ function registerCheckout(program2) {
   checkout.addCommand(doctorCommand());
 }
 
+// src/program.ts
+function commandPath(cmd) {
+  const names = [];
+  for (let c = cmd; c && c.parent; c = c.parent) names.unshift(c.name());
+  return names.join(" ");
+}
+function buildProgram() {
+  const program = new Command13();
+  program.name("vonpay").description("Von Payments developer tools").version(CLI_VERSION).option(
+    ALLOW_CUSTOM_BASE_URL_FLAG,
+    "With VONPAY_ALLOW_CUSTOM_BASE_URL=1: send a live key to a base URL that is not a Von Payments host (a proxy you run)"
+  ).hook("preAction", (_root, actionCommand) => {
+    setAllowCustomBaseUrlFlag(program.opts().allowCustomBaseUrl === true);
+    try {
+      auditStart(commandPath(actionCommand), CLI_VERSION, actionCommand.opts(), actionCommand.args);
+    } catch {
+    }
+  });
+  registerCheckout(program);
+  const withUsageAudit = (cmd) => {
+    cmd.exitOverride((err) => auditUsageError(commandPath(cmd), CLI_VERSION, err.code, err.exitCode));
+    cmd.commands.forEach(withUsageAudit);
+  };
+  withUsageAudit(program);
+  return program;
+}
+
 // src/index.ts
-var __dirname = dirname2(fileURLToPath2(import.meta.url));
-var pkg2 = JSON.parse(
-  readFileSync4(join3(__dirname, "..", "package.json"), "utf-8")
-);
-var program = new Command13();
-program.name("vonpay").description("Von Payments developer tools").version(pkg2.version);
-registerCheckout(program);
-program.parse();
+buildProgram().parse();