@guardion/guardion 0.2.0 → 0.4.0

package/dist/core/mcp/jsonrpc.cjs

@@ -0,0 +1,194 @@
+'use strict';
+/**
+ * JSON-RPC / MCP framing + helpers shared by every transport.
+ *
+ * Zero-dep (node builtins only) so the interposer runs when launched by arbitrary
+ * hosts without node_modules. Pure functions — unit-testable standalone.
+ */
+
+// Canonical Guard message roles for the two MCP scan directions. These MUST match
+// Guard's MessagesRole enum (guard/guard/core/schemas.py) — `tool_response`, NOT
+// `tool_output` (which is a Target name, not a role). A mismatch makes /v1/guard
+// 422 and silently fail-open, so both directions are pinned here once.
+const ROLES = { input: 'tool_input', output: 'tool_response' };
+
+// Keys that hold base64 binary — never sent for detection, never rewritten.
+const BINARY_KEYS = new Set(['data', 'blob']);
+// MCP structural / metadata keys carried alongside text in result shapes. Skipped
+// when walking result content so we only redact human-readable text leaves.
+const META_KEYS = new Set(['type', 'mimeType', 'annotations', '_meta', 'role', 'isError', 'size']);
+
+/** Incremental newline-delimited JSON-RPC framer (stdio / SSE data lines). */
+class LineFramer {
+  constructor() { this.buf = ''; }
+  /** Feed a chunk; returns the complete lines it produced (trailing partial kept). */
+  push(chunk) {
+    this.buf += chunk;
+    const out = [];
+    let nl;
+    while ((nl = this.buf.indexOf('\n')) >= 0) {
+      const line = this.buf.slice(0, nl);
+      this.buf = this.buf.slice(nl + 1);
+      if (line.trim()) out.push(line);
+    }
+    return out;
+  }
+}
+
+function parse(line) {
+  try { return JSON.parse(line); } catch { return null; }
+}
+
+function serialize(obj) {
+  return JSON.stringify(obj);
+}
+
+function isRequest(msg) {
+  return !!(msg && typeof msg === 'object' && msg.method && msg.id != null);
+}
+function isNotification(msg) {
+  return !!(msg && typeof msg === 'object' && msg.method && msg.id == null);
+}
+function isResponse(msg) {
+  return !!(msg && typeof msg === 'object' && msg.id != null && !msg.method
+    && (Object.prototype.hasOwnProperty.call(msg, 'result')
+      || Object.prototype.hasOwnProperty.call(msg, 'error')));
+}
+
+function rpcError(id, message, code) {
+  return { jsonrpc: '2.0', id: id == null ? null : id, error: { code: code || -32000, message } };
+}
+
+/** Flatten an MCP tool/resource/prompt result into scannable text. */
+function resultText(result) {
+  try {
+    if (result && Array.isArray(result.content)) {                 // tools/call
+      return result.content.map((c) => (c && typeof c.text === 'string' ? c.text : '')).join('\n');
+    }
+    if (result && Array.isArray(result.contents)) {                // resources/read
+      return result.contents.map((c) => (c && typeof c.text === 'string' ? c.text : '')).join('\n');
+    }
+    if (result && Array.isArray(result.messages)) {                // prompts/get
+      return result.messages.map((m) => {
+        const c = m && m.content;
+        if (c && typeof c.text === 'string') return c.text;
+        return typeof c === 'string' ? c : '';
+      }).join('\n');
+    }
+  } catch { /* ignore */ }
+  return typeof result === 'string' ? result : JSON.stringify(result || '');
+}
+
+/** Replace the textual payload of a result in place with `text` (best-effort SANITIZE). */
+function replaceResultText(result, text) {
+  if (!result || typeof result !== 'object') return result;
+  if (Array.isArray(result.content)) { result.content = [{ type: 'text', text }]; return result; }
+  if (Array.isArray(result.contents)) {
+    const uri = (result.contents[0] && result.contents[0].uri) || '';
+    result.contents = [{ uri, mimeType: 'text/plain', text }];
+    return result;
+  }
+  if (Array.isArray(result.messages)) {
+    result.messages = [{ role: 'user', content: { type: 'text', text } }];
+    return result;
+  }
+  return result;
+}
+
+/** Extract the text a server-initiated sampling/createMessage wants the host LLM to run. */
+function samplingText(params) {
+  if (!params || typeof params !== 'object') return '';
+  const parts = [];
+  if (typeof params.systemPrompt === 'string') parts.push(params.systemPrompt);
+  for (const m of (Array.isArray(params.messages) ? params.messages : [])) {
+    const c = m && m.content;
+    if (c && typeof c.text === 'string') parts.push(c.text);
+    else if (typeof c === 'string') parts.push(c);
+  }
+  return parts.join('\n');
+}
+
+// ── leaf-level, structure-preserving redaction ───────────────────────────────
+// Detection/redaction is a string transform: we extract every human-readable
+// string leaf (with its JSON path), let Guard redact each, then write the result
+// back IN PLACE — so multiple content blocks, structuredContent, images/audio,
+// blobs, isError, _meta and mimeType all survive untouched. Guard never has to
+// reserialize an MCP payload.
+
+/** Recursively collect string leaves of `node` as { path, text }. Skips base64
+ *  binary keys always; skips MCP metadata keys when `skipMeta` (result shapes). */
+function collectStringLeaves(node, basePath, out, skipMeta) {
+  if (node == null) return out;
+  if (typeof node === 'string') { out.push({ path: basePath.slice(), text: node }); return out; }
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) collectStringLeaves(node[i], basePath.concat(i), out, skipMeta);
+    return out;
+  }
+  if (typeof node === 'object') {
+    for (const k of Object.keys(node)) {
+      // Skip MCP binary (base64) + structural/metadata keys ONLY in result shapes
+      // (skipMeta). Tool-input arguments are arbitrary tool-defined keys — a field
+      // named `data`/`blob`/`type` there can be redactable text, so scan it.
+      if (skipMeta && (BINARY_KEYS.has(k) || META_KEYS.has(k))) continue;
+      collectStringLeaves(node[k], basePath.concat(k), out, skipMeta);
+    }
+  }
+  return out; // numbers / booleans are not redactable text
+}
+
+/** Redactable string leaves of a tool-call INPUT (relative to `params`). */
+function collectInputLeaves(method, params) {
+  const out = [];
+  if (!params || typeof params !== 'object') return out;
+  if (method === 'tools/call' || method === 'prompts/get') {
+    collectStringLeaves(params.arguments, ['arguments'], out, false); // arbitrary tool keys
+  } else if (method === 'resources/read') {
+    if (typeof params.uri === 'string') out.push({ path: ['uri'], text: params.uri });
+  }
+  return out;
+}
+
+/** Redactable string leaves of a tool/resource/prompt OUTPUT (relative to `result`). */
+function collectOutputLeaves(method, result) {
+  const out = [];
+  if (!result || typeof result !== 'object') return out;
+  if (method === 'tools/call') {
+    collectStringLeaves(result.content, ['content'], out, true);                 // text / resource_link / embedded resource text
+    if (result.structuredContent != null) collectStringLeaves(result.structuredContent, ['structuredContent'], out, false);
+  } else if (method === 'resources/read') {
+    collectStringLeaves(result.contents, ['contents'], out, true);               // TextResourceContents.text / .uri (blob skipped)
+  } else if (method === 'prompts/get') {
+    collectStringLeaves(result.messages, ['messages'], out, true);
+  }
+  return out;
+}
+
+function setByPath(root, p, value) {
+  let n = root;
+  for (let i = 0; i < p.length - 1; i++) { if (n == null) return; n = n[p[i]]; }
+  if (n != null && p.length) n[p[p.length - 1]] = value;
+}
+
+/** Write redacted strings back into `root` by path, preserving everything else. */
+function applyLeaves(root, leaves) {
+  for (const l of (leaves || [])) {
+    if (l && Array.isArray(l.path) && typeof l.text === 'string') setByPath(root, l.path, l.text);
+  }
+  return root;
+}
+
+function paramsToList(inputSchema) {
+  const props = inputSchema && inputSchema.properties ? inputSchema.properties : {};
+  return Object.keys(props).map((k) => ({
+    name: k,
+    type: (props[k] && props[k].type) || '',
+    description: (props[k] && props[k].description) || '',
+  }));
+}
+
+module.exports = {
+  ROLES,
+  LineFramer, parse, serialize, isRequest, isNotification, isResponse,
+  rpcError, resultText, replaceResultText, samplingText, paramsToList,
+  collectStringLeaves, collectInputLeaves, collectOutputLeaves, applyLeaves, setByPath,
+};

