@truefoundry/ai-gateway-sdk 0.0.0-stage → 0.0.1

package/dist/http/meshTls.d.ts

@@ -0,0 +1,154 @@
+import { Agent as HttpsAgent } from 'https';
+import type { SafeFetchTlsOptions } from './createSafeDispatcher';
+export declare const meshTlsCertPath: () => string;
+export declare const meshTlsKeyPath: () => string;
+export declare const meshTlsCaPath: () => string;
+/** Whether inbound requests must carry a verified client certificate. */
+export declare const isMeshMutualTlsEnabled: () => boolean;
+/**
+ * Reports whether `rawUrl` names a mesh-direct internal peer — a bare service name or a Kubernetes
+ * DNS suffix — rather than an edge path or a public FQDN. Scheme-agnostic and fails closed. Mirrors
+ * the identical gate in tfy-infra-manager, tfy-controller and servicefoundry-server.
+ *
+ * Note for the gateway specifically: `SERVICEFOUNDRY_SERVER_URL` defaults to
+ * `${CONTROL_PLANE_URL}/api/svc`, which is both a public host and an edge path, so it is excluded
+ * twice over. Mesh TLS only engages on the outbound side if that URL is overridden to point at the
+ * in-cluster service (e.g. `http://servicefoundry-server:3000/v1`).
+ */
+export declare function isInternalMeshUrl(rawUrl: string | undefined): boolean;
+/**
+ * Upgrades a mesh-direct peer URL from http to https when TLS is on, so one flag flips the scheme
+ * and the client certificate together instead of hand-editing every peer URL per environment.
+ * Idempotent no-op when TLS is off, when the target is an edge or public URL, or when it is
+ * already https.
+ *
+ * SCOPE NOTE: this ties the scheme to the gateway's own TLS_ENABLED. Correct for flipping a whole
+ * environment together, wrong for a phased rollout where the callee may still be plain HTTP.
+ */
+export declare function normalizeInternalMeshUrl(targetUrl: string): string;
+export interface MeshTlsMaterial {
+    cert: Buffer;
+    key: Buffer;
+    ca: Buffer;
+}
+/**
+ * Fails at startup if TLS is on but the mount is missing, so a misdirected TLS_DIR is a clear boot
+ * error rather than an opaque handshake failure on the first control-plane call, or a pod that
+ * comes up and fails every probe.
+ */
+export declare function assertMeshTlsFilesReadable(): void;
+/**
+ * HTTPS agent options (cert/key/ca) for a mesh-direct peer, or `undefined` when TLS is off or the
+ * target is not mesh-direct. Prefer this for libraries that take agent *options* (OTLP exporters'
+ * `httpAgentOptions`) rather than a pre-built Agent.
+ */
+export declare function meshTlsHttpsAgentOptions(targetUrl: string | undefined): {
+    cert: Buffer;
+    key: Buffer;
+    ca: Buffer;
+    keepAlive: true;
+} | undefined;
+/**
+ * An https.Agent that trusts the internal CA and presents this pod's certificate, or `undefined`
+ * when TLS is off or `targetUrl` is not a mesh-direct peer. Callers may pass the `undefined`
+ * straight to axios — it means "leave the default agent alone".
+ *
+ * `keepAlive` matches axios' usual pooling behaviour so switching a client onto this agent does not
+ * silently turn off connection reuse on a hot path.
+ */
+export declare function createMeshHttpsAgent(targetUrl: string | undefined): HttpsAgent | undefined;
+/**
+ * The same material shaped for `safeFetch`/`createSafeDispatcher`, or `undefined` when TLS is off
+ * or the target is not mesh-direct.
+ *
+ * `SafeFetchTlsOptions` is declared with `ca?: string`, which is why this returns PEM strings
+ * rather than the Buffers the agent uses.
+ */
+export declare function meshTlsFetchOptions(targetUrl: string | undefined): (SafeFetchTlsOptions & {
+    cert: string;
+    key: string;
+}) | undefined;
+/**
+ * File-path TLS options for a NATS TCP `connect()` to an in-cluster mesh peer, or `undefined`
+ * when TLS is off or `serverUrl` is not mesh-direct (e.g. `ws(s)://` via tfy-proxy).
+ *
+ * NATS on :4222 is configured with `tls.verify: true`, so the client must both trust the internal
+ * CA and present this pod's certificate. Passing only `tls: {}` produces
+ * `UNABLE_TO_VERIFY_LEAF_SIGNATURE`. Paths rather than PEM strings match what
+ * `@nats-io/transport-node` loads via `certFile` / `keyFile` / `caFile`.
+ *
+ * `nats://host:4222` is accepted by `URL` and by {@link isInternalMeshUrl} (bare service names and
+ * `*.svc.cluster.local` suffixes).
+ */
+export declare function meshNatsTlsOptions(serverUrl: string | undefined): {
+    caFile: string;
+    certFile: string;
+    keyFile: string;
+} | undefined;
+/**
+ * TLS options for the inbound listener, or `undefined` when TLS is off (in which case the caller
+ * serves plain HTTP, as before).
+ *
+ * On client auth: under mutual TLS this sets `requestCert: true` with `rejectUnauthorized: false`
+ * — Node's equivalent of Go's `VerifyClientCertIfGiven`. Rejecting at the handshake would refuse
+ * the kubelet and Prometheus, which present no certificate, so every httpGet probe and every
+ * metrics scrape would fail. The handshake completes either way and
+ * {@link requireClientCertificate} enforces presence per request, so probe paths can be exempted.
+ *
+ * IMPORTANT, and different from the Go implementation: because `rejectUnauthorized` is false, Node
+ * completes the handshake even for a certificate it could NOT verify, setting `socket.authorized`
+ * to false and recording `socket.authorizationError`. A presence check alone would therefore accept
+ * a self-signed client certificate. The middleware must check `authorized`, and it does.
+ */
+export declare function meshServerTlsOptions(): {
+    cert: Buffer;
+    key: Buffer;
+    ca?: Buffer;
+    requestCert?: boolean;
+    rejectUnauthorized?: boolean;
+} | undefined;
+/**
+ * The scheme the gateway's own listener is speaking. Loopback callers need this: several code paths
+ * call the gateway back through its own port (the MCP transport probe, the semantic-cache embeddings
+ * hop, complexity routing, the agent channels client), and a hardcoded `http://` against a TLS
+ * listener is not a clean error — Node destroys the connection and the caller sees a bare transport
+ * failure, which surfaces to the user as a 502 with no explanation.
+ */
+export declare const loopbackScheme: () => "http" | "https";
+/**
+ * Base origin for a call the gateway makes to itself, e.g. `https://localhost:8787`.
+ *
+ * `localhost` rather than the service DNS name on purpose: these hops are same-pod by design. The
+ * MCP transport caches a session id per pod, and the semantic-cache and complexity-routing hops
+ * assume the in-process adapter state of the pod they started on — routing them through the Service
+ * would land them on an arbitrary replica.
+ *
+ * REQUIRES A CERTIFICATE SAN. Because the target is dialled as `localhost`, the internal
+ * certificate must carry `localhost` as a DNS SAN and `127.0.0.1` as an IP SAN, or verification
+ * fails with ERR_TLS_CERT_ALTNAME_INVALID before the client certificate is ever considered. That is
+ * a chart-side setting (`global.mTLS.extraDnsNames`); see docs/internal-mutual-tls.md. The
+ * alternative — disabling verification for loopback — was rejected deliberately: it would put a
+ * `rejectUnauthorized: false` in the request path, where it is one careless edit away from applying
+ * to real peers.
+ */
+export declare const loopbackOrigin: () => string;
+/**
+ * TLS material for a loopback call, or `undefined` when TLS is off.
+ *
+ * Needed in both directions even though the peer is this same process: the internal CA is not in
+ * Node's default trust store, so `ca` is required to verify our own certificate, and the loopback
+ * path (`/{tenant}/mcp/{server}/server`) is not in the exempt set, so `cert`/`key` are required to
+ * get past {@link requireClientCertificate}. Adding the loopback path to the exempt list instead
+ * would have been the smaller change, but it would mean anything that can reach the port
+ * unauthenticated can reach the MCP fan-out.
+ */
+export declare function loopbackTlsFetchOptions(): (SafeFetchTlsOptions & {
+    cert: string;
+    key: string;
+}) | undefined;
+/**
+ * The exempt paths as a lookup set, each normalized to a leading slash. Matched exactly, not as
+ * prefixes.
+ */
+export declare function meshTlsExemptPathSet(): Set<string>;
+//# sourceMappingURL=meshTls.d.ts.map

