@frontmcp/utils 1.11.2 → 1.12.0-rc.1

package/browser/net/outbound-request.mjs

@@ -0,0 +1,190 @@
+var __frontmcpModule = typeof process !== "undefined" && typeof process.getBuiltinModule === "function" ? process.getBuiltinModule("module") : undefined;
+const require = __frontmcpModule ? __frontmcpModule.createRequire(import.meta.url || 'file:///') : undefined;
+// __frontmcpCreateRequire
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// libs/utils/src/net/outbound-request.ts
+import { isEdgeRuntime } from "../env/browser-env.mjs";
+import { isNode } from "../crypto/runtime.mjs";
+import {
+  isAllowedOutboundAddress,
+  isIpLiteralHostname,
+  validateOutboundUrl
+} from "./outbound-url.mjs";
+var OUTBOUND_TIMEOUT_MS = 1e4;
+var OUTBOUND_MAX_REQUEST_BYTES = 262144;
+var FAILURE_CATEGORIES = {
+  invalid_url: "connection_refused",
+  forbidden_address: "connection_refused",
+  unresolved_host: "connection_refused",
+  unpinned_dns: "connection_refused",
+  request_too_large: "http_4xx",
+  connection_refused: "connection_refused",
+  timeout: "timeout",
+  tls_error: "tls_error"
+};
+var TIMEOUT_CODE_PATTERN = /TIMEDOUT|TIMEOUT/;
+var TLS_CODE_PATTERN = /CERT|TLS|SSL|CRL|EPROTO|^UNABLE_TO_|^INVALID_(?:CA|PURPOSE)$|^PATH_LENGTH_EXCEEDED$|^HOSTNAME_MISMATCH$/;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var OutboundRefusal = class extends Error {
+  /** Carries the failure reason the request's result reports. */
+  constructor(reason) {
+    super(reason);
+    this.reason = reason;
+  }
+  reason;
+};
+function outboundFailureCategory(result) {
+  if (!result.answered) return FAILURE_CATEGORIES[result.reason];
+  if (result.status >= 200 && result.status < 300) return void 0;
+  return result.status >= 500 ? "http_5xx" : "http_4xx";
+}
+async function sendOutboundRequest(request) {
+  const check = validateOutboundUrl(request.url, request);
+  if (!check.ok) return { answered: false, reason: check.problem === "host" ? "forbidden_address" : "invalid_url" };
+  const node = loadNodeNetworking();
+  const needsPlatformDns = !node && !isIpLiteralHostname(check.url.hostname);
+  if (needsPlatformDns && request.allowPlatformDns !== true) return { answered: false, reason: "unpinned_dns" };
+  const body = request.body === void 0 ? void 0 : encoder.encode(request.body);
+  if (body && body.byteLength > (request.maxRequestBytes ?? OUTBOUND_MAX_REQUEST_BYTES)) {
+    return { answered: false, reason: "request_too_large" };
+  }
+  const timeout = AbortSignal.timeout(request.timeoutMs ?? OUTBOUND_TIMEOUT_MS);
+  const signal = request.signal ? AbortSignal.any([request.signal, timeout]) : timeout;
+  const headers = { ...request.headers };
+  if (body) headers["content-length"] = String(body.byteLength);
+  const method = request.method ?? (body ? "POST" : "GET");
+  const exchange = { url: check.url, method, headers, body, signal };
+  try {
+    const upstream = node ? await exchangeOverNode(node, exchange, request) : await exchangeOverFetch(exchange);
+    return await answerOf(upstream, request);
+  } catch (error) {
+    return { answered: false, reason: failureReasonOf(error, signal) };
+  }
+}
+function loadNodeNetworking() {
+  if (!isNode() || isEdgeRuntime()) return void 0;
+  return { dns: __require("node:dns"), http: __require("node:http"), https: __require("node:https") };
+}
+function rejectedOnAbort(signal) {
+  return new Promise((_resolve, reject) => {
+    signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+}
+async function resolveAllowedAddresses(node, exchange, options) {
+  exchange.signal.throwIfAborted();
+  const hostname = exchange.url.hostname.replace(/^\[|\]$/g, "");
+  let addresses;
+  try {
+    const lookup = node.dns.promises.lookup(hostname, { all: true });
+    addresses = await Promise.race([lookup, rejectedOnAbort(exchange.signal)]);
+  } catch (error) {
+    throw exchange.signal.aborted ? error : new OutboundRefusal("unresolved_host");
+  }
+  if (addresses.length === 0) throw new OutboundRefusal("unresolved_host");
+  if (!addresses.every(({ address }) => isAllowedOutboundAddress(address, options))) {
+    throw new OutboundRefusal("forbidden_address");
+  }
+  return addresses;
+}
+function pinnedLookup(addresses) {
+  return (_hostname, options, callback) => {
+    if (options.all) {
+      callback(null, [...addresses]);
+      return;
+    }
+    const [first] = addresses;
+    callback(null, first.address, first.family);
+  };
+}
+async function exchangeOverNode(node, exchange, options) {
+  const { url, method, headers, body, signal } = exchange;
+  const lookup = pinnedLookup(await resolveAllowedAddresses(node, exchange, options));
+  const transport = url.protocol === "https:" ? node.https : node.http;
+  const incoming = await new Promise((resolve, reject) => {
+    const outgoing = transport.request(url, { method, headers, signal, lookup, agent: false }, resolve);
+    outgoing.on("error", reject);
+    outgoing.end(body);
+  });
+  return {
+    status: Number(incoming.statusCode),
+    headerOf: (name) => {
+      const value = incoming.headers[name];
+      return value === void 0 ? void 0 : String(value);
+    },
+    chunks: incoming,
+    discard: () => incoming.destroy()
+  };
+}
+async function* chunksOf(stream) {
+  const reader = stream.getReader();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      yield value;
+    }
+  } finally {
+    await reader.cancel();
+  }
+}
+async function exchangeOverFetch(exchange) {
+  const { url, method, headers, body, signal } = exchange;
+  const response = await fetch(url, { method, headers, body, redirect: "manual", signal });
+  return {
+    status: response.status,
+    headerOf: (name) => response.headers.get(name) ?? void 0,
+    chunks: response.body ? chunksOf(response.body) : [],
+    discard: () => response.body?.cancel()
+  };
+}
+async function readBody(upstream, maxBytes) {
+  if (maxBytes <= 0) {
+    await upstream.discard();
+    return { body: "", bodyTruncated: false };
+  }
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of upstream.chunks) {
+    chunks.push(chunk);
+    received += chunk.byteLength;
+    if (received > maxBytes) break;
+  }
+  const bytes = new Uint8Array(Math.min(received, maxBytes));
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk.subarray(0, bytes.byteLength - offset), offset);
+    offset += chunk.byteLength;
+  }
+  return { body: decoder.decode(bytes), bodyTruncated: received > maxBytes };
+}
+async function answerOf(upstream, request) {
+  const headers = {};
+  for (const requestedName of request.responseHeaders ?? []) {
+    const name = requestedName.toLowerCase();
+    const value = upstream.headerOf(name);
+    if (value !== void 0) headers[name] = value;
+  }
+  const { body, bodyTruncated } = await readBody(upstream, request.maxResponseBytes ?? 0);
+  return { answered: true, status: upstream.status, body, bodyTruncated, headers };
+}
+function failureReasonOf(error, signal) {
+  if (error instanceof OutboundRefusal) return error.reason;
+  if (signal.aborted) return "timeout";
+  const { code, cause } = Object(error);
+  const errorCode = String(code ?? Object(cause).code);
+  if (TIMEOUT_CODE_PATTERN.test(errorCode)) return "timeout";
+  return TLS_CODE_PATTERN.test(errorCode) ? "tls_error" : "connection_refused";
+}
+export {
+  OUTBOUND_MAX_REQUEST_BYTES,
+  OUTBOUND_TIMEOUT_MS,
+  outboundFailureCategory,
+  sendOutboundRequest
+};

