@peac/mcp-server 0.10.13 → 0.11.3

package/dist/cli.cjs

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 'use strict';
 
+var crypto$1 = require('crypto');
+var streamableHttp_js = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+var http = require('http');
 var promises = require('fs/promises');
 var commander = require('commander');
 var zod = require('zod');
 var crypto = require('@peac/crypto');
 var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+var kernel = require('@peac/kernel');
 var protocol = require('@peac/protocol');
 var schema = require('@peac/schema');
 var nodePath = require('path');
-var crypto$1 = require('crypto');
-var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -32,10 +34,521 @@ function _interopNamespace(e) {
 
 var nodePath__namespace = /*#__PURE__*/_interopNamespace(nodePath);
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
 // src/infra/constants.ts
-var SERVER_NAME = "peac-mcp-server";
-var SERVER_VERSION = "0.10.12";
-var MCP_PROTOCOL_VERSION = "2025-11-25";
+var SERVER_NAME, SERVER_VERSION, MCP_PROTOCOL_VERSION;
+var init_constants = __esm({
+  "src/infra/constants.ts"() {
+    SERVER_NAME = "peac-mcp-server";
+    SERVER_VERSION = "0.11.2";
+    MCP_PROTOCOL_VERSION = "2025-11-25";
+  }
+});
+var SessionManager;
+var init_session_manager = __esm({
+  "src/session-manager.ts"() {
+    SessionManager = class {
+      constructor(options = {}) {
+        this.options = options;
+        this.ttlMs = options.ttlMs ?? 30 * 60 * 1e3;
+        this.maxSessions = options.maxSessions ?? 100;
+        this.maxSessionsPerIp = options.maxSessionsPerIp ?? 10;
+      }
+      sessions = /* @__PURE__ */ new Map();
+      ipSessionCount = /* @__PURE__ */ new Map();
+      ttlMs;
+      maxSessions;
+      maxSessionsPerIp;
+      sweepTimer;
+      /** Start periodic eviction sweep */
+      startSweep() {
+        const intervalMs = this.options.sweepIntervalMs ?? 6e4;
+        this.sweepTimer = setInterval(() => this.evictStale(), intervalMs);
+        this.sweepTimer.unref();
+      }
+      /** Create a new isolated session with its own McpServer + transport */
+      async createSession(serverFactory, clientIp = "unknown") {
+        this.evictStale();
+        if (this.sessions.size >= this.maxSessions) {
+          throw new Error(`Session limit reached (${this.maxSessions}). Try again later.`);
+        }
+        const ipCount = this.ipSessionCount.get(clientIp) ?? 0;
+        if (ipCount >= this.maxSessionsPerIp) {
+          throw new Error(
+            `Per-IP session limit reached (${this.maxSessionsPerIp} for ${clientIp}). Try again later.`
+          );
+        }
+        const sessionId = crypto$1.randomUUID();
+        const server = serverFactory();
+        const transport = new streamableHttp_js.StreamableHTTPServerTransport({
+          sessionIdGenerator: () => sessionId
+        });
+        await server.connect(transport);
+        const now = Date.now();
+        const entry = {
+          sessionId,
+          server,
+          transport,
+          clientIp,
+          createdAt: now,
+          lastSeen: now
+        };
+        this.sessions.set(sessionId, entry);
+        this.ipSessionCount.set(clientIp, ipCount + 1);
+        return entry;
+      }
+      /** Look up an existing session by ID */
+      getSession(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (entry) {
+          entry.lastSeen = Date.now();
+        }
+        return entry;
+      }
+      /** Terminate and clean up a specific session */
+      async terminateSession(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry) return false;
+        this.sessions.delete(sessionId);
+        this.decrementIpCount(entry.clientIp);
+        try {
+          await entry.transport.close();
+          await entry.server.close();
+        } catch {
+        }
+        return true;
+      }
+      /** Terminate all sessions and stop sweep */
+      async cleanup() {
+        if (this.sweepTimer) {
+          clearInterval(this.sweepTimer);
+          this.sweepTimer = void 0;
+        }
+        const entries = [...this.sessions.values()];
+        this.sessions.clear();
+        this.ipSessionCount.clear();
+        await Promise.allSettled(
+          entries.map(async (entry) => {
+            try {
+              await entry.transport.close();
+              await entry.server.close();
+            } catch {
+            }
+          })
+        );
+      }
+      /** Get current session count */
+      get size() {
+        return this.sessions.size;
+      }
+      /** Evict sessions past TTL */
+      evictStale() {
+        const now = Date.now();
+        for (const [id, entry] of this.sessions) {
+          if (now - entry.lastSeen > this.ttlMs) {
+            this.sessions.delete(id);
+            this.decrementIpCount(entry.clientIp);
+            void entry.transport.close().catch(() => {
+            });
+            void entry.server.close().catch(() => {
+            });
+          }
+        }
+      }
+      /** Decrement per-IP session count, removing the key when it reaches 0 */
+      decrementIpCount(ip) {
+        const count = this.ipSessionCount.get(ip) ?? 0;
+        if (count <= 1) {
+          this.ipSessionCount.delete(ip);
+        } else {
+          this.ipSessionCount.set(ip, count - 1);
+        }
+      }
+    };
+  }
+});
+
+// src/http-transport.ts
+var http_transport_exports = {};
+__export(http_transport_exports, {
+  createHttpTransport: () => createHttpTransport
+});
+function isValidSessionId(id) {
+  if (id.length === 0 || id.length > MAX_SESSION_ID_LENGTH) return false;
+  for (let i = 0; i < id.length; i++) {
+    const code = id.charCodeAt(i);
+    if (code < 33 || code > 126) return false;
+  }
+  return true;
+}
+function isLoopbackAddr(addr) {
+  return addr.startsWith("127.") || addr === "::1" || addr === "::ffff:127.0.0.1";
+}
+function isLinkLocalAddr(addr) {
+  if (isLoopbackAddr(addr)) return true;
+  return addr.startsWith("169.254.") || addr.startsWith("fe80");
+}
+function isPrivateAddr(addr) {
+  if (isLinkLocalAddr(addr)) return true;
+  return addr.startsWith("10.") || addr.startsWith("192.168.") || /^172\.(1[6-9]|2\d|3[01])\./.test(addr) || addr.startsWith("fc") || addr.startsWith("fd") || addr.startsWith("::ffff:10.") || addr.startsWith("::ffff:192.168.") || /^::ffff:172\.(1[6-9]|2\d|3[01])\./.test(addr);
+}
+function isTrustedProxy(remoteAddr, trustProxy) {
+  if (trustProxy === "off") return false;
+  if (trustProxy === "all") return true;
+  if (trustProxy === "loopback") return isLoopbackAddr(remoteAddr);
+  if (trustProxy === "linklocal") return isLinkLocalAddr(remoteAddr);
+  if (trustProxy === "private") return isPrivateAddr(remoteAddr);
+  const trusted = trustProxy.split(",").map((s) => s.trim());
+  return trusted.includes(remoteAddr);
+}
+function validatePublicUrl(rawUrl) {
+  let u;
+  try {
+    u = new URL(rawUrl);
+  } catch {
+    return { error: `Invalid URL: ${rawUrl}` };
+  }
+  if (u.hash) {
+    return { error: "Public URL must not contain fragments (#)" };
+  }
+  const isLoopback = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
+  if (u.protocol !== "https:" && !isLoopback) {
+    return { error: "Public URL must use https (except for localhost/loopback dev usage)" };
+  }
+  const normalized = u.href.replace(/\/+$/, "") || u.origin;
+  return { url: u, normalized };
+}
+async function createHttpTransport(options) {
+  const port = options.port ?? 3e3;
+  const host = options.host ?? "127.0.0.1";
+  const corsOrigins = new Set(options.corsOrigins ?? []);
+  const maxRequestBytes = options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES;
+  const rateLimitRpm = options.rateLimitRpm ?? DEFAULT_RATE_LIMIT_RPM;
+  const sessionManager = new SessionManager({
+    ttlMs: options.sessionTtlMs,
+    maxSessions: options.maxSessions,
+    maxSessionsPerIp: options.maxSessionsPerIp
+  });
+  sessionManager.startSweep();
+  const rateLimits = /* @__PURE__ */ new Map();
+  function checkRateLimit(key) {
+    const now = Date.now();
+    let entry = rateLimits.get(key);
+    if (!entry || now - entry.windowStart > ONE_MINUTE_MS) {
+      entry = { count: 0, windowStart: now };
+      rateLimits.set(key, entry);
+    }
+    entry.count++;
+    return entry.count <= rateLimitRpm;
+  }
+  const trustProxyValue = options.trustProxy ?? "off";
+  function getClientIp(req) {
+    const peerIp = req.socket.remoteAddress ?? "unknown";
+    if (trustProxyValue !== "off" && isTrustedProxy(peerIp, trustProxyValue)) {
+      const xff = req.headers["x-forwarded-for"];
+      if (typeof xff === "string") {
+        const first = xff.split(",")[0]?.trim();
+        if (first) return first;
+      }
+    }
+    return peerIp;
+  }
+  const allowedHosts = /* @__PURE__ */ new Set();
+  allowedHosts.add(`${host}:${port}`);
+  allowedHosts.add(host === "0.0.0.0" ? `localhost:${port}` : `${host}:${port}`);
+  if (host === "127.0.0.1" || host === "0.0.0.0") {
+    allowedHosts.add(`localhost:${port}`);
+    allowedHosts.add(`127.0.0.1:${port}`);
+  }
+  if (options.publicUrl) {
+    try {
+      const u = new URL(options.publicUrl);
+      allowedHosts.add(u.host);
+    } catch {
+    }
+  }
+  const allowedOrigins = new Set(corsOrigins);
+  function validateOrigin(req, res) {
+    const origin = req.headers.origin;
+    if (!origin) return true;
+    if (allowedOrigins.size === 0) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Origin not allowed" }));
+      return false;
+    }
+    if (!allowedOrigins.has(origin)) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Origin not allowed" }));
+      return false;
+    }
+    return true;
+  }
+  function setCorsHeaders(req, res) {
+    const origin = req.headers.origin;
+    if (origin && allowedOrigins.has(origin)) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Access-Control-Allow-Methods", "POST, DELETE, GET, OPTIONS");
+      res.setHeader(
+        "Access-Control-Allow-Headers",
+        "Content-Type, Mcp-Session-Id, Accept, MCP-Protocol-Version"
+      );
+      res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+    }
+  }
+  function sendJson(res, status, body) {
+    const json = JSON.stringify(body);
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(json);
+  }
+  async function readBody(req) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of req) {
+      totalBytes += chunk.length;
+      if (totalBytes > maxRequestBytes) {
+        throw new Error(`Request body exceeds ${maxRequestBytes} bytes`);
+      }
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+  const authServers = (options.authorizationServers ?? []).filter((s) => s.trim().length > 0);
+  if (options.authorizationServers?.length && authServers.length === 0) {
+    process.stderr.write(
+      `[${SERVER_NAME}] WARNING: --authorization-servers contains only empty entries, PRM disabled
+`
+    );
+  }
+  if (authServers.length > 0 && !options.publicUrl) {
+    process.stderr.write(
+      `[${SERVER_NAME}] WARNING: --authorization-servers set without --public-url, PRM disabled
+`
+    );
+  }
+  if (options.publicUrl && authServers.length === 0) {
+    process.stderr.write(
+      `[${SERVER_NAME}] WARNING: --public-url set without --authorization-servers, PRM disabled
+`
+    );
+  }
+  const prmEnabled = !!(authServers.length > 0 && options.publicUrl);
+  let prmPath = "/.well-known/oauth-protected-resource";
+  let prmDocument;
+  if (prmEnabled && options.publicUrl) {
+    const validation = validatePublicUrl(options.publicUrl);
+    if ("error" in validation) {
+      process.stderr.write(
+        `[${SERVER_NAME}] WARNING: --public-url invalid, PRM disabled: ${validation.error}
+`
+      );
+    } else {
+      const { url: u, normalized } = validation;
+      const resourcePath = u.pathname.replace(/\/+$/, "");
+      if (resourcePath && resourcePath !== "/") {
+        prmPath = `/.well-known/oauth-protected-resource${resourcePath}`;
+      }
+      prmDocument = {
+        resource: normalized,
+        authorization_servers: authServers
+      };
+    }
+  }
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const pathname = url.pathname;
+    res.setTimeout(3e4);
+    if (req.method === "OPTIONS") {
+      setCorsHeaders(req, res);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    setCorsHeaders(req, res);
+    const hostHeader = req.headers.host;
+    if (hostHeader && !allowedHosts.has(hostHeader)) {
+      sendJson(res, 400, { error: "Invalid Host header" });
+      return;
+    }
+    if (!validateOrigin(req, res)) return;
+    if (pathname === "/health" && req.method === "GET") {
+      sendJson(res, 200, {
+        ok: true,
+        version: SERVER_VERSION,
+        protocolVersion: MCP_PROTOCOL_VERSION
+      });
+      return;
+    }
+    if (pathname === prmPath && req.method === "GET") {
+      if (prmEnabled && prmDocument) {
+        sendJson(res, 200, prmDocument);
+      } else {
+        sendJson(res, 404, { error: "Not found" });
+      }
+      return;
+    }
+    if (pathname === "/mcp") {
+      if (req.method === "GET") {
+        res.writeHead(405, { Allow: "POST, DELETE", "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Method Not Allowed. Use POST for JSON-RPC requests." }));
+        return;
+      }
+      if (req.method === "DELETE") {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId) {
+          sendJson(res, 400, { error: "Missing Mcp-Session-Id header" });
+          return;
+        }
+        if (!isValidSessionId(sessionId)) {
+          sendJson(res, 400, {
+            error: "Invalid Mcp-Session-Id: must be visible ASCII (0x21-0x7E), max 128 chars"
+          });
+          return;
+        }
+        const terminated = await sessionManager.terminateSession(sessionId);
+        if (terminated) {
+          sendJson(res, 200, { ok: true });
+        } else {
+          sendJson(res, 404, { error: "Session not found or already terminated" });
+        }
+        return;
+      }
+      if (req.method === "POST") {
+        const sessionId = req.headers["mcp-session-id"];
+        const rateLimitKey = sessionId ?? `ip:${getClientIp(req)}`;
+        if (!checkRateLimit(rateLimitKey)) {
+          res.writeHead(429, { "Content-Type": "application/json", "Retry-After": "60" });
+          res.end(JSON.stringify({ error: "Rate limit exceeded" }));
+          return;
+        }
+        let body;
+        try {
+          const raw = await readBody(req);
+          body = JSON.parse(raw.toString("utf-8"));
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : "Invalid request body";
+          sendJson(res, 400, { error: msg });
+          return;
+        }
+        const isInit = typeof body === "object" && body !== null && "method" in body && body.method === "initialize";
+        if (isInit) {
+          const protocolVersion = req.headers["mcp-protocol-version"];
+          if (protocolVersion && protocolVersion !== MCP_PROTOCOL_VERSION && protocolVersion !== "2025-03-26") {
+            sendJson(res, 400, { error: `Unsupported MCP protocol version: ${protocolVersion}` });
+            return;
+          }
+          const accept = req.headers.accept;
+          if (!accept) {
+            process.stderr.write(
+              `[${SERVER_NAME}] Warning: missing Accept header on init request
+`
+            );
+          }
+          let entry2;
+          try {
+            entry2 = await sessionManager.createSession(options.serverFactory, getClientIp(req));
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : "Failed to create session";
+            sendJson(res, 503, { error: msg });
+            return;
+          }
+          await entry2.transport.handleRequest(req, res, body);
+          return;
+        }
+        if (!sessionId) {
+          sendJson(res, 400, { error: "Missing Mcp-Session-Id header" });
+          return;
+        }
+        if (!isValidSessionId(sessionId)) {
+          sendJson(res, 400, {
+            error: "Invalid Mcp-Session-Id: must be visible ASCII (0x21-0x7E), max 128 chars"
+          });
+          return;
+        }
+        const entry = sessionManager.getSession(sessionId);
+        if (!entry) {
+          sendJson(res, 404, { error: "Session not found or terminated" });
+          return;
+        }
+        await entry.transport.handleRequest(req, res, body);
+        return;
+      }
+      res.writeHead(405, { Allow: "POST, DELETE", "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Method Not Allowed" }));
+      return;
+    }
+    sendJson(res, 404, { error: "Not found" });
+  });
+  server.headersTimeout = 1e4;
+  server.requestTimeout = 3e4;
+  server.keepAliveTimeout = 5e3;
+  return new Promise((resolve2, reject) => {
+    server.on("error", reject);
+    server.listen(port, host, () => {
+      process.stderr.write(`[${SERVER_NAME}] HTTP transport listening on http://${host}:${port}
+`);
+      process.stderr.write(`  Transport: Streamable HTTP (MCP 2025-06-18)
+`);
+      process.stderr.write(
+        `  Auth: unprotected mode (no token validation); PRM discovery per RFC 9728
+`
+      );
+      process.stderr.write(`  Endpoints: POST /mcp, DELETE /mcp, GET /health
+`);
+      if (prmEnabled) {
+        process.stderr.write(`  PRM: GET ${prmPath} (implemented, enabled by config)
+`);
+      } else {
+        process.stderr.write(
+          `  PRM: disabled (set --authorization-servers + --public-url to enable)
+`
+        );
+      }
+      process.stderr.write(
+        `  Sessions: max ${options.maxSessions ?? 100} (${options.maxSessionsPerIp ?? 10}/IP), TTL ${(options.sessionTtlMs ?? 18e5) / 1e3}s
+`
+      );
+      process.stderr.write(`  Rate limit: ${rateLimitRpm} req/min per session
+`);
+      process.stderr.write(
+        `  CORS: ${corsOrigins.size > 0 ? [...corsOrigins].join(", ") : "deny all"}
+`
+      );
+      process.stderr.write(
+        `  Mode: unprotected (token validation deferred to v0.11.x+; deployer auth via reverse proxy)
+`
+      );
+      resolve2({
+        cleanup: async () => {
+          await sessionManager.cleanup();
+          await new Promise((res) => server.close(() => res()));
+        }
+      });
+    });
+  });
+}
+var ONE_MINUTE_MS, DEFAULT_MAX_REQUEST_BYTES, DEFAULT_RATE_LIMIT_RPM, MAX_SESSION_ID_LENGTH;
+var init_http_transport = __esm({
+  "src/http-transport.ts"() {
+    init_session_manager();
+    init_constants();
+    ONE_MINUTE_MS = 6e4;
+    DEFAULT_MAX_REQUEST_BYTES = 1048576;
+    DEFAULT_RATE_LIMIT_RPM = 100;
+    MAX_SESSION_ID_LENGTH = 128;
+  }
+});
+
+// src/cli.ts
+init_constants();
 
 // src/infra/errors.ts
 var McpServerError = class extends Error {
@@ -104,9 +617,9 @@ var JwksConfigSchema = zod.z.object({
 var PolicySchema = zod.z.object({
   version: zod.z.literal("1"),
   allow_network: zod.z.boolean().default(false),
-  redaction: RedactionSchema.default({}),
-  tools: zod.z.record(zod.z.string(), ToolPolicySchema).default({}),
-  limits: LimitsSchema.default({}),
+  redaction: RedactionSchema.prefault({}),
+  tools: zod.z.record(zod.z.string(), ToolPolicySchema).prefault({}),
+  limits: LimitsSchema.prefault({}),
   jwks: JwksConfigSchema.optional()
 });
 var DEFAULT_POLICY = {
@@ -382,6 +895,9 @@ function installStdoutFence() {
   };
 }
 
+// src/server.ts
+init_constants();
+
 // src/handlers/guards.ts
 function checkJwsSize(jws, policy) {
   const byteLength = new TextEncoder().encode(jws).length;
@@ -987,10 +1503,40 @@ async function handleIssue(params) {
     };
   }
 }
+var WINDOWS_RESERVED_NAMES = /* @__PURE__ */ new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  "com1",
+  "com2",
+  "com3",
+  "com4",
+  "com5",
+  "com6",
+  "com7",
+  "com8",
+  "com9",
+  "lpt1",
+  "lpt2",
+  "lpt3",
+  "lpt4",
+  "lpt5",
+  "lpt6",
+  "lpt7",
+  "lpt8",
+  "lpt9"
+]);
 function assertRelativePath(p) {
   if (!p || p.trim().length === 0) {
     throw new PathTraversalError("Path must not be empty");
   }
+  if (p.includes("\0")) {
+    throw new PathTraversalError("Null bytes are not allowed in paths");
+  }
+  if (p.includes(":")) {
+    throw new PathTraversalError("Colons are not allowed in paths (drive letters, NTFS ADS)");
+  }
   if (nodePath__namespace.isAbsolute(p)) {
     throw new PathTraversalError("Absolute paths are not allowed");
   }
@@ -1007,6 +1553,14 @@ function assertRelativePath(p) {
   if (p.startsWith(".")) {
     throw new PathTraversalError("Hidden paths (starting with .) are not allowed");
   }
+  if (p.endsWith(".") || p.endsWith(" ")) {
+    throw new PathTraversalError("Trailing dots and spaces are not allowed");
+  }
+  const dotIndex = p.indexOf(".");
+  const baseName = (dotIndex >= 0 ? p.slice(0, dotIndex) : p).toLowerCase();
+  if (WINDOWS_RESERVED_NAMES.has(baseName)) {
+    throw new PathTraversalError(`Windows reserved device name: ${baseName.toUpperCase()}`);
+  }
 }
 async function assertNotSymlink(componentPath) {
   try {
@@ -1038,6 +1592,7 @@ async function createTempDir(basePath) {
 }
 
 // src/handlers/bundle.ts
+init_constants();
 function stableJsonStringify(value) {
   return JSON.stringify(
     value,
@@ -1359,7 +1914,7 @@ var IssueOutputSchema = zod.z.object({
 });
 var BundleInputSchema = zod.z.object({
   receipts: zod.z.array(zod.z.string().max(16384)).min(1).max(256).describe("Receipt JWS strings to bundle (1-256)"),
-  metadata: zod.z.record(zod.z.unknown()).optional().describe("Optional metadata to include in the manifest"),
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).optional().describe("Optional metadata to include in the manifest"),
   output_path: zod.z.string().max(255).optional().describe("Output directory name (single segment within --bundle-dir)")
 });
 var MetaSchema5 = zod.z.object({
@@ -1415,9 +1970,17 @@ var BUNDLE_TOOL_ANNOTATIONS = {
 };
 var MAX_INPUT_DEPTH = 10;
 function errorCallToolResult(meta, code, message) {
+  const errorDef = kernel.ERRORS[code];
   return {
     content: [{ type: "text", text: message }],
-    structuredContent: { _meta: meta, ok: false, code, message },
+    structuredContent: {
+      _meta: meta,
+      ok: false,
+      code,
+      message,
+      retryable: errorDef?.retryable ?? false,
+      next_action: errorDef?.next_action ?? "none"
+    },
     isError: true
   };
 }
@@ -1521,7 +2084,7 @@ function createPeacMcpServer(options) {
     "peac_verify",
     {
       title: "Verify PEAC Receipt",
-      description: "Verify a PEAC receipt JWS signature and validate claims. Returns structured check results.",
+      description: "Verify a PEAC receipt: check Ed25519 signature, validate claims, and return structured check results. Read-only, no side effects.",
       inputSchema: VerifyInputSchema,
       outputSchema: VerifyOutputSchema,
       annotations: PURE_TOOL_ANNOTATIONS
@@ -1537,7 +2100,7 @@ function createPeacMcpServer(options) {
     "peac_inspect",
     {
       title: "Inspect PEAC Receipt",
-      description: "Decode and inspect a PEAC receipt without verifying the signature. Shows header, payload metadata, and optionally full claims.",
+      description: "Inspect a PEAC receipt without verifying the signature. Returns decoded header, payload metadata, and timestamps. Read-only.",
       inputSchema: InspectInputSchema,
       outputSchema: InspectOutputSchema,
       annotations: PURE_TOOL_ANNOTATIONS
@@ -1553,7 +2116,7 @@ function createPeacMcpServer(options) {
     "peac_decode",
     {
       title: "Decode PEAC Receipt",
-      description: "Raw decode of a PEAC receipt JWS. Returns header and payload without signature verification.",
+      description: "Raw-decode a PEAC receipt JWS into header and payload objects. No signature check. Use peac_verify for trusted results.",
       inputSchema: DecodeInputSchema,
       outputSchema: DecodeOutputSchema,
       annotations: PURE_TOOL_ANNOTATIONS
@@ -1570,7 +2133,7 @@ function createPeacMcpServer(options) {
       "peac_issue",
       {
         title: "Issue PEAC Receipt",
-        description: "Sign and return a PEAC receipt JWS. Requires server to be configured with --issuer-key and --issuer-id.",
+        description: "Sign and return a new PEAC receipt JWS. Requires server configured with an Ed25519 issuer key (--issuer-key and --issuer-id).",
         inputSchema: IssueInputSchema,
         outputSchema: IssueOutputSchema,
         annotations: ISSUE_TOOL_ANNOTATIONS
@@ -1587,7 +2150,7 @@ function createPeacMcpServer(options) {
         "peac_create_bundle",
         {
           title: "Create Evidence Bundle",
-          description: "Create a signed evidence bundle directory from receipt JWS strings. Requires --issuer-key, --issuer-id, and --bundle-dir.",
+          description: "Create a signed evidence bundle directory from one or more receipt JWS strings. Writes files to disk. Requires --issuer-key, --issuer-id, and --bundle-dir.",
           inputSchema: BundleInputSchema,
           outputSchema: BundleOutputSchema,
           annotations: BUNDLE_TOOL_ANNOTATIONS
@@ -1603,8 +2166,25 @@ function createPeacMcpServer(options) {
   }
   return server;
 }
+
+// src/cli.ts
 var program = new commander.Command();
-program.name(SERVER_NAME).version(SERVER_VERSION).description("PEAC receipt operations as MCP tools").option("--issuer-key <ref>", "Issuer key reference (env:VAR or file:/path)").option("--issuer-id <uri>", "Issuer identifier URI").option("--policy <path>", "Policy configuration file path").option("--jwks-file <path>", "JWKS file for verifier key resolution").option("--bundle-dir <path>", "Directory for evidence bundle output").action(async (opts) => {
+program.name(SERVER_NAME).version(SERVER_VERSION).description("PEAC receipt operations as MCP tools").option("--issuer-key <ref>", "Issuer key reference (env:VAR or file:/path)").option("--issuer-id <uri>", "Issuer identifier URI").option("--policy <path>", "Policy configuration file path").option("--jwks-file <path>", "JWKS file for verifier key resolution").option("--bundle-dir <path>", "Directory for evidence bundle output").option("--transport <type>", "Transport: stdio (default) or http", "stdio").option("--port <number>", "HTTP port (default: 3000, http only)", "3000").option("--host <address>", "HTTP bind address (default: 127.0.0.1)", "127.0.0.1").option("--cors-origins <list>", "Allowed CORS origins (comma-separated)").option(
+  "--authorization-servers <list>",
+  "OAuth authorization server URIs (enables PRM with --public-url)"
+).option("--public-url <url>", "Canonical public URL of this server (required for PRM)").option(
+  "--trust-proxy <value>",
+  "Trust X-Forwarded-For: off (default), loopback, linklocal, private, all (discouraged), or comma-separated IPs",
+  "off"
+).action(async (opts) => {
+  const transportType = opts.transport;
+  if (transportType !== "stdio" && transportType !== "http") {
+    process.stderr.write(
+      `ERROR: --transport must be "stdio" or "http", got "${transportType}"
+`
+    );
+    process.exit(1);
+  }
   if (opts.issuerKey && !opts.issuerId) {
     process.stderr.write("ERROR: --issuer-key requires --issuer-id\n");
     process.exit(1);
@@ -1658,13 +2238,6 @@ program.name(SERVER_NAME).version(SERVER_VERSION).description("PEAC receipt oper
     issuerId: opts.issuerId,
     bundleDir
   };
-  const teardownFence = installStdoutFence();
-  const server = createPeacMcpServer({
-    version: SERVER_VERSION,
-    policy,
-    context
-  });
-  const transport = new stdio_js.StdioServerTransport();
   const tools = ["peac_verify", "peac_inspect", "peac_decode"];
   if (issuerKey && opts.issuerId) {
     tools.push("peac_issue");
@@ -1672,10 +2245,17 @@ program.name(SERVER_NAME).version(SERVER_VERSION).description("PEAC receipt oper
       tools.push("peac_create_bundle");
     }
   }
+  const serverOptions = {
+    version: SERVER_VERSION,
+    policy,
+    context
+  };
   process.stderr.write(
     `[${SERVER_NAME}] v${SERVER_VERSION} | protocol ${MCP_PROTOCOL_VERSION}
 `
   );
+  process.stderr.write(`  Transport: ${transportType}
+`);
   process.stderr.write(`  Tools: ${tools.join(", ")}
 `);
   process.stderr.write(`  Key: ${issuerKey ? "loaded" : "none"}
@@ -1686,16 +2266,43 @@ program.name(SERVER_NAME).version(SERVER_VERSION).description("PEAC receipt oper
 `);
   process.stderr.write(`  Policy hash: ${policyHash.slice(0, 16)}...
 `);
-  const shutdown = async () => {
-    process.stderr.write(`[${SERVER_NAME}] Shutting down...
+  if (transportType === "http") {
+    const { createHttpTransport: createHttpTransport2 } = await Promise.resolve().then(() => (init_http_transport(), http_transport_exports));
+    const corsOrigins = opts.corsOrigins ? opts.corsOrigins.split(",").map((s) => s.trim()) : void 0;
+    const authorizationServers = opts.authorizationServers ? opts.authorizationServers.split(",").map((s) => s.trim()) : void 0;
+    const { cleanup } = await createHttpTransport2({
+      port: parseInt(opts.port, 10),
+      host: opts.host,
+      corsOrigins,
+      authorizationServers,
+      publicUrl: opts.publicUrl,
+      trustProxy: opts.trustProxy || "off",
+      serverFactory: () => createPeacMcpServer(serverOptions)
+    });
+    const shutdown = async () => {
+      process.stderr.write(`[${SERVER_NAME}] Shutting down...
 `);
-    await server.close();
-    teardownFence();
-    process.exit(0);
-  };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-  await server.connect(transport);
+      await cleanup();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  } else {
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const teardownFence = installStdoutFence();
+    const server = createPeacMcpServer(serverOptions);
+    const transport = new StdioServerTransport();
+    const shutdown = async () => {
+      process.stderr.write(`[${SERVER_NAME}] Shutting down...
+`);
+      await server.close();
+      teardownFence();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await server.connect(transport);
+  }
 });
 void program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(