package/dist/http/meshTls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meshTls.d.ts","sourceRoot":"","sources":["../../src/http/meshTls.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,OAAO,CAAC;AAG5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAqBlE,eAAO,MAAM,eAAe,QAAO,MAAyC,CAAC;AAC7E,eAAO,MAAM,cAAc,QAAO,MAAwC,CAAC;AAC3E,eAAO,MAAM,aAAa,QAAO,MAAuC,CAAC;AAEzE,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,QAAO,OAAkD,CAAC;AAE7F;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAuBrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGlE;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;CACZ;AAmBD;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAoBjD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CAIxE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAG1F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,CAAC,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAInE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOnE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/F,SAAS,CAKZ;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAAO,MAAM,GAAG,OAAkD,CAAC;AAE9F;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,QAAO,MAA0D,CAAC;AAE7F;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,CAAC,mBAAmB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAE3G;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,GAAG,CAAC,MAAM,CAAC,CAQlD"}

package/dist/http/meshTls.js

@@ -0,0 +1,274 @@
+/**
+ * Internal mutual TLS for talking to, and being called by, other TrueFoundry control-plane
+ * components.
+ *
+ * One certificate mounted at TLS_DIR is used in both directions, because both directions are
+ * always enabled together: the gateway SERVES HTTPS on PORT (tfy-proxy dials it) and it CALLS
+ * servicefoundry-server, which requires a client certificate when its own TLS_MUTUAL is on. The
+ * env var names match servicefoundry-server, tfy-controller and tfy-infra-manager so one set of
+ * chart values configures every component. The file layout is the one every component shares:
+ *
+ *   ${TLS_DIR}/tls.crt  -> this pod's certificate, presented both as server and as client cert
+ *   ${TLS_DIR}/tls.key  -> its private key
+ *   ${TLS_DIR}/ca.crt   -> the internal CA, used to verify peers (trust anchor)
+ *
+ * The gateway chart already mounts these via `tfy-llm-gateway.mtls.volumeMount`, gated on
+ * `global.mTLS.enabled`.
+ *
+ * READ THIS BEFORE ADDING A CALLER. Node's `ca` option REPLACES the default trust store rather
+ * than adding to it, so anything carrying the material below can *only* reach peers signed by the
+ * internal CA. The gateway talks to far more public hosts than any other component — every LLM
+ * provider, every customer MCP server, TTS/STT, auth-server — so the mesh material must never be
+ * installed globally (no `axios.defaults`, no `setGlobalDispatcher`). Every entry point here takes
+ * the target URL and returns `undefined` unless it passes {@link isInternalMeshUrl}.
+ * One exception: `http/loopbackDispatcher.ts` sits on the global dispatcher, but installs a router
+ * rather than the material — every origin except {@link loopbackOrigin} goes to the base dispatcher
+ * untouched.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { Agent as HttpsAgent } from 'https';
+import { join } from 'path';
+import config from '../config.js';
+const CERT_FILE = 'tls.crt';
+const KEY_FILE = 'tls.key';
+const CA_FILE = 'ca.crt';
+/**
+ * tfy-proxy (Caddy) edge routes. A URL carrying one of these is going through the gateway, which
+ * terminates and re-originates TLS with its own certificate, so it is never a mesh-direct peer even
+ * when the host looks internal.
+ *
+ * `/api/llm` is in here for symmetry with the other components even though the gateway does not
+ * call itself: a self-referential URL (the semantic-cache localhost hop) must not pick up the
+ * client certificate either. `/api/otel` is the edge path for OTLP; mesh-direct
+ * `http://…-tfy-otel-collector:4318` is *not* excluded and gets client certs on the exporter.
+ */
+const EDGE_PATH_PREFIXES = ['/api/svc', '/api/ml', '/api/llm', '/api/otel', '/api/auth'];
+/** In-cluster DNS suffixes. A bare hostname with no dot is also treated as in-cluster. */
+const MESH_HOST_SUFFIXES = ['.svc.cluster.local', '.svc', '.cluster.local'];
+export const meshTlsCertPath = () => join(config.TLS_DIR, CERT_FILE);
+export const meshTlsKeyPath = () => join(config.TLS_DIR, KEY_FILE);
+export const meshTlsCaPath = () => join(config.TLS_DIR, CA_FILE);
+/** Whether inbound requests must carry a verified client certificate. */
+export const isMeshMutualTlsEnabled = () => config.TLS_ENABLED && config.TLS_MUTUAL;
+/**
+ * Reports whether `rawUrl` names a mesh-direct internal peer — a bare service name or a Kubernetes
+ * DNS suffix — rather than an edge path or a public FQDN. Scheme-agnostic and fails closed. Mirrors
+ * the identical gate in tfy-infra-manager, tfy-controller and servicefoundry-server.
+ *
+ * Note for the gateway specifically: `SERVICEFOUNDRY_SERVER_URL` defaults to
+ * `${CONTROL_PLANE_URL}/api/svc`, which is both a public host and an edge path, so it is excluded
+ * twice over. Mesh TLS only engages on the outbound side if that URL is overridden to point at the
+ * in-cluster service (e.g. `http://servicefoundry-server:3000/v1`).
+ */
+export function isInternalMeshUrl(rawUrl) {
+    if (!rawUrl)
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        return false;
+    }
+    if (!parsed.hostname)
+        return false;
+    for (const prefix of EDGE_PATH_PREFIXES) {
+        if (parsed.pathname === prefix || parsed.pathname.startsWith(`${prefix}/`)) {
+            return false;
+        }
+    }
+    const host = parsed.hostname;
+    // Bare in-cluster service name. Note this also covers `localhost`, which {@link loopbackOrigin}
+    // depends on — the gateway's self-calls need the certificate material and would silently fall back
+    // to plaintext-with-no-cert if this stopped returning true for it. Tighten with care.
+    if (!host.includes('.'))
+        return true;
+    return MESH_HOST_SUFFIXES.some(suffix => host.endsWith(suffix));
+}
+/**
+ * Upgrades a mesh-direct peer URL from http to https when TLS is on, so one flag flips the scheme
+ * and the client certificate together instead of hand-editing every peer URL per environment.
+ * Idempotent no-op when TLS is off, when the target is an edge or public URL, or when it is
+ * already https.
+ *
+ * SCOPE NOTE: this ties the scheme to the gateway's own TLS_ENABLED. Correct for flipping a whole
+ * environment together, wrong for a phased rollout where the callee may still be plain HTTP.
+ */
+export function normalizeInternalMeshUrl(targetUrl) {
+    if (!config.TLS_ENABLED || !isInternalMeshUrl(targetUrl))
+        return targetUrl;
+    return targetUrl.startsWith('http://') ? `https://${targetUrl.slice('http://'.length)}` : targetUrl;
+}
+let cachedMaterial;
+/**
+ * Reads and caches the certificate triple. Cached because the files do not change without a pod
+ * restart (the chart's bootstrap job reissues into the secret, and Kubernetes does not signal the
+ * process), and because this sits on the request path via the pooled agent.
+ */
+function loadMeshTlsMaterial() {
+    if (cachedMaterial)
+        return cachedMaterial;
+    cachedMaterial = {
+        cert: readFileSync(meshTlsCertPath()),
+        key: readFileSync(meshTlsKeyPath()),
+        ca: readFileSync(meshTlsCaPath()),
+    };
+    return cachedMaterial;
+}
+/**
+ * Fails at startup if TLS is on but the mount is missing, so a misdirected TLS_DIR is a clear boot
+ * error rather than an opaque handshake failure on the first control-plane call, or a pod that
+ * comes up and fails every probe.
+ */
+export function assertMeshTlsFilesReadable() {
+    if (!config.TLS_ENABLED)
+        return;
+    for (const path of [meshTlsCertPath(), meshTlsKeyPath(), meshTlsCaPath()]) {
+        if (!existsSync(path)) {
+            throw new Error(`TLS_ENABLED is true but ${path} does not exist. Check that the mTLS secret is mounted at ` +
+                `TLS_DIR (must match global.mTLS.mountPath in the chart), or set TLS_ENABLED=false.`);
+        }
+    }
+    // Read eagerly so a mounted-but-unreadable file (wrong fsGroup, bad permissions) also fails here
+    // rather than on the first request.
+    try {
+        loadMeshTlsMaterial();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`TLS_ENABLED is true but the certificate triple under ${config.TLS_DIR} could not be read: ${message}`);
+    }
+}
+/**
+ * HTTPS agent options (cert/key/ca) for a mesh-direct peer, or `undefined` when TLS is off or the
+ * target is not mesh-direct. Prefer this for libraries that take agent *options* (OTLP exporters'
+ * `httpAgentOptions`) rather than a pre-built Agent.
+ */
+export function meshTlsHttpsAgentOptions(targetUrl) {
+    if (!config.TLS_ENABLED || !isInternalMeshUrl(targetUrl))
+        return undefined;
+    const { cert, key, ca } = loadMeshTlsMaterial();
+    return { cert, key, ca, keepAlive: true };
+}
+/**
+ * An https.Agent that trusts the internal CA and presents this pod's certificate, or `undefined`
+ * when TLS is off or `targetUrl` is not a mesh-direct peer. Callers may pass the `undefined`
+ * straight to axios — it means "leave the default agent alone".
+ *
+ * `keepAlive` matches axios' usual pooling behaviour so switching a client onto this agent does not
+ * silently turn off connection reuse on a hot path.
+ */
+export function createMeshHttpsAgent(targetUrl) {
+    const options = meshTlsHttpsAgentOptions(targetUrl);
+    return options ? new HttpsAgent(options) : undefined;
+}
+/**
+ * The same material shaped for `safeFetch`/`createSafeDispatcher`, or `undefined` when TLS is off
+ * or the target is not mesh-direct.
+ *
+ * `SafeFetchTlsOptions` is declared with `ca?: string`, which is why this returns PEM strings
+ * rather than the Buffers the agent uses.
+ */
+export function meshTlsFetchOptions(targetUrl) {
+    if (!config.TLS_ENABLED || !isInternalMeshUrl(targetUrl))
+        return undefined;
+    const { cert, key, ca } = loadMeshTlsMaterial();
+    return { ca: ca.toString('utf8'), cert: cert.toString('utf8'), key: key.toString('utf8') };
+}
+/**
+ * File-path TLS options for a NATS TCP `connect()` to an in-cluster mesh peer, or `undefined`
+ * when TLS is off or `serverUrl` is not mesh-direct (e.g. `ws(s)://` via tfy-proxy).
+ *
+ * NATS on :4222 is configured with `tls.verify: true`, so the client must both trust the internal
+ * CA and present this pod's certificate. Passing only `tls: {}` produces
+ * `UNABLE_TO_VERIFY_LEAF_SIGNATURE`. Paths rather than PEM strings match what
+ * `@nats-io/transport-node` loads via `certFile` / `keyFile` / `caFile`.
+ *
+ * `nats://host:4222` is accepted by `URL` and by {@link isInternalMeshUrl} (bare service names and
+ * `*.svc.cluster.local` suffixes).
+ */
+export function meshNatsTlsOptions(serverUrl) {
+    if (!config.TLS_ENABLED || !serverUrl || !isInternalMeshUrl(serverUrl))
+        return undefined;
+    return {
+        caFile: meshTlsCaPath(),
+        certFile: meshTlsCertPath(),
+        keyFile: meshTlsKeyPath(),
+    };
+}
+/**
+ * TLS options for the inbound listener, or `undefined` when TLS is off (in which case the caller
+ * serves plain HTTP, as before).
+ *
+ * On client auth: under mutual TLS this sets `requestCert: true` with `rejectUnauthorized: false`
+ * — Node's equivalent of Go's `VerifyClientCertIfGiven`. Rejecting at the handshake would refuse
+ * the kubelet and Prometheus, which present no certificate, so every httpGet probe and every
+ * metrics scrape would fail. The handshake completes either way and
+ * {@link requireClientCertificate} enforces presence per request, so probe paths can be exempted.
+ *
+ * IMPORTANT, and different from the Go implementation: because `rejectUnauthorized` is false, Node
+ * completes the handshake even for a certificate it could NOT verify, setting `socket.authorized`
+ * to false and recording `socket.authorizationError`. A presence check alone would therefore accept
+ * a self-signed client certificate. The middleware must check `authorized`, and it does.
+ */
+export function meshServerTlsOptions() {
+    if (!config.TLS_ENABLED)
+        return undefined;
+    const { cert, key, ca } = loadMeshTlsMaterial();
+    if (!config.TLS_MUTUAL)
+        return { cert, key };
+    return { cert, key, ca, requestCert: true, rejectUnauthorized: false };
+}
+/**
+ * The scheme the gateway's own listener is speaking. Loopback callers need this: several code paths
+ * call the gateway back through its own port (the MCP transport probe, the semantic-cache embeddings
+ * hop, complexity routing, the agent channels client), and a hardcoded `http://` against a TLS
+ * listener is not a clean error — Node destroys the connection and the caller sees a bare transport
+ * failure, which surfaces to the user as a 502 with no explanation.
+ */
+export const loopbackScheme = () => (config.TLS_ENABLED ? 'https' : 'http');
+/**
+ * Base origin for a call the gateway makes to itself, e.g. `https://localhost:8787`.
+ *
+ * `localhost` rather than the service DNS name on purpose: these hops are same-pod by design. The
+ * MCP transport caches a session id per pod, and the semantic-cache and complexity-routing hops
+ * assume the in-process adapter state of the pod they started on — routing them through the Service
+ * would land them on an arbitrary replica.
+ *
+ * REQUIRES A CERTIFICATE SAN. Because the target is dialled as `localhost`, the internal
+ * certificate must carry `localhost` as a DNS SAN and `127.0.0.1` as an IP SAN, or verification
+ * fails with ERR_TLS_CERT_ALTNAME_INVALID before the client certificate is ever considered. That is
+ * a chart-side setting (`global.mTLS.extraDnsNames`); see docs/internal-mutual-tls.md. The
+ * alternative — disabling verification for loopback — was rejected deliberately: it would put a
+ * `rejectUnauthorized: false` in the request path, where it is one careless edit away from applying
+ * to real peers.
+ */
+export const loopbackOrigin = () => `${loopbackScheme()}://localhost:${config.PORT}`;
+/**
+ * TLS material for a loopback call, or `undefined` when TLS is off.
+ *
+ * Needed in both directions even though the peer is this same process: the internal CA is not in
+ * Node's default trust store, so `ca` is required to verify our own certificate, and the loopback
+ * path (`/{tenant}/mcp/{server}/server`) is not in the exempt set, so `cert`/`key` are required to
+ * get past {@link requireClientCertificate}. Adding the loopback path to the exempt list instead
+ * would have been the smaller change, but it would mean anything that can reach the port
+ * unauthenticated can reach the MCP fan-out.
+ */
+export function loopbackTlsFetchOptions() {
+    return meshTlsFetchOptions(loopbackOrigin());
+}
+/**
+ * The exempt paths as a lookup set, each normalized to a leading slash. Matched exactly, not as
+ * prefixes.
+ */
+export function meshTlsExemptPathSet() {
+    const paths = new Set();
+    for (const entry of config.TLS_MUTUAL_EXEMPT_PATHS) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        paths.add(trimmed.startsWith('/') ? trimmed : `/${trimmed}`);
+    }
+    return paths;
+}
+//# sourceMappingURL=meshTls.js.map