package/browser/net/outbound-url.mjs

@@ -0,0 +1,43 @@
+// libs/utils/src/net/outbound-url.ts
+import { classifyIpAddress, isGloballyRoutableIp, parseIpv4 } from "./ip-address.mjs";
+var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "localhost.localdomain"]);
+var METADATA_HOSTNAMES = /* @__PURE__ */ new Set([
+  "metadata",
+  "metadata.google.internal",
+  "metadata.goog",
+  "metadata.azure.com",
+  "metadata.aws.com"
+]);
+function isAllowedOutboundAddress(address, options = {}) {
+  if (isGloballyRoutableIp(address)) return true;
+  const range = classifyIpAddress(address)?.range;
+  return options.allowLocal === true && (range === "loopback" || range === "private");
+}
+function isIpLiteralHostname(hostname) {
+  return hostname.startsWith("[") || parseIpv4(hostname) !== void 0;
+}
+function isAllowedHostname(hostname, options) {
+  if (isIpLiteralHostname(hostname)) return isAllowedOutboundAddress(hostname, options);
+  const name = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+  if (METADATA_HOSTNAMES.has(name)) return false;
+  const isLoopbackName = LOOPBACK_HOSTNAMES.has(name) || name.endsWith(".localhost");
+  return !isLoopbackName || options.allowLocal === true;
+}
+function validateOutboundUrl(target, options = {}) {
+  let url;
+  try {
+    url = new URL(target);
+  } catch {
+    return { ok: false, problem: "malformed" };
+  }
+  const isAllowedScheme = url.protocol === "https:" || url.protocol === "http:" && options.allowLocal === true;
+  if (!isAllowedScheme) return { ok: false, problem: "scheme" };
+  if (url.username !== "" || url.password !== "") return { ok: false, problem: "credentials" };
+  if (!isAllowedHostname(url.hostname, options)) return { ok: false, problem: "host" };
+  return { ok: true, url };
+}
+export {
+  isAllowedOutboundAddress,
+  isIpLiteralHostname,
+  validateOutboundUrl
+};

