@fgv/ts-extras 5.1.0-5 → 5.1.0-50

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"}

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

@@ -0,0 +1,78 @@
+"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.nodeHostResolver = exports.blockPrivateNetworks = 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;
+/**
+ * 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
+ */
+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; } });
+// Two layers, one naming rule: an **unsuffixed** factory returns the asynchronous,
+// hop-chain-aware, name-resolving `IAddressGuard` that an entry point's `addressGuard` option
+// takes (`allowAnyAddress`, `blockPrivateNetworks`), while a **`Policy`-suffixed** factory
+// returns the pure, synchronous `IAddressPolicy` over an already-resolved address list that such
+// a guard delegates to (`allowAnyAddressPolicy`, `blockPrivateNetworksPolicy`). The unsuffixed
+// names are the ones callers reach for, which is why they are the ones that fit the call site.
+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; } });
+// Node only — it resolves names, and no browser API returns a hostname's A/AAAA records. This
+// is the one module in the packlet that performs I/O, and the reason this barrel and the browser
+// barrel differ at all.
+var nodeAddressGuard_1 = require("./nodeAddressGuard");
+Object.defineProperty(exports, "blockPrivateNetworks", { enumerable: true, get: function () { return nodeAddressGuard_1.blockPrivateNetworks; } });
+Object.defineProperty(exports, "nodeHostResolver", { enumerable: true, get: function () { return nodeAddressGuard_1.nodeHostResolver; } });
+var addressClassification_1 = require("./addressClassification");
+Object.defineProperty(exports, "classifyAddress", { enumerable: true, get: function () { return addressClassification_1.classifyAddress; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/index.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;;;;;;;;;;;;;;;GAeG;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,mFAAmF;AACnF,8FAA8F;AAC9F,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,+FAA+F;AAC/F,iDAMyB;AALvB,sHAAA,qBAAqB,OAAA;AACrB,2HAAA,0BAA0B,OAAA;AAM5B,8FAA8F;AAC9F,iGAAiG;AACjG,wBAAwB;AACxB,uDAK4B;AAJ1B,wHAAA,oBAAoB,OAAA;AACpB,oHAAA,gBAAgB,OAAA;AAKlB,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 * A safer `fetch` primitive with an explicit threat model.\n *\n * This is deliberately **not** a thin, unopinionated boundary over an upstream library. There\n * is no upstream to wrap — `fetch` is a platform global — and the opinion *is* the product:\n * the deadlines, the scheme refusal, the streaming size cap, the redirect posture, and the\n * required address guard are the deliverable. A caller who strips the opinion out has `fetch`,\n * which is where they started.\n *\n * The guiding constraint: *a primitive that advertises a guarantee it does not have is worse\n * than five lines at a call site, because it transfers responsibility without transferring\n * protection.* Every entry point's documentation names what it does **not** protect against\n * next to what it does.\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// Two layers, one naming rule: an **unsuffixed** factory returns the asynchronous,\n// hop-chain-aware, name-resolving `IAddressGuard` that an entry point's `addressGuard` option\n// takes (`allowAnyAddress`, `blockPrivateNetworks`), while a **`Policy`-suffixed** factory\n// returns the pure, synchronous `IAddressPolicy` over an already-resolved address list that such\n// a guard delegates to (`allowAnyAddressPolicy`, `blockPrivateNetworksPolicy`). The unsuffixed\n// names are the ones callers reach for, which is why they are the ones that fit the call site.\nexport {\n  allowAnyAddressPolicy,\n  blockPrivateNetworksPolicy,\n  type IAddressCheckVerdict,\n  type IAddressPolicy,\n  type IBlockPrivateNetworksOptions\n} from './addressPolicy';\n\n// Node only — it resolves names, and no browser API returns a hostname's A/AAAA records. This\n// is the one module in the packlet that performs I/O, and the reason this barrel and the browser\n// barrel differ at all.\nexport {\n  blockPrivateNetworks,\n  nodeHostResolver,\n  type HostResolver,\n  type IBlockPrivateNetworksGuardOptions\n} from './nodeAddressGuard';\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/model.d.ts

@@ -0,0 +1,373 @@
+import type { Logging, Result } from '@fgv/ts-utils';
+import type { IRetryPolicy } from './retry';
+/**
+ * HTTP methods a safer-fetch call may use.
+ * @public
+ */
+export type SaferFetchMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * How redirects are handled.
+ *
+ * @remarks
+ * `'reject'` fails on any redirect status. It is the default, and the only mode with an
+ * equivalent guarantee on every runtime — a browser cannot inspect a redirect hop at all, so a
+ * per-hop revalidating mode is not implementable there.
+ *
+ * The *guarantee* is equivalent on both runtimes; the failure **reason** is not. Every call uses
+ * `redirect: 'manual'`, so on Node a rejected redirect surfaces as `'redirect-rejected'` carrying
+ * the status, while in a browser the response is opaque — `type` is `'opaqueredirect'` and
+ * `status` is `0`, so there is no status to report — and the same redirect surfaces as
+ * `'redirect-opaque'`. Callers that branch on the reason under `'reject'` must handle both.
+ *
+ * `'validate-each-hop'` follows redirects with `redirect: 'manual'` and runs the **full address
+ * guard on every hop before any connection is made**, resolving `Location` against the hop that
+ * sent it. Redirect handling and the address check are one mechanism, not two: a guard that
+ * validated only the caller's URL is defeated by a single `302` to `http://169.254.169.254/`.
+ * Following hops also makes this primitive responsible for credential stripping — see
+ * `ISaferFetchOptions.sensitiveHeaders`.
+ *
+ * **`'validate-each-hop'` is accepted by the browser barrel but cannot succeed there, and fails
+ * loudly rather than degrading.** The type is shared because one core serves both runtimes; the
+ * runtime is not. A browser's `redirect: 'manual'` yields an opaque response — `type` is
+ * `'opaqueredirect'`, `status` is `0`, and `Location` is not readable — so the first redirect
+ * fails as `'redirect-opaque'`. That is the honest outcome: the hop information does not exist
+ * on the browser side of the API, so there is nothing to guard and nothing to follow. Use
+ * `'reject'` there, or handle `'redirect-opaque'`.
+ *
+ * A mode that defers to the platform's own redirect following is deliberately absent on Node:
+ * it would put hops on the wire that the guard never saw.
+ * @public
+ */
+export type SaferFetchRedirectPolicy = 'reject' | 'validate-each-hop';
+/**
+ * One hop in a redirect chain. Entry 0 is the caller's original request.
+ * @public
+ */
+export interface IRequestHop {
+    /** The URL under consideration for this hop. */
+    readonly url: URL;
+    /** The redirect status that produced the NEXT hop; absent on the current one. */
+    readonly status?: number;
+    /**
+     * The address actually connected to on this hop, when address pinning was in effect.
+     *
+     * @remarks
+     * Populated from the address guard's {@link SaferFetch.IGuardVerdict.pinnedAddress} once the
+     * transport has accepted it — which is sound because a transport that cannot honor a pin is
+     * required to fail rather than connect by hostname, so a completed request with a pin set is
+     * evidence the pin held. **Undefined throughout this release**, since no shipped guard pins
+     * and {@link SaferFetch.platformFetchTransport} cannot honor one; the field is where the
+     * rebinding defense's per-hop evidence will live.
+     */
+    readonly connectedAddress?: string;
+}
+/**
+ * An address guard's decision about a hop.
+ * @public
+ */
+export interface IGuardVerdict {
+    /**
+     * The URL cleared for request. Guards may **normalize** it — lowercase the host, strip a
+     * trailing dot, punycode an IDN — and the normalized URL is what gets requested. Guards
+     * must not **retarget** it to a different destination.
+     *
+     * @remarks
+     * That contract is documented rather than enforced: origin-equality enforcement would
+     * reject exactly the normalizations the guard is supposed to perform. Guards are trusted
+     * first-party code; a malicious in-process caller is out of this primitive's threat model.
+     * The one check that is enforced is the scheme — a verdict URL whose scheme is not
+     * `http:` or `https:` is rejected.
+     */
+    readonly url: URL;
+    /**
+     * The address the guard validated and to which the connection SHOULD be pinned.
+     *
+     * @remarks
+     * **Always `undefined` in this release** — reserved for the pinned-connect work that
+     * closes the DNS-rebinding hole. A transport that receives a defined value it cannot
+     * honor MUST fail rather than connect by hostname; {@link SaferFetch.platformFetchTransport}
+     * does exactly that. Ignoring the hint would give a deployment that wired a pinning guard
+     * but forgot the matching transport precisely the rebinding exposure it believed it had
+     * closed, silently.
+     */
+    readonly pinnedAddress?: string;
+}
+/**
+ * Decides whether a connection may be made. Invoked once per redirect hop, never only on
+ * the initial URL.
+ *
+ * @remarks
+ * This is the SSRF boundary and the one guard whose failure is catastrophic, which is why
+ * it is a separate seam from the request and response policy guards: "did the address check
+ * run, and run correctly?" should be answerable by reading one small implementation.
+ *
+ * The seam is **asynchronous and hop-chain-aware so that it can wrap a pure classifier**: a
+ * real guard resolves `url.hostname` to an address list and then delegates the judgement to a
+ * synchronous, address-list-in policy. That split keeps the part with the adversarial test
+ * matrix — the address classification itself — free of transports, DNS, and hop bookkeeping,
+ * and keeps exactly one implementation of it. A guard is the resolving, chain-aware half; it
+ * should not re-derive what the classifier already decides.
+ *
+ * Classify `url.hostname`, never raw URL text: the WHATWG parser has already normalized
+ * `127.0x.1` to `127.0.0.1` and `::ffff:169.254.169.254` to `::ffff:a9fe:a9fe`, and text
+ * matching misses both.
+ * @public
+ */
+export interface IAddressGuard {
+    /** Stable identifier, surfaced in `'blocked-by-guard'` failures. */
+    readonly name: string;
+    /**
+     * @param chain - Every hop so far, oldest first. The URL under consideration is the last
+     * entry; `chain.length === 1` is the initial request. There is deliberately no separate
+     * "is this a redirect" flag — hop 0 is not a special case, and a guard that compares only
+     * against the immediately previous hop cannot see an `A → B → A` laundering hop.
+     */
+    check(chain: ReadonlyArray<IRequestHop>): Promise<Result<IGuardVerdict>>;
+}
+/**
+ * The request a safer-fetch call is about to issue.
+ * @public
+ */
+export interface ISaferFetchRequest {
+    readonly url: URL;
+    readonly method: SaferFetchMethod;
+    /** Header names are lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string | Uint8Array;
+}
+/**
+ * Response status and headers, available before any body bytes are read.
+ * @public
+ */
+export interface ISaferFetchResponseHead {
+    readonly status: number;
+    readonly statusText: string;
+    /** Header names are lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Raw `content-type` header value, including any parameters. */
+    readonly contentType?: string;
+    /** Parsed `content-length`, present only when the header was sent and is a valid count. */
+    readonly contentLength?: number;
+}
+/**
+ * Policy guard over the outbound request.
+ *
+ * @remarks
+ * **Reject-only.** Silently rewriting a caller's headers or body inside a fetch primitive
+ * means the caller no longer knows what was sent. To alter the request, return an explicit
+ * replacement the caller could have observed.
+ *
+ * Runs **before** the address guard, so an address guard is always the last word before the
+ * connect: a replacement request that changed the URL is still address-checked.
+ * @public
+ */
+export interface IRequestGuard {
+    readonly name: string;
+    check(request: ISaferFetchRequest, chain: ReadonlyArray<IRequestHop>): Promise<Result<ISaferFetchRequest>>;
+}
+/**
+ * Policy guard over the response head.
+ *
+ * @remarks
+ * Runs before any body bytes are read, so a rejection costs a header comparison instead of a
+ * partial body transfer. This is the right layer for content-type gating — see
+ * {@link SaferFetch.allowContentTypes}.
+ * @public
+ */
+export interface IResponseHeadersGuard {
+    readonly name: string;
+    /**
+     * The media types this guard accepts, when it is a content-type allowlist.
+     *
+     * @remarks
+     * Present so that a rejection can be reported as `'unsupported-content-type'` carrying the
+     * accepted list, rather than as an opaque policy rejection the caller has to parse a message
+     * to understand. A guard that is not a content-type allowlist omits it and its rejections are
+     * reported as `'blocked-by-guard'`.
+     */
+    readonly acceptedContentTypes?: ReadonlyArray<string>;
+    check(head: ISaferFetchResponseHead, chain: ReadonlyArray<IRequestHop>): Promise<Result<true>>;
+}
+/**
+ * Policy guard over the buffered response body.
+ *
+ * @remarks
+ * Runs on the buffered body, after the size cap has been enforced — so it can never be handed
+ * an unbounded stream.
+ * @public
+ */
+export interface IResponseBodyGuard {
+    readonly name: string;
+    check(body: Uint8Array, head: ISaferFetchResponseHead): Promise<Result<true>>;
+}
+/**
+ * Out-of-band information a transport may need that `RequestInit` cannot express.
+ * @public
+ */
+export interface IFetchTransportHints {
+    /**
+     * The address the address guard validated, to which this connection must be pinned.
+     * A transport that cannot pin MUST fail rather than connect by hostname.
+     */
+    readonly pinnedAddress?: string;
+}
+/**
+ * Performs the actual request.
+ *
+ * @remarks
+ * Injectable for two reasons. It is the seam through which a pinned-connect implementation
+ * drops in without any caller-visible signature change — which is what keeps closing the
+ * DNS-rebinding hole additive rather than breaking. And it is the test seam: redirect chains,
+ * lying `Content-Length` headers, compression-bomb shapes, and trickling bodies are all
+ * unit-testable through a scripted transport, with no live server anywhere in the suite.
+ * @public
+ */
+export interface IFetchTransport {
+    readonly name: string;
+    fetch(url: URL, init: RequestInit, hints: IFetchTransportHints): Promise<Result<Response>>;
+}
+/**
+ * Options common to every safer-fetch entry point.
+ * @public
+ */
+export interface ISaferFetchOptions {
+    /**
+     * **Required, with no default.** A passthrough default here would be exactly the failure
+     * this primitive exists to avoid — advertising a guarantee it does not have. Requiring it
+     * makes omission a *compile* error rather than a runtime surprise or a lint rule, and makes
+     * every call site's posture greppable in one search with no ambient default to overlook.
+     *
+     * Use a named factory. `allowAnyAddress()` is the explicit, deliberately uncomfortable
+     * opt-out, and is the only correct choice in a browser, where neither DNS resolution nor
+     * redirect interposition exists.
+     */
+    readonly addressGuard: IAddressGuard;
+    /**
+     * Policy guard over the outbound request. Optional here and non-optional once resolved —
+     * it defaults to silent passthrough, applied once at the boundary, so no downstream code
+     * path branches on a guard's absence.
+     */
+    readonly requestGuard?: IRequestGuard;
+    /**
+     * Policy guard over the response head. Defaults to silent passthrough. Content-type gating
+     * lives here — see {@link SaferFetch.allowContentTypes}; it is deliberately not a separate
+     * option, which would be a second mechanism for one job.
+     */
+    readonly responseHeadersGuard?: IResponseHeadersGuard;
+    /** Policy guard over the buffered body. Defaults to silent passthrough. */
+    readonly responseBodyGuard?: IResponseBodyGuard;
+    /** Defaults to `'GET'`. */
+    readonly method?: SaferFetchMethod;
+    /** Request headers. Names are lowercased before the request guard sees them. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Request body. Not permitted with `'GET'` or `'HEAD'`. */
+    readonly body?: string | Uint8Array;
+    /**
+     * Overall deadline in milliseconds, covering the connect, the response headers, and the
+     * body read. Default {@link SaferFetch.DEFAULT_TIMEOUT_MS}. This is the deadline that stops
+     * a response dribbling one byte every 25 seconds, which passes every per-read check.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Deadline to first response headers, in milliseconds. Default
+     * {@link SaferFetch.DEFAULT_HEADERS_TIMEOUT_MS}. Distinguishes "the host is not answering"
+     * from "the host is answering slowly", which the failure taxonomy then reports as
+     * `timeout.phase`.
+     *
+     * @remarks
+     * Measured from the start of the attempt, which includes guard evaluation — an address guard
+     * that resolves DNS spends this budget too. That is deliberate: the deadline bounds the time
+     * a caller waits for a usable response, not the time one layer of the implementation spends.
+     */
+    readonly headersTimeoutMs?: number;
+    /**
+     * Cap on decoded response bytes. Default {@link SaferFetch.DEFAULT_MAX_RESPONSE_BYTES}
+     * (5 MiB).
+     *
+     * @remarks
+     * **This knob is meant to be reached for.** 5 MiB is roughly an order of magnitude above a
+     * realistic JSON API response and is generous for text, but real documents clear it — raise
+     * it per call for the calls that need it rather than treating the default as a ceiling. The
+     * cap is enforced by counting decoded bytes during the read, so raising it raises the
+     * buffer the process may be asked to hold; size it against the heap you are willing to
+     * spend, not against the largest document you can imagine.
+     */
+    readonly maxResponseBytes?: number;
+    /**
+     * How redirects are handled. Defaults to `'reject'`.
+     *
+     * @remarks
+     * The conservative default is deliberate, and is the same polarity as `addressGuard` having no
+     * default: one core serves both runtimes, `'reject'` is the only mode whose guarantee is
+     * identical on each, and following a redirect chain into hosts the caller never named is a
+     * posture worth spelling at the call site. Callers ingesting real-world URLs want
+     * `'validate-each-hop'`.
+     */
+    readonly redirectPolicy?: SaferFetchRedirectPolicy;
+    /**
+     * Cap on redirect hops followed under `'validate-each-hop'`. Default
+     * {@link SaferFetch.DEFAULT_MAX_REDIRECTS} (5). Must be a non-negative integer; `0` refuses
+     * to follow any redirect.
+     */
+    readonly maxRedirects?: number;
+    /**
+     * Additional header names to drop on a cross-origin redirect hop, on top of the always-dropped
+     * `authorization`, `cookie` and `proxy-authorization`
+     * ({@link SaferFetch.ALWAYS_STRIPPED_HEADERS}).
+     *
+     * @remarks
+     * Matching is case-insensitive. Use this for bearer-equivalent headers a deployment invented —
+     * `x-api-key`, `x-auth-token`, a signed-request header. Stripping is **monotonic**: once a hop
+     * has left an origin the headers are gone for the rest of the chain, so an `A` → `B` → `A`
+     * chain does not hand the credential back to `A` after `B` has watched it leave.
+     */
+    readonly sensitiveHeaders?: ReadonlyArray<string>;
+    /**
+     * Opt-in retry. **Off by default** — a primitive that silently retries changes the semantics
+     * of every call site and amplifies load against a service that is already struggling.
+     *
+     * @remarks
+     * Retries consume `timeoutMs` and never reset it, so enabling retry does not extend the
+     * deadline; and every attempt re-runs the address guard from hop 0 as a full re-walk, never a
+     * resume and never a cached verdict. Both rules are load-bearing rather than incidental — see
+     * {@link SaferFetch.IRetryPolicy}, which states why.
+     */
+    readonly retry?: IRetryPolicy;
+    /** Defaults to {@link SaferFetch.platformFetchTransport}. */
+    readonly transport?: IFetchTransport;
+    /** Caller's cancellation signal. Reported as `'aborted'`, never as `'timeout'`. */
+    readonly signal?: AbortSignal;
+    /** Diagnostics sink. Defaults to a no-op logger. */
+    readonly logger?: Logging.ILogger;
+}
+/**
+ * The guards a call will actually use. Every field is concrete: defaults are applied once, at
+ * the boundary, and nothing downstream branches on a guard's absence.
+ * @public
+ */
+export interface IResolvedGuards {
+    /** Caller-supplied; there is no default. */
+    readonly address: IAddressGuard;
+    readonly request: IRequestGuard;
+    readonly responseHeaders: IResponseHeadersGuard;
+    readonly responseBody: IResponseBodyGuard;
+}
+/**
+ * A successful safer-fetch response.
+ * @public
+ */
+export interface ISaferFetchResponse<T> {
+    readonly value: T;
+    readonly status: number;
+    /** Header names are lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    /**
+     * Every URL actually requested, in order, as cleared by the address guard. `[0]` is the
+     * caller's; later entries are redirect hops. A caller that allowlisted `api.example.com`
+     * and was redirected to `cdn.example.com` usually wants to know.
+     */
+    readonly urlChain: ReadonlyArray<string>;
+    /** Decoded bytes read from the response body. */
+    readonly bytesRead: number;
+}
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/model.ts"],"names":[],"mappings":"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"}

package/lib/packlets/safer-fetch/model.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=model.js.map