@apifuse/provider-sdk 2.2.0-beta.58 → 2.2.0-beta.60

package/dist/server/trace-output.d.ts

@@ -1,6 +1,7 @@
+import { type DiagnosticRedactor } from "../runtime/diagnostic-redactor.js";
 import { type CreateTraceContextOptions } from "../runtime/trace.js";
 import type { TraceConfig } from "../types.js";
 type EnvLike = Record<string, string | undefined>;
 /** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
-export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>, env?: EnvLike): CreateTraceContextOptions;
+export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>, env?: EnvLike, redact?: DiagnosticRedactor): CreateTraceContextOptions;
 export {};

package/dist/server/trace-output.js

@@ -1,7 +1,9 @@
 import { isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE } from "../fixture-sanitization.js";
+import { redactedKeyAllocator, isRedactedKey, REDACTION_FAILED, redactDiagnosticText, } from "../runtime/diagnostic-redactor.js";
 import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, resolveOTLPExportOptions, resolveOTLPResourceAttributes, } from "../runtime/otlp.js";
 import { resolveTraceContextOptions, } from "../runtime/trace.js";
 import { sanitizeSpanForOutput, sanitizeSpanNameForOutput, sanitizeTraceAttributes, } from "../trace-sanitization.js";
+const TRACE_RESOURCE_ATTRIBUTE_SANITIZER = Symbol.for("@apifuse/provider-sdk/runtime/trace-resource-attribute-sanitizer");
 // Warn once per environment object: process.env in production, each injected env in tests.
 const warnedEnvironments = new WeakSet();
 const warnedResourceEnvironments = new WeakSet();
@@ -36,25 +38,48 @@ function resolveServerOTLPExportOptions(config, env) {
  * environment are identifiers rather than request data: their values are kept, with control
  * characters neutralized, length bounded, and secret-named keys redacted.
  */
