@frontmcp/utils 1.11.3 → 1.12.0-rc.1

package/net/index.d.ts

@@ -1,4 +1,8 @@
-export { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, parseIpv4 } from './ip-address';
+export { classifyIpAddress, expandIpv6, extractEmbeddedIpv4, isGloballyRoutableIp, parseIpv4 } from './ip-address';
 export type { IpAddressClassification, IpAddressRange, SpecialPurposeIpRange } from './ip-address';
 export { isRedirectResponse } from './redirect';
 export type { RedirectCandidate } from './redirect';
+export { validateOutboundUrl } from './outbound-url';
+export type { OutboundTargetOptions, OutboundUrlCheck, OutboundUrlProblem } from './outbound-url';
+export { OUTBOUND_MAX_REQUEST_BYTES, OUTBOUND_TIMEOUT_MS, outboundFailureCategory, sendOutboundRequest, } from './outbound-request';
+export type { OutboundAnswer, OutboundFailure, OutboundFailureCategory, OutboundFailureReason, OutboundRequest, OutboundResult, } from './outbound-request';

package/net/ip-address.d.ts

@@ -33,3 +33,5 @@ export declare function extractEmbeddedIpv4(groups: readonly number[]): string |
  * @returns undefined when the input is not a well-formed IP literal.
  */
 export declare function classifyIpAddress(address: string): IpAddressClassification | undefined;
+/** Whether an IP literal is globally routable: public for {@link classifyIpAddress} and in no unrouted IANA block. */
+export declare function isGloballyRoutableIp(address: string): boolean;

package/net/outbound-request.d.ts

@@ -0,0 +1,46 @@
+/** SSRF-hardened HTTP for a URL a client chose: validated addresses only, no redirects, bounded time and sizes. */
+import { type OutboundTargetOptions } from './outbound-url';
+export declare const OUTBOUND_TIMEOUT_MS = 10000;
+export declare const OUTBOUND_MAX_REQUEST_BYTES = 262144;
+export interface OutboundRequest extends OutboundTargetOptions {
+    url: string;
+    /** @default 'POST' with a body, 'GET' without */
+    method?: 'GET' | 'POST';
+    headers?: Record<string, string>;
+    /** Sent as these exact UTF-8 bytes. */
+    body?: string;
+    /** Cancels the request, which then ends as a timeout. */
+    signal?: AbortSignal;
+    /** @default OUTBOUND_TIMEOUT_MS */
+    timeoutMs?: number;
+    /** @default OUTBOUND_MAX_REQUEST_BYTES */
+    maxRequestBytes?: number;
+    /** How many bytes of the answer's body to read. @default 0 */
+    maxResponseBytes?: number;
+    /** The answer's headers to return, by name. @default none */
+    responseHeaders?: readonly string[];
+    /** Where the connection cannot be pinned to checked addresses (browser, edge), send to a hostname anyway. @default false */
+    allowPlatformDns?: boolean;
+}
+export interface OutboundAnswer {
+    answered: true;
+    /** A redirect is not followed: its 3xx status is returned, or 0 where a browser hides it. */
+    status: number;
+    /** The first `maxResponseBytes` of the body, as UTF-8 text. */
+    body: string;
+    /** Whether the body was longer than `maxResponseBytes`; false when that is 0, as the body is then not read. */
+    bodyTruncated: boolean;
+    /** The headers named in `responseHeaders` that the answer carries, by lowercase name. */
+    headers: Record<string, string>;
+}
+export type OutboundFailureReason = 'invalid_url' | 'forbidden_address' | 'unresolved_host' | 'unpinned_dns' | 'request_too_large' | 'connection_refused' | 'timeout' | 'tls_error';
+export interface OutboundFailure {
+    answered: false;
+    reason: OutboundFailureReason;
+}
+export type OutboundResult = OutboundAnswer | OutboundFailure;
+export type OutboundFailureCategory = 'connection_refused' | 'timeout' | 'tls_error' | 'http_4xx' | 'http_5xx';
+/** The fixed category of a result that is not a 2xx answer: all that the party who chose the URL may be told. */
+export declare function outboundFailureCategory(result: OutboundResult): OutboundFailureCategory | undefined;
+/** Sends the request; without Node's `dns` and `net` (browser, edge) a hostname is refused unless `allowPlatformDns`. */
+export declare function sendOutboundRequest(request: OutboundRequest): Promise<OutboundResult>;

