@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/bin/apifuse-submit-check.ts

@@ -11,15 +11,22 @@ import * as acorn from "acorn";
 import { z } from "zod";
 
 import packageJson from "../package.json";
-import type { ProviderDefinition } from "../src";
+import { formatPromptAssetIssues, verifyPromptAssets } from "../src/cli/prompt-assets.js";
 import {
 	loadProviderLocaleCatalogs,
 	type ProviderLocale,
 	validateProviderLocaleCatalogs,
-} from "../src/i18n";
-import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema";
-import { safeParseSchemaSync } from "../src/schema";
-import { type CheckResult, runChecks } from "./apifuse-check";
+} from "../src/i18n/index.js";
+import type { ProviderDefinition } from "../src/index.js";
+import { APIFUSE_DESCRIPTION_KEY_META_KEY, safeParseSchemaSync } from "../src/schema.js";
+import {
+	findStreamCaptureGroup,
+	hasStreamEvidenceMarker,
+	parseStreamEvidenceRecord,
+} from "../src/stream-evidence.js";
+import { type CheckResult, PROMPT_ASSETS_CHECK_MESSAGE, runChecks } from "./apifuse-check.js";
+import { hasSubstantiveDelimitedTextStructure } from "./submit-check-delimited-text.js";
+import { hasSubstantiveXmlStructure } from "./submit-check-xml.js";
 
 const TIERS = ["bronze", "silver", "gold", "diamond"] as const;
 const TIER_VALUES: ReadonlySet<string> = new Set(TIERS);
