@spfn/core 0.2.0-beta.9 → 0.3.0-beta.1

package/dist/security/index.d.ts

@@ -0,0 +1,83 @@
+import { fetch, Agent } from 'undici';
+
+/**
+ * @spfn/core - SSRF-safe outbound fetch
+ *
+ * A drop-in `fetch` for calling URLs that may be influenced by user input
+ * (webhooks, image fetchers, callback URLs). It blocks requests to private and
+ * reserved IP ranges — including the cloud metadata address (169.254.169.254) —
+ * and defeats DNS rebinding by resolving the hostname, validating every returned
+ * address, and pinning the connection to a validated IP via a custom undici
+ * `lookup`. Redirects go through the same dispatcher, so each hop is re-validated.
+ *
+ * A plain string allowlist cannot stop SSRF on its own: an attacker-controlled
+ * hostname can resolve to a private IP (DNS rebinding). The pinning is the point.
+ */
+
+/** Thrown when a request target is blocked by the SSRF policy. */
+declare class SsrfBlockedError extends Error {
+    constructor(message: string);
+}
+interface SafeFetchPolicy {
+    /** URL schemes allowed. @default ['http:', 'https:'] */
+    allowedProtocols?: string[];
+    /**
+     * Reject targets that resolve to a private or reserved IP range (loopback,
+     * link-local/metadata, RFC1918, ULA, multicast, …). @default true
+     */
+    blockPrivateIps?: boolean;
+    /**
+     * Exact hostname allowlist (case-insensitive). When set, only these hosts
+     * are reachable — the strongest control for a known set of upstreams.
+     * Enforced on every redirect hop, not just the first URL.
+     */
+    allowHosts?: string[];
+    /** Max redirects to follow, each re-validated. @default 5 */
+    maxRedirects?: number;
+}
+/**
+ * Whether an IP literal falls in a private or reserved range. A non-IP input is
+ * treated as unsafe (`true`) — callers pass resolved addresses, never hostnames.
+ */
+declare function isPrivateOrReservedIp(ip: string): boolean;
+/**
+ * Validate a URL for SSRF without making the request: runs the sync checks and,
+ * for hostnames, resolves DNS and rejects if any address is private/reserved.
+ *
+ * Use this to guard a URL handed to code you do not control (so you cannot pin
+ * the connection). It cannot prevent rebinding between this check and that
+ * code's own connection — for requests you make yourself, use {@link safeFetch}.
+ */
+declare function assertSafeUrl(rawUrl: string, policy?: SafeFetchPolicy): Promise<void>;
+type FetchInput = Parameters<typeof fetch>[0];
+type FetchInit = Parameters<typeof fetch>[1];
+type FetchReturn = ReturnType<typeof fetch>;
+type SafeFetchFn = ((input: FetchInput, init?: FetchInit) => FetchReturn) & {
+    _dispatcher: Agent;
+};
+/**
+ * Build an SSRF-safe fetch bound to a policy. Reuse the returned function (it
+ * owns a pooled dispatcher) rather than calling this per request.
+ *
+ * Redirects are followed manually so EVERY hop is validated — including a hop
+ * whose target is a bare IP literal, which undici would otherwise connect to
+ * directly without invoking the pinning lookup. The original method/body and
+ * headers are NOT replayed across a redirect: the next hop may be attacker-
+ * chosen, so forwarding the payload or auth headers would leak them.
+ */
+declare function createSafeFetch(policy?: SafeFetchPolicy): SafeFetchFn;
+/**
+ * Replace the default policy used by {@link safeFetch}. Called by the server at
+ * boot from `defineServerConfig().outboundFetch(...)`. Passing undefined resets
+ * to the secure defaults (private IPs blocked, http/https only).
+ */
+declare function setDefaultSafeFetchPolicy(policy?: SafeFetchPolicy): void;
+/** The effective default policy (secure defaults merged with any configured overrides). */
+declare function getDefaultSafeFetchPolicy(): SafeFetchPolicy;
+/**
+ * SSRF-safe `fetch` using the configured default policy. Drop-in replacement for
+ * `fetch` when the URL may be influenced by user input.
+ */
+declare function safeFetch(input: FetchInput, init?: FetchInit): FetchReturn;
+
+export { type SafeFetchPolicy, SsrfBlockedError, assertSafeUrl, createSafeFetch, getDefaultSafeFetchPolicy, isPrivateOrReservedIp, safeFetch, setDefaultSafeFetchPolicy };

