@fgv/ts-extras 5.1.0-45 → 5.1.0-47

package/lib/packlets/safer-fetch/failureReason.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Which deadline a {@link SaferFetch.FetchFailureReason | timeout failure} belongs to.
+ *
+ * - `'headers'`: the per-attempt headers deadline elapsed before the server sent
+ *   response headers — the host is not answering.
+ * - `'body'`: the overall deadline elapsed while the response body was being read
+ *   — the host answered and then trickled (the slowloris shape).
+ * - `'overall'`: the overall deadline elapsed before response headers arrived.
+ * @public
+ */
+export type FetchTimeoutPhase = 'headers' | 'body' | 'overall';
+/**
+ * Machine-readable reason a safer-fetch call failed, carried as the detail of the
+ * `DetailedResult` every entry point returns.
+ *
+ * @remarks
+ * **This value is an internal-network scanning oracle. Do not echo it, or any string
+ * derived from it, to an untrusted caller.** A `'blocked-by-guard'` detail names the
+ * URL, the hop, and the guard that rejected it; an attacker who can influence the
+ * request URL and observe the error learns whether an internal host exists. Log the
+ * detail; return a coarse code (the `kind` alone, or a generic message) to callers.
+ *
+ * Following the `AiAssist.JsonParseFailureReason` precedent in this package: a `kind`
+ * discriminant with per-kind payload fields, and `'unknown'` as an honest catch-all
+ * rather than a guess.
+ * @public
+ */
+export type FetchFailureReason = 
+/** The supplied URL could not be parsed, or its scheme is not `http:` or `https:`. */
+{
+    readonly kind: 'invalid-url';
+    readonly url: string;
+    readonly detail: string;
+}
+/**
+ * A guard refused. `hop` is 0-based; hop 0 is the caller's URL, and `guard` names which
+ * guard rejected — which is what makes "did the address check run, and was it the thing that
+ * said no?" answerable from the failure alone. A content-type rejection is reported as
+ * `'unsupported-content-type'` instead, because that case carries a more useful payload.
+ */
+ | {
+    readonly kind: 'blocked-by-guard';
+    readonly url: string;
+    readonly hop: number;
+    readonly guard: string;
+    readonly detail: string;
+}
+/**
+ * A redirect status was received that this call would not follow: the policy is `'reject'`,
+ * or the response carried no usable `Location`, or following it would revisit a URL already
+ * in the chain.
+ *
+ * @remarks
+ * The three are deliberately one kind. Splitting them would buy a caller almost nothing and
+ * would widen the scanning oracle this taxonomy already is — and the two follow-time cases
+ * are facts about the chain the redirecting server produced, not about the network behind
+ * this process. "The chain got too long" is a different question and stays
+ * `'too-many-redirects'`.
+ *
+ * `url` is always the URL that **issued** the rejected redirect — the hop this call actually
+ * requested and got a 3xx back from — never the `Location` target it pointed at. That holds
+ * for all three cases, including the revisit case, where the target is the URL already in the
+ * chain and naming it here would make the same field mean two different things. The target is
+ * named in the message instead. `status` is the redirect status that was received.
+ */
+ | {
+    readonly kind: 'redirect-rejected';
+    readonly url: string;
+    readonly status: number;
+}
+/**
+ * The platform returned an opaque redirect, whose `Location` is not readable. This is
+ * what a browser yields for `redirect: 'manual'`; the hop cannot be inspected at all.
+ */
+ | {
+    readonly kind: 'redirect-opaque';
+}
+/** The redirect hop budget was exhausted. */
+ | {
+    readonly kind: 'too-many-redirects';
+    readonly hops: number;
+    readonly limit: number;
+}
+/** One of the deadlines elapsed. Distinct from `'aborted'`, which is the caller's signal. */
+ | {
+    readonly kind: 'timeout';
+    readonly phase: FetchTimeoutPhase;
+    readonly elapsedMs: number;
+    readonly limitMs: number;
+}
+/** The caller's `AbortSignal` fired. Distinct from `'timeout'`, which is our deadline. */
+ | {
+    readonly kind: 'aborted';
+}
+/** The transport could not complete the request. */
+ | {
+    readonly kind: 'network';
+    readonly detail: string;
+}
+/**
+ * A non-2xx response. `bodyPreview` is **never populated in this release** — error bodies
+ * routinely echo request content, including credentials, so surfacing one has to be an
+ * explicit, length-capped opt-in rather than a default. The field is declared so that adding
+ * that opt-in later is additive.
+ */
+ | {
+    readonly kind: 'http-status';
+    readonly status: number;
+    readonly statusText: string;
+    readonly bodyPreview?: string;
+}
+/**
+ * The response exceeded the byte cap. `declared` is what `Content-Length` claimed, present
+ * only when the header was sent — and it counts *encoded* bytes where `bytesRead` counts
+ * *decoded* bytes, so a `declared` far below `bytesRead` is evidence of a compression bomb
+ * or a lying server rather than an arithmetic error.
+ */
+ | {
+    readonly kind: 'too-large';
+    readonly bytesRead: number;
+    readonly limit: number;
+    readonly declared?: number;
+}
+/** A response-headers guard rejected the response's content type. */
+ | {
+    readonly kind: 'unsupported-content-type';
+    readonly contentType?: string;
+    readonly accepted: ReadonlyArray<string>;
+}
+/** The response bytes could not be decoded to text with the indicated charset. */
+ | {
+    readonly kind: 'decode';
+    readonly detail: string;
+}
+/** The decoded text could not be parsed, or failed the caller's converter. */
+ | {
+    readonly kind: 'parse';
+    readonly detail: string;
+}
+/**
+ * Anything else — including invalid options and a guard or transport that violated its
+ * contract. Reports what it knows rather than guessing at a more specific kind.
+ */
+ | {
+    readonly kind: 'unknown';
+    readonly detail: string;
+};
+//# sourceMappingURL=failureReason.d.ts.map