-function resolveExportResourceAttributes(requestAttributes, env) {
+function resolveExportResourceAttributes(requestAttributes, env, redact) {
     const resolution = resolveOTLPResourceAttributes({}, env);
     warnDiscardedResourceAttributes(env, resolution);
-    const operatorAttributes = Object.fromEntries(Object.entries(resolution.attributes).map(([key, value]) => [
-        sanitizeSpanNameForOutput(key),
-        isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeSpanNameForOutput(value),
-    ]));
-    const sanitizedRequestAttributes = Object.fromEntries(Object.entries(sanitizeTraceAttributes(requestAttributes)).map(([key, value]) => [
-        key,
-        String(value),
-    ]));
-    return { ...operatorAttributes, ...sanitizedRequestAttributes };
+    const operatorAttributes = resolution.attributes;
+    const requestKeys = new Set(Object.keys(requestAttributes));
+    return {
+        // Keep the raw snapshot private until export. A credential registered after
+        // trace creation must be matched before any key or value is bounded.
+        attributes: { ...operatorAttributes, ...requestAttributes },
+        sanitize(attributes) {
+            const nextKey = redactedKeyAllocator(Object.keys(attributes));
+            const sanitizedOperatorAttributes = {};
+            const rawRequestAttributes = {};
+            for (const [key, value] of Object.entries(attributes)) {
+                const unchangedOperatorValue = !requestKeys.has(key) && operatorAttributes[key] === value;
+                if (unchangedOperatorValue) {
+                    const redactedKey = isRedactedKey(key) ? key : redactDiagnosticText(key, redact);
+                    const keyChanged = redactedKey !== key;
+                    const sanitizedKey = keyChanged ? nextKey() : sanitizeSpanNameForOutput(key);
+                    sanitizedOperatorAttributes[sanitizedKey] = keyChanged
+                        ? redactedKey === REDACTION_FAILED
+                            ? REDACTION_FAILED
+                            : REDACTED_FIXTURE_VALUE
+                        : isSensitiveFixtureKey(key)
+                            ? REDACTED_FIXTURE_VALUE
+                            : sanitizeSpanNameForOutput(value, redact);
+                }
+                else {
+                    rawRequestAttributes[key] = value;
+                }
+            }
+            const sanitizedRequestAttributes = Object.fromEntries(Object.entries(sanitizeTraceAttributes(rawRequestAttributes, redact, Object.keys(sanitizedOperatorAttributes))).map(([key, value]) => [key, String(value)]));
+            return { ...sanitizedOperatorAttributes, ...sanitizedRequestAttributes };
+        },
+    };
 }
 /** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
-export function resolveServerTraceContextOptions(config, resourceAttributes, env = process.env) {
+export function resolveServerTraceContextOptions(config, resourceAttributes, env = process.env, redact) {
     const resolved = resolveTraceContextOptions(config);
     const outputEnabled = config.enabled !== false && config.exporter !== "none";
     const consoleHook = outputEnabled && (config.exporter === "console" || config.exporter === "json")
-        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes)))
+        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes, redact)))
         : undefined;
     const onSpan = consoleHook && resolved.onSpan
         ? (span) => {
@@ -65,14 +90,21 @@ export function resolveServerTraceContextOptions(config, resourceAttributes, env
     const exportOptions = outputEnabled && config.exporter === "otlp"
         ? resolveServerOTLPExportOptions(config, env)
         : undefined;
+    const exportResources = exportOptions
+        ? resolveExportResourceAttributes(resourceAttributes, env, redact)
+        : undefined;
+    if (exportResources) {
+        Object.defineProperty(exportResources.attributes, TRACE_RESOURCE_ATTRIBUTE_SANITIZER, { value: exportResources.sanitize });
+    }
     return {
         maxSpans: resolved.maxSpans,
         onSpan,
+        ...(redact ? { redact } : {}),
         ...(exportOptions
             ? {
                 exportOptions,
-                resourceAttributes: resolveExportResourceAttributes(resourceAttributes, env),
-                sanitizeSpanForExport: (span) => sanitizeSpanForOutput(span),
+                resourceAttributes: exportResources?.attributes,
+                sanitizeSpanForExport: (span) => sanitizeSpanForOutput(span, undefined, redact),
             }
             : {}),
     };

package/dist/server/types.d.ts

@@ -115,6 +115,9 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    engine: z.ZodOptional<z.ZodObject<{
+        egressLease: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
@@ -133,6 +136,9 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
 export declare const AuthFlowSuccessResponseSchema: z.ZodObject<{
     data: z.ZodUnknown;
     contextPatch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodUnknown>>>;
+    engine: z.ZodOptional<z.ZodObject<{
+        egressLease: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
     error: z.ZodObject<{

package/dist/server/types.js

@@ -85,10 +85,24 @@ export const AuthFlowRequestSchema = z.object({
     headers: z.record(z.string(), z.string()).optional(),
     input: z.record(z.string(), z.unknown()).optional(),
     context: z.record(z.string(), z.unknown()).optional(),
+    /** Opaque engine state. This is never projected into FlowContext or provider contextPatch. */
+    engine: z
+        .object({
+        egressLease: z.string().min(1).max(16_384).optional(),
+    })
+        .strict()
+        .optional(),
     connection: OperationConnectionSchema.optional(),
 });
 export const AuthFlowSuccessResponseSchema = z.object({
     data: z.unknown(),
     contextPatch: z.record(z.string(), z.unknown().nullable()).optional(),
+    /** Opaque engine state to carry verbatim to the next auth turn. */
+    engine: z
+        .object({
+        egressLease: z.string().min(1).max(16_384).optional(),
+    })
+        .strict()
+        .optional(),
 });
 export const AuthFlowErrorResponseSchema = OperationErrorResponseSchema;

package/dist/stealth/profiles.d.ts

@@ -1,4 +1,4 @@
-import type { StealthProfile, StealthProfileDescriptor, StealthProfileSelection } from "../types.js";
+import type { StealthBrowser, StealthProfile, StealthProfileDescriptor, StealthProfileSelection } from "../types.js";
 export declare const DEFAULT_STEALTH_BROWSER: "chrome";
 export declare const DEFAULT_STEALTH_OS: "macos";
 /** Internal detector used to keep version-pinned string failures actionable. */
