@apifuse/provider-sdk 2.1.0-beta.12 → 2.1.0-beta.14

package/AUTHORING.md

@@ -264,6 +264,140 @@ deployment projection checks, and release workflows.
 - Credential-backed smoke requests pass local-only credential material in
   `connection.secrets`. Keep real values in shell env or `.env`, never in source
   or fixtures.
+- Hand-written auth flows should use `ctx.auth` helpers and return exactly one
+  terminal/next turn from each handler: `ctx.auth.nextForm(...)` or
+  `ctx.auth.nextPoll(...)` to ask Gateway for the next user/system step,
+  `ctx.auth.complete(...)` to finish with `data.credential`, or
+  `ctx.auth.abort(...)` to stop safely. Keep abort `data` and `actionHint`
+  JSON-safe and secret-free; never include raw cookies, credentials, headers,
+  HTML, or upstream `Error` objects.
+
+```ts
+export default defineProvider({
+  id: "example-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  auth: {
+    mode: "credentials",
+    flow: {
+      async start(ctx) {
+        return ctx.auth.nextForm({
+          fields: {
+            email: { type: "email", labelKey: "auth.email.label" },
+            password: { type: "password", labelKey: "auth.password.label" },
+          },
+          hintKey: "auth.signIn",
+        });
+      },
+      async continue(ctx, input) {
+        const result = await loginWithSubmittedFields(ctx, input);
+        if (result.blocked) {
+          return ctx.auth.abort({
+            code: "account_action_required",
+            retry: "after_user_action",
+            actionHint: { kind: "open_provider_app" },
+            message: "Approve the login in the provider app.",
+          });
+        }
+        return ctx.auth.complete({
+          credential: { cookie: result.cookie },
+          metadata: { accountId: result.accountId },
+        });
+      },
+    },
+  },
+  credential: { keys: ["cookie"] },
+  // ...metadata and operations
+});
+```
+
+- Credentials auth providers should use `defineCredentialsAuth()` instead of
+  hand-writing `auth.flow.start/continue`. The helper exposes one happy path:
+  declare form `fields`, declare `credentialKeys`, and put upstream login/session
+  creation in `login(ctx, input)`. It returns both `auth` and `credential` for
+  `defineProvider()` and builds the complete turn as `data.credential`, which is
+  the only value Gateway persists onto the connection.
+
+```ts
+import { defineCredentialsAuth, defineProvider } from "@apifuse/provider-sdk";
+
+const credentialsAuth = defineCredentialsAuth({
+  fields: {
+    email: { type: "email", labelKey: "auth.email.label" },
+    password: { type: "password", labelKey: "auth.password.label" },
+  },
+  credentialKeys: ["cookie"] as const,
+  storesReusableSecret: true,
+  justification: "Session cookie is required for authenticated operations.",
+  async login(ctx, input) {
+    const cookie = await loginAndBuildSessionCookie(ctx, input);
+    return { credential: { cookie } };
+  },
+});
+
+export default defineProvider({
+  id: "example-provider",
+  version: "1.0.0",
+  runtime: "standard",
+  auth: credentialsAuth.auth,
+  credential: credentialsAuth.credential,
+  context: credentialsAuth.context,
+  // ...metadata and operations
+});
+```
+
+For OTP, MFA, CAPTCHA handoff, or user-approved login, return a challenge from
+`login()` instead of hand-writing `contextPatch`, `poll`, and final credential
+turns. SDK stores the pending challenge in auth-flow context, returns the next
+form/pending turn, and still persists only the final `data.credential`.
+
+```ts
+import {
+  credentialsAuthChallenge,
+  defineCredentialsAuth,
+} from "@apifuse/provider-sdk";
+
+const credentialsAuth = defineCredentialsAuth({
+  fields: {
+    email: { type: "email" },
+    password: { type: "password" },
+  },
+  credentialKeys: ["cookie"] as const,
+  async login(ctx, input) {
+    const result = await passwordLogin(ctx, input);
+    if (result.otpRequired) {
+      return credentialsAuthChallenge("otp", {
+        state: { transactionId: result.transactionId },
+        hintKey: "auth.otp.prompt",
+      });
+    }
+    if (result.manualApprovalRequired) {
+      return credentialsAuthChallenge("manualApproval", {
+        state: { transactionId: result.transactionId },
+        hintKey: "auth.manualApproval.openApp",
+        timing: { suggestedPollIntervalMs: 3000, maxWaitMs: 120000 },
+      });
+    }
+    return { credential: { cookie: result.cookie } };
+  },
+  challenges: {
+    otp: {
+      fields: { otp: { type: "otp", labelKey: "auth.otp.label" } },
+      async verify(ctx, input, state) {
+        const result = await verifyOtp(ctx, state.transactionId, input.otp);
+        return { credential: { cookie: result.cookie } };
+      },
+    },
+    manualApproval: {
+      async poll(ctx, state) {
+        const result = await checkApproval(ctx, state.transactionId);
+        if (!result.approved) return null;
+        return { credential: { cookie: result.cookie } };
+      },
+    },
+  },
+});
+```
 - Auth-flow debugging starts with `/auth/start`, continues with
   `/auth/continue`, and carries returned `contextPatch` values into the next
   request's `context`.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.14