package/net/outbound-url.d.ts

@@ -0,0 +1,18 @@
+export interface OutboundTargetOptions {
+    /** Test-only: also accept `http:` and loopback or private targets. */
+    allowLocal?: boolean;
+}
+export type OutboundUrlProblem = 'malformed' | 'scheme' | 'credentials' | 'host';
+export type OutboundUrlCheck = {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    problem: OutboundUrlProblem;
+};
+/** Whether a request may connect to an IP address: globally routable, or loopback or private with `allowLocal`. */
+export declare function isAllowedOutboundAddress(address: string, options?: OutboundTargetOptions): boolean;
+/** Whether a URL host is an IP address, which needs no DNS resolution. */
+export declare function isIpLiteralHostname(hostname: string): boolean;
+/** Checks a URL a server did not choose before any I/O: `https:`, no credentials, and a host that is not local. */
+export declare function validateOutboundUrl(target: string, options?: OutboundTargetOptions): OutboundUrlCheck;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.11.3",
+  "version": "1.12.0-rc.1",
   "description": "Shared helpers for FrontMCP: URI templates, naming, cross-platform crypto and PKCE, key-value storage, file system and environment detection",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -33,7 +33,7 @@
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.11.3",
+    "@frontmcp/lazy-zod": "1.12.0-rc.1",
     "@upstash/redis": "^1.34.0",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"

package/serialization/canonical-json.d.ts

@@ -0,0 +1,2 @@
+/** Deterministic JSON: object keys sorted, arrays in order, `undefined` members dropped; a non-JSON value throws. */
+export declare function canonicalJson(value: unknown): string;

package/serialization/index.d.ts

@@ -1 +1,2 @@
 export { safeStringify } from './serialization';
+export { canonicalJson } from './canonical-json';

package/stdio-bridge/claude-code-channels.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the HTTP upstream does so Claude Code channels reach a bridged stdio session. Claude Code probes a stdio
+ * server on MCP 2026-07-28, delivers channel events only to a session started with `initialize`, and never
+ * declares the channel capability. The constants mirror `@frontmcp/protocol`, which this package can't import.
+ */
+import type { JsonRpcFrame } from './stdio-framer';
+/** The headers a 2026-07-28 `server/discover` must mirror from its body over HTTP. */
+export declare const DISCOVER_HEADERS: {
+    'mcp-protocol-version': string;
+    'mcp-method': string;
+};
+/** What a server says of itself: whether it pushes channels, and the revisions its `initialize` negotiates. */
+export interface ServerRevisions {
+    pushesChannels: boolean;
+    supported: string[];
+}
+/** Whether a client frame belongs to 2026-07-28: its `_meta` declares a revision, or its method exists only there. */
+export declare function namesProtocol20260728(frame: JsonRpcFrame): boolean;
+/** The `-32022` answer to a 2026-07-28 request, naming the revisions the server speaks instead. */
+export declare function unsupportedProtocolVersion(request: JsonRpcFrame, supported: readonly string[]): JsonRpcFrame;
+/** The `server/discover` request the bridge sends for itself, under an id of its own. */
+export declare function discoverRequest(id: string): JsonRpcFrame;
+/** Whether a `server/discover` or `initialize` result advertises `experimental['claude/channel']`. */
+export declare function advertisesChannels(result: unknown): boolean;
+/** What a `server/discover` result says of the server; `undefined` when it lists no revisions. */
+export declare function serverRevisionsOf(discoverResult: unknown): ServerRevisions | undefined;
+/** The client's `initialize` with `experimental['claude/channel']` declared, when it does not declare it itself. */
+export declare function declaringChannels(initialize: JsonRpcFrame): JsonRpcFrame;

