@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.51

package/src/stealth/profiles.ts

@@ -1,57 +1,29 @@
+import { createRequire } from "node:module";
+
+import type { BrowserProfile, EmulationOS } from "wreq-js";
+
 import { SDKError } from "../errors.js";
-import type { StealthPlatform, StealthProfile } from "../types.js";
+import type {
+	StealthBrowser,
+	StealthProfile,
+	StealthProfileDescriptor,
+	StealthProfileSelection,
+	StealthOS,
+} from "../types.js";
 
-type StealthProfileDefinition = Omit<StealthProfile, "name" | "platform"> & {
-	platform: StealthPlatform;
-};
+type StealthProfileDefinition = Omit<StealthProfile, "browser" | "os">;
+type WreqProfileApi = Pick<typeof import("wreq-js"), "getEmulationHeaders" | "getProfiles">;
 
-const CHROMIUM_HEADER_ORDER = [
-	":method",
-	":authority",
-	":scheme",
-	":path",
-	"user-agent",
-	"accept",
-	"accept-encoding",
-	"accept-language",
-	"cache-control",
-	"pragma",
-	"cookie",
-	"sec-ch-ua",
-	"sec-ch-ua-mobile",
-	"sec-ch-ua-platform",
-];
+const requireModule = createRequire(import.meta.url);
+let wreqProfileApi: WreqProfileApi | undefined;
 
-const FIREFOX_HEADER_ORDER = [
-	":method",
-	":path",
-	":authority",
-	":scheme",
-	"user-agent",
-	"accept",
-	"accept-language",
-	"accept-encoding",
-	"referer",
-	"cookie",
-	"upgrade-insecure-requests",
-	"sec-fetch-dest",
-	"sec-fetch-mode",
-	"sec-fetch-site",
-	"sec-fetch-user",
-];
+function getWreqProfileApi(): WreqProfileApi {
+	wreqProfileApi ??= requireModule("wreq-js") as WreqProfileApi;
+	return wreqProfileApi;
+}
 
