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

package/AUTHORING.md

@@ -32,6 +32,45 @@ No retry templates, next-action routing, or other agent choreography: provider p
 
 Declare the union in the operation `output` schema (`z.union([CreatedSchema, NeedsInputSchema])`). Reserve hard errors for genuinely unrecoverable flows (payment-gated, unsupported input kinds) and state the concrete reason in the error `message` itself, not only in `details`. Reference implementation: `providers/catchtable` `reserve` in the platform monorepo.
 
+### Attempt tokens: the server carries the decisions
+
+When a mutation needs more than one user decision (or one decision plus a
+final go/no-go), do not make the agent re-send accumulated state across
+rounds — weak models drop or corrupt it. Split the operation into a
+**prepare/confirm pair** driven by a server-held attempt record:
+
+- The prepare operation is non-destructive. A start call takes only the
+  scalar intent fields; every response returns a fresh `attempt_token`
+  referencing a server-side record (`ctx.choice.issue` with
+  `storage.mode: "server"`) that stores every settled decision. Continue
+  calls take `attempt_token` plus only the NEW answers.
+- `needs_input` rounds list only the still-pending selections; settled
+  decisions may ride along in a display-only field but are never re-sent.
+- When nothing is pending, the prepare operation returns `status: "ready"`
+  with a human-readable summary — the consumer's user-facing confirmation.
+- The confirm operation is the only mutation and takes exactly
+  `{attempt_token}`. It re-validates everything live before executing and
+  returns `needs_input` (fresh token) instead of proceeding when upstream
+  drift invalidates a stored decision — never substitute a different option
+  for what the user picked.
+- Expired or foreign tokens fail factually (nothing happened; start a new
+  attempt with the scalar fields) — no answer salvage from a dead token.
+- **The provider must enforce consumption itself.** `ctx.choice` server
+  storage keeps tokens parseable until TTL — `parse` does not invalidate
+  them, so a confirm handler that only parses can be replayed into a second
+  booking or payment. After a successful execution, record the result under
+  the token's digest in `ctx.state` and make replays idempotent: a repeated
+  confirm returns the original created payload without touching upstream,
+  and later prepare rounds on the consumed token fail factually with the
+  existing reference. Record the result only after upstream success, so an
+  interrupted confirm stays retryable.
+
+The invariant behind all of it: complex flow state is the system's job, not
+the model's. The model carries exactly one opaque key between calls.
+Reference implementations: `providers/catchtable` `reserve`/`reserve-confirm`
+(including the consume-on-success guard) and `providers/modu-parking`
+payment state tokens in the platform monorepo.
+
 ### Description template
 
 Every operation `description` MUST be at least 150 characters and follow this structure:

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.5
+
+- Release candidate for main commit 82fa14e99a9af7edd44e3196aa3f4e87b4699edf.
+
 ## 2.2.0-beta.4
 
 - Release candidate for main commit 73f2c6ec429c2fbce8ac458a67111e4844b99178.

package/bin/apifuse-submit-check.ts

@@ -3546,9 +3546,47 @@ function scoreProviderDocs(providerRoot: string): SubmitCheck[] {
 	];
 }
 
+// Splits secret findings into still-active findings and acknowledged
+// `// @apifuse-allow secret-scan` overrides, mirroring partitionAllowOverrides
+// (same pragma placement: the finding line or the line directly above it).
+// Every finding source carries a line number (entropy candidates and located
+// SECRET_PATTERNS matches); a finding that somehow lacks one stays active
+// defensively.
+function partitionSecretScanAllowOverrides(
+	providerRoot: string,
+	findings: readonly SecretFinding[],
+): { active: SecretFinding[]; overridden: SecretFinding[] } {
+	const fileLineCache = new Map<string, string[]>();
+	const active: SecretFinding[] = [];
+	const overridden: SecretFinding[] = [];
+
+	for (const finding of findings) {
+		if (finding.line === undefined) {
+			active.push(finding);
+			continue;
+		}
+		const absolute = resolve(providerRoot, finding.file);
+		let lines = fileLineCache.get(absolute);
+		if (lines === undefined) {
+			lines = existsSync(absolute) ? readFileSync(absolute, "utf8").split(/\r?\n/) : [];
+			fileLineCache.set(absolute, lines);
+		}
+		if (hasAllowOverride(lines, finding.line, "secret-scan")) {
+			overridden.push(finding);
+		} else {
+			active.push(finding);
+		}
+	}
+
+	return { active, overridden };
+}
+
 function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): SubmitCheck {
-	const findings = findSecretFindings(providerRoot, provider?.id);
-	const blockerFindings = findings.filter((finding) => finding.level !== "warn");
+	const { active, overridden } = partitionSecretScanAllowOverrides(
+		providerRoot,
+		findSecretFindings(providerRoot, provider?.id),
+	);
+	const blockerFindings = active.filter((finding) => finding.level !== "warn");
 	if (blockerFindings.length > 0) {
 		return {
 			id: "secret-scan",
@@ -3568,7 +3606,15 @@ function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): Subm
 			),
 		};
 	}
