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

package/dist/ts-extras.d.ts

@@ -2,6 +2,7 @@ import { Brand } from '@fgv/ts-utils';
 import { Conversion } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
 import { DateTime } from 'luxon';
+import { DetailedResult } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
 import { Hash as Hash_2 } from '@fgv/ts-utils';
 import { JsonObject } from '@fgv/ts-json-base';
@@ -12,6 +13,54 @@ import { Result } from '@fgv/ts-utils';
 import { Uuid } from '@fgv/ts-utils';
 import { Validator } from '@fgv/ts-utils';
 
+/**
+ * The security-relevant classification of an IP address.
+ *
+ * `'public'` is the only classification that describes an address which is
+ * globally routable on the public internet; every other value names a
+ * special-purpose range that a server-side fetch reaching untrusted input
+ * should not be able to reach by default.
+ *
+ * @public
+ */
+declare type AddressClassification = 
+/** Globally routable unicast — the only classification a default guard permits. */
+'public'
+/** `0.0.0.0/8` and `::` — "this host on this network"; routes to localhost on Linux. */
+| 'unspecified'
+/** `127.0.0.0/8` and `::1`. */
+| 'loopback'
+/**
+* `169.254.0.0/16` and `fe80::/10`. The IPv4 range contains the cloud
+* instance-metadata endpoint (`169.254.169.254`) and is the single
+* highest-value SSRF target.
+*/
+| 'link-local'
+/** RFC 1918 — `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`. */
+| 'private'
+/** RFC 4193 IPv6 unique-local — `fc00::/7`. */
+| 'unique-local'
+/** RFC 6598 carrier-grade NAT — `100.64.0.0/10`. Frequently carrier or container internal. */
+| 'carrier-grade-nat'
+/** RFC 2544 benchmarking — `198.18.0.0/15`. */
+| 'benchmarking'
+/** Documentation ranges — `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32`. */
+| 'documentation'
+/** IETF protocol assignments — `192.0.0.0/24` and `2001::/23`. */
+| 'protocol-assignment'
+/** `224.0.0.0/4` and `ff00::/8`. */
+| 'multicast'
+/** `255.255.255.255/32`. */
+| 'broadcast'
+/** Every other special-purpose or future-use range (e.g. `240.0.0.0/4`, `fec0::/10`). */
+| 'reserved';
+
+/**
+ * The address family of a parsed IP address literal.
+ * @public
+ */
+declare type AddressFamily = 'ipv4' | 'ipv6';
+
 /**
  * Key size in bytes for AES-256.
  * @public
@@ -164,10 +213,12 @@ declare namespace AiAssist {
         modelSpecKey,
         modelSpec,
         resolveEffectiveTools,
+        classifyJsonParseFailure,
         extractJsonText,
         fencedStringifiedJson,
         IFencedStringifiedJsonExtractorOptions,
         IFencedStringifiedJsonOptions,
+        JsonParseFailureReason,
         JsonTextExtractor,
         generateJsonCompletion,
         SMART_JSON_PROMPT_HINT,
@@ -416,12 +467,89 @@ declare const allModelCapabilities: ReadonlyArray<AiModelCapability>;
  */
 declare const allModelSpecKeys: ReadonlyArray<ModelSpecKey>;
 
+/**
+ * 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
+ */
+declare function allowAnyAddress(): IAddressGuard;
+
+/**
+ * Creates a policy that permits every address, including loopback, link-local
+ * and private ones.
+ *
+ * **This policy provides no protection whatsoever.** It classifies nothing,
+ * rejects nothing, and never fails — not even for an empty address list or an
+ * address that is not a well-formed literal. It exists so that choosing to go
+ * without an address guarantee is a deliberate, named, greppable act at the
+ * call site rather than something reachable by omission, and so that tests and
+ * genuinely trusted-input paths do not hand-roll something worse.
+ *
+ * It is the only correct choice in a browser, where neither name resolution nor
+ * redirect interposition is available and no address guarantee is possible.
+ *
+ * @returns the policy.
+ * @public
+ */
+declare function allowAnyAddressPolicy(): IAddressPolicy;
+
+/**
+ * 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
+ */
+declare function allowContentTypes(types: ReadonlyArray<string>): Result<IResponseHeadersGuard>;
+
 /**
  * All valid provider ID values, in the same order as the registry.
  * @public
  */
 declare const allProviderIds: ReadonlyArray<AiProviderId>;
 
+/**
+ * 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
+ */
+declare const ALWAYS_STRIPPED_HEADERS: ReadonlyArray<string>;
+
 /**
  * Maps Anthropic effort level to the `thinking.budget_tokens` integer that the
  * Anthropic API requires when `thinking.type === 'enabled'`.
@@ -497,6 +625,85 @@ declare function base64UrlNoPadDecode(encoded: string): Result<Uint8Array>;
  */
 declare function base64UrlNoPadEncode(data: Uint8Array): string;
 
+/**
+ * Creates the recommended address guard: resolves each hop's host and requires every resolved
+ * address to be globally routable public unicast.
+ *
+ * @remarks
+ * **Node only** — it resolves names, and no browser API returns a hostname's A/AAAA records.
+ * `allowAnyAddress()` is the honest choice there, and its name says so.
+ *
+ * This is the guard an entry point's `addressGuard` option takes. It is the resolving,
+ * hop-chain-aware half; the judgement itself belongs to
+ * {@link SaferFetch.blockPrivateNetworksPolicy}, which this guard delegates to unchanged. Keeping
+ * the adversarial classification matrix in one pure, synchronous implementation is what makes
+ * "did the address check run, and run correctly?" answerable by reading one file.
+ *
+ * The guard is invoked **once per redirect hop**, on the last entry of the chain. Hop 0 is not a
+ * special case: a guard that only validated the initial URL is defeated by a single `302` to
+ * `http://169.254.169.254/`.
+ *
+ * The URL-level constraints — `https:` unless `allowInsecureHttp`, plus the optional `allowHosts`
+ * and `allowPorts` allowlists — are checked **before** the name resolution, so a host the caller
+ * never allowlisted is refused by string comparison rather than handed to a resolver.
+ *
+ * ```typescript
+ * // A local Ollama sidecar: every deviation from the default posture is named and greppable.
+ * const guard = blockPrivateNetworks({
+ *   allowLoopback: true,
+ *   allowInsecureHttp: true,
+ *   allowHosts: ['localhost'],
+ *   allowPorts: [11434]
+ * });
+ * ```
+ *
+ * **What this does not protect against.** It validates a resolved address and the transport then
+ * re-resolves, so hostile DNS can answer the two lookups differently — the documented
+ * DNS-rebinding limit, which is open in this release. A strict `allowHosts` list is the
+ * recommended posture precisely because it shrinks that exposure to "an allowlisted host's own
+ * resolver is hostile".
+ *
+ * @param options - optional relaxations of the default posture, plus the resolver seam.
+ * @returns the guard. Construction cannot fail.
+ * @public
+ */
+declare function blockPrivateNetworks(options?: IBlockPrivateNetworksGuardOptions): IAddressGuard;
+
+/**
+ * Creates the recommended address policy: every address must be a globally
+ * routable public unicast address.
+ *
+ * Rejected, in both their plain and their IPv6-embedded encodings: loopback,
+ * the link-local range that carries the cloud instance-metadata endpoint
+ * (`169.254.169.254`), RFC 1918 private ranges, IPv6 unique-local, carrier-grade
+ * NAT (`100.64.0.0/10`), the unspecified address, multicast, broadcast,
+ * benchmarking, documentation and every other reserved range. The encoding
+ * bypasses covered are IPv4-mapped IPv6 (`::ffff:169.254.169.254`),
+ * IPv4-compatible IPv6, NAT64 (`64:ff9b::a9fe:a9fe`), 6to4 (`2002:a9fe:a9fe::`)
+ * and the shortened / octal / hexadecimal / decimal IPv4 literal forms
+ * (`127.1`, `0177.0.0.1`, `0x7f.1`, `2130706433`).
+ *
+ * **What this does not protect against.** The policy classifies addresses a
+ * caller has already resolved; it cannot see the address the connection
+ * ultimately uses. A hostile DNS server that answers the resolution with a
+ * public address and the connect with a private one is not stopped by this
+ * policy — closing that requires connecting to a pinned address. The policy
+ * also says nothing about scheme, host, port, redirects or response content.
+ *
+ * This is the **policy-layer** factory. It is not what a safer-fetch call's
+ * `addressGuard` option takes: an entry point takes an `IAddressGuard`, which is
+ * the asynchronous, hop-chain-aware, name-resolving half. `blockPrivateNetworks`
+ * (Node only) is the guard that resolves a hostname and delegates every resolved
+ * address to this policy; reach for that unless you are classifying an address
+ * list you already hold.
+ *
+ * @param options - optional {@link IBlockPrivateNetworksOptions | relaxations}
+ * of the default posture.
+ * @returns the policy. Construction cannot fail.
+ * @public
+ */
+declare function blockPrivateNetworksPolicy(options?: IBlockPrivateNetworksOptions): IAddressPolicy;
+
 /**
  * Calls the appropriate chat completion API for a given provider. Routes by
  * `apiFormat`: `'openai'` (xAI/OpenAI/Groq/Mistral — switches to Responses API
@@ -636,6 +843,92 @@ declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderI
  */
 declare function callProxiedListModels(proxyUrl: string, params: IProviderListModelsParams): Promise<Result<ReadonlyArray<IAiModelInfo>>>;
 
