@xultrax-web/agent-memory-mcp 0.11.1 → 0.11.3

package/README.md

@@ -43,11 +43,64 @@ Companion file targets (v0.11.1):
 
 Set `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project` to auto-regenerate all companions on every rule save.
 
-Roadmap for the v0.11.x series:
+### `check_action` · the protocol enforcement point (v0.11.3)
 
-- Compliance Receipts (Macaroon-style HMAC tokens · protocol-level enforcement of our own destructive tools)
-- `check_action` tool (deterministic rule matching · optional Sampling enrichment where clients support it)
-- `audit` command (rule conflicts · staleness · receipt-denial log)
+```bash
+# Agent proposes an action · server matches against rule store
+agent-memory check-action "delete the memory called old-project-notes" --type deletions
+
+# → On approval: returns a Compliance Receipt the agent passes back to destructive tools
+# → On deny: returns structured hard_violations + soft_warnings
+```
+
+MCP shape:
+
+```jsonc
+{
+  "name": "check_action",
+  "arguments": {
+    "action": "delete the memory called old-project-notes",
+    "action_type": "deletions",
+    "session_id": "sess_abc",
+  },
+}
+```
+
+Tier 1 (deterministic, every client): action is matched against `rule.matches` regexes, filtered by `rule.enforce_on` categories. Hard violations block; soft violations warn. Approved actions get a fresh receipt with 60s TTL.
+
+Tier 2 (Sampling-enriched LLM judgment on `rule.applies_when`) lands in v0.11.3.x for clients that support Sampling.
+
+**Receipt-gated delete_memory:** v0.11.3 accepts an optional `receipt` argument on `delete_memory`. Pass a receipt with `{type: 'action_type', value: 'deletions'}` and the delete validates against the rule store. v0.12 will make this required.
+
+### Compliance Receipts (v0.11.2 · primitive · tool wiring in v0.11.3)
+
+Receipts are short-lived, HMAC-signed bearer tokens with caveats (Macaroon pattern · [Birgisson et al., NDSS 2014](https://research.google/pubs/pub41892/)). The novel protocol primitive in agent-memory-mcp: server-issued tokens that bind to action + session + rules-version-hash + expiry. Tampering breaks the HMAC. Rule changes invalidate stale receipts (because `rules_version` is part of the signed payload).
+
+```typescript
+import { issueReceipt, validateReceipt } from "@xultrax-web/agent-memory-mcp";
+
+// Server-internal: issue a receipt for a destructive action
+const r = issueReceipt({
+  caveats: [
+    { type: "action", value: "delete_memory" },
+    { type: "session", value: "sess_abc123" },
+  ],
+  ttl_seconds: 60,
+});
+
+// Later: validate before executing the destructive op
+const v = validateReceipt(r, {
+  required_caveats: [{ type: "action", value: "delete_memory" }],
+});
+if (!v.valid) throw new Error(v.reason);
+```
+
+HMAC key lives at `<MEMORY_DIR>/.keyring/hmac-key` · 32 random bytes · mode `0600`. v0.11.3 wires receipts into `delete_memory` + other destructive tools and adds the `check_action` MCP tool.
+
+### Roadmap for the v0.11.x series:
+
+- `check_action` tool · deterministic rule matching · optional Sampling enrichment where clients support it · issues Compliance Receipts when proposed action passes
+- `audit` command · rule conflicts · staleness · receipt-denial log
 
 ---
 

package/dist/index.js

@@ -27,6 +27,7 @@ import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema
 import Fuse from "fuse.js";
 import matter from "gray-matter";
 import { spawnSync } from "node:child_process";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -602,6 +603,27 @@ export function toolDeleteMemory(args) {
     const fp = memoryFilePath(name);
     if (!existsSync(fp))
         return `Memory "${name}" not found.`;
+    // v0.11.3 · receipt-gated path. If a receipt is supplied, validate it
+    // against the current rule set + required caveats. If validation fails,
+    // refuse the delete with a clear reason. If no receipt is supplied,
+    // proceed (back-compat) but log so audit can surface the gap. v0.12
+    // will require receipts unconditionally for destructive ops.
+    const receipt = parseReceiptArg(args.receipt);
+    if (receipt) {
+        const v = validateReceipt(receipt, {
+            required_caveats: [{ type: "action_type", value: "deletions" }],
+        });
+        if (!v.valid) {
+            logEvent("delete_denied", { name, reason: v.reason, receipt_id: receipt.id });
+            throw new Error(`delete_memory refused · receipt invalid (${v.reason}). ` +
+                `Call check_action({action: 'delete memory ${name}', action_type: 'deletions'}) ` +
+                `to get a fresh receipt.`);
+        }
+        logEvent("delete_approved_via_receipt", { name, receipt_id: receipt.id });
+    }
+    else {
+        logEvent("delete_without_receipt", { name });
+    }
     return withLock(() => {
         ensureTrash();
         // Trash filename: <unix-ms>-<name>.md so restore can pick the
@@ -610,9 +632,12 @@ export function toolDeleteMemory(args) {
         const trashPath = join(TRASH_DIR, `${ts}-${name}.md`);
         renameSync(fp, trashPath);
         removeIndexEntryUnlocked(name);
-        logEvent("delete", { name, trash: `${ts}-${name}.md` });
+        logEvent("delete", { name, trash: `${ts}-${name}.md`, gated: !!receipt });
         log("debug", "delete_memory", { name });
-        return `Moved "${name}" to trash. Restore with: agent-memory restore ${name}`;
+        const gateMsg = receipt
+            ? ` (gated by receipt ${receipt.id})`
+            : " (no receipt · v0.11.3 back-compat path)";
+        return `Moved "${name}" to trash${gateMsg}. Restore with: agent-memory restore ${name}`;
     });
 }
 function toolRestoreMemory(args) {
@@ -1270,6 +1295,271 @@ function toolSaveRule(args) {
     });
 }
 // -------------------------------------------------------------
+// Compliance Receipts · v0.11.2 · the novel protocol primitive
+// -------------------------------------------------------------
+//
+// Receipts are short-lived, HMAC-signed bearer tokens with caveats
+// (attenuations). Macaroon-style. Issued by `check_action` (v0.11.3),
+// validated before our own destructive tools execute. Prior art:
+//
+//   Birgisson et al · "Macaroons: Cookies with Contextual Caveats for
+//   Decentralized Authorization in the Cloud" · Google Research,
+//   NDSS 2014 · https://research.google/pubs/pub41892/
+//
+// Why receipts work where MCP Sampling doesn't:
+//   - MCP Sampling is unsupported on Claude Code / Cursor / Cline /
+//     Codex CLI (the primary coding clients) per the MCP client matrix.
+//   - Receipts are server-issued protocol artifacts — they work on every
+//     client because the server controls both ends (issue + validate).
+//   - Receipts bind to: action + session + rules-version-hash + expiry.
+//     Tampering breaks the HMAC. Rule changes invalidate stale receipts.
+//
+// Storage:
+//   HMAC key lives at <MEMORY_DIR>/.keyring/hmac-key · 32 random bytes
+//   created on first use with mode 0o600 (owner read/write only).
+//   Caller-rotatable via `agent-memory rotate-key` (a v0.11.x follow-up).
+//
+// v0.11.2 ships the PRIMITIVE only — issuance + validation +
+// canonicalization. Tool wiring (delete_memory + check_action) lands
+// in v0.11.3.
+const KEYRING_DIR = join(MEMORY_DIR, ".keyring");
+const HMAC_KEY_FILE = join(KEYRING_DIR, "hmac-key");
+const RECEIPT_DEFAULT_TTL_SECONDS = 60;
+function loadOrCreateHmacKey() {
+    if (existsSync(HMAC_KEY_FILE)) {
+        return readFileSync(HMAC_KEY_FILE);
+    }
+    if (!existsSync(KEYRING_DIR)) {
+        mkdirSync(KEYRING_DIR, { recursive: true });
+    }
+    const key = randomBytes(32); // 256 bits · plenty for HMAC-SHA256
+    // mode 0o600 is owner-only on POSIX; Windows ignores mode but ACLs
+    // default to the user, so practically equivalent for our threat model.
+    writeFileSync(HMAC_KEY_FILE, key, { mode: 0o600 });
+    return key;
+}
+/**
+ * Compute the rules-version hash · first 16 hex chars of SHA-256 over
+ * the concatenated bytes of every type=rule memory file, in sorted
+ * filename order. Any rule add / edit / remove changes this hash,
+ * which invalidates outstanding receipts (they were issued against a
+ * different rule set).
+ */
+function computeRulesVersion() {
+    const rules = loadAllRules();
+    const sortedPaths = rules.map((r) => r.filePath).sort();
+    const hash = createHash("sha256");
+    for (const fp of sortedPaths) {
+        try {
+            hash.update(readFileSync(fp));
+        }
+        catch {
+            // File disappeared between listMemoryFiles + read; skip it.
+            // Next computation will reflect the change.
+        }
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+/**
+ * Deterministic canonical form for HMAC input · caveats sorted by
+ * (type, value) so the order in which the caller listed them doesn't
+ * change the signature. JSON with no whitespace (single line) so the
+ * exact byte sequence is reproducible across platforms.
+ */
+function canonicalizeReceipt(r) {
+    const sortedCaveats = [...r.caveats].sort((a, b) => a.type === b.type ? a.value.localeCompare(b.value) : a.type.localeCompare(b.type));
+    return JSON.stringify({
+        id: r.id,
+        issued_at: r.issued_at,
+        expires_at: r.expires_at,
+        rules_version: r.rules_version,
+        caveats: sortedCaveats,
+    });
+}
+function signReceipt(r) {
+    const key = loadOrCreateHmacKey();
+    return createHmac("sha256", key).update(canonicalizeReceipt(r)).digest("hex");
+}
+/**
+ * Issue a fresh Compliance Receipt with the given caveats. The receipt
+ * is bound to the current rule-store hash; any rule edit invalidates it.
+ */
+export function issueReceipt(opts) {
+    const now = Math.floor(Date.now() / 1000);
+    const ttl = Math.max(1, opts.ttl_seconds ?? RECEIPT_DEFAULT_TTL_SECONDS);
+    const base = {
+        id: "rcpt_" + randomBytes(8).toString("hex"),
+        issued_at: now,
+        expires_at: now + ttl,
+        rules_version: computeRulesVersion(),
+        caveats: opts.caveats,
+    };
+    return { ...base, signature: signReceipt(base) };
+}
+/**
+ * Validate a Compliance Receipt against the current rule store + caller's
+ * required caveats. Returns {valid: true} on success, otherwise
+ * {valid: false, reason: <human-readable>}.
+ */
+export function validateReceipt(receipt, opts = {}) {
+    // 1. HMAC verification · constant-time compare to avoid timing leaks.
+    const expected = signReceipt({
+        id: receipt.id,
+        issued_at: receipt.issued_at,
+        expires_at: receipt.expires_at,
+        rules_version: receipt.rules_version,
+        caveats: receipt.caveats,
+    });
+    const expectedBuf = Buffer.from(expected, "hex");
+    const actualBuf = Buffer.from(receipt.signature, "hex");
+    if (expectedBuf.length !== actualBuf.length || !timingSafeEqual(expectedBuf, actualBuf)) {
+        return { valid: false, reason: "invalid signature" };
+    }
+    // 2. Expiry · receipts past their expires_at are dead.
+    const now = Math.floor(Date.now() / 1000);
+    if (now > receipt.expires_at) {
+        return { valid: false, reason: "receipt expired" };
+    }
+    // 3. Rules-version binding · any rule edit since issuance invalidates.
+    const currentRulesVersion = opts.current_rules_version ?? computeRulesVersion();
+    if (receipt.rules_version !== currentRulesVersion) {
+        return {
+            valid: false,
+            reason: `rules changed since receipt issued (was ${receipt.rules_version}, now ${currentRulesVersion})`,
+        };
+    }
+    // 4. Required-caveat check · each required pair must appear on the receipt.
+    if (opts.required_caveats) {
+        for (const required of opts.required_caveats) {
+            const found = receipt.caveats.find((c) => c.type === required.type && c.value === required.value);
+            if (!found) {
+                return {
+                    valid: false,
+                    reason: `missing required caveat: ${required.type}=${required.value}`,
+                };
+            }
+        }
+    }
+    return { valid: true };
+}
+function safeRegex(pattern) {
+    try {
+        return new RegExp(pattern, "i");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Deterministic rule check. For each type=rule memory:
+ *   1. Skip if rule.enforce_on is non-empty and doesn't include actionType.
+ *   2. For each pattern in rule.matches, test against the proposed action.
+ *   3. If any pattern matches → violation entry.
+ * Hard violations block; soft violations warn.
+ */
+export function checkActionAgainstRules(action, actionType) {
+    const rules = loadAllRules();
+    const hard = [];
+    const soft = [];
+    for (const rule of rules) {
+        // Scope filter · if enforce_on is specified, the action's type must be
+        // listed. Empty enforce_on means "applies everywhere".
+        if (rule.enforce_on && rule.enforce_on.length > 0) {
+            if (!rule.enforce_on.includes(actionType))
+                continue;
+        }
+        // No matches array → this rule has no deterministic pattern, only
+        // applies_when (Sampling-only). Skip in Tier 1.
+        if (!rule.matches || rule.matches.length === 0)
+            continue;
+        for (const pat of rule.matches) {
+            const re = safeRegex(pat);
+            if (!re)
+                continue;
+            if (re.test(action)) {
+                const violation = {
+                    rule: rule.name,
+                    severity: rule.severity ?? "soft",
+                    reason: `matched pattern '${pat}' on action of type '${actionType}'`,
+                };
+                if (violation.severity === "hard")
+                    hard.push(violation);
+                else
+                    soft.push(violation);
+                break; // one match per rule is enough
+            }
+        }
+    }
+    return { hard, soft, rules_evaluated: rules.length };
+}
+function toolCheckAction(args) {
+    const action = String(args.action ?? "").trim();
+    const actionType = String(args.action_type ?? "").trim();
+    const sessionId = typeof args.session_id === "string" ? args.session_id.trim() : "";
+    if (!action)
+        throw new Error("action is required (the proposed action description)");
+    if (!actionType)
+        throw new Error("action_type is required (e.g. 'deletions', 'commits', 'file_writes', 'chat_responses')");
+    const { hard, soft, rules_evaluated } = checkActionAgainstRules(action, actionType);
+    if (hard.length > 0) {
+        const result = {
+            approved: false,
+            hard_violations: hard,
+            soft_warnings: soft,
+            rules_evaluated,
+        };
+        logEvent("check_action_denied", {
+            action,
+            action_type: actionType,
+            hard_count: hard.length,
+            soft_count: soft.length,
+        });
+        return JSON.stringify(result, null, 2);
+    }
+    // Approved · issue a receipt that downstream tools can require.
+    const caveats = [
+        { type: "action_type", value: actionType },
+        { type: "action_hash", value: createHash("sha256").update(action).digest("hex").slice(0, 16) },
+    ];
+    if (sessionId)
+        caveats.push({ type: "session", value: sessionId });
+    const receipt = issueReceipt({ caveats });
+    const result = {
+        approved: true,
+        receipt,
+        hard_violations: [],
+        soft_warnings: soft,
+        rules_evaluated,
+    };
+    logEvent("check_action_approved", {
+        action,
+        action_type: actionType,
+        receipt_id: receipt.id,
+        soft_count: soft.length,
+    });
+    return JSON.stringify(result, null, 2);
+}
+/**
+ * Parse a receipt argument · accepts either an already-decoded object or
+ * a JSON string (the form check_action returns when the agent calls it).
+ * Returns null if missing/unparseable.
+ */
+function parseReceiptArg(input) {
+    if (!input)
+        return null;
+    if (typeof input === "object")
+        return input;
+    if (typeof input === "string") {
+        try {
+            return JSON.parse(input);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+// -------------------------------------------------------------
 // Git sync · multi-machine memory via git remote
 // -------------------------------------------------------------
 //
@@ -1591,7 +1881,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.11.1" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.11.3" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -1914,11 +2204,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "delete_memory",
-            description: "Move a memory to .trash/ (soft delete). The file is removed from the index but recoverable via restore_memory until you manually empty .trash/.",
+            description: "Move a memory to .trash/ (soft delete). The file is removed from the index but recoverable via restore_memory until you manually empty .trash/. " +
+                "v0.11.3+ accepts an optional `receipt` argument · pass a Compliance Receipt from check_action({action_type: 'deletions'}) to gate the delete against the rule store. " +
+                "Receipts must carry the caveat {type: 'action_type', value: 'deletions'} or the delete refuses. " +
+                "Receipts not supplied are accepted (back-compat) but logged · v0.12 will require them.",
             inputSchema: {
                 type: "object",
                 properties: {
                     name: { type: "string", description: "The memory's name slug" },
+                    receipt: {
+                        description: "Optional Compliance Receipt (object or JSON string) from check_action. v0.11.3 logs unreceipted deletes but doesn't block them yet.",
+                    },
                 },
                 required: ["name"],
             },
@@ -2087,6 +2383,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "List every active rule memory with severity, scope, and staleness markers (>90 days since last_verified). Use this to audit which rules are currently constraining the agent.",
             inputSchema: { type: "object", properties: {} },
         },
+        {
+            name: "check_action",
+            description: "v0.11.3 · the protocol enforcement point. Pass a proposed action description + its category; the server matches against rule memories (type=rule) and either:\n" +
+                "  - APPROVES: returns a short-lived Compliance Receipt (HMAC-signed, 60s default) the agent can pass to destructive tools (e.g. delete_memory) as proof of compliance.\n" +
+                "  - DENIES: returns structured hard_violations (severity:hard rules that block) and/or soft_warnings (severity:soft rules that warn but allow).\n\n" +
+                "Tier 1 (deterministic) matches the action against rule.matches regexes + rule.enforce_on category filter. Works on every MCP client.\n" +
+                "Tier 2 (Sampling-enriched LLM judgment on rule.applies_when) ships in v0.11.3.x for clients that support Sampling (Claude Desktop, VS Code Copilot).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    action: {
+                        type: "string",
+                        description: "Description of the proposed action. Plain prose · 'delete the memory called X', 'push to main branch', 'commit with message Y', etc.",
+                    },
+                    action_type: {
+                        type: "string",
+                        description: "Action category for rule.enforce_on matching. Examples: 'deletions', 'commits', 'pushes', 'file_writes', 'chat_responses', 'tool_calls'.",
+                    },
+                    session_id: {
+                        type: "string",
+                        description: "Optional session identifier · binds the issued receipt to this session via a caveat.",
+                    },
+                },
+                required: ["action", "action_type"],
+            },
+        },
         {
             name: "emit_companions",
             description: "Regenerate companion rule files from the current rule memories. " +
@@ -2176,6 +2498,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "emit_companions":
                 result = toolEmitCompanions(args);
                 break;
+            case "check_action":
+                result = toolCheckAction(args);
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -2215,6 +2540,7 @@ const CLI_COMMANDS = new Set([
     "save-rule",
     "list-rules",
     "emit-companions",
+    "check-action",
     "ui",
     "import-claude-code",
     "help",
@@ -2460,6 +2786,19 @@ async function cliMain(command, rest) {
                 process.stdout.write(toolEmitCompanions({ out_dir: out, targets }) + "\n");
                 return 0;
             }
+            case "check-action": {
+                const action = positional[0];
+                const actionType = String(flags.type ?? flags["action-type"] ?? "");
+                if (!action || !actionType) {
+                    throw new Error("Usage: agent-memory check-action '<action description>' --type <action_type> [--session <id>]");
+                }
+                process.stdout.write(toolCheckAction({
+                    action,
+                    action_type: actionType,
+                    session_id: flags.session ? String(flags.session) : undefined,
+                }) + "\n");
+                return 0;
+            }
             case "ui": {
                 // Dynamic import so Ink + React only load when the TUI runs,
                 // keeping cold-start fast for MCP server + every other CLI command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xultrax-web/agent-memory-mcp",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "mcpName": "io.github.xultrax-web/agent-memory-mcp",
   "description": "Markdown memory for AI agents. Plain files you can read, edit, grep, and commit. Operator-grade storage with atomic writes, file locking, tags, [[wiki-links]], find_related, git-backed multi-machine sync, and an Ink-based TUI.",
   "type": "module",