+
+- Release candidate for main commit 6eb132be6abf34ad9a70bfe28c6d26b36348ff4a.
+
+## 2.1.0-beta.13
+
+- Release candidate for main commit d7b12716f54781df3e40206144c167844a485f8f.
+
 ## 2.1.0-beta.12
 
 - Release candidate for main commit 2bc1061c6a68facaa2efde08bee31bf5cd96945e.

package/README.md

@@ -120,6 +120,14 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `ctx.credential.get("key")` or `ctx.credential.getAccessToken()`.
 - **Provider env secrets**: declare `secrets[]`, set values in your shell or
   `.env`, and read only those names through `ctx.env.get("NAME")`.
+- **Credentials auth flows**: prefer `defineCredentialsAuth()` over hand-written
+  `auth.flow`. Declare the form fields and credential keys once, then put the
+  upstream login/session creation in `login(ctx, input)`. Return
+  `credentialsAuthChallenge("otp" | "manualApproval" | ...)` for MFA, CAPTCHA
+  handoff, or user-approved login branches. The helper returns
+  `{ auth, credential, context }` for `defineProvider()` and always completes
+  with `data.credential`, which is the value Gateway persists onto the
+  connection.
 - **Auth flows**: call `/auth/start`, then `/auth/continue` with the same
   `flowId`; preserve any returned `contextPatch` in the next local request's
   `context` object.

package/dist/auth.d.ts

