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

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

@@ -0,0 +1,760 @@
+"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.saferFetchBytes = saferFetchBytes;
+exports.saferFetchText = saferFetchText;
+exports.saferFetchJson = saferFetchJson;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const contentType_1 = require("./contentType");
+const deadline_1 = require("./deadline");
+const defaults_1 = require("./defaults");
+const guards_1 = require("./guards");
+const retry_1 = require("./retry");
+const redirect_1 = require("./redirect");
+const transport_1 = require("./transport");
+const METHODS_WITHOUT_BODY = ['GET', 'HEAD'];
+const REDIRECT_POLICIES = ['reject', 'validate-each-hop'];
+function _succeed(value) {
+    return (0, ts_utils_1.succeedWithDetail)(value);
+}
+function _fail(detail, message) {
+    return (0, ts_utils_1.failWithDetail)(message, detail);
+}
+/** Re-types a failure for the next stage without re-deriving its message or detail. */
+function _propagate(from) {
+    return (0, ts_utils_1.failWithDetail)(from.message, from.detail);
+}
+function _unknown(message) {
+    return _fail({ kind: 'unknown', detail: message }, message);
+}
+/** The wrapping that every escaped-exception path reports, defined once so the two agree exactly. */
+function _unexpected(message) {
+    return _unknown(`saferFetch: unexpected error: ${message}`);
+}
+/**
+ * Restores the taxonomy's invariant that **every** failure leaving this module carries a
+ * `FetchFailureReason`.
+ *
+ * @remarks
+ * Only one thing can produce a detail-less failure: a bug inside this module that throws or
+ * rejects somewhere a `thenOnSuccess` callback catches it. `AsyncDetailedResult` converts such a
+ * throw to a `DetailedFailure` with `detail: undefined` — correctly, since a thrown error supplies
+ * no reason and inventing one would be worse — but that is a *chaining* primitive's contract, not
+ * this module's.
+ *
+ * Before the chaining pass those throws propagated as real rejections all the way to
+ * {@link _execute}'s `captureAsyncResult` and were reported as `'unknown'`. Catching them earlier
+ * must not change what the caller sees, so the same wrapping is reapplied here. Without this a
+ * caller switching on `detail.kind` — the documented way to consume this API — would fault on
+ * `undefined`.
+ */
+function _withReason(outcome) {
+    return outcome.isFailure() && outcome.detail === undefined ? _unexpected(outcome.message) : outcome;
+}
+function _blocked(seam, url, hop, guard, detail) {
+    return _fail({ kind: 'blocked-by-guard', url: url.toString(), hop, guard, detail }, `${seam} guard "${guard}" rejected ${url.toString()} at hop ${hop}: ${detail}`);
+}
+/**
+ * Awaits a guard or transport call, converting a thrown error or rejected promise into a
+ * `Failure` so a misbehaving implementation cannot escape the taxonomy as an exception.
+ */
+async function _capture(fn) {
+    return (0, ts_utils_1.captureAsyncResult)(fn).onSuccess((inner) => inner);
+}
+/**
+ * Runs a guard or transport call against the deadlines and folds all three outcomes — stopped,
+ * refused, cleared — into one `DetailedResult` the caller can chain from.
+ *
+ * @remarks
+ * Exists so the request path reads as a chain rather than as five copies of the same
+ * stopped-then-failed ladder. The taxonomy mapping stays per-site, because it genuinely differs
+ * per site: an address guard's refusal is `'blocked-by-guard'`, a transport's is `'network'`,
+ * and a content-type guard's is `'unsupported-content-type'`.
+ *
+ * **A stop is checked first and is never re-derived afterwards.** A stop resolves every
+ * in-flight race the instant it fires, so reaching the failure branch means the work settled
+ * *before* the call gave up — and relabelling that as a timeout because the deadline expired a
+ * microsecond later would be the taxonomy lying about which came first.
+ *
+ * @param onAbandon - Released whenever the value will not be used — on a stop and on a refusal
+ * alike. In practice this is the response body: leaving one unconsumed holds the connection
+ * open for a call that has already failed.
+ */
+async function _raced(watch, work, toFailure, onAbandon) {
+    const race = await watch.race(_capture(work));
+    if (race.stopped) {
+        onAbandon === null || onAbandon === void 0 ? void 0 : onAbandon();
+        return _stopped(watch, race.cause);
+    }
+    if (race.value.isFailure()) {
+        onAbandon === null || onAbandon === void 0 ? void 0 : onAbandon();
+        return toFailure(race.value.message);
+    }
+    return _succeed(race.value.value);
+}
+function _stopMessage(cause) {
+    return cause === 'caller-aborted' ? 'request aborted by caller.' : `request timed out (${cause}).`;
+}
+function _stopped(watch, cause) {
+    return _fail(watch.toFailureReason(cause), _stopMessage(cause));
+}
+/**
+ * Rejects any scheme this primitive will never request.
+ *
+ * `file:`, `data:`, `blob:`, `ftp:`, `gopher:` and `ws:` are refused here, in the core, because
+ * none is a legitimate network fetch and each is a standard SSRF payload. Choosing between
+ * `http:` and `https:`, and deciding which ports are acceptable, is the address guard's job —
+ * which is why the core does not narrow further, and why `allowInsecureHttp` can exist there.
+ */
+function _checkScheme(url) {
+    if (!defaults_1.SUPPORTED_SCHEMES.includes(url.protocol)) {
+        const detail = `scheme "${url.protocol}" is not supported (expected ${defaults_1.SUPPORTED_SCHEMES.join(' or ')})`;
+        return _fail({ kind: 'invalid-url', url: url.toString(), detail }, `invalid URL: ${detail}`);
+    }
+    return _succeed(url);
+}
+function _parseUrl(url) {
+    const text = String(url);
+    const parsed = (0, ts_utils_1.captureResult)(() => new URL(text));
+    if (parsed.isFailure()) {
+        return _fail({ kind: 'invalid-url', url: text, detail: parsed.message }, `invalid URL "${text}": ${parsed.message}`);
+    }
+    return _checkScheme(parsed.value);
+}
+function _lowercaseHeaders(headers) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        result[name.toLowerCase()] = value;
+    }
+    return result;
+}
+function _readHeaders(response) {
+    const headers = {};
+    response.headers.forEach((value, name) => {
+        headers[name.toLowerCase()] = value;
+    });
+    return headers;
+}
+/** Releases a response body that will not be read, so the socket is not held open. */
+function _discardBody(response) {
+    var _a;
+    const body = (_a = response.body) !== null && _a !== void 0 ? _a : undefined;
+    if (body !== undefined) {
+        // Best-effort and deliberately not awaited: the failure is already decided, and a cancel
+        // that rejects (an already-errored stream) must not replace it.
+        body.cancel().catch(() => undefined);
+    }
+}
+async function _cancelReader(reader) {
+    // A cancel that rejects (an already-errored or already-released stream) must not mask the
+    // failure that prompted it.
+    await reader.cancel().catch(() => undefined);
+}
+function _resolveCallOptions(options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    const method = (_a = options.method) !== null && _a !== void 0 ? _a : 'GET';
+    const body = (_b = options.body) !== null && _b !== void 0 ? _b : undefined;
+    if (body !== undefined && METHODS_WITHOUT_BODY.includes(method)) {
+        return _unknown(`a ${method} request cannot carry a body.`);
+    }
+    const timeoutMs = (_c = options.timeoutMs) !== null && _c !== void 0 ? _c : defaults_1.DEFAULT_TIMEOUT_MS;
+    const headersTimeoutMs = (_d = options.headersTimeoutMs) !== null && _d !== void 0 ? _d : defaults_1.DEFAULT_HEADERS_TIMEOUT_MS;
+    const maxResponseBytes = (_e = options.maxResponseBytes) !== null && _e !== void 0 ? _e : defaults_1.DEFAULT_MAX_RESPONSE_BYTES;
+    const limits = [
+        ['timeoutMs', timeoutMs],
+        ['headersTimeoutMs', headersTimeoutMs],
+        ['maxResponseBytes', maxResponseBytes]
+    ];
+    for (const [name, value] of limits) {
+        if (!Number.isFinite(value) || value <= 0) {
+            return _unknown(`${name} must be a positive finite number; got ${value}.`);
+        }
+    }
+    // `String(...)` and a lookup rather than a literal comparison, so that a JavaScript caller
+    // supplying a policy this release does not implement is rejected instead of silently getting a
+    // different one. The lookup also narrows to the union with no cast.
+    const requestedPolicy = String((_f = options.redirectPolicy) !== null && _f !== void 0 ? _f : 'reject');
+    const redirectPolicy = REDIRECT_POLICIES.find((p) => p === requestedPolicy);
+    if (redirectPolicy === undefined) {
+        return _unknown(`redirectPolicy "${requestedPolicy}" is not supported; expected ${REDIRECT_POLICIES.join(' or ')}.`);
+    }
+    const maxRedirects = (_g = options.maxRedirects) !== null && _g !== void 0 ? _g : defaults_1.DEFAULT_MAX_REDIRECTS;
+    if (!Number.isInteger(maxRedirects) || maxRedirects < 0) {
+        return _unknown(`maxRedirects must be a non-negative integer; got ${maxRedirects}.`);
+    }
+    // Same reasoning as `redirectPolicy` above, and the stakes are higher: these name the headers
+    // that get stripped on a cross-origin hop. A JavaScript caller can pass anything, and a
+    // non-string entry would throw out of an API contracted to only ever return a `Result`.
+    // Coercing instead of rejecting would be worse than either — `String(123)` is a header name
+    // that silently never matches, so a caller who fumbled the type would believe a credential was
+    // being stripped while it was carried across origins. A non-array is rejected for the same
+    // reason: spreading a bare string would enumerate it into single characters.
+    const extraSensitive = options.sensitiveHeaders;
+    if (extraSensitive !== undefined) {
+        if (!Array.isArray(extraSensitive)) {
+            return _unknown(`sensitiveHeaders must be an array of header names; got ${typeof extraSensitive}.`);
+        }
+        // `findIndex`, not `find`: an array containing `undefined` is itself invalid, and `find`
+        // cannot distinguish that from "no offender".
+        const badIndex = extraSensitive.findIndex((n) => typeof n !== 'string');
+        if (badIndex >= 0) {
+            return _unknown(`sensitiveHeaders[${badIndex}] must be a string header name; got ${typeof extraSensitive[badIndex]}.`);
+        }
+    }
+    const retry = (0, retry_1.resolveRetryPolicy)(options.retry);
+    if (retry.isFailure()) {
+        return _unknown(retry.message);
+    }
+    return _succeed({
+        method,
+        headers: _lowercaseHeaders((_h = options.headers) !== null && _h !== void 0 ? _h : {}),
+        body,
+        timeoutMs,
+        headersTimeoutMs,
+        maxResponseBytes,
+        redirectPolicy,
+        maxRedirects,
+        sensitiveHeaders: (0, redirect_1.sensitiveHeaderSet)(options.sensitiveHeaders),
+        retry: retry.value,
+        logger: (_j = options.logger) !== null && _j !== void 0 ? _j : new ts_utils_1.Logging.NoOpLogger()
+    });
+}
+/**
+ * Reads the body, counting decoded bytes as they arrive and failing the moment the cap is
+ * exceeded.
+ *
+ * `Content-Length` is a fast-reject path only. It is absent on chunked responses, and it is a
+ * value a hostile server chooses freely — a `Content-Length: 12` on a ten-gigabyte body costs
+ * the attacker nothing. The cap must therefore hold with no help from it, which is what
+ * counting during the read buys.
+ *
+ * The count is of *decoded* bytes, because the platform transparently decompresses
+ * `Content-Encoding`. That is also the decompression-bomb defense: a 2 KB gzip that expands to
+ * 10 GB clears the fast reject and then trips the cap after `limit` decoded bytes. It is why
+ * `too-large.declared` reads as "what the wire claimed", never as "how big it was".
+ */
+async function _readCappedBody(response, head, limit, watch) {
+    var _a;
+    const declared = head.contentLength;
+    if (declared !== undefined && declared > limit) {
+        _discardBody(response);
+        return _fail({ kind: 'too-large', bytesRead: 0, limit, declared }, `response declares ${declared} bytes, over the ${limit}-byte cap.`);
+    }
+    const body = (_a = response.body) !== null && _a !== void 0 ? _a : undefined;
+    if (body === undefined) {
+        return _succeed(new Uint8Array(0));
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        // The read must be captured, not raced raw. `reader.read()` rejects whenever the connection
+        // drops mid-transfer — a server reset, a proxy killing an idle connection, a TLS teardown —
+        // which is ordinary AC2 behaviour, not an exotic one. Racing the bare promise would let that
+        // rejection escape as a throw out of an entry point documented to always return a Result,
+        // which is precisely the guarantee this primitive sells.
+        const race = await watch.race(_capture(() => reader.read().then(ts_utils_1.succeed)));
+        if (race.stopped) {
+            // Cancelling is what makes the deadline effective rather than decorative: without it the
+            // transfer continues against a call that has already given up.
+            await _cancelReader(reader);
+            return _stopped(watch, race.cause);
+        }
+        if (race.value.isFailure()) {
+            // No cancel: the stream has already errored, so there is nothing left to cancel. Reported
+            // as `network` — the same kind a transport-level failure gets, because it is the same
+            // class of event, observed a few frames later.
+            return _fail({ kind: 'network', detail: race.value.message }, `response body read failed: ${race.value.message}`);
+        }
+        if (race.value.value.done) {
+            break;
+        }
+        const chunk = race.value.value.value;
+        total += chunk.byteLength;
+        if (total > limit) {
+            // Returning without cancelling would leave the body unconsumed and the connection held,
+            // turning the size-cap rejection into the exact resource exhaustion the cap exists to
+            // prevent.
+            await _cancelReader(reader);
+            return _fail({ kind: 'too-large', bytesRead: total, limit, declared }, `response exceeded the ${limit}-byte cap after ${total} bytes.`);
+        }
+        chunks.push(chunk);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return _succeed(bytes);
+}
+async function _receive(response, url, chain, guards, resolved, watch, notes) {
+    var _a;
+    if (response.type === 'opaqueredirect') {
+        _discardBody(response);
+        return _fail({ kind: 'redirect-opaque' }, 'the platform returned an opaque redirect, whose target cannot be inspected or guarded.');
+    }
+    if (defaults_1.REDIRECT_STATUSES.includes(response.status)) {
+        // The body of a redirect is never the body this call wanted, and leaving it unconsumed holds
+        // the connection open for the whole rest of the chain.
+        _discardBody(response);
+        if (resolved.redirectPolicy === 'reject') {
+            return _fail({ kind: 'redirect-rejected', url: url.toString(), status: response.status }, `${url.toString()} redirected with status ${response.status}; redirects are rejected.`);
+        }
+        const location = (_a = response.headers.get('location')) !== null && _a !== void 0 ? _a : undefined;
+        if (location === undefined || location.trim().length === 0) {
+            return _fail({ kind: 'redirect-rejected', url: url.toString(), status: response.status }, `${url.toString()} redirected with status ${response.status} but sent no usable Location header.`);
+        }
+        return _succeed({ kind: 'redirect', status: response.status, location });
+    }
+    const headers = _readHeaders(response);
+    // Annotated because a `Record<string, string>` lookup is typed as present even when the
+    // header was never sent; these are read as optional everywhere downstream.
+    const contentType = headers['content-type'];
+    const contentLength = headers['content-length'];
+    const head = {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+        contentType,
+        contentLength: (0, contentType_1.parseContentLength)(contentLength)
+    };
+    if (!response.ok) {
+        _discardBody(response);
+        // Recorded before the failure is built rather than carried on it: `Retry-After` is
+        // scheduling advice for this process, not a fact about the response worth widening the
+        // taxonomy — and the taxonomy is a surface callers may echo, which advice from an
+        // attacker-controlled server should not join.
+        notes.retryAfter = headers['retry-after'];
+        return _fail(
+        // `bodyPreview` is deliberately never populated: error bodies routinely echo request
+        // content, including credentials.
+        { kind: 'http-status', status: response.status, statusText: response.statusText }, `${url.toString()} returned ${response.status} ${response.statusText}.`);
+    }
+    const hop = chain.length - 1;
+    // Chained rather than stepped: `thenOnSuccess` now preserves `FetchFailureReason` across an
+    // async step, so each stage's failure propagates with its detail intact and the two
+    // `_propagate` re-types this sequence used to need are gone.
+    return (await _raced(watch, () => guards.responseHeaders.check(head, chain), (message) => {
+        var _a;
+        // A content-type allowlist names itself by exposing `acceptedContentTypes`, and its
+        // rejections carry a more useful payload than an opaque policy refusal would.
+        const accepted = (_a = guards.responseHeaders.acceptedContentTypes) !== null && _a !== void 0 ? _a : undefined;
+        return accepted !== undefined
+            ? _fail({ kind: 'unsupported-content-type', contentType: head.contentType, accepted }, `${url.toString()}: ${message}`)
+            : _blocked('response-headers', url, hop, guards.responseHeaders.name, message);
+    }, () => _discardBody(response)))
+        .thenOnSuccess(async () => _readCappedBody(response, head, resolved.maxResponseBytes, watch))
+        .thenOnSuccess(async (bytes) => (await _raced(watch, () => guards.responseBody.check(bytes, head), (message) => _blocked('response-body', url, hop, guards.responseBody.name, message))).onSuccess(() => _succeed({ kind: 'final', bytes, head })));
+}
+/**
+ * Runs the address guard on the hop about to be requested and returns the URL it cleared.
+ *
+ * @remarks
+ * Split out of {@link _connect} so that the guard's verdict is available to the caller *before*
+ * anything is put on the wire. Redirect loop detection needs exactly that: it compares the hop
+ * about to be requested against the hops already requested, and both sides have to be
+ * guard-cleared URLs for the comparison to mean anything (see {@link _detectLoop}).
+ *
+ * It runs after the request guard, so a request guard that returned a replacement request
+ * cannot route around it, and it runs on **every** hop rather than only the first: a `302` to
+ * `http://169.254.169.254/` is exactly what a guard that only saw the caller's URL would miss.
+ */
+async function _clearAddress(chain, guards, watch) {
+    const hop = chain[chain.length - 1];
+    const hopIndex = chain.length - 1;
+    return (await _raced(watch, () => guards.address.check(chain), (message) => _blocked('address', hop.url, hopIndex, guards.address.name, message))).onSuccess((verdict) => 
+    // A guard may normalize the URL it cleared; the normalized URL is what gets requested. The
+    // scheme is re-checked because normalization must never be able to widen it.
+    _checkScheme(verdict.url).onSuccess((url) => { var _a; return _succeed({ url, pinnedAddress: (_a = verdict.pinnedAddress) !== null && _a !== void 0 ? _a : undefined }); }));
+}
+/**
+ * Rejects a hop that revisits a URL already requested on this walk.
+ *
+ * @remarks
+ * `A → B → A → B` passes every per-hop check while consuming the whole redirect budget, and the
+ * hop cap alone would let it — the same reason the address guard is handed the chain rather
+ * than a counter.
+ *
+ * **Both sides of the comparison are guard-cleared URLs**, which is why this runs after
+ * {@link _clearAddress} rather than on the raw `Location` target. A guard may normalize the URL
+ * it clears — `IGuardVerdict.url` explicitly permits lowercasing a host, stripping a trailing
+ * dot, punycoding an IDN — so comparing a cleared URL against an uncleared one lets a repeat
+ * escape detection and run to `maxRedirects` instead. Comparing like with like is the whole
+ * fix; special-casing particular normalizations here would be worse than leaving it, because
+ * this layer does not own normalization and cannot anticipate what a custom guard does.
+ *
+ * `url` on the failure is the URL that **issued** the redirect, never the repeated target — the
+ * contract `FetchFailureReason.redirect-rejected` documents. The target is named in the message.
+ */
+function _detectLoop(cleared, completed) {
+    var _a;
+    const issuer = (_a = completed[completed.length - 1]) !== null && _a !== void 0 ? _a : undefined;
+    // Hop 0 cannot repeat anything, so an empty chain is trivially clear — and there would be no
+    // issuing hop to name if it could.
+    if (issuer === undefined || !completed.some((hop) => hop.url.toString() === cleared.toString())) {
+        return _succeed(cleared);
+    }
+    return _fail({ kind: 'redirect-rejected', url: issuer.url.toString(), status: issuer.status }, `${issuer.url.toString()} redirected with status ${issuer.status} to ${cleared.toString()}, which is already in the chain.`);
+}
+async function _connect(request, cleared, chain, guards, options, resolved, watch, notes) {
+    var _a;
+    const transport = (_a = options.transport) !== null && _a !== void 0 ? _a : transport_1.platformFetchTransport;
+    const init = {
+        method: request.method,
+        headers: request.headers,
+        // `'manual'` rather than `'follow'`: the platform must not follow anything on our behalf,
+        // because a hop the guard never sees is a hop the guard never guarded.
+        redirect: 'manual',
+        signal: watch.signal
+    };
+    if (request.body !== undefined) {
+        // A byte body is copied into a fresh buffer rather than handed over by reference: it keeps
+        // the platform's non-shared `BufferSource` requirement satisfied without a cast, and it
+        // means a caller mutating its array after the call cannot change what goes on the wire.
+        init.body = typeof request.body === 'string' ? request.body : new Uint8Array(request.body);
+    }
+    return (await _raced(watch, () => transport.fetch(cleared.url, init, { pinnedAddress: cleared.pinnedAddress }), (message) => _fail({ kind: 'network', detail: message }, `transport "${transport.name}" failed: ${message}`)))
+        .thenOnSuccess(async (response) => {
+        // Inside the continuation rather than before it, which is where it already ran: the
+        // headers deadline is retired only once a response has actually arrived.
+        watch.headersReceived();
+        return _receive(response, cleared.url, chain, guards, resolved, watch, notes);
+    })
+        .onSuccess((outcome) => 
+    // The pin is recorded only once the transport has accepted it. A transport that cannot
+    // honor a pin is required to fail rather than connect by hostname, so a settled request
+    // with a pin set is evidence the pin held — which is the only basis on which recording it
+    // would be honest.
+    _succeed({ url: cleared.url, connectedAddress: cleared.pinnedAddress, outcome }));
+}
+/**
+ * Derives the next hop's request from a redirect, or explains why the chain stops here.
+ *
+ * @remarks
+ * The hop cap is checked before the target is resolved: a chain that has already run out of
+ * budget stops for that reason, whatever the `Location` header happens to contain.
+ *
+ * Loop detection is deliberately **not** here — it belongs after the address guard has cleared
+ * the next hop, where both sides of the comparison are cleared URLs. See {@link _detectLoop}.
+ */
+function _nextHop(from, completed, redirect, request, resolved) {
+    const followed = completed.length;
+    if (followed >= resolved.maxRedirects) {
+        return _fail({ kind: 'too-many-redirects', hops: followed + 1, limit: resolved.maxRedirects }, `redirect chain exceeded the limit of ${resolved.maxRedirects} hops.`);
+    }
+    // The plain-`Result`-to-`DetailedResult` conversion is done here rather than chained, for the
+    // same reason `_parseUrl` and `_decodeText` do it: it is the boundary where a `Result` becomes
+    // an `Outcome`, and naming the boundary is what lets everything downstream of it chain.
+    const located = (0, redirect_1.resolveLocation)(redirect.location, from);
+    if (located.isFailure()) {
+        return _fail({ kind: 'invalid-url', url: redirect.location, detail: located.message }, `invalid redirect target: ${located.message}`);
+    }
+    return _checkScheme(located.value).onSuccess((to) => {
+        // Headers come from the request that was actually sent on this hop, never from the
+        // caller's original set — that carry-forward is what makes credential stripping monotonic.
+        const rewritten = (0, redirect_1.rewriteForRedirect)({
+            from,
+            to,
+            status: redirect.status,
+            method: request.method,
+            headers: request.headers,
+            body: request.body,
+            sensitiveHeaders: resolved.sensitiveHeaders
+        });
+        return _succeed(Object.assign({ url: to, method: rewritten.method, headers: rewritten.headers }, (rewritten.body !== undefined ? { body: rewritten.body } : {})));
+    });
+}
+/**
+ * Walks one attempt: the caller's URL, then every redirect hop it leads to, each fully guarded.
+ *
+ * @remarks
+ * **A retry calls this again from the top, with a request rebuilt from the caller's resolved
+ * options.** Nothing is carried across attempts — not the guard's verdict, not the redirect
+ * chain, not the headers a previous attempt's cross-origin hop had already stripped. That is
+ * what makes a retry a full re-walk rather than a resume, and the reason is in
+ * {@link SaferFetch.IRetryPolicy}: a cached verdict would turn retry into a DNS-rebinding
+ * amplifier, and a resumed chain would revalidate hops the new attempt no longer follows.
+ */
+async function _walk(url, guards, options, resolved, watch, notes) {
+    let request = Object.assign({ url, method: resolved.method, headers: resolved.headers }, (resolved.body !== undefined ? { body: resolved.body } : {}));
+    /** Hops already requested and redirected away from, oldest first. */
+    const completed = [];
+    for (;;) {
+        // Re-arms the per-attempt headers deadline. Without this, the first hop's
+        // `headersReceived()` would retire it for the whole call and a later host that never
+        // answers would be bounded only by the overall deadline.
+        watch.attemptStarted();
+        const guarded = await _raced(watch, () => guards.request.check(request, [...completed, { url: request.url }]), (message) => _blocked('request', request.url, completed.length, guards.request.name, message));
+        if (guarded.isFailure()) {
+            return _propagate(guarded);
+        }
+        const checked = guarded.value;
+        const rechecked = _checkScheme(checked.url);
+        if (rechecked.isFailure()) {
+            return _propagate(rechecked);
+        }
+        // The address guard runs immediately before the connect and after the request guard, so it
+        // is always the last word before anything reaches the wire.
+        const cleared = await _clearAddress([...completed, { url: checked.url }], guards, watch);
+        if (cleared.isFailure()) {
+            return _propagate(cleared);
+        }
+        const unrepeated = _detectLoop(cleared.value.url, completed);
+        if (unrepeated.isFailure()) {
+            resolved.logger.detail(`saferFetch: ${cleared.value.url.toString()} failed: ${unrepeated.message}`);
+            return _propagate(unrepeated);
+        }
+        // Downstream guards see the chain as it was actually requested, so the URL a response guard
+        // reads is the URL the address guard cleared — not the pre-normalization spelling.
+        const requested = [...completed, { url: cleared.value.url }];
+        const attempted = await _connect(checked, cleared.value, requested, guards, options, resolved, watch, notes);
+        if (attempted.isFailure()) {
+            resolved.logger.detail(`saferFetch: ${cleared.value.url.toString()} failed: ${attempted.message}`);
+            return _propagate(attempted);
+        }
+        const attempt = attempted.value;
+        if (attempt.outcome.kind === 'final') {
+            return _succeed({
+                bytes: attempt.outcome.bytes,
+                head: attempt.outcome.head,
+                urlChain: [...completed.map((hop) => hop.url.toString()), attempt.url.toString()]
+            });
+        }
+        const next = _nextHop(attempt.url, completed, attempt.outcome, checked, resolved);
+        if (next.isFailure()) {
+            resolved.logger.detail(`saferFetch: ${attempt.url.toString()} failed: ${next.message}`);
+            return _propagate(next);
+        }
+        completed.push(Object.assign({ url: attempt.url, status: attempt.outcome.status }, (attempt.connectedAddress !== undefined ? { connectedAddress: attempt.connectedAddress } : {})));
+        request = next.value;
+    }
+}
+/**
+ * Decides how long to wait before retrying a failed walk, or that it must not be retried.
+ *
+ * @remarks
+ * Every rule that can refuse a retry is applied here, in one place, so "would this have been
+ * retried?" is answerable by reading one function: the attempt budget, the retryable-failure
+ * set, the idempotency rule, the `Retry-After` clamp, and the overall deadline as ceiling.
+ *
+ * **The deadline is the last word.** When the remaining budget is shorter than the computed
+ * delay, the call fails with the attempt's own failure rather than sleeping past the deadline
+ * the caller set — a `timeout` reported at `timeoutMs` is what the caller asked for, and one
+ * reported at `timeoutMs + backoff` is a primitive that does not keep its own promises.
+ */
+function _retryDelayMs(reason, attempt, resolved, notes, watch) {
+    const policy = resolved.retry;
+    if (attempt >= policy.attempts) {
+        return undefined;
+    }
+    if (!(0, retry_1.isRetryableFailure)(reason) || !(0, retry_1.isRetryableMethod)(resolved.method, policy)) {
+        return undefined;
+    }
+    const retryAfterMs = (0, retry_1.honorsRetryAfter)(reason, policy)
+        ? (0, retry_1.parseRetryAfterMs)(notes.retryAfter, Date.now())
+        : undefined;
+    const delay = (0, retry_1.computeRetryDelayMs)(Object.assign(Object.assign({ attempt,
+        policy }, (retryAfterMs !== undefined ? { retryAfterMs } : {})), { random: Math.random }));
+    return delay <= watch.remainingMs ? delay : undefined;
+}
+/**
+ * Runs one attempt and, if the policy says so, the next one after it.
+ *
+ * @remarks
+ * Recursive rather than a loop, because **a retry is a fresh start rather than another turn of
+ * something already in progress**: every attempt is a full {@link _walk} from hop 0, and nothing
+ * survives the boundary — not the guard's verdict, not the redirect chain, not the headers a
+ * cross-origin hop stripped, not the previous response's `Retry-After`. Expressing that as a
+ * self-call keeps the "nothing carries over" property visible in the shape of the code rather
+ * than resting on a reader noticing which variables are declared inside the loop body.
+ *
+ * Depth is bounded by `retry.attempts` and each level is `await`ed, so the frames unwind rather
+ * than nest.
+ *
+ * @param attempt - 0-based index of the attempt about to run; `0` is the caller's first request.
+ */
+async function _runAttempt(url, guards, options, resolved, watch, attempt) {
+    // Fresh per attempt: notes describe the attempt that just failed, and carrying a previous
+    // attempt's `Retry-After` into a later decision would schedule against a response that is no
+    // longer the reason we are retrying.
+    const notes = {};
+    const walked = await _walk(url, guards, options, resolved, watch, notes);
+    // `!isFailure()` rather than `isSuccess()`: only the former narrows to the failure branch
+    // below, where `detail` is known to be present.
+    if (!walked.isFailure()) {
+        return walked;
+    }
+    const delay = _retryDelayMs(walked.detail, attempt, resolved, notes, watch);
+    if (delay === undefined) {
+        return walked;
+    }
+    // Clears an attempt-scoped stop — a headers timeout ends the attempt, not the call — so the
+    // backoff below is not answered instantly by the previous attempt's own deadline. A terminal
+    // stop deliberately survives, and ends the call at the first race below.
+    watch.attemptEnded();
+    resolved.logger.detail(`saferFetch: ${url.toString()} failed (${walked.message}); retrying in ` +
+        `${Math.round(delay)}ms — attempt ${attempt + 2} of ${resolved.retry.attempts + 1}.`);
+    // Delayed on the same watch the request races against, so a caller who aborts during a backoff
+    // is answered then rather than after the sleep.
+    const slept = await watch.delay(delay);
+    return slept.stopped
+        ? _stopped(watch, slept.cause)
+        : _runAttempt(url, guards, options, resolved, watch, attempt + 1);
+}
+async function _execute(url, options) {
+    const resolvedOptions = _resolveCallOptions(options);
+    if (resolvedOptions.isFailure()) {
+        return _propagate(resolvedOptions);
+    }
+    const resolved = resolvedOptions.value;
+    const resolvedGuards = (0, guards_1.resolveGuards)(options);
+    if (resolvedGuards.isFailure()) {
+        return _unknown(resolvedGuards.message);
+    }
+    const guards = resolvedGuards.value;
+    const parsed = _parseUrl(url);
+    if (parsed.isFailure()) {
+        return _propagate(parsed);
+    }
+    const watch = new deadline_1.DeadlineWatch(resolved.timeoutMs, resolved.headersTimeoutMs, options.signal);
+    // `captureAsyncResult` rather than `try`/`finally`, for the same reason `_capture` wraps every
+    // guard and transport call: an entry point documented to always return a `Result` has to keep
+    // that promise even when a collaborator breaks its own. Nothing inside is *supposed* to throw
+    // — guards, transports and the body read are each captured already — but the caller's
+    // `logger` is collaborator code this primitive does not wrap, and a thrown diagnostic must not
+    // become the caller's problem. The watch is disposed on both paths because the capture has
+    // already converted the throw into a value.
+    const ran = await (0, ts_utils_1.captureAsyncResult)(async () => _runAttempt(parsed.value, guards, options, resolved, watch, 0));
+    watch.dispose();
+    return ran.isFailure()
+        ? // `'unknown'` is the taxonomy's honest slot for "something violated its contract", rather
+            // than a guess at a more specific kind.
+            _unexpected(ran.message)
+        : // Same wrapping for a throw a `thenOnSuccess` callback caught before it could reach the
+            // capture above — see {@link _withReason}. This is the single boundary where an `Outcome`
+            // becomes the caller's result, so it is the one place the invariant has to hold.
+            _withReason(ran.value);
+}
+function _toResponse(value, raw) {
+    return {
+        value,
+        status: raw.head.status,
+        headers: raw.head.headers,
+        urlChain: raw.urlChain,
+        bytesRead: raw.bytes.byteLength
+    };
+}
+/**
+ * Applies the caller's parser to the decoded body.
+ *
+ * @remarks
+ * Exists for the same reason as {@link _decodeText}: it is the boundary where a plain
+ * `Result` from a `Converter` becomes a `DetailedResult` carrying a `FetchFailureReason`.
+ * Isolating that conversion in a named helper is what lets the entry points stay chained.
+ */
+function _parseJson(text, parser) {
+    const parsed = parser.convert(text);
+    if (parsed.isFailure()) {
+        return _fail({ kind: 'parse', detail: parsed.message }, `failed to parse response as JSON: ${parsed.message}`);
+    }
+    return _succeed(parsed.value);
+}
+function _decodeText(raw) {
+    var _a;
+    const charset = (_a = (0, contentType_1.parseCharset)(raw.head.contentType)) !== null && _a !== void 0 ? _a : 'utf-8';
+    // `fatal: true` so an unknown charset, or a byte sequence invalid in the declared one,
+    // surfaces as a decode failure rather than as silent mojibake some caller treats as data.
+    const decoded = (0, ts_utils_1.captureResult)(() => new TextDecoder(charset, { fatal: true }).decode(raw.bytes));
+    if (decoded.isFailure()) {
+        return _fail({ kind: 'decode', detail: decoded.message }, `failed to decode response as "${charset}": ${decoded.message}`);
+    }
+    return _succeed(decoded.value);
+}
+/**
+ * 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
+ */
+async function saferFetchBytes(url, options) {
+    return (await _execute(url, options)).onSuccess((raw) => _succeed(_toResponse(raw.bytes, raw)));
+}
+/**
+ * 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
+ */
+async function saferFetchText(url, options) {
+    // Nested rather than flat: `_toResponse` needs both the decoded text and the raw outcome it
+    // came from, and nesting is what keeps `raw` in scope for it.
+    return (await _execute(url, options)).onSuccess((raw) => _decodeText(raw).onSuccess((text) => _succeed(_toResponse(text, raw))));
+}
+async function saferFetchJson(url, options) {
+    var _a;
+    const converter = (_a = options.converter) !== null && _a !== void 0 ? _a : undefined;
+    const parser = converter !== undefined
+        ? ts_json_base_1.Converters.stringifiedJson(converter)
+        : ts_json_base_1.Converters.stringifiedJson();
+    // Nested for the same reason as `saferFetchText`: the response needs the raw outcome as well
+    // as the parsed value, and nesting is what keeps `raw` in scope.
+    return (await _execute(url, options)).onSuccess((raw) => _decodeText(raw).onSuccess((text) => _parseJson(text, parser).onSuccess((parsed) => _succeed(_toResponse(parsed, raw)))));
+}
+//# sourceMappingURL=saferFetch.js.map