package/dist/core/mcp/transport/http-server-side.cjs

@@ -0,0 +1,89 @@
+'use strict';
+/**
+ * Streamable-HTTP MCP server endpoint (the side a host connects TO). Reused by
+ * http_input (stdio upstream) and http_reverse (HTTP upstream).
+ *
+ *   • POST <path>  a JSON-RPC message → routed to onInbound; the matching
+ *     response (correlated by id) is written back on that same connection as
+ *     application/json. Notification-only POSTs get 202 Accepted.
+ *   • GET  <path>  (Accept: text/event-stream) → a server→client SSE stream that
+ *     carries server-initiated messages (e.g. sampling/createMessage) and any
+ *     emit() not tied to a pending POST.
+ *
+ * Zero-dep. emit(obj) routes a message to the right place (pending POST or SSE).
+ */
+const http = require('http');
+const J = require('../jsonrpc.cjs');
+
+function createHttpServerSide(opts) {
+  const { port = 0, host = '127.0.0.1', mcpPath = '/', log = () => {} } = opts;
+  let _onInbound = () => {};
+  const pendingPost = new Map();   // request id → http.ServerResponse
+  const sseClients = new Set();    // open GET streams (http.ServerResponse)
+
+  function writeJson(res, obj, code) {
+    const body = J.serialize(obj);
+    res.writeHead(code || 200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+    res.end(body);
+  }
+
+  const server = http.createServer((req, res) => {
+    const url = req.url || '/';
+    if (req.method === 'GET' && url.startsWith(mcpPath)) {
+      if (!String(req.headers.accept || '').includes('text/event-stream')) { res.writeHead(405).end(); return; }
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+      sseClients.add(res);
+      req.on('close', () => sseClients.delete(res));
+      return;
+    }
+    if (req.method === 'POST' && url.startsWith(mcpPath)) {
+      let b = ''; req.setEncoding('utf8');
+      req.on('data', (c) => { b += c; });
+      req.on('end', () => {
+        let parsed = J.parse(b);
+        if (parsed == null) { res.writeHead(400).end(); return; }
+        const batch = Array.isArray(parsed) ? parsed : [parsed];
+        const reqIds = batch.filter((m) => J.isRequest(m)).map((m) => m.id);
+        if (reqIds.length === 0) {                 // notifications/responses only
+          res.writeHead(202).end();
+          for (const m of batch) Promise.resolve(_onInbound(m)).catch(() => {});
+          return;
+        }
+        // hold the connection until the (first) request's response is emitted
+        pendingPost.set(reqIds[0], res);
+        req.on('close', () => { if (pendingPost.get(reqIds[0]) === res) pendingPost.delete(reqIds[0]); });
+        for (const m of batch) Promise.resolve(_onInbound(m)).catch(() => {});
+        return;
+      });
+      return;
+    }
+    res.writeHead(404).end();
+  });
+
+  function emit(obj) {
+    if (J.isResponse(obj) && pendingPost.has(obj.id)) {
+      const res = pendingPost.get(obj.id); pendingPost.delete(obj.id);
+      try { writeJson(res, obj); } catch { /* client gone */ }
+      return;
+    }
+    // server-initiated request/notification → broadcast on the SSE stream(s)
+    const frame = `data: ${J.serialize(obj)}\n\n`;
+    for (const c of sseClients) { try { c.write(frame); } catch { sseClients.delete(c); } }
+  }
+
+  function listen() {
+    return new Promise((resolve) => {
+      server.listen(port, host, () => {
+        const addr = server.address();
+        log(`http endpoint listening on http://${host}:${addr.port}${mcpPath}`);
+        resolve(addr.port);
+      });
+    });
+  }
+
+  function close() { try { server.close(); } catch { /* ignore */ } for (const c of sseClients) { try { c.end(); } catch { /* ignore */ } } }
+
+  return { emit, listen, close, onInbound(cb) { _onInbound = cb || (() => {}); }, get port() { const a = server.address(); return a && a.port; } };
+}
+
+module.exports = { createHttpServerSide };

package/dist/core/mcp/transport/http-upstream.cjs

@@ -0,0 +1,111 @@
+'use strict';
+/**
+ * Streamable-HTTP MCP upstream client (spec 2025-03-26). Talks to a remote MCP
+ * server over HTTP so the interposer can govern URL servers — not just stdio.
+ *
+ *   • POST <url>  with a JSON-RPC message; the response is either
+ *       application/json      → a single JSON-RPC message, or
+ *       text/event-stream     → SSE frames, each `data:` a JSON-RPC message
+ *       (the server may interleave its own requests, e.g. sampling/createMessage)
+ *   • GET  <url>  (Accept: text/event-stream) → a standalone server→client stream
+ *   • the server may issue an `Mcp-Session-Id` header on initialize; we echo it
+ *
+ * Zero-dep. Routes every inbound JSON-RPC message to the registered onMessage.
+ */
+const http = require('http');
+const https = require('https');
+const J = require('../jsonrpc.cjs');
+
+function createHttpUpstream(opts) {
+  const { url, headers = {}, timeout = 30000, log = () => {} } = opts;
+  let u; try { u = new URL(url); } catch { throw new Error(`bad upstream url: ${url}`); }
+  const tr = u.protocol === 'https:' ? https : http;
+  let sessionId = '';
+  let _onMessage = () => {};
+
+  function baseHeaders(extra) {
+    const h = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json, text/event-stream',
+      ...headers,
+    };
+    if (sessionId) h['Mcp-Session-Id'] = sessionId;
+    return Object.assign(h, extra || {});
+  }
+
+  // Parse an SSE body incrementally and emit each data payload as a message.
+  function makeSseConsumer() {
+    let buf = '';
+    return (chunk) => {
+      buf += chunk;
+      let idx;
+      while ((idx = buf.indexOf('\n\n')) >= 0) {
+        const frame = buf.slice(0, idx); buf = buf.slice(idx + 2);
+        const data = frame.split('\n')
+          .filter((l) => l.startsWith('data:'))
+          .map((l) => l.slice(5).trim()).join('\n');
+        if (!data) continue;
+        const msg = J.parse(data);
+        if (msg) Promise.resolve(_onMessage(msg)).catch(() => {});
+      }
+    };
+  }
+
+  function send(obj) {
+    return new Promise((resolve) => {
+      const body = J.serialize(obj);
+      const req = tr.request({
+        hostname: u.hostname, port: u.port || (u.protocol === 'https:' ? 443 : 80),
+        path: u.pathname + u.search, method: 'POST', timeout,
+        headers: baseHeaders({ 'Content-Length': Buffer.byteLength(body) }),
+      }, (r) => {
+        const sid = r.headers['mcp-session-id'];
+        if (sid) sessionId = Array.isArray(sid) ? sid[0] : sid;
+        const ctype = String(r.headers['content-type'] || '');
+        r.setEncoding('utf8');
+        if (ctype.includes('text/event-stream')) {
+          const consume = makeSseConsumer();
+          r.on('data', consume);
+          r.on('end', () => resolve());
+        } else {
+          let d = '';
+          r.on('data', (c) => { d += c; });
+          r.on('end', () => { const m = J.parse(d); if (m) Promise.resolve(_onMessage(m)).catch(() => {}); resolve(); });
+        }
+      });
+      req.on('error', (e) => { log(`upstream POST error: ${e.message}`); resolve(); });
+      req.on('timeout', () => { req.destroy(); resolve(); });
+      req.write(body); req.end();
+    });
+  }
+
+  // Open the optional standalone server→client SSE stream (best-effort).
+  function startStream() {
+    let req;
+    try {
+      req = tr.request({
+        hostname: u.hostname, port: u.port || (u.protocol === 'https:' ? 443 : 80),
+        path: u.pathname + u.search, method: 'GET',
+        headers: baseHeaders({ 'Accept': 'text/event-stream' }),
+      }, (r) => {
+        if (String(r.headers['content-type'] || '').includes('text/event-stream')) {
+          const consume = makeSseConsumer();
+          r.setEncoding('utf8');
+          r.on('data', consume);
+        } else { r.resume(); }       // server doesn't offer a GET stream — fine
+      });
+      req.on('error', () => {});      // optional; ignore
+      req.end();
+    } catch { /* optional */ }
+    return () => { try { req && req.destroy(); } catch { /* ignore */ } };
+  }
+
+  return {
+    send,
+    startStream,
+    onMessage(cb) { _onMessage = cb || (() => {}); },
+    get sessionId() { return sessionId; },
+  };
+}
+
+module.exports = { createHttpUpstream };