@@ -0,0 +1,76 @@
+import { AuthError } from "./errors";
+import type { AuthConfig, AuthFlowTerminalContext, AuthTurn, ContextDeclaration, CredentialDeclaration, FlowContext, ProviderLocaleKeyInput } from "./types";
+export type CredentialsAuthFieldType = "string" | "email" | "password" | "otp";
+export interface CredentialsAuthField {
+    type?: CredentialsAuthFieldType;
+    labelKey?: ProviderLocaleKeyInput;
+    descriptionKey?: ProviderLocaleKeyInput;
+    placeholderKey?: ProviderLocaleKeyInput;
+    required?: boolean;
+    /** Marks field values as secret UI/input material, for example passwords or OTPs. */
+    sensitive?: boolean;
+}
+export type CredentialsAuthFields = Record<string, CredentialsAuthField>;
+export type CredentialsAuthInput<TFields extends CredentialsAuthFields> = {
+    [K in keyof TFields]: string;
+};
+export type CredentialsAuthCredential<TCredentialKeys extends readonly string[]> = {
+    [K in TCredentialKeys[number]]: string;
+};
+export declare function createAuthFlowHelpers(options?: {
+    readonly signal?: AbortSignal;
+    readonly deadline?: string;
+}): AuthFlowTerminalContext;
+export declare class AuthAbortError extends AuthError {
+    readonly turn: AuthTurn;
+    constructor(options: Parameters<AuthFlowTerminalContext["abort"]>[0]);
+}
+export interface CredentialsAuthCompleteResult<TCredentialKeys extends readonly string[]> {
+    credential: CredentialsAuthCredential<TCredentialKeys>;
+    /** Additional non-credential auth-flow data to return alongside credential. */
+    data?: Record<string, unknown>;
+    turnId?: string;
+    expiresAt?: string;
+}
+export interface CredentialsAuthChallengeRequest<TChallengeId extends string = string> {
+    kind: "challenge";
+    challengeId: TChallengeId;
+    state?: Record<string, unknown>;
+    turnId?: string;
+    hintKey?: ProviderLocaleKeyInput;
+    expiresAt?: string;
+    data?: Record<string, unknown>;
+    timing?: AuthTurn["timing"];
+}
+export type CredentialsAuthLoginResult<TCredentialKeys extends readonly string[], TChallengeId extends string = string> = CredentialsAuthCompleteResult<TCredentialKeys> | CredentialsAuthChallengeRequest<TChallengeId>;
+export interface CredentialsAuthChallengeDefinition<TFields extends CredentialsAuthFields, TCredentialKeys extends readonly string[], TChallengeId extends string> {
+    fields?: TFields;
+    hintKey?: ProviderLocaleKeyInput;
+    turnId?: string;
+    retryTurnId?: string;
+    pendingTurnId?: string;
+    timing?: AuthTurn["timing"];
+    verify?: (ctx: FlowContext, input: CredentialsAuthInput<TFields>, state: Record<string, unknown>) => CredentialsAuthLoginResult<TCredentialKeys, TChallengeId> | Promise<CredentialsAuthLoginResult<TCredentialKeys, TChallengeId>>;
+    poll?: (ctx: FlowContext, state: Record<string, unknown>) => CredentialsAuthLoginResult<TCredentialKeys, TChallengeId> | null | Promise<CredentialsAuthLoginResult<TCredentialKeys, TChallengeId> | null>;
+}
+export interface DefineCredentialsAuthOptions<TFields extends CredentialsAuthFields, TCredentialKeys extends readonly string[], TChallenges extends Record<string, CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, keyof TChallenges & string>> = Record<string, CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, string>>> {
+    fields: TFields;
+    credentialKeys: TCredentialKeys;
+    storesReusableSecret?: boolean;
+    justification?: string;
+    hintKey?: ProviderLocaleKeyInput;
+    startTurnId?: string;
+    retryTurnId?: string;
+    completeTurnId?: string;
+    challenges?: TChallenges;
+    /** Extra auth-flow context keys used by custom login/challenge code. */
+    contextKeys?: readonly string[];
+    login(ctx: FlowContext, input: CredentialsAuthInput<TFields>): CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string> | Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
+}
+export interface DefinedCredentialsAuth {
+    auth: AuthConfig;
+    credential: CredentialDeclaration;
+    context: ContextDeclaration;
+}
+export declare function credentialsAuthChallenge<TChallengeId extends string>(challengeId: TChallengeId, options?: Omit<CredentialsAuthChallengeRequest<TChallengeId>, "kind" | "challengeId">): CredentialsAuthChallengeRequest<TChallengeId>;
+export declare function defineCredentialsAuth<TFields extends CredentialsAuthFields, TCredentialKeys extends readonly [string, ...string[]], TChallenges extends Record<string, CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, keyof TChallenges & string>> = Record<string, CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, string>>>(options: DefineCredentialsAuthOptions<TFields, TCredentialKeys, TChallenges>): DefinedCredentialsAuth;

package/dist/auth.js

