@apifuse/provider-sdk 2.2.0-beta.67 → 2.2.0-beta.69

package/dist/runtime/diagnostic-redactor.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { allSensitiveValueVariants, normalizePercentEscapes, REDACTED_QUERY_VALUE, } from "./request-options.js";
+import { RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES } from "./resolver-span-attributes.js";
 export const REDACTION_FAILED = "[REDACTION_FAILED]";
 // No supported credential source needs 1–3 character secrets. Registering these
 // common tokens damages unrelated IDs and diagnostics even with token boundaries.
@@ -492,9 +493,15 @@ export function redactDiagnosticAttributeKey(key, redact) {
 export function redactCriticalDiagnosticText(text, redact) {
     return redactDiagnosticText(text, redact ? (criticalRedactors.get(redact) ?? redact) : undefined);
 }
-export function diagnosticAttributeRedactor(key, redact) {
-    if (CLOSED_ENUM_ATTRIBUTE_KEYS.has(key))
+/**
+ * The redactor for one attribute value. A value its producer declares as a closed-enum literal for
+ * this key is a contract, like a typed number: exhaustion suppression skips it, while registered
+ * credentials still match. Any other value under the same key stays free text.
+ */
+export function diagnosticAttributeRedactor(key, redact, value) {
+    if (typeof value === "string" && CLOSED_ENUM_ATTRIBUTE_VALUES.get(key)?.has(value)) {
         return diagnosticStructuredRedactor(redact);
+    }
     return CRITICAL_ATTRIBUTE_KEYS.has(key) && redact
         ? (criticalRedactors.get(redact) ?? redact)
         : redact;
@@ -512,18 +519,13 @@ const CRITICAL_ATTRIBUTE_KEYS = new Set([
     "operation",
     "http.status_code",
 ]);
-// SDK-owned closed enums are contracts, like typed numbers and booleans. This
-// exempts only exhaustion suppression; registered credentials still match.
-const CLOSED_ENUM_ATTRIBUTE_KEYS = new Set([
-    "outcome",
-    "code",
-    "errorClass",
-    "phase",
-    "cacheStatus",
-    "identitySource",
-    "taxonomy",
-    "taxonomyVersion",
-]);
+// SDK-owned closed enums are contracts, like typed numbers and booleans. The table is the
+// producers' own declaration of which span attributes are closed enums and of every literal each
+// one can carry; it exempts only exhaustion suppression, and registered credentials still match.
+const CLOSED_ENUM_ATTRIBUTE_VALUES = new Map(Object.entries(RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES).map(([key, values]) => [
+    key,
+    new Set(values),
+]));
 // Bigints normalize to strings for OTLP. Carry their type policy through internal
 // detached copies without treating arbitrary numeric-looking free text as typed.
 const bigintAttributes = new WeakMap();

package/dist/runtime/executor.js

@@ -22,6 +22,9 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     if (!operation) {
         throw new ProviderError(`Unknown operation: ${provider.id}/${operationId}`, {
             code: "NOT_FOUND",
+            // No upstream was asked: keep the registered NOT_FOUND code from
+            // attributing this to one.
+            category: "provider_error",
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }

package/dist/runtime/http.d.ts

@@ -37,4 +37,6 @@ export type HttpClientOptions = ProxyResolutionOptions & {
     httpTelemetry?: HttpTelemetrySink;
     signal?: AbortSignal;
 };
+/** Whether `url` carries its own scheme, so it needs no `upstream.baseUrl` to resolve. */
+export declare function isAbsoluteUrl(url: string): boolean;
 export declare function createHttpClient(baseUrl?: string, clientOptions?: HttpClientOptions): HttpClient;

package/dist/runtime/http.js

@@ -1,9 +1,9 @@
 import { policyRotatesTransportVendorChain, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, } from "../config/loader.js";
-import { HttpRedirectError, ProviderError, TransportError } from "../errors.js";
+import { 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 { httpTelemetryErrorCode, } from "./http-telemetry.js";
-import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl } from "./redirects.js";
+import { invalidRedirectPolicy, isRedirectStatus, nextSameOriginRedirectHop, normalizeRedirectPolicy, } from "./redirects.js";
 import { normalizeHttpRequestBody, redactSensitiveError, redactSensitiveRequestError, serializeRequestUrl, } from "./request-options.js";
 import { startHttpTelemetry } from "./http-telemetry-guard.js";
 import { scopedHttpTelemetry } from "./http-telemetry-binding.js";
@@ -401,73 +401,32 @@ function normalizeHttpMethod(method) {
             });
     }
 }
-function isAbsoluteUrl(url) {
+/** Whether `url` carries its own scheme, so it needs no `upstream.baseUrl` to resolve. */
+export function isAbsoluteUrl(url) {
     return /^[a-z][a-z\d+\-.]*:/i.test(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 HTTP_REDIRECT_POLICY_TRANSPORT = {
+    label: "ctx.http",
+    maxHops: MAX_HTTP_REDIRECT_HOPS,
+};
 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);
+        return normalizeRedirectPolicy(options.redirectPolicy, HTTP_REDIRECT_POLICY_TRANSPORT);
     }
     catch (error) {
         if (error instanceof TransportError)
             throw error;
-        throw invalidHttpRedirectPolicy("could not be read safely", error instanceof Error ? error : undefined);
+        throw invalidRedirectPolicy(HTTP_REDIRECT_POLICY_TRANSPORT, "could not be read safely", error instanceof Error ? error : undefined);
     }
 }
 function withoutRedirectBodyHeaders(headers) {
@@ -476,21 +435,6 @@ function withoutRedirectBodyHeaders(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();
@@ -531,47 +475,17 @@ async function fetchWithHttpRedirectPolicy(requestUrl, requestInit, policy) {
             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({
+        const decision = nextSameOriginRedirectHop({
+            policy,
+            initialOrigin,
+            currentUrl,
+            responseUrl: currentUrl,
             status: response.status,
             method,
-            nextUrl: nextUrlString,
-            shouldStop: nextUrlString ? new URL(nextUrlString).origin !== initialOrigin : false,
-            redirectCount: followedHops + 1,
-            maxHops: policy.maxHops,
+            location: location ?? undefined,
+            followedHops,
             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);

package/dist/runtime/instrumentation.js

@@ -4,6 +4,7 @@ import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { parseHttpRequestInvocation, isSensitiveKey, redactSensitiveError, redactSensitiveText, redactUrlQueryParams, requestOptionsFromHttpInvocation, serializeRequestUrl, } from "./request-options.js";
 import { createTraceContext, getTraceRecorder, } from "./trace.js";
 import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 const BROWSER_PAGE_METHODS = new Set([
     "goto",
     "fill",
@@ -485,7 +486,9 @@ function wrapNamespace(namespace, target, trace, shouldInstrument) {
                         ? challenge.kind
                         : undefined;
                     return recorder.runSpan("resolver.solve", () => Reflect.apply(value, namespaceTarget, [args[0], args[1], recorder]), {
-                        attributes: challengeKind ? { challenge_kind: challengeKind } : undefined,
+                        attributes: challengeKind
+                            ? resolverSpanAttributes({ challenge_kind: challengeKind })
+                            : undefined,
                     });
                 };
                 wrappedMethods.set(property, wrapped);

package/dist/runtime/provider.d.ts

@@ -1,2 +1,9 @@
 import type { ProviderDefinition } from "../types.js";
 export declare function getProviderBaseUrl(provider: ProviderDefinition): string | undefined;
+/**
+ * The base `ctx.stealth` resolves relative request URLs (and seeds its cookie
+ * jar's default origin) against: the provider's first declared
+ * `upstream.baseUrl`, else `https://<allowedHosts[0]>`. `undefined` means the
+ * provider declares neither, and `serve` binds no stealth transport at all.
+ */
+export declare function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undefined;

package/dist/runtime/provider.js

@@ -8,3 +8,17 @@ export function getProviderBaseUrl(provider) {
     }
     return undefined;
 }
+/**
+ * The base `ctx.stealth` resolves relative request URLs (and seeds its cookie
+ * jar's default origin) against: the provider's first declared
+ * `upstream.baseUrl`, else `https://<allowedHosts[0]>`. `undefined` means the
+ * provider declares neither, and `serve` binds no stealth transport at all.
+ */
+export function getProviderStealthBaseUrl(provider) {
+    const baseUrl = getProviderBaseUrl(provider);
+    if (baseUrl) {
+        return baseUrl;
+    }
+    const firstHost = provider.allowedHosts?.[0];
+    return firstHost ? `https://${firstHost}` : undefined;
+}

package/dist/runtime/redirect-hop-headers.d.ts

@@ -0,0 +1,19 @@
+/** One redirect hop: the URL the headers were sent to, and the next request. */
+export interface RedirectHop {
+    readonly from: string;
+    readonly to: string;
+    readonly methodChanged: boolean;
+}
+/**
+ * The caller headers the next redirect hop carries, derived from the headers
+ * the previous hop sent. Both stealth redirect walkers compute every hop's
+ * headers here, so the rules hold on every path:
+ *
+ * - a method change drops the request-body headers;
+ * - a cross-origin hop drops `Authorization` and `Proxy-Authorization`;
+ * - a cross-site hop drops an explicit `Cookie`, after which the session
+ *   cookie jar supplies cookies by its own domain rules, as a browser does.
+ *
+ * A header dropped on one hop stays dropped for the rest of the chain.
+ */
+export declare function redirectHopHeaders<T>(hop: RedirectHop, headers: Readonly<Record<string, T>>): Record<string, T>;

package/dist/runtime/redirect-hop-headers.js

@@ -0,0 +1,58 @@
+import { getPublicSuffix } from "tough-cookie";
+/**
+ * Request-body header names a redirect drops when it changes the method
+ * (Fetch "request-body-header name").
+ */
+const REDIRECT_BODY_HEADERS = new Set([
+    "content-encoding",
+    "content-language",
+    "content-location",
+    "content-type",
+]);
+/**
+ * Credentials a redirect never carries to another origin. Fetch removes
+ * `Authorization` on a cross-origin redirect; `Proxy-Authorization` is a
+ * credential of the same kind.
+ */
+const CROSS_ORIGIN_CREDENTIAL_HEADERS = new Set([
+    "authorization",
+    "proxy-authorization",
+]);
+/**
+ * Schemeful site (HTML "same site"): scheme plus registrable domain from the
+ * public suffix list, or the bare host when there is none (an IP address or
+ * a single-label host).
+ */
+function schemefulSite(url) {
+    const host = url.hostname;
+    const registrable = getPublicSuffix(host, { allowSpecialUseDomain: true, ignoreError: true });
+    return `${url.protocol}//${registrable ?? host}`;
+}
+/**
+ * The caller headers the next redirect hop carries, derived from the headers
+ * the previous hop sent. Both stealth redirect walkers compute every hop's
+ * headers here, so the rules hold on every path:
+ *
+ * - a method change drops the request-body headers;
+ * - a cross-origin hop drops `Authorization` and `Proxy-Authorization`;
+ * - a cross-site hop drops an explicit `Cookie`, after which the session
+ *   cookie jar supplies cookies by its own domain rules, as a browser does.
+ *
+ * A header dropped on one hop stays dropped for the rest of the chain.
+ */
+export function redirectHopHeaders(hop, headers) {
+    const from = new URL(hop.from);
+    const to = new URL(hop.to);
+    const crossOrigin = from.origin !== to.origin;
+    const crossSite = schemefulSite(from) !== schemefulSite(to);
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => {
+        const lower = name.toLowerCase();
+        if (hop.methodChanged && REDIRECT_BODY_HEADERS.has(lower))
+            return false;
+        if (crossOrigin && CROSS_ORIGIN_CREDENTIAL_HEADERS.has(lower))
+            return false;
+        if (crossSite && lower === "cookie")
+            return false;
+        return true;
+    }));
+}

package/dist/runtime/redirects.d.ts

@@ -1,4 +1,5 @@
-import type { HttpRedirectFailureReason } from "../types.js";
+import { TransportError } from "../errors.js";
+import type { HttpRedirectFailureReason, HttpRedirectPolicy } from "../types.js";
 export type RedirectHopDecision<TMethod extends string> = {
     kind: "follow";
     nextMethod: TMethod | "GET";
@@ -27,3 +28,34 @@ export declare function evaluateRedirectHop<TMethod extends string>(input: {
     maxHops: number;
     visitedRequests: ReadonlySet<string>;
 }): RedirectHopDecision<TMethod>;
+export declare const MALFORMED_REDIRECT_TARGET = "[malformed redirect target]";
+/** The transport a redirectPolicy belongs to: its name in diagnostics and its own hop limit. */
+export interface RedirectPolicyTransport {
+    readonly label: string;
+    readonly maxHops: number;
+}
+export declare function invalidRedirectPolicy(transport: RedirectPolicyTransport, message: string, cause?: Error): TransportError;
+/** Snapshot untrusted caller input synchronously, before proxy resolution or fetch. */
+export declare function normalizeRedirectPolicy(value: unknown, transport: RedirectPolicyTransport): HttpRedirectPolicy | undefined;
+export declare function redirectDiagnosticTarget(value: string): string;
+/**
+ * One hop of a same-origin `redirectPolicy` walk, shared by ctx.http and
+ * ctx.stealth so both follow and refuse identically: returns the next request
+ * inside the initial origin, or throws the `HttpRedirectError` naming why the
+ * walk stopped (cross-origin target, maxHops, loop, missing or malformed
+ * Location) before any request leaves for that target.
+ */
+export declare function nextSameOriginRedirectHop<TMethod extends string>(input: {
+    policy: HttpRedirectPolicy;
+    initialOrigin: string;
+    currentUrl: string;
+    responseUrl: string;
+    status: number;
+    method: TMethod;
+    location: string | undefined;
+    followedHops: number;
+    visitedRequests: ReadonlySet<string>;
+}): {
+    nextMethod: TMethod | "GET";
+    nextUrl: string;
+};

package/dist/runtime/redirects.js

@@ -1,3 +1,4 @@
+import { HttpRedirectError, TransportError } from "../errors.js";
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 export function isRedirectStatus(status) {
     return REDIRECT_STATUSES.has(status);
@@ -34,3 +35,115 @@ export function evaluateRedirectHop(input) {
     }
     return { kind: "follow", nextMethod, nextUrl: input.nextUrl };
 }
+const REDIRECT_POLICY_FIELDS = new Set(["mode", "maxHops"]);
+export const MALFORMED_REDIRECT_TARGET = "[malformed redirect target]";
+export function invalidRedirectPolicy(transport, message, cause) {
+    return new TransportError(`Invalid ${transport.label} redirectPolicy: ${message}`, {
+        code: "http_redirect_policy_invalid",
+        ...(cause ? { cause } : {}),
+    });
+}
+/** Snapshot untrusted caller input synchronously, before proxy resolution or fetch. */
+export function normalizeRedirectPolicy(value, transport) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidRedirectPolicy(transport, "expected an object");
+    }
+    try {
+        const keys = Reflect.ownKeys(value);
+        for (const key of keys) {
+            if (typeof key !== "string" || !REDIRECT_POLICY_FIELDS.has(key)) {
+                throw invalidRedirectPolicy(transport, `unknown field ${String(key)}`);
+            }
+        }
+        for (const field of REDIRECT_POLICY_FIELDS) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, field);
+            if (!descriptor || !("value" in descriptor)) {
+                throw invalidRedirectPolicy(transport, `${field} must be an own data property`);
+            }
+        }
+        const record = value;
+        if (record.mode !== "same-origin") {
+            throw invalidRedirectPolicy(transport, 'mode must be "same-origin"');
+        }
+        if (typeof record.maxHops !== "number" ||
+            !Number.isInteger(record.maxHops) ||
+            record.maxHops < 0 ||
+            record.maxHops > transport.maxHops) {
+            throw invalidRedirectPolicy(transport, `maxHops must be an integer from 0 to ${transport.maxHops}`);
+        }
+        return { mode: "same-origin", maxHops: record.maxHops };
+    }
+    catch (error) {
+        if (error instanceof TransportError)
+            throw error;
+        throw invalidRedirectPolicy(transport, "could not be inspected safely", error instanceof Error ? error : undefined);
+    }
+}
+export 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;
+    }
+}
+/**
+ * One hop of a same-origin `redirectPolicy` walk, shared by ctx.http and
+ * ctx.stealth so both follow and refuse identically: returns the next request
+ * inside the initial origin, or throws the `HttpRedirectError` naming why the
+ * walk stopped (cross-origin target, maxHops, loop, missing or malformed
+ * Location) before any request leaves for that target.
+ */
+export function nextSameOriginRedirectHop(input) {
+    let nextUrl;
+    try {
+        nextUrl = resolveRedirectUrl(input.location || undefined, input.responseUrl);
+    }
+    catch {
+        const target = MALFORMED_REDIRECT_TARGET;
+        throw new HttpRedirectError(`Redirect response has malformed Location target ${target}`, {
+            reason: "missing_location",
+            target,
+            status: input.status,
+        });
+    }
+    const decision = evaluateRedirectHop({
+        status: input.status,
+        method: input.method,
+        nextUrl,
+        shouldStop: nextUrl ? new URL(nextUrl).origin !== input.initialOrigin : false,
+        redirectCount: input.followedHops + 1,
+        maxHops: input.policy.maxHops,
+        visitedRequests: input.visitedRequests,
+    });
+    if (decision.kind === "follow") {
+        return { nextMethod: decision.nextMethod, nextUrl: decision.nextUrl };
+    }
+    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(input.currentUrl)} is missing Location`;
+        }
+    })();
+    throw new HttpRedirectError(message, {
+        reason: decision.reason,
+        ...(target ? { target } : {}),
+        status: input.status,
+    });
+}

package/dist/runtime/resolver-span-attributes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Closed-enum span attributes emitted by the resolver, by attribute key. A value listed here is an
+ * SDK-declared literal, so fail-closed diagnostic redaction keeps it the way it keeps a typed
+ * number; any other value under the same key is still free text. Registered credentials are
+ * matched either way.
+ */
+export declare const RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES: {
+    readonly vendor: readonly ["browser", "capsolver", "capmonster", "2captcha", "hypersolutions", "custom"];
+    readonly challenge_kind: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor", "akamai_sbsd"];
+    readonly endpoint: readonly ["capsolver:create_task", "twocaptcha:create_task", "hyper:ip", "hyper:sbsd_create"];
+    readonly billing: readonly ["metered", "unconfirmed"];
+    readonly outcome: readonly ["success", "vendor_error", "timeout", "abandoned", "cache_disabled", "entry_deleted", "index_entry_deleted", "not_cookie_solution", "solution_not_cached"];
+    readonly unavailability_reason: readonly ["missing_credentials", "missing_proxy_identity", "missing_client_profile", "missing_challenge_input", "missing_transport", "allocation_exhausted", "transport_failure", "timeout", "not_implemented"];
+    readonly verdict_reason: readonly ["human_puzzle", "solve_failed"];
+    readonly transport_phase: readonly ["create_task", "poll_result", "cleanup", "measure_ip", "fetch_script", "generate_payload", "post_payload"];
+    readonly resolver_identity_source: readonly ["declared", "defaulted"];
+    readonly operation: readonly ["client.close", "context.close"];
+};
+type ResolverClosedEnumSpanAttributes = typeof RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES;
+type Present<T> = Exclude<T, undefined>;
+/** Properties typed as a finite union of string literals, never plain `string`. */
+type FiniteStringKeys<T> = {
+    [K in keyof T]-?: [Present<T[K]>] extends [never] ? never : [Present<T[K]>] extends [string] ? string extends Present<T[K]> ? never : K : never;
+}[keyof T];
+type DeclaredClosedEnumAttributes<T> = {
+    [K in keyof T]: K extends FiniteStringKeys<T> ? K extends keyof ResolverClosedEnumSpanAttributes ? [Present<T[K]>] extends [ResolverClosedEnumSpanAttributes[K][number]] ? T[K] : never : never : T[K];
+};
+/**
+ * Resolver span attributes. Every property typed as a finite string union must be declared in
+ * `RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES` with all of its members, so a new closed-enum attribute
+ * cannot silently become free text that fail-closed redaction suppresses.
+ */
+export declare function resolverSpanAttributes<const T extends Record<string, unknown>>(attributes: T & DeclaredClosedEnumAttributes<T>): T;
+export {};

package/dist/runtime/resolver-span-attributes.js

@@ -0,0 +1,93 @@
+// Type-only imports: the diagnostic redactor reads this table, so it must not pull the resolver
+// runtime (or anything that imports the redactor) into module evaluation.
+/** Every member of a closed string union, as runtime values; a missing or extra member fails tsc. */
+function closedEnumValues() {
+    return (values, ..._missing) => values;
+}
+const RESOLVER_PAID_USAGE_OUTCOMES = closedEnumValues()([
+    "success",
+    "vendor_error",
+    "timeout",
+    "abandoned",
+]);
+// `resolver.cache.invalidate` outcomes. The union stays private to resolver.ts; its producer's
+// `resolverSpanAttributes` call fails to compile if it can emit an outcome missing here.
+const RESOLVER_CACHE_INVALIDATION_OUTCOMES = [
+    "cache_disabled",
+    "entry_deleted",
+    "index_entry_deleted",
+    "not_cookie_solution",
+    "solution_not_cached",
+];
+/**
+ * Closed-enum span attributes emitted by the resolver, by attribute key. A value listed here is an
+ * SDK-declared literal, so fail-closed diagnostic redaction keeps it the way it keeps a typed
+ * number; any other value under the same key is still free text. Registered credentials are
+ * matched either way.
+ */
+export const RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES = {
+    vendor: closedEnumValues()([
+        "browser",
+        "capsolver",
+        "capmonster",
+        "2captcha",
+        "hypersolutions",
+        "custom",
+    ]),
+    challenge_kind: closedEnumValues()([
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
+        "akamai_sbsd",
+    ]),
+    endpoint: closedEnumValues()([
+        "capsolver:create_task",
+        "twocaptcha:create_task",
+        "hyper:ip",
+        "hyper:sbsd_create",
+    ]),
+    billing: closedEnumValues()(["metered", "unconfirmed"]),
+    outcome: [...RESOLVER_PAID_USAGE_OUTCOMES, ...RESOLVER_CACHE_INVALIDATION_OUTCOMES],
+    unavailability_reason: closedEnumValues()([
+        "missing_credentials",
+        "missing_proxy_identity",
+        "missing_client_profile",
+        "missing_challenge_input",
+        "missing_transport",
+        "allocation_exhausted",
+        "transport_failure",
+        "timeout",
+        "not_implemented",
+    ]),
+    verdict_reason: closedEnumValues()([
+        "human_puzzle",
+        "solve_failed",
+    ]),
+    transport_phase: closedEnumValues()([
+        "create_task",
+        "poll_result",
+        "cleanup",
+        "measure_ip",
+        "fetch_script",
+        "generate_payload",
+        "post_payload",
+    ]),
+    resolver_identity_source: closedEnumValues()(["declared", "defaulted"]),
+    operation: closedEnumValues()([
+        "client.close",
+        "context.close",
+    ]),
+};
+/**
+ * Resolver span attributes. Every property typed as a finite string union must be declared in
+ * `RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES` with all of its members, so a new closed-enum attribute
+ * cannot silently become free text that fail-closed redaction suppresses.
+ */
+export function resolverSpanAttributes(attributes) {
+    return attributes;
+}