package/dist/core/mcp/transport/http_forward.cjs

@@ -0,0 +1,40 @@
+'use strict';
+/**
+ * http_forward transport: the host launches us over stdio, but the REAL MCP
+ * server is remote (HTTP / streamable-HTTP). We bridge stdio ⇄ HTTP so URL
+ * servers get the same governance as local stdio servers — fixing the gap where
+ * mcp-protect could only interpose stdio commands.
+ *
+ *   client (host)  ⇄  process.stdin / process.stdout   (stdio)
+ *   server (real)  ⇄  POST/GET <url>                    (HTTP)
+ */
+const J = require('../jsonrpc.cjs');
+const { createHttpUpstream } = require('./http-upstream.cjs');
+
+function createHttpForwardChannel(opts) {
+  const { url, headers, timeout, log = () => {} } = opts;
+  const upstream = createHttpUpstream({ url, headers, timeout, log });
+
+  function sendClient(obj) { process.stdout.write(J.serialize(obj) + '\n'); }
+  function sendServer(obj) { return upstream.send(obj); }   // POST; responses routed to onServer
+
+  function start(handlers) {
+    upstream.onMessage((m) => handlers.onServer(m));
+    const inF = new J.LineFramer();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => {
+      for (const line of inF.push(d)) {
+        const msg = J.parse(line);
+        if (msg) Promise.resolve(handlers.onClient(msg)).catch(() => {});
+        // unparseable lines are dropped: HTTP upstream requires JSON-RPC objects
+      }
+    });
+    upstream.startStream();          // optional server→client stream
+  }
+
+  function close() { /* nothing to tear down (no child) */ }
+
+  return { sendClient, sendServer, start, close };
+}
+
+module.exports = { createHttpForwardChannel };

