@atproto-labs/fetch-node 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @atproto-labs/fetch-node
 
+## 0.1.10
+
+### Patch Changes
+
+- [#4108](https://github.com/bluesky-social/atproto/pull/4108) [`f9dc9aa4c`](https://github.com/bluesky-social/atproto/commit/f9dc9aa4c9eaf2f82d140fbf011a9015e7f1a00d) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Allow forcing the use of keep-alive agent on older NodeJs version when unicast protection is active
+
+- [#4108](https://github.com/bluesky-social/atproto/pull/4108) [`f9dc9aa4c`](https://github.com/bluesky-social/atproto/commit/f9dc9aa4c9eaf2f82d140fbf011a9015e7f1a00d) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Use keep-alive connection when unicast protection is enabled on NodeJS >= 20
+
 ## 0.1.9
 
 ### Patch Changes

package/dist/safe.d.ts

@@ -1,30 +1,41 @@
-import { Fetch } from '@atproto-labs/fetch';
-export type SafeFetchWrapOptions = NonNullable<Parameters<typeof safeFetchWrap>[0]>;
+import { UnicastFetchWrapOptions } from './unicast.js';
+export type SafeFetchWrapOptions<C> = UnicastFetchWrapOptions<C> & {
+    responseMaxSize?: number;
+    ssrfProtection?: boolean;
+    allowCustomPort?: boolean;
+    allowData?: boolean;
+    allowHttp?: boolean;
+    allowIpHost?: boolean;
+    allowPrivateIps?: boolean;
+    timeout?: number;
+    forbiddenDomainNames?: Iterable<string>;
+    /**
+     * When `false`, a {@link RequestInit['redirect']} value must be explicitly
+     * provided as second argument to the returned function or requests will fail.
+     *
+     * @default false
+     */
+    allowImplicitRedirect?: boolean;
+};
 /**
  * Wrap a fetch function with safety checks so that it can be safely used
  * with user provided input (URL).
  *
  * @see {@link https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html}
- */
-export declare function safeFetchWrap({ fetch, responseMaxSize, // 512kB
-ssrfProtection, allowCustomPort, allowData, allowHttp, allowIpHost, allowPrivateIps, timeout, forbiddenDomainNames, 
-/**
- * When `false`, a {@link RequestInit['redirect']} value must be explicitly
- * provided or the request will fail.
  *
- * @default false
+ * @note When {@link SafeFetchWrapOptions.allowImplicitRedirect} is `false`
+ * (default), then the returned function **must** be called setting the second
+ * argument's `redirect` property to one of the allowed values. Otherwise, if
+ * the returned fetch function is called with a `Request` object (and no
+ * explicit `redirect` init object), then the verification code will not be able
+ * to determine if the `redirect` property was explicitly set or based on the
+ * default value (`follow`), causing it to preventively block the request (throw
+ * an error). For this reason, unless you set
+ * {@link SafeFetchWrapOptions.allowImplicitRedirect} to `true`, you should
+ * **not** wrap the returned function into another function that creates a
+ * {@link Request} object before passing it to the function (as a e.g. a logging
+ * function would).
  */
-allowImplicitRedirect, }?: {
-    fetch?: Fetch | undefined;
-    responseMaxSize?: number | undefined;
-    ssrfProtection?: boolean | undefined;
-    allowCustomPort?: boolean | undefined;
-    allowData?: boolean | undefined;
-    allowHttp?: boolean | undefined;
-    allowIpHost?: boolean | undefined;
-    allowPrivateIps?: boolean | undefined;
-    timeout?: number | undefined;
-    forbiddenDomainNames?: Iterable<string> | undefined;
-    allowImplicitRedirect?: boolean | undefined;
-}): (input: string | URL | Request, init?: RequestInit | undefined) => Promise<Response>;
+export declare function safeFetchWrap<C>({ fetch, dangerouslyForceKeepAliveAgent, responseMaxSize, // 512kB
+ssrfProtection, allowCustomPort, allowData, allowHttp, allowIpHost, allowPrivateIps, timeout, forbiddenDomainNames, allowImplicitRedirect, }?: SafeFetchWrapOptions<C>): (input: string | URL | Request, init?: RequestInit | undefined) => Promise<Response>;
 //# sourceMappingURL=safe.d.ts.map

package/dist/safe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe.d.ts","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,EAQN,MAAM,qBAAqB,CAAA;AAI5B,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAC5C,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CACpC,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAC5B,KAAiC,EACjC,eAA4B,EAAE,QAAQ;AACtC,cAAqB,EACrB,eAAiC,EACjC,SAAiB,EACjB,SAA2B,EAC3B,WAAkB,EAClB,eAAiC,EACjC,OAAc,EACd,oBAAyE;AACzE;;;;;GAKG;AACH,qBAA6B,GAC9B;;;;;;;;;;;;CAAK,wFAoDL"}
+{"version":3,"file":"safe.d.ts","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,uBAAuB,EAAoB,MAAM,cAAc,CAAA;AAExE,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC,CAAC,GAAG;IACjE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACvC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAC/B,KAAoC,EACpC,8BAAsC,EACtC,eAA4B,EAAE,QAAQ;AACtC,cAAqB,EACrB,eAAiC,EACjC,SAAiB,EACjB,SAA2B,EAC3B,WAAkB,EAClB,eAAiC,EACjC,OAAc,EACd,oBAAyE,EACzE,qBAA6B,GAC9B,GAAE,oBAAoB,CAAC,CAAC,CAAM,wFAsD9B"}

package/dist/safe.js

@@ -9,16 +9,22 @@ const unicast_js_1 = require("./unicast.js");
  * with user provided input (URL).
  *
  * @see {@link https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html}
- */
-function safeFetchWrap({ fetch = globalThis.fetch, responseMaxSize = 512 * 1024, // 512kB
-ssrfProtection = true, allowCustomPort = !ssrfProtection, allowData = false, allowHttp = !ssrfProtection, allowIpHost = true, allowPrivateIps = !ssrfProtection, timeout = 10e3, forbiddenDomainNames = fetch_1.DEFAULT_FORBIDDEN_DOMAIN_NAMES, 
-/**
- * When `false`, a {@link RequestInit['redirect']} value must be explicitly
- * provided or the request will fail.
  *
- * @default false
+ * @note When {@link SafeFetchWrapOptions.allowImplicitRedirect} is `false`
+ * (default), then the returned function **must** be called setting the second
+ * argument's `redirect` property to one of the allowed values. Otherwise, if
+ * the returned fetch function is called with a `Request` object (and no
+ * explicit `redirect` init object), then the verification code will not be able
+ * to determine if the `redirect` property was explicitly set or based on the
+ * default value (`follow`), causing it to preventively block the request (throw
+ * an error). For this reason, unless you set
+ * {@link SafeFetchWrapOptions.allowImplicitRedirect} to `true`, you should
+ * **not** wrap the returned function into another function that creates a
+ * {@link Request} object before passing it to the function (as a e.g. a logging
+ * function would).
  */
-allowImplicitRedirect = false, } = {}) {
+function safeFetchWrap({ fetch = globalThis.fetch, dangerouslyForceKeepAliveAgent = false, responseMaxSize = 512 * 1024, // 512kB
+ssrfProtection = true, allowCustomPort = !ssrfProtection, allowData = false, allowHttp = !ssrfProtection, allowIpHost = true, allowPrivateIps = !ssrfProtection, timeout = 10e3, forbiddenDomainNames = fetch_1.DEFAULT_FORBIDDEN_DOMAIN_NAMES, allowImplicitRedirect = false, } = {}) {
     return (0, pipe_1.pipe)(
     /**
      * Require explicit {@link RequestInit['redirect']} mode
@@ -55,7 +61,9 @@ allowImplicitRedirect = false, } = {}) {
      * input, we need to make sure that the request is not vulnerable to SSRF
      * attacks.
      */
-    allowPrivateIps ? fetch : (0, unicast_js_1.unicastFetchWrap)({ fetch })), 
+    allowPrivateIps
+        ? fetch
+        : (0, unicast_js_1.unicastFetchWrap)({ fetch, dangerouslyForceKeepAliveAgent })), 
     /**
      * Since we will be fetching user owned data, we need to make sure that an
      * attacker cannot force us to download a large amounts of data.

package/dist/safe.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe.js","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":";;AAwBA,sCAsEC;AA9FD,+CAU4B;AAC5B,6CAAyC;AACzC,6CAA+C;AAM/C;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,EAC5B,KAAK,GAAG,UAAU,CAAC,KAAc,EACjC,eAAe,GAAG,GAAG,GAAG,IAAI,EAAE,QAAQ;AACtC,cAAc,GAAG,IAAI,EACrB,eAAe,GAAG,CAAC,cAAc,EACjC,SAAS,GAAG,KAAK,EACjB,SAAS,GAAG,CAAC,cAAc,EAC3B,WAAW,GAAG,IAAI,EAClB,eAAe,GAAG,CAAC,cAAc,EACjC,OAAO,GAAG,IAAI,EACd,oBAAoB,GAAG,sCAAkD;AACzE;;;;;GAKG;AACH,qBAAqB,GAAG,KAAK,MAC3B,EAAE;IACJ,OAAO,IAAA,WAAI;IACT;;OAEG;IACH,qBAAqB,CAAC,CAAC,CAAC,iBAAS,CAAC,CAAC,CAAC,IAAA,6CAAqC,GAAE;IAE3E;;OAEG;IACH,WAAW,CAAC,CAAC,CAAC,iBAAS,CAAC,CAAC,CAAC,IAAA,kCAA0B,GAAE;IAEtD;;OAEG;IACH,IAAA,qCAA6B,EAAC;QAC5B,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,SAAS,IAAI,EAAE,eAAe,EAAE;QACzC,QAAQ,EAAE,EAAE,eAAe,EAAE;KAC9B,CAAC;IAEF;;;;;OAKG;IACH,IAAA,2CAAmC,EAAC,oBAAoB,CAAC;IAEzD;;;OAGG;IACH,IAAA,kBAAU,EACR,OAAO;IAEP;;;;OAIG;IACH,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAA,6BAAgB,EAAC,EAAE,KAAK,EAAE,CAAC,CACtD;IAED;;;OAGG;IACH,IAAA,6BAAqB,EAAC,eAAe,CAAC,CACd,CAAA;AAC5B,CAAC"}
+{"version":3,"file":"safe.js","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":";;AAoDA,sCAmEC;AAvHD,+CAU4B;AAC5B,6CAAyC;AACzC,6CAAwE;AAqBxE;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,aAAa,CAAI,EAC/B,KAAK,GAAG,UAAU,CAAC,KAAiB,EACpC,8BAA8B,GAAG,KAAK,EACtC,eAAe,GAAG,GAAG,GAAG,IAAI,EAAE,QAAQ;AACtC,cAAc,GAAG,IAAI,EACrB,eAAe,GAAG,CAAC,cAAc,EACjC,SAAS,GAAG,KAAK,EACjB,SAAS,GAAG,CAAC,cAAc,EAC3B,WAAW,GAAG,IAAI,EAClB,eAAe,GAAG,CAAC,cAAc,EACjC,OAAO,GAAG,IAAI,EACd,oBAAoB,GAAG,sCAAkD,EACzE,qBAAqB,GAAG,KAAK,MACF,EAAE;IAC7B,OAAO,IAAA,WAAI;IACT;;OAEG;IACH,qBAAqB,CAAC,CAAC,CAAC,iBAAS,CAAC,CAAC,CAAC,IAAA,6CAAqC,GAAE;IAE3E;;OAEG;IACH,WAAW,CAAC,CAAC,CAAC,iBAAS,CAAC,CAAC,CAAC,IAAA,kCAA0B,GAAE;IAEtD;;OAEG;IACH,IAAA,qCAA6B,EAAC;QAC5B,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,SAAS,IAAI,EAAE,eAAe,EAAE;QACzC,QAAQ,EAAE,EAAE,eAAe,EAAE;KAC9B,CAAC;IAEF;;;;;OAKG;IACH,IAAA,2CAAmC,EAAC,oBAAoB,CAAC;IAEzD;;;OAGG;IACH,IAAA,kBAAU,EACR,OAAO;IAEP;;;;OAIG;IACH,eAAe;QACb,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAA,6BAAgB,EAAC,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC,CAChE;IAED;;;OAGG;IACH,IAAA,6BAAqB,EAAC,eAAe,CAAC,CACd,CAAA;AAC5B,CAAC"}

package/dist/unicast.d.ts

@@ -1,13 +1,41 @@
 import dns from 'node:dns';
 import { LookupFunction } from 'node:net';
 import { Fetch, FetchContext } from '@atproto-labs/fetch';
-export type SsrfFetchWrapOptions<C = FetchContext> = {
+export type UnicastFetchWrapOptions<C = FetchContext> = {
     fetch?: Fetch<C>;
+    /**
+     * ## ‼️ important security feature use with care
+     *
+     * On older NodeJS version, the `dispatcher` init option is ignored when
+     * creating a new Request instance. It can only be passed through the fetch
+     * function directly.
+     *
+     * Since this is a security feature, we need to ensure that the unicastLookup
+     * function is called to resolve the hostname to a unicast IP address.
+     *
+     * However, in the case a custom "fetch" function is passed here (fetch !==
+     * globalThis.fetch), we have no guarantee that the dispatcher will be used to
+     * make the request. Because of this, in such a case, we will use a one-time
+     * use dispatcher that checks that the provided fetch function indeed made use
+     * of the "unicastLookup" when a custom dispatch init function is used.
+     *
+     * Sadly, this means that we cannot use "keepAlive" connections, as the method
+     * used to ensure that "unicastLookup" gets called requires to create a new
+     * dispatcher for each request.
+     *
+     * If you can guarantee that the provided fetch function will make use of the
+     * "dispatcher" init option, you can set this flag to true, which will enable
+     * the use of a single agent (with keep-alive) for all requests.
+     *
+     * @default false
+     * @note This option has no effect on Node.js versions >= 20
+     */
+    dangerouslyForceKeepAliveAgent?: boolean;
 };
 /**
  * @see {@link https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_%28SSRF%29/}
  */
-export declare function unicastFetchWrap<C = FetchContext>({ fetch, }: SsrfFetchWrapOptions<C>): Fetch<C>;
+export declare function unicastFetchWrap<C = FetchContext>({ fetch, dangerouslyForceKeepAliveAgent, }: UnicastFetchWrapOptions<C>): Fetch<C>;
 export declare function unicastLookup(hostname: string, options: dns.LookupOptions, callback: Parameters<LookupFunction>[2]): void;
 /**
  * @param hostname - a syntactically valid hostname

package/dist/unicast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unicast.d.ts","sourceRoot":"","sources":["../src/unicast.ts"],"names":[],"mappings":"AAAA,OAAO,GAAsB,MAAM,UAAU,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAGzC,OAAO,EACL,KAAK,EACL,YAAY,EAIb,MAAM,qBAAqB,CAAA;AAK5B,MAAM,MAAM,oBAAoB,CAAC,CAAC,GAAG,YAAY,IAAI;IACnD,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;CACjB,CAAA;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,YAAY,EAAE,EACjD,KAAwB,GACzB,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA0IpC;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,aAAa,EAC1B,QAAQ,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,QA0BxC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAYzD"}
+{"version":3,"file":"unicast.d.ts","sourceRoot":"","sources":["../src/unicast.ts"],"names":[],"mappings":"AAAA,OAAO,GAAsB,MAAM,UAAU,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAGzC,OAAO,EACL,KAAK,EACL,YAAY,EAIb,MAAM,qBAAqB,CAAA;AAK5B,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,YAAY,IAAI;IACtD,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;IAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAA;CACzC,CAAA;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,YAAY,EAAE,EACjD,KAAwB,EACxB,8BAAsC,GACvC,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAuIvC;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,aAAa,EAC1B,QAAQ,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,QA0BxC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAYzD"}

package/dist/unicast.js

@@ -12,22 +12,15 @@ const undici_1 = require("undici");
 const fetch_1 = require("@atproto-labs/fetch");
 const util_js_1 = require("./util.js");
 const { IPv4, IPv6 } = ipaddr_js_1.default;
+// @TODO support other runtimes ?
+const SUPPORTS_REQUEST_INIT_DISPATCHER = Number(process.versions.node.split('.')[0]) >= 20;
 /**
  * @see {@link https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_%28SSRF%29/}
  */
-function unicastFetchWrap({ fetch = globalThis.fetch, }) {
-    // In order to enforce the SSRF protection, we need to use a custom dispatcher
-    // that uses "unicastLookup" to resolve the hostname to a unicast IP address.
-    // In case a custom "fetch" function is passed here, we have no assurance that
-    // the dispatcher will be used to make the request. Because of this, in case a
-    // custom fetch method is passed, we will use a on-time use dispatcher that
-    // ensures that "unicastLookup" gets called to resolve the hostname to an IP
-    // address and ensure that it is a unicast address.
-    // Sadly, this means that we cannot use "keepAlive" connections, as the method
-    // used to ensure that "unicastLookup" gets called requires to create a new
-    // dispatcher for each request.
-    // @TODO: find a way to use a re-usable dispatcher with a custom fetch method.
-    if (fetch === globalThis.fetch) {
+function unicastFetchWrap({ fetch = globalThis.fetch, dangerouslyForceKeepAliveAgent = false, }) {
+    if (SUPPORTS_REQUEST_INIT_DISPATCHER ||
+        dangerouslyForceKeepAliveAgent ||
+        fetch === globalThis.fetch) {
         const dispatcher = new undici_1.Agent({
             connect: { lookup: unicastLookup },
         });
@@ -39,8 +32,15 @@ function unicastFetchWrap({ fetch = globalThis.fetch, }) {
             if (url.hostname && (0, util_js_1.isUnicastIp)(url.hostname) === false) {
                 throw new fetch_1.FetchRequestError((0, fetch_1.asRequest)(input, init), 400, 'Hostname is a non-unicast address');
             }
-            // @ts-expect-error non-standard option
-            return fetch.call(this, input, { ...init, dispatcher });
+            if (SUPPORTS_REQUEST_INIT_DISPATCHER) {
+                // @ts-expect-error non-standard option
+                const request = new Request(input, { ...init, dispatcher });
+                return fetch.call(this, request);
+            }
+            else {
+                // @ts-expect-error non-standard option
+                return fetch.call(this, input, { ...init, dispatcher });
+            }
         };
     }
     else {
@@ -61,13 +61,15 @@ function unicastFetchWrap({ fetch = globalThis.fetch, }) {
                     throw new fetch_1.FetchRequestError((0, fetch_1.asRequest)(input, init), 400, 'Hostname is a non-unicast address');
                 }
                 case undefined: {
-                    // hostname is a domain name, using the dispatcher defined above
-                    // will result in the DNS lookup being performed, ensuring that the
-                    // hostname resolves to a unicast address.
+                    // hostname is a domain name, let's create a new dispatcher that
+                    // will 1) use the unicastLookup function to resolve the hostname
+                    // and 2) allow us to check that the lookup function was indeed
+                    // called.
                     let didLookup = false;
                     const dispatcher = new undici_1.Client(url.origin, {
-                        // Do *not* enable H2 here, as it will cause an error (the client
-                        // will terminate the connection before the response is consumed).
+                        // Do *not* enable H2 here, as it will cause an error (the
+                        // client will terminate the connection before the response is
+                        // consumed).
                         // https://github.com/nodejs/undici/issues/3671
                         connect: {
                             keepAlive: false, // Client will be used once

package/dist/unicast.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto-labs/fetch-node",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "license": "MIT",
   "description": "SSRF protection for fetch() in Node.js",
   "keywords": [

package/src/safe.ts

@@ -10,20 +10,49 @@ import {
   timedFetch,
 } from '@atproto-labs/fetch'
 import { pipe } from '@atproto-labs/pipe'
-import { unicastFetchWrap } from './unicast.js'
+import { UnicastFetchWrapOptions, unicastFetchWrap } from './unicast.js'
 
-export type SafeFetchWrapOptions = NonNullable<
-  Parameters<typeof safeFetchWrap>[0]
->
+export type SafeFetchWrapOptions<C> = UnicastFetchWrapOptions<C> & {
+  responseMaxSize?: number
+  ssrfProtection?: boolean
+  allowCustomPort?: boolean
+  allowData?: boolean
+  allowHttp?: boolean
+  allowIpHost?: boolean
+  allowPrivateIps?: boolean
+  timeout?: number
+  forbiddenDomainNames?: Iterable<string>
+  /**
+   * When `false`, a {@link RequestInit['redirect']} value must be explicitly
+   * provided as second argument to the returned function or requests will fail.
+   *
+   * @default false
+   */
+  allowImplicitRedirect?: boolean
+}
 
 /**
  * Wrap a fetch function with safety checks so that it can be safely used
  * with user provided input (URL).
  *
  * @see {@link https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html}
+ *
+ * @note When {@link SafeFetchWrapOptions.allowImplicitRedirect} is `false`
+ * (default), then the returned function **must** be called setting the second
+ * argument's `redirect` property to one of the allowed values. Otherwise, if
+ * the returned fetch function is called with a `Request` object (and no
+ * explicit `redirect` init object), then the verification code will not be able
+ * to determine if the `redirect` property was explicitly set or based on the
+ * default value (`follow`), causing it to preventively block the request (throw
+ * an error). For this reason, unless you set
+ * {@link SafeFetchWrapOptions.allowImplicitRedirect} to `true`, you should
+ * **not** wrap the returned function into another function that creates a
+ * {@link Request} object before passing it to the function (as a e.g. a logging
+ * function would).
  */
-export function safeFetchWrap({
-  fetch = globalThis.fetch as Fetch,
+export function safeFetchWrap<C>({
+  fetch = globalThis.fetch as Fetch<C>,
+  dangerouslyForceKeepAliveAgent = false,
   responseMaxSize = 512 * 1024, // 512kB
   ssrfProtection = true,
   allowCustomPort = !ssrfProtection,
@@ -33,14 +62,8 @@ export function safeFetchWrap({
   allowPrivateIps = !ssrfProtection,
   timeout = 10e3,
   forbiddenDomainNames = DEFAULT_FORBIDDEN_DOMAIN_NAMES as Iterable<string>,
-  /**
-   * When `false`, a {@link RequestInit['redirect']} value must be explicitly
-   * provided or the request will fail.
-   *
-   * @default false
-   */
   allowImplicitRedirect = false,
-} = {}) {
+}: SafeFetchWrapOptions<C> = {}) {
   return pipe(
     /**
      * Require explicit {@link RequestInit['redirect']} mode
@@ -83,7 +106,9 @@ export function safeFetchWrap({
        * input, we need to make sure that the request is not vulnerable to SSRF
        * attacks.
        */
-      allowPrivateIps ? fetch : unicastFetchWrap({ fetch }),
+      allowPrivateIps
+        ? fetch
+        : unicastFetchWrap({ fetch, dangerouslyForceKeepAliveAgent }),
     ),
 
     /**

package/src/unicast.ts

@@ -13,32 +13,55 @@ import { isUnicastIp } from './util.js'
 
 const { IPv4, IPv6 } = ipaddr
 
-export type SsrfFetchWrapOptions<C = FetchContext> = {
+export type UnicastFetchWrapOptions<C = FetchContext> = {
   fetch?: Fetch<C>
+
+  /**
+   * ## ‼️ important security feature use with care
+   *
+   * On older NodeJS version, the `dispatcher` init option is ignored when
+   * creating a new Request instance. It can only be passed through the fetch
+   * function directly.
+   *
+   * Since this is a security feature, we need to ensure that the unicastLookup
+   * function is called to resolve the hostname to a unicast IP address.
+   *
+   * However, in the case a custom "fetch" function is passed here (fetch !==
+   * globalThis.fetch), we have no guarantee that the dispatcher will be used to
+   * make the request. Because of this, in such a case, we will use a one-time
+   * use dispatcher that checks that the provided fetch function indeed made use
+   * of the "unicastLookup" when a custom dispatch init function is used.
+   *
+   * Sadly, this means that we cannot use "keepAlive" connections, as the method
+   * used to ensure that "unicastLookup" gets called requires to create a new
+   * dispatcher for each request.
+   *
+   * If you can guarantee that the provided fetch function will make use of the
+   * "dispatcher" init option, you can set this flag to true, which will enable
+   * the use of a single agent (with keep-alive) for all requests.
+   *
+   * @default false
+   * @note This option has no effect on Node.js versions >= 20
+   */
+  dangerouslyForceKeepAliveAgent?: boolean
 }
 
+// @TODO support other runtimes ?
+const SUPPORTS_REQUEST_INIT_DISPATCHER =
+  Number(process.versions.node.split('.')[0]) >= 20
+
 /**
  * @see {@link https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_%28SSRF%29/}
  */
 export function unicastFetchWrap<C = FetchContext>({
   fetch = globalThis.fetch,
-}: SsrfFetchWrapOptions<C>): Fetch<C> {
-  // In order to enforce the SSRF protection, we need to use a custom dispatcher
-  // that uses "unicastLookup" to resolve the hostname to a unicast IP address.
-
-  // In case a custom "fetch" function is passed here, we have no assurance that
-  // the dispatcher will be used to make the request. Because of this, in case a
-  // custom fetch method is passed, we will use a on-time use dispatcher that
-  // ensures that "unicastLookup" gets called to resolve the hostname to an IP
-  // address and ensure that it is a unicast address.
-
-  // Sadly, this means that we cannot use "keepAlive" connections, as the method
-  // used to ensure that "unicastLookup" gets called requires to create a new
-  // dispatcher for each request.
-
-  // @TODO: find a way to use a re-usable dispatcher with a custom fetch method.
-
-  if (fetch === globalThis.fetch) {
+  dangerouslyForceKeepAliveAgent = false,
+}: UnicastFetchWrapOptions<C>): Fetch<C> {
+  if (
+    SUPPORTS_REQUEST_INIT_DISPATCHER ||
+    dangerouslyForceKeepAliveAgent ||
+    fetch === globalThis.fetch
+  ) {
     const dispatcher = new Agent({
       connect: { lookup: unicastLookup },
     })
@@ -62,8 +85,14 @@ export function unicastFetchWrap<C = FetchContext>({
         )
       }
 
-      // @ts-expect-error non-standard option
-      return fetch.call(this, input, { ...init, dispatcher })
+      if (SUPPORTS_REQUEST_INIT_DISPATCHER) {
+        // @ts-expect-error non-standard option
+        const request = new Request(input, { ...init, dispatcher })
+        return fetch.call(this, request)
+      } else {
+        // @ts-expect-error non-standard option
+        return fetch.call(this, input, { ...init, dispatcher })
+      }
     }
   } else {
     return async function (input, init): Promise<Response> {
@@ -96,14 +125,16 @@ export function unicastFetchWrap<C = FetchContext>({
         }
 
         case undefined: {
-          // hostname is a domain name, using the dispatcher defined above
-          // will result in the DNS lookup being performed, ensuring that the
-          // hostname resolves to a unicast address.
+          // hostname is a domain name, let's create a new dispatcher that
+          // will 1) use the unicastLookup function to resolve the hostname
+          // and 2) allow us to check that the lookup function was indeed
+          // called.
 
           let didLookup = false
           const dispatcher = new Client(url.origin, {
-            // Do *not* enable H2 here, as it will cause an error (the client
-            // will terminate the connection before the response is consumed).
+            // Do *not* enable H2 here, as it will cause an error (the
+            // client will terminate the connection before the response is
+            // consumed).
             // https://github.com/nodejs/undici/issues/3671
             connect: {
               keepAlive: false, // Client will be used once