package/lib/packlets/safer-fetch/failureReason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureReason.d.ts","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/failureReason.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,kBAAkB;AAC5B,sFAAsF;AACpF;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACjF;;;;;GAKG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACH;;;;;;;;;;;;;;;;;GAiBG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACvF;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE;AACtC,6CAA6C;GAC3C;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACxF,6FAA6F;GAC3F;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AACH,0FAA0F;GACxF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,oDAAoD;GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACvD;;;;;GAKG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AACH;;;;;GAKG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AACH,qEAAqE;GACnE;IACE,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1C;AACH,kFAAkF;GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACtD,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACrD;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/lib/packlets/safer-fetch/failureReason.js

@@ -0,0 +1,22 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=failureReason.js.map

package/lib/packlets/safer-fetch/failureReason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failureReason.js","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/failureReason.ts"],"names":[],"mappings":";AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Which deadline a {@link SaferFetch.FetchFailureReason | timeout failure} belongs to.\n *\n * - `'headers'`: the per-attempt headers deadline elapsed before the server sent\n *   response headers — the host is not answering.\n * - `'body'`: the overall deadline elapsed while the response body was being read\n *   — the host answered and then trickled (the slowloris shape).\n * - `'overall'`: the overall deadline elapsed before response headers arrived.\n * @public\n */\nexport type FetchTimeoutPhase = 'headers' | 'body' | 'overall';\n\n/**\n * Machine-readable reason a safer-fetch call failed, carried as the detail of the\n * `DetailedResult` every entry point returns.\n *\n * @remarks\n * **This value is an internal-network scanning oracle. Do not echo it, or any string\n * derived from it, to an untrusted caller.** A `'blocked-by-guard'` detail names the\n * URL, the hop, and the guard that rejected it; an attacker who can influence the\n * request URL and observe the error learns whether an internal host exists. Log the\n * detail; return a coarse code (the `kind` alone, or a generic message) to callers.\n *\n * Following the `AiAssist.JsonParseFailureReason` precedent in this package: a `kind`\n * discriminant with per-kind payload fields, and `'unknown'` as an honest catch-all\n * rather than a guess.\n * @public\n */\nexport type FetchFailureReason =\n  /** The supplied URL could not be parsed, or its scheme is not `http:` or `https:`. */\n  | { readonly kind: 'invalid-url'; readonly url: string; readonly detail: string }\n  /**\n   * A guard refused. `hop` is 0-based; hop 0 is the caller's URL, and `guard` names which\n   * guard rejected — which is what makes \"did the address check run, and was it the thing that\n   * said no?\" answerable from the failure alone. A content-type rejection is reported as\n   * `'unsupported-content-type'` instead, because that case carries a more useful payload.\n   */\n  | {\n      readonly kind: 'blocked-by-guard';\n      readonly url: string;\n      readonly hop: number;\n      readonly guard: string;\n      readonly detail: string;\n    }\n  /**\n   * A redirect status was received that this call would not follow: the policy is `'reject'`,\n   * or the response carried no usable `Location`, or following it would revisit a URL already\n   * in the chain.\n   *\n   * @remarks\n   * The three are deliberately one kind. Splitting them would buy a caller almost nothing and\n   * would widen the scanning oracle this taxonomy already is — and the two follow-time cases\n   * are facts about the chain the redirecting server produced, not about the network behind\n   * this process. \"The chain got too long\" is a different question and stays\n   * `'too-many-redirects'`.\n   *\n   * `url` is always the URL that **issued** the rejected redirect — the hop this call actually\n   * requested and got a 3xx back from — never the `Location` target it pointed at. That holds\n   * for all three cases, including the revisit case, where the target is the URL already in the\n   * chain and naming it here would make the same field mean two different things. The target is\n   * named in the message instead. `status` is the redirect status that was received.\n   */\n  | { readonly kind: 'redirect-rejected'; readonly url: string; readonly status: number }\n  /**\n   * The platform returned an opaque redirect, whose `Location` is not readable. This is\n   * what a browser yields for `redirect: 'manual'`; the hop cannot be inspected at all.\n   */\n  | { readonly kind: 'redirect-opaque' }\n  /** The redirect hop budget was exhausted. */\n  | { readonly kind: 'too-many-redirects'; readonly hops: number; readonly limit: number }\n  /** One of the deadlines elapsed. Distinct from `'aborted'`, which is the caller's signal. */\n  | {\n      readonly kind: 'timeout';\n      readonly phase: FetchTimeoutPhase;\n      readonly elapsedMs: number;\n      readonly limitMs: number;\n    }\n  /** The caller's `AbortSignal` fired. Distinct from `'timeout'`, which is our deadline. */\n  | { readonly kind: 'aborted' }\n  /** The transport could not complete the request. */\n  | { readonly kind: 'network'; readonly detail: string }\n  /**\n   * A non-2xx response. `bodyPreview` is **never populated in this release** — error bodies\n   * routinely echo request content, including credentials, so surfacing one has to be an\n   * explicit, length-capped opt-in rather than a default. The field is declared so that adding\n   * that opt-in later is additive.\n   */\n  | {\n      readonly kind: 'http-status';\n      readonly status: number;\n      readonly statusText: string;\n      readonly bodyPreview?: string;\n    }\n  /**\n   * The response exceeded the byte cap. `declared` is what `Content-Length` claimed, present\n   * only when the header was sent — and it counts *encoded* bytes where `bytesRead` counts\n   * *decoded* bytes, so a `declared` far below `bytesRead` is evidence of a compression bomb\n   * or a lying server rather than an arithmetic error.\n   */\n  | {\n      readonly kind: 'too-large';\n      readonly bytesRead: number;\n      readonly limit: number;\n      readonly declared?: number;\n    }\n  /** A response-headers guard rejected the response's content type. */\n  | {\n      readonly kind: 'unsupported-content-type';\n      readonly contentType?: string;\n      readonly accepted: ReadonlyArray<string>;\n    }\n  /** The response bytes could not be decoded to text with the indicated charset. */\n  | { readonly kind: 'decode'; readonly detail: string }\n  /** The decoded text could not be parsed, or failed the caller's converter. */\n  | { readonly kind: 'parse'; readonly detail: string }\n  /**\n   * Anything else — including invalid options and a guard or transport that violated its\n   * contract. Reports what it knows rather than guessing at a more specific kind.\n   */\n  | { readonly kind: 'unknown'; readonly detail: string };\n"]}

