@stigmer/outbound 3.18.1-dev.20260919070736

package/egress/fetch.js

@@ -0,0 +1,59 @@
+import { checkEgress, EgressError } from "./check.js";
+/** The default hop budget: a scheme upgrade and a canonicalisation, with one to spare. */
+export const DEFAULT_MAX_REDIRECTS = 3;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * An `OutboundFetch` in the global `fetch`'s shape, for a seam typed
+ * `typeof fetch`. A `Request` input is refused rather than flattened: this
+ * library's callers pass URLs, and a wrapper that silently dropped a
+ * Request's body or headers would be a bug that looked like a network
+ * failure.
+ */
+export function asFetch(outbound) {
+    return (input, init) => {
+        if (typeof input === "string" || input instanceof URL)
+            return outbound(input, init);
+        return Promise.reject(new TypeError("OutboundFetch takes a URL, not a Request"));
+    };
+}
+/** Compose a fetch that judges every URL and every hop under `policy`. */
+export function guardedFetch(policy, options) {
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    return async (input, init) => {
+        let url = new URL(input);
+        let method = (init?.method ?? "GET").toUpperCase();
+        let body = init?.body;
+        const headers = new Headers(init?.headers);
+        const callerRedirect = init?.redirect ?? "follow";
+        for (let hop = 0;; hop += 1) {
+            const check = await checkEgress(url, policy, { lookup: options.lookup, signal: init?.signal });
+            if (!check.ok)
+                throw new EgressError(check.refusal);
+            const response = await options.fetchImpl(url, { ...init, method, body, headers, redirect: "manual" });
+            const location = response.headers.get("location");
+            if (!REDIRECT_STATUSES.has(response.status) || location === null || callerRedirect === "manual") {
+                return response;
+            }
+            if (callerRedirect === "error") {
+                await response.body?.cancel();
+                throw new TypeError(`fetch refused to follow a redirect from ${url.href}`);
+            }
+            if (hop >= maxRedirects) {
+                await response.body?.cancel();
+                throw new EgressError({ kind: "too-many-redirects", url, hops: maxRedirects });
+            }
+            await response.body?.cancel();
+            const next = new URL(location, url);
+            if (next.origin !== url.origin)
+                headers.delete("authorization");
+            if (response.status === 303 || ((response.status === 301 || response.status === 302) && method !== "GET" && method !== "HEAD")) {
+                method = "GET";
+                body = undefined;
+                headers.delete("content-type");
+                headers.delete("content-length");
+            }
+            url = next;
+        }
+    };
+}
+//# sourceMappingURL=fetch.js.map

package/egress/fetch.js.map

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

package/egress/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@stigmer/outbound/egress`: the address policy a Stigmer process dials
+ * user-supplied URLs under, the check that applies it to a URL, and the
+ * fetch that applies it to every hop. See each module's header.
+ */
+export { blockedReason, egressPolicyForPosture, type EgressPolicy, type EgressPosture } from "./address.js";
+export { checkEgress, describeRefusal, EgressError, type EgressCheck, type EgressCheckOptions, type EgressRefusal, type LookupFn, } from "./check.js";
+export { asFetch, DEFAULT_MAX_REDIRECTS, guardedFetch, type GuardedFetchOptions, type OutboundFetch } from "./fetch.js";
+export { nodeLookup } from "./node-lookup.js";
+//# sourceMappingURL=index.d.ts.map

package/egress/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/egress/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAC5G,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,QAAQ,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACxH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/egress/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@stigmer/outbound/egress`: the address policy a Stigmer process dials
+ * user-supplied URLs under, the check that applies it to a URL, and the
+ * fetch that applies it to every hop. See each module's header.
+ */
+export { blockedReason, egressPolicyForPosture } from "./address.js";
+export { checkEgress, describeRefusal, EgressError, } from "./check.js";
+export { asFetch, DEFAULT_MAX_REDIRECTS, guardedFetch } from "./fetch.js";
+export { nodeLookup } from "./node-lookup.js";
+//# sourceMappingURL=index.js.map

