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

package/dist/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/dist/index.d.ts

@@ -27,6 +27,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } 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, } from "./runtime/state.js";
 export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";

package/dist/index.js

@@ -24,6 +24,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";

package/dist/runtime/executor.js

@@ -1,5 +1,6 @@
 import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
 import { parseSchema } from "../schema.js";
+import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
     const kind = provider.operations[operationId]?.transport?.kind ?? "json";
     return kind !== "json";
@@ -23,6 +24,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }
+    // 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, `operations.${operationId}.input`);
     const execute = () => ctx.trace.span(`handler:${operationId}`, () => Promise.resolve(operation.handler(ctx, validatedInput)));
     let result;

package/dist/runtime/secrets.d.ts

@@ -0,0 +1,27 @@
+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 declare 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 declare function listMissingRequiredSecrets(provider: ProviderDefinition, env: EnvContext): string[];
+/**
+ * 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 declare function assertRequiredSecretsPresent(provider: ProviderDefinition, env: EnvContext): void;

package/dist/runtime/secrets.js

@@ -0,0 +1,51 @@
+import { ProviderSecretError } from "../errors.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, env) {
+    const missing = [];
+    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, env) {
+    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/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 export { createServerApp, type ServeOptions, serve } from "./serve.js";
-export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
+export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";

package/dist/server/index.js

@@ -1,5 +1,5 @@
 export { createServerApp, serve } from "./serve.js";
-export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
+export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";

package/dist/server/self-test.d.ts

@@ -61,11 +61,53 @@ export type SelfTestOperationInvoke = (args: {
     data: unknown;
     meta?: Record<string, unknown>;
 }>;
+export type SelfTestAuthFlowRoute = "start" | "continue";
+/**
+ * In-process driver for the tenant app's /auth pipeline. Self-test uses it to
+ * materialize `requiresConnection` credentials through the provider's declared
+ * auth flow — the exact path production connections take — instead of
+ * injecting raw credential inputs as connection secrets.
+ */
+export type SelfTestAuthFlowInvoke = (args: {
+    route: SelfTestAuthFlowRoute;
+    requestId: string;
+    flowId: string;
+    /** Stable per-credential connection id — keeps login on the probe's affinity. */
+    connectionId?: string;
+    /** The probe connection's externalRef — flows reading ctx.externalRef see the same identity. */
+    externalRef?: string;
+    input?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+/**
+ * Skip reason reported when a declared auth flow does not complete in a single
+ * continue (OTP, retry loop). Cross-repo contract: the health-monitor maps
+ * this exact string to `self_test_incapable`; never vary it.
+ */
+export declare const SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON = "auth_flow_multi_turn";
+/**
+ * A `retry` turn after credential submission: the flow REJECTED the
+ * configured inputs (bad password, exchange failure). Distinct from the
+ * multi-turn gap so monitoring surfaces it as a real credential outage, and
+ * memoized like multi-turn so the probe does not re-submit rejected
+ * credentials every cycle (lockout safety).
+ */
+export declare const SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON = "auth_flow_rejected";
 export interface SelfTestAppOptions {
     /** Derived-token verification secrets; without them every self-test route 404s. */
     secrets?: SelfTestMasterSecrets;
     /** In-process invoke bound to the tenant-facing app's /v1 pipeline. */
     invoke: SelfTestOperationInvoke;
+    /**
+     * In-process auth-flow driver bound to the tenant-facing app's /auth
+     * pipeline. Required for providers that declare `auth.mode: "credentials"`
+     * with a flow; without it their requiresConnection cases report a visible
+     * auth_flow_unavailable error instead of probing with raw inputs.
+     */
+    authFlow?: SelfTestAuthFlowInvoke;
     /** Overall request budget; defaults to env / 120s. */
     requestBudgetMs?: number;
     /** Env override for secret collection + budget resolution (tests). */
@@ -88,6 +130,65 @@ export declare function isSelfTestReadOnlyOperation(operation: OperationDefiniti
 export declare function createSelfTestInvoke(app: {
     request: (input: string, requestInit?: RequestInit) => Response | Promise<Response>;
 }): SelfTestOperationInvoke;
+/** Binds the self-test auth-flow driver to a tenant app's /auth pipeline in-process. */
+export declare function createSelfTestAuthFlowInvoke(app: {
+    request: (input: string, requestInit?: RequestInit) => Response | Promise<Response>;
+}): SelfTestAuthFlowInvoke;
+/**
+ * How long a memoized multi-turn flow outcome suppresses re-driving the auth
+ * flow. Generous on purpose: a multi-turn ceremony (OTP, device approval) is a
+ * provider property that changes on the timescale of releases, not probe
+ * cycles, and every re-drive is a REAL upstream login submission. The cache is
+ * in-process, so a pod restart also clears the entry.
+ */
+export declare const SELF_TEST_MULTI_TURN_RETRY_AFTER_MS: number;
+/**
+ * Age bound for POSITIVE cached credentials. Expiry modes that never produce
+ * a 401/403 (a 200 login page, an assertion failure) would otherwise replay
+ * the same stale session until pod restart — one re-login per day is the
+ * upstream-safe recovery for them.
+ */
+export declare const SELF_TEST_CREDENTIAL_MAX_AGE_MS: number;
+export type SelfTestCredentialSessionEntry = 
+/** Flow-materialized credential reused across probe cycles. */
+{
+    kind: "credential";
+    credential: Record<string, string>;
+    cachedAtMs: number;
+}
+/**
+ * Negative entry: the flow did not complete in a single continue turn
+ * (`auth_flow_multi_turn`). Memoized so subsequent cycles report the skip
+ * WITHOUT contacting the upstream again — the first attempt already
+ * submitted real credentials (and may have triggered an OTP send).
+ */
+ | {
+    kind: "multi_turn";
+    cachedAtMs: number;
+}
+/**
+ * Negative entry: the flow REJECTED the submitted credential inputs
+ * (`retry` turn after continue — bad password, exchange failure).
+ * Memoized so the probe does not re-submit rejected credentials every
+ * cycle; a new entry is attempted when the inputs rotate (new hash),
+ * the TTL lapses, or the process restarts.
+ */
+ | {
+    kind: "rejected";
+    cachedAtMs: number;
+};
+/**
+ * In-process cache of per-(providerId + stable hash of credentialInputs) auth
+ * flow outcomes, so consecutive probe cycles reuse the session — or the
+ * memoized multi-turn skip — instead of logging in every cycle (upstream
+ * account safety, DR-7). Credential entries are invalidated on a probe auth
+ * failure, at most once; multi-turn entries expire after
+ * `SELF_TEST_MULTI_TURN_RETRY_AFTER_MS` or on process restart. Flow ERRORS
+ * (transport/protocol failures, thrown start/continue) are deliberately NEVER
+ * cached: they are typically transient, and retrying a failed request next
+ * cycle is not a repeated login submission.
+ */
+export type SelfTestCredentialSessionCache = Map<string, SelfTestCredentialSessionEntry>;
 export declare function resolveSelfTestPort(env?: Readonly<Record<string, string | undefined>>): number;
 /**
  * Builds the internal self-test Hono app. This app is served on a SEPARATE