@lyric_dev/data-loom 0.4.0 → 0.4.1

package/README.md

@@ -81,6 +81,17 @@ The running daemon also **hosts an MCP server** over HTTP, so your own Claude se
 
 > **Upgrading from an earlier version?** The MCP server used to be a per-project stdio registration (`claude mcp add data-loom -- npx … mcp "<path>"`). That mode is gone. Remove any old per-project `data-loom` registrations and add the single user-scope HTTP one above.
 
+## Security
+
+DataLoom runs entirely on `127.0.0.1` and is built for a single local user.
+
+- **Loopback only** — the daemon (dashboard, WebSocket, and MCP endpoint) binds to the loopback interface and is never exposed to the network.
+- **Host + Origin validated** — every HTTP request and WebSocket upgrade is checked: requests with a non-loopback `Host` (DNS-rebinding) or a non-loopback `Origin` (cross-site requests from a web page) are rejected. Native MCP clients (which send no `Origin`) are allowed. This is what keeps a random website you visit from driving the daemon.
+- **No secrets** — the MCP tools carry only proposal text and change names; the topology view redacts server commands/args and shows scheme+host only. No API keys or config are read or returned, and the daemon holds no credential.
+- **Bounded** — request bodies are capped (4 MB) and MCP sessions are capped and idle-evicted, so a local client can't exhaust memory.
+
+The MCP tools can read and write any OpenSpec workspace path you point them at (this is intentional, so the tool can stay LLM-provider-independent). That means: treat the daemon as you would any local dev server — fine for your own machine, not something to run on a shared/multi-user host.
+
 ## Design principles
 
 - **Derived, not stored** — phase/order is a pure function of the OpenSpec files, recomputed on every change. Nothing about ordering is persisted.

package/dist/mcpServer.js

@@ -15,6 +15,14 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { OpenSpecClient } from "./openspecClient.js";
 import { deriveModel } from "./derive.js";
 import { discoverProjects, isViewableProject } from "./projects.js";
