@oxy.so/core 1.0.0

package/dist/types/models/session.d.ts

@@ -0,0 +1,51 @@
+import type { UserNameResponse } from '@oxy.so/contracts';
+export interface ClientSession {
+    sessionId: string;
+    deviceId: string;
+    expiresAt: string;
+    lastActive: string;
+    userId?: string;
+    isCurrent?: boolean;
+    /**
+     * The account's ordinal slot (0..N) within the device's account set
+     * (`SessionAccount.authuser` in `@oxy.so/contracts`), projected from the
+     * device-first `DeviceSessionState` — used purely for stable Google-style
+     * account-chooser ordering, not for any token-refresh mechanism.
+     */
+    authuser?: number;
+    /**
+     * The HUMAN operating this account, when it is a delegated session — the
+     * audit actor behind "The Oxy Collective". Absent when the session belongs to
+     * the account itself.
+     *
+     * The flat wire shape has carried it since the multi-account model shipped and
+     * nothing read it, so an operated org rendered exactly like a directly
+     * signed-in one. `SessionClient.getActiveContext()` is the richer answer
+     * (ADR 0002); this is the same fact on the compatibility lane.
+     */
+    operatedByUserId?: string;
+}
+export interface StorageKeys {
+    sessions: string;
+    activeSessionId: string;
+}
+export interface MinimalUserData {
+    id: string;
+    username: string;
+    name: UserNameResponse;
+    avatar?: string;
+}
+export interface SessionLoginResponse {
+    sessionId: string;
+    deviceId: string;
+    expiresAt: string;
+    user: MinimalUserData;
+    /** JWT access token for API authentication */
+    accessToken?: string;
+    /**
+     * Rotating zero-cookie device credential minted on sign-in / claim. Persisted
+     * first-party alongside `deviceId` so cold boot can re-mint via
+     * `POST /session/device/token`.
+     */
+    deviceSecret?: string;
+}

package/dist/types/server/auth.d.ts

