@mnemom/mnemom 0.11.0 → 0.12.1

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/commands/webhooks.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `mnemom webhooks ...` commands — Track 2 W3.5.
+ *
+ *   mnemom webhooks list <org_id>                              — list endpoints
+ *   mnemom webhooks get <org_id> <endpoint_id>                 — show one
+ *   mnemom webhooks create <org_id> --url <u> [--events <list>]
+ *                                              [--description <d>]
+ *   mnemom webhooks update <org_id> <endpoint_id> [--url <u>]
+ *                                                  [--events <list>]
+ *                                                  [--active <bool>]
+ *   mnemom webhooks delete <org_id> <endpoint_id>              — remove endpoint
+ *   mnemom webhooks rotate-secret <org_id> <endpoint_id>       — mint new secret
+ *   mnemom webhooks list-deliveries <org_id> [--endpoint <id>] [--limit <n>]
+ *   mnemom webhooks redeliver <org_id> <delivery_id>           — retry one delivery
+ *   mnemom webhooks replay <org_id> <event_id> [--endpoint <id>...]
+ *   mnemom webhooks trigger <org_id> <endpoint_id>             — fire a test event
+ *
+ * Every mutation auto-generates a fresh `Idempotency-Key`. Re-running the
+ * same command does NOT replay the cache (you'd need to keep the key
+ * around for that — the curl/programmatic clients do); for the typical
+ * CLI ergonomic path, each invocation is its own logical mutation.
+ */
+export declare function webhooksListCommand(orgId: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksGetCommand(orgId: string, endpointId: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksCreateCommand(orgId: string, opts?: {
+    url?: string;
+    events?: string;
+    description?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksUpdateCommand(orgId: string, endpointId: string, opts?: {
+    url?: string;
+    events?: string;
+    description?: string;
+    active?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksDeleteCommand(orgId: string, endpointId: string): Promise<void>;
+export declare function webhooksRotateSecretCommand(orgId: string, endpointId: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksTriggerCommand(orgId: string, endpointId: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksListDeliveriesCommand(orgId: string, opts?: {
+    endpoint?: string;
+    limit?: string;
+    offset?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksRedeliverCommand(orgId: string, deliveryId: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function webhooksReplayCommand(orgId: string, eventId: string, opts?: {
+    endpoint?: string[];
+    json?: boolean;
+}): Promise<void>;