@apifuse/provider-sdk 2.2.0-beta.65 → 2.2.0-beta.67

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.67
+
+- Release candidate for main commit 9ef92b86b293253597801e29764d76beb0a3f3b7.
+
+## 2.2.0-beta.66
+
+- Release candidate for main commit e7f93a6c71e3bca3a680861c0968e22dbe5d1d40.
+
 ## 2.2.0-beta.65
 
 - Release candidate for main commit 4731ac76145caf85a6c340ad0c446371bd24b052.

package/bin/apifuse-check.ts

@@ -588,12 +588,56 @@ function checkPackageJson(packageJsonPath: string): CheckResult {
 
 export const PROVIDER_JSON_CHECK_MESSAGE = "provider.json exists with a valid declaration";
 
+/**
+ * Markets a provider may declare as its primary, and the locales the platform
+ * catalogs can carry.
+ *
+ * These mirror `scripts/provider-deploy/provider-locale-coverage.mjs` in the
+ * APIFuse monorepo, which is the policy's source of truth. The duplication is
+ * deliberate and bounded: the monorepo cannot be imported from a provider
+ * checkout, and a *closed* mirror is the point — it keeps a typo
+ * (`primaryMarket: "jp-JP"`) a local failure instead of one that only surfaces
+ * in the monorepo's contract validator days later.
+ */
+const PROVIDER_PRIMARY_MARKETS = ["jp", "kr", "global"] as const;
+const PROVIDER_COVERAGE_LOCALES = ["en", "ko", "ja"] as const;
+const PROVIDER_BASELINE_LOCALE = "en";
+
+/**
+ * Declared locale coverage, optional at schemaVersion 1.
+ *
+ * `apifuse provider declare-locale-coverage` writes this block, and the
+ * monorepo declaration schema has accepted it since the rollout landed. This
+ * check used to close `provider.json` over four keys, which made the only
+ * documented way to clear the monorepo's `LOCALE_COVERAGE_UNDECLARED` finding
+ * turn a green `bun run check` red — the declaration was unfixable from either
+ * side. The fix is to mirror the monorepo schema rather than to stop
+ * validating: the block stays closed over its own two keys so a misspelled
+ * field is still caught here, at authoring time.
+ */
+const providerI18nDeclarationSchema = z
+	.object({
+		primaryMarket: z.enum(PROVIDER_PRIMARY_MARKETS),
+		locales: z
+			.array(z.enum(PROVIDER_COVERAGE_LOCALES))
+			.nonempty()
+			.refine((locales) => new Set(locales).size === locales.length, {
+				message: "i18n.locales must not repeat a locale",
+			})
+			.refine((locales) => locales.includes(PROVIDER_BASELINE_LOCALE), {
+				message: `i18n.locales must include "${PROVIDER_BASELINE_LOCALE}": it is the fallback every other locale resolves through`,
+			})
+			.optional(),
+	})
+	.strict();
+
 const providerDeclarationSchema = z
 	.object({
 		schemaVersion: z.literal(1),
 		providerId: z.string(),
 		owner: z.string(),
 		lifecycle: z.enum(["draft", "ready", "live", "retired"]),
+		i18n: providerI18nDeclarationSchema.optional(),
 	})
 	.strict();
 
@@ -624,7 +668,17 @@ function checkProviderJson(providerJsonPath: string, packageJsonPath: string): C
 		return {
 			message: PROVIDER_JSON_CHECK_MESSAGE,
 			passed: true,
-			details: [`providerId: ${declaration.providerId}`, `lifecycle: ${declaration.lifecycle}`],
+			details: [
+				`providerId: ${declaration.providerId}`,
+				`lifecycle: ${declaration.lifecycle}`,
+				...(declaration.i18n
+					? [
+							`locale coverage: primaryMarket ${declaration.i18n.primaryMarket}${
+								declaration.i18n.locales ? ` (locales: ${declaration.i18n.locales.join(", ")})` : ""
+							}`,
+						]
+					: []),
+			],
 		};
 	} catch (error) {
 		return {

package/bin/apifuse-record.ts

@@ -8,6 +8,7 @@ import { pathToFileURL } from "node:url";
 
 import {
 	createBypassProviderCache,
+	createCredentialContext,
 	createHttpClient,
 	createInProcessProviderEngine,
 	createOcrClientFromEnv,
@@ -27,6 +28,13 @@ import {
 	TransportError,
 	ValidationError,
 } from "../src/index.js";
+import {
+	type LocalConnection,
+	LOCAL_CONNECTION_ID,
+	LOCAL_CONNECTION_SECRETS_ENV,
+	providerRequiresConnection,
+	resolveLocalConnection,
+} from "../src/cli/local-connection.js";
 import { createCliResolverRuntime } from "../src/cli/resolver-runtime.js";
 import { assertProcessEngineModeSupported } from "../src/runtime/engine-mode.js";
 import type { JsonValue } from "../src/contract-json.js";
@@ -71,6 +79,10 @@ type CliArgs = {
 	operation?: string;
 	params: string;
 	sanitize: boolean;
+	/** Repeated `--credential key=value`, in order. */
+	credentials: string[];
+	/** `--no-credential`: run without a connection even when auth declares one. */
+	noCredential: boolean;
 };
 
 type ProviderRuntime = ProviderDefinition;
@@ -94,8 +106,18 @@ Options:
   --append                 preserve the existing fixture and append this capture
   --sanitize               redact common token/header fields (default)
   --no-sanitize            disable common-field redaction (sensitiveParams are always redacted)
+  --credential <k>=<v>     credential the gateway would inject (repeatable)
+  --no-credential          record without a credential even when auth declares one
   --help, -h               show this help
 
+Credentials:
+  A provider whose auth.mode is not "none" reads a credential the gateway
+  resolves and injects at invocation time -- for "platform-managed" that is the
+  platform-owned key, which is not a provider secret and is not in the
+  checkout. Supply it with --credential, or with
+  ${LOCAL_CONNECTION_SECRETS_ENV}='{"<key>":"<value>"}'. The keys are the ones
+  the provider passes to ctx.credential.get(...).
+
 Example:
   apifuse record providers/korea-air-quality --operation realtime --params '{"stationName":"jongno"}'`;
 
@@ -111,10 +133,13 @@ export async function main() {
 		const operation = provider.operations[operationName];
 		const parsedParams = await parseParams(operation, args.params);
 
+		const connection = resolveRecordConnection(provider, args);
+
 		capture = createCaptureContext(
 			provider,
 			resolveOperationBaseUrl(provider, operationName),
 			args.sanitize,
+			connection,
 		);
 
 		console.log(`[apifuse record] Calling ${operationName} on ${provider.id}...`);
@@ -181,6 +206,41 @@ export async function main() {
 	}
 }
 
+/**
+ * The connection this run attaches, or a hard failure when the provider needs
+ * one and none is configured.
+ *
+ * Failing here rather than at the handler is the whole point. Before this, a
+ * platform-managed provider recorded with `credential: { mode: "none" }`, so
+ * `ctx.credential.get(...)` returned `undefined` and the run died on the
+ * provider's own `MISSING_SECRET` — indistinguishable, to the author, from an
+ * upstream outage or a bad key. It reported as a capability the recorder
+ * lacked only if you already knew to look.
+ */
+function resolveRecordConnection(
+	provider: ProviderRuntime,
+	args: CliArgs,
+): LocalConnection | undefined {
+	if (args.noCredential) {
+		if (providerRequiresConnection(provider)) {
+			console.warn(
+				`[apifuse record] --no-credential: recording ${provider.id} without the credential its auth.mode "${provider.auth?.mode}" declares.`,
+			);
+		}
+		return undefined;
+	}
+
+	const resolution = resolveLocalConnection(provider, {
+		overrides: args.credentials,
+	});
+	if (!resolution.ok)
+		throw new ProviderError(resolution.reason, {
+			code: "CREDENTIAL_UNAVAILABLE",
+			fix: "Supply the credential with --credential or the environment variable named above.",
+		});
+	return resolution.connection;
+}
+
 function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "record" ? argv.slice(1) : argv;
 }
@@ -191,6 +251,8 @@ function parseArgs(argv: string[]): CliArgs {
 	let params = "{}";
 	let sanitize = true;
 	let append = false;
+	const credentials: string[] = [];
+	let noCredential = false;
 
 	for (let index = 0; index < argv.length; index += 1) {
 		const arg = argv[index];
@@ -247,6 +309,26 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--credential") {
+			const value = argv[index + 1];
+			if (!value) {
+				throw new Error("Missing value for --credential.");
+			}
+			credentials.push(value);
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--credential=")) {
+			credentials.push(arg.slice("--credential=".length));
+			continue;
+		}
+
+		if (arg === "--no-credential") {
+			noCredential = true;
+			continue;
+		}
+
 		if (arg.startsWith("-")) {
 			throw new Error(`Unknown option: ${arg}`);
 		}
@@ -259,7 +341,15 @@ function parseArgs(argv: string[]): CliArgs {
 		throw new Error(`Unexpected argument: ${arg}`);
 	}
 
-	return { append, providerPath, operation, params, sanitize };
+	return {
+		append,
+		providerPath,
+		operation,
+		params,
+		sanitize,
+		credentials,
+		noCredential,
+	};
 }
 
 /**
@@ -459,6 +549,7 @@ export function createCaptureContext(
 	provider: ProviderRuntime,
 	baseUrl: string,
 	sanitize: boolean,
+	connection?: LocalConnection,
 ) {
 	let nextCaptureOrder = 0;
 	let nextStreamOrdinal = 0;
@@ -477,6 +568,25 @@ export function createCaptureContext(
 		provider,
 		cache,
 	);
+	// The injected credential is the most sensitive value in the run, and the
+	// recorder prints provider errors and writes fixtures. Seed its VALUES into
+	// the redaction set before anything can execute, so an upstream error that
+	// echoes the key, and any fixture that captured it, are redacted by the same
+	// machinery that already covers declared query secrets.
+	//
+	// Values only, never the key names: `sensitiveParamNames` means "declared
+	// query-key position", and `redactFixture` deliberately skips common-field
+	// sanitization for a key that appears in it. Seeding `access_token` there
+	// would therefore write a *newly issued* upstream `access_token` — which
+	// does not equal the injected value — to raw.json in plaintext. A credential
+	// key that really is a query parameter is added to the name set by
+	// `captureSensitiveRequestValues` when the provider sends it, which is the
+	// only place that claim is true.
+	for (const value of Object.values(connection?.secrets ?? {})) {
+		if (value.length > 0) sensitiveParamValues.add(value);
+	}
+	registerSensitiveValues([...sensitiveParamValues]);
+
 	const captureSensitiveParams = (url: string, options?: SensitiveRequestOptions) => {
 		try {
 			captureSensitiveRequestValues(url, options, sensitiveParamNames, sensitiveParamValues);
@@ -550,18 +660,21 @@ export function createCaptureContext(
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
 	const env = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
-	const credential = {
-		mode: "none" as const,
-		get: () => undefined,
-		getAll: () => ({}),
-		getAccessToken: () => undefined,
-		getScopes: () => [],
-	};
+	// Built exactly the way `serve` builds it from a gateway-supplied
+	// `request.connection`, so the provider takes its production branch rather
+	// than the always-undefined one a stub credential forces.
+	const credential = createCredentialContext({
+		...(provider.credential?.keys ? { allowedKeys: provider.credential.keys } : {}),
+		...(connection ? { mode: connection.mode, values: connection.secrets } : {}),
+	});
 	const state = createMemoryProviderRuntimeState();
 	const candidates: ProviderEngineBindingCandidates = {
 		env,
 		credential,
-		request: { headers: {}, connectionId: "local-record" },
+		request: {
+			headers: {},
+			connectionId: connection ? LOCAL_CONNECTION_ID : "local-record",
+		},
 		http,
 		cache,
 		state,
@@ -595,7 +708,10 @@ export function createCaptureContext(
 		resolver,
 		handle: createHandleContext({
 			providerId: provider.id,
-			request: { headers: {}, connectionId: "local-record" },
+			request: {
+				headers: {},
+				connectionId: connection ? LOCAL_CONNECTION_ID : "local-record",
+			},
 			state,
 		}),
 	};

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);
@@ -4088,11 +4098,7 @@ export function maskCommentsAndStrings(
 	return masked;
 }
 
-function computeMaskedSource(
-	source: string,
-	fileName: string,
-	blankPropertyKeys: boolean,
-): string {
+function computeMaskedSource(source: string, fileName: string, blankPropertyKeys: boolean): string {
 	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
@@ -4125,10 +4131,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] = " ";
@@ -4150,8 +4153,7 @@ function computeMaskedSource(
 			// 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 {
@@ -5026,7 +5028,7 @@ function isAstNode(value: unknown): value is acorn.AnyNode {
 	);
 }
 
-function scoreSmoke(
+export function scoreSmoke(
 	smokeResult: SmokeResult | undefined,
 	smokeNote: string | undefined,
 ): SubmitCheck {
@@ -5048,8 +5050,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 +5089,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 +5184,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 +5197,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);
 	}
@@ -5994,8 +6052,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;

package/dist/cli/local-connection.js

@@ -0,0 +1,151 @@
+/**
+ * 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 const LOCAL_CONNECTION_SECRETS_ENV = "APIFUSE__LOCAL_CONNECTION__SECRETS";
+/** Stable local connection id, mirroring the CLIs' other `local-*` scopes. */
+export const LOCAL_CONNECTION_ID = "local-connection";
+/** Auth modes whose providers read a credential the gateway supplies. */
+export function providerRequiresConnection(provider) {
+    const mode = provider.auth?.mode;
+    return mode !== undefined && mode !== "none";
+}
+/**
+ * Parses repeated `--credential key=value` arguments.
+ *
+ * Splits on the first `=` only: a base64 or URL-shaped secret routinely
+ * contains more.
+ */
+export function parseCredentialOverrides(values) {
+    const secrets = {};
+    for (const [index, value] of values.entries()) {
+        // The offending argument is never echoed. `--credential =secret` and
+        // `--credential secret` are both malformed *and* carry the credential, so
+        // quoting the input to be helpful would print it to stderr — before any
+        // redaction context exists, so no caller could scrub it.
+        const separator = value.indexOf("=");
+        if (separator <= 0) {
+            return {
+                ok: false,
+                reason: `--credential #${index + 1} is not of the form key=value; its value is not echoed here because it may be the credential.`,
+            };
+        }
+        const key = value.slice(0, separator).trim();
+        if (key.length === 0) {
+            return {
+                ok: false,
+                reason: `--credential #${index + 1} has an empty key; its value is not echoed here because it may be the credential.`,
+            };
+        }
+        secrets[key] = value.slice(separator + 1);
+    }
+    return { ok: true, secrets };
+}
+/** Reads {@link LOCAL_CONNECTION_SECRETS_ENV} into a secrets map. */
+export function parseEnvironmentSecrets(raw) {
+    if (raw === undefined || raw.trim().length === 0) {
+        return { ok: true, secrets: {} };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `${LOCAL_CONNECTION_SECRETS_ENV} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            reason: `${LOCAL_CONNECTION_SECRETS_ENV} must be a JSON object of credential key to string value.`,
+        };
+    }
+    const secrets = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== "string") {
+            return {
+                ok: false,
+                reason: `${LOCAL_CONNECTION_SECRETS_ENV}.${key} must be a string (received ${typeof value}); the value is not echoed here.`,
+            };
+        }
+        secrets[key] = value;
+    }
+    return { ok: true, secrets };
+}
+/**
+ * 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 function resolveLocalConnection(provider, options = {}) {
+    const fromEnv = parseEnvironmentSecrets((options.env ?? process.env)[LOCAL_CONNECTION_SECRETS_ENV]);
+    if (!fromEnv.ok)
+        return fromEnv;
+    const fromArgs = parseCredentialOverrides(options.overrides ?? []);
+    if (!fromArgs.ok)
+        return fromArgs;
+    const secrets = { ...fromEnv.secrets, ...fromArgs.secrets };
+    const mode = provider.auth?.mode;
+    if (!providerRequiresConnection(provider)) {
+        if (Object.keys(secrets).length > 0) {
+            return {
+                ok: false,
+                reason: `Provider "${provider.id}" declares auth.mode ${JSON.stringify(mode ?? "none")}, which takes no credential. Remove the supplied credential values.`,
+            };
+        }
+        return { ok: true, connection: undefined };
+    }
+    if (Object.keys(secrets).length === 0) {
+        return {
+            ok: false,
+            reason: missingLocalConnectionMessage(provider.id, mode ?? "none"),
+        };
+    }
+    return {
+        ok: true,
+        connection: {
+            id: LOCAL_CONNECTION_ID,
+            // `mode` is narrowed by providerRequiresConnection above.
+            mode: mode ?? "none",
+            secrets,
+            metadata: {},
+            externalRef: "",
+        },
+    };
+}
+/** The message a caller prints when a needed credential is not configured. */
+export function missingLocalConnectionMessage(providerId, mode) {
+    const platformManaged = mode === "platform-managed";
+    return [
+        `Provider "${providerId}" declares auth.mode "${mode}", so the gateway injects a credential on every invocation and this command has none.`,
+        platformManaged
+            ? "The value is the platform-owned key an operator holds; it is not a provider secret and is not derivable from the checkout."
+            : "Supply the same credential the gateway would resolve for a connection.",
+        "Supply it with one of:",
+        "  --credential <key>=<value>   (repeatable)",
+        `  ${LOCAL_CONNECTION_SECRETS_ENV}='{"<key>":"<value>"}'`,
+        "The keys are the ones the provider passes to ctx.credential.get(...).",
+        "Pass --no-credential to run without one anyway (the provider will fail the way it does in production when the credential is unavailable).",
+    ].join("\n");
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.65",
+	"version": "2.2.0-beta.67",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/local-connection.ts

@@ -0,0 +1,221 @@
+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 const LOCAL_CONNECTION_SECRETS_ENV = "APIFUSE__LOCAL_CONNECTION__SECRETS";
+
+/** Stable local connection id, mirroring the CLIs' other `local-*` scopes. */
+export const LOCAL_CONNECTION_ID = "local-connection";
+
+/** Auth modes whose providers read a credential the gateway supplies. */
+export function providerRequiresConnection(provider: {
+	readonly auth?: { readonly mode?: AuthMode } | undefined;
+}): boolean {
+	const mode = provider.auth?.mode;
+	return mode !== undefined && mode !== "none";
+}
+
+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 function parseCredentialOverrides(values: readonly string[]): CredentialOverrideParse {
+	const secrets: Record<string, string> = {};
+	for (const [index, value] of values.entries()) {
+		// The offending argument is never echoed. `--credential =secret` and
+		// `--credential secret` are both malformed *and* carry the credential, so
+		// quoting the input to be helpful would print it to stderr — before any
+		// redaction context exists, so no caller could scrub it.
+		const separator = value.indexOf("=");
+		if (separator <= 0) {
+			return {
+				ok: false,
+				reason: `--credential #${index + 1} is not of the form key=value; its value is not echoed here because it may be the credential.`,
+			};
+		}
+		const key = value.slice(0, separator).trim();
+		if (key.length === 0) {
+			return {
+				ok: false,
+				reason: `--credential #${index + 1} has an empty key; its value is not echoed here because it may be the credential.`,
+			};
+		}
+		secrets[key] = value.slice(separator + 1);
+	}
+	return { ok: true, secrets };
+}
+
+/** Reads {@link LOCAL_CONNECTION_SECRETS_ENV} into a secrets map. */
+export function parseEnvironmentSecrets(raw: string | undefined): CredentialOverrideParse {
+	if (raw === undefined || raw.trim().length === 0) {
+		return { ok: true, secrets: {} };
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `${LOCAL_CONNECTION_SECRETS_ENV} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		return {
+			ok: false,
+			reason: `${LOCAL_CONNECTION_SECRETS_ENV} must be a JSON object of credential key to string value.`,
+		};
+	}
+	const secrets: Record<string, string> = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		if (typeof value !== "string") {
+			return {
+				ok: false,
+				reason: `${LOCAL_CONNECTION_SECRETS_ENV}.${key} must be a string (received ${typeof value}); the value is not echoed here.`,
+			};
+		}
+		secrets[key] = value;
+	}
+	return { ok: true, secrets };
+}
+
+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 function resolveLocalConnection(
+	provider: Pick<ProviderDefinition, "id"> & { auth?: { mode?: AuthMode } },
+	options: ResolveLocalConnectionOptions = {},
+): LocalConnectionResolution {
+	const fromEnv = parseEnvironmentSecrets(
+		(options.env ?? process.env)[LOCAL_CONNECTION_SECRETS_ENV],
+	);
+	if (!fromEnv.ok) return fromEnv;
+
+	const fromArgs = parseCredentialOverrides(options.overrides ?? []);
+	if (!fromArgs.ok) return fromArgs;
+
+	const secrets = { ...fromEnv.secrets, ...fromArgs.secrets };
+	const mode = provider.auth?.mode;
+
+	if (!providerRequiresConnection(provider)) {
+		if (Object.keys(secrets).length > 0) {
+			return {
+				ok: false,
+				reason: `Provider "${provider.id}" declares auth.mode ${JSON.stringify(mode ?? "none")}, which takes no credential. Remove the supplied credential values.`,
+			};
+		}
+		return { ok: true, connection: undefined };
+	}
+
+	if (Object.keys(secrets).length === 0) {
+		return {
+			ok: false,
+			reason: missingLocalConnectionMessage(provider.id, mode ?? "none"),
+		};
+	}
+
+	return {
+		ok: true,
+		connection: {
+			id: LOCAL_CONNECTION_ID,
+			// `mode` is narrowed by providerRequiresConnection above.
+			mode: mode ?? "none",
+			secrets,
+			metadata: {},
+			externalRef: "",
+		},
+	};
+}
+
+/** The message a caller prints when a needed credential is not configured. */
+export function missingLocalConnectionMessage(providerId: string, mode: AuthMode): string {
+	const platformManaged = mode === "platform-managed";
+	return [
+		`Provider "${providerId}" declares auth.mode "${mode}", so the gateway injects a credential on every invocation and this command has none.`,
+		platformManaged
+			? "The value is the platform-owned key an operator holds; it is not a provider secret and is not derivable from the checkout."
+			: "Supply the same credential the gateway would resolve for a connection.",
+		"Supply it with one of:",
+		"  --credential <key>=<value>   (repeatable)",
+		`  ${LOCAL_CONNECTION_SECRETS_ENV}='{"<key>":"<value>"}'`,
+		"The keys are the ones the provider passes to ctx.credential.get(...).",
+		"Pass --no-credential to run without one anyway (the provider will fail the way it does in production when the credential is unavailable).",
+	].join("\n");
+}