@@ -0,0 +1,130 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import type { OxyServices } from '../OxyServices';
+import { OXY_SERVICE_ENVIRONMENTS, type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+export { OXY_SERVICE_ENVIRONMENTS };
+export type { OxyServiceEnvironment };
+export interface OxyRequestUser {
+    id: string;
+    _id?: string;
+    username?: string;
+    email?: string;
+    avatar?: string;
+    [key: string]: unknown;
+}
+export interface OxyServiceAppContext {
+    appId: string;
+    appName: string;
+    scopes: string[];
+    credentialId: string;
+    /**
+     * The Oxy account that owns `appId` and is financially responsible for it.
+     * Read off the VERIFIED service-token claim set — never a user id, and never
+     * the delegated `X-Oxy-User-Id` (ADR 0007).
+     */
+    ownerAccountId: string;
+    environment: OxyServiceEnvironment;
+}
+export interface OxyServiceActingAsContext {
+    userId: string;
+    scopes: string[];
+}
+export interface OxyAuthRequest extends Request {
+    userId?: string | null;
+    user?: OxyRequestUser | null;
+    accessToken?: string;
+    sessionId?: string | null;
+    serviceApp?: OxyServiceAppContext;
+    serviceActingAs?: OxyServiceActingAsContext;
+}
+export interface OxyAuthenticatedRequest extends OxyAuthRequest {
+    userId: string;
+    user: OxyRequestUser;
+}
+export interface OxyAuthMiddlewareOptions {
+    /**
+     * Options forwarded to `oxy.auth()`.
+     * `optional` is forced to `true` by the composed helpers so route guards can
+     * produce one consistent 401 shape.
+     */
+    auth?: Parameters<OxyServices['auth']>[0];
+}
+export declare function getOxyUserId(req: Request): string | null;
+export declare function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest;
+/**
+ * The principal a request is CHARGED to, and the identifiers a receipt needs.
+ *
+ * Every field is read from the verified service-token claim set. It is an
+ * OBJECT, not a string, and that is the point: `getOxyUserId` returns a
+ * `string | null`, so a delegated end-user id cannot be passed anywhere an
+ * `OxyBillingPrincipal` is expected. The confusion ADR 0007 forbids —
+ * attributing spend to the person a service is acting for rather than to the
+ * service's own account — stops being a code-review question and becomes a
+ * compile error.
+ *
+ * `scopes` are the effective scopes minted into the token (credential ∩
+ * application). Nothing re-intersects them here.
+ */
+export interface OxyBillingPrincipal {
+    /** `applications.owner_account_id` — the financially responsible account. */
+    readonly accountId: string;
+    readonly applicationId: string;
+    readonly credentialId: string;
+    readonly environment: OxyServiceEnvironment;
+    readonly scopes: readonly string[];
+}
+/**
+ * The full canonical attribution of ADR 0007 for a request: the billing
+ * principal PLUS the optional delegated end user.
+ *
+ * `delegatedUserId` is named for what it is. It answers "on whose behalf" and
+ * is absent for a machine credential acting for itself — its absence is normal,
+ * and nothing may synthesize one. If removing it would change what any account
+ * is charged, the code reading it is wrong.
+ */
+export interface OxyRequestAttribution extends OxyBillingPrincipal {
+    readonly delegatedUserId: string | null;
+}
+/**
+ * The billing principal of a request, or `null` when the request carries no
+ * verified service principal (an ordinary user session is not a billable
+ * machine principal — its account is resolved from the account graph, not from
+ * a token claim).
+ *
+ * Reads `req.serviceApp` and NOTHING else: not `req.userId`, not `req.user`,
+ * not `req.serviceActingAs`. That exclusivity is the invariant this function
+ * exists to hold, and `serviceTokenAttribution.test.ts` mutation-tests it.
+ *
+ * **It answers for the SERVICE-TOKEN lane only.** The API's machine-credential
+ * lane (`oxy_sk_*`, issue #972 §2.3) resolves the same five facts into its own
+ * `req.machineCredential`, deliberately never `req.serviceApp` — populating the
+ * latter would hand a self-serve third-party credential the lane that only
+ * platform-trusted applications may enter. So a machine-credential request has
+ * no billing principal HERE and resolves `null`, which fails closed: the caller
+ * must handle it, and `getRequiredOxyBillingPrincipal` throws rather than
+ * charging anyone. One accessor answering for both lanes belongs to the public
+ * inference edge that has to admit both, and it needs the machine principal's
+ * shape to move into this package first.
+ */
+export declare function getOxyBillingPrincipal(req: Request): OxyBillingPrincipal | null;
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+export declare function getRequiredOxyBillingPrincipal(req: Request): OxyBillingPrincipal;
+/**
+ * The delegated end user of a service request, or `null`.
+ *
+ * Deliberately reads `req.serviceActingAs` — the grant-verified delegation —
+ * and not `req.userId`, which on a non-service request is the caller's own
+ * session identity and is not a delegation at all.
+ */
+export declare function getOxyDelegatedUserId(req: Request): string | null;
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+export declare function getOxyRequestAttribution(req: Request): OxyRequestAttribution | null;
+export declare function getRequiredOxyUserId(req: Request): string;
+export declare function requireOxyAuth(req: Request, res: Response, next: NextFunction): void;
+export declare function createOptionalOxyAuth(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;
+export declare function createOxyAuthMiddleware(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;

package/dist/types/server/capabilityTicket.d.ts

@@ -0,0 +1,41 @@
+import { type KeyObject } from 'node:crypto';
+import { type CapabilityTicketClaims, type GrantLimit, type PolicyDecision } from '@oxy.so/contracts';
+import type { Request, RequestHandler } from 'express';
+type UnsignedCapabilityTicketClaims = Omit<CapabilityTicketClaims, 'iss' | 'iat' | 'exp' | 'jti'>;
+export interface CapabilityTicketSigningOptions {
+    privateKey: KeyObject;
+    keyId: string;
+    issuer: string;
+    ttlSeconds?: number;
+    now?: Date;
+    jti?: string;
+}
+export interface CapabilityTicketVerificationOptions {
+    resolvePublicKey: (keyId: string) => KeyObject | undefined;
+    audience: string;
+    issuer?: string;
+    now?: Date;
+    maximumTtlSeconds?: number;
+}
+export interface CapabilityTicketRequest extends Request {
+    capabilityTicket?: CapabilityTicketClaims;
+}
+export interface CapabilityTicketMiddlewareOptions extends CapabilityTicketVerificationOptions {
+    authorize: (claims: CapabilityTicketClaims) => Promise<PolicyDecision>;
+}
+export declare class CapabilityTicketError extends Error {
+    readonly code: 'malformed' | 'invalid_signature' | 'unknown_key' | 'invalid_claims' | 'expired' | 'not_yet_valid' | 'wrong_audience' | 'wrong_issuer' | 'ttl_exceeded';
+    constructor(code: 'malformed' | 'invalid_signature' | 'unknown_key' | 'invalid_claims' | 'expired' | 'not_yet_valid' | 'wrong_audience' | 'wrong_issuer' | 'ttl_exceeded', message: string);
+}
+/** Enforces the signed per-action bounds before a domain handler runs. */
+export declare function inputSatisfiesCapabilityLimits(tool: string, input: Record<string, unknown>, limits: readonly GrantLimit[]): boolean;
+export declare function issueCapabilityTicket(claims: UnsignedCapabilityTicketClaims, options: CapabilityTicketSigningOptions): string;
+export declare function verifyCapabilityTicket(token: string, options: CapabilityTicketVerificationOptions): CapabilityTicketClaims;
+export declare function readCapabilityAuthorization(authorization: string | undefined): string | null;
+/**
+ * Verifies cryptographic scope first, then asks the authority service for a
+ * live decision. This second check is what makes revocation effective between
+ * planning and execution.
+ */
+export declare function createCapabilityTicketMiddleware(options: CapabilityTicketMiddlewareOptions): RequestHandler;
+export {};

package/dist/types/server/cors.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 over HTTPS only: the apex plus
+ *     one-label subdomains such as `auth.oxy.so`, `api.oxy.so`,
+ *     `accounts.oxy.so`, `console.oxy.so`, and `inbox.oxy.so`,
+ *   - allows the caller's explicit `appOrigins`,
+ *   - REFUSES the opaque origin on both sides (see `OPAQUE_ORIGIN`),
+ *   - 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 `@oxy.so/core/server`.
+ */
+import type { RequestHandler } from 'express';
+export interface OxyCorsOptions {
+    /**
+     * Explicit additional allowed origins (exact-origin match, e.g.
+     * `https://app.example.com`, `http://localhost:3000`). These are allowed IN
+     * ADDITION TO the built-in HTTPS Oxy apex origin family. Each is normalized
+     * via `new URL().origin`.
+     *
+     * An entry that is not a URL, or whose origin is the opaque origin
+     * (`exp://…`, `capacitor://…`, `chrome-extension://…`, `file:`, `data:`), is
+     * DROPPED with an error log rather than admitted — see `OPAQUE_ORIGIN` for
+     * why one such entry would otherwise admit every other one.
+     */
+    appOrigins?: string[];
+    /**
+     * Whether to emit `Access-Control-Allow-Credentials: true`. Default `true`
+     * (the Oxy ecosystem uses cookie/bearer credentials). Even when `true`, the
+     * helper NEVER emits a wildcard origin — only an exact matched origin.
+     */
+    allowCredentials?: boolean;
+    /** HTTP methods to allow. Defaults to the full standard set. */
+    methods?: string[];
+    /** Request headers to allow. Defaults to the common Oxy set. */
+    allowedHeaders?: string[];
+    /** Response headers to expose to the browser. Defaults to none. */
+    exposedHeaders?: string[];
+    /** Preflight cache lifetime in seconds. Default 86400 (24h). */
+    maxAgeSeconds?: number;
+}
+/**
+ * Normalize the configured `appOrigins` into the exact-match set — the
+ * CONFIGURE-SIDE half of the opaque-origin guard.
+ *
+ * An entry that is not a URL, or whose origin is opaque, is dropped and named
+ * in an error log. Dropped rather than thrown on because `appOrigins` is
+ * deployment configuration — at least one Oxy backend reads it from the
+ * environment — and a typo there must cost that one origin its CORS headers,
+ * never the whole service its boot. Both failure modes are equally SAFE (the
+ * entry is absent from the set either way), so the choice is purely about
+ * blast radius, and dropping keeps it to one origin whose requests then fail
+ * visibly in the browser.
+ *
+ * Exported for `__tests__/cors.socket.test.ts` and NOT re-exported from
+ * `server/index.ts`, so it is not part of the package's public surface. The
+ * two halves of the guard are separately exported because they are separately
+ * testable only that way: with this half in place the match-side half is
+ * unreachable through `createOxyCors`, so a test driving the public API alone
+ * would measure this function twice and the other one never.
+ */
+export declare function normalizeAppOrigins(appOrigins: string[]): Set<string>;
+/**
+ * Whether `origin` may be echoed back: it is in the built-in HTTPS Oxy apex
+ * family, or it exactly matches one of the configured app origins.
+ *
+ * The opaque-origin refusal here is the MATCH-SIDE half of the guard, and it
+ * is what makes the property hold regardless of how `explicit` was built — a
+ * set that somehow contains `"null"` still matches nothing, because no
+ * incoming origin ever normalizes past this line. `normalizeAppOrigins` is
+ * what stops such a set existing today; this is what stops it mattering.
+ *
+ * Exported for the same reason as `normalizeAppOrigins`, and likewise absent
+ * from `server/index.ts`.
+ */
+export declare function matchesAllowedOrigin(explicit: ReadonlySet<string>, origin: string): boolean;
+/**
+ * Create a strict Oxy CORS middleware. See module docs.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxyCors({ appOrigins: ['https://app.example.com'] }));
+ * ```
+ */
+export declare function createOxyCors(options?: OxyCorsOptions): RequestHandler;

package/dist/types/server/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @oxy.so/core/server — Server-only utilities for Oxy backends
+ *
+ * This subpath export provides Express middleware and Node.js-specific
+ * utilities that are not available in React Native or browser environments.
+ *
+ * @example
+ * ```ts
+ * import { createOxyRateLimit } from '@oxy.so/core/server';
+ * import { oxyClient } from '@oxy.so/core';
+ *
+ * const oxy = oxyClient({ apiUrl: 'https://api.oxy.so' });
+ *
+ * app.use(createOxyRateLimit(oxy, { store: redisStore }));
+ * ```
+ */
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
+export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyBillingPrincipal, OxyRequestAttribution, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
+export { createOxyRateLimit } from './rateLimit';
+export type { OxyRateLimitOptions } from './rateLimit';
+export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch';
+export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, SsrfCheckResult, } from './safeFetch';
+export { createOxyCors } from './cors';
+export type { OxyCorsOptions } from './cors';
+export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, cspSourcesFor, extractInlineScripts, formatOxyCspPolicy, inlineScriptCspHash, OXY_CSP_BASELINE, } from './securityHeaders';
+export type { OxyCspDirective, OxyCspExtensions, OxyPagesHeadersOptions, OxySecurityHeadersOptions, } from './securityHeaders';
+export { CapabilityTicketError, createCapabilityTicketMiddleware, inputSatisfiesCapabilityLimits, issueCapabilityTicket, readCapabilityAuthorization, verifyCapabilityTicket, } from './capabilityTicket';
+export type { CapabilityTicketMiddlewareOptions, CapabilityTicketRequest, CapabilityTicketSigningOptions, CapabilityTicketVerificationOptions, } from './capabilityTicket';
+export { verifySecret } from './verifySecret';
+export { createOxyUserInvalidationHandler, publishOxyUserInvalidation, } from './userInvalidation';
+export type { OxyInvalidationPublisher, OxyUserInvalidationHandlerOptions, } from './userInvalidation';
+export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES } from '../utils/identityCacheSweep';
+export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
+export { registrableApex } from '../utils/registrableApex';
+export { isOfficialWebOrigin } from '../utils/officialOrigins';

