@stigmer/runner 3.18.0 → 3.19.0

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"743b3c1774352cc9","builtAt":"2026-09-18T15:39:55.306Z","fileCount":329}
+{"hash":"6742d02a5e9d864d","builtAt":"2026-09-19T18:45:10.207Z","fileCount":329}

package/dist/shared/mcp-oauth-detect.d.ts

@@ -1,23 +1,4 @@
-/**
- * OAuth-challenge classification for HTTP MCP endpoints.
- *
- * When an HTTP MCP endpoint requires OAuth (per the MCP Authorization spec /
- * RFC 9728), an unauthenticated or statically-tokened request is answered with
- * `401` and a `WWW-Authenticate: Bearer ...` header pointing at OAuth protected
- * resource metadata. The MCP client SDK surfaces this only as an opaque
- * aggregate error ("unhandled errors in a TaskGroup"), which tells the user
- * nothing.
- *
- * This module turns that opaque failure into a precise, actionable signal: it
- * re-probes the endpoint once (only on the failure path, so the happy path pays
- * nothing) and, if it sees an OAuth challenge, returns an {@link
- * OAuthRequiredError} whose message tells the user to connect via OAuth instead
- * of a manual token.
- *
- * Kept transport-library-agnostic (uses global `fetch`) so it is reusable by
- * connect-time discovery, execution-time error enrichment, and any other caller
- * that holds an MCP endpoint URL + headers.
- */
+export { isOAuthChallenge, parseResourceMetadataUrl } from "@stigmer/outbound/mcp-oauth";
 /**
  * Raised when an HTTP MCP endpoint answers with an OAuth authentication
  * challenge. The message is self-contained and user-facing: it survives the
@@ -31,17 +12,6 @@ export declare class OAuthRequiredError extends Error {
     readonly resourceMetadataUrl?: string | undefined;
     constructor(serverSlug: string, resourceMetadataUrl?: string | undefined);
 }
-/**
- * Whether a `WWW-Authenticate` header value is an OAuth challenge.
- *
- * The MCP auth spec emits `Bearer realm="OAuth", resource_metadata="..."`. We
- * require the `Bearer` scheme plus either an OAuth realm or a resource-metadata
- * pointer, so a plain `Bearer` 401 from a static-token API (an invalid key, not
- * an OAuth requirement) is not misclassified.
- */
-export declare function isOAuthChallenge(wwwAuthenticate: string): boolean;
-/** Extract the `resource_metadata` URL from a `WWW-Authenticate` value, if present. */
-export declare function parseResourceMetadataUrl(wwwAuthenticate: string): string | undefined;
 /**
  * Probe an HTTP MCP endpoint once to decide whether its failure is an OAuth
  * challenge. Returns an {@link OAuthRequiredError} to throw, or `null` when the

package/dist/shared/mcp-oauth-detect.js

@@ -14,11 +14,23 @@
  * OAuthRequiredError} whose message tells the user to connect via OAuth instead
  * of a manual token.
  *
- * Kept transport-library-agnostic (uses global `fetch`) so it is reusable by
- * connect-time discovery, execution-time error enrichment, and any other caller
- * that holds an MCP endpoint URL + headers.
+ * The rule and the request have one home, `@stigmer/outbound/mcp-oauth`,
+ * shared with the control plane (which asks the same question of a URL-only
+ * server at save time, so the Sign in button exists before the first run)
+ * and the catalogue audit. The request is the complete `initialize`
+ * (protocol version, capabilities, client info): several hosted servers
+ * validate the request before they check authentication and answer a bare
+ * one with HTTP 200 and a JSON-RPC error, so the bare request this module
+ * once sent never reached their 401 (stigmer #1188). What stays here is the
+ * runner's own: its deadline, its name in the handshake, and the sentence
+ * the user reads.
  */
+import { probeEndpointAuth } from "@stigmer/outbound/mcp-oauth";
+export { isOAuthChallenge, parseResourceMetadataUrl } from "@stigmer/outbound/mcp-oauth";
+/** The failure path can afford a patient probe; a save cannot, and uses its own. */
 const OAUTH_PROBE_TIMEOUT_MS = 10_000;
