@mnemom/mnemom 0.12.0 → 0.13.0

package/dist/commands/verify-card.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `mnemom verify-card` — cards-as-primitive Phase 5 D1.
+ *
+ * Offline verifier for AAP attestation tokens + transparency-log
+ * inclusion proofs. Fetches public-key material from
+ * `<api>/v1/.well-known/jwks.json` once, caches under `~/.mnemom/cache/`,
+ * then verifies the attestation against the cached JWKS without any
+ * subsequent server round-trip beyond the data the verifier asks for.
+ *
+ * Usage:
+ *   mnemom verify-card <agent_id> [--at <ISO>] [--card-kind alignment|protection]
+ *                                  [--api https://api.mnemom.ai] [--strict]
+ *                                  [--jwks-cache <path>] [--no-cache]
+ *
+ * Behavior:
+ *   1. Fetch JWKS from <api>/v1/.well-known/jwks.json (or load cached).
+ *   2. If --at present: fetch /v1/transparency/log/{id}?at=<ts>&card_kind=<k>.
+ *      Else: fetch the agent's current A2A AgentCard at
+ *      /v1/agents/{id}/a2a-agent-card and extract the embedded attestation.
+ *   3. Verify the JWS signature against the JWKS.
+ *   4. Fetch the transparency-log row by log_index for the freshly-computed
+ *      inclusion proof, plus /v1/transparency/root for the signed root.
+ *   5. Verify the Merkle inclusion proof against the root.
+ *   6. Print a care-framed result.
+ *
+ * --strict mode bypasses the JWKS cache and exits non-zero on any
+ * verification gap (signature, expiry, proof, root signature).
+ *
+ * care-framing:rule-slug care-framed-output — stderr lines use the
+ * would-benefit-from vocabulary; stdout carries machine-readable
+ * verification status.
+ */
+interface JwkPublic {
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+    kid: string;
+    alg?: string;
+    use?: string;
+    mnemom_ext?: {
+        status?: "active" | "retired";
+        activated_at?: string;
+        retired_at?: string;
+        rotation_reason?: string;
+    };
+}
+interface Jwks {
+    keys: JwkPublic[];
+}
+interface AttestationPayload {
+    typ: "AAP-Attestation/v1";
+    iss: string;
+    sub: string;
+    iat: number;
+    exp: number;
+    content_hash: string;
+    version: number;
+    composed_at: string;
+    card_kind: "alignment" | "protection";
+    smolt_id?: string;
+    historic_backfill?: true;
+}
+interface MerkleProof {
+    leaf_hash: string;
+    log_index: number;
+    tree_size: number;
+    hashes: {
+        sibling: string;
+        position: "left" | "right";
+    }[];
+}
+export interface VerifyCardOptions {
+    agentId: string;
+    at?: string;
+    cardKind?: "alignment" | "protection";
+    api?: string;
+    strict?: boolean;
+    jwksCache?: string;
+    noCache?: boolean;
+}
+export declare function verifyCardCommand(options: VerifyCardOptions): Promise<number>;
+interface JwsVerification {
+    ok: boolean;
+    kid?: string;
+    payload?: AttestationPayload;
+    error?: string;
+}
+declare function verifyJws(jws: string, jwks: Jwks): Promise<JwsVerification>;
+declare function verifyInclusionProof(proof: MerkleProof, expectedRoot: string): Promise<boolean>;
+declare function internalHash(left: string, right: string): Promise<string>;
+declare function base64urlDecode(s: string): Uint8Array;
+declare function base64urlDecodeString(s: string): string;
+declare function hexToBytes(hex: string): Uint8Array;
+export declare const __testing: {
+    verifyInclusionProof: typeof verifyInclusionProof;
+    internalHash: typeof internalHash;
+    hexToBytes: typeof hexToBytes;
+    base64urlDecode: typeof base64urlDecode;
+    base64urlDecodeString: typeof base64urlDecodeString;
+    verifyJws: typeof verifyJws;
+};
+export {};

package/dist/commands/verify-card.js

@@ -0,0 +1,287 @@
+/**
+ * `mnemom verify-card` — cards-as-primitive Phase 5 D1.
+ *
+ * Offline verifier for AAP attestation tokens + transparency-log
+ * inclusion proofs. Fetches public-key material from
+ * `<api>/v1/.well-known/jwks.json` once, caches under `~/.mnemom/cache/`,
+ * then verifies the attestation against the cached JWKS without any
+ * subsequent server round-trip beyond the data the verifier asks for.
+ *
+ * Usage:
+ *   mnemom verify-card <agent_id> [--at <ISO>] [--card-kind alignment|protection]
+ *                                  [--api https://api.mnemom.ai] [--strict]
+ *                                  [--jwks-cache <path>] [--no-cache]
+ *
+ * Behavior:
+ *   1. Fetch JWKS from <api>/v1/.well-known/jwks.json (or load cached).
+ *   2. If --at present: fetch /v1/transparency/log/{id}?at=<ts>&card_kind=<k>.
+ *      Else: fetch the agent's current A2A AgentCard at
+ *      /v1/agents/{id}/a2a-agent-card and extract the embedded attestation.
+ *   3. Verify the JWS signature against the JWKS.
+ *   4. Fetch the transparency-log row by log_index for the freshly-computed
+ *      inclusion proof, plus /v1/transparency/root for the signed root.
+ *   5. Verify the Merkle inclusion proof against the root.
+ *   6. Print a care-framed result.
+ *
+ * --strict mode bypasses the JWKS cache and exits non-zero on any
+ * verification gap (signature, expiry, proof, root signature).
+ *
+ * care-framing:rule-slug care-framed-output — stderr lines use the
+ * would-benefit-from vocabulary; stdout carries machine-readable
+ * verification status.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { MNEMOM_DIR } from "../lib/config.js";
+const JWKS_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+const DEFAULT_API = "https://api.mnemom.ai";
+export async function verifyCardCommand(options) {
+    const api = (options.api ?? DEFAULT_API).replace(/\/+$/, "");
+    const cardKind = options.cardKind ?? "alignment";
+    const cachePath = options.jwksCache ?? path.join(MNEMOM_DIR, "cache", "aap-jwks.json");
+    let exitCode = 0;
+    const findings = [];
+    try {
+        const jwks = await loadJwks(api, cachePath, !options.strict && !options.noCache);
+        // Step 2: fetch the attestation + log row.
+        const target = await resolveTargetEntry(api, options.agentId, cardKind, options.at);
+        if (!target) {
+            process.stderr.write(`No attestation was integrated for ${options.agentId} (kind=${cardKind})${options.at ? ` at-or-before ${options.at}` : ""} — nothing to verify yet.\n`);
+            return options.strict ? 1 : 0;
+        }
+        // Step 3: verify the JWS signature against the JWKS.
+        const verification = await verifyJws(target.entry.signed_attestation, jwks);
+        if (!verification.ok) {
+            findings.push(`signature: ${verification.error}`);
+            exitCode = 1;
+        }
+        else {
+            findings.push(`signature: ok (kid=${verification.kid})`);
+        }
+        const payload = verification.payload;
+        // Step 4: fetch signed root.
+        const root = await fetchSignedRoot(api);
+        if (!root) {
+            findings.push("merkle: transparency log is empty (no root to verify against)");
+        }
+        else {
+            // Step 5: verify the Merkle inclusion proof.
+            const proofOk = await verifyInclusionProof(target.inclusion_proof, root.root_hash);
+            if (!proofOk) {
+                findings.push(`merkle: inclusion proof did not reconstruct root (log_index=${target.entry.log_index}, tree_size=${target.inclusion_proof.tree_size})`);
+                exitCode = 1;
+            }
+            else {
+                findings.push(`merkle: inclusion proof ok (log_index=${target.entry.log_index}, tree_size=${target.inclusion_proof.tree_size})`);
+            }
+        }
+        // Step 6: print result.
+        const result = {
+            ok: exitCode === 0,
+            agent_id: target.entry.agent_id,
+            card_kind: target.entry.card_kind,
+            content_hash: target.entry.content_hash,
+            version: target.entry.version,
+            composed_at: target.entry.composed_at,
+            integrated_time: target.entry.integrated_time,
+            signing_key_id: target.entry.signing_key_id,
+            historic_backfill: payload?.historic_backfill === true,
+            findings,
+        };
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        if (exitCode === 0) {
+            process.stderr.write(`Canonical posture verifies: ${target.entry.agent_id} @ version ${target.entry.version} composed ${target.entry.composed_at}.\n`);
+        }
+        else {
+            process.stderr.write(`Verification gaps surfaced — see findings above.\n`);
+        }
+        return exitCode;
+    }
+    catch (err) {
+        process.stderr.write(`verify-card couldn't complete — the underlying registry surfaced an error: ${err.message}\n`);
+        return 1;
+    }
+}
+// ── JWKS fetch + cache ───────────────────────────────────────────────
+async function loadJwks(api, cachePath, useCache) {
+    if (useCache && fs.existsSync(cachePath)) {
+        try {
+            const stat = fs.statSync(cachePath);
+            if (Date.now() - stat.mtimeMs < JWKS_CACHE_TTL_MS) {
+                const raw = fs.readFileSync(cachePath, "utf8");
+                return JSON.parse(raw);
+            }
+        }
+        catch {
+            /* fall through to network */
+        }
+    }
+    const res = await fetch(`${api}/v1/.well-known/jwks.json`);
+    if (!res.ok) {
+        throw new Error(`JWKS fetch failed: ${res.status} ${await res.text()}`);
+    }
+    const jwks = (await res.json());
+    if (useCache) {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify(jwks, null, 2));
+    }
+    return jwks;
+}
+async function resolveTargetEntry(api, agentId, cardKind, at) {
+    if (at) {
+        const url = new URL(`${api}/v1/transparency/log/${encodeURIComponent(agentId)}`);
+        url.searchParams.set("at", at);
+        url.searchParams.set("card_kind", cardKind);
+        const res = await fetch(url.toString());
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            throw new Error(`transparency log at lookup failed: ${res.status}`);
+        }
+        return (await res.json());
+    }
+    // No --at: fetch the A2A AgentCard for live attestation, then locate
+    // the matching log entry by content_hash + version.
+    const a2aRes = await fetch(`${api}/v1/agents/${encodeURIComponent(agentId)}/a2a-agent-card`);
+    if (a2aRes.status === 404)
+        return null;
+    if (!a2aRes.ok) {
+        throw new Error(`A2A export fetch failed: ${a2aRes.status}`);
+    }
+    const card = (await a2aRes.json());
+    const attestation = card.extensions?.find((e) => e.uri === "https://aap.mnemom.ai/v1/attestation");
+    if (!attestation || typeof attestation.body?.token !== "string") {
+        throw new Error("A2A AgentCard exists but ships no AAP attestation extension — AAP_ATTESTATION_SIGNING_ENABLED may be off on the server.");
+    }
+    // Decode payload for content_hash + version to locate the log entry.
+    const segs = attestation.body.token.split(".");
+    if (segs.length !== 3) {
+        throw new Error("Embedded attestation is not a 3-part JWS.");
+    }
+    const payload = JSON.parse(base64urlDecodeString(segs[1]));
+    // Now fetch the log row matching this content_hash + version.
+    return resolveLatestLogEntry(api, agentId, cardKind, payload.composed_at);
+}
+async function resolveLatestLogEntry(api, agentId, cardKind, composedAt) {
+    const url = new URL(`${api}/v1/transparency/log/${encodeURIComponent(agentId)}`);
+    url.searchParams.set("at", composedAt);
+    url.searchParams.set("card_kind", cardKind);
+    const res = await fetch(url.toString());
+    if (res.status === 404)
+        return null;
+    if (!res.ok) {
+        throw new Error(`transparency log latest lookup failed: ${res.status}`);
+    }
+    return (await res.json());
+}
+async function fetchSignedRoot(api) {
+    const res = await fetch(`${api}/v1/transparency/root`);
+    if (!res.ok)
+        return null;
+    const body = (await res.json());
+    if (body.tree_size === 0)
+        return null;
+    return body;
+}
+async function verifyJws(jws, jwks) {
+    const parts = jws.split(".");
+    if (parts.length !== 3) {
+        return { ok: false, error: "JWS does not have three parts" };
+    }
+    let header;
+    let payload;
+    try {
+        header = JSON.parse(base64urlDecodeString(parts[0]));
+        payload = JSON.parse(base64urlDecodeString(parts[1]));
+    }
+    catch {
+        return { ok: false, error: "could not parse JWS header/payload" };
+    }
+    if (header.alg !== "EdDSA" || header.typ !== "AAP-Attestation/v1") {
+        return { ok: false, error: `unexpected header alg=${header.alg} typ=${header.typ}` };
+    }
+    const kid = header.kid ?? "";
+    const key = jwks.keys.find((k) => k.kid === kid);
+    if (!key) {
+        return { ok: false, error: `kid ${kid} not in JWKS` };
+    }
+    const publicKey = await crypto.subtle.importKey("jwk", { kty: key.kty, crv: key.crv, x: key.x, ext: true }, { name: "Ed25519" }, true, ["verify"]);
+    const signingInput = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+    const sigBytes = base64urlDecode(parts[2]);
+    // BufferSource over a fresh ArrayBuffer keeps newer TS lib defs happy
+    // (older Uint8Array<ArrayBufferLike> trips a SharedArrayBuffer mismatch).
+    const sigBuf = new ArrayBuffer(sigBytes.length);
+    new Uint8Array(sigBuf).set(sigBytes);
+    const sigOk = await crypto.subtle.verify("Ed25519", publicKey, sigBuf, signingInput);
+    if (!sigOk) {
+        return { ok: false, kid, payload, error: "signature did not verify" };
+    }
+    const nowSecs = Math.floor(Date.now() / 1000);
+    if (nowSecs >= payload.exp) {
+        return {
+            ok: false,
+            kid,
+            payload,
+            error: `token expired at ${new Date(payload.exp * 1000).toISOString()} — the transparency log row still proves the historic posture but the embedded token is past its TTL.`,
+        };
+    }
+    return { ok: true, kid, payload };
+}
+// ── Merkle proof verification ────────────────────────────────────────
+async function verifyInclusionProof(proof, expectedRoot) {
+    let current = proof.leaf_hash;
+    for (const step of proof.hashes) {
+        if (step.position === "right") {
+            current = await internalHash(current, step.sibling);
+        }
+        else {
+            current = await internalHash(step.sibling, current);
+        }
+    }
+    return current === expectedRoot;
+}
+async function internalHash(left, right) {
+    const leftBytes = hexToBytes(left);
+    const rightBytes = hexToBytes(right);
+    const buf = new Uint8Array(1 + leftBytes.length + rightBytes.length);
+    buf[0] = 0x01;
+    buf.set(leftBytes, 1);
+    buf.set(rightBytes, 1 + leftBytes.length);
+    const digest = await crypto.subtle.digest("SHA-256", buf);
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// ── Encoding helpers ─────────────────────────────────────────────────
+function base64urlDecode(s) {
+    const padded = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice(0, (4 - (s.length % 4)) % 4);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function base64urlDecodeString(s) {
+    return new TextDecoder().decode(base64urlDecode(s));
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error(`hexToBytes: odd-length hex "${hex}"`);
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+// Sentinel for tests that want to exercise individual helpers.
+export const __testing = {
+    verifyInclusionProof,
+    internalHash,
+    hexToBytes,
+    base64urlDecode,
+    base64urlDecodeString,
+    verifyJws,
+};
+// Silence "MNEMOM_DIR unused" if the cache code path is taken in tests.
+void MNEMOM_DIR;

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { program } from "commander";
+import { CLI_VERSION } from "./version.js";
 import { statusCommand } from "./commands/status.js";
 import { integrityCommand } from "./commands/integrity.js";
 import { logsCommand } from "./commands/logs.js";
@@ -20,7 +21,7 @@ import { listenCommand } from "./commands/listen.js";
 program
     .name("mnemom")
     .description("Transparent AI agent tracing")
-    .version("0.9.1")
+    .version(CLI_VERSION)
     .option("--agent <name>", "Select agent by name (or set MNEMOM_AGENT)");
 program
     .command("status")
@@ -149,10 +150,12 @@ cardCmd
 cardCmd
     .command("validate")
     .argument("<file>", "Path to alignment card file (YAML or JSON)")
-    .description("Validate alignment card locally")
-    .action(async (file) => {
+    .description("Validate an alignment card (server-authoritative when --agent is set; --offline forces local)")
+    .option("--offline", "Validate locally only (skip the server preview-compose)")
+    .action(async (file, subOpts) => {
     try {
-        await cardValidateCommand(file);
+        const opts = program.opts();
+        await cardValidateCommand(file, { offline: subOpts.offline, agent: opts.agent });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -224,10 +227,12 @@ protectionCmd
 protectionCmd
     .command("validate")
     .argument("<file>", "Path to protection card file (YAML or JSON)")
-    .description("Validate protection card locally")
-    .action(async (file) => {
+    .description("Validate a protection card (server-authoritative when --agent is set; --offline forces local)")
+    .option("--offline", "Validate locally only (skip the server preview-compose)")
+    .action(async (file, subOpts) => {
     try {
-        await protectionValidateCommand(file);
+        const opts = program.opts();
+        await protectionValidateCommand(file, { offline: subOpts.offline, agent: opts.agent });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -1214,7 +1219,7 @@ program
 // fingerprint is folded server-side so a retry with corrected text returns
 // 422 rather than silently replaying.
 // ============================================================================
-import { recipesReportFnCommand, recipesReportFpCommand, } from "./commands/recipes.js";
+import { recipesReportFnCommand, recipesReportFpCommand } from "./commands/recipes.js";
 const recipesCmd = program
     .command("recipes")
     .description("Customer-side recipe reporting (false-negatives, false-positives)");
@@ -1252,4 +1257,43 @@ recipesCmd
         process.exit(1);
     }
 });
+// ============================================================================
+// verify-card — cards-as-primitive Phase 5 D1
+// ============================================================================
+//
+// Offline verifier for AAP attestation tokens + transparency-log Merkle
+// inclusion proofs. Validates that a Mnemom-published canonical card was
+// in fact composed by Mnemom at the claimed (content_hash, version,
+// composed_at) point in time. JWKS is cached at ~/.mnemom/cache/aap-jwks.json
+// for one hour; --strict bypasses the cache.
+program
+    .command("verify-card")
+    .description("Verify a Mnemom-published canonical card's AAP attestation + Merkle inclusion proof offline.")
+    .argument("<agent_id>", "Mnemom agent id (e.g., smolt-e2ca60ef)")
+    .option("--at <iso>", "Verify the historic posture at this ISO-8601 timestamp (defaults to current live A2A export).")
+    .option("--card-kind <kind>", "alignment | protection (defaults to alignment)", "alignment")
+    .option("--api <url>", "Mnemom API base (defaults to https://api.mnemom.ai)", "https://api.mnemom.ai")
+    .option("--strict", "Bypass JWKS cache; exit non-zero on any verification gap.")
+    .option("--jwks-cache <path>", "Override the JWKS cache path (default ~/.mnemom/cache/aap-jwks.json)")
+    .option("--no-cache", "Skip the JWKS cache for this invocation.")
+    .action(async (agentId, options) => {
+    try {
+        const { verifyCardCommand } = await import("./commands/verify-card.js");
+        const kind = options.cardKind === "protection" ? "protection" : "alignment";
+        const rc = await verifyCardCommand({
+            agentId,
+            at: options.at,
+            cardKind: kind,
+            api: options.api,
+            strict: options.strict,
+            jwksCache: options.jwksCache,
+            noCache: options.cache === false,
+        });
+        process.exit(rc);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 program.parse();