@apifuse/provider-sdk 2.2.0-beta.44 → 2.2.0-beta.45

package/dist/stealth/profiles.js

@@ -1,4 +1,11 @@
+import { createRequire } from "node:module";
 import { SDKError } from "../errors.js";
+const requireModule = createRequire(import.meta.url);
+let wreqProfileApi;
+function getWreqProfileApi() {
+    wreqProfileApi ??= requireModule("wreq-js");
+    return wreqProfileApi;
+}
 const CHROMIUM_HEADER_ORDER = [
     ":method",
     ":authority",
@@ -65,6 +72,50 @@ const SAFARI_H2_SETTINGS = {
 const CHROMIUM_JA3 = "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513-65037,29-23-24,0";
 const FIREFOX_JA3 = "771,4865-4867-4866-49195-49199-52393-52392-49196-49200-49162-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-28-27-43-45-51,29-23-24-25,0";
 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";
+/**
+ * The newest Chromium build wreq-js can emulate, resolved on first profile use.
+ *
+ * A literal version here rots: it went stale twice (146 was six releases behind
+ * stable when an upstream integrity analyzer flagged it), and a fingerprint that
+ * advertises an old Chrome is exactly what bot managers score against. wreq-js
+ * already ships the profile table, so the newest entry is derived from it rather
+ * than restated. `resolveProfile("chrome")` is deliberately NOT used because its
+ * conservative default can lag newer entries in that table.
+ *
+ * package.json pins wreq-js exactly on purpose. Even a semver-minor wreq-js update
+ * can change the profile table, emitted headers, native bindings, and therefore
+ * the wire fingerprint inherited by every provider. Upgrade that exact version
+ * only in a dedicated change with profile-parity and packed-native verification.
+ */
+function resolveLatestChromiumProfile() {
+    const { getProfiles } = getWreqProfileApi();
+    let newest;
+    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` };
+}
+/** The user agent wreq-js itself emits for that profile, so the two never disagree. */
+function chromiumUserAgent(latest) {
+    const { getEmulationHeaders } = getWreqProfileApi();
+    for (const [name, value] of getEmulationHeaders(latest.wreqName, "macos")) {
+        if (String(name).toLowerCase() === "user-agent")
+            return String(value);
+    }
+    throw new SDKError(`wreq-js profile ${latest.wreqName} exposes no user-agent header.`, {
+        code: "STEALTH_PROFILE_UNAVAILABLE",
+    });
+}
 function createProfile(name, definition) {
     return {
         name,
@@ -120,10 +171,21 @@ export function generateLayer2Headers(profile) {
     }
     return headers;
 }
-const STEALTH_PROFILE_ALIASES = {
-    "chrome-desktop": "chrome-146",
+const STATIC_STEALTH_PROFILE_ALIASES = {
+    "firefox-desktop": "firefox-147",
+    "safari-desktop": "safari-17",
+    "safari-mobile": "ios-safari-26",
 };
-const STEALTH_PROFILES = {
+const PUBLIC_STEALTH_PROFILE_NAMES = [
+    "chrome-desktop",
+    "firefox-desktop",
+    "safari-desktop",
+    "safari-mobile",
+    "generic-desktop",
+    "generic-mobile",
+];
+const PUBLIC_STEALTH_PROFILE_NAME_SET = new Set(PUBLIC_STEALTH_PROFILE_NAMES);
+const STATIC_STEALTH_PROFILES = {
     "chrome-146": createProfile("chrome-146", {
         platform: "macos",
         version: "146.0.0.0",
@@ -223,15 +285,6 @@ const STEALTH_PROFILES = {
         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",
@@ -242,9 +295,38 @@ const STEALTH_PROFILES = {
         headerOrder: SAFARI_HEADER_ORDER,
     }),
 };
+let stealthProfileCatalog;
+function getStealthProfileCatalog() {
+    if (stealthProfileCatalog)
+        return stealthProfileCatalog;
+    const latest = resolveLatestChromiumProfile();
+    const currentName = `chrome-${latest.version.split(".")[0]}`;
+    const currentProfile = createProfile(currentName, {
+        platform: "macos",
+        version: latest.version,
+        userAgent: chromiumUserAgent(latest),
+        tlsClientIdentifier: latest.wreqName,
+        ja3: CHROMIUM_JA3,
+        h2Settings: CHROMIUM_H2_SETTINGS,
+        headerOrder: CHROMIUM_HEADER_ORDER,
+    });
+    stealthProfileCatalog = {
+        aliases: {
+            "chrome-desktop": currentName,
+            ...STATIC_STEALTH_PROFILE_ALIASES,
+        },
+        profiles: {
+            [currentName]: currentProfile,
+            ...STATIC_STEALTH_PROFILES,
+            "generic-desktop": createProfile("generic-desktop", currentProfile),
+        },
+    };
+    return stealthProfileCatalog;
+}
 export function getStealthProfile(name) {
-    const canonicalName = STEALTH_PROFILE_ALIASES[name] ?? name;
-    const profile = STEALTH_PROFILES[canonicalName];
+    const catalog = getStealthProfileCatalog();
+    const canonicalName = catalog.aliases[name] ?? name;
+    const profile = catalog.profiles[canonicalName];
     if (!profile) {
         throw new SDKError(`Unknown stealth profile: ${name}`);
     }
@@ -254,6 +336,27 @@ export function getStealthProfile(name) {
         headerOrder: profile.headerOrder ? [...profile.headerOrder] : undefined,
     };
 }
+/** Returns the intent alias that replaces a registered version-pinned profile. */
+export function getStealthProfileIntentAlias(name) {
+    if (PUBLIC_STEALTH_PROFILE_NAME_SET.has(name))
+        return undefined;
+    if (/^(?:chrome|chromium|edge)[-_]\d/i.test(name)) {
+        return "chrome-desktop";
+    }
+    if (/^firefox[-_]\d/i.test(name))
+        return "firefox-desktop";
+    if (/^(?:ios[-_]safari|safari[-_](?:ios|ipad))[-_]\d/i.test(name)) {
+        return "safari-mobile";
+    }
+    if (/^safari[-_]\d/i.test(name))
+        return "safari-desktop";
+    return undefined;
+}
+/** Internal compatibility catalog used by transport-parity tests. */
+export function listRegisteredStealthProfiles() {
+    const catalog = getStealthProfileCatalog();
+    return [...Object.keys(catalog.profiles), ...Object.keys(catalog.aliases)];
+}
 export function listStealthProfiles() {
-    return [...Object.keys(STEALTH_PROFILES), ...Object.keys(STEALTH_PROFILE_ALIASES)];
+    return [...PUBLIC_STEALTH_PROFILE_NAMES];
 }

package/dist/types.d.ts

@@ -956,6 +956,10 @@ export interface ProviderMeta {
     publicProfile?: ProviderPublicProfile;
     contract?: {
         publicSchemaFieldNames?: "normalized";
+        readonly pinnedWireFieldPaths?: readonly {
+            readonly path: string;
+            readonly reason: string;
+        }[];
     };
 }
 export type RequestParamPrimitive = string | number | boolean | null | undefined;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.44",
+	"version": "2.2.0-beta.45",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/declaration-validation.ts

@@ -21,6 +21,7 @@ export const DECLARATION_RULE_IDS = {
 	proxyNoMixedVendors: "proxy-no-mixed-vendors",
 	proxySmartproxyGeo: "proxy-smartproxy-country-only",
 	operationUpstreamProxy: "operation-upstream-proxy-unsupported",
+	pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid",
 } as const;
 
 export type DeclarationRuleId =
@@ -53,13 +54,14 @@ export function declarationInvalidError(
 export function validateFailClosedDeclaration(provider: ProviderDefinition): void {
 	const violations: DeclarationViolation[] = [];
 	validateHealthDeclaration(provider, violations);
+	validatePinnedWireFieldPaths(provider, violations);
 	validateSchemaDeclaration(provider, violations);
 	validateProxyDeclaration(provider, violations);
 	validateOperationDeclaration(provider, violations);
 	if (violations.length > 0) throw declarationInvalidError(violations);
 }
 
-type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "proxy">;
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "meta" | "proxy">;
 type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
 
 /** Enforces fail-closed rules that only depend on the provider declaration. */
@@ -85,9 +87,71 @@ function collectProviderDeclarationViolations(
 	violations: DeclarationViolation[],
 ): void {
 	validateHealthDeclaration(provider, violations);
+	validatePinnedWireFieldPaths(provider, violations);
 	validateProxyDeclaration(provider, violations);
 }
 
+function validatePinnedWireFieldPaths(
+	provider: ProviderDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	const pins = provider.meta?.contract?.pinnedWireFieldPaths;
+	if (pins === undefined) return;
+
+	if (!Array.isArray(pins)) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+			path: "meta.contract.pinnedWireFieldPaths",
+			message: "pinned wire field paths must be an array.",
+			fix: "Declare a readonly array of { path, reason } entries.",
+		});
+		return;
+	}
+
+	const seenPaths = new Set<string>();
+	for (const [index, pin] of pins.entries()) {
+		const entryPath = `meta.contract.pinnedWireFieldPaths[${index}]`;
+		if (!pin || typeof pin !== "object" || Array.isArray(pin)) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: entryPath,
+				message: "each pinned wire field path must be an object.",
+				fix: `Replace ${entryPath} with { path: "operations.<operation-id>.<field-path>", reason: "<non-empty reason>" }.`,
+			});
+			continue;
+		}
+
+		const path = "path" in pin ? pin.path : undefined;
+		const reason = "reason" in pin ? pin.reason : undefined;
+		if (typeof path !== "string" || path.trim().length === 0) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: `${entryPath}.path`,
+				message: "path must be a non-empty string.",
+				fix: `Set ${entryPath}.path to the exact public-schema-upstream-field diagnostic path.`,
+			});
+		} else if (seenPaths.has(path)) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: `${entryPath}.path`,
+				message: `duplicate pinned wire field path ${JSON.stringify(path)}.`,
+				fix: `Keep exactly one declaration for ${JSON.stringify(path)}.`,
+			});
+		} else {
+			seenPaths.add(path);
+		}
+
+		if (typeof reason !== "string" || reason.trim().length === 0) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: `${entryPath}.reason`,
+				message: "reason must be a non-empty string.",
+				fix: `Document why renaming the exact wire field would break the upstream contract.`,
+			});
+		}
+	}
+}
+
 function collectOperationDeclarationViolations(
 	provider: OperationDeclarationRulesInput,
 	violations: DeclarationViolation[],

package/src/define.ts

@@ -638,6 +638,10 @@ export interface ProviderDeclaration {
 		implementationProfile?: ProviderImplementationProfile;
 		contract?: {
 			publicSchemaFieldNames?: "normalized";
+			readonly pinnedWireFieldPaths?: readonly {
+				readonly path: string;
+				readonly reason: string;
+			}[];
 		};
 	};
 	healthMonitor?: ProviderHealthMonitorConfig;

package/src/lint.ts

@@ -1,3 +1,5 @@
+import { createRequire } from "node:module";
+
 import type { ZodType } from "zod";
 
 import {
@@ -7,6 +9,17 @@ import {
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 
+const requireModule = createRequire(import.meta.url);
+// `typeof import(...)` keeps the type without emitting a static import: the
+// typescript package is a CLI-only dependency and src/lint.ts is production
+// runtime, which the typescript-import-boundary test enforces.
+let typeScriptModule: typeof import("typescript") | undefined;
+
+function getTypeScript(): typeof import("typescript") {
+	typeScriptModule ??= requireModule("typescript") as typeof import("typescript");
+	return typeScriptModule;
+}
+
 type AuthModeLike =
 	| "none"
 	| "platform-managed"
@@ -120,6 +133,10 @@ function isAuthLifecycleOperationId(operationId: string, authMode: string): bool
 
 type ProviderContractMetaLike = {
 	publicSchemaFieldNames?: "normalized";
+	pinnedWireFieldPaths?: readonly {
+		readonly path: string;
+		readonly reason: string;
+	}[];
 };
 
 type SchemaLike = ZodType & {
@@ -153,6 +170,17 @@ type ProviderLintOptions = {
 	mode?: ProviderLintMode;
 };
 
+export interface ProviderLintInformation {
+	rule: string;
+	message: string;
+	field?: string;
+}
+
+export interface ProviderLintResult {
+	diagnostics: LintDiagnostic[];
+	information: ProviderLintInformation[];
+}
+
 type ProviderSourceLike = {
 	authFlowSource?: string;
 	providerSourceFiles?: Record<string, string>;
@@ -894,6 +922,146 @@ function lintSelfHostedBrowserPatterns(
 const THROWN_ERROR_CONSTRUCTION_PATTERN = /new\s+(?:ProviderError|ValidationError)\s*\(/g;
 
 const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+const RECORDED_FIXTURE_SOURCE_FILE_PATTERN =
+	/(?:^|\/)__fixtures__(?:\/|$)|(?:^|\/)__tests__\/fixtures(?:\/|$)/;
+const JAVASCRIPT_SOURCE_FILE_PATTERN = /\.[cm]?[jt]sx?$/;
+const VERSIONED_PROFILE_LITERAL_PATTERN =
+	/\b(?:chrome|chromium|firefox|safari|edge|opera|ios[-_]safari)[-_]\d+(?:[._-]\d+)*(?=$|[^A-Za-z0-9])/i;
+const VERSIONED_USER_AGENT_PATTERN = /\b(?:Chrome|CriOS|Firefox|FxiOS|EdgA?|OPR)\/\d+(?:\.\d+)*/i;
+const VERSIONED_SAFARI_USER_AGENT_PATTERN = /\bVersion\/(\d+(?:\.\d+)*)(?=[\s\S]*\bSafari\/\d)/i;
+const VERSIONED_CLIENT_HINT_PATTERN = /(?:^|[;,\s])v\s*=\s*["']?\d+/i;
+
+type BrowserVersionLiteralKind = "profile" | "user-agent" | "sec-ch-ua";
+
+type BrowserVersionLiteralFinding = {
+	kind: BrowserVersionLiteralKind;
+	literal: string;
+	position: number;
+};
+
+function staticStringText(node: import("typescript").Node | undefined): string | undefined {
+	if (!node) return undefined;
+	const ts = getTypeScript();
+	if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+	return undefined;
+}
+
+function staticPropertyName(node: import("typescript").PropertyName): string | undefined {
+	const ts = getTypeScript();
+	if (ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node)) {
+		return node.text;
+	}
+	if (ts.isComputedPropertyName(node)) return staticStringText(node.expression);
+	return undefined;
+}
+
+function isSecChUaHeaderName(value: string | undefined): boolean {
+	return value?.toLowerCase() === "sec-ch-ua";
+}
+
+function collectBrowserVersionLiteralFindings(source: string): BrowserVersionLiteralFinding[] {
+	const ts = getTypeScript();
+	const sourceFile = ts.createSourceFile(
+		"provider-source.ts",
+		source,
+		ts.ScriptTarget.Latest,
+		true,
+		ts.ScriptKind.TSX,
+	);
+	const findings: BrowserVersionLiteralFinding[] = [];
+	const seen = new Set<string>();
+
+	const addFinding = (kind: BrowserVersionLiteralKind, literal: string, position: number) => {
+		const key = `${kind}:${position}:${literal}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		findings.push({ kind, literal, position });
+	};
+
+	const inspectLiteral = (text: string, position: number) => {
+		const profile = text.match(VERSIONED_PROFILE_LITERAL_PATTERN)?.[0];
+		if (profile) addFinding("profile", profile, position);
+
+		const userAgent =
+			text.match(VERSIONED_USER_AGENT_PATTERN)?.[0] ??
+			text.match(VERSIONED_SAFARI_USER_AGENT_PATTERN)?.[0];
+		if (userAgent) addFinding("user-agent", userAgent, position);
+	};
+
+	const inspectSecChUaValue = (node: import("typescript").Node | undefined) => {
+		const text = staticStringText(node);
+		if (text && VERSIONED_CLIENT_HINT_PATTERN.test(text)) {
+			addFinding("sec-ch-ua", "sec-ch-ua", node!.getStart(sourceFile));
+		}
+	};
+
+	const visit = (node: import("typescript").Node) => {
+		const text = staticStringText(node);
+		if (text !== undefined) inspectLiteral(text, node.getStart(sourceFile));
+
+		if (ts.isPropertyAssignment(node) && isSecChUaHeaderName(staticPropertyName(node.name))) {
+			inspectSecChUaValue(node.initializer);
+		}
+
+		if (ts.isCallExpression(node) && isSecChUaHeaderName(staticStringText(node.arguments[0]))) {
+			inspectSecChUaValue(node.arguments[1]);
+		}
+
+		if (
+			ts.isArrayLiteralExpression(node) &&
+			isSecChUaHeaderName(staticStringText(node.elements[0]))
+		) {
+			inspectSecChUaValue(node.elements[1]);
+		}
+
+		ts.forEachChild(node, visit);
+	};
+
+	visit(sourceFile);
+	return findings.sort((left, right) => left.position - right.position);
+}
+
+function browserVersionLiteralMessage(finding: BrowserVersionLiteralFinding): string {
+	switch (finding.kind) {
+		case "profile":
+			return `Hardcoded stealth profile "${finding.literal}" pins a browser version and will rot. Use the matching intent alias instead: "chrome-desktop", "firefox-desktop", "safari-desktop", or "safari-mobile".`;
+		case "user-agent":
+			return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal and derive it from the matching intent profile, for example getStealthProfile("chrome-desktop").userAgent.`;
+		case "sec-ch-ua":
+			return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from an intent profile such as "chrome-desktop"; derive any explicit User-Agent with getStealthProfile("chrome-desktop").userAgent.';
+	}
+}
+
+function lintBrowserVersionLiterals(provider: ProviderSourceLike): LintDiagnostic[] {
+	const sources: Array<{ field: string; source: string }> = [];
+	const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(
+		([filePath]) =>
+			JAVASCRIPT_SOURCE_FILE_PATTERN.test(filePath) &&
+			!TEST_SOURCE_FILE_PATTERN.test(filePath) &&
+			!RECORDED_FIXTURE_SOURCE_FILE_PATTERN.test(filePath),
+	);
+	if (sourceFiles.length > 0) {
+		for (const [filePath, source] of sourceFiles) {
+			sources.push({ field: `sourceFiles.${filePath}`, source });
+		}
+	} else {
+		if (provider.authFlowSource)
+			sources.push({ field: "auth.flow", source: provider.authFlowSource });
+		for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+			const source = getOperationSource(operation);
+			if (source) sources.push({ field: `operations.${operationKey}.handler`, source });
+		}
+	}
+
+	return sources.flatMap(({ field, source }) =>
+		collectBrowserVersionLiteralFindings(source).map((finding) => ({
+			rule: "browser-version-literal",
+			level: "error" as const,
+			field,
+			message: browserVersionLiteralMessage(finding),
+		})),
+	);
+}
 
 /**
  * Skips a string literal starting at `startIndex` (which must point at the
@@ -1298,6 +1466,67 @@ export function lintOperation(op: {
 	return diagnostics;
 }
 
+function declaredPinnedWireFieldPaths(provider: {
+	meta?: { contract?: ProviderContractMetaLike };
+}): readonly { readonly path: string; readonly reason: string }[] {
+	const pins = provider.meta?.contract?.pinnedWireFieldPaths;
+	if (!Array.isArray(pins)) return [];
+	return pins.filter(
+		(pin) =>
+			pin !== null &&
+			typeof pin === "object" &&
+			typeof pin.path === "string" &&
+			pin.path.trim().length > 0 &&
+			typeof pin.reason === "string" &&
+			pin.reason.trim().length > 0,
+	);
+}
+
+function applyPinnedWireFieldPaths(
+	provider: { meta?: { contract?: ProviderContractMetaLike } },
+	diagnostics: readonly LintDiagnostic[],
+): ProviderLintResult {
+	const pins = declaredPinnedWireFieldPaths(provider);
+	if (pins.length === 0) {
+		return { diagnostics: [...diagnostics], information: [] };
+	}
+
+	const pinsByPath = new Map(pins.map((pin) => [pin.path, pin]));
+	const matchedPaths = new Set<string>();
+	const remainingDiagnostics = diagnostics.filter((diagnostic) => {
+		if (
+			diagnostic.rule !== "public-schema-upstream-field" ||
+			diagnostic.field === undefined ||
+			!pinsByPath.has(diagnostic.field)
+		) {
+			return true;
+		}
+		matchedPaths.add(diagnostic.field);
+		return false;
+	});
+
+	const information: ProviderLintInformation[] = [];
+	for (const pin of pins) {
+		if (matchedPaths.has(pin.path)) {
+			information.push({
+				rule: "public-schema-pinned-wire-field",
+				field: pin.path,
+				message: `Suppressed exact public-schema-upstream-field diagnostic. Reason: ${pin.reason}`,
+			});
+			continue;
+		}
+
+		remainingDiagnostics.push({
+			rule: "public-schema-pinned-wire-field-stale",
+			level: "error",
+			field: pin.path,
+			message: `Pinned wire field path ${JSON.stringify(pin.path)} matches no current public-schema-upstream-field diagnostic; remove the stale declaration.`,
+		});
+	}
+
+	return { diagnostics: remainingDiagnostics, information };
+}
+
 export function lintProvider(
 	provider: {
 		id?: string;
@@ -1340,6 +1569,14 @@ export function lintProvider(
 	},
 	options: ProviderLintOptions = {},
 ): LintDiagnostic[] {
+	return lintProviderWithInformation(provider, options).diagnostics;
+}
+
+/** Internal detailed result used by the CLI to render suppression audits. */
+export function lintProviderWithInformation(
+	provider: Parameters<typeof lintProvider>[0],
+	options: ProviderLintOptions = {},
+): ProviderLintResult {
 	const diagnostics: LintDiagnostic[] = [
 		...lintAllowedHosts(provider.id, provider.allowedHosts),
 		...lintReviewed(provider.id, provider.reviewed),
@@ -1348,6 +1585,7 @@ export function lintProvider(
 		...lintCredentialWriteUsage(provider),
 		...lintPlaywrightDirectImports(provider),
 		...lintSelfHostedBrowserPatterns(provider, options),
+		...lintBrowserVersionLiterals(provider),
 		...lintUndeclaredThrownErrorCodes(provider),
 	];
 
@@ -1375,7 +1613,7 @@ export function lintProvider(
 	}
 
 	if (!provider.operations) {
-		return diagnostics;
+		return applyPinnedWireFieldPaths(provider, diagnostics);
 	}
 
 	diagnostics.push(
@@ -1411,5 +1649,5 @@ export function lintProvider(
 		),
 	);
 
-	return diagnostics;
+	return applyPinnedWireFieldPaths(provider, diagnostics);
 }

package/src/runtime/insights.ts

@@ -27,7 +27,7 @@ const DNS_WARN_MS = 5;
 const BROWSER_IDLE_MS = 5_000;
 const REFRESH_WARN_RATE = 0.1;
 
-const TLS_REUSE_FIX = `const session = ctx.stealth.createSession({ profile: 'chrome-146' });
+const TLS_REUSE_FIX = `const session = ctx.stealth.createSession({ profile: 'chrome-desktop' });
 const resp = await session.fetch(url, opts);`;
 
 const TRANSFORM_FIX = `transformResponse: (raw) => {
@@ -39,7 +39,7 @@ const LARGE_RESPONSE_FIX = `const resp = await ctx.http.get('/items', {
 });`;
 
 const DNS_FIX = `// Enable DNS caching or reuse a long-lived session per host.
-const session = ctx.stealth.createSession({ profile: 'chrome-146' });
+const session = ctx.stealth.createSession({ profile: 'chrome-desktop' });
 await session.fetch(url, opts);`;
 
 const PROXY_FIX = `// Re-check whether this operation really needs a proxy.

package/src/runtime/stealth.ts

@@ -18,7 +18,7 @@ import {
 	vendorFromResolvedSource,
 } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
-import { getStealthProfile } from "../stealth/profiles.js";
+import { getStealthProfile, getStealthProfileIntentAlias } from "../stealth/profiles.js";
 import type {
 	HttpMethod,
 	StealthClient,
@@ -67,7 +67,7 @@ import {
 	serializeRequestUrl,
 } from "./request-options.js";
 
-export const DEFAULT_PROFILE = "chrome-146";
+export const DEFAULT_PROFILE = "chrome-desktop";
 
 const MISSING_PROXY_WARNING =
 	"[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
@@ -244,7 +244,12 @@ function resolveDefaultWreqProfileMapping(): { identifier: string; os: Emulation
 	return { identifier, os: profile.platform };
 }
 
-const DEFAULT_WREQ_PROFILE_MAPPING = resolveDefaultWreqProfileMapping();
+let defaultWreqProfileMapping: ReturnType<typeof resolveDefaultWreqProfileMapping> | undefined;
+
+function getDefaultWreqProfileMapping(): ReturnType<typeof resolveDefaultWreqProfileMapping> {
+	defaultWreqProfileMapping ??= resolveDefaultWreqProfileMapping();
+	return defaultWreqProfileMapping;
+}
 
 export function resolveWreqProfile(
 	profileName: string,
@@ -268,8 +273,9 @@ export function resolveWreqProfile(
 		// profile strings still run with the transport default instead of failing
 		// before the request starts. Removed built-in profile aliases above remain
 		// explicit errors so callers do not accidentally pin retired fingerprints.
-		identifier = DEFAULT_WREQ_PROFILE_MAPPING.identifier;
-		os = DEFAULT_WREQ_PROFILE_MAPPING.os;
+		const defaultMapping = getDefaultWreqProfileMapping();
+		identifier = defaultMapping.identifier;
+		os = defaultMapping.os;
 	}
 
 	const browser = closestWreqProfile(identifier, wreqProfiles);
@@ -772,6 +778,12 @@ function createSessionFetcher(
 	let closed = false;
 	let hasWarnedMissingProxy = false;
 	const warn = clientOptions.warn ?? console.warn;
+	const intentAlias = getStealthProfileIntentAlias(defaultProfile);
+	if (intentAlias) {
+		warn(
+			`[provider-sdk] Stealth profile "${defaultProfile}" pins a browser version and is deprecated. Use the intent profile "${intentAlias}" so TLS, headers, and User-Agent stay aligned with SDK updates; derive an explicit User-Agent with getStealthProfile("${intentAlias}").userAgent instead of hardcoding one.`,
+		);
+	}
 	const cookieJar = new StealthCookieJar([], baseUrl);
 
 	async function getClientEntry(