package/lib/packlets/safer-fetch/guards.d.ts

@@ -0,0 +1,62 @@
+import { Result } from '@fgv/ts-utils';
+import type { IAddressGuard, IResolvedGuards, IResponseHeadersGuard, ISaferFetchOptions } from './model';
+/**
+ * An address guard that permits every address.
+ *
+ * @remarks
+ * **This is the absence of the SSRF guarantee, given a name.** It performs no address
+ * classification, no DNS resolution, and no scheme or port narrowing beyond the core's
+ * refusal of non-`http(s)` schemes. A call site using it is reachable at any address the
+ * process can route to, including cloud metadata endpoints, loopback admin ports, and
+ * RFC-1918 hosts.
+ *
+ * It ships anyway, for two reasons. It is the honest and only possible choice in a browser,
+ * where neither DNS resolution nor redirect interposition exists. And omitting it would not
+ * make anyone safer — it would make consumers hand-roll something worse. It is deliberately
+ * named to be uncomfortable in review and to grep as a distinct posture.
+ *
+ * This is the **guard-layer** factory: it returns an {@link SaferFetch.IAddressGuard}, which is
+ * what an entry point's `addressGuard` option takes. A pure address *policy* — the synchronous,
+ * address-list-in classifier a resolving guard delegates to — is a different layer and needs a
+ * distinct name.
+ * @public
+ */
+export declare function allowAnyAddress(): IAddressGuard;
+/**
+ * A response-headers guard that accepts only the listed media types.
+ *
+ * @remarks
+ * Rejecting on `Content-Type` is strictly cheaper than capping mid-read — a header comparison
+ * instead of a partial body transfer — so a consumer ingesting URLs wants it on every call. It
+ * is also what keeps an HTML error page served with a `200` from being parsed as JSON twenty
+ * frames away from where it went wrong.
+ *
+ * Entries are media types, optionally with a wildcard subtype (`text/*`); a wildcard type
+ * requires a wildcard subtype. Matching is case-insensitive and ignores parameters, so
+ * `text/html` accepts `text/html; charset=utf-8`. A response with **no** `Content-Type` is
+ * rejected: an untyped response has not satisfied a content-type allowlist.
+ *
+ * Construction is fallible because a malformed entry in a security-adjacent allowlist must be
+ * reported to its author rather than silently compiled into a pattern that never matches.
+ *
+ * @param types - Accepted media types. Must be non-empty.
+ * @public
+ */
+export declare function allowContentTypes(types: ReadonlyArray<string>): Result<IResponseHeadersGuard>;
+/**
+ * Resolves the guards a call will use, applying defaults once at the boundary so that no
+ * downstream code path branches on a guard's absence.
+ *
+ * @remarks
+ * Every optional guard resolves with `??`, uniformly. That uniformity is the point: a
+ * `!== undefined` test in one slot where its siblings use `??` lets a `null` — from a
+ * JavaScript caller, or through an `unknown` escape hatch — pass straight through and install
+ * itself as a guard, which is a real defect that has shipped in this repo before. A `null`
+ * guard here is treated as *absent*, never as *installed*.
+ *
+ * `addressGuard` has no default, so a `null` or missing value is a hard failure rather than a
+ * silent passthrough.
+ * @internal
+ */
+export declare function resolveGuards(options: ISaferFetchOptions): Result<IResolvedGuards>;
+//# sourceMappingURL=guards.d.ts.map

package/lib/packlets/safer-fetch/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/guards.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAoB,MAAM,EAAW,MAAM,eAAe,CAAC;AAGlE,OAAO,KAAK,EACV,aAAa,EAIb,eAAe,EAEf,qBAAqB,EACrB,kBAAkB,EAGnB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,IAAI,aAAa,CAa/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,qBAAqB,CAAC,CA6B7F;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAAC,eAAe,CAAC,CAclF"}

package/lib/packlets/safer-fetch/guards.js

