@trucore/atf 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TruCore AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# @trucore/atf
+
+> Agent Transaction Firewall CLI — simulate, verify, and audit on-chain transactions trustlessly.
+
+## One-Liner
+
+```bash
+npx @trucore/atf@1.0.0 simulate --preset swap_small --verify --pretty
+```
+
+That's it. No install, no config, no API key required.
+
+## What It Does
+
+1. Sends a deterministic preset transaction to the ATF public API
+2. Returns **allowed** or **denied** with a reason and receipt hash
+3. Verifies **content_hash** integrity client-side — don't trust TruCore, verify
+
+## Install (optional)
+
+```bash
+npm install -g @trucore/atf@1.0.0
+```
+
+Or use directly with `npx` (always pin the version):
+
+```bash
+npx @trucore/atf@1.0.0 simulate --preset swap_small
+```
+
+## Commands
+
+### `health`
+
+Check API health and round-trip latency.
+
+```bash
+npx @trucore/atf@1.0.0 health
+npx @trucore/atf@1.0.0 health --pretty
+npx @trucore/atf@1.0.0 health --base-url http://localhost:3000
+```
+
+**Output shape:**
+
+```json
+{ "ok": true, "baseUrl": "https://api.trucore.xyz", "latency_ms": 42, "response": { "status": "ok" } }
+```
+
+### `simulate`
+
+Run a transaction simulation against the ATF API.
+
+```bash
+npx @trucore/atf@1.0.0 simulate --preset swap_small --verify
+npx @trucore/atf@1.0.0 simulate --preset swap_too_large --pretty
+npx @trucore/atf@1.0.0 simulate --json '{"chain_id":1,"value_eth":"0.5"}' --base-url http://localhost:3000
+```
+
+**Output shape:**
+
+```json
+{ "ok": true, "baseUrl": "https://api.trucore.xyz", "preset": "swap_small", "verified": true, "response": { "decision": "allowed", "reasons": [], "receipt_hash": "a1b2...64hex", "content_hash": "c3d4...64hex" } }
+```
+
+### `approve`
+
+Approve a pending intent (requires authentication).
+
+```bash
+npx @trucore/atf@1.0.0 approve --intent abc123 --token mytoken
+npx @trucore/atf@1.0.0 approve --intent abc123 --token mytoken --pretty
+```
+
+**Output shape:**
+
+```json
+{ "ok": true, "baseUrl": "https://api.trucore.xyz", "intent": "abc123", "response": { "intent_id": "abc123", "status": "approved" } }
+```
+
+### `version`
+
+Show rich version information (CLI version, Node version, build info).
+
+```bash
+npx @trucore/atf@1.0.0 version
+npx @trucore/atf@1.0.0 version --pretty
+```
+
+**Output shape:**
+
+```json
+{ "ok": true, "cli_version": "1.0.0", "node_version": "v22.0.0", "platform": "linux", "arch": "x64", "default_base_url": "https://api.trucore.xyz", "build_commit": "abc1234", "build_date": "2025-01-01T00:00:00Z" }
+```
+
+## Global Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--base-url <url>` | API base URL | `https://api.trucore.xyz` |
+| `--timeout-ms <ms>` | Request timeout in milliseconds | `20000` |
+| `--format <fmt>` | Output: `json` or `pretty` | `json` |
+| `--pretty` | Shorthand for `--format pretty` | `false` |
+| `--no-color` | Disable ANSI colors | `false` |
+| `--api-key <key>` | API key (also: `ATF_API_KEY` env var) | — |
+
+## Simulate Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--preset <name>` | Built-in preset: `swap_small`, `swap_too_large`, `ttl_too_high` | — |
+| `--json '<json>'` | Raw JSON transaction body | — |
+| `--verify` | Verify content_hash integrity | `false` |
+| `--quiet` | Suppress non-essential output | `false` |
+
+## Approve Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--intent <id>` | Intent ID to approve (required) | — |
+| `--intent-id <id>` | Alias for `--intent` (backward compat) | — |
+| `--token <bearer>` | Bearer token for auth (also: `ATF_API_KEY` env var) | — |
+
+### Presets
+
+| Preset | Description | Expected |
+|--------|-------------|----------|
+| `swap_small` | Small 0.01 ETH swap | ALLOWED |
+| `swap_too_large` | 999,999 ETH swap | DENIED (value limit) |
+| `ttl_too_high` | Swap with 24h TTL | DENIED (TTL policy) |
+
+## Output
+
+All commands return a JSON envelope with `"ok": true/false`.
+
+### Success (JSON, default)
+
+```json
+{
+  "ok": true,
+  "baseUrl": "https://api.trucore.xyz",
+  "preset": "swap_small",
+  "verified": true,
+  "response": {
+    "decision": "allowed",
+    "reasons": [],
+    "receipt_hash": "a1b2c3...64hex",
+    "content_hash": "d4e5f6...64hex"
+  }
+}
+```
+
+When `--verify` is not used, the `verified` field is `null`.
+When a preset is not used, the `preset` field is `null`.
+```
+
+### Success (Pretty, `--pretty`)
+
+```
+  ✓ ALLOWED
+  Reason: All policies passed
+  Receipt: a1b2c3...64hex
+
+  ✓ Content hash verified
+```
+
+### Errors
+
+All errors return a structured JSON envelope:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "NETWORK_ERROR",
+    "message": "Network failure — fetch failed",
+    "details": {
+      "hint": "Check your network connection and base URL."
+    }
+  }
+}
+```
+
+Error codes: `USER_ERROR`, `DENIED`, `NETWORK_ERROR`, `SERVER_ERROR`, `VALIDATION_ERROR`, `AUTH_ERROR`, `VERIFY_FAILED`.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (allowed, healthy, approved, etc.) |
+| 1 | User error or denied (bad input, auth failure, transaction denied, verify failed) |
+| 2 | Network / server error (unreachable, 5xx, timeout, rate limited) |
+
+## Trustless Verification
+
+**Don't trust TruCore — verify.**
+
+Every simulation produces a `content_hash` (SHA-256). You can:
+
+1. **Use `--verify` flag:** Automatically recomputes and checks content_hash integrity client-side.
+2. **Recompute locally:** The policy engine is deterministic. Same input → same hash.
+3. **Check receipt signatures** (when available): `GET /api/receipt-signing-key`
+
+The `--verify` flag checks content_hash integrity automatically. On mismatch it exits 1 with `VERIFY_FAILED`.
+
+## Token Redaction
+
+Bearer tokens are **never** emitted in CLI output. All stdout/stderr is scrubbed
+for token values and `Bearer <token>` patterns before printing.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ATF_API_KEY` | API key (sent as `x-api-key` header or Bearer token) |
+| `ATF_BASE_URL` | Override default base URL |
+| `ATF_TIMEOUT_MS` | Override default timeout (milliseconds, default: `20000`) |
+| `NO_COLOR` | Disable ANSI colors when set |
+
+## Requirements
+
+- Node.js 18+
+- **Zero** runtime dependencies
+
+## Development
+
+```bash
+# Build
+node build.mjs
+
+# Test (all offline — no network calls)
+node --test tests/*.mjs
+
+# Pack (dry run — verify included files)
+npm pack --dry-run
+```
+
+## Publishing
+
+```bash
+# 1. Build
+node build.mjs
+
+# 2. Run all tests
+node --test tests/*.mjs
+
+# 3. Inspect the tarball
+npm pack --dry-run
+#    Expected files: LICENSE, README.md, dist/index.js, package.json
+
+# 4. Publish to npm (requires npm login)
+npm publish --access public
+
+# 5. Verify install (from a clean machine or CI)
+npx @trucore/atf@1.0.0 version
+npx @trucore/atf@1.0.0 health
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,1073 @@
+#!/usr/bin/env node
+"use strict";
+
+// @trucore/atf v1.0.0 — Agent Transaction Firewall CLI
+// Built: 2026-02-27T22:14:44.003Z
+// Commit: 809c30e
+
+// ---- src/constants.mjs ----
+/**
+ * constants.mjs — shared constants for the ATF CLI
+ *
+ * Build-time placeholders (__BUILD_COMMIT__, __BUILD_DATE__) are replaced
+ * by build.mjs during the bundling step.
+ */
+
+const VERSION = "1.0.0";
+const DEFAULT_BASE_URL = "https://api.trucore.xyz";
+const BUILD_COMMIT = "809c30e";
+const BUILD_DATE = "2026-02-27T22:14:44.003Z";
+const SIMULATE_PATHS = ["/api/simulate", "/v1/simulate"];
+
+// ---- src/redact.mjs ----
+/**
+ * redact.mjs — token redaction utilities
+ *
+ * Ensures secrets (Bearer tokens, API keys) never appear in CLI output.
+ * Used by approve, error handling, and the global catch handler.
+ */
+
+const BEARER_PATTERN = /Bearer\s+[A-Za-z0-9\-\._~\+\/]+=*/g;
+
+/**
+ * Replace any occurrence of `token` with ***REDACTED***.
+ * Also scrub Bearer patterns for defense-in-depth.
+ */
+function redactToken(str, token) {
+  if (!str || typeof str !== "string") return str || "";
+  let result = str;
+  if (token && typeof token === "string" && token.length > 0) {
+    // split+join: safe literal replacement (no regex special-char issues)
+    result = result.split(token).join("***REDACTED***");
+  }
+  result = result.replace(BEARER_PATTERN, "Bearer ***REDACTED***");
+  return result;
+}
+
+// ---- src/presets.mjs ----
+/**
+ * presets.mjs — deterministic simulation presets
+ */
+
+const PRESETS = {
+  swap_small: {
+    description: "Small token swap (should be ALLOWED)",
+    transaction: {
+      chain_id: 1,
+      from_address: "0x1234567890abcdef1234567890abcdef12345678",
+      to_address: "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
+      value_eth: "0.01",
+      function_name: "swap",
+      protocol: "0x",
+      calldata_summary: "swap exactInputSingle 0.01 ETH -> USDC",
+      estimated_gas: 150000,
+    },
+  },
+  swap_too_large: {
+    description: "Oversized swap (should be DENIED by value limit)",
+    transaction: {
+      chain_id: 1,
+      from_address: "0x1234567890abcdef1234567890abcdef12345678",
+      to_address: "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
+      value_eth: "999999.0",
+      function_name: "swap",
+      protocol: "0x",
+      calldata_summary: "swap exactInputSingle 999999 ETH -> USDC",
+      estimated_gas: 150000,
+    },
+  },
+  ttl_too_high: {
+    description: "Transaction with excessive TTL (should be DENIED by TTL policy)",
+    transaction: {
+      chain_id: 1,
+      from_address: "0x1234567890abcdef1234567890abcdef12345678",
+      to_address: "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
+      value_eth: "0.01",
+      function_name: "swap",
+      protocol: "0x",
+      calldata_summary: "swap with TTL=86400",
+      estimated_gas: 150000,
+      ttl_seconds: 86400,
+    },
+  },
+};
+
+const PRESET_NAMES = Object.keys(PRESETS);
+
+// ---- src/validate.mjs ----
+/**
+ * validate.mjs — receipt hash and input validation
+ */
+
+const RECEIPT_HASH_RE = /^[0-9a-f]{64}$/;
+
+function isValidReceiptHash(hash) {
+  return typeof hash === "string" && RECEIPT_HASH_RE.test(hash);
+}
+
+function validatePreset(name) {
+  if (!PRESETS[name]) {
+    return {
+      ok: false,
+      message: `Unknown preset "${name}". Available: ${PRESET_NAMES.join(", ")}`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Recursively sort object keys for canonical JSON serialization.
+ * Arrays are left in-order; non-objects pass through.
+ */
+function sortKeysDeep(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sortKeysDeep);
+  const sorted = {};
+  for (const k of Object.keys(obj).sort()) sorted[k] = sortKeysDeep(obj[k]);
+  return sorted;
+}
+
+/**
+ * Compute a deterministic content hash from the canonical payload.
+ * SHA-256 over canonicalized JSON (sorted keys recursively, compact separators, UTF-8).
+ *
+ * Canonical payload fields (MUST match Python exactly):
+ *   - decision (lowercase string)
+ *   - reasons (array of strings — order preserved)
+ *   - policy_hash (string) — omit if null/empty
+ *   - params (object)      — omit if null/empty
+ *
+ * Used by --verify to detect response tampering.
+ */
+function computeContentHash(decision, reasons, policyHash, params) {
+  // require used inline — safe in the CJS bundle (dist/index.js)
+  const { createHash } = require("node:crypto");
+  const payload = {
+    decision: (decision || "").toLowerCase(),
+    reasons: Array.isArray(reasons) ? reasons : [],
+  };
+  if (policyHash !== undefined && policyHash !== null && policyHash !== "") {
+    payload.policy_hash = policyHash;
+  }
+  if (params !== undefined && params !== null && typeof params === "object" && Object.keys(params).length > 0) {
+    payload.params = params;
+  }
+  const canonical = JSON.stringify(sortKeysDeep(payload));
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+/**
+ * Legacy content hash — decision + reason only (for backward compat).
+ */
+function computeLegacyContentHash(decision, reason) {
+  const { createHash } = require("node:crypto");
+  const payload = { decision: (decision || "").toLowerCase(), reason: reason || "" };
+  const keys = Object.keys(payload).sort();
+  const sorted = {};
+  for (const k of keys) sorted[k] = payload[k];
+  const canonical = JSON.stringify(sorted);
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+function parseJsonBody(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return { ok: false, message: "JSON body must be an object" };
+    }
+    return { ok: true, body: parsed };
+  } catch (e) {
+    return { ok: false, message: `Invalid JSON: ${e.message}` };
+  }
+}
+
+// ---- src/http.mjs ----
+/**
+ * http.mjs — minimal HTTP helpers using Node 18+ built-in fetch.
+ * Zero runtime dependencies.
+ */
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+const MAX_TEXT_CAPTURE = 4096;
+
+function resolveTimeout(overrideMs) {
+  if (overrideMs && overrideMs > 0) return overrideMs;
+  const envMs = process.env.ATF_TIMEOUT_MS;
+  if (envMs) {
+    const parsed = parseInt(envMs, 10);
+    if (parsed > 0) return parsed;
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+
+function generateRequestId() {
+  const { randomBytes } = require("node:crypto");
+  return randomBytes(8).toString("hex");
+}
+
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+
+async function getHealth(baseUrl, timeoutMs) {
+  const timeout = resolveTimeout(timeoutMs);
+  const requestId = generateRequestId();
+  const url = `${stripTrailingSlash(baseUrl)}/health`;
+  const res = await fetch(url, {
+    headers: { "X-Request-ID": requestId },
+    signal: AbortSignal.timeout(timeout),
+  });
+  const parsed = await parseResponse(res);
+  parsed.requestId = requestId;
+  return parsed;
+}
+
+async function postSimulate(baseUrl, body, apiKey, timeoutMs, path) {
+  const timeout = resolveTimeout(timeoutMs);
+  const requestId = generateRequestId();
+  const url = `${stripTrailingSlash(baseUrl)}${path || "/api/simulate"}`;
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Request-ID": requestId,
+  };
+  if (apiKey) headers["x-api-key"] = apiKey;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeout),
+  });
+  const parsed = await parseResponse(res);
+  parsed.requestId = requestId;
+  return parsed;
+}
+
+async function postApprove(baseUrl, intentId, token, timeoutMs) {
+  const timeout = resolveTimeout(timeoutMs);
+  const requestId = generateRequestId();
+  const url = `${stripTrailingSlash(baseUrl)}/v1/intents/approve`;
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${token}`,
+    "X-Request-ID": requestId,
+  };
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ intent_id: intentId }),
+    signal: AbortSignal.timeout(timeout),
+  });
+  const parsed = await parseResponse(res);
+  parsed.requestId = requestId;
+  return parsed;
+}
+
+async function getReceiptSigningKey(baseUrl) {
+  const url = `${stripTrailingSlash(baseUrl)}/api/receipt-signing-key`;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return { available: false };
+    const data = await res.json();
+    return data;
+  } catch {
+    return { available: false };
+  }
+}
+
+async function parseResponse(res) {
+  const rateLimitHeaders = {};
+  for (const h of ["x-ratelimit-limit", "x-ratelimit-remaining", "x-ratelimit-reset"]) {
+    const v = res.headers.get(h);
+    if (v !== null) rateLimitHeaders[h] = v;
+  }
+
+  let data;
+  const rawText = await res.text();
+  const text = rawText.slice(0, MAX_TEXT_CAPTURE);
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = null;
+  }
+
+  return {
+    ok: res.ok,
+    status: res.status,
+    data,
+    text,
+    rateLimitHeaders,
+    retryAfter: res.headers.get("retry-after"),
+  };
+}
+
+// ---- src/format.mjs ----
+/**
+ * format.mjs — shared ANSI color constants
+ *
+ * Each command handles its own output formatting.
+ * COLORS is shared across errors.mjs, health.mjs, approve.mjs,
+ * version_cmd.mjs, simulate.mjs, and cli.mjs.
+ */
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  gray: "\x1b[90m",
+};
+
+// ---- src/errors.mjs ----
+/**
+ * errors.mjs — structured error model for the ATF CLI
+ *
+ * Error envelope:   { ok: false, error: { code, message, details? } }
+ * Success envelope: { ok: true, ... }
+ *
+ * Exit codes:
+ *   0 — success (allowed, healthy, version)
+ *   1 — user error / denied / verify-failed / 401 / 403 / 404 / 409
+ *   2 — network / server error (fetch throw, timeout, 5xx, rate-limited)
+ */
+
+const ERROR_CODES = {
+  USER_ERROR: "USER_ERROR",
+  DENIED: "DENIED",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  SERVER_ERROR: "SERVER_ERROR",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  AUTH_ERROR: "AUTH_ERROR",
+  VERIFY_FAILED: "VERIFY_FAILED",
+};
+
+function makeError(code, message, details) {
+  const err = { code, message };
+  if (details && typeof details === "object" && Object.keys(details).length > 0) {
+    err.details = details;
+  }
+  return { ok: false, error: err };
+}
+
+function exitCodeForError(code) {
+  switch (code) {
+    case ERROR_CODES.NETWORK_ERROR:
+    case ERROR_CODES.SERVER_ERROR:
+      return 2;
+    default:
+      return 1;
+  }
+}
+
+function formatErrorPretty(errEnvelope) {
+  const e = errEnvelope.error;
+  const noColor = process.env.NO_COLOR;
+  const c = noColor ? { reset: "", bold: "", red: "", dim: "", yellow: "", cyan: "" } : COLORS;
+  const lines = [];
+  lines.push("");
+  lines.push(`${c.bold}${c.red}  \u2717 ERROR [${e.code}]${c.reset}`);
+  lines.push(`  ${e.message}`);
+  if (e.details) {
+    if (e.details.hint) lines.push(`${c.dim}  Hint: ${e.details.hint}${c.reset}`);
+    if (e.details.status) lines.push(`${c.dim}  HTTP status: ${e.details.status}${c.reset}`);
+    if (e.details.requestId) lines.push(`${c.dim}  Request ID: ${e.details.requestId}${c.reset}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Returns true if `obj` looks like a structured ATF error envelope.
+ * Shape: { ok: false, error: { code: <string>, ... } }
+ * Used to distinguish app-level 404s from endpoint-miss 404s.
+ */
+function isAtfErrorEnvelope(obj) {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    obj.ok === false &&
+    obj.error !== null &&
+    typeof obj.error === "object" &&
+    typeof obj.error.code === "string"
+  );
+}
+
+function exitWithError(code, message, hint, format, extra) {
+  const details = {};
+  if (hint) details.hint = hint;
+  if (extra && extra.status) details.status = extra.status;
+  if (extra && extra.requestId) details.requestId = extra.requestId;
+  if (extra && extra.path) details.path = extra.path;
+  if (extra && extra.attempted_paths) details.attempted_paths = extra.attempted_paths;
+  if (extra && extra.baseUrl) details.baseUrl = extra.baseUrl;
+  const err = makeError(code, message, Object.keys(details).length > 0 ? details : undefined);
+  if (format === "pretty") {
+    process.stderr.write(formatErrorPretty(err));
+  } else {
+    process.stdout.write(JSON.stringify(err, null, 2) + "\n");
+  }
+  process.exit(exitCodeForError(code));
+}
+
+// ---- src/health.mjs ----
+/**
+ * health.mjs — health command implementation
+ *
+ * GET {base}/health — check API availability and measure latency.
+ * Output: { ok:true, baseUrl, latencyMs, response:<healthJson> }
+ */
+
+async function runHealth(args) {
+  const baseUrl = args.baseUrl;
+  const format = args.format;
+  const timeoutMs = args.timeoutMs;
+
+  const start = Date.now();
+  let response;
+  try {
+    response = await getHealth(baseUrl, timeoutMs);
+  } catch (err) {
+    exitWithError(
+      ERROR_CODES.NETWORK_ERROR,
+      `Cannot reach ${baseUrl}/health — ${err.message}`,
+      "Check that the API is running and the base URL is correct.",
+      format
+    );
+  }
+  const latencyMs = Date.now() - start;
+
+  if (!response.ok) {
+    exitWithError(
+      ERROR_CODES.SERVER_ERROR,
+      `Health check failed with HTTP ${response.status}`,
+      "The API may be down or misconfigured.",
+      format,
+      { status: response.status, requestId: response.requestId }
+    );
+  }
+
+  const result = {
+    ok: true,
+    baseUrl,
+    latency_ms: latencyMs,
+    response: response.data || {},
+  };
+
+  if (format === "pretty") {
+    const noColor = process.env.NO_COLOR;
+    const c = noColor ? { reset: "", bold: "", green: "", dim: "" } : COLORS;
+    process.stdout.write(
+      `\n${c.bold}${c.green}  \u2713 HEALTHY${c.reset}\n` +
+        `${c.dim}  Base URL:${c.reset} ${baseUrl}\n` +
+        `${c.dim}  Latency:${c.reset}  ${latencyMs}ms\n` +
+        `${c.dim}  HTTP:${c.reset}     ${response.status}\n\n`
+    );
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+  process.exit(0);
+}
+
+// ---- src/approve.mjs ----
+/**
+ * approve.mjs — approve command implementation
+ *
+ * POST {base}/v1/intents/approve with Bearer token.
+ * Approves a pending intent returned from a previous simulation.
+ * Output: { ok:true, baseUrl, intent, response:<approveJson> }
+ */
+
+async function runApprove(args) {
+  const baseUrl = args.baseUrl;
+  const format = args.format;
+  const token = args.token || args.apiKey;
+  const intent = args.intent;
+  const timeoutMs = args.timeoutMs;
+
+  if (!intent) {
+    exitWithError(
+      ERROR_CODES.USER_ERROR,
+      "Missing --intent <id>",
+      "Provide the intent ID returned from a simulation.",
+      format
+    );
+  }
+
+  if (!token) {
+    exitWithError(
+      ERROR_CODES.AUTH_ERROR,
+      "Missing authentication token",
+      "Provide --token <bearer> or set ATF_API_KEY env var.",
+      format
+    );
+  }
+
+  let response;
+  try {
+    response = await postApprove(baseUrl, intent, token, timeoutMs);
+  } catch (err) {
+    exitWithError(
+      ERROR_CODES.NETWORK_ERROR,
+      redactToken(`Cannot reach ${baseUrl} — ${err.message}`, token),
+      "Check your network connection and base URL.",
+      format
+    );
+  }
+
+  if (!response.ok) {
+    const data = response.data || {};
+    const errCode =
+      response.status >= 500
+        ? ERROR_CODES.SERVER_ERROR
+        : response.status === 401 || response.status === 403
+          ? ERROR_CODES.AUTH_ERROR
+          : ERROR_CODES.USER_ERROR;
+    const hint =
+      response.status === 401
+        ? "Check your Bearer token."
+        : response.status === 404
+          ? "Intent not found — check the intent ID."
+          : response.status === 409
+            ? "Intent already approved or expired."
+            : null;
+    const msg = redactToken(data.message || data.detail || `HTTP ${response.status}`, token);
+    exitWithError(
+      errCode,
+      msg,
+      hint,
+      format,
+      { status: response.status, requestId: response.requestId || data.request_id }
+    );
+  }
+
+  const data = response.data || {};
+  const result = { ok: true, baseUrl, intent, response: data };
+  if (args.verbose && args._deprecatedIntentId) {
+    result.warnings = ["--intent-id is deprecated; use --intent"];
+  }
+
+  if (format === "pretty") {
+    const noColor = process.env.NO_COLOR;
+    const c = noColor ? { reset: "", bold: "", green: "", dim: "" } : COLORS;
+    process.stdout.write(
+      `\n${c.bold}${c.green}  \u2713 APPROVED${c.reset}\n` +
+        `${c.dim}  Intent:${c.reset}  ${intent}\n` +
+        (data.tx_hash
+          ? `${c.dim}  TX Hash:${c.reset} ${data.tx_hash}\n`
+          : "") +
+        `\n`
+    );
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+  process.exit(0);
+}
+
+// ---- src/version_cmd.mjs ----
+/**
+ * version_cmd.mjs — rich version command
+ *
+ * Output: { ok:true, cli_version, node_version, platform, arch, default_base_url, build_commit, build_date }
+ */
+
+async function runVersion(args) {
+  const format = args.format;
+  const commit = BUILD_COMMIT === "__BUILD_COMMIT__" ? null : BUILD_COMMIT;
+  const buildTime = BUILD_DATE === "__BUILD_DATE__" ? null : BUILD_DATE;
+  const result = {
+    ok: true,
+    cli_version: VERSION,
+    node_version: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    default_base_url: DEFAULT_BASE_URL,
+    build_commit: commit,
+    build_date: buildTime,
+  };
+
+  if (format === "pretty") {
+    const noColor = process.env.NO_COLOR;
+    const c = noColor ? { reset: "", bold: "", dim: "" } : COLORS;
+    process.stdout.write(
+      `\n${c.bold}  @trucore/atf v${VERSION}${c.reset}\n` +
+        `${c.dim}  Node:${c.reset}     ${process.version}\n` +
+        `${c.dim}  Platform:${c.reset} ${process.platform}/${process.arch}\n` +
+        `${c.dim}  API:${c.reset}      ${DEFAULT_BASE_URL}\n` +
+        `${c.dim}  Commit:${c.reset}   ${commit || "dev"}\n` +
+        `${c.dim}  Built:${c.reset}    ${buildTime || "dev"}\n\n`
+    );
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+  process.exit(0);
+}
+
+// ---- src/simulate.mjs ----
+/**
+ * simulate.mjs — simulate command implementation
+ *
+ * Output: { ok:true, baseUrl, preset?, verified?:boolean, response:<simulateJson> }
+ */
+
+async function runSimulate(args) {
+  const baseUrl = args.baseUrl;
+  const verify = args.verify;
+  const format = args.format;
+  const quiet = args.quiet;
+  const apiKey = args.apiKey;
+  const timeoutMs = args.timeoutMs;
+
+  // Resolve body
+  let body;
+  let presetName = null;
+  if (args.json) {
+    const parsed = parseJsonBody(args.json);
+    if (!parsed.ok) {
+      exitWithError(
+        ERROR_CODES.USER_ERROR,
+        parsed.message,
+        "Provide valid JSON via --json '{...}'",
+        format
+      );
+    }
+    body = parsed.body;
+  } else if (args.preset) {
+    presetName = args.preset;
+    const check = validatePreset(presetName);
+    if (!check.ok) {
+      exitWithError(
+        ERROR_CODES.USER_ERROR,
+        check.message,
+        `Available presets: ${PRESET_NAMES.join(", ")}`,
+        format
+      );
+    }
+    body = PRESETS[presetName].transaction;
+    if (!quiet && format === "pretty") {
+      process.stderr.write(
+        `${COLORS.dim}Preset: ${presetName} — ${PRESETS[presetName].description}${COLORS.reset}\n`
+      );
+    }
+  } else {
+    exitWithError(
+      ERROR_CODES.USER_ERROR,
+      "Either --preset <name> or --json '<json>' is required.",
+      `Available presets: ${PRESET_NAMES.join(", ")}`,
+      format
+    );
+  }
+
+  // Make request — try SIMULATE_PATHS in order; stop on first non-404.
+  // If a 404 carries a structured ATF error envelope ({ok:false, error:{code:...}})
+  // we treat it as an authoritative app-level response and do NOT fallback.
+  let response;
+  const attemptedPaths = [];
+  try {
+    for (const path of SIMULATE_PATHS) {
+      attemptedPaths.push(path);
+      response = await postSimulate(baseUrl, body, apiKey, timeoutMs, path);
+      if (response.status !== 404) break;
+      // 404 with a structured ATF error envelope → authoritative, stop fallback
+      if (isAtfErrorEnvelope(response.data)) break;
+    }
+  } catch (err) {
+    exitWithError(
+      ERROR_CODES.NETWORK_ERROR,
+      `Network failure — ${err.message}`,
+      "Check your network connection and base URL.",
+      format
+    );
+  }
+
+  // Handle non-200
+  if (!response.ok) {
+    let errCode;
+    let msg;
+    let hint = null;
+
+    if (response.status === 401 || response.status === 403) {
+      errCode = ERROR_CODES.AUTH_ERROR;
+      const data = response.data || {};
+      msg = data.message || data.detail || `HTTP ${response.status}`;
+      hint = response.status === 401
+        ? "Check your API key or Bearer token."
+        : "Access denied. Check your permissions.";
+    } else if (response.status === 404) {
+      if (isAtfErrorEnvelope(response.data)) {
+        // Authoritative ATF 404 — surface the server's error as-is
+        errCode = response.data.error.code || ERROR_CODES.SERVER_ERROR;
+        msg = response.data.error.message || `HTTP 404`;
+        hint = (response.data.error.details && response.data.error.details.hint) || null;
+        exitWithError(errCode, msg, hint, format, {
+          status: 404,
+          attempted_paths: attemptedPaths,
+          baseUrl,
+          requestId: response.requestId,
+        });
+      }
+      // Endpoint miss — none of the paths exist on this server
+      errCode = ERROR_CODES.SERVER_ERROR;
+      msg = "SIMULATE_NOT_AVAILABLE";
+      hint = "The simulate endpoint is not available on this server.";
+      exitWithError(errCode, msg, hint, format, {
+        status: 404,
+        attempted_paths: attemptedPaths,
+        baseUrl,
+        requestId: response.requestId,
+      });
+    } else if (response.status === 422 || response.status === 400) {
+      errCode = ERROR_CODES.VALIDATION_ERROR;
+      const data = response.data || {};
+      msg = data.message || data.detail || data.error || `HTTP ${response.status}`;
+      hint = "Check the request body format and required fields.";
+    } else if (response.status === 429) {
+      errCode = ERROR_CODES.SERVER_ERROR;
+      const data = response.data || {};
+      msg = data.message || data.detail || data.error || `HTTP ${response.status}`;
+      hint = response.retryAfter
+        ? `Rate limited. Retry after ${response.retryAfter}s.`
+        : "Rate limited. Try again later.";
+    } else if (response.status >= 500) {
+      errCode = ERROR_CODES.SERVER_ERROR;
+      const data = response.data || {};
+      msg = data.message || data.detail || data.error || `HTTP ${response.status}`;
+    } else {
+      errCode = ERROR_CODES.USER_ERROR;
+      const data = response.data || {};
+      msg = data.message || data.detail || data.error || `HTTP ${response.status}`;
+    }
+    exitWithError(errCode, msg, hint, format, { status: response.status, requestId: response.requestId });
+  }
+
+  const data = response.data;
+  if (!data || typeof data !== "object") {
+    exitWithError(
+      ERROR_CODES.SERVER_ERROR,
+      "API returned non-JSON response.",
+      null,
+      format
+    );
+  }
+
+  // Extract fields — firewall-api returns decision/reasons (array);
+  // legacy servers may return status/reason (string).
+  const decision = (data.decision || data.status || "").toLowerCase();
+  const reasons = Array.isArray(data.reasons) ? data.reasons : [];
+  const reason = data.reason || data.deny_reason || data.message || "";  // legacy display
+  const receipt_hash = data.receipt_hash || data.hash || "";
+  const content_hash = data.content_hash || "";
+  const policy_hash = data.policy_hash !== undefined ? data.policy_hash : null;
+  const params = data.params || null;
+  const displayReason = reasons.length > 0 ? reasons.join(", ") : reason;
+
+  // Validate receipt_hash
+  if (receipt_hash && !isValidReceiptHash(receipt_hash)) {
+    exitWithError(
+      ERROR_CODES.VALIDATION_ERROR,
+      `API returned invalid receipt_hash: "${receipt_hash}"`,
+      "Expected: 64 lowercase hex characters.",
+      format
+    );
+  }
+
+  // Validate content_hash if present
+  if (content_hash && !isValidReceiptHash(content_hash)) {
+    exitWithError(
+      ERROR_CODES.VALIDATION_ERROR,
+      `API returned invalid content_hash: "${content_hash}"`,
+      "Expected: 64 lowercase hex characters.",
+      format
+    );
+  }
+
+  // Verification (--verify only)
+  let verified = undefined;
+  if (verify) {
+    if (content_hash) {
+      const expectedHash = computeContentHash(decision, reasons, policy_hash, params);
+      if (content_hash !== expectedHash) {
+        exitWithError(
+          ERROR_CODES.VERIFY_FAILED,
+          `content_hash does not match local computation.`,
+          `Expected: ${expectedHash.slice(0, 16)}... Got: ${content_hash.slice(0, 16)}... Open ${baseUrl}/verify?hash=${content_hash}`,
+          format
+        );
+      }
+      verified = true;
+    } else if (receipt_hash) {
+      // DEPRECATED legacy path — content_hash not returned by server.
+      if (!quiet) {
+        process.stderr.write(
+          `${COLORS.yellow}[DEPRECATED] server did not return content_hash; falling back to legacy receipt_hash verification.${COLORS.reset}\n`
+        );
+      }
+      const expectedHash = computeLegacyContentHash(decision, reason);
+      if (receipt_hash !== expectedHash) {
+        exitWithError(
+          ERROR_CODES.VERIFY_FAILED,
+          `receipt_hash does not match local computation (legacy).`,
+          `Expected: ${expectedHash.slice(0, 16)}... Got: ${receipt_hash.slice(0, 16)}... Open ${baseUrl}/verify?hash=${receipt_hash}`,
+          format
+        );
+      }
+      verified = true;
+    } else {
+      verified = false;
+    }
+  }
+
+  // Build result envelope
+  const result = { ok: true, baseUrl };
+  result.preset = presetName || null;
+  result.verified = verify ? (verified === true) : null;
+  result.response = data;
+
+  // Format output (only reached if verify passed or not requested)
+  if (format === "pretty") {
+    const isAllowed = decision === "allowed" || decision === "approved" || decision === "approve";
+    const noColor = process.env.NO_COLOR;
+    const c = noColor
+      ? { reset: "", bold: "", dim: "", green: "", red: "", yellow: "", cyan: "", gray: "" }
+      : COLORS;
+    const statusColor = isAllowed ? c.green : c.red;
+    const statusIcon = isAllowed ? "\u2713" : "\u2717";
+    const lines = [];
+    lines.push("");
+    lines.push(`${c.bold}${statusColor}  ${statusIcon} ${decision.toUpperCase()}${c.reset}`);
+    if (displayReason) lines.push(`${c.dim}  Reason:${c.reset} ${displayReason}`);
+    if (content_hash) lines.push(`${c.dim}  Content hash:${c.reset} ${content_hash}`);
+    if (receipt_hash) lines.push(`${c.dim}  Receipt:${c.reset} ${receipt_hash}`);
+    const verifyHash = content_hash || receipt_hash;
+    if (verify && verifyHash) {
+      lines.push("");
+      lines.push(`${c.cyan}${c.bold}  Trustless Verification${c.reset}`);
+      lines.push(`${c.cyan}  Verify: ${baseUrl}/verify?hash=${verifyHash}${c.reset}`);
+      lines.push(`${c.dim}  Don't trust TruCore \u2014 recompute/verify deterministically.${c.reset}`);
+    }
+    lines.push("");
+    process.stdout.write(lines.join("\n") + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+
+  // If verify + receipt signing key available, print extra info
+  if (verify && receipt_hash) {
+    try {
+      const keyInfo = await getReceiptSigningKey(baseUrl);
+      if (keyInfo && keyInfo.available === true) {
+        if (!quiet) {
+          process.stderr.write(
+            `${COLORS.dim}  Receipt signing is available. ` +
+              `Public key: ${keyInfo.public_key || "(see /api/receipt-signing-key)"}${COLORS.reset}\n`
+          );
+          process.stderr.write(
+            `${COLORS.dim}  You can verify the receipt signature via POST /api/receipt-signature${COLORS.reset}\n`
+          );
+        }
+      }
+    } catch {
+      // Non-critical — ignore
+    }
+  }
+
+  // Exit code: allowed=0, denied=1
+  if (decision === "allowed" || decision === "approve" || decision === "approved") {
+    process.exit(0);
+  } else {
+    process.exit(1);
+  }
+}
+
+// ---- src/cli.mjs ----
+/**
+ * cli.mjs — argument parsing and entry point (zero deps)
+ *
+ * VERSION, DEFAULT_BASE_URL, BUILD_COMMIT, BUILD_DATE are defined
+ * in constants.mjs (concatenated above by build.mjs).
+ */
+
+const HELP_TEXT = `
+@trucore/atf v${VERSION} — Agent Transaction Firewall CLI
+
+USAGE
+  npx @trucore/atf@${VERSION} <command> [options]
+
+COMMANDS
+  version     Show CLI version and build metadata
+  health      Check API health and latency
+  simulate    Run a transaction simulation
+  approve     Approve a pending intent
+
+GLOBAL OPTIONS
+  --base-url <url>      API base URL (default: ${DEFAULT_BASE_URL})
+  --timeout-ms <ms>     Request timeout in ms (default: 20000)
+  --format <fmt>        Output format: json | pretty (default: json)
+  --pretty              Shorthand for --format pretty
+  --no-color            Disable ANSI colors
+  --api-key <key>       API key (also: ATF_API_KEY env var)
+
+SIMULATE OPTIONS
+  --preset <name>       Use a built-in preset: ${PRESET_NAMES.join(", ")}
+  --json '<json>'       Send raw JSON transaction body
+  --verify              Verify content_hash integrity
+  --quiet               Suppress non-essential output
+
+APPROVE OPTIONS
+  --intent <id>         Intent ID to approve (required)
+  --token <bearer>      Bearer token for auth (also: ATF_API_KEY env var)
+
+ENVIRONMENT
+  ATF_API_KEY           API key (sent as x-api-key header or Bearer token)
+  ATF_BASE_URL          Override default base URL
+  ATF_TIMEOUT_MS        Override default timeout (ms)
+  NO_COLOR              Disable ANSI colors when set
+
+EXIT CODES
+  0   Success (allowed, healthy, etc.)
+  1   User error or denied
+  2   Network / server error
+
+EXAMPLES
+  npx @trucore/atf@${VERSION} version
+  npx @trucore/atf@${VERSION} health
+  npx @trucore/atf@${VERSION} simulate --preset swap_small --verify
+  npx @trucore/atf@${VERSION} approve --intent abc123 --token mytoken
+`;
+
+function parseArgs(argv) {
+  const defaultTimeout = (() => {
+    const env = process.env.ATF_TIMEOUT_MS;
+    if (env) { const n = parseInt(env, 10); if (n > 0) return n; }
+    return 20000;
+  })();
+
+  const args = {
+    command: null,
+    preset: null,
+    json: null,
+    baseUrl: process.env.ATF_BASE_URL || DEFAULT_BASE_URL,
+    verify: false,
+    format: "json",
+    quiet: false,
+    apiKey: process.env.ATF_API_KEY || null,
+    help: false,
+    showVersion: false,
+    timeoutMs: defaultTimeout,
+    noColor: !!process.env.NO_COLOR,
+    intent: null,
+    token: null,
+    verbose: false,
+    _deprecatedIntentId: false,
+  };
+
+  const raw = argv.slice(2);
+  let i = 0;
+
+  while (i < raw.length) {
+    const arg = raw[i];
+
+    if (arg === "--help" || arg === "-h") {
+      args.help = true;
+      i++;
+    } else if (arg === "--version" || arg === "-V") {
+      args.showVersion = true;
+      i++;
+    } else if (arg === "--verify") {
+      args.verify = true;
+      i++;
+    } else if (arg === "--quiet" || arg === "-q") {
+      args.quiet = true;
+      i++;
+    } else if (arg === "--pretty") {
+      args.format = "pretty";
+      i++;
+    } else if (arg === "--no-color") {
+      args.noColor = true;
+      i++;
+    } else if (arg === "--verbose") {
+      args.verbose = true;
+      i++;
+    } else if (arg === "--preset") {
+      args.preset = raw[++i] || null;
+      i++;
+    } else if (arg === "--json") {
+      args.json = raw[++i] || null;
+      i++;
+    } else if (arg === "--base-url") {
+      args.baseUrl = raw[++i] || args.baseUrl;
+      i++;
+    } else if (arg === "--format") {
+      args.format = raw[++i] || args.format;
+      i++;
+    } else if (arg === "--api-key") {
+      args.apiKey = raw[++i] || args.apiKey;
+      i++;
+    } else if (arg === "--timeout-ms") {
+      args.timeoutMs = parseInt(raw[++i], 10) || defaultTimeout;
+      i++;
+    } else if (arg === "--intent" || arg === "--intent-id") {
+      if (arg === "--intent-id") args._deprecatedIntentId = true;
+      args.intent = raw[++i] || null;
+      i++;
+    } else if (arg === "--token") {
+      args.token = raw[++i] || null;
+      i++;
+    } else if (!arg.startsWith("-") && !args.command) {
+      args.command = arg;
+      i++;
+    } else {
+      // Unknown argument — structured JSON error, exit 1
+      const err = makeError("USER_ERROR", `Unknown argument: ${arg}`, { hint: "Run with --help for usage." });
+      process.stdout.write(JSON.stringify(err, null, 2) + "\n");
+      process.exit(1);
+    }
+  }
+
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.showVersion) {
+    process.stdout.write(`${VERSION}\n`);
+    process.exit(0);
+  }
+
+  if (args.help || !args.command) {
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+  }
+
+  switch (args.command) {
+    case "version":
+      await runVersion(args);
+      break;
+    case "health":
+      await runHealth(args);
+      break;
+    case "simulate":
+      await runSimulate(args);
+      break;
+    case "approve":
+      await runApprove(args);
+      break;
+    default:
+      exitWithError(ERROR_CODES.USER_ERROR, `Unknown command: ${args.command}`, "Run with --help for usage.", args.format);
+  }
+
+  // Ensure clean exit — fetch() can leave open handles that prevent
+  // the event loop from draining naturally.
+  process.exit(0);
+}
+
+main().catch((err) => {
+  const msg = err && err.message ? err.message : String(err);
+  const safeMsg = typeof redactToken === "function" ? redactToken(msg) : msg;
+  process.stderr.write(`Fatal: ${safeMsg}\n`);
+  process.exit(2);
+});
+

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@trucore/atf",
+  "version": "1.0.0",
+  "description": "Agent Transaction Firewall CLI — simulate, verify, and audit on-chain transactions trustlessly.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trucore-ai/agent-transaction-firewall.git",
+    "directory": "packages/atf-cli"
+  },
+  "homepage": "https://github.com/trucore-ai/agent-transaction-firewall/tree/main/packages/atf-cli#readme",
+  "bugs": {
+    "url": "https://github.com/trucore-ai/agent-transaction-firewall/issues"
+  },
+  "author": "TruCore AI",
+  "funding": "https://trucore.xyz",
+  "keywords": [
+    "blockchain",
+    "firewall",
+    "transaction",
+    "defi",
+    "security",
+    "simulation",
+    "trustless"
+  ],
+  "bin": {
+    "atf": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test tests/",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "devDependencies": {}
+}