package/dist/core/mcp/transport/http_input.cjs

@@ -0,0 +1,46 @@
+'use strict';
+/**
+ * http_input transport: we LISTEN as a streamable-HTTP MCP server (the host
+ * connects to us over HTTP) and forward to a local stdio MCP server we spawn.
+ * Lets HTTP-speaking hosts get governance in front of a stdio server.
+ *
+ *   client (host)  ⇄  POST/GET <url>   (HTTP, we listen)
+ *   server (real)  ⇄  child.stdin/out  (stdio, we spawn)
+ */
+const { spawn } = require('child_process');
+const J = require('../jsonrpc.cjs');
+const { createHttpServerSide } = require('./http-server-side.cjs');
+
+function createHttpInputChannel(opts) {
+  const { target, env, port, host, mcpPath, onExit, log = () => {} } = opts;
+  if (!Array.isArray(target) || target.length === 0) {
+    throw new Error('http_input transport requires a target command after --');
+  }
+  const child = spawn(target[0], target.slice(1), { stdio: ['pipe', 'pipe', 'inherit'], env: env || process.env });
+  child.on('error', (e) => { log(`spawn error: ${e.message}`); process.exit(1); });
+  child.on('exit', (code) => { if (onExit) onExit(code); });
+
+  const httpSide = createHttpServerSide({ port, host, mcpPath, log });
+
+  function sendClient(obj) { httpSide.emit(obj); }                              // → host (HTTP)
+  function sendServer(obj) { try { child.stdin.write(J.serialize(obj) + '\n'); } catch { /* gone */ } } // → server (stdio)
+
+  function start(handlers) {
+    httpSide.onInbound((m) => handlers.onClient(m));
+    const outF = new J.LineFramer();
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (d) => {
+      for (const line of outF.push(d)) {
+        const msg = J.parse(line);
+        if (msg) Promise.resolve(handlers.onServer(msg)).catch(() => {});
+      }
+    });
+    return httpSide.listen();
+  }
+
+  function close() { try { child.kill(); } catch { /* ignore */ } httpSide.close(); }
+
+  return { sendClient, sendServer, start, close, child, get port() { return httpSide.port; } };
+}
+
+module.exports = { createHttpInputChannel };