package/egress/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/egress/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAyC,MAAM,cAAc,CAAC;AAC5G,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,GAKZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAgD,MAAM,YAAY,CAAC;AACxH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/egress/node-lookup.d.ts

@@ -0,0 +1,4 @@
+import type { LookupFn } from "./check.js";
+/** Resolve through the process's resolver, every record, in resolver order. */
+export declare function nodeLookup(): LookupFn;
+//# sourceMappingURL=node-lookup.d.ts.map

package/egress/node-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-lookup.d.ts","sourceRoot":"","sources":["../../src/egress/node-lookup.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,+EAA+E;AAC/E,wBAAgB,UAAU,IAAI,QAAQ,CAKrC"}

package/egress/node-lookup.js

@@ -0,0 +1,20 @@
+/**
+ * The one Node-bound piece of the egress module: a `LookupFn` over
+ * `node:dns/promises`. Kept in its own file so the judgement (`check.ts`,
+ * `address.ts`) stays free of I/O and a test composes the check with a
+ * table instead of a resolver.
+ *
+ * `all: true` because the check must judge every address a name has;
+ * `verbatim: true` so the resolver's order is kept rather than re-sorted,
+ * which keeps the refusal's named address the one a socket would have
+ * taken first.
+ */
+import { lookup } from "node:dns/promises";
+/** Resolve through the process's resolver, every record, in resolver order. */
+export function nodeLookup() {
+    return async (hostname) => {
+        const records = await lookup(hostname, { all: true, verbatim: true });
+        return records.map((record) => record.address);
+    };
+}
+//# sourceMappingURL=node-lookup.js.map

package/egress/node-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-lookup.js","sourceRoot":"","sources":["../../src/egress/node-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI3C,+EAA+E;AAC/E,MAAM,UAAU,UAAU;IACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACtE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC,CAAC;AACJ,CAAC"}

package/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@stigmer/outbound`: the rules a Stigmer process dials a user-supplied
+ * endpoint by. Two entry points, also reachable as subpaths:
+ * `./egress` (the address policy, its check, the guarded fetch) and
+ * `./mcp-oauth` (reading an MCP endpoint's authentication and finding its
+ * login server). Consumers: the control plane, the runner, the catalogue
+ * audit. The README says why one library and not three copies.
+ */
+export * from "./egress/index.js";
+export * from "./mcp-oauth/index.js";
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@stigmer/outbound`: the rules a Stigmer process dials a user-supplied
+ * endpoint by. Two entry points, also reachable as subpaths:
+ * `./egress` (the address policy, its check, the guarded fetch) and
+ * `./mcp-oauth` (reading an MCP endpoint's authentication and finding its
+ * login server). Consumers: the control plane, the runner, the catalogue
+ * audit. The README says why one library and not three copies.
+ */
+export * from "./egress/index.js";
+export * from "./mcp-oauth/index.js";
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/mcp-oauth/challenge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The OAuth-challenge rule: what a `WWW-Authenticate` header must say for
+ * Stigmer to tell a user "this server requires OAuth".
+ *
+ * One home for a rule three processes apply. The runner applies it at the
+ * first failed tool call (shared/mcp-oauth-detect.ts, where the rule was
+ * born); the control plane applies it at save time so a URL-only server
+ * gets its Sign in button before anyone runs it; the catalogue audit applies
+ * it to decide what the official catalogue may promise. A rule with one copy
+ * per process would let the storefront call OAuth what the runner calls a
+ * bad token.
+ *
+ * The rule, per the MCP Authorization specification and RFC 9728: the
+ * scheme is `Bearer`, and the challenge names either an OAuth realm or a
+ * `resource_metadata` pointer. A plain `Bearer` 401 (an invalid static API
+ * key) is not an OAuth requirement and must not be read as one, or a user
+ * with a mistyped token would be sent to a Sign in that does not exist.
+ *
+ * Proven by __tests__/challenge.test.ts, the runner's cases moved here.
+ */
+/** Whether a `WWW-Authenticate` value is an OAuth challenge. */
+export declare function isOAuthChallenge(wwwAuthenticate: string): boolean;
+/** The `resource_metadata` URL a challenge points at (RFC 9728 section 5.1), if any. */
+export declare function parseResourceMetadataUrl(wwwAuthenticate: string): string | undefined;
+//# sourceMappingURL=challenge.d.ts.map

