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

package/dist/server/serve.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
+import { AuthAbortError, createAuthFlowHelpers } from "../auth";
 import { AuthError, ProviderError, SessionExpiredError, TransportError, } from "../errors";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability";
@@ -24,6 +25,8 @@ import { createTraceContext } from "../runtime/trace";
 import { parseSchema } from "../schema";
 import { getStealthProfile } from "../stealth/profiles";
 import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream";
+import { createSelfTestApp, createSelfTestInvoke, resolveSelfTestPort, } from "./self-test";
+import { resolveSelfTestMasterSecrets } from "./self-test-token";
 import { AuthFlowRequestSchema, OperationRequestSchema, } from "./types";
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
@@ -104,7 +107,7 @@ function isProductionProviderBrowserMode(provider, env = process.env) {
     return (env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id);
 }
 export function resolveProviderProxyAffinityKey(provider, request, operationId) {
-    const connectionKey = request.connection?.id ?? request.connection?.externalRef;
+    const connectionKey = resolveOperationConnectionId(request) ?? request.connection?.externalRef;
     const affinity = typeof provider.proxy === "object"
         ? provider.proxy.session?.affinity
         : undefined;
@@ -113,6 +116,9 @@ export function resolveProviderProxyAffinityKey(provider, request, operationId)
     }
     return connectionKey ?? provider.id;
 }
+function resolveOperationConnectionId(request) {
+    return request.connection?.id ?? request.connectionId;
+}
 function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
@@ -139,7 +145,7 @@ function createProviderContext(provider, request, operationId, options = {}, sta
         values: request.connection?.secrets,
     });
     const requestContext = {
-        connectionId: request.connection?.id,
+        connectionId: resolveOperationConnectionId(request),
         headers: request.headers ?? {},
     };
     const context = wrapWithInstrumentation({
@@ -209,7 +215,7 @@ function createFlowContextStore(allowedKeys, initialContext = {}) {
         },
     };
 }
-function createAuthFlowContext(provider, request, options = {}) {
+function createAuthFlowContext(provider, request, options = {}, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -251,6 +257,7 @@ function createAuthFlowContext(provider, request, options = {}) {
             credential,
             context: flowContextStore.context,
             stt: options.stt ?? createSttClientFromEnv(provider.stt),
+            auth: createAuthFlowHelpers({ signal }),
         },
         getPatch: flowContextStore.getPatch,
     };
@@ -879,14 +886,14 @@ function responseWithProviderTelemetry(response, proxyTelemetry) {
         statusText: response.statusText,
     });
 }
