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

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.44",
+	"version": "2.2.0-beta.46",
 	"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.