@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/runtime/stealth-akamai-sbsd.ts

@@ -0,0 +1,207 @@
+import type { ChallengeSolution, ProviderChallenge, StealthResponse } from "../types.js";
+import { normalizedResolverHostname } from "./resolver-vendors/hosts.js";
+import type { ResolverVendorTransport } from "./resolver-vendors/types.js";
+import type { StealthCookieJar } from "./stealth-cookies.js";
+
+export type AkamaiSbsdChallenge = Extract<ProviderChallenge, { readonly kind: "akamai_sbsd" }>;
+
+/**
+ * SDK-owned response detection and solve wiring derived from the provider declaration.
+ * The server attaches it to the stealth client options it builds; it is deliberately not
+ * part of the public `StealthClientOptions` type.
+ */
+export type StealthChallengeRuntime = {
+	readonly akamaiSbsd?: {
+		readonly allowedHosts: readonly string[];
+		/** Resolver-declared client profile; must name the initiating session's browser family. */
+		readonly clientProfile?: string;
+		readonly solve?: (
+			challenge: AkamaiSbsdChallenge,
+			transport: ResolverVendorTransport,
+			signal: AbortSignal,
+		) => Promise<ChallengeSolution>;
+	};
+};
+
+export type AkamaiSbsdSessionState = {
+	/**
+	 * Latest v-only script for this session; Phase 2 deliberately has no wall-clock TTL.
+	 * Challenge-state expiry belongs to the Phase 3 ceremony/solve lease handle
+	 * (ADR-0010 v1.1), not to the stealth session.
+	 */
+	rememberedScript?: URL;
+	/** In-flight solves keyed by akamaiSbsdChallengeKey; an entry leaves only when it settles. */
+	readonly transactions: Map<
+		string,
+		{
+			readonly result: Promise<
+				{ readonly solved: true } | { readonly solved: false; error: unknown }
+			>;
+		}
+	>;
+	/**
+	 * Key of the last automatic (safe-method) solve whose refetch was not challenged again.
+	 * An explicit replay for the same key reuses the solved cookies once instead of solving
+	 * again; any newer solve or lease expiry clears it.
+	 */
+	completedSuccessKey?: string;
+};
+
+/**
+ * Live SBSD `<script src>` paths are per-site obfuscated (zozo.jp captures, 2026-08-28:
+ * `/EdTyEb8Lyxqf/9iGcpl/GmKux0/DXObrkm53w/B1p4AQ/ZCF5f/VoJN08X?v=<uuid>` on the
+ * `Access Denied` shape, `/SHO9K/...?v=<uuid>&t=<token>` on the behavioral-tile hard shape).
+ * `/.well-known/sbsd` is only the POST endpoint string inside the deobfuscated
+ * script, never the page's script path. The stable shape is a same-origin script whose `v`
+ * is a UUID; cache-busted bundles (`?v=abc123`, hashes, semver) never match it.
+ */
+const SBSD_SCRIPT_VERSION = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu;
+const SBSD_INTERSTITIAL_MAX_BYTES = 4_000;
+const SBSD_SCRIPT_DISCOVERY_MAX_BYTES = 4 * 1_024 * 1_024;
+const SBSD_CHALLENGE_TOKEN_MAX_BYTES = 1_024;
+const SBSD_INTERSTITIAL_MARKER =
+	/sec-bc-tile-container|Access Denied|Reference #\d|Pardon Our Interruption|cpr_chlge/iu;
+
+function htmlAttribute(value: string): string {
+	return value.replace(/&amp;/giu, "&");
+}
+
+function isDeclaredHost(url: URL, allowedHosts: readonly string[]): boolean {
+	const hostname = normalizedResolverHostname(url.hostname);
+	return allowedHosts.some((host) => normalizedResolverHostname(host) === hostname);
+}
+
+export function findAkamaiSbsdScript(body: string, page: URL): URL | undefined {
+	// Only markup carries the script tag; JSON and binary bodies skip the scan entirely.
+	if (!/^\s*</u.test(body) || Buffer.byteLength(body) > SBSD_SCRIPT_DISCOVERY_MAX_BYTES) {
+		return undefined;
+	}
+	let passiveScript: URL | undefined;
+	for (const match of body.matchAll(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["'][^>]*>/giu)) {
+		let script: URL;
+		try {
+			// Relative sources resolve against the page URL, as the browser would.
+			script = new URL(htmlAttribute(match[1]!), page);
+		} catch {
+			continue;
+		}
+		const version = script.searchParams.get("v")?.trim();
+		if (script.origin !== page.origin || !version || !SBSD_SCRIPT_VERSION.test(version)) {
+			continue;
+		}
+		if (script.searchParams.get("t")?.trim()) return script;
+		passiveScript ??= script;
+	}
+	return passiveScript;
+}
+
+function isAkamaiSbsdInterstitial(body: string): boolean {
+	return (
+		Buffer.byteLength(body) < SBSD_INTERSTITIAL_MAX_BYTES && SBSD_INTERSTITIAL_MARKER.test(body)
+	);
+}
+
+function parseAkamaiSbsdChallengeToken(body: string): string | undefined {
+	if (Buffer.byteLength(body) >= SBSD_INTERSTITIAL_MAX_BYTES) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return undefined;
+	}
+	if (
+		!parsed ||
+		typeof parsed !== "object" ||
+		Array.isArray(parsed) ||
+		!("cpr_chlge" in parsed) ||
+		parsed.cpr_chlge !== "true" ||
+		!("t" in parsed) ||
+		typeof parsed.t !== "string"
+	) {
+		return undefined;
+	}
+	const token = parsed.t.trim();
+	return token && Buffer.byteLength(token) <= SBSD_CHALLENGE_TOKEN_MAX_BYTES ? token : undefined;
+}
+
+export function detectAkamaiSbsdChallenge(
+	response: Pick<StealthResponse, "url" | "body">,
+	pageUrl: string,
+	jar: Pick<StealthCookieJar, "has">,
+	allowedHosts: readonly string[],
+	state: AkamaiSbsdSessionState,
+): AkamaiSbsdChallenge | undefined {
+	let page: URL;
+	try {
+		page = new URL(response.url ?? pageUrl);
+	} catch {
+		return undefined;
+	}
+	if (!isDeclaredHost(page, allowedHosts)) return undefined;
+	const stateCookieName = jar.has("sbsd_o", page.toString())
+		? "sbsd_o"
+		: jar.has("bm_so", page.toString())
+			? "bm_so"
+			: undefined;
+	const interstitial = isAkamaiSbsdInterstitial(response.body);
+	// Without the state cookie (the jar already holds the Set-Cookie of this very response;
+	// the live capture sets bm_so on the page that carries the script) or an interstitial,
+	// nothing here is Akamai's: do not scan, and do not let an unrelated UUID-versioned
+	// bundle become the remembered script.
+	if (!stateCookieName && !interstitial) return undefined;
+	const currentScript = findAkamaiSbsdScript(response.body, page);
+	if (currentScript) {
+		const version = currentScript.searchParams.get("v")?.trim();
+		if (version) {
+			// Clone rather than re-parse the pathname: a `//x` path would re-parse as a host.
+			const rememberedScript = new URL(currentScript);
+			rememberedScript.search = "";
+			rememberedScript.hash = "";
+			rememberedScript.searchParams.set("v", version);
+			state.rememberedScript = rememberedScript;
+		}
+	}
+	if (!stateCookieName) return undefined;
+
+	const laterToken = parseAkamaiSbsdChallengeToken(response.body);
+	const rememberedScript = state.rememberedScript;
+	if (laterToken && rememberedScript && rememberedScript.origin === page.origin) {
+		return {
+			kind: "akamai_sbsd",
+			pageUrl: page.toString(),
+			scriptUrl: rememberedScript.toString(),
+			stateCookieName,
+			challengeToken: laterToken,
+		};
+	}
+	if (!currentScript || !interstitial) return undefined;
+	return {
+		kind: "akamai_sbsd",
+		pageUrl: page.toString(),
+		scriptUrl: currentScript.toString(),
+		stateCookieName,
+	};
+}
+
+/**
+ * One in-flight solve per session, challenge, and bound identity: requests on one session
+ * may still pick a different wreq browser/OS or proxy, and a solve is only valid for the
+ * identity that ran it.
+ */
+export function akamaiSbsdChallengeKey(
+	challenge: AkamaiSbsdChallenge,
+	identity: {
+		readonly wreqBrowser: string;
+		readonly wreqOs: string;
+		readonly proxyUrl: string | undefined;
+	},
+): string {
+	return JSON.stringify([
+		new URL(challenge.scriptUrl).toString(),
+		challenge.challengeToken ?? "",
+		challenge.stateCookieName,
+		identity.wreqBrowser,
+		identity.wreqOs,
+		identity.proxyUrl ?? "",
+	]);
+}

package/src/runtime/stealth-cookies.ts

@@ -0,0 +1,155 @@
+import { Cookie, CookieJar as ToughCookieJar } from "tough-cookie";
+
+import { SDKError, StealthCookieStoreVersionError } from "../errors.js";
+import type {
+	CookieJar,
+	StealthCookieStore,
+	StealthCookieStoreV1,
+	StealthSessionCookies,
+} from "../types.js";
+
+function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+const LEGACY_COOKIE_ORIGIN = "https://legacy-cookie.invalid/";
+
+/** Extract cookie values from Set-Cookie/header strings for request-scoped registration. */
+export function cookieValuesFromHeaders(headers: string | readonly string[]): string[] {
+	const values: string[] = [];
+	for (const header of typeof headers === "string" ? [headers] : headers) {
+		const cookie = Cookie.parse(header);
+		if (cookie?.value) values.push(cookie.value);
+	}
+	return values;
+}
+
+export class StealthCookieJar implements CookieJar, StealthSessionCookies {
+	private cookies: ToughCookieJar;
+	private readonly defaultUrl: string;
+	private readonly register: ((value: string) => void) | undefined;
+
+	constructor(
+		cookieStrings: readonly string[],
+		defaultUrl = LEGACY_COOKIE_ORIGIN,
+		register?: (value: string) => void,
+	) {
+		this.cookies = new ToughCookieJar(undefined, {
+			allowSecureOnLocal: false,
+			rejectPublicSuffixes: true,
+		});
+		this.defaultUrl = this.normalizeUrl(defaultUrl) ?? LEGACY_COOKIE_ORIGIN;
+		this.register = register;
+		this.setFromCookieStrings(cookieStrings);
+	}
+
+	setFromCookieStrings(cookieStrings: readonly string[], url = this.defaultUrl): void {
+		const cookieUrl = this.normalizeUrl(url);
+		if (!cookieUrl) return;
+		for (const cookieString of cookieStrings) {
+			for (const value of cookieValuesFromHeaders(cookieString)) this.register?.(value);
+			this.cookies.setCookieSync(cookieString, cookieUrl, { ignoreError: true });
+		}
+	}
+
+	get(name: string, url?: string): string | undefined {
+		return this.getAll(url)[name];
+	}
+
+	getAll(url?: string): Record<string, string> {
+		return Object.fromEntries(
+			this.getUniqueCookies(url ?? this.defaultUrl).map((cookie) => [cookie.key, cookie.value]),
+		);
+	}
+
+	has(name: string, url?: string): boolean {
+		return Object.hasOwn(this.getAll(url), name);
+	}
+
+	toString(url?: string): string {
+		return this.getUniqueCookies(url ?? this.defaultUrl)
+			.map((cookie) => cookie.cookieString())
+			.join("; ");
+	}
+
+	toHeader(url?: string): string {
+		return this.toString(url);
+	}
+
+	snapshot(): Record<string, string> {
+		const entries: [string, string][] = [];
+		for (const cookie of this.serialize().jar.cookies) {
+			if (typeof cookie.key === "string" && typeof cookie.value === "string" && cookie.key) {
+				entries.push([cookie.key, cookie.value]);
+			}
+		}
+		return Object.fromEntries(entries);
+	}
+
+	restore(cookies: Record<string, string>): void {
+		this.clear();
+		for (const [name, value] of Object.entries(cookies)) {
+			if (!name) continue;
+			this.register?.(value);
+			this.cookies.setCookieSync(new Cookie({ key: name, path: "/", value }), this.defaultUrl, {
+				ignoreError: true,
+			});
+		}
+	}
+
+	serialize(): StealthCookieStoreV1 {
+		const jar = this.cookies.serializeSync();
+		if (!jar) {
+			throw new SDKError("Stealth cookie store could not be serialized", {
+				code: "stealth_cookie_store_serialize_failed",
+			});
+		}
+		return { version: 1, jar };
+	}
+
+	deserialize(state: StealthCookieStore): void {
+		const version = isRecord(state) ? state.version : undefined;
+		if (version !== 1) {
+			throw new StealthCookieStoreVersionError(version);
+		}
+		const restored = ToughCookieJar.deserializeSync(state.jar);
+		Reflect.set(restored, "allowSecureOnLocal", false);
+		this.cookies = restored;
+	}
+
+	clear(): void {
+		this.cookies.removeAllCookiesSync();
+	}
+
+	find(predicate: (cookie: string) => boolean, url?: string): string | undefined {
+		for (const cookie of this.getUniqueCookies(url ?? this.defaultUrl)) {
+			const cookieString = cookie.cookieString();
+			if (predicate(cookieString)) return cookieString;
+		}
+		return undefined;
+	}
+
+	names(url?: string): string[] {
+		return this.getUniqueCookies(url ?? this.defaultUrl).map((cookie) => cookie.key);
+	}
+
+	private normalizeUrl(url: string): string | undefined {
+		try {
+			return new URL(url).toString();
+		} catch {
+			return undefined;
+		}
+	}
+
+	private getUniqueCookies(url: string): Cookie[] {
+		const cookieUrl = this.normalizeUrl(url);
+		if (!cookieUrl) return [];
+		const names = new Set<string>();
+		return this.cookies.getCookiesSync(cookieUrl).filter((cookie) => {
+			if (cookie.value) this.register?.(cookie.value);
+			if (names.has(cookie.key)) return false;
+			names.add(cookie.key);
+			return true;
+		});
+	}
+}

package/src/runtime/stealth-owned-headers.ts

@@ -0,0 +1,67 @@
+import { SDKError } from "../errors.js";
+
+/**
+ * Header names the stealth transport owns.
+ *
+ * `ctx.stealth` composes these from the Chrome emulation and the request class,
+ * so a caller value is rejected at request time with `SDKError` code
+ * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` ({@link assertCallerHeadersSupported}).
+ * The offline test harness (`runStandardTests`) calls the same function on
+ * every `ctx.stealth` request it serves, so a provider test fails exactly where
+ * production would, whichever file or variable the header came from. That is
+ * the cross-file enforcement.
+ *
+ * The `browser-version-literal` lint reports a subset of these names — the
+ * `sec-fetch-*` and `sec-ch-ua*` families — in files that use `ctx.stealth`
+ * (`isReportedOwnedHeaderName` in lint.ts). Both read this module, so the lint
+ * cannot claim a rejection the runtime does not perform; it reports
+ * deliberately less than the runtime rejects (host, connection,
+ * accept-encoding and a non-literal user-agent stay silent — see that
+ * predicate for why), so a green `apifuse check` is not proof that no owned
+ * header is set.
+ *
+ * Kept off the stealth runtime: the only import is `errors.js`, whose own
+ * imports are type-only, so the lazily loaded CLI lint path does not pull the
+ * stealth runtime in.
+ */
+export const SDK_OWNED_EXACT_CHROME_HEADERS: ReadonlySet<string> = new Set([
+	"host",
+	"connection",
+	"user-agent",
+	"sec-ch-ua",
+	"sec-ch-ua-mobile",
+	"sec-ch-ua-platform",
+	"accept-encoding",
+]);
+
+export const SDK_OWNED_CHROME_HEADER_PREFIX = "sec-fetch-";
+
+/**
+ * True when `ctx.stealth` rejects a caller value for `name` (case-insensitive):
+ * an exact member of {@link SDK_OWNED_EXACT_CHROME_HEADERS} or any
+ * `sec-fetch-*` name.
+ */
+export function isStealthOwnedHeaderName(name: string): boolean {
+	const lower = name.toLowerCase();
+	return (
+		SDK_OWNED_EXACT_CHROME_HEADERS.has(lower) || lower.startsWith(SDK_OWNED_CHROME_HEADER_PREFIX)
+	);
+}
+
+/**
+ * Throws `SDKError` `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` for the first caller
+ * header `ctx.stealth` owns. An `undefined` value is skipped, as the transport
+ * drops it before sending. The stealth runtime and the offline test harness
+ * both call this, so the two cannot disagree about what is rejected.
+ */
+export function assertCallerHeadersSupported(
+	headers: Readonly<Record<string, string | readonly string[] | undefined>>,
+): void {
+	for (const [name, value] of Object.entries(headers)) {
+		if (value === undefined || !isStealthOwnedHeaderName(name)) continue;
+		throw new SDKError(
+			`Stealth transport owns the "${name.toLowerCase()}" header; remove it from headers.`,
+			{ code: "STEALTH_HEADER_OVERRIDE_UNSUPPORTED" },
+		);
+	}
+}