@sdxc/outbound 0.0.0-stage → 2026.10.6

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+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.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# @sdxc/outbound
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Check, follow and read URLs a stranger chose: public hosts on every redirect, one deadline, bounded bodies.
+
+A Worker that fetches a feed someone subscribed to, a page someone saved or an image a post embeds has to decide where it is willing to go, re-decide on every redirect, stop waiting at some point, and stop reading at some size. This package answers those four questions with plain functions that call the global `fetch` and answer a `Result`. Checking and following matter only for the public internet; reading within a cap works on any `Request` or `Response`, including one from a Durable Object stub, a service binding or an incoming request.
+
+## Installation
+
+```bash
+npm add @sdxc/outbound
+```
+
+Every function answers a `Result` from [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result), installed with this package.
+
+## Usage
+
+### Checking A URL
+
+```typescript
+import { checkUrl } from "@sdxc/outbound";
+
+checkUrl("https://example.com/feed.xml"); // success: URL
+checkUrl("http://169.254.169.254/latest"); // failure: OutboundError { code: "refused-address" }
+checkUrl("https://printer.local/"); // failure: OutboundError { code: "refused-host" }
+checkUrl("https://user:pass@example.com/"); // failure: OutboundError { code: "refused-credentials" }
+```
+
+### Following A URL And Reading The Body
+
+```typescript
+import { follow, readText } from "@sdxc/outbound";
+import { isFailure } from "@sdxc/result";
+
+let followed = await follow(url, {
+	headers: { accept: "application/atom+xml", "user-agent": "ExampleReader/1.0" },
+	timeout: "8 seconds",
+	maxRedirects: 5,
+});
+if (isFailure(followed)) return followed;
+
+let body = await readText(followed.data.response, { maxBytes: 2 * 1024 * 1024 });
+if (isFailure(body)) return body; // too-large, timeout or network
+```
+
+The `timeout` covers the whole chain **and** the body read afterwards.
+
+### Capping A Body That Did Not Come From `fetch`
+
+```typescript
+import { readBytes } from "@sdxc/outbound";
+
+let body = await readBytes(request, { maxBytes: 1024 * 1024 });
+if (isFailure(body)) return new Response(null, { status: 413 });
+verifySignature(body.data.data);
+```
+
+### Streaming A Capped Body Through
+
+```typescript
+import { follow, limitBody } from "@sdxc/outbound";
+
+let followed = await follow(imageUrl, { timeout: "10 seconds", ports: "default" });
+if (isFailure(followed)) return new Response(null, { status: 404 });
+
+return limitBody(followed.data.response, { maxBytes: 5 * 1024 * 1024 });
+```
+
+## API
+
+### `checkUrl(input, options?): Result<URL, OutboundError>`
+
+Parses a URL and refuses it unless every rule passes. No request or lookup is made.
+
+- Only `http:` and `https:` pass, and a URL carrying a username or password is refused.
+- An address literal passes when it is on the public internet, judged by [`@sdxc/ip`](https://www.npmjs.com/package/@sdxc/ip). IPv4-mapped and NAT64 addresses are judged by the IPv4 inside.
+- A name passes when it has a dot and does not end in a reserved suffix: `localhost`, `local`, `internal`, `intranet`, `lan`, `corp`, `private`, `home.arpa`, `test`, `invalid` or `example`.
+
+Options:
+
+- `hosts` — `"public"` (default) applies the host rules; `"any"` keeps only the scheme and credential rules, for a caller that reaches its own network on purpose.
+- `literals` — `"public"` (default) allows a public address literal; `"refuse"` refuses every literal.
+- `ports` — `"any"` (default), `"default"` for only the scheme's own port, or a list such as `[80, 443]`, where an omitted port counts as the scheme's own.
+
+### `follow(input, options?): Promise<Result<Followed, OutboundError>>`
+
+Requests a URL with `redirect: "manual"` and `credentials: "omit"`, and walks the redirect chain itself. Every hop passes `checkUrl` with the same options, so a redirect cannot reach somewhere the first URL could not, and the same headers are sent on every hop. A redirect's body is released before the next hop. The final response is answered whatever its status: mapping a status to an error is the caller's.
+
+Options, beside every `checkUrl` option:
+
+- `method` — `"GET"` (default) or `"HEAD"`. A request with a body is a single `fetch` to a URL `checkUrl` passed.
+- `headers` — sent on every hop.
+- `timeout` — a number of milliseconds or a duration string such as `"8 seconds"`.
+- `signal` — the caller's own abort, combined with `timeout` through `AbortSignal.any`.
+- `maxRedirects` — default `5`.
+- `resolve` — resolves every hop's name over DNS-over-HTTPS (Cloudflare's resolver, through [`@sdxc/doh`](https://www.npmjs.com/package/@sdxc/doh)) and refuses it when any address is not public. Default `false`.
+
+`Followed` is `{ response, url, redirects }`, where `url` is where the chain ended. The response's body carries the deadline, so reading it after the deadline fails with `timeout`.
+
+### `resolveHost(url, options?): Promise<Result<string[], OutboundError>>`
+
+Resolves the `A` and `AAAA` records of a URL's host and answers every address when all are public. An address literal answers itself. `refused-host` for a name that does not exist or has no address, `refused-address` for any address that is not public or cannot be read, and `network` when the resolver fails. `options.signal` aborts both lookups.
+
+### `readText(message, { maxBytes }): Promise<Result<{ text, bytes }, OutboundError>>`
+
+Reads a `Request` or `Response` body as UTF-8 text. A `Content-Length` over the cap fails before any of the body is read; the count over the stream is what enforces the cap, so a body that lies about its length fails at the same byte and the stream is cancelled.
+
+### `readBytes(message, { maxBytes }): Promise<Result<{ data, bytes }, OutboundError>>`
+
+The same read, keeping the bytes exactly as they arrived in a `Uint8Array`.
+
+### `limitBody(response, { maxBytes }): Response`
+
+The same status and headers, with a body that errors with a `too-large` `OutboundError` at the first chunk past the cap. For a body passed through rather than read.
+
+### `release(body)`
+
+Cancels an unread body, or a reader of one, without waiting on the origin. `null` is ignored.
+
+### `OutboundError`
+
+Carries `code`, the `url` it concerns, and `retryable`.
+
+| `code`                | `retryable` | When                                              |
+| --------------------- | ----------- | ------------------------------------------------- |
+| `invalid-url`         | No          | The input does not parse as a URL                 |
+| `refused-scheme`      | No          | Not HTTP(S)                                       |
+| `refused-credentials` | No          | The URL carries a username or password            |
+| `refused-port`        | No          | A port the `ports` option does not allow          |
+| `refused-host`        | No          | A reserved name, a single label, or no address    |
+| `refused-address`     | No          | A non-public literal, or a non-public DNS answer  |
+| `too-many-redirects`  | No          | The chain ran past `maxRedirects`                 |
+| `too-large`           | No          | The body passed `maxBytes`                        |
+| `timeout`             | Yes         | The deadline passed                               |
+| `network`             | Yes         | `fetch` rejected, a body broke off, or DNS failed |
+
+## Pattern: Mapping To Your Own Errors
+
+Keep your package's or app's error type and translate at the boundary.
+
+```typescript
+import { follow } from "@sdxc/outbound";
+import { failure, isFailure, success } from "@sdxc/result";
+
+class FetchFeedError extends Error {
+	constructor(
+		message: string,
+		readonly retryable: boolean,
+	) {
+		super(message);
+	}
+}
+
+async function fetchFeed(url: string) {
+	let followed = await follow(url, { timeout: "10 seconds" });
+	if (isFailure(followed)) {
+		return failure(new FetchFeedError(followed.error.message, followed.error.retryable));
+	}
+	if (followed.data.response.status === 304) return success(null);
+	return success(followed.data.response);
+}
+```
+
+## Pattern: DNS Rebinding
+
+`resolve: true` and `resolveHost` catch a public name whose records point inside a network. A Worker cannot pin its connection to the addresses that were checked, so a name that answers with a public address to the check and a private one to the connection still gets through. This narrows DNS rebinding and leaves it open. What holds regardless is architectural: a Worker that reaches its own storage through bindings rather than URLs has nothing private for an escaped request to reach.
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/outbound": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/check.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Decides whether a URL is somewhere a Worker should send a request, from the URL
+ * alone: the scheme, any credentials, the port, and a host that is a public address
+ * or a name outside every reserved suffix. No request and no lookup is made here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { OutboundError } from "./error.js";
+/** Which URLs a check lets through; every field defaults to the strictest public policy. */
+export interface CheckOptions {
+    /**
+     * `"public"` refuses reserved names and non-public addresses; `"any"` keeps only the
+     * scheme and credential rules, for a caller that reaches its own network on purpose.
+     *
+     * @default "public"
+     */
+    hosts?: "public" | "any";
+    /**
+     * `"public"` lets through an address literal that is on the public internet;
+     * `"refuse"` refuses every literal, so only a name can be asked.
+     *
+     * @default "public"
+     */
+    literals?: "public" | "refuse";
+    /**
+     * `"any"` lets through every port, `"default"` only the scheme's own, and a list
+     * only the ports it names, an omitted port counting as the scheme's own.
+     *
+     * @default "any"
+     */
+    ports?: "any" | "default" | readonly number[];
+}
+/**
+ * Parses a URL and refuses it unless every rule passes. The rules run on the parsed
+ * URL, so a host spelled in octal, hex or with a trailing dot is judged by the address
+ * or name it normalizes to.
+ *
+ * @param input - The URL as a stranger wrote it, or one already parsed.
+ * @param options - Which hosts, literals and ports are allowed.
+ * @returns The parsed URL, or the `OutboundError` naming the rule that refused it.
+ * @example checkUrl("https://example.com/feed.xml"); // success
+ * @example checkUrl("http://169.254.169.254/"); // failure: refused-address
+ */
+export declare function checkUrl(input: string | URL, options?: CheckOptions): Result<URL, OutboundError>;

package/dist/check.js

@@ -0,0 +1,95 @@
+/**
+ * Decides whether a URL is somewhere a Worker should send a request, from the URL
+ * alone: the scheme, any credentials, the port, and a host that is a public address
+ * or a name outside every reserved suffix. No request and no lookup is made here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { IP } from "@sdxc/ip";
+import { failure, isSuccess, success } from "@sdxc/result";
+import { OutboundError } from "./error.js";
+/** The port each scheme uses when the URL names none. */
+const DEFAULT_PORTS = { "http:": 80, "https:": 443 };
+/**
+ * Name suffixes that never denote a public host: resolver-local names, private-network
+ * conventions, and the RFC 2606 and RFC 6761 reserved names. Matched against whole
+ * trailing labels, so `example` refuses `www.example` and leaves `example.com` alone.
+ */
+const RESERVED_SUFFIXES = [
+    "localhost",
+    "local",
+    "internal",
+    "intranet",
+    "lan",
+    "corp",
+    "private",
+    "home.arpa",
+    "test",
+    "invalid",
+    "example",
+];
+/**
+ * Parses a URL and refuses it unless every rule passes. The rules run on the parsed
+ * URL, so a host spelled in octal, hex or with a trailing dot is judged by the address
+ * or name it normalizes to.
+ *
+ * @param input - The URL as a stranger wrote it, or one already parsed.
+ * @param options - Which hosts, literals and ports are allowed.
+ * @returns The parsed URL, or the `OutboundError` naming the rule that refused it.
+ * @example checkUrl("https://example.com/feed.xml"); // success
+ * @example checkUrl("http://169.254.169.254/"); // failure: refused-address
+ */
+export function checkUrl(input, options = {}) {
+    let text = String(input);
+    if (!URL.canParse(text)) {
+        return failure(new OutboundError("invalid-url", text, `Refused ${text}: it is not a URL`));
+    }
+    let url = new URL(text);
+    let refuse = (code, why) => failure(new OutboundError(code, url.href, `Refused ${url.href}: ${why}`));
+    if (!(url.protocol in DEFAULT_PORTS)) {
+        return refuse("refused-scheme", "only HTTP(S) is fetched");
+    }
+    if (url.username !== "" || url.password !== "") {
+        return refuse("refused-credentials", "it carries credentials");
+    }
+    if (!isAllowedPort(url, options.ports ?? "any")) {
+        return refuse("refused-port", `port ${url.port} is not allowed`);
+    }
+    if (options.hosts === "any")
+        return success(url);
+    let literal = IP.parse(url.hostname);
+    if (isSuccess(literal)) {
+        if (options.literals === "refuse")
+            return refuse("refused-address", "it names an address");
+        if (!literal.data.isPublic) {
+            return refuse("refused-address", `${literal.data.toString()} is ${literal.data.classification}`);
+        }
+        return success(url);
+    }
+    if (url.hostname.startsWith("["))
+        return refuse("refused-address", "it names an address");
+    if (!isPublicName(url.hostname))
+        return refuse("refused-host", `${url.hostname} is not public`);
+    return success(url);
+}
+/** Whether a URL's port, or its scheme's own when it names none, is one the policy allows. */
+function isAllowedPort(url, ports) {
+    if (ports === "any")
+        return true;
+    if (ports === "default")
+        return url.port === "";
+    let port = url.port === "" ? DEFAULT_PORTS[url.protocol] : Number(url.port);
+    return port !== undefined && ports.includes(port);
+}
+/**
+ * Whether a name may be public. A single label is refused because a resolver's search
+ * domains can complete it into an internal host, and trailing root dots are dropped
+ * first so `localhost.` is judged as `localhost`.
+ */
+function isPublicName(hostname) {
+    let name = hostname.toLowerCase().replace(/\.+$/u, "");
+    if (!name.includes("."))
+        return false;
+    return !RESERVED_SUFFIXES.some((suffix) => name === suffix || name.endsWith(`.${suffix}`));
+}

package/dist/error.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The one failure every check, walk and read in this package answers with: a code a
+ * caller maps to its own error, the URL it concerns, and whether asking again later
+ * can change the outcome.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Why an outbound request was refused or failed. Each `refused-*` code is decided
+ * before a request leaves; `timeout` and `network` are the only outcomes a retry can
+ * change.
+ */
+export type OutboundErrorCode = "invalid-url" | "refused-scheme" | "refused-credentials" | "refused-port" | "refused-host" | "refused-address" | "too-many-redirects" | "too-large" | "timeout" | "network";
+/** Returned inside a `Failure` by every function in this package, never thrown. */
+export declare class OutboundError extends Error {
+    name: string;
+    /** Machine-readable cause, for a caller that maps it to its own error type. */
+    readonly code: OutboundErrorCode;
+    /**
+     * The URL the failure concerns: the hop that was refused or failed, the input text
+     * for `invalid-url`, or an empty string for a body whose message carries no URL.
+     */
+    readonly url: string;
+    /**
+     * @param code - Why the request was refused or failed.
+     * @param url - The URL it concerns.
+     * @param message - The explanation a log shows.
+     * @param options - The underlying error, when one was thrown.
+     */
+    constructor(code: OutboundErrorCode, url: string, message: string, options?: ErrorOptions);
+    /** Whether asking again later can succeed, which holds only for `timeout` and `network`. */
+    get retryable(): boolean;
+}
+/**
+ * Classifies a thrown value from `fetch` or a body stream: a deadline reports itself
+ * as a `TimeoutError`, a capped body errors with its own `OutboundError`, and every
+ * other rejection is the transport's.
+ *
+ * @param url - The URL the failure concerns.
+ * @param error - What was thrown.
+ */
+export declare function failedWith(url: string, error: unknown): OutboundError;

package/dist/error.js

@@ -0,0 +1,60 @@
+/**
+ * The one failure every check, walk and read in this package answers with: a code a
+ * caller maps to its own error, the URL it concerns, and whether asking again later
+ * can change the outcome.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The codes a later attempt can clear: the deadline and the transport. */
+const RETRYABLE_CODES = new Set(["timeout", "network"]);
+/** Returned inside a `Failure` by every function in this package, never thrown. */
+export class OutboundError extends Error {
+    name = "OutboundError";
+    /** Machine-readable cause, for a caller that maps it to its own error type. */
+    code;
+    /**
+     * The URL the failure concerns: the hop that was refused or failed, the input text
+     * for `invalid-url`, or an empty string for a body whose message carries no URL.
+     */
+    url;
+    /**
+     * @param code - Why the request was refused or failed.
+     * @param url - The URL it concerns.
+     * @param message - The explanation a log shows.
+     * @param options - The underlying error, when one was thrown.
+     */
+    constructor(code, url, message, options) {
+        super(message, options);
+        this.code = code;
+        this.url = url;
+    }
+    /** Whether asking again later can succeed, which holds only for `timeout` and `network`. */
+    get retryable() {
+        return RETRYABLE_CODES.has(this.code);
+    }
+}
+/**
+ * Classifies a thrown value from `fetch` or a body stream: a deadline reports itself
+ * as a `TimeoutError`, a capped body errors with its own `OutboundError`, and every
+ * other rejection is the transport's.
+ *
+ * @param url - The URL the failure concerns.
+ * @param error - What was thrown.
+ */
+export function failedWith(url, error) {
+    if (error instanceof OutboundError)
+        return error;
+    let reason = error instanceof Error ? error.message : String(error);
+    let label = url === "" ? "the body" : url;
+    if (isTimeout(error)) {
+        return new OutboundError("timeout", url, `Timed out reading ${label}`, { cause: error });
+    }
+    return new OutboundError("network", url, `Failed to read ${label}: ${reason}`, {
+        cause: error,
+    });
+}
+/** Whether a thrown value is a deadline's reason, which a `DOMException` carries by name. */
+function isTimeout(error) {
+    return (typeof error === "object" && error !== null && "name" in error && error.name === "TimeoutError");
+}

package/dist/follow.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Requests a URL and walks its redirect chain by hand, so every hop passes the same
+ * check as the first, the chain has a length it can exceed, and one deadline covers
+ * the whole chain and the body read after it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Result } from "@sdxc/result";
+import type { CheckOptions } from "./check.js";
+import { OutboundError } from "./error.js";
+/** What a walk sends, and what it may spend; every `checkUrl` option applies to every hop. */
+export interface FollowOptions extends CheckOptions {
+    /** @default "GET" */
+    method?: "GET" | "HEAD";
+    /** Sent on every hop, so the origin sees the same request wherever the chain leads. */
+    headers?: HeadersInit;
+    /** How long the chain and the body read after it may take together. */
+    timeout?: DurationInput;
+    /** @default 5 */
+    maxRedirects?: number;
+    /**
+     * Resolves every hop's name over DNS-over-HTTPS and refuses it when any address is
+     * not public. The connection itself is not pinned to those addresses, so this
+     * narrows DNS rebinding and leaves it open to a name that answers differently twice.
+     *
+     * @default false
+     */
+    resolve?: boolean;
+    /** The caller's own abort, combined with `timeout`. */
+    signal?: AbortSignal;
+}
+/** The last response of a chain, where it came from, and how many hops it took. */
+export interface Followed {
+    /** Answered whatever its status; its body is bound to the walk's deadline. */
+    response: Response;
+    /** Where the chain ended, which is what a relative URL in the body resolves against. */
+    url: URL;
+    redirects: number;
+}
+/**
+ * Requests a URL, following redirects while each one passes the check. Requests carry
+ * no credentials and only the headers given, so the origin sees an anonymous visitor.
+ * A request with a body belongs to a single checked `fetch` with `redirect: "manual"`.
+ *
+ * @param input - The URL to request, as a stranger wrote it.
+ * @param options - The check every hop passes, the headers, and the bounds.
+ * @returns The final response whatever its status, or why there is none.
+ * @example let followed = await follow(url, { timeout: "8 seconds", headers: { accept: "text/html" } });
+ */
+export declare function follow(input: string | URL, options?: FollowOptions): Promise<Result<Followed, OutboundError>>;

package/dist/follow.js

@@ -0,0 +1,101 @@
+/**
+ * Requests a URL and walks its redirect chain by hand, so every hop passes the same
+ * check as the first, the chain has a length it can exceed, and one deadline covers
+ * the whole chain and the body read after it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { toMs } from "@sdxc/duration";
+import { failure, isFailure, success } from "@sdxc/result";
+import { checkUrl } from "./check.js";
+import { failedWith, OutboundError } from "./error.js";
+import { release, withBody } from "./read.js";
+import { resolveHost } from "./resolve.js";
+/** A moved page moves once or twice; five hops covers that with room to spare. */
+const MAX_REDIRECTS = 5;
+/** The statuses that answer with another URL to ask instead. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Requests a URL, following redirects while each one passes the check. Requests carry
+ * no credentials and only the headers given, so the origin sees an anonymous visitor.
+ * A request with a body belongs to a single checked `fetch` with `redirect: "manual"`.
+ *
+ * @param input - The URL to request, as a stranger wrote it.
+ * @param options - The check every hop passes, the headers, and the bounds.
+ * @returns The final response whatever its status, or why there is none.
+ * @example let followed = await follow(url, { timeout: "8 seconds", headers: { accept: "text/html" } });
+ */
+export async function follow(input, options = {}) {
+    let checked = checkUrl(input, options);
+    if (isFailure(checked))
+        return checked;
+    let limit = options.maxRedirects ?? MAX_REDIRECTS;
+    let signal = deadlineOf(options);
+    let headers = new Headers(options.headers);
+    let url = checked.data;
+    for (let redirects = 0;; redirects++) {
+        if (options.resolve && options.hosts !== "any") {
+            let resolved = await resolveHost(url, signal ? { signal } : {});
+            if (isFailure(resolved))
+                return resolved;
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method: options.method ?? "GET",
+                headers,
+                signal,
+                redirect: "manual",
+                credentials: "omit",
+            });
+        }
+        catch (error) {
+            return failure(failedWith(url.href, error));
+        }
+        let next = redirectTarget(response, url);
+        if (next === undefined) {
+            return success({ response: bindBody(response, signal), url, redirects });
+        }
+        release(response.body);
+        if (redirects === limit) {
+            let first = checked.data.href;
+            return failure(new OutboundError("too-many-redirects", first, `Refused ${first}: more than ${limit} redirects`));
+        }
+        let hop = checkUrl(next, options);
+        if (isFailure(hop))
+            return hop;
+        url = hop.data;
+    }
+}
+/** The one signal every hop and the body carry, or none when the caller set no bound. */
+function deadlineOf(options) {
+    let signals = [];
+    if (options.timeout !== undefined)
+        signals.push(AbortSignal.timeout(toMs(options.timeout)));
+    if (options.signal)
+        signals.push(options.signal);
+    return signals.length > 0 ? AbortSignal.any(signals) : undefined;
+}
+/**
+ * Ties a body to the walk's deadline, so a body that is still arriving when it passes
+ * errors with the deadline's reason in every runtime and the read fails `timeout`.
+ */
+function bindBody(response, signal) {
+    if (signal === undefined || response.body === null)
+        return response;
+    return withBody(response, response.body.pipeThrough(new TransformStream(), { signal }));
+}
+/**
+ * Names the URL a response sends the client on to, absent when it is an answer rather
+ * than a redirect, or when its `Location` is not a URL and so leaves the status itself
+ * as the outcome.
+ */
+function redirectTarget(response, from) {
+    if (!REDIRECT_STATUSES.has(response.status))
+        return undefined;
+    let location = response.headers.get("location");
+    if (location === null || !URL.canParse(location, from))
+        return undefined;
+    return new URL(location, from).href;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The package entrypoint: checking and following a URL a stranger chose, which only
+ * the public internet needs, beside reading any message's body within a cap, which
+ * every runtime boundary needs. Every failure is one `OutboundError`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { CheckOptions } from "./check.js";
+export type { OutboundErrorCode } from "./error.js";
+export type { Followed, FollowOptions } from "./follow.js";
+export type { ReadBytes, ReadOptions, ReadText } from "./read.js";
+export type { ResolveHostOptions } from "./resolve.js";
+export { checkUrl } from "./check.js";
+export { OutboundError } from "./error.js";
+export { follow } from "./follow.js";
+export { limitBody, readBytes, readText, release } from "./read.js";
+export { resolveHost } from "./resolve.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * The package entrypoint: checking and following a URL a stranger chose, which only
+ * the public internet needs, beside reading any message's body within a cap, which
+ * every runtime boundary needs. Every failure is one `OutboundError`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { checkUrl } from "./check.js";
+export { OutboundError } from "./error.js";
+export { follow } from "./follow.js";
+export { limitBody, readBytes, readText, release } from "./read.js";
+export { resolveHost } from "./resolve.js";

package/dist/read.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reads, caps and lets go of message bodies, whichever runtime handed over the
+ * message: the global `fetch`, a binding, a router, or a request a handler received.
+ * The count over the stream enforces the cap, so a body never sits whole past it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { OutboundError } from "./error.js";
+/** How large a body may be. */
+export interface ReadOptions {
+    /** The most bytes the body may carry; one more and the read fails `too-large`. */
+    maxBytes: number;
+}
+/** A body read as text, and the bytes that came off the wire to produce it. */
+export interface ReadText {
+    text: string;
+    bytes: number;
+}
+/** A body read as bytes, exactly as they arrived. */
+export interface ReadBytes {
+    data: Uint8Array<ArrayBuffer>;
+    bytes: number;
+}
+/**
+ * Reads a body as UTF-8 text within a cap.
+ *
+ * @param message - The request or response whose body to read.
+ * @param options - The cap.
+ * @returns The text and its size in bytes; `too-large` past the cap, `timeout` when the
+ * deadline `follow` set passed mid-body, and `network` when the stream broke off.
+ * @example let body = await readText(response, { maxBytes: 2 * 1024 * 1024 });
+ */
+export declare function readText(message: Request | Response, options: ReadOptions): Promise<Result<ReadText, OutboundError>>;
+/**
+ * Reads a body as bytes within a cap, for a caller that verifies a signature over the
+ * exact bytes or decodes them itself.
+ *
+ * @param message - The request or response whose body to read.
+ * @param options - The cap.
+ * @returns The bytes and their count, or the same failures as `readText`.
+ * @example let body = await readBytes(request, { maxBytes: 1024 * 1024 });
+ */
+export declare function readBytes(message: Request | Response, options: ReadOptions): Promise<Result<ReadBytes, OutboundError>>;
+/**
+ * Answers the same response with a body that errors with a `too-large` `OutboundError`
+ * at the first chunk past the cap, for a body passed through rather than read. A
+ * declared length over the cap errors the body before any of it is forwarded.
+ *
+ * @param response - The response whose body to cap.
+ * @param options - The cap.
+ * @returns A response with the same status and headers, and the capped body.
+ * @example return limitBody(upstream, { maxBytes: 5 * 1024 * 1024 });
+ */
+export declare function limitBody(response: Response, options: ReadOptions): Response;
+/**
+ * Lets go of a body left unread, telling the origin it may stop sending. The
+ * cancellation runs on its own, so a stream that stalls costs the caller nothing.
+ *
+ * @param source - A body, a reader of one, or `null` for a message with none.
+ * @example release(response.body);
+ */
+export declare function release(source: {
+    cancel(): Promise<void>;
+} | null): void;
+/**
+ * The same response around a new body, keeping the URL it came from, so an error
+ * reading the new body still names where it was fetched.
+ */
+export declare function withBody(response: Response, body: ReadableStream<Uint8Array>): Response;
+/** Reads the length a message claims, for the refusal that costs no bytes at all. */
+export declare function declaredLength(message: Request | Response): number | undefined;

package/dist/read.js

@@ -0,0 +1,151 @@
+/**
+ * Reads, caps and lets go of message bodies, whichever runtime handed over the
+ * message: the global `fetch`, a binding, a router, or a request a handler received.
+ * The count over the stream enforces the cap, so a body never sits whole past it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { failedWith, OutboundError } from "./error.js";
+/**
+ * Reads a body as UTF-8 text within a cap.
+ *
+ * @param message - The request or response whose body to read.
+ * @param options - The cap.
+ * @returns The text and its size in bytes; `too-large` past the cap, `timeout` when the
+ * deadline `follow` set passed mid-body, and `network` when the stream broke off.
+ * @example let body = await readText(response, { maxBytes: 2 * 1024 * 1024 });
+ */
+export async function readText(message, options) {
+    let decoder = new TextDecoder();
+    let text = "";
+    let read = await consume(message, options.maxBytes, (chunk) => {
+        text += decoder.decode(chunk, { stream: true });
+    });
+    if (isFailure(read))
+        return read;
+    return success({ text: text + decoder.decode(), bytes: read.data });
+}
+/**
+ * Reads a body as bytes within a cap, for a caller that verifies a signature over the
+ * exact bytes or decodes them itself.
+ *
+ * @param message - The request or response whose body to read.
+ * @param options - The cap.
+ * @returns The bytes and their count, or the same failures as `readText`.
+ * @example let body = await readBytes(request, { maxBytes: 1024 * 1024 });
+ */
+export async function readBytes(message, options) {
+    let chunks = [];
+    let read = await consume(message, options.maxBytes, (chunk) => {
+        chunks.push(chunk);
+    });
+    if (isFailure(read))
+        return read;
+    let data = new Uint8Array(new ArrayBuffer(read.data));
+    let offset = 0;
+    for (let chunk of chunks) {
+        data.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return success({ data, bytes: read.data });
+}
+/**
+ * Answers the same response with a body that errors with a `too-large` `OutboundError`
+ * at the first chunk past the cap, for a body passed through rather than read. A
+ * declared length over the cap errors the body before any of it is forwarded.
+ *
+ * @param response - The response whose body to cap.
+ * @param options - The cap.
+ * @returns A response with the same status and headers, and the capped body.
+ * @example return limitBody(upstream, { maxBytes: 5 * 1024 * 1024 });
+ */
+export function limitBody(response, options) {
+    if (response.body === null)
+        return response;
+    let { maxBytes } = options;
+    let url = response.url;
+    let declared = declaredLength(response);
+    let seen = 0;
+    let capped = new TransformStream({
+        start(controller) {
+            if (declared !== undefined && declared > maxBytes)
+                controller.error(tooLarge(url, maxBytes));
+        },
+        transform(chunk, controller) {
+            seen += chunk.byteLength;
+            if (seen > maxBytes)
+                controller.error(tooLarge(url, maxBytes));
+            else
+                controller.enqueue(chunk);
+        },
+    });
+    return withBody(response, response.body.pipeThrough(capped));
+}
+/**
+ * Lets go of a body left unread, telling the origin it may stop sending. The
+ * cancellation runs on its own, so a stream that stalls costs the caller nothing.
+ *
+ * @param source - A body, a reader of one, or `null` for a message with none.
+ * @example release(response.body);
+ */
+export function release(source) {
+    void source?.cancel().catch(() => undefined);
+}
+/**
+ * The same response around a new body, keeping the URL it came from, so an error
+ * reading the new body still names where it was fetched.
+ */
+export function withBody(response, body) {
+    let replaced = new Response(body, response);
+    Object.defineProperty(replaced, "url", { value: response.url });
+    return replaced;
+}
+/** Reads the length a message claims, for the refusal that costs no bytes at all. */
+export function declaredLength(message) {
+    let header = message.headers.get("content-length");
+    if (header === null)
+        return undefined;
+    let length = Number(header);
+    return Number.isFinite(length) ? length : undefined;
+}
+/**
+ * Hands every chunk of a body to `take` and answers how many bytes it read. A
+ * declared length over the cap fails before a byte is read, and crossing the cap
+ * cancels the stream so the origin stops sending.
+ */
+async function consume(message, maxBytes, take) {
+    let url = message.url;
+    let declared = declaredLength(message);
+    if (declared !== undefined && declared > maxBytes) {
+        release(message.body);
+        return failure(tooLarge(url, maxBytes));
+    }
+    if (message.body === null)
+        return success(0);
+    let reader = message.body.getReader();
+    let bytes = 0;
+    try {
+        for (;;) {
+            let { done, value } = await reader.read();
+            if (done || value === undefined)
+                break;
+            bytes += value.byteLength;
+            if (bytes > maxBytes) {
+                release(reader);
+                return failure(tooLarge(url, maxBytes));
+            }
+            take(value);
+        }
+    }
+    catch (error) {
+        return failure(failedWith(url, error));
+    }
+    return success(bytes);
+}
+/** The failure for a body past its cap. */
+function tooLarge(url, maxBytes) {
+    let label = url === "" ? "the body" : url;
+    return new OutboundError("too-large", url, `Refused ${label}: it exceeded the ${maxBytes} byte cap`);
+}

package/dist/resolve.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolves a URL's host over DNS-over-HTTPS and refuses it unless every address it
+ * answers with is public, which is what catches a public name whose records point
+ * inside a network. A Worker cannot pin a connection to the addresses checked here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { OutboundError } from "./error.js";
+/** What a lookup may spend. */
+export interface ResolveHostOptions {
+    /** Aborts both lookups, so the caller's deadline covers resolution too. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolves the `A` and `AAAA` records of a URL's host. An address literal answers
+ * itself. A record the resolver could not parse is refused with the rest, since an
+ * address that cannot be read cannot be judged public.
+ *
+ * @param url - A URL, normally one `checkUrl` already let through.
+ * @param options - The signal both lookups carry.
+ * @returns Every address the host resolved to, all public; `refused-host` for a name
+ * with no address, `refused-address` for any address that is not public, and
+ * `network` when the resolver could not answer.
+ * @example let addresses = await resolveHost(new URL("https://example.com/"));
+ */
+export declare function resolveHost(url: URL, options?: ResolveHostOptions): Promise<Result<string[], OutboundError>>;

package/dist/resolve.js

@@ -0,0 +1,62 @@
+/**
+ * Resolves a URL's host over DNS-over-HTTPS and refuses it unless every address it
+ * answers with is public, which is what catches a public name whose records point
+ * inside a network. A Worker cannot pin a connection to the addresses checked here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { NameNotFoundError, resolve } from "@sdxc/doh";
+import { IP } from "@sdxc/ip";
+import { failure, isFailure, isSuccess, success } from "@sdxc/result";
+import { OutboundError } from "./error.js";
+/**
+ * Resolves the `A` and `AAAA` records of a URL's host. An address literal answers
+ * itself. A record the resolver could not parse is refused with the rest, since an
+ * address that cannot be read cannot be judged public.
+ *
+ * @param url - A URL, normally one `checkUrl` already let through.
+ * @param options - The signal both lookups carry.
+ * @returns Every address the host resolved to, all public; `refused-host` for a name
+ * with no address, `refused-address` for any address that is not public, and
+ * `network` when the resolver could not answer.
+ * @example let addresses = await resolveHost(new URL("https://example.com/"));
+ */
+export async function resolveHost(url, options = {}) {
+    let literal = IP.parse(url.hostname);
+    if (isSuccess(literal))
+        return success([literal.data.toString()]);
+    let host = url.hostname.replace(/\.+$/u, "");
+    let lookup = options.signal ? { signal: options.signal } : {};
+    let [a, aaaa] = await Promise.all([resolve(host, "A", lookup), resolve(host, "AAAA", lookup)]);
+    if (isFailure(a))
+        return failure(lookupFailed(url, host, a.error));
+    if (isFailure(aaaa))
+        return failure(lookupFailed(url, host, aaaa.error));
+    if (a.data.unparsed.length > 0 || aaaa.data.unparsed.length > 0) {
+        return failure(new OutboundError("refused-address", url.href, `Refused ${url.href}: ${host} answered an unreadable address`));
+    }
+    let addresses = [...a.data.records, ...aaaa.data.records].map((record) => record.address);
+    if (addresses.length === 0) {
+        return failure(new OutboundError("refused-host", url.href, `Refused ${url.href}: ${host} has no address`));
+    }
+    for (let address of addresses) {
+        let ip = IP.parse(address);
+        if (isSuccess(ip) && ip.data.isPublic)
+            continue;
+        return failure(new OutboundError("refused-address", url.href, `Refused ${url.href}: ${host} resolves to ${address}`));
+    }
+    return success(addresses);
+}
+/**
+ * Reads a failed lookup: NXDOMAIN is the name saying it does not exist, which no
+ * retry changes, and every other failure is the resolver's.
+ */
+function lookupFailed(url, host, error) {
+    if (error instanceof NameNotFoundError) {
+        return new OutboundError("refused-host", url.href, `Refused ${url.href}: ${host} does not exist`);
+    }
+    return new OutboundError("network", url.href, `Failed to resolve ${host}: ${error.message}`, {
+        cause: error,
+    });
+}

package/package.json

@@ -1,6 +1,34 @@
 {
-  "name": "@sdxc/outbound",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sdxc/outbound",
+	"version": "2026.10.6",
+	"description": "Check, follow and read URLs a stranger chose: public hosts on every redirect, one deadline, bounded bodies",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/doh": "2026.10.6",
+		"@sdxc/duration": "2026.10.6",
+		"@sdxc/ip": "2026.10.6",
+		"@sdxc/result": "2026.10.6"
+	},
+	"gitHead": "b1067eb20fc47ec51ff8c4de47d07dc3f9c00466",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/outbound"
+	},
+	"homepage": "https://sdxc.sergiodxa.com/api/outbound",
+	"author": {
+		"name": "Sergio Xalambrí",
+		"url": "https://sergiodxa.com"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/sergiodxa"
+	}
+}