@atproto-labs/fetch-node 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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
+
+- [#3821](https://github.com/bluesky-social/atproto/pull/3821) [`5050b6550`](https://github.com/bluesky-social/atproto/commit/5050b6550e07e71b0a524eda0b71b837583294d4) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Allow explicit `follow` mode in safe fetch wrap.
+
+- [#3819](https://github.com/bluesky-social/atproto/pull/3819) [`36dbd4155`](https://github.com/bluesky-social/atproto/commit/36dbd41551f74052a3f584719a1a7edd86eca201) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix potential memory leak
+
+- [#3821](https://github.com/bluesky-social/atproto/pull/3821) [`5050b6550`](https://github.com/bluesky-social/atproto/commit/5050b6550e07e71b0a524eda0b71b837583294d4) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Allow disabling the need for an explicit `redirect` mode
+
+- [#3818](https://github.com/bluesky-social/atproto/pull/3818) [`43861a452`](https://github.com/bluesky-social/atproto/commit/43861a452b70268e738ef12033297cddacbe25d4) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Remove dependency on the Public Suffix List
+
+- Updated dependencies [[`5050b6550`](https://github.com/bluesky-social/atproto/commit/5050b6550e07e71b0a524eda0b71b837583294d4), [`5050b6550`](https://github.com/bluesky-social/atproto/commit/5050b6550e07e71b0a524eda0b71b837583294d4)]:
+  - @atproto-labs/pipe@0.1.1
+  - @atproto-labs/fetch@0.2.3
+
 ## 0.1.8
 
 ### Patch Changes

package/LICENSE.txt

@@ -1,6 +1,6 @@
 Dual MIT/Apache-2.0 License
 
-Copyright (c) 2022-2025 Bluesky PBC, and Contributors
+Copyright (c) 2022-2025 Bluesky Social PBC, and Contributors
 
 Except as otherwise noted in individual files, this software is licensed under the MIT license (<http://opensource.org/licenses/MIT>), or the Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>).
 

package/dist/safe.d.ts

@@ -1,22 +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}
+ *
+ * @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 declare function safeFetchWrap({ fetch, responseMaxSize, // 512kB
-ssrfProtection, allowCustomPort, allowData, allowHttp, allowIpHost, allowPrivateIps, timeout, forbiddenDomainNames, }?: {
-    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;
-}): Fetch<unknown>;
+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,EASN,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,GAC1E;;;;;;;;;;;CAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAsDtB"}
+{"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,14 +9,27 @@ 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}
+ *
+ * @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).
  */
-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, } = {}) {
-    return (0, fetch_1.toRequestTransformer)((0, pipe_1.pipe)(
+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)(
     /**
-     * Disable HTTP redirects
+     * Require explicit {@link RequestInit['redirect']} mode
      */
-    (0, fetch_1.redirectCheckRequestTransform)(), 
+    allowImplicitRedirect ? fetch_1.asRequest : (0, fetch_1.explicitRedirectCheckRequestTransform)(), 
     /**
      * Only requests that will be issued with a "Host" header are allowed.
      */
@@ -48,11 +61,13 @@ ssrfProtection = true, allowCustomPort = !ssrfProtection, allowData = false, all
      * 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.
      */
-    (0, fetch_1.fetchMaxSizeProcessor)(responseMaxSize)));
+    (0, fetch_1.fetchMaxSizeProcessor)(responseMaxSize));
 }
 //# sourceMappingURL=safe.js.map

package/dist/safe.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe.js","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":";;AAyBA,sCAiEC;AA1FD,+CAW4B;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,MACvE,EAAE;IACJ,OAAO,IAAA,4BAAoB,EACzB,IAAA,WAAI;IACF;;OAEG;IACH,IAAA,qCAA6B,GAAE;IAE/B;;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,CACvC,CACF,CAAA;AACH,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,12 +1,46 @@
 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
+ * @returns whether the hostname is a name typically used for on locale area networks.
+ * @note **DO NOT** use for security reasons. Only as heuristic.
+ */
+export declare function isLocalHostname(hostname: string): boolean;
 //# sourceMappingURL=unicast.d.ts.map

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;AAIzC,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,CA+HpC;AAED,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,GAAG,CAAC,aAAa,EAC1B,QAAQ,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,QA0BxC"}
+{"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

@@ -5,29 +5,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unicastFetchWrap = unicastFetchWrap;
 exports.unicastLookup = unicastLookup;
+exports.isLocalHostname = isLocalHostname;
 const node_dns_1 = __importDefault(require("node:dns"));
 const ipaddr_js_1 = __importDefault(require("ipaddr.js"));
-const psl_1 = require("psl");
 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
@@ -77,15 +79,31 @@ function unicastFetchWrap({ fetch = globalThis.fetch, }) {
                             },
                         },
                     });
-                    const headers = new Headers(init?.headers);
-                    headers.set('connection', 'close'); // Proactively close the connection
                     try {
-                        return await fetch.call(this, input, {
+                        const headers = new Headers(init?.headers);
+                        headers.set('connection', 'close'); // Proactively close the connection
+                        const response = await fetch.call(this, input, {
                             ...init,
                             headers,
                             // @ts-expect-error non-standard option
                             dispatcher,
                         });
+                        if (!didLookup) {
+                            // We need to ensure that the body is discarded. We can either
+                            // consume the whole body (for await loop) in order to keep the
+                            // socket alive, or cancel the request. Since we sent "connection:
+                            // close", there is no point in consuming the whole response
+                            // (which would cause un-necessary bandwidth).
+                            //
+                            // https://undici.nodejs.org/#/?id=garbage-collection
+                            await response.body?.cancel();
+                            // If you encounter this error, either upgrade to Node.js >=21 or
+                            // make sure that the dispatcher passed through the requestInit
+                            // object ends up being used to make the request.
+                            // eslint-disable-next-line no-unsafe-finally
+                            throw new fetch_1.FetchRequestError((0, fetch_1.asRequest)(input, init), 500, 'Unable to enforce SSRF protection');
+                        }
+                        return response;
                     }
                     finally {
                         // Free resources (we cannot await here since the response was not
@@ -94,13 +112,6 @@ function unicastFetchWrap({ fetch = globalThis.fetch, }) {
                             // No biggie, but let's still log it
                             console.warn('Failed to close dispatcher', err);
                         });
-                        if (!didLookup) {
-                            // If you encounter this error, either upgrade to Node.js >=21 or
-                            // make sure that the dispatcher passed through the requestInit
-                            // object ends up being used to make the request.
-                            // eslint-disable-next-line no-unsafe-finally
-                            throw new fetch_1.FetchRequestError((0, fetch_1.asRequest)(input, init), 500, 'Unable to enforce SSRF protection');
-                        }
                     }
                 }
             }
