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

package/src/cli/templates/provider/AGENTS.md.tpl

@@ -4,8 +4,8 @@ You are building an APIFuse provider. APIFuse turns messy upstream APIs into
 normalized, typed, evidence-backed public APIs. A provider that merely proxies
 the upstream is a failed provider, even if every check passes.
 
-This file is the core contract. Detailed procedures live in `skills/` — load
-the matching skill BEFORE working on that area (index at the bottom).
+This file is the core contract. Detailed procedures live in `.agents/skills/` —
+load the matching skill BEFORE working on that area (index at the bottom).
 
 ## Non-negotiable principles
 
@@ -75,13 +75,22 @@ bun run submit-check # structural score; a high score does NOT prove quality
 `submit-check` is a structural gate. Every principle above can be violated
 while scoring 95/100 — reviewers and CI audit for exactly these classes.
 
+## Managed prompt assets
+
+`AGENTS.md` and `.agents/skills/**` are generated by the SDK; `CLAUDE.md`,
+`.claude`, and `.codex` are symlinks onto them so every agent CLI reads the
+same contract. Do not hand-edit these files — regenerate them with
+`bun run sync-assets` (or `bunx apifuse sync-assets .`). `apifuse check` and
+`submit-check` enforce a freshness gate: stale or modified prompt assets
+(tracked in `.apifuse/prompt-assets.json`) block submission until re-synced.
+
 ## Skill index — load before working on:
 
 | Area | Load |
 | --- | --- |
-| Output schemas, mappers, field naming, timestamps, enums | `skills/normalization-standards/SKILL.md` |
-| Upstream request params, new endpoint wiring, field mapping | `skills/upstream-contract-verification/SKILL.md` |
-| Recording fixtures, writing tests against fixtures | `skills/fixtures-and-recording/SKILL.md` |
-| List operations, paging, totals, client-side filtering | `skills/pagination-and-counts/SKILL.md` |
-| healthCheck blocks, error classification, fail-closed guards | `skills/health-checks-and-fail-closed/SKILL.md` |
-| Upstream-specific known pitfalls for THIS bounty | `skills/upstream-notes/` (read every file) |
+| Output schemas, mappers, field naming, timestamps, enums | `.agents/skills/normalization-standards/SKILL.md` |
+| Upstream request params, new endpoint wiring, field mapping | `.agents/skills/upstream-contract-verification/SKILL.md` |
+| Recording fixtures, writing tests against fixtures | `.agents/skills/fixtures-and-recording/SKILL.md` |
+| List operations, paging, totals, client-side filtering | `.agents/skills/pagination-and-counts/SKILL.md` |
+| healthCheck blocks, error classification, fail-closed guards | `.agents/skills/health-checks-and-fail-closed/SKILL.md` |
+| Upstream-specific known pitfalls for THIS bounty | `.agents/skills/upstream-notes/` (read every file) |

package/src/index.ts

@@ -74,6 +74,11 @@ export {
 } from "./runtime/instrumentation.js";
 export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export {
+	assertRequiredSecretsPresent,
+	listMissingRequiredSecrets,
+	MISSING_SECRET_CODE,
+} from "./runtime/secrets.js";
 export {
 	createUnsupportedProviderRuntimeState,
 	UnsupportedProviderStateError,

package/src/runtime/executor.ts

@@ -1,6 +1,7 @@
 import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
 import { parseSchema } from "../schema.js";
 import type { ProviderContext, ProviderDefinition } from "../types.js";
+import { assertRequiredSecretsPresent } from "./secrets.js";
 
 export function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean {
 	const kind = provider.operations[operationId]?.transport?.kind ?? "json";
@@ -34,6 +35,13 @@ export async function executeOperation(
 		});
 	}
 