@@ -0,0 +1,153 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allowAnyAddress = allowAnyAddress;
+exports.allowContentTypes = allowContentTypes;
+exports.resolveGuards = resolveGuards;
+const ts_utils_1 = require("@fgv/ts-utils");
+const contentType_1 = require("./contentType");
+/**
+ * An address guard that permits every address.
+ *
+ * @remarks
+ * **This is the absence of the SSRF guarantee, given a name.** It performs no address
+ * classification, no DNS resolution, and no scheme or port narrowing beyond the core's
+ * refusal of non-`http(s)` schemes. A call site using it is reachable at any address the
+ * process can route to, including cloud metadata endpoints, loopback admin ports, and
+ * RFC-1918 hosts.
+ *
+ * It ships anyway, for two reasons. It is the honest and only possible choice in a browser,
+ * where neither DNS resolution nor redirect interposition exists. And omitting it would not
+ * make anyone safer — it would make consumers hand-roll something worse. It is deliberately
+ * named to be uncomfortable in review and to grep as a distinct posture.
+ *
+ * This is the **guard-layer** factory: it returns an {@link SaferFetch.IAddressGuard}, which is
+ * what an entry point's `addressGuard` option takes. A pure address *policy* — the synchronous,
+ * address-list-in classifier a resolving guard delegates to — is a different layer and needs a
+ * distinct name.
+ * @public
+ */
+function allowAnyAddress() {
+    return {
+        name: 'allowAnyAddress',
+        check: async (chain) => {
+            var _a;
+            const hop = (_a = chain[chain.length - 1]) !== null && _a !== void 0 ? _a : undefined;
+            if (hop === undefined) {
+                return (0, ts_utils_1.fail)('allowAnyAddress: hop chain is empty.');
+            }
+            // pinnedAddress is deliberately left undefined: this guard validates nothing, so it has
+            // no address to pin, and a transport must never be told otherwise.
+            return (0, ts_utils_1.succeed)({ url: hop.url });
+        }
+    };
+}
+/**
+ * A response-headers guard that accepts only the listed media types.
+ *
+ * @remarks
+ * Rejecting on `Content-Type` is strictly cheaper than capping mid-read — a header comparison
+ * instead of a partial body transfer — so a consumer ingesting URLs wants it on every call. It
+ * is also what keeps an HTML error page served with a `200` from being parsed as JSON twenty
+ * frames away from where it went wrong.
+ *
+ * Entries are media types, optionally with a wildcard subtype (`text/*`); a wildcard type
+ * requires a wildcard subtype. Matching is case-insensitive and ignores parameters, so
+ * `text/html` accepts `text/html; charset=utf-8`. A response with **no** `Content-Type` is
+ * rejected: an untyped response has not satisfied a content-type allowlist.
+ *
+ * Construction is fallible because a malformed entry in a security-adjacent allowlist must be
+ * reported to its author rather than silently compiled into a pattern that never matches.
+ *
+ * @param types - Accepted media types. Must be non-empty.
+ * @public
+ */
+function allowContentTypes(types) {
+    if (types.length === 0) {
+        return (0, ts_utils_1.fail)('allowContentTypes: at least one media type is required.');
+    }
+    return (0, ts_utils_1.mapResults)(types.map((t) => (0, contentType_1.parseMediaTypePattern)(t)))
+        .withErrorFormat((message) => `allowContentTypes: ${message}`)
+        .onSuccess((patterns) => {
+        const accepted = patterns.map((p) => `${p.type}/${p.subtype}`);
+        return (0, ts_utils_1.succeed)({
+            name: 'allowContentTypes',
+            acceptedContentTypes: accepted,
+            check: async (head) => {
+                var _a;
+                const contentType = (_a = head.contentType) !== null && _a !== void 0 ? _a : undefined;
+                if (contentType === undefined) {
+                    return (0, ts_utils_1.fail)(`response has no content-type; expected one of [${accepted.join(', ')}].`);
+                }
+                return (0, contentType_1.parseMediaType)(contentType)
+                    .withErrorFormat((message) => `content-type ${message}`)
+                    .onSuccess((actual) => {
+                    if (patterns.some((p) => (0, contentType_1.mediaTypeMatches)(actual, p))) {
+                        return (0, ts_utils_1.succeed)(true);
+                    }
+                    return (0, ts_utils_1.fail)(`content-type "${contentType}" is not accepted; expected one of [${accepted.join(', ')}].`);
+                });
+            }
+        });
+    });
+}
+const passthroughRequestGuard = {
+    name: 'passthrough',
+    check: async (request) => (0, ts_utils_1.succeed)(request)
+};
+const passthroughResponseHeadersGuard = {
+    name: 'passthrough',
+    check: async () => (0, ts_utils_1.succeed)(true)
+};
+const passthroughResponseBodyGuard = {
+    name: 'passthrough',
+    check: async () => (0, ts_utils_1.succeed)(true)
+};
+/**
+ * Resolves the guards a call will use, applying defaults once at the boundary so that no
+ * downstream code path branches on a guard's absence.
+ *
+ * @remarks
+ * Every optional guard resolves with `??`, uniformly. That uniformity is the point: a
+ * `!== undefined` test in one slot where its siblings use `??` lets a `null` — from a
+ * JavaScript caller, or through an `unknown` escape hatch — pass straight through and install
+ * itself as a guard, which is a real defect that has shipped in this repo before. A `null`
+ * guard here is treated as *absent*, never as *installed*.
+ *
+ * `addressGuard` has no default, so a `null` or missing value is a hard failure rather than a
+ * silent passthrough.
+ * @internal
+ */
+function resolveGuards(options) {
+    var _a, _b, _c, _d;
+    const address = (_a = options.addressGuard) !== null && _a !== void 0 ? _a : undefined;
+    if (address === undefined) {
+        return (0, ts_utils_1.fail)('addressGuard is required and has no default. Supply a named factory — ' +
+            'allowAnyAddress() is the explicit opt-out.');
+    }
+    return (0, ts_utils_1.succeed)({
+        address,
+        request: (_b = options.requestGuard) !== null && _b !== void 0 ? _b : passthroughRequestGuard,
+        responseHeaders: (_c = options.responseHeadersGuard) !== null && _c !== void 0 ? _c : passthroughResponseHeadersGuard,
+        responseBody: (_d = options.responseBodyGuard) !== null && _d !== void 0 ? _d : passthroughResponseBodyGuard
+    });
+}
+//# sourceMappingURL=guards.js.map