package/dist/types/server/rateLimit.d.ts

@@ -0,0 +1,40 @@
+import type { Request, RequestHandler } from 'express';
+import { type Store } from 'express-rate-limit';
+import type { OxyServices } from '../OxyServices';
+export interface OxyRateLimitOptions {
+    /**
+     * Max requests per window for AUTHENTICATED users (keyed per user).
+     * Default 5000 — ~5.5 req/s sustained, comfortable for a media client that
+     * fans out into many small requests per screen.
+     */
+    authenticatedMax?: number;
+    /**
+     * Max requests per window for ANONYMOUS callers (keyed per IP).
+     * Default 600 — enough to browse public pages while bounding abuse.
+     */
+    anonymousMax?: number;
+    /** Rate-limit window in milliseconds. Default 15 minutes. */
+    windowMs?: number;
+    /**
+     * Optional `express-rate-limit` store (e.g. a Redis store) for distributed
+     * limiting across instances. Defaults to the library's in-memory store.
+     */
+    store?: Store;
+    /**
+     * Extra path predicates to exempt from limiting, in addition to the built-in
+     * exemptions (uploads, image proxy, streaming sub-requests, health probes,
+     * CORS preflight). Return `true` to skip limiting for the request.
+     */
+    exempt?: (req: Request) => boolean;
+    /** Response message body sent with a 429. */
+    message?: string;
+    /**
+     * Options forwarded to the internal `oxy.auth({ optional: true })` resolver
+     * (e.g. `{ jwtSecret }` to verify service tokens). `optional` is forced true.
+     */
+    auth?: Parameters<OxyServices['auth']>[0];
+}
+/**
+ * Build the composed Oxy rate-limit middleware. See module docs for rationale.
+ */
+export declare function createOxyRateLimit(oxy: OxyServices, options?: OxyRateLimitOptions): RequestHandler;