+/** How the runner names itself in the handshake's `clientInfo`. */
+const PROBE_CLIENT_NAME = "stigmer-runner";
 /**
  * Raised when an HTTP MCP endpoint answers with an OAuth authentication
  * challenge. The message is self-contained and user-facing: it survives the
@@ -39,25 +51,6 @@ export class OAuthRequiredError extends Error {
         this.name = "OAuthRequiredError";
     }
 }
-/**
- * Whether a `WWW-Authenticate` header value is an OAuth challenge.
- *
- * The MCP auth spec emits `Bearer realm="OAuth", resource_metadata="..."`. We
- * require the `Bearer` scheme plus either an OAuth realm or a resource-metadata
- * pointer, so a plain `Bearer` 401 from a static-token API (an invalid key, not
- * an OAuth requirement) is not misclassified.
- */
-export function isOAuthChallenge(wwwAuthenticate) {
-    const value = wwwAuthenticate.toLowerCase();
-    if (!value.includes("bearer"))
-        return false;
-    return value.includes("oauth") || value.includes("resource_metadata");
-}
-/** Extract the `resource_metadata` URL from a `WWW-Authenticate` value, if present. */
-export function parseResourceMetadataUrl(wwwAuthenticate) {
-    const match = /resource_metadata="([^"]+)"/i.exec(wwwAuthenticate);
-    return match?.[1];
-}
 /**
  * Probe an HTTP MCP endpoint once to decide whether its failure is an OAuth
  * challenge. Returns an {@link OAuthRequiredError} to throw, or `null` when the
@@ -67,33 +60,13 @@ export function parseResourceMetadataUrl(wwwAuthenticate) {
  * step can never mask or replace the original discovery error.
  */
 export async function detectOAuthChallenge(url, headers, slug) {
-    try {
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Accept: "application/json, text/event-stream",
-                ...(headers ?? {}),
-            },
-            // A minimal MCP initialize request — enough to trigger the endpoint's
-            // auth check without establishing a session.
-            body: JSON.stringify({
-                jsonrpc: "2.0",
-                id: 1,
-                method: "initialize",
-                params: {},
-            }),
-            signal: AbortSignal.timeout(OAUTH_PROBE_TIMEOUT_MS),
-        });
-        if (response.status !== 401)
-            return null;
-        const wwwAuthenticate = response.headers.get("www-authenticate") ?? "";
-        if (!isOAuthChallenge(wwwAuthenticate))
-            return null;
-        return new OAuthRequiredError(slug, parseResourceMetadataUrl(wwwAuthenticate));
-    }
-    catch {
+    const outcome = await probeEndpointAuth(url, headers, {
+        fetchImpl: fetch,
+        timeoutMs: OAUTH_PROBE_TIMEOUT_MS,
+        clientName: PROBE_CLIENT_NAME,
+    });
+    if (outcome.kind !== "oauth")
         return null;
-    }
+    return new OAuthRequiredError(slug, outcome.resourceMetadataUrl);
 }
 //# sourceMappingURL=mcp-oauth-detect.js.map

package/dist/shared/mcp-oauth-detect.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-oauth-detect.js","sourceRoot":"","sources":["../../src/shared/mcp-oauth-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IACA;IAFlB,YACkB,UAAkB,EAClB,mBAA4B;QAE5C,KAAK,CACH,eAAe,UAAU,6CAA6C;YACpE,yEAAyE;YACzE,mEAAmE,CACtE,CAAC;QAPc,eAAU,GAAV,UAAU,CAAQ;QAClB,wBAAmB,GAAnB,mBAAmB,CAAS;QAO5C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,eAAuB;IACtD,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;AACxE,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,wBAAwB,CACtC,eAAuB;IAEvB,MAAM,KAAK,GAAG,8BAA8B,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACnE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAW,EACX,OAA2C,EAC3C,IAAY;IAEZ,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,qCAAqC;gBAC7C,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;aACnB;YACD,sEAAsE;YACtE,6CAA6C;YAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,CAAC;gBACL,MAAM,EAAE,YAAY;gBACpB,MAAM,EAAE,EAAE;aACX,CAAC;YACF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,sBAAsB,CAAC;SACpD,CAAC,CAAC;QAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAEzC,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACvE,IAAI,CAAC,gBAAgB,CAAC,eAAe,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpD,OAAO,IAAI,kBAAkB,CAC3B,IAAI,EACJ,wBAAwB,CAAC,eAAe,CAAC,CAC1C,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"mcp-oauth-detect.js","sourceRoot":"","sources":["../../src/shared/mcp-oauth-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAEzF,oFAAoF;AACpF,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAEtC,mEAAmE;AACnE,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IACA;IAFlB,YACkB,UAAkB,EAClB,mBAA4B;QAE5C,KAAK,CACH,eAAe,UAAU,6CAA6C;YACpE,yEAAyE;YACzE,mEAAmE,CACtE,CAAC;QAPc,eAAU,GAAV,UAAU,CAAQ;QAClB,wBAAmB,GAAnB,mBAAmB,CAAS;QAO5C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAW,EACX,OAA2C,EAC3C,IAAY;IAEZ,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE;QACpD,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,sBAAsB;QACjC,UAAU,EAAE,iBAAiB;KAC9B,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,IAAI,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACnE,CAAC"}

