@opengeni/network 0.2.3 → 0.3.0-canary.0

package/README.md

@@ -41,3 +41,29 @@ The package also exports `readJsonBase64Field` for provider APIs that return
 large binary artifacts inside JSON. It validates declared and streamed limits,
 decodes canonical base64 incrementally, and avoids retaining the JSON envelope
 or encoded string. Callers remain responsible for validating the decoded media.
+
+## MCP OAuth discovery
+
+`resolveMcpOAuthDiscovery` provides the shared MCP OAuth discovery state machine
+used by runtime connections and catalog diagnostics. It prefers RFC 9728
+Protected Resource Metadata and permits the MCP 2025-03-26 compatibility path
+only after every PRM candidate is explicitly absent with HTTP 404 or 410. The
+legacy path requires a Bearer/OAuth challenge, RFC 8414 metadata on the MCP
+origin, an exact issuer match, same-origin resource binding, and PKCE S256.
+
+The resolver is transport-independent. Its `fetchMetadata` callback must
+validate each candidate before I/O, bound response size and duration, disable
+automatic redirects, and independently validate and DNS-pin every redirect
+hop. It must return `status: "absent"` only for HTTP 404 or 410 and throw for
+network, redirect, destination-policy, HTTP, body, and JSON failures; otherwise
+an unsafe or unreachable PRM endpoint could be mistaken for legacy absence.
+`validateEndpoint` and `canonicalizeResource` provide the caller's deployment
+policy and canonical identifier rules.
+
+Successful results include the discovery mode, normalized metadata, structured
+classification, and a stable SHA-256 provenance digest. Fail-closed errors carry
+classifications for broken discovery, unverified legacy defaults, or a legacy
+cross-origin configuration that requires an explicit reviewed profile. These
+classifications are diagnostics; callers still decide whether a provider
+profile is supported and must perform fresh runtime discovery before granting
+credentials.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./json-base64.js";
+export * from "./mcp-oauth-discovery.js";
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export type DnsAddress = {
     address: string;

package/dist/index.js

@@ -259,6 +259,396 @@ function isJsonWhitespace(byte) {
   return byte === 32 || byte === 9 || byte === 10 || byte === 13;
 }
 
+// src/mcp-oauth-discovery.ts
+import { createHash } from "crypto";
+var McpOAuthDiscoveryError = class extends Error {
+  constructor(stage, classification, message, cause) {
+    super(message);
+    this.stage = stage;
+    this.classification = classification;
+    this.cause = cause;
+    this.name = "McpOAuthDiscoveryError";
+  }
+};
+async function resolveMcpOAuthDiscovery(input) {
+  const prmCandidates = protectedResourceMetadataCandidates(
+    input.resourceUrl,
+    input.challenge.resourceMetadata
+  );
+  let prmDocument = null;
+  for (const candidate of prmCandidates) {
+    const fetched = await input.fetchMetadata({ kind: "protected_resource", url: candidate });
+    if (fetched.status === "absent") continue;
+    prmDocument = fetched;
+    break;
+  }
+  if (prmDocument) {
+    const prm = parseProtectedResourceMetadata(prmDocument, input);
+    const authorizationServer = prm.authorizationServers[0];
+    const as2 = await discoverAuthorizationServerMetadata(authorizationServer, "modern", input);
+    return discoveryResult({
+      mode: "rfc9728_protected_resource",
+      classification: "oauth_rfc9728",
+      challenge: input.challenge,
+      resource: prm.resource ?? input.canonicalizeResource(input.resourceUrl),
+      prm,
+      as: as2
+    });
+  }
+  if (input.challenge.resourceMetadata !== void 0) {
+    throw new McpOAuthDiscoveryError(
+      "protected_resource_metadata",
+      "oauth_discovery_broken",
+      "MCP advertised protected resource metadata, but no metadata document was found"
+    );
+  }
+  if (!input.challenge.scheme) {
+    throw new McpOAuthDiscoveryError(
+      "protected_resource_metadata",
+      "oauth_discovery_broken",
+      "MCP protected resource metadata was absent and the server returned no Bearer/OAuth challenge"
+    );
+  }
+  const resource = input.canonicalizeResource(input.resourceUrl);
+  const resourceOrigin = new URL(resource).origin;
+  const as = await discoverAuthorizationServerMetadata(resourceOrigin, "legacy", input);
+  if (new URL(as.issuer).origin !== resourceOrigin) {
+    throw new McpOAuthDiscoveryError(
+      "authorization_server_metadata",
+      "oauth_requires_profile",
+      "legacy MCP OAuth discovery requires the authorization server issuer to share the MCP server origin"
+    );
+  }
+  const syntheticPrm = {
+    resource,
+    authorizationServers: [as.issuer],
+    scopesSupported: [...input.challenge.scope],
+    raw: {
+      resource,
+      authorization_servers: [as.issuer],
+      scopes_supported: [...input.challenge.scope]
+    },
+    metadataUrl: ""
+  };
+  return discoveryResult({
+    mode: "legacy_2025_03_26_metadata",
+    classification: "oauth_legacy_same_origin_metadata",
+    challenge: input.challenge,
+    resource,
+    prm: syntheticPrm,
+    as
+  });
+}
+function parseMcpOAuthChallenge(header) {
+  if (!header) return { scheme: null, scope: [] };
+  const challenges = parseAuthenticateChallenges(header);
+  if (!challenges) return { scheme: null, scope: [] };
+  const oauthChallenges = challenges.filter((candidate) => {
+    const scheme = candidate.scheme.toLowerCase();
+    return scheme === "bearer" || scheme === "oauth";
+  }).map(parseOAuthChallenge);
+  return oauthChallenges.find((challenge) => challenge.resourceMetadata !== void 0) ?? oauthChallenges[0] ?? { scheme: null, scope: [] };
+}
+function parseOAuthChallenge(challenge) {
+  const scheme = challenge.scheme.toLowerCase();
+  const resourceMetadataPresent = challenge.parameterParts.some(
+    (part) => /^resource_metadata\s*=/i.test(part.trim())
+  );
+  const paramsText = challenge.parameterParts.join(",");
+  const params = {};
+  const re = /([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*("(?:[^"\\]|\\.)*"|[^,\s]+)/g;
+  let match;
+  while ((match = re.exec(paramsText)) !== null) {
+    const raw = match[2];
+    params[match[1].toLowerCase()] = raw.startsWith('"') ? raw.slice(1, -1).replace(/\\"/g, '"') : raw;
+  }
+  return {
+    scheme,
+    scope: params.scope ? params.scope.split(/\s+/).filter(Boolean) : [],
+    ...resourceMetadataPresent ? { resourceMetadata: params.resource_metadata ?? "" } : {},
+    ...params.error ? { error: params.error } : {}
+  };
+}
+var MAX_EMPTY_AUTHENTICATE_LIST_ELEMENTS = 8;
+function parseAuthenticateChallenges(header) {
+  const segments = splitAuthenticateHeader(header);
+  if (!segments) return null;
+  const challenges = [];
+  let emptyElements = 0;
+  for (const segment of segments) {
+    const trimmed = segment.trim();
+    if (!trimmed) {
+      emptyElements += 1;
+      if (emptyElements > MAX_EMPTY_AUTHENTICATE_LIST_ELEMENTS) return null;
+      continue;
+    }
+    const token = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+/.exec(trimmed)?.[0];
+    if (!token) return null;
+    let cursor = token.length;
+    while (/\s/.test(trimmed[cursor] ?? "")) cursor += 1;
+    if (trimmed[cursor] === "=") {
+      const current = challenges.at(-1);
+      if (!current) return null;
+      current.parameterParts.push(trimmed);
+      continue;
+    }
+    const remainder = trimmed.slice(token.length);
+    if (remainder && !/^\s/.test(remainder)) return null;
+    challenges.push({
+      scheme: token,
+      parameterParts: remainder.trim() ? [remainder.trim()] : []
+    });
+  }
+  return challenges;
+}
+function splitAuthenticateHeader(header) {
+  const segments = [];
+  let segmentStart = 0;
+  let quoted = false;
+  let escaped = false;
+  for (let index = 0; index < header.length; index += 1) {
+    const character = header[index];
+    if (quoted) {
+      if (escaped) {
+        escaped = false;
+      } else if (character === "\\") {
+        escaped = true;
+      } else if (character === '"') {
+        quoted = false;
+      }
+      continue;
+    }
+    if (character === '"') {
+      quoted = true;
+      continue;
+    }
+    if (character === ",") {
+      segments.push(header.slice(segmentStart, index));
+      segmentStart = index + 1;
+    }
+  }
+  if (quoted) return null;
+  segments.push(header.slice(segmentStart));
+  return segments;
+}
+function protectedResourceMetadataCandidates(resourceUrl, advertisedUrl) {
+  return uniqueStrings([
+    ...advertisedUrl !== void 0 ? [advertisedUrl] : [],
+    ...oauthWellKnownCandidates(resourceUrl, "oauth-protected-resource")
+  ]);
+}
+function authorizationServerMetadataCandidates(authorizationServer) {
+  return uniqueStrings([
+    ...oauthWellKnownCandidates(authorizationServer, "oauth-authorization-server"),
+    ...oauthWellKnownCandidates(authorizationServer, "openid-configuration"),
+    authorizationServer
+  ]);
+}
+function legacyAuthorizationServerMetadataCandidates(resourceUrl) {
+  const origin = new URL(resourceUrl).origin;
+  return [`${origin}/.well-known/oauth-authorization-server`];
+}
+function oauthWellKnownCandidates(rawUrl, name) {
+  const url = new URL(rawUrl);
+  const path = url.pathname.replace(/^\/+|\/+$/g, "");
+  return uniqueStrings([
+    `${url.origin}/.well-known/${name}${path ? `/${path}` : ""}`,
+    `${url.origin}${path ? `/${path}` : ""}/.well-known/${name}`,
+    `${url.origin}/.well-known/${name}`
+  ]);
+}
+function parseProtectedResourceMetadata(fetched, input) {
+  const authorizationServers = stringArray(fetched.document.authorization_servers).map(
+    (value) => validateDiscoveryEndpoint(
+      input,
+      value,
+      "OAuth authorization server",
+      "protected_resource_metadata"
+    )
+  );
+  if (authorizationServers.length === 0) {
+    throw new McpOAuthDiscoveryError(
+      "protected_resource_metadata",
+      "oauth_discovery_broken",
+      "MCP protected resource metadata did not advertise an authorization server"
+    );
+  }
+  const resourceValue = stringValue(fetched.document.resource);
+  return {
+    authorizationServers,
+    scopesSupported: stringArray(fetched.document.scopes_supported),
+    raw: fetched.document,
+    metadataUrl: fetched.url,
+    ...resourceValue ? { resource: input.canonicalizeResource(resourceValue) } : {}
+  };
+}
+async function discoverAuthorizationServerMetadata(authorizationServer, profile, input) {
+  const safeAuthorizationServer = validateDiscoveryEndpoint(
+    input,
+    authorizationServer,
+    "OAuth authorization server",
+    "authorization_server_metadata"
+  ).replace(/\/+$/, "");
+  const candidates = profile === "legacy" ? legacyAuthorizationServerMetadataCandidates(safeAuthorizationServer) : authorizationServerMetadataCandidates(safeAuthorizationServer);
+  let fetched = null;
+  for (const candidate of candidates) {
+    const result = await input.fetchMetadata({ kind: "authorization_server", url: candidate });
+    if (result.status === "absent") continue;
+    fetched = result;
+    break;
+  }
+  if (!fetched) {
+    throw new McpOAuthDiscoveryError(
+      "authorization_server_metadata",
+      profile === "legacy" ? "oauth_legacy_default_endpoints_unverified" : "oauth_discovery_broken",
+      profile === "legacy" ? "legacy MCP OAuth metadata was absent; default authorization endpoints require explicit verification" : "could not discover OAuth authorization server metadata"
+    );
+  }
+  const authorizationEndpoint = requiredString(
+    fetched.document.authorization_endpoint,
+    "authorization_endpoint",
+    "authorization_server_metadata"
+  );
+  const tokenEndpoint = requiredString(
+    fetched.document.token_endpoint,
+    "token_endpoint",
+    "authorization_server_metadata"
+  );
+  const issuerValue = stringValue(fetched.document.issuer);
+  if (profile === "legacy" && !issuerValue) {
+    throw new McpOAuthDiscoveryError(
+      "authorization_server_metadata",
+      "oauth_discovery_broken",
+      "legacy MCP OAuth metadata did not include issuer"
+    );
+  }
+  const issuer = validateDiscoveryEndpoint(
+    input,
+    issuerValue ?? safeAuthorizationServer,
+    "OAuth issuer",
+    "authorization_server_metadata"
+  );
+  if (profile === "legacy" && normalizedIssuerIdentifier(issuer) !== normalizedIssuerIdentifier(safeAuthorizationServer)) {
+    const crossOrigin = new URL(issuer).origin !== new URL(safeAuthorizationServer).origin;
+    throw new McpOAuthDiscoveryError(
+      "authorization_server_metadata",
+      crossOrigin ? "oauth_requires_profile" : "oauth_discovery_broken",
+      "OAuth authorization server metadata issuer did not match the selected authorization server"
+    );
+  }
+  const registrationEndpoint = stringValue(fetched.document.registration_endpoint);
+  const parsed = {
+    issuer,
+    authorizationServer: safeAuthorizationServer,
+    authorizationEndpoint: validateDiscoveryEndpoint(
+      input,
+      authorizationEndpoint,
+      "OAuth authorization endpoint",
+      "authorization_server_metadata"
+    ),
+    tokenEndpoint: validateDiscoveryEndpoint(
+      input,
+      tokenEndpoint,
+      "OAuth token endpoint",
+      "authorization_server_metadata"
+    ),
+    clientIdMetadataDocumentSupported: fetched.document.client_id_metadata_document_supported === true,
+    tokenEndpointAuthMethodsSupported: stringArray(
+      fetched.document.token_endpoint_auth_methods_supported
+    ),
+    codeChallengeMethodsSupported: stringArray(fetched.document.code_challenge_methods_supported),
+    raw: fetched.document,
+    metadataUrl: fetched.url,
+    ...registrationEndpoint ? {
+      registrationEndpoint: validateDiscoveryEndpoint(
+        input,
+        registrationEndpoint,
+        "OAuth registration endpoint",
+        "authorization_server_metadata"
+      )
+    } : {}
+  };
+  if (!parsed.codeChallengeMethodsSupported.includes("S256")) {
+    throw new McpOAuthDiscoveryError(
+      "authorization_server_metadata",
+      "oauth_discovery_broken",
+      "authorization server does not support required PKCE S256"
+    );
+  }
+  return parsed;
+}
+function discoveryResult(input) {
+  const protectedResourceMetadataUrl = input.prm.metadataUrl || null;
+  return {
+    mode: input.mode,
+    classification: input.classification,
+    challenge: input.challenge,
+    resource: input.resource,
+    protectedResourceMetadata: input.prm,
+    authorizationServerMetadata: input.as,
+    provenance: {
+      protectedResourceMetadataUrl,
+      authorizationServerMetadataUrl: input.as.metadataUrl,
+      metadataSha256: createHash("sha256").update(
+        stableJson({
+          mode: input.mode,
+          resource: input.resource,
+          challenge: input.challenge,
+          protectedResourceMetadata: {
+            url: protectedResourceMetadataUrl,
+            document: input.prm.raw
+          },
+          authorizationServerMetadata: {
+            url: input.as.metadataUrl,
+            document: input.as.raw
+          }
+        })
+      ).digest("hex")
+    }
+  };
+}
+function validateDiscoveryEndpoint(input, rawUrl, label, stage) {
+  try {
+    return input.validateEndpoint(rawUrl, label);
+  } catch (error) {
+    throw new McpOAuthDiscoveryError(
+      stage,
+      "oauth_discovery_broken",
+      error instanceof Error ? error.message : `${label} was invalid`,
+      error
+    );
+  }
+}
+function normalizedIssuerIdentifier(value) {
+  return value.replace(/\/+$/, "");
+}
+function stableJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+}
+function uniqueStrings(values) {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+function stringArray(value) {
+  return Array.isArray(value) ? uniqueStrings(value.filter((entry) => typeof entry === "string")) : [];
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function requiredString(value, field, stage) {
+  const parsed = stringValue(value);
+  if (!parsed) {
+    throw new McpOAuthDiscoveryError(
+      stage,
+      "oauth_discovery_broken",
+      `OAuth metadata did not include ${field}`
+    );
+  }
+  return parsed;
+}
+
 // src/index.ts
 var DISPATCHER_CLOSE_TIMEOUT_MS = 100;
 var OAUTH_MAX_RESPONSE_BYTES = 1024 * 1024;
@@ -876,18 +1266,24 @@ function ipv6Constant(address) {
 export {
   DestinationPolicyError,
   JsonBase64ResponseError,
+  McpOAuthDiscoveryError,
   OAUTH_MAX_RESPONSE_BYTES,
   RequestDeadlineError,
   ResponseBodyLimitError,
+  authorizationServerMetadataCandidates,
   isInvalidAddress,
   isLocalTestEnvironment,
   isNonPublicAddress,
   isPrivateAddress,
+  legacyAuthorizationServerMetadataCandidates,
+  parseMcpOAuthChallenge,
   pinnedFetch,
+  protectedResourceMetadataCandidates,
   readJsonBase64Field,
   readResponseBodyBounded,
   readResponseJsonBounded,
   readResponseTextBounded,
+  resolveMcpOAuthDiscovery,
   resolvePinnedDestination,
   undiciFetch,
   validateHttpUrl