package/dist/core/mcp/transport/http_reverse.cjs

@@ -0,0 +1,33 @@
+'use strict';
+/**
+ * http_reverse transport: a full HTTP↔HTTP reverse proxy. We LISTEN as a
+ * streamable-HTTP MCP server for the host AND forward to a remote HTTP MCP
+ * server — governing remote servers for HTTP-speaking hosts with no stdio at all.
+ *
+ *   client (host)  ⇄  POST/GET <listen>   (HTTP, we listen)
+ *   server (real)  ⇄  POST/GET <url>       (HTTP, we forward)
+ */
+const { createHttpServerSide } = require('./http-server-side.cjs');
+const { createHttpUpstream } = require('./http-upstream.cjs');
+
+function createHttpReverseChannel(opts) {
+  const { url, headers, timeout, port, host, mcpPath, log = () => {} } = opts;
+  const httpSide = createHttpServerSide({ port, host, mcpPath, log });
+  const upstream = createHttpUpstream({ url, headers, timeout, log });
+
+  function sendClient(obj) { httpSide.emit(obj); }     // → host (HTTP)
+  function sendServer(obj) { return upstream.send(obj); } // → server (HTTP)
+
+  function start(handlers) {
+    httpSide.onInbound((m) => handlers.onClient(m));
+    upstream.onMessage((m) => handlers.onServer(m));
+    upstream.startStream();
+    return httpSide.listen();
+  }
+
+  function close() { httpSide.close(); }
+
+  return { sendClient, sendServer, start, close, get port() { return httpSide.port; } };
+}
+
+module.exports = { createHttpReverseChannel };

