totemlayer 0.1.1 → 0.1.3

package/bin/totem.mjs

@@ -4,9 +4,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { stripVTControlCharacters } from "node:util";
 
-const RFQ_EXAMPLE =
-  "Request a quote for 50,000 Industrial Sensors (SKU-1001) from SupplyCo using Acme Procurement Agent.";
-const CLI_VERSION = "0.1.1";
+const CLI_VERSION = "0.1.3";
 const DEFAULT_BASE_URL = "https://totemlayer.com";
 const API_KEY_PATTERN = /^at_(?:live|test)_[A-Za-z0-9_-]{20,}$/;
 const ACTION_PATTERN = /^[a-z0-9][a-z0-9._:-]*$/;
@@ -16,25 +14,45 @@ const TERMINAL_UNSAFE_PATTERN =
   /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
 const MAX_JSON_INPUT_BYTES = 128 * 1_024;
 const MAX_REQUEST_FILE_BYTES = 16 * 1_024 * 1_024;
+const ISO_CURRENCY_CODES = new Set(Intl.supportedValuesOf("currency"));
 const BRAND_ART = [
   "       ╭╮",
   "   ╭───╯╰────╮   ╺┳╸┏━┓╺┳╸┏━╸┏┳┓",
   "  ╰────╮╭────╯    ┃ ┃ ┃ ┃ ┣╸ ┃┃┃",
   "       ╰╯          ╹ ┗━┛ ╹ ┗━╸╹ ╹",
 ];
