@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/dist/runtime/stt.js

@@ -1,4 +1,4 @@
-import { ProviderError, TransportError, ValidationError } from "../errors";
+import { ProviderError, TransportError, ValidationError } from "../errors.js";
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
 export const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";
@@ -59,17 +59,12 @@ export function createSttClientFromEnv(config, env = process.env) {
     return createCloudflareWorkersAiSttClient({
         accountId,
         apiToken,
-        model: normalizedEnvValue(env, APIFUSE__STT__MODEL_ENV) ??
-            DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL,
+        model: normalizedEnvValue(env, APIFUSE__STT__MODEL_ENV) ?? DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL,
     });
 }
 function base64ByteLength(data) {
     const normalized = data.trim();
-    const padding = normalized.endsWith("==")
-        ? 2
-        : normalized.endsWith("=")
-            ? 1
-            : 0;
+    const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
     return Math.floor((normalized.length * 3) / 4) - padding;
 }
 function assertBase64Audio(audio, maxAudioBytes) {
@@ -80,9 +75,7 @@ function assertBase64Audio(audio, maxAudioBytes) {
         });
     }
     const data = audio.data.trim();
-    if (data.length === 0 ||
-        data.length % 4 !== 0 ||
-        !BASE64_AUDIO_PATTERN.test(data)) {
+    if (data.length === 0 || data.length % 4 !== 0 || !BASE64_AUDIO_PATTERN.test(data)) {
         throw new ValidationError("STT audio.data must be a base64-encoded string", {
             code: "INVALID_STT_AUDIO",
         });
@@ -90,7 +83,9 @@ function assertBase64Audio(audio, maxAudioBytes) {
     const bytes = base64ByteLength(data);
     const maxBytes = maxAudioBytes ?? DEFAULT_STT_MAX_AUDIO_BYTES;
     if (bytes > maxBytes) {
-        throw new ValidationError(`STT audio exceeds maxAudioBytes (${bytes} > ${maxBytes})`, { code: "STT_AUDIO_TOO_LARGE" });
+        throw new ValidationError(`STT audio exceeds maxAudioBytes (${bytes} > ${maxBytes})`, {
+            code: "STT_AUDIO_TOO_LARGE",
+        });
     }
     return bytes;
 }
@@ -227,8 +222,7 @@ export function createCloudflareWorkersAiSttClient(options) {
     return {
         async transcribe(request) {
             const warnings = [];
-            if (request.initialPrompt &&
-                effectivePromptPolicy(request) !== "custom-hint") {
+            if (request.initialPrompt && effectivePromptPolicy(request) !== "custom-hint") {
                 const warning = warnOrThrowUnsupportedOption(request, "initialPrompt is honored only when promptPolicy is custom-hint");
                 if (warning)
                     warnings.push(warning);
@@ -350,7 +344,9 @@ function lengthSet(codeLengths) {
 }
 function validCodeLength(value) {
     if (!Number.isInteger(value) || value < 1 || value > 32) {
-        throw new ValidationError("STT verification code length must be an integer between 1 and 32", { code: "INVALID_STT_VERIFICATION_CODE_OPTIONS" });
+        throw new ValidationError("STT verification code length must be an integer between 1 and 32", {
+            code: "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+        });
     }
     return value;
 }

package/dist/runtime/trace.d.ts

@@ -1,5 +1,5 @@
-import type { TraceContext as BaseTraceContext, TraceAttributeValue, TraceConfig, TraceSpan } from "../types";
-import { type OTLPExportOptions } from "./otlp";
+import type { TraceContext as BaseTraceContext, TraceAttributeValue, TraceConfig, TraceSpan } from "../types.js";
+import { type OTLPExportOptions } from "./otlp.js";
 export type SpanAttributeValue = TraceAttributeValue;
 export type Span = TraceSpan;
 export interface TraceContext extends BaseTraceContext {

package/dist/runtime/trace.js

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { exportSpansOTLP } from "./otlp";
+import { exportSpansOTLP } from "./otlp.js";
 export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-recorder");
 function buildOTLPExportOptions(config) {
     if (config?.exporter !== "otlp") {
@@ -23,9 +23,7 @@ export function resolveTraceContextOptions(config) {
     };
 }
 function normalizeAttributeValue(value) {
-    if (typeof value === "string" ||
-        typeof value === "number" ||
-        typeof value === "boolean") {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         return value;
     }
     if (value === null || value === undefined) {

package/dist/runtime/waterfall.d.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 export type WaterfallRequest = {
     method: string;
     path: string;

package/dist/schema.d.ts

@@ -1,5 +1,5 @@
 import { type ZodString, type ZodType, z } from "zod";
-import type { InferSchemaOutput, ProviderLocaleKey, SchemaLike } from "./types";
+import type { InferSchemaOutput, ProviderLocaleKey, SchemaLike } from "./types.js";
 export { z };
 export type SchemaValidationResult<TSchema extends SchemaLike> = {
     success: true;

package/dist/schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { ValidationError } from "./errors";
-import { providerLocaleKey } from "./i18n/keys";
+import { ValidationError } from "./errors.js";
+import { providerLocaleKey } from "./i18n/keys.js";
 export { z };
 function isFailureResult(result) {
     return "issues" in result;
@@ -99,21 +99,15 @@ export function field(schema, options = {}) {
     const metadata = described.meta() ?? {};
     return described.meta({
         ...metadata,
-        ...((options.sensitive ?? true)
-            ? { [APIFUSE_SENSITIVE_META_KEY]: true }
-            : {}),
-        ...(options.kind
-            ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: options.kind }
-            : {}),
+        ...((options.sensitive ?? true) ? { [APIFUSE_SENSITIVE_META_KEY]: true } : {}),
+        ...(options.kind ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: options.kind } : {}),
     });
 }
 export function sensitive(schema, kind) {
     return field(schema, { sensitive: true, kind });
 }
 function sensitiveString(kind, description, options = {}) {
-    const schema = options.minLength === undefined
-        ? z.string()
-        : z.string().min(options.minLength);
+    const schema = options.minLength === undefined ? z.string() : z.string().min(options.minLength);
     return field(schema, {
         kind,
         description: options.description ?? description,
@@ -132,8 +126,7 @@ export const fields = {
 };
 export function isSensitiveSchema(schema) {
     const metadata = readZodMetadata(schema);
-    return (metadata !== undefined &&
-        Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true);
+    return metadata !== undefined && Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true;
 }
 export function collectSensitivePaths(schema) {
     const out = [];
@@ -217,8 +210,7 @@ function pathMatches(path, patterns) {
 }
 function isReservedSensitiveKey(key) {
     const normalized = key.toLowerCase().replace(/[-_\s]/g, "");
-    return (RESERVED_SENSITIVE_KEYS.has(normalized) ||
-        RESERVED_SENSITIVE_KEYS.has(key.toLowerCase()));
+    return RESERVED_SENSITIVE_KEYS.has(normalized) || RESERVED_SENSITIVE_KEYS.has(key.toLowerCase());
 }
 function readZodMetadata(schema) {
     if (!schema || typeof schema !== "object" || !("meta" in schema)) {

package/dist/serve.d.ts

@@ -1 +1 @@
-export { createServerApp, type ServeOptions, serve } from "./server/serve";
+export { createServerApp, type ServeOptions, serve } from "./server/serve.js";

package/dist/serve.js

@@ -1 +1 @@
-export { createServerApp, serve } from "./server/serve";
+export { createServerApp, serve } from "./server/serve.js";

package/dist/server/index.d.ts

@@ -1,3 +1,7 @@
-export { createServerApp, type ServeOptions, serve } from "./serve";
-export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types";
-export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";
+export { createServerApp, type ServeOptions, serve } from "./serve.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";
+export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";
+export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";

package/dist/server/index.js

@@ -1,2 +1,6 @@
-export { createServerApp, serve } from "./serve";
-export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types";
+export { createServerApp, serve } from "./serve.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";
+export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";

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

@@ -0,0 +1 @@
+export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date): unknown;

package/dist/server/self-test-input-tokens.js

@@ -0,0 +1,37 @@
+/**
+ * Relative-KST date token resolution for health-check case inputs, ported from
+ * the monorepo health-monitor (`apps/health-monitor/src/lib/health-check-input.ts`)
+ * so provider self-tests resolve durable probe inputs identically.
+ *
+ * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead, KST).
+ */
+const RELATIVE_KST_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
+function dateFromKstDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD") {
+    const kstNow = new Date(now.getTime() + 9 * 60 * 60 * 1000);
+    const date = new Date(Date.UTC(kstNow.getUTCFullYear(), kstNow.getUTCMonth(), kstNow.getUTCDate() + daysAhead));
+    const isoDate = date.toISOString().slice(0, 10);
+    return format === "YYYYMMDD" ? isoDate.replace(/-/g, "") : isoDate;
+}
+export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
+    if (typeof value === "string") {
+        const relative = value.match(RELATIVE_KST_DATE_TOKEN);
+        if (!relative)
+            return value;
+        const daysAhead = Number(relative[1]);
+        if (!Number.isInteger(daysAhead) || daysAhead < 1 || daysAhead > 365) {
+            return value;
+        }
+        const format = relative[2]?.toUpperCase() === "YYYYMMDD" ? "YYYYMMDD" : "YYYY-MM-DD";
+        return dateFromKstDaysAhead(daysAhead, now, format);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => resolveHealthCheckInputDateTokens(entry, now));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            resolveHealthCheckInputDateTokens(entry, now),
+        ]));
+    }
+    return value;
+}

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

@@ -0,0 +1,20 @@
+import type { ProviderDefinition } from "../types.js";
+export declare const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
+/** Maximum length of any string echoed in a self-test response. */
+export declare const SELF_TEST_MAX_TEXT_LENGTH = 300;
+/**
+ * Collects every secret-shaped value known to the self-test runtime so probe
+ * results can be scrubbed before they leave the pod: master secrets, declared
+ * provider env secrets, health-probe credential env values, and request-supplied
+ * credential inputs.
+ */
+export declare function collectSelfTestSensitiveValues(provider: ProviderDefinition, options?: {
+    env?: Readonly<Record<string, string | undefined>>;
+    credentialInputs?: Readonly<Record<string, string>>;
+}): string[];
+/**
+ * Scrubs known secret values and header-shaped credentials from a string and
+ * caps its length. Every string embedded in a SelfTestResponse MUST pass
+ * through this before serialization.
+ */
+export declare function redactSelfTestText(text: string, sensitiveValues: readonly string[], maxLength?: number): string;

package/dist/server/self-test-redaction.js

@@ -0,0 +1,70 @@
+import { PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, } from "./self-test-token.js";
+export const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
+/** Maximum length of any string echoed in a self-test response. */
+export const SELF_TEST_MAX_TEXT_LENGTH = 300;
+/** Values shorter than this are too generic to be treated as secrets. */
+const MIN_SENSITIVE_VALUE_LENGTH = 4;
+const HEADER_SHAPED_SECRETS = [
+    /(authorization\s*[:=]\s*)[^\s;,]+/gi,
+    /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi,
+    /((?:set-)?cookie\s*[:=]\s*)[^;\n]+/gi,
+];
+/**
+ * Collects every secret-shaped value known to the self-test runtime so probe
+ * results can be scrubbed before they leave the pod: master secrets, declared
+ * provider env secrets, health-probe credential env values, and request-supplied
+ * credential inputs.
+ */
+export function collectSelfTestSensitiveValues(provider, options = {}) {
+    const env = options.env ?? process.env;
+    const envNames = new Set([
+        PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
+        PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
+    ]);
+    for (const secret of provider.secrets ?? []) {
+        envNames.add(secret.name);
+    }
+    const healthProbe = provider.healthProbe ?? provider.healthMonitor;
+    for (const name of healthProbe?.requiredSecrets ?? []) {
+        envNames.add(name);
+    }
+    for (const name of Object.values(healthProbe?.credentialInputs ?? {})) {
+        envNames.add(name);
+    }
+    const values = new Set();
+    for (const name of envNames) {
+        const value = env[name];
+        if (typeof value === "string" && value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
+            values.add(value);
+        }
+    }
+    for (const value of Object.values(options.credentialInputs ?? {})) {
+        if (value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
+            values.add(value);
+        }
+    }
+    return [...values];
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Scrubs known secret values and header-shaped credentials from a string and
+ * caps its length. Every string embedded in a SelfTestResponse MUST pass
+ * through this before serialization.
+ */
+export function redactSelfTestText(text, sensitiveValues, maxLength = SELF_TEST_MAX_TEXT_LENGTH) {
+    let redacted = text;
+    for (const value of sensitiveValues) {
+        if (value.length < MIN_SENSITIVE_VALUE_LENGTH)
+            continue;
+        redacted = redacted.replace(new RegExp(escapeRegExp(value), "g"), SELF_TEST_REDACTED_PLACEHOLDER);
+    }
+    for (const pattern of HEADER_SHAPED_SECRETS) {
+        redacted = redacted.replace(pattern, (_match, prefix) => `${prefix}${SELF_TEST_REDACTED_PLACEHOLDER}`);
+    }
+    if (redacted.length > maxLength) {
+        redacted = `${redacted.slice(0, maxLength)}… [truncated]`;
+    }
+    return redacted;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Shared master secret injected into every provider pod. The per-provider
+ * bearer token is derived from it, so compromise of one pod's env cannot
+ * unlock another provider's self-test endpoint.
+ */
+export declare const PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET";
+/**
+ * Previous master secret accepted during a rotation window so fleet-wide
+ * rotation does not need to be atomic.
+ */
+export declare const PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET_PREVIOUS";
+/** Internal self-test listener port (never the tenant-facing serve() port). */
+export declare const PROVIDER_RUNTIME_SELF_TEST_PORT_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT";
+export declare const DEFAULT_SELF_TEST_PORT = 3001;
+export interface SelfTestMasterSecrets {
+    readonly current: string;
+    readonly previous?: string;
+}
+/**
+ * Per-provider self-test bearer token: HMAC-SHA256(masterSecret, providerId),
+ * hex-encoded. Computed identically by the provider pod and the scheduler.
+ */
+export declare function deriveSelfTestToken(masterSecret: string, providerId: string): string;
+export declare function resolveSelfTestMasterSecrets(env?: Readonly<Record<string, string | undefined>>): SelfTestMasterSecrets | undefined;
+/**
+ * Verifies an Authorization header against the current-or-previous derived
+ * token (dual acceptance for one rotation window). Constant-time comparison;
+ * returns only a boolean so callers cannot leak which check failed.
+ */
+export declare function verifySelfTestAuthorization(authorizationHeader: string | undefined, providerId: string, secrets: SelfTestMasterSecrets): boolean;

package/dist/server/self-test-token.js

@@ -0,0 +1,50 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Shared master secret injected into every provider pod. The per-provider
+ * bearer token is derived from it, so compromise of one pod's env cannot
+ * unlock another provider's self-test endpoint.
+ */
+export const PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET";
+/**
+ * Previous master secret accepted during a rotation window so fleet-wide
+ * rotation does not need to be atomic.
+ */
+export const PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET_PREVIOUS";
+/** Internal self-test listener port (never the tenant-facing serve() port). */
+export const PROVIDER_RUNTIME_SELF_TEST_PORT_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT";
+export const DEFAULT_SELF_TEST_PORT = 3001;
+/**
+ * Per-provider self-test bearer token: HMAC-SHA256(masterSecret, providerId),
+ * hex-encoded. Computed identically by the provider pod and the scheduler.
+ */
+export function deriveSelfTestToken(masterSecret, providerId) {
+    return createHmac("sha256", masterSecret).update(providerId).digest("hex");
+}
+export function resolveSelfTestMasterSecrets(env = process.env) {
+    const current = env[PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV]?.trim();
+    if (!current)
+        return undefined;
+    const previous = env[PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV]?.trim();
+    return previous ? { current, previous } : { current };
+}
+function digestsMatch(presented, expected) {
+    // Hash both sides before comparison so timingSafeEqual sees equal-length
+    // buffers regardless of what the caller presented (constant-time path).
+    const presentedDigest = createHash("sha256").update(presented).digest();
+    const expectedDigest = createHash("sha256").update(expected).digest();
+    return timingSafeEqual(presentedDigest, expectedDigest);
+}
+/**
+ * Verifies an Authorization header against the current-or-previous derived
+ * token (dual acceptance for one rotation window). Constant-time comparison;
+ * returns only a boolean so callers cannot leak which check failed.
+ */
+export function verifySelfTestAuthorization(authorizationHeader, providerId, secrets) {
+    const match = /^Bearer\s+(\S+)$/i.exec(authorizationHeader ?? "");
+    const presented = match?.[1] ?? "";
+    const currentOk = digestsMatch(presented, deriveSelfTestToken(secrets.current, providerId));
+    const previousOk = secrets.previous
+        ? digestsMatch(presented, deriveSelfTestToken(secrets.previous, providerId))
+        : false;
+    return currentOk || previousOk;
+}

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

@@ -0,0 +1,199 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import type { OperationDefinition, ProviderDefinition } from "../types.js";
+import { type SelfTestMasterSecrets } from "./self-test-token.js";
+import type { OperationConnection } from "./types.js";
+export declare const SELF_TEST_SCHEMA_VERSION: 1;
+export declare const SELF_TEST_PATH = "/internal/health/self-test";
+export declare const SELF_TEST_HEALTHZ_PATH = "/healthz";
+/** Overall wall-clock budget for one self-test request (all selected cases). */
+export declare const PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_REQUEST_BUDGET_MS";
+export declare const DEFAULT_SELF_TEST_REQUEST_BUDGET_MS = 120000;
+export declare const SelfTestRequestSchema: z.ZodObject<{
+    schemaVersion: z.ZodNumber;
+    requestId: z.ZodString;
+    operationId: z.ZodOptional<z.ZodString>;
+    caseName: z.ZodOptional<z.ZodString>;
+    operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    caseNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    credentials: z.ZodOptional<z.ZodObject<{
+        inputs: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SelfTestRequest = z.infer<typeof SelfTestRequestSchema>;
+export type SelfTestCaseStatus = "ok" | "degraded" | "failed" | "error" | "skipped";
+export interface SelfTestCaseResult {
+    operationId: string;
+    caseName: string;
+    status: SelfTestCaseStatus;
+    label: string;
+    responseTimeMs: number;
+    httpStatus?: number;
+    assertion?: {
+        passed: boolean;
+        message?: string;
+    };
+    skipReason?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    startedAt: string;
+    finishedAt: string;
+}
+export interface SelfTestResponse {
+    schemaVersion: typeof SELF_TEST_SCHEMA_VERSION;
+    providerId: string;
+    sdkVersion: string;
+    planDigest: string;
+    /** Present for single-case requests (mirrors results[0]). */
+    result?: SelfTestCaseResult;
+    results: SelfTestCaseResult[];
+}
+export type SelfTestOperationInvoke = (args: {
+    operationId: string;
+    input: unknown;
+    connection?: OperationConnection;
+    requestId: string;
+}) => Promise<{
+    status: number;
+    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). */
+    env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Stable sha256 over the provider's declared health plan (operations, case
+ * names, timeouts) so the scheduler can detect plan/image skew by comparing
+ * the manifest planDigest against the pod-reported one.
+ */
+export declare function computeSelfTestPlanDigest(provider: ProviderDefinition): string;
+/**
+ * Fail-closed read-only classification: an operation may self-test only when
+ * its own metadata marks it read-only (annotations.readOnly or
+ * toolRouter.riskClass "read") and nothing marks it side-effecting. Unclassified
+ * operations are refused so the endpoint cannot become a mutation oracle.
+ */
+export declare function isSelfTestReadOnlyOperation(operation: OperationDefinition): boolean;
+/** Binds the self-test executor to a tenant app's /v1 pipeline in-process. */
+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
+ * listener (default :3001) that the tenant-facing gateway never dials; when no
+ * master secret is resolvable the self-test route responds 404 (safe default
+ * off) while `GET /healthz` stays available for liveness.
+ */
+export declare function createSelfTestApp(provider: ProviderDefinition, options: SelfTestAppOptions): Hono;