+	// SDK-owned secret presence gate (single source of truth): declared
+	// `required: true` secrets are validated here, before input parsing and the
+	// handler, so every invocation path (serve /v1, self-test probes, perf,
+	// record) fails with the same structured MISSING_SECRET error instead of a
+	// handler-specific crash. Providers must not re-check presence locally.
+	assertRequiredSecretsPresent(provider, ctx.env);
+
 	const validatedInput = await parseSchema(
 		operation.input,
 		input,

package/src/runtime/secrets.ts

@@ -0,0 +1,64 @@
+import { ProviderSecretError } from "../errors.js";
+import type { EnvContext, ProviderDefinition } from "../types.js";
+
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export const MISSING_SECRET_CODE = "MISSING_SECRET";
+
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export function listMissingRequiredSecrets(
+	provider: ProviderDefinition,
+	env: EnvContext,
+): string[] {
+	const missing: string[] = [];
+	for (const secret of provider.secrets ?? []) {
+		if (secret.required !== true) {
+			continue;
+		}
+		const value = env.get(secret.name);
+		if (value === undefined || value.trim() === "") {
+			missing.push(secret.name);
+		}
+	}
+	return missing;
+}
+
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export function assertRequiredSecretsPresent(
+	provider: ProviderDefinition,
+	env: EnvContext,
+): void {
+	const missing = listMissingRequiredSecrets(provider, env);
+	if (missing.length === 0) {
+		return;
+	}
+	const names = missing.join(", ");
+	throw new ProviderSecretError(
+		`Missing required provider secret${missing.length > 1 ? "s" : ""}: ${names}`,
+		{
+			code: MISSING_SECRET_CODE,
+			category: "credential_unavailable",
+			retryable: false,
+			fix: `Provision ${names} in the provider environment (e.g. Doppler). Declared in defineProvider({ secrets: [...] }).`,
+		},
+	);
+}

package/src/server/serve.ts

@@ -42,6 +42,11 @@ import {
 	PROXY_POOL_EXHAUSTED_CODE,
 } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
+import {
+	assertRequiredSecretsPresent,
+	listMissingRequiredSecrets,
+	MISSING_SECRET_CODE,
+} from "../runtime/secrets.js";
 import {
 	createProviderRuntimeStateFromEnv,
 	createUnsupportedProviderRuntimeState,
@@ -408,6 +413,12 @@ export type ProviderServerLogEvent =
 			retryable?: boolean;
 			issues?: Array<{ path: string; code: string; message: string }>;
 	  })
+	| {
+			level: "warn";
+			event: "provider_secrets_missing";
+			providerId: string;
+			missingSecrets: string[];
+	  }
 	| {
 			level: "warn";
 			event: "provider_cleanup_failed";
@@ -558,6 +569,18 @@ function providerObservabilityDetails(error: unknown):
 			retryable: error.options?.retryable ?? false,
 		};
 	}
+	// Missing-secret errors carry the canonical credential_unavailable category
+	// so Gateway/observability can attribute the failure to provisioning, not
+	// the upstream. Matched by code (not constructor) so both the SDK-owned
+	// runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
+	// serialize identically, including across duplicate SDK module instances.
+	if (isProviderError(error) && error.code === MISSING_SECRET_CODE) {
+		return {
+			category: error.options?.category ?? "credential_unavailable",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: error.options?.retryable ?? false,
+		};
+	}
 	if (!isTransportError(error)) {
 		return undefined;
 	}
@@ -628,6 +651,10 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 			case "AUTH_REQUIRED":
 			case "reauth_required":
 				return 401;
+			// Unprovisioned declared secret: a deployment/config defect, never an
+			// upstream failure — explicit 400 (was only reached via fallthrough).
+			case MISSING_SECRET_CODE:
+				return 400;
 			case "NOT_FOUND":
 			case "not_found":
 			case "NO_DATA":
@@ -1224,8 +1251,16 @@ async function handleAuthFlow(
 		});
 	}
 
+	// Same SDK-owned gate as executeOperation: OAuth/credentials ceremonies
+	// depend on declared secrets (client ids/secrets), so fail structured before
+	// any flow code runs instead of at whatever point the ceremony first reads
+	// the env. `abort` stays exempt: a user must always be able to cancel a
+	// stranded flow even when provisioning is broken.
 	const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
 	try {
+		if (route !== "abort") {
+			assertRequiredSecretsPresent(provider, context.env);
+		}
 		const result =
 			route === "start"
 				? await flow.start(context)
@@ -1280,6 +1315,24 @@ export function createServerApp(
 			allowMemoryFallback: options.allowMemoryStateFallback === true,
 		});
 
+	// Boot-time visibility for unprovisioned declared secrets: emit a structured
+	// warn so deploy tooling/alerting sees the gap the moment the pod boots,
+	// instead of discovering it request-by-request. Deliberately log-only — a
+	// boot crash would trade a structured MISSING_SECRET signal for
+	// CrashLoopBackOff. Requests still fail closed via the executeOperation gate.
+	const missingSecretsAtBoot = listMissingRequiredSecrets(
+		provider,
+		createEnvContext(provider.secrets?.map((secret) => secret.name)),
+	);
+	if (missingSecretsAtBoot.length > 0) {
+		logger({
+			level: "warn",
+			event: "provider_secrets_missing",
+			providerId: provider.id,
+			missingSecrets: missingSecretsAtBoot,
+		});
+	}
+
 	app.notFound((c) =>
 		c.json(
 			{

package/dist/cli/templates/provider/CLAUDE.md.tpl

@@ -1 +0,0 @@
-@AGENTS.md

package/src/cli/templates/provider/CLAUDE.md.tpl

@@ -1 +0,0 @@
-@AGENTS.md