package/dist/core/mcp/transport/index.cjs

@@ -0,0 +1,32 @@
+'use strict';
+/**
+ * Transport factory. Picks the channel implementation from the parsed flags.
+ *
+ *   stdio        spawn a local server, relay over its stdin/stdout (default)
+ *   http_forward stdio host ⇄ remote HTTP server   (--url)
+ *   http_input   HTTP host  ⇄ local stdio server   (--listen, -- cmd)
+ *   http_reverse HTTP host  ⇄ remote HTTP server    (--listen, --url)
+ *   sse_bridge   stdio host ⇄ remote legacy SSE server (--url)
+ *
+ * Every channel exposes the same contract: sendClient / sendServer / start / close.
+ */
+const { createStdioChannel } = require('./stdio.cjs');
+const { createHttpForwardChannel } = require('./http_forward.cjs');
+const { createHttpInputChannel } = require('./http_input.cjs');
+const { createHttpReverseChannel } = require('./http_reverse.cjs');
+const { createSseBridgeChannel } = require('./sse_bridge.cjs');
+
+const TRANSPORTS = new Set(['stdio', 'http_forward', 'http_input', 'http_reverse', 'sse_bridge']);
+
+function selectTransport(kind, opts) {
+  switch (kind) {
+    case 'stdio': return createStdioChannel(opts);
+    case 'http_forward': return createHttpForwardChannel(opts);
+    case 'http_input': return createHttpInputChannel(opts);
+    case 'http_reverse': return createHttpReverseChannel(opts);
+    case 'sse_bridge': return createSseBridgeChannel(opts);
+    default: throw new Error(`unknown transport: ${kind}`);
+  }
+}
+
+module.exports = { selectTransport, TRANSPORTS };

package/dist/core/mcp/transport/sse_bridge.cjs

