@apifuse/provider-sdk 2.2.0-beta.57 → 2.2.0-beta.59

package/src/server/types.ts

@@ -93,12 +93,26 @@ 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/src/stealth/profiles.ts

@@ -258,6 +258,16 @@ export function getStealthProfile(selection: StealthProfileSelection = {}): Stea
 	};
 }
 
+/**
+ * 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: string): StealthBrowser | undefined {
+	const family = /^[a-z]+/u.exec(clientProfile.trim().toLowerCase())?.[0];
+	return family === "chrome" || family === "firefox" || family === "safari" ? family : undefined;
+}
+
 export function listStealthProfiles(): StealthProfileDescriptor[] {
 	return SUPPORTED_STEALTH_PROFILES.map((profile) => ({ ...profile }));
 }

package/src/testing/run.ts

@@ -1,5 +1,6 @@
 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";
@@ -425,6 +426,11 @@ function createUpstreamContext(
 
 	const createStealthSession = (): ReturnType<ProviderContext["stealth"]["createSession"]> => ({
 		fetch: stealthCall,
+		async replayChallenged() {
+			throw new ProviderError("Recorded transports cannot replay an engine-owned challenge", {
+				code: "REPLAY_SESSION_MISMATCH",
+			});
+		},
 		cookies: {
 			...emptyCookieJar,
 			has: () => false,

package/src/types.ts

@@ -278,6 +278,7 @@ export type ProviderResolverVendor =
 	| "capsolver"
 	| "capmonster"
 	| "2captcha"
+	| "hypersolutions"
 	| "custom";
 
 /**
@@ -343,6 +344,23 @@ 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"];
@@ -352,7 +370,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"; readonly token: string }
@@ -367,21 +387,44 @@ 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 {
-	/** 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 ProviderChallengeKind[];
-	/**
-	 * Client fingerprint profile the SDK must use when reaching this upstream.
-	 * Measured on zozo.jp: Chrome/Firefox profiles are refused 403 before any
-	 * challenge is served, while a Safari profile is admitted. Provider-declared
-	 * because only the provider knows its upstream's admission rule.
-	 */
-	readonly clientProfile?: string;
-}
+/**
+ * `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. */
+			readonly kinds: readonly ProviderChallengeKind[];
+			/**
+			 * Client fingerprint profile the SDK must use when reaching this upstream.
+			 * Measured on zozo.jp: Chrome/Firefox profiles are refused 403 before any
+			 * challenge is served, while a Safari profile is admitted. Provider-declared
+			 * because only the provider knows its upstream's admission rule.
+			 */
+			readonly clientProfile: string;
+		};
 
 export type SttAudioInput = {
 	kind: "base64";
@@ -905,6 +948,14 @@ export type StealthProfileSelection =
 	| { browser: "firefox"; os?: "windows" | "macos" | "linux" }
 	| { 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;
@@ -1238,9 +1289,25 @@ export type HttpMethod =
 	| "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;
@@ -1260,13 +1327,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.
@@ -1326,6 +1406,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; cipher?: string; [key: string]: unknown };
 	cookies: CookieJar;
@@ -1336,6 +1418,23 @@ export interface DeclarativeStealthResponse {
 
 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;
@@ -1371,6 +1470,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>;
@@ -2266,8 +2371,9 @@ export interface ProviderRuntimeState {
 /**
  * The operation context exposed for one provider declaration. Capability
  * bindings are present only when their corresponding declaration is present;
- * trace and request remain ambient runtime bindings. Omitting the type
- * parameter preserves the legacy full context shape for existing annotations.
+ * platform-managed auth itself declares the credential binding. Trace and
+ * request remain ambient runtime bindings. Omitting the type parameter
+ * preserves the legacy full context shape for existing annotations.
  */
 export type ProviderContext<TConfig = Record<string, unknown>> = {
 	request?: ProviderRequestContext;
@@ -2276,7 +2382,9 @@ export type ProviderContext<TConfig = Record<string, unknown>> = {
 	& ("env" extends keyof TConfig ? { env: EnvContext } : Record<never, never>)
 	& ("credential" extends keyof TConfig
 		? { credential: CredentialContext }
-		: Record<never, never>)
+		: TConfig extends { auth: { mode: "platform-managed" } }
+			? { credential: CredentialContext }
+			: Record<never, never>)
 	& ("http" extends keyof TConfig ? { http: HttpClient } : Record<never, never>)
 	& ("files" extends keyof TConfig
 		? string extends keyof TConfig
@@ -2471,7 +2579,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;