@@ -6,4 +6,10 @@ export declare function getVersionPinnedStealthReplacement(name: string): string
 /** Resolve omitted axes and validate that the resulting pair is supported. */
 export declare function resolveStealthProfileSelection(selection: StealthProfileSelection | undefined, base?: StealthProfileDescriptor): StealthProfileDescriptor;
 export declare function getStealthProfile(selection?: StealthProfileSelection): StealthProfile;
+/**
+ * The transport owns the browser version (Chromium follows the pinned wreq-js build), so a
+ * resolver `clientProfile` such as `safari17_0` or `chrome_149` only has to name the same
+ * browser family as the stealth session it runs on.
+ */
+export declare function resolverClientProfileFamily(clientProfile: string): StealthBrowser | undefined;
 export declare function listStealthProfiles(): StealthProfileDescriptor[];

package/dist/stealth/profiles.js

@@ -194,6 +194,15 @@ export function getStealthProfile(selection = {}) {
         h2Settings: profile.h2Settings ? { ...profile.h2Settings } : undefined,
     };
 }
+/**
+ * The transport owns the browser version (Chromium follows the pinned wreq-js build), so a
+ * resolver `clientProfile` such as `safari17_0` or `chrome_149` only has to name the same
+ * browser family as the stealth session it runs on.
+ */
+export function resolverClientProfileFamily(clientProfile) {
+    const family = /^[a-z]+/u.exec(clientProfile.trim().toLowerCase())?.[0];
+    return family === "chrome" || family === "firefox" || family === "safari" ? family : undefined;
+}
 export function listStealthProfiles() {
     return SUPPORTED_STEALTH_PROFILES.map((profile) => ({ ...profile }));
 }

package/dist/testing/run.js

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { ProviderError } from "../errors.js";
 import { createProviderCache } from "../runtime/cache.js";
 import { createTestProviderChoiceContext } from "../runtime/choice.js";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