package/dist/security/index.js

@@ -0,0 +1,173 @@
+import { promises } from 'dns';
+import { BlockList, isIP } from 'net';
+import { Agent, fetch } from 'undici';
+
+// src/security/safe-fetch.ts
+var SsrfBlockedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SsrfBlockedError";
+  }
+};
+var DEFAULT_MAX_REDIRECTS = 5;
+var DEFAULTS = {
+  allowedProtocols: ["http:", "https:"],
+  blockPrivateIps: true
+};
+var blockedRanges = (() => {
+  const list = new BlockList();
+  list.addSubnet("0.0.0.0", 8, "ipv4");
+  list.addSubnet("10.0.0.0", 8, "ipv4");
+  list.addSubnet("100.64.0.0", 10, "ipv4");
+  list.addSubnet("127.0.0.0", 8, "ipv4");
+  list.addSubnet("169.254.0.0", 16, "ipv4");
+  list.addSubnet("172.16.0.0", 12, "ipv4");
+  list.addSubnet("192.0.0.0", 24, "ipv4");
+  list.addSubnet("192.0.2.0", 24, "ipv4");
+  list.addSubnet("192.168.0.0", 16, "ipv4");
+  list.addSubnet("198.18.0.0", 15, "ipv4");
+  list.addSubnet("198.51.100.0", 24, "ipv4");
+  list.addSubnet("203.0.113.0", 24, "ipv4");
+  list.addSubnet("224.0.0.0", 4, "ipv4");
+  list.addSubnet("240.0.0.0", 4, "ipv4");
+  list.addAddress("::1", "ipv6");
+  list.addAddress("::", "ipv6");
+  list.addSubnet("fc00::", 7, "ipv6");
+  list.addSubnet("fe80::", 10, "ipv6");
+  list.addSubnet("ff00::", 8, "ipv6");
+  list.addSubnet("2001:db8::", 32, "ipv6");
+  list.addSubnet("64:ff9b::", 96, "ipv6");
+  list.addSubnet("2002::", 16, "ipv6");
+  list.addSubnet("192.88.99.0", 24, "ipv4");
+  return list;
+})();
+function isPrivateOrReservedIp(ip) {
+  const family = isIP(ip);
+  if (family === 4) {
+    return blockedRanges.check(ip, "ipv4");
+  }
+  if (family === 6) {
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(ip);
+    if (mapped) {
+      return blockedRanges.check(mapped[1], "ipv4");
+    }
+    return blockedRanges.check(ip, "ipv6");
+  }
+  return true;
+}
+function stripBrackets(hostname) {
+  return hostname.replace(/^\[/, "").replace(/\]$/, "");
+}
+function assertUrlAllowed(rawUrl, policy) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new SsrfBlockedError(`Invalid URL: ${rawUrl}`);
+  }
+  const protocols = policy.allowedProtocols ?? DEFAULTS.allowedProtocols;
+  if (!protocols.includes(url.protocol)) {
+    throw new SsrfBlockedError(`Protocol not allowed: ${url.protocol}`);
+  }
+  const host = stripBrackets(url.hostname);
+  if (policy.allowHosts) {
+    const allowed = policy.allowHosts.some((h) => h.toLowerCase() === host.toLowerCase());
+    if (!allowed) {
+      throw new SsrfBlockedError(`Host not in allowlist: ${host}`);
+    }
+  }
+  if (policy.blockPrivateIps !== false && isIP(host) && isPrivateOrReservedIp(host)) {
+    throw new SsrfBlockedError(`Blocked address: ${host}`);
+  }
+  return url;
+}
+async function assertSafeUrl(rawUrl, policy) {
+  const merged = { ...getDefaultSafeFetchPolicy(), ...policy };
+  const url = assertUrlAllowed(rawUrl, merged);
+  const host = stripBrackets(url.hostname);
+  if (isIP(host) || merged.blockPrivateIps === false) {
+    return;
+  }
+  const addresses = await promises.lookup(host, { all: true });
+  for (const { address } of addresses) {
+    if (isPrivateOrReservedIp(address)) {
+      throw new SsrfBlockedError(`Host resolves to a blocked address: ${host} \u2192 ${address}`);
+    }
+  }
+}
+function pinnedLookup(policy) {
+  return (hostname, options, callback) => {
+    const family = typeof options === "object" && typeof options.family === "number" ? options.family : 0;
+    const wantsAll = typeof options === "object" && options.all === true;
+    promises.lookup(hostname, { all: true, verbatim: true, family }).then(
+      (addresses) => {
+        const safe = policy.blockPrivateIps === false ? addresses : addresses.filter((a) => !isPrivateOrReservedIp(a.address));
+        if (safe.length === 0) {
+          callback(new SsrfBlockedError(`Host resolves only to blocked addresses: ${hostname}`), "", 0);
+          return;
+        }
+        if (wantsAll) {
+          callback(null, safe);
+          return;
+        }
+        callback(null, safe[0].address, safe[0].family);
+      },
+      (err) => callback(err, "", 0)
+    );
+  };
+}
+function urlOf(input) {
+  if (typeof input === "string") {
+    return input;
+  }
+  if (input instanceof URL) {
+    return input.href;
+  }
+  return input.url;
+}
+function createSafeFetch(policy = {}) {
+  const merged = { ...DEFAULTS, ...policy };
+  const maxRedirects = merged.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  const dispatcher = new Agent({ connect: { lookup: pinnedLookup(merged) } });
+  const run = async (input, init) => {
+    let url = urlOf(input);
+    let hopInit = init;
+    for (let hop = 0; ; hop++) {
+      assertUrlAllowed(url, merged);
+      const res = await fetch(url, { ...hopInit, dispatcher, redirect: "manual" });
+      const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
+      if (!location) {
+        return res;
+      }
+      await res.body?.cancel().catch(() => {
+      });
+      if (hop >= maxRedirects) {
+        throw new SsrfBlockedError(`Too many redirects (> ${maxRedirects})`);
+      }
+      url = new URL(location, url).href;
+      hopInit = { method: "GET" };
+    }
+  };
+  const fn = ((input, init) => run(input, init));
+  fn._dispatcher = dispatcher;
+  return fn;
+}
+var configuredPolicy = {};
+var cachedDefaultFetch;
+function setDefaultSafeFetchPolicy(policy) {
+  cachedDefaultFetch?._dispatcher.close().catch(() => {
+  });
+  configuredPolicy = policy ?? {};
+  cachedDefaultFetch = void 0;
+}
+function getDefaultSafeFetchPolicy() {
+  return { ...DEFAULTS, ...configuredPolicy };
+}
+function safeFetch(input, init) {
+  cachedDefaultFetch ??= createSafeFetch(getDefaultSafeFetchPolicy());
+  return cachedDefaultFetch(input, init);
+}
+
+export { SsrfBlockedError, assertSafeUrl, createSafeFetch, getDefaultSafeFetchPolicy, isPrivateOrReservedIp, safeFetch, setDefaultSafeFetchPolicy };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/security/safe-fetch.ts"],"names":["dnsPromises","undiciFetch"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @spfn/core - SSRF-safe outbound fetch\n *\n * A drop-in `fetch` for calling URLs that may be influenced by user input\n * (webhooks, image fetchers, callback URLs). It blocks requests to private and\n * reserved IP ranges — including the cloud metadata address (169.254.169.254) —\n * and defeats DNS rebinding by resolving the hostname, validating every returned\n * address, and pinning the connection to a validated IP via a custom undici\n * `lookup`. Redirects go through the same dispatcher, so each hop is re-validated.\n *\n * A plain string allowlist cannot stop SSRF on its own: an attacker-controlled\n * hostname can resolve to a private IP (DNS rebinding). The pinning is the point.\n */\n\nimport { promises as dnsPromises } from 'node:dns';\nimport { isIP, BlockList, type LookupFunction } from 'node:net';\nimport { fetch as undiciFetch, Agent } from 'undici';\n\n/** Thrown when a request target is blocked by the SSRF policy. */\nexport class SsrfBlockedError extends Error\n{\n    constructor(message: string)\n    {\n        super(message);\n        this.name = 'SsrfBlockedError';\n    }\n}\n\nexport interface SafeFetchPolicy\n{\n    /** URL schemes allowed. @default ['http:', 'https:'] */\n    allowedProtocols?: string[];\n\n    /**\n     * Reject targets that resolve to a private or reserved IP range (loopback,\n     * link-local/metadata, RFC1918, ULA, multicast, …). @default true\n     */\n    blockPrivateIps?: boolean;\n\n    /**\n     * Exact hostname allowlist (case-insensitive). When set, only these hosts\n     * are reachable — the strongest control for a known set of upstreams.\n     * Enforced on every redirect hop, not just the first URL.\n     */\n    allowHosts?: string[];\n\n    /** Max redirects to follow, each re-validated. @default 5 */\n    maxRedirects?: number;\n}\n\nconst DEFAULT_MAX_REDIRECTS = 5;\n\nconst DEFAULTS: Required<Pick<SafeFetchPolicy, 'allowedProtocols' | 'blockPrivateIps'>> = {\n    allowedProtocols: ['http:', 'https:'],\n    blockPrivateIps: true,\n};\n\n/**\n * Private/reserved IP ranges. Built once. `BlockList` handles CIDR membership\n * for both families; IPv4-mapped IPv6 is unwrapped and checked as IPv4 so a\n * mapped public address still resolves.\n */\nconst blockedRanges = (() =>\n{\n    const list = new BlockList();\n\n    // IPv4 — RFC 1918 + special-purpose / reserved\n    list.addSubnet('0.0.0.0', 8, 'ipv4');\n    list.addSubnet('10.0.0.0', 8, 'ipv4');\n    list.addSubnet('100.64.0.0', 10, 'ipv4');   // CGNAT\n    list.addSubnet('127.0.0.0', 8, 'ipv4');     // loopback\n    list.addSubnet('169.254.0.0', 16, 'ipv4');  // link-local incl. cloud metadata\n    list.addSubnet('172.16.0.0', 12, 'ipv4');\n    list.addSubnet('192.0.0.0', 24, 'ipv4');\n    list.addSubnet('192.0.2.0', 24, 'ipv4');    // TEST-NET-1\n    list.addSubnet('192.168.0.0', 16, 'ipv4');\n    list.addSubnet('198.18.0.0', 15, 'ipv4');   // benchmarking\n    list.addSubnet('198.51.100.0', 24, 'ipv4'); // TEST-NET-2\n    list.addSubnet('203.0.113.0', 24, 'ipv4');  // TEST-NET-3\n    list.addSubnet('224.0.0.0', 4, 'ipv4');     // multicast\n    list.addSubnet('240.0.0.0', 4, 'ipv4');     // reserved + broadcast\n\n    // IPv6\n    list.addAddress('::1', 'ipv6');             // loopback\n    list.addAddress('::', 'ipv6');              // unspecified\n    list.addSubnet('fc00::', 7, 'ipv6');        // unique local\n    list.addSubnet('fe80::', 10, 'ipv6');       // link-local\n    list.addSubnet('ff00::', 8, 'ipv6');        // multicast\n    list.addSubnet('2001:db8::', 32, 'ipv6');   // documentation\n    list.addSubnet('64:ff9b::', 96, 'ipv6');    // NAT64 well-known prefix (can wrap private v4)\n    list.addSubnet('2002::', 16, 'ipv6');       // 6to4 (can wrap private v4)\n    list.addSubnet('192.88.99.0', 24, 'ipv4');  // 6to4 anycast relay\n\n    return list;\n})();\n\n/**\n * Whether an IP literal falls in a private or reserved range. A non-IP input is\n * treated as unsafe (`true`) — callers pass resolved addresses, never hostnames.\n */\nexport function isPrivateOrReservedIp(ip: string): boolean\n{\n    const family = isIP(ip);\n\n    if (family === 4)\n    {\n        return blockedRanges.check(ip, 'ipv4');\n    }\n\n    if (family === 6)\n    {\n        // IPv4-mapped (::ffff:a.b.c.d): judge by the embedded IPv4.\n        const mapped = /^::ffff:(\\d{1,3}(?:\\.\\d{1,3}){3})$/i.exec(ip);\n        if (mapped)\n        {\n            return blockedRanges.check(mapped[1], 'ipv4');\n        }\n\n        return blockedRanges.check(ip, 'ipv6');\n    }\n\n    return true;\n}\n\nfunction stripBrackets(hostname: string): string\n{\n    return hostname.replace(/^\\[/, '').replace(/\\]$/, '');\n}\n\n/**\n * Synchronous, no-DNS checks: protocol, host allowlist, and — when the host is\n * an IP literal — the private-range check. Throws SsrfBlockedError on violation.\n */\nfunction assertUrlAllowed(rawUrl: string, policy: SafeFetchPolicy): URL\n{\n    let url: URL;\n    try\n    {\n        url = new URL(rawUrl);\n    }\n    catch\n    {\n        throw new SsrfBlockedError(`Invalid URL: ${rawUrl}`);\n    }\n\n    const protocols = policy.allowedProtocols ?? DEFAULTS.allowedProtocols;\n    if (!protocols.includes(url.protocol))\n    {\n        throw new SsrfBlockedError(`Protocol not allowed: ${url.protocol}`);\n    }\n\n    const host = stripBrackets(url.hostname);\n\n    if (policy.allowHosts)\n    {\n        const allowed = policy.allowHosts.some(h => h.toLowerCase() === host.toLowerCase());\n        if (!allowed)\n        {\n            throw new SsrfBlockedError(`Host not in allowlist: ${host}`);\n        }\n    }\n\n    if (policy.blockPrivateIps !== false && isIP(host) && isPrivateOrReservedIp(host))\n    {\n        throw new SsrfBlockedError(`Blocked address: ${host}`);\n    }\n\n    return url;\n}\n\n/**\n * Validate a URL for SSRF without making the request: runs the sync checks and,\n * for hostnames, resolves DNS and rejects if any address is private/reserved.\n *\n * Use this to guard a URL handed to code you do not control (so you cannot pin\n * the connection). It cannot prevent rebinding between this check and that\n * code's own connection — for requests you make yourself, use {@link safeFetch}.\n */\nexport async function assertSafeUrl(rawUrl: string, policy?: SafeFetchPolicy): Promise<void>\n{\n    const merged = { ...getDefaultSafeFetchPolicy(), ...policy };\n    const url = assertUrlAllowed(rawUrl, merged);\n    const host = stripBrackets(url.hostname);\n\n    // IP literals are fully judged by assertUrlAllowed; only hostnames need DNS.\n    if (isIP(host) || merged.blockPrivateIps === false)\n    {\n        return;\n    }\n\n    const addresses = await dnsPromises.lookup(host, { all: true });\n    for (const { address } of addresses)\n    {\n        if (isPrivateOrReservedIp(address))\n        {\n            throw new SsrfBlockedError(`Host resolves to a blocked address: ${host} → ${address}`);\n        }\n    }\n}\n\n/**\n * Custom DNS lookup for undici: resolve, drop private/reserved addresses, and\n * return only validated ones — so the connection is pinned to an address we\n * already checked (no rebinding window between check and connect).\n */\nfunction pinnedLookup(policy: SafeFetchPolicy): LookupFunction\n{\n    return (hostname, options, callback) =>\n    {\n        const family = typeof options === 'object' && typeof options.family === 'number' ? options.family : 0;\n        const wantsAll = typeof options === 'object' && options.all === true;\n\n        dnsPromises.lookup(hostname, { all: true, verbatim: true, family }).then(\n            (addresses) =>\n            {\n                const safe = policy.blockPrivateIps === false\n                    ? addresses\n                    : addresses.filter(a => !isPrivateOrReservedIp(a.address));\n\n                if (safe.length === 0)\n                {\n                    callback(new SsrfBlockedError(`Host resolves only to blocked addresses: ${hostname}`), '', 0);\n\n                    return;\n                }\n\n                if (wantsAll)\n                {\n                    (callback as unknown as (err: null, addresses: typeof safe) => void)(null, safe);\n\n                    return;\n                }\n\n                callback(null, safe[0].address, safe[0].family);\n            },\n            (err: NodeJS.ErrnoException) => callback(err, '', 0),\n        );\n    };\n}\n\ntype FetchInput = Parameters<typeof undiciFetch>[0];\n\ntype FetchInit = Parameters<typeof undiciFetch>[1];\n\ntype FetchReturn = ReturnType<typeof undiciFetch>;\n\nfunction urlOf(input: FetchInput): string\n{\n    if (typeof input === 'string')\n    {\n        return input;\n    }\n    if (input instanceof URL)\n    {\n        return input.href;\n    }\n\n    return (input as { url: string }).url;\n}\n\ntype SafeFetchFn = ((input: FetchInput, init?: FetchInit) => FetchReturn) & { _dispatcher: Agent };\n\n/**\n * Build an SSRF-safe fetch bound to a policy. Reuse the returned function (it\n * owns a pooled dispatcher) rather than calling this per request.\n *\n * Redirects are followed manually so EVERY hop is validated — including a hop\n * whose target is a bare IP literal, which undici would otherwise connect to\n * directly without invoking the pinning lookup. The original method/body and\n * headers are NOT replayed across a redirect: the next hop may be attacker-\n * chosen, so forwarding the payload or auth headers would leak them.\n */\nexport function createSafeFetch(policy: SafeFetchPolicy = {}): SafeFetchFn\n{\n    const merged = { ...DEFAULTS, ...policy };\n    const maxRedirects = merged.maxRedirects ?? DEFAULT_MAX_REDIRECTS;\n    const dispatcher = new Agent({ connect: { lookup: pinnedLookup(merged) } });\n\n    const run = async (input: FetchInput, init?: FetchInit): Promise<Awaited<FetchReturn>> =>\n    {\n        let url = urlOf(input);\n        let hopInit: FetchInit = init;\n\n        for (let hop = 0; ; hop++)\n        {\n            assertUrlAllowed(url, merged);\n\n            const res = await undiciFetch(url, { ...hopInit, dispatcher, redirect: 'manual' });\n\n            const location = res.status >= 300 && res.status < 400 ? res.headers.get('location') : null;\n            if (!location)\n            {\n                return res;\n            }\n\n            await res.body?.cancel().catch(() => \n            {});\n\n            if (hop >= maxRedirects)\n            {\n                throw new SsrfBlockedError(`Too many redirects (> ${maxRedirects})`);\n            }\n\n            url = new URL(location, url).href;\n            hopInit = { method: 'GET' };\n        }\n    };\n\n    const fn = ((input: FetchInput, init?: FetchInit) => run(input, init)) as SafeFetchFn;\n    fn._dispatcher = dispatcher;\n\n    return fn;\n}\n\n// ---------------------------------------------------------------------------\n// Default policy registry — set once at server boot, read by safeFetch().\n// ---------------------------------------------------------------------------\n\nlet configuredPolicy: SafeFetchPolicy = {};\nlet cachedDefaultFetch: SafeFetchFn | undefined;\n\n/**\n * Replace the default policy used by {@link safeFetch}. Called by the server at\n * boot from `defineServerConfig().outboundFetch(...)`. Passing undefined resets\n * to the secure defaults (private IPs blocked, http/https only).\n */\nexport function setDefaultSafeFetchPolicy(policy?: SafeFetchPolicy): void\n{\n    // Close the previous dispatcher's connection pool so repeated boots\n    // (tests, multi-app processes) don't leak Agents.\n    cachedDefaultFetch?._dispatcher.close().catch(() => \n    {});\n    configuredPolicy = policy ?? {};\n    cachedDefaultFetch = undefined;\n}\n\n/** The effective default policy (secure defaults merged with any configured overrides). */\nexport function getDefaultSafeFetchPolicy(): SafeFetchPolicy\n{\n    return { ...DEFAULTS, ...configuredPolicy };\n}\n\n/**\n * SSRF-safe `fetch` using the configured default policy. Drop-in replacement for\n * `fetch` when the URL may be influenced by user input.\n */\nexport function safeFetch(input: FetchInput, init?: FetchInit): FetchReturn\n{\n    cachedDefaultFetch ??= createSafeFetch(getDefaultSafeFetchPolicy());\n\n    return cachedDefaultFetch(input, init);\n}\n"]}