package/stdio-bridge/notification-stream.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The standalone notification stream of an MCP session over streamable HTTP: the `GET` a server answers with the
+ * messages it starts itself, such as a channel event, `list_changed`, a log line or a resource update.
+ */
+import type { JsonRpcFrame } from './stdio-framer';
+import type { BridgeLogger } from './types';
+export declare const SESSION_HEADER = "mcp-session-id";
+export interface NotificationStreamOptions {
+    url: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+    log: BridgeLogger;
+    /** Called for every frame the server sends on the stream. */
+    onFrame: (frame: JsonRpcFrame) => void | Promise<void>;
+    /**
+     * Called once when the stream of a live session is given up: it could not be opened five times in a row, or the
+     * server no longer knows a session it streamed to.
+     */
+    onLost?: () => void;
+}
+export interface NotificationStream {
+    /**
+     * Relay the stream of `sessionId` and end the one relayed before; with no session, only end it. Resolves once
+     * the server answered the stream's first `GET`, or after 2 s without an answer.
+     */
+    follow(sessionId: string | undefined): Promise<void>;
+}
+/** Relays one session's notification stream at a time, reopening it when it drops while the session lives. */
+export declare function createNotificationStream(options: NotificationStreamOptions): NotificationStream;

package/stdio-bridge/sse-frames.d.ts

@@ -0,0 +1,8 @@
+import type { JsonRpcFrame } from './stdio-framer';
+import type { BridgeLogger } from './types';
+/**
+ * Hand the frame of each event of an SSE body to `deliver`, until the body ends. An event is its `data:` lines up
+ * to a blank line, joined by newlines; the event a body ends in is delivered without one. A body whose pending
+ * event grows past `maxEventChars` is cancelled, and the relay rejects.
+ */
+export declare function relaySseFrames(body: ReadableStream<Uint8Array>, deliver: (frame: JsonRpcFrame) => void | Promise<void>, log: BridgeLogger, maxEventChars?: number): Promise<void>;

package/stdio-bridge/upstream-client.d.ts

@@ -16,6 +16,9 @@
  * A restarted child has no session at all, so the bridge replays the client's
  * MCP handshake against it (`reinitialize`) before draining buffered requests.
  * The client keeps its stdio connection and never learns the server restarted.
+ *
+ * In HTTP mode the bridge also relays the session's standalone notification
+ * stream, which carries what the server sends on its own.
  */
 import type { ChildProcess } from 'node:child_process';
 import type { JsonRpcFrame } from './stdio-framer';
@@ -43,10 +46,20 @@ export interface HttpUpstreamOptions extends UpstreamClientOptions {
     headers?: Record<string, string>;
     /** Sends the requests instead of the global `fetch`, such as one that reaches a Unix socket. */
     fetch?: typeof fetch;
+    /**
+     * Serve Claude Code channels: declare `experimental['claude/channel']` on the client's `initialize`, and answer
+     * the 2026-07-28 requests of a server that advertises it with `-32022`, since Claude Code delivers channel
+     * events only to a session. Without it, every frame is relayed as it is.
+     */
+    claudeCodeChannels?: boolean;
+    /** Called once when the session's notification stream is given up, as a server that went away makes it. */
+    onNotificationStreamLost?: () => void;
 }
 export interface HttpUpstreamClient extends UpstreamClient {
     /** End the MCP session the server issued (`DELETE` with its id); the next `initialize` starts a new one. */
     endSession(): Promise<void>;
+    /** Forget the session of a server that went away, without telling it: its notification stream is closed. */
+    leaveSession(): void;
 }
 export declare function createHttpUpstream(options: HttpUpstreamOptions): HttpUpstreamClient;
 export interface PipeUpstreamOptions extends UpstreamClientOptions {