mcp-from-openapi 2.3.0 → 2.5.0

package/ssrf.d.ts

@@ -0,0 +1,108 @@
+/**
+ * SSRF protection for spec loading and external `$ref` resolution.
+ *
+ * The generator fetches two kinds of attacker-influenceable URLs:
+ *   1. the OpenAPI spec itself (`fromURL`), and
+ *   2. external `$ref` targets during dereferencing.
+ *
+ * A hostname-string denylist (the pre-2.5 approach) is bypassable, as reported
+ * in GHSA-65h7-9wrw-629c:
+ *   - DNS names that resolve to internal IPs, e.g. `http://127.0.0.1.nip.io/`
+ *     — the literal-string `127.0.0.1` patterns never match, yet the name
+ *     resolves to loopback;
+ *   - IPv4-mapped IPv6 forms (handled since 2.4 via {@link decodeIpv4MappedIpv6});
+ *   - redirects from an allowed host to an internal one.
+ *
+ * This module validates the **resolved IP**, not just the hostname string:
+ *   - parses/normalizes IPv4 (incl. numeric/hex/octal forms canonicalized by
+ *     `new URL()`) and IPv4-mapped IPv6 before range checks;
+ *   - blocks loopback / private (RFC 1918) / CGNAT (RFC 6598) / link-local /
+ *     multicast / unspecified / reserved ranges and cloud-metadata endpoints;
+ *   - resolves the hostname (Node, via `node:dns`) and rejects if **any**
+ *     resolved address is internal — closing the DNS-name-to-internal bypass;
+ *   - re-validates every redirect hop ({@link safeFetch}) instead of letting the
+ *     HTTP client follow 3xx blindly.
+ *
+ * Node-aware: DNS resolution lazily imports `node:dns` and is a no-op on
+ * runtimes without it (Web/edge), where the literal-address checks still apply.
+ *
+ * Residual: this does DNS resolve-then-fetch without connection-level IP
+ * pinning, so a sub-second DNS-rebinding race (flip the record between the
+ * validating resolve and the client's connect-time resolve) is not fully
+ * eliminated. For fully-untrusted inputs, combine with an `allowedHosts`
+ * allow-list and network egress controls.
+ */
+import type { RefResolutionOptions } from './types';
+/** The subset of {@link RefResolutionOptions} relevant to address blocking. */
+export interface ResolvedSsrfOptions {
+    allowedHosts: string[];
+    blockedHosts: string[];
+    allowInternalIPs: boolean;
+}
+/** Resolved DNS address shape (subset of Node's `dns.LookupAddress`). */
+export interface ResolvedAddress {
+    address: string;
+    family: number;
+}
+/** Hostname → resolved addresses. Injectable for testing. */
+export type SsrfHostLookup = (hostname: string) => Promise<ResolvedAddress[]>;
+/**
+ * Non-IP hostnames that map to internal targets, so the IP-range checks alone
+ * would miss them when DNS resolution is unavailable. DNS resolution (when
+ * available) also catches these; this set is defense-in-depth.
+ */
+export declare const BLOCKED_HOSTNAMES: ReadonlySet<string>;
+/** Normalize a (possibly undefined) {@link RefResolutionOptions} to the SSRF subset. */
+export declare function normalizeSsrfOptions(refResolution?: RefResolutionOptions): ResolvedSsrfOptions;
+/**
+ * Decode an IPv4-mapped IPv6 host (`::ffff:169.254.169.254` or its hex form
+ * `::ffff:a9fe:a9fe`, optionally bracketed) to its embedded dotted-quad IPv4, or
+ * `null` if the host isn't IPv4-mapped. `new URL().hostname` normalizes
+ * `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, which the plain
+ * dotted-quad range checks would otherwise miss.
+ */
+export declare function decodeIpv4MappedIpv6(hostname: string): string | null;
+/**
+ * Predicate: is `host` (an IP literal — dotted-quad IPv4, bracketed/zoned IPv6,
+ * or IPv4-mapped IPv6) in a blocked, non-public range? Returns `false` for
+ * non-IP-literal hostnames (use DNS resolution for those).
+ */
+export declare function isBlockedAddress(host: string): boolean;
+/**
+ * Synchronous host check used by the `$RefParser` `canRead` filter (which cannot
+ * be async). Blocks known internal hostnames, explicit `blockedHosts`, and
+ * literal internal IPs (incl. IPv4-mapped IPv6). DNS names that *resolve* to
+ * internal addresses are caught later, asynchronously, in {@link safeFetch}.
+ */
+export declare function isBlockedHostname(hostname: string, ssrf: ResolvedSsrfOptions): boolean;
+/** Default DNS resolver: lazily loads `node:dns`; rejects on non-Node runtimes. */
+export declare const defaultLookup: SsrfHostLookup;
+/**
+ * Validate that `url` is safe to fetch (spec URL or `$ref` target), throwing
+ * {@link SsrfError} if not. Enforces http/https, the `allowedHosts` allow-list,
+ * the internal-address denylist, and — for DNS names — resolves and rejects if
+ * any resolved address is internal.
+ */
+export declare function assertUrlSafe(url: string, ssrf: ResolvedSsrfOptions, lookup?: SsrfHostLookup): Promise<void>;
+/** Options for {@link safeFetch}. */
+export interface SafeFetchOptions {
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    /** Follow 3xx redirects (re-validating each hop). @default true */
+    followRedirects?: boolean;
+    /** Max redirect hops before failing. @default 5 */
+    maxRedirects?: number;
+    ssrf: ResolvedSsrfOptions;
+    /** Injectable DNS resolver (tests). */
+    lookup?: SsrfHostLookup;
+    /** Injectable fetch implementation (tests / custom runtimes). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * SSRF-safe `fetch`: validates the initial URL and **every redirect hop** with
+ * {@link assertUrlSafe} before issuing the request, using manual redirect
+ * handling so a 3xx to an internal target can't be followed without
+ * re-validation. Returns the final {@link Response} (the caller checks
+ * `response.ok` / reads the body).
+ */
+export declare function safeFetch(url: string, opts: SafeFetchOptions): Promise<Response>;

package/types.d.ts

@@ -327,9 +327,15 @@ export interface ServerInfo {
     variables?: Record<string, ServerVariableObject>;
 }
 /**
- * Controls how external $ref pointers are resolved during dereferencing.
- * By default, only http/https protocols are allowed and internal/private
- * IP addresses are blocked to prevent SSRF attacks.
+ * Controls how external `$ref` pointers are resolved during dereferencing, and
+ * the host policy applied to the initial spec-URL fetch in `fromURL`.
+ *
+ * By default only http/https protocols are allowed and internal/private targets
+ * are blocked to prevent SSRF. As of 2.5.0 the guard validates the **resolved
+ * IP** (it resolves DNS and rejects hostnames that map to internal addresses —
+ * e.g. `127.0.0.1.nip.io`), normalizes IPv4-mapped IPv6, and re-validates every
+ * HTTP redirect hop. `allowedHosts` / `blockedHosts` / `allowInternalIPs` apply
+ * to both the spec URL and external `$ref`s.
  */
 export interface RefResolutionOptions {
     /**
@@ -386,13 +392,17 @@ export interface LoadOptions {
      */
     validate?: boolean;
     /**
-     * Whether to follow HTTP redirects
+     * Whether to follow HTTP redirects when fetching the spec URL. Each redirect
+     * hop is re-validated against the SSRF guard before being followed (a 3xx to
+     * an internal target is refused), so following is safe by default.
      * @default true
      */
     followRedirects?: boolean;
     /**
-     * Controls external $ref resolution security.
-     * By default, file:// is blocked and internal IPs are blocked.
+     * Controls spec-loading security: external `$ref` resolution AND the host
+     * policy for the initial spec-URL fetch. By default `file://` is blocked,
+     * internal/private targets are blocked, and hostnames are DNS-resolved and
+     * re-checked against the internal-address ranges.
      * @see RefResolutionOptions
      */
     refResolution?: RefResolutionOptions;