@oxyhq/core 3.9.1 → 3.10.0

package/dist/cjs/server/cors.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Strict CORS allowlist for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * App backends kept hand-rolling CORS, and the unsafe patterns recurred:
+ *   - `Access-Control-Allow-Origin: *` together with credentials (which is
+ *     spec-invalid AND a credential-leak vector), or
+ *   - a "reflect whatever Origin the request carried" fallback (effectively
+ *     `*` for credentialed requests — the Allo wildcard-fallback class).
+ *
+ * `createOxyCors` returns a self-contained Express middleware (no `cors`
+ * package dependency) that:
+ *   - allows the Oxy apex origin family (anything under `*.${CENTRAL_IDP_APEX}`,
+ *     i.e. `oxy.so` — covering `auth.oxy.so`, `api.oxy.so`, `accounts.oxy.so`,
+ *     `console.oxy.so`, `inbox.oxy.so`, the marketing site, …) reusing the
+ *     central-origin constants already in core, NOT a fresh hardcoded list,
+ *   - allows the caller's explicit `appOrigins`,
+ *   - DENIES everything else (no reflection, never a wildcard with credentials),
+ *   - echoes back the EXACT matched origin (so credentialed requests work) and
+ *     sets `Vary: Origin` for correct caching,
+ *   - answers CORS preflight (`OPTIONS`) with `204`.
+ *
+ * Node/Express-only: exported solely from `@oxyhq/core/server`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOxyCors = createOxyCors;
+const authWebUrl_1 = require("../utils/authWebUrl");
+const fapiAutoDetect_1 = require("../utils/fapiAutoDetect");
+/** Default HTTP methods allowed across origins. */
+const DEFAULT_ALLOWED_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'];
+/** Default request headers a browser may send on a credentialed cross-origin call. */
+const DEFAULT_ALLOWED_HEADERS = [
+    'Content-Type',
+    'Authorization',
+    'X-Requested-With',
+    'X-Oxy-User-Id',
+    'X-Oxy-Internal',
+    'X-CSRF-Token',
+];
+/** How long (seconds) a browser may cache a successful preflight. */
+const DEFAULT_MAX_AGE_SECONDS = 86400;
+/**
+ * Whether `candidate` belongs to the Oxy apex origin family — i.e. its
+ * registrable apex equals {@link CENTRAL_IDP_APEX} (`oxy.so`). This matches the
+ * apex itself (`https://oxy.so`) and any subdomain (`https://auth.oxy.so`,
+ * `https://api.oxy.so`, …) over http or https, ports allowed. Returns false on
+ * any parse failure (fail closed).
+ */
+function isOxyFamilyOrigin(candidate) {
+    let hostname;
+    let protocol;
+    try {
+        const url = new URL(candidate);
+        hostname = url.hostname.toLowerCase();
+        protocol = url.protocol;
+    }
+    catch {
+        return false;
+    }
+    if (protocol !== 'https:' && protocol !== 'http:')
+        return false;
+    if (hostname === authWebUrl_1.CENTRAL_IDP_APEX)
+        return true;
+    return (0, fapiAutoDetect_1.registrableApex)(hostname) === authWebUrl_1.CENTRAL_IDP_APEX;
+}
+/** Normalize a raw origin string to its canonical `scheme://host[:port]` form. */
+function normalizeOrigin(raw) {
+    try {
+        return new URL(raw).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the origin-matching predicate: true iff `origin` is in the Oxy apex
+ * family OR exactly matches one of the configured app origins.
+ */
+function buildOriginAllowed(appOrigins) {
+    const explicit = new Set();
+    for (const raw of appOrigins) {
+        const normalized = normalizeOrigin(raw);
+        if (normalized)
+            explicit.add(normalized);
+    }
+    return (origin) => {
+        const normalized = normalizeOrigin(origin);
+        if (normalized === null)
+            return false;
+        if (explicit.has(normalized))
+            return true;
+        return isOxyFamilyOrigin(normalized);
+    };
+}
+/**
+ * Create a strict Oxy CORS middleware. See module docs.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxyCors({ appOrigins: ['https://app.example.com'] }));
+ * ```
+ */
+function createOxyCors(options = {}) {
+    const { appOrigins = [], allowCredentials = true, methods = DEFAULT_ALLOWED_METHODS, allowedHeaders = DEFAULT_ALLOWED_HEADERS, exposedHeaders = [], maxAgeSeconds = DEFAULT_MAX_AGE_SECONDS, } = options;
+    const isOriginAllowed = buildOriginAllowed(appOrigins);
+    const methodsHeader = methods.join(', ');
+    const allowedHeadersHeader = allowedHeaders.join(', ');
+    const exposedHeadersHeader = exposedHeaders.join(', ');
+    return (req, res, next) => {
+        const origin = req.headers.origin;
+        // Same-origin or non-browser requests carry no Origin header — pass through
+        // untouched (no ACAO header is emitted, which is correct for them).
+        if (typeof origin !== 'string' || origin.length === 0) {
+            if (req.method === 'OPTIONS') {
+                res.sendStatus(204);
+                return;
+            }
+            next();
+            return;
+        }
+        // Origin is present. Caching correctness: this response varies by Origin.
+        res.setHeader('Vary', 'Origin');
+        if (!isOriginAllowed(origin)) {
+            // DENY: do NOT reflect the origin, do NOT emit a wildcard. The browser
+            // will block the cross-origin read. Preflights for denied origins get a
+            // 204 with no CORS headers (the actual request then fails CORS).
+            if (req.method === 'OPTIONS') {
+                res.sendStatus(204);
+                return;
+            }
+            next();
+            return;
+        }
+        // ALLOW: echo the EXACT matched origin — never `*`, even without credentials.
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        if (allowCredentials) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        if (exposedHeadersHeader) {
+            res.setHeader('Access-Control-Expose-Headers', exposedHeadersHeader);
+        }
+        if (req.method === 'OPTIONS') {
+            res.setHeader('Access-Control-Allow-Methods', methodsHeader);
+            // Honour the browser's requested headers when present, else the default set.
+            const requested = req.headers['access-control-request-headers'];
+            res.setHeader('Access-Control-Allow-Headers', typeof requested === 'string' && requested.length > 0 ? requested : allowedHeadersHeader);
+            res.setHeader('Access-Control-Max-Age', String(maxAgeSeconds));
+            res.sendStatus(204);
+            return;
+        }
+        next();
+    };
+}

package/dist/cjs/server/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createOxyRateLimit = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getOxyUserId = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
+exports.verifySecret = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getOxyUserId = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "createOptionalOxyAuth", { enumerable: true, get: function () { return auth_1.createOptionalOxyAuth; } });
 Object.defineProperty(exports, "createOxyAuthMiddleware", { enumerable: true, get: function () { return auth_1.createOxyAuthMiddleware; } });
@@ -26,3 +26,23 @@ Object.defineProperty(exports, "isOxyAuthenticated", { enumerable: true, get: fu
 Object.defineProperty(exports, "requireOxyAuth", { enumerable: true, get: function () { return auth_1.requireOxyAuth; } });
 var rateLimit_1 = require("./rateLimit");
 Object.defineProperty(exports, "createOxyRateLimit", { enumerable: true, get: function () { return rateLimit_1.createOxyRateLimit; } });
+// SSRF-safe upstream fetch + URL validation (Node-only).
+var safeFetch_1 = require("./safeFetch");
+Object.defineProperty(exports, "assertSafePublicUrl", { enumerable: true, get: function () { return safeFetch_1.assertSafePublicUrl; } });
+Object.defineProperty(exports, "isBlockedIp", { enumerable: true, get: function () { return safeFetch_1.isBlockedIp; } });
+Object.defineProperty(exports, "safeFetch", { enumerable: true, get: function () { return safeFetch_1.safeFetch; } });
+Object.defineProperty(exports, "SsrfRejection", { enumerable: true, get: function () { return safeFetch_1.SsrfRejection; } });
+Object.defineProperty(exports, "UpstreamError", { enumerable: true, get: function () { return safeFetch_1.UpstreamError; } });
+Object.defineProperty(exports, "ALLOWED_PORTS", { enumerable: true, get: function () { return safeFetch_1.ALLOWED_PORTS; } });
+Object.defineProperty(exports, "ALLOWED_PROTOCOLS", { enumerable: true, get: function () { return safeFetch_1.ALLOWED_PROTOCOLS; } });
+Object.defineProperty(exports, "BLOCKED_HOSTNAMES", { enumerable: true, get: function () { return safeFetch_1.BLOCKED_HOSTNAMES; } });
+Object.defineProperty(exports, "DEFAULT_USER_AGENT", { enumerable: true, get: function () { return safeFetch_1.DEFAULT_USER_AGENT; } });
+Object.defineProperty(exports, "MAX_REDIRECTS", { enumerable: true, get: function () { return safeFetch_1.MAX_REDIRECTS; } });
+Object.defineProperty(exports, "MAX_URL_LENGTH", { enumerable: true, get: function () { return safeFetch_1.MAX_URL_LENGTH; } });
+Object.defineProperty(exports, "UPSTREAM_HEADERS_TIMEOUT_MS", { enumerable: true, get: function () { return safeFetch_1.UPSTREAM_HEADERS_TIMEOUT_MS; } });
+// Strict CORS allowlist (Oxy apex family + explicit app origins).
+var cors_1 = require("./cors");
+Object.defineProperty(exports, "createOxyCors", { enumerable: true, get: function () { return cors_1.createOxyCors; } });
+// Constant-time secret comparison.
+var verifySecret_1 = require("./verifySecret");
+Object.defineProperty(exports, "verifySecret", { enumerable: true, get: function () { return verifySecret_1.verifySecret; } });

package/dist/cjs/server/safeFetch.js

@@ -0,0 +1,458 @@
+"use strict";
+/**
+ * SSRF-safe upstream HTTP fetch for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every Oxy backend that contacts a caller-influenced URL — media proxies,
+ * the website MCP image upload/debug tools, federated fetches, link
+ * unfurlers — needs the exact same Server-Side Request Forgery (SSRF)
+ * defence. Apps were re-implementing it (or worse, omitting it), so the
+ * gold-standard primitive (originally `packages/backend/src/utils` in
+ * Mention) lives here ONCE.
+ *
+ * THE CONTRACT
+ * ------------
+ *  - Every URL — including each redirect hop — is validated by
+ *    {@link assertSafePublicUrl}: a real DNS resolution plus a denylist of
+ *    private/reserved/metadata ranges (10/8, 127/8, 169.254.169.254, ::1, …).
+ *  - The TCP connection is PINNED to the validated IP via a custom `lookup`,
+ *    closing the DNS-rebind TOCTOU window — DNS is NOT re-resolved at connect
+ *    time, so the address we validated is exactly the address Node connects to.
+ *  - Redirects are followed manually (bounded) so every hop is re-validated and
+ *    redirect bodies (potentially unbounded) are destroyed, not drained.
+ *
+ * Node-only: this module imports `node:http`/`node:https`/`node:dns` and is
+ * exported solely from `@oxyhq/core/server`. It MUST NOT be reachable from the
+ * browser `@oxyhq/core` entry.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpstreamError = exports.SsrfRejection = exports.BLOCKED_HOSTNAMES = exports.DEFAULT_USER_AGENT = exports.MAX_REDIRECTS = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.MAX_URL_LENGTH = void 0;
+exports.isBlockedIp = isBlockedIp;
+exports.assertSafePublicUrl = assertSafePublicUrl;
+exports.safeFetch = safeFetch;
+const node_http_1 = __importDefault(require("node:http"));
+const node_https_1 = __importDefault(require("node:https"));
+const promises_1 = require("node:dns/promises");
+const node_net_1 = require("node:net");
+const node_url_1 = require("node:url");
+/** Maximum accepted length of an input URL (DoS guard). */
+exports.MAX_URL_LENGTH = 2048;
+/** The only network ports a safe fetch is allowed to reach upstream. */
+exports.ALLOWED_PORTS = new Set([80, 443]);
+/** Protocols a safe fetch is allowed to contact. */
+exports.ALLOWED_PROTOCOLS = new Set(['http:', 'https:']);
+/**
+ * Time-to-first-byte deadline: how long to wait for the upstream to establish
+ * the connection and send its RESPONSE HEADERS before aborting. Enforced via
+ * `req.setTimeout` on the `ClientRequest`; once headers arrive, the caller owns
+ * the (longer) streaming lifetime of the response body.
+ */
+exports.UPSTREAM_HEADERS_TIMEOUT_MS = 8000;
+/** Maximum number of HTTP redirects to follow; each hop is re-validated. */
+exports.MAX_REDIRECTS = 5;
+/** Default User-Agent presented to upstreams when the caller does not set one. */
+exports.DEFAULT_USER_AGENT = 'OxyServices/1.0 (+https://oxy.so)';
+/** HTTP status codes that indicate a redirect we should follow. */
+const REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Matches hosts composed exclusively of characters that appear in numeric IP
+ * notations — decimal/hex digits, dots, colons and the hex marker `x`. A real
+ * DNS hostname always carries at least one alphabetic label character outside
+ * this set. Used to reject ambiguous partial/mixed numeric forms (`127.1`,
+ * `0x7f.1`, `0177.0.0.1`, `2130706433`) that `isIP()` does not accept as a
+ * literal but that the OS resolver may canonicalize into a loopback/internal
+ * address — and inconsistently so across glibc vs. musl (prod is Alpine/musl).
+ */
+const AMBIGUOUS_NUMERIC_HOST = /^[0-9a-fx.:]+$/i;
+/** Hostnames that must never be resolved or contacted, regardless of DNS. */
+exports.BLOCKED_HOSTNAMES = new Set([
+    'localhost',
+    'localhost.localdomain',
+    'ip6-localhost',
+    'ip6-loopback',
+]);
+/**
+ * IPv4 CIDR denylist (network, prefix-length) covering loopback, RFC1918
+ * private, link-local (incl. cloud metadata 169.254.169.254), shared CGNAT,
+ * "this host", multicast and reserved/broadcast space.
+ */
+const BLOCKED_IPV4_CIDRS = [
+    ['0.0.0.0', 8], // "this" network
+    ['10.0.0.0', 8], // RFC1918 private
+    ['100.64.0.0', 10], // RFC6598 CGNAT / shared address space
+    ['127.0.0.0', 8], // loopback
+    ['169.254.0.0', 16], // link-local (cloud instance metadata 169.254.169.254)
+    ['172.16.0.0', 12], // RFC1918 private
+    ['192.0.0.0', 24], // IETF protocol assignments
+    ['192.0.2.0', 24], // TEST-NET-1 (documentation)
+    ['192.168.0.0', 16], // RFC1918 private
+    ['198.18.0.0', 15], // benchmarking
+    ['198.51.100.0', 24], // TEST-NET-2 (documentation)
+    ['203.0.113.0', 24], // TEST-NET-3 (documentation)
+    ['224.0.0.0', 4], // multicast
+    ['240.0.0.0', 4], // reserved / future use (incl. 255.255.255.255 broadcast)
+];
+/**
+ * IPv6 prefix denylist (prefix, prefix-length) covering loopback, unspecified,
+ * unique-local (fc00::/7), link-local (fe80::/10), multicast and documentation.
+ * IPv4-mapped/embedded addresses are unwrapped to IPv4 before reaching here.
+ */
+const BLOCKED_IPV6_CIDRS = [
+    ['::1', 128], // loopback
+    ['::', 128], // unspecified
+    ['fc00::', 7], // unique local address
+    ['fe80::', 10], // link-local
+    ['ff00::', 8], // multicast
+    ['2001:db8::', 32], // documentation
+    ['64:ff9b::', 96], // NAT64 (maps to IPv4 — IPv4 denylist still applies after unwrap)
+];
+/** Number of bits in each IPv4 octet. */
+const IPV4_OCTET_BITS = 8;
+/** Number of octets in an IPv4 address. */
+const IPV4_OCTETS = 4;
+/** Number of bits in each IPv6 16-bit group. */
+const IPV6_GROUP_BITS = 16;
+/** Number of 16-bit groups in an IPv6 address. */
+const IPV6_GROUPS = 8;
+/** Convert a dotted-quad IPv4 string into its unsigned 32-bit integer value. */
+function ipv4ToInt(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== IPV4_OCTETS)
+        return null;
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const octet = Number(part);
+        if (octet > 255)
+            return null;
+        value = value * 256 + octet;
+    }
+    // Force unsigned 32-bit.
+    return value >>> 0;
+}
+/** Test whether an IPv4 address falls inside a CIDR block. */
+function ipv4InCidr(ip, network, prefix) {
+    const ipInt = ipv4ToInt(ip);
+    const netInt = ipv4ToInt(network);
+    if (ipInt === null || netInt === null)
+        return false;
+    if (prefix === 0)
+        return true;
+    const mask = (0xffffffff << (IPV4_OCTET_BITS * IPV4_OCTETS - prefix)) >>> 0;
+    return (ipInt & mask) === (netInt & mask);
+}
+/** Expand an IPv6 address (possibly using `::`) into its 8 group values. */
+function ipv6ToGroups(ip) {
+    // Strip a zone index (e.g. "fe80::1%eth0") — not relevant for range checks.
+    const zoneless = ip.split('%')[0];
+    // An IPv4-mapped/embedded tail (e.g. "::ffff:1.2.3.4") is handled by the
+    // caller, which unwraps to IPv4 before calling this. Reject here to be safe.
+    if (zoneless.includes('.'))
+        return null;
+    const halves = zoneless.split('::');
+    if (halves.length > 2)
+        return null;
+    const parseGroups = (segment) => {
+        if (segment === '')
+            return [];
+        const groups = [];
+        for (const part of segment.split(':')) {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(part))
+                return null;
+            groups.push(parseInt(part, 16));
+        }
+        return groups;
+    };
+    const head = parseGroups(halves[0]);
+    if (head === null)
+        return null;
+    if (halves.length === 1) {
+        return head.length === IPV6_GROUPS ? head : null;
+    }
+    const tail = parseGroups(halves[1]);
+    if (tail === null)
+        return null;
+    const missing = IPV6_GROUPS - head.length - tail.length;
+    if (missing < 0)
+        return null;
+    return [...head, ...new Array(missing).fill(0), ...tail];
+}
+/** Test whether an IPv6 address falls inside a prefix block. */
+function ipv6InCidr(ip, network, prefix) {
+    const ipGroups = ipv6ToGroups(ip);
+    const netGroups = ipv6ToGroups(network);
+    if (ipGroups === null || netGroups === null)
+        return false;
+    let bitsRemaining = prefix;
+    for (let i = 0; i < IPV6_GROUPS; i++) {
+        if (bitsRemaining <= 0)
+            break;
+        const groupBits = Math.min(IPV6_GROUP_BITS, bitsRemaining);
+        const mask = (0xffff << (IPV6_GROUP_BITS - groupBits)) & 0xffff;
+        if ((ipGroups[i] & mask) !== (netGroups[i] & mask))
+            return false;
+        bitsRemaining -= groupBits;
+    }
+    return true;
+}
+/**
+ * Unwrap an IPv4-mapped/compatible/NAT64 IPv6 address to its embedded IPv4
+ * dotted-quad form, so the IPv4 denylist applies. Returns null if not embedded.
+ */
+function extractEmbeddedIpv4(ip) {
+    const lower = ip.toLowerCase();
+    // Forms like "::ffff:1.2.3.4" already carry dotted-quad notation.
+    const dotted = lower.match(/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (dotted && (lower.startsWith('::ffff:') || lower.startsWith('::'))) {
+        return dotted[1];
+    }
+    // Hex form "::ffff:0102:0304" → 1.2.3.4
+    const hexMapped = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hexMapped) {
+        const hi = parseInt(hexMapped[1], 16);
+        const lo = parseInt(hexMapped[2], 16);
+        return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+    }
+    return null;
+}
+/**
+ * Return true if a literal IP address is private/loopback/link-local/reserved/
+ * multicast/metadata and therefore must NOT be contacted.
+ */
+function isBlockedIp(rawIp) {
+    const family = (0, node_net_1.isIP)(rawIp);
+    if (family === 0) {
+        // Not a valid IP literal — treat as blocked (fail closed).
+        return true;
+    }
+    if (family === 4) {
+        return BLOCKED_IPV4_CIDRS.some(([net, prefix]) => ipv4InCidr(rawIp, net, prefix));
+    }
+    // IPv6: first unwrap any embedded IPv4 and apply the IPv4 denylist.
+    const embedded = extractEmbeddedIpv4(rawIp);
+    if (embedded !== null) {
+        return BLOCKED_IPV4_CIDRS.some(([net, prefix]) => ipv4InCidr(embedded, net, prefix));
+    }
+    return BLOCKED_IPV6_CIDRS.some(([net, prefix]) => ipv6InCidr(rawIp, net, prefix));
+}
+/**
+ * Validate that a URL is syntactically a public http(s) URL and that its
+ * hostname resolves ONLY to non-blocked, public IP addresses.
+ *
+ * On success, returns the single validated IP (the first allowed record) that
+ * the HTTP client MUST pin its connection to. Every resolved address is checked;
+ * if ANY resolves into a blocked range the URL is rejected (an attacker
+ * controlling a multi-record DNS response cannot smuggle one internal IP past
+ * the check).
+ *
+ * Re-run this on EVERY redirect hop so a public hostname cannot redirect (or
+ * DNS-rebind) into an internal address.
+ */
+async function assertSafePublicUrl(rawUrl) {
+    if (typeof rawUrl !== 'string' || rawUrl.length === 0) {
+        return { ok: false, reason: 'missing url' };
+    }
+    if (rawUrl.length > exports.MAX_URL_LENGTH) {
+        return { ok: false, reason: 'url too long' };
+    }
+    let parsed;
+    try {
+        parsed = new node_url_1.URL(rawUrl);
+    }
+    catch {
+        return { ok: false, reason: 'malformed url' };
+    }
+    if (!exports.ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        return { ok: false, reason: `disallowed protocol ${parsed.protocol}` };
+    }
+    // Reject embedded credentials (user:pass@host) — never appropriate here.
+    if (parsed.username !== '' || parsed.password !== '') {
+        return { ok: false, reason: 'credentials in url not allowed' };
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname.length === 0) {
+        return { ok: false, reason: 'empty hostname' };
+    }
+    if (exports.BLOCKED_HOSTNAMES.has(hostname)) {
+        return { ok: false, reason: 'blocked hostname' };
+    }
+    // Enforce the standard-port allowlist. An empty `port` means the protocol
+    // default (80/443), which is allowed.
+    if (parsed.port !== '') {
+        const port = Number(parsed.port);
+        if (!Number.isInteger(port) || !exports.ALLOWED_PORTS.has(port)) {
+            return { ok: false, reason: `disallowed port ${parsed.port}` };
+        }
+    }
+    // If the hostname is already a literal IP, validate it directly (IPv6 hosts
+    // arrive bracket-wrapped from the URL parser; strip the brackets).
+    const literalHost = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+    const literalFamily = (0, node_net_1.isIP)(literalHost);
+    if (literalFamily !== 0) {
+        if (isBlockedIp(literalHost)) {
+            return { ok: false, reason: 'literal ip in blocked range' };
+        }
+        return { ok: true, ip: literalHost, family: literalFamily === 4 ? 4 : 6 };
+    }
+    // Reject ambiguous numeric host forms BEFORE touching the resolver. `isIP`
+    // returned 0 (not a canonical IP literal), yet the host is made entirely of
+    // numeric/hex notation characters — e.g. `127.1`, `0x7f.1`, `0177.0.0.1`,
+    // `2130706433`. The OS resolver might still canonicalize these into a
+    // loopback/internal address (musl vs. glibc differ), so we never hand them to
+    // DNS. Genuine hostnames always include a non-numeric/non-hex label.
+    if (AMBIGUOUS_NUMERIC_HOST.test(literalHost)) {
+        return { ok: false, reason: 'ambiguous numeric host' };
+    }
+    // Resolve the hostname. `all: true` returns every A/AAAA record so we can
+    // reject if ANY of them is internal.
+    let records;
+    try {
+        records = await (0, promises_1.lookup)(literalHost, { all: true });
+    }
+    catch {
+        return { ok: false, reason: 'dns resolution failed' };
+    }
+    if (records.length === 0) {
+        return { ok: false, reason: 'no dns records' };
+    }
+    for (const record of records) {
+        if (isBlockedIp(record.address)) {
+            return { ok: false, reason: 'hostname resolves to blocked range' };
+        }
+    }
+    // All records are public. Pin the connection to the first one.
+    const chosen = records[0];
+    return {
+        ok: true,
+        ip: chosen.address,
+        family: chosen.family === 4 ? 4 : 6,
+    };
+}
+/** Marker error for a blocked SSRF target (map to 403 at the route layer). */
+class SsrfRejection extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = 'SsrfRejection';
+    }
+}
+exports.SsrfRejection = SsrfRejection;
+/** Marker error for a generic upstream failure (map to 502 at the route layer). */
+class UpstreamError extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = 'UpstreamError';
+    }
+}
+exports.UpstreamError = UpstreamError;
+/**
+ * Build the request options for a single hop, pinning the TCP connection to the
+ * already-validated IP via a custom `lookup`. This closes the DNS-rebind TOCTOU
+ * window: the address we validated is exactly the address Node connects to.
+ */
+function buildRequestOptions(target, pinnedIp, pinnedFamily, method, headers, signal) {
+    return {
+        protocol: target.protocol,
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        path: `${target.pathname}${target.search}`,
+        method,
+        headers,
+        ...(signal ? { signal } : {}),
+        // Pin the connection to the validated IP — DNS is NOT re-resolved here.
+        //
+        // CRITICAL (Bun gotcha): the runtime — notably Bun's HTTP client — may
+        // invoke a custom lookup with `{ all: true }` and then sort the result
+        // internally (`results.sort(...)`). When `all` is requested we MUST return
+        // an ARRAY of `{ address, family }`; returning a single value makes that
+        // internal sort throw `results.sort is not a function`. Node (non-`all`)
+        // expects the `(err, address, family)` triple. Handle both.
+        lookup: ((_hostname, options, callback) => {
+            const wantsAll = typeof options === 'object' && options !== null && options.all === true;
+            if (wantsAll) {
+                callback(null, [{ address: pinnedIp, family: pinnedFamily }]);
+            }
+            else {
+                callback(null, pinnedIp, pinnedFamily);
+            }
+        }),
+    };
+}
+/** Perform a single upstream request (no auto-redirect). */
+function fetchOnce(options, isHttps, headersTimeoutMs) {
+    return new Promise((resolve, reject) => {
+        const transport = isHttps ? node_https_1.default : node_http_1.default;
+        const req = transport.request(options, (res) => resolve(res));
+        req.setTimeout(headersTimeoutMs, () => {
+            req.destroy(new UpstreamError('upstream headers timeout'));
+        });
+        req.on('error', (err) => reject(err));
+        req.end();
+    });
+}
+/**
+ * SSRF-safe HTTP(S) fetch. Validates the URL (and every redirect hop) against
+ * the private/metadata-range denylist, pins the connection to the validated IP,
+ * follows a bounded number of redirects (destroying redirect bodies), and
+ * returns the first non-redirect response.
+ *
+ * The caller owns the returned response stream — drain or destroy it.
+ *
+ * @throws {SsrfRejection} when any hop targets a blocked address/host/port.
+ * @throws {UpstreamError} on redirect-loop / malformed-redirect / timeout.
+ */
+async function safeFetch(rawUrl, options = {}) {
+    const { method = 'GET', headers: callerHeaders, maxRedirects = exports.MAX_REDIRECTS, headersTimeoutMs = exports.UPSTREAM_HEADERS_TIMEOUT_MS, signal, } = options;
+    // Normalize a case-insensitive header map and ensure a User-Agent default.
+    const baseHeaders = {};
+    if (callerHeaders) {
+        for (const [k, v] of Object.entries(callerHeaders)) {
+            baseHeaders[k] = v;
+        }
+    }
+    const hasUserAgent = Object.keys(baseHeaders).some((k) => k.toLowerCase() === 'user-agent');
+    if (!hasUserAgent) {
+        baseHeaders['User-Agent'] = exports.DEFAULT_USER_AGENT;
+    }
+    let currentUrl = rawUrl;
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+        if (signal?.aborted) {
+            throw new UpstreamError('request aborted');
+        }
+        const guard = await assertSafePublicUrl(currentUrl);
+        if (!guard.ok) {
+            throw new SsrfRejection(guard.reason);
+        }
+        const target = new node_url_1.URL(currentUrl);
+        const requestOptions = buildRequestOptions(target, guard.ip, guard.family, method, baseHeaders, signal);
+        const response = await fetchOnce(requestOptions, target.protocol === 'https:', headersTimeoutMs);
+        const status = response.statusCode ?? 0;
+        if (REDIRECT_STATUS_CODES.has(status)) {
+            const location = response.headers.location;
+            // We only need the Location header. Destroy immediately rather than
+            // draining the (potentially unbounded) redirect body.
+            response.destroy();
+            if (hop === maxRedirects) {
+                throw new UpstreamError('too many redirects');
+            }
+            if (!location || typeof location !== 'string') {
+                throw new UpstreamError('redirect without location');
+            }
+            // Resolve relative redirects against the current URL.
+            currentUrl = new node_url_1.URL(location, currentUrl).toString();
+            continue;
+        }
+        return {
+            response,
+            status,
+            headers: response.headers,
+            finalUrl: currentUrl,
+        };
+    }
+    // Unreachable: the loop either returns a response or throws.
+    throw new UpstreamError('redirect loop exhausted');
+}