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

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

@@ -0,0 +1,134 @@
+"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.IDEMPOTENT_METHODS = exports.RETRY_AFTER_STATUSES = exports.RETRYABLE_HTTP_STATUSES = exports.DEFAULT_RETRY_MAX_DELAY_MS = exports.DEFAULT_RETRY_BASE_DELAY_MS = exports.SUPPORTED_SCHEMES = exports.ALWAYS_STRIPPED_HEADERS = exports.DEFAULT_MAX_REDIRECTS = exports.REDIRECT_STATUSES = exports.DEFAULT_MAX_RESPONSE_BYTES = exports.DEFAULT_HEADERS_TIMEOUT_MS = exports.DEFAULT_TIMEOUT_MS = void 0;
+/**
+ * Default overall deadline, in milliseconds — comfortably above a slow-but-real API and far
+ * below "a hung request pins a socket for minutes". Streaming LLM calls should not use this
+ * primitive at all; that is what `AiAssist` is for.
+ * @public
+ */
+exports.DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Default deadline to first response headers, in milliseconds. A host that has not sent
+ * headers in ten seconds is not answering.
+ * @public
+ */
+exports.DEFAULT_HEADERS_TIMEOUT_MS = 10000;
+/**
+ * Default cap on decoded response bytes (5 MiB) — roughly an order of magnitude above a
+ * realistic JSON API response and well below a size that threatens a Node heap.
+ *
+ * @remarks
+ * Raising it is a per-call option, not a construction-time setting, precisely because real
+ * documents clear this. See `ISaferFetchOptions.maxResponseBytes`.
+ * @public
+ */
+exports.DEFAULT_MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+/**
+ * Redirect statuses this primitive recognizes as redirects. Other 3xx statuses (`300`, `304`,
+ * …) do not direct the client at a new URL and are reported as ordinary non-2xx responses.
+ * @public
+ */
+exports.REDIRECT_STATUSES = [301, 302, 303, 307, 308];
+/**
+ * Default cap on redirect hops followed under `'validate-each-hop'`.
+ *
+ * @remarks
+ * Five is enough for the ordinary shortener-then-canonicalize-then-CDN chains real services
+ * produce and small enough that a chain designed to burn budget is refused quickly. Every hop
+ * costs a full guard evaluation — including a DNS resolution — against the same overall
+ * deadline, so the cap bounds work, not just politeness.
+ * @public
+ */
+exports.DEFAULT_MAX_REDIRECTS = 5;
+/**
+ * Header names dropped on every cross-origin redirect hop, whatever the caller configured.
+ *
+ * @remarks
+ * Turning on manual redirects makes this primitive responsible for a rule the platform was
+ * applying for free: browsers and `curl` both strip credential headers when a redirect leaves
+ * the origin, and a hand-rolled loop that replays them hands `Authorization: Bearer …` to
+ * whatever host the redirect names. Callers add their own names with
+ * `ISaferFetchOptions.sensitiveHeaders`; these three are not removable.
+ * @public
+ */
+exports.ALWAYS_STRIPPED_HEADERS = [
+    'authorization',
+    'cookie',
+    'proxy-authorization'
+];
+/**
+ * URL schemes this primitive will ever request.
+ *
+ * @remarks
+ * Core rejects everything else — `file:`, `data:`, `blob:`, `ftp:`, `gopher:`, `ws:` — outright
+ * and at every hop, because none of them is a legitimate network fetch and each is a standard
+ * SSRF payload. Deciding between `http:` and `https:`, and which ports are acceptable, belongs
+ * to the address guard, which is why core does not narrow this further.
+ * @public
+ */
+exports.SUPPORTED_SCHEMES = ['http:', 'https:'];
+/**
+ * Default base delay for {@link SaferFetch.IRetryPolicy | retry} backoff, in milliseconds.
+ * @public
+ */
+exports.DEFAULT_RETRY_BASE_DELAY_MS = 250;
+/**
+ * Default ceiling on a single {@link SaferFetch.IRetryPolicy | retry} delay, in milliseconds.
+ *
+ * @remarks
+ * It bounds the computed backoff **and** a server-supplied `Retry-After`. That second role is
+ * the security-relevant one: `Retry-After` is a header an attacker-controlled server chooses
+ * freely, so an unclamped `Retry-After: 86400` is a denial of service on the caller.
+ * @public
+ */
+exports.DEFAULT_RETRY_MAX_DELAY_MS = 5000;
+/**
+ * HTTP statuses a {@link SaferFetch.IRetryPolicy | retry policy} will retry.
+ *
+ * @remarks
+ * Every other status — including every other 4xx — is terminal. A `401`, a `403` and a `404`
+ * mean the same thing on the second attempt as on the first, and retrying them turns a client
+ * bug into load against a service that already said no.
+ * @public
+ */
+exports.RETRYABLE_HTTP_STATUSES = [408, 429, 500, 502, 503, 504];
+/**
+ * Statuses whose `Retry-After` header is honored.
+ *
+ * @remarks
+ * `429` and `503` are the two the header is specified for and the two where it carries real
+ * scheduling information. Honoring it on a `500` would let any failing endpoint dictate the
+ * caller's schedule for no benefit.
+ * @public
+ */
+exports.RETRY_AFTER_STATUSES = [429, 503];
+/**
+ * Methods retried without an explicit opt-in.
+ *
+ * @remarks
+ * A timeout does not tell you whether the server processed the request, so a retried `POST`
+ * can double-charge. `retryNonIdempotent` opts out, per call, visibly.
+ * @public
+ */
+exports.IDEMPOTENT_METHODS = ['GET', 'HEAD'];
+//# sourceMappingURL=defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../../src/packlets/safer-fetch/defaults.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;;;;;GAKG;AACU,QAAA,kBAAkB,GAAW,KAAM,CAAC;AAEjD;;;;GAIG;AACU,QAAA,0BAA0B,GAAW,KAAM,CAAC;AAEzD;;;;;;;;GAQG;AACU,QAAA,0BAA0B,GAAW,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAElE;;;;GAIG;AACU,QAAA,iBAAiB,GAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAElF;;;;;;;;;GASG;AACU,QAAA,qBAAqB,GAAW,CAAC,CAAC;AAE/C;;;;;;;;;;GAUG;AACU,QAAA,uBAAuB,GAA0B;IAC5D,eAAe;IACf,QAAQ;IACR,qBAAqB;CACtB,CAAC;AAEF;;;;;;;;;GASG;AACU,QAAA,iBAAiB,GAA0B,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAE5E;;;GAGG;AACU,QAAA,2BAA2B,GAAW,GAAG,CAAC;AAEvD;;;;;;;;GAQG;AACU,QAAA,0BAA0B,GAAW,IAAK,CAAC;AAExD;;;;;;;;GAQG;AACU,QAAA,uBAAuB,GAA0B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAE7F;;;;;;;;GAQG;AACU,QAAA,oBAAoB,GAA0B,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEtE;;;;;;;GAOG;AACU,QAAA,kBAAkB,GAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC","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 * Default overall deadline, in milliseconds — comfortably above a slow-but-real API and far\n * below \"a hung request pins a socket for minutes\". Streaming LLM calls should not use this\n * primitive at all; that is what `AiAssist` is for.\n * @public\n */\nexport const DEFAULT_TIMEOUT_MS: number = 30_000;\n\n/**\n * Default deadline to first response headers, in milliseconds. A host that has not sent\n * headers in ten seconds is not answering.\n * @public\n */\nexport const DEFAULT_HEADERS_TIMEOUT_MS: number = 10_000;\n\n/**\n * Default cap on decoded response bytes (5 MiB) — roughly an order of magnitude above a\n * realistic JSON API response and well below a size that threatens a Node heap.\n *\n * @remarks\n * Raising it is a per-call option, not a construction-time setting, precisely because real\n * documents clear this. See `ISaferFetchOptions.maxResponseBytes`.\n * @public\n */\nexport const DEFAULT_MAX_RESPONSE_BYTES: number = 5 * 1024 * 1024;\n\n/**\n * Redirect statuses this primitive recognizes as redirects. Other 3xx statuses (`300`, `304`,\n * …) do not direct the client at a new URL and are reported as ordinary non-2xx responses.\n * @public\n */\nexport const REDIRECT_STATUSES: ReadonlyArray<number> = [301, 302, 303, 307, 308];\n\n/**\n * Default cap on redirect hops followed under `'validate-each-hop'`.\n *\n * @remarks\n * Five is enough for the ordinary shortener-then-canonicalize-then-CDN chains real services\n * produce and small enough that a chain designed to burn budget is refused quickly. Every hop\n * costs a full guard evaluation — including a DNS resolution — against the same overall\n * deadline, so the cap bounds work, not just politeness.\n * @public\n */\nexport const DEFAULT_MAX_REDIRECTS: number = 5;\n\n/**\n * Header names dropped on every cross-origin redirect hop, whatever the caller configured.\n *\n * @remarks\n * Turning on manual redirects makes this primitive responsible for a rule the platform was\n * applying for free: browsers and `curl` both strip credential headers when a redirect leaves\n * the origin, and a hand-rolled loop that replays them hands `Authorization: Bearer …` to\n * whatever host the redirect names. Callers add their own names with\n * `ISaferFetchOptions.sensitiveHeaders`; these three are not removable.\n * @public\n */\nexport const ALWAYS_STRIPPED_HEADERS: ReadonlyArray<string> = [\n  'authorization',\n  'cookie',\n  'proxy-authorization'\n];\n\n/**\n * URL schemes this primitive will ever request.\n *\n * @remarks\n * Core rejects everything else — `file:`, `data:`, `blob:`, `ftp:`, `gopher:`, `ws:` — outright\n * and at every hop, because none of them is a legitimate network fetch and each is a standard\n * SSRF payload. Deciding between `http:` and `https:`, and which ports are acceptable, belongs\n * to the address guard, which is why core does not narrow this further.\n * @public\n */\nexport const SUPPORTED_SCHEMES: ReadonlyArray<string> = ['http:', 'https:'];\n\n/**\n * Default base delay for {@link SaferFetch.IRetryPolicy | retry} backoff, in milliseconds.\n * @public\n */\nexport const DEFAULT_RETRY_BASE_DELAY_MS: number = 250;\n\n/**\n * Default ceiling on a single {@link SaferFetch.IRetryPolicy | retry} delay, in milliseconds.\n *\n * @remarks\n * It bounds the computed backoff **and** a server-supplied `Retry-After`. That second role is\n * the security-relevant one: `Retry-After` is a header an attacker-controlled server chooses\n * freely, so an unclamped `Retry-After: 86400` is a denial of service on the caller.\n * @public\n */\nexport const DEFAULT_RETRY_MAX_DELAY_MS: number = 5_000;\n\n/**\n * HTTP statuses a {@link SaferFetch.IRetryPolicy | retry policy} will retry.\n *\n * @remarks\n * Every other status — including every other 4xx — is terminal. A `401`, a `403` and a `404`\n * mean the same thing on the second attempt as on the first, and retrying them turns a client\n * bug into load against a service that already said no.\n * @public\n */\nexport const RETRYABLE_HTTP_STATUSES: ReadonlyArray<number> = [408, 429, 500, 502, 503, 504];\n\n/**\n * Statuses whose `Retry-After` header is honored.\n *\n * @remarks\n * `429` and `503` are the two the header is specified for and the two where it carries real\n * scheduling information. Honoring it on a `500` would let any failing endpoint dictate the\n * caller's schedule for no benefit.\n * @public\n */\nexport const RETRY_AFTER_STATUSES: ReadonlyArray<number> = [429, 503];\n\n/**\n * Methods retried without an explicit opt-in.\n *\n * @remarks\n * A timeout does not tell you whether the server processed the request, so a retried `POST`\n * can double-charge. `retryNonIdempotent` opts out, per call, visibly.\n * @public\n */\nexport const IDEMPOTENT_METHODS: ReadonlyArray<string> = ['GET', 'HEAD'];\n"]}

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