@oimdb/mcp 1.2.0 → 2.0.0

package/dist/index.cjs

@@ -30,31 +30,225 @@ module.exports = __toCommonJS(index_exports);
 // src/core/OIMDevMcpServer.ts
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
-var import_ws = require("ws");
 var import_node_url = require("url");
 var import_node_path = require("path");
+var import_zod2 = require("zod");
+
+// src/core/OIMDevBridge.ts
+var import_ws = require("ws");
+
+// src/core/OIMDevBridgeMessageReader.ts
 var import_zod = require("zod");
+var _OIMDevBridgeMessageReader = class _OIMDevBridgeMessageReader {
+  read(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+    const result = _OIMDevBridgeMessageReader.SCHEMA.safeParse(parsed);
+    if (!result.success) return null;
+    return result.data;
+  }
+};
+_OIMDevBridgeMessageReader.SCHEMA = import_zod.z.discriminatedUnion("type", [
+  import_zod.z.object({
+    type: import_zod.z.literal("hello"),
+    url: import_zod.z.string(),
+    title: import_zod.z.string(),
+    timestamp: import_zod.z.number()
+  }),
+  import_zod.z.object({
+    type: import_zod.z.literal("response"),
+    id: import_zod.z.string(),
+    data: import_zod.z.unknown(),
+    error: import_zod.z.string().optional()
+  })
+]);
+var OIMDevBridgeMessageReader = _OIMDevBridgeMessageReader;
+
+// src/core/OIMDevLoopbackPolicy.ts
+var _OIMDevLoopbackPolicy = class _OIMDevLoopbackPolicy {
+  static isLoopbackHost(host) {
+    return _OIMDevLoopbackPolicy.HOSTS.has(host) || host.endsWith(".localhost");
+  }
+  static isLoopbackAuthority(authority) {
+    const host = authority.startsWith("[") ? authority.slice(0, authority.indexOf("]") + 1) : authority.split(":", 1)[0];
+    return _OIMDevLoopbackPolicy.isLoopbackHost(host);
+  }
+  // The literal string `null` is NOT loopback: a sandboxed iframe on any site
+  // in the world sends exactly that.
+  static isLoopbackOrigin(origin) {
+    try {
+      return _OIMDevLoopbackPolicy.isLoopbackHost(new URL(origin).hostname);
+    } catch {
+      return false;
+    }
+  }
+};
+_OIMDevLoopbackPolicy.HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "::1",
+  "[::1]"
+]);
+var OIMDevLoopbackPolicy = _OIMDevLoopbackPolicy;
+
+// src/core/OIMDevBridge.ts
+var OIM_REQUEST_TIMEOUT_MS = 5e3;
+var OIMDevBridge = class {
+  constructor(bridgeOptions) {
+    this.bridgeOptions = bridgeOptions;
+    this.messageReader = new OIMDevBridgeMessageReader();
+    this.pending = /* @__PURE__ */ new Map();
+    this.webSocketServer = null;
+    this.devConnectedBrowser = null;
+  }
+  get connectedBrowser() {
+    return this.devConnectedBrowser;
+  }
+  /**
+   * May a page use this bridge?
+   *
+   * From this machine, or named by whoever started the server. An ABSENT
+   * origin is a non-browser client — a CLI, a test — and is allowed; the
+   * literal `'null'` is not, because a sandboxed iframe on any site can send
+   * exactly that.
+   */
+  isOriginAllowed(origin) {
+    if (origin === void 0 || origin === "") return true;
+    if (this.bridgeOptions.allowedOrigins.has(origin)) return true;
+    return OIMDevLoopbackPolicy.isLoopbackOrigin(origin);
+  }
+  request(action) {
+    const browser = this.devConnectedBrowser;
+    if (browser === null) {
+      return Promise.reject(
+        new Error(this.bridgeOptions.requestTimeoutMessage)
+      );
+    }
+    return new Promise((resolve, reject) => {
+      const id = Math.random().toString(36).slice(2);
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(this.bridgeOptions.requestTimeoutMessage));
+      }, OIM_REQUEST_TIMEOUT_MS);
+      this.pending.set(id, { resolve, reject, timer });
+      browser.ws.send(JSON.stringify({ type: "request", id, action }));
+    });
+  }
+  start() {
+    this.webSocketServer = new import_ws.WebSocketServer({
+      port: this.bridgeOptions.wsPort,
+      host: this.bridgeOptions.host,
+      verifyClient: (info) => this.isOriginAllowed(info.origin)
+    });
+    this.webSocketServer.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        this.write(
+          `Port ${this.bridgeOptions.wsPort} is already in use.
+`
+        );
+        process.stderr.write(
+          `Set a different port: OIMDB_WS_PORT=7433 ${this.bridgeOptions.portInUseHint}
+`
+        );
+        process.exit(1);
+      }
+      this.write(`Bridge error: ${err.message}
+`);
+      process.exit(1);
+    });
+    this.webSocketServer.on("connection", (ws) => {
+      ws.on("error", (err) => {
+        this.write(`Bridge socket error: ${err.message}
+`);
+      });
+      ws.on("message", (raw) => this.readFrame(ws, raw.toString()));
+      ws.on("close", () => {
+        if (this.devConnectedBrowser?.ws === ws) {
+          this.devConnectedBrowser = null;
+          this.write("Browser disconnected\n");
+        }
+      });
+    });
+    this.write(
+      `Bridge ready on ws://localhost:${this.bridgeOptions.wsPort} (bound to ${this.bridgeOptions.host})
+`
+    );
+  }
+  readFrame(ws, raw) {
+    const devBridgeMessage = this.messageReader.read(raw);
+    if (devBridgeMessage === null) {
+      this.write("Dropping a client that sent a malformed frame\n");
+      ws.close(1007, "Malformed bridge message");
+      return;
+    }
+    if (devBridgeMessage.type === "hello") {
+      this.adoptBrowser(ws, devBridgeMessage.url, devBridgeMessage.title);
+      return;
+    }
+    if (this.devConnectedBrowser?.ws !== ws) return;
+    const devPendingRequest = this.pending.get(devBridgeMessage.id);
+    if (!devPendingRequest) return;
+    this.pending.delete(devBridgeMessage.id);
+    clearTimeout(devPendingRequest.timer);
+    if (devBridgeMessage.error) devPendingRequest.reject(new Error(devBridgeMessage.error));
+    else devPendingRequest.resolve(devBridgeMessage.data);
+  }
+  /**
+   * Newest tab wins — a reload is the ordinary reason for a second `hello` —
+   * but the tab it displaces is CLOSED and the swap is printed. Overwriting the
+   * field in place leaves the displaced socket open for ever and lets a second
+   * connection take the bridge over in silence.
+   */
+  adoptBrowser(ws, url, title) {
+    const previousDevConnectedBrowser = this.devConnectedBrowser;
+    this.devConnectedBrowser = { ws, url, title };
+    if (previousDevConnectedBrowser !== null && previousDevConnectedBrowser.ws !== ws) {
+      this.write(
+        `Bridge taken over by "${title}" (${url}); dropping "${previousDevConnectedBrowser.title}"
+`
+      );
+      previousDevConnectedBrowser.ws.close(1e3, "Replaced by a newer OIMDB DevTools tab");
+      return;
+    }
+    this.write(`Browser connected: ${title} (${url})
+`);
+  }
+  write(line) {
+    process.stderr.write(`${this.bridgeOptions.logPrefix} ${line}`);
+  }
+};
+
+// src/core/OIMDevMcpServer.ts
 async function loadRegistryFromModule(path) {
   const url = (0, import_node_url.pathToFileURL)((0, import_node_path.resolve)(path)).href;
   const mod = await import(url);
-  let candidate = mod.registry ?? mod.default ?? mod;
+  let candidate = mod.oimDevRegistry ?? mod.default ?? mod;
   if (typeof candidate === "function") {
     candidate = await candidate();
   }
   if (!candidate || typeof candidate.inspect !== "function" || typeof candidate.dumpString !== "function") {
     throw new Error(
-      `[OIMDB MCP] Module "${path}" must export a registry exposing inspect() and dumpString() (as a "registry" or default export, or a zero-arg factory returning one).`
+      `[OIMDB MCP] Module "${path}" must export a registry exposing inspect() and dumpString() (as an "oimDevRegistry" or default export, or a zero-arg factory returning one).`
     );
   }
   return candidate;
 }
 var OIMDevMcpServer = class {
   constructor(options = {}) {
-    this.wss = null;
-    this.latestBrowser = null;
-    this.pending = /* @__PURE__ */ new Map();
     this.modelModuleLoaded = false;
     this.wsPort = options.wsPort ?? 7432;
+    this.bridge = new OIMDevBridge({
+      wsPort: this.wsPort,
+      host: options.host ?? "127.0.0.1",
+      allowedOrigins: new Set(options.allowedOrigins ?? []),
+      logPrefix: "[OIMDB MCP]",
+      portInUseHint: "npx @oimdb/mcp",
+      requestTimeoutMessage: "Browser response timeout (5s). Is the page active?"
+    });
     this.inProcessRegistry = options.registry ?? null;
     this.modelModulePath = options.modelModulePath;
     this.mcpServer = new import_mcp.McpServer(
@@ -83,17 +277,17 @@ var OIMDevMcpServer = class {
   async readInspect() {
     const registry = await this.getInProcessRegistry();
     if (registry) return registry.inspect();
-    return this.queryBrowser("inspect");
+    return this.requestBrowser("inspect");
   }
   /** Reads the human-readable dump from the in-process model or the browser. */
   async readDump() {
     const registry = await this.getInProcessRegistry();
     if (registry) return registry.dumpString();
-    return await this.queryBrowser("dump");
+    return await this.requestBrowser("dump");
   }
   registerTools() {
     const server = this.mcpServer;
-    const nameSchema = { name: import_zod.z.string().describe("Registered name") };
+    const nameSchema = { name: import_zod2.z.string().describe("Registered name") };
     server.registerTool("oimdb_inspect", {
       description: "Get full state of all registered OIMDB collections and computeds. Returns structured JSON with entity counts, field names, index keys, relations, and computed statuses. Source is the connected browser tab, or an in-process model when one is configured (offline/static \u2014 field names appear only if the model holds sample entities)."
     }, async () => {
@@ -101,7 +295,7 @@ var OIMDevMcpServer = class {
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool("oimdb_dump", {
-      description: "Get a human-readable text summary of OIMDB state. Same output as registry.dump(). Reads the connected browser tab or an in-process model when configured."
+      description: "Get a human-readable text summary of OIMDB state. Same output as oimDevRegistry.dump(). Reads the connected browser tab or an in-process model when configured."
     }, async () => {
       const text = await this.readDump();
       return { content: [{ type: "text", text }] };
@@ -131,76 +325,22 @@ var OIMDevMcpServer = class {
       return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
     });
   }
-  async queryBrowser(action) {
-    if (!this.latestBrowser) {
+  requestBrowser(action) {
+    if (this.bridge.connectedBrowser === null) {
       throw new Error(
         `No browser tab connected to the OIMDB MCP bridge.
 
 Live mode \u2014 add to your debug entry point:
-  import { registry } from '@oimdb/devtools';
-  registry.connect(); // connects to ws://localhost:${this.wsPort}
+  import { oimDevRegistry } from '@oimdb/devtools';
+  oimDevRegistry.connect(); // connects to ws://localhost:${this.wsPort}
 Then reload the page.
 
 Offline mode \u2014 point the server at a model module instead:
   OIMDB_MODEL_MODULE=./path/to/model.js npx @oimdb/mcp
-(the module exports a "registry" with inspect()/dumpString()).`
+(the module exports an "oimDevRegistry" with inspect()/dumpString()).`
       );
     }
-    return new Promise((resolve, reject) => {
-      const id = Math.random().toString(36).slice(2);
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error("Browser response timeout (5s). Is the page active?"));
-      }, 5e3);
-      this.pending.set(id, { resolve, reject, timer });
-      this.latestBrowser.ws.send(JSON.stringify({ type: "request", id, action }));
-    });
-  }
-  setupWebSocketServer() {
-    this.wss = new import_ws.WebSocketServer({ port: this.wsPort });
-    this.wss.on("error", (err) => {
-      if (err.code === "EADDRINUSE") {
-        process.stderr.write(
-          `[OIMDB MCP] Port ${this.wsPort} is already in use.
-Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp
-`
-        );
-        process.exit(1);
-      }
-      process.stderr.write(`[OIMDB MCP] WebSocket server error: ${err.message}
-`);
-      process.exit(1);
-    });
-    this.wss.on("connection", (ws) => {
-      ws.on("message", (raw) => {
-        const msg = JSON.parse(raw.toString());
-        if (msg.type === "hello") {
-          this.latestBrowser = { ws, url: msg.url, title: msg.title };
-          process.stderr.write(`[OIMDB MCP] Browser connected: ${msg.title} (${msg.url})
-`);
-          return;
-        }
-        if (msg.type === "response") {
-          const pending = this.pending.get(msg.id);
-          if (!pending) return;
-          this.pending.delete(msg.id);
-          clearTimeout(pending.timer);
-          if (msg.error) {
-            pending.reject(new Error(msg.error));
-          } else {
-            pending.resolve(msg.data);
-          }
-        }
-      });
-      ws.on("close", () => {
-        if (this.latestBrowser?.ws === ws) {
-          this.latestBrowser = null;
-          process.stderr.write("[OIMDB MCP] Browser disconnected\n");
-        }
-      });
-    });
-    process.stderr.write(`[OIMDB MCP] Bridge ready on ws://localhost:${this.wsPort}
-`);
+    return this.bridge.request(action);
   }
   async start() {
     const registry = await this.getInProcessRegistry();
@@ -209,7 +349,7 @@ Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp
         "[OIMDB MCP] In-process model loaded \u2014 serving offline (no browser bridge).\n"
       );
     } else {
-      this.setupWebSocketServer();
+      this.bridge.start();
     }
     const transport = new import_stdio.StdioServerTransport();
     await this.mcpServer.connect(transport);
@@ -218,90 +358,88 @@ Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp
 
 // src/core/OIMDevUIServer.ts
 var import_http = require("http");
+var import_child_process = require("child_process");
+
+// src/core/OIMDevUIAssetCatalog.ts
 var import_fs = require("fs");
 var import_path = require("path");
-var import_child_process = require("child_process");
-var import_ws2 = require("ws");
-var MIME = {
-  ".html": "text/html; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".css": "text/css; charset=utf-8"
+var _OIMDevUIAssetCatalog = class _OIMDevUIAssetCatalog {
+  constructor(uiDir) {
+    this.uiDir = uiDir;
+  }
+  resolve(requestUrl) {
+    const path = requestUrl.split("?", 1)[0].split("#", 1)[0];
+    return _OIMDevUIAssetCatalog.ASSETS.get(path) ?? null;
+  }
+  // Per request, so the UI stays editable; the constant file name is what
+  // makes that safe, not the timing.
+  read(asset) {
+    return (0, import_fs.readFileSync)((0, import_path.join)(this.uiDir, asset.fileName));
+  }
 };
+_OIMDevUIAssetCatalog.ASSETS = /* @__PURE__ */ new Map([
+  ["/", { fileName: "index.html", contentType: "text/html; charset=utf-8" }],
+  ["/index.html", { fileName: "index.html", contentType: "text/html; charset=utf-8" }],
+  ["/app.js", { fileName: "app.js", contentType: "text/javascript; charset=utf-8" }],
+  ["/app.css", { fileName: "app.css", contentType: "text/css; charset=utf-8" }]
+]);
+var OIMDevUIAssetCatalog = _OIMDevUIAssetCatalog;
+
+// src/core/OIMDevUIServer.ts
 var OIMDevUIServer = class {
   constructor(options) {
-    this.wss = null;
-    this.latestBrowser = null;
-    this.pending = /* @__PURE__ */ new Map();
-    this.wsPort = options.wsPort ?? 7432;
     this.uiPort = options.uiPort ?? 7433;
-    this.uiDir = options.uiDir;
     this.shouldOpen = options.open ?? true;
-  }
-  async queryBrowser(action) {
-    if (!this.latestBrowser) return null;
-    return new Promise((resolve, reject) => {
-      const id = Math.random().toString(36).slice(2);
-      const timer = setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error("timeout"));
-      }, 5e3);
-      this.pending.set(id, { resolve, reject, timer });
-      this.latestBrowser.ws.send(JSON.stringify({ type: "request", id, action }));
+    this.host = options.host ?? "127.0.0.1";
+    this.allowedOrigins = new Set(options.allowedOrigins ?? []);
+    this.devUIAssetCatalog = new OIMDevUIAssetCatalog(options.uiDir);
+    this.bridge = new OIMDevBridge({
+      wsPort: options.wsPort ?? 7432,
+      host: this.host,
+      allowedOrigins: this.allowedOrigins,
+      logPrefix: "[OIMDB DevTools]",
+      portInUseHint: "npx @oimdb/mcp devtools",
+      requestTimeoutMessage: "timeout"
     });
   }
-  setupBridge() {
-    this.wss = new import_ws2.WebSocketServer({ port: this.wsPort });
-    this.wss.on("error", (err) => {
-      if (err.code === "EADDRINUSE") {
-        process.stderr.write(
-          `[OIMDB DevTools] Port ${this.wsPort} is already in use.
-Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp devtools
-`
-        );
-        process.exit(1);
-      }
-      process.stderr.write(`[OIMDB DevTools] Bridge error: ${err.message}
-`);
-      process.exit(1);
-    });
-    this.wss.on("connection", (ws) => {
-      ws.on("message", (raw) => {
-        const msg = JSON.parse(raw.toString());
-        if (msg.type === "hello") {
-          this.latestBrowser = { ws, url: msg.url, title: msg.title };
-          process.stderr.write(`[OIMDB DevTools] Browser connected: ${msg.title} (${msg.url})
-`);
-          return;
-        }
-        if (msg.type === "response") {
-          const req = this.pending.get(msg.id);
-          if (!req) return;
-          this.pending.delete(msg.id);
-          clearTimeout(req.timer);
-          if (msg.error) req.reject(new Error(msg.error));
-          else req.resolve(msg.data);
-        }
-      });
-      ws.on("close", () => {
-        if (this.latestBrowser?.ws === ws) {
-          this.latestBrowser = null;
-          process.stderr.write("[OIMDB DevTools] Browser disconnected\n");
-        }
-      });
-    });
-    process.stderr.write(`[OIMDB DevTools] Bridge on ws://localhost:${this.wsPort}
-`);
+  /**
+   * While bound to loopback, answer only what was addressed to a loopback
+   * name.
+   *
+   * Without this, a page on any site can point a hostname it controls at
+   * 127.0.0.1 and become same-origin with this server. The `Host` header is
+   * the part of that a browser cannot forge. Binding elsewhere is an explicit
+   * decision, so the check stands down there.
+   */
+  isRequestAddressedHere(req) {
+    if (!OIMDevLoopbackPolicy.isLoopbackHost(this.host)) return true;
+    const host = req.headers.host;
+    return host !== void 0 && OIMDevLoopbackPolicy.isLoopbackAuthority(host);
+  }
+  requestBrowser(action) {
+    if (this.bridge.connectedBrowser === null) return Promise.resolve(null);
+    return this.bridge.request(action);
   }
   setupHTTP() {
     const server = (0, import_http.createServer)((req, res) => {
+      if (!this.isRequestAddressedHere(req)) {
+        res.writeHead(421);
+        res.end("Misdirected request");
+        return;
+      }
+      const origin = req.headers.origin;
+      if (origin !== void 0 && this.allowedOrigins.has(origin)) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+      }
       const url = req.url ?? "/";
-      res.setHeader("Access-Control-Allow-Origin", "*");
-      if (url === "/api/inspect") {
-        this.queryBrowser("inspect").then((data) => {
+      if (url.split("?", 1)[0] === "/api/inspect") {
+        this.requestBrowser("inspect").then((data) => {
           res.writeHead(200, { "Content-Type": "application/json" });
+          const connectedBrowser = this.bridge.connectedBrowser;
           res.end(JSON.stringify({
-            connected: !!this.latestBrowser,
-            tab: this.latestBrowser ? { url: this.latestBrowser.url, title: this.latestBrowser.title } : null,
+            connected: connectedBrowser !== null,
+            tab: connectedBrowser === null ? null : { url: connectedBrowser.url, title: connectedBrowser.title },
             data
           }));
         }).catch(() => {
@@ -310,11 +448,15 @@ Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp devtools
         });
         return;
       }
-      const filePath = (0, import_path.join)(this.uiDir, url === "/" ? "index.html" : url);
+      const asset = this.devUIAssetCatalog.resolve(url);
+      if (asset === null) {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
       try {
-        const content = (0, import_fs.readFileSync)(filePath);
-        res.writeHead(200, { "Content-Type": MIME[(0, import_path.extname)(filePath)] ?? "text/plain" });
-        res.end(content);
+        res.writeHead(200, { "Content-Type": asset.contentType });
+        res.end(this.devUIAssetCatalog.read(asset));
       } catch {
         res.writeHead(404);
         res.end("Not found");
@@ -330,9 +472,9 @@ Set a different port: OIMDB_UI_PORT=7434 npx @oimdb/mcp devtools
         process.exit(1);
       }
     });
-    server.listen(this.uiPort, () => {
+    server.listen(this.uiPort, this.host, () => {
       const uiUrl = `http://localhost:${this.uiPort}`;
-      process.stderr.write(`[OIMDB DevTools] UI ready \u2192 ${uiUrl}
+      process.stderr.write(`[OIMDB DevTools] UI ready \u2192 ${uiUrl} (bound to ${this.host})
 `);
       if (this.shouldOpen) this.openURL(uiUrl);
     });
@@ -345,10 +487,10 @@ Set a different port: OIMDB_UI_PORT=7434 npx @oimdb/mcp devtools
     });
   }
   start() {
-    this.setupBridge();
+    this.bridge.start();
     this.setupHTTP();
     process.stderr.write(
-      `[OIMDB DevTools] Add to debug.ts: registry.connect();
+      `[OIMDB DevTools] Add to debug.ts: oimDevRegistry.connect();
 `
     );
   }

package/dist/index.d.cts

@@ -1,37 +1,24 @@
-/**
- * The readable shape the MCP tools need from a registry — `OIMDevRegistry` from
- * `@oimdb/devtools` already satisfies it. Declared structurally (following the
- * existing `IOIMDev*Like` convention) so `@oimdb/mcp` need not depend on
- * `@oimdb/devtools`; it is not a separate registry implementation.
- */
-interface IOIMDevRegistryLike {
+interface IOIMDevRegistry {
     inspect(): unknown;
     dumpString(): string;
 }
+
 type TOIMDevMcpOptions = {
-    /** Port for the WebSocket bridge that browser tabs connect to. Default: 7432 */
+    /** Default 7432; unused when `registry` is given — no bridge is started. */
     wsPort?: number;
-    /**
-     * An in-process registry to read directly (your `OIMDevRegistry`). When
-     * provided, the tools answer from it without a browser/WebSocket bridge
-     * (no `wsPort` server started).
-     */
-    registry?: IOIMDevRegistryLike;
-    /**
-     * Path to a module that builds the model in this process for offline
-     * introspection. The module must export a `registry` (or a default export,
-     * or a zero-arg factory) exposing `inspect()` and `dumpString()`.
-     * Also settable via the `OIMDB_MODEL_MODULE` env var for the CLI.
-     */
+    registry?: IOIMDevRegistry;
+    /** Must export `oimDevRegistry`, a default, or a zero-arg factory. Env: `OIMDB_MODEL_MODULE`. */
     modelModulePath?: string;
+    /** LOOPBACK BY DEFAULT: a `WebSocketServer` built without a host binds everything. */
+    host?: string;
+    /** On top of the loopback origins. Exact, never `'*'`. */
+    allowedOrigins?: readonly string[];
 };
 
 declare class OIMDevMcpServer {
     private readonly mcpServer;
     private readonly wsPort;
-    private wss;
-    private latestBrowser;
-    private readonly pending;
+    private readonly bridge;
     private inProcessRegistry;
     private readonly modelModulePath?;
     private modelModuleLoaded;
@@ -46,8 +33,7 @@ declare class OIMDevMcpServer {
     /** Reads the human-readable dump from the in-process model or the browser. */
     private readDump;
     private registerTools;
-    private queryBrowser;
-    private setupWebSocketServer;
+    private requestBrowser;
     start(): Promise<void>;
 }
 
@@ -56,18 +42,46 @@ type TOIMDevUIServerOptions = {
     uiPort?: number;
     uiDir: string;
     open?: boolean;
+    /**
+     * The interface both ports bind to. LOOPBACK BY DEFAULT: a tool that hands
+     * out the application's entire data model has no business being reachable
+     * from the café Wi-Fi, and `listen` without a host binds every interface.
+     *
+     * Set it — `'0.0.0.0'` — when the browser genuinely runs somewhere else: a
+     * container, a VM, a phone. That is an opt-in to everyone who can route
+     * there reading the model.
+     */
+    host?: string;
+    /**
+     * Page origins allowed onto the bridge and allowed to read `/api/inspect`,
+     * on top of the loopback origins allowed by default.
+     *
+     * Exact origins (`'http://app.test:3000'`). Never `'*'`: with that on every
+     * response, any page in any tab the developer has open can read every entity
+     * of every registered collection.
+     */
+    allowedOrigins?: readonly string[];
 };
+
 declare class OIMDevUIServer {
-    private readonly wsPort;
     private readonly uiPort;
-    private readonly uiDir;
     private readonly shouldOpen;
-    private wss;
-    private latestBrowser;
-    private readonly pending;
+    private readonly host;
+    private readonly allowedOrigins;
+    private readonly devUIAssetCatalog;
+    private readonly bridge;
     constructor(options: TOIMDevUIServerOptions);
-    private queryBrowser;
-    private setupBridge;
+    /**
+     * While bound to loopback, answer only what was addressed to a loopback
+     * name.
+     *
+     * Without this, a page on any site can point a hostname it controls at
+     * 127.0.0.1 and become same-origin with this server. The `Host` header is
+     * the part of that a browser cannot forge. Binding elsewhere is an explicit
+     * decision, so the check stands down there.
+     */
+    private isRequestAddressedHere;
+    private requestBrowser;
     private setupHTTP;
     private openURL;
     start(): void;
@@ -76,4 +90,4 @@ declare class OIMDevUIServer {
 declare function createOIMDevMcpServer(options?: TOIMDevMcpOptions): OIMDevMcpServer;
 declare function createOIMDevUIServer(options: TOIMDevUIServerOptions): OIMDevUIServer;
 
-export { type IOIMDevRegistryLike, OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };
+export { type IOIMDevRegistry, OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };