@xultrax-web/agent-memory-mcp 0.11.7 → 0.13.0

package/dist/index.js

@@ -27,7 +27,7 @@ import { CallToolRequestSchema, CreateMessageResultSchema, GetPromptRequestSchem
 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 { createHash, createHmac, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign as cryptoSign, timingSafeEqual, verify as cryptoVerify, } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -615,27 +615,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.
+    // v0.12.0 · receipt REQUIRED for delete_memory. The v0.11.x back-compat
+    // path (delete without receipt) is removed. Callers MUST first call
+    // check_action({action_type: 'deletions'}) to obtain a fresh receipt,
+    // then pass it to delete_memory as the `receipt` argument.
     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 });
+    if (!receipt) {
+        logEvent("delete_refused_no_receipt", { name });
+        throw new Error(`delete_memory refused · receipt required (v0.12.0+). ` +
+            `Call check_action({action: 'delete memory ${name}', action_type: 'deletions'}) ` +
+            `first, then pass the issued receipt as the 'receipt' argument to delete_memory.`);
+    }
+    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 });
     return withLock(() => {
         ensureTrash();
         // Trash filename: <unix-ms>-<name>.md so restore can pick the
@@ -644,12 +644,9 @@ export function toolDeleteMemory(args) {
         const trashPath = join(TRASH_DIR, `${ts}-${name}.md`);
         renameSync(fp, trashPath);
         removeIndexEntryUnlocked(name);
-        logEvent("delete", { name, trash: `${ts}-${name}.md`, gated: !!receipt });
+        logEvent("delete", { name, trash: `${ts}-${name}.md`, gated: true });
         log("debug", "delete_memory", { 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}`;
+        return `Moved "${name}" to trash (gated by receipt ${receipt.id}). Restore with: agent-memory restore ${name}`;
     });
 }
 function toolRestoreMemory(args) {
@@ -1336,7 +1333,16 @@ function toolSaveRule(args) {
 // in v0.11.3.
 const KEYRING_DIR = join(MEMORY_DIR, ".keyring");
 const HMAC_KEY_FILE = join(KEYRING_DIR, "hmac-key");
+const ED25519_PRIV_FILE = join(KEYRING_DIR, "ed25519.priv");
+const ED25519_PUB_FILE = join(KEYRING_DIR, "ed25519.pub");
 const RECEIPT_DEFAULT_TTL_SECONDS = 60;
+/**
+ * Signing-mode selector. CRP 1.0 = HMAC-SHA256 with shared symmetric secret.
+ * CRP 1.1 = Ed25519 asymmetric · enables cross-server federation (validators
+ * verify with the issuer's public key, no shared secret needed). Set via
+ * the `CRP_SIGNING_MODE` env var. Default stays `hmac` for back-compat.
+ */
+const CRP_SIGNING_MODE = process.env.CRP_SIGNING_MODE === "ed25519" ? "ed25519" : "hmac";
 function loadOrCreateHmacKey() {
     if (existsSync(HMAC_KEY_FILE)) {
         return readFileSync(HMAC_KEY_FILE);
@@ -1350,6 +1356,39 @@ function loadOrCreateHmacKey() {
     writeFileSync(HMAC_KEY_FILE, key, { mode: 0o600 });
     return key;
 }
+/**
+ * Load or lazily create the Ed25519 keypair for CRP 1.1 receipts. Private
+ * key (PEM, mode 0o600) signs · public key (PEM, mode 0o644) verifies and
+ * can be shared with other MCP servers for federation. The public key
+ * is exportable via the `agent-memory export-pubkey` CLI command.
+ */
+function loadOrCreateEd25519Keys() {
+    if (!existsSync(KEYRING_DIR)) {
+        mkdirSync(KEYRING_DIR, { recursive: true });
+    }
+    if (existsSync(ED25519_PRIV_FILE) && existsSync(ED25519_PUB_FILE)) {
+        return {
+            privateKeyPem: readFileSync(ED25519_PRIV_FILE, "utf8"),
+            publicKeyPem: readFileSync(ED25519_PUB_FILE, "utf8"),
+        };
+    }
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    const privPem = privateKey.export({ format: "pem", type: "pkcs8" });
+    const pubPem = publicKey.export({ format: "pem", type: "spki" });
+    writeFileSync(ED25519_PRIV_FILE, privPem, { mode: 0o600 });
+    writeFileSync(ED25519_PUB_FILE, pubPem, { mode: 0o644 });
+    return { privateKeyPem: privPem, publicKeyPem: pubPem };
+}
+/**
+ * Export the Ed25519 public key (PEM) for sharing with other servers.
+ * Returns null when CRP 1.1 hasn't been initialized yet · the keypair is
+ * created lazily on first Ed25519 receipt issuance.
+ */
+export function exportEd25519PublicKey() {
+    if (!existsSync(ED25519_PUB_FILE))
+        return null;
+    return readFileSync(ED25519_PUB_FILE, "utf8");
+}
 /**
  * Compute the rules-version hash · first 16 hex chars of SHA-256 over
  * the concatenated bytes of every type=rule memory file, in sorted
@@ -1380,21 +1419,70 @@ function computeRulesVersion() {
  */
 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({
+    // Field ordering is significant for the signed canonical form. The
+    // version field is included only when present so v1.0 and v1.1 receipts
+    // produce distinct signatures (preventing version-downgrade attacks).
+    const base = {
         id: r.id,
         issued_at: r.issued_at,
         expires_at: r.expires_at,
         rules_version: r.rules_version,
         caveats: sortedCaveats,
-    });
+    };
+    if (r.version)
+        base.version = r.version;
+    return JSON.stringify(base);
 }
 function signReceipt(r) {
+    const canonical = canonicalizeReceipt(r);
+    if (r.version === "1.1") {
+        const { privateKeyPem } = loadOrCreateEd25519Keys();
+        const privKey = createPrivateKey(privateKeyPem);
+        // Ed25519 signs the raw bytes directly (no separate digest); pass null
+        // as the algorithm per Node's API contract.
+        return cryptoSign(null, Buffer.from(canonical, "utf8"), privKey).toString("hex");
+    }
+    // Default CRP 1.0 · HMAC-SHA256
     const key = loadOrCreateHmacKey();
-    return createHmac("sha256", key).update(canonicalizeReceipt(r)).digest("hex");
+    return createHmac("sha256", key).update(canonical).digest("hex");
+}
+function verifySignature(receipt) {
+    const canonical = canonicalizeReceipt({
+        id: receipt.id,
+        issued_at: receipt.issued_at,
+        expires_at: receipt.expires_at,
+        rules_version: receipt.rules_version,
+        caveats: receipt.caveats,
+        version: receipt.version,
+    });
+    if (receipt.version === "1.1") {
+        try {
+            const { publicKeyPem } = loadOrCreateEd25519Keys();
+            const pubKey = createPublicKey(publicKeyPem);
+            return cryptoVerify(null, Buffer.from(canonical, "utf8"), pubKey, Buffer.from(receipt.signature, "hex"));
+        }
+        catch {
+            return false;
+        }
+    }
+    // CRP 1.0 · HMAC-SHA256 with constant-time compare
+    const key = loadOrCreateHmacKey();
+    const expected = createHmac("sha256", key).update(canonical).digest();
+    const actual = Buffer.from(receipt.signature, "hex");
+    if (expected.length !== actual.length)
+        return false;
+    return timingSafeEqual(expected, actual);
 }
 /**
- * Issue a fresh Compliance Receipt with the given caveats. The receipt
- * is bound to the current rule-store hash; any rule edit invalidates it.
+ * Issue a fresh Compliance Receipt with the given caveats. The receipt is
+ * bound to the current rule-store hash; any rule edit invalidates it.
+ *
+ * Signing mode selected by the `CRP_SIGNING_MODE` env var:
+ *   - `hmac` (default) · CRP 1.0 · HMAC-SHA256 with a 256-bit shared secret
+ *   - `ed25519` · CRP 1.1 · Ed25519 asymmetric · enables cross-server
+ *     federation since validators verify with the issuer's public key
+ *     without sharing any secret. Public key exportable via the
+ *     `agent-memory export-pubkey` CLI command.
  */
 export function issueReceipt(opts) {
     const now = Math.floor(Date.now() / 1000);
@@ -1405,6 +1493,7 @@ export function issueReceipt(opts) {
         expires_at: now + ttl,
         rules_version: computeRulesVersion(),
         caveats: opts.caveats,
+        ...(CRP_SIGNING_MODE === "ed25519" ? { version: "1.1" } : {}),
     };
     return { ...base, signature: signReceipt(base) };
 }
@@ -1414,17 +1503,10 @@ export function issueReceipt(opts) {
  * {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)) {
+    // 1. Signature verification · routes to HMAC (CRP 1.0) or Ed25519 (CRP 1.1)
+    //    based on the receipt's version field. Both paths use constant-time
+    //    comparisons internally to avoid timing leaks.
+    if (!verifySignature(receipt)) {
         return { valid: false, reason: "invalid signature" };
     }
     // 2. Expiry · receipts past their expires_at are dead.
@@ -1782,7 +1864,14 @@ function recentDenials() {
     }));
 }
 function recentUnreceiptedDeletes() {
-    const records = readEventLog({ tail: AUDIT_EVENT_TAIL, action: "delete_without_receipt" });
+    // v0.11.x emitted "delete_without_receipt" when an unreceipted delete
+    // succeeded. v0.12.0 emits "delete_refused_no_receipt" when refusing.
+    // We surface BOTH event types so an audit run against pre-v0.12 logs
+    // still reports historical unreceipted deletes correctly.
+    const records = [
+        ...readEventLog({ tail: AUDIT_EVENT_TAIL, action: "delete_without_receipt" }),
+        ...readEventLog({ tail: AUDIT_EVENT_TAIL, action: "delete_refused_no_receipt" }),
+    ];
     return records.map((r) => ({
         ts: String(r.ts),
         name: String(r.name ?? ""),
@@ -2188,7 +2277,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.11.7" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.13.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -2512,18 +2601,18 @@ 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/. " +
-                "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. " +
+                "v0.12.0+ · receipt REQUIRED. Caller MUST first call check_action({action: 'delete memory <name>', action_type: 'deletions'}) to obtain a fresh Compliance Receipt, then pass it to this tool as `receipt`. " +
                 "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.",
+                "Migration from v0.11.x: previously unreceipted deletes were accepted with a warning · now they throw. Add a check_action call before each delete_memory call.",
             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.",
+                        description: "REQUIRED · Compliance Receipt (object or JSON string) from check_action with action_type=deletions. Without this, the delete is refused.",
                     },
                 },
-                required: ["name"],
+                required: ["name", "receipt"],
             },
         },
         {
@@ -2872,6 +2961,7 @@ const CLI_COMMANDS = new Set([
     "emit-companions",
     "check-action",
     "audit",
+    "export-pubkey",
     "ui",
     "import-claude-code",
     "help",
@@ -2986,7 +3076,19 @@ async function cliMain(command, rest) {
                 const name = positional[0];
                 if (!name)
                     throw new Error("Usage: agent-memory delete <name>");
-                process.stdout.write(toolDeleteMemory({ name }) + "\n");
+                // v0.12.0+ · delete_memory requires a Compliance Receipt. The CLI
+                // is the trusted operator path (a human is running the command,
+                // not an AI agent), so we auto-issue a CLI-scoped receipt rather
+                // than make the operator chain `check-action` then paste JSON.
+                // MCP callers (AI agents) still must go through check_action
+                // explicitly — this short-circuit only fires from the CLI binary.
+                const receipt = issueReceipt({
+                    caveats: [
+                        { type: "action_type", value: "deletions" },
+                        { type: "issued_by", value: "cli" },
+                    ],
+                });
+                process.stdout.write(toolDeleteMemory({ name, receipt: JSON.stringify(receipt) }) + "\n");
                 return 0;
             }
             case "restore": {
@@ -3137,6 +3239,14 @@ async function cliMain(command, rest) {
                 process.stdout.write(toolAudit({ format: flags.json ? "json" : "pretty" }) + "\n");
                 return 0;
             }
+            case "export-pubkey": {
+                // CRP 1.1 · print the Ed25519 public key (PEM) so other MCP servers
+                // can verify receipts issued by this server without sharing the
+                // signing secret. Lazily initializes the keypair if missing.
+                const { publicKeyPem } = loadOrCreateEd25519Keys();
+                process.stdout.write(publicKeyPem);
+                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.7",
+  "version": "0.13.0",
   "mcpName": "io.github.xultrax-web/agent-memory-mcp",
   "description": "Codify how you work. Every AI tool obeys. Markdown rules + cross-tool companion files (AGENTS.md/CLAUDE.md/.cursor/rules/.gemini) + Compliance Receipts for protocol-level enforcement of destructive ops. Reference implementation of CRP 1.0. Works on every MCP client (no Sampling required).",
   "type": "module",