package/lib/packlets/safer-fetch/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/guards.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\nimport { fail, mapResults, Result, succeed } from '@fgv/ts-utils';\n\nimport { IMediaType, mediaTypeMatches, parseMediaType, parseMediaTypePattern } from './contentType';\nimport type {\n  IAddressGuard,\n  IGuardVerdict,\n  IRequestGuard,\n  IRequestHop,\n  IResolvedGuards,\n  IResponseBodyGuard,\n  IResponseHeadersGuard,\n  ISaferFetchOptions,\n  ISaferFetchRequest,\n  ISaferFetchResponseHead\n} from './model';\n\n/**\n * An address guard that permits every address.\n *\n * @remarks\n * **This is the absence of the SSRF guarantee, given a name.** It performs no address\n * classification, no DNS resolution, and no scheme or port narrowing beyond the core's\n * refusal of non-`http(s)` schemes. A call site using it is reachable at any address the\n * process can route to, including cloud metadata endpoints, loopback admin ports, and\n * RFC-1918 hosts.\n *\n * It ships anyway, for two reasons. It is the honest and only possible choice in a browser,\n * where neither DNS resolution nor redirect interposition exists. And omitting it would not\n * make anyone safer — it would make consumers hand-roll something worse. It is deliberately\n * named to be uncomfortable in review and to grep as a distinct posture.\n *\n * This is the **guard-layer** factory: it returns an {@link SaferFetch.IAddressGuard}, which is\n * what an entry point's `addressGuard` option takes. A pure address *policy* — the synchronous,\n * address-list-in classifier a resolving guard delegates to — is a different layer and needs a\n * distinct name.\n * @public\n */\nexport function allowAnyAddress(): IAddressGuard {\n  return {\n    name: 'allowAnyAddress',\n    check: async (chain: ReadonlyArray<IRequestHop>): Promise<Result<IGuardVerdict>> => {\n      const hop = chain[chain.length - 1] ?? undefined;\n      if (hop === undefined) {\n        return fail('allowAnyAddress: hop chain is empty.');\n      }\n      // pinnedAddress is deliberately left undefined: this guard validates nothing, so it has\n      // no address to pin, and a transport must never be told otherwise.\n      return succeed({ url: hop.url });\n    }\n  };\n}\n\n/**\n * A response-headers guard that accepts only the listed media types.\n *\n * @remarks\n * Rejecting on `Content-Type` is strictly cheaper than capping mid-read — a header comparison\n * instead of a partial body transfer — so a consumer ingesting URLs wants it on every call. It\n * is also what keeps an HTML error page served with a `200` from being parsed as JSON twenty\n * frames away from where it went wrong.\n *\n * Entries are media types, optionally with a wildcard subtype (`text/*`); a wildcard type\n * requires a wildcard subtype. Matching is case-insensitive and ignores parameters, so\n * `text/html` accepts `text/html; charset=utf-8`. A response with **no** `Content-Type` is\n * rejected: an untyped response has not satisfied a content-type allowlist.\n *\n * Construction is fallible because a malformed entry in a security-adjacent allowlist must be\n * reported to its author rather than silently compiled into a pattern that never matches.\n *\n * @param types - Accepted media types. Must be non-empty.\n * @public\n */\nexport function allowContentTypes(types: ReadonlyArray<string>): Result<IResponseHeadersGuard> {\n  if (types.length === 0) {\n    return fail('allowContentTypes: at least one media type is required.');\n  }\n  return mapResults(types.map((t) => parseMediaTypePattern(t)))\n    .withErrorFormat((message) => `allowContentTypes: ${message}`)\n    .onSuccess((patterns: IMediaType[]) => {\n      const accepted: ReadonlyArray<string> = patterns.map((p) => `${p.type}/${p.subtype}`);\n      return succeed({\n        name: 'allowContentTypes',\n        acceptedContentTypes: accepted,\n        check: async (head: ISaferFetchResponseHead): Promise<Result<true>> => {\n          const contentType = head.contentType ?? undefined;\n          if (contentType === undefined) {\n            return fail(`response has no content-type; expected one of [${accepted.join(', ')}].`);\n          }\n          return parseMediaType(contentType)\n            .withErrorFormat((message) => `content-type ${message}`)\n            .onSuccess((actual) => {\n              if (patterns.some((p) => mediaTypeMatches(actual, p))) {\n                return succeed(true as const);\n              }\n              return fail(\n                `content-type \"${contentType}\" is not accepted; expected one of [${accepted.join(', ')}].`\n              );\n            });\n        }\n      });\n    });\n}\n\nconst passthroughRequestGuard: IRequestGuard = {\n  name: 'passthrough',\n  check: async (request: ISaferFetchRequest): Promise<Result<ISaferFetchRequest>> => succeed(request)\n};\n\nconst passthroughResponseHeadersGuard: IResponseHeadersGuard = {\n  name: 'passthrough',\n  check: async (): Promise<Result<true>> => succeed(true as const)\n};\n\nconst passthroughResponseBodyGuard: IResponseBodyGuard = {\n  name: 'passthrough',\n  check: async (): Promise<Result<true>> => succeed(true as const)\n};\n\n/**\n * Resolves the guards a call will use, applying defaults once at the boundary so that no\n * downstream code path branches on a guard's absence.\n *\n * @remarks\n * Every optional guard resolves with `??`, uniformly. That uniformity is the point: a\n * `!== undefined` test in one slot where its siblings use `??` lets a `null` — from a\n * JavaScript caller, or through an `unknown` escape hatch — pass straight through and install\n * itself as a guard, which is a real defect that has shipped in this repo before. A `null`\n * guard here is treated as *absent*, never as *installed*.\n *\n * `addressGuard` has no default, so a `null` or missing value is a hard failure rather than a\n * silent passthrough.\n * @internal\n */\nexport function resolveGuards(options: ISaferFetchOptions): Result<IResolvedGuards> {\n  const address = options.addressGuard ?? undefined;\n  if (address === undefined) {\n    return fail(\n      'addressGuard is required and has no default. Supply a named factory — ' +\n        'allowAnyAddress() is the explicit opt-out.'\n    );\n  }\n  return succeed({\n    address,\n    request: options.requestGuard ?? passthroughRequestGuard,\n    responseHeaders: options.responseHeadersGuard ?? passthroughResponseHeadersGuard,\n    responseBody: options.responseBodyGuard ?? passthroughResponseBodyGuard\n  });\n}\n"]}

package/lib/packlets/safer-fetch/index.browser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * An HTTP fetch primitive with an explicit threat model (browser version).
+ *
+ * This barrel deliberately omits `blockPrivateNetworks` and the resolver seam beneath it: that
+ * module imports `node:dns/promises`, and exporting it here would pull a Node builtin into a
+ * browser bundle.
+ *
+ * The address-classification layer — `classifyAddress`, and the pure synchronous policies
+ * `allowAnyAddressPolicy` / `blockPrivateNetworksPolicy` — **is** exported here: it is pure
+ * arithmetic over parsed octets, it works identically in a browser, and it is useful for a
+ * URL-zero check. It is not a substitute for the guard, and cannot be: it classifies an address
+ * a caller already holds, while what the browser lacks is any way to learn the address a
+ * hostname resolves to.
+ *
+ * Note: the resolved-address (private-IP) guard and per-hop redirect revalidation are NOT
+ * available in a browser, and not for want of implementation. There is no browser API that
+ * returns a hostname's A/AAAA records, nothing in `fetch` or `Response` exposes the peer
+ * address, and `redirect: 'manual'` yields an opaque response whose `Location` is not
+ * readable — a `'validate-each-hop'` call there fails as `'redirect-opaque'` rather than
+ * quietly following anything. `allowAnyAddress()` is the honest choice, and its name says so.
+ *
+ * @packageDocumentation
+ */
+export { ALWAYS_STRIPPED_HEADERS, DEFAULT_HEADERS_TIMEOUT_MS, DEFAULT_MAX_REDIRECTS, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_BASE_DELAY_MS, DEFAULT_RETRY_MAX_DELAY_MS, DEFAULT_TIMEOUT_MS, IDEMPOTENT_METHODS, REDIRECT_STATUSES, RETRY_AFTER_STATUSES, RETRYABLE_HTTP_STATUSES, SUPPORTED_SCHEMES } from './defaults';
+export type { FetchFailureReason, FetchTimeoutPhase } from './failureReason';
+export type { IRetryPolicy } from './retry';
+export type { IAddressGuard, IFetchTransport, IFetchTransportHints, IGuardVerdict, IRequestGuard, IRequestHop, IResolvedGuards, IResponseBodyGuard, IResponseHeadersGuard, ISaferFetchOptions, ISaferFetchRequest, ISaferFetchResponse, ISaferFetchResponseHead, SaferFetchMethod, SaferFetchRedirectPolicy } from './model';
+export { allowAnyAddress, allowContentTypes } from './guards';
+export { platformFetchTransport } from './transport';
+export { saferFetchBytes, saferFetchJson, saferFetchText, type ISaferFetchJsonOptions } from './saferFetch';
+export { allowAnyAddressPolicy, blockPrivateNetworksPolicy, type IAddressCheckVerdict, type IAddressPolicy, type IBlockPrivateNetworksOptions } from './addressPolicy';
+export { classifyAddress, type AddressClassification, type AddressFamily, type IClassifiedAddress, type IEmbeddedIpv4, type Ipv4EmbeddingKind } from './addressClassification';
+//# sourceMappingURL=index.browser.d.ts.map

package/lib/packlets/safer-fetch/index.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/index.browser.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,YAAY,EACV,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAW5G,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,4BAA4B,EAClC,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC"}

package/lib/packlets/safer-fetch/index.browser.js

@@ -0,0 +1,82 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyAddress = exports.blockPrivateNetworksPolicy = exports.allowAnyAddressPolicy = exports.saferFetchText = exports.saferFetchJson = exports.saferFetchBytes = exports.platformFetchTransport = exports.allowContentTypes = exports.allowAnyAddress = exports.SUPPORTED_SCHEMES = exports.RETRYABLE_HTTP_STATUSES = exports.RETRY_AFTER_STATUSES = exports.REDIRECT_STATUSES = exports.IDEMPOTENT_METHODS = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_RETRY_MAX_DELAY_MS = exports.DEFAULT_RETRY_BASE_DELAY_MS = exports.DEFAULT_MAX_RESPONSE_BYTES = exports.DEFAULT_MAX_REDIRECTS = exports.DEFAULT_HEADERS_TIMEOUT_MS = exports.ALWAYS_STRIPPED_HEADERS = void 0;
+/**
+ * An HTTP fetch primitive with an explicit threat model (browser version).
+ *
+ * This barrel deliberately omits `blockPrivateNetworks` and the resolver seam beneath it: that
+ * module imports `node:dns/promises`, and exporting it here would pull a Node builtin into a
+ * browser bundle.
+ *
+ * The address-classification layer — `classifyAddress`, and the pure synchronous policies
+ * `allowAnyAddressPolicy` / `blockPrivateNetworksPolicy` — **is** exported here: it is pure
+ * arithmetic over parsed octets, it works identically in a browser, and it is useful for a
+ * URL-zero check. It is not a substitute for the guard, and cannot be: it classifies an address
+ * a caller already holds, while what the browser lacks is any way to learn the address a
+ * hostname resolves to.
+ *
+ * Note: the resolved-address (private-IP) guard and per-hop redirect revalidation are NOT
+ * available in a browser, and not for want of implementation. There is no browser API that
+ * returns a hostname's A/AAAA records, nothing in `fetch` or `Response` exposes the peer
+ * address, and `redirect: 'manual'` yields an opaque response whose `Location` is not
+ * readable — a `'validate-each-hop'` call there fails as `'redirect-opaque'` rather than
+ * quietly following anything. `allowAnyAddress()` is the honest choice, and its name says so.
+ *
+ * @packageDocumentation
+ */
+var defaults_1 = require("./defaults");
+Object.defineProperty(exports, "ALWAYS_STRIPPED_HEADERS", { enumerable: true, get: function () { return defaults_1.ALWAYS_STRIPPED_HEADERS; } });
+Object.defineProperty(exports, "DEFAULT_HEADERS_TIMEOUT_MS", { enumerable: true, get: function () { return defaults_1.DEFAULT_HEADERS_TIMEOUT_MS; } });
+Object.defineProperty(exports, "DEFAULT_MAX_REDIRECTS", { enumerable: true, get: function () { return defaults_1.DEFAULT_MAX_REDIRECTS; } });
+Object.defineProperty(exports, "DEFAULT_MAX_RESPONSE_BYTES", { enumerable: true, get: function () { return defaults_1.DEFAULT_MAX_RESPONSE_BYTES; } });
+Object.defineProperty(exports, "DEFAULT_RETRY_BASE_DELAY_MS", { enumerable: true, get: function () { return defaults_1.DEFAULT_RETRY_BASE_DELAY_MS; } });
+Object.defineProperty(exports, "DEFAULT_RETRY_MAX_DELAY_MS", { enumerable: true, get: function () { return defaults_1.DEFAULT_RETRY_MAX_DELAY_MS; } });
+Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: function () { return defaults_1.DEFAULT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "IDEMPOTENT_METHODS", { enumerable: true, get: function () { return defaults_1.IDEMPOTENT_METHODS; } });
+Object.defineProperty(exports, "REDIRECT_STATUSES", { enumerable: true, get: function () { return defaults_1.REDIRECT_STATUSES; } });
+Object.defineProperty(exports, "RETRY_AFTER_STATUSES", { enumerable: true, get: function () { return defaults_1.RETRY_AFTER_STATUSES; } });
+Object.defineProperty(exports, "RETRYABLE_HTTP_STATUSES", { enumerable: true, get: function () { return defaults_1.RETRYABLE_HTTP_STATUSES; } });
+Object.defineProperty(exports, "SUPPORTED_SCHEMES", { enumerable: true, get: function () { return defaults_1.SUPPORTED_SCHEMES; } });
+var guards_1 = require("./guards");
+Object.defineProperty(exports, "allowAnyAddress", { enumerable: true, get: function () { return guards_1.allowAnyAddress; } });
+Object.defineProperty(exports, "allowContentTypes", { enumerable: true, get: function () { return guards_1.allowContentTypes; } });
+var transport_1 = require("./transport");
+Object.defineProperty(exports, "platformFetchTransport", { enumerable: true, get: function () { return transport_1.platformFetchTransport; } });
+var saferFetch_1 = require("./saferFetch");
+Object.defineProperty(exports, "saferFetchBytes", { enumerable: true, get: function () { return saferFetch_1.saferFetchBytes; } });
+Object.defineProperty(exports, "saferFetchJson", { enumerable: true, get: function () { return saferFetch_1.saferFetchJson; } });
+Object.defineProperty(exports, "saferFetchText", { enumerable: true, get: function () { return saferFetch_1.saferFetchText; } });
+// Runtime-agnostic and exported from both barrels: the address *classification* layer is pure
+// arithmetic over parsed octets with no I/O, so it works in a browser exactly as it does on
+// Node. It is useful there for a URL-zero check — a caller can refuse an IP-literal URL that
+// classifies as private before ever calling `fetch`.
+//
+// **It cannot substitute for the resolved-address guard.** It classifies an address you already
+// have; the guarantee the browser lacks is *obtaining* the address a hostname resolves to, which
+// no browser API provides. `https://internal.example.com/` resolving to `10.0.0.5` is invisible
+// to every function exported here.
+var addressPolicy_1 = require("./addressPolicy");
+Object.defineProperty(exports, "allowAnyAddressPolicy", { enumerable: true, get: function () { return addressPolicy_1.allowAnyAddressPolicy; } });
+Object.defineProperty(exports, "blockPrivateNetworksPolicy", { enumerable: true, get: function () { return addressPolicy_1.blockPrivateNetworksPolicy; } });
+var addressClassification_1 = require("./addressClassification");
+Object.defineProperty(exports, "classifyAddress", { enumerable: true, get: function () { return addressClassification_1.classifyAddress; } });
+//# sourceMappingURL=index.browser.js.map

package/lib/packlets/safer-fetch/index.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/index.browser.ts"],"names":[],"mappings":";AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;;;AAEZ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,uCAaoB;AAZlB,mHAAA,uBAAuB,OAAA;AACvB,sHAAA,0BAA0B,OAAA;AAC1B,iHAAA,qBAAqB,OAAA;AACrB,sHAAA,0BAA0B,OAAA;AAC1B,uHAAA,2BAA2B,OAAA;AAC3B,sHAAA,0BAA0B,OAAA;AAC1B,8GAAA,kBAAkB,OAAA;AAClB,8GAAA,kBAAkB,OAAA;AAClB,6GAAA,iBAAiB,OAAA;AACjB,gHAAA,oBAAoB,OAAA;AACpB,mHAAA,uBAAuB,OAAA;AACvB,6GAAA,iBAAiB,OAAA;AAwBnB,mCAA8D;AAArD,yGAAA,eAAe,OAAA;AAAE,2GAAA,iBAAiB,OAAA;AAE3C,yCAAqD;AAA5C,mHAAA,sBAAsB,OAAA;AAE/B,2CAA4G;AAAnG,6GAAA,eAAe,OAAA;AAAE,4GAAA,cAAc,OAAA;AAAE,4GAAA,cAAc,OAAA;AAExD,8FAA8F;AAC9F,4FAA4F;AAC5F,6FAA6F;AAC7F,qDAAqD;AACrD,EAAE;AACF,gGAAgG;AAChG,iGAAiG;AACjG,gGAAgG;AAChG,mCAAmC;AACnC,iDAMyB;AALvB,sHAAA,qBAAqB,OAAA;AACrB,2HAAA,0BAA0B,OAAA;AAM5B,iEAOiC;AAN/B,wHAAA,eAAe,OAAA","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * An HTTP fetch primitive with an explicit threat model (browser version).\n *\n * This barrel deliberately omits `blockPrivateNetworks` and the resolver seam beneath it: that\n * module imports `node:dns/promises`, and exporting it here would pull a Node builtin into a\n * browser bundle.\n *\n * The address-classification layer — `classifyAddress`, and the pure synchronous policies\n * `allowAnyAddressPolicy` / `blockPrivateNetworksPolicy` — **is** exported here: it is pure\n * arithmetic over parsed octets, it works identically in a browser, and it is useful for a\n * URL-zero check. It is not a substitute for the guard, and cannot be: it classifies an address\n * a caller already holds, while what the browser lacks is any way to learn the address a\n * hostname resolves to.\n *\n * Note: the resolved-address (private-IP) guard and per-hop redirect revalidation are NOT\n * available in a browser, and not for want of implementation. There is no browser API that\n * returns a hostname's A/AAAA records, nothing in `fetch` or `Response` exposes the peer\n * address, and `redirect: 'manual'` yields an opaque response whose `Location` is not\n * readable — a `'validate-each-hop'` call there fails as `'redirect-opaque'` rather than\n * quietly following anything. `allowAnyAddress()` is the honest choice, and its name says so.\n *\n * @packageDocumentation\n */\n\nexport {\n  ALWAYS_STRIPPED_HEADERS,\n  DEFAULT_HEADERS_TIMEOUT_MS,\n  DEFAULT_MAX_REDIRECTS,\n  DEFAULT_MAX_RESPONSE_BYTES,\n  DEFAULT_RETRY_BASE_DELAY_MS,\n  DEFAULT_RETRY_MAX_DELAY_MS,\n  DEFAULT_TIMEOUT_MS,\n  IDEMPOTENT_METHODS,\n  REDIRECT_STATUSES,\n  RETRY_AFTER_STATUSES,\n  RETRYABLE_HTTP_STATUSES,\n  SUPPORTED_SCHEMES\n} from './defaults';\n\nexport type { FetchFailureReason, FetchTimeoutPhase } from './failureReason';\nexport type { IRetryPolicy } from './retry';\n\nexport type {\n  IAddressGuard,\n  IFetchTransport,\n  IFetchTransportHints,\n  IGuardVerdict,\n  IRequestGuard,\n  IRequestHop,\n  IResolvedGuards,\n  IResponseBodyGuard,\n  IResponseHeadersGuard,\n  ISaferFetchOptions,\n  ISaferFetchRequest,\n  ISaferFetchResponse,\n  ISaferFetchResponseHead,\n  SaferFetchMethod,\n  SaferFetchRedirectPolicy\n} from './model';\n\nexport { allowAnyAddress, allowContentTypes } from './guards';\n\nexport { platformFetchTransport } from './transport';\n\nexport { saferFetchBytes, saferFetchJson, saferFetchText, type ISaferFetchJsonOptions } from './saferFetch';\n\n// Runtime-agnostic and exported from both barrels: the address *classification* layer is pure\n// arithmetic over parsed octets with no I/O, so it works in a browser exactly as it does on\n// Node. It is useful there for a URL-zero check — a caller can refuse an IP-literal URL that\n// classifies as private before ever calling `fetch`.\n//\n// **It cannot substitute for the resolved-address guard.** It classifies an address you already\n// have; the guarantee the browser lacks is *obtaining* the address a hostname resolves to, which\n// no browser API provides. `https://internal.example.com/` resolving to `10.0.0.5` is invisible\n// to every function exported here.\nexport {\n  allowAnyAddressPolicy,\n  blockPrivateNetworksPolicy,\n  type IAddressCheckVerdict,\n  type IAddressPolicy,\n  type IBlockPrivateNetworksOptions\n} from './addressPolicy';\n\nexport {\n  classifyAddress,\n  type AddressClassification,\n  type AddressFamily,\n  type IClassifiedAddress,\n  type IEmbeddedIpv4,\n  type Ipv4EmbeddingKind\n} from './addressClassification';\n"]}

package/lib/packlets/safer-fetch/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A safer `fetch` primitive with an explicit threat model.
+ *
+ * This is deliberately **not** a thin, unopinionated boundary over an upstream library. There
+ * is no upstream to wrap — `fetch` is a platform global — and the opinion *is* the product:
+ * the deadlines, the scheme refusal, the streaming size cap, the redirect posture, and the
+ * required address guard are the deliverable. A caller who strips the opinion out has `fetch`,
+ * which is where they started.
+ *
+ * The guiding constraint: *a primitive that advertises a guarantee it does not have is worse
+ * than five lines at a call site, because it transfers responsibility without transferring
+ * protection.* Every entry point's documentation names what it does **not** protect against
+ * next to what it does.
+ *
+ * @packageDocumentation
+ */
+export { ALWAYS_STRIPPED_HEADERS, DEFAULT_HEADERS_TIMEOUT_MS, DEFAULT_MAX_REDIRECTS, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_BASE_DELAY_MS, DEFAULT_RETRY_MAX_DELAY_MS, DEFAULT_TIMEOUT_MS, IDEMPOTENT_METHODS, REDIRECT_STATUSES, RETRY_AFTER_STATUSES, RETRYABLE_HTTP_STATUSES, SUPPORTED_SCHEMES } from './defaults';
+export type { FetchFailureReason, FetchTimeoutPhase } from './failureReason';
+export type { IRetryPolicy } from './retry';
+export type { IAddressGuard, IFetchTransport, IFetchTransportHints, IGuardVerdict, IRequestGuard, IRequestHop, IResolvedGuards, IResponseBodyGuard, IResponseHeadersGuard, ISaferFetchOptions, ISaferFetchRequest, ISaferFetchResponse, ISaferFetchResponseHead, SaferFetchMethod, SaferFetchRedirectPolicy } from './model';
+export { allowAnyAddress, allowContentTypes } from './guards';
+export { platformFetchTransport } from './transport';
+export { saferFetchBytes, saferFetchJson, saferFetchText, type ISaferFetchJsonOptions } from './saferFetch';
+export { allowAnyAddressPolicy, blockPrivateNetworksPolicy, type IAddressCheckVerdict, type IAddressPolicy, type IBlockPrivateNetworksOptions } from './addressPolicy';
+export { blockPrivateNetworks, nodeHostResolver, type HostResolver, type IBlockPrivateNetworksGuardOptions } from './nodeAddressGuard';
+export { classifyAddress, type AddressClassification, type AddressFamily, type IClassifiedAddress, type IEmbeddedIpv4, type Ipv4EmbeddingKind } from './addressClassification';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/safer-fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/index.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,YAAY,EACV,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAQ5G,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,4BAA4B,EAClC,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,iCAAiC,EACvC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC"}