@mnemom/mnemom 0.8.0 → 0.9.0

package/dist/commands/integrity.js

@@ -6,15 +6,16 @@ export async function integrityCommand(agentName) {
     console.log("\nFetching integrity score...\n");
     try {
         const integrity = await getIntegrity(agentId);
-        const scorePercent = (integrity.score * 100).toFixed(1);
-        const scoreBar = generateScoreBar(integrity.score);
+        // Field names match the docs.mnemom.ai canonical IntegrityScore schema:
+        // integrity_score (in [0,1]), total_traces, verified_traces, violation_count.
+        const scorePercent = (integrity.integrity_score * 100).toFixed(1);
+        const scoreBar = generateScoreBar(integrity.integrity_score);
         console.log(fmt.header("Integrity Score"));
         console.log(`  ${fmt.label("Score:     ", `${scorePercent}% ${scoreBar}`)}`);
         console.log(`  ${fmt.label("Total:     ", `${integrity.total_traces} traces`)}`);
-        console.log(`  ${fmt.label("Verified:  ", `${integrity.verified}`)} ${fmt.success("")}`);
-        console.log(`  ${fmt.label("Violations:", ` ${integrity.violations}`)} ${fmt.error("")}`);
-        console.log(`  ${fmt.label("Updated:   ", integrity.last_updated)}`);
-        if (integrity.violations > 0) {
+        console.log(`  ${fmt.label("Verified:  ", `${integrity.verified_traces}`)}`);
+        console.log(`  ${fmt.label("Violations:", ` ${integrity.violation_count}`)}`);
+        if (integrity.violation_count > 0) {
             console.log("\n" + fmt.warn("You have integrity violations. Run `mnemom logs` to investigate.") + "\n");
         }
         else if (integrity.total_traces === 0) {

package/dist/commands/protection.d.ts

@@ -4,11 +4,19 @@ export interface ValidationCheck {
     message: string;
 }
 /**
- * Validate a protection card object.
- * Schema: mode, thresholds, screen_surfaces, trusted_sources
+ * Validate a protection card against ADR-037 canonical form.
+ *
+ * Required: card_version, agent_id, mode (off|observe|nudge|enforce).
+ * Optional: thresholds (warn ≤ quarantine ≤ block, all in [0,1]),
+ *           screen_surfaces (object of bools with the four named keys),
+ *           trusted_sources (object of typed buckets, per-bucket deny-lists).
  */
 export declare function validateProtectionCard(card: Record<string, unknown>): ValidationCheck[];
 export declare function protectionShowCommand(agentName?: string): Promise<void>;
-export declare function protectionPublishCommand(file: string, agentName?: string): Promise<void>;
+export declare function protectionPublishCommand(file: string, agentName?: string, options?: {
+    idempotencyKey?: string;
+}): Promise<void>;
 export declare function protectionValidateCommand(file: string): Promise<void>;
-export declare function protectionEditCommand(agentName?: string): Promise<void>;
+export declare function protectionEditCommand(agentName?: string, options?: {
+    idempotencyKey?: string;
+}): Promise<void>;

package/dist/commands/protection.js

@@ -3,76 +3,283 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { spawnSync } from "node:child_process";
 import yaml from "js-yaml";
-import { getProtectionCard, putProtectionCard, resolveAgentId, } from "../lib/api.js";
+import { PROTECTION_CARD_MAX_BYTES, getProtectionCard, putProtectionCard, resolveAgentId, } from "../lib/api.js";
 import { requireAuth } from "../lib/auth.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
-const VALID_MODES = new Set(["observe", "warn", "block"]);
+const PROTECTION_MODES = ["off", "observe", "nudge", "enforce"];
+const SURFACE_KEYS = ["incoming", "outgoing", "tool_calls", "tool_responses"];
+// Per ADR-037 Decision 4: deny public LLM endpoints + public DNS providers,
+// and the any-host CIDRs, at write time.
+const DENY_DOMAINS = new Set([
+    "api.openai.com",
+    "api.anthropic.com",
+    "generativelanguage.googleapis.com",
+    "api.cohere.ai",
+    "api.mistral.ai",
+    "api.groq.com",
+    "cloud.google.com",
+    "dns.google",
+    "cloudflare-dns.com",
+    "one.one.one.one",
+    "dns.quad9.net",
+]);
+const DENY_IP_PREFIXES = [
+    "0.0.0.0/0",
+    "::/0",
+    "8.8.8.0/24",
+    "8.8.4.0/24",
+    "1.1.1.0/24",
+    "1.0.0.0/24",
+    "9.9.9.0/24",
+];
+const DOMAIN_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+(:\d{1,5})?$/i;
+const AGENT_ID_RE = /^mnm-[a-z0-9-]{4,}$/i;
+const CIDR_RE = /^([0-9]{1,3}(\.[0-9]{1,3}){3})\/([0-9]|[12][0-9]|3[0-2])$|^([0-9a-f:]+)\/(\d{1,3})$/i;
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function validateDomain(d) {
+    const lower = d.toLowerCase();
+    if (DENY_DOMAINS.has(lower.split(":")[0])) {
+        return "domain is on the static deny-list (public LLM/DNS endpoint)";
+    }
+    if (!DOMAIN_RE.test(lower))
+        return "not a valid DNS name (or host:port)";
+    return null;
+}
+function validateAgentId(a) {
+    if (!AGENT_ID_RE.test(a))
+        return "must match Mnemom agent ID format (mnm-*)";
+    return null;
+}
+function validateCidr(c) {
+    if (DENY_IP_PREFIXES.includes(c)) {
+        return "CIDR is on the static deny-list (public DNS / 0.0.0.0/0 / ::/0)";
+    }
+    if (!CIDR_RE.test(c))
+        return "not a valid CIDR notation";
+    return null;
+}
+function validateTrustedBucket(name, bucket, checks, perEntry) {
+    if (bucket === undefined)
+        return;
+    if (!Array.isArray(bucket)) {
+        checks.push({
+            name: `trusted_sources.${name}`,
+            passed: false,
+            message: `Must be an array of strings (got ${typeof bucket}). Per ADR-037 trusted_sources is an object of typed buckets — not an array of objects.`,
+        });
+        return;
+    }
+    let bad = 0;
+    bucket.forEach((entry, i) => {
+        if (typeof entry !== "string") {
+            checks.push({
+                name: `trusted_sources.${name}[${i}]`,
+                passed: false,
+                message: "Must be a string",
+            });
+            bad++;
+            return;
+        }
+        const err = perEntry(entry);
+        if (err) {
+            checks.push({
+                name: `trusted_sources.${name}[${i}]`,
+                passed: false,
+                message: `${entry}: ${err}`,
+            });
+            bad++;
+        }
+    });
+    if (bad === 0) {
+        checks.push({
+            name: `trusted_sources.${name}`,
+            passed: true,
+            message: `${bucket.length} entr${bucket.length === 1 ? "y" : "ies"}`,
+        });
+    }
+}
 /**
- * Validate a protection card object.
- * Schema: mode, thresholds, screen_surfaces, trusted_sources
+ * Validate a protection card against ADR-037 canonical form.
+ *
+ * Required: card_version, agent_id, mode (off|observe|nudge|enforce).
+ * Optional: thresholds (warn ≤ quarantine ≤ block, all in [0,1]),
+ *           screen_surfaces (object of bools with the four named keys),
+ *           trusted_sources (object of typed buckets, per-bucket deny-lists).
  */
 export function validateProtectionCard(card) {
     const checks = [];
-    // mode: required, must be observe | warn | block
-    const mode = card.mode;
-    if (typeof mode === "string" && VALID_MODES.has(mode)) {
-        checks.push({ name: "mode", passed: true, message: mode });
+    // ── card_version (required) ──
+    if (typeof card.card_version !== "string" || card.card_version.length === 0) {
+        checks.push({
+            name: "card_version",
+            passed: false,
+            message: 'Required (string, e.g. "protection/2026-04-26"). See ADR-037.',
+        });
+    }
+    else {
+        checks.push({ name: "card_version", passed: true, message: card.card_version });
+    }
+    // ── agent_id (required) ──
+    if (typeof card.agent_id !== "string" || card.agent_id.length === 0) {
+        checks.push({
+            name: "agent_id",
+            passed: false,
+            message: "Required (string).",
+        });
+    }
+    else {
+        checks.push({ name: "agent_id", passed: true, message: card.agent_id });
     }
-    else if (mode === undefined) {
-        checks.push({ name: "mode", passed: false, message: "Required (observe | warn | block)" });
+    // ── mode (required, ADR-037 canonical enum) ──
+    const mode = card.mode;
+    if (typeof mode !== "string") {
+        checks.push({
+            name: "mode",
+            passed: false,
+            message: `Required. Must be one of: ${PROTECTION_MODES.join(" | ")}. Per ADR-037 the legacy "block"/"warn" values are no longer accepted.`,
+        });
+    }
+    else if (!PROTECTION_MODES.includes(mode)) {
+        checks.push({
+            name: "mode",
+            passed: false,
+            message: `Invalid: "${mode}". Must be one of: ${PROTECTION_MODES.join(" | ")}. (Per ADR-037 the legacy "block"/"warn" values are no longer accepted; use "enforce"/"nudge".)`,
+        });
     }
     else {
-        checks.push({ name: "mode", passed: false, message: `Invalid: "${mode}". Must be observe | warn | block` });
+        checks.push({ name: "mode", passed: true, message: mode });
     }
-    // thresholds: optional, if present must have warn/quarantine/block in ascending order (0-1)
-    const thresholds = card.thresholds;
-    if (thresholds !== undefined) {
-        if (typeof thresholds !== "object" || thresholds === null) {
-            checks.push({ name: "thresholds", passed: false, message: "Must be an object" });
+    // ── thresholds (optional) ──
+    if (card.thresholds !== undefined) {
+        if (!isObject(card.thresholds)) {
+            checks.push({ name: "thresholds", passed: false, message: "Must be an object if present" });
         }
         else {
-            const w = thresholds.warn;
-            const q = thresholds.quarantine;
-            const b = thresholds.block;
-            if (w === undefined || q === undefined || b === undefined) {
-                checks.push({ name: "thresholds", passed: false, message: "Must have warn, quarantine, and block fields" });
+            const t = card.thresholds;
+            const nums = {};
+            let bad = false;
+            for (const key of ["warn", "quarantine", "block"]) {
+                const v = t[key];
+                if (v === undefined) {
+                    checks.push({
+                        name: `thresholds.${key}`,
+                        passed: false,
+                        message: "Required when thresholds is present",
+                    });
+                    bad = true;
+                    continue;
+                }
+                if (typeof v !== "number" || v < 0 || v > 1 || Number.isNaN(v)) {
+                    checks.push({
+                        name: `thresholds.${key}`,
+                        passed: false,
+                        message: "Must be a number in [0, 1]",
+                    });
+                    bad = true;
+                    continue;
+                }
+                nums[key] = v;
             }
-            else if (typeof w !== "number" || typeof q !== "number" || typeof b !== "number") {
-                checks.push({ name: "thresholds", passed: false, message: "Values must be numbers" });
+            if (nums.warn !== undefined && nums.quarantine !== undefined && nums.warn > nums.quarantine) {
+                checks.push({
+                    name: "thresholds.warn",
+                    passed: false,
+                    message: `Must be ≤ thresholds.quarantine (warn=${nums.warn} > quarantine=${nums.quarantine})`,
+                });
+                bad = true;
             }
-            else if (w < 0 || w > 1 || q < 0 || q > 1 || b < 0 || b > 1) {
-                checks.push({ name: "thresholds", passed: false, message: "Values must be between 0 and 1" });
+            if (nums.quarantine !== undefined && nums.block !== undefined && nums.quarantine > nums.block) {
+                checks.push({
+                    name: "thresholds.quarantine",
+                    passed: false,
+                    message: `Must be ≤ thresholds.block (quarantine=${nums.quarantine} > block=${nums.block})`,
+                });
+                bad = true;
             }
-            else if (!(w <= q && q <= b)) {
-                checks.push({ name: "thresholds", passed: false, message: `Must be in ascending order (warn=${w} <= quarantine=${q} <= block=${b})` });
-            }
-            else {
-                checks.push({ name: "thresholds", passed: true, message: `warn=${w}, quarantine=${q}, block=${b}` });
+            if (!bad) {
+                checks.push({
+                    name: "thresholds",
+                    passed: true,
+                    message: `warn=${nums.warn}, quarantine=${nums.quarantine}, block=${nums.block}`,
+                });
             }
         }
     }
-    // screen_surfaces: optional, array of strings
-    const surfaces = card.screen_surfaces;
-    if (surfaces !== undefined) {
-        if (!Array.isArray(surfaces)) {
-            checks.push({ name: "screen_surfaces", passed: false, message: "Must be an array" });
+    // ── screen_surfaces (optional, object of bools) ──
+    if (card.screen_surfaces !== undefined) {
+        if (Array.isArray(card.screen_surfaces)) {
+            checks.push({
+                name: "screen_surfaces",
+                passed: false,
+                message: 'Must be an object of booleans, not an array. Per ADR-037 use { incoming: true, outgoing: true, tool_calls: true, tool_responses: true }.',
+            });
         }
-        else if (surfaces.some((s) => typeof s !== "string")) {
-            checks.push({ name: "screen_surfaces", passed: false, message: "All entries must be strings" });
+        else if (!isObject(card.screen_surfaces)) {
+            checks.push({ name: "screen_surfaces", passed: false, message: "Must be an object if present" });
         }
         else {
-            checks.push({ name: "screen_surfaces", passed: true, message: `${surfaces.length} surface(s)` });
+            const s = card.screen_surfaces;
+            let bad = false;
+            for (const key of SURFACE_KEYS) {
+                const v = s[key];
+                if (v !== undefined && typeof v !== "boolean") {
+                    checks.push({
+                        name: `screen_surfaces.${key}`,
+                        passed: false,
+                        message: "Must be a boolean",
+                    });
+                    bad = true;
+                }
+            }
+            for (const key of Object.keys(s)) {
+                if (!SURFACE_KEYS.includes(key)) {
+                    checks.push({
+                        name: `screen_surfaces.${key}`,
+                        passed: false,
+                        message: `Unknown surface (allowed: ${SURFACE_KEYS.join(", ")})`,
+                    });
+                    bad = true;
+                }
+            }
+            if (!bad) {
+                const enabled = SURFACE_KEYS.filter(k => s[k] === true).length;
+                checks.push({
+                    name: "screen_surfaces",
+                    passed: true,
+                    message: `${enabled}/${SURFACE_KEYS.length} surfaces enabled`,
+                });
+            }
         }
     }
-    // trusted_sources: optional, array of objects
-    const trusted = card.trusted_sources;
-    if (trusted !== undefined) {
-        if (!Array.isArray(trusted)) {
-            checks.push({ name: "trusted_sources", passed: false, message: "Must be an array" });
+    // ── trusted_sources (optional, typed buckets) ──
+    if (card.trusted_sources !== undefined) {
+        if (Array.isArray(card.trusted_sources)) {
+            checks.push({
+                name: "trusted_sources",
+                passed: false,
+                message: 'Must be an object of typed buckets, not an array. Per ADR-037 use { domains: [...], agent_ids: [...], ip_ranges: [...] } — the legacy [{pattern, ...}] shape is no longer accepted.',
+            });
+        }
+        else if (!isObject(card.trusted_sources)) {
+            checks.push({ name: "trusted_sources", passed: false, message: "Must be an object if present" });
         }
         else {
-            checks.push({ name: "trusted_sources", passed: true, message: `${trusted.length} source(s)` });
+            const ts = card.trusted_sources;
+            validateTrustedBucket("domains", ts.domains, checks, validateDomain);
+            validateTrustedBucket("agent_ids", ts.agent_ids, checks, validateAgentId);
+            validateTrustedBucket("ip_ranges", ts.ip_ranges, checks, validateCidr);
+            for (const key of Object.keys(ts)) {
+                if (!["domains", "agent_ids", "ip_ranges"].includes(key)) {
+                    checks.push({
+                        name: `trusted_sources.${key}`,
+                        passed: false,
+                        message: "Unknown bucket (allowed: domains, agent_ids, ip_ranges)",
+                    });
+                }
+            }
         }
     }
     return checks;
@@ -125,7 +332,7 @@ export async function protectionShowCommand(agentName) {
         process.exit(1);
     }
 }
-export async function protectionPublishCommand(file, agentName) {
+export async function protectionPublishCommand(file, agentName, options = {}) {
     const agentId = await resolveAgentId(agentName);
     const filePath = path.resolve(file);
     if (!fs.existsSync(filePath)) {
@@ -172,11 +379,19 @@ export async function protectionPublishCommand(file, agentName) {
         console.log("\nPublishing protection card...");
         const contentType = parsed.format === "yaml" ? "text/yaml" : "application/json";
         const body = parsed.format === "yaml" ? parsed.raw : JSON.stringify(parsed.parsed);
-        const result = await putProtectionCard(agentId, body, contentType);
+        const bodyBytes = Buffer.byteLength(body, "utf-8");
+        if (bodyBytes > PROTECTION_CARD_MAX_BYTES) {
+            console.log("\n" +
+                fmt.error(`Protection card is ${bodyBytes} bytes; limit is ${PROTECTION_CARD_MAX_BYTES} bytes (64 KB). The API will return 413.`) +
+                "\n");
+            process.exit(1);
+        }
+        const result = await putProtectionCard(agentId, body, contentType, {
+            idempotencyKey: options.idempotencyKey,
+        });
         console.log(fmt.success("Protection card published!"));
-        console.log(fmt.label("  Card ID:", ` ${result.card_id}`));
-        if (result.composed) {
-            console.log(fmt.success("Canonical protection card recomposed"));
+        if (typeof result.card_id === "string" && result.card_id.length > 0) {
+            console.log(fmt.label("  Card ID:", ` ${result.card_id}`));
         }
         console.log();
     }
@@ -227,7 +442,7 @@ export async function protectionValidateCommand(file) {
         process.exit(1);
     }
 }
-export async function protectionEditCommand(agentName) {
+export async function protectionEditCommand(agentName, options = {}) {
     const agentId = await resolveAgentId(agentName);
     await requireAuth();
     console.log("\nFetching current protection card...\n");
@@ -236,10 +451,17 @@ export async function protectionEditCommand(agentName) {
         console.log(fmt.warn("No protection card found. Creating a template..."));
     }
     const cardYaml = original || yaml.dump({
+        card_version: "protection/2026-04-26",
+        agent_id: agentId,
         mode: "observe",
         thresholds: { warn: 0.3, quarantine: 0.6, block: 0.9 },
-        screen_surfaces: ["system_prompt", "tool_input", "tool_output"],
-        trusted_sources: [],
+        screen_surfaces: {
+            incoming: true,
+            outgoing: true,
+            tool_calls: true,
+            tool_responses: true,
+        },
+        trusted_sources: { domains: [], agent_ids: [], ip_ranges: [] },
     }, { lineWidth: 120, noRefs: true });
     const tmpDir = os.tmpdir();
     const tmpFile = path.join(tmpDir, `mnemom-protection-${agentId}.yaml`);
@@ -296,9 +518,21 @@ export async function protectionEditCommand(agentName) {
     }
     try {
         console.log("\nPublishing protection card...");
-        const putResult = await putProtectionCard(agentId, edited, "text/yaml");
+        const editedBytes = Buffer.byteLength(edited, "utf-8");
+        if (editedBytes > PROTECTION_CARD_MAX_BYTES) {
+            console.log("\n" +
+                fmt.error(`Protection card is ${editedBytes} bytes; limit is ${PROTECTION_CARD_MAX_BYTES} bytes (64 KB). The API will return 413.`) +
+                "\n");
+            process.exit(1);
+        }
+        const putResult = await putProtectionCard(agentId, edited, "text/yaml", {
+            idempotencyKey: options.idempotencyKey,
+        });
         console.log(fmt.success("Protection card published!"));
-        console.log(fmt.label("  Card ID:", ` ${putResult.card_id}`) + "\n");
+        if (typeof putResult.card_id === "string" && putResult.card_id.length > 0) {
+            console.log(fmt.label("  Card ID:", ` ${putResult.card_id}`));
+        }
+        console.log();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/commands/status.js

@@ -331,12 +331,14 @@ async function showTraceSummary(agentId) {
         console.log();
         if (integrityResult.status === "fulfilled") {
             const integrity = integrityResult.value;
-            const score = (integrity.score * 100).toFixed(1);
+            // Field names per docs.mnemom.ai IntegrityScore: integrity_score
+            // (in [0,1]), verified_traces, violation_count.
+            const score = (integrity.integrity_score * 100).toFixed(1);
             console.log(`Integrity Score: ${score}%`);
             console.log(`Total Traces:    ${integrity.total_traces}`);
-            console.log(`Verified:        ${integrity.verified}`);
-            if (integrity.violations > 0) {
-                console.log(`Violations:      ${integrity.violations}`);
+            console.log(`Verified:        ${integrity.verified_traces}`);
+            if (integrity.violation_count > 0) {
+                console.log(`Violations:      ${integrity.violation_count}`);
             }
         }
         else {

package/dist/index.js

@@ -116,10 +116,11 @@ cardCmd
 cardCmd
     .command("edit")
     .description("Edit alignment card in $EDITOR")
-    .action(async () => {
+    .option("--idempotency-key <uuid>", "Reuse a specific Idempotency-Key (for retries; default: auto)")
+    .action(async (subOpts) => {
     try {
         const opts = program.opts();
-        await cardEditCommand(opts.agent);
+        await cardEditCommand(opts.agent, { idempotencyKey: subOpts.idempotencyKey });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -130,10 +131,11 @@ cardCmd
     .command("publish")
     .argument("<file>", "Path to alignment card file (YAML or JSON)")
     .description("Publish alignment card")
-    .action(async (file) => {
+    .option("--idempotency-key <uuid>", "Reuse a specific Idempotency-Key (for retries; default: auto)")
+    .action(async (file, subOpts) => {
     try {
         const opts = program.opts();
-        await cardPublishCommand(file, opts.agent);
+        await cardPublishCommand(file, opts.agent, { idempotencyKey: subOpts.idempotencyKey });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -191,10 +193,11 @@ protectionCmd
 protectionCmd
     .command("edit")
     .description("Edit protection card in $EDITOR")
-    .action(async () => {
+    .option("--idempotency-key <uuid>", "Reuse a specific Idempotency-Key (for retries; default: auto)")
+    .action(async (subOpts) => {
     try {
         const opts = program.opts();
-        await protectionEditCommand(opts.agent);
+        await protectionEditCommand(opts.agent, { idempotencyKey: subOpts.idempotencyKey });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);
@@ -205,10 +208,11 @@ protectionCmd
     .command("publish")
     .argument("<file>", "Path to protection card file (YAML or JSON)")
     .description("Publish protection card")
-    .action(async (file) => {
+    .option("--idempotency-key <uuid>", "Reuse a specific Idempotency-Key (for retries; default: auto)")
+    .action(async (file, subOpts) => {
     try {
         const opts = program.opts();
-        await protectionPublishCommand(file, opts.agent);
+        await protectionPublishCommand(file, opts.agent, { idempotencyKey: subOpts.idempotencyKey });
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);