@@ -266,7 +273,15 @@ export async function buildSubmitCheckReport(
 	const baseChecks = await safeRunChecks(providerRoot);
 	const provider = await safeLoadProvider(providerRoot);
 
-	checks.push(...scoreBaseChecks(baseChecks));
+	// Prompt-asset freshness is reported by its own dedicated zero-point
+	// blocker below; filter the base-check duplicate so it is not double
+	// penalized under the definition category.
+	checks.push(
+		...scoreBaseChecks(
+			baseChecks.filter((result) => result.message !== PROMPT_ASSETS_CHECK_MESSAGE),
+		),
+	);
+	checks.push(scorePromptAssetFreshness(providerRoot));
 	checks.push(scoreProviderIdSlug(providerRoot, provider));
 	checks.push(scoreNoVendorShim(providerRoot));
 	checks.push(scoreNoVendorImport(providerRoot));
@@ -282,6 +297,7 @@ export async function buildSubmitCheckReport(
 	if (provider) {
 		const smokeResult = args.smoke ? await runSubmitCheckSmoke(providerRoot, provider) : undefined;
 		checks.push(scoreCredentialUsage(providerRoot, provider));
+		checks.push(scoreSdkOwnedSecretPresence(providerRoot, provider));
 		checks.push(scoreLocaleCatalog(providerRoot, provider));
 		checks.push(scoreOperationMetadata(provider));
 		checks.push(scoreFixtureCoverage(provider));
@@ -1423,6 +1439,159 @@ function scoreCredentialUsage(providerRoot: string, provider: ProviderDefinition
 	);
 }
 
+// ---------------------------------------------------------------------------
+// sdk-owned-secret-presence (warn): provider-local double validation of
+// declared env secrets.
+//
+// The SDK runtime is the single source of truth for secret presence: declared
+// `required: true` secrets are validated before every handler/auth-flow
+// invocation and fail with the canonical structured MISSING_SECRET error
+// (HTTP 400, category credential_unavailable). Provider-local presence guards
+// (requireServiceKey/requireApiKey style) are dead weight that historically
+// diverged into inconsistent shapes (CONFIGURATION_ERROR vs MISSING_SECRET,
+// with/without category), which broke uniform incident attribution when nine
+// providers shipped with unprovisioned secrets (2026-07-22).
+//
+// Heuristic, warn-only: a line reading a declared `required: true` secret via
+// `.env.get(...)` (string literal or a const alias of a declared name)
+// followed within a small window by a falsy presence check plus a `throw`.
+// The rule flags duplication of the SDK gate ONLY: env names that are not
+// declared in defineProvider secrets[], and optional declarations
+// (`required: false`/omitted) that the runtime deliberately does not enforce,
+// are out of scope. Escape hatch:
+// `// @apifuse-allow sdk-owned-secret-presence: <reason>`.
+// ---------------------------------------------------------------------------
+
+const SDK_OWNED_SECRET_PRESENCE_RULE_ID = "sdk-owned-secret-presence";
+const SECRET_PRESENCE_GUARD_LOOKAHEAD_LINES = 10;
+
+const ENV_GET_CALL_PATTERN =
+	/\.env\.get\(\s*(?:"([^"]+)"|'([^']+)'|`([^`$]+)`|([A-Za-z_$][\w$]*))\s*\)/;
+
+const SECRET_ALIAS_CONST_PATTERN =
+	/\bconst\s+([A-Za-z_$][\w$]*)\s*=\s*(?:"([^"]+)"|'([^']+)'|`([^`$]+)`)/g;
+
+const ENV_GET_ASSIGNMENT_PATTERN = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=[^;]*\.env\.get\(/;
+
+// Const aliases of declared secret names (e.g. `const SERVICE_KEY_ENV =
+// "APIFUSE__PROVIDER__X__SERVICE_KEY"`) so aliased `.env.get(SERVICE_KEY_ENV)`
+// guards are detected, not just direct string literals.
+function buildDeclaredSecretAliasMap(
+	providerRoot: string,
+	declaredNames: ReadonlySet<string>,
+): Map<string, string> {
+	const aliases = new Map<string, string>();
+	for (const filePath of listNonTestTypeScriptFiles(providerRoot)) {
+		const content = readFileSync(filePath, "utf8");
+		for (const match of content.matchAll(SECRET_ALIAS_CONST_PATTERN)) {
+			const alias = match[1];
+			const name = match[2] ?? match[3] ?? match[4];
+			if (alias && name && declaredNames.has(name)) {
+				aliases.set(alias, name);
+			}
+		}
+	}
+	return aliases;
+}
+
+function hasLocalSecretPresenceGuard(
+	line: string,
+	remainingLines: readonly string[],
+	declaredNames: ReadonlySet<string>,
+	aliases: ReadonlyMap<string, string>,
+): boolean {
+	const match = ENV_GET_CALL_PATTERN.exec(line);
+	if (!match) {
+		return false;
+	}
+	const literal = match[1] ?? match[2] ?? match[3];
+	const identifier = match[4];
+	const readsDeclaredSecret =
+		literal !== undefined
+			? declaredNames.has(literal)
+			: identifier !== undefined && aliases.has(identifier);
+	if (!readsDeclaredSecret) {
+		return false;
+	}
+
+	const window = [line, ...remainingLines.slice(0, SECRET_PRESENCE_GUARD_LOOKAHEAD_LINES)];
+	if (!window.some((candidate) => /\bthrow\b/.test(candidate))) {
+		return false;
+	}
+
+	// Assigned read (`const key = ctx.env.get(...)`): only a falsy/undefined
+	// check on THAT variable counts as a presence guard. Anchoring on the
+	// assigned identifier avoids false positives from unrelated guards/throws
+	// that merely sit near the env read (mirrors the aliased runtime-guard rule).
+	const assigned = ENV_GET_ASSIGNMENT_PATTERN.exec(line)?.[1];
+	if (assigned) {
+		const escaped = assigned.replace(/\$/g, "\\$");
+		const guardPattern = new RegExp(
+			`(?:!\\s*${escaped}\\b|\\b${escaped}\\s*===?\\s*(?:undefined|null)\\b|\\b${escaped}\\s*==\\s*null\\b|\\b${escaped}(?:\\?\\.|\\.)length\\s*===?\\s*0\\b)`,
+		);
+		return window.some((candidate) => guardPattern.test(candidate));
+	}
+
+	// Un-assigned read: only an inline presence check on the same line counts,
+	// e.g. `if (!ctx.env.get(KEY)) throw ...`.
+	return /(?:if\s*\(\s*!|===?\s*undefined\b|==\s*null\b)/.test(line);
+}
+
+function scoreSdkOwnedSecretPresence(
+	providerRoot: string,
+	provider: ProviderDefinition,
+): SubmitCheck {
+	const passMessage = "Provider relies on SDK-owned secret presence validation.";
+	// Only `required: true` declarations: those are exactly what the runtime
+	// gate enforces. A presence guard over an optional secret is conditional
+	// business logic the SDK will not replace, not double validation.
+	const declaredNames: ReadonlySet<string> = new Set(
+		(provider.secrets ?? [])
+			.filter((secret) => secret.required === true)
+			.map((secret) => secret.name),
+	);
+	if (declaredNames.size === 0) {
+		return pass(SDK_OWNED_SECRET_PRESENCE_RULE_ID, SDK_NATIVE_CATEGORY, passMessage, 0);
+	}
+
+	const aliases = buildDeclaredSecretAliasMap(providerRoot, declaredNames);
+	const findings = findSourceFindings(providerRoot, (line, remainingLines) =>
+		hasLocalSecretPresenceGuard(line, remainingLines, declaredNames, aliases),
+	);
+	if (findings.length === 0) {
+		return pass(SDK_OWNED_SECRET_PRESENCE_RULE_ID, SDK_NATIVE_CATEGORY, passMessage, 0);
+	}
+
+	const { violations, overridden } = partitionAllowOverrides(
+		providerRoot,
+		findings,
+		SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+	);
+	if (violations.length === 0) {
+		return pass(
+			SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+			SDK_NATIVE_CATEGORY,
+			`${passMessage} ${overridden.length} acknowledged @apifuse-allow override(s).`,
+			0,
+			formatSourceFindings(overridden),
+		);
+	}
+
+	return {
+		id: SDK_OWNED_SECRET_PRESENCE_RULE_ID,
+		category: SDK_NATIVE_CATEGORY,
+		level: "warn",
+		status: "warn",
+		points: 0,
+		maxPoints: 0,
+		message:
+			"Provider source re-validates declared env secret presence locally; the SDK owns this check.",
+		remediation:
+			"The provider SDK validates declared required secrets before handlers and auth flows run and returns the canonical MISSING_SECRET error (HTTP 400, category credential_unavailable). Declare the secret with required: true in defineProvider({ secrets: [...] }), delete the provider-local presence guard (requireServiceKey/requireApiKey style), and read the value directly with ctx.env.get(); the guard is dead weight and its divergent CONFIGURATION_ERROR-style shape is deprecated. Acknowledge intentional exceptions with `// @apifuse-allow sdk-owned-secret-presence: <reason>`.",
+		evidence: formatSourceFindings(violations),
+	};
+}
+
 function findSourceLineMatches(
 	providerRoot: string,
 	pattern: RegExp | ((line: string) => boolean),
@@ -1522,6 +1691,10 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+// `.agents`/`.apifuse` stay IN scope on purpose: managed content there is
+// markdown/JSON (never scannable), while a planted `.ts`/`.sh` under those
+// directories must not become a scan-exempt hiding place for secrets, raw
+// fetch, or vendor imports.
 function shouldScanSourceDirectory(relativePath: string): boolean {
 	return ![".git", "node_modules", "dist", "build", "coverage"].includes(relativePath);
 }
@@ -1544,6 +1717,27 @@ function formatSourceFindings(findings: readonly SourceFinding[]): string[] {
 	return findings.map((finding) => `${finding.file}:${finding.line}`);
 }
 
+function scorePromptAssetFreshness(providerRoot: string): SubmitCheck {
+	const verification = verifyPromptAssets(providerRoot);
+	if (verification.ok) {
+		return pass(
+			"prompt-assets-fresh",
+			"docs",
+			"SDK-managed agent prompt assets match the installed SDK version.",
+			0,
+		);
+	}
+
+	return blocker(
+		"prompt-assets-fresh",
+		"docs",
+		"SDK-managed agent prompt assets are missing, stale, or modified.",
+		"Run `bun run sync-assets` (or `bunx apifuse sync-assets .`) to regenerate AGENTS.md, .agents/skills/**, the CLAUDE.md/.claude/.codex symlinks, and .apifuse/prompt-assets.json for the installed SDK version.",
+		0,
+		formatPromptAssetIssues(verification),
+	);
+}
+
 function scoreRepositoryDx(providerRoot: string): SubmitCheck {
 	const missing: string[] = [];
 	if (!existsSync(resolve(providerRoot, ".gitignore"))) {
@@ -1979,17 +2173,19 @@ function scoreFixtureCoverage(provider: ProviderDefinition): SubmitCheck {
 
 const GENERATED_LOCAL_ONLY_SCAFFOLD_REASON = /generated local-only scaffold/i;
 
-function scoreFixtureProvenance(
-	providerRoot: string,
-	provider: ProviderDefinition,
-): SubmitCheck {
+function scoreFixtureProvenance(providerRoot: string, provider: ProviderDefinition): SubmitCheck {
 	const rawPath = resolve(providerRoot, "__fixtures__", "raw.json");
 	let hasRecordedEvidence = false;
+	let fixtureValidationError: string | undefined;
 	if (existsSync(rawPath)) {
 		try {
-			hasRecordedEvidence = hasNonEmptyRecordedFixture(JSON.parse(readFileSync(rawPath, "utf8")));
-		} catch {
+			hasRecordedEvidence = recordedFixtureStats(
+				JSON.parse(readFileSync(rawPath, "utf8")),
+				0,
+			).hasNestedSubstance;
+		} catch (error) {
 			hasRecordedEvidence = false;
+			fixtureValidationError = error instanceof Error ? error.message : String(error);
 		}
 	}
 
@@ -2001,6 +2197,16 @@ function scoreFixtureProvenance(
 			0,
 		);
 	}
+	if (fixtureValidationError) {
+		return blocker(
+			"fixture-provenance",
+			"fixtures",
+			`Malformed recorded fixture evidence in __fixtures__/raw.json: ${fixtureValidationError}`,
+			"Re-run `bun run record` to replace the malformed stream evidence, or repair the named field using the stream evidence contract.",
+			0,
+			["__fixtures__/raw.json"],
+		);
+	}
 
 	if (allOperationsAreGeneratedLocalScaffold(provider)) {
 		return {
@@ -2028,14 +2234,32 @@ function scoreFixtureProvenance(
 	);
 }
 
-function hasNonEmptyRecordedFixture(value: unknown): boolean {
-	return recordedFixtureStats(value, 0).hasNestedSubstance;
+export function hasNonEmptyRecordedFixture(value: unknown): boolean {
+	try {
+		return recordedFixtureStats(value, 0).hasNestedSubstance;
+	} catch {
+		return false;
+	}
 }
 
 function recordedFixtureStats(
 	value: unknown,
 	depth: number,
 ): { hasNestedSubstance: boolean; leafValues: number } {
+	if (
+		value !== null &&
+		typeof value === "object" &&
+		!Array.isArray(value) &&
+		(value as Record<string, unknown>).__apifuse_capture__ === true
+	) {
+		const group = findStreamCaptureGroup(value);
+		if (!group) throw new Error("Stream capture envelope is invalid.");
+		return { hasNestedSubstance: true, leafValues: group.items.length };
+	}
+	if (hasStreamEvidenceMarker(value)) {
+		parseStreamEvidenceRecord(value);
+		return { hasNestedSubstance: true, leafValues: 1 };
+	}
 	if (value === null || value === undefined) {
 		return { hasNestedSubstance: false, leafValues: 0 };
 	}
@@ -2066,8 +2290,18 @@ function recordedFixtureStats(
 			leafValues,
 		};
 	}
-	if (typeof value === "string" && value.length === 0) {
-		return { hasNestedSubstance: false, leafValues: 0 };
+	if (typeof value === "string") {
+		if (value.length === 0) {
+			return { hasNestedSubstance: false, leafValues: 0 };
+		}
+		// A recorded operation value may be a raw XML or delimited-text success
+		// payload. Treat a substantive one as nested evidence while still counting
+		// the string as a leaf so existing JSON provenance heuristics are unchanged.
+		return {
+			hasNestedSubstance:
+				hasSubstantiveXmlStructure(value) || hasSubstantiveDelimitedTextStructure(value),
+			leafValues: 1,
+		};
 	}
 	return { hasNestedSubstance: false, leafValues: 1 };
 }
@@ -2083,12 +2317,17 @@ function allOperationsAreGeneratedLocalScaffold(provider: ProviderDefinition): b
 }
 
 function scoreVendorKeyLeak(providerRoot: string): SubmitCheck {
-	return escapeHatchResult(providerRoot, "vendor-key-leak", findVendorKeyLeakFindings(providerRoot), {
-		blockerMessage: "Public schema keys leak raw vendor field names.",
-		remediation:
-			"Normalize public request/response fields to APIFuse-standard lowerCamelCase names (e.g. isOpen24h, latitude); keep raw vendor keys only in upstream-parsing schemas (const upstream... = z.object(...)). Add `// @apifuse-allow vendor-key-leak` only with a comment explaining why the vendor name is genuinely canonical.",
-		passMessage: "No vendor field-name leaks detected in public schemas.",
-	});
+	return escapeHatchResult(
+		providerRoot,
+		"vendor-key-leak",
+		findVendorKeyLeakFindings(providerRoot),
+		{
+			blockerMessage: "Public schema keys leak raw vendor field names.",
+			remediation:
+				"Normalize public request/response fields to APIFuse-standard lowerCamelCase names (e.g. isOpen24h, latitude); keep raw vendor keys only in upstream-parsing schemas (const upstream... = z.object(...)). Add `// @apifuse-allow vendor-key-leak` only with a comment explaining why the vendor name is genuinely canonical.",
+			passMessage: "No vendor field-name leaks detected in public schemas.",
+		},
+	);
 }
 
 function scoreVendorTimestampLeak(providerRoot: string): SubmitCheck {
@@ -2191,26 +2430,57 @@ function vendorKeyFindingsForObject(
 	const keys = collectTopLevelObjectKeys(source, zObject.objectStart, zObject.objectEnd);
 	const digitFamilies = new Map<string, Set<string>>();
 	for (const key of keys) {
-		const digitMatch = /^([a-z][a-zA-Z]*)(\d+)[a-z]*$/i.exec(key.name);
-		if (!digitMatch?.[1] || !digitMatch[2]) {
+		const member = numberedFamilyMember(key.name);
+		if (!member) {
 			continue;
 		}
-		const digits = digitFamilies.get(digitMatch[1]) ?? new Set<string>();
-		digits.add(digitMatch[2]);
-		digitFamilies.set(digitMatch[1], digits);
+		const positions = digitFamilies.get(member.base) ?? new Set<string>();
+		positions.add(member.position);
+		digitFamilies.set(member.base, positions);
 	}
 
 	return keys
 		.filter((key) => {
-			if (!/^[a-z][a-zA-Z0-9]*$/.test(key.name)) {
+			if (!isAllowedPublicOutputKeyName(key.name)) {
 				return true;
 			}
-			const digitMatch = /^([a-z][a-zA-Z]*)(\d+)[a-z]*$/i.exec(key.name);
-			return digitMatch?.[1] !== undefined && (digitFamilies.get(digitMatch[1])?.size ?? 0) >= 3;
+			const member = numberedFamilyMember(key.name);
+			return member !== null && (digitFamilies.get(member.base)?.size ?? 0) >= 3;
 		})
 		.map((key) => ({ key: key.name, line: offsetToLine(source, key.offset) }));
 }
 
+// A numbered vendor family is a base name plus a numeric position and an
+// optional trailing letter suffix, in either compact/camel form (sensor1,
+// duty1s) or semantic snake_case form (sensor_1, duty_time_1s). Both styles
+// normalize to the same { base, position } so a family of >=3 distinct
+// positions is caught regardless of which naming style the vendor leaked
+// through. Returns null for names that carry no numeric position.
+function numberedFamilyMember(name: string): { base: string; position: string } | null {
+	const camelMatch = /^([a-z][a-zA-Z]*)(\d+)[a-z]*$/i.exec(name);
+	if (camelMatch?.[1] && camelMatch[2]) {
+		return { base: camelMatch[1], position: camelMatch[2] };
+	}
+	const snakeMatch = /^([a-z][a-z0-9]*(?:_[a-z0-9]+)*?)_(\d+)[a-z]*$/.exec(name);
+	if (snakeMatch?.[1] && snakeMatch[2]) {
+		return { base: snakeMatch[1], position: snakeMatch[2] };
+	}
+	return null;
+}
+
+// Public output keys may use APIFuse lowerCamelCase (isOpen24h, latitude) or
+// semantic snake_case (pharmacy_id, weekly_hours, total_count, scan_exhausted).
+// Both are normalized, human-authored names. Raw vendor keys leak through mixed
+// case or uppercase acronyms (MKioskTy) and match neither, so they stay flagged.
+// Numbered vendor families still pass this name gate in either style
+// (sensor1/2/3 or sensor_1/sensor_2/sensor_3), so they are caught separately by
+// the >=3-member numberedFamilyMember check in vendorKeyFindingsForObject.
+function isAllowedPublicOutputKeyName(name: string): boolean {
+	const isLowerCamelCase = /^[a-z][a-zA-Z0-9]*$/.test(name);
+	const isSemanticSnakeCase = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/.test(name);
+	return isLowerCamelCase || isSemanticSnakeCase;
+}
+
 function collectTopLevelObjectKeys(
 	source: string,
 	objectStart: number,
@@ -2244,9 +2514,7 @@ function collectTopLevelObjectKeys(
 			if (computedQuote === '"' || computedQuote === "'") {
 				const literalEnd = findStringEnd(source, literalStart);
 				const afterLiteral =
-					literalEnd === -1
-						? -1
-						: skipWhitespaceAndComments(masked, literalEnd + 1, computedEnd);
+					literalEnd === -1 ? -1 : skipWhitespaceAndComments(masked, literalEnd + 1, computedEnd);
 				if (literalEnd !== -1 && afterLiteral === computedEnd) {
 					key = source.slice(literalStart + 1, literalEnd);
 				}
@@ -2364,8 +2632,13 @@ function findNamedConstValueRanges(source: string): NamedObjectRange[] {
 	return ranges;
 }
 
-function findConstValueRangeContaining(source: string, offset: number): NamedObjectRange | undefined {
-	return findNamedConstValueRanges(source).find((range) => offset >= range.start && offset <= range.end);
+function findConstValueRangeContaining(
+	source: string,
+	offset: number,
+): NamedObjectRange | undefined {
+	return findNamedConstValueRanges(source).find(
+		(range) => offset >= range.start && offset <= range.end,
+	);
 }
 
 function findStringLiteralsInRange(
@@ -3503,9 +3776,47 @@ function scoreProviderDocs(providerRoot: string): SubmitCheck[] {
 	];
 }
 
+// Splits secret findings into still-active findings and acknowledged
+// `// @apifuse-allow secret-scan` overrides, mirroring partitionAllowOverrides
+// (same pragma placement: the finding line or the line directly above it).
+// Every finding source carries a line number (entropy candidates and located
+// SECRET_PATTERNS matches); a finding that somehow lacks one stays active
+// defensively.
+function partitionSecretScanAllowOverrides(
+	providerRoot: string,
+	findings: readonly SecretFinding[],
+): { active: SecretFinding[]; overridden: SecretFinding[] } {
+	const fileLineCache = new Map<string, string[]>();
+	const active: SecretFinding[] = [];
+	const overridden: SecretFinding[] = [];
+
+	for (const finding of findings) {
+		if (finding.line === undefined) {
+			active.push(finding);
+			continue;
+		}
+		const absolute = resolve(providerRoot, finding.file);
+		let lines = fileLineCache.get(absolute);
+		if (lines === undefined) {
+			lines = existsSync(absolute) ? readFileSync(absolute, "utf8").split(/\r?\n/) : [];
+			fileLineCache.set(absolute, lines);
+		}
+		if (hasAllowOverride(lines, finding.line, "secret-scan")) {
+			overridden.push(finding);
+		} else {
+			active.push(finding);
+		}
+	}
+
+	return { active, overridden };
+}
+
 function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): SubmitCheck {
-	const findings = findSecretFindings(providerRoot, provider?.id);
-	const blockerFindings = findings.filter((finding) => finding.level !== "warn");
+	const { active, overridden } = partitionSecretScanAllowOverrides(
+		providerRoot,
+		findSecretFindings(providerRoot, provider?.id),
+	);
+	const blockerFindings = active.filter((finding) => finding.level !== "warn");
 	if (blockerFindings.length > 0) {
 		return {
 			id: "secret-scan",
@@ -3525,7 +3836,15 @@ function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): Subm
 			),
 		};
 	}
-	if (findings.length > 0) {
+	if (active.length > 0 || overridden.length > 0) {
+		const messageBase =
+			active.length > 0
+				? "High-entropy source strings were found without secret-like identifier context; they may be false positives."
+				: "Potential credential-like strings were found in shareable files.";
+		const message =
+			overridden.length > 0
+				? `${messageBase} ${overridden.length} acknowledged @apifuse-allow override(s).`
+				: messageBase;
 		return {
 			id: "secret-scan",
 			category: "security",
@@ -3533,11 +3852,10 @@ function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): Subm
 			status: "warn",
 			points: 8,
 			maxPoints: CATEGORY_MAX_POINTS.security,
-			message:
-				"High-entropy source strings were found without secret-like identifier context; they may be false positives.",
+			message,
 			remediation:
-				'Review the listed strings. If any are credentials, move them to env vars read via `ctx.env.get("APIFUSE__PROVIDER__<ID>__<NAME>")` and rotate the leaked credential; otherwise keep generated blobs in fixtures/tests or document why they are public.',
-			evidence: findings.map(
+				'Review the listed strings. If any are credentials, move them to env vars read via `ctx.env.get("APIFUSE__PROVIDER__<ID>__<NAME>")` and rotate the leaked credential; otherwise keep generated blobs in fixtures/tests or document why they are public with `// @apifuse-allow secret-scan: <reason>`.',
+			evidence: [...active, ...overridden].map(
 				(finding) =>
 					finding.evidence ??
 					`${finding.file}${finding.line ? `:${finding.line}` : ""}: ${finding.label}`,
@@ -3568,8 +3886,19 @@ function findSecretFindings(providerRoot: string, providerId = "<ID>"): SecretFi
 		if (!existsSync(filePath)) continue;
 		const content = readFileSync(filePath, "utf8");
 		for (const [label, pattern] of SECRET_PATTERNS) {
-			if (pattern.test(content)) {
-				findings.push({ label, file: relativePath });
+			// Locate every match to its line so pattern findings carry the line
+			// information hasAllowOverride needs: `// @apifuse-allow secret-scan`
+			// must behave uniformly across entropy findings and pattern findings.
+			const globalPattern = new RegExp(
+				pattern.source,
+				pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`,
+			);
+			const seenLines = new Set<number>();
+			for (const match of content.matchAll(globalPattern)) {
+				const line = offsetToLine(content, match.index);
+				if (seenLines.has(line)) continue;
+				seenLines.add(line);
+				findings.push({ label, file: relativePath, line });
 			}
 		}
 	}
@@ -3627,7 +3956,7 @@ export function extractStringLiteralCandidates(line: string): string[] {
 				continue;
 			}
 			if (char === quote) {
-				if (cursor - contentStart >= 20) {
+				if (cursor - contentStart >= ENTROPY_CANDIDATE_MIN_LENGTH) {
 					candidates.push(line.slice(contentStart, cursor));
 				}
 				index = cursor;
@@ -3652,6 +3981,25 @@ function classifyEntropyCandidate(input: {
 	if (!charset) return undefined;
 	const entropy = shannonEntropy(value);
 	const secretishContext = SECRETISH_IDENTIFIER_PATTERN.test(input.line);
+	// Word-like SCREAMING_SNAKE values (e.g. error-code constants such as
+	// "AUTH_PASSWORD_LOGIN_CAPTCHA_REQUIRED") may contain secret-ish words
+	// (AUTH/PASSWORD/...) in their own text and would otherwise be permanently
+	// blocker-flagged. They are never skipped — entropy classification always
+	// runs — but when the secret-ish context comes solely from identifier-
+	// constant-shaped literal text (the line with those literals stripped
+	// carries no secret-ish identifier), the finding is capped at a
+	// non-blocking warning instead of a blocker. Stripping constant-shaped
+	// siblings — not just the candidate — matters for lines holding several
+	// constants (e.g. an ERROR_CODES array), while quoted property keys and
+	// header names ("Authorization", "apiKey") stay visible as genuine
+	// external context. Assignments to `apiKey`/`token`/`secret`-style names
+	// still escalate to blockers via the identifier side, and
+	// `// @apifuse-allow secret-scan` remains the reviewed way to silence the
+	// warning.
+	const selfContextOnlyConstant =
+		secretishContext &&
+		isScreamingSnakeConstantValue(value) &&
+		!SECRETISH_IDENTIFIER_PATTERN.test(stripIdentifierConstantLiterals(input.line, value));
 	const threshold = charset === "hex" ? 3.0 : secretishContext ? 4.0 : 4.5;
 	if (entropy < threshold) return undefined;
 
@@ -3662,16 +4010,161 @@ function classifyEntropyCandidate(input: {
 		charset === "hex"
 			? `high-entropy hex string (${entropy.toFixed(2)} bits/char)`
 			: `high-entropy base64-like string (${entropy.toFixed(2)} bits/char)`;
+	const contextNote = selfContextOnlyConstant
+		? "; identifier-like constant (downgraded to warning)"
+		: secretishContext
+			? ""
+			: "; may be a false positive";
 	return {
 		label,
 		file: input.file,
 		line: input.lineNumber,
-		level: secretishContext ? "blocker" : "warn",
+		level: secretishContext && !selfContextOnlyConstant ? "blocker" : "warn",
 		remediation: `Move ${location} to an env var read via \`ctx.env.get("${envName}")\` and rotate the leaked credential.`,
-		evidence: `${location}: ${label}; preview ${preview}${secretishContext ? "" : "; may be a false positive"}`,
+		evidence: `${location}: ${label}; preview ${preview}${contextNote}`,
 	};
 }
 
+// Word-like SCREAMING_SNAKE identifier shape: at least two underscore-
+// separated segments, each essentially pure alphabetic — letters optionally
+// followed by a SHORT digit suffix (at most 2, e.g. version markers like
+// "V2") — and at most 15% digits across the whole value. Dictionary-style
+// constants like "AUTH_PASSWORD_LOGIN_CAPTCHA_REQUIRED" or
+// "PROVIDER_CONTRACT_V2_REQUIRED" match; digit-heavy segmented material
+// (e.g. license/credential shapes like "ABCD1234_EFGH5678_IJKL9012"),
+// uppercase blobs ("XK9J_Q2ZP_M7VN"), and underscore-free hex-like values
+// ("A1B2C3D4...") do not. This shape gate never skips entropy classification;
+// it only decides whether a finding whose secret-ish context comes solely
+// from the literal's own text is downgraded from blocker to warning, so it
+// deliberately stays strict: values that merely contain a secret-ish word but
+// are not word-like constants keep full blocker severity.
+function isScreamingSnakeConstantValue(value: string): boolean {
+	if (!/^[A-Z][A-Z0-9_]*$/.test(value) || !value.includes("_")) return false;
+	const segments = value.split("_");
+	if (segments.length < 2) return false;
+	if (!segments.every((segment) => /^[A-Z]+[0-9]{0,2}$/.test(segment))) return false;
+	const digitCount = value.match(/[0-9]/g)?.length ?? 0;
+	return digitCount / value.length <= 0.15;
+}
+
+type LineStringLiteral = {
+	// Index of the opening quote.
+	start: number;
+	// Index just past the closing quote (line end when unterminated).
+	end: number;
+	content: string;
+	closed: boolean;
+	role: "key" | "value";
+	// Nearest unclosed bracket enclosing the literal's start, if any.
+	container?: { bracket: "[" | "(" | "{"; index: number };
+};
+
+// Stable identity for the container a literal sits in ("top" when the
+// literal is not inside any bracket on the line).
+function literalContainerKey(literal: LineStringLiteral): string {
+	return literal.container ? `${literal.container.bracket}${literal.container.index}` : "top";
+}
+
+// Single-pass line tokenizer: extracts every string literal with its span and
+// classifies its syntactic role once. A literal is a KEY when it is preceded
+// (ignoring whitespace) by "{", ",", "(", or the line start AND followed
+// (ignoring whitespace) by ":" — i.e. it names the value next to it. Every
+// other literal is a VALUE: ternary arms (preceded by "?" or ":"), array
+// elements, call arguments, and assignment right-hand sides, even when a
+// ternary's ":" happens to follow them. Uses the same quote/escape walking as
+// extractStringLiteralCandidates.
+function tokenizeLineStringLiterals(line: string): LineStringLiteral[] {
+	const literals: LineStringLiteral[] = [];
+	const bracketStack: Array<{ bracket: "[" | "(" | "{"; index: number }> = [];
+	let index = 0;
+	while (index < line.length) {
+		const char = line[index];
+		if (char !== '"' && char !== "'" && char !== "`") {
+			if (char === "[" || char === "(" || char === "{") {
+				bracketStack.push({ bracket: char, index });
+			} else if (char === "]" || char === ")" || char === "}") {
+				bracketStack.pop();
+			}
+			index += 1;
+			continue;
+		}
+		const quote = char;
+		const start = index;
+		const contentStart = index + 1;
+		let cursor = contentStart;
+		let closed = false;
+		while (cursor < line.length) {
+			const inner = line[cursor];
+			if (inner === "\\") {
+				cursor += 2;
+				continue;
+			}
+			if (inner === quote) {
+				closed = true;
+				break;
+			}
+			cursor += 1;
+		}
+		const contentEnd = Math.min(cursor, line.length);
+		const end = closed ? cursor + 1 : line.length;
+		const before = line.slice(0, start).trimEnd();
+		const keyPreceded = before === "" || /[{,(]$/.test(before);
+		const keyFollowed = closed && /^\s*:/.test(line.slice(end));
+		literals.push({
+			start,
+			end,
+			content: line.slice(contentStart, contentEnd),
+			closed,
+			role: keyPreceded && keyFollowed ? "key" : "value",
+			container: bracketStack[bracketStack.length - 1],
+		});
+		index = end;
+	}
+	return literals;
+}
+
+// Builds the context text used to decide whether a candidate's secret-ish
+// context is genuine. The candidate's own literal is ALWAYS stripped
+// (self-context rule). SIBLING identifier-constant-shaped candidate literals
+// (VALUE role, SCREAMING_SNAKE shape, >= ENTROPY_CANDIDATE_MIN_LENGTH) are
+// stripped only when they share the candidate's non-call container — the same
+// `[...]` array, the same `{...}` object value list, or the bracket-free top
+// level (ternary arms) — so a value list of error codes cannot poison its own
+// members' context. Call-argument siblings (inside `(...)`) always keep their
+// context: in `headers.set("X_LONG_AUTH_TOKEN_NAME", "QWERTY_...")` the first
+// argument genuinely describes the second, so stripping it would erase real
+// auth/token context. KEY-role literals are never stripped.
+function stripIdentifierConstantLiterals(line: string, candidate: string): string {
+	const literals = tokenizeLineStringLiterals(line);
+	const candidateContainers = new Set<string>();
+	for (const literal of literals) {
+		if (literal.content === candidate) {
+			candidateContainers.add(literalContainerKey(literal));
+		}
+	}
+	let result = "";
+	let previousEnd = 0;
+	for (const literal of literals) {
+		result += line.slice(previousEnd, literal.start);
+		const isSelf = literal.content === candidate;
+		const isSameNonCallContainerSibling =
+			literal.role === "value" &&
+			literal.content.length >= ENTROPY_CANDIDATE_MIN_LENGTH &&
+			isScreamingSnakeConstantValue(literal.content) &&
+			literal.container?.bracket !== "(" &&
+			candidateContainers.has(literalContainerKey(literal));
+		if (isSelf || isSameNonCallContainerSibling) {
+			const quote = line[literal.start] ?? "";
+			result += quote + (literal.closed ? quote : "");
+		} else {
+			result += line.slice(literal.start, literal.end);
+		}
+		previousEnd = literal.end;
+	}
+	result += line.slice(previousEnd);
+	return result;
+}
+
 function shouldConsiderEntropyValue(value: string): boolean {
 	const lower = value.toLowerCase();
 	if (/^(?:dev-only|local|example|sample|your-|replace|<)/i.test(value)) {
@@ -3687,7 +4180,7 @@ function shouldConsiderEntropyValue(value: string): boolean {
 	if (lower.includes("/") && /\.[a-z0-9]{1,8}(?:$|[/?#])/i.test(value)) {
 		return false;
 	}
-	return value.length >= 20;
+	return value.length >= ENTROPY_CANDIDATE_MIN_LENGTH;
 }
 
 function classifyEntropyCharset(value: string): "base64" | "hex" | undefined {
@@ -3721,6 +4214,11 @@ function guessSecretName(line: string): string {
 
 const SECRETISH_IDENTIFIER_PATTERN = /key|token|secret|password|credential|auth/i;
 
+// Minimum length for a string literal to be considered an entropy candidate.
+// Shared by candidate extraction, entropy screening, and the context strip so
+// the three stay coherent.
+const ENTROPY_CANDIDATE_MIN_LENGTH = 20;
+
 const SECRET_PATTERNS: Array<[string, RegExp]> = [
 	["JWT-like token", /eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}/],
 	["GitHub token", /gh[pousr]_[A-Za-z0-9_]{30,}/],