@mnemom/mnemom 0.11.0 → 0.12.1

package/dist/commands/webhooks.js

@@ -0,0 +1,328 @@
+/**
+ * `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.
+ */
+import { listWebhookEndpoints, getWebhookEndpoint, createWebhookEndpoint, updateWebhookEndpoint, deleteWebhookEndpoint, rotateWebhookSecret, testWebhookEndpoint, listWebhookDeliveries, redeliverWebhookEvent, replayWebhookEvent, } from "../lib/webhooks-api.js";
+import { requireAuth } from "../lib/auth.js";
+import { fmt } from "../lib/format.js";
+function parseEventList(value) {
+    if (!value)
+        return undefined;
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function fail(msg) {
+    console.log(fmt.error(msg) + "\n");
+    process.exit(1);
+}
+function shortenSecret(secret) {
+    if (!secret)
+        return "—";
+    if (secret.length <= 16)
+        return secret;
+    return `${secret.slice(0, 8)}…${secret.slice(-4)}`;
+}
+function formatTime(ts) {
+    if (!ts)
+        return "—";
+    try {
+        return new Date(ts).toISOString().replace("T", " ").slice(0, 19) + "Z";
+    }
+    catch {
+        return ts;
+    }
+}
+// ─── list ────────────────────────────────────────────────────────────────
+export async function webhooksListCommand(orgId, opts = {}) {
+    await requireAuth();
+    let endpoints;
+    try {
+        endpoints = await listWebhookEndpoints(orgId);
+    }
+    catch (err) {
+        fail(`Failed to list endpoints: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(endpoints, null, 2));
+        return;
+    }
+    console.log(fmt.header(`Webhook endpoints — org ${orgId}`));
+    console.log();
+    if (endpoints.length === 0) {
+        console.log("  No endpoints configured. Create one with `mnemom webhooks create`.\n");
+        return;
+    }
+    const idW = 26;
+    const urlW = 44;
+    const eventsW = 8;
+    const activeW = 8;
+    console.log("Endpoint".padEnd(idW) +
+        "URL".padEnd(urlW) +
+        "Events".padEnd(eventsW) +
+        "Active".padEnd(activeW));
+    console.log("─".repeat(idW + urlW + eventsW + activeW));
+    for (const ep of endpoints) {
+        const url = ep.url.length > urlW - 1 ? ep.url.slice(0, urlW - 4) + "…" : ep.url;
+        console.log(ep.endpoint_id.padEnd(idW) +
+            url.padEnd(urlW) +
+            String(ep.event_types.length).padEnd(eventsW) +
+            (ep.is_active ? "yes" : "no").padEnd(activeW));
+    }
+    console.log();
+}
+// ─── get ─────────────────────────────────────────────────────────────────
+export async function webhooksGetCommand(orgId, endpointId, opts = {}) {
+    await requireAuth();
+    let ep;
+    try {
+        ep = await getWebhookEndpoint(orgId, endpointId);
+    }
+    catch (err) {
+        fail(`Failed to fetch endpoint: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(ep, null, 2));
+        return;
+    }
+    console.log(fmt.header(`Webhook endpoint ${ep.endpoint_id}`));
+    console.log();
+    console.log(`  URL          ${ep.url}`);
+    console.log(`  Description  ${ep.description || "(none)"}`);
+    console.log(`  Events       ${ep.event_types.length === 0 ? "(none)" : ep.event_types.join(", ")}`);
+    console.log(`  Active       ${ep.is_active ? "yes" : "no"}`);
+    console.log(`  Failures     ${ep.consecutive_failures}`);
+    if (ep.disabled_at) {
+        console.log(`  Disabled at  ${formatTime(ep.disabled_at)} — ${ep.disabled_reason ?? "(no reason)"}`);
+    }
+    console.log(`  Created      ${formatTime(ep.created_at)}`);
+    console.log(`  Updated      ${formatTime(ep.updated_at)}`);
+    if (ep.signing_secret) {
+        console.log(`  Secret       ${shortenSecret(ep.signing_secret)} (shown only on create / rotate)`);
+    }
+    console.log();
+}
+// ─── create ──────────────────────────────────────────────────────────────
+export async function webhooksCreateCommand(orgId, opts = {}) {
+    await requireAuth();
+    if (!opts.url)
+        fail("--url is required (HTTPS only; private/internal IPs blocked)");
+    let created;
+    try {
+        created = await createWebhookEndpoint(orgId, {
+            url: opts.url,
+            description: opts.description,
+            event_types: parseEventList(opts.events),
+        });
+    }
+    catch (err) {
+        fail(`Failed to create endpoint: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(created, null, 2));
+        return;
+    }
+    console.log(fmt.success("Webhook endpoint created"));
+    console.log();
+    console.log(`  Endpoint ID    ${created.endpoint_id}`);
+    console.log(`  URL            ${created.url}`);
+    console.log(`  Events         ${created.event_types.length === 0 ? "(none — explicit per-event opt-in required)" : created.event_types.join(", ")}`);
+    if (created.signing_secret) {
+        console.log();
+        console.log(fmt.warn("Signing secret (shown ONCE — store it now):"));
+        console.log(`  ${created.signing_secret}`);
+    }
+    console.log();
+}
+// ─── update ──────────────────────────────────────────────────────────────
+export async function webhooksUpdateCommand(orgId, endpointId, opts = {}) {
+    await requireAuth();
+    const body = {};
+    if (opts.url !== undefined)
+        body.url = opts.url;
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    const events = parseEventList(opts.events);
+    if (events !== undefined)
+        body.event_types = events;
+    if (opts.active !== undefined) {
+        if (opts.active === "true")
+            body.is_active = true;
+        else if (opts.active === "false")
+            body.is_active = false;
+        else
+            fail("--active must be 'true' or 'false'");
+    }
+    if (Object.keys(body).length === 0)
+        fail("Nothing to update — pass --url / --events / --description / --active.");
+    let updated;
+    try {
+        updated = await updateWebhookEndpoint(orgId, endpointId, body);
+    }
+    catch (err) {
+        fail(`Failed to update endpoint: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(updated, null, 2));
+        return;
+    }
+    console.log(fmt.success(`Updated endpoint ${updated.endpoint_id}`));
+    console.log();
+}
+// ─── delete ──────────────────────────────────────────────────────────────
+export async function webhooksDeleteCommand(orgId, endpointId) {
+    await requireAuth();
+    try {
+        await deleteWebhookEndpoint(orgId, endpointId);
+    }
+    catch (err) {
+        fail(`Failed to delete endpoint: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    console.log(fmt.success(`Deleted endpoint ${endpointId}`));
+    console.log();
+}
+// ─── rotate-secret ───────────────────────────────────────────────────────
+export async function webhooksRotateSecretCommand(orgId, endpointId, opts = {}) {
+    await requireAuth();
+    let result;
+    try {
+        result = await rotateWebhookSecret(orgId, endpointId);
+    }
+    catch (err) {
+        fail(`Failed to rotate secret: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(fmt.success(`Rotated signing secret for ${result.endpoint_id}`));
+    console.log();
+    console.log(fmt.warn("New signing secret (shown ONCE — store it now):"));
+    console.log(`  ${result.signing_secret}`);
+    console.log();
+}
+// ─── trigger (test) ──────────────────────────────────────────────────────
+export async function webhooksTriggerCommand(orgId, endpointId, opts = {}) {
+    await requireAuth();
+    let result;
+    try {
+        result = await testWebhookEndpoint(orgId, endpointId);
+    }
+    catch (err) {
+        fail(`Failed to trigger test: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.success) {
+        console.log(fmt.success(`Test delivery succeeded — receiver returned ${result.status} in ${result.latency_ms}ms`));
+    }
+    else {
+        console.log(fmt.error(`Test delivery failed — status ${result.status ?? "(no response)"}`));
+        if (result.error)
+            console.log(`  ${result.error}`);
+    }
+    console.log();
+}
+// ─── list-deliveries ─────────────────────────────────────────────────────
+export async function webhooksListDeliveriesCommand(orgId, opts = {}) {
+    await requireAuth();
+    const limit = opts.limit ? parseInt(opts.limit, 10) : undefined;
+    const offset = opts.offset ? parseInt(opts.offset, 10) : undefined;
+    let deliveries;
+    try {
+        deliveries = await listWebhookDeliveries(orgId, {
+            endpointId: opts.endpoint,
+            limit: limit && !Number.isNaN(limit) ? limit : undefined,
+            offset: offset && !Number.isNaN(offset) ? offset : undefined,
+        });
+    }
+    catch (err) {
+        fail(`Failed to list deliveries: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(deliveries, null, 2));
+        return;
+    }
+    console.log(fmt.header(`Webhook deliveries — org ${orgId}`));
+    console.log();
+    if (deliveries.length === 0) {
+        console.log("  No deliveries on record.\n");
+        return;
+    }
+    for (const d of deliveries) {
+        const ts = formatTime(d.last_attempt_at ?? d.created_at);
+        console.log(`  ${d.delivery_id}  ${d.status.padEnd(10)} → endpoint ${d.endpoint_id} (${ts})`);
+    }
+    console.log();
+}
+// ─── redeliver ───────────────────────────────────────────────────────────
+export async function webhooksRedeliverCommand(orgId, deliveryId, opts = {}) {
+    await requireAuth();
+    let result;
+    try {
+        result = await redeliverWebhookEvent(orgId, deliveryId);
+    }
+    catch (err) {
+        fail(`Failed to redeliver: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(fmt.success(`Redelivery queued — new delivery_id ${result.delivery_id} (status ${result.status})`));
+    console.log();
+}
+// ─── replay ──────────────────────────────────────────────────────────────
+export async function webhooksReplayCommand(orgId, eventId, opts = {}) {
+    await requireAuth();
+    let result;
+    try {
+        result = await replayWebhookEvent(orgId, eventId, { endpointIds: opts.endpoint });
+    }
+    catch (err) {
+        fail(`Failed to replay event: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(fmt.header(`Replay — event ${eventId} (${result.event_type})`));
+    console.log();
+    if (result.deliveries.length === 0) {
+        console.log("  " + (result.message ?? "No subscribed endpoints to replay to."));
+        console.log();
+        return;
+    }
+    for (const d of result.deliveries) {
+        console.log(`  ✓ ${d.delivery_id} → endpoint ${d.endpoint_id}`);
+    }
+    if (result.failed_endpoints && result.failed_endpoints.length > 0) {
+        console.log();
+        console.log(fmt.warn("Failed endpoints:"));
+        for (const f of result.failed_endpoints) {
+            console.log(`  ✗ ${f.endpoint_id}: ${f.error}`);
+        }
+    }
+    console.log();
+}

package/dist/index.js

@@ -10,11 +10,13 @@ import { protectionShowCommand, protectionPublishCommand, protectionValidateComm
 import { agentsListCommand } from "./commands/agents.js";
 import { orgListCommand, orgShowCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
-import { advisoriesListCommand, advisoriesShowCommand, } from "./commands/advisories.js";
+import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
 import { postureListCommand, postureShowCommand, postureCreateCommand, postureUpdateCommand, postureCloneCommand, postureRevisionsCommand, postureDiffCommand, postureAssignCommand, postureUnassignCommand, posturePreviewComposeCommand, postureDeleteCommand, } from "./commands/posture.js";
 import { loginCommand, logoutCommand, whoamiCommand } from "./commands/auth.js";
 import { validateSafeHouseCommand } from "./commands/validate.js";
 import { apiKeyListCommand, apiKeyCreateCommand, apiKeyRotateCommand, apiKeyRevokeCommand, } from "./commands/api-key.js";
+import { webhooksListCommand, webhooksGetCommand, webhooksCreateCommand, webhooksUpdateCommand, webhooksDeleteCommand, webhooksRotateSecretCommand, webhooksTriggerCommand, webhooksListDeliveriesCommand, webhooksRedeliverCommand, webhooksReplayCommand, } from "./commands/webhooks.js";
+import { listenCommand } from "./commands/listen.js";
 program
     .name("mnemom")
     .description("Transparent AI agent tracing")
@@ -638,7 +640,7 @@ govDestCmd
     .description("Add a destination (channel + JSON config)")
     .requiredOption("--org <id>", "Org ID")
     .requiredOption("--channel <c>", "webhook|slack|email|pagerduty")
-    .requiredOption("--config <json>", "Channel config (e.g., '{\"url\":\"...\",\"signing_secret\":\"...\"}')")
+    .requiredOption("--config <json>", 'Channel config (e.g., \'{"url":"...","signing_secret":"..."}\')')
     .option("--name <n>", "Display name")
     .option("--filter <json>", "Filter narrowing (sources/severities/etc)")
     .option("--json", "Output JSON")
@@ -701,7 +703,7 @@ govRulesCmd
     .description("Add an escalation rule (predicate JSON + destination IDs)")
     .requiredOption("--org <id>", "Org ID")
     .requiredOption("--name <n>", "Rule name")
-    .requiredOption("--predicate <json>", "Predicate JSON (e.g., '{\"source\":\"sideband.fleet\",\"severity_min\":\"high\"}')")
+    .requiredOption("--predicate <json>", 'Predicate JSON (e.g., \'{"source":"sideband.fleet","severity_min":"high"}\')')
     .requiredOption("--destinations <ids>", "Comma-separated destination IDs")
     .option("--json", "Output JSON")
     .action(async (options) => {
@@ -1035,4 +1037,258 @@ apiKeyCmd
         process.exit(1);
     }
 });
+// ============================================================================
+// Webhook lifecycle commands (Track 2 W3.5)
+// ============================================================================
+const webhooksCmd = program
+    .command("webhooks")
+    .description("Manage webhook endpoints, deliveries, and event replay");
+webhooksCmd
+    .command("list <org_id>")
+    .description("List webhook endpoints for an org")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, options) => {
+    try {
+        await webhooksListCommand(orgId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("get <org_id> <endpoint_id>")
+    .description("Show details for a single webhook endpoint")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, endpointId, options) => {
+    try {
+        await webhooksGetCommand(orgId, endpointId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("create <org_id>")
+    .description("Create a new webhook endpoint (signing secret returned ONCE)")
+    .requiredOption("--url <url>", "HTTPS URL to deliver events to (private/internal IPs blocked)")
+    .option("--events <list>", "Comma-separated list of event types to subscribe to (default: none — explicit per-event opt-in)")
+    .option("--description <text>", "Human-readable description")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, options) => {
+    try {
+        await webhooksCreateCommand(orgId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("update <org_id> <endpoint_id>")
+    .description("Update fields on an existing webhook endpoint")
+    .option("--url <url>", "Replace the delivery URL")
+    .option("--events <list>", "Replace the event-type subscription list (comma-separated)")
+    .option("--description <text>", "Replace the description")
+    .option("--active <bool>", "Set is_active to 'true' or 'false' (re-enabling resets failure counter)")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, endpointId, options) => {
+    try {
+        await webhooksUpdateCommand(orgId, endpointId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("delete <org_id> <endpoint_id>")
+    .description("Permanently delete a webhook endpoint")
+    .action(async (orgId, endpointId) => {
+    try {
+        await webhooksDeleteCommand(orgId, endpointId);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("rotate-secret <org_id> <endpoint_id>")
+    .description("Mint a new signing secret (shown ONCE; immediately invalidates the previous secret)")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, endpointId, options) => {
+    try {
+        await webhooksRotateSecretCommand(orgId, endpointId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("trigger <org_id> <endpoint_id>")
+    .description("Fire a synthetic test event through the full delivery pipeline (Stripe-equivalent ergonomics)")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, endpointId, options) => {
+    try {
+        await webhooksTriggerCommand(orgId, endpointId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("list-deliveries <org_id>")
+    .description("List recent webhook deliveries (optionally scoped to one endpoint)")
+    .option("--endpoint <endpoint_id>", "Scope to a single endpoint")
+    .option("--limit <n>", "Maximum entries to return (default 50, max 100)")
+    .option("--offset <n>", "Skip the first N entries (pagination)")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, options) => {
+    try {
+        await webhooksListDeliveriesCommand(orgId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("redeliver <org_id> <delivery_id>")
+    .description("Retry a single previous delivery (re-fires that one delivery row)")
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, deliveryId, options) => {
+    try {
+        await webhooksRedeliverCommand(orgId, deliveryId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+webhooksCmd
+    .command("replay <org_id> <event_id>")
+    .description("Re-fan-out a historical event to all currently-subscribed endpoints (or to a specified subset)")
+    .option("--endpoint <endpoint_id>", "Only replay to the specified endpoint (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
+    .option("--json", "Emit raw JSON instead of rendered output")
+    .action(async (orgId, eventId, options) => {
+    try {
+        await webhooksReplayCommand(orgId, eventId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+// ============================================================================
+// mnemom listen — live webhook event stream (Track 2 W3.4)
+// ============================================================================
+program
+    .command("listen <org_id>")
+    .description("Stream live webhook events for an org (Stripe-equivalent ergonomics)")
+    .option("--forward-to <url>", "POST each event to this local URL (requires --secret for HMAC re-signing)")
+    .option("--secret <hex>", "Local signing secret used to re-sign forwarded deliveries")
+    .option("--filter <list>", "Comma-separated event types to surface (default: all)")
+    .option("--since <event_id>", "Resume from this cursor on first connect")
+    .option("--json", "Emit raw JSON lines instead of a formatted summary")
+    .action(async (orgId, options) => {
+    try {
+        await listenCommand(orgId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+// ============================================================================
+// AEGIS-6b — Customer FN/FP recipe report commands.
+//
+// `mnemom recipes report-fn <recipe-id>` / `mnemom recipes report-fp <id>`
+// POST to /v1/recipes/:id/report (AEGIS-6a; mnemom-api#508). The endpoint
+// requires customer-session auth (JWT cookie/bearer or API key) and a
+// non-empty summary; the CLI accepts the summary as `--summary` or via
+// stdin. Idempotency-Key is generated per call by postApi(); the body
+// fingerprint is folded server-side so a retry with corrected text returns
+// 422 rather than silently replaying.
+// ============================================================================
+import { recipesReportFnCommand, recipesReportFpCommand } from "./commands/recipes.js";
+const recipesCmd = program
+    .command("recipes")
+    .description("Customer-side recipe reporting (false-negatives, false-positives)");
+recipesCmd
+    .command("report-fn <recipe-id>")
+    .description("File a false-negative report against an existing recipe (something got through that the recipe should have caught)")
+    .option("--summary <text>", "Human-readable description of what happened (required; pipe via stdin alternatively)")
+    .option("--evidence <text>", "Optional raw payload / log excerpt")
+    .option("--agent <id>", "Optional. Your agent id when the report concerns a specific agent")
+    .option("--checkpoint <id>", "Optional. Related integrity_checkpoints id (helps the reviewer correlate)")
+    .option("--json", "Output JSON")
+    .action(async (recipeId, options) => {
+    try {
+        await recipesReportFnCommand(recipeId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+recipesCmd
+    .command("report-fp <recipe-id>")
+    .description("File a false-positive report against an existing recipe (the recipe fired on legitimate behaviour)")
+    .option("--summary <text>", "Human-readable description of what happened (required; pipe via stdin alternatively)")
+    .option("--evidence <text>", "Optional raw payload / log excerpt")
+    .option("--agent <id>", "Optional. Your agent id when the report concerns a specific agent")
+    .option("--checkpoint <id>", "Optional. Related integrity_checkpoints id (helps the reviewer correlate)")
+    .option("--json", "Output JSON")
+    .action(async (recipeId, options) => {
+    try {
+        await recipesReportFpCommand(recipeId, options);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        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();

package/dist/lib/api.d.ts

@@ -18,7 +18,7 @@ export interface Agent {
     created_at: string;
 }
 /**
- * Per docs.mnemom.ai/api-reference/openapi.json#components/schemas/IntegrityScore:
+ * Per api.mnemom.ai/openapi.json#components/schemas/IntegrityScore:
  *
  *   { agent_id, total_traces, verified_traces, violation_count, integrity_score }
  *
@@ -344,7 +344,7 @@ export declare function testPolicyHistorical(agentId: string, policyJson: Record
     agent_id: string;
     policy_name: string;
     total_traces: number;
-    results: any[];
+    results: unknown[];
     summary: {
         pass: number;
         warn: number;
@@ -828,4 +828,18 @@ export declare function rotateApiKey(keyId: string): Promise<ApiKeyCreated>;
  * audit; `is_active` flips to false and `revoked_at` is timestamped.
  */
 export declare function revokeApiKey(keyId: string): Promise<void>;
+export interface RecipeReportInput {
+    type: "fn" | "fp";
+    summary: string;
+    evidence?: string;
+    agent_id?: string;
+    checkpoint_id?: string;
+}
+export interface RecipeReportResult {
+    ok: true;
+    candidate_id: string;
+    type: "fn" | "fp";
+    related_recipe_id: string;
+}
+export declare function reportRecipeFnFp(recipeId: string, input: RecipeReportInput): Promise<RecipeReportResult>;
 export {};

package/dist/lib/api.js

@@ -1260,11 +1260,7 @@ export const API_KEY_SCOPES = [
     "admin:org",
     "admin:platform",
 ];
-export const DEFAULT_API_KEY_SCOPES = [
-    "gateway",
-    "api:read",
-    "api:write",
-];
+export const DEFAULT_API_KEY_SCOPES = ["gateway", "api:read", "api:write"];
 /**
  * Recognize legacy two-scope sets so the CLI can annotate pre-ADR-049
  * keys appropriately. Mirror of mnemom-api `expandLegacyScopes` logic
@@ -1370,3 +1366,6 @@ export async function revokeApiKey(keyId) {
         throw new Error(`Failed to revoke api key: ${response.status} ${body}`);
     }
 }
+export async function reportRecipeFnFp(recipeId, input) {
+    return postApi(`/v1/recipes/${encodeURIComponent(recipeId)}/report`, input);
+}