@@ -108,8 +119,8 @@ function unicastFetchWrap({ fetch = globalThis.fetch, }) {
     }
 }
 function unicastLookup(hostname, options, callback) {
-    if (!isValidDomain(hostname)) {
-        callback(new Error('Hostname is not a public domain'), '');
+    if (isLocalHostname(hostname)) {
+        callback(new Error('Hostname is not a public domain'), []);
         return;
     }
     node_dns_1.default.lookup(hostname, options, (err, address, family) => {
@@ -129,12 +140,21 @@ function unicastLookup(hostname, options, callback) {
         }
     });
 }
-// see lupomontero/psl#258 for context on psl usage.
-// in short, this ensures a structurally valid domain
-// plus a "listed" tld.
-function isValidDomain(domain) {
-    const parsed = (0, psl_1.parse)(domain);
-    return !parsed.error && parsed.listed;
+/**
+ * @param hostname - a syntactically valid hostname
+ * @returns whether the hostname is a name typically used for on locale area networks.
+ * @note **DO NOT** use for security reasons. Only as heuristic.
+ */
+function isLocalHostname(hostname) {
+    const parts = hostname.split('.');
+    if (parts.length < 2)
+        return true;
+    const tld = parts.at(-1).toLowerCase();
+    return (tld === 'test' ||
+        tld === 'local' ||
+        tld === 'localhost' ||
+        tld === 'invalid' ||
+        tld === 'example');
 }
 function isNotUnicast(ip) {
     return ip.range() !== 'unicast';

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.8",
+  "version": "0.1.10",
   "license": "MIT",
   "description": "SSRF protection for fetch() in Node.js",
   "keywords": [
@@ -28,13 +28,11 @@
   },
   "dependencies": {
     "ipaddr.js": "^2.1.0",
-    "psl": "^1.9.0",
     "undici": "^6.14.1",
-    "@atproto-labs/fetch": "0.2.2",
-    "@atproto-labs/pipe": "0.1.0"
+    "@atproto-labs/fetch": "0.2.3",
+    "@atproto-labs/pipe": "0.1.1"
   },
   "devDependencies": {
-    "@types/psl": "1.1.3",
     "typescript": "^5.6.3"
   },
   "scripts": {

package/src/safe.ts

@@ -2,29 +2,57 @@ import {
   DEFAULT_FORBIDDEN_DOMAIN_NAMES,
   Fetch,
   asRequest,
+  explicitRedirectCheckRequestTransform,
   fetchMaxSizeProcessor,
   forbiddenDomainNameRequestTransform,
   protocolCheckRequestTransform,
-  redirectCheckRequestTransform,
   requireHostHeaderTransform,
   timedFetch,
-  toRequestTransformer,
 } 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,
@@ -34,58 +62,59 @@ export function safeFetchWrap({
   allowPrivateIps = !ssrfProtection,
   timeout = 10e3,
   forbiddenDomainNames = DEFAULT_FORBIDDEN_DOMAIN_NAMES as Iterable<string>,
-} = {}): Fetch<unknown> {
-  return toRequestTransformer(
-    pipe(
-      /**
-       * Disable HTTP redirects
-       */
-      redirectCheckRequestTransform(),
+  allowImplicitRedirect = false,
+}: SafeFetchWrapOptions<C> = {}) {
+  return pipe(
+    /**
+     * Require explicit {@link RequestInit['redirect']} mode
+     */
+    allowImplicitRedirect ? asRequest : explicitRedirectCheckRequestTransform(),
 
-      /**
-       * Only requests that will be issued with a "Host" header are allowed.
-       */
-      allowIpHost ? asRequest : requireHostHeaderTransform(),
-
-      /**
-       * Prevent using http:, file: or data: protocols.
-       */
-      protocolCheckRequestTransform({
-        'about:': false,
-        'data:': allowData,
-        'file:': false,
-        'http:': allowHttp && { allowCustomPort },
-        'https:': { allowCustomPort },
-      }),
+    /**
+     * Only requests that will be issued with a "Host" header are allowed.
+     */
+    allowIpHost ? asRequest : requireHostHeaderTransform(),
 
-      /**
-       * Disallow fetching from domains we know are not atproto/OIDC client
-       * implementation. Note that other domains can be blocked by providing a
-       * custom fetch function combined with another
-       * forbiddenDomainNameRequestTransform.
-       */
-      forbiddenDomainNameRequestTransform(forbiddenDomainNames),
+    /**
+     * Prevent using http:, file: or data: protocols.
+     */
+    protocolCheckRequestTransform({
+      'about:': false,
+      'data:': allowData,
+      'file:': false,
+      'http:': allowHttp && { allowCustomPort },
+      'https:': { allowCustomPort },
+    }),
 
-      /**
-       * Since we will be fetching from the network based on user provided
-       * input, let's mitigate resource exhaustion attacks by setting a timeout.
-       */
-      timedFetch(
-        timeout,
+    /**
+     * Disallow fetching from domains we know are not atproto/OIDC client
+     * implementation. Note that other domains can be blocked by providing a
+     * custom fetch function combined with another
+     * forbiddenDomainNameRequestTransform.
+     */
+    forbiddenDomainNameRequestTransform(forbiddenDomainNames),
 
-        /**
-         * Since we will be fetching from the network based on user provided
-         * input, we need to make sure that the request is not vulnerable to SSRF
-         * attacks.
-         */
-        allowPrivateIps ? fetch : unicastFetchWrap({ fetch }),
-      ),
+    /**
+     * Since we will be fetching from the network based on user provided
+     * input, let's mitigate resource exhaustion attacks by setting a timeout.
+     */
+    timedFetch(
+      timeout,
 
       /**
-       * 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.
+       * Since we will be fetching from the network based on user provided
+       * input, we need to make sure that the request is not vulnerable to SSRF
+       * attacks.
        */
-      fetchMaxSizeProcessor(responseMaxSize),
+      allowPrivateIps
+        ? fetch
+        : 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.
+     */
+    fetchMaxSizeProcessor(responseMaxSize),
+  ) satisfies Fetch<unknown>
 }

package/src/unicast.ts

@@ -1,7 +1,6 @@
 import dns, { LookupAddress } from 'node:dns'
 import { LookupFunction } from 'node:net'
 import ipaddr from 'ipaddr.js'
-import { parse as pslParse } from 'psl'
 import { Agent, Client } from 'undici'
 import {
   Fetch,
@@ -14,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 },
     })
@@ -63,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> {
@@ -97,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
@@ -115,25 +145,27 @@ export function unicastFetchWrap<C = FetchContext>({
             },
           })
 
-          const headers = new Headers(init?.headers)
-          headers.set('connection', 'close') // Proactively close the connection
-
           try {
-            return await fetch.call(this, input, {
+            const headers = new Headers(init?.headers)
+            headers.set('connection', 'close') // Proactively close the connection
+
+            const response = await fetch.call(this, input, {
               ...init,
               headers,
               // @ts-expect-error non-standard option
               dispatcher,
             })
-          } finally {
-            // Free resources (we cannot await here since the response was not
-            // consumed yet).
-            void dispatcher.close().catch((err) => {
-              // No biggie, but let's still log it
-              console.warn('Failed to close dispatcher', err)
-            })
 
             if (!didLookup) {
+              // We need to ensure that the body is discarded. We can either
+              // consume the whole body (for await loop) in order to keep the
+              // socket alive, or cancel the request. Since we sent "connection:
+              // close", there is no point in consuming the whole response
+              // (which would cause un-necessary bandwidth).
+              //
+              // https://undici.nodejs.org/#/?id=garbage-collection
+              await response.body?.cancel()
+
               // If you encounter this error, either upgrade to Node.js >=21 or
               // make sure that the dispatcher passed through the requestInit
               // object ends up being used to make the request.
@@ -145,6 +177,15 @@ export function unicastFetchWrap<C = FetchContext>({
                 'Unable to enforce SSRF protection',
               )
             }
+
+            return response
+          } finally {
+            // Free resources (we cannot await here since the response was not
+            // consumed yet).
+            void dispatcher.close().catch((err) => {
+              // No biggie, but let's still log it
+              console.warn('Failed to close dispatcher', err)
+            })
           }
         }
       }
@@ -157,8 +198,8 @@ export function unicastLookup(
   options: dns.LookupOptions,
   callback: Parameters<LookupFunction>[2],
 ) {
-  if (!isValidDomain(hostname)) {
-    callback(new Error('Hostname is not a public domain'), '')
+  if (isLocalHostname(hostname)) {
+    callback(new Error('Hostname is not a public domain'), [])
     return
   }
 
@@ -183,12 +224,23 @@ export function unicastLookup(
   })
 }
 
-// see lupomontero/psl#258 for context on psl usage.
-// in short, this ensures a structurally valid domain
-// plus a "listed" tld.
-function isValidDomain(domain: string) {
-  const parsed = pslParse(domain)
-  return !parsed.error && parsed.listed
+/**
+ * @param hostname - a syntactically valid hostname
+ * @returns whether the hostname is a name typically used for on locale area networks.
+ * @note **DO NOT** use for security reasons. Only as heuristic.
+ */
+export function isLocalHostname(hostname: string): boolean {
+  const parts = hostname.split('.')
+  if (parts.length < 2) return true
+
+  const tld = parts.at(-1)!.toLowerCase()
+  return (
+    tld === 'test' ||
+    tld === 'local' ||
+    tld === 'localhost' ||
+    tld === 'invalid' ||
+    tld === 'example'
+  )
 }
 
 function isNotUnicast(ip: ipaddr.IPv4 | ipaddr.IPv6): boolean {

package/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/index.ts","./src/safe.ts","./src/unicast.ts","./src/util.ts"],"version":"5.6.3"}
+{"root":["./src/index.ts","./src/safe.ts","./src/unicast.ts","./src/util.ts"],"version":"5.8.2"}