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

package/src/lint.ts

@@ -1,9 +1,53 @@
+import { createRequire } from "node:module";
+
 import type { ZodType } from "zod";
 
+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";
+import type {
+	AuthMode,
+	OperationApprovalPolicy,
+	OperationRiskClass,
+} from "./types.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"
+	| "credentials"
+	| "oauth2"
+	| "oauth2_proxied"
+	| "api-key";
+
+const CREDENTIAL_BEARING_AUTH_MODES = [
+	"credentials",
+	"oauth2",
+	"oauth2_proxied",
+] satisfies readonly AuthMode[];
+
+function isCredentialBearingAuthMode(mode: AuthModeLike | undefined): boolean {
+	return CREDENTIAL_BEARING_AUTH_MODES.some((credentialMode) => credentialMode === mode);
+}
 
-type AuthModeLike = "none" | "platform-managed" | "credentials" | "oauth2" | "api-key";
+function defaultApprovalPolicy(riskClass: OperationRiskClass): OperationApprovalPolicy {
+	if (riskClass === "read") return "never";
+	if (riskClass === "write") return "risk-based";
+	return "always";
+}
 
 type ProviderAuthLike = {
 	mode?: AuthModeLike;
@@ -17,11 +61,103 @@ type ProviderAuthLike = {
 	exchange?: unknown;
 };
 
+// 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
+//   - exit  (logout / signout / disconnect) => auth.flow.abort
+//
+// Matching works on `-`/`_` separated segments rather than a raw substring or a
+// leading anchor, so `shop-logout`, `shop_logout` and `user-sign-out-everywhere`
+// are all recognised: a domain prefix does not make the operation any less of an
+// auth-lifecycle action, and operation ids may use either separator.
+//
+// Vocabulary is split into two tiers because auth words collide with ordinary
+// domain verbs. Measured against the live fleet plus synthetic domain ids:
+//   - `authorize-payment`, `revoke-invitation`, `unlink-record`,
+//     `disconnect-device` are domain actions that never touch the connection
+//     credential, so these verbs are NOT matched as segments;
+//   - the same verbs as a complete operation id (`authorize`, `revoke`) do
+//     refer to the credential itself, so they are matched only in that form.
+// `exchange`, `callback`, `connect`, `session`, `token`, `credential`,
+// `password` and `otp` stay out entirely for the same reason.
+const AUTH_LIFECYCLE_SEGMENT_WORDS = new Set([
+	"login",
+	"logout",
+	"signin",
+	"signout",
+	"signup",
+	"authenticate",
+	"reauth",
+	"auth",
+]);
+
+// Ambiguous as a prefix, unambiguous when they are the whole operation id.
+const AUTH_LIFECYCLE_WHOLE_ID_WORDS = new Set([
+	"authorize",
+	"revoke",
+	"unlink",
+	"disconnect",
+]);
+
+// A verb stem followed by a direction word across two segments: `sign-out`,
+// `user_sign_up_flow`, and the spelled-out `log-in` / `shop-log-out` forms
+// (their fused equivalents `login`/`logout` live in the segment set above).
+// `sign` pairs match anywhere; `log` pairs match only at the END of the id,
+// because mid-id `log` is the noun in domain phrases measured against real
+// fleets (`audit-log-in-range`, `change-log-out-of-band` are reads of a log,
+// while `shop-log-out` is a logout).
+const AUTH_DIRECTION_PAIRS: ReadonlyMap<
+	string,
+	{ directions: ReadonlySet<string>; endOnly: boolean }
+> = new Map([
+	["sign", { directions: new Set(["in", "out", "up"]), endOnly: false }],
+	["log", { directions: new Set(["in", "out"]), endOnly: true }],
+]);
+
+// Legacy anchored form kept for token-plumbing words whose bare use is only
+// auth-related when it leads the operation id (`exchange-code`, `refresh`).
 const AUTH_OPERATION_ID_PATTERN =
 	/^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
 
+function isAuthLifecycleOperationId(operationId: string, authMode: string): boolean {
+	const segments = operationId.toLowerCase().split(/[-_]+/).filter(Boolean);
+
+	if (segments.some((segment) => AUTH_LIFECYCLE_SEGMENT_WORDS.has(segment))) return true;
+
+	// A verb stem + direction spread across two segments (`sign-out`,
+	// `sign_up`, `shop-log-out`); see AUTH_DIRECTION_PAIRS for positioning.
+	if (
+		segments.some((segment, index) => {
+			const pair = AUTH_DIRECTION_PAIRS.get(segment);
+			if (pair === undefined || index + 1 >= segments.length) return false;
+			if (!pair.directions.has(segments[index + 1] as string)) return false;
+			return pair.endOnly ? index + 2 === segments.length : true;
+		})
+	) {
+		return true;
+	}
+
+	if (segments.length === 1 && AUTH_LIFECYCLE_WHOLE_ID_WORDS.has(segments[0] as string)) {
+		return true;
+	}
+
+	// The legacy anchored pattern keeps its original scope. It matches ordinary
+	// domain ids such as `exchange-rates` and `refresh-catalog`, so extending it
+	// to `oauth2_proxied` would spread that behavior to providers it never
+	// applied to; proxied providers are covered by the segment tiers above.
+	if (authMode === "credentials" || authMode === "oauth2") {
+		return AUTH_OPERATION_ID_PATTERN.test(operationId);
+	}
+
+	return false;
+}
+
 type ProviderContractMetaLike = {
 	publicSchemaFieldNames?: "normalized";
+	pinnedWireFieldPaths?: readonly {
+		readonly path: string;
+		readonly reason: string;
+	}[];
 };
 
 type SchemaLike = ZodType & {
@@ -55,6 +191,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>;
@@ -573,21 +720,6 @@ function collectSchemaDescriptionKeyDiagnostics(
 	return diagnostics;
 }
 
-function isComplexSchema(schema: unknown, seen = new Set<SchemaLike>()): boolean {
-	if (!isSchema(schema) || seen.has(schema)) {
-		return false;
-	}
-
-	seen.add(schema);
-	const children = getChildSchemas(schema);
-	const hasNestedComposite = children.some(({ schema: child }) => {
-		const childChildren = getChildSchemas(child);
-		return childChildren.length > 0;
-	});
-
-	return hasNestedComposite || children.some(({ schema: child }) => isComplexSchema(child, seen));
-}
-
 function hasBidirectionalFixtures(fixtures: unknown): boolean {
 	if (!fixtures || typeof fixtures !== "object") {
 		return true;
@@ -793,69 +925,460 @@ function lintSelfHostedBrowserPatterns(
 	return diagnostics;
 }
 
+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. Select the browser and OS structurally, for example stealth: { browser: "chrome", os: "macos" }.`;
+		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 structured profile, for example getStealthProfile({ browser: "chrome", os: "macos" }).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 stealth: { browser: "chrome", os: "macos" }; derive any explicit User-Agent with getStealthProfile({ browser: "chrome", os: "macos" }).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
+ * opening quote). Returns the index of the closing quote, or -1 when the
+ * literal is unterminated. Template literals handle nested `${...}`
+ * expressions, including strings inside them.
+ */
+function skipStringLiteral(source: string, startIndex: number): number {
+	const quote = source[startIndex];
+	for (let index = startIndex + 1; index < source.length; index++) {
+		const char = source[index];
+		if (char === "\\") {
+			index++;
+			continue;
+		}
+		if (quote === "`" && char === "$" && source[index + 1] === "{") {
+			index = skipTemplateExpression(source, index + 2);
+			if (index < 0) {
+				return -1;
+			}
+			continue;
+		}
+		if (char === quote) {
+			return index;
+		}
+		if (quote !== "`" && char === "\n") {
+			return -1;
+		}
+	}
+	return -1;
+}
+
+function skipTemplateExpression(source: string, startIndex: number): number {
+	let depth = 1;
+	for (let index = startIndex; index < source.length; index++) {
+		const char = source[index];
+		if (char === '"' || char === "'" || char === "`") {
+			index = skipStringLiteral(source, index);
+			if (index < 0) {
+				return -1;
+			}
+			continue;
+		}
+		if (char === "{") {
+			depth++;
+		} else if (char === "}") {
+			depth--;
+			if (depth === 0) {
+				return index;
+			}
+		}
+	}
+	return -1;
+}
+
+/**
+ * Extracts the argument text of a call whose opening paren has already been
+ * consumed (`startIndex` points just past it). Returns undefined when the
+ * call never closes in this source, which the caller treats as "skip
+ * silently" — this scanner is conservative by design.
+ */
+function extractBalancedCallArguments(source: string, startIndex: number): string | undefined {
+	let depth = 1;
+	for (let index = startIndex; index < source.length; index++) {
+		const char = source[index];
+		if (char === '"' || char === "'" || char === "`") {
+			index = skipStringLiteral(source, index);
+			if (index < 0) {
+				return undefined;
+			}
+			continue;
+		}
+		if (char === "/" && source[index + 1] === "/") {
+			const newline = source.indexOf("\n", index);
+			if (newline === -1) {
+				return undefined;
+			}
+			index = newline;
+			continue;
+		}
+		if (char === "/" && source[index + 1] === "*") {
+			const end = source.indexOf("*/", index + 2);
+			if (end === -1) {
+				return undefined;
+			}
+			index = end + 1;
+			continue;
+		}
+		if (char === "(") {
+			depth++;
+		} else if (char === ")") {
+			depth--;
+			if (depth === 0) {
+				return source.slice(startIndex, index);
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Collects literal string values of top-level `code:` properties inside a
+ * ProviderError/ValidationError options object. Only plain `"..."` / `'...'`
+ * literals at options-object depth count; computed codes (identifiers,
+ * ternaries, template substitutions, concatenations, escapes) are skipped
+ * silently so the rule never guesses.
+ */
+function collectLiteralErrorCodeValues(args: string): string[] {
+	const codes: string[] = [];
+	let braceDepth = 0;
+	let parenDepth = 0;
+	let bracketDepth = 0;
+	let previousSignificantChar = "";
+	for (let index = 0; index < args.length; index++) {
+		const char = args[index] ?? "";
+		if (char === '"' || char === "'" || char === "`") {
+			const end = skipStringLiteral(args, index);
+			if (end < 0) {
+				return codes;
+			}
+			index = end;
+			previousSignificantChar = char;
+			continue;
+		}
+		if (char === "/" && args[index + 1] === "/") {
+			const newline = args.indexOf("\n", index);
+			if (newline === -1) {
+				return codes;
+			}
+			index = newline;
+			continue;
+		}
+		if (char === "/" && args[index + 1] === "*") {
+			const end = args.indexOf("*/", index + 2);
+			if (end === -1) {
+				return codes;
+			}
+			index = end + 1;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			continue;
+		}
+		if (char === "{") {
+			braceDepth++;
+		} else if (char === "}") {
+			braceDepth--;
+		} else if (char === "(") {
+			parenDepth++;
+		} else if (char === ")") {
+			parenDepth--;
+		} else if (char === "[") {
+			bracketDepth++;
+		} else if (char === "]") {
+			bracketDepth--;
+		} else if (
+			braceDepth === 1 &&
+			parenDepth === 0 &&
+			bracketDepth === 0 &&
+			(previousSignificantChar === "{" || previousSignificantChar === ",") &&
+			args.startsWith("code", index)
+		) {
+			let cursor = index + "code".length;
+			while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+				cursor++;
+			}
+			if (args[cursor] === ":") {
+				cursor++;
+				while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+					cursor++;
+				}
+				const quote = args[cursor];
+				if (quote === '"' || quote === "'") {
+					const end = skipStringLiteral(args, cursor);
+					if (end > cursor) {
+						const value = args.slice(cursor + 1, end);
+						let after = end + 1;
+						while (after < args.length && /\s/.test(args[after] ?? "")) {
+							after++;
+						}
+						const nextChar = after < args.length ? (args[after] ?? "") : "";
+						if (!value.includes("\\") && (nextChar === "," || nextChar === "}" || nextChar === "")) {
+							codes.push(value);
+						}
+						index = end;
+						previousSignificantChar = quote;
+						continue;
+					}
+					return codes;
+				}
+			}
+		}
+		previousSignificantChar = char;
+	}
+	return codes;
+}
+
+function collectLiteralThrownErrorCodes(source: string): string[] {
+	const codes: string[] = [];
+	THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = 0;
+	for (
+		let match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source);
+		match;
+		match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source)
+	) {
+		const argsStart = match.index + match[0].length;
+		const args = extractBalancedCallArguments(source, argsStart);
+		if (args !== undefined) {
+			codes.push(...collectLiteralErrorCodeValues(args));
+		}
+		THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = argsStart;
+	}
+	return codes;
+}
+
+/**
+ * Static counterpart of the runtime `unregistered_provider_error_code`
+ * signal (honest-provider-error-contract Phase 3.5.5): flags
+ * `new ProviderError(...)` / `new ValidationError(...)` constructions whose
+ * literal `code` is neither SDK-registered (SDK_RUNTIME_OWNED_ERROR_CODES
+ * plus the canonical status-mapped codes shared with serve.ts toStatusCode)
+ * nor declared in any operation's errorCodes. At runtime such a code
+ * serves HTTP 500 and emits the signal; this rule surfaces it at check time.
+ *
+ * A throw site cannot be attributed to a specific operation statically —
+ * providers routinely throw from helpers shared across operations — so this
+ * rule matches against the provider-level union of declared codes. That is
+ * the honest scope: it will not catch a code declared only on the "wrong"
+ * operation, and it never claims per-operation attribution it cannot prove.
+ * Only literal string codes are checked; computed/dynamic codes and test
+ * sources are skipped silently. Warning level: the long tail of existing
+ * providers converges gradually, so this must not fail `apifuse check`.
+ */
+function lintUndeclaredThrownErrorCodes(provider: {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<
+		string,
+		{
+			handler?: unknown;
+			source?: string;
+			errorCodes?: ReadonlyArray<{ code: string }>;
+		}
+	>;
+}): LintDiagnostic[] {
+	const knownCodes = new Set<string>([
+		...SDK_RUNTIME_OWNED_ERROR_CODES,
+		...SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.keys(),
+	]);
+	for (const operation of Object.values(provider.operations ?? {})) {
+		for (const entry of operation.errorCodes ?? []) {
+			if (typeof entry?.code === "string") {
+				knownCodes.add(entry.code);
+			}
+		}
+	}
+
+	const sources: Array<{ field: string; source: string }> = [];
+	const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(
+		([filePath]) => !TEST_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 });
+			}
+		}
+	}
+
+	const diagnostics: LintDiagnostic[] = [];
+	for (const { field, source } of sources) {
+		const undeclaredCodes = new Set(
+			collectLiteralThrownErrorCodes(source).filter((code) => !knownCodes.has(code)),
+		);
+		for (const code of undeclaredCodes) {
+			diagnostics.push({
+				rule: "thrown-error-code-undeclared",
+				level: "warn",
+				field,
+				message: `Thrown error code "${code}" (${field}) is neither SDK-registered nor declared in any operation's errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's errorCodes with status and retryable.`,
+			});
+		}
+	}
+	return diagnostics;
+}
+
 export function lintOperation(op: {
-	description?: string;
 	descriptionKey?: string;
-	whenToUse?: readonly string[];
 	whenToUseKeys?: readonly string[];
-	whenNotToUse?: readonly string[];
 	whenNotToUseKeys?: readonly string[];
 	input: unknown;
 	output: unknown;
 	fixtures?: unknown;
-	inputExamples?: readonly unknown[];
-	derivations?: Record<string, string>;
 }): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [];