+/**
+ * A validation error whose message is safe to return to the client because it
+ * only references caller-supplied input (a change name, a path the caller named).
+ * Anything that is NOT a ToolError is treated as an unexpected internal failure
+ * and reported generically, so host filesystem detail never leaks.
+ */
+class ToolError extends Error {
+}
 // Advertised to the client on connect. The "confirm before writing" gate lives
 // here, in the agent's behavior — the server cannot verify a human approved.
 const INSTRUCTIONS = `This server exposes a project's open OpenSpec proposals and lets you record the dependency order between them. It holds no model and cannot infer anything on its own — the judgment is yours and the decision is the user's.
@@ -67,18 +75,18 @@ const PROJECT_ARG = {
  * the dashboard selection is the single fallback source of project truth.
  */
 export function createMcpServer(deps) {
-    const server = new Server({ name: "data-loom", version: "0.4.0" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+    const server = new Server({ name: "data-loom", version: "0.4.1" }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     // Resolve the target project for a call: explicit arg, then dashboard
     // selection, then an instructive error. Validated as a real workspace before
     // any read or write.
     const resolveProject = (explicit) => {
         const raw = typeof explicit === "string" && explicit.trim() ? explicit : deps.getCurrentProject();
         if (!raw) {
-            throw new Error("No `project` given and no project is selected in the DataLoom dashboard. Call list_projects to see the available OpenSpec workspaces, then pass one as the `project` argument.");
+            throw new ToolError("No `project` given and no project is selected in the DataLoom dashboard. Call list_projects to see the available OpenSpec workspaces, then pass one as the `project` argument.");
         }
         const abs = resolve(raw);
         if (!isViewableProject(abs)) {
-            throw new Error(`${abs} is not an OpenSpec workspace (no openspec/ directory). Call list_projects to see the available workspaces.`);
+            throw new ToolError(`${abs} is not an OpenSpec workspace (no openspec/ directory). Call list_projects to see the available workspaces.`);
         }
         return abs;
     };
@@ -161,7 +169,12 @@ export function createMcpServer(deps) {
             return err(`unknown tool: ${name}`);
         }
         catch (e) {
-            return err(e instanceof Error ? e.message : String(e));
+            // Validation errors (caller-supplied input) are safe to surface; anything
+            // else is an unexpected internal failure → generic message, detail to log.
+            if (e instanceof ToolError)
+                return err(e.message);
+            console.error("[data-loom mcp] tool error:", e);
+            return err("internal error");
         }
     });
     return server;
@@ -202,14 +215,14 @@ async function listOpenProposals(client, changesDir, project) {
 }
 async function setDependency(client, changesDir, project, from, to) {
     if (!from || !to)
-        throw new Error("both 'from' and 'to' are required");
+        throw new ToolError("both 'from' and 'to' are required");
     if (from === to)
-        throw new Error("a change cannot depend on itself");
+        throw new ToolError("a change cannot depend on itself");
     const names = new Set((await openChanges(client)).map((c) => c.name));
     if (!names.has(from))
-        throw new Error(`unknown open change: ${from}`);
+        throw new ToolError(`unknown open change: ${from}`);
     if (!names.has(to))
-        throw new Error(`unknown open change: ${to}`);
+        throw new ToolError(`unknown open change: ${to}`);
     const path = join(changesDir, from, "proposal.md");
     const text = await readFile(path, "utf8");
     const updated = addDependsOn(text, to);
@@ -220,10 +233,10 @@ async function setDependency(client, changesDir, project, from, to) {
 }
 async function markIndependent(client, changesDir, project, change) {
     if (!change)
-        throw new Error("'change' is required");
+        throw new ToolError("'change' is required");
     const names = new Set((await openChanges(client)).map((c) => c.name));
     if (!names.has(change))
-        throw new Error(`unknown open change: ${change}`);
+        throw new ToolError(`unknown open change: ${change}`);
     const path = join(changesDir, change, "proposal.md");
     const text = await readFile(path, "utf8");
     const updated = ensureDependsOnSection(text);

package/dist/server.js

@@ -1,7 +1,7 @@
 // Serve the SPA on loopback and push roadmap + MCP + project state over a websocket.
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
-import { extname } from "node:path";
+import { extname, resolve, sep } from "node:path";
 import { WebSocketServer, WebSocket } from "ws";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
@@ -24,53 +24,110 @@ export async function startServer(opts) {
                 ws.send(data);
         }
     };
+    // Loopback origin/host allowlist — the DNS-rebinding + CSRF guard. Built from
+    // the actually-bound port after listen; seeded from the requested port so the
+    // guard is active from the first request.
+    const loopbackHosts = ["127.0.0.1", "localhost", "[::1]"];
+    let allowedAuthorities = new Set();
+    const setAllowed = (p) => {
+        allowedAuthorities = new Set(loopbackHosts.map((h) => `${h}:${p}`));
+    };
+    setAllowed(port);
+    // Reject what a hostile web page or a rebound DNS name could mount: a Host
+    // that is not our loopback authority (DNS rebinding), or any *present* Origin
+    // that is not a loopback origin (CSRF). An absent Origin = a native, non-
+    // browser client (e.g. Claude Code), which is allowed.
+    const isAllowed = (req) => {
+        const host = req.headers.host;
+        if (!host || !allowedAuthorities.has(host))
+            return false;
+        const origin = req.headers.origin;
+        if (origin) {
+            try {
+                if (!allowedAuthorities.has(new URL(origin).host))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    };
     // One MCP server + transport per client session (stateful Streamable-HTTP),
-    // keyed by the session id. Each session's tools resolve their target project
-    // per call from getCurrentProject (see mcpServer.ts), so one daemon serves
-    // every project.
-    const mcpTransports = new Map();
+    // keyed by session id. Sessions are capped and idle-evicted so churn cannot
+    // grow memory without bound. Tools resolve their target project per call from
+    // getCurrentProject (see mcpServer.ts), so one daemon serves every project.
+    const MAX_SESSIONS = 32;
+    const SESSION_IDLE_TTL_MS = 30 * 60 * 1000;
+    const mcpSessions = new Map();
+    const idleSweep = setInterval(() => {
+        const now = Date.now();
+        for (const [sid, s] of mcpSessions) {
+            if (now - s.lastSeen > SESSION_IDLE_TTL_MS) {
+                mcpSessions.delete(sid);
+                void s.transport.close();
+            }
+        }
+    }, 60 * 1000);
+    idleSweep.unref();
     const handleMcp = async (req, res) => {
         const sessionId = req.headers["mcp-session-id"];
         try {
             if (req.method === "POST") {
                 const body = await readJsonBody(req);
-                let transport = sessionId ? mcpTransports.get(sessionId) : undefined;
-                if (!transport) {
-                    if (!isInitializeRequest(body)) {
-                        return sendError(res, 400, "missing or invalid mcp-session-id");
-                    }
-                    transport = new StreamableHTTPServerTransport({
-                        sessionIdGenerator: () => randomUUID(),
-                        onsessioninitialized: (sid) => {
-                            mcpTransports.set(sid, transport);
-                        },
-                    });
-                    transport.onclose = () => {
-                        if (transport.sessionId)
-                            mcpTransports.delete(transport.sessionId);
-                    };
-                    await createMcpServer({ getCurrentProject }).connect(transport);
+                const existing = sessionId ? mcpSessions.get(sessionId) : undefined;
+                if (existing) {
+                    existing.lastSeen = Date.now();
+                    await existing.transport.handleRequest(req, res, body);
+                    return;
+                }
+                if (!isInitializeRequest(body)) {
+                    return sendError(res, 400, "missing or invalid mcp-session-id");
                 }
+                if (mcpSessions.size >= MAX_SESSIONS) {
+                    return sendError(res, 503, "too many sessions");
+                }
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        mcpSessions.set(sid, { transport, lastSeen: Date.now() });
+                    },
+                });
+                transport.onclose = () => {
+                    if (transport.sessionId)
+                        mcpSessions.delete(transport.sessionId);
+                };
+                await createMcpServer({ getCurrentProject }).connect(transport);
                 await transport.handleRequest(req, res, body);
                 return;
             }
             if (req.method === "GET" || req.method === "DELETE") {
-                const transport = sessionId ? mcpTransports.get(sessionId) : undefined;
-                if (!transport)
+                const s = sessionId ? mcpSessions.get(sessionId) : undefined;
+                if (!s)
                     return sendError(res, 400, "missing or invalid mcp-session-id");
-                await transport.handleRequest(req, res);
+                s.lastSeen = Date.now();
+                await s.transport.handleRequest(req, res);
                 return;
             }
             return sendError(res, 405, "method not allowed");
         }
         catch (e) {
-            if (!res.headersSent) {
-                sendError(res, 500, e instanceof Error ? e.message : "mcp error");
+            if (e instanceof PayloadTooLargeError) {
+                if (!res.headersSent)
+                    sendError(res, 413, "request body too large");
+                return;
             }
+            // Unexpected failures stay in the server log; the client gets nothing
+            // about the host (no paths, no stack).
+            console.error("[data-loom] mcp request error:", e);
+            if (!res.headersSent)
+                sendError(res, 500, "internal error");
         }
     };
     const http = createServer(async (req, res) => {
         try {
+            if (!isAllowed(req))
+                return sendError(res, 403, "forbidden");
             const url = new URL(req.url ?? "/", `http://${host}`);
             if (url.pathname === "/mcp")
                 return handleMcp(req, res);
