@apifuse/provider-sdk 2.2.0-beta.66 → 2.2.0-beta.68

package/bin/apifuse-submit-check.ts

@@ -12,6 +12,11 @@ import type TS from "typescript";
 import { z } from "zod";
 
 import packageJson from "../package.json";
+import {
+	LOCAL_CONNECTION_SECRETS_ENV,
+	providerRequiresConnection,
+	resolveLocalConnection,
+} from "../src/cli/local-connection.js";
 import { formatPromptAssetIssues, verifyPromptAssets } from "../src/cli/prompt-assets.js";
 import {
 	loadProviderLocaleCatalogs,
@@ -125,6 +130,25 @@ export type SmokeResult = {
 	healthOk: boolean;
 	bootError?: string;
 	operations: SmokeOperationOutcome[];
+	/**
+	 * Whether the provider's declared auth mode needs a gateway-injected
+	 * credential, and whether this run had one. Recorded so a provider that
+	 * could not be exercised at all says so, instead of scoring as "ran, but
+	 * saw no live success" — the two are not the same evidence.
+	 */
+	credential?: {
+		required: boolean;
+		supplied: boolean;
+		mode: string;
+		/**
+		 * Why the local credential could not be resolved — a malformed
+		 * `APIFUSE__LOCAL_CONNECTION__SECRETS`, a non-string value, a bad
+		 * `--credential`. Distinct from "not configured": a misconfiguration
+		 * reported as an absence sends the author looking for a key they already
+		 * set.
+		 */
+		error?: string;
+	};
 };
 
 type SourceFinding = {
@@ -156,7 +180,9 @@ const HELP_TEXT = `Usage: apifuse submit-check [path] [--tier bronze|silver|gold
 Alias: apifuse bounty-check [path]
 Default: apifuse submit-check .
 
-Smoke: --smoke boots the provider dev server, checks /health, and POSTs every operation fixture. APIFUSE__PROVIDER__* env vars enable live upstream calls; without them, structured provider errors can still verify runtime routing. --smoke-note is deprecated and ignored for scoring.`;
+Smoke: --smoke boots the provider dev server, checks /health, and POSTs every operation fixture. APIFUSE__PROVIDER__* env vars enable live upstream calls; without them, structured provider errors can still verify runtime routing. --smoke-note is deprecated and ignored for scoring.
+
+A provider whose auth.mode is not "none" reads a credential the gateway injects at invocation time; smoke attaches the same connection from ${LOCAL_CONNECTION_SECRETS_ENV}='{"<key>":"<value>"}', keyed as the provider reads them through ctx.credential.get(...). Without it no operation reaches the upstream, and the smoke check says so rather than scoring it as a missing live success.`;
 
 export async function main() {
 	try {
@@ -1007,11 +1033,9 @@ function countAsAssertions(providerRoot: string): {
 
 	for (const filePath of listNonTestTypeScriptFiles(providerRoot)) {
 		const content = readFileSync(filePath, "utf8");
-		const lines = maskCommentsAndStrings(
-			content,
-			toRelativeProviderPath(providerRoot, filePath),
-			{ blankPropertyKeys: true },
-		).split(/\r?\n/);
+		const lines = maskCommentsAndStrings(content, toRelativeProviderPath(providerRoot, filePath), {
+			blankPropertyKeys: true,
+		}).split(/\r?\n/);
 		for (let index = 0; index < lines.length; index += 1) {
 			const line = lines[index];
 			if (
@@ -2017,18 +2041,13 @@ function scoreFlatOperationComposition(providerRoot: string): SubmitCheck {
 	);
 	if (opaqueSpread !== undefined) {
 		const spreadLine = offsetToLine(source, opaqueSpread.getStart(sourceFile));
-		return escapeHatchResult(
-			providerRoot,
-			ruleId,
-			[{ file: indexRelPath, line: spreadLine }],
-			{
-				blockerMessage:
-					"The defineProvider implementation uses a non-enumerable spread that could override operations.",
-				remediation:
-					"Declare operations directly with a static object literal. Implementation spreads must be inline static object literals so the provider-registry AST gate can enumerate every property name.",
-				passMessage: "defineProvider declares operations as a static object literal.",
-			},
-		);
+		return escapeHatchResult(providerRoot, ruleId, [{ file: indexRelPath, line: spreadLine }], {
+			blockerMessage:
+				"The defineProvider implementation uses a non-enumerable spread that could override operations.",
+			remediation:
+				"Declare operations directly with a static object literal. Implementation spreads must be inline static object literals so the provider-registry AST gate can enumerate every property name.",
+			passMessage: "defineProvider declares operations as a static object literal.",
+		});
 	}
 
 	// Determine the effective initializer expression to classify. The alias may
@@ -2079,11 +2098,7 @@ function scoreFlatOperationComposition(providerRoot: string): SubmitCheck {
 			});
 
 			const declRe = new RegExp(aliasDecl.source, "g");
-			for (
-				let m = declRe.exec(maskedFileSource);
-				m !== null;
-				m = declRe.exec(maskedFileSource)
-			) {
+			for (let m = declRe.exec(maskedFileSource); m !== null; m = declRe.exec(maskedFileSource)) {
 				const valueStart = m.index + m[0].length;
 				const expr = unwrapParens(balancedExpressionSlice(fileSource, valueStart, relPath));
 				const isFactory =
@@ -2133,9 +2148,9 @@ function scoreFlatOperationComposition(providerRoot: string): SubmitCheck {
 			const maskedIndexSource = maskCommentsAndStrings(source, indexRelPath, {
 				blankPropertyKeys: true,
 			});
-			const importMatch = new RegExp(
-				`\\bimport\\b[^;]*\\b${aliasName}\\b[^;]*\\bfrom\\b`,
-			).exec(maskedIndexSource);
+			const importMatch = new RegExp(`\\bimport\\b[^;]*\\b${aliasName}\\b[^;]*\\bfrom\\b`).exec(
+				maskedIndexSource,
+			);
 			if (importMatch) {
 				const raw = `${aliasName}(`;
 				effective = { raw, masked: raw };
@@ -3303,12 +3318,7 @@ function findVendorKeyLeakFindings(providerRoot: string): SourceFinding[] {
 			if (!zObjectAppearsPublicOutput(sourceFile, zObject, relPath)) {
 				continue;
 			}
-			for (const keyFinding of vendorKeyFindingsForObject(
-				source,
-				sourceFile,
-				zObject,
-				bindings,
-			)) {
+			for (const keyFinding of vendorKeyFindingsForObject(source, sourceFile, zObject, bindings)) {
 				const key = `${relPath}:${keyFinding.line}:${keyFinding.key}`;
 				if (!seen.has(key)) {
 					seen.add(key);
@@ -4066,18 +4076,37 @@ type MaskCommentsAndStringsOptions = {
 	blankPropertyKeys?: boolean;
 };
 
+// Which literal bodies are blanked alongside comment bodies. "all" blanks
+// every string/template/regex body; "values" does the same but keeps quoted
+// property-key text (only its structural characters are blanked); "none"
+// leaves every literal and all code byte-identical, so only comments go.
+type LiteralMaskMode = "all" | "values" | "none";
+
 export function maskCommentsAndStrings(
 	source: string,
 	fileName = "provider.ts",
 	options: MaskCommentsAndStringsOptions = {},
 ): string {
-	const blankPropertyKeys = options.blankPropertyKeys === true;
-	const cacheKey = `${blankPropertyKeys ? "blank-keys" : "preserve-keys"}\0${source}`;
+	return maskSource(source, fileName, options.blankPropertyKeys === true ? "all" : "values");
+}
+
+// Blanks comment bodies only, from the same TypeScript-lexer comment ranges
+// maskCommentsAndStrings uses: a `//` inside a string, template, or regex is
+// not a comment, and a block comment spanning lines is blanked whole. Line
+// terminators survive, so line N of the result is line N of the source.
+// Throws like maskCommentsAndStrings when the source cannot be parsed.
+export function maskComments(source: string, fileName = "provider.ts"): string {
+	return maskSource(source, fileName, "none");
+}
+
+function maskSource(source: string, fileName: string, literals: LiteralMaskMode): string {
+	const { scriptKind } = maskScriptKind(fileName);
+	const cacheKey = `${literals}\0${scriptKind}\0${source}`;
 	const cached = maskCache.get(cacheKey);
 	if (cached !== undefined) {
 		return cached;
 	}
-	const masked = computeMaskedSource(source, fileName, blankPropertyKeys);
+	const masked = computeMaskedSource(source, fileName, literals);
 	if (maskCache.size >= MASK_CACHE_LIMIT) {
 		const oldest = maskCache.keys().next();
 		if (!oldest.done) {
@@ -4088,17 +4117,34 @@ export function maskCommentsAndStrings(
 	return masked;
 }
 
-function computeMaskedSource(
-	source: string,
-	fileName: string,
-	blankPropertyKeys: boolean,
-): string {
+// The script kind a source is lexed as, from its file name, and the synthetic
+// implementation file name transpileModule parses it under. Declaration files
+// trigger an internal TypeScript Debug Failure when passed to transpileModule,
+// so `.d.ts` (like every other non-JS/JSX/TSX name) parses as `provider.ts`.
+function maskScriptKind(fileName: string): {
+	scriptKind: TS.ScriptKind;
+	syntheticFileName: string;
+} {
+	if (fileName.endsWith(".tsx")) {
+		return { scriptKind: ts.ScriptKind.TSX, syntheticFileName: "provider.tsx" };
+	}
+	if (fileName.endsWith(".jsx")) {
+		return { scriptKind: ts.ScriptKind.JSX, syntheticFileName: "provider.jsx" };
+	}
+	if (/\.[cm]?js$/.test(fileName)) {
+		return { scriptKind: ts.ScriptKind.JS, syntheticFileName: "provider.js" };
+	}
+	return { scriptKind: ts.ScriptKind.TS, syntheticFileName: "provider.ts" };
+}
+
+function computeMaskedSource(source: string, fileName: string, literals: LiteralMaskMode): string {
+	const blankPropertyKeys = literals === "all";
+	const { scriptKind, syntheticFileName } = maskScriptKind(fileName);
 	const transpiled = ts.transpileModule(source, {
-		// Declaration files trigger an internal TypeScript Debug Failure when
-		// passed to transpileModule. Parsing is all we need here, so always use a
-		// synthetic implementation filename while retaining the real filename
-		// for source mapping and sanitized diagnostics below.
-		fileName: "provider.ts",
+		// Parsing is all we need here: parse under the synthetic implementation
+		// filename while retaining the real filename for source mapping and
+		// sanitized diagnostics below.
+		fileName: syntheticFileName,
 		reportDiagnostics: true,
 		compilerOptions: { target: ts.ScriptTarget.Latest },
 	});
@@ -4107,7 +4153,7 @@ function computeMaskedSource(
 		source,
 		ts.ScriptTarget.Latest,
 		true,
-		ts.ScriptKind.TS,
+		scriptKind,
 	);
 	const parseDiagnostic = transpiled.diagnostics?.[0];
 	if (parseDiagnostic) {
@@ -4125,10 +4171,7 @@ function computeMaskedSource(
 			// by LF, CRLF, or lone CR) and every line terminator, so masked
 			// string bodies remain syntactically valid and the mask output can
 			// be re-parsed (mask(mask(x)) === mask(x)).
-			if (
-				source[index] === "\\" &&
-				(source[index + 1] === "\n" || source[index + 1] === "\r")
-			) {
+			if (source[index] === "\\" && (source[index + 1] === "\n" || source[index + 1] === "\r")) {
 				continue;
 			}
 			if (chars[index] !== "\n" && chars[index] !== "\r") chars[index] = " ";
@@ -4141,17 +4184,13 @@ function computeMaskedSource(
 		}
 	};
 
-	const visit = (node: TS.Node): void => {
-		addCommentRanges(ts.getLeadingCommentRanges(source, node.getFullStart()));
-		addCommentRanges(ts.getTrailingCommentRanges(source, node.getEnd()));
-
+	const maskLiteralBody = (node: TS.Node): void => {
 		const start = node.getStart(sourceFile);
 		if (ts.isStringLiteral(node)) {
 			// Preserve quoted property keys ("response": ...) by default so range/key
 			// scanners can still match them. Line scanners opt into blanking key bodies
 			// as well, preventing key text from looking like executable source.
-			const isQuotedPropertyKey =
-				ts.isPropertyAssignment(node.parent) && node.parent.name === node;
+			const isQuotedPropertyKey = ts.isPropertyAssignment(node.parent) && node.parent.name === node;
 			if (blankPropertyKeys || !isQuotedPropertyKey) {
 				maskRange(start + 1, node.end - 1);
 			} else {
@@ -4182,7 +4221,12 @@ function computeMaskedSource(
 		} else if (node.kind === ts.SyntaxKind.TemplateTail) {
 			maskRange(start + 1, node.end - 1);
 		}
+	};
 
+	const visit = (node: TS.Node): void => {
+		addCommentRanges(ts.getLeadingCommentRanges(source, node.getFullStart()));
+		addCommentRanges(ts.getTrailingCommentRanges(source, node.getEnd()));
+		if (literals !== "none") maskLiteralBody(node);
 		for (const child of node.getChildren(sourceFile)) visit(child);
 	};
 
@@ -5026,7 +5070,7 @@ function isAstNode(value: unknown): value is acorn.AnyNode {
 	);
 }
 
-function scoreSmoke(
+export function scoreSmoke(
 	smokeResult: SmokeResult | undefined,
 	smokeNote: string | undefined,
 ): SubmitCheck {
@@ -5048,8 +5092,22 @@ function scoreSmoke(
 		};
 	}
 
+	const credential = smokeResult.credential;
+	// An invalid configuration is reported even for a provider that needs no
+	// credential: the operator set something, and silence would read as accepted.
+	const credentialEvidence =
+		credential?.required === true || credential?.error !== undefined
+			? [
+					credential.supplied
+						? `credential: supplied for auth.mode "${credential.mode}"`
+						: credential.error
+							? `credential: CONFIGURED BUT INVALID — ${credential.error}`
+							: `credential: NOT supplied; auth.mode "${credential.mode}" needs one the gateway injects at invocation time, so every credentialed operation failed before reaching the upstream`,
+				]
+			: [];
 	const evidence = [
 		`/health: ${smokeResult.healthOk ? "ok" : "failed"}`,
+		...credentialEvidence,
 		...smokeResult.operations.map(
 			(outcome) =>
 				`${outcome.operationId}: ${outcome.status}${outcome.httpStatus ? ` HTTP ${outcome.httpStatus}` : ""} - ${outcome.message}`,
@@ -5073,6 +5131,31 @@ function scoreSmoke(
 		};
 	}
 
+	// Checked BEFORE the success branch. A provider that needs a
+	// gateway-injected credential and did not get one never exercised its
+	// credentialed path, so a schema-valid success from some other operation --
+	// an unauthenticated one, or a fixture-shaped response -- must not buy full
+	// smoke points. Saying "verified" would credit the run with evidence it does
+	// not have.
+	if (credential?.required === true && !credential.supplied) {
+		return {
+			id: "local-smoke",
+			category: "smoke",
+			level: "warn",
+			status: "warn",
+			points: 7,
+			maxPoints: CATEGORY_MAX_POINTS.smoke,
+			message: credential.error
+				? `Runtime path was verified, but the configured local credential could not be used, so the provider's credentialed operations never reached the upstream.`
+				: `Runtime path was verified, but auth.mode "${credential.mode}" needs a credential this run did not have, so the provider's credentialed operations never reached the upstream.`,
+			remediation: credential.error
+				? `Fix the local credential configuration and rerun \`bun run submit-check -- --smoke\`: ${credential.error}`
+				: `Supply the credential the gateway injects and rerun \`bun run submit-check -- --smoke\`: ${LOCAL_CONNECTION_SECRETS_ENV}='{"<key>":"<value>"}', where the keys are the ones the provider passes to ctx.credential.get(...). For platform-managed providers that value is the platform-owned key an operator holds; it is not in the checkout.`,
+			evidence,
+			details: smokeResult,
+		};
+	}
+
 	const successes = smokeResult.operations.filter((outcome) => outcome.status === "success");
 	if (successes.length > 0) {
 		return {
@@ -5143,6 +5226,12 @@ export async function runSubmitCheckSmoke(
 				operations: [],
 			};
 		}
+		// The gateway attaches a resolved credential to every invocation of a
+		// provider whose auth.mode is not "none". Smoke POSTed an envelope with
+		// no `connection` at all, so every platform-managed provider answered
+		// MISSING_SECRET and scored as "runtime verified, no live success" —
+		// a capability gap wearing the costume of an ordinary upstream miss.
+		const connection = resolveLocalConnection(loadedProvider);
 		const operations: SmokeOperationOutcome[] = [];
 		for (const [operationId, operation] of Object.entries(loadedProvider.operations)) {
 			operations.push(
@@ -5150,10 +5239,21 @@ export async function runSubmitCheckSmoke(
 					requestId: `req_submit_check_smoke_${operationId}`,
 					input: operation.fixtures?.request ?? {},
 					headers: {},
+					...(connection.ok && connection.connection ? { connection: connection.connection } : {}),
 				}),
 			);
 		}
-		return { measured: true, healthOk: true, operations };
+		return {
+			measured: true,
+			healthOk: true,
+			operations,
+			credential: {
+				required: providerRequiresConnection(loadedProvider),
+				supplied: connection.ok && connection.connection !== undefined,
+				mode: loadedProvider.auth?.mode ?? "none",
+				...(connection.ok ? {} : { error: connection.reason }),
+			},
+		};
 	} finally {
 		await stopSmokeServer(server);
 	}
@@ -5541,18 +5641,18 @@ function findEntropySecretFindings(providerRoot: string, providerId: string): Se
 		if (isEntropySecretExcludedPath(relativePath)) continue;
 		const content = readFileSync(filePath, "utf8");
 		const lines = content.split(/\r?\n/);
-		for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
-			const line = lines[lineIndex] ?? "";
-			for (const candidate of extractStringLiteralCandidates(line)) {
-				const finding = classifyEntropyCandidate({
-					value: candidate,
-					line,
-					file: relativePath,
-					lineNumber: lineIndex + 1,
-					providerId,
-				});
-				if (finding) findings.push(finding);
-			}
+		for (const candidate of extractStringLiteralCandidates(content, relativePath)) {
+			// Context is the whole source line, comment tail included: a
+			// comment that names the value is evidence about it, even though
+			// comment text itself is never a candidate.
+			const finding = classifyEntropyCandidate({
+				value: candidate.value,
+				line: lines[candidate.lineIndex] ?? "",
+				file: relativePath,
+				lineNumber: candidate.lineIndex + 1,
+				providerId,
+			});
+			if (finding) findings.push(finding);
 		}
 	}
 	return findings;
@@ -5568,7 +5668,62 @@ function isEntropySecretExcludedPath(relativePath: string): boolean {
 	);
 }
 
-export function extractStringLiteralCandidates(line: string): string[] {
+export type StringLiteralCandidate = {
+	value: string;
+	// 0-based index of the source line the literal sits on.
+	lineIndex: number;
+};
+
+// Every string-literal candidate (a quoted body of at least
+// ENTROPY_CANDIDATE_MIN_LENGTH characters) in one provider source file.
+// Candidates come from code only. Comments are prose, not values, so each
+// file's own comment syntax is removed before a quote is read:
+// - JS/TS sources: comment trivia is blanked with the TypeScript lexer
+//   (maskComments, the comment ranges the other source lints skip), so `//`
+//   inside a string or regex is not a comment and a `/* … */` block spanning
+//   lines is skipped whole. A backtick in code opens a template literal — a
+//   string value — so it stays a quote form.
+// - Shell sources (.sh/.bash, Dockerfile, entrypoint): `#` starts a comment
+//   when it begins a word outside quotes, and a backtick is command
+//   substitution (code), not a string delimiter.
+// Identifiers are therefore never candidates by construction: a bare name is
+// not a string literal, and a backticked name in a comment is comment text.
+// A JS/TS source the lexer cannot parse keeps the unmasked scan (every quote
+// pair is a candidate): when comments cannot be located the scan may
+// over-report, never under-report.
+export function extractStringLiteralCandidates(
+	content: string,
+	relativePath: string,
+): StringLiteralCandidate[] {
+	const shell = !isJavaScriptFamilySource(relativePath);
+	const codeLines = (shell ? content : maskCommentsForSecretScan(content, relativePath)).split(
+		/\r?\n/,
+	);
+	const candidates: StringLiteralCandidate[] = [];
+	for (let lineIndex = 0; lineIndex < codeLines.length; lineIndex += 1) {
+		const line = codeLines[lineIndex] ?? "";
+		const values = shell ? extractShellLineStrings(line) : extractQuotedLineStrings(line);
+		for (const value of values) candidates.push({ value, lineIndex });
+	}
+	return candidates;
+}
+
+function isJavaScriptFamilySource(relativePath: string): boolean {
+	return /\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(relativePath);
+}
+
+function maskCommentsForSecretScan(content: string, relativePath: string): string {
+	try {
+		return maskComments(content, relativePath);
+	} catch {
+		// Unparseable: scan the source unmasked rather than skip it.
+		return content;
+	}
+}
+
+// Quoted bodies on one comment-free JS/TS line (`"`, `'`, and template
+// backticks), with backslash escapes.
+function extractQuotedLineStrings(line: string): string[] {
 	const candidates: string[] = [];
 	for (let index = 0; index < line.length; index += 1) {
 		const quote = line[index];
@@ -5595,6 +5750,51 @@ export function extractStringLiteralCandidates(line: string): string[] {
 	return candidates;
 }
 
+// Characters after which a `#` begins a new shell word (blanks and the
+// metacharacters `;&|()<>`).
+const SHELL_WORD_BOUNDARY = /[\s;&|()<>]/;
+
+// Quoted bodies on one shell line. Single quotes take no escapes; double
+// quotes and unquoted text honor backslash escapes. A `#` that begins a word
+// outside quotes ends the line's code (the rest is a comment). A word begins
+// at the line start or after an UNESCAPED boundary character, so `${#var}`,
+// `$#`, `"a"#b`, and `word\ #` (escaped blank) keep `#` inside the word.
+// Backticks are command substitution, so their text is lexed as code. A
+// quote left open on the line is read as a literal character, as the
+// line-based scan always has.
+function extractShellLineStrings(line: string): string[] {
+	const candidates: string[] = [];
+	let index = 0;
+	let atWordStart = true;
+	while (index < line.length) {
+		const char = line[index];
+		if (char === "\\") {
+			index += 2;
+			atWordStart = false;
+			continue;
+		}
+		if (char === "#" && atWordStart) break;
+		if (char === '"' || char === "'") {
+			const contentStart = index + 1;
+			let cursor = contentStart;
+			while (cursor < line.length && line[cursor] !== char) {
+				cursor += char === '"' && line[cursor] === "\\" ? 2 : 1;
+			}
+			if (cursor < line.length) {
+				if (cursor - contentStart >= ENTROPY_CANDIDATE_MIN_LENGTH) {
+					candidates.push(line.slice(contentStart, cursor));
+				}
+				index = cursor + 1;
+				atWordStart = false;
+				continue;
+			}
+		}
+		atWordStart = SHELL_WORD_BOUNDARY.test(char ?? "");
+		index += 1;
+	}
+	return candidates;
+}
+
 function classifyEntropyCandidate(input: {
 	value: string;
 	line: string;
@@ -5699,7 +5899,7 @@ function literalContainerKey(literal: LineStringLiteral): string {
 // 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.
+// extractQuotedLineStrings.
 function tokenizeLineStringLiterals(line: string): LineStringLiteral[] {
 	const literals: LineStringLiteral[] = [];
 	const bracketStack: Array<{ bracket: "[" | "(" | "{"; index: number }> = [];
@@ -5994,8 +6194,7 @@ function sanitizeLoadErrorText(value: string, providerRoot: string): string {
 			const pathCandidate = rawPath.replace(/[),.;:!?]+$/u, "");
 			const relativePath = relative(providerRoot, resolve(pathCandidate));
 			const insideProvider =
-				relativePath === "" ||
-				(relativePath !== ".." && !relativePath.startsWith(`..${sep}`));
+				relativePath === "" || (relativePath !== ".." && !relativePath.startsWith(`..${sep}`));
 			return `${prefix}${insideProvider ? relativePath || "." : "[REDACTED_PATH]"}`;
 		},
 	);

package/dist/cli/local-connection.d.ts

@@ -0,0 +1,111 @@
+import type { AuthMode, ProviderDefinition } from "../types.js";
+/**
+ * The connection the local CLIs stand in for the gateway with.
+ *
+ * At invocation time the gateway resolves the credential a provider needs and
+ * attaches it to the request envelope as
+ * `connection: { id, mode, secrets, metadata }`; `serve` then builds
+ * `ctx.credential` from `connection.secrets` and nothing else. For
+ * `auth.mode: "platform-managed"` the secrets are the platform-owned key the
+ * caller never sees — which is why a probe reaches one only by going back
+ * through the gateway (`ctx.gateway.execute(...)` in a health case's
+ * `prepareInput`), and why nothing that runs outside the gateway had any way
+ * to supply it.
+ *
+ * `apifuse record` hard-coded `credential: { mode: "none" }`, so
+ * `ctx.credential.get(...)` returned `undefined` for every platform-managed
+ * provider and the run died on that provider's own `MISSING_SECRET`. The same
+ * hole made `submit-check --smoke` POST an envelope with no `connection` at
+ * all. A large share of the fleet was unrecordable and unsmokeable, and it
+ * read as "no live upstream success" rather than as a missing capability.
+ *
+ * This module is the local resolver for that connection. It does not invent a
+ * second credential path: it produces the exact shape the gateway injects, so
+ * the provider code under test takes the production branch.
+ */
+export interface LocalConnection {
+    readonly id: string;
+    readonly mode: AuthMode;
+    readonly secrets: Record<string, string>;
+    readonly metadata: Record<string, never>;
+    /**
+     * Empty, exactly as the gateway leaves it when it injects a platform
+     * credential. `OperationConnectionSchema` requires the field, so omitting
+     * it would make every smoke envelope fail request validation before the
+     * provider ran.
+     */
+    readonly externalRef: string;
+}
+/**
+ * JSON object of `connection.secrets`, keyed exactly as the provider reads
+ * them through `ctx.credential.get(...)`.
+ *
+ * A single JSON value rather than one variable per key on purpose:
+ * platform-managed providers must not declare `credential.keys` (the SDK lint
+ * rejects it), so the key names are known only to the provider's own source.
+ * There is no derivation from an env name that would be right for every
+ * provider, and guessing one would be a second, lossy contract next to the
+ * gateway's.
+ */
+export declare const LOCAL_CONNECTION_SECRETS_ENV = "APIFUSE__LOCAL_CONNECTION__SECRETS";
+/** Stable local connection id, mirroring the CLIs' other `local-*` scopes. */
+export declare const LOCAL_CONNECTION_ID = "local-connection";
+/** Auth modes whose providers read a credential the gateway supplies. */
+export declare function providerRequiresConnection(provider: {
+    readonly auth?: {
+        readonly mode?: AuthMode;
+    } | undefined;
+}): boolean;
+export type CredentialOverrideParse = {
+    readonly ok: true;
+    readonly secrets: Record<string, string>;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Parses repeated `--credential key=value` arguments.
+ *
+ * Splits on the first `=` only: a base64 or URL-shaped secret routinely
+ * contains more.
+ */
+export declare function parseCredentialOverrides(values: readonly string[]): CredentialOverrideParse;
+/** Reads {@link LOCAL_CONNECTION_SECRETS_ENV} into a secrets map. */
+export declare function parseEnvironmentSecrets(raw: string | undefined): CredentialOverrideParse;
+export interface ResolveLocalConnectionOptions {
+    /** Repeated `--credential key=value` arguments, in order. */
+    readonly overrides?: readonly string[];
+    /** Environment to read {@link LOCAL_CONNECTION_SECRETS_ENV} from. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export type LocalConnectionResolution = {
+    readonly ok: true;
+    readonly connection: LocalConnection | undefined;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Resolves the connection to attach for one local invocation.
+ *
+ * Three outcomes, and the middle one is the point of the change:
+ *
+ * - the provider needs no credential (`auth.mode` absent or `"none"`) →
+ *   no connection, exactly as before;
+ * - the provider needs one and none is configured → `ok: false` with a
+ *   message naming both ways to supply it. The caller surfaces that instead
+ *   of letting the provider fail deep inside a handler on a `MISSING_SECRET`
+ *   that reads like an upstream problem;
+ * - the provider needs one and it is configured → the gateway's envelope
+ *   shape.
+ *
+ * CLI overrides win over the environment so a one-off run does not need the
+ * shell variable unset.
+ */
+export declare function resolveLocalConnection(provider: Pick<ProviderDefinition, "id"> & {
+    auth?: {
+        mode?: AuthMode;
+    };
+}, options?: ResolveLocalConnectionOptions): LocalConnectionResolution;
+/** The message a caller prints when a needed credential is not configured. */
+export declare function missingLocalConnectionMessage(providerId: string, mode: AuthMode): string;