-	const description = op.description ?? "";
 	const hasDescriptionKey = typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
 
-	if (description.trim().length > 0 && !hasDescriptionKey) {
-		diagnostics.push({
-			rule: "operation-description-raw-prose",
-			level: "error",
-			field: "description",
-			message: "Operation description must use descriptionKey instead of raw static prose.",
-		});
-	}
-
-	if (!hasDescriptionKey && description.length < 150) {
-		diagnostics.push({
-			rule: "description-min-length",
-			level: "error",
-			field: "description",
-			message: "Operation description must be at least 150 characters.",
-		});
-	}
-
-	if ((op.whenToUse?.length ?? 0) > 0 && !(op.whenToUseKeys?.length ?? 0)) {
-		diagnostics.push({
-			rule: "operation-when-to-use-raw-prose",
-			level: "error",
-			field: "whenToUse",
-			message: "Operation whenToUse must use whenToUseKeys instead of raw static prose.",
-		});
-	}
-
-	if ((op.whenNotToUse?.length ?? 0) > 0 && !(op.whenNotToUseKeys?.length ?? 0)) {
+	if (!hasDescriptionKey) {
 		diagnostics.push({
-			rule: "operation-when-not-to-use-raw-prose",
+			rule: "description-key-required",
 			level: "error",
-			field: "whenNotToUse",
-			message: "Operation whenNotToUse must use whenNotToUseKeys instead of raw static prose.",
-		});
-	}
-
-	const lowerDescription = description.toLowerCase();
-	if (
-		!hasDescriptionKey &&
-		!(lowerDescription.includes("use") && lowerDescription.includes("when"))
-	) {
-		diagnostics.push({
-			rule: "description-has-when-clause",
-			level: "warn",
-			field: "description",
-			message: 'Operation description should include both "use" and "when".',
+			field: "descriptionKey",
+			message: "Operation must declare a locale-backed descriptionKey.",
 		});
 	}
 
@@ -873,15 +1396,6 @@ export function lintOperation(op: {
 		});
 	}
 