package/dist/http/meshTls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meshTls.js","sourceRoot":"","sources":["../../src/http/meshTls.ts"],"names":[],"mappings":"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"}

package/dist/http/safeFetch.d.ts

@@ -0,0 +1,50 @@
+import { type SafeFetchConnectionOptions, type SafeFetchTlsOptions } from './createSafeDispatcher';
+import type { SsrfMode } from './types';
+/**
+ * The gateway's outbound HTTP entry point. Prefer this over bare `fetch` everywhere in `src/`.
+ *
+ * Under the default `ssrf: 'guard'` mode it refuses to connect to internal/reserved addresses and
+ * denylisted hostnames (see `./urlverify`, ported from servicefoundry-server's PLA-2199). The IP
+ * check runs inside the socket's own DNS lookup, so the validated address is the one connected to
+ * and there is no rebinding window. Pass `ssrf: 'none'` for destinations chosen by tenant
+ * configuration or by us (localhost loopback, cloud metadata) — private endpoints are a supported
+ * feature there, so IP blocking would break them.
+ *
+ * These checks run according to `getSsrfGuardMode()` (`ENABLE_SSRF` / `ENFORCE_SSRF` in
+ * `src/config.ts`), independent of the per-call `ssrf` option:
+ *   - `off`: no classification runs at all.
+ *   - `monitor`: classification runs but a violation is only logged, not blocked.
+ *   - `enforce`: classification runs and a violation throws `SSRFError`.
+ * A deployment that enables the guard is responsible for tuning `config.URL_VERIFY_CONFIG` for its
+ * own private ranges.
+ *
+ * Redirects are followed like `fetch` follows them, except that every hop is validated before it is
+ * connected to — see {@link guardedFetch}. The caller's `redirect` option is honored as-is.
+ *
+ * Node's own `fetch` already rejects non-http(s) URLs and URLs with embedded credentials before any
+ * network activity, so safeFetch does not duplicate those checks.
+ */
+export interface SafeFetchInit extends RequestInit {
+    /** Defaults to `'guard'`. See {@link SsrfMode}. */
+    ssrf?: SsrfMode;
+    /** Replaces the per-call undici dispatchers that used to carry custom CAs. */
+    tls?: SafeFetchTlsOptions;
+    /** Overrides the process-wide proxy and undici timeouts. Only needed by the MCP gateway. */
+    connection?: SafeFetchConnectionOptions;
+    /**
+     * Tenant for SSRF monitor-mode logs (`SessionContext.tenantName`). Entered into
+     * request ALS for this fetch (and its redirect hops / guarded DNS lookups).
+     * Not forwarded as an HTTP header.
+     */
+    tenantName?: string;
+}
+/**
+ * The same internal-address validation `safeFetch` runs before connecting, exposed for callers that
+ * can't route their actual request through `safeFetch` itself — e.g. a caller that needs to inspect
+ * every hop of a redirect chain rather than only its final response. Re-run this on every hop of a
+ * manually-followed redirect chain, not just the first URL.
+ */
+export declare function assertSafeToFetch(url: URL, ssrf?: SsrfMode, connection?: SafeFetchConnectionOptions): Promise<void>;
+export declare function safeFetch(input: string | URL | Request, init?: SafeFetchInit): Promise<Response>;
+export default safeFetch;
+//# sourceMappingURL=safeFetch.d.ts.map

package/dist/http/safeFetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeFetch.d.ts","sourceRoot":"","sources":["../../src/http/safeFetch.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,mDAAmD;IACnD,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,mBAAmB,CAAC;IAC1B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA6DD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,GAAG,EACR,IAAI,GAAE,QAAkB,EACxB,UAAU,CAAC,EAAE,0BAA0B,GACtC,OAAO,CAAC,IAAI,CAAC,CAKf;AA6KD,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAM1G;AAED,eAAe,SAAS,CAAC"}