@apifuse/provider-sdk 2.2.0-beta.14 → 2.2.0-beta.16

package/dist/provider.js

@@ -2,9 +2,9 @@ export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, define
 export { createFormCeremony } from "./ceremonies/index.js";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, parseProviderChoiceToken, } from "./choice-token.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
-export { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/http.js

@@ -1,7 +1,8 @@
 import { policyRotatesTransportVendorChain, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, } from "../config/loader.js";
-import { ProviderError, TransportError } from "../errors.js";
+import { HttpRedirectError, ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
+import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl } from "./redirects.js";
 import { normalizeHttpRequestBody, redactSensitiveError, redactSensitiveRequestError, serializeRequestUrl, } from "./request-options.js";
 const DEFAULT_HTTP_BASE_URL = "http://localhost";
 function isHttpStatusOutcome(outcome) {
@@ -196,6 +197,181 @@ function isAbsoluteUrl(url) {
 function resolveHttpUrl(baseUrl, url) {
     return new URL(url, baseUrl ?? DEFAULT_HTTP_BASE_URL).toString();
 }
+const MAX_HTTP_REDIRECT_HOPS = 20;
+const HTTP_REDIRECT_POLICY_FIELDS = new Set(["mode", "maxHops"]);
+const REDIRECT_BODY_HEADERS = new Set([
+    "content-encoding",
+    "content-language",
+    "content-location",
+    "content-type",
+]);
+const MALFORMED_REDIRECT_TARGET = "[malformed redirect target]";
+function invalidHttpRedirectPolicy(message, cause) {
+    return new TransportError(`Invalid ctx.http redirectPolicy: ${message}`, {
+        code: "http_redirect_policy_invalid",
+        ...(cause ? { cause } : {}),
+    });
+}
+/** Snapshot untrusted caller input synchronously, before proxy resolution or fetch. */
+function normalizeHttpRedirectPolicy(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidHttpRedirectPolicy("expected an object");
+    }
+    try {
+        const keys = Reflect.ownKeys(value);
+        for (const key of keys) {
+            if (typeof key !== "string" || !HTTP_REDIRECT_POLICY_FIELDS.has(key)) {
+                throw invalidHttpRedirectPolicy(`unknown field ${String(key)}`);
+            }
+        }
+        for (const field of HTTP_REDIRECT_POLICY_FIELDS) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, field);
+            if (!descriptor || !("value" in descriptor)) {
+                throw invalidHttpRedirectPolicy(`${field} must be an own data property`);
+            }
+        }
+        const record = value;
+        if (record.mode !== "same-origin") {
+            throw invalidHttpRedirectPolicy('mode must be "same-origin"');
+        }
+        if (typeof record.maxHops !== "number" ||
+            !Number.isInteger(record.maxHops) ||
+            record.maxHops < 0 ||
+            record.maxHops > MAX_HTTP_REDIRECT_HOPS) {
+            throw invalidHttpRedirectPolicy(`maxHops must be an integer from 0 to ${MAX_HTTP_REDIRECT_HOPS}`);
+        }
+        return { mode: "same-origin", maxHops: record.maxHops };
+    }
+    catch (error) {
+        if (error instanceof TransportError)
+            throw error;
+        throw invalidHttpRedirectPolicy("could not be inspected safely", error instanceof Error ? error : undefined);
+    }
+}
+function snapshotHttpRedirectPolicy(options) {
+    try {
+        return normalizeHttpRedirectPolicy(options.redirectPolicy);
+    }
+    catch (error) {
+        if (error instanceof TransportError)
+            throw error;
+        throw invalidHttpRedirectPolicy("could not be read safely", error instanceof Error ? error : undefined);
+    }
+}
+function withoutRedirectBodyHeaders(headers) {
+    const nextHeaders = new Headers(headers);
+    for (const name of REDIRECT_BODY_HEADERS)
+        nextHeaders.delete(name);
+    return nextHeaders;
+}
+function redirectDiagnosticTarget(value) {
+    try {
+        const parsed = new URL(value);
+        // Origin omits URL userinfo. Keeping only origin + path makes diagnostics
+        // useful while structurally excluding every query value and fragment,
+        // including attacker-chosen keys the provider did not declare sensitive.
+        const redactedQuery = parsed.search ? "?[REDACTED]" : "";
+        return parsed.origin === "null"
+            ? `${parsed.protocol}<opaque-target>`
+            : `${parsed.origin}${parsed.pathname}${redactedQuery}`;
+    }
+    catch {
+        return MALFORMED_REDIRECT_TARGET;
+    }
+}
+function discardRedirectResponseBody(response) {
+    try {
+        const cancellation = response.body?.cancel();
+        if (cancellation)
+            void cancellation.catch(() => undefined);
+    }
+    catch {
+        // The redirect decision is security-significant and must not be replaced
+        // or delayed by an upstream body's cancellation failure. Cancellation was
+        // attempted; redirect evaluation continues without awaiting its completion.
+    }
+}
+async function fetchWithHttpRedirectPolicy(requestUrl, requestInit, policy) {
+    if (!policy)
+        return fetch(requestUrl, requestInit);
+    const initialUrl = new URL(requestUrl);
+    if (initialUrl.protocol !== "http:" && initialUrl.protocol !== "https:") {
+        throw new TransportError("ctx.http redirectPolicy requires an HTTP(S) origin", {
+            code: "transport_invalid_url",
+        });
+    }
+    const initialOrigin = initialUrl.origin;
+    let currentUrl = requestUrl;
+    let method = normalizeHttpMethod(requestInit.method ?? "GET");
+    let body = requestInit.body;
+    let headers = requestInit.headers;
+    let followedHops = 0;
+    const visitedRequests = new Set([`${method} ${currentUrl}`]);
+    while (true) {
+        const response = await fetch(currentUrl, {
+            ...requestInit,
+            body,
+            headers,
+            method,
+            redirect: "manual",
+        });
+        if (!isRedirectStatus(response.status))
+            return response;
+        const location = response.headers.get("location");
+        discardRedirectResponseBody(response);
+        let nextUrlString;
+        try {
+            nextUrlString = resolveRedirectUrl(location || undefined, currentUrl);
+        }
+        catch {
+            const target = MALFORMED_REDIRECT_TARGET;
+            throw new HttpRedirectError(`Redirect response has malformed Location target ${target}`, {
+                reason: "missing_location",
+                target,
+                status: response.status,
+            });
+        }
+        const decision = evaluateRedirectHop({
+            status: response.status,
+            method,
+            nextUrl: nextUrlString,
+            shouldStop: nextUrlString ? new URL(nextUrlString).origin !== initialOrigin : false,
+            redirectCount: followedHops + 1,
+            maxHops: policy.maxHops,
+            visitedRequests,
+        });
+        if (decision.kind === "stop") {
+            const target = decision.nextUrl ? redirectDiagnosticTarget(decision.nextUrl) : undefined;
+            const message = (() => {
+                switch (decision.reason) {
+                    case "stopped":
+                        return `Redirect policy refused cross-origin target ${target}`;
+                    case "max_hops":
+                        return `Redirect policy reached maxHops before target ${target}`;
+                    case "loop":
+                        return `Redirect loop refused target ${target}`;
+                    case "missing_location":
+                        return `Redirect response from ${redirectDiagnosticTarget(currentUrl)} is missing Location`;
+                }
+            })();
+            throw new HttpRedirectError(message, {
+                reason: decision.reason,
+                ...(target ? { target } : {}),
+                status: response.status,
+            });
+        }
+        if (decision.nextMethod !== method) {
+            body = undefined;
+            headers = withoutRedirectBodyHeaders(headers);
+        }
+        method = decision.nextMethod;
+        currentUrl = decision.nextUrl;
+        followedHops += 1;
+        visitedRequests.add(`${method} ${currentUrl}`);
+    }
+}
 async function resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset = 0) {
     const resolvedProxy = await resolveProxyConfigAsync({
         proxy: options.proxy ?? clientOptions.proxy,
@@ -271,9 +447,7 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
         if (options.body !== undefined) {
             requestInit.body = normalizeNativeFetchBody(options.body);
         }
-        const response = await fetch(requestUrl, {
-            ...requestInit,
-        });
+        const response = await fetchWithHttpRedirectPolicy(requestUrl, requestInit, options.redirectPolicy);
         const headers = Object.fromEntries(response.headers.entries());
         if (statusRetryCodes && response.status >= 400) {
             await drainNativeResponseBody(response);
@@ -325,9 +499,7 @@ async function fetchNativeHttpStream(baseUrl, url, method, options, clientOption
         if (options.body !== undefined) {
             requestInit.body = normalizeNativeFetchBody(options.body);
         }
-        const response = await fetch(requestUrl, {
-            ...requestInit,
-        });
+        const response = await fetchWithHttpRedirectPolicy(requestUrl, requestInit, options.redirectPolicy);
         if (response.status >= 400 && options.throwOnHttpError !== false) {
             await drainNativeResponseBody(response);
             throw new TransportError(`Upstream request failed with status ${response.status}`, {
@@ -365,7 +537,11 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                     throw new TransportError("ctx.http requires an absolute URL when provider.upstream.baseUrl is not declared", { code: "transport_invalid_url" });
                 }
                 assertNoHttpTransportOverrides(options);
-                const headersOptions = withClientHeaders(options, clientOptions, options.body);
+                const redirectPolicy = snapshotHttpRedirectPolicy(options);
+                const headersOptions = {
+                    ...withClientHeaders(options, clientOptions, options.body),
+                    redirectPolicy,
+                };
                 const methodName = normalizeHttpMethod(method);
                 const explicitRetry = headersOptions.retry !== undefined;
                 const retryOptions = normalizeProxyTransportRetryOptions(headersOptions.retry, {
@@ -543,8 +719,12 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                     throw new TransportError("ctx.http requires an absolute URL when provider.upstream.baseUrl is not declared", { code: "transport_invalid_url" });
                 }
                 assertNoHttpTransportOverrides(options);
+                const redirectPolicy = snapshotHttpRedirectPolicy(options);
                 return {
-                    headersOptions: withClientHeaders(options, clientOptions, options.body),
+                    headersOptions: {
+                        ...withClientHeaders(options, clientOptions, options.body),
+                        redirectPolicy,
+                    },
                     methodName: normalizeHttpMethod(method),
                 };
             }

package/dist/runtime/native-network.d.ts

@@ -1,8 +1,8 @@
 import { Socket } from "node:net";
 import { type TLSSocket } from "node:tls";
 import { TransportError } from "../errors.js";
-import type { NativeNetworkClient, NativeNetworkConnection, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider } from "../types.js";
-export type NativeNetworkErrorCode = "native_connection_aborted" | "native_connection_closed" | "native_connection_failed" | "native_connection_idle_timeout" | "native_connection_timeout" | "native_dynamic_egress_unsupported" | "native_proxy_expired" | "native_proxy_invalid";
+import type { NativeNetworkClient, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider } from "../types.js";
+export type NativeNetworkErrorCode = "native_connection_aborted" | "native_connection_closed" | "native_connection_failed" | "native_connection_idle_timeout" | "native_connection_timeout" | "native_egress_authorization_failed" | "native_egress_grant_expired" | "native_egress_grant_invalid" | "native_egress_grant_limit_exceeded" | "native_egress_input_invalid" | "native_egress_not_declared" | "native_egress_policy_invalid" | "native_dynamic_egress_unsupported" | "native_proxy_expired" | "native_proxy_invalid";
 export declare class NativeNetworkError extends TransportError {
     constructor(message: string, code: NativeNetworkErrorCode);
     get code(): NativeNetworkErrorCode;
@@ -11,6 +11,24 @@ export declare class NativeProxyExpiredError extends NativeNetworkError {
     readonly expiresAt: string;
     constructor(expiresAt: string);
 }
+/** Raised before transport setup when a native destination is not authorized. */
+export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
+    readonly host: string;
+    readonly port: number;
+    readonly tls: "required" | "disabled";
+    constructor(host: string, port: number, tls: "required" | "disabled");
+}
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export declare class NativeEgressGrantExpiredError extends NativeNetworkError {
+    readonly host: string;
+    readonly port: number;
+    readonly tls: "required" | "disabled";
+    readonly expiresAt: string;
+    constructor(host: string, port: number, tls: "required" | "disabled", expiresAt: string);
+}
 /** Raised when an established connection exceeds its opt-in read-idle window. */
 export declare class NativeIdleTimeoutError extends NativeNetworkError {
     constructor();
@@ -41,7 +59,12 @@ export type NativeNetworkClientOptions = {
     readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
     /** Warning-level lifecycle diagnostic sink. */
     readonly warn?: (message: string) => void;
-    /** Delegate to the deployment's native egress authorization layer. */
+    /**
+     * Provider-declared native egress. Undefined preserves legacy unrestricted
+     * behavior; any provided declaration, including an empty object, is enforced.
+     */
+    readonly egress?: NonNullable<NativeProviderConfig["network"]>;
+    /** Additional deployment authorization layered on top of SDK enforcement. */
     readonly grantTcpEgress?: (input: NativeNetworkDynamicGrantOptions) => NativeNetworkEgressGrant;
 };
 /** Domain-separated, process-independent affinity derived from credential identity. */
@@ -49,5 +72,17 @@ export declare function deriveNativeCredentialAffinityKey(credentialIdentity: st
 /** Resolve the first configured native gateway without invoking an allocator API. */
 export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResolutionInput): NativeGatewayProxy | undefined;
 export declare function createNativeNetworkConnection(socket: Socket | TLSSocket, proxy: NativeGatewayProxy | undefined, options: NativeNetworkClientOptions, idleTimeoutMs?: number): NativeNetworkConnection;
-/** Create the SDK byte-stream runtime; deployment egress authorization stays delegated. */
+type NativeConnectTls = "required" | "disabled";
+export declare const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;
+/** Internal canonical snapshot shared by production and SDK transport test doubles. */
+export declare function snapshotNativeConnectInput(input: NativeNetworkConnectInput): NativeNetworkConnectInput;
+/** Internal canonical snapshot shared by production and SDK transport test doubles. */
+export declare function snapshotNativeGrantInput(input: NativeNetworkDynamicGrantOptions): NativeNetworkDynamicGrantOptions;
+/** Internal authorization seam shared by production and SDK transport test doubles. */
+export declare function createNativeEgressAuthorization(options: NativeNetworkClientOptions): {
+    assertConnect(input: NativeNetworkConnectInput, tls: NativeConnectTls): void;
+    grant(input: NativeNetworkDynamicGrantOptions): NativeNetworkEgressGrant;
+};
+/** Create the SDK byte-stream runtime with provider-declared egress enforcement. */
 export declare function createNativeNetworkClient(options?: NativeNetworkClientOptions): NativeNetworkClient;
+export {};