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

package/dist/server/serve-implementation.js

@@ -15,7 +15,7 @@ import { createEngineForMode, isUnavailableProviderEngine, resolveProviderEngine
 import { SDK_VERSION } from "./sdk-version.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
 import { providerErrorStackFrames } from "./error-stack-frames.js";
-import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
+import { registeredUpstreamErrorCategory, SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, SDKError, } from "../errors.js";
 import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
@@ -37,7 +37,7 @@ import { HttpTelemetryCollector } from "../runtime/http-telemetry.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { bindOcrTelemetry, OcrTelemetryCollector } from "../runtime/ocr-telemetry.js";
-import { getProviderBaseUrl } from "../runtime/provider.js";
+import { getProviderBaseUrl, getProviderStealthBaseUrl } from "../runtime/provider.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry.js";
 import { closedEnum, RequestTelemetry, tenantOpaqueKeys, } from "../runtime/request-telemetry.js";
@@ -62,6 +62,7 @@ import { getStealthProfile } from "../stealth/profiles.js";
 import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream.js";
 import { sanitizeSpanNameForOutput, sanitizeTraceAttributes } from "../trace-sanitization.js";
 import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
+import { providerStateBackendLogEvent, } from "./state-backend-report.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { collectStaticDiagnosticSensitiveValues, createDiagnosticEnvObserver, } from "./sensitive-values.js";
 import { resolveServerTraceContextOptions } from "./trace-output.js";
@@ -340,14 +341,6 @@ function bindResolverSignalWithoutRuntime(resolver, defaultSignal) {
     inheritResolverTelemetryBinding(resolver, boundResolver);
     return boundResolver;
 }
-function getProviderStealthBaseUrl(provider) {
-    const baseUrl = getProviderBaseUrl(provider);
-    if (baseUrl) {
-        return baseUrl;
-    }
-    const firstHost = provider.allowedHosts?.[0];
-    return firstHost ? `https://${firstHost}` : undefined;
-}
 function getProviderStealthProfile(provider) {
     return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 }
@@ -849,8 +842,9 @@ function zodDetails(error, redact) {
 // (credential_unavailable) usually means a caller credential problem, an
 // internal stateful-routing deadline is APIFuse-owned despite its timeout
 // category, and the built-in upstream failure families keep their upstream
-// attribution even when the author left the category at the provider_error
-// default.
+// attribution even under an explicit non-upstream category. An unset category
+// needs no override: a registered upstream code already carries its category
+// (SDK_UPSTREAM_ERROR_CODE_REGISTRY), and the source follows from it.
 function publicErrorSource(error, category) {
     if (error instanceof StatefulRoutingDeadlineError)
         return "apifuse";
@@ -1120,6 +1114,18 @@ function providerObservabilityDetails(error, declaredErrorCode) {
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
+// The category a `ProviderError` (validation errors included) gets when its
+// author set none, ahead of the branch's own default: an operation-declared
+// rejection status (409/410/422) → upstream_rejected, then the registered
+// upstream code's category (UPSTREAM_SCHEMA_ERROR → upstream_schema_drift,
+// NOT_FOUND → upstream_http, ...). `undefined` leaves the branch default.
+function derivedErrorCategory(error, declaredStatus) {
+    if (isEmittableErrorStatus(declaredStatus) &&
+        categoryForStatus(declaredStatus) === "upstream_rejected") {
+        return "upstream_rejected";
+    }
+    return registeredUpstreamErrorCategory(providerErrorCode(error));
+}
 function classifiedErrorObservabilityDetails(error, declaredErrorCode) {
     const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
     const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
@@ -1131,12 +1137,10 @@ function classifiedErrorObservabilityDetails(error, declaredErrorCode) {
         return {
             category: providerCategory
                 ? providerCategory
-                : isEmittableErrorStatus(declaredStatus) &&
-                    categoryForStatus(declaredStatus) === "upstream_rejected"
-                    ? "upstream_rejected"
-                    : isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+                : (derivedErrorCategory(error, declaredStatus) ??
+                    (isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
                         ? "provider_error"
-                        : "input_validation",
+                        : "input_validation")),
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
             retryable: isProviderError(error)
                 ? (providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false)
@@ -1151,18 +1155,12 @@ function classifiedErrorObservabilityDetails(error, declaredErrorCode) {
         };
     }
     if (isProviderError(error)) {
-        // Deterministic upstream refusals default to the rejection category:
-        // the UPSTREAM_REJECTED family and any operation-declared rejection
-        // status (409/410/422) classify as upstream_rejected unless the
-        // author set an explicit category.
-        const declaredStatus = effectiveDeclaration?.status;
-        const rejectionDefault = providerErrorCode(error) === "UPSTREAM_REJECTED" ||
-            (isEmittableErrorStatus(declaredStatus) &&
-                categoryForStatus(declaredStatus) === "upstream_rejected")
-            ? "upstream_rejected"
-            : "provider_error";
+        // Retryability does not follow the derived category: it stays
+        // instance ?? declared ?? false below.
         return {
-            category: providerErrorOption(error, "category") ?? rejectionDefault,
+            category: providerErrorOption(error, "category") ??
+                derivedErrorCategory(error, effectiveDeclaration?.status) ??
+                "provider_error",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
             retryable: providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false,
         };
@@ -2560,7 +2558,13 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         });
     }
     app.notFound((c) => {
-        const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+        // An unknown route is not an upstream answer: the explicit category keeps
+        // the registered not_found code from attributing it to an upstream.
+        const error = new ProviderError("Not found", {
+            code: "not_found",
+            category: "provider_error",
+            retryable: false,
+        });
         const observabilityDetails = errorObservabilityDetails(error);
         return responseWithErrorObservability(c.json(toErrorResponse(error, undefined, observabilityDetails, undefined, errorEnvelopeLocalization({
             catalogs: localeCatalogs,
@@ -2968,6 +2972,16 @@ export async function serve(provider, options = {}) {
     // One structured line per process boot, before the listener binds: the fleet
     // audit (ADR-0011 migration) counts these.
     logger(engineModeLogEvent(provider, engineSelection.resolution, !isUnavailableProviderEngine(engineSelection.engine)));
+    // Same contract for the stores: one line per process boot naming the state
+    // and cache backends this pod resolved, so "which Redis is this provider's
+    // state actually on" is a log grep instead of an inference from the
+    // Deployment spec (apifuse#2302).
+    logger(providerStateBackendLogEvent({
+        providerId: provider.id,
+        sdkVersion: SDK_VERSION,
+        injectedState: options.state !== undefined,
+        allowMemoryFallback: options.allowMemoryStateFallback === true,
+    }));
     const servers = [];
     try {
         servers.push(bunRuntime.serve({

package/dist/server/state-backend-report.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What a provider store resolved to at boot.
+ *
+ * `endpoint` is deliberately host and port only: the URL can carry a password
+ * (`redis://:secret@host:6379`), and the diagnostic inventory already treats
+ * those credential components — and only those — as sensitive
+ * (`collectDiagnosticSensitiveValues`, `urlCredentialComponents(url, {
+ * includePathAndQuery: false })`). A URL that does not parse contributes no
+ * endpoint at all rather than a redacted-looking fragment of itself.
+ */
+export type ProviderStoreBackendReport = {
+    /**
+     * `redis` when a URL resolved, `memory` for the in-process fallback,
+     * `unsupported` when state has no backend and every call fails closed,
+     * `injected` when the host handed the server a store object.
+     */
+    readonly backend: "redis" | "memory" | "unsupported" | "injected";
+    /** Env name that supplied the Redis URL. Present only for `redis`. */
+    readonly envName?: string;
+    /**
+     * `host:port` of the resolved Redis. Never includes credentials, path or
+     * query. Absent when the URL does not parse, or when its query carries an
+     * ioredis option that moves the endpoint (`path`, `port`, `host`, `family`)
+     * so the authority is not where the client connects — see
+     * `state_redis_url_ambiguous_endpoint`.
+     */
+    readonly endpoint?: string;
+    /** URL scheme, e.g. `redis` or `rediss`. Present only for `redis`. */
+    readonly scheme?: string;
+    /** True when the URL came from a shared fallback env rather than the store's own. */
+    readonly fallback?: boolean;
+};
+/**
+ * One line per process boot naming the stores the provider resolved. Without
+ * it, a provider silently riding the cache Redis for its state is
+ * indistinguishable from one on a durable instance, from outside the pod and
+ * from the pod's own logs (apifuse#2302, the reason apifuse#2144 could only be
+ * verified by inference from the Deployment spec).
+ */
+export type ProviderStateBackendLogEvent = {
+    /** `warn` when a warning was raised, otherwise `info`. */
+    readonly level: "info" | "warn";
+    readonly event: "provider_state_backend";
+    readonly providerId: string;
+    readonly state: ProviderStoreBackendReport;
+    readonly cache: ProviderStoreBackendReport;
+    readonly sdkVersion: string;
+    /**
+     * Non-fatal findings, e.g. `state_redis_url_fallback` (the state store is
+     * sharing an instance provisioned for something else),
+     * `state_redis_url_unparsed`, or `state_redis_url_ambiguous_endpoint` (the
+     * URL's query carries an ioredis option that moves the endpoint, so the
+     * authority is not reported as the endpoint). Absent when the resolution
+     * was unambiguous.
+     */
+    readonly warnings?: readonly string[];
+};
+/**
+ * Build the boot event from the same env precedence the stores themselves use
+ * (`providerStateRedisResolutionFromEnv` / `providerCacheRedisResolutionFromEnv`),
+ * so the line can never describe a backend other than the one in use.
+ */
+export declare function providerStateBackendLogEvent(input: {
+    readonly providerId: string;
+    readonly sdkVersion: string;
+    /** The host passed an explicit state store, so no env resolution happened. */
+    readonly injectedState: boolean;
+    /** Mirrors `createProviderRuntimeStateFromEnv({ allowMemoryFallback })`. */
+    readonly allowMemoryFallback: boolean;
+}): ProviderStateBackendLogEvent;

package/dist/server/state-backend-report.js

@@ -0,0 +1,113 @@
+import { providerCacheRedisResolutionFromEnv, providerStateRedisResolutionFromEnv, } from "../config/loader.js";
+/**
+ * Whether ioredis' own URL parsing would move the endpoint away from the
+ * authority this function can see. `createProviderRedisClient` hands the raw
+ * URL to `new Redis(url, …)`, and `parseURL` ends with
+ * `defaults(result, queryOptions)` — lodash `defaults`, so a query key only
+ * applies where the authority supplied nothing:
+ *
+ * - `path` is never derived from the authority of a `redis://` URL (that
+ *   pathname is the db index), so `?path=` always applies — and
+ *   `StandaloneConnector` connects to `options.path` INSTEAD of host/port.
+ *   The client is then on a Unix socket the authority says nothing about.
+ * - `port` applies only when the URL carries no explicit port.
+ * - `host` never applies here: we return early unless `parsed.hostname` is
+ *   set, so `result.host` is always already populated.
+ * - `family` selects an address family; it does not move `host:port`.
+ *
+ * Verified against the pinned ioredis 5.11.1. In those cases the endpoint is
+ * WITHHELD and the ambiguity named, rather than reported as the authority — a
+ * diagnostic whose whole job is to answer "which Redis is this provider on"
+ * must not answer it wrongly. The query is never echoed: it can carry a
+ * password, which is why `endpoint` is host-and-port only to begin with.
+ */
+function queryMovesEndpoint(parsed) {
+    if (parsed.searchParams.has("path"))
+        return true;
+    return parsed.searchParams.has("port") && parsed.port === "";
+}
+function redisEndpoint(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return {};
+    }
+    // No authority means this is not the `redis://host:port` shape at all (e.g.
+    // a bare `host:port`, which parses as a scheme). Report nothing rather than
+    // a fragment of a string whose parts we have not identified.
+    if (!parsed.hostname)
+        return {};
+    const scheme = parsed.protocol.replace(/:$/, "");
+    if (queryMovesEndpoint(parsed))
+        return { scheme, ambiguous: true };
+    return {
+        scheme,
+        endpoint: parsed.port ? `${parsed.hostname}:${parsed.port}` : parsed.hostname,
+    };
+}
+function redisReport(resolution) {
+    const { endpoint, scheme, ambiguous } = redisEndpoint(resolution.url);
+    return {
+        parsed: endpoint !== undefined || ambiguous === true,
+        ambiguous: ambiguous === true,
+        report: {
+            backend: "redis",
+            envName: resolution.envName,
+            ...(endpoint === undefined ? {} : { endpoint }),
+            ...(scheme === undefined ? {} : { scheme }),
+            ...(resolution.fallback ? { fallback: true } : {}),
+        },
+    };
+}
+/**
+ * Build the boot event from the same env precedence the stores themselves use
+ * (`providerStateRedisResolutionFromEnv` / `providerCacheRedisResolutionFromEnv`),
+ * so the line can never describe a backend other than the one in use.
+ */
+export function providerStateBackendLogEvent(input) {
+    const warnings = [];
+    let state;
+    if (input.injectedState) {
+        state = { backend: "injected" };
+    }
+    else {
+        const resolution = providerStateRedisResolutionFromEnv();
+        if (resolution) {
+            const { report, parsed, ambiguous } = redisReport(resolution);
+            state = report;
+            if (!parsed)
+                warnings.push("state_redis_url_unparsed");
+            if (ambiguous)
+                warnings.push("state_redis_url_ambiguous_endpoint");
+            if (resolution.fallback)
+                warnings.push("state_redis_url_fallback");
+        }
+        else {
+            state = { backend: input.allowMemoryFallback ? "memory" : "unsupported" };
+        }
+    }
+    const cacheResolution = providerCacheRedisResolutionFromEnv();
+    let cache;
+    if (cacheResolution) {
+        const { report, parsed, ambiguous } = redisReport(cacheResolution);
+        cache = report;
+        if (!parsed)
+            warnings.push("cache_redis_url_unparsed");
+        if (ambiguous)
+            warnings.push("cache_redis_url_ambiguous_endpoint");
+    }
+    else {
+        cache = { backend: "memory" };
+    }
+    return {
+        level: warnings.length > 0 ? "warn" : "info",
+        event: "provider_state_backend",
+        providerId: input.providerId,
+        state,
+        cache,
+        sdkVersion: input.sdkVersion,
+        ...(warnings.length === 0 ? {} : { warnings }),
+    };
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.66",
+	"version": "2.2.0-beta.68",
 	"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");
+}