@xultrax-web/agent-memory-mcp 0.12.0 → 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";
@@ -1333,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);
@@ -1347,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
@@ -1377,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);
@@ -1402,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) };
 }
@@ -1411,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.
@@ -2192,7 +2277,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.12.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.13.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -2876,6 +2961,7 @@ const CLI_COMMANDS = new Set([
     "emit-companions",
     "check-action",
     "audit",
+    "export-pubkey",
     "ui",
     "import-claude-code",
     "help",
@@ -3153,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.12.0",
+  "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",