-	if (findings.length > 0) {
+	if (active.length > 0 || overridden.length > 0) {
+		const messageBase =
+			active.length > 0
+				? "High-entropy source strings were found without secret-like identifier context; they may be false positives."
+				: "Potential credential-like strings were found in shareable files.";
+		const message =
+			overridden.length > 0
+				? `${messageBase} ${overridden.length} acknowledged @apifuse-allow override(s).`
+				: messageBase;
 		return {
 			id: "secret-scan",
 			category: "security",
@@ -3576,11 +3622,10 @@ function scoreSecrets(providerRoot: string, provider?: ProviderDefinition): Subm
 			status: "warn",
 			points: 8,
 			maxPoints: CATEGORY_MAX_POINTS.security,
-			message:
-				"High-entropy source strings were found without secret-like identifier context; they may be false positives.",
+			message,
 			remediation:
-				'Review the listed strings. If any are credentials, move them to env vars read via `ctx.env.get("APIFUSE__PROVIDER__<ID>__<NAME>")` and rotate the leaked credential; otherwise keep generated blobs in fixtures/tests or document why they are public.',
-			evidence: findings.map(
+				'Review the listed strings. If any are credentials, move them to env vars read via `ctx.env.get("APIFUSE__PROVIDER__<ID>__<NAME>")` and rotate the leaked credential; otherwise keep generated blobs in fixtures/tests or document why they are public with `// @apifuse-allow secret-scan: <reason>`.',
+			evidence: [...active, ...overridden].map(
 				(finding) =>
 					finding.evidence ??
 					`${finding.file}${finding.line ? `:${finding.line}` : ""}: ${finding.label}`,
@@ -3611,8 +3656,19 @@ function findSecretFindings(providerRoot: string, providerId = "<ID>"): SecretFi
 		if (!existsSync(filePath)) continue;
 		const content = readFileSync(filePath, "utf8");
 		for (const [label, pattern] of SECRET_PATTERNS) {
-			if (pattern.test(content)) {
-				findings.push({ label, file: relativePath });
+			// Locate every match to its line so pattern findings carry the line
+			// information hasAllowOverride needs: `// @apifuse-allow secret-scan`
+			// must behave uniformly across entropy findings and pattern findings.
+			const globalPattern = new RegExp(
+				pattern.source,
+				pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`,
+			);
+			const seenLines = new Set<number>();
+			for (const match of content.matchAll(globalPattern)) {
+				const line = offsetToLine(content, match.index);
+				if (seenLines.has(line)) continue;
+				seenLines.add(line);
+				findings.push({ label, file: relativePath, line });
 			}
 		}
 	}
@@ -3670,7 +3726,7 @@ export function extractStringLiteralCandidates(line: string): string[] {
 				continue;
 			}
 			if (char === quote) {
-				if (cursor - contentStart >= 20) {
+				if (cursor - contentStart >= ENTROPY_CANDIDATE_MIN_LENGTH) {
 					candidates.push(line.slice(contentStart, cursor));
 				}
 				index = cursor;
@@ -3695,6 +3751,25 @@ function classifyEntropyCandidate(input: {
 	if (!charset) return undefined;
 	const entropy = shannonEntropy(value);
 	const secretishContext = SECRETISH_IDENTIFIER_PATTERN.test(input.line);
+	// Word-like SCREAMING_SNAKE values (e.g. error-code constants such as
+	// "AUTH_PASSWORD_LOGIN_CAPTCHA_REQUIRED") may contain secret-ish words
+	// (AUTH/PASSWORD/...) in their own text and would otherwise be permanently
+	// blocker-flagged. They are never skipped — entropy classification always
+	// runs — but when the secret-ish context comes solely from identifier-
+	// constant-shaped literal text (the line with those literals stripped
+	// carries no secret-ish identifier), the finding is capped at a
+	// non-blocking warning instead of a blocker. Stripping constant-shaped
+	// siblings — not just the candidate — matters for lines holding several
+	// constants (e.g. an ERROR_CODES array), while quoted property keys and
+	// header names ("Authorization", "apiKey") stay visible as genuine
+	// external context. Assignments to `apiKey`/`token`/`secret`-style names
+	// still escalate to blockers via the identifier side, and
+	// `// @apifuse-allow secret-scan` remains the reviewed way to silence the
+	// warning.
+	const selfContextOnlyConstant =
+		secretishContext &&
+		isScreamingSnakeConstantValue(value) &&
+		!SECRETISH_IDENTIFIER_PATTERN.test(stripIdentifierConstantLiterals(input.line, value));
 	const threshold = charset === "hex" ? 3.0 : secretishContext ? 4.0 : 4.5;
 	if (entropy < threshold) return undefined;
 
@@ -3705,16 +3780,163 @@ function classifyEntropyCandidate(input: {
 		charset === "hex"
 			? `high-entropy hex string (${entropy.toFixed(2)} bits/char)`
 			: `high-entropy base64-like string (${entropy.toFixed(2)} bits/char)`;
+	const contextNote = selfContextOnlyConstant
+		? "; identifier-like constant (downgraded to warning)"
+		: secretishContext
+			? ""
+			: "; may be a false positive";
 	return {
 		label,
 		file: input.file,
 		line: input.lineNumber,
-		level: secretishContext ? "blocker" : "warn",
+		level: secretishContext && !selfContextOnlyConstant ? "blocker" : "warn",
 		remediation: `Move ${location} to an env var read via \`ctx.env.get("${envName}")\` and rotate the leaked credential.`,
-		evidence: `${location}: ${label}; preview ${preview}${secretishContext ? "" : "; may be a false positive"}`,
+		evidence: `${location}: ${label}; preview ${preview}${contextNote}`,
 	};
 }
 
+// Word-like SCREAMING_SNAKE identifier shape: at least two underscore-
+// separated segments, each essentially pure alphabetic — letters optionally
+// followed by a SHORT digit suffix (at most 2, e.g. version markers like
+// "V2") — and at most 15% digits across the whole value. Dictionary-style
+// constants like "AUTH_PASSWORD_LOGIN_CAPTCHA_REQUIRED" or
+// "PROVIDER_CONTRACT_V2_REQUIRED" match; digit-heavy segmented material
+// (e.g. license/credential shapes like "ABCD1234_EFGH5678_IJKL9012"),
+// uppercase blobs ("XK9J_Q2ZP_M7VN"), and underscore-free hex-like values
+// ("A1B2C3D4...") do not. This shape gate never skips entropy classification;
+// it only decides whether a finding whose secret-ish context comes solely
+// from the literal's own text is downgraded from blocker to warning, so it
+// deliberately stays strict: values that merely contain a secret-ish word but
+// are not word-like constants keep full blocker severity.
+function isScreamingSnakeConstantValue(value: string): boolean {
+	if (!/^[A-Z][A-Z0-9_]*$/.test(value) || !value.includes("_")) return false;
+	const segments = value.split("_");
+	if (segments.length < 2) return false;
+	if (!segments.every((segment) => /^[A-Z]+[0-9]{0,2}$/.test(segment))) return false;
+	const digitCount = value.match(/[0-9]/g)?.length ?? 0;
+	return digitCount / value.length <= 0.15;
+}
+
+type LineStringLiteral = {
+	// Index of the opening quote.
+	start: number;
+	// Index just past the closing quote (line end when unterminated).
+	end: number;
+	content: string;
+	closed: boolean;
+	role: "key" | "value";
+	// Nearest unclosed bracket enclosing the literal's start, if any.
+	container?: { bracket: "[" | "(" | "{"; index: number };
+};
+
+// Stable identity for the container a literal sits in ("top" when the
+// literal is not inside any bracket on the line).
+function literalContainerKey(literal: LineStringLiteral): string {
+	return literal.container
+		? `${literal.container.bracket}${literal.container.index}`
+		: "top";
+}
+
+// Single-pass line tokenizer: extracts every string literal with its span and
+// classifies its syntactic role once. A literal is a KEY when it is preceded
+// (ignoring whitespace) by "{", ",", "(", or the line start AND followed
+// (ignoring whitespace) by ":" — i.e. it names the value next to it. Every
+// other literal is a VALUE: ternary arms (preceded by "?" or ":"), array
+// elements, call arguments, and assignment right-hand sides, even when a
+// ternary's ":" happens to follow them. Uses the same quote/escape walking as
+// extractStringLiteralCandidates.
+function tokenizeLineStringLiterals(line: string): LineStringLiteral[] {
+	const literals: LineStringLiteral[] = [];
+	const bracketStack: Array<{ bracket: "[" | "(" | "{"; index: number }> = [];
+	let index = 0;
+	while (index < line.length) {
+		const char = line[index];
+		if (char !== '"' && char !== "'" && char !== "`") {
+			if (char === "[" || char === "(" || char === "{") {
+				bracketStack.push({ bracket: char, index });
+			} else if (char === "]" || char === ")" || char === "}") {
+				bracketStack.pop();
+			}
+			index += 1;
+			continue;
+		}
+		const quote = char;
+		const start = index;
+		const contentStart = index + 1;
+		let cursor = contentStart;
+		let closed = false;
+		while (cursor < line.length) {
+			const inner = line[cursor];
+			if (inner === "\\") {
+				cursor += 2;
+				continue;
+			}
+			if (inner === quote) {
+				closed = true;
+				break;
+			}
+			cursor += 1;
+		}
+		const contentEnd = Math.min(cursor, line.length);
+		const end = closed ? cursor + 1 : line.length;
+		const before = line.slice(0, start).trimEnd();
+		const keyPreceded = before === "" || /[{,(]$/.test(before);
+		const keyFollowed = closed && /^\s*:/.test(line.slice(end));
+		literals.push({
+			start,
+			end,
+			content: line.slice(contentStart, contentEnd),
+			closed,
+			role: keyPreceded && keyFollowed ? "key" : "value",
+			container: bracketStack[bracketStack.length - 1],
+		});
+		index = end;
+	}
+	return literals;
+}
+
+// Builds the context text used to decide whether a candidate's secret-ish
+// context is genuine. The candidate's own literal is ALWAYS stripped
+// (self-context rule). SIBLING identifier-constant-shaped candidate literals
+// (VALUE role, SCREAMING_SNAKE shape, >= ENTROPY_CANDIDATE_MIN_LENGTH) are
+// stripped only when they share the candidate's non-call container — the same
+// `[...]` array, the same `{...}` object value list, or the bracket-free top
+// level (ternary arms) — so a value list of error codes cannot poison its own
+// members' context. Call-argument siblings (inside `(...)`) always keep their
+// context: in `headers.set("X_LONG_AUTH_TOKEN_NAME", "QWERTY_...")` the first
+// argument genuinely describes the second, so stripping it would erase real
+// auth/token context. KEY-role literals are never stripped.
+function stripIdentifierConstantLiterals(line: string, candidate: string): string {
+	const literals = tokenizeLineStringLiterals(line);
+	const candidateContainers = new Set<string>();
+	for (const literal of literals) {
+		if (literal.content === candidate) {
+			candidateContainers.add(literalContainerKey(literal));
+		}
+	}
+	let result = "";
+	let previousEnd = 0;
+	for (const literal of literals) {
+		result += line.slice(previousEnd, literal.start);
+		const isSelf = literal.content === candidate;
+		const isSameNonCallContainerSibling =
+			literal.role === "value" &&
+			literal.content.length >= ENTROPY_CANDIDATE_MIN_LENGTH &&
+			isScreamingSnakeConstantValue(literal.content) &&
+			literal.container?.bracket !== "(" &&
+			candidateContainers.has(literalContainerKey(literal));
+		if (isSelf || isSameNonCallContainerSibling) {
+			const quote = line[literal.start] ?? "";
+			result += quote + (literal.closed ? quote : "");
+		} else {
+			result += line.slice(literal.start, literal.end);
+		}
+		previousEnd = literal.end;
+	}
+	result += line.slice(previousEnd);
+	return result;
+}
+
 function shouldConsiderEntropyValue(value: string): boolean {
 	const lower = value.toLowerCase();
 	if (/^(?:dev-only|local|example|sample|your-|replace|<)/i.test(value)) {
@@ -3730,7 +3952,7 @@ function shouldConsiderEntropyValue(value: string): boolean {
 	if (lower.includes("/") && /\.[a-z0-9]{1,8}(?:$|[/?#])/i.test(value)) {
 		return false;
 	}
-	return value.length >= 20;
+	return value.length >= ENTROPY_CANDIDATE_MIN_LENGTH;
 }
 
 function classifyEntropyCharset(value: string): "base64" | "hex" | undefined {
@@ -3764,6 +3986,11 @@ function guessSecretName(line: string): string {
 
 const SECRETISH_IDENTIFIER_PATTERN = /key|token|secret|password|credential|auth/i;
 
+// Minimum length for a string literal to be considered an entropy candidate.
+// Shared by candidate extraction, entropy screening, and the context strip so
+// the three stay coherent.
+const ENTROPY_CANDIDATE_MIN_LENGTH = 20;
+
 const SECRET_PATTERNS: Array<[string, RegExp]> = [
 	["JWT-like token", /eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}/],
 	["GitHub token", /gh[pousr]_[A-Za-z0-9_]{30,}/],

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