package/dist/types/server/safeFetch.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 `@oxy.so/core/server`. It MUST NOT be reachable from the
+ * browser `@oxy.so/core` entry.
+ */
+import { type IncomingMessage, type IncomingHttpHeaders } from 'node:http';
+/** Maximum accepted length of an input URL (DoS guard). */
+export declare const MAX_URL_LENGTH = 2048;
+/** The only network ports a safe fetch is allowed to reach upstream. */
+export declare const ALLOWED_PORTS: ReadonlySet<number>;
+/** Protocols a safe fetch is allowed to contact. */
+export declare const ALLOWED_PROTOCOLS: ReadonlySet<string>;
+/**
+ * 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.
+ */
+export declare const UPSTREAM_HEADERS_TIMEOUT_MS = 8000;
+/** Maximum number of HTTP redirects to follow; each hop is re-validated. */
+export declare const MAX_REDIRECTS = 5;
+/** Default User-Agent presented to upstreams when the caller does not set one. */
+export declare const DEFAULT_USER_AGENT = "OxyServices/1.0 (+https://oxy.so)";
+/** Hostnames that must never be resolved or contacted, regardless of DNS. */
+export declare const BLOCKED_HOSTNAMES: ReadonlySet<string>;
+export interface SsrfCheckOk {
+    ok: true;
+    /** The validated literal IP the caller MUST connect to. */
+    ip: string;
+    /** IP family of the validated address (4 or 6). */
+    family: 4 | 6;
+}
+export interface SsrfCheckFail {
+    ok: false;
+    /** Human-readable, non-sensitive reason (safe to log; not echoed to clients). */
+    reason: string;
+}
+export type SsrfCheckResult = SsrfCheckOk | SsrfCheckFail;
+/**
+ * Return true if a literal IP address is private/loopback/link-local/reserved/
+ * multicast/metadata and therefore must NOT be contacted.
+ */
+export declare function isBlockedIp(rawIp: string): boolean;
+/**
+ * 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.
+ */
+export declare function assertSafePublicUrl(rawUrl: string): Promise<SsrfCheckResult>;
+/** Marker error for a blocked SSRF target (map to 403 at the route layer). */
+export declare class SsrfRejection extends Error {
+    constructor(reason: string);
+}
+/** Marker error for a generic upstream failure (map to 502 at the route layer). */
+export declare class UpstreamError extends Error {
+    constructor(reason: string);
+}
+/** Options for {@link safeFetch}. */
+export interface SafeFetchOptions {
+    /** HTTP method. Defaults to `GET`. */
+    method?: string;
+    /** Extra request headers. A `User-Agent` is added if none is provided. */
+    headers?: Record<string, string>;
+    /** Request body for POST/PUT/PATCH. */
+    body?: string | Buffer;
+    /**
+     * Maximum number of redirects to follow (each re-validated). Defaults to
+     * {@link MAX_REDIRECTS}. Set to `0` to disallow redirects.
+     */
+    maxRedirects?: number;
+    /**
+     * Time-to-first-byte deadline in milliseconds (connect + response headers).
+     * Defaults to {@link UPSTREAM_HEADERS_TIMEOUT_MS}.
+     */
+    headersTimeoutMs?: number;
+    /**
+     * Optional external abort signal. When it fires the in-flight request is
+     * destroyed.
+     */
+    signal?: AbortSignal;
+}
+/** The validated, non-redirect response returned by {@link safeFetch}. */
+export interface SafeFetchResult {
+    /**
+     * The first non-redirect response. The caller OWNS draining/destroying this
+     * stream (stream it to the client, or buffer a bounded prefix, then destroy).
+     */
+    response: IncomingMessage;
+    /** The HTTP status code of the response. */
+    status: number;
+    /** Response headers. */
+    headers: IncomingHttpHeaders;
+    /** The final, post-redirect URL that produced the response. */
+    finalUrl: string;
+}
+/**
+ * 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.
+ */
+export declare function safeFetch(rawUrl: string, options?: SafeFetchOptions): Promise<SafeFetchResult>;