+/**
+ * Classifies a single IP address literal.
+ *
+ * The function is pure, synchronous, and deterministic — it performs no name
+ * resolution and no I/O. Input that is not an IP address literal (a DNS
+ * hostname, for instance) fails; callers that accept hostnames should treat a
+ * failure here as "not a literal" and resolve the name, then classify each
+ * resolved address.
+ *
+ * Accepted forms:
+ *
+ * - dotted-quad IPv4 (`169.254.169.254`)
+ * - the shortened and non-decimal IPv4 forms the WHATWG URL parser accepts
+ *   (`127.1`, `2130706433`, `0177.0.0.1`, `0x7f.1`)
+ * - IPv6, with or without `::` compression, optionally bracketed as a URL
+ *   `hostname` is (`[::1]`) and optionally carrying a zone id (`fe80::1%eth0`)
+ * - IPv6 forms that embed an IPv4 address — IPv4-mapped, IPv4-compatible,
+ *   NAT64 and 6to4 — which are classified by their embedded IPv4 address
+ *
+ * A trailing dot is accepted on an IPv4 literal (`127.0.0.1.`), matching URL
+ * hostname normalization.
+ *
+ * **Classify a URL's `hostname`, never the raw URL text.** This function does
+ * not apply IDNA/Unicode normalization, and that step is not cosmetic: the
+ * platform's URL parser reads `http://１２７.０.０.１/`, `http://127。0。0。1/` and
+ * even `http://⑫7.0.0.1/` as the host `127.0.0.1`, because IDNA normalizes
+ * fullwidth digits, the ideographic full stop and circled numbers to their
+ * ASCII equivalents. Handed one of those strings directly this function fails —
+ * which is fail-closed, but only because the caller is then expected to treat
+ * "not a literal" as "resolve it as a name". Reading `new URL(...).hostname`
+ * gets the normalization for free and is the only supported use.
+ *
+ * @param address - the address literal to classify.
+ * @returns `Success` with the {@link IClassifiedAddress | classification},
+ * or `Failure` if the supplied text is not a well-formed IP address literal.
+ * @public
+ */
+declare function classifyAddress(address: string): Result<IClassifiedAddress>;
+
+/**
+ * Classifies why a JSON-shaped LLM response would not parse, returning a
+ * {@link AiAssist.JsonParseFailureReason} a caller can branch on — repair the
+ * cheap cases, re-prompt the expensive ones, fail outright on the rest —
+ * instead of regex-matching an engine-specific `JSON.parse` message.
+ *
+ * Pass the same raw model text you handed
+ * {@link AiAssist.fencedStringifiedJson} or {@link AiAssist.extractJsonText};
+ * this applies the same BOM / whitespace / fence / preamble handling before
+ * scanning, and reports `offset` against that original text.
+ *
+ * Classification is **structural and deliberately conservative**. The scan
+ * walks the JSON grammar itself rather than reading the engine's error string,
+ * so its verdicts are stable across Node versions — and any fault it cannot
+ * name with confidence comes back as `'unknown'` rather than a guess. In
+ * particular an input that opened a structure and never closed it (the
+ * truncated-response shape {@link AiAssist.extractJsonText} already diagnoses)
+ * classifies as `'unknown'` here; the two diagnostics are complementary, not
+ * competing.
+ *
+ * This never fails and never repairs — it only names the fault. It is a
+ * diagnostic on the failure path, so calling it on text that parses fine is
+ * harmless but pointless: it returns `'unknown'`.
+ *
+ * @example
+ * ```ts
+ * const parsed = fencedStringifiedJson({ inner }).convert(raw);
+ * if (parsed.isFailure()) {
+ *   const reason = classifyJsonParseFailure(raw);
+ *   switch (reason.kind) {
+ *     case 'unquoted-property-name': // cheap to repair
+ *     case 'single-quoted-property-name':
+ *       break;
+ *     case 'elided-member':
+ *     case 'unterminated-property-name': // worth a re-prompt
+ *       break;
+ *     default: // 'unknown' — fail outright
+ *   }
+ * }
+ * ```
+ *
+ * @param text - Raw model output (the same string handed to the extractor).
+ * @returns A {@link AiAssist.JsonParseFailureReason}.
+ * @public
+ */
+declare function classifyJsonParseFailure(text: string): JsonParseFailureReason;
+
 declare namespace Constants {
     export {
         ENCRYPTED_FILE_FORMAT,
@@ -710,8 +1003,22 @@ declare function createEncryptedFile<TMetadata = JsonValue>(params: ICreateEncry
  */
 declare function createEncryptedFileConverter<TMetadata = JsonValue>(metadataConverter?: Converter<TMetadata>): Converter<IEncryptedFile<TMetadata>>;
 
+/**
+ * Creates a zip file from an array of files whose contents are either text or raw bytes.
+ *
+ * @remarks
+ * String contents are encoded as UTF-8; `Uint8Array` contents are stored verbatim, so
+ * arbitrary binary payloads round-trip through the archive unchanged.
+ * @public
+ */
+declare function createZipFromFiles(files: ReadonlyArray<IZipFile>, options?: ICreateZipOptions): Result<Uint8Array>;
+
 /**
  * Creates a zip file from an array of text files.
+ *
+ * @remarks
+ * Contents are encoded as UTF-8. Use `createZipFromFiles` to write entries whose
+ * contents are raw bytes.
  * @public
  */
 declare function createZipFromTextFiles(files: ReadonlyArray<IZipTextFile>, options?: ICreateZipOptions): Result<Uint8Array>;
@@ -842,6 +1149,13 @@ declare const DEFAULT_ALGORITHM: "AES-256-GCM";
  */
 declare const DEFAULT_ANTHROPIC_MAX_TOKENS: number;
 
+/**
+ * Default deadline to first response headers, in milliseconds. A host that has not sent
+ * headers in ten seconds is not answering.
+ * @public
+ */
+declare const DEFAULT_HEADERS_TIMEOUT_MS: number;
+
 /**
  * Default PBKDF2 iterations for key store encryption.
  * Higher than regular files since this protects the master key vault.
@@ -849,6 +1163,29 @@ declare const DEFAULT_ANTHROPIC_MAX_TOKENS: number;
  */
 declare const DEFAULT_KEYSTORE_ITERATIONS: number;
 
+/**
+ * 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
+ */
+declare const DEFAULT_MAX_REDIRECTS: number;
+
+/**
+ * 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
+ */
+declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+
 /**
  * Default capability config used by `callProviderListModels` when callers
  * don't supply their own. Patterns are intentionally narrow — false
@@ -866,6 +1203,23 @@ declare const DEFAULT_MODEL_CAPABILITY_CONFIG: IAiModelCapabilityConfig;
  */
 declare const DEFAULT_RANGEOF_FORMATS: RangeOfFormats;
 
+/**
+ * Default base delay for {@link SaferFetch.IRetryPolicy | retry} backoff, in milliseconds.
+ * @public
+ */
+declare const DEFAULT_RETRY_BASE_DELAY_MS: number;
+
+/**
+ * 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
+ */
+declare const DEFAULT_RETRY_MAX_DELAY_MS: number;
+
 /**
  * Default PBKDF2 iterations for secret-level key derivation.
  * Lower than keystore encryption since these are used more frequently.
@@ -873,6 +1227,14 @@ declare const DEFAULT_RANGEOF_FORMATS: RangeOfFormats;
  */
 declare const DEFAULT_SECRET_ITERATIONS: number;
 
+/**
+ * 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
+ */
+declare const DEFAULT_TIMEOUT_MS: number;
+
 /**
  * Derives an asymmetric keypair *deterministically* from a fixed secret seed
  * using `globalThis.crypto.subtle`, shared by the Node and browser
@@ -1292,6 +1654,155 @@ declare function fencedStringifiedJson(options?: IFencedStringifiedJsonExtractor
  */
 declare function fencedStringifiedJson<T>(options: IFencedStringifiedJsonOptions<T>): Converter<T>;
 
+/**
+ * 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
+ */
+declare 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;
+};
+
+/**
+ * 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
+ */
+declare type FetchTimeoutPhase = 'headers' | 'body' | 'overall';
+
 /**
  * Formats a list of items using the supplied template and formatter, one result
  * per output line.
@@ -1475,6 +1986,23 @@ declare function hexDecode(encoded: string): Result<Uint8Array>;
  */
 declare function hexEncode(data: Uint8Array): string;
 
+/**
+ * Resolves a hostname to every address it names.
+ *
+ * @remarks
+ * Injectable so that the resolving half of an address guard is testable without a network — a
+ * guard test that performs a real lookup fails in CI for reasons unrelated to the guard, and a
+ * guard test that could reach `169.254.169.254` is worse than flaky.
+ *
+ * An implementation must return a `Failure` rather than reject: `node:dns` rejects on
+ * `ENOTFOUND`, `EAI_AGAIN` and friends, and an entry point documented to always return a
+ * `Result` must not let that escape as a throw. {@link SaferFetch.nodeHostResolver} converts.
+ *
+ * @param hostname - The host to resolve, with no surrounding brackets.
+ * @public
+ */
+declare type HostResolver = (hostname: string) => Promise<Result<ReadonlyArray<string>>>;
+
 /**
  * HPKE base mode (RFC 9180) — `DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM`.
  *
@@ -1678,6 +2206,85 @@ declare interface IAddKeyPairResult {
     readonly warning?: string;
 }
 
+/**
+ * The evidence behind an allowed address-policy decision.
+ * @public
+ */
+declare interface IAddressCheckVerdict {
+    /** The {@link IAddressPolicy.name | name} of the policy that produced the verdict. */
+    readonly policy: string;
+    /**
+     * The classification of every address the policy examined, in the order
+     * supplied. Empty for {@link allowAnyAddressPolicy}, which classifies nothing.
+     */
+    readonly addresses: ReadonlyArray<IClassifiedAddress>;
+}
+
+/**
+ * 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
+ */
+declare 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>>;
+}
+
+/**
+ * A pure, synchronous decision over a set of IP addresses.
+ *
+ * A policy performs no name resolution and no I/O: a caller resolves a
+ * hostname to its addresses and hands the whole list to
+ * {@link IAddressPolicy.checkAddresses}. The list contract is
+ * **reject-if-any** — a hostname that resolves to one public and one private
+ * address is disallowed, because without connect-time address pinning there is
+ * no guarantee which address the connection will use.
+ *
+ * @public
+ */
+declare interface IAddressPolicy {
+    /**
+     * A stable, greppable identifier for the posture this policy implements.
+     * Surfaced in the failure message when an address is disallowed.
+     */
+    readonly name: string;
+    /**
+     * Decides whether a connection may be made to a destination that resolved to
+     * `addresses`.
+     *
+     * @param addresses - every address the destination resolved to, or the
+     * single literal address when the destination was an IP literal.
+     * @returns `Success` with the {@link IAddressCheckVerdict | verdict} when
+     * *every* address is permitted, `Failure` naming every address that is not.
+     * An empty list is a failure for any policy that offers a guarantee: nothing
+     * was verified, so nothing may be reached.
+     */
+    checkAddresses(addresses: ReadonlyArray<string>): Result<IAddressCheckVerdict>;
+}
+
 /**
  * Options for adding an Argon2id password-derived secret.
  * @public
@@ -2745,6 +3352,71 @@ declare interface IArgon2idProvider {
     argon2id(password: Uint8Array | string, salt: Uint8Array, params: IArgon2idParams, options?: IArgon2idKeyingOptions): Promise<Result<Uint8Array>>;
 }
 
+/**
+ * Options for {@link SaferFetch.blockPrivateNetworks}.
+ * @public
+ */
+declare interface IBlockPrivateNetworksGuardOptions extends IBlockPrivateNetworksOptions {
+    /**
+     * Restricts every hop to these hostnames. Absent means any hostname.
+     *
+     * @remarks
+     * Matching is case-insensitive and exact — no wildcards and no suffix matching, because
+     * `endsWith('.example.com')` is the classic host-allowlist bypass (`evil-example.com`,
+     * `example.com.attacker.net`) and a primitive that offers the convenient form invites it.
+     * List the hosts.
+     *
+     * **A host allowlist is the recommended posture**, and it is stronger than address
+     * classification alone: with one, DNS rebinding can only be mounted by an allowlisted host's
+     * own resolver, which is a far smaller surface than "any hostname the caller was handed".
+     */
+    readonly allowHosts?: ReadonlyArray<string>;
+    /**
+     * Restricts every hop to these ports. Absent means any port.
+     *
+     * @remarks
+     * A URL with no explicit port is checked against the scheme's default — `443` for `https:`,
+     * `80` for `http:` — so `allowPorts: [443]` accepts `https://example.com/`.
+     */
+    readonly allowPorts?: ReadonlyArray<number>;
+    /**
+     * Permits `http:` hops. **Off by default**, so this guard requires `https:`.
+     *
+     * @remarks
+     * The core refuses everything that is not `http:` or `https:` and deliberately chooses
+     * between those two here rather than there, because the choice is a posture rather than a
+     * structural rule. Plaintext HTTP is exposed to a network-position attacker and is the scheme
+     * every SSRF payload reaches for, so the polarity matches `allowLoopback`: deny by default,
+     * opt in visibly, and let a reviewer grep for the opt-in.
+     */
+    readonly allowInsecureHttp?: boolean;
+    /**
+     * Name resolution. Defaults to {@link SaferFetch.nodeHostResolver}.
+     *
+     * @remarks
+     * Present so the guard is unit-testable with no network. It is **not** a hook through which
+     * DNS rebinding can be closed: swapping the resolver changes only the address the guard
+     * validates, while the transport still connects by hostname and resolves again. Closing that
+     * requires a pinning transport — see `IGuardVerdict.pinnedAddress`.
+     */
+    readonly resolve?: HostResolver;
+}
+
+/**
+ * Options shared by {@link blockPrivateNetworksPolicy} and the address guard built over it.
+ * @public
+ */
+declare interface IBlockPrivateNetworksOptions {
+    /**
+     * Permits `127.0.0.0/8` and `::1` (and their IPv4-mapped forms). Off by
+     * default: the polarity that ships a guard permitting `http://127.0.0.1:6379/`
+     * so a local-development convenience keeps working is the wrong one. A
+     * caller talking to a local sidecar opts in here, and the opt-in is
+     * independently greppable at the call site.
+     */
+    readonly allowLoopback?: boolean;
+}
+
 /**
  * A single chat message in OpenAI format.
  * @public
@@ -2791,6 +3463,36 @@ declare interface IChatRequest {
     readonly messages: ReadonlyArray<IChatMessage>;
 }
 
+/**
+ * The result of classifying a single IP address literal.
+ * @public
+ */
+declare interface IClassifiedAddress {
+    /** The address exactly as supplied to {@link classifyAddress}. */
+    readonly address: string;
+    /**
+     * A canonical textual form of the address: dotted-quad for IPv4, and
+     * lowercase RFC 5952 hex-group form (with `::` run compression) for IPv6.
+     * Note that IPv6 addresses embedding an IPv4 address canonicalize to their
+     * hex-group form (`::ffff:a9fe:a9fe`), not to the dotted-quad mixed form;
+     * `embeddedIpv4` carries the readable IPv4 value.
+     */
+    readonly canonical: string;
+    /** The address family of the literal as supplied — never the embedded family. */
+    readonly family: AddressFamily;
+    /**
+     * The classification used for policy decisions. For an IPv6 address that
+     * embeds an IPv4 address, this is the classification of the *embedded* IPv4
+     * address.
+     */
+    readonly classification: AddressClassification;
+    /**
+     * Present exactly when `classification` was derived from an IPv4 address
+     * embedded in this IPv6 address, and absent otherwise.
+     */
+    readonly embeddedIpv4?: IEmbeddedIpv4;
+}
+
 /**
  * Result of context validation, containing details about missing variables.
  * @public
@@ -3173,6 +3875,16 @@ declare interface ICryptoProvider {
     verifyHmacSha256(key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<Result<boolean>>;
 }
 
+/**
+ * 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
+ */
+declare const IDEMPOTENT_METHODS: ReadonlyArray<string>;
+
 /**
  * Parameters for creating a {@link DirectEncryptionProvider}.
  * @public
@@ -3194,6 +3906,17 @@ declare interface IDirectEncryptionProviderParams {
     readonly boundSecretName?: string;
 }
 
+/**
+ * The IPv4 address an IPv6 address embedded, and the way it embedded it.
+ * @public
+ */
+declare interface IEmbeddedIpv4 {
+    /** The encoding that carried the IPv4 address. */
+    readonly kind: Ipv4EmbeddingKind;
+    /** The dotted-quad form of the embedded IPv4 address. */
+    readonly address: string;
+}
+
 /**
  * Result of a raw-byte AES-256-GCM encryption via
  * {@link CryptoUtils.ICryptoProvider.encryptBytes | encryptBytes}. The
@@ -3512,6 +4235,34 @@ declare interface IFencedStringifiedJsonOptions<T> extends IFencedStringifiedJso
     readonly inner: Converter<T> | Validator<T>;
 }
 
+/**
+ * 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
+ */
+declare interface IFetchTransport {
+    readonly name: string;
+    fetch(url: URL, init: RequestInit, hints: IFetchTransportHints): Promise<Result<Response>>;
+}
+
+/**
+ * Out-of-band information a transport may need that `RequestInit` cannot express.
+ * @public
+ */
+declare 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;
+}
+
 /**
  * Provider-specific config for Gemini Flash Image.
  * @public
@@ -3676,6 +4427,38 @@ declare interface IGrokImagineModelOptions extends INamedModelFamilyConfig {
     readonly config: IGrokImagineImageGenerationConfig;
 }
 
+/**
+ * An address guard's decision about a hop.
+ * @public
+ */
+declare 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;
+}
+
 /**
  * Output of {@link HpkeProvider.sealBase}.
  *
@@ -4560,6 +5343,26 @@ declare interface IProviderListModelsParams {
     readonly endpoint?: string;
 }
 
+/**
+ * The way an IPv6 address carried the IPv4 address whose classification was used.
+ *
+ * Each of these is a documented SSRF bypass: an address such as
+ * `::ffff:169.254.169.254` is an IPv6 address by family, but the address the
+ * connection actually reaches is the embedded IPv4 one, so the embedded
+ * address is what must be classified.
+ *
+ * @public
+ */
+declare type Ipv4EmbeddingKind = 
+/** `::ffff:0:0/96` — the IPv4-mapped IPv6 form. */
+'ipv4-mapped'
+/** `::/96` — the deprecated (RFC 4291) IPv4-compatible form. */
+| 'ipv4-compatible'
+/** `64:ff9b::/96` — the RFC 6052 well-known NAT64 prefix. */
+| 'nat64'
+/** `2002::/16` — the RFC 3056 6to4 form, whose IPv4 lives in bits 16..47. */
+| '6to4';
+
 /**
  * Result of removing a secret from the key store.
  * @public
@@ -4578,6 +5381,46 @@ declare interface IRemoveSecretResult {
     readonly warning?: string;
 }
 
+/**
+ * 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
+ */
+declare interface IRequestGuard {
+    readonly name: string;
+    check(request: ISaferFetchRequest, chain: ReadonlyArray<IRequestHop>): Promise<Result<ISaferFetchRequest>>;
+}
+
+/**
+ * One hop in a redirect chain. Entry 0 is the caller's original request.
+ * @public
+ */
+declare 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;
+}
+
 /**
  * Required version of options with all fields populated.
  * @internal
@@ -4589,6 +5432,19 @@ declare interface IRequiredMustacheTemplateOptions {
     readonly escape: MustacheEscapeStrategy;
 }
 
+/**
+ * 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
+ */
+declare interface IResolvedGuards {
+    /** Caller-supplied; there is no default. */
+    readonly address: IAddressGuard;
+    readonly request: IRequestGuard;
+    readonly responseHeaders: IResponseHeadersGuard;
+    readonly responseBody: IResponseBodyGuard;
+}
+
 /**
  * The resolved, merged wire parameters for an image generation request.
  * Built from the layered options and ready for provider-specific encoding.
@@ -4635,6 +5491,106 @@ declare interface IResolvedThinkingConfig {
     readonly otherParams?: JsonObject;
 }
 
+/**
+ * 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
+ */
+declare interface IResponseBodyGuard {
+    readonly name: string;
+    check(body: Uint8Array, head: ISaferFetchResponseHead): Promise<Result<true>>;
+}
+
+/**
+ * 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
+ */
+declare 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>>;
+}
+
+/**
+ * Opt-in retry policy.
+ *
+ * @remarks
+ * **Retry is off by default and has to be asked for.** A primitive that silently retries
+ * changes the semantics of every call site and amplifies load against a service that is already
+ * struggling.
+ *
+ * Two rules are load-bearing rather than incidental, and are worth reading before enabling this:
+ *
+ * **Every attempt re-runs the address guard from hop 0 — a full re-walk, never a resume and
+ * never a cached verdict.** Reusing an earlier attempt's verdict would make retry its own
+ * DNS-rebinding vector: an attacker needs the guard to pass once and a connect to land on a
+ * private address, so `N` connects against **one** check multiplies their odds by the retry
+ * count — and a retry delay is precisely when a short-TTL rebind lands. A resume is
+ * independently wrong because the redirect chain is not stable across attempts: attempt 2's
+ * server may answer with a different `Location`, so revalidating only the current hop would
+ * validate a chain the request no longer follows. The consequence is that retries cost more
+ * than a naive implementation would suggest — each carries full re-resolution — and that cost
+ * is deliberate.
+ *
+ * **The overall deadline is the ceiling.** Retries consume `timeoutMs` and never reset it, so
+ * `{ timeoutMs: 30_000, retry: { attempts: 3 } }` is a thirty-second call, not a two-minute
+ * one. When the remaining budget is shorter than the computed delay, the call fails with the
+ * attempt's own failure rather than sleeping past its deadline.
+ * @public
+ */
+declare interface IRetryPolicy {
+    /**
+     * Additional attempts after the first, **not** a total. `attempts: 2` means up to three
+     * requests. Must be a non-negative integer; `0` disables retry.
+     */
+    readonly attempts: number;
+    /**
+     * First backoff delay, in milliseconds, doubled per attempt before jitter. Default
+     * {@link SaferFetch.DEFAULT_RETRY_BASE_DELAY_MS}.
+     */
+    readonly baseDelayMs?: number;
+    /**
+     * Ceiling on any single delay, in milliseconds. Default
+     * {@link SaferFetch.DEFAULT_RETRY_MAX_DELAY_MS}. Also clamps a server-supplied
+     * `Retry-After`, which is the security-relevant half of its job.
+     */
+    readonly maxDelayMs?: number;
+    /**
+     * Retries `POST` / `PUT` / `PATCH` / `DELETE` as well as `GET` / `HEAD`. Default `false`.
+     *
+     * @remarks
+     * Off by default because a timeout does not tell you whether the server processed the
+     * request: a retried `POST` after a timeout can double-charge. Turn it on for endpoints you
+     * know are idempotent — an idempotency key, a `PUT` of a whole resource — and not otherwise.
+     */
+    readonly retryNonIdempotent?: boolean;
+    /**
+     * Honors a `Retry-After` header on `429` and `503`. Default `true`.
+     *
+     * @remarks
+     * Always clamped to `maxDelayMs`, whatever this is set to. The header is chosen by the
+     * server, which in this threat model may be the adversary.
+     */
+    readonly respectRetryAfter?: boolean;
+}
+
 /**
  * Determines whether a concrete (already-resolved) Anthropic model id uses the adaptive
  * thinking wire shape (`thinking: { type: 'adaptive' }` + top-level `output_config.effort`)
@@ -4661,6 +5617,182 @@ declare interface IResolvedThinkingConfig {
  */
 declare function isAdaptiveThinkingModel(descriptor: IAiProviderDescriptor, modelId: string): boolean;
 