@@ -0,0 +1,436 @@
+import { AuthError, ProviderError } from "./errors";
+const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
+const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
+const DEFAULT_ABORT_TURN_ID = "auth.abort";
+const DEFAULT_FORM_TURN_ID = "auth.form";
+const DEFAULT_POLL_TURN_ID = "auth.poll";
+const SENSITIVE_ABORT_DATA_KEY_PATTERN = /(authorization|cookie|credential|header|html|password|secret|session|token|apikey)/i;
+function normalizedAuthDataKey(key) {
+    return key.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+function isPlainAuthJsonObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isSensitiveAuthDataKey(key) {
+    return SENSITIVE_ABORT_DATA_KEY_PATTERN.test(normalizedAuthDataKey(key));
+}
+function assertSafeAuthJson(value, path) {
+    if (value === null)
+        return;
+    if (typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new AuthError(`Auth abort ${path} must be a finite number`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            assertSafeAuthJson(item, `${path}[${index}]`);
+        }
+        return;
+    }
+    if (value instanceof Error) {
+        throw new AuthError(`Auth abort ${path} must not include Error objects`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    if (typeof value !== "object") {
+        throw new AuthError(`Auth abort ${path} must be JSON-safe`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    if (!isPlainAuthJsonObject(value)) {
+        throw new AuthError(`Auth abort ${path} must be a plain JSON object`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (isSensitiveAuthDataKey(key)) {
+            throw new AuthError(`Auth abort ${path}.${key} must not include secrets`, {
+                code: "auth_abort_unsafe_data",
+            });
+        }
+        assertSafeAuthJson(item, `${path}.${key}`);
+    }
+}
+function assertSafeAuthData(data, path) {
+    assertSafeAuthJson(data, path);
+}
+function authTurnBase(options) {
+    return {
+        turnId: options.turnId ?? options.defaultTurnId,
+        ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
+    };
+}
+function abortData(options) {
+    if (options.actionHint !== undefined) {
+        assertSafeAuthJson(options.actionHint, "actionHint");
+    }
+    if (options.data !== undefined) {
+        assertSafeAuthData(options.data, "data");
+    }
+    return {
+        code: options.code,
+        ...(options.message ? { message: options.message } : {}),
+        ...(options.retry ? { retry: options.retry } : {}),
+        ...(options.actionHint !== undefined ? { actionHint: options.actionHint } : {}),
+        ...(options.fieldErrors ? { fieldErrors: options.fieldErrors } : {}),
+        ...(options.data ? { details: options.data } : {}),
+    };
+}
+export function createAuthFlowHelpers(options = {}) {
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.deadline ? { deadline: options.deadline } : {}),
+        complete({ credential, metadata, data, turnId, expiresAt }) {
+            return {
+                kind: "complete",
+                ...authTurnBase({ turnId, defaultTurnId: DEFAULT_COMPLETE_TURN_ID, expiresAt }),
+                data: {
+                    ...(data ?? {}),
+                    credential,
+                    ...(metadata ? { metadata } : {}),
+                },
+            };
+        },
+        abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt, }) {
+            return {
+                kind: "abort",
+                ...authTurnBase({ turnId, defaultTurnId: DEFAULT_ABORT_TURN_ID, expiresAt }),
+                data: abortData({
+                    code,
+                    message,
+                    retry,
+                    actionHint,
+                    fieldErrors,
+                    data,
+                }),
+            };
+        },
+        nextForm(options) {
+            return {
+                kind: "form",
+                ...authTurnBase({
+                    turnId: options.turnId,
+                    defaultTurnId: DEFAULT_FORM_TURN_ID,
+                    expiresAt: options.expiresAt,
+                }),
+                ...(options.hintKey ? { hintKey: options.hintKey } : {}),
+                ...(options.timing ? { timing: options.timing } : {}),
+                ...(options.data ? { data: options.data } : {}),
+                expectedInput: options.expectedInput ?? expectedInputFromFields(options.fields ?? {}),
+            };
+        },
+        nextPoll(options = {}) {
+            return {
+                kind: "poll",
+                ...authTurnBase({
+                    turnId: options.turnId,
+                    defaultTurnId: DEFAULT_POLL_TURN_ID,
+                    expiresAt: options.expiresAt,
+                }),
+                ...(options.hintKey ? { hintKey: options.hintKey } : {}),
+                ...(options.timing ? { timing: options.timing } : {}),
+                ...(options.data ? { data: options.data } : {}),
+            };
+        },
+    };
+}
+export class AuthAbortError extends AuthError {
+    turn;
+    constructor(options) {
+        super(options.message ?? options.code, {
+            code: options.code,
+            retryable: options.retry === "retry",
+        });
+        this.name = "AuthAbortError";
+        this.turn = createAuthFlowHelpers().abort(options);
+    }
+}
+export function credentialsAuthChallenge(challengeId, options = {}) {
+    return {
+        kind: "challenge",
+        challengeId,
+        ...options,
+    };
+}
+function expectedInputFromFields(fields) {
+    return {
+        type: "object",
+        properties: Object.fromEntries(Object.entries(fields).map(([name, field]) => [
+            name,
+            {
+                type: "string",
+                ...(field.type === "email" ? { format: "email" } : {}),
+                ...(field.type === "password" ? { format: "password" } : {}),
+                ...(field.type === "otp" ? { format: "otp" } : {}),
+                ...(field.labelKey ? { nameKey: field.labelKey } : {}),
+                ...(field.descriptionKey
+                    ? { descriptionKey: field.descriptionKey }
+                    : {}),
+                ...(field.placeholderKey
+                    ? { placeholderKey: field.placeholderKey }
+                    : {}),
+                ...(field.sensitive || field.type === "password" || field.type === "otp"
+                    ? { sensitive: true }
+                    : {}),
+            },
+        ])),
+        required: Object.entries(fields)
+            .filter(([, field]) => field.required !== false)
+            .map(([name]) => name),
+    };
+}
+function collectMissingFields(fields, input) {
+    return Object.entries(fields)
+        .filter(([, field]) => field.required !== false)
+        .map(([name]) => name)
+        .filter((name) => {
+        const value = input?.[name];
+        return typeof value !== "string" || value.trim().length === 0;
+    });
+}
+function normalizeInput(fields, input) {
+    const result = {};
+    for (const name of Object.keys(fields)) {
+        const value = input?.[name];
+        result[name] = typeof value === "string" ? value : "";
+    }
+    return result;
+}
+function assertCredentialKeys(credentialKeys, credential) {
+    const missing = credentialKeys.filter((key) => {
+        const value = credential[key];
+        return typeof value !== "string" || value.length === 0;
+    });
+    if (missing.length > 0) {
+        throw new ProviderError(`Credentials auth login completed without required credential key(s): ${missing.join(", ")}`, {
+            code: "credentials_auth_missing_credential_keys",
+            fix: "Return every credentialKeys entry from defineCredentialsAuth({ login }) as result.credential. Gateway persists only auth.flow complete data.credential into the connection.",
+        });
+    }
+}
+function getPendingChallenge(ctx) {
+    const value = ctx.context.get(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY);
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (typeof record.challengeId !== "string")
+        return null;
+    const state = record.state && typeof record.state === "object" && !Array.isArray(record.state)
+        ? record.state
+        : {};
+    return {
+        challengeId: record.challengeId,
+        state,
+        ...(typeof record.turnId === "string" ? { turnId: record.turnId } : {}),
+        ...(typeof record.hintKey === "string" ? { hintKey: record.hintKey } : {}),
+        ...(typeof record.expiresAt === "string" ? { expiresAt: record.expiresAt } : {}),
+        ...(record.data && typeof record.data === "object" && !Array.isArray(record.data)
+            ? { data: record.data }
+            : {}),
+        ...(record.timing && typeof record.timing === "object" && !Array.isArray(record.timing)
+            ? { timing: record.timing }
+            : {}),
+    };
+}
+function setPendingChallenge(ctx, challenge) {
+    ctx.context.set(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, challenge);
+}
+function clearPendingChallenge(ctx) {
+    ctx.context.set(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, null);
+}
+function pendingToChallengeRequest(pending) {
+    return {
+        kind: "challenge",
+        challengeId: pending.challengeId,
+        state: pending.state,
+        ...(pending.turnId ? { turnId: pending.turnId } : {}),
+        ...(pending.hintKey ? { hintKey: pending.hintKey } : {}),
+        ...(pending.expiresAt ? { expiresAt: pending.expiresAt } : {}),
+        ...(pending.data ? { data: pending.data } : {}),
+        ...(pending.timing ? { timing: pending.timing } : {}),
+    };
+}
+function retryTurn(expectedInput, missing, retryTurnId) {
+    return {
+        kind: "retry",
+        turnId: retryTurnId,
+        expectedInput,
+        data: {
+            fieldErrors: Object.fromEntries(missing.map((name) => [name, "Required"])),
+            fieldErrorKeys: Object.fromEntries(missing.map((name) => [name, "auth.credentials.fieldRequired"])),
+        },
+    };
+}
+function isChallengeRequest(result) {
+    return "kind" in result && result.kind === "challenge";
+}
+function completeTurn(credentialKeys, result, defaultTurnId) {
+    if (!result.credential ||
+        typeof result.credential !== "object" ||
+        Array.isArray(result.credential)) {
+        throw new ProviderError("Credentials auth login completed without a credential object", {
+            code: "credentials_auth_missing_credential",
+            fix: "Return { credential: { ... } } from defineCredentialsAuth handlers. Gateway persists only auth.flow complete data.credential into the connection.",
+        });
+    }
+    assertCredentialKeys(credentialKeys, result.credential);
+    return {
+        kind: "complete",
+        turnId: result.turnId ?? defaultTurnId,
+        ...(result.expiresAt ? { expiresAt: result.expiresAt } : {}),
+        data: {
+            ...(result.data ?? {}),
+            credential: result.credential,
+        },
+    };
+}
+function challengeTurn(definition, request) {
+    const expectedInput = definition.fields
+        ? expectedInputFromFields(definition.fields)
+        : undefined;
+    return {
+        kind: expectedInput ? "form" : "pending",
+        turnId: request.turnId ?? definition.turnId ?? `credentials.${request.challengeId}`,
+        ...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
+        ...(request.hintKey ?? definition.hintKey
+            ? { hintKey: request.hintKey ?? definition.hintKey }
+            : {}),
+        ...(request.timing ?? definition.timing
+            ? { timing: request.timing ?? definition.timing }
+            : {}),
+        ...(expectedInput ? { expectedInput } : {}),
+        data: {
+            ...(request.data ?? {}),
+            challengeId: request.challengeId,
+        },
+    };
+}
+async function resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId) {
+    if (!result || typeof result !== "object") {
+        throw new AuthError("Credentials auth login did not return a result", {
+            code: "credentials_auth_invalid_login_result",
+            fix: "Return { credential: { ... } } or credentialsAuthChallenge(...) from defineCredentialsAuth handlers.",
+        });
+    }
+    if (!isChallengeRequest(result)) {
+        clearPendingChallenge(ctx);
+        return completeTurn(credentialKeys, result, completeTurnId);
+    }
+    const definition = challenges[result.challengeId];
+    if (!definition) {
+        throw new ProviderError(`Credentials auth requested unknown challenge "${result.challengeId}"`, {
+            code: "credentials_auth_unknown_challenge",
+            fix: `Add challenges.${result.challengeId} to defineCredentialsAuth({ challenges }).`,
+        });
+    }
+    setPendingChallenge(ctx, {
+        challengeId: result.challengeId,
+        state: result.state ?? {},
+        ...(result.turnId ? { turnId: result.turnId } : {}),
+        ...(result.hintKey ? { hintKey: result.hintKey } : {}),
+        ...(result.expiresAt ? { expiresAt: result.expiresAt } : {}),
+        ...(result.data ? { data: result.data } : {}),
+        ...(result.timing ? { timing: result.timing } : {}),
+    });
+    return challengeTurn(definition, result);
+}
+async function continuePendingChallenge(ctx, credentialKeys, challenges, pending, rawInput, completeTurnId) {
+    const definition = challenges[pending.challengeId];
+    if (!definition) {
+        throw new ProviderError(`Credentials auth has pending unknown challenge "${pending.challengeId}"`, { code: "credentials_auth_unknown_pending_challenge" });
+    }
+    if (!definition.fields || !definition.verify) {
+        return challengeTurn(definition, pendingToChallengeRequest(pending));
+    }
+    const missing = collectMissingFields(definition.fields, rawInput);
+    const expectedInput = expectedInputFromFields(definition.fields);
+    if (missing.length > 0) {
+        return retryTurn(expectedInput, missing, definition.retryTurnId ?? `credentials.${pending.challengeId}.retry`);
+    }
+    const result = await definition.verify(ctx, normalizeInput(definition.fields, rawInput), pending.state);
+    return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
+}
+async function pollPendingChallenge(ctx, credentialKeys, challenges, pending, completeTurnId) {
+    const definition = challenges[pending.challengeId];
+    if (!definition) {
+        throw new ProviderError(`Credentials auth has pending unknown challenge "${pending.challengeId}"`, { code: "credentials_auth_unknown_pending_challenge" });
+    }
+    if (!definition.poll) {
+        return challengeTurn(definition, pendingToChallengeRequest(pending));
+    }
+    const result = await definition.poll(ctx, pending.state);
+    if (!result) {
+        return {
+            ...challengeTurn(definition, pendingToChallengeRequest(pending)),
+            turnId: definition.pendingTurnId ??
+                definition.turnId ??
+                `credentials.${pending.challengeId}.pending`,
+        };
+    }
+    return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
+}
+export function defineCredentialsAuth(options) {
+    if (Object.keys(options.fields).length === 0) {
+        throw new ProviderError("defineCredentialsAuth requires at least one field", {
+            fix: "Pass fields such as { email: { type: \"email\" }, password: { type: \"password\" } }.",
+        });
+    }
+    const expectedInput = expectedInputFromFields(options.fields);
+    const retryTurnId = options.retryTurnId ?? "credentials.retry";
+    const completeTurnId = options.completeTurnId ?? "credentials.complete";
+    const challenges = (options.challenges ?? {});
+    return {
+        auth: {
+            mode: "credentials",
+            flow: {
+                start: async () => ({
+                    kind: "form",
+                    turnId: options.startTurnId ?? "credentials.start",
+                    ...(options.hintKey ? { hintKey: options.hintKey } : {}),
+                    expectedInput,
+                }),
+                continue: async (ctx, rawInput) => {
+                    const pending = getPendingChallenge(ctx);
+                    if (pending) {
+                        return await continuePendingChallenge(ctx, options.credentialKeys, challenges, pending, rawInput, completeTurnId);
+                    }
+                    const missing = collectMissingFields(options.fields, rawInput);
+                    if (missing.length > 0) {
+                        return retryTurn(expectedInput, missing, retryTurnId);
+                    }
+                    const result = await options.login(ctx, normalizeInput(options.fields, rawInput));
+                    return await resolveAuthResult(ctx, options.credentialKeys, challenges, result, completeTurnId);
+                },
+                poll: async (ctx) => {
+                    const pending = getPendingChallenge(ctx);
+                    if (!pending) {
+                        return {
+                            kind: "pending",
+                            turnId: "credentials.noPendingChallenge",
+                        };
+                    }
+                    return await pollPendingChallenge(ctx, options.credentialKeys, challenges, pending, completeTurnId);
+                },
+            },
+        },
+        credential: {
+            keys: Array.from(options.credentialKeys),
+            ...(options.storesReusableSecret === undefined
+                ? {}
+                : { storesReusableSecret: options.storesReusableSecret }),
+            ...(options.justification ? { justification: options.justification } : {}),
+        },
+        context: {
+            keys: Array.from(new Set([
+                CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY,
+                ...(options.contextKeys ?? []),
+            ])),
+        },
+    };
+}