package/browser/serialization/canonical-json.mjs

@@ -0,0 +1,35 @@
+// libs/utils/src/serialization/canonical-json.ts
+function canonicalJson(value) {
+  return serialize(value, /* @__PURE__ */ new Set());
+}
+function refuse(description) {
+  throw new TypeError(`canonicalJson: ${description} is not a JSON value`);
+}
+function serialize(value, ancestors) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : refuse(String(value));
+  if (typeof value !== "object") return refuse(typeof value);
+  if (ancestors.has(value)) return refuse("a circular reference");
+  ancestors.add(value);
+  const text = serializeObject(value, ancestors);
+  ancestors.delete(value);
+  return text;
+}
+function serializeObject(value, ancestors) {
+  if (hasToJson(value)) return serialize(value.toJSON(), ancestors);
+  if (Array.isArray(value)) return `[${Array.from(value, (item) => serialize(item, ancestors)).join(",")}]`;
+  if (!isPlainObject(value)) return refuse("a class instance");
+  const record = value;
+  const members = Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${serialize(record[key], ancestors)}`);
+  return `{${members.join(",")}}`;
+}
+function hasToJson(value) {
+  return typeof value.toJSON === "function";
+}
+function isPlainObject(value) {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+export {
+  canonicalJson
+};

package/browser/serialization/index.mjs

@@ -1,5 +1,7 @@
 // libs/utils/src/serialization/index.ts
 import { safeStringify } from "./serialization.mjs";
+import { canonicalJson } from "./canonical-json.mjs";
 export {
+  canonicalJson,
   safeStringify
 };

package/browser/stdio-bridge/claude-code-channels.mjs

@@ -0,0 +1,73 @@
+// libs/utils/src/stdio-bridge/claude-code-channels.ts
+var PROTOCOL_2026_07_28 = "2026-07-28";
+var PROTOCOL_VERSION_META = "io.modelcontextprotocol/protocolVersion";
+var DISCOVER_METHOD = "server/discover";
+var PROTOCOL_20260728_ONLY_METHODS = [DISCOVER_METHOD, "subscriptions/listen"];
+var UNSUPPORTED_PROTOCOL_VERSION = -32022;
+var CHANNEL_CAPABILITY = "claude/channel";
+var DISCOVER_HEADERS = { "mcp-protocol-version": PROTOCOL_2026_07_28, "mcp-method": DISCOVER_METHOD };
+function recordOf(value) {
+  return typeof value === "object" && value !== null ? value : void 0;
+}
+function declaredRevision(frame) {
+  const declared = recordOf(recordOf(frame.params)?.["_meta"])?.[PROTOCOL_VERSION_META];
+  return typeof declared === "string" ? declared : void 0;
+}
+function namesProtocol20260728(frame) {
+  if (frame.method === void 0) return false;
+  return declaredRevision(frame) !== void 0 || PROTOCOL_20260728_ONLY_METHODS.includes(frame.method);
+}
+function unsupportedProtocolVersion(request, supported) {
+  const requested = declaredRevision(request) ?? PROTOCOL_2026_07_28;
+  return {
+    jsonrpc: "2.0",
+    id: request.id,
+    error: {
+      code: UNSUPPORTED_PROTOCOL_VERSION,
+      message: `Unsupported protocol version: ${requested}`,
+      data: { supported: [...supported], requested }
+    }
+  };
+}
+function discoverRequest(id) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method: DISCOVER_METHOD,
+    params: { _meta: { [PROTOCOL_VERSION_META]: PROTOCOL_2026_07_28 } }
+  };
+}
+function advertisesChannels(result) {
+  const experimental = recordOf(recordOf(recordOf(result)?.["capabilities"])?.["experimental"]);
+  return experimental?.[CHANNEL_CAPABILITY] !== void 0;
+}
+function serverRevisionsOf(discoverResult) {
+  const supportedVersions = recordOf(discoverResult)?.["supportedVersions"];
+  if (!Array.isArray(supportedVersions)) return void 0;
+  const supported = supportedVersions.filter(
+    (version) => typeof version === "string" && version !== PROTOCOL_2026_07_28
+  );
+  return { pushesChannels: advertisesChannels(discoverResult), supported };
+}
+function declaringChannels(initialize) {
+  const params = recordOf(initialize.params) ?? {};
+  const capabilities = recordOf(params["capabilities"]) ?? {};
+  const experimental = recordOf(capabilities["experimental"]) ?? {};
+  if (experimental[CHANNEL_CAPABILITY] !== void 0) return initialize;
+  return {
+    ...initialize,
+    params: {
+      ...params,
+      capabilities: { ...capabilities, experimental: { ...experimental, [CHANNEL_CAPABILITY]: {} } }
+    }
+  };
+}
+export {
+  DISCOVER_HEADERS,
+  advertisesChannels,
+  declaringChannels,
+  discoverRequest,
+  namesProtocol20260728,
+  serverRevisionsOf,
+  unsupportedProtocolVersion
+};

package/browser/stdio-bridge/notification-stream.mjs

@@ -0,0 +1,111 @@
+// libs/utils/src/stdio-bridge/notification-stream.ts
+import { relaySseFrames } from "./sse-frames.mjs";
+var SESSION_HEADER = "mcp-session-id";
+var NO_STREAM_STATUS = 405;
+var UNKNOWN_SESSION_STATUS = 404;
+var OPEN_WAIT_MS = 2e3;
+var FIRST_REOPEN_DELAY_MS = 250;
+var MAX_REOPEN_DELAY_MS = 4e3;
+var MAX_FAILED_OPENS = 5;
+function pause(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(finish, ms).unref();
+    signal.addEventListener("abort", finish, { once: true });
+    function finish() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    }
+  });
+}
+function createNotificationStream(options) {
+  const { url, log, onFrame } = options;
+  let following;
+  async function open(sessionId, signal) {
+    try {
+      const response = await (options.fetch ?? fetch)(url, {
+        method: "GET",
+        redirect: "error",
+        headers: { ...options.headers, accept: "text/event-stream", [SESSION_HEADER]: sessionId },
+        signal
+      });
+      const streams = (response.headers.get("content-type") ?? "").includes("text/event-stream");
+      if (response.ok && streams && response.body) return response.body;
+      await response.body?.cancel();
+      const unknownSession = response.status === UNKNOWN_SESSION_STATUS;
+      const offersNone = unknownSession || response.ok || response.status === NO_STREAM_STATUS;
+      log.debug(offersNone ? "notification-stream-unavailable" : "notification-stream-failed", {
+        status: response.status
+      });
+      if (unknownSession) return "unknown-session";
+      return offersNone ? "unavailable" : "failed";
+    } catch (err) {
+      if (!signal.aborted) log.debug("notification-stream-failed", { error: err.message });
+      return "failed";
+    }
+  }
+  async function relay(body, signal) {
+    let relayed = false;
+    try {
+      await relaySseFrames(
+        body,
+        async (frame) => {
+          relayed = true;
+          await onFrame(frame);
+        },
+        log
+      );
+    } catch (err) {
+      if (!signal.aborted) log.debug("notification-stream-dropped", { error: err.message });
+    }
+    return relayed;
+  }
+  function giveUp(reason) {
+    log.warn("notification-stream-lost", reason);
+    options.onLost?.();
+  }
+  async function relayUntilEnded(sessionId, signal, onAnswered) {
+    let failedOpens = 0;
+    let streamed = false;
+    let delayMs = FIRST_REOPEN_DELAY_MS;
+    while (!signal.aborted) {
+      const opened = await open(sessionId, signal);
+      onAnswered();
+      if (signal.aborted || opened === "unavailable") return;
+      if (opened === "unknown-session") {
+        if (streamed) giveUp({ status: UNKNOWN_SESSION_STATUS });
+        return;
+      }
+      if (opened === "failed") {
+        failedOpens += 1;
+        if (failedOpens === MAX_FAILED_OPENS) {
+          giveUp({ attempts: failedOpens });
+          return;
+        }
+      } else {
+        failedOpens = 0;
+        streamed = true;
+        if (await relay(opened, signal)) delayMs = FIRST_REOPEN_DELAY_MS;
+      }
+      await pause(delayMs, signal);
+      delayMs = Math.min(delayMs * 2, MAX_REOPEN_DELAY_MS);
+    }
+  }
+  return {
+    follow(sessionId) {
+      following?.abort();
+      following = void 0;
+      if (!sessionId) return Promise.resolve();
+      const stream = new AbortController();
+      following = stream;
+      return new Promise((answered) => {
+        void relayUntilEnded(sessionId, stream.signal, answered);
+        void pause(OPEN_WAIT_MS, stream.signal).then(answered);
+      });
+    }
+  };
+}
+export {
+  SESSION_HEADER,
+  createNotificationStream
+};

package/browser/stdio-bridge/sse-frames.mjs

@@ -0,0 +1,48 @@
+// libs/utils/src/stdio-bridge/sse-frames.ts
+var MAX_EVENT_CHARS = 64 * 1024 * 1024;
+async function relaySseFrames(body, deliver, log, maxEventChars = MAX_EVENT_CHARS) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let eventData = [];
+  let eventChars = 0;
+  async function deliverEvent() {
+    const json = eventData.join("\n").trim();
+    eventData = [];
+    eventChars = 0;
+    if (!json) return;
+    try {
+      await deliver(JSON.parse(json));
+    } catch (err) {
+      log.warn("sse-parse-error", { error: err.message, raw: json.slice(0, 200) });
+    }
+  }
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      await deliverEvent();
+      return;
+    }
+    buffer += decoder.decode(value, { stream: true });
+    let newline = buffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+      if (line === "") {
+        await deliverEvent();
+      } else if (line.startsWith("data:")) {
+        const data = line.slice(5).trim();
+        eventData.push(data);
+        eventChars += data.length + 1;
+      }
+    }
+    if (eventChars + buffer.length > maxEventChars) {
+      await reader.cancel();
+      throw new Error(`an SSE event is larger than ${maxEventChars} characters`);
+    }
+  }
+}
+export {
+  relaySseFrames
+};