@apifuse/provider-sdk 2.2.0-beta.13 → 2.2.0-beta.15

package/dist/runtime/native-network.js

@@ -4,10 +4,16 @@ import { connect as connectTlsSocket } from "node:tls";
 import { SocksClient } from "socks";
 import { ProxyResolutionError } from "../config/loader.js";
 import { TransportError } from "../errors.js";
+import { NativeEgressPolicyValidationError, parseNativeEgressPolicy, } from "../native-egress-policy.js";
 import { hasNodemavenCredentials, nodemavenSessionWindow, synthesizeNodemavenProxy, } from "./proxy-nodemaven.js";
 export class NativeNetworkError extends TransportError {
     constructor(message, code) {
-        super(message, { code, status: 0 });
+        const isEgressPolicyFailure = code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
+        super(message, {
+            code,
+            status: 0,
+            ...(isEgressPolicyFailure ? { category: "provider_error", retryable: false } : {}),
+        });
         this.name = "NativeNetworkError";
     }
     get code() {
@@ -22,6 +28,37 @@ export class NativeProxyExpiredError extends NativeNetworkError {
         this.name = "NativeProxyExpiredError";
     }
 }
+/** Raised before transport setup when a native destination is not authorized. */
+export class NativeEgressNotDeclaredError extends NativeNetworkError {
+    host;
+    port;
+    tls;
+    constructor(host, port, tls) {
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${host}:${port}`, "native_egress_not_declared");
+        this.host = host;
+        this.port = port;
+        this.tls = tls;
+        this.name = "NativeEgressNotDeclaredError";
+    }
+}
+/**
+ * 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 class NativeEgressGrantExpiredError extends NativeNetworkError {
+    host;
+    port;
+    tls;
+    expiresAt;
+    constructor(host, port, tls, expiresAt) {
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${host}:${port}`, "native_egress_grant_expired");
+        this.host = host;
+        this.port = port;
+        this.tls = tls;
+        this.expiresAt = expiresAt;
+        this.name = "NativeEgressGrantExpiredError";
+    }
+}
 /** Raised when an established connection exceeds its opt-in read-idle window. */
 export class NativeIdleTimeoutError extends NativeNetworkError {
     constructor() {
@@ -227,7 +264,7 @@ async function waitForSocksHandshake(proxySocket, promise, signal, deadline) {
             : failedError()));
     });
 }