-const PRESENTATION_REJECTION_CODES = new Set([
-  "CHALLENGE_NOT_FOUND",
-  "CHALLENGE_NOT_PRESENTED",
-  "CHALLENGE_ALREADY_PRESENTED",
+const HANDSHAKE_REJECTION_CODES = new Set([
+  "AGENT_AUTHORITY_REVOKED",
+  "BEACON_VERIFICATION_FAILED",
   "CHALLENGE_ALREADY_CONSUMED",
+  "CHALLENGE_ALREADY_PRESENTED",
   "CHALLENGE_EXPIRED",
+  "CHALLENGE_NOT_FOUND",
+  "CHALLENGE_NOT_PENDING",
+  "CHALLENGE_NOT_PRESENTED",
+  "CONTACT_RELATIONSHIP_CHANGED",
+  "CONTACT_RELATIONSHIP_REQUIRED",
+  "CREDENTIAL_NOT_PRESENTABLE",
+  "ENVIRONMENT_MISMATCH",
+  "ENVIRONMENT_UNCLASSIFIED",
+  "IDEMPOTENCY_KEY_REUSED",
+  "INVALID_PRESENTATION_SIGNATURE",
   "PRESENTATION_EXPIRED",
+  "PRESENTATION_CLAIMS_MISMATCH",
   "PRESENTATION_MISMATCH",
   "PRESENTER_AGENT_INACTIVE",
-  "AGENT_AUTHORITY_REVOKED",
-  "INVALID_PRESENTATION_SIGNATURE",
-  "PRESENTATION_CLAIMS_MISMATCH",
+  "TRANSACTION_NOT_AUTHORIZED",
+  "VERIFIER_AGENT_INACTIVE",
+]);
+const ACTION_CHECK_SUITE_STATUSES = new Set(["QUEUED", "RUNNING", "COMPLETED", "STALE"]);
+const ACTION_CHECK_SUITE_CONCLUSIONS = new Set([
+  "ALLOW",
+  "ALLOW_WITH_WARNINGS",
+  "REQUIRES_APPROVAL",
+  "BLOCK",
+  "ERROR",
 ]);
+const ACTION_EXECUTION_OUTCOMES = new Set(["SUCCEEDED", "FAILED", "UNKNOWN", "COMPENSATED"]);
 const ACTION_CHECK_POLICY_CODES = new Set([
   "ACTION_APPROVAL_REQUIRED",
   "ACTION_APPROVAL_STALE",
@@ -71,25 +89,144 @@ function styled(value, code, stream = process.stdout) {
   return supportsColor(stream) ? `\u001b[${code}m${value}\u001b[0m` : value;
 }
 
+function interactiveWidth(stream = process.stdout) {
+  const columns = Number(stream.columns);
+  if (!stream.isTTY || !Number.isInteger(columns) || columns < 48) return undefined;
+  return Math.min(columns, 120);
+}
+
+function wrappedTerminalLines(value, prefixLength, stream = process.stdout) {
+  const width = interactiveWidth(stream);
+  if (!width) return [value];
+  const available = Math.max(24, width - prefixLength - 1);
+  const words = value.split(" ");
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (!line) {
+      line = word;
+      continue;
+    }
+    if (line.length + word.length + 1 <= available) {
+      line += ` ${word}`;
+      continue;
+    }
+    lines.push(line);
+    line = word;
+  }
+  if (line) lines.push(line);
+  return lines.length > 0 ? lines : [""];
+}
+
+function writeHumanLine(
+  label,
+  value,
+  { stream = process.stdout, labelCode = "2", valueCode, suffix = ":" } = {},
+) {
+  const safeLabel = terminalText(label, "Result");
+  const safeValue = terminalText(value, "unknown");
+  const prefix = `${safeLabel}${suffix} `;
+  const continuation = " ".repeat(prefix.length);
+  for (const [index, line] of wrappedTerminalLines(safeValue, prefix.length, stream).entries()) {
+    const renderedValue = valueCode ? styled(line, valueCode, stream) : line;
+    stream.write(
+      index === 0
+        ? `${styled(`${safeLabel}${suffix}`, labelCode, stream)} ${renderedValue}\n`
+        : `${continuation}${renderedValue}\n`,
+    );
+  }
+}
+
+function wrappedHelpLines(line, width) {
+  if (!width || line.length <= width) return [line];
+
+  const optionMatch = line.match(
+    /^(\s{2}(?:--\S+(?:\s+<[^>]+>)?|-[hv],\s+--\S+|decision\.json|Install once|Confirm installation|Run one-off)\s+)(\S.*)$/,
+  );
+  const firstPrefix = optionMatch?.[1] ?? line.match(/^\s*/)?.[0] ?? "";
+  let continuationPrefix = optionMatch ? " ".repeat(firstPrefix.length) : firstPrefix;
+  const fallbackPrefix = firstPrefix ? "    " : "";
+  const words = (optionMatch?.[2] ?? line.slice(firstPrefix.length)).split(" ");
+  const output = [];
+  let prefix = firstPrefix;
+  let current = prefix;
+
+  for (const word of words) {
+    if (!word) continue;
+    const separator = current.length > prefix.length ? " " : "";
+    if (`${current}${separator}${word}`.length <= width) {
+      current += `${separator}${word}`;
+      continue;
+    }
+    if (current.length > prefix.length) output.push(current);
+    if (continuationPrefix.length + word.length > width) continuationPrefix = fallbackPrefix;
+    prefix = continuationPrefix;
+    current = `${prefix}${word}`;
+  }
+  if (current.length > prefix.length) output.push(current);
+  return output.length > 0 ? output : [line];
+}
+
+function writeHelpBody(body) {
+  const headings = new Set([
+    "Start here",
+    "Authorization handshake",
+    "Action Checks · local or self-hosted",
+    "Procurement demonstration",
+    "Shared options:",
+    "Challenge options:",
+    "Verification binding:",
+    "Presentation input:",
+    "Action Checks input (local/self-hosted only):",
+    "Authentication:",
+  ]);
+  const width = interactiveWidth();
+  const output = body
+    .split("\n")
+    .flatMap((line) => wrappedHelpLines(line, width))
+    .map((line) => (headings.has(line) ? styled(line, "1;38;2;58;153;200") : line))
+    .join("\n");
+  process.stdout.write(output);
+}
+
 function writeBrand() {
   const art = BRAND_ART.map((line, index) =>
     styled(line, index < 2 ? "38;2;58;153;200" : "38;2;21;37;131"),
   ).join("\n");
   process.stdout.write(`${art}\n`);
-  process.stdout.write(
-    `${styled(`TotemLayer CLI ${CLI_VERSION}`, "1")} · cross-company agent authorization\n\n`,
-  );
+  const title = `TotemLayer CLI ${CLI_VERSION} · cross-company agent authorization`;
+  const titleLines = wrappedTerminalLines(title, 0);
+  for (const [index, line] of titleLines.entries()) {
+    const versionPrefix = `TotemLayer CLI ${CLI_VERSION}`;
+    process.stdout.write(
+      `${index === 0 && line.startsWith(versionPrefix) ? styled(versionPrefix, "1") + line.slice(versionPrefix.length) : line}\n`,
+    );
+  }
+  process.stdout.write("\n");
 }
 
-function writeHumanResult(header, fields, nextStep, tone = "success") {
+function writeHumanResult(header, fields, nextStep, tone = "success", secrets = []) {
   const toneCode = tone === "danger" ? "38;2;255;114;114" : "38;2;58;153;200";
-  process.stdout.write(`${styled(header, `1;${toneCode}`)}\n`);
-  process.stdout.write(`${styled("────────────────────────────────────────", "2")}\n`);
+  process.stdout.write(`${styled(redactCliSecrets(header, secrets), `1;${toneCode}`)}\n`);
+  const dividerLength = Math.min(interactiveWidth() ?? 40, 56);
+  process.stdout.write(`${styled("─".repeat(dividerLength), "2")}\n`);
   for (const [label, value] of fields) {
     if (value === undefined || value === null || value === "") continue;
-    process.stdout.write(`${styled(`${label}:`, "2")} ${terminalText(value)}\n`);
+    writeHumanLine(label, redactCliSecrets(value, secrets), {
+      valueCode: ["Status", "Decision", "Run", "Agent authority"].includes(label)
+        ? `1;${toneCode}`
+        : undefined,
+    });
+  }
+  if (nextStep) {
+    process.stdout.write("\n");
+    writeHumanLine("Next →", nextStep, { labelCode: `1;${toneCode}`, suffix: "" });
   }
-  if (nextStep) process.stdout.write(`\n${styled("Next →", "1")} ${nextStep}\n`);
+}
+
+function writeHumanArtifact(payload, secrets) {
+  process.stdout.write(`\n${styled("Artifact JSON · save securely", "1")}\n`);
+  writeJson(redactJsonSecrets(payload, secrets));
 }
 
 function compactDigest(value) {
@@ -99,76 +236,131 @@ function compactDigest(value) {
 
 function help() {
   writeBrand();
-  process.stdout.write(`Start here
+  writeHelpBody(`Start here
   Install once          npm install --global totemlayer
   Confirm installation totem --version
   Run one-off           npx --yes totemlayer --help
 
+Agent messaging and local runtime
+  totem network --help
+  totem network run --provider ollama --model qwen3.5:9b
+
+Connect an AI app through MCP
+  totem mcp
+
 Authorization handshake
-  totem challenge --presenter-agent <agent-id> --action <action> \\
-    (--request-digest <sha256> | --request-file <path>) [--amount <number> --currency <ISO-4217>] --json
-  totem present --credential-id <credential-id> [--challenge-file <path>] --json
-  totem verify --challenge-file <receiver-challenge.json> \\
-    (--request-digest <sha256> | --request-file <path>) [--presentation-file <path>] --json
+  totem challenge \\
+    --presenter-agent <agent-id> \\
+    --action <action> \\
+    (--request-digest <sha256> | \\
+      --request-file <path>) \\
+    [--amount <number> --currency <ISO-4217>] \\
+    --json
+  totem present \\
+    --credential-id <credential-id> \\
+    [--challenge-file <path>] \\
+    --json
+  totem verify \\
+    --challenge-file <receiver-challenge.json> \\
+    (--request-digest <sha256> | \\
+      --request-file <path>) \\
+    [--presentation-file <path>] \\
+    --json
 
 Action Checks · local or self-hosted
   totem checks run --file <action.json>
   totem checks view <suite-id>
-  totem checks approve <suite-id> [--file <decision.json>]
-  totem checks reject <suite-id> [--file <decision.json>]
-  totem checks grant <suite-id> --file <action.json>
-  totem checks execute <suite-id> --file <execution.json>
+  totem checks approve <suite-id> \\
+    [--file <decision.json>]
+  totem checks reject <suite-id> \\
+    [--file <decision.json>]
+  totem checks grant <suite-id> \\
+    --file <action.json>
+  totem checks execute <suite-id> \\
+    --file <execution.json>
 
 Procurement demonstration
-  totem rfq "${RFQ_EXAMPLE}"  # sandbox/self-hosted demo only
+  totem rfq \\
+    "Request a quote for 50,000 Industrial" \\
+    "Sensors (SKU-1001) from SupplyCo using" \\
+    "Acme Procurement Agent."
+  Sandbox/self-hosted demo only.
 
 Shared options:
-  --base-url <url>          Totem URL (default: TOTEM_URL or ${DEFAULT_BASE_URL})
-  --json                    Print the complete machine-readable JSON response
+  --base-url <url>          Totem URL; default:
+                            TOTEM_URL or
+                            ${DEFAULT_BASE_URL}
+  --json                    Print complete machine-readable
+                            JSON
   -h, --help                Show this help
   -v, --version             Print the CLI version
 
 Challenge options:
-  --presenter-agent <id>    Exact agent expected to present authority
-  --action <action>         Namespaced action, for example inventory.read
-  --request-digest <sha256> SHA-256 of the request being authorized
-  --request-file <path>     Hash this file locally; file contents are never uploaded
-  --amount <number>         Optional transaction amount; requires --currency
-  --currency <code>         Three-letter ISO currency; requires --amount
-  --idempotency-key <key>   Reuse for an exact retry (a random key is used by default)
+  --presenter-agent <id>    Exact expected presenter agent
+  --action <action>         Namespaced action; for example,
+                            inventory.read
+  --request-digest <sha256> SHA-256 of the exact request
+  --request-file <path>     Hash this file locally; contents
+                            are never uploaded
+  --amount <number>         Optional amount; requires
+                            --currency
+  --currency <code>         ISO currency; requires --amount
+  --idempotency-key <key>   Reuse for an exact retry; a
+                            random key is used by default
 
 Verification binding:
-  --challenge-file <path>   Receiver's original challenge; never trust a returned copy
-  --request-digest <sha256> Require approval evidence for this exact request digest
-  --request-file <path>     Hash the exact local request before accepting an approval
+  --challenge-file <path>   Receiver's original challenge;
+                            never trust a returned copy
+  --request-digest <sha256> Require evidence for this exact
+                            request digest
+  --request-file <path>     Hash the exact local request
+                            before accepting approval
 
 Presentation input:
-  present reads challenge JSON from stdin unless --challenge-file is supplied.
-  verify reads presentation JSON from stdin unless --presentation-file is supplied and
-  compares it with the receiver-owned --challenge-file before consuming the proof.
-  Raw keys, nonces, credentials, and presentation tokens are never accepted as arguments.
+  present reads challenge JSON from stdin unless
+  you supply --challenge-file.
+  verify reads presentation JSON from stdin unless
+  you supply --presentation-file. It compares that proof
+  with the receiver-owned --challenge-file before use.
+  Raw keys, nonces, credentials, and presentation tokens are
+  never accepted as arguments.
 
 Action Checks input (local/self-hosted only):
-  --file <path>             run/grant: exact action JSON; execute: {"action":...,"grant":"..."}
-  decision.json             Optional {"confirmation":"...","reason":"..."}; never put the
-                            confirmation, grant, session cookie, or action payload on the command line
-  Action Checks always emit structured JSON. A blocked, rejected, expired, stale, or replayed
-  action exits 2; invalid input, network, authentication, and operational failures exit 1.
+  --file <path>             run/grant: exact action JSON
+                            execute: JSON containing
+                            "action" and "grant"
+  decision.json             Optional decision body; example:
+      {"confirmation":"...","reason":"..."}
+                            Never put confirmation, grant,
+                            session cookie, or action
+                            payload on the command line
+  Action Checks always emit structured JSON.
+  Blocked, rejected, expired, stale, or replayed actions
+  exit 2. Invalid input, network, authentication, and
+  operational failures exit 1.
 
 Authentication:
   challenge and verify use TOTEM_API_KEY.
-  present uses TOTEM_AGENT_API_KEY bound to the presenting agent.
-  checks run/view/grant/execute use TOTEM_API_KEY with an Action Checks scope.
-  checks approve/reject never use an API key. They require an authenticated human browser
-  session supplied only through TOTEM_SESSION_COOKIE as a Cookie header value. Clear it after
-  the command. Without it, use the /checks browser page.
-  Keys are sent only in the Authorization header and are never printed.
-
-Production supports challenge, present, and verify. Action Checks and RFQ commands require a
-sandbox or self-hosted Totem deployment with their respective local demonstrations enabled.
-
-Human-readable commands show the decision, relevant evidence, and the safest next step.
-Add --json whenever another program needs the complete machine-readable response.
+  present uses TOTEM_AGENT_API_KEY bound to the presenter.
+  checks run/view/grant/execute use TOTEM_API_KEY with an
+  Action Checks scope.
+  checks approve/reject never use an API key. They require
+  an authenticated human browser session, supplied only
+  through TOTEM_SESSION_COOKIE as a Cookie header value.
+  Clear it after the command. Without it, use /checks.
+  Keys are sent only in the Authorization header and are
+  never printed.
+
+Production supports challenge, present, and verify.
+Action Checks and RFQ require a sandbox or self-hosted Totem
+deployment with their local demonstrations enabled.
+
+Human-readable commands show the decision, evidence, and
+safest next step. Successful human challenge and present
+commands also print their complete short-lived artifact.
+Save it securely: the next participant needs its nonce or
+presentation token. Add --json when another program needs
+the complete machine-readable response.
 `);
 }
 
@@ -176,10 +368,14 @@ function fail(message) {
   process.stderr.write(
     `${styled("Totem: command failed", "1;38;2;255;114;114", process.stderr)}\n`,
   );
-  process.stderr.write(`Reason: ${terminalText(message, "The Totem command failed.")}\n`);
-  process.stderr.write(
-    "Next: Fix the reason above, or run `totem --help` for a complete example.\n",
-  );
+  writeHumanLine("Reason", terminalText(message, "The Totem command failed."), {
+    stream: process.stderr,
+    labelCode: "1;38;2;255;114;114",
+  });
+  writeHumanLine("Next", "Fix the reason above, or run `totem --help` for a complete example.", {
+    stream: process.stderr,
+    labelCode: "1;38;2;58;153;200",
+  });
   process.exitCode = 1;
 }
 
@@ -201,8 +397,23 @@ function failUnknownOutcome(message, idempotencyKey, json, machineStdout = false
   fail(`${message} The outcome is unknown; retry with --idempotency-key "${idempotencyKey}".`);
 }
 
+function failHandshakeUnknownOutcome(operation, message, json) {
+  const guidance =
+    operation === "presentation"
+      ? "Do not retry this challenge blindly; ask the receiver to reconcile it or create a fresh challenge."
+      : "Do not act on the request; reconcile the original challenge before retrying or create a fresh handshake.";
+  const safeMessage = `${message} The ${operation} outcome is unknown. ${guidance}`;
+  if (json) {
+    writeJson({ error: { message: safeMessage, outcome: "unknown", operation } });
+    process.exitCode = 1;
+    return;
+  }
+  fail(safeMessage);
+}
+
 function parseArguments(values) {
   const options = { json: false, positionals: [] };
+  let parsingOptions = true;
   const valuedOptions = new Set([
     "--base-url",
     "--idempotency-key",
@@ -219,7 +430,14 @@ function parseArguments(values) {
   ]);
   for (let index = 0; index < values.length; index += 1) {
     const value = values[index];
-    if (value === "--") continue;
+    if (parsingOptions && value === "--") {
+      parsingOptions = false;
+      continue;
+    }
+    if (!parsingOptions) {
+      options.positionals.push(value);
+      continue;
+    }
     if (value === "--json") {
       options.json = true;
       continue;
@@ -235,7 +453,9 @@ function parseArguments(values) {
     if (valuedOptions.has(value)) {
       const next = values[index + 1];
       if (!next || next.startsWith("--")) throw new Error(`${value} requires a value.`);
-      options[value.slice(2).replaceAll("-", "_")] = next;
+      const key = value.slice(2).replaceAll("-", "_");
+      if (options[key] !== undefined) throw new Error(`${value} may be supplied only once.`);
+      options[key] = next;
       index += 1;
       continue;
     }
@@ -247,8 +467,13 @@ function parseArguments(values) {
 
 function safeBaseUrl(value) {
   const url = new URL(value);
-  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
-    throw new Error("The Totem URL must be an HTTP(S) origin without credentials.");
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    (url.pathname !== "/" && url.pathname !== "")
+  ) {
+    throw new Error("The Totem URL must be an HTTP(S) origin without credentials or a path.");
   }
   const local = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
   if (url.protocol !== "https:" && !local) {
@@ -260,6 +485,21 @@ function safeBaseUrl(value) {
   return url;
 }
 
+function validIdempotencyKey(value, flag = "--idempotency-key") {
+  if (
+    typeof value !== "string" ||
+    value !== value.trim() ||
+    value.length < 8 ||
+    value.length > 128 ||
+    !SAFE_IDENTIFIER_PATTERN.test(value) ||
+    /^at_(?:live|test)_/i.test(value) ||
+    value.split(".").length === 3
+  ) {
+    throw new Error(`${flag} must contain 8 to 128 safe identifier characters.`);
+  }
+  return value;
+}
+
 function requireLocalActionChecks(baseUrl) {
   if (baseUrl.origin === DEFAULT_BASE_URL) {
     throw new Error(
@@ -326,13 +566,13 @@ function actionCheckSessionCookie() {
   return value;
 }
 
-function errorFrom(payload, fallback) {
-  if (!payload || typeof payload !== "object") return fallback;
+function errorFrom(payload, fallback, secrets = []) {
+  if (!payload || typeof payload !== "object") return redactCliSecrets(fallback, secrets);
   const error = payload.error;
-  if (!error || typeof error !== "object") return fallback;
+  if (!error || typeof error !== "object") return redactCliSecrets(fallback, secrets);
   const code = typeof error.code === "string" ? error.code : "REQUEST_FAILED";
   const message = typeof error.message === "string" ? error.message : fallback;
-  return `${code}: ${message}`;
+  return redactCliSecrets(`${code}: ${message}`, secrets);
 }
 
 function redactCliSecrets(value, secrets) {
@@ -344,6 +584,30 @@ function redactCliSecrets(value, secrets) {
   return redacted;
 }
 
+function redactJsonSecrets(value, secrets) {
+  if (typeof value === "string") {
+    let redacted = value;
+    for (const secret of secrets) {
+      if (typeof secret === "string" && secret.length >= 8) {
+        redacted = redacted.replaceAll(secret, "[REDACTED]");
+      }
+    }
+    return redacted;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactJsonSecrets(item, secrets));
+  }
+  if (record(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        redactJsonSecrets(key, secrets),
+        redactJsonSecrets(item, secrets),
+      ]),
+    );
+  }
+  return value;
+}
+
 function writeActionCheckFailure(payload, fallback, status, secrets = []) {
   const error = record(record(payload)?.error);
   const code = redactCliSecrets(
@@ -387,10 +651,33 @@ function terminalText(value, fallback = "unknown") {
   return sanitized.slice(0, 2_000) || fallback;
 }
 
+function organizationProofText(organization) {
+  if (organization?.verified !== true) return organization?.domain;
+  if (organization.accountType === "PERSONAL") return "Owner email · verified";
+  return `${terminalText(organization.domain, "verified domain")} · verified`;
+}
+
 function record(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 }
 
+function validActionCheckSuite(suite, expectedId) {
+  if (
+    !suite ||
+    typeof suite.id !== "string" ||
+    suite.id.length > 200 ||
+    !SAFE_IDENTIFIER_PATTERN.test(suite.id) ||
+    (expectedId && suite.id !== expectedId) ||
+    !ACTION_CHECK_SUITE_STATUSES.has(suite.status)
+  ) {
+    return false;
+  }
+  if (suite.conclusion === null || suite.conclusion === undefined) {
+    return suite.status !== "COMPLETED";
+  }
+  return ACTION_CHECK_SUITE_CONCLUSIONS.has(suite.conclusion);
+}
+
 function requiredOption(options, key, flag, pattern = SAFE_IDENTIFIER_PATTERN) {
   const value = options[key]?.trim();
   if (!value || value.length > 200 || (pattern && !pattern.test(value))) {
@@ -535,6 +822,7 @@ function receiverChallenge(input) {
     challenge.nonce.length < 32 ||
     challenge.nonce.length > 256 ||
     !/^[A-Za-z0-9_-]+$/.test(challenge.nonce) ||
+    !["SANDBOX", "PRODUCTION"].includes(challenge.environment) ||
     typeof challenge.requestedAction !== "string" ||
     !ACTION_PATTERN.test(challenge.requestedAction) ||
     typeof challenge.requestDigest !== "string" ||
@@ -568,6 +856,7 @@ function receiverChallenge(input) {
     issuerOrganizationId: challenge.issuerOrganizationId,
     verifierAgentId: challenge.verifierAgentId,
     presenterAgentId: challenge.presenterAgentId,
+    environment: challenge.environment,
     requestedAction: challenge.requestedAction,
     requestDigest: challenge.requestDigest.toLowerCase(),
     ...(hasAmount
@@ -617,6 +906,7 @@ function boundPresentationClaims(token, challenge, credentialId, expiresAt) {
     claims.credentialId !== credentialId ||
     claims.agentId !== challenge.presenterAgentId ||
     claims.organizationId !== challenge.issuerOrganizationId ||
+    claims.environment !== challenge.environment ||
     claims.requestedAction !== challenge.requestedAction ||
     claims.requestDigest !== challenge.requestDigest ||
     claims.transactionAmount !== expectedAmount ||
@@ -688,25 +978,21 @@ async function runChallenge(options, baseUrl) {
   let transactionAmount;
   let currency;
   if (hasAmount) {
-    transactionAmount = Number(options.amount);
-    if (!Number.isFinite(transactionAmount) || transactionAmount < 0 || transactionAmount > 1e12) {
+    const rawAmount = options.amount.trim();
+    if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(rawAmount)) {
+      throw new Error("--amount must be a decimal number from 0 through 1000000000000.");
+    }
+    transactionAmount = Number(rawAmount);
+    if (!Number.isFinite(transactionAmount) || transactionAmount > 1e12) {
       throw new Error("--amount must be a finite number from 0 through 1000000000000.");
     }
     currency = options.currency.trim().toUpperCase();
-    if (!/^[A-Z]{3}$/.test(currency)) {
-      throw new Error("--currency must be a three-letter ISO currency code.");
+    if (!ISO_CURRENCY_CODES.has(currency)) {
+      throw new Error("--currency must be a recognized three-letter ISO 4217 currency code.");
     }
   }
 
-  const idempotencyKey = options.idempotency_key ?? `cli:${randomUUID()}`;
-  if (
-    typeof idempotencyKey !== "string" ||
-    idempotencyKey.length < 8 ||
-    idempotencyKey.length > 128 ||
-    !SAFE_IDENTIFIER_PATTERN.test(idempotencyKey)
-  ) {
-    throw new Error("--idempotency-key must contain 8 to 128 safe identifier characters.");
-  }
+  const idempotencyKey = validIdempotencyKey(options.idempotency_key ?? `cli:${randomUUID()}`);
   if (!options.json) process.stderr.write(`Totem retry key: ${idempotencyKey}\n`);
 
   let result;
@@ -728,15 +1014,39 @@ async function runChallenge(options, baseUrl) {
     failUnknownOutcome(message, idempotencyKey, options.json, true);
     return;
   }
-  const challenge = record(result.payload?.challenge);
   if (!result.response.ok) {
+    const apiError = record(result.payload?.error);
+    if (typeof apiError?.code === "string" && HANDSHAKE_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
+      else {
+        writeHumanResult(
+          "Totem challenge · REJECTED",
+          [
+            ["Status", "Challenge was not created"],
+            ["Presenter", presenterAgentId],
+            ["Action", requestedAction],
+            ["Reason", apiError.code],
+          ],
+          "Resolve the policy state before creating a new challenge; this request is not authorized.",
+          "danger",
+          [key],
+        );
+      }
+      process.exitCode = 2;
+      return;
+    }
     failCommand(
-      errorFrom(result.payload, `Challenge creation returned HTTP ${result.response.status}.`),
+      errorFrom(result.payload, `Challenge creation returned HTTP ${result.response.status}.`, [
+        key,
+      ]),
       options.json,
     );
     return;
   }
-  if (!challenge || typeof challenge.id !== "string" || typeof challenge.nonce !== "string") {
+  let challenge;
+  try {
+    challenge = receiverChallenge(result.payload);
+  } catch {
     failUnknownOutcome(
       "Totem returned an invalid challenge response.",
       idempotencyKey,
@@ -745,7 +1055,28 @@ async function runChallenge(options, baseUrl) {
     );
     return;
   }
-  if (options.json) writeJson(result.payload);
+  const responseHasTransaction = challenge.transactionAmount !== undefined;
+  const replayed = result.payload?.replayed;
+  if (
+    typeof replayed !== "boolean" ||
+    result.response.status !== (replayed ? 200 : 201) ||
+    challenge.presenterAgentId !== presenterAgentId ||
+    challenge.requestedAction !== requestedAction ||
+    challenge.requestDigest !== requestDigest ||
+    Date.parse(challenge.expiresAt) <= Date.now() ||
+    responseHasTransaction !== (transactionAmount !== undefined) ||
+    (responseHasTransaction &&
+      (challenge.transactionAmount !== transactionAmount || challenge.currency !== currency))
+  ) {
+    failUnknownOutcome(
+      "Totem returned a challenge that does not match the exact request.",
+      idempotencyKey,
+      options.json,
+      true,
+    );
+    return;
+  }
+  if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
   else {
     writeHumanResult(
       `Totem challenge · ${terminalText(challenge.id)}`,
@@ -764,8 +1095,11 @@ async function runChallenge(options, baseUrl) {
         ["Expires", challenge.expiresAt],
         ["Protection", "Recipient-bound · request-bound · single-use"],
       ],
-      "Run again with --json to save the nonce-bearing challenge for the presenting agent.",
+      "Save the complete JSON artifact below as the receiver-owned challenge, then send a copy to the presenting agent.",
+      "success",
+      [key],
     );
+    writeHumanArtifact(result.payload, [key]);
   }
 }
 
@@ -780,6 +1114,7 @@ async function runPresent(options, baseUrl) {
   const nonce = challenge.nonce;
   if (
     typeof challengeId !== "string" ||
+    challengeId.length > 200 ||
     !SAFE_IDENTIFIER_PATTERN.test(challengeId) ||
     typeof nonce !== "string" ||
     nonce.length < 32 ||
@@ -789,17 +1124,27 @@ async function runPresent(options, baseUrl) {
     throw new Error("Challenge JSON is missing a valid challenge id or nonce.");
   }
 
-  const result = await requestJson({
-    baseUrl,
-    path: "/api/v1/presentations",
-    key,
-    body: { credentialId, challengeId, nonce },
-  });
+  let result;
+  try {
+    result = await requestJson({
+      baseUrl,
+      path: "/api/v1/presentations",
+      key,
+      body: { credentialId, challengeId, nonce },
+    });
+  } catch (error) {
+    failHandshakeUnknownOutcome(
+      "presentation",
+      error instanceof Error ? error.message : "Could not create the presentation.",
+      options.json,
+    );
+    return;
+  }
   const presentation = record(result.payload?.presentation);
   if (!result.response.ok) {
     const apiError = record(result.payload?.error);
-    if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
-      if (options.json) writeJson(result.payload);
+    if (typeof apiError?.code === "string" && HANDSHAKE_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
       else {
         writeHumanResult(
           "Totem presentation · REJECTED",
@@ -810,28 +1155,41 @@ async function runPresent(options, baseUrl) {
           ],
           "Return to the receiver for a fresh challenge before trying again.",
           "danger",
+          [key],
         );
       }
       process.exitCode = 2;
       return;
     }
     failCommand(
-      errorFrom(result.payload, `Presentation creation returned HTTP ${result.response.status}.`),
+      errorFrom(result.payload, `Presentation creation returned HTTP ${result.response.status}.`, [
+        key,
+      ]),
       options.json,
     );
     return;
   }
   if (
     !presentation ||
-    typeof presentation.challengeId !== "string" ||
-    typeof presentation.credentialId !== "string" ||
+    result.response.status !== 201 ||
+    presentation.challengeId !== challengeId ||
+    presentation.credentialId !== credentialId ||
     typeof presentation.token !== "string" ||
-    typeof presentation.expiresAt !== "string"
+    presentation.token.length < 20 ||
+    presentation.token.length > 100_000 ||
+    presentation.token.split(".").length !== 3 ||
+    !presentation.token.split(".").every((part) => /^[A-Za-z0-9_-]+$/.test(part)) ||
+    !validIsoTimestamp(presentation.expiresAt) ||
+    Date.parse(presentation.expiresAt) <= Date.now()
   ) {
-    failCommand("Totem returned an invalid presentation response.", options.json);
+    failHandshakeUnknownOutcome(
+      "presentation",
+      "Totem returned an invalid or mismatched presentation response.",
+      options.json,
+    );
     return;
   }
-  if (options.json) writeJson(result.payload);
+  if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
   else {
     writeHumanResult(
       `Totem presentation · ${terminalText(presentation.challengeId)}`,
@@ -844,8 +1202,11 @@ async function runPresent(options, baseUrl) {
         ["Expires", presentation.expiresAt],
         ["Protection", "Challenge-bound · recipient-bound · one-minute proof"],
       ],
-      "Run again with --json to save the token-bearing presentation for the verifier.",
+      "Save the complete JSON artifact below and return it to the verifier before the proof expires.",
+      "success",
+      [key],
     );
+    writeHumanArtifact(result.payload, [key]);
   }
 }
 
@@ -887,17 +1248,27 @@ async function runVerify(options, baseUrl) {
   }
   const claims = boundPresentationClaims(token, challenge, credentialId, presentation.expiresAt);
 
-  const result = await requestJson({
-    baseUrl,
-    path: "/api/v1/presentations/verify",
-    key,
-    body: { challengeId: challenge.id, presentation: token },
-  });
+  let result;
+  try {
+    result = await requestJson({
+      baseUrl,
+      path: "/api/v1/presentations/verify",
+      key,
+      body: { challengeId: challenge.id, presentation: token },
+    });
+  } catch (error) {
+    failHandshakeUnknownOutcome(
+      "verification",
+      error instanceof Error ? error.message : "Could not verify the presentation.",
+      options.json,
+    );
+    return;
+  }
   const payload = record(result.payload);
   if (!payload || typeof payload.verified !== "boolean" || typeof payload.result !== "string") {
     const apiError = record(payload?.error);
-    if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
-      if (options.json) writeJson(payload);
+    if (typeof apiError?.code === "string" && HANDSHAKE_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(redactJsonSecrets(payload, [key, token]));
       else {
         writeHumanResult(
           "Totem verification · REJECTED",
@@ -909,18 +1280,22 @@ async function runVerify(options, baseUrl) {
           ],
           "Create a fresh challenge and verify the exact request again before taking action.",
           "danger",
+          [key, token],
         );
       }
       process.exitCode = 2;
       return;
     }
-    failCommand(
-      errorFrom(
-        result.payload,
-        `Presentation verification returned HTTP ${result.response.status}.`,
-      ),
-      options.json,
+    const message = errorFrom(
+      result.payload,
+      `Presentation verification returned HTTP ${result.response.status}.`,
+      [key, token],
     );
+    if (result.response.status >= 500 || result.response.ok) {
+      failHandshakeUnknownOutcome("verification", message, options.json);
+    } else {
+      failCommand(message, options.json);
+    }
     return;
   }
 
@@ -972,7 +1347,7 @@ async function runVerify(options, baseUrl) {
     }
   }
 
-  if (options.json) writeJson(payload);
+  if (options.json) writeJson(redactJsonSecrets(payload, [key, token]));
   else {
     const approvedResult = payload.verified && payload.result === "APPROVED" && result.response.ok;
     writeHumanResult(
@@ -982,12 +1357,7 @@ async function runVerify(options, baseUrl) {
         ["Agent", payload.agent?.name ?? payload.agent?.id],
         ["Agent ID", payload.agent?.id],
         ["Organization", payload.organization?.name ?? payload.organization?.id],
-        [
-          "Organization proof",
-          payload.organization?.verified
-            ? `${terminalText(payload.organization.domain, "verified domain")} · verified`
-            : payload.organization?.domain,
-        ],
+        ["Organization proof", organizationProofText(payload.organization)],
         ["Action", payload.authorization?.requestedAction],
         [
           "Authority",
@@ -1011,6 +1381,7 @@ async function runVerify(options, baseUrl) {
         ? "Continue only with the unchanged request bytes shown by this approval."
         : "Do not process the request; resolve the reason and create a fresh proof.",
       approvedResult ? "success" : "danger",
+      [key, token],
     );
   }
   if (payload.verified && payload.result === "APPROVED" && result.response.ok) return;
@@ -1127,14 +1498,14 @@ async function runChecks(options, baseUrl) {
     });
     if (!payload) return;
     const suite = record(payload.suite);
-    if (!suite || typeof suite.id !== "string" || typeof suite.conclusion !== "string") {
+    if (!validActionCheckSuite(suite)) {
       writeActionCheckOperationalError("Totem returned an invalid action check suite.");
       return;
     }
-    writeJson({ suite });
+    writeJson(redactJsonSecrets({ suite }, [key]));
     if (suite.status === "STALE" || ["BLOCK", "REQUIRES_APPROVAL"].includes(suite.conclusion)) {
       process.exitCode = 2;
-    } else if (suite.conclusion === "ERROR") {
+    } else if (suite.status !== "COMPLETED" || suite.conclusion === "ERROR") {
       process.exitCode = 1;
     }
     return;
@@ -1153,11 +1524,11 @@ async function runChecks(options, baseUrl) {
     });
     if (!payload) return;
     const suite = record(payload.suite);
-    if (!suite || typeof suite.id !== "string") {
+    if (!validActionCheckSuite(suite, suiteId)) {
       writeActionCheckOperationalError("Totem returned an invalid action check suite.");
       return;
     }
-    writeJson({ suite });
+    writeJson(redactJsonSecrets({ suite }, [key]));
     return;
   }
 
@@ -1175,11 +1546,11 @@ async function runChecks(options, baseUrl) {
     });
     if (!payload) return;
     const suite = record(payload.suite);
-    if (!suite || typeof suite.id !== "string") {
+    if (!validActionCheckSuite(suite, suiteId)) {
       writeActionCheckOperationalError("Totem returned an invalid action check decision response.");
       return;
     }
-    writeJson({ suite });
+    writeJson(redactJsonSecrets({ suite }, [cookie]));
     if (decision === "REJECT") process.exitCode = 2;
     return;
   }
@@ -1203,13 +1574,17 @@ async function runChecks(options, baseUrl) {
       typeof grant.token !== "string" ||
       grant.token.length < 32 ||
       grant.token.length > 512 ||
-      typeof grant.expiresAt !== "string" ||
-      !suite
+      !validIsoTimestamp(grant.expiresAt) ||
+      !validActionCheckSuite(suite, suiteId)
     ) {
       writeActionCheckOperationalError("Totem returned an invalid execution grant response.");
       return;
     }
-    writeJson({ grant: { token: grant.token, expiresAt: grant.expiresAt, suite } });
+    writeJson(
+      redactJsonSecrets({ grant: { token: grant.token, expiresAt: grant.expiresAt, suite } }, [
+        key,
+      ]),
+    );
     return;
   }
 
@@ -1233,19 +1608,27 @@ async function runChecks(options, baseUrl) {
     const suite = record(payload.suite);
     const receipt = record(payload.receipt);
     if (
-      !suite ||
+      !validActionCheckSuite(suite, suiteId) ||
       !receipt ||
       typeof receipt.id !== "string" ||
-      typeof receipt.outcome !== "string"
+      receipt.id.length > 200 ||
+      !SAFE_IDENTIFIER_PATTERN.test(receipt.id) ||
+      !ACTION_EXECUTION_OUTCOMES.has(receipt.outcome) ||
+      (typeof receipt.suiteId === "string" && receipt.suiteId !== suiteId)
     ) {
       writeActionCheckOperationalError("Totem returned an invalid execution receipt response.");
       return;
     }
-    writeJson({
-      suite,
-      receipt,
-      ...(typeof payload.receiptId === "string" ? { receiptId: payload.receiptId } : {}),
-    });
+    writeJson(
+      redactJsonSecrets(
+        {
+          suite,
+          receipt,
+          ...(typeof payload.receiptId === "string" ? { receiptId: payload.receiptId } : {}),
+        },
+        [key, grant],
+      ),
+    );
     if (["FAILED", "UNKNOWN", "COMPENSATED"].includes(receipt.outcome)) process.exitCode = 1;
     return;
   }
@@ -1264,8 +1647,11 @@ async function runRfq(options, baseUrl) {
   }
   const requestParts = options.positionals.slice(1);
   if (requestParts.length === 0) throw new Error('Provide an RFQ request after the "rfq" command.');
-  const idempotencyKey = options.idempotency_key ?? `cli:${randomUUID()}`;
   const prompt = requestParts.join(" ").trim();
+  if (prompt.length < 4 || prompt.length > 2_000) {
+    throw new Error("The RFQ request must contain 4 to 2000 characters.");
+  }
+  const idempotencyKey = validIdempotencyKey(options.idempotency_key ?? `cli:${randomUUID()}`);
   process.stderr.write(`Totem retry key: ${idempotencyKey}\n`);
 
   let result;
@@ -1285,6 +1671,7 @@ async function runRfq(options, baseUrl) {
         : "Could not reach Totem.",
       idempotencyKey,
       options.json,
+      options.json,
     );
     return;
   }
@@ -1292,18 +1679,28 @@ async function runRfq(options, baseUrl) {
     const message = errorFrom(
       result.payload,
       `The RFQ endpoint returned HTTP ${result.response.status}.`,
+      [key],
     );
-    if (result.response.status >= 500) failUnknownOutcome(message, idempotencyKey, options.json);
-    else fail(message);
+    if (result.response.status >= 500) {
+      failUnknownOutcome(message, idempotencyKey, options.json, options.json);
+    } else {
+      failCommand(message, options.json);
+    }
     return;
   }
   const run = record(result.payload?.run);
   if (!run) {
-    failUnknownOutcome("Totem returned an invalid success response.", idempotencyKey, options.json);
+    failUnknownOutcome(
+      "Totem returned an invalid success response.",
+      idempotencyKey,
+      options.json,
+      options.json,
+    );
     return;
   }
   if (options.json) {
-    writeJson(result.payload);
+    writeJson(redactJsonSecrets(result.payload, [key]));
+    if (run.status !== "SUCCEEDED") process.exitCode = 1;
     return;
   }
 
@@ -1338,12 +1735,43 @@ async function runRfq(options, baseUrl) {
       ? "Review the supplier response and retain the run ID as the audit reference."
       : "Open the Totem operator run for the bounded trace before retrying.",
     succeeded ? "success" : "danger",
+    [key],
   );
   if (run.status !== "SUCCEEDED") process.exitCode = 1;
 }
 
 async function main() {
+  if (process.argv[2] === "mcp") {
+    if (process.argv[3] === "install" || process.argv[3] === "--help" || process.argv[3] === "-h") {
+      const { installTotemMcp } = await import("./mcp-install.mjs");
+      try {
+        process.stdout.write(
+          await installTotemMcp(process.argv[3] === "install" ? process.argv.slice(4) : ["--help"]),
+        );
+      } catch (error) {
+        process.stderr.write(
+          `${error instanceof Error ? error.message : "Could not install the Totem MCP server."}\n`,
+        );
+        process.exitCode = 1;
+      }
+      return;
+    }
+    if (process.argv.length > 3) {
+      process.stderr.write("Unknown Totem MCP option. Run `totem mcp install --help`.\n");
+      process.exitCode = 1;
+      return;
+    }
+    const { mcpMain } = await import("./local-mcp.mjs");
+    await mcpMain();
+    return;
+  }
+  if (process.argv[2] === "network") {
+    const { networkMain } = await import("./network.mjs");
+    await networkMain(process.argv.slice(3));
+    return;
+  }
   let options;
+  const jsonRequested = process.argv.slice(2).includes("--json");
   try {
     options = parseArguments(process.argv.slice(2));
     const command = options.positionals[0];
@@ -1368,8 +1796,7 @@ async function main() {
     const message = error instanceof Error ? error.message : "The Totem command failed.";
     const command = options?.positionals?.[0] ?? process.argv[2];
     if (command === "checks") writeActionCheckOperationalError(message);
-    else if (command && command !== "rfq") failCommand(message, options?.json);
-    else fail(message);
+    else failCommand(message, options?.json ?? jsonRequested);
   }
 }