@vonpay/checkout-cli 0.14.0 → 0.15.0

package/dist/index.js

@@ -7,13 +7,12 @@ import { dirname as dirname2, join as join3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/login.ts
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { createInterface } from "readline";
 import chalk from "chalk";
-import { isLiveKey } from "@vonpay/checkout-node";
 
 // src/config.ts
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
@@ -34,6 +33,17 @@ function emitCliError(json, text) {
   return process.exit(1);
 }
 
+// src/utils/key-mode.ts
+import { isLiveKey } from "@vonpay/checkout-node";
+var TEST_SECRET_KEY_PREFIX = "vp_sk_test_";
+function secretKeyMode(key) {
+  if (typeof key !== "string") return null;
+  if (isLiveKey(key)) return "live";
+  if (key.startsWith(TEST_SECRET_KEY_PREFIX)) return "test";
+  return null;
+}
+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/config.ts
 var CONFIG_DIR = join(homedir(), ".vonpay");
 var CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -48,7 +58,20 @@ function loadConfig() {
     return {};
   }
 }
+var LiveKeyNotStoredError = class extends Error {
+  constructor() {
+    super(
+      "Refusing to save a live key (vp_sk_live_\u2026) to ~/.vonpay/config.json: live keys are never stored on disk. Supply it for this terminal session only, through the VON_PAY_SECRET_KEY environment variable."
+    );
+    this.name = "LiveKeyNotStoredError";
+  }
+};
 function saveConfig(config) {
+  const key = config.checkout?.apiKey;
+  if (secretKeyMode(key) === "live") {
+    if (key !== loadConfig().checkout?.apiKey) throw new LiveKeyNotStoredError();
+    warnStoredLiveKey();
+  }
   if (!existsSync(CONFIG_DIR)) {
     mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
   }
@@ -56,6 +79,7 @@ function saveConfig(config) {
     encoding: "utf-8",
     mode: 384
   });