-async function connectSocksTunnel(proxy, input, deadline) {
+async function connectSocksTunnel(proxy, input, deadline, beforeDestinationConnect) {
     const parsed = parseSocks5Proxy(proxy.url);
     const proxySocket = await connectPlainSocket(parsed.host, parsed.port, input.signal, deadline);
     // `socks` removes its internal listeners as the handshake settles. Keep a
@@ -235,6 +272,13 @@ async function connectSocksTunnel(proxy, input, deadline) {
     // an unhandled late network error between library cleanup and our wrapper.
     proxySocket.on("error", () => undefined);
     const remaining = remainingMs(deadline);
+    try {
+        beforeDestinationConnect();
+    }
+    catch (error) {
+        proxySocket.destroy();
+        throw error;
+    }
     const handshake = SocksClient.createConnection({
         command: "connect",
         destination: { host: input.host, port: input.port },
@@ -448,30 +492,331 @@ async function resolveConnectionProxy(options, input) {
         throw proxyRequiredError(policy);
     return resolved;
 }
-/** Create the SDK byte-stream runtime; deployment egress authorization stays delegated. */
+export const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;
+function normalizeEgressHost(host) {
+    return host.trim().toLowerCase().replace(/\.$/, "");
+}
+function invalidPolicy(message) {
+    return new NativeNetworkError(message, "native_egress_policy_invalid");
+}
+function matchesDnsSuffix(host, suffix) {
+    return host === suffix || host.endsWith(`.${suffix}`);
+}
+function matchesSourceHost(rule, host) {
+    const hasSelector = rule.sourceHost !== undefined || rule.sourceHostSuffixes.length > 0;
+    if (!hasSelector)
+        return false;
+    return (host === rule.sourceHost ||
+        rule.sourceHostSuffixes.some((suffix) => matchesDnsSuffix(host, suffix)));
+}
+function matchesPortSelectors(port, ports, ranges) {
+    if (ports.length === 0 && ranges.length === 0)
+        return false;
+    return ports.includes(port) || ranges.some(({ start, end }) => port >= start && port <= end);
+}
+function tlsModeAllows(mode, requested) {
+    return mode === "allowed" || mode === requested;
+}
+function grantTlsFitsRule(grant, rule) {
+    return (rule === "allowed" ||
+        (grant === "required" && rule === "required") ||
+        (grant === "disabled" && rule === "disabled"));
+}
+function matchesDynamicRuleSelectors(rule, input) {
+    const sourceHost = normalizeEgressHost(input.sourceHost);
+    const targetHost = normalizeEgressHost(input.host);
+    return (matchesSourceHost(rule, sourceHost) &&
+        matchesPortSelectors(input.sourcePort, rule.sourcePorts, rule.sourcePortRanges) &&
+        rule.targetHostSuffixes.some((suffix) => matchesDnsSuffix(targetHost, suffix)) &&
+        matchesPortSelectors(input.port, rule.targetPorts, rule.targetPortRanges) &&
+        grantTlsFitsRule(input.tls, rule.tls));
+}
+function invalidGrant(message) {
+    return new NativeNetworkError(message, "native_egress_grant_invalid");
+}
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return false;
+}
+function assertValidGrantInput(input) {
+    if (!normalizeEgressHost(input.sourceHost) ||
+        !normalizeEgressHost(input.host) ||
+        hasControlCharacter(input.sourceHost) ||
+        hasControlCharacter(input.host) ||
+        /\s/.test(input.sourceHost) ||
+        /\s/.test(input.host) ||
+        input.sourceHost.includes("://") ||
+        input.host.includes("://") ||
+        input.sourceHost.includes("*") ||
+        input.host.includes("*"))
+        throw invalidGrant("Native TCP egress grant hosts must be exact non-empty hostnames");
+    if (!Number.isSafeInteger(input.sourcePort) ||
+        input.sourcePort < 1 ||
+        input.sourcePort > 65_535 ||
+        !Number.isSafeInteger(input.port) ||
+        input.port < 1 ||
+        input.port > 65_535)
+        throw invalidGrant("Native TCP egress grant ports must be integers from 1 to 65535");
+    if (input.tls !== "required" && input.tls !== "allowed" && input.tls !== "disabled")
+        throw invalidGrant("Native TCP egress grant tls must be required, allowed, or disabled");
+    if (input.ttlMs !== undefined && (!Number.isSafeInteger(input.ttlMs) || input.ttlMs <= 0))
+        throw invalidGrant("Native TCP egress grant ttlMs must be a positive integer");
+}
+/** Internal canonical snapshot shared by production and SDK transport test doubles. */
+export function snapshotNativeConnectInput(input) {
+    try {
+        const host = input.host;
+        const port = input.port;
+        const serverName = input.serverName;
+        const rejectUnauthorized = input.rejectUnauthorized;
+        const idleTimeoutMs = input.idleTimeoutMs;
+        const timeoutMs = input.timeoutMs;
+        const signal = input.signal;
+        const affinityKey = input.affinityKey;
+        const snapshot = {
+            host,
+            port,
+            ...(serverName === undefined ? {} : { serverName }),
+            ...(rejectUnauthorized === undefined ? {} : { rejectUnauthorized }),
+            ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            ...(signal === undefined ? {} : { signal }),
+            ...(affinityKey === undefined ? {} : { affinityKey }),
+        };
+        if (typeof snapshot.host !== "string" ||
+            !snapshot.host.trim() ||
+            hasControlCharacter(snapshot.host) ||
+            !Number.isInteger(snapshot.port) ||
+            snapshot.port < 1 ||
+            snapshot.port > 65_535)
+            throw new TypeError("invalid native connection target");
+        return snapshot;
+    }
+    catch {
+        throw new NativeNetworkError("Native connection input could not be inspected safely", "native_egress_input_invalid");
+    }
+}
+/** Internal canonical snapshot shared by production and SDK transport test doubles. */
+export function snapshotNativeGrantInput(input) {
+    try {
+        const sourceHost = input.sourceHost;
+        const sourcePort = input.sourcePort;
+        const host = input.host;
+        const port = input.port;
+        const tls = input.tls;
+        const ttlMs = input.ttlMs;
+        return {
+            sourceHost,
+            sourcePort,
+            host,
+            port,
+            tls,
+            ...(ttlMs === undefined ? {} : { ttlMs }),
+        };
+    }
+    catch {
+        throw new NativeNetworkError("Native TCP egress grant input could not be inspected safely", "native_egress_input_invalid");
+    }
+}
+/** Internal authorization seam shared by production and SDK transport test doubles. */
+export function createNativeEgressAuthorization(options) {
+    let declared;
+    let staticRules;
+    let dynamicRules;
+    let delegate;
+    try {
+        const policy = options.egress;
+        delegate = options.grantTcpEgress;
+        if (delegate !== undefined && typeof delegate !== "function")
+            throw invalidPolicy("Native egress delegate must be a function");
+        declared = policy !== undefined;
+        const snapshot = declared
+            ? parseNativeEgressPolicy(policy)
+            : { staticRules: [], dynamicRules: [] };
+        staticRules = snapshot.staticRules;
+        dynamicRules = snapshot.dynamicRules;
+    }
+    catch (error) {
+        if (error instanceof NativeNetworkError)
+            throw error;
+        if (error instanceof NativeEgressPolicyValidationError)
+            throw invalidPolicy(error.message);
+        throw invalidPolicy("Native egress policy could not be inspected safely");
+    }
+    const grants = [];
+    const expiredEvidence = new Map();
+    const grantKey = (grant) => `${grant.host}\0${grant.port}\0${grant.tls}`;
+    const recordExpired = (grant) => {
+        const key = grantKey(grant);
+        expiredEvidence.delete(key);
+        expiredEvidence.set(key, grant);
+        while (expiredEvidence.size > NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT) {
+            const oldest = expiredEvidence.keys().next().value;
+            if (typeof oldest !== "string")
+                break;
+            expiredEvidence.delete(oldest);
+        }
+    };
+    const purgeInactive = (now) => {
+        const live = [];
+        for (const grant of grants) {
+            if (grant.revoked)
+                continue;
+            if (grant.expiresAtMs !== undefined && now >= grant.expiresAtMs) {
+                recordExpired(grant);
+                continue;
+            }
+            live.push(grant);
+        }
+        grants.length = 0;
+        grants.push(...live);
+    };
+    const assertConnect = (input, tls) => {
+        if (!declared)
+            return;
+        const host = normalizeEgressHost(input.host);
+        const now = Date.now();
+        purgeInactive(now);
+        if (staticRules.some((rule) => rule.host === host && rule.ports.includes(input.port) && tlsModeAllows(rule.tls, tls)))
+            return;
+        const matching = grants.filter((grant) => !grant.revoked &&
+            grant.host === host &&
+            grant.port === input.port &&
+            tlsModeAllows(grant.tls, tls));
+        if (matching.length > 0)
+            return;
+        const expired = [...expiredEvidence.values()]
+            .filter((grant) => grant.host === host &&
+            grant.port === input.port &&
+            tlsModeAllows(grant.tls, tls))
+            .sort((left, right) => (right.expiresAtMs ?? 0) - (left.expiresAtMs ?? 0))[0];
+        if (expired?.expiresAtMs !== undefined)
+            throw new NativeEgressGrantExpiredError(input.host, input.port, tls, new Date(expired.expiresAtMs).toISOString());
+        throw new NativeEgressNotDeclaredError(input.host, input.port, tls);
+    };
+    const grantLocal = (input) => {
+        assertValidGrantInput(input);
+        const ruleIndex = dynamicRules.findIndex((rule) => matchesDynamicRuleSelectors(rule, input));
+        if (ruleIndex < 0)
+            throw new NativeNetworkError(`Native TCP egress grant is not declared for ${input.host}:${input.port} (${input.tls})`, "native_egress_not_declared");
+        const rule = dynamicRules[ruleIndex];
+        if (!rule)
+            throw invalidGrant("Native TCP egress declaration is missing its matched rule");
+        if (input.ttlMs !== undefined && rule.ttlMs !== undefined && input.ttlMs > rule.ttlMs)
+            throw invalidGrant(`Native TCP egress grant ttlMs ${input.ttlMs} exceeds declared maximum ${rule.ttlMs}`);
+        const now = Date.now();
+        const targetHost = normalizeEgressHost(input.host);
+        purgeInactive(now);
+        const activeForRule = grants.filter((grant) => grant.ruleIndex === ruleIndex &&
+            !grant.revoked &&
+            (grant.expiresAtMs === undefined || now < grant.expiresAtMs)).length;
+        if (rule.maxGrants !== undefined && activeForRule >= rule.maxGrants)
+            throw new NativeNetworkError(`Native TCP egress grant limit exceeded for declaration ${ruleIndex}`, "native_egress_grant_limit_exceeded");
+        const ttlMs = input.ttlMs ?? rule.ttlMs;
+        const expiresAtMs = ttlMs === undefined ? undefined : now + ttlMs;
+        if (expiresAtMs !== undefined && (!Number.isFinite(expiresAtMs) || expiresAtMs > 8.64e15))
+            throw invalidGrant("Native TCP egress grant expiry exceeds the supported date range");
+        const stored = {
+            ruleIndex,
+            host: targetHost,
+            port: input.port,
+            tls: input.tls,
+            ...(expiresAtMs === undefined ? {} : { expiresAtMs }),
+            revoked: false,
+        };
+        expiredEvidence.delete(grantKey(stored));
+        grants.push(stored);
+        return {
+            revoke() {
+                stored.revoked = true;
+            },
+        };
+    };
+    return {
+        assertConnect,
+        grant(input) {
+            if (!declared) {
+                if (delegate) {
+                    try {
+                        const delegated = delegate(input);
+                        if (!delegated || typeof delegated.revoke !== "function")
+                            throw new TypeError("Native egress delegate returned an invalid grant");
+                        return delegated;
+                    }
+                    catch (error) {
+                        if (error instanceof NativeNetworkError)
+                            throw error;
+                        throw new NativeNetworkError("Deployment native egress authorization failed", "native_egress_authorization_failed");
+                    }
+                }
+                throw new NativeNetworkError("Dynamic native egress authorization is not configured", "native_dynamic_egress_unsupported");
+            }
+            const local = grantLocal(input);
+            let delegated;
+            try {
+                delegated = delegate?.(Object.freeze({ ...input }));
+                if (delegated !== undefined && typeof delegated.revoke !== "function")
+                    throw new TypeError("Native egress delegate returned an invalid grant");
+            }
+            catch (error) {
+                local.revoke();
+                if (error instanceof NativeNetworkError)
+                    throw error;
+                throw new NativeNetworkError("Deployment native egress authorization failed", "native_egress_authorization_failed");
+            }
+            let revoked = false;
+            return {
+                revoke() {
+                    if (revoked)
+                        return;
+                    revoked = true;
+                    local.revoke();
+                    try {
+                        delegated?.revoke();
+                    }
+                    catch (error) {
+                        if (error instanceof NativeNetworkError)
+                            throw error;
+                        throw new NativeNetworkError("Deployment native egress grant revocation failed", "native_egress_authorization_failed");
+                    }
+                },
+            };
+        },
+    };
+}
+/** Create the SDK byte-stream runtime with provider-declared egress enforcement. */
 export function createNativeNetworkClient(options = {}) {
+    const egress = createNativeEgressAuthorization(options);
     return {
         connectTcp: async (input) => {
-            const deadline = deadlineFrom(input.timeoutMs);
-            assertCanStart(input.signal, deadline);
-            const proxy = await resolveConnectionProxy(options, input);
+            const request = snapshotNativeConnectInput(input);
+            egress.assertConnect(request, "disabled");
+            const deadline = deadlineFrom(request.timeoutMs);
+            assertCanStart(request.signal, deadline);
+            const proxy = await resolveConnectionProxy(options, request);
+            egress.assertConnect(request, "disabled");
             const socket = proxy
-                ? await connectSocksTunnel(proxy, input, deadline)
-                : await connectPlainSocket(input.host, input.port, input.signal, deadline);
-            return createNativeNetworkConnection(socket, proxy, options, input.idleTimeoutMs);
+                ? await connectSocksTunnel(proxy, request, deadline, () => egress.assertConnect(request, "disabled"))
+                : await connectPlainSocket(request.host, request.port, request.signal, deadline);
+            return createNativeNetworkConnection(socket, proxy, options, request.idleTimeoutMs);
         },
         connectTls: async (input) => {
-            const deadline = deadlineFrom(input.timeoutMs);
-            assertCanStart(input.signal, deadline);
-            const proxy = await resolveConnectionProxy(options, input);
-            const tunnel = proxy ? await connectSocksTunnel(proxy, input, deadline) : undefined;
-            const socket = await upgradeTls(tunnel, input, deadline);
-            return createNativeNetworkConnection(socket, proxy, options, input.idleTimeoutMs);
-        },
-        grantTcpEgress: (input) => {
-            if (options.grantTcpEgress)
-                return options.grantTcpEgress(input);
-            throw new NativeNetworkError("Dynamic native egress authorization is not configured", "native_dynamic_egress_unsupported");
+            const request = snapshotNativeConnectInput(input);
+            egress.assertConnect(request, "required");
+            const deadline = deadlineFrom(request.timeoutMs);
+            assertCanStart(request.signal, deadline);
+            const proxy = await resolveConnectionProxy(options, request);
+            egress.assertConnect(request, "required");
+            const tunnel = proxy
+                ? await connectSocksTunnel(proxy, request, deadline, () => egress.assertConnect(request, "required"))
+                : undefined;
+            const socket = await upgradeTls(tunnel, request, deadline);
+            return createNativeNetworkConnection(socket, proxy, options, request.idleTimeoutMs);
         },
+        grantTcpEgress: (input) => egress.grant(snapshotNativeGrantInput(input)),
     };
 }

package/dist/runtime/redirects.d.ts

@@ -0,0 +1,29 @@
+import type { HttpRedirectFailureReason } from "../types.js";
+export type RedirectHopDecision<TMethod extends string> = {
+    kind: "follow";
+    nextMethod: TMethod | "GET";
+    nextUrl: string;
+} | {
+    kind: "stop";
+    reason: HttpRedirectFailureReason;
+    nextUrl?: string;
+};
+export declare function isRedirectStatus(status: number): boolean;
+/** Shared fetch-compatible redirect method rewriting for stealth and ctx.http. */
+export declare function nextRedirectMethod<TMethod extends string>(status: number, method: TMethod): TMethod | "GET";
+/** Resolves a Location value against the response URL without issuing a request. */
+export declare function resolveRedirectUrl(location: string | undefined, responseUrl: string): string | undefined;
+/**
+ * Shared post-response decision ordering for both redirect walkers. The
+ * caller-owned stop hook is checked first, matching stealth's pre-follow
+ * contract, then structural termination and loop checks run before follow.
+ */
+export declare function evaluateRedirectHop<TMethod extends string>(input: {
+    status: number;
+    method: TMethod;
+    nextUrl: string | undefined;
+    shouldStop: boolean;
+    redirectCount: number;
+    maxHops: number;
+    visitedRequests: ReadonlySet<string>;
+}): RedirectHopDecision<TMethod>;

package/dist/runtime/redirects.js

@@ -0,0 +1,36 @@
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+export function isRedirectStatus(status) {
+    return REDIRECT_STATUSES.has(status);
+}
+/** Shared fetch-compatible redirect method rewriting for stealth and ctx.http. */
+export function nextRedirectMethod(status, method) {
+    if (status === 303 && method !== "HEAD")
+        return "GET";
+    if ((status === 301 || status === 302) && method === "POST")
+        return "GET";
+    return method;
+}
+/** Resolves a Location value against the response URL without issuing a request. */
+export function resolveRedirectUrl(location, responseUrl) {
+    return location ? new URL(location, responseUrl).toString() : undefined;
+}
+/**
+ * Shared post-response decision ordering for both redirect walkers. The
+ * caller-owned stop hook is checked first, matching stealth's pre-follow
+ * contract, then structural termination and loop checks run before follow.
+ */
+export function evaluateRedirectHop(input) {
+    if (input.shouldStop) {
+        return { kind: "stop", reason: "stopped", ...(input.nextUrl ? { nextUrl: input.nextUrl } : {}) };
+    }
+    if (!input.nextUrl)
+        return { kind: "stop", reason: "missing_location" };
+    if (input.redirectCount > input.maxHops) {
+        return { kind: "stop", reason: "max_hops", nextUrl: input.nextUrl };
+    }
+    const nextMethod = nextRedirectMethod(input.status, input.method);
+    if (input.visitedRequests.has(`${nextMethod} ${input.nextUrl}`)) {
+        return { kind: "stop", reason: "loop", nextUrl: input.nextUrl };
+    }
+    return { kind: "follow", nextMethod, nextUrl: input.nextUrl };
+}

package/dist/runtime/stealth.js

@@ -6,6 +6,7 @@ import { SDKError, StealthCookieStoreVersionError, TransportError } from "../err
 import { getStealthProfile } from "../stealth/profiles.js";
 import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
+import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl, } from "./redirects.js";
 import { isSensitiveKey, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, normalizeSensitiveParams, serializeRequestUrl, } from "./request-options.js";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
@@ -558,16 +559,6 @@ function normalizeMethod(method) {
             throw new SDKError(`Unsupported stealth method: ${method}`);
     }
 }
-function isRedirectStatus(status) {
-    return [301, 302, 303, 307, 308].includes(status);
-}
-function nextRedirectMethod(status, method) {
-    if (status === 303 && method !== "HEAD")
-        return "GET";
-    if ((status === 301 || status === 302) && method === "POST")
-        return "GET";
-    return method;
-}
 function locationHeader(headers) {
     for (const [name, value] of Object.entries(headers)) {
         if (name.toLowerCase() === "location")
@@ -972,7 +963,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     const redactedLocation = location ? redactRedirectUrl(location) : undefined;
                     let nextUrl;
                     try {
-                        nextUrl = location ? new URL(location, responseUrl).toString() : undefined;
+                        nextUrl = resolveRedirectUrl(location, responseUrl);
                     }
                     catch (error) {
                         throw redactSensitiveError(error, [...sensitiveValues], location, redactedLocation);
@@ -1010,48 +1001,29 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             throw sanitizedError;
                         }
                     }
-                    if (shouldStop) {
-                        return {
-                            final: response,
-                            hops,
-                            reason: "stopped",
-                            cookies: cookieJar.snapshot(),
-                            cookieStore: cookieJar.serialize(),
-                        };
-                    }
-                    if (!nextUrl) {
-                        return {
-                            final: response,
-                            hops,
-                            reason: "missing_location",
-                            cookies: cookieJar.snapshot(),
-                            cookieStore: cookieJar.serialize(),
-                        };
-                    }
-                    if (hops.length > maxHops) {
+                    const decision = evaluateRedirectHop({
+                        status: response.status,
+                        method,
+                        nextUrl,
+                        shouldStop,
+                        redirectCount: hops.length,
+                        maxHops,
+                        visitedRequests,
+                    });
+                    if (decision.kind === "stop") {
                         return {
                             final: response,
                             hops,
-                            reason: "max_hops",
+                            reason: decision.reason,
                             cookies: cookieJar.snapshot(),
                             cookieStore: cookieJar.serialize(),
                         };
                     }
-                    const nextMethod = nextRedirectMethod(response.status, method);
-                    if (nextMethod !== method) {
+                    if (decision.nextMethod !== method) {
                         body = undefined;
                     }
-                    if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
-                        return {
-                            final: response,
-                            hops,
-                            reason: "loop",
-                            cookies: cookieJar.snapshot(),
-                            cookieStore: cookieJar.serialize(),
-                        };
-                    }
-                    method = nextMethod;
-                    currentUrl = nextUrl;
+                    method = decision.nextMethod;
+                    currentUrl = decision.nextUrl;
                 }
                 if (!response) {
                     response = await session.fetch(currentUrl, {

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { createServerApp, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";

package/dist/server/index.js

@@ -1,4 +1,4 @@
-export { createServerApp, serve, } from "./serve.js";
+export { createServerApp, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";

package/dist/server/serve.d.ts

@@ -3,6 +3,14 @@ import { z } from "zod";
 import { type ProviderErrorCategory } from "../observability.js";
 import type { ProviderContext, ProviderDefinition, ProviderRuntimeState, SttContext } from "../types.js";
 import { type OperationRequest } from "./types.js";
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+export type ErrorObservabilityDetails = {
+    category: ProviderErrorCategory;
+    taxonomyVersion: string;
+    retryable: boolean;
+    upstreamStatus?: number;
+};
 export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
     requestId: z.ZodString;
     providerId: z.ZodString;
@@ -78,6 +86,7 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     errorCategory?: ProviderErrorCategory;
     taxonomyVersion?: string;
     retryable?: boolean;
+    signal?: "unregistered_provider_error_code";
     issues?: Array<{
         path: string;
         code: string;