-	if (isComplexSchema(op.input) && (op.inputExamples?.length ?? 0) < 2) {
-		diagnostics.push({
-			rule: "complex-input-has-examples",
-			level: "warn",
-			field: "inputExamples",
-			message: "Complex input schemas should provide at least 2 input examples.",
-		});
-	}
-
 	for (const field of uniqueFields(collectUnmarkedSensitiveFields(op.input, "input"))) {
 		diagnostics.push({
 			rule: "sensitive-field-unmarked",
@@ -903,6 +1417,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;
@@ -922,19 +1497,18 @@ export function lintProvider(
 		operations?: Record<
 			string,
 			{
-				description?: string;
 				descriptionKey?: string;
-				whenToUse?: readonly string[];
 				whenToUseKeys?: readonly string[];
-				whenNotToUse?: readonly string[];
 				whenNotToUseKeys?: readonly string[];
+				connectionMode?: "none" | "optional" | "required";
+				riskClass?: OperationRiskClass;
+				approval?: OperationApprovalPolicy;
 				input: unknown;
 				output: unknown;
 				fixtures?: unknown;
-				inputExamples?: readonly unknown[];
-				derivations?: Record<string, string>;
 				handler?: unknown;
 				source?: string;
+				errorCodes?: ReadonlyArray<{ code: string }>;
 			}
 		>;
 		meta?: {
@@ -944,6 +1518,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),
@@ -952,18 +1534,49 @@ export function lintProvider(
 		...lintCredentialWriteUsage(provider),
 		...lintPlaywrightDirectImports(provider),
 		...lintSelfHostedBrowserPatterns(provider, options),
+		...lintBrowserVersionLiterals(provider),
+		...lintUndeclaredThrownErrorCodes(provider),
 	];
 
 	if (provider.operations) {
 		const authMode = provider.auth?.mode;
-		if (authMode === "credentials" || authMode === "oauth2") {
+		for (const [operationKey, operation] of Object.entries(provider.operations)) {
+			if (isCredentialBearingAuthMode(authMode) && operation.connectionMode === undefined) {
+				diagnostics.push({
+					rule: "mixed-auth-connection-mode-required",
+					level: "error",
+					field: `operations.${operationKey}.connectionMode`,
+					message: `Provider "${provider.id ?? "unknown"}" uses credential-bearing auth.mode "${authMode}"; operation "${operationKey}" must declare connectionMode explicitly.`,
+				});
+			}
+			if (
+				operation.riskClass !== undefined &&
+				operation.approval !== undefined &&
+				operation.approval === defaultApprovalPolicy(operation.riskClass)
+			) {
+				diagnostics.push({
+					rule: "redundant-approval",
+					level: "error",
+					field: `operations.${operationKey}.approval`,
+					message: `Operation "${operationKey}" approval "${operation.approval}" repeats the default for riskClass "${operation.riskClass}"; omit approval unless it is a deliberate override.`,
+				});
+			}
+		}
+		// Every authenticated mode owns an auth.flow; `oauth2_proxied` was
+		// previously exempt, which let auth-lifecycle operations ship on
+		// proxied providers unchecked.
+		if (
+			authMode === "credentials" ||
+			authMode === "oauth2" ||
+			authMode === "oauth2_proxied"
+		) {
 			for (const operationKey of Object.keys(provider.operations)) {
-				if (AUTH_OPERATION_ID_PATTERN.test(operationKey)) {
+				if (isAuthLifecycleOperationId(operationKey, authMode)) {
 					diagnostics.push({
 						rule: "auth-operation-unsupported",
 						level: "error",
 						field: `operations.${operationKey}`,
-						message: `Provider "${provider.id ?? "unknown"}" operation "${operationKey}" looks like a login/token/session exchange endpoint. Authenticated providers must expose login through the single auth.flow interface because Gateway persists only auth.flow complete turn data.credential as the connection credential. Move this logic into auth.flow.continue instead of a provider operation.`,
+						message: `Provider "${provider.id ?? "unknown"}" operation "${operationKey}" performs an auth-lifecycle action (login, logout, token exchange or similar). Authenticated providers must expose the whole credential lifecycle through the single auth.flow interface because Gateway persists only auth.flow complete turn data.credential as the connection credential, and an operation that mutates the session outside that interface leaves the stored connection stale. Move sign-in logic into auth.flow.start/continue and sign-out/disconnect logic into auth.flow.abort (served by POST /auth/disconnect) instead of a provider operation.`,
 					});
 				}
 			}
@@ -971,24 +1584,19 @@ export function lintProvider(
 	}
 
 	if (!provider.operations) {
-		return diagnostics;
+		return applyPinnedWireFieldPaths(provider, diagnostics);
 	}
 
 	diagnostics.push(
 		...Object.entries(provider.operations).flatMap(([operationKey, operation]) =>
 			[
 				...lintOperation({
-					description: operation.description ?? "",
 					descriptionKey: operation.descriptionKey,
-					whenToUse: operation.whenToUse,
 					whenToUseKeys: operation.whenToUseKeys,
-					whenNotToUse: operation.whenNotToUse,
 					whenNotToUseKeys: operation.whenNotToUseKeys,
 					input: operation.input,
 					output: operation.output,
 					fixtures: operation.fixtures,
-					inputExamples: operation.inputExamples,
-					derivations: operation.derivations,
 				}),
 				...lintPublicSchemaFieldNames(
 					provider.id,
@@ -1007,5 +1615,5 @@ export function lintProvider(
 		),
 	);
 
-	return diagnostics;
+	return applyPinnedWireFieldPaths(provider, diagnostics);
 }