+  chmodSync(CONFIG_FILE, 384);
 }
 function clearStoredApiKey() {
   const config = loadConfig();
@@ -73,7 +97,17 @@ function getApiKey() {
   const envKey = process.env.VON_PAY_SECRET_KEY;
   if (envKey) return envKey;
   const config = loadConfig();
-  return config.checkout?.apiKey;
+  const stored = config.checkout?.apiKey;
+  if (secretKeyMode(stored) === "live") warnStoredLiveKey();
+  return stored;
+}
+var warnedStoredLiveKey = false;
+function warnStoredLiveKey() {
+  if (warnedStoredLiveKey) return;
+  warnedStoredLiveKey = true;
+  console.warn(
+    "Warning: a LIVE key is saved in plaintext in ~/.vonpay/config.json (stored by an older version of this CLI). Live keys are no longer stored. Run `vonpay checkout logout` to delete it, and supply the key through the VON_PAY_SECRET_KEY environment variable for the session instead."
+  );
 }
 function requireApiKey() {
   const key = getApiKey();
@@ -81,21 +115,28 @@ function requireApiKey() {
     const message = "No API key found. Run `vonpay checkout login` or set VON_PAY_SECRET_KEY.";
     emitCliError({ error: message, code: null }, message);
   }
+  if (secretKeyMode(key) === null) {
+    emitCliError({ error: NOT_A_SECRET_KEY_MESSAGE, code: null }, NOT_A_SECRET_KEY_MESSAGE);
+  }
   return key;
 }
 
 // src/commands/login.ts
-var VALID_PREFIXES = ["vp_sk_test_", "vp_sk_live_"];
-function evaluateCliKeyGate(key, opts) {
+var LIVE_KEY_NOT_SAVED_MESSAGE = "Live keys (vp_sk_live_\u2026) are never saved to ~/.vonpay/config.json: the file is plaintext, and a live key moves real money. Supply it for this terminal session only, through the environment, for example:\n  read -rs VON_PAY_SECRET_KEY && export VON_PAY_SECRET_KEY\n(paste the key at the silent prompt; it ends with the session). Use `login` for sandbox keys (vp_sk_test_\u2026).";
+function evaluateCliKeyGate(key, _opts = {}) {
   if (!key) return { action: "prompt" };
-  const warning = "Warning: passing keys as a command argument exposes them in shell history and process-list (`ps`). Use interactive mode (`vonpay checkout login`) instead.";
-  if (isLiveKey(key) && !opts.confirmCliExposure) {
-    return {
-      action: "refuse",
-      reason: "Refusing to save a live key supplied on the CLI. Re-run with --confirm-cli-exposure if this is intentional, or omit the key argument to be prompted interactively."
-    };
-  }
-  return { action: "save", warning };
+  const refusal = evaluateKeyToSave(key);
+  if (refusal) return refusal;
+  return {
+    action: "save",
+    warning: "Warning: passing keys as a command argument exposes them in shell history and process-list (`ps`). Use interactive mode (`vonpay checkout login`) instead."
+  };
+}
+function evaluateKeyToSave(key) {
+  const mode = secretKeyMode(key);
+  if (mode === null) return { action: "refuse", reason: NOT_A_SECRET_KEY_MESSAGE };
+  if (mode === "live") return { action: "refuse", reason: LIVE_KEY_NOT_SAVED_MESSAGE };
+  return null;
 }
 function readLine(prompt) {
   const rl = createInterface({ input: process.stdin, output: process.stderr });
@@ -107,18 +148,15 @@ function readLine(prompt) {
   });
 }
 function loginCommand() {
-  return new Command("login").description("Store your API key for CLI access").argument("[key]", "API secret key (vp_sk_*)").option(
-    "--confirm-cli-exposure",
-    "Acknowledge that passing a live key as a command argument exposes it to shell history and ps(1)."
+  return new Command("login").description("Store a sandbox API key (vp_sk_test_\u2026) for CLI access. Live keys are never stored").argument("[key]", "Sandbox API secret key (vp_sk_test_*)").addOption(
+    new Option(
+      "--confirm-cli-exposure",
+      "No longer has any effect: live keys are never saved"
+    ).hideHelp()
   ).action(async (key, opts) => {
     let apiKey = key;
     const verdict = evaluateCliKeyGate(key, opts);
     if (verdict.action === "refuse") {
-      console.warn(
-        chalk.yellow(
-          "Warning: passing keys as a command argument exposes them in shell history and process-list (`ps`). Use interactive mode (`vonpay checkout login`) instead."
-        )
-      );
       console.error(chalk.red(verdict.reason));
       process.exit(1);
     }
@@ -131,26 +169,22 @@ function loginCommand() {
           "Get your API key from the Von Payments dashboard \u2192 Developers"
         )
       );
-      apiKey = await readLine("API key (vp_sk_*): ");
+      apiKey = await readLine("Sandbox API key (vp_sk_test_*): ");
     }
     if (!apiKey) {
       console.error(chalk.red("No key provided."));
       process.exit(1);
     }
-    if (!VALID_PREFIXES.some((p) => apiKey.startsWith(p))) {
-      console.error(
-        chalk.red(
-          `Invalid key format. Must start with ${VALID_PREFIXES.join(" or ")}`
-        )
-      );
+    const refusal = evaluateKeyToSave(apiKey);
+    if (refusal) {
+      console.error(chalk.red(refusal.reason));
       process.exit(1);
     }
     const config = loadConfig();
     config.checkout = { ...config.checkout, apiKey };
     saveConfig(config);
-    const mode = apiKey.includes("_test_") ? "test" : "live";
     console.log(
-      chalk.green(`\u2713 API key saved (${mode} mode) \u2192 ~/.vonpay/config.json`)
+      chalk.green(`\u2713 API key saved (test mode) \u2192 ~/.vonpay/config.json`)
     );
   });
 }
@@ -182,9 +216,10 @@ function logoutCommand() {
 
 // src/commands/init.ts
 import { Command as Command3 } from "commander";
-import { appendFileSync, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { appendFileSync, chmodSync as chmodSync2, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 import { resolve } 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() {
   if (!existsSync2(".gitignore")) return "no-repo";
   if (envAlreadyIgnored(".gitignore")) {
@@ -242,20 +277,14 @@ function initCommand() {
       );
       process.exit(1);
     }
-    const mode = apiKey.includes("_test_") ? "test" : "live";
+    const mode = secretKeyMode(apiKey);
+    if (mode === null) {
+      console.error(chalk3.red(NOT_A_SECRET_KEY_MESSAGE));
+      process.exit(1);
+    }
     if (mode === "live") {
-      console.warn(
-        chalk3.yellow(
-          `\u26A0 About to write a LIVE API key to ${absPath}.
-  Confirm this is the intended directory, then re-run with --force if you're sure.`
-        )
-      );
-      if (!opts.force) {
-        console.error(
-          chalk3.red("Refusing to write live key without --force.")
-        );
-        process.exit(1);
-      }
+      console.error(chalk3.red(LIVE_KEY_NOT_WRITTEN_MESSAGE));
+      process.exit(1);
     }
     const content = [
       "# Von Payments Checkout",
@@ -264,6 +293,7 @@ function initCommand() {
       ""
     ].join("\n");
     writeFileSync2(envFile, content, { encoding: "utf-8", mode: 384 });
+    chmodSync2(envFile, 384);
     console.log(chalk3.green(`\u2713 .env created (${mode} mode) \u2192 ${absPath}`));
     const gitignoreState = ensureGitignoreBlocksEnv();
     if (gitignoreState === "added") {
@@ -308,29 +338,39 @@ var CLI_APP_INFO = { name: "vonpay-cli", version: CLI_VERSION };
 var SILENT_ERROR_REPORTER = () => {
 };
 
-// src/client-factory.ts
-function getBaseUrl() {
-  const envBase = process.env.VONPAY_BASE_URL;
-  if (envBase) return envBase;
-  const config = loadConfig();
-  return config.checkout?.baseUrl;
+// 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 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) {
+  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}`;
+  }
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return `Refusing to use the base URL: it is not a valid absolute URL (for example https://checkout.vonpay.com). ${WHERE}`;
+  }
+  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}`;
 }
-function makeCheckoutClient() {
-  const apiKey = requireApiKey();
-  const baseUrl = getBaseUrl();
-  return new VonPayCheckout({
-    apiKey,
-    ...baseUrl ? { baseUrl } : {},
-    appInfo: CLI_APP_INFO,
-    // 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
-  });
+function allowCustomBaseUrl(env = process.env) {
+  return customBaseUrlAllowed(env);
 }
 
 // src/utils/errors.ts
 import chalk4 from "chalk";
 import {
+  RETRY_WITHHELD_HELP,
   VonPayError
 } from "@vonpay/checkout-node";
 var SECRET_PATTERNS = [
@@ -345,13 +385,24 @@ function scrubSecrets(s) {
   for (const [re, replacement] of SECRET_PATTERNS) out = out.replace(re, replacement);
   return out;
 }
+var CLI_READ_BACK = "From this CLI: `vonpay checkout payment-intents get <id>` (charge, capture, void), `vonpay checkout refunds list --payment-intent <id>` or `--transaction <id>` (refund), `sessions get <id>` (checkout session).";
+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 FIELD_PRINTERS = {
   code: (e) => `Code: ${str(e.code)}`,
   fix: (e) => `Fix:  ${str(e.fix)}`,
-  nextAction: (e) => e.nextAction ? `Next action: ${str(e.nextAction)}` : null,
+  nextAction: (e) => (
+    // A withheld retry carries its own (SDK) guidance on the line below.
+    e.nextAction === "reconcile" && e.retryWithheld !== true ? `Next action: reconcile \u2014 ${UNKNOWN_OUTCOME_GUIDANCE}` : e.nextAction ? `Next action: ${str(e.nextAction)}` : null
+  ),
   retryable: (e) => typeof e.retryable === "boolean" ? `Retryable: ${e.retryable ? "yes" : "no \u2014 do not re-run this command as-is"}` : null,
-  retryWithheld: (e) => e.retryWithheld === true ? "Retry withheld: the outcome was unclear and no idempotency key was sent, so the CLI did not retry. Check whether it went through before running it again; with --idempotency-key, re-running the SAME key is safe." : null,
+  retryWithheld: (e) => e.retryWithheld === true ? (
+    // What to do is the SDK's RETRY_WITHHELD_HELP, printed on the Hint line
+    // (the SDK puts it in llmHint; quoted here only when the error carries
+    // something else). This line adds the CLI commands for the read-back.
+    "Retry withheld: the outcome is unknown and the CLI did not retry it. " + (e.llmHint === RETRY_WITHHELD_HELP.llmHint ? "" : `${RETRY_WITHHELD_HELP.llmHint} `) + CLI_READ_BACK
+  ) : null,
   captureOutcome: (e) => e.captureOutcome ? `Capture outcome: ${str(e.captureOutcome)} \u2014 the provider accepted the capture but it could not be recorded, so money may have moved. Do NOT capture again; read the payment intent back first.` : null,
   voidOutcome: (e) => e.voidOutcome ? `Void outcome: ${str(e.voidOutcome)} \u2014 the provider accepted the void but it could not be recorded. Do NOT void again or tell the buyer the hold was released until a read-back confirms it.` : null,
   currentStatus: (e) => e.currentStatus ? `Current status: ${str(e.currentStatus)}` : null,
@@ -365,6 +416,8 @@ var FIELD_PRINTERS = {
   rawReason: (e) => e.rawReason && e.rawReason !== e.reason ? `Reason as sent: ${str(e.rawReason)}` : null,
   retryAfterSeconds: (e) => typeof e.retryAfterSeconds === "number" ? `Retry after: ${e.retryAfterSeconds} seconds \u2014 then ask again` : null,
   session: (e) => e.session ? `Session: ${JSON.stringify(e.session)}` : 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,
   docs: (e) => e.docs ? `Docs: ${str(e.docs)}` : null,
   status: (e) => typeof e.status === "number" ? `HTTP status: ${e.status}` : null,
@@ -422,6 +475,66 @@ function handleError(err) {
   process.exit(1);
 }
 
+// src/client-factory.ts
+function getBaseUrl() {
+  const envBase = process.env.VONPAY_BASE_URL;
+  if (envBase) return envBase;
+  const config = loadConfig();
+  return config.checkout?.baseUrl;
+}
+function refuseUnsafeLiveDestination(apiKey) {
+  const problem = keyDestinationProblem(apiKey, getBaseUrl());
+  if (problem) exitWithCliError(problem, problem);
+}
+function apiHostDetail() {
+  const baseUrl = getBaseUrl();
+  if (!baseUrl) return [];
+  let origin = baseUrl;
+  try {
+    origin = new URL(baseUrl).origin;
+  } catch {
+  }
+  return origin === "https://checkout.vonpay.com" ? [] : [["API host", origin]];
+}
+function makeCheckoutClient() {
+  const apiKey = requireApiKey();
+  const baseUrl = getBaseUrl();
+  refuseUnsafeLiveDestination(apiKey);
+  return new VonPayCheckout({
+    apiKey,
+    ...baseUrl ? { baseUrl } : {},
+    // The SDK applies the same host rule at construction; the opt-in is the
+    // same environment variable (real process environment only).
+    allowCustomBaseUrl: allowCustomBaseUrl(),
+    appInfo: CLI_APP_INFO,
+    // 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/amount.ts
+var WHOLE_NUMBER = /^\d+$/;
+function parseMinorUnits(raw, flag) {
+  const text = raw.trim();
+  const value = Number(text);
+  if (!WHOLE_NUMBER.test(text) || !Number.isSafeInteger(value)) {
+    return {
+      ok: false,
+      message: `${flag} must be a whole number in minor units (the currency's smallest unit): for example 1499 = 14.99 USD. Got ${JSON.stringify(raw)}.`
+    };
+  }
+  return { ok: true, value };
+}
+function minorUnitsOrExit(raw, flag) {
+  const parsed = parseMinorUnits(raw, flag);
+  if (!parsed.ok) exitWithCliError(parsed.message, `Error: ${parsed.message}`);
+  return parsed.value;
+}
+function optionalMinorUnitsOrExit(raw, flag) {
+  return raw === void 0 ? void 0 : minorUnitsOrExit(raw, flag);
+}
+
 // src/commands/sessions.ts
 var makeClient = makeCheckoutClient;
 function sessionLines(session) {
@@ -469,12 +582,13 @@ 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 (e.g. 1499 = $14.99)", (v) => parseInt(v, 10)).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").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").option("--json", "Output raw JSON").action(async (opts) => {
+    const amount = minorUnitsOrExit(String(opts.amount), "--amount");
     const client = makeClient();
     const spinner = startSpinner("Creating session...");
     try {
       const params = {
-        amount: opts.amount,
+        amount,
         currency: opts.currency.toUpperCase(),
         country: opts.country?.toUpperCase(),
         description: opts.description,
@@ -537,11 +651,30 @@ function sessionsCommand() {
 }
 
 // src/commands/payment-intents.ts
-import { randomUUID } from "crypto";
 import { Command as Command5 } from "commander";
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 import { formatMinorUnits as formatMinorUnits2 } from "@vonpay/checkout-node";
 
+// src/utils/idempotency.ts
+import { randomUUID } from "crypto";
+import chalk6 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) {
+  const { key, generated } = resolveIdempotencyKey(flag);
+  if (generated) {
+    console.error(
+      chalk6.dim(
+        `Idempotency key: ${key} (to retry this same ${what}, re-run with --idempotency-key ${key})`
+      )
+    );
+  }
+  return key;
+}
+
 // src/utils/metadata.ts
 var MAX_LEN = 256;
 var CONTROL_CHARS = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
@@ -597,25 +730,75 @@ function safeDisplay(s, max = 200) {
 }
 
 // src/utils/live-key.ts
-import chalk6 from "chalk";
+import { createInterface as createInterface2 } from "readline";
+import chalk7 from "chalk";
+import { Option as Option2 } from "commander";
 import { isLiveKey as isLiveKey2 } from "@vonpay/checkout-node";
-function requireLiveConfirmation(key, opts, operation, consequence = "is irreversible") {
+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);
+      });
+    });
+  }
+};
+function keyFingerprint(key) {
+  const m = key.match(/^(vp_sk_live_)([A-Za-z0-9_-]{0,4})/);
+  return m ? `${m[1]}${m[2]}\u2026` : "vp_sk_live_\u2026";
+}
+async function confirmLiveAction(key, summary, opts = {}) {
   if (!isLiveKey2(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));
+  }
   if (opts.confirmLive) {
     console.warn(
-      chalk6.yellow(
-        `Live key in use \u2014 ${operation} ${consequence}. Proceeding because --confirm-live was passed.`
+      chalk7.yellow(
+        "Note: --confirm-live no longer confirms a live action by itself. A person confirms it at the terminal."
       )
     );
-    return;
   }
-  const message = `Refusing to ${operation} with a live key. Pass --confirm-live to acknowledge this is intentional.`;
-  exitWithCliError(message, chalk6.red(message));
+  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.")
+  ];
+  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));
+  }
+}
+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 (!isLiveKey2(key)) return;
   console.warn(
-    chalk6.yellow(
+    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.`
     )
   );
@@ -660,11 +843,6 @@ function buildCreateParams(opts, resolved) {
   }
   return params;
 }
-function resolveIdempotencyKey(flag) {
-  const given = flag?.trim();
-  if (given) return { key: given, generated: false };
-  return { key: `cli-${randomUUID()}`, generated: true };
-}
 function buildMITBlock(opts) {
   const initiator = opts.mitInitiator?.trim().toLowerCase();
   const reason = opts.mitReason?.trim().toLowerCase();
@@ -695,7 +873,7 @@ function buildMITBlock(opts) {
   };
 }
 function printPaymentIntent(intent) {
-  const statusColor = intent.status === "succeeded" ? chalk7.green : intent.status === "authorized" ? chalk7.cyan : intent.status === "requires_action" ? chalk7.yellow : intent.status === "failed" || intent.status === "canceled" ? chalk7.red : chalk7.gray;
+  const statusColor = intent.status === "succeeded" ? chalk8.green : intent.status === "authorized" ? chalk8.cyan : intent.status === "requires_action" ? chalk8.yellow : intent.status === "failed" || intent.status === "canceled" ? chalk8.red : chalk8.gray;
   console.log(`  ID:           ${intent.id}`);
   console.log(`  Status:       ${statusColor(intent.status)}`);
   console.log(
@@ -704,29 +882,25 @@ function printPaymentIntent(intent) {
   console.log(`  Capture:      ${intent.captureMethod}`);
   if (intent.nextAction) {
     console.log(
-      `  Next action:  ${chalk7.yellow(safeDisplay(intent.nextAction.type))}`
+      `  Next action:  ${chalk8.yellow(safeDisplay(intent.nextAction.type))}`
     );
     if (intent.nextAction.type === "redirect_to_url") {
       console.log(
-        `  Redirect:     ${chalk7.yellow(safeDisplay(intent.nextAction.redirectToUrl.url))}`
+        `  Redirect:     ${chalk8.yellow(safeDisplay(intent.nextAction.redirectToUrl.url))}`
       );
     }
   }
   if (intent.declineCode) {
-    console.log(`  Decline code: ${chalk7.red(safeDisplay(intent.declineCode))}`);
+    console.log(`  Decline code: ${chalk8.red(safeDisplay(intent.declineCode))}`);
   }
   console.log(`  Created:      ${intent.createdAt}`);
 }
-var CONFIRM_LIVE_DESCRIPTION = "Required to proceed when the loaded key is vp_sk_live_* (this operation is irreversible)";
+var AMOUNT_HELP = "Amount in minor units, a whole number (e.g. 1499 = $14.99)";
 function paymentIntentsCommand() {
   const intents = new Command5("payment-intents").description(
-    "Create, capture, and void payment intents (discrete lifecycle)"
+    "Create, read, capture, and void payment intents (discrete lifecycle)"
   );
-  intents.command("create").description("Create a new payment intent").requiredOption(
-    "--amount <cents>",
-    "Amount in minor units (e.g. 1499 = $14.99)",
-    (v) => parseInt(v, 10)
-  ).requiredOption("--currency <code>", "ISO 4217 currency (e.g. USD)").option(
+  intents.command("create").description("Create a new payment intent").requiredOption("--amount <cents>", AMOUNT_HELP).requiredOption("--currency <code>", "ISO 4217 currency (e.g. USD)").option(
     "--capture-method <mode>",
     "automatic (default) or manual (parks at authorized)"
   ).option(
@@ -753,33 +927,43 @@ function paymentIntentsCommand() {
   ).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"
-  ).option("--confirm-live", CONFIRM_LIVE_DESCRIPTION).option("--json", "Output raw JSON").action(async (opts) => {
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(async (raw) => {
     const apiKey = requireApiKey();
-    requireLiveConfirmation(apiKey, opts, "create a payment intent");
-    const client = makeCheckoutClient();
-    const spinner = startSpinner("Creating payment intent...");
+    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));
+    }
+    let params;
     try {
-      const captureMethod = opts.captureMethod?.toLowerCase();
-      if (captureMethod !== void 0 && captureMethod !== "automatic" && captureMethod !== "manual") {
-        spinner.stop();
-        const message = `Invalid --capture-method "${opts.captureMethod}". Expected automatic or manual.`;
-        exitWithCliError(message, chalk7.red(message));
-      }
       const metadata = parseMetadata(opts.metadata);
       const mit = buildMITBlock(opts);
-      const params = buildCreateParams(opts, { captureMethod, metadata, mit });
-      const { key: idempotencyKey, generated } = resolveIdempotencyKey(
-        opts.idempotencyKey
-      );
-      if (generated) {
-        spinner.stop();
-        console.error(
-          chalk7.dim(
-            `Idempotency key: ${idempotencyKey} (to retry this same charge, re-run with --idempotency-key ${idempotencyKey})`
-          )
-        );
-        spinner.start();
-      }
+      params = buildCreateParams(opts, { captureMethod, metadata, mit });
+    } catch (err) {
+      handleError(err);
+    }
+    refuseUnsafeLiveDestination(apiKey);
+    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "charge");
+    await confirmLiveAction(
+      apiKey,
+      {
+        action: "create a payment intent (charge a payment)",
+        details: [
+          ...apiHostDetail(),
+          ["Amount", formatMinorUnits2(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]
+        ]
+      },
+      opts
+    );
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Creating payment intent...");
+    try {
       const intent = await client.paymentIntents.create(params, {
         idempotencyKey
       });
@@ -787,7 +971,25 @@ function paymentIntentsCommand() {
       if (opts.json) {
         console.log(JSON.stringify(intent, null, 2));
       } else {
-        console.log(chalk7.green("\u2713 Payment intent created"));
+        console.log(chalk8.green("\u2713 Payment intent created"));
+        printPaymentIntent(intent);
+      }
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+  intents.command("get").description(
+    "Read a payment intent back \u2014 the way to check a payment whose outcome was unclear before doing anything else"
+  ).argument("<id>", "Payment intent ID (vpi_*)").option("--json", "Output raw JSON").action(async (id, opts) => {
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Fetching payment intent...");
+    try {
+      const intent = await client.paymentIntents.retrieve(id);
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(intent, null, 2));
+      } else {
         printPaymentIntent(intent);
       }
     } catch (err) {
@@ -797,26 +999,49 @@ function paymentIntentsCommand() {
   });
   intents.command("capture").description("Capture an authorized payment intent").argument("<id>", "Payment intent ID (vpi_*)").option(
     "--amount-to-capture <cents>",
-    "Partial capture amount in minor units (omit for full)",
-    (v) => parseInt(v, 10)
-  ).option("--idempotency-key <key>", "Idempotency key for safe retries").option("--confirm-live", CONFIRM_LIVE_DESCRIPTION).option("--json", "Output raw JSON").action(
+    "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"
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(
     async (id, opts) => {
       const apiKey = requireApiKey();
-      requireLiveConfirmation(apiKey, opts, "capture a payment intent");
+      const amountToCapture = optionalMinorUnitsOrExit(
+        opts.amountToCapture,
+        "--amount-to-capture"
+      );
+      refuseUnsafeLiveDestination(apiKey);
+      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "capture");
+      await confirmLiveAction(
+        apiKey,
+        {
+          action: "capture a payment intent (take the held money)",
+          details: [
+            ...apiHostDetail(),
+            ["Payment intent", id],
+            [
+              "Amount",
+              amountToCapture !== void 0 ? `${amountToCapture} in minor units (partial capture)` : "the full authorized amount"
+            ],
+            ["Idempotency key", idempotencyKey]
+          ]
+        },
+        opts
+      );
       const client = makeCheckoutClient();
       const spinner = startSpinner("Capturing payment intent...");
       try {
         const intent = await client.paymentIntents.capture(
           id,
-          opts.amountToCapture !== void 0 ? { amountToCapture: opts.amountToCapture } : void 0,
-          opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : void 0
+          amountToCapture !== void 0 ? { amountToCapture } : void 0,
+          { idempotencyKey }
         );
         spinner.stop();
         if (opts.json) {
           console.log(JSON.stringify(intent, null, 2));
         } else {
-          const captureLabel = opts.amountToCapture !== void 0 ? ` (partial: ${formatMinorUnits2(opts.amountToCapture, intent.currency)})` : "";
-          console.log(chalk7.green(`\u2713 Payment intent captured${captureLabel}`));
+          const captureLabel = amountToCapture !== void 0 ? ` (partial: ${formatMinorUnits2(amountToCapture, intent.currency)})` : "";
+          console.log(chalk8.green(`\u2713 Payment intent captured${captureLabel}`));
           printPaymentIntent(intent);
         }
       } catch (err) {
@@ -825,22 +1050,36 @@ function paymentIntentsCommand() {
       }
     }
   );
-  intents.command("void").description("Void an authorized (uncaptured) payment intent").argument("<id>", "Payment intent ID (vpi_*)").option("--idempotency-key <key>", "Idempotency key for safe retries").option("--confirm-live", CONFIRM_LIVE_DESCRIPTION).option("--json", "Output raw JSON").action(
+  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"
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(
     async (id, opts) => {
       const apiKey = requireApiKey();
-      requireLiveConfirmation(apiKey, opts, "void a payment intent");
+      refuseUnsafeLiveDestination(apiKey);
+      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "void");
+      await confirmLiveAction(
+        apiKey,
+        {
+          action: "void a payment intent (release the hold)",
+          details: [
+            ...apiHostDetail(),
+            ["Payment intent", id],
+            ["Idempotency key", idempotencyKey]
+          ],
+          consequence: "A voided payment cannot be captured afterwards; this cannot be undone from here."
+        },
+        opts
+      );
       const client = makeCheckoutClient();
       const spinner = startSpinner("Voiding payment intent...");
       try {
-        const intent = await client.paymentIntents.void(
-          id,
-          opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : void 0
-        );
+        const intent = await client.paymentIntents.void(id, { idempotencyKey });
         spinner.stop();
         if (opts.json) {
           console.log(JSON.stringify(intent, null, 2));
         } else {
-          console.log(chalk7.green("\u2713 Payment intent voided"));
+          console.log(chalk8.green("\u2713 Payment intent voided"));
           printPaymentIntent(intent);
         }
       } catch (err) {
@@ -854,7 +1093,7 @@ function paymentIntentsCommand() {
 
 // src/commands/refunds.ts
 import { Command as Command6 } from "commander";
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 import { formatMinorUnits as formatMinorUnits3 } from "@vonpay/checkout-node";
 function present(v) {
   return v !== void 0 && v.trim() !== "";
@@ -884,7 +1123,7 @@ function buildRefundParams(opts, metadata) {
   return params;
 }
 function printRefund(refund) {
-  const statusColor = refund.status === "succeeded" ? chalk8.green : refund.status === "failed" ? chalk8.red : chalk8.yellow;
+  const statusColor = refund.status === "succeeded" ? chalk9.green : refund.status === "failed" ? chalk9.red : chalk9.yellow;
   console.log(`  ID:             ${refund.id}`);
   if (refund.transaction !== null) {
     console.log(`  Transaction:    ${refund.transaction}`);
@@ -913,37 +1152,60 @@ function refundsCommand() {
     "Transaction ID to refund (vp_tx_*), instead of --payment-intent (prefer --payment-intent whenever the payment has one). Use it for a payment that has no payment intent, to follow the transaction a refund_target_is_duplicate error names, or as the vp_tx_id read from the session when its payment has no payment intent \u2014 only when vp_tx_count is exactly 1, and only after matching it to the order in your own records. A transaction id is also visible to the shopper's browser \u2014 only refund one you looked up from your own order records"
   ).option(
     "--amount <cents>",
-    "Refund amount in minor units (omit for full remaining balance)",
-    (v) => parseInt(v, 10)
+    "Refund amount in minor units, a whole number (omit for full remaining balance)"
   ).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("--idempotency-key <key>", "Idempotency key for safe retries").option(
-    "--confirm-live",
-    "Required to proceed when the loaded key is vp_sk_live_* (this operation is irreversible)"
-  ).option("--json", "Output raw JSON").action(async (opts) => {
+  ).option(
+    "--idempotency-key <key>",
+    "Idempotency key. Reuse the SAME key to retry safely. Generated (and printed) when omitted"
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(async (raw) => {
     try {
-      resolveRefundTarget(opts);
+      resolveRefundTarget(raw);
     } catch (err) {
       const message = err.message;
-      exitWithCliError(message, chalk8.red(`Error: ${message}`));
+      exitWithCliError(message, chalk9.red(`Error: ${message}`));
     }
     const apiKey = requireApiKey();
-    requireLiveConfirmation(apiKey, opts, "create a refund");
+    const opts = {
+      ...raw,
+      amount: optionalMinorUnitsOrExit(raw.amount, "--amount")
+    };
+    let params;
+    try {
+      params = buildRefundParams(opts, parseMetadata(opts.metadata));
+    } catch (err) {
+      handleError(err);
+    }
+    const target = resolveRefundTarget(opts);
+    refuseUnsafeLiveDestination(apiKey);
+    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "refund");
+    await confirmLiveAction(
+      apiKey,
+      {
+        action: "create a refund (send money back to the buyer)",
+        details: [
+          ...apiHostDetail(),
+          "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`
+          ],
+          ["Idempotency key", idempotencyKey]
+        ],
+        consequence: "This pays money back out of the merchant's balance and cannot be reversed once settled."
+      },
+      opts
+    );
     const client = makeCheckoutClient();
     const spinner = startSpinner("Creating refund...");
     try {
-      const metadata = parseMetadata(opts.metadata);
-      const params = buildRefundParams(opts, metadata);
-      const refund = await client.refunds.create(
-        params,
-        opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : void 0
-      );
+      const refund = await client.refunds.create(params, { idempotencyKey });
       spinner.stop();
       if (opts.json) {
         console.log(JSON.stringify(refund, null, 2));
       } else {
-        console.log(chalk8.green("\u2713 Refund created"));
+        console.log(chalk9.green("\u2713 Refund created"));
         printRefund(refund);
       }
     } catch (err) {
@@ -951,14 +1213,77 @@ function refundsCommand() {
       handleError(err);
     }
   });