@@ -96,9 +153,12 @@ export async function startServer(opts) {
                     return sendError(res, 400, err instanceof Error ? err.message : "invalid project");
                 }
             }
-            // static assets (served from public/ on the filesystem)
+            // static assets (served from public/ on the filesystem) — resolve and
+            // assert the path stays within publicDir before reading.
             const rel = url.pathname === "/" ? "index.html" : url.pathname.replace(/^\/+/, "");
-            if (rel.includes(".."))
+            const root = resolve(publicDir);
+            const full = resolve(root, rel);
+            if (full !== root && !full.startsWith(root + sep))
                 return sendError(res, 403, "forbidden");
             const file = await loadAsset(rel, publicDir);
             if (!file)
@@ -110,7 +170,10 @@ export async function startServer(opts) {
             sendError(res, 500, "error");
         }
     });
-    wss = new WebSocketServer({ server: http });
+    wss = new WebSocketServer({
+        server: http,
+        verifyClient: (info) => isAllowed(info.req),
+    });
     wss.on("connection", async (ws) => {
         const roadmap = getRoadmap();
         if (roadmap)
@@ -123,11 +186,14 @@ export async function startServer(opts) {
             /* project list optional */
         }
     });
-    await new Promise((resolve) => http.listen(port, host, resolve));
+    await new Promise((ready) => http.listen(port, host, ready));
+    const actualPort = http.address()?.port ?? port;
+    setAllowed(actualPort);
     return {
-        port,
+        port: actualPort,
         broadcast,
         close: () => {
+            clearInterval(idleSweep);
             wss.close();
             http.close();
         },
@@ -141,12 +207,32 @@ function sendError(res, code, message) {
     res.writeHead(code, { "content-type": MIME[".json"] });
     res.end(JSON.stringify({ error: message }));
 }
+/** Raised when a request body exceeds the cap; mapped to HTTP 413. */
+class PayloadTooLargeError extends Error {
+}
+/** Largest request body we will buffer (JSON-RPC tool calls are tiny). */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
 /** Read and JSON-parse a request body; returns undefined for an empty body. */
 function readJsonBody(req) {
     return new Promise((resolve, reject) => {
         let data = "";
-        req.on("data", (chunk) => (data += chunk));
+        let size = 0;
+        let aborted = false;
+        req.on("data", (chunk) => {
+            if (aborted)
+                return;
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                aborted = true;
+                reject(new PayloadTooLargeError("request body too large"));
+                req.destroy();
+                return;
+            }
+            data += chunk;
+        });
         req.on("end", () => {
+            if (aborted)
+                return;
             if (!data)
                 return resolve(undefined);
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyric_dev/data-loom",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local dashboard for spec-driven development: a phased OpenSpec roadmap (WHAT) and an MCP topology (HOW).",
   "type": "module",
   "license": "MIT",