@aarmos/cli 0.1.2 → 0.2.0

package/README.md

@@ -18,7 +18,7 @@ aarmos run ./my-agent.js
 | `aarmos run <agent>` | Run agent under policy — writes AVAR receipt on every execution |
 | `aarmos proxy` | Transparent local HTTP proxy on 127.0.0.1 (any framework enrolls via `HTTPS_PROXY`) |
 | `aarmos daemon start|stop|status` | Manage background proxy daemon |
-| `aarmos verify <receipt>` | Discovery wrapper — install standalone `avar` for full verification |
+| `aarmos verify <receipt>` | Verify an AVAR receipt locally (signatures + hash chain, via `@aarmos/avar-core`). Works with the daemon stopped. Zero network. |
 
 ## Guarantees
 

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command6 } from "commander";
+import { Command as Command9 } from "commander";
 
 // src/commands/init.ts
 import { Command } from "commander";
@@ -299,34 +299,936 @@ function isRunning() {
 // src/commands/verify.ts
 import { Command as Command5 } from "commander";
 import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
-function verifyCommand() {
-  return new Command5("verify").description(
-    "Thin wrapper on the standalone `avar` binary for discovery. Install `avar` for the full verifier \u2014 it works with the Aarmos daemon stopped."
-  ).argument("<receipt>", "Path to AVAR receipt").action(async (receipt) => {
-    if (!existsSync5(receipt)) {
-      console.error(`\u2717 receipt not found: ${receipt}`);
-      process.exit(2);
+import { unzipSync, strFromU8 } from "fflate";
+
+// ../avar-core/src/canonicalize.ts
+var NFC = (s) => s.normalize("NFC");
+function encodeString(s) {
+  return JSON.stringify(NFC(s));
+}
+function encodeNumber(n) {
+  if (!Number.isFinite(n)) {
+    throw new Error(`avar-core/canonicalize: non-finite number (${n}) is forbidden.`);
+  }
+  return JSON.stringify(n);
+}
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return encodeNumber(value);
+  if (typeof value === "string") return encodeString(value);
+  if (typeof value === "undefined") {
+    throw new Error("avar-core/canonicalize: undefined is forbidden at value position.");
+  }
+  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new Error(`avar-core/canonicalize: ${typeof value} is forbidden.`);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => canonicalize(v)).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = [];
+    for (const k of Object.keys(obj)) {
+      if (obj[k] === void 0) continue;
+      keys.push(NFC(k));
+    }
+    keys.sort();
+    const parts = new Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      const rawVal = obj[k] ?? findKey(obj, k);
+      parts[i] = encodeString(k) + ":" + canonicalize(rawVal);
+    }
+    return "{" + parts.join(",") + "}";
+  }
+  throw new Error(`avar-core/canonicalize: unsupported type ${typeof value}.`);
+}
+function findKey(obj, nfcKey) {
+  for (const k of Object.keys(obj)) {
+    if (NFC(k) === nfcKey) return obj[k];
+  }
+  return void 0;
+}
+function utf8(s) {
+  return new TextEncoder().encode(s);
+}
+
+// ../avar-core/src/hash.ts
+var GENESIS_PREV_HASH = "0000000000000000000000000000000000000000000000000000000000000000";
+function getSubtle() {
+  const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
+  if (!c || !c.subtle) {
+    throw new Error(
+      "avar-core: WebCrypto SubtleCrypto is unavailable. Requires Node 20+ or a modern browser."
+    );
+  }
+  return c.subtle;
+}
+async function sha256Hex(input) {
+  const bytes = typeof input === "string" ? utf8(input) : input;
+  const digest = await getSubtle().digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function computeEntryHash(entry, prevHash) {
+  const withPrev = { ...entry, prevHash };
+  const {
+    entryHash: _e,
+    signature: _sig,
+    devicePubKey: _pk,
+    ...rest
+  } = withPrev;
+  void _e;
+  void _sig;
+  void _pk;
+  return sha256Hex(prevHash + "\n" + canonicalize(rest));
+}
+async function computeStepHash(step, prevStepHash) {
+  const asRec = step;
+  const { stepHash: _s, prevStepHash: _p, ...rest } = asRec;
+  void _s;
+  void _p;
+  const withPrev = { ...rest, prevStepHash };
+  return sha256Hex(prevStepHash + "\n" + canonicalize(withPrev));
+}
+
+// ../avar-core/src/signature.ts
+function getSubtle2() {
+  const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
+  if (!c || !c.subtle) {
+    throw new Error("avar-core: WebCrypto SubtleCrypto is unavailable.");
+  }
+  return c.subtle;
+}
+function b64uDecode(s) {
+  const b642 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
+  const bin = typeof atob === "function" ? atob(b642) : globalThis.Buffer.from(b642, "base64").toString("binary");
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+async function verifySignature(signedBody, signatureB64u, publicKeyB64u) {
+  try {
+    const raw = b64uDecode(publicKeyB64u);
+    const key = await getSubtle2().importKey("raw", raw, "Ed25519", false, [
+      "verify"
+    ]);
+    const sig = b64uDecode(signatureB64u);
+    const bytes = utf8(canonicalize(signedBody));
+    return await getSubtle2().verify(
+      "Ed25519",
+      key,
+      sig,
+      bytes
+    );
+  } catch {
+    return false;
+  }
+}
+async function computeDeviceFingerprint(publicKeyB64u) {
+  const hex = await sha256Hex(utf8(publicKeyB64u));
+  return hex.slice(0, 12);
+}
+function signedBodyOf(entry) {
+  const { signature: _sig, devicePubKey: _pk, ...rest } = entry;
+  void _sig;
+  void _pk;
+  return rest;
+}
+
+// ../avar-core/src/verify.ts
+var SPEC_VERSION = "avar/1";
+async function verifyBundle(bundle) {
+  const issues = [];
+  let formatOk = true;
+  const specV = bundle.specVersion.trim();
+  if (specV !== SPEC_VERSION) {
+    formatOk = false;
+    issues.push({
+      index: -1,
+      kind: "spec-version-mismatch",
+      detail: `Expected "${SPEC_VERSION}", got "${specV}".`
+    });
+  }
+  if (bundle.manifest.format !== SPEC_VERSION) {
+    formatOk = false;
+    issues.push({
+      index: -1,
+      kind: "manifest-invalid",
+      detail: `manifest.format expected "${SPEC_VERSION}", got "${bundle.manifest.format}".`
+    });
+  }
+  const actualSha = await sha256Hex(bundle.entriesNdjsonBytes);
+  const entriesSha256Ok = actualSha === bundle.manifest.entriesSha256;
+  if (!entriesSha256Ok) {
+    issues.push({
+      index: -1,
+      kind: "entries-sha256-mismatch",
+      detail: `Expected ${bundle.manifest.entriesSha256}, got ${actualSha}.`
+    });
+  }
+  const entries = bundle.entries;
+  const entryCount = entries.length;
+  let signaturesOk = true;
+  let fingerprintsOk = true;
+  let signedCount = 0;
+  let unsignedCount = 0;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const hasSig = typeof e.signature === "string" && typeof e.devicePubKey === "string";
+    if (!hasSig) {
+      unsignedCount++;
+      continue;
+    }
+    signedCount++;
+    if (typeof e.deviceFingerprint === "string") {
+      const expected = await computeDeviceFingerprint(e.devicePubKey);
+      if (expected !== e.deviceFingerprint) {
+        fingerprintsOk = false;
+        issues.push({
+          index: i,
+          kind: "fingerprint-mismatch",
+          detail: `Expected ${expected}, got ${e.deviceFingerprint}.`
+        });
+      }
+    }
+    const ok = await verifySignature(signedBodyOf(e), e.signature, e.devicePubKey);
+    if (!ok) {
+      signaturesOk = false;
+      issues.push({ index: i, kind: "signature-invalid" });
+    }
+  }
+  let chainOk = true;
+  let unchainedCount = 0;
+  let expectedPrev = GENESIS_PREV_HASH;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    const isLegacyUnchained = !e.entryHash || !e.prevHash;
+    if (isLegacyUnchained) {
+      unchainedCount++;
+      expectedPrev = GENESIS_PREV_HASH;
+      continue;
+    }
+    if (e.prevHash !== expectedPrev) {
+      chainOk = false;
+      issues.push({
+        index: i,
+        kind: "chain-broken",
+        detail: `prevHash mismatch at entry ${i}.`
+      });
+    }
+    const recomputed = await computeEntryHash(e, e.prevHash);
+    if (recomputed !== e.entryHash) {
+      chainOk = false;
+      issues.push({
+        index: i,
+        kind: "chain-broken",
+        detail: `entryHash mismatch at entry ${i} (body modified after signing).`
+      });
+    }
+    expectedPrev = e.entryHash;
+  }
+  const perStepChainOk = await verifyAllStepChains(entries, issues);
+  const chainHead = computeChainHead(entries);
+  const anyHardFail = !formatOk || !entriesSha256Ok || !chainOk || !perStepChainOk || !signaturesOk || !fingerprintsOk;
+  const verdict = anyHardFail ? "invalid" : unsignedCount > 0 || unchainedCount > 0 ? "valid-with-warnings" : "valid";
+  return {
+    formatOk,
+    entriesSha256Ok,
+    chainOk,
+    perStepChainOk,
+    signaturesOk,
+    fingerprintsOk,
+    entryCount,
+    signedCount,
+    unsignedCount,
+    unchainedCount,
+    chainHead,
+    issues,
+    verdict
+  };
+}
+async function verifyAllStepChains(entries, issues) {
+  let ok = true;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (!Array.isArray(e.steps) || e.steps.length === 0) continue;
+    const anyChained = e.steps.some(hasChainFields);
+    const allChained = e.steps.every(hasChainFields);
+    if (anyChained && !allChained) {
+      ok = false;
+      issues.push({ index: i, kind: "partial-step-chain" });
+      continue;
+    }
+    if (!anyChained) continue;
+    let prev = "step-genesis:0000000000000000000000000000000000000000000000000000000000000000";
+    for (let j = 0; j < e.steps.length; j++) {
+      const s = e.steps[j];
+      if (s.prevStepHash !== prev) {
+        ok = false;
+        issues.push({
+          index: i,
+          kind: "step-chain-broken",
+          detail: `entry ${i} step ${j}: prevStepHash mismatch.`
+        });
+      }
+      const recomputed = await computeStepHash(s, s.prevStepHash);
+      if (recomputed !== s.stepHash) {
+        ok = false;
+        issues.push({
+          index: i,
+          kind: "step-chain-broken",
+          detail: `entry ${i} step ${j}: stepHash mismatch (step body modified).`
+        });
+      }
+      prev = s.stepHash;
+    }
+  }
+  return ok;
+}
+function hasChainFields(s) {
+  return typeof s.prevStepHash === "string" && typeof s.stepHash === "string";
+}
+function computeChainHead(entries) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e.entryHash) return { entryHash: e.entryHash, index: i };
+  }
+  return { entryHash: "", index: -1 };
+}
+
+// ../avar-core/src/errors.ts
+var SPEC_URL = "https://aarmos.io/docs/avar-spec";
+var VERIFY_URL = "https://aarmos.io/trust/verify";
+var QUICKSTART_URL = "https://aarmos.io/docs/quickstart";
+var AARMOS_ERROR_TEMPLATES = {
+  BUNDLE_OVERSIZED: {
+    message: "That bundle is larger than the 25 MB browser limit.",
+    hint: "Run `aarmos verify <bundle>` locally instead \u2014 the CLI has no size cap.",
+    docsUrl: QUICKSTART_URL
+  },
+  BUNDLE_NOT_ZIP: {
+    message: "That file is not a valid .avar.zip.",
+    hint: "Bundles are zip archives. Rename or re-export the file, then try again.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_MISSING_FILES: {
+    message: "Bundle is missing one or more required files.",
+    hint: "A valid AVAR bundle contains SPEC-VERSION, manifest.json, entries.ndjson, and pubkeys.json.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_INVALID_JSON: {
+    message: "manifest.json or pubkeys.json is not valid JSON.",
+    hint: "The file exists but cannot be parsed. Re-export from the CLI to regenerate a clean bundle.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_INVALID_NDJSON: {
+    message: "entries.ndjson contains a malformed line.",
+    hint: "Each line must be a self-contained JSON entry. One corrupt line usually means the file was edited by hand.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_SPEC_UNSUPPORTED: {
+    message: "This bundle was produced by a spec version this verifier does not support.",
+    hint: "Update to the latest verifier (`npm i -g @aarmos/avar-core`) or re-export with a matching spec version.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_EMPTY: {
+    message: "Bundle contains no entries.",
+    hint: "An empty ledger is unusual \u2014 check that the run actually produced receipts before exporting.",
+    docsUrl: SPEC_URL
+  },
+  SPEC_VERSION_MISMATCH: {
+    message: "This bundle uses a spec version this verifier does not recognize.",
+    hint: "Update the verifier (`npm i -g @aarmos/avar-core`) or re-export the bundle with matching spec version.",
+    docsUrl: SPEC_URL
+  },
+  ENTRIES_SHA256_MISMATCH: {
+    message: "entries.ndjson has been modified since the bundle was signed.",
+    hint: "The envelope hash in manifest.json no longer matches the file. Do not trust this bundle \u2014 re-export from the CLI.",
+    docsUrl: VERIFY_URL
+  },
+  SIGNATURE_MISMATCH: {
+    message: "One or more entry signatures do not match the embedded public keys.",
+    hint: "The bundle was modified after signing, or the wrong pubkeys.json is bundled.",
+    docsUrl: VERIFY_URL
+  },
+  FINGERPRINT_MISMATCH: {
+    message: "Device fingerprint on one or more entries does not match its public key.",
+    hint: "The entry claims a device whose public key does not hash to the declared fingerprint. Treat this bundle as untrusted.",
+    docsUrl: VERIFY_URL
+  },
+  CHAIN_BROKEN: {
+    message: "The per-entry hash chain is broken.",
+    hint: "An entry was inserted, removed, or edited after signing. The break index is shown in the issues list.",
+    docsUrl: VERIFY_URL
+  },
+  STEP_CHAIN_BROKEN: {
+    message: "The per-step hash chain inside one or more entries is broken.",
+    hint: "A decision or tool step was tampered with. The affected entry index is in the issues list.",
+    docsUrl: VERIFY_URL
+  },
+  MANIFEST_INVALID: {
+    message: "manifest.json is missing required fields or uses an unsupported format.",
+    hint: "Re-export the bundle from the CLI \u2014 do not edit manifest.json by hand.",
+    docsUrl: SPEC_URL
+  },
+  FILE_NOT_FOUND: {
+    message: "Receipt not found at the given path.",
+    hint: "Check the path \u2014 a common cause is running from a different working directory than expected.",
+    docsUrl: QUICKSTART_URL
+  },
+  FILE_UNREADABLE: {
+    message: "Receipt exists but could not be read.",
+    hint: "Check filesystem permissions on the file.",
+    docsUrl: QUICKSTART_URL
+  },
+  UNKNOWN: {
+    message: "Something went wrong while verifying that bundle.",
+    hint: "Try again with a fresh export. If the error persists, run `aarmos verify` locally to see the raw error.",
+    docsUrl: QUICKSTART_URL
+  }
+};
+function aarmosError(code, overrides = {}) {
+  const base = AARMOS_ERROR_TEMPLATES[code];
+  return {
+    code,
+    message: overrides.message ?? base.message,
+    hint: overrides.hint ?? base.hint,
+    docsUrl: overrides.docsUrl ?? base.docsUrl
+  };
+}
+function formatAarmosErrorLine(err) {
+  return `\u2717 ${err.code}: ${err.message}
+  Next: ${err.hint}
+  Docs: ${err.docsUrl}`;
+}
+function classifyReport(report) {
+  if (report.verdict !== "invalid") return null;
+  if (!report.entriesSha256Ok) return aarmosError("ENTRIES_SHA256_MISMATCH");
+  if (!report.signaturesOk) return aarmosError("SIGNATURE_MISMATCH");
+  if (!report.fingerprintsOk) return aarmosError("FINGERPRINT_MISMATCH");
+  if (!report.chainOk) return aarmosError("CHAIN_BROKEN");
+  if (!report.perStepChainOk) return aarmosError("STEP_CHAIN_BROKEN");
+  if (!report.formatOk) {
+    const specIssue = report.issues.find((i) => i.kind === "spec-version-mismatch");
+    if (specIssue) {
+      return aarmosError("SPEC_VERSION_MISMATCH", {
+        message: specIssue.detail ? `Spec mismatch \u2014 ${specIssue.detail}` : void 0
+      });
+    }
+    return aarmosError("MANIFEST_INVALID");
+  }
+  return aarmosError("UNKNOWN");
+}
+
+// src/commands/verify.ts
+async function runVerify(opts) {
+  const { file, json = false, quiet = false } = opts;
+  const emitError = (err, rc) => {
+    if (json) {
+      process.stdout.write(JSON.stringify({ verdict: "invalid", error: err }) + "\n");
+    } else if (!quiet) {
+      process.stderr.write(formatAarmosErrorLine(err) + "\n");
     }
-    const raw = readFileSync4(receipt, "utf8");
+    return rc;
+  };
+  if (!existsSync5(file)) {
+    return emitError(aarmosError("FILE_NOT_FOUND", { message: `Receipt not found: ${file}` }), 2);
+  }
+  let bytes;
+  try {
+    bytes = readFileSync4(file);
+  } catch (err) {
+    return emitError(
+      aarmosError("FILE_UNREADABLE", {
+        message: err instanceof Error ? err.message : String(err)
+      }),
+      1
+    );
+  }
+  const isZip = looksLikeZip(bytes);
+  if (!isZip) {
     try {
-      const parsed = JSON.parse(raw);
+      const parsed = JSON.parse(bytes.toString("utf8"));
       const entries = Array.isArray(parsed.entries) ? parsed.entries.length : 0;
-      console.log(`\u2713 receipt parsed (${entries} entr${entries === 1 ? "y" : "ies"})`);
-      console.log(`  spec_version: ${parsed.spec_version ?? "unknown"}`);
-      console.log(`  signature_alg: ${parsed.signature_alg ?? "unknown"}`);
-      console.log(
-        "\nFor full signature + hash-chain verification, install the standalone `avar` binary:"
+      if (json) {
+        process.stdout.write(
+          JSON.stringify({
+            verdict: "parsed-only",
+            format: "json",
+            entryCount: entries,
+            note: "JSON receipt parsed; full verification requires an .avar.zip bundle."
+          }) + "\n"
+        );
+      } else if (!quiet) {
+        process.stdout.write(`\u2713 receipt parsed (${entries} entr${entries === 1 ? "y" : "ies"})
+`);
+        process.stdout.write(`  spec_version: ${parsed.spec_version ?? "unknown"}
+`);
+        process.stdout.write(`  signature_alg: ${parsed.signature_alg ?? "unknown"}
+`);
+        process.stdout.write(
+          "\nNote: JSON receipts are parse-only. For full signature + hash-chain\nverification, export an .avar.zip bundle.\n"
+        );
+      }
+      return 0;
+    } catch (err) {
+      return emitError(
+        aarmosError("BUNDLE_INVALID_JSON", {
+          message: `invalid JSON receipt: ${err instanceof Error ? err.message : String(err)}`
+        }),
+        1
       );
-      console.log("  https://www.aarmos.io/docs/avar-spec");
+    }
+  }
+  let bundle;
+  try {
+    bundle = parseBundleBytes(bytes);
+  } catch (err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    let classified2;
+    if (/missing /i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_MISSING_FILES", { message: raw });
+    } else if (/invalid zip|central directory|not a zip/i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_NOT_ZIP", { message: raw });
+    } else if (/ndjson|entries\.ndjson/i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_INVALID_NDJSON", { message: raw });
+    } else if (/JSON|Unexpected token/i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_INVALID_JSON", { message: raw });
+    } else {
+      classified2 = aarmosError("UNKNOWN", { message: `malformed .avar.zip: ${raw}` });
+    }
+    return emitError(classified2, 1);
+  }
+  const report = await verifyBundle(bundle);
+  const failed = report.verdict === "invalid";
+  const classified = classifyReport(report);
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(classified ? { ...report, error: classified } : report) + "\n"
+    );
+  } else if (!quiet) {
+    const mark = failed ? "\u2717" : "\u2713";
+    process.stdout.write(`${mark} verdict: ${report.verdict}
+`);
+    process.stdout.write(`  entries:   ${report.entryCount}
+`);
+    process.stdout.write(`  signed:    ${report.signedCount}
+`);
+    process.stdout.write(`  unsigned:  ${report.unsignedCount}
+`);
+    process.stdout.write(`  unchained: ${report.unchainedCount}
+`);
+    if (report.issues.length) {
+      process.stdout.write(`  issues:
+`);
+      for (const issue of report.issues) {
+        process.stdout.write(`    - [${issue.kind}] ${issue.detail ?? ""}
+`);
+      }
+    }
+    if (classified) {
+      process.stderr.write("\n" + formatAarmosErrorLine(classified) + "\n");
+    } else {
+      process.stdout.write("\nverified locally \u2014 no Aarmos service was contacted.\n");
+    }
+  }
+  return failed ? 1 : 0;
+}
+function looksLikeZip(bytes) {
+  return bytes.length >= 4 && bytes[0] === 80 && bytes[1] === 75 && bytes[2] === 3 && bytes[3] === 4;
+}
+function parseBundleBytes(bytes) {
+  const files = unzipSync(bytes);
+  const requireFile = (name) => {
+    const f = files[name];
+    if (!f) throw new Error(`missing ${name} in bundle`);
+    return f;
+  };
+  const specVersion = strFromU8(requireFile("SPEC-VERSION")).trim();
+  const manifest = JSON.parse(strFromU8(requireFile("manifest.json")));
+  const pubkeys = JSON.parse(strFromU8(requireFile("pubkeys.json")));
+  const entriesNdjsonBytes = requireFile("entries.ndjson");
+  const entries = strFromU8(entriesNdjsonBytes).split("\n").filter((l) => l.length > 0).map((l) => JSON.parse(l));
+  return { specVersion, manifest, entriesNdjsonBytes, entries, pubkeys };
+}
+function verifyCommand() {
+  return new Command5("verify").description(
+    "Verify an AVAR receipt (.avar.zip bundle or legacy .json) locally \u2014 signatures + hash chain via @aarmos/avar-core. Works with the Aarmos daemon stopped. Zero network."
+  ).argument("<receipt>", "Path to AVAR receipt (.avar.zip or .json)").option("--json", "Emit machine-readable JSON report on stdout").option("--quiet", "Suppress non-error output; exit code carries the verdict").action(async (receipt, opts) => {
+    const rc = await runVerify({ file: receipt, json: opts.json, quiet: opts.quiet });
+    process.exit(rc);
+  });
+}
+
+// src/commands/lint.ts
+import { Command as Command6 } from "commander";
+import { existsSync as existsSync6, readFileSync as readFileSync5, statSync, readdirSync } from "fs";
+import { join as join4, extname } from "path";
+
+// src/lib/asp-compile.ts
+import { parse as parseYaml } from "yaml";
+import { createHash as createHash3, createPrivateKey, sign as edSign, generateKeyPairSync as generateKeyPairSync2 } from "crypto";
+function canonicalize2(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(canonicalize2).join(",") + "]";
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize2(obj[k])).join(",") + "}";
+}
+function parseAspYaml(source) {
+  const doc = parseYaml(source);
+  if (!doc || typeof doc !== "object") throw new Error("ASP YAML must be a mapping");
+  return doc;
+}
+function compileAsp(doc) {
+  const errors = [];
+  const v = doc.version ?? 1;
+  if (v !== 1) errors.push(`version must be 1 (got ${v})`);
+  const name = doc.metadata?.issuer?.name;
+  const pubKey = doc.metadata?.issuer?.pubKey;
+  if (!name) errors.push("metadata.issuer.name is required");
+  if (!pubKey) errors.push("metadata.issuer.pubKey is required (base64 raw 32B ed25519)");
+  const issuedAt = doc.metadata?.issuedAt;
+  const expiresAt = doc.metadata?.expiresAt;
+  if (!issuedAt) errors.push("metadata.issuedAt is required (ISO 8601)");
+  if (!expiresAt) errors.push("metadata.expiresAt is required (ISO 8601)");
+  if (issuedAt && Number.isNaN(Date.parse(issuedAt)))
+    errors.push(`metadata.issuedAt is not a valid ISO date: ${issuedAt}`);
+  if (expiresAt && Number.isNaN(Date.parse(expiresAt)))
+    errors.push(`metadata.expiresAt is not a valid ISO date: ${expiresAt}`);
+  if (issuedAt && expiresAt && Date.parse(expiresAt) <= Date.parse(issuedAt))
+    errors.push("metadata.expiresAt must be after metadata.issuedAt");
+  if (errors.length) return { ok: false, errors };
+  const policy = {};
+  if (doc.allow?.servers?.length) policy.allowedServers = [...doc.allow.servers];
+  if (doc.allow?.tools?.length) policy.allowedTools = [...doc.allow.tools];
+  if (doc.deny?.tools?.length) policy.deniedTools = [...doc.deny.tools];
+  if (doc.scopes && Object.keys(doc.scopes).length) policy.allowedScopes = { ...doc.scopes };
+  if (typeof doc.kill_switch?.default === "boolean")
+    policy.killSwitchDefault = doc.kill_switch.default;
+  if (doc.redaction?.length) policy.redactionRules = doc.redaction.map((r) => ({ ...r }));
+  if (doc.autonomous_scopes?.length)
+    policy.autonomousScopes = doc.autonomous_scopes.map((s) => ({
+      agentId: s.agent_id,
+      tools: [...s.tools],
+      maxUsdPerDay: s.max_usd_per_day,
+      maxStepsPerRun: s.max_steps_per_run,
+      expiresAt: s.expires_at
+    }));
+  const body = {
+    version: 1,
+    issuer: { name, pubKey },
+    issuedAt,
+    expiresAt,
+    policy
+  };
+  return { ok: true, body, canonical: canonicalize2(body) };
+}
+function compileAspYamlToCanonicalJson(source) {
+  let doc;
+  try {
+    doc = parseAspYaml(source);
+  } catch (err) {
+    return { ok: false, errors: [`YAML parse error: ${err.message}`] };
+  }
+  return compileAsp(doc);
+}
+var fromB64u = (s) => {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - s.length % 4);
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64");
+};
+var b64 = (buf) => Buffer.from(buf).toString("base64");
+function privateKeyFromSeedB64u(seedB64u) {
+  const seed = fromB64u(seedB64u);
+  if (seed.length !== 32) throw new Error("Seed must be 32 bytes (base64url)");
+  const pkcs8 = Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), seed]);
+  return createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" });
+}
+function signBody(body, seedB64u) {
+  const priv = privateKeyFromSeedB64u(seedB64u);
+  const canon = canonicalize2(body);
+  const sig = edSign(null, Buffer.from(canon), priv);
+  return { ...body, sig: b64(sig) };
+}
+function keygen() {
+  const { publicKey, privateKey } = generateKeyPairSync2("ed25519");
+  const pubJwk = publicKey.export({ format: "jwk" });
+  const privJwk = privateKey.export({ format: "jwk" });
+  return { pubKeyB64: b64(fromB64u(pubJwk.x)), seedB64u: privJwk.d };
+}
+
+// src/commands/lint.ts
+function collectFiles(target) {
+  if (!existsSync6(target)) return [];
+  const st = statSync(target);
+  if (st.isFile()) return [target];
+  const out = [];
+  for (const name of readdirSync(target)) {
+    const full = join4(target, name);
+    const s = statSync(full);
+    if (s.isDirectory()) {
+      if (name === "tests" || name === "node_modules" || name.startsWith(".")) continue;
+      out.push(...collectFiles(full));
+    } else if (extname(name) === ".yaml" || extname(name) === ".yml") {
+      if (name.endsWith(".asp.yaml") || name === "asp.yaml" || name === "asp.yml") {
+        out.push(full);
+      }
+    }
+  }
+  return out;
+}
+function lintPath(target) {
+  const files = collectFiles(target);
+  const issues = [];
+  if (files.length === 0) {
+    issues.push({ severity: "error", file: target, message: "no ASP files found (asp.yaml or *.asp.yaml)" });
+    return issues;
+  }
+  for (const file of files) {
+    const src = readFileSync5(file, "utf8");
+    const result = compileAspYamlToCanonicalJson(src);
+    if (!result.ok) {
+      for (const m of result.errors) issues.push({ severity: "error", file, message: m });
+      continue;
+    }
+    const body = result.body;
+    const dangerous = /(delete|drop|admin|payment|transfer)/i;
+    const allow = body.policy.allowedTools ?? [];
+    const hasDangerous = allow.some((t) => dangerous.test(t));
+    if (hasDangerous) {
+      issues.push({
+        severity: "warning",
+        file,
+        message: "allow.tools includes admin/delete-capable patterns \u2014 declare human_oversight.require_approval_for or move to deny."
+      });
+    }
+    const deny = body.policy.deniedTools ?? [];
+    for (const d of deny) {
+      if (allow.includes(d)) {
+        issues.push({ severity: "warning", file, message: `rule "${d}" is in both allow.tools and deny.tools (deny wins; remove from allow).` });
+      }
+    }
+    const soon = Date.parse(body.expiresAt) - Date.now() < 7 * 24 * 3600 * 1e3;
+    if (soon) {
+      issues.push({ severity: "warning", file, message: `metadata.expiresAt is within 7 days (${body.expiresAt}).` });
+    }
+  }
+  return issues;
+}
+function lintCommand() {
+  return new Command6("lint").description("Validate ASP YAML policy files. Zero network.").argument("[path]", "File or directory to lint", ".").option("--strict", "Treat warnings as errors").option("--json", "Emit JSON report").action((path, opts) => {
+    const issues = lintPath(path);
+    const errors = issues.filter((i) => i.severity === "error");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ errors, warnings }, null, 2) + "\n");
+    } else {
+      for (const i of issues) {
+        const mark = i.severity === "error" ? "\u2717" : "\u26A0";
+        process.stdout.write(`${mark} [${i.severity}] ${i.file}: ${i.message}
+`);
+      }
+      if (errors.length === 0 && warnings.length === 0) {
+        process.stdout.write("\u2713 ASP clean.\n");
+      }
+    }
+    if (errors.length > 0) process.exit(1);
+    if (opts.strict && warnings.length > 0) process.exit(2);
+    process.exit(0);
+  });
+}
+
+// src/commands/test.ts
+import { Command as Command7 } from "commander";
+import { existsSync as existsSync7, readFileSync as readFileSync6, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join5, extname as extname2, dirname } from "path";
+import { parse as parseYaml2 } from "yaml";
+
+// src/lib/asp-eval.ts
+function globMatch(pattern, value) {
+  const re = new RegExp(
+    "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
+  );
+  return re.test(value);
+}
+function evaluate(body, call) {
+  const p = body.policy;
+  if (p.deniedTools?.some((g) => globMatch(g, call.tool))) {
+    return { decision: "deny", reason: `matched deny.tools glob for "${call.tool}"` };
+  }
+  if (call.server && p.allowedServers && p.allowedServers.length > 0) {
+    const serverOk = p.allowedServers.some((s) => s === call.server || globMatch(s, call.server));
+    if (!serverOk) return { decision: "deny", reason: `server "${call.server}" not in allow.servers` };
+  }
+  if (p.allowedTools && p.allowedTools.length > 0) {
+    const toolOk = p.allowedTools.some((g) => globMatch(g, call.tool));
+    if (!toolOk) return { decision: "deny", reason: `tool "${call.tool}" not in allow.tools` };
+  }
+  if (call.scopes && p.allowedScopes) {
+    for (const [svc, requested] of Object.entries(call.scopes)) {
+      const allowed = p.allowedScopes[svc] ?? [];
+      for (const scope of requested) {
+        if (!allowed.includes(scope)) {
+          return { decision: "deny", reason: `scope "${scope}" not allowed for service "${svc}"` };
+        }
+      }
+    }
+  }
+  return { decision: "allow", reason: "matched allow rules" };
+}
+
+// src/commands/test.ts
+function findAspYaml(startDir) {
+  let d = startDir;
+  for (let i = 0; i < 6; i++) {
+    for (const cand of ["asp.yaml", "asp.yml"]) {
+      const p = join5(d, cand);
+      if (existsSync7(p)) return p;
+    }
+    const parent = dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  return null;
+}
+function collectFixtures(target) {
+  if (!existsSync7(target)) return [];
+  const st = statSync2(target);
+  if (st.isFile()) return [target];
+  const out = [];
+  for (const name of readdirSync2(target)) {
+    const full = join5(target, name);
+    const s = statSync2(full);
+    if (s.isDirectory()) out.push(...collectFixtures(full));
+    else if ((extname2(name) === ".yaml" || extname2(name) === ".yml") && !name.endsWith(".asp.yaml"))
+      out.push(full);
+  }
+  return out;
+}
+function runFixtures(target) {
+  const dir = existsSync7(target) && statSync2(target).isDirectory() ? target : "policies/tests";
+  const fixtures = collectFixtures(existsSync7(dir) ? dir : target);
+  const results = [];
+  for (const file of fixtures) {
+    let fx;
+    try {
+      fx = parseYaml2(readFileSync6(file, "utf8"));
     } catch (err) {
-      console.error(`\u2717 invalid JSON: ${String(err)}`);
+      results.push({ file, name: "<parse>", ok: false, reason: err.message });
+      continue;
+    }
+    const policyPath = fx.policy ? join5(dirname(file), fx.policy) : findAspYaml(dirname(file));
+    if (!policyPath || !existsSync7(policyPath)) {
+      results.push({ file, name: "<policy>", ok: false, reason: "no asp.yaml found" });
+      continue;
+    }
+    const compiled = compileAspYamlToCanonicalJson(readFileSync6(policyPath, "utf8"));
+    if (!compiled.ok) {
+      results.push({ file, name: "<compile>", ok: false, reason: compiled.errors.join("; ") });
+      continue;
+    }
+    for (const c of fx.cases ?? []) {
+      const r = evaluate(compiled.body, c.call);
+      const ok = r.decision === c.expect;
+      results.push({
+        file,
+        name: c.name,
+        ok,
+        reason: ok ? r.reason : `expected ${c.expect}, got ${r.decision} (${r.reason})`
+      });
+    }
+  }
+  return results;
+}
+function testCommand() {
+  return new Command7("test").description("Run ASP policy golden tests against fixtures. Deterministic, zero network.").argument("[path]", "Fixtures dir", "policies/tests").option("--json", "Emit JSON report").action((path, opts) => {
+    const results = runFixtures(path);
+    const failed = results.filter((r) => !r.ok);
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ results }, null, 2) + "\n");
+    } else {
+      for (const r of results) {
+        process.stdout.write(`${r.ok ? "\u2713" : "\u2717"} ${r.file} :: ${r.name} \u2014 ${r.reason}
+`);
+      }
+      process.stdout.write(`
+${results.length - failed.length}/${results.length} passed.
+`);
+    }
+    process.exit(failed.length > 0 ? 1 : 0);
+  });
+}
+
+// src/commands/policy.ts
+import { Command as Command8 } from "commander";
+import { existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+function readAspOrDie(path) {
+  if (!existsSync8(path)) {
+    process.stderr.write(`\u2717 file not found: ${path}
+`);
+    process.exit(1);
+  }
+  return readFileSync7(path, "utf8");
+}
+function policyCommand() {
+  const cmd = new Command8("policy").description("Compile / sign ASP YAML policies.");
+  cmd.command("compile <file>").description("Compile ASP YAML \u2192 canonical JSON bundle body (unsigned).").option("--out <file>", "Write to file instead of stdout").action((file, opts) => {
+    const result = compileAspYamlToCanonicalJson(readAspOrDie(file));
+    if (!result.ok) {
+      for (const m of result.errors) process.stderr.write(`\u2717 ${m}
+`);
       process.exit(1);
     }
+    const out = JSON.stringify(result.body, null, 2) + "\n";
+    if (opts.out) {
+      writeFileSync4(opts.out, out);
+      process.stderr.write(`\u2713 wrote ${opts.out}
+`);
+    } else {
+      process.stdout.write(out);
+    }
   });
+  cmd.command("sign <file>").description(
+    "Compile + Ed25519-sign ASP YAML into a policy bundle the Aarmos runtime consumes. Reads AARMOS_POLICY_PRIVATE_KEY (base64url 32B seed)."
+  ).option("--out <file>", "Write signed bundle here (default: stdout)").action((file, opts) => {
+    const seed = process.env.AARMOS_POLICY_PRIVATE_KEY;
+    if (!seed) {
+      process.stderr.write("\u2717 AARMOS_POLICY_PRIVATE_KEY not set (base64url 32B ed25519 seed)\n");
+      process.exit(1);
+    }
+    const result = compileAspYamlToCanonicalJson(readAspOrDie(file));
+    if (!result.ok) {
+      for (const m of result.errors) process.stderr.write(`\u2717 ${m}
+`);
+      process.exit(1);
+    }
+    const signed = signBody(result.body, seed);
+    const out = JSON.stringify(signed, null, 2) + "\n";
+    if (opts.out) {
+      writeFileSync4(opts.out, out);
+      process.stderr.write(`\u2713 signed \u2192 ${opts.out}
+`);
+    } else {
+      process.stdout.write(out);
+    }
+  });
+  cmd.command("keygen").description("Generate a new Ed25519 keypair for signing ASP policies.").action(() => {
+    const k = keygen();
+    process.stdout.write(
+      `issuer.pubKey (paste into metadata.issuer.pubKey):
+  ${k.pubKeyB64}
+
+AARMOS_POLICY_PRIVATE_KEY (keep secret):
+  ${k.seedB64u}
+`
+    );
+  });
+  return cmd;
 }
 
 // src/index.ts
-var program = new Command6();
+var program = new Command9();
 program.name("aarmos").description(
   "Run your agent locally, across any protocol, with a signed receipt \u2014 in 60 seconds."
 ).version("0.1.0");
@@ -335,6 +1237,9 @@ program.addCommand(runCommand());
 program.addCommand(proxyCommand());
 program.addCommand(daemonCommand());
 program.addCommand(verifyCommand());
+program.addCommand(lintCommand());
+program.addCommand(testCommand());
+program.addCommand(policyCommand());
 program.parseAsync(process.argv).catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aarmos/cli",
-  "version": "0.1.2",
-  "description": "Aarmos CLI \u2014 run any agent locally, across any protocol (MCP, OpenAPI, deep-link), with a signed AVAR receipt on every execution. Sovereign runtime, universal tool gateway, verifiable governance.",
+  "version": "0.2.0",
+  "description": "Aarmos CLI — run any agent locally, across any protocol (MCP, OpenAPI, deep-link), with a signed AVAR receipt on every execution. Sovereign runtime, universal tool gateway, verifiable governance.",
   "keywords": [
     "aarmos",
     "agent",
@@ -36,14 +36,17 @@
   "author": "Aarmatix LLC",
   "license": "Apache-2.0",
   "dependencies": {
+    "@aarmos/avar-core": "^1.0.0-rc.3",
     "commander": "^12.1.0",
+    "fflate": "^0.8.3",
+    "yaml": "^2.9.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",
-    "tsup": "^8.3.0",
+    "tsup": "^8.5.1",
     "tsx": "^4.19.0",
-    "typescript": "^5.6.2"
+    "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=18.17"