package/dist/tools/url-guard.d.ts

@@ -8,6 +8,12 @@
  * with network reach to internal services and the cloud metadata endpoint —
  * without this guard, "fetch a URL" becomes "read my pod's credentials".
  *
+ * The address rule itself (which ranges each posture refuses, how an
+ * IPv4-mapped IPv6 is unwrapped, how every resolved address is judged) has
+ * one home, `@stigmer/outbound/egress`, shared with the control plane, which
+ * dials user-supplied URLs too. This module keeps what is the runner's:
+ * deriving the posture from its mode, and the sentence a model reads.
+ *
  * Posture is mode-aware because locality differs, not trust:
  *
  * - "strict" (managed cloud runners): loopback, RFC 1918 private,
@@ -28,12 +34,11 @@
  *
  * Validation runs on the addresses DNS resolves to immediately before the
  * request is dispatched, and the caller re-validates every redirect hop.
- * Accepted limitation: a DNS-rebinding window remains between our lookup
- * and the socket connect — Node's fetch (undici) offers no lookup pinning
- * without replacing the dispatcher, and the strict posture's range blocks
- * make the rebinding payoff (an internal address) unreachable anyway.
+ * The accepted DNS-rebinding limitation is stated in the shared check's
+ * header.
  */
-export type GuardPosture = "strict" | "relaxed";
+import { type EgressPosture } from "@stigmer/outbound/egress";
+export type GuardPosture = EgressPosture;
 /** Thrown for every guard rejection; message is safe to surface to the model. */
 export declare class UrlGuardError extends Error {
     constructor(message: string);

package/dist/tools/url-guard.js

@@ -8,6 +8,12 @@
  * with network reach to internal services and the cloud metadata endpoint —
  * without this guard, "fetch a URL" becomes "read my pod's credentials".
  *
+ * The address rule itself (which ranges each posture refuses, how an
+ * IPv4-mapped IPv6 is unwrapped, how every resolved address is judged) has
+ * one home, `@stigmer/outbound/egress`, shared with the control plane, which
+ * dials user-supplied URLs too. This module keeps what is the runner's:
+ * deriving the posture from its mode, and the sentence a model reads.
+ *
  * Posture is mode-aware because locality differs, not trust:
  *
  * - "strict" (managed cloud runners): loopback, RFC 1918 private,
@@ -28,13 +34,10 @@
  *
  * Validation runs on the addresses DNS resolves to immediately before the
  * request is dispatched, and the caller re-validates every redirect hop.
- * Accepted limitation: a DNS-rebinding window remains between our lookup
- * and the socket connect — Node's fetch (undici) offers no lookup pinning
- * without replacing the dispatcher, and the strict posture's range blocks
- * make the rebinding payoff (an internal address) unreachable anyway.
+ * The accepted DNS-rebinding limitation is stated in the shared check's
+ * header.
  */
-import { lookup } from "node:dns/promises";
-import { isIP } from "node:net";
+import { checkEgress, egressPolicyForPosture, nodeLookup, blockedReason as sharedBlockedReason, } from "@stigmer/outbound/egress";
 /** Thrown for every guard rejection; message is safe to surface to the model. */
 export class UrlGuardError extends Error {
     constructor(message) {
@@ -56,6 +59,7 @@ export function resolveGuardPosture(mode, env = process.env) {
         return "strict";
     return mode === "cloud" ? "strict" : "relaxed";
 }
+const lookup = nodeLookup();
 /**
  * Validate a URL for fetching under the given posture.
  *
@@ -67,41 +71,28 @@ export function resolveGuardPosture(mode, env = process.env) {
  * @throws UrlGuardError with a model-readable reason on rejection.
  */
 export async function validateFetchUrl(rawUrl, posture) {
-    let url;
-    try {
-        url = new URL(rawUrl);
-    }
-    catch {
-        throw new UrlGuardError(`Invalid URL: ${rawUrl}`);
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new UrlGuardError(`Unsupported URL scheme "${url.protocol.replace(/:$/, "")}" — only http and https are allowed.`);
-    }
-    const addresses = await resolveAddresses(url.hostname);
-    for (const address of addresses) {
-        const reason = blockedReason(address, posture);
-        if (reason) {
-            throw new UrlGuardError(`Refusing to fetch ${url.hostname}: it resolves to ${address}, a ${reason} address that this runner does not fetch from.`);
+    const check = await checkEgress(rawUrl, egressPolicyForPosture(posture), { lookup });
+    if (check.ok)
+        return check.url;
+    const refusal = check.refusal;
+    switch (refusal.kind) {
+        case "invalid-url":
+            throw new UrlGuardError(`Invalid URL: ${refusal.url}`);
+        case "unsupported-scheme":
+            throw new UrlGuardError(`Unsupported URL scheme "${refusal.scheme}" — only http and https are allowed.`);
+        case "unresolvable":
+            throw new UrlGuardError(`Could not resolve hostname: ${refusal.hostname}`);
+        case "blocked":
+            throw new UrlGuardError(`Refusing to fetch ${refusal.hostname}: it resolves to ${refusal.address}, a ${refusal.reason} address that this runner does not fetch from.`);
+        case "too-many-redirects":
+            // The check itself never follows a redirect; web_fetch walks hops
+            // one validateFetchUrl at a time, so this refusal cannot arise here.
+            throw new UrlGuardError(`Refusing to follow more than ${refusal.hops} redirects.`);
+        default: {
+            const exhaustive = refusal;
+            throw new UrlGuardError(String(exhaustive));
         }
     }
-    return url;
-}
-/**
- * Resolve a hostname to all of its addresses. Literal IPs pass through
- * (bracketed IPv6 hosts arrive from URL.hostname still bracketed).
- */
-async function resolveAddresses(hostname) {
-    const literal = hostname.replace(/^\[|\]$/g, "");
-    if (isIP(literal) !== 0) {
-        return [literal];
-    }
-    try {
-        const records = await lookup(hostname, { all: true, verbatim: true });
-        return records.map((r) => r.address);
-    }
-    catch {
-        throw new UrlGuardError(`Could not resolve hostname: ${hostname}`);
-    }
 }
 /**
  * Classify an IP address against the posture's blocked ranges.
@@ -109,103 +100,6 @@ async function resolveAddresses(hostname) {
  * @returns a human-readable range name when blocked, or null when allowed.
  */
 export function blockedReason(address, posture) {
-    const family = isIP(address);
-    if (family === 4) {
-        return blockedReasonV4(address, posture);
-    }
-    if (family === 6) {
-        const groups = expandV6(address);
-        if (!groups)
-            return "unrecognized";
-        // IPv4-mapped IPv6 (::ffff:a.b.c.d, in dotted OR hex form) — classify
-        // the embedded IPv4 so the mapping cannot smuggle a blocked v4 address
-        // past the guard.
-        const embedded = extractMappedV4(groups);
-        if (embedded) {
-            return blockedReasonV4(embedded, posture);
-        }
-        return blockedReasonV6(groups, posture);
-    }
-    // Unparseable — fail closed; only real addresses get sockets.
-    return "unrecognized";
-}
-function blockedReasonV4(address, posture) {
-    const octets = address.split(".").map(Number);
-    if (octets.length !== 4 || octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) {
-        return "unrecognized";
-    }
-    const [a, b] = octets;
-    // Link-local (169.254.0.0/16) hosts the cloud metadata service at
-    // 169.254.169.254 — blocked under BOTH postures.
-    if (a === 169 && b === 254)
-        return "link-local (cloud metadata)";
-    if (posture === "relaxed")
-        return null;
-    if (a === 127)
-        return "loopback";
-    if (a === 0)
-        return "unspecified";
-    if (a === 10)
-        return "private (RFC 1918)";
-    if (a === 172 && b >= 16 && b <= 31)
-        return "private (RFC 1918)";
-    if (a === 192 && b === 168)
-        return "private (RFC 1918)";
-    return null;
-}
-function blockedReasonV6(groups, posture) {
-    // fe80::/10 — IPv6 link-local, the v6 sibling of the metadata range;
-    // blocked under BOTH postures for symmetry with v4.
-    if ((groups[0] & 0xffc0) === 0xfe80)
-        return "link-local (cloud metadata)";
-    if (posture === "relaxed")
-        return null;
-    const allZero = groups.every((g) => g === 0);
-    if (allZero)
-        return "unspecified";
-    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
-        return "loopback";
-    // fc00::/7 — unique local (private) addresses.
-    if ((groups[0] & 0xfe00) === 0xfc00)
-        return "private (unique local)";
-    return null;
-}
-/**
- * Expand an IPv6 address (already validated by isIP) into its 8 groups.
- * Handles `::` compression, a trailing dotted-IPv4 tail, and zone suffixes.
- */
-function expandV6(address) {
-    let text = address.toLowerCase().split("%")[0];
-    // Convert a dotted-IPv4 tail (e.g. ::ffff:127.0.0.1) into two hex groups.
-    const v4Tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
-    if (v4Tail) {
-        const octets = v4Tail[1].split(".").map(Number);
-        if (octets.length !== 4 || octets.some((o) => o > 255))
-            return null;
-        const hex = `${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
-        text = text.slice(0, -v4Tail[1].length) + hex;
-    }
-    const halves = text.split("::");
-    if (halves.length > 2)
-        return null;
-    const parseHalf = (half) => half === "" ? [] : half.split(":").map((g) => parseInt(g, 16));
-    const head = parseHalf(halves[0]);
-    const tail = halves.length === 2 ? parseHalf(halves[1]) : [];
-    const fill = 8 - head.length - tail.length;
-    if (halves.length === 2 ? fill < 0 : head.length !== 8)
-        return null;
-    const groups = [...head, ...(halves.length === 2 ? Array(fill).fill(0) : []), ...tail];
-    if (groups.length !== 8 || groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff)) {
-        return null;
-    }
-    return groups;
-}
-/** Extract the IPv4 payload from IPv4-mapped groups (::ffff:0:0/96), if any. */
-function extractMappedV4(groups) {
-    const isMapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
-    if (!isMapped)
-        return null;
-    const [hi, lo] = [groups[6], groups[7]];
-    return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+    return sharedBlockedReason(address, posture);
 }
 //# sourceMappingURL=url-guard.js.map

package/dist/tools/url-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"url-guard.js","sourceRoot":"","sources":["../../src/tools/url-guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"url-guard.js","sourceRoot":"","sources":["../../src/tools/url-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,UAAU,EACV,aAAa,IAAI,mBAAmB,GAErC,MAAM,0BAA0B,CAAC;AAIlC,iFAAiF;AACjF,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAuB,EACvB,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,QAAQ,GAAG,GAAG,CAAC,+BAA+B,CAAC;IACrD,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC;IAC1C,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACjD,CAAC;AAED,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;AAE5B;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAc,EACd,OAAqB;IAErB,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACrF,IAAI,KAAK,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC;IAE/B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,aAAa;YAChB,MAAM,IAAI,aAAa,CAAC,gBAAgB,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACzD,KAAK,oBAAoB;YACvB,MAAM,IAAI,aAAa,CACrB,2BAA2B,OAAO,CAAC,MAAM,sCAAsC,CAChF,CAAC;QACJ,KAAK,cAAc;YACjB,MAAM,IAAI,aAAa,CAAC,+BAA+B,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC7E,KAAK,SAAS;YACZ,MAAM,IAAI,aAAa,CACrB,qBAAqB,OAAO,CAAC,QAAQ,oBAAoB,OAAO,CAAC,OAAO,OAAO,OAAO,CAAC,MAAM,gDAAgD,CAC9I,CAAC;QACJ,KAAK,oBAAoB;YACvB,kEAAkE;YAClE,qEAAqE;YACrE,MAAM,IAAI,aAAa,CAAC,gCAAgC,OAAO,CAAC,IAAI,aAAa,CAAC,CAAC;QACrF,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,UAAU,GAAU,OAAO,CAAC;YAClC,MAAM,IAAI,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,OAAqB;IAClE,OAAO,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC/C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -104,9 +104,10 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.18.0",
-    "@stigmer/temporal-codecs": "3.18.0",
-    "@stigmer/zip-structure": "3.18.0",
+    "@stigmer/outbound": "3.19.0",
+    "@stigmer/protos": "3.19.0",
+    "@stigmer/temporal-codecs": "3.19.0",
+    "@stigmer/zip-structure": "3.19.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/common": "1.16.2",
     "@temporalio/interceptors-opentelemetry": "1.16.2",

package/src/shared/__tests__/mcp-oauth-detect.test.ts

@@ -144,4 +144,24 @@ describe("detectOAuthChallenge", () => {
     );
     expect(init?.method).toBe("POST");
   });
+
+  it("sends a complete initialize naming the runner, so servers that validate before they authenticate reach their 401 (#1188)", async () => {
+    const fetchMock = vi.fn(
+      async (_url: string | URL, _init?: RequestInit) =>
+        new Response(null, { status: 200 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await detectOAuthChallenge("https://mcp.example.com/mcp", undefined, "example");
+
+    const init = fetchMock.mock.calls[0]?.[1];
+    const body = JSON.parse(String(init?.body)) as {
+      method: string;
+      params: { protocolVersion?: string; capabilities?: object; clientInfo?: { name: string } };
+    };
+    expect(body.method).toBe("initialize");
+    expect(body.params.protocolVersion).toBe("2025-06-18");
+    expect(body.params.capabilities).toEqual({});
+    expect(body.params.clientInfo?.name).toBe("stigmer-runner");
+  });
 });

package/src/shared/mcp-oauth-detect.ts

@@ -14,13 +14,27 @@
  * OAuthRequiredError} whose message tells the user to connect via OAuth instead
  * of a manual token.
  *
- * Kept transport-library-agnostic (uses global `fetch`) so it is reusable by
- * connect-time discovery, execution-time error enrichment, and any other caller
- * that holds an MCP endpoint URL + headers.
+ * The rule and the request have one home, `@stigmer/outbound/mcp-oauth`,
+ * shared with the control plane (which asks the same question of a URL-only
+ * server at save time, so the Sign in button exists before the first run)
+ * and the catalogue audit. The request is the complete `initialize`
+ * (protocol version, capabilities, client info): several hosted servers
+ * validate the request before they check authentication and answer a bare
+ * one with HTTP 200 and a JSON-RPC error, so the bare request this module
+ * once sent never reached their 401 (stigmer #1188). What stays here is the
+ * runner's own: its deadline, its name in the handshake, and the sentence
+ * the user reads.
  */
+import { probeEndpointAuth } from "@stigmer/outbound/mcp-oauth";
 
+export { isOAuthChallenge, parseResourceMetadataUrl } from "@stigmer/outbound/mcp-oauth";
+
+/** The failure path can afford a patient probe; a save cannot, and uses its own. */
 const OAUTH_PROBE_TIMEOUT_MS = 10_000;
 
+/** How the runner names itself in the handshake's `clientInfo`. */
+const PROBE_CLIENT_NAME = "stigmer-runner";
+
 /**
  * Raised when an HTTP MCP endpoint answers with an OAuth authentication
  * challenge. The message is self-contained and user-facing: it survives the
@@ -43,28 +57,6 @@ export class OAuthRequiredError extends Error {
   }
 }
 
-/**
- * Whether a `WWW-Authenticate` header value is an OAuth challenge.
- *
- * The MCP auth spec emits `Bearer realm="OAuth", resource_metadata="..."`. We
- * require the `Bearer` scheme plus either an OAuth realm or a resource-metadata
- * pointer, so a plain `Bearer` 401 from a static-token API (an invalid key, not
- * an OAuth requirement) is not misclassified.
- */
-export function isOAuthChallenge(wwwAuthenticate: string): boolean {
-  const value = wwwAuthenticate.toLowerCase();
-  if (!value.includes("bearer")) return false;
-  return value.includes("oauth") || value.includes("resource_metadata");
-}
-
-/** Extract the `resource_metadata` URL from a `WWW-Authenticate` value, if present. */
-export function parseResourceMetadataUrl(
-  wwwAuthenticate: string,
-): string | undefined {
-  const match = /resource_metadata="([^"]+)"/i.exec(wwwAuthenticate);
-  return match?.[1];
-}
-
 /**
  * Probe an HTTP MCP endpoint once to decide whether its failure is an OAuth
  * challenge. Returns an {@link OAuthRequiredError} to throw, or `null` when the
@@ -78,35 +70,11 @@ export async function detectOAuthChallenge(
   headers: Record<string, string> | undefined,
   slug: string,
 ): Promise<OAuthRequiredError | null> {
-  try {
-    const response = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json, text/event-stream",
-        ...(headers ?? {}),
-      },
-      // A minimal MCP initialize request — enough to trigger the endpoint's
-      // auth check without establishing a session.
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "initialize",
-        params: {},
-      }),
-      signal: AbortSignal.timeout(OAUTH_PROBE_TIMEOUT_MS),
-    });
-
-    if (response.status !== 401) return null;
-
-    const wwwAuthenticate = response.headers.get("www-authenticate") ?? "";
-    if (!isOAuthChallenge(wwwAuthenticate)) return null;
-
-    return new OAuthRequiredError(
-      slug,
-      parseResourceMetadataUrl(wwwAuthenticate),
-    );
-  } catch {
-    return null;
-  }
+  const outcome = await probeEndpointAuth(url, headers, {
+    fetchImpl: fetch,
+    timeoutMs: OAUTH_PROBE_TIMEOUT_MS,
+    clientName: PROBE_CLIENT_NAME,
+  });
+  if (outcome.kind !== "oauth") return null;
+  return new OAuthRequiredError(slug, outcome.resourceMetadataUrl);
 }

package/src/tools/url-guard.ts

@@ -8,6 +8,12 @@
  * with network reach to internal services and the cloud metadata endpoint —
  * without this guard, "fetch a URL" becomes "read my pod's credentials".
  *
+ * The address rule itself (which ranges each posture refuses, how an
+ * IPv4-mapped IPv6 is unwrapped, how every resolved address is judged) has
+ * one home, `@stigmer/outbound/egress`, shared with the control plane, which
+ * dials user-supplied URLs too. This module keeps what is the runner's:
+ * deriving the posture from its mode, and the sentence a model reads.
+ *
  * Posture is mode-aware because locality differs, not trust:
  *
  * - "strict" (managed cloud runners): loopback, RFC 1918 private,
@@ -28,16 +34,18 @@
  *
  * Validation runs on the addresses DNS resolves to immediately before the
  * request is dispatched, and the caller re-validates every redirect hop.
- * Accepted limitation: a DNS-rebinding window remains between our lookup
- * and the socket connect — Node's fetch (undici) offers no lookup pinning
- * without replacing the dispatcher, and the strict posture's range blocks
- * make the rebinding payoff (an internal address) unreachable anyway.
+ * The accepted DNS-rebinding limitation is stated in the shared check's
+ * header.
  */
+import {
+  checkEgress,
+  egressPolicyForPosture,
+  nodeLookup,
+  blockedReason as sharedBlockedReason,
+  type EgressPosture,
+} from "@stigmer/outbound/egress";
 
-import { lookup } from "node:dns/promises";
-import { isIP } from "node:net";
-
-export type GuardPosture = "strict" | "relaxed";
+export type GuardPosture = EgressPosture;
 
 /** Thrown for every guard rejection; message is safe to surface to the model. */
 export class UrlGuardError extends Error {
@@ -63,6 +71,8 @@ export function resolveGuardPosture(
   return mode === "cloud" ? "strict" : "relaxed";
 }
 
+const lookup = nodeLookup();
+
 /**
  * Validate a URL for fetching under the given posture.
  *
@@ -77,48 +87,32 @@ export async function validateFetchUrl(
   rawUrl: string,
   posture: GuardPosture,
 ): Promise<URL> {
-  let url: URL;
-  try {
-    url = new URL(rawUrl);
-  } catch {
-    throw new UrlGuardError(`Invalid URL: ${rawUrl}`);
-  }
-
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new UrlGuardError(
-      `Unsupported URL scheme "${url.protocol.replace(/:$/, "")}" — only http and https are allowed.`,
-    );
-  }
-
-  const addresses = await resolveAddresses(url.hostname);
-  for (const address of addresses) {
-    const reason = blockedReason(address, posture);
-    if (reason) {
+  const check = await checkEgress(rawUrl, egressPolicyForPosture(posture), { lookup });
+  if (check.ok) return check.url;
+
+  const refusal = check.refusal;
+  switch (refusal.kind) {
+    case "invalid-url":
+      throw new UrlGuardError(`Invalid URL: ${refusal.url}`);
+    case "unsupported-scheme":
       throw new UrlGuardError(
-        `Refusing to fetch ${url.hostname}: it resolves to ${address}, a ${reason} address that this runner does not fetch from.`,
+        `Unsupported URL scheme "${refusal.scheme}" — only http and https are allowed.`,
       );
+    case "unresolvable":
+      throw new UrlGuardError(`Could not resolve hostname: ${refusal.hostname}`);
+    case "blocked":
+      throw new UrlGuardError(
+        `Refusing to fetch ${refusal.hostname}: it resolves to ${refusal.address}, a ${refusal.reason} address that this runner does not fetch from.`,
+      );
+    case "too-many-redirects":
+      // The check itself never follows a redirect; web_fetch walks hops
+      // one validateFetchUrl at a time, so this refusal cannot arise here.
+      throw new UrlGuardError(`Refusing to follow more than ${refusal.hops} redirects.`);
+    default: {
+      const exhaustive: never = refusal;
+      throw new UrlGuardError(String(exhaustive));
     }
   }
-
-  return url;
-}
-
-/**
- * Resolve a hostname to all of its addresses. Literal IPs pass through
- * (bracketed IPv6 hosts arrive from URL.hostname still bracketed).
- */
-async function resolveAddresses(hostname: string): Promise<string[]> {
-  const literal = hostname.replace(/^\[|\]$/g, "");
-  if (isIP(literal) !== 0) {
-    return [literal];
-  }
-
-  try {
-    const records = await lookup(hostname, { all: true, verbatim: true });
-    return records.map((r) => r.address);
-  } catch {
-    throw new UrlGuardError(`Could not resolve hostname: ${hostname}`);
-  }
 }
 
 /**
@@ -127,106 +121,5 @@ async function resolveAddresses(hostname: string): Promise<string[]> {
  * @returns a human-readable range name when blocked, or null when allowed.
  */
 export function blockedReason(address: string, posture: GuardPosture): string | null {
-  const family = isIP(address);
-
-  if (family === 4) {
-    return blockedReasonV4(address, posture);
-  }
-
-  if (family === 6) {
-    const groups = expandV6(address);
-    if (!groups) return "unrecognized";
-
-    // IPv4-mapped IPv6 (::ffff:a.b.c.d, in dotted OR hex form) — classify
-    // the embedded IPv4 so the mapping cannot smuggle a blocked v4 address
-    // past the guard.
-    const embedded = extractMappedV4(groups);
-    if (embedded) {
-      return blockedReasonV4(embedded, posture);
-    }
-    return blockedReasonV6(groups, posture);
-  }
-
-  // Unparseable — fail closed; only real addresses get sockets.
-  return "unrecognized";
-}
-
-function blockedReasonV4(address: string, posture: GuardPosture): string | null {
-  const octets = address.split(".").map(Number);
-  if (octets.length !== 4 || octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) {
-    return "unrecognized";
-  }
-  const [a, b] = octets;
-
-  // Link-local (169.254.0.0/16) hosts the cloud metadata service at
-  // 169.254.169.254 — blocked under BOTH postures.
-  if (a === 169 && b === 254) return "link-local (cloud metadata)";
-
-  if (posture === "relaxed") return null;
-
-  if (a === 127) return "loopback";
-  if (a === 0) return "unspecified";
-  if (a === 10) return "private (RFC 1918)";
-  if (a === 172 && b >= 16 && b <= 31) return "private (RFC 1918)";
-  if (a === 192 && b === 168) return "private (RFC 1918)";
-
-  return null;
-}
-
-function blockedReasonV6(groups: readonly number[], posture: GuardPosture): string | null {
-  // fe80::/10 — IPv6 link-local, the v6 sibling of the metadata range;
-  // blocked under BOTH postures for symmetry with v4.
-  if ((groups[0] & 0xffc0) === 0xfe80) return "link-local (cloud metadata)";
-
-  if (posture === "relaxed") return null;
-
-  const allZero = groups.every((g) => g === 0);
-  if (allZero) return "unspecified";
-  if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return "loopback";
-  // fc00::/7 — unique local (private) addresses.
-  if ((groups[0] & 0xfe00) === 0xfc00) return "private (unique local)";
-
-  return null;
-}
-
-/**
- * Expand an IPv6 address (already validated by isIP) into its 8 groups.
- * Handles `::` compression, a trailing dotted-IPv4 tail, and zone suffixes.
- */
-function expandV6(address: string): number[] | null {
-  let text = address.toLowerCase().split("%")[0];
-
-  // Convert a dotted-IPv4 tail (e.g. ::ffff:127.0.0.1) into two hex groups.
-  const v4Tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
-  if (v4Tail) {
-    const octets = v4Tail[1].split(".").map(Number);
-    if (octets.length !== 4 || octets.some((o) => o > 255)) return null;
-    const hex = `${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
-    text = text.slice(0, -v4Tail[1].length) + hex;
-  }
-
-  const halves = text.split("::");
-  if (halves.length > 2) return null;
-
-  const parseHalf = (half: string): number[] =>
-    half === "" ? [] : half.split(":").map((g) => parseInt(g, 16));
-
-  const head = parseHalf(halves[0]);
-  const tail = halves.length === 2 ? parseHalf(halves[1]) : [];
-  const fill = 8 - head.length - tail.length;
-  if (halves.length === 2 ? fill < 0 : head.length !== 8) return null;
-
-  const groups = [...head, ...(halves.length === 2 ? Array(fill).fill(0) : []), ...tail];
-  if (groups.length !== 8 || groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff)) {
-    return null;
-  }
-  return groups;
-}
-
-/** Extract the IPv4 payload from IPv4-mapped groups (::ffff:0:0/96), if any. */
-function extractMappedV4(groups: readonly number[]): string | null {
-  const isMapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
-  if (!isMapped) return null;
-  const [hi, lo] = [groups[6], groups[7]];
-  return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+  return sharedBlockedReason(address, posture);
 }