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

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

@@ -1,8 +1,8 @@
 import { Hono } from "hono";
 import { z } from "zod";
-import type { OperationDefinition, ProviderDefinition } from "../types";
-import { type SelfTestMasterSecrets } from "./self-test-token";
-import type { OperationConnection } from "./types";
+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";
@@ -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