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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.46
+
+- Release candidate for main commit 0340fbc51b4ad71689bb1ec61b9b818dedda4587.
+
+## 2.2.0-beta.45
+
+- Release candidate for main commit 5d337d9fc1c77cd814ec7a4e1aa44ba0f8b2a5a9.
+
 ## 2.2.0-beta.44
 
 - Release candidate for main commit a3091c0b4931c5ae48fe01b9776e4dc213db2716.

package/README.md

@@ -144,7 +144,8 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
-  `profile` such as `chrome-146`; do not tune JA3, HTTP/2 SETTINGS, or
+  intent-based `profile` such as `chrome-desktop`; do not pin a browser version
+  or tune JA3, HTTP/2 SETTINGS, or
   pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
   are supported; use `ctx.browser` when the provider needs browser execution.
 - **Query-parameter credentials**: when an upstream requires a credential in

package/bin/apifuse-check.ts

@@ -17,7 +17,7 @@ import {
 } from "../src/declaration-validation.js";
 import { isProviderError } from "../src/errors.js";
 import type { ProviderDefinition } from "../src/index.js";
-import { lintProvider, type ProviderLintMode } from "../src/lint.js";
+import { lintProviderWithInformation, type ProviderLintMode } from "../src/lint.js";
 import { safeParseSchemaSync } from "../src/schema.js";
 
 const HELP_TEXT = `Usage: apifuse check [path]
@@ -379,12 +379,21 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider({ ...provider, providerSourceFiles }, { mode: lintMode });
+	const { diagnostics, information } = lintProviderWithInformation(
+		{ ...provider, providerSourceFiles },
+		{ mode: lintMode },
+	);
 	const errors = diagnostics.filter((diagnostic) => diagnostic.level === "error");
-	const details = diagnostics.map((diagnostic) => {
-		const field = diagnostic.field ? `${diagnostic.field}: ` : "";
-		return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
+	const details = information.map((entry) => {
+		const field = entry.field ? `${entry.field}: ` : "";
+		return `INFO ${entry.rule} ${field}${entry.message}`;
 	});
+	details.push(
+		...diagnostics.map((diagnostic) => {
+			const field = diagnostic.field ? `${diagnostic.field}: ` : "";
+			return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
+		}),
+	);
 
 	return {
 		message: "Provider authoring lint has no error-level diagnostics",

package/dist/declaration-validation.d.ts

@@ -12,6 +12,7 @@ export declare const DECLARATION_RULE_IDS: {
     readonly proxyNoMixedVendors: "proxy-no-mixed-vendors";
     readonly proxySmartproxyGeo: "proxy-smartproxy-country-only";
     readonly operationUpstreamProxy: "operation-upstream-proxy-unsupported";
+    readonly pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid";
 };
 export type DeclarationRuleId = (typeof DECLARATION_RULE_IDS)[keyof typeof DECLARATION_RULE_IDS];
 export type DeclarationViolation = {
@@ -23,7 +24,7 @@ export type DeclarationViolation = {
 export declare function declarationInvalidError(violations: readonly DeclarationViolation[]): ProviderError;
 /** Enforces declaration rules whose runtime behavior would otherwise fail open. */
 export declare function validateFailClosedDeclaration(provider: ProviderDefinition): void;
-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. */
 export declare function validateFailClosedProviderDeclaration(provider: ProviderDeclarationRulesInput): void;

package/dist/declaration-validation.js

@@ -13,6 +13,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",
 };
 export function declarationInvalidError(violations) {
     const summary = violations
@@ -28,6 +29,7 @@ export function declarationInvalidError(violations) {
 export function validateFailClosedDeclaration(provider) {
     const violations = [];
     validateHealthDeclaration(provider, violations);
+    validatePinnedWireFieldPaths(provider, violations);
     validateSchemaDeclaration(provider, violations);
     validateProxyDeclaration(provider, violations);
     validateOperationDeclaration(provider, violations);
@@ -50,8 +52,65 @@ export function validateFailClosedOperationDeclaration(provider) {
 }
 function collectProviderDeclarationViolations(provider, violations) {
     validateHealthDeclaration(provider, violations);
+    validatePinnedWireFieldPaths(provider, violations);
     validateProxyDeclaration(provider, violations);
 }
+function validatePinnedWireFieldPaths(provider, violations) {
+    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();
+    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, violations) {
     validateSchemaDeclaration(provider, violations);
     validateOperationDeclaration(provider, violations);

package/dist/define.d.ts

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

package/dist/lint.d.ts

@@ -12,6 +12,10 @@ type ProviderAuthLike = {
 };
 type ProviderContractMetaLike = {
     publicSchemaFieldNames?: "normalized";
+    pinnedWireFieldPaths?: readonly {
+        readonly path: string;
+        readonly reason: string;
+    }[];
 };
 export interface LintDiagnostic {
     rule: string;
@@ -23,6 +27,15 @@ export type ProviderLintMode = "official" | "standalone";
 type ProviderLintOptions = {
     mode?: ProviderLintMode;
 };
+export interface ProviderLintInformation {
+    rule: string;
+    message: string;
+    field?: string;
+}
+export interface ProviderLintResult {
+    diagnostics: LintDiagnostic[];
+    information: ProviderLintInformation[];
+}
 export declare function lintOperation(op: {
     description?: string;
     descriptionKey?: string;
@@ -76,4 +89,6 @@ export declare function lintProvider(provider: {
     };
     reviewed?: string;
 }, options?: ProviderLintOptions): LintDiagnostic[];
+/** Internal detailed result used by the CLI to render suppression audits. */
+export declare function lintProviderWithInformation(provider: Parameters<typeof lintProvider>[0], options?: ProviderLintOptions): ProviderLintResult;
 export {};

package/dist/lint.js

@@ -1,6 +1,16 @@
+import { createRequire } from "node:module";
 import { SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
 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;
+function getTypeScript() {
+    typeScriptModule ??= requireModule("typescript");
+    return typeScriptModule;
+}
 // Operations that perform an auth-lifecycle action belong on the single
 // `auth.flow` interface, never on a provider operation:
 //   - entry (login / signin / authenticate) => auth.flow.start/continue
@@ -667,6 +677,114 @@ function lintSelfHostedBrowserPatterns(provider, options) {
 }
 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;
+function staticStringText(node) {
+    if (!node)
+        return undefined;
+    const ts = getTypeScript();
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return undefined;
+}
+function staticPropertyName(node) {
+    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) {
+    return value?.toLowerCase() === "sec-ch-ua";
+}
+function collectBrowserVersionLiteralFindings(source) {
+    const ts = getTypeScript();
+    const sourceFile = ts.createSourceFile("provider-source.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const findings = [];
+    const seen = new Set();
+    const addFinding = (kind, literal, position) => {
+        const key = `${kind}:${position}:${literal}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        findings.push({ kind, literal, position });
+    };
+    const inspectLiteral = (text, position) => {
+        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) => {
+        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) => {
+        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) {
+    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) {
+    const sources = [];
+    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",
+        field,
+        message: browserVersionLiteralMessage(finding),
+    })));
+}
 /**
  * Skips a string literal starting at `startIndex` (which must point at the
  * opening quote). Returns the index of the closing quote, or -1 when the
@@ -1021,7 +1139,57 @@ export function lintOperation(op) {
     }
     return diagnostics;
 }
+function declaredPinnedWireFieldPaths(provider) {
+    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, diagnostics) {
+    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();
+    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 = [];
+    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, options = {}) {
+    return lintProviderWithInformation(provider, options).diagnostics;
+}
+/** Internal detailed result used by the CLI to render suppression audits. */
+export function lintProviderWithInformation(provider, options = {}) {
     const diagnostics = [
         ...lintAllowedHosts(provider.id, provider.allowedHosts),
         ...lintReviewed(provider.id, provider.reviewed),
@@ -1030,6 +1198,7 @@ export function lintProvider(provider, options = {}) {
         ...lintCredentialWriteUsage(provider),
         ...lintPlaywrightDirectImports(provider),
         ...lintSelfHostedBrowserPatterns(provider, options),
+        ...lintBrowserVersionLiterals(provider),
         ...lintUndeclaredThrownErrorCodes(provider),
     ];
     if (provider.operations) {
@@ -1053,7 +1222,7 @@ export function lintProvider(provider, options = {}) {
         }
     }
     if (!provider.operations) {
-        return diagnostics;
+        return applyPinnedWireFieldPaths(provider, diagnostics);
     }
     diagnostics.push(...Object.entries(provider.operations).flatMap(([operationKey, operation]) => [
         ...lintOperation({
@@ -1077,5 +1246,5 @@ export function lintProvider(provider, options = {}) {
             : `operations.${operationKey}`,
         message: `[${operationKey}] ${diagnostic.message}`,
     }))));
-    return diagnostics;
+    return applyPinnedWireFieldPaths(provider, diagnostics);
 }

package/dist/runtime/insights.js

@@ -4,7 +4,7 @@ const SLOW_TRANSFORM_MS = 10;
 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) => {
 	return raw.items.map(({ id, name, price }) => ({ id, name, price }));
@@ -13,7 +13,7 @@ const LARGE_RESPONSE_FIX = `const resp = await ctx.http.get('/items', {
 	params: { limit: 50, page: 1 },
 });`;
 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.
 await ctx.stealth.fetch(url, { ...opts, proxy: undefined });`;

package/dist/runtime/stealth.d.ts

@@ -1,9 +1,11 @@
 import type { BrowserProfile, EmulationOS } from "wreq-js";
 import type { ProxyResolutionOptions } from "../config/loader.js";
 import type { StealthClient, StealthResponse } from "../types.js";
-export declare const DEFAULT_PROFILE = "chrome-146";
+export declare const DEFAULT_PROFILE = "chrome-desktop";
 export type StealthClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
+    /** Abort all requests issued by this client. */
+    signal?: AbortSignal;
     /**
      * Proxy-only stealth transport overrides. Use only for upstream proxy products
      * that terminate CONNECT with a private CA instead of tunneling the origin