-async function handleAuthFlow(provider, request, route, options = {}) {
+async function handleAuthFlow(provider, request, route, options = {}, signal) {
     const flow = provider.auth?.flow;
     if (!flow) {
         throw new ProviderError("Auth flow is not configured", {
             code: "AUTH_FLOW_NOT_CONFIGURED",
         });
     }
-    const { context, getPatch } = createAuthFlowContext(provider, request, options);
+    const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
     try {
         const result = route === "start"
             ? await flow.start(context)
@@ -916,6 +923,12 @@ async function handleAuthFlow(provider, request, route, options = {}) {
             : result;
         return toAuthFlowResponse(materializedResult, getPatch());
     }
+    catch (error) {
+        if (error instanceof AuthAbortError) {
+            return toAuthFlowResponse(error.turn, getPatch());
+        }
+        throw error;
+    }
     finally {
         context.stealth.close?.();
     }
@@ -982,7 +995,7 @@ export function createServerApp(provider, options = {}) {
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "start", options);
+            const response = await handleAuthFlow(provider, body, "start", options, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "start", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1002,7 +1015,7 @@ export function createServerApp(provider, options = {}) {
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "continue", options);
+            const response = await handleAuthFlow(provider, body, "continue", options, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "continue", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1022,7 +1035,7 @@ export function createServerApp(provider, options = {}) {
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "poll", options);
+            const response = await handleAuthFlow(provider, body, "poll", options, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "poll", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1042,7 +1055,7 @@ export function createServerApp(provider, options = {}) {
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "refresh", options);
+            const response = await handleAuthFlow(provider, body, "refresh", options, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "refresh", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1062,7 +1075,7 @@ export function createServerApp(provider, options = {}) {
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "abort", options);
+            const response = await handleAuthFlow(provider, body, "abort", options, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "disconnect", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1106,5 +1119,20 @@ export async function serve(provider, options = {}) {
         hostname: options.host ?? DEFAULT_HOST,
         fetch: app.fetch,
     });
+    // Internal self-test listener (health dependency inversion): a SEPARATE
+    // socket the tenant-facing gateway never dials. Off by default — it only
+    // starts when the shared self-test master secret env is present.
+    const selfTestSecrets = resolveSelfTestMasterSecrets();
+    if (selfTestSecrets) {
+        const selfTestApp = createSelfTestApp(provider, {
+            secrets: selfTestSecrets,
+            invoke: createSelfTestInvoke(app),
+        });
+        bunRuntime.serve({
+            port: options.selfTestPort ?? resolveSelfTestPort(),
+            hostname: options.host ?? DEFAULT_HOST,
+            fetch: selfTestApp.fetch,
+        });
+    }
     await Promise.resolve();
 }

package/dist/server/types.d.ts

@@ -21,6 +21,7 @@ export declare const OperationConnectionSchema: z.ZodObject<{
 export declare const OperationRequestSchema: z.ZodObject<{
     requestId: z.ZodString;
     input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    connectionId: z.ZodOptional<z.ZodString>;
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{

package/dist/server/types.js

@@ -17,6 +17,7 @@ export const OperationConnectionSchema = z.object({
 export const OperationRequestSchema = z.object({
     requestId: z.string(),
     input: z.record(z.string(), z.unknown()),
+    connectionId: z.string().optional(),
     connection: OperationConnectionSchema.optional(),
     headers: z.record(z.string(), z.string()).optional(),
     trace: z.record(z.string(), z.string()).optional(),

package/dist/testing/run.js

@@ -68,13 +68,17 @@ function inferFixtureDir(providerId) {
     return `providers/${providerId}/__fixtures__`;
 }
 function jsonResponse(data) {
+    const body = JSON.stringify(data);
+    const bodyBytes = new TextEncoder().encode(body);
     return {
         status: 200,
         ok: true,
         headers: {},
         data,
         json: async () => JSON.parse(JSON.stringify(data)),
-        text: async () => JSON.stringify(data),
+        text: async () => body,
+        arrayBuffer: async () => bodyBytes.buffer.slice(bodyBytes.byteOffset, bodyBytes.byteOffset + bodyBytes.byteLength),
+        bytes: async () => bodyBytes.slice(0),
     };
 }
 function unsupported(name) {

package/dist/types.d.ts

@@ -268,8 +268,16 @@ export interface HealthJourneySchedule {
     kind: "interval";
     /** ISO 8601 duration, for example PT8H. */
     interval: Iso8601Duration;
+    randomize?: HealthScheduleRandomization;
     jitter?: Iso8601Duration;
 }
+export type HealthScheduleRandomization = {
+    mode: "centered";
+    maxOffset: Iso8601Duration;
+} | {
+    mode: "delayed";
+    maxDelay: Iso8601Duration;
+};
 export interface HealthJourneyStep {
     id: string;
     description?: string;
@@ -511,6 +519,9 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
     /** Polling interval for the suite. All cases share this cadence. */
     interval: ProbeInterval;
+    schedule?: {
+        randomize?: HealthScheduleRandomization;
+    };
     /** Per-case timeout in milliseconds. Default: 30000. */
     timeoutMs?: number;
     /** Default degradation threshold for cases in this suite. Default: runtime threshold. */
@@ -583,6 +594,13 @@ export interface ProviderHealthMonitorConfig {
      */
     serviceAccount?: string;
 }
+/**
+ * New name for `ProviderHealthMonitorConfig` as part of the health dependency
+ * inversion (`healthMonitor` → `healthProbe`). Both provider-level fields are
+ * accepted transitionally with identical validation; declaring both is a
+ * `ValidationError`.
+ */
+export type ProviderHealthProbeConfig = ProviderHealthMonitorConfig;
 export interface HealthMonitorProbeOverride {
     /** Optional runtime interval override as a positive `ms`-style duration string. */
     interval?: ProbeInterval;
@@ -805,6 +823,7 @@ export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PU
 export interface StealthFetchOptions extends RequestOptions {
     method?: HttpMethod;
     body?: string | Buffer;
+    redirect?: "follow" | "manual" | "error";
     /**
      * Offsets policy-managed proxy pool selection for caller-managed retries.
      * Use when a request receives an upstream challenge page rather than a
@@ -829,9 +848,19 @@ export interface CookieJar {
     toString(): string;
     find?(predicate: (cookie: string) => boolean): string | undefined;
 }
+export interface StealthSessionCookies extends CookieJar {
+    has(name: string): boolean;
+    setFromCookieStrings(cookieStrings: readonly string[]): void;
+    toHeader(): string;
+    snapshot(): Record<string, string>;
+    restore(cookies: Record<string, string>): void;
+    clear(): void;
+}
 export interface DeclarativeStealthResponse {
     status: number;
     ok: boolean;
+    url?: string;
+    redirected?: boolean;
     headers: Record<string, string>;
     rawHeaders: [string, string][];
     body: string;
@@ -851,8 +880,30 @@ export type RequestWithMethodOptions = RequestOptions & {
     method?: string;
     body?: unknown;
 };
+export interface StealthRedirectHop {
+    url: string;
+    status: number;
+    method: string;
+    location?: string;
+    nextUrl?: string;
+}
+export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "redirect"> {
+    url: string;
+    maxHops?: number;
+    stopWhen?: (hop: StealthRedirectHop) => boolean | Promise<boolean>;
+}
+export interface StealthRedirectRunResult {
+    final: StealthResponse;
+    hops: StealthRedirectHop[];
+    reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    cookies: Record<string, string>;
+}
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+    cookies: StealthSessionCookies;
+    redirects: {
+        run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
+    };
     close(): void;
 }
 export interface ApiFuseResponse<T> {
@@ -873,6 +924,8 @@ export interface HttpResponse<T = unknown> {
     data: T;
     json<U = T>(): Promise<U>;
     text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
 }
 export interface HttpStreamResponse {
     status: number;
@@ -983,6 +1036,32 @@ export interface BrowserFrame {
     evaluate<T>(fn: string | (() => T)): Promise<T>;
     locator(selector: string): BrowserLocator;
 }
+export type BrowserResourceMethod = "GET" | "HEAD";
+export type BrowserResourceRequest = {
+    readonly url: string;
+    readonly method: BrowserResourceMethod;
+    readonly resourceType?: string;
+    readonly headers: Readonly<Record<string, string>>;
+};
+export type BrowserResourceBody = Buffer | Uint8Array | ArrayBuffer | string;
+export type BrowserResourceDecision = {
+    readonly action: "fulfill";
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: BrowserResourceBody;
+} | {
+    readonly action: "block";
+    readonly reason?: string;
+};
+export type BrowserResourceRoute = {
+    readonly match: string | RegExp | ((request: BrowserResourceRequest) => boolean);
+    readonly handle: (request: BrowserResourceRequest) => Promise<BrowserResourceDecision> | BrowserResourceDecision;
+};
+export type BrowserResourcePolicy = {
+    readonly defaultAction?: "block";
+    readonly allowedMethods?: readonly BrowserResourceMethod[];
+    readonly routes: readonly BrowserResourceRoute[];
+};
 export interface BrowserPage extends BrowserFrame {
     close(): Promise<void>;
     fill(selector: string, text: string): Promise<void>;
@@ -997,6 +1076,7 @@ export interface BrowserPage extends BrowserFrame {
         timeout?: number;
     }): Promise<void>;
     frames(): Promise<BrowserFrame[]>;
+    withResourcePolicy<T>(policy: BrowserResourcePolicy, run: () => Promise<T>): Promise<T>;
 }
 export type BrowserChallengeRequest = {
     type: "recaptcha";
@@ -1137,6 +1217,73 @@ export interface ContextScratchpad {
     toJSON(): Record<string, unknown>;
 }
 export type FlowContextStore = ContextScratchpad;
+export type AuthSafeJson = string | number | boolean | null | readonly AuthSafeJson[] | {
+    readonly [key: string]: AuthSafeJson;
+};
+export type AuthSafeData = {
+    readonly [key: string]: AuthSafeJson;
+};
+export type AuthAbortRetry = "never" | "retry" | "after_user_action";
+export type AuthAbortData = Record<string, unknown> & {
+    readonly code: string;
+    readonly message?: string;
+    readonly retry?: AuthAbortRetry;
+    readonly actionHint?: AuthSafeJson;
+    readonly fieldErrors?: {
+        readonly [field: string]: string;
+    };
+    readonly details?: AuthSafeData;
+};
+export interface AuthFlowTerminalContext {
+    readonly signal?: AbortSignal;
+    readonly deadline?: string;
+    complete<TCredential extends Record<string, string>>(options: {
+        readonly credential: TCredential;
+        readonly metadata?: AuthSafeData;
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+    }): AuthTurn;
+    abort(options: {
+        readonly code: string;
+        readonly message?: string;
+        readonly retry?: AuthAbortRetry;
+        readonly actionHint?: AuthSafeJson;
+        readonly fieldErrors?: {
+            readonly [field: string]: string;
+        };
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+    }): AuthTurn;
+    nextForm(options: {
+        readonly hintKey?: ProviderLocaleKeyInput;
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+        readonly timing?: AuthTurn["timing"];
+    } & ({
+        readonly fields: Record<string, {
+            readonly type?: "string" | "email" | "password" | "otp";
+            readonly labelKey?: ProviderLocaleKeyInput;
+            readonly descriptionKey?: ProviderLocaleKeyInput;
+            readonly placeholderKey?: ProviderLocaleKeyInput;
+            readonly required?: boolean;
+            readonly sensitive?: boolean;
+        }>;
+        readonly expectedInput?: never;
+    } | {
+        readonly expectedInput: Record<string, unknown>;
+        readonly fields?: never;
+    })): AuthTurn;
+    nextPoll(options?: {
+        readonly hintKey?: ProviderLocaleKeyInput;
+        readonly data?: AuthSafeData;
+        readonly turnId?: string;
+        readonly expiresAt?: string;
+        readonly timing?: AuthTurn["timing"];
+    }): AuthTurn;
+}
 export interface FlowContext {
     connectionId?: string;
     externalRef?: string;
@@ -1148,6 +1295,7 @@ export interface FlowContext {
     credential?: CredentialContext;
     context: ContextScratchpad;
     stt: SttContext;
+    auth: AuthFlowTerminalContext;
 }
 export interface AuthTurn {
     kind: string;
@@ -1322,5 +1470,7 @@ export interface ProviderDefinition {
     meta: ProviderMeta;
     operations: Record<string, OperationDefinition<SchemaLike, SchemaLike>>;
     healthMonitor?: ProviderHealthMonitorConfig;
+    /** Transitional alias for `healthMonitor`; `defineProvider` mirrors both. */
+    healthProbe?: ProviderHealthProbeConfig;
     healthJourneys?: readonly HealthJourneyDefinition[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
+	"version": "2.2.0-beta.2",
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.9",
 	"private": false,
 	"type": "module",
 	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",
@@ -50,6 +50,12 @@
 			"import": "./dist/contract.js",
 			"default": "./dist/contract.js"
 		},
+		"./auth-turn": {
+			"types": "./dist/auth-turn/index.d.ts",
+			"import": "./dist/auth-turn/index.js",
+			"default": "./dist/auth-turn/index.js"
+		},
+		"./auth-turn/auth-turn.v1.schema.json": "./dist/auth-turn/auth-turn.v1.schema.json",
 		"./server": {
 			"types": "./dist/server/index.d.ts",
 			"import": "./dist/server/index.js",
@@ -77,7 +83,7 @@
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
 		"release:guard": "bun scripts/guard-release-pr.ts",
 		"format:check": "biome format .",
-		"build": "tsgo -p tsconfig.build.json"
+		"build": "tsgo -p tsconfig.build.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates && rm -rf dist/auth-turn/fixtures && cp -R src/auth-turn/fixtures dist/auth-turn/fixtures && cp src/auth-turn/auth-turn.v1.schema.json dist/auth-turn/auth-turn.v1.schema.json"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.5.0",
@@ -88,6 +94,7 @@
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
 		"@types/ms": "^2.1.0",
+		"acorn": "^8.17.0",
 		"ajv": "^8.17",
 		"hono": "^4.12.25",
 		"impit": "0.14.1",

package/src/auth-turn/auth-turn.v1.schema.json

@@ -0,0 +1,89 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://apifuse.com/contracts/auth-turn/v1",
+	"title": "APIFuse AuthTurn envelope v1",
+	"description": "Protocol message exchanged during auth.flow ceremonies. kind is an open string; known kinds are tooling metadata, not a wire constraint.",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["kind", "turnId"],
+	"properties": {
+		"kind": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Open turn kind. Known kinds are listed in the TURN_KINDS registry; unknown kinds remain valid on the wire."
+		},
+		"turnId": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Provider-scoped identifier of this turn."
+		},
+		"expiresAt": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Turn expiry timestamp as an ISO 8601 / RFC 3339 string."
+		},
+		"data": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "Kind-specific payload. Terminal kinds carry the payloads described in $defs."
+		},
+		"expectedInput": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "JSON Schema describing the input expected next."
+		},
+		"hint": {
+			"type": "string",
+			"description": "Deprecated but load-bearing human-readable hint materialized from provider locale catalogs."
+		},
+		"hintKey": {
+			"type": "string",
+			"description": "Provider locale catalog key for the turn hint."
+		},
+		"timing": {
+			"type": "object",
+			"additionalProperties": false,
+			"description": "Client pacing guidance for poll-style turns.",
+			"properties": {
+				"suggestedPollIntervalMs": {
+					"type": "number",
+					"minimum": 1
+				},
+				"maxWaitMs": {
+					"type": "number",
+					"minimum": 1
+				}
+			}
+		}
+	},
+	"$defs": {
+		"completeTurnData": {
+			"title": "Terminal payload for kind \"complete\"",
+			"description": "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.",
+			"type": "object",
+			"additionalProperties": true,
+			"required": ["credential"],
+			"properties": {
+				"credential": {
+					"type": "object",
+					"additionalProperties": true
+				},
+				"metadata": {
+					"type": "object",
+					"additionalProperties": true
+				}
+			}
+		},
+		"abortTurnData": {
+			"title": "Terminal payload for kind \"abort\"",
+			"description": "data payload of an abort turn. code, when present, is the machine-readable abort reason.",
+			"type": "object",
+			"additionalProperties": true,
+			"properties": {
+				"code": {
+					"type": "string"
+				}
+			}
+		}
+	}
+}

package/src/auth-turn/fixtures/invalid/empty-kind.json

@@ -0,0 +1,4 @@
+{
+	"kind": "",
+	"turnId": "fixture.invalid.empty-kind"
+}

package/src/auth-turn/fixtures/invalid/expires-at-not-string.json

@@ -0,0 +1,5 @@
+{
+	"kind": "challenge",
+	"turnId": "fixture.invalid.expires-at-not-string",
+	"expiresAt": 1767225600000
+}

package/src/auth-turn/fixtures/invalid/missing-kind.json

@@ -0,0 +1,3 @@
+{
+	"turnId": "fixture.invalid.missing-kind"
+}

package/src/auth-turn/fixtures/invalid/missing-turn-id.json

@@ -0,0 +1,3 @@
+{
+	"kind": "form"
+}

package/src/auth-turn/fixtures/invalid/timing-unknown-field.json

@@ -0,0 +1,7 @@
+{
+	"kind": "poll",
+	"turnId": "fixture.invalid.timing-unknown-field",
+	"timing": {
+		"recommendedIntervalMs": 5000
+	}
+}

package/src/auth-turn/fixtures/invalid/turn-id-snake-case.json

@@ -0,0 +1,4 @@
+{
+	"kind": "form",
+	"turn_id": "fixture.invalid.turn-id-snake-case"
+}

package/src/auth-turn/fixtures/invalid/unknown-top-level-field.json

@@ -0,0 +1,5 @@
+{
+	"kind": "form",
+	"turnId": "fixture.invalid.unknown-top-level-field",
+	"setCookie": "session=leaked-value"
+}

package/src/auth-turn/fixtures/valid/abort.json

@@ -0,0 +1,8 @@
+{
+	"kind": "abort",
+	"turnId": "fixture.abort",
+	"hint": "OAuth flow aborted.",
+	"data": {
+		"code": "flow_expired"
+	}
+}

package/src/auth-turn/fixtures/valid/challenge.json

@@ -0,0 +1,17 @@
+{
+	"kind": "challenge",
+	"turnId": "fixture.challenge",
+	"hint": "Complete the WebAuthn prompt in your browser.",
+	"expiresAt": "2026-01-01T00:00:00.000Z",
+	"data": {
+		"challenge": "fixture-challenge-not-real",
+		"rpId": "example.com"
+	},
+	"expectedInput": {
+		"type": "object",
+		"required": ["attestation"],
+		"properties": {
+			"attestation": { "type": "object" }
+		}
+	}
+}

package/src/auth-turn/fixtures/valid/complete.json

@@ -0,0 +1,13 @@
+{
+	"kind": "complete",
+	"turnId": "fixture.complete",
+	"hint": "OAuth flow completed.",
+	"data": {
+		"credential": {
+			"accessToken": "fixture-fake-access-token-not-a-secret"
+		},
+		"metadata": {
+			"scope": "read"
+		}
+	}
+}

package/src/auth-turn/fixtures/valid/form.json

@@ -0,0 +1,14 @@
+{
+	"kind": "form",
+	"turnId": "fixture.form",
+	"hint": "Provide the required input to continue.",
+	"data": {},
+	"expectedInput": {
+		"type": "object",
+		"required": ["apiKey"],
+		"properties": {
+			"apiKey": { "type": "string" }
+		},
+		"x-apifuse-field-order": ["apiKey"]
+	}
+}

package/src/auth-turn/fixtures/valid/message.json

@@ -0,0 +1,13 @@
+{
+	"kind": "message",
+	"turnId": "fixture.message",
+	"hint": "Enter the code on the verification page, then poll for completion.",
+	"data": {
+		"user_code": "FIXT-CODE",
+		"verification_uri": "https://example.com/device"
+	},
+	"timing": {
+		"suggestedPollIntervalMs": 5000,
+		"maxWaitMs": 120000
+	}
+}