-const SAFARI_HEADER_ORDER = [
-	":method",
-	":scheme",
-	":path",
-	":authority",
-	"accept",
-	"user-agent",
-	"accept-language",
-	"accept-encoding",
-	"cookie",
-	"upgrade-insecure-requests",
-];
+export const DEFAULT_STEALTH_BROWSER = "chrome" as const;
+export const DEFAULT_STEALTH_OS = "macos" as const;
 
 const CHROMIUM_H2_SETTINGS = {
 	HEADER_TABLE_SIZE: 65536,
@@ -68,7 +40,7 @@ const FIREFOX_H2_SETTINGS = {
 };
 
 const SAFARI_H2_SETTINGS = {
-	HEADER_TABLE_SIZE: 4096,
+	// Safari 17 also sends a connection-level WINDOW_UPDATE increment of 10485760.
 	ENABLE_PUSH: 0,
 	INITIAL_WINDOW_SIZE: 4194304,
 	MAX_CONCURRENT_STREAMS: 100,
@@ -81,212 +53,211 @@ const FIREFOX_JA3 =
 const SAFARI_JA3 =
 	"771,4865-4866-4867-49196-49195-52393-49200-49199-49188-49192-159-158-107-103-57-51-157-156-61-60-53-47-255,0-23-65281-10-11-16-5-13-18-51-45-43-27,29-23-24-25,0";
 
-function createProfile(name: string, definition: StealthProfileDefinition): StealthProfile {
-	return {
-		name,
-		platform: definition.platform,
-		version: definition.version,
-		userAgent: definition.userAgent,
-		tlsClientIdentifier: definition.tlsClientIdentifier,
-		ja3: definition.ja3,
-		ja4: definition.ja4,
-		h2Settings: definition.h2Settings ? { ...definition.h2Settings } : undefined,
-		headerOrder: definition.headerOrder ? [...definition.headerOrder] : undefined,
-	};
+const SUPPORTED_STEALTH_PROFILES: readonly StealthProfileDescriptor[] = [
+	{ browser: "chrome", os: "windows" },
+	{ browser: "chrome", os: "macos" },
+	{ browser: "chrome", os: "linux" },
+	{ browser: "firefox", os: "windows" },
+	{ browser: "firefox", os: "macos" },
+	{ browser: "firefox", os: "linux" },
+	{ browser: "safari", os: "macos" },
+	{ browser: "safari", os: "ios" },
+];
+
+const DESKTOP_OSES = new Set<StealthOS>(["windows", "macos", "linux"]);
+
+function structuredReplacement(browser: StealthBrowser, os: StealthOS): string {
+	return `stealth: { browser: "${browser}", os: "${os}" }`;
 }
 
-function extractBrowserMajorVersion(profile: StealthProfile): string {
-	const chromeVersion = profile.userAgent.match(/Chrome\/(\d+)/)?.[1];
-	if (chromeVersion) {
-		return chromeVersion;
+/** Internal detector used to keep version-pinned string failures actionable. */
+export function getVersionPinnedStealthReplacement(name: string): string | undefined {
+	if (/^(?:chrome|chromium|edge)[-_]\d/i.test(name)) {
+		return structuredReplacement("chrome", DEFAULT_STEALTH_OS);
 	}
-
-	const identifierVersion = profile.tlsClientIdentifier?.match(/(\d+)(?!.*\d)/)?.[1];
-	if (identifierVersion) {
-		return identifierVersion;
+	if (/^firefox[-_]\d/i.test(name)) {
+		return structuredReplacement("firefox", DEFAULT_STEALTH_OS);
+	}
+	if (/^(?:ios[-_]safari|safari[-_](?:ios|ipad))[-_]\d/i.test(name)) {
+		return structuredReplacement("safari", "ios");
+	}
+	if (/^safari[-_]\d/i.test(name)) {
+		return structuredReplacement("safari", DEFAULT_STEALTH_OS);
 	}
+	return undefined;
+}
 
-	return profile.version.split(".")[0] ?? profile.version;
+function rejectStringSelection(name: string): never {
+	const replacement = getVersionPinnedStealthReplacement(name);
+	if (replacement) {
+		throw new SDKError(
+			`Stealth profile "${name}" pins a browser version and is not supported. Use ${replacement}.`,
+			{ code: "STEALTH_VERSION_PIN_UNSUPPORTED" },
+		);
+	}
+	throw new SDKError(
+		`Stealth profile names are no longer supported: "${name}". Use structured browser/os options.`,
+		{ code: "STEALTH_PROFILE_NAME_UNSUPPORTED" },
+	);
 }
 
-function toPlatformHeaderValue(platform: StealthPlatform): string {
-	switch (platform) {
-		case "macos":
-			return '"macOS"';
-		case "windows":
-			return '"Windows"';
-		case "linux":
-			return '"Linux"';
-		case "android":
-			return '"Android"';
-		case "ios":
-			return '"iOS"';
+function assertSupportedDescriptor(browser: StealthBrowser, os: StealthOS): void {
+	const supported =
+		(browser === "chrome" && DESKTOP_OSES.has(os)) ||
+		(browser === "firefox" && DESKTOP_OSES.has(os)) ||
+		(browser === "safari" && (os === "macos" || os === "ios"));
+	if (!supported) {
+		throw new SDKError(
+			`Unsupported stealth browser/OS combination: ${browser}/${os}. ` +
+				"Chrome and Firefox support windows, macos, and linux; Safari supports macos and ios.",
+			{ code: "STEALTH_PROFILE_UNAVAILABLE" },
+		);
 	}
 }
 
-export function generateLayer2Headers(profile: StealthProfile): Record<string, string> {
-	const headers: Record<string, string> = {
-		"Accept-Language": "ko-KR,ko;q=0.9,en-US;q=0.8",
-	};
+/** Resolve omitted axes and validate that the resulting pair is supported. */
+export function resolveStealthProfileSelection(
+	selection: StealthProfileSelection | undefined,
+	base?: StealthProfileDescriptor,
+): StealthProfileDescriptor {
+	if (typeof selection === "string") rejectStringSelection(selection);
+	if (selection !== undefined && (typeof selection !== "object" || selection === null)) {
+		throw new SDKError("Stealth profile selection must use structured browser/os options.");
+	}
+	const unsafeSelection = selection as
+		| (Record<string, unknown> & { browser?: unknown; os?: unknown })
+		| undefined;
+	if (unsafeSelection && "profile" in unsafeSelection) {
+		if (typeof unsafeSelection.profile === "string") rejectStringSelection(unsafeSelection.profile);
+		throw new SDKError(
+			"stealth.profile is no longer supported. Use stealth.browser and stealth.os.",
+			{ code: "STEALTH_PROFILE_NAME_UNSUPPORTED" },
+		);
+	}
 
-	const identifier = profile.tlsClientIdentifier?.toLowerCase() ?? "";
-	const majorVersion = extractBrowserMajorVersion(profile);
+	const browser = unsafeSelection?.browser ?? base?.browser ?? DEFAULT_STEALTH_BROWSER;
+	if (browser !== "chrome" && browser !== "firefox" && browser !== "safari") {
+		throw new SDKError(`Unsupported stealth browser: ${String(browser)}`);
+	}
+	const browserChanged =
+		base !== undefined && unsafeSelection?.browser !== undefined && browser !== base.browser;
+	const os =
+		unsafeSelection?.os ?? (browserChanged ? DEFAULT_STEALTH_OS : base?.os) ?? DEFAULT_STEALTH_OS;
+	if (os !== "windows" && os !== "macos" && os !== "linux" && os !== "ios") {
+		throw new SDKError(`Unsupported stealth OS: ${String(os)}`);
+	}
+	assertSupportedDescriptor(browser, os);
+	return { browser, os } as StealthProfileDescriptor;
+}
 
-	if (identifier.startsWith("chrome_") || identifier.startsWith("edge_")) {
-		const isEdge = identifier.startsWith("edge_") || /\bEdg\//.test(profile.userAgent);
-		headers["Sec-Ch-Ua"] = isEdge
-			? `"Chromium";v="${majorVersion}", "Microsoft Edge";v="${majorVersion}", "Not)A;Brand";v="99"`
-			: `"Chromium";v="${majorVersion}", "Google Chrome";v="${majorVersion}", "Not)A;Brand";v="99"`;
-		headers["Sec-Ch-Ua-Platform"] = toPlatformHeaderValue(profile.platform);
-		headers["Sec-Ch-Ua-Mobile"] =
-			profile.platform === "android" || profile.platform === "ios" ? "?1" : "?0";
+/** Resolve the newest Chromium build exposed by the exactly pinned wreq-js package. */
+function resolveLatestChromiumProfile(): {
+	readonly wreqName: BrowserProfile;
+	readonly version: string;
+} {
+	const { getProfiles } = getWreqProfileApi();
+	let newest: { name: BrowserProfile; version: number } | undefined;
+	for (const name of getProfiles()) {
+		const match = /^chrome_(\d+)$/.exec(name);
+		if (!match) continue;
+		const version = Number(match[1]);
+		if (!newest || version > newest.version) newest = { name, version };
 	}
+	if (!newest) {
+		throw new SDKError("wreq-js exposes no chrome_<version> emulation profile.", {
+			code: "STEALTH_PROFILE_UNAVAILABLE",
+		});
+	}
+	return { wreqName: newest.name, version: `${newest.version}.0.0.0` };
+}
 
-	return headers;
+/** Read the identity wreq itself emits so the accessor and transport cannot diverge. */
+function emulationUserAgent(profile: BrowserProfile, os: EmulationOS): string {
+	for (const [name, value] of getWreqProfileApi().getEmulationHeaders(profile, os)) {
+		if (String(name).toLowerCase() === "user-agent") return String(value);
+	}
+	throw new SDKError(`wreq-js profile ${profile} exposes no user-agent header.`, {
+		code: "STEALTH_PROFILE_UNAVAILABLE",
+	});
 }
 
-const STEALTH_PROFILE_ALIASES: Record<string, string> = {
-	"chrome-desktop": "chrome-146",
-};
+function createProfile(
+	descriptor: StealthProfileDescriptor,
+	definition: StealthProfileDefinition,
+): StealthProfile {
+	return {
+		...descriptor,
+		...definition,
+		h2Settings: definition.h2Settings ? { ...definition.h2Settings } : undefined,
+	};
+}
 
-const STEALTH_PROFILES: Record<string, StealthProfile> = {
-	"chrome-146": createProfile("chrome-146", {
-		platform: "macos",
-		version: "146.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_146",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"firefox-147": createProfile("firefox-147", {
-		platform: "macos",
-		version: "147.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:147.0) Gecko/20100101 Firefox/147.0",
-		tlsClientIdentifier: "firefox_147",
-		ja3: FIREFOX_JA3,
-		h2Settings: FIREFOX_H2_SETTINGS,
-		headerOrder: FIREFOX_HEADER_ORDER,
-	}),
-	"firefox-135": createProfile("firefox-135", {
-		platform: "macos",
-		version: "135.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:135.0) Gecko/20100101 Firefox/135.0",
-		tlsClientIdentifier: "firefox_135",
-		ja3: FIREFOX_JA3,
-		h2Settings: FIREFOX_H2_SETTINGS,
-		headerOrder: FIREFOX_HEADER_ORDER,
-	}),
-	"firefox-133": createProfile("firefox-133", {
-		platform: "macos",
-		version: "133.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:133.0) Gecko/20100101 Firefox/133.0",
-		tlsClientIdentifier: "firefox_133",
-		ja3: FIREFOX_JA3,
-		h2Settings: FIREFOX_H2_SETTINGS,
-		headerOrder: FIREFOX_HEADER_ORDER,
-	}),
-	"firefox-132": createProfile("firefox-132", {
-		platform: "macos",
-		version: "132.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:132.0) Gecko/20100101 Firefox/132.0",
-		tlsClientIdentifier: "firefox_132",
-		ja3: FIREFOX_JA3,
-		h2Settings: FIREFOX_H2_SETTINGS,
-		headerOrder: FIREFOX_HEADER_ORDER,
-	}),
-	"safari-16": createProfile("safari-16", {
-		platform: "macos",
-		version: "16.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Safari/605.1.15",
-		tlsClientIdentifier: "safari_16_0",
-		ja3: SAFARI_JA3,
-		h2Settings: SAFARI_H2_SETTINGS,
-		headerOrder: SAFARI_HEADER_ORDER,
-	}),
-	"safari-15": createProfile("safari-15", {
-		platform: "macos",
-		version: "15.6.1",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.6.1 Safari/605.1.15",
-		tlsClientIdentifier: "safari_15_6_1",
-		ja3: SAFARI_JA3,
-		h2Settings: SAFARI_H2_SETTINGS,
-		headerOrder: SAFARI_HEADER_ORDER,
-	}),
-	"ios-safari-26": createProfile("ios-safari-26", {
-		platform: "ios",
-		version: "26.0",
-		userAgent:
-			"Mozilla/5.0 (iPhone; CPU iPhone OS 26_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Mobile/15E148 Safari/604.1",
-		tlsClientIdentifier: "safari_ios_26_0",
-		ja3: SAFARI_JA3,
-		h2Settings: SAFARI_H2_SETTINGS,
-		headerOrder: SAFARI_HEADER_ORDER,
-	}),
-	"ios-safari-18": createProfile("ios-safari-18", {
-		platform: "ios",
-		version: "18.0",
-		userAgent:
-			"Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1",
-		tlsClientIdentifier: "safari_ios_18_0",
-		ja3: SAFARI_JA3,
-		h2Settings: SAFARI_H2_SETTINGS,
-		headerOrder: SAFARI_HEADER_ORDER,
-	}),
-	"ios-safari-17": createProfile("ios-safari-17", {
-		platform: "ios",
-		version: "17.0",
-		userAgent:
-			"Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1",
-		tlsClientIdentifier: "safari_ios_17_0",
-		ja3: SAFARI_JA3,
-		h2Settings: SAFARI_H2_SETTINGS,
-		headerOrder: SAFARI_HEADER_ORDER,
-	}),
-	"generic-desktop": createProfile("generic-desktop", {
-		platform: "macos",
-		version: "146.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_146",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"generic-mobile": createProfile("generic-mobile", {
-		platform: "ios",
-		version: "26.0",
-		userAgent:
-			"Mozilla/5.0 (iPhone; CPU iPhone OS 26_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Mobile/15E148 Safari/604.1",
-		tlsClientIdentifier: "safari_ios_26_0",
-		ja3: SAFARI_JA3,
-		h2Settings: SAFARI_H2_SETTINGS,
-		headerOrder: SAFARI_HEADER_ORDER,
-	}),
-};
+function profileKey(descriptor: StealthProfileDescriptor): string {
+	return `${descriptor.browser}:${descriptor.os}`;
+}
 
-export function getStealthProfile(name: string): StealthProfile {
-	const canonicalName = STEALTH_PROFILE_ALIASES[name] ?? name;
-	const profile = STEALTH_PROFILES[canonicalName];
+let stealthProfileCatalog: Map<string, StealthProfile> | undefined;
 
-	if (!profile) {
-		throw new SDKError(`Unknown stealth profile: ${name}`);
+function getStealthProfileCatalog(): Map<string, StealthProfile> {
+	if (stealthProfileCatalog) return stealthProfileCatalog;
+
+	const latestChrome = resolveLatestChromiumProfile();
+	const definitions: Record<StealthBrowser, Omit<StealthProfileDefinition, "userAgent">> = {
+		chrome: {
+			version: latestChrome.version,
+			tlsClientIdentifier: latestChrome.wreqName,
+			ja3: CHROMIUM_JA3,
+			h2Settings: CHROMIUM_H2_SETTINGS,
+		},
+		firefox: {
+			version: "147.0",
+			tlsClientIdentifier: "firefox_147",
+			ja3: FIREFOX_JA3,
+			h2Settings: FIREFOX_H2_SETTINGS,
+		},
+		safari: {
+			version: "17.0",
+			tlsClientIdentifier: "safari_17.0",
+			ja3: SAFARI_JA3,
+			h2Settings: SAFARI_H2_SETTINGS,
+		},
+	};
+
+	stealthProfileCatalog = new Map();
+	for (const descriptor of SUPPORTED_STEALTH_PROFILES) {
+		const isMobileSafari = descriptor.browser === "safari" && descriptor.os === "ios";
+		const definition = isMobileSafari
+			? {
+					version: "26.0",
+					tlsClientIdentifier: "safari_ios_26" as BrowserProfile,
+					ja3: SAFARI_JA3,
+					h2Settings: SAFARI_H2_SETTINGS,
+				}
+			: definitions[descriptor.browser];
+		const wreqName = definition.tlsClientIdentifier as BrowserProfile;
+		stealthProfileCatalog.set(
+			profileKey(descriptor),
+			createProfile(descriptor, {
+				...definition,
+				userAgent: emulationUserAgent(wreqName, descriptor.os),
+			}),
+		);
 	}
+	return stealthProfileCatalog;
+}
 
+export function getStealthProfile(selection: StealthProfileSelection = {}): StealthProfile {
+	const descriptor = resolveStealthProfileSelection(selection);
+	const profile = getStealthProfileCatalog().get(profileKey(descriptor));
+	if (!profile) {
+		throw new SDKError(`Unknown stealth profile: ${descriptor.browser}/${descriptor.os}`);
+	}
 	return {
 		...profile,
 		h2Settings: profile.h2Settings ? { ...profile.h2Settings } : undefined,
-		headerOrder: profile.headerOrder ? [...profile.headerOrder] : undefined,
 	};
 }
 
-export function listStealthProfiles(): string[] {
-	return [...Object.keys(STEALTH_PROFILES), ...Object.keys(STEALTH_PROFILE_ALIASES)];
+export function listStealthProfiles(): StealthProfileDescriptor[] {
+	return SUPPORTED_STEALTH_PROFILES.map((profile) => ({ ...profile }));
 }