@@ -0,0 +1,101 @@
+'use strict';
+/**
+ * sse_bridge transport: bridge a legacy SSE MCP server (the pre-2025-03-26 HTTP+SSE
+ * transport) to a stdio-speaking host. The host launches us over stdio; we connect
+ * to the remote server's SSE endpoint.
+ *
+ *   client (host)  ⇄  process.stdin / process.stdout         (stdio)
+ *   server (real)  ⇄  GET <url> (SSE: endpoint + messages)   +  POST <endpoint>
+ *
+ * Legacy SSE handshake: open GET <url>; the server emits an `endpoint` event whose
+ * data is the URL to POST client→server messages to; subsequent `message` events
+ * carry server→client JSON-RPC. We queue outbound sends until the endpoint arrives.
+ */
+const http = require('http');
+const https = require('https');
+const J = require('../jsonrpc.cjs');
+
+function createSseBridgeChannel(opts) {
+  const { url, headers = {}, log = () => {} } = opts;
+  let u; try { u = new URL(url); } catch { throw new Error(`bad sse url: ${url}`); }
+  const tr = u.protocol === 'https:' ? https : http;
+  let messageUrl = null;        // resolved POST endpoint (from the `endpoint` event)
+  const outbox = [];            // sends queued before endpoint is known
+  let _onServer = () => {};
+
+  function sendClient(obj) { process.stdout.write(J.serialize(obj) + '\n'); }
+
+  function postMessage(obj) {
+    if (!messageUrl) { outbox.push(obj); return Promise.resolve(); }
+    return new Promise((resolve) => {
+      const m = new URL(messageUrl);
+      const t = m.protocol === 'https:' ? https : http;
+      const body = J.serialize(obj);
+      const req = t.request({
+        hostname: m.hostname, port: m.port || (m.protocol === 'https:' ? 443 : 80),
+        path: m.pathname + m.search, method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...headers, 'Content-Length': Buffer.byteLength(body) },
+      }, (r) => { r.resume(); r.on('end', resolve); });
+      req.on('error', (e) => { log(`sse POST error: ${e.message}`); resolve(); });
+      req.write(body); req.end();
+    });
+  }
+  function sendServer(obj) { return postMessage(obj); }
+
+  function flushOutbox() { const q = outbox.splice(0); for (const o of q) postMessage(o); }
+
+  function openSse() {
+    const req = tr.request({
+      hostname: u.hostname, port: u.port || (u.protocol === 'https:' ? 443 : 80),
+      path: u.pathname + u.search, method: 'GET',
+      headers: { Accept: 'text/event-stream', ...headers },
+    }, (r) => {
+      r.setEncoding('utf8');
+      let buf = '';
+      r.on('data', (chunk) => {
+        buf += chunk;
+        let idx;
+        while ((idx = buf.indexOf('\n\n')) >= 0) {
+          const frame = buf.slice(0, idx); buf = buf.slice(idx + 2);
+          let event = 'message';
+          const dataLines = [];
+          for (const line of frame.split('\n')) {
+            if (line.startsWith('event:')) event = line.slice(6).trim();
+            else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim());
+          }
+          const data = dataLines.join('\n');
+          if (!data) continue;
+          if (event === 'endpoint') {
+            try { messageUrl = new URL(data, u).toString(); flushOutbox(); }
+            catch { log(`bad endpoint event: ${data}`); }
+            continue;
+          }
+          const msg = J.parse(data);
+          if (msg) Promise.resolve(_onServer(msg)).catch(() => {});
+        }
+      });
+    });
+    req.on('error', (e) => { log(`sse GET error: ${e.message}`); });
+    req.end();
+    return req;
+  }
+
+  function start(handlers) {
+    _onServer = handlers.onServer;
+    const inF = new J.LineFramer();
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (d) => {
+      for (const line of inF.push(d)) {
+        const msg = J.parse(line);
+        if (msg) Promise.resolve(handlers.onClient(msg)).catch(() => {});
+      }
+    });
+    openSse();
+  }
+
+  function close() { /* sockets close with the process */ }
+
+  return { sendClient, sendServer, start, close };
+}
+
+module.exports = { createSseBridgeChannel };