+  refunds.command("list").description(
+    "List the refunds of ONE payment and its refund totals \u2014 the way to check a refund whose outcome was unclear"
+  ).option("--payment-intent <id>", "The payment's payment intent ID (vpi_*). Use this OR --transaction").option("--transaction <id>", "The payment's transaction ID (vp_tx_*), instead of --payment-intent").option("--limit <n>", "How many refunds to show (default 25, at most 100)").option("--starting-after <cursor>", "The next-page cursor printed by a previous run").option("--json", "Output raw JSON").action(
+    async (opts) => {
+      let target;
+      try {
+        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}`));
+      }
+      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}`));
+        }
+        limit = parsed.value;
+      }
+      const client = makeCheckoutClient();
+      const spinner = startSpinner("Listing refunds...");
+      try {
+        const list = await client.refunds.list(target, {
+          ...limit !== void 0 ? { limit } : {},
+          ...opts.startingAfter ? { startingAfter: opts.startingAfter } : {}
+        });
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(list, null, 2));
+          return;
+        }
+        for (const line of refundListLines(list)) console.log(line);
+      } catch (err) {
+        spinner.stop();
+        handleError(err);
+      }
+    }
+  );
   return refunds;
 }
+function refundListLines(list) {
+  const currency = list.data[0]?.currency;
+  const money = (n) => currency ? formatMinorUnits3(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"}`
+  ];
+  if (list.data.length === 0) {
+    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);
+    lines.push(
+      `  ${r.id}  ${status}  ${formatMinorUnits3(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."));
+  }
+  if (list.hasMore && list.nextCursor) {
+    lines.push(`  More: re-run with --starting-after ${safeDisplay(list.nextCursor)}`);
+  }
+  return lines;
+}
 
 // src/commands/tokens.ts
 import { Command as Command7 } from "commander";
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function printToken(token) {
-  const statusColor = token.status === "active" ? chalk9.green : token.status === "expired" ? chalk9.yellow : chalk9.red;
+  const statusColor = token.status === "active" ? chalk10.green : token.status === "expired" ? chalk10.yellow : chalk10.red;
   console.log(`  ID:        ${token.id}`);
   console.log(`  Status:    ${statusColor(token.status)}`);
   const card = formatTokenCard(token.card);
@@ -980,7 +1305,7 @@ function tokensCommand() {
       const apiKey = requireApiKey();
       if (!opts.buyerId && !opts.providerReference) {
         console.warn(
-          chalk9.yellow(
+          chalk10.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."
           )
         );
@@ -1006,7 +1331,7 @@ function tokensCommand() {
         if (opts.json) {
           console.log(JSON.stringify(token, null, 2));
         } else {
-          console.log(chalk9.green("\u2713 Token created"));
+          console.log(chalk10.green("\u2713 Token created"));
           printToken(token);
         }
       } catch (err) {
@@ -1025,33 +1350,33 @@ function formatTokenCard(card) {
 
 // src/commands/capabilities.ts
 import { Command as Command8 } from "commander";
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 function fmtBool(v) {
-  return v ? chalk10.green("yes") : chalk10.dim("no");
+  return v ? chalk11.green("yes") : chalk11.dim("no");
 }
 function fmtVoidPolicy(v) {
   switch (v) {
     case "supported":
-      return chalk10.green(v);
+      return chalk11.green(v);
     case "rerouted_to_refund":
-      return chalk10.yellow(v);
+      return chalk11.yellow(v);
     case "not_supported":
-      return chalk10.dim(v);
+      return chalk11.dim(v);
     default:
-      return chalk10.dim(String(v));
+      return chalk11.dim(String(v));
   }
 }
 function fmtDisputeReporting(v) {
-  return v === "tracked" ? chalk10.green(v) : chalk10.yellow(v);
+  return v === "tracked" ? chalk11.green(v) : chalk11.yellow(v);
 }
 function fmtSubscriptionBilling(v) {
-  if (v === true) return chalk10.yellow("yes");
-  if (v === false) return chalk10.green("no");
-  return chalk10.yellow("unknown");
+  if (v === true) return chalk11.yellow("yes");
+  if (v === false) return chalk11.green("no");
+  return chalk11.yellow("unknown");
 }
 function printCapabilities(caps) {
   const ops = caps.supportedOperations;
-  console.log(chalk10.bold("Supported operations"));
+  console.log(chalk11.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)}`);
@@ -1066,17 +1391,17 @@ function printCapabilities(caps) {
   console.log();
   if (ops.disputeReporting !== "tracked") {
     console.log(
-      chalk10.yellow(
+      chalk11.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(chalk10.bold("Subscription billing"));
+  console.log(chalk11.bold("Subscription billing"));
   console.log(`  Von Pay renews for you:   ${fmtSubscriptionBilling(caps.subscriptionBilling?.enabled)}`);
   if (caps.subscriptionBilling?.enabled !== false) {
     console.log(
-      chalk10.yellow(
+      chalk11.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.`
@@ -1084,12 +1409,12 @@ function printCapabilities(caps) {
     );
   }
   console.log();
-  console.log(chalk10.bold("Settlement currencies"));
+  console.log(chalk11.bold("Settlement currencies"));
   console.log(
-    `  ${caps.settlementCurrencies.length ? caps.settlementCurrencies.join(", ") : chalk10.dim("(none reported)")}`
+    `  ${caps.settlementCurrencies.length ? caps.settlementCurrencies.join(", ") : chalk11.dim("(none reported)")}`
   );
   console.log();
-  console.log(chalk10.bold("Rate limits"));
+  console.log(chalk11.bold("Rate limits"));
   console.log(
     `  payment intents / minute: ${caps.rateLimits.paymentIntentsPerMinute}`
   );
@@ -1115,8 +1440,8 @@ function capabilitiesCommand() {
 
 // src/commands/trigger.ts
 import { Command as Command9 } from "commander";
-import { createHmac, randomUUID as randomUUID2 } from "crypto";
-import chalk11 from "chalk";
+import { createHmac as createHmac2, randomUUID as randomUUID2 } from "crypto";
+import chalk12 from "chalk";
 import ora2 from "ora";
 
 // src/utils/forward-to.ts
@@ -1158,6 +1483,12 @@ function validateForwardTo(raw, opts) {
       reason: `${flag} scheme must be http or https; got ${url.protocol}`
     };
   }
+  if (url.username !== "" || url.password !== "") {
+    return {
+      ok: false,
+      reason: `${flag} must not contain a user name or password.`
+    };
+  }
   const host = normalizeHost(url.hostname);
   const isLoopback = LOOPBACK_HOSTS.has(host);
   if (!isLoopback && !opts.allowTunnel) {
@@ -1179,6 +1510,93 @@ function truncate2(s) {
   return s.length <= 120 ? s : `${s.slice(0, 117)}...`;
 }
 
+// src/utils/listen-forward.ts
+import { createHmac } from "crypto";
+async function forwardPayload(payload, opts) {
+  const body = JSON.stringify(payload);
+  const t = Math.floor(Date.now() / 1e3);
+  const v1 = createHmac("sha256", opts.signingSecret).update(`${t}.${body}`).digest("hex");
+  const signatureHeader = `t=${t},v1=${v1}`;
+  const timeoutMs = opts.timeoutMs ?? 5e3;
+  const localController = new AbortController();
+  const timeoutId = setTimeout(() => localController.abort(), timeoutMs);
+  const combinedSignal = anySignal([opts.signal, localController.signal]);
+  const start = Date.now();
+  try {
+    const res = await fetch(opts.url.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-vonpay-signature": signatureHeader,
+        "User-Agent": "vonpay-cli-listen"
+      },
+      body,
+      signal: combinedSignal,
+      // Never follow a redirect: a 307/308 from the local endpoint would make
+      // fetch re-send this body AND the signature header to wherever it points,
+      // including a non-loopback host --forward-to never allowed.
+      redirect: "manual"
+    });
+    try {
+      await res.arrayBuffer();
+    } catch {
+    }
+    if (isRedirect(res)) {
+      return {
+        attempted: true,
+        status: res.status,
+        latencyMs: Date.now() - start,
+        error: `the endpoint answered with a redirect (HTTP ${res.status}); it was not followed and the event was not sent anywhere else`
+      };
+    }
+    return {
+      attempted: true,
+      status: res.status,
+      latencyMs: Date.now() - start,
+      error: null
+    };
+  } catch (err) {
+    if (opts.signal.aborted) {
+      return { attempted: true, status: null, latencyMs: null, error: "aborted" };
+    }
+    if (localController.signal.aborted) {
+      return { attempted: true, status: null, latencyMs: null, error: `timeout after ${timeoutMs}ms` };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { attempted: true, status: null, latencyMs: null, error: message };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+function isRedirect(res) {
+  return res.status >= 300 && res.status < 400 || res.type === "opaqueredirect";
+}
+function anySignal(signals) {
+  if (typeof AbortSignal.any === "function") {
+    return AbortSignal.any(signals);
+  }
+  const controller = new AbortController();
+  const tracked = [];
+  const onAbort = () => {
+    for (const sig of tracked) {
+      sig.removeEventListener("abort", onAbort);
+    }
+    controller.abort();
+  };
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort();
+      for (const sig of tracked) {
+        sig.removeEventListener("abort", onAbort);
+      }
+      return controller.signal;
+    }
+    signal.addEventListener("abort", onAbort);
+    tracked.push(signal);
+  }
+  return controller.signal;
+}
+
 // src/commands/trigger.ts
 var SUPPORTED_EVENTS = [
   "charge.succeeded",
@@ -1200,7 +1618,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(
-    chalk11.yellow(
+    chalk12.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
@@ -1305,16 +1723,13 @@ function buildPayload(event, opts) {
   };
 }
 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", (v) => parseInt(v, 10)).option("--currency <code>", "Currency code").option(
+  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(
-    "--confirm-live",
-    "Required when the loaded key is vp_sk_live_*: the event is signed with that LIVE key and sent to --url"
-  ).action(async (event, opts) => {
+  ).addOption(retiredConfirmLiveOption()).action(async (event, opts) => {
     if (!SUPPORTED_EVENTS.includes(event)) {
       console.error(
-        chalk11.red(
+        chalk12.red(
           `Unknown event: ${event}
 Supported: ${SUPPORTED_EVENTS.join(", ")}`
         )
@@ -1328,21 +1743,31 @@ Supported: ${SUPPORTED_EVENTS.join(", ")}`
       tunnelFlag: "--url-tunnel"
     });
     if (!destination.ok) {
-      console.error(chalk11.red(destination.reason));
+      console.error(chalk12.red(destination.reason));
       process.exit(1);
     }
-    if (destination.warning) console.warn(chalk11.yellow(destination.warning));
+    if (destination.warning) console.warn(chalk12.yellow(destination.warning));
+    const amount = optionalMinorUnitsOrExit(
+      opts.amount === void 0 ? void 0 : String(opts.amount),
+      "--amount"
+    );
     const apiKey = requireApiKey();
-    requireLiveConfirmation(
+    await confirmLiveAction(
       apiKey,
-      opts,
-      "trigger a test webhook event",
-      `signs a synthetic event with your LIVE key and sends it to ${safeDisplay(String(opts.url))}`
+      {
+        action: "trigger a test webhook event",
+        details: [
+          ["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."
+      },
+      opts
     );
-    const payload = buildPayload(event, opts);
+    const payload = buildPayload(event, { ...opts, amount });
     const body = JSON.stringify(payload);
     const t = Math.floor(Date.now() / 1e3);
-    const v1 = createHmac("sha256", apiKey).update(`${t}.${body}`).digest("hex");
+    const v1 = createHmac2("sha256", apiKey).update(`${t}.${body}`).digest("hex");
     const signatureHeader = `t=${t},v1=${v1}`;
     const spinner = ora2(`Sending ${event} to ${opts.url}...`).start();
     try {
@@ -1354,42 +1779,53 @@ Supported: ${SUPPORTED_EVENTS.join(", ")}`
           "User-Agent": "VonPay-Webhook/1.0 (CLI trigger)"
         },
         body,
-        signal: AbortSignal.timeout(1e4)
+        signal: AbortSignal.timeout(1e4),
+        // Never follow a redirect: a 307/308 would re-send this signed body
+        // to wherever it points, including a host --url never allowed.
+        redirect: "manual"
       });
       spinner.stop();
+      if (isRedirect(response)) {
+        console.error(
+          chalk12.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(chalk11.green(`\u2713 ${event} delivered \u2192 ${response.status}`));
+        console.log(chalk12.green(`\u2713 ${event} delivered \u2192 ${response.status}`));
       } else {
         console.log(
-          chalk11.yellow(
+          chalk12.yellow(
             `\u26A0 ${event} delivered but got ${response.status} response`
           )
         );
       }
-      console.log(chalk11.dim(`  Event:   ${payload.id} (${payload.type})`));
+      console.log(chalk12.dim(`  Event:   ${payload.id} (${payload.type})`));
       console.log(
-        chalk11.dim(
+        chalk12.dim(
           `  Amount:  ${payload.data.amount} ${payload.data.currency}`
         )
       );
       console.log(
-        chalk11.dim(
+        chalk12.dim(
           `
   Verify with: vonpay.webhooks.constructEvent(rawBody, signatureHeader, secret)`
         )
       );
       console.log(
-        chalk11.dim(
+        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)`
         )
       );
     } catch (err) {
       spinner.stop();
       if (err instanceof Error && err.name === "TimeoutError") {
-        console.error(chalk11.red(`Timeout: ${opts.url} did not respond within 10s`));
+        console.error(chalk12.red(`Timeout: ${opts.url} did not respond within 10s`));
       } else {
         console.error(
-          chalk11.red(
+          chalk12.red(
             `Failed to deliver: ${err instanceof Error ? err.message : err}`
           )
         );
@@ -1401,7 +1837,7 @@ Supported: ${SUPPORTED_EVENTS.join(", ")}`
 
 // src/commands/listen.ts
 import { Command as Command10 } from "commander";
-import { VonPayCheckout as VonPayCheckout2, isLiveKey as isLiveKey3 } from "@vonpay/checkout-node";
+import { VonPayCheckout as VonPayCheckout2 } from "@vonpay/checkout-node";
 
 // ../sse-parser/dist/index.js
 var SseParser = class {
@@ -1645,24 +2081,24 @@ function noop() {
 }
 
 // src/utils/listen-output.ts
-import chalk12 from "chalk";
+import chalk13 from "chalk";
 function formatAttemptHuman(payload, forward) {
   const ts = formatTimestamp(payload.timestamp);
-  const eventType = chalk12.cyan(payload.event_type.padEnd(24));
-  const eventId = chalk12.gray(payload.event_id.padEnd(28));
-  const attempt = chalk12.gray(`attempt ${payload.attempt}`);
-  const arrow = chalk12.gray("\u2192");
+  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 upstream = formatUpstream(payload);
-  const latency = chalk12.gray(`${payload.latency_ms}ms`);
-  const liveBadge = payload.livemode ? chalk12.red(" [LIVE]") : "";
+  const latency = chalk13.gray(`${payload.latency_ms}ms`);
+  const liveBadge = payload.livemode ? chalk13.red(" [LIVE]") : "";
   let line = `[${ts}] ${eventType} ${eventId} ${attempt}  ${arrow} ${upstream}  ${latency}${liveBadge}`;
   if (forward && forward.attempted) {
-    const fwdArrow = chalk12.gray("\u2192 local");
+    const fwdArrow = chalk13.gray("\u2192 local");
     if (forward.error) {
-      line += `  ${fwdArrow} ${chalk12.red(forward.error)}`;
+      line += `  ${fwdArrow} ${chalk13.red(forward.error)}`;
     } else if (forward.status !== null) {
       const fwdStatus = formatStatus(forward.status);
-      const fwdLatency = chalk12.gray(`${forward.latencyMs}ms`);
+      const fwdLatency = chalk13.gray(`${forward.latencyMs}ms`);
       line += `  ${fwdArrow} ${fwdStatus} ${fwdLatency}`;
     }
   }
@@ -1691,21 +2127,21 @@ function formatAttemptJson(payload, forward) {
   return JSON.stringify(body);
 }
 function formatLifecycleHuman(message, kind) {
-  const tag = kind === "info" ? chalk12.cyan("[vonpay]") : kind === "warn" ? chalk12.yellow("[vonpay]") : chalk12.red("[vonpay]");
+  const tag = kind === "info" ? chalk13.cyan("[vonpay]") : kind === "warn" ? chalk13.yellow("[vonpay]") : chalk13.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 chalk12.green(String(status));
-  if (status >= 400 && status < 500) return chalk12.yellow(String(status));
-  if (status >= 500) return chalk12.red(String(status));
-  return chalk12.gray(String(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));
 }
 function formatUpstream(payload) {
   if (payload.response_status === null) {
-    return chalk12.red("timeout");
+    return chalk13.red("timeout");
   }
   return formatStatus(payload.response_status);
 }
@@ -1718,78 +2154,6 @@ function formatTimestamp(iso) {
   return `${h}:${m}:${s}`;
 }
 
-// src/utils/listen-forward.ts
-import { createHmac as createHmac2 } from "crypto";
-async function forwardPayload(payload, opts) {
-  const body = JSON.stringify(payload);
-  const t = Math.floor(Date.now() / 1e3);
-  const v1 = createHmac2("sha256", opts.signingSecret).update(`${t}.${body}`).digest("hex");
-  const signatureHeader = `t=${t},v1=${v1}`;
-  const timeoutMs = opts.timeoutMs ?? 5e3;
-  const localController = new AbortController();
-  const timeoutId = setTimeout(() => localController.abort(), timeoutMs);
-  const combinedSignal = anySignal([opts.signal, localController.signal]);
-  const start = Date.now();
-  try {
-    const res = await fetch(opts.url.toString(), {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "x-vonpay-signature": signatureHeader,
-        "User-Agent": "vonpay-cli-listen"
-      },
-      body,
-      signal: combinedSignal
-    });
-    try {
-      await res.arrayBuffer();
-    } catch {
-    }
-    return {
-      attempted: true,
-      status: res.status,
-      latencyMs: Date.now() - start,
-      error: null
-    };
-  } catch (err) {
-    if (opts.signal.aborted) {
-      return { attempted: true, status: null, latencyMs: null, error: "aborted" };
-    }
-    if (localController.signal.aborted) {
-      return { attempted: true, status: null, latencyMs: null, error: `timeout after ${timeoutMs}ms` };
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    return { attempted: true, status: null, latencyMs: null, error: message };
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
-function anySignal(signals) {
-  if (typeof AbortSignal.any === "function") {
-    return AbortSignal.any(signals);
-  }
-  const controller = new AbortController();
-  const tracked = [];
-  const onAbort = () => {
-    for (const sig of tracked) {
-      sig.removeEventListener("abort", onAbort);
-    }
-    controller.abort();
-  };
-  for (const signal of signals) {
-    if (signal.aborted) {
-      controller.abort();
-      for (const sig of tracked) {
-        sig.removeEventListener("abort", onAbort);
-      }
-      return controller.signal;
-    }
-    signal.addEventListener("abort", onAbort);
-    tracked.push(signal);
-  }
-  return controller.signal;
-}
-
 // src/commands/listen.ts
 function listenCommand() {
   return new Command10("listen").description(
@@ -1804,22 +2168,15 @@ 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").option(
-    "--confirm-live",
-    "Acknowledge that the listen stream may surface production webhook attempts (required for vp_sk_live_* keys)"
-  ).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").addOption(retiredConfirmLiveOption()).action(async (opts) => {
     const apiKey = opts.apiKey ?? requireApiKey();
+    if (opts.apiKey !== void 0) warnLiveSecretFlag(opts.apiKey, "--api-key");
     const refuse = (message) => {
       if (jsonErrorsEnabled()) exitWithCliError(message, message);
       process.stderr.write(formatLifecycleHuman(message, "error") + "\n");
       return process.exit(1);
     };
-    if (isLiveKey3(apiKey) && !opts.confirmLive) {
-      refuse(
-        "Refusing to start listen with a live key (vp_sk_live_*). Re-run with --confirm-live to acknowledge that production webhook attempts will stream to this terminal."
-      );
-    }
-    if (!apiKey.startsWith("vp_sk_test_") && !isLiveKey3(apiKey)) {
+    if (secretKeyMode(apiKey) === null) {
       refuse(
         "Listen requires a secret key (vp_sk_*). Publishable keys are rejected by the server."
       );
@@ -1834,15 +2191,36 @@ function listenCommand() {
       forwardUrl = verdict.url;
       forwardWarning = verdict.warning;
     }
-    const baseUrl = (getBaseUrl() ?? "https://checkout.vonpay.com").replace(
+    const configuredBaseUrl = getBaseUrl();
+    const destinationProblem = keyDestinationProblem(apiKey, configuredBaseUrl);
+    if (destinationProblem) refuse(destinationProblem);
+    const baseUrl = (configuredBaseUrl ?? "https://checkout.vonpay.com").replace(
       /\/+$/,
       ""
     );
+    await confirmLiveAction(
+      apiKey,
+      {
+        action: "stream live webhook delivery attempts",
+        details: [
+          ["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."
+      },
+      opts
+    );
     const sseUrl = new URL(`${baseUrl}/v1/webhook_listen`);
     if (opts.events && opts.events.length > 0) {
       sseUrl.searchParams.set("event_types", opts.events.join(","));
     }
-    const sdk = forwardUrl ? new VonPayCheckout2({ apiKey, baseUrl, appInfo: CLI_APP_INFO, errorReporter: SILENT_ERROR_REPORTER }) : null;
+    const sdk = forwardUrl ? new VonPayCheckout2({
+      apiKey,
+      baseUrl,
+      allowCustomBaseUrl: allowCustomBaseUrl(),
+      appInfo: CLI_APP_INFO,
+      errorReporter: SILENT_ERROR_REPORTER
+    }) : null;
     const controller = new AbortController();
     let eventCount = 0;
     const startedAt = Date.now();
@@ -2012,7 +2390,7 @@ function lifecycleSeverity(kind) {
 
 // src/commands/health.ts
 import { Command as Command11 } from "commander";
-import chalk13 from "chalk";
+import chalk14 from "chalk";
 import { VonPayError as VonPayError2 } from "@vonpay/checkout-node";
 function healthCommand() {
   return new Command11("health").description("Check checkout API health").option("--json", "Output raw JSON").action(async (opts) => {
@@ -2024,7 +2402,7 @@ function healthCommand() {
       if (opts.json) {
         console.log(JSON.stringify(health, null, 2));
       } else {
-        const statusColor = health.status === "ok" ? chalk13.green : health.status === "degraded" ? chalk13.yellow : chalk13.red;
+        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`);
         if (health.version) {
@@ -2035,11 +2413,11 @@ function healthCommand() {
       spinner.stop();
       if (jsonErrorsEnabled()) handleError(err);
       if (err instanceof VonPayError2) {
-        console.error(chalk13.red(`API error: ${scrubSecrets(err.message)}`));
-        console.error(chalk13.dim(`  Code: ${err.code}`));
+        console.error(chalk14.red(`API error: ${scrubSecrets(err.message)}`));
+        console.error(chalk14.dim(`  Code: ${err.code}`));
       } else {
         console.error(
-          chalk13.red(
+          chalk14.red(
             `Cannot reach API: ${scrubSecrets(err instanceof Error ? err.message : String(err))}`
           )
         );
@@ -2051,7 +2429,7 @@ function healthCommand() {
 
 // src/commands/doctor.ts
 import { Command as Command12 } from "commander";
-import chalk14 from "chalk";
+import chalk15 from "chalk";
 import ora3 from "ora";
 import { homedir as homedir2 } from "os";
 import { existsSync as existsSync3 } from "fs";
@@ -2083,14 +2461,11 @@ function maskPrefix(key) {
 }
 function keyMode(key) {
   if (!key) return void 0;
-  if (!/^vp_[ps]k_/.test(key)) return void 0;
-  if (key.includes("_test_")) return "test";
-  if (key.includes("_live_")) return "live";
-  return void 0;
+  return secretKeyMode(key) ?? "not_a_secret_key";
 }
 async function gather() {
   const config = loadConfig();
-  const apiKey = process.env.VON_PAY_SECRET_KEY ?? config.checkout?.apiKey;
+  const apiKey = process.env.VON_PAY_SECRET_KEY || config.checkout?.apiKey;
   const baseUrl = process.env.VONPAY_BASE_URL ?? "https://checkout.vonpay.com";
   const envVarsPresent = RELEVANT_ENV_VARS.filter(
     (n) => process.env[n] && process.env[n] !== ""
@@ -2122,8 +2497,14 @@ async function gather() {
       "No API key found. Set VON_PAY_SECRET_KEY in env, or run `vonpay checkout login` to save one. Without a key the health probe still runs but sessions.validate is skipped."
     );
   }
+  const shapeProblem = keyDestinationProblem("", process.env.VONPAY_BASE_URL);
+  if (shapeProblem) {
+    report.health.baseUrl = "(not shown: the base URL was refused)";
+    report.health.error = shapeProblem;
+    report.hints.push(`${shapeProblem} No probe was run.`);
+  }
   const start = Date.now();
-  try {
+  if (!shapeProblem) try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), 1e4);
     const res = await fetch(`${baseUrl}/api/health`, {
@@ -2155,11 +2536,27 @@ async function gather() {
       "Health probe could not reach the API. Check network / DNS / firewall \u2014 vonpay-checkout requires outbound HTTPS to checkout.vonpay.com."
     );
   }
-  if (apiKey && report.health.reachable) {
+  let mayProbe = Boolean(apiKey) && !shapeProblem;
+  if (apiKey && report.apiKeyMode === "not_a_secret_key") {
+    mayProbe = false;
+    report.hints.push(`${NOT_A_SECRET_KEY_MESSAGE} The sessions.validate probe was not run.`);
+  }
+  const destinationProblem = apiKey && mayProbe ? keyDestinationProblem(apiKey, process.env.VONPAY_BASE_URL) : null;
+  if (destinationProblem) {
+    mayProbe = false;
+    report.hints.push(`${destinationProblem} The sessions.validate probe was not run.`);
+  }
+  if (config.checkout?.apiKey && report.configFile.keyType === "live") {
+    report.hints.push(
+      "A LIVE key is saved in plaintext in ~/.vonpay/config.json. Live keys are no longer stored: run `vonpay checkout logout` to delete it, and supply it through VON_PAY_SECRET_KEY for the session instead."
+    );
+  }
+  if (apiKey && mayProbe && report.health.reachable) {
     try {
       const probeClient = new VonPayCheckout3({
         apiKey,
         baseUrl,
+        allowCustomBaseUrl: allowCustomBaseUrl(),
         timeout: 1e4,
         maxRetries: 0,
         errorReporter: () => {
@@ -2216,47 +2613,47 @@ async function gather() {
 }
 function renderHuman(r) {
   const lines = [];
-  lines.push(chalk14.bold.blue("vonpay doctor \u2014 diagnostic report"));
-  lines.push(chalk14.dim(`generated ${r.generatedAt}`));
+  lines.push(chalk15.bold.blue("vonpay doctor \u2014 diagnostic report"));
+  lines.push(chalk15.dim(`generated ${r.generatedAt}`));
   lines.push("");
-  lines.push(chalk14.bold("Runtime"));
+  lines.push(chalk15.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(chalk14.bold("API key"));
+  lines.push(chalk15.bold("API key"));
   if (r.apiKeyPrefix) {
     lines.push(`  Prefix:    ${r.apiKeyPrefix}`);
     lines.push(`  Mode:      ${r.apiKeyMode}`);
   } else {
-    lines.push(chalk14.dim("  (no key found in env or ~/.vonpay/config.json)"));
+    lines.push(chalk15.dim("  (no key found in env or ~/.vonpay/config.json)"));
   }
   lines.push("");
-  lines.push(chalk14.bold("Env vars present (names only)"));
+  lines.push(chalk15.bold("Env vars present (names only)"));
   if (r.envVarsPresent.length === 0) {
-    lines.push(chalk14.dim("  (none of the expected vonpay env vars are set)"));
+    lines.push(chalk15.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(chalk14.bold("Health probe"));
+  lines.push(chalk15.bold("Health probe"));
   if (r.health.reachable) {
-    const statusColor = r.health.status === "ok" ? chalk14.green : r.health.status === "degraded" ? chalk14.yellow : chalk14.red;
-    lines.push(`  Reachable: ${chalk14.green("yes")}`);
+    const statusColor = r.health.status === "ok" ? chalk15.green : r.health.status === "degraded" ? chalk15.yellow : chalk15.red;
+    lines.push(`  Reachable: ${chalk15.green("yes")}`);
     lines.push(`  Status:    ${statusColor(r.health.status ?? "?")}`);
     lines.push(`  Latency:   ${r.health.latencyMs}ms`);
   } else {
-    lines.push(`  Reachable: ${chalk14.red("no")}`);
+    lines.push(`  Reachable: ${chalk15.red("no")}`);
     lines.push(`  Error:     ${r.health.error}`);
   }
   lines.push("");
   if (r.validateProbe) {
-    lines.push(chalk14.bold("sessions.validate probe ($14.99 USD dry-run)"));
+    lines.push(chalk15.bold("sessions.validate probe ($14.99 USD dry-run)"));
     if (r.validateProbe.ok) {
-      lines.push(`  Result:    ${chalk14.green("valid")}`);
+      lines.push(`  Result:    ${chalk15.green("valid")}`);
     } else {
-      lines.push(`  Result:    ${chalk14.red("invalid")}`);
+      lines.push(`  Result:    ${chalk15.red("invalid")}`);
       if (r.validateProbe.error) {
         lines.push(`  Code:      ${r.validateProbe.error.code}`);
         lines.push(`  Action:    ${r.validateProbe.error.nextAction}`);
@@ -2269,7 +2666,7 @@ function renderHuman(r) {
     lines.push("");
   }
   if (r.hints.length > 0) {
-    lines.push(chalk14.bold("Hints"));
+    lines.push(chalk15.bold("Hints"));
     for (const h of r.hints) lines.push(`  \u2022 ${h}`);
     lines.push("");
   }