@@ -274,6 +275,11 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
     };
     const createStealthSession = () => ({
         fetch: stealthCall,
+        async replayChallenged() {
+            throw new ProviderError("Recorded transports cannot replay an engine-owned challenge", {
+                code: "REPLAY_SESSION_MISMATCH",
+            });
+        },
         cookies: {
             ...emptyCookieJar,
             has: () => false,

package/dist/trace-sanitization.d.ts

@@ -1,5 +1,6 @@
+import { type DiagnosticRedactor } from "./runtime/diagnostic-redactor.js";
 import type { TraceSpan } from "./types.js";
 /** Span names are SDK-authored identifiers; retain them while preventing log injection. */
-export declare function sanitizeSpanNameForOutput(value: string): string;
-export declare function sanitizeTraceAttributes(attributes: Record<string, unknown>): Record<string, string | number | boolean>;
-export declare function sanitizeSpanForOutput(span: TraceSpan, additionalAttributes?: Record<string, string>): TraceSpan;
+export declare function sanitizeSpanNameForOutput(value: string, redact?: DiagnosticRedactor): string;
+export declare function sanitizeTraceAttributes(attributes: Record<string, unknown>, redact?: DiagnosticRedactor, reservedKeys?: Iterable<string>): Record<string, string | number | boolean>;
+export declare function sanitizeSpanForOutput(span: TraceSpan, additionalAttributes?: Record<string, string>, redact?: DiagnosticRedactor): TraceSpan;

package/dist/trace-sanitization.js

@@ -1,45 +1,68 @@
 import { encodeDiagnosticControls, isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE, sanitizeDiagnosticText, } from "./fixture-sanitization.js";
+import { diagnosticStructuredRedactor, redactDiagnosticAttributeKey, copyDiagnosticAttributeTypes, isDiagnosticBigintAttribute, redactedKeyAllocator, isRedactedKey, redactCriticalDiagnosticText, diagnosticAttributeRedactor, REDACTION_FAILED, redactDiagnosticText, } from "./runtime/diagnostic-redactor.js";
 const MAX_TRACE_TEXT_LENGTH = 300;
-function sanitizeTraceText(value) {
-    const encoded = sanitizeDiagnosticText(value);
+function sanitizeTraceText(value, redact) {
+    const encoded = sanitizeDiagnosticText(redactDiagnosticText(value, redact));
     return encoded.length > MAX_TRACE_TEXT_LENGTH
         ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
         : encoded;
 }
 /** Span names are SDK-authored identifiers; retain them while preventing log injection. */
-export function sanitizeSpanNameForOutput(value) {
-    const encoded = encodeDiagnosticControls(value);
+export function sanitizeSpanNameForOutput(value, redact) {
+    const encoded = encodeDiagnosticControls(redactDiagnosticText(value, redact));
     return encoded.length > MAX_TRACE_TEXT_LENGTH
         ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
         : encoded;
 }
-export function sanitizeTraceAttributes(attributes) {
-    return Object.fromEntries(Object.entries(attributes).map(([key, value]) => [
-        sanitizeTraceText(key),
-        isSensitiveFixtureKey(key)
-            ? REDACTED_FIXTURE_VALUE
-            : typeof value === "string"
-                ? sanitizeTraceText(value)
-                : typeof value === "number" || typeof value === "boolean"
-                    ? value
-                    : sanitizeTraceText(String(value)),
-    ]));
+export function sanitizeTraceAttributes(attributes, redact, reservedKeys = []) {
+    const nextKey = redactedKeyAllocator([...Object.keys(attributes), ...reservedKeys]);
+    return copyDiagnosticAttributeTypes(attributes, Object.fromEntries(Object.entries(attributes).map(([key, value]) => {
+        const redactedKey = isRedactedKey(key) ? key : redactDiagnosticAttributeKey(key, redact);
+        const keyChanged = redactedKey !== key;
+        const sanitizedKey = keyChanged ? nextKey() : sanitizeTraceText(key);
+        const valueRedactor = typeof value === "bigint" || isDiagnosticBigintAttribute(attributes, key)
+            ? diagnosticStructuredRedactor(redact)
+            : diagnosticAttributeRedactor(key, redact);
+        const sanitizedValue = keyChanged
+            ? redactedKey === REDACTION_FAILED
+                ? REDACTION_FAILED
+                : REDACTED_FIXTURE_VALUE
+            : isSensitiveFixtureKey(key)
+                ? REDACTED_FIXTURE_VALUE
+                : typeof value === "bigint" || isDiagnosticBigintAttribute(attributes, key)
+                    ? String(value).length < 8
+                        ? String(value)
+                        : sanitizeTraceText(String(value), valueRedactor)
+                    : typeof value === "string"
+                        ? sanitizeTraceText(value, valueRedactor)
+                        : typeof value === "number" || typeof value === "boolean"
+                            ? (() => {
+                                if (String(value).length < 8)
+                                    return value;
+                                const redacted = redactDiagnosticText(String(value), diagnosticStructuredRedactor(valueRedactor));
+                                return redacted === String(value) ? value : sanitizeTraceText(redacted);
+                            })()
+                            : sanitizeTraceText(String(value), valueRedactor);
+        return [sanitizedKey, sanitizedValue];
+    })));
 }
-export function sanitizeSpanForOutput(span, additionalAttributes) {
+export function sanitizeSpanForOutput(span, additionalAttributes, redact) {
     // Keep this schema explicit so future fields are not silently added to a
     // process output path before their trust boundary has been reviewed.
     return {
-        id: span.id,
-        name: sanitizeSpanNameForOutput(span.name),
+        id: redactCriticalDiagnosticText(span.id, redact),
+        name: sanitizeSpanNameForOutput(redactCriticalDiagnosticText(span.name, redact)),
         startedAt: span.startedAt,
         endedAt: span.endedAt,
         duration_ms: span.duration_ms,
         status: span.status,
-        attributes: sanitizeTraceAttributes({
+        attributes: sanitizeTraceAttributes(copyDiagnosticAttributeTypes(span.attributes, {
             ...span.attributes,
             ...(additionalAttributes ?? {}),
-        }),
-        ...(span.error !== undefined ? { error: sanitizeTraceText(span.error) } : {}),
-        ...(span.parentId !== undefined ? { parentId: span.parentId } : {}),
+        }), redact),
+        ...(span.error !== undefined ? { error: sanitizeTraceText(span.error, redact) } : {}),
+        ...(span.parentId !== undefined
+            ? { parentId: redactCriticalDiagnosticText(span.parentId, redact) }
+            : {}),
     };
 }

package/dist/types.d.ts

@@ -219,7 +219,7 @@ export interface ProviderSttConfig {
  *
  * `ProviderResolverConfig.vendors` overrides the SDK policy when declared.
  */
-export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "custom";
+export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "hypersolutions" | "custom";
 /**
  * Token-family kinds resolve to `{ form: "token" }`. Cookie-family kinds resolve
  * to `{ form: "cookies" }`; network-identity binding is defined per kind. `aws_waf`
@@ -275,6 +275,22 @@ export type ProviderChallenge = {
     readonly bmsz?: string;
     /** Bot Manager major version when known ("3" measured on zozo.jp). */
     readonly version?: string;
+} | {
+    readonly kind: "akamai_sbsd";
+    readonly pageUrl: string;
+    /**
+     * Discovered SBSD script URL. `?v=&t=` is a hard challenge and `?v=`
+     * is passive or a remembered script. A later challenge token never
+     * changes this URL.
+     */
+    readonly scriptUrl: string;
+    readonly stateCookieName: "sbsd_o" | "bm_so";
+    /**
+     * Token returned by a later `cpr_chlge` response. When present with a
+     * remembered v-only script, it selects index 0 and is appended only to
+     * the payload POST URL.
+     */
+    readonly challengeToken?: string;
 };
 export type ProviderChallengeKind = ProviderChallenge["kind"];
 /**
@@ -282,7 +298,9 @@ export type ProviderChallengeKind = ProviderChallenge["kind"];
  * per challenge kind: `aws_waf` was measured portable across residential leases
  * on buyee, while `cf_clearance` is unmeasured here and treated as scoped to the
  * identity that produced it. The provider attaches the returned cookies to its
- * own requests.
+ * own requests. `cookie_state` solutions carry no values: SBSD state lives only
+ * in the engine-owned bound jar, and a 2xx payload POST is not proof of a solve;
+ * only the next protected GET can verify it (the safe refetch is Phase 2).
  */
 export type ChallengeSolution = {
     readonly form: "token";
@@ -298,8 +316,28 @@ export type ChallengeSolution = {
      * the upstream cookie's expiry. `expires` takes precedence when both are present.
      */
     readonly sdkEstimatedExpires?: number;
+} | {
+    readonly form: "cookie_state";
+    readonly kind: "akamai_sbsd";
+    readonly outcome: "payload_accepted";
+    /** Always false until a later protected GET verifies the bound jar (Phase 2). */
+    readonly verified: false;
+    /** Name only; the identity-bound cookie value remains in the engine-owned jar. */
+    readonly stateCookieName: "sbsd_o" | "bm_so";
+    /** Epoch seconds observed on the updated state cookie, when supplied upstream. */
+    readonly expires?: number;
 };
-export interface ProviderResolverConfig {
+/**
+ * `akamai_sbsd` declarations require a transport-owned client profile because the
+ * solve runs on the provider's admitted session. Other kinds may omit it.
+ */
+export type ProviderResolverConfig = {
+    /** Optional ordered override for the SDK-owned vendor fallback chain. */
+    readonly vendors?: readonly ProviderResolverVendor[];
+    /** Challenge kinds this provider is permitted to request. */
+    readonly kinds: readonly Exclude<ProviderChallengeKind, "akamai_sbsd">[];
+    readonly clientProfile?: string;
+} | {
     /** Optional ordered override for the SDK-owned vendor fallback chain. */
     readonly vendors?: readonly ProviderResolverVendor[];
     /** Challenge kinds this provider is permitted to request. */
@@ -310,8 +348,8 @@ export interface ProviderResolverConfig {
      * challenge is served, while a Safari profile is admitted. Provider-declared
      * because only the provider knows its upstream's admission rule.
      */
-    readonly clientProfile?: string;
-}
+    readonly clientProfile: string;
+};
 export type SttAudioInput = {
     kind: "base64";
     data: string;
@@ -774,6 +812,13 @@ export type StealthProfileSelection = {
     browser: "safari";
     os?: "macos" | "ios";
 };
+/** Provider-owned opt-ins layered onto the transport-owned browser/OS profile. */
+export type ProviderStealthConfig = StealthProfileSelection & {
+    readonly challengeDetection?: {
+        /** Classify SBSD responses even when no resolver is declared (detect/report mode). */
+        readonly akamaiSbsd?: boolean;
+    };
+};
 export type BrowserEngine = "playwright-stealth" | "nodriver" | "selenium-uc";
 export interface BrowserOptions {
     headless?: boolean;
@@ -1027,9 +1072,25 @@ export interface HttpRedirectPolicy {
 export type HttpRedirectFailureReason = Exclude<RedirectRunReason, "completed">;
 export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
 export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy" | "headers"> {
+    /**
+     * Defaults to true. Set to false when callers need to inspect upstream
+     * non-2xx bodies themselves instead of converting them to TransportError.
+     *
+     * Documented exception: a non-2xx response that an opted-in SDK challenge
+     * detector classified (`response.challenge` is set) is returned, not thrown,
+     * whatever this flag says, so the classification stays observable. Callers
+     * that need the failure semantics check `response.challenge` first.
+     */
+    throwOnHttpError?: boolean;
     /**
      * Request headers. Array values and case-insensitive duplicate names are
      * combined in caller order using `", "`, matching Chrome's Fetch behavior.
+     *
+     * The stealth transport owns `host`, `connection`, `user-agent`, `sec-ch-ua`,
+     * `sec-ch-ua-mobile`, `sec-ch-ua-platform`, `accept-encoding`, and every
+     * `sec-fetch-*` header. Supplying any of them throws
+     * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` at request time; declare the request
+     * shape with `stealth.requestClass` instead.
      */
     headers?: Record<string, string | string[]>;
     method?: HttpMethod;
@@ -1049,13 +1110,26 @@ export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolic
      */
     proxyAttemptOffset?: number;
     /**
-     * SDK-specific stealth controls. Standard HTTP metadata such as language,
-     * referrer, and content type belongs in `headers`.
+     * SDK-specific stealth controls, including a per-request browser and/or OS
+     * override. Standard HTTP metadata such as language, referrer, and content
+     * type belongs in `headers`.
      */
     stealth?: StealthProfileSelection & {
-        /** Override the configured browser and/or OS for this request. */
-        /** Declare the Chrome request class when it cannot be inferred from the method. */
+        /**
+         * Declare the Chrome request class when it cannot be inferred from the
+         * method (`POST` infers `post`, everything else `navigation`). This is the
+         * replacement for hand-set `Sec-Fetch-*` headers, which the transport
+         * rejects; it drives `Sec-Fetch-Mode`/`Dest`/`User`, `Accept`, `Priority`,
+         * and `Upgrade-Insecure-Requests`.
+         */
         requestClass?: "navigation" | "xhr" | "post";
+        /**
+         * Whether a `navigation` request carries a user gesture and therefore
+         * `Sec-Fetch-User: ?1` (default `true`). Set `false` for script-driven
+         * navigations such as `location.replace`, which Chrome sends without it.
+         * Ignored for the `xhr` and `post` request classes.
+         */
+        userActivation?: boolean;
         /**
          * Use only for proxy products that terminate CONNECT with a private CA
          * instead of tunneling the origin certificate chain.
@@ -1110,6 +1184,8 @@ export interface DeclarativeStealthResponse {
     headers: Record<string, string>;
     rawHeaders: [string, string][];
     body: string;
+    /** Present only when an opted-in SDK detector returned an unresolved challenge response. */
+    challenge?: StealthChallengeClassification;
     httpVersion?: string;
     tlsInfo?: {
         protocol?: string;
@@ -1122,6 +1198,20 @@ export interface DeclarativeStealthResponse {
     bytes(): Promise<Uint8Array>;
 }
 export type StealthResponse = DeclarativeStealthResponse;
+/** Why a detected challenge response was returned to the caller instead of being solved and refetched. */
+export type StealthChallengeClassification = {
+    readonly challenge: Extract<ProviderChallenge, {
+        readonly kind: "akamai_sbsd";
+    }>;
+    /**
+     * `resolver_unavailable`: detect-only provider or no solver configured.
+     * `replay_required`: the request is not a plain GET, so it is never solved or replayed
+     * automatically. `solve_failed`: a concurrent request on the same session owned the
+     * solve and it rejected (that owner receives the error). `challenge_persisted`: the
+     * single refetch after a solve was challenged again.
+     */
+    readonly outcome: "resolver_unavailable" | "replay_required" | "solve_failed" | "challenge_persisted";
+};
 export type RequestWithMethodOptions = RequestOptions & {
     method?: string;
     body?: unknown;
@@ -1152,6 +1242,12 @@ export interface StealthRedirectRunResult {
 }
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+    /**
+     * Explicitly solve and replay one unsafe request previously classified as
+     * `replay_required`. The original method, URL, headers, and body bytes are
+     * retained by this session and may be replayed exactly once.
+     */
+    replayChallenged(response: StealthResponse): Promise<StealthResponse>;
     cookies: StealthSessionCookies;
     redirects: {
         run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
@@ -2054,7 +2150,7 @@ export interface ProviderDefinition<TContext = ProviderContext> {
     http?: Record<string, never> | true;
     allowedHosts?: string[];
     native?: NativeProviderConfig;
-    stealth?: StealthProfileSelection;
+    stealth?: ProviderStealthConfig;
     proxy?: ProviderProxyConfig;
     ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.58",
+	"version": "2.2.0-beta.60",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -110,6 +110,7 @@
 		"format": "biome format --write",
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
+		"bench:redaction": "bun scripts/benchmark-request-redaction.ts",
 		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
 		"api:update": "bun run build && bun scripts/api-reports.ts update",
 		"api:check": "bun run build && bun scripts/api-reports.ts check",

package/src/cli/templates/provider/README.md.tpl

@@ -97,9 +97,21 @@ The `POST /v1/{operation}` body is a request envelope:
 - `requestId` is required and can be any unique local debugging string.
 - `input` contains the operation input shape.
 - `headers` is optional.
-- `connection` is optional; omit it for no-auth/public operations. For
-  credential debugging, pass `{ "id", "mode", "secrets", "metadata",
-  "externalRef" }` with local-only secret values.
+- `connectionId` is optional connection identity only and does not include
+  credentials. The gateway sends it for `optional` connection mode, and only
+  when the caller supplied a connection that passed authorization. It is
+  exposed as `ctx.request.connectionId`.
+- `connection` is optional credential-bearing connection data. The gateway
+  sends it for `required` connection mode; omit it for no-auth/public (`none`
+  mode) operations. For local debugging, pass
+  `{ "id", "mode", "secrets", "metadata", "externalRef" }` with local-only
+  secret values.
+
+The gateway sends only `connection` for `required` mode, only `connectionId`
+for `optional` mode (and nothing when the caller passed no connection), and
+neither field for `none` mode. If a malformed or manually constructed envelope
+contains both, a non-empty nested `connection.id` takes precedence over the
+top-level `connectionId`; an empty string is treated as absent.
 
 Structured errors return an `error` object with `code`, `message`,
 `requestId`, and optional `details`; validation failures include field paths in