+/**
+ * Options for the validating form of {@link SaferFetch.saferFetchJson}.
+ *
+ * @remarks
+ * `converter` is **required** here, and `T` is inferred from it. There is deliberately no way
+ * to assert a `T` without supplying the converter that evidences it at runtime: a caller-named
+ * type with nothing checking it is a claim the primitive cannot keep. Omit the whole options
+ * type and the value comes back as `JsonValue`, which is what the wire actually guarantees.
+ * @public
+ */
+declare interface ISaferFetchJsonOptions<T> extends ISaferFetchOptions {
+    /** Applied to the parsed JSON, taking the caller from wire to validated `T` in one step. */
+    readonly converter: Converter<T> | Validator<T>;
+}
+
+/**
+ * Options common to every safer-fetch entry point.
+ * @public
+ */
+declare 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 request a safer-fetch call is about to issue.
+ * @public
+ */
+declare interface ISaferFetchRequest {
+    readonly url: URL;
+    readonly method: SaferFetchMethod;
+    /** Header names are lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string | Uint8Array;
+}
+
+/**
+ * A successful safer-fetch response.
+ * @public
+ */
+declare 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;
+}
+
+/**
+ * Response status and headers, available before any body bytes are read.
+ * @public
+ */
+declare 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;
+}
+
 /**
  * Checks if a JSON object appears to be an encrypted file.
  * Uses the format field as a discriminator.
@@ -4923,7 +6055,20 @@ declare interface IYamlSerializeOptions {
 }
 
 /**
- * Simple interface for a file to be added to a zip file.
+ * Interface for a file to be added to a zip file, whose contents are either text or
+ * raw bytes.
+ *
+ * @remarks
+ * String contents are encoded as UTF-8; `Uint8Array` contents are stored verbatim.
+ * @public
+ */
+declare interface IZipFile {
+    readonly path: string;
+    readonly contents: string | Uint8Array;
+}
+
+/**
+ * Simple interface for a text file to be added to a zip file.
  * @public
  */
 declare interface IZipTextFile {
@@ -4951,6 +6096,57 @@ declare interface JarRecordParserOptions {
     readonly fixedContinuationSize?: number;
 }
 
+/**
+ * Typed reason a JSON-shaped LLM response failed to parse, so a caller can
+ * branch on the failure class instead of regex-matching the engine's
+ * `JSON.parse` message (whose wording varies across V8 / Node versions).
+ *
+ * Every classified arm describes a fault at an **object property-name
+ * position** — the position an LLM most often gets wrong, and the one whose
+ * repair strategy differs most by case:
+ *
+ * - `'unquoted-property-name'`: a bare identifier where a quoted name belongs
+ *   (`{ key: 1 }`). `token` is the identifier run, `offset` its first
+ *   character. Identifier recognition is ASCII-only, so a non-ASCII bare name
+ *   (`{ ключ: 1 }`) reports `'unknown'` rather than being named.
+ * - `'single-quoted-property-name'`: a single-quoted name (`{ 'key': 1 }`).
+ *   `token` is the quoted literal (or just `'` if it never closes), `offset`
+ *   the opening quote.
+ * - `'unterminated-property-name'`: a name whose closing `"` is missing, and
+ *   whose body swallowed structural text (`{ "key: 1 }`). `token` is the
+ *   unterminated fragment, `offset` the opening quote.
+ * - `'elided-member'`: a `,` where a member is expected — a leading or doubled
+ *   comma in an object (`{ , "a": 1 }`, `{ "a":1, , "b":2 }`) or an array
+ *   (`[1, , 2]`). `token` is `','`, `offset` its position.
+ * - `'unknown'`: the catch-all. The scan reached the end of the text, or hit a
+ *   fault it cannot name with confidence, and reports nothing rather than
+ *   guessing. Truncated responses, missing colons, trailing commas, bad number
+ *   literals, and anything else not listed above land here.
+ *
+ * `offset` is a 0-based index into the `text` passed to
+ * {@link AiAssist.classifyJsonParseFailure}, not into the extracted substring.
+ * @public
+ */
+declare type JsonParseFailureReason = {
+    readonly kind: 'unquoted-property-name';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'single-quoted-property-name';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'unterminated-property-name';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'elided-member';
+    readonly token: string;
+    readonly offset: number;
+} | {
+    readonly kind: 'unknown';
+};
+
 /**
  * Controls the optional system-prompt augmentation applied by
  * {@link AiAssist.generateJsonCompletion}.
@@ -5817,6 +7013,35 @@ declare const modelSpec: Converter<ModelSpec>;
 
 /**
  * Known context keys for model specification maps.
+ *
+ * @remarks
+ * Two axes live here and nothing else: the **quality tier** (`base` / `advanced`
+ * / `frontier`) selects the *completion* model, and `image` / `embedding` select
+ * the non-completion modalities.
+ *
+ * There is deliberately **no `tools` or `thinking` key**. Both existed before the
+ * quality-tier axis landed and were removed with it: server-side tools and
+ * reasoning effort are orthogonal *request* params that ride on top of whatever
+ * model the tier already selected — they never select a model. A tool-using or
+ * thinking-enabled call passes a tier like any other call (omit → `base`, or
+ * `'advanced'` / `'frontier'`) and sets the tools / thinking request params
+ * independently. Thinking composes with any tier without a tier-level capability
+ * check — but that is a statement about the tier axis, not a claim that every
+ * provider supports thinking: several descriptors declare
+ * `thinkingMode: 'unsupported'` (e.g. `copy-paste`, `groq`, `mistral`, `ollama`,
+ * `openai-compat`).
+ *
+ * Thinking availability is declared **per provider**, on the descriptor's
+ * `thinkingMode`; the descriptor does not encode per-model thinking availability at
+ * all, so a provider that declares support may still have individual models its own
+ * API rejects thinking on. (`adaptiveThinkingModelPrefixes` is per-model but selects
+ * a wire *shape*, not availability.) What the tier axis guarantees is therefore
+ * narrow and exact: a tier selects a model within one provider and never changes the
+ * provider, so it never changes `thinkingMode`.
+ *
+ * Do not add a `'tools'` or `'thinking'` key here, and do not hand-roll a
+ * `resolveModel` + `resolveModelAlias` walk to emulate one — call
+ * `resolveProviderModel` with the tier you want.
  * @public
  */
 declare type ModelSpecKey = 'base' | 'advanced' | 'frontier' | 'image' | 'embedding';
@@ -6209,6 +7434,24 @@ declare class NodeCryptoProvider implements ICryptoProvider {
  */
 declare const nodeCryptoProvider: NodeCryptoProvider;
 
+/**
+ * The default {@link SaferFetch.HostResolver}: `node:dns`'s `lookup`, returning every address.
+ *
+ * @remarks
+ * `lookup` rather than `resolve4`/`resolve6` deliberately. `lookup` goes through the operating
+ * system's resolver — the same path `fetch`'s connect takes — so it sees `/etc/hosts`, `nsswitch`
+ * ordering, and any local override. `resolve4` queries DNS directly and would miss a
+ * `hosts`-file entry pointing an allowlisted name at `127.0.0.1`, which is a bypass rather than
+ * a curiosity.
+ *
+ * `all: true` because the list contract is reject-if-any: a name resolving to one public and one
+ * private address must be refused, and asking for one address would hide the second.
+ *
+ * A rejected lookup (`ENOTFOUND`, `EAI_AGAIN`, …) becomes a `Failure`, never a throw.
+ * @public
+ */
+declare const nodeHostResolver: HostResolver;
+
 /**
  * Model IDs for OpenAI thinking-capable models.
  * @public
@@ -6240,6 +7483,23 @@ declare function parseRecordJarLines(lines: string[], options?: JarRecordParserO
  */
 declare const pbkdf2KeyDerivationParams: Converter<IPbkdf2KeyDerivationParams>;
 
+/**
+ * The {@link SaferFetch.IFetchTransport | transport} that wraps `globalThis.fetch`.
+ *
+ * @remarks
+ * **Fails loudly when asked to honor a `pinnedAddress`.** `globalThis.fetch` connects by
+ * hostname and re-resolves DNS itself, so it cannot honor a pin. Ignoring the hint instead
+ * would mean that a deployment which wired an address-pinning guard but forgot the matching
+ * pinning transport gets exactly the DNS-rebinding exposure it believed it had closed, and
+ * gets it silently. A primitive that advertises a guarantee it does not have is worse than no
+ * primitive — and that applies to future versions of itself.
+ *
+ * No guard in this release populates `pinnedAddress`, so the interlock is dormant. It is here
+ * so that populating it later is an additive change that cannot be made unsafely.
+ * @public
+ */
+declare const platformFetchTransport: IFetchTransport;
+
 /**
  * Returns the canonical `CryptoUtils.KeyStore.KeyStore` secret name for a provider's API key,
  * of the form `provider:<providerId>`. Apps that store provider API keys in a `KeyStore`
@@ -6438,6 +7698,13 @@ declare namespace RecordJar {
 }
 export { RecordJar }
 
+/**
+ * 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
+ */
+declare const REDIRECT_STATUSES: ReadonlyArray<number>;
+
 /**
  * Resolves the effective tools for a completion call.
  *
@@ -6460,10 +7727,20 @@ declare function resolveEffectiveTools(descriptor: IAiProviderDescriptor, settin
  * `modelPrefix` is the longest prefix of `modelId`. Ties are broken by
  * first-encountered.
  *
+ * @remarks
+ * `modelId` may be either a concrete provider model id or an fgv model alias
+ * (`@<provider>:<role>`, see `MODEL_ALIAS_SIGIL`) — it is resolved via
+ * `resolveModelAlias` against `descriptor.aliases` before prefix matching,
+ * so both forms select the same capability. A raw provider id passes through
+ * unchanged. An alias that is not registered on `descriptor` (or is cyclic)
+ * names no model and yields `undefined` rather than falling through to the
+ * `modelPrefix: ''` catch-all.
+ *
  * @param descriptor - The provider descriptor
- * @param modelId - The resolved embedding model id
- * @returns The matching capability, or `undefined` when no rule matches or the
- *   provider declares no embedding capabilities.
+ * @param modelId - The embedding model id — concrete or an fgv alias
+ * @returns The matching capability, or `undefined` when no rule matches, the
+ *   provider declares no embedding capabilities, or `modelId` is an
+ *   unresolvable alias.
  * @public
  */
 declare function resolveEmbeddingCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiEmbeddingModelCapability | undefined;
@@ -6476,10 +7753,20 @@ declare function resolveEmbeddingCapability(descriptor: IAiProviderDescriptor, m
  * order does not matter for correctness — only for tie-breaking among rules
  * with identical-length prefixes (an unusual case).
  *
+ * @remarks
+ * `modelId` may be either a concrete provider model id or an fgv model alias
+ * (`@<provider>:<role>`, see `MODEL_ALIAS_SIGIL`) — it is resolved via
+ * `resolveModelAlias` against `descriptor.aliases` before prefix matching,
+ * so both forms select the same capability. A raw provider id passes through
+ * unchanged. An alias that is not registered on `descriptor` (or is cyclic)
+ * names no model and yields `undefined` rather than falling through to the
+ * `modelPrefix: ''` catch-all.
+ *
  * @param descriptor - The provider descriptor
- * @param modelId - The resolved image model id
- * @returns The matching capability, or `undefined` when no rule matches or
- *   the provider declares no image-generation capabilities.
+ * @param modelId - The image model id — concrete or an fgv alias
+ * @returns The matching capability, or `undefined` when no rule matches, the
+ *   provider declares no image-generation capabilities, or `modelId` is an
+ *   unresolvable alias.
  * @public
  */
 declare function resolveImageCapability(descriptor: IAiProviderDescriptor, modelId: string): IAiImageModelCapability | undefined;
@@ -6560,6 +7847,20 @@ declare function resolveModelAlias(descriptor: IAiProviderDescriptor, model: str
  * `ModelSpec` branch is selected first; the resulting string — which may itself
  * be an fgv alias — is then resolved to a concrete id.
  *
+ * **This is the whole model-selection surface — do not hand-roll the walk.**
+ * Callers should pass the `ModelSpecKey` they want and use the concrete id
+ * this returns; a manual `resolveModel` + `resolveModelAlias` sequence is
+ * both redundant and easy to get wrong (it is how alias-form ids leak into
+ * capability lookups such as `resolveImageCapability`).
+ *
+ * **`context` carries the quality tier and the modality — never tools or
+ * thinking.** `ModelSpecKey` has no `tools` / `thinking` key: server-side
+ * tools and reasoning effort are orthogonal request params that ride on top of
+ * whatever model the tier selected, and never select a model. A tool-path caller
+ * passes a tier like any other caller — omit `context` for `base`, or pass
+ * `'advanced'` / `'frontier'` — and sets the tools / thinking request params
+ * separately.
+ *
  * @param descriptor - The provider descriptor (supplies `defaultModel` and `aliases`).
  * @param modelOverride - An optional caller-supplied `ModelSpec` that takes precedence
  * over `descriptor.defaultModel`. May itself contain or be an alias.
@@ -6569,6 +7870,220 @@ declare function resolveModelAlias(descriptor: IAiProviderDescriptor, model: str
  */
 declare function resolveProviderModel(descriptor: IAiProviderDescriptor, modelOverride: ModelSpec | undefined, context?: ModelSpecKey): Result<string>;
 
+/**
+ * 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
+ */
+declare const RETRY_AFTER_STATUSES: ReadonlyArray<number>;
+
+/**
+ * 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
+ */
+declare const RETRYABLE_HTTP_STATUSES: ReadonlyArray<number>;
+
+declare namespace SaferFetch {
+    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,
+        FetchFailureReason,
+        FetchTimeoutPhase,
+        IRetryPolicy,
+        IAddressGuard,
+        IFetchTransport,
+        IFetchTransportHints,
+        IGuardVerdict,
+        IRequestGuard,
+        IRequestHop,
+        IResolvedGuards,
+        IResponseBodyGuard,
+        IResponseHeadersGuard,
+        ISaferFetchOptions,
+        ISaferFetchRequest,
+        ISaferFetchResponse,
+        ISaferFetchResponseHead,
+        SaferFetchMethod,
+        SaferFetchRedirectPolicy,
+        allowAnyAddress,
+        allowContentTypes,
+        platformFetchTransport,
+        saferFetchBytes,
+        saferFetchJson,
+        saferFetchText,
+        ISaferFetchJsonOptions,
+        allowAnyAddressPolicy,
+        blockPrivateNetworksPolicy,
+        IAddressCheckVerdict,
+        IAddressPolicy,
+        IBlockPrivateNetworksOptions,
+        blockPrivateNetworks,
+        nodeHostResolver,
+        HostResolver,
+        IBlockPrivateNetworksGuardOptions,
+        classifyAddress,
+        AddressClassification,
+        AddressFamily,
+        IClassifiedAddress,
+        IEmbeddedIpv4,
+        Ipv4EmbeddingKind
+    }
+}
+export { SaferFetch }
+
+/**
+ * Fetches a URL and returns the raw response bytes, subject to the scheme check, the address
+ * guard, the request and response guards, the deadlines, and the response size cap.
+ *
+ * @remarks
+ * **What this does not protect against.** It is not a sandbox: a caller who wants to reach
+ * `127.0.0.1` can call `globalThis.fetch` directly, so this guards untrusted *data*, never
+ * untrusted *code in the same process*. It does no certificate pinning and adds nothing
+ * against a network-position attacker — TLS is that control. It does not resist DNS rebinding:
+ * an address guard validates a resolved address and the transport then re-resolves, so a
+ * hostile resolver can answer the two lookups differently. And it inspects nothing in the
+ * response body. If your deployment has an egress proxy or firewall, that control is strictly
+ * stronger than this one; this is defense in depth for deployments that do not.
+ *
+ * **The failure detail is an internal-network scanning oracle.** Log it; do not echo it, or
+ * any string derived from it, to an untrusted caller. The detail is structured precisely so
+ * that mapping it to a coarse public code is trivial.
+ *
+ * **Redirects are rejected unless you ask for them.** `redirectPolicy: 'validate-each-hop'`
+ * follows them, runs the address guard on every hop before any connection, and drops credential
+ * headers the first time the chain leaves an origin — and never restores them, so an
+ * `A` → `B` → `A` chain does not hand the token back to `A`.
+ *
+ * @param url - The URL to fetch. Only `http:` and `https:` are ever requested; every other
+ * scheme fails as `'invalid-url'`.
+ * @param options - Call options. `addressGuard` is required and has no default — use
+ * `blockPrivateNetworks()` on Node, or `allowAnyAddress()` to name the absence of the
+ * guarantee at the call site. `maxResponseBytes` defaults to 5 MiB and is meant to be tuned
+ * per call: real documents clear that, and raising it for the calls that need it is the
+ * intended use, not a workaround.
+ * @public
+ */
+declare function saferFetchBytes(url: string | URL, options: ISaferFetchOptions): Promise<DetailedResult<ISaferFetchResponse<Uint8Array>, FetchFailureReason>>;
+
+/**
+ * Fetches a URL and parses the response body as JSON, yielding the raw `JsonValue` for the
+ * caller to validate.
+ *
+ * @remarks
+ * **This does not gate on `Content-Type` by itself.** A server returning an HTML error page
+ * with a `200` will be decoded and parsed, and fail as `'parse'` — twenty frames from where it
+ * actually went wrong. Pass `responseHeadersGuard: allowContentTypes(['application/json'])`
+ * to reject on the header instead: it costs a header comparison rather than a body transfer,
+ * and the failure names the type. Content-type gating is a guard rather than an option so that
+ * there is exactly one mechanism for it.
+ *
+ * See {@link SaferFetch.saferFetchBytes} for what this primitive does **not** protect against,
+ * and for the warning about echoing failure detail to untrusted callers.
+ *
+ * @param url - The URL to fetch.
+ * @param options - Call options. `addressGuard` is required. `maxResponseBytes` defaults to
+ * 5 MiB and is meant to be tuned per call.
+ * @public
+ */
+declare function saferFetchJson(url: string | URL, options: ISaferFetchOptions): Promise<DetailedResult<ISaferFetchResponse<JsonValue>, FetchFailureReason>>;
+
+/**
+ * Fetches a URL, parses the response body as JSON, and runs it through the supplied converter
+ * or validator so the caller reaches a validated `T` in one step.
+ *
+ * @remarks
+ * `T` is inferred from `converter` and is never caller-asserted, so the returned type is
+ * evidenced at runtime rather than claimed.
+ *
+ * See {@link SaferFetch.saferFetchBytes} for what this primitive does **not** protect against,
+ * and for the warning about echoing failure detail to untrusted callers.
+ *
+ * @param url - The URL to fetch.
+ * @param options - Call options plus the required `converter`. `addressGuard` is required.
+ * `maxResponseBytes` defaults to 5 MiB and is meant to be tuned per call.
+ * @public
+ */
+declare function saferFetchJson<T>(url: string | URL, options: ISaferFetchJsonOptions<T>): Promise<DetailedResult<ISaferFetchResponse<T>, FetchFailureReason>>;
+
+/**
+ * HTTP methods a safer-fetch call may use.
+ * @public
+ */
+declare 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
+ */
+declare type SaferFetchRedirectPolicy = 'reject' | 'validate-each-hop';
+
+/**
+ * Fetches a URL and decodes the response body as text.
+ *
+ * @remarks
+ * The charset comes from the `Content-Type` parameter and defaults to UTF-8. Decoding is
+ * strict: an unknown charset, or a byte sequence that is not valid in the declared one, fails
+ * as `'decode'` rather than silently producing mojibake that some caller downstream treats as
+ * data.
+ *
+ * See {@link SaferFetch.saferFetchBytes} for what this primitive does **not** protect against,
+ * and for the warning about echoing failure detail to untrusted callers.
+ *
+ * @param url - The URL to fetch.
+ * @param options - Call options. `addressGuard` is required. `maxResponseBytes` defaults to
+ * 5 MiB and is meant to be tuned per call.
+ * @public
+ */
+declare function saferFetchText(url: string | URL, options: ISaferFetchOptions): Promise<DetailedResult<ISaferFetchResponse<string>, FetchFailureReason>>;
+
 /**
  * Function type for dynamic secret retrieval.
  * @public
@@ -6621,6 +8136,18 @@ declare const SMART_JSON_PROMPT_HINT: string;
  */
 declare function spkiToRawX25519(spki: Uint8Array): Result<Uint8Array>;
 
+/**
+ * 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
+ */
+declare const SUPPORTED_SCHEMES: ReadonlyArray<string>;
+
 /**
  * Whether a provider declares any embedding capability at all.
  *
@@ -6802,9 +8329,15 @@ declare class ZipDirectoryItem<TCT extends string = string> implements FileTree.
  * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
  * ZIP files are read-only, so this item does not support mutation.
  * Use {@link FileTree.isMutableFileItem | isMutableFileItem} to check before attempting mutations.
+ *
+ * @remarks
+ * ZIP entries are byte-native, so this item also implements the read half of the
+ * optional binary capability (`FileTree.IBinaryFileTreeFileItem`) — use
+ * `FileTree.isBinaryFileItem` to narrow and `getRawBytes()` to read the entry's
+ * undecoded bytes.
  * @public
  */
-declare class ZipFileItem<TCT extends string = string> implements FileTree.IFileTreeFileItem<TCT> {
+declare class ZipFileItem<TCT extends string = string> implements FileTree.IBinaryFileTreeFileItem<TCT> {
     /**
      * Indicates that this `FileTree.FileTreeItem` is a file.
      */
@@ -6830,9 +8363,13 @@ declare class ZipFileItem<TCT extends string = string> implements FileTree.IFile
      */
     get contentType(): TCT | undefined;
     /**
-     * The pre-loaded contents of the file.
+     * The pre-loaded raw bytes of the ZIP entry.
+     */
+    private readonly _bytes;
+    /**
+     * Text form of the entry, decoded lazily from the raw bytes on first text read.
      */
-    private readonly _contents;
+    private _contents;
     /**
      * The ZIP file tree accessors that created this item.
      */
@@ -6848,10 +8385,12 @@ declare class ZipFileItem<TCT extends string = string> implements FileTree.IFile
     /**
      * Constructor for ZipFileItem.
      * @param zipFilePath - The path of the file within the ZIP.
-     * @param contents - The pre-loaded contents of the file.
+     * @param contents - The pre-loaded contents of the entry, either as raw bytes or as
+     * already-decoded text. Text is encoded as UTF-8 for the byte accessor and is also
+     * retained verbatim, so supplying text never round-trips through a decode.
      * @param accessors - The ZIP file tree accessors.
      */
-    constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors<TCT>);
+    constructor(zipFilePath: string, contents: string | Uint8Array, accessors: ZipFileTreeAccessors<TCT>);
     /**
      * Sets the content type of the file.
      * @param contentType - The content type of the file.
@@ -6864,8 +8403,21 @@ declare class ZipFileItem<TCT extends string = string> implements FileTree.IFile
     getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
     /**
      * Gets the raw contents of the file as a string.
+     *
+     * @remarks
+     * The entry's bytes are decoded as UTF-8 with the lenient WHATWG default, so
+     * malformed input is silently replaced with U+FFFD. Use `getRawBytes()` for the
+     * undecoded bytes — and `new TextDecoder('utf-8', { fatal: true }).decode(bytes)`
+     * for a decode that fails loudly instead.
      */
     getRawContents(): Result<string>;
+    /**
+     * Gets the raw bytes of the ZIP entry, with no text decoding applied.
+     *
+     * @remarks
+     * The returned array is the item's internal buffer and must not be modified.
+     */
+    getRawBytes(): Result<Uint8Array>;
 }
 
 declare namespace ZipFileTree {
@@ -6874,7 +8426,9 @@ declare namespace ZipFileTree {
         ZipFileItem,
         ZipDirectoryItem,
         createZipFromTextFiles,
+        createZipFromFiles,
         IZipTextFile,
+        IZipFile,
         ZipCompressionLevel,
         ICreateZipOptions
     }
@@ -6885,9 +8439,15 @@ export { ZipFileTree }
  * Read-only file tree accessors for ZIP archives.
  * ZIP archives are read-only by design — use {@link FileTree.isMutableAccessors | isMutableAccessors}
  * to check before attempting mutations.
+ *
+ * @remarks
+ * ZIP entries are byte-native, so these accessors also implement the read half of the
+ * optional binary capability (`FileTree.IBinaryFileTreeAccessors`) — use
+ * `FileTree.isBinaryAccessors` to narrow and `getFileBytes()` to read an entry's
+ * undecoded bytes.
  * @public
  */
-declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IFileTreeAccessors<TCT> {
+declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IBinaryFileTreeAccessors<TCT> {
     /**
      * The unzipped file data.
      */
@@ -6981,8 +8541,25 @@ declare class ZipFileTreeAccessors<TCT extends string = string> implements FileT
     getItem(path: string): Result<FileTree.FileTreeItem<TCT>>;
     /**
      * Gets the contents of a file in the file tree.
+     *
+     * @remarks
+     * The entry's bytes are decoded as UTF-8 with the lenient WHATWG default. Use
+     * `getFileBytes()` for the undecoded bytes.
      */
     getFileContents(path: string): Result<string>;
+    /**
+     * Gets the raw bytes of a ZIP entry, with no text decoding applied.
+     *
+     * @remarks
+     * The returned array is the archive's internal buffer and must not be modified.
+     */
+    getFileBytes(path: string): Result<Uint8Array>;
+    /**
+     * Resolves a path to the ZIP file item it names.
+     * @param path - Path of the entry to look up.
+     * @returns `Success` with the item, or `Failure` if it is missing or is a directory.
+     */
+    private _getFileItem;
     /**
      * Gets the content type of a file in the file tree.
      */