package/mcp-oauth/challenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../../src/mcp-oauth/challenge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAIjE;AAED,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGpF"}

package/mcp-oauth/challenge.js

@@ -0,0 +1,33 @@
+/**
+ * The OAuth-challenge rule: what a `WWW-Authenticate` header must say for
+ * Stigmer to tell a user "this server requires OAuth".
+ *
+ * One home for a rule three processes apply. The runner applies it at the
+ * first failed tool call (shared/mcp-oauth-detect.ts, where the rule was
+ * born); the control plane applies it at save time so a URL-only server
+ * gets its Sign in button before anyone runs it; the catalogue audit applies
+ * it to decide what the official catalogue may promise. A rule with one copy
+ * per process would let the storefront call OAuth what the runner calls a
+ * bad token.
+ *
+ * The rule, per the MCP Authorization specification and RFC 9728: the
+ * scheme is `Bearer`, and the challenge names either an OAuth realm or a
+ * `resource_metadata` pointer. A plain `Bearer` 401 (an invalid static API
+ * key) is not an OAuth requirement and must not be read as one, or a user
+ * with a mistyped token would be sent to a Sign in that does not exist.
+ *
+ * Proven by __tests__/challenge.test.ts, the runner's cases moved here.
+ */
+/** Whether a `WWW-Authenticate` value is an OAuth challenge. */
+export function isOAuthChallenge(wwwAuthenticate) {
+    const value = wwwAuthenticate.toLowerCase();
+    if (!value.includes("bearer"))
+        return false;
+    return value.includes("oauth") || value.includes("resource_metadata");
+}
+/** The `resource_metadata` URL a challenge points at (RFC 9728 section 5.1), if any. */
+export function parseResourceMetadataUrl(wwwAuthenticate) {
+    const match = /resource_metadata="([^"]+)"/i.exec(wwwAuthenticate);
+    return match?.[1];
+}
+//# sourceMappingURL=challenge.js.map

package/mcp-oauth/challenge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.js","sourceRoot":"","sources":["../../src/mcp-oauth/challenge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gEAAgE;AAChE,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,wFAAwF;AACxF,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,MAAM,KAAK,GAAG,8BAA8B,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACnE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC"}

package/mcp-oauth/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@stigmer/outbound/mcp-oauth`: how an MCP endpoint's authentication is
+ * read without a credential (the challenge rule, the complete `initialize`,
+ * the one-request probe) and how its login server is found (the RFC 9728,
+ * RFC 8414 and OpenID walk). See each module's header.
+ */
+export { isOAuthChallenge, parseResourceMetadataUrl } from "./challenge.js";
+export { authorizationServerMetadataUrls, protectedResourceMetadataUrls, readAuthorizationServerMetadata, resolveAuthorizationServers, type AuthorizationServerMetadata, type MetadataAttempt, type MetadataRead, type MetadataReadDeps, } from "./metadata.js";
+export { probeEndpointAuth, type EndpointAuthOutcome, type EndpointProbeDeps } from "./probe.js";
+export { initializeRequest, MCP_PROTOCOL_VERSION, MCP_SESSION_HEADER, toolsListRequest, type JsonRpcRequestInit, } from "./request.js";
+//# sourceMappingURL=index.d.ts.map

package/mcp-oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp-oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,+BAA+B,EAC/B,2BAA2B,EAC3B,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC"}

package/mcp-oauth/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@stigmer/outbound/mcp-oauth`: how an MCP endpoint's authentication is
+ * read without a credential (the challenge rule, the complete `initialize`,
+ * the one-request probe) and how its login server is found (the RFC 9728,
+ * RFC 8414 and OpenID walk). See each module's header.
+ */
+export { isOAuthChallenge, parseResourceMetadataUrl } from "./challenge.js";
+export { authorizationServerMetadataUrls, protectedResourceMetadataUrls, readAuthorizationServerMetadata, resolveAuthorizationServers, } from "./metadata.js";
+export { probeEndpointAuth } from "./probe.js";
+export { initializeRequest, MCP_PROTOCOL_VERSION, MCP_SESSION_HEADER, toolsListRequest, } from "./request.js";
+//# sourceMappingURL=index.js.map

package/mcp-oauth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp-oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,+BAA+B,EAC/B,2BAA2B,GAK5B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAoD,MAAM,YAAY,CAAC;AACjG,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GAEjB,MAAM,cAAc,CAAC"}

package/mcp-oauth/metadata.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Finding an MCP endpoint's login server: the RFC 9728, RFC 8414 and
+ * OpenID walk, as documents to try in order and the reader that tries them.
+ *
+ * Why a walk and not one URL. Of the 41 OAuth-protected MCP servers the
+ * catalogue audit resolved on 2026-09-19, 21 keep their login server on a
+ * different origin from the MCP URL, which only RFC 9728's protected
+ * resource metadata can point at, and several issuers carry a path, which
+ * RFC 8414 section 3 says to insert the well-known segment BEFORE (an
+ * issuer `https://auth.example/tenant` describes itself at
+ * `https://auth.example/.well-known/oauth-authorization-server/tenant`).
+ * A reader that only asked the MCP origin for `oauth-authorization-server`
+ * reached half of them.
+ *
+ * The order, from the most specific to the fallback that worked before:
+ *
+ *   1. The protected resource's own document: the `resource_metadata` URL
+ *      a 401 challenge named, else `/.well-known/oauth-protected-resource`
+ *      at the MCP origin with the MCP path appended, else bare
+ *      (RFC 9728 section 3). It names `authorization_servers`.
+ *   2. For each issuer named, its authorization-server metadata: RFC 8414
+ *      with the issuer's path inserted, RFC 8414 at the origin, then
+ *      OpenID's `/.well-known/openid-configuration` under the path and at
+ *      the origin (RFC 8414 section 5 allows the OpenID document).
+ *   3. When no protected-resource document exists, the MCP origin itself is
+ *      the one issuer to try, which is exactly the reader this replaces.
+ *
+ * Every attempt is recorded (URL, status or error) so a caller can name the
+ * document it failed on. The reader validates nothing beyond the two
+ * endpoints a login needs; the control plane keeps its own pinned
+ * validation and copy on top. Pure over an injected fetch, one deadline per
+ * request.
+ *
+ * Proven by __tests__/metadata.test.ts.
+ */
+import type { OutboundFetch } from "../egress/fetch.js";
+/** RFC 8414 metadata in the fields Sign in reads; snake_case on the wire, camelCase here. */
+export interface AuthorizationServerMetadata {
+    /** The document these facts were read from. */
+    readonly metadataUrl: string;
+    readonly issuer: string;
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    /** Empty when the login server does not register clients dynamically (RFC 7591). */
+    readonly registrationEndpoint: string;
+    readonly scopesSupported: readonly string[];
+    readonly codeChallengeMethodsSupported: readonly string[];
+}
+/** One GET the walk made and what came back. */
+export interface MetadataAttempt {
+    readonly url: string;
+    readonly status?: number;
+    readonly error?: string;
+    /** Set when the document parsed but lacked the endpoint a login needs, so a caller can say which. */
+    readonly missing?: "authorization_endpoint" | "token_endpoint";
+}
+export type MetadataRead = {
+    readonly kind: "found";
+    readonly metadata: AuthorizationServerMetadata;
+    readonly attempts: readonly MetadataAttempt[];
+} | {
+    readonly kind: "not-found";
+    readonly attempts: readonly MetadataAttempt[];
+};
+export interface MetadataReadDeps {
+    readonly fetchImpl: OutboundFetch;
+    /** Per request. */
+    readonly timeoutMs: number;
+}
+/** The RFC 9728 documents describing a resource, most specific first. */
+export declare function protectedResourceMetadataUrls(resource: URL): readonly string[];
+/** The documents describing an issuer, RFC 8414 (path inserted, then origin) then OpenID (path, then origin). */
+export declare function authorizationServerMetadataUrls(issuer: URL): readonly string[];
+/**
+ * The issuers protecting a resource, from its RFC 9728 document (the
+ * challenge's pointer when the caller has one, else the well-known
+ * documents at the resource). Empty when no document names any; the caller
+ * decides what that means (the control plane falls back to the origin).
+ */
+export declare function resolveAuthorizationServers(resourceUrl: string, pointer: string | undefined, deps: MetadataReadDeps): Promise<{
+    readonly issuers: readonly string[];
+    readonly attempts: readonly MetadataAttempt[];
+}>;
+/** The first document for `issuer` that names an authorization and a token endpoint. */
+export declare function readAuthorizationServerMetadata(issuer: string, deps: MetadataReadDeps): Promise<MetadataRead>;
+//# sourceMappingURL=metadata.d.ts.map

package/mcp-oauth/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/mcp-oauth/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,6FAA6F;AAC7F,MAAM,WAAW,2BAA2B;IAC1C,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,6BAA6B,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3D;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,gBAAgB,CAAC;CAChE;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,GACzH;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,CAAC;AAElF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,mBAAmB;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,yEAAyE;AACzE,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,GAAG,GAAG,SAAS,MAAM,EAAE,CAI9E;AAED,iHAAiH;AACjH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS,MAAM,EAAE,CAS9E;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,CAAC,CAUjG;AAED,wFAAwF;AACxF,wBAAsB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAiCnH"}

package/mcp-oauth/metadata.js

@@ -0,0 +1,113 @@
+/** The RFC 9728 documents describing a resource, most specific first. */
+export function protectedResourceMetadataUrls(resource) {
+    const bare = `${resource.origin}/.well-known/oauth-protected-resource`;
+    const path = resource.pathname.replace(/\/+$/, "");
+    return path === "" ? [bare] : [`${bare}${path}`, bare];
+}
+/** The documents describing an issuer, RFC 8414 (path inserted, then origin) then OpenID (path, then origin). */
+export function authorizationServerMetadataUrls(issuer) {
+    const path = issuer.pathname.replace(/\/+$/, "");
+    const urls = [
+        ...(path === "" ? [] : [`${issuer.origin}/.well-known/oauth-authorization-server${path}`]),
+        `${issuer.origin}/.well-known/oauth-authorization-server`,
+        ...(path === "" ? [] : [`${issuer.origin}${path}/.well-known/openid-configuration`]),
+        `${issuer.origin}/.well-known/openid-configuration`,
+    ];
+    return [...new Set(urls)];
+}
+/**
+ * The issuers protecting a resource, from its RFC 9728 document (the
+ * challenge's pointer when the caller has one, else the well-known
+ * documents at the resource). Empty when no document names any; the caller
+ * decides what that means (the control plane falls back to the origin).
+ */
+export async function resolveAuthorizationServers(resourceUrl, pointer, deps) {
+    const attempts = [];
+    const candidates = pointer !== undefined ? [pointer] : protectedResourceMetadataUrls(new URL(resourceUrl));
+    for (const candidate of candidates) {
+        const read = await readJson(candidate, deps, attempts);
+        if (read === undefined)
+            continue;
+        const issuers = readStringArray(read, "authorization_servers");
+        if (issuers.length > 0)
+            return { issuers, attempts };
+    }
+    return { issuers: [], attempts };
+}
+/** The first document for `issuer` that names an authorization and a token endpoint. */
+export async function readAuthorizationServerMetadata(issuer, deps) {
+    const attempts = [];
+    let parsed;
+    try {
+        parsed = new URL(issuer);
+    }
+    catch {
+        return { kind: "not-found", attempts };
+    }
+    for (const metadataUrl of authorizationServerMetadataUrls(parsed)) {
+        const document = await readJson(metadataUrl, deps, attempts);
+        if (document === undefined)
+            continue;
+        const authorizationEndpoint = readString(document, "authorization_endpoint");
+        const tokenEndpoint = readString(document, "token_endpoint");
+        if (authorizationEndpoint === "" || tokenEndpoint === "") {
+            const last = attempts.pop();
+            if (last !== undefined)
+                attempts.push({ ...last, missing: authorizationEndpoint === "" ? "authorization_endpoint" : "token_endpoint" });
+            continue;
+        }
+        return {
+            kind: "found",
+            attempts,
+            metadata: {
+                metadataUrl,
+                issuer: readString(document, "issuer"),
+                authorizationEndpoint,
+                tokenEndpoint,
+                registrationEndpoint: readString(document, "registration_endpoint"),
+                scopesSupported: readStringArray(document, "scopes_supported"),
+                codeChallengeMethodsSupported: readStringArray(document, "code_challenge_methods_supported"),
+            },
+        };
+    }
+    return { kind: "not-found", attempts };
+}
+/** A GET expecting a JSON object; anything else is recorded and read as absent. */
+async function readJson(url, deps, attempts) {
+    let response;
+    try {
+        response = await deps.fetchImpl(url, {
+            method: "GET",
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(deps.timeoutMs),
+        });
+    }
+    catch (error) {
+        attempts.push({ url, error: error instanceof Error ? error.message : String(error) });
+        return undefined;
+    }
+    attempts.push({ url, status: response.status });
+    if (response.status !== 200) {
+        await response.body?.cancel().catch(() => undefined);
+        return undefined;
+    }
+    try {
+        const parsed = await response.json();
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : "";
+}
+function readStringArray(record, key) {
+    const list = record[key];
+    return Array.isArray(list) ? list.filter((item) => typeof item === "string") : [];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=metadata.js.map

package/mcp-oauth/metadata.js.map

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

package/mcp-oauth/probe.d.ts

@@ -0,0 +1,68 @@
+/**
+ * What an MCP endpoint says to a caller without a credential, read from one
+ * `initialize` and its status line and headers alone.
+ *
+ * Two processes ask this question and both need the same answer: the
+ * control plane at save time (does this URL-only server need Sign in, so
+ * the button appears before anyone runs it) and the runner at the first
+ * failed tool call (was that failure an OAuth requirement, so the user is
+ * told to sign in instead of to check a token). The catalogue audit asks
+ * it too, and then keeps asking (`tools/list`, the SSE arm, the metadata
+ * walk) because it measures; those extra moves are the audit's, built on
+ * `request.ts` and `metadata.ts`, not this function's.
+ *
+ * The outcome vocabulary is closed and says only what the wire said. A 2xx
+ * is `accepted`: the handshake was not refused for want of a credential,
+ * and whether the body carried a result or a JSON-RPC error is not this
+ * reader's question (both mean "not OAuth" to its callers). The body is
+ * cancelled unread, so a server that streams its answer over an event
+ * stream that never closes cannot hold the probe open. Only a 401 enters
+ * the OAuth rule (`challenge.ts`).
+ *
+ * Never throws: a network failure, an abort or a deadline is `unreachable`,
+ * because a caller that saves a resource or classifies a failure must not
+ * fail on a probe. No redirect is followed by the probe itself; the fetch
+ * it is handed decides that (the control plane's guarded fetch follows and
+ * re-judges each hop, the runner's `fetch` follows). The caller sets the
+ * deadline: 3 s on a user's save, 10 s on the runner's failure path.
+ *
+ * Proven by __tests__/probe.test.ts.
+ */
+import type { OutboundFetch } from "../egress/fetch.js";
+export type EndpointAuthOutcome = 
+/** A 401 the OAuth rule accepts: the endpoint wants an OAuth token and says where its login server is described. */
+{
+    readonly kind: "oauth";
+    readonly challenge: string;
+    readonly resourceMetadataUrl: string | undefined;
+}
+/** A 401 the rule refuses: a static-token API's bad-key answer, or a proxy asking for its own credential. */
+ | {
+    readonly kind: "challenge-not-oauth";
+    readonly challenge: string;
+}
+/** A 2xx: the handshake was not refused for want of a credential. */
+ | {
+    readonly kind: "accepted";
+    readonly status: number;
+}
+/** Any other HTTP status. */
+ | {
+    readonly kind: "http-other";
+    readonly status: number;
+}
+/** No HTTP answer: a network failure, a refusal by the fetch, or the deadline. */
+ | {
+    readonly kind: "unreachable";
+    readonly error: string;
+};
+export interface EndpointProbeDeps {
+    readonly fetchImpl: OutboundFetch;
+    /** The whole probe's deadline, connection and headers included. */
+    readonly timeoutMs: number;
+    /** Who is asking, for the handshake's `clientInfo`. */
+    readonly clientName: string;
+}
+/** Ask an endpoint once, with the caller's headers, and say what it answered. */
+export declare function probeEndpointAuth(url: string, headers: Readonly<Record<string, string>> | undefined, deps: EndpointProbeDeps): Promise<EndpointAuthOutcome>;
+//# sourceMappingURL=probe.d.ts.map

package/mcp-oauth/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../src/mcp-oauth/probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,MAAM,MAAM,mBAAmB;AAC7B,oHAAoH;AAClH;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE;AAC1G,6GAA6G;GAC3G;IAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AACtE,qEAAqE;GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACxD,6BAA6B;GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC1D,kFAAkF;GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACrD,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CA2B9B"}

package/mcp-oauth/probe.js

@@ -0,0 +1,35 @@
+import { isOAuthChallenge, parseResourceMetadataUrl } from "./challenge.js";
+import { initializeRequest } from "./request.js";
+/** Ask an endpoint once, with the caller's headers, and say what it answered. */
+export async function probeEndpointAuth(url, headers, deps) {
+    const request = initializeRequest(deps.clientName, headers);
+    let response;
+    try {
+        response = await deps.fetchImpl(url, {
+            method: request.method,
+            headers: { ...request.headers },
+            body: request.body,
+            signal: AbortSignal.timeout(deps.timeoutMs),
+        });
+    }
+    catch (error) {
+        return { kind: "unreachable", error: describeError(error) };
+    }
+    // Only the status line and the headers classify; the body is released so
+    // an endless event stream cannot hold the probe open.
+    await response.body?.cancel().catch(() => undefined);
+    if (response.status === 401) {
+        const challenge = response.headers.get("www-authenticate") ?? "";
+        if (!isOAuthChallenge(challenge))
+            return { kind: "challenge-not-oauth", challenge };
+        return { kind: "oauth", challenge, resourceMetadataUrl: parseResourceMetadataUrl(challenge) };
+    }
+    if (response.status >= 200 && response.status < 300) {
+        return { kind: "accepted", status: response.status };
+    }
+    return { kind: "http-other", status: response.status };
+}
+function describeError(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+//# sourceMappingURL=probe.js.map

package/mcp-oauth/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../src/mcp-oauth/probe.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAsBjD,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAW,EACX,OAAqD,EACrD,IAAuB;IAEvB,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5D,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;YACnC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE;YAC/B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IAC9D,CAAC;IAED,yEAAyE;IACzE,sDAAsD;IACtD,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAErD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACjE,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,qBAAqB,EAAE,SAAS,EAAE,CAAC;QACpF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,wBAAwB,CAAC,SAAS,CAAC,EAAE,CAAC;IAChG,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;AACzD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpF,CAAC"}