authhero 5.8.1 → 5.9.0

package/dist/types/routes/universal-login/screens/mfa-totp-enrollment.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MFA TOTP Enrollment screen - for setting up authenticator app MFA
+ *
+ * Corresponds to: /u2/mfa/totp-enrollment
+ */
+import type { ScreenContext, ScreenResult, ScreenDefinition } from "./types";
+/**
+ * Create the mfa-totp-enrollment screen
+ */
+export declare function mfaTotpEnrollmentScreen(context: ScreenContext, extraData?: {
+    qrCodeSvg?: string;
+    secretBase32?: string;
+}): Promise<ScreenResult>;
+/**
+ * Screen definition for the mfa-totp-enrollment screen
+ */
+export declare const mfaTotpEnrollmentScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/passkey-challenge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Passkey Challenge screen — WebAuthn authentication ceremony
+ *
+ * Allows users to sign in using a registered passkey (discoverable credential).
+ * This triggers navigator.credentials.get() and verifies the assertion response.
+ *
+ * GET:  Generates WebAuthn authentication options and renders the challenge screen.
+ * POST: Verifies the assertion response, resolves the user, and completes login.
+ *
+ * Passkey authentication bypasses MFA since it already provides strong
+ * multi-factor assurance (possession + biometric/PIN).
+ *
+ * Corresponds to: /u2/passkey/challenge
+ */
+import type { ScreenDefinition } from "./types";
+export declare const passkeyChallengeScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/passkey-enrollment-nudge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Passkey Enrollment Nudge screen
+ *
+ * Shown after login when progressive enrollment is enabled and the user
+ * has no passkeys registered. Offers three choices:
+ *   - "Set up passkey" → proceeds to the enrollment ceremony
+ *   - "Maybe later"    → snoozes the prompt for 30 days
+ *   - "Don't show again" → permanently opts out
+ *
+ * Client-side: if the browser doesn't support WebAuthn
+ * (window.PublicKeyCredential is undefined), the screen auto-submits
+ * with action_no_webauthn so the login flow is never blocked.
+ *
+ * Corresponds to: /u2/passkey/enrollment-nudge
+ */
+import type { ScreenDefinition } from "./types";
+export declare const passkeyEnrollmentNudgeScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/passkey-enrollment.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Passkey Enrollment screen — WebAuthn registration ceremony
+ *
+ * GET:  Generates WebAuthn registration options and renders a screen that
+ *       triggers `navigator.credentials.create()` via an inline script.
+ * POST: Verifies the attestation response and stores the credential.
+ *
+ * Corresponds to: /u2/passkey/enrollment
+ */
+import type { ScreenDefinition } from "./types";
+export declare const passkeyEnrollmentScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/passkey-utils.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared WebAuthn/passkey utilities used by passkey-enrollment, account-passkeys,
+ * passkey-challenge, and conditional mediation on identifier/login screens.
+ */
+import { AuthenticationMethod } from "@authhero/adapter-interfaces";
+import { Context } from "hono";
+import type { Bindings, Variables } from "../../../types";
+import type { WebAuthnCeremony, ScreenContext } from "./types";
+export declare const PASSKEY_TYPES: readonly ["passkey", "webauthn-roaming", "webauthn-platform"];
+/**
+ * List the tenant-scoped passkey authentication methods for a given user.
+ * Filters out non-passkey types and rows missing a credential_id.
+ * Used by the challenge screen (to build allowCredentials) and by the login
+ * screen (to gate the "Log in with passkey" link when the current tenant has
+ * no matching credential for the known user).
+ */
+export declare function listTenantPasskeys(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string, userId: string): Promise<AuthenticationMethod[]>;
+/**
+ * Extract the RP ID from the host — strips port and uses the root domain.
+ * Must use the actual request host (not custom_domain) because WebAuthn
+ * requires rp.id to match the browser's current origin.
+ */
+export declare function getRpId(ctx: any): string;
+/**
+ * Get the origin URL for WebAuthn verification.
+ * Must use the actual request host to match the browser's origin.
+ */
+export declare function getExpectedOrigin(ctx: any): string;
+/**
+ * Build the inline JavaScript that triggers navigator.credentials.create()
+ * and auto-submits the form with the credential result.
+ *
+ * @param optionsJSON - JSON string of WebAuthn registration options
+ * @param successAction - The action value to set on successful registration (default: "register")
+ */
+export declare function buildWebAuthnRegistrationScript(optionsJSON: string, successAction?: string): string;
+/**
+ * Build a structured WebAuthn ceremony object for the widget SPA flow.
+ * The widget validates the shape and performs the ceremony natively
+ * instead of executing arbitrary script content.
+ *
+ * @param optionsJSON - JSON string of WebAuthn registration options
+ * @param successAction - The action value to set on successful registration (default: "register")
+ */
+export declare function buildWebAuthnCeremony(optionsJSON: string, successAction?: string): WebAuthnCeremony;
+/**
+ * Build the inline JavaScript that triggers navigator.credentials.get()
+ * for passkey authentication (login) and auto-submits the form.
+ *
+ * @param optionsJSON - JSON string of WebAuthn authentication options
+ * @param successAction - The action value to set on successful authentication (default: "authenticate")
+ */
+export declare function buildWebAuthnAuthenticationScript(optionsJSON: string, successAction?: string): string;
+/**
+ * Build a structured WebAuthn authentication ceremony object for the widget SPA flow.
+ *
+ * @param optionsJSON - JSON string of WebAuthn authentication options
+ * @param successAction - The action value to set on successful authentication (default: "authenticate")
+ */
+export declare function buildWebAuthnAuthenticationCeremony(optionsJSON: string, successAction?: string): WebAuthnCeremony;
+/**
+ * Build a structured WebAuthn conditional mediation ceremony object for the widget SPA flow.
+ * Conditional mediation shows passkey suggestions in the username field's autofill dropdown.
+ *
+ * @param optionsJSON - JSON string of WebAuthn authentication options
+ * @param successAction - The action value to set on successful authentication (default: "passkey-authenticate")
+ */
+export declare function buildWebAuthnConditionalMediationCeremony(optionsJSON: string, successAction?: string): WebAuthnCeremony;
+/**
+ * Build inline JavaScript for conditional mediation (autofill-assisted passkeys).
+ * This script runs on page load and silently offers passkey suggestions in the
+ * username field's autofill dropdown via `navigator.credentials.get({ mediation: "conditional" })`.
+ *
+ * @param optionsJSON - JSON string of WebAuthn authentication options
+ * @param successAction - The action value to set on successful authentication (default: "passkey-authenticate")
+ */
+export declare function buildConditionalMediationScript(optionsJSON: string, successAction?: string): string;
+/**
+ * Result type for passkey verification
+ */
+export type PasskeyVerificationResult = {
+    success: true;
+    user: any;
+    primaryUser: any;
+    loginSession: any;
+    authConnection: string;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Shared passkey authentication verification logic.
+ * Used by both passkey-challenge screen (MFA) and identifier/login screens (conditional mediation).
+ *
+ * Verifies the WebAuthn assertion response, resolves the user, and updates session state.
+ */
+export declare function verifyPasskeyAuthentication(context: ScreenContext, credentialJson: string): Promise<PasskeyVerificationResult>;

package/dist/types/routes/universal-login/screens/registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Screen Registry - maps screen IDs to their definitions
+ */
+import type { ScreenDefinition, ScreenContext, ScreenResult } from "./types";
+/**
+ * Registry of all built-in screens
+ */
+export declare const screenRegistry: Map<string, ScreenDefinition>;
+/**
+ * Get a screen definition by ID
+ */
+export declare function getScreenDefinition(screenId: string): ScreenDefinition | undefined;
+/**
+ * Get a screen by ID
+ *
+ * @param screenId - The screen ID (e.g., "identifier", "email-otp-challenge")
+ * @param context - The screen context with tenant, client, branding, etc.
+ * @returns The screen result promise or undefined if not found
+ */
+export declare function getScreen(screenId: string, context: ScreenContext): Promise<ScreenResult> | undefined;
+/**
+ * List all available screen IDs
+ */
+export declare function listScreenIds(): string[];
+/**
+ * Check if a screen ID is valid
+ */
+export declare function isValidScreenId(screenId: string): boolean;

package/dist/types/routes/universal-login/screens/reset-password-code.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reset Password Code screen - enter code + new password
+ *
+ * Used when the connection's verification_method is "code".
+ * The user receives a 6-digit code via email and enters it
+ * along with their new password on the same page.
+ *
+ * Corresponds to: /u2/reset-password/code
+ */
+import type { ScreenContext, ScreenResult, ScreenDefinition } from "./types";
+/**
+ * Create the reset-password-code screen
+ */
+export declare function resetPasswordCodeScreen(context: ScreenContext): Promise<ScreenResult>;
+/**
+ * Screen definition for the reset-password-code screen
+ */
+export declare const resetPasswordCodeScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/reset-password.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Reset Password screen - set new password after reset
+ *
+ * Corresponds to: /u/reset-password
+ */
+import type { ScreenContext, ScreenResult, ScreenDefinition } from "./types";
+import type { Context } from "hono";
+import type { Bindings, Variables } from "../../../types";
+import type { EnrichedClient } from "../../../helpers/client";
+/**
+ * Shared helper to execute a password reset: validate code, validate policy,
+ * update password, mark email verified, log, and delete code.
+ */
+export declare function executePasswordReset(params: {
+    ctx: Context<{
+        Bindings: Bindings;
+        Variables: Variables;
+    }>;
+    client: EnrichedClient;
+    code: string;
+    password: string;
+    username: string;
+}): Promise<{
+    success: true;
+} | {
+    error: string;
+    field: "code" | "password";
+}>;
+/**
+ * Create the reset-password screen
+ */
+export declare function resetPasswordScreen(context: ScreenContext): Promise<ScreenResult>;
+/**
+ * Screen definition for the reset-password screen
+ */
+export declare const resetPasswordScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/signup.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Signup screen - for new user registration
+ *
+ * Corresponds to: /u/signup
+ */
+import type { ScreenContext, ScreenResult, ScreenDefinition } from "./types";
+/**
+ * Create the signup screen
+ */
+export declare function signupScreen(context: ScreenContext): Promise<ScreenResult>;
+/**
+ * Screen definition for the signup screen
+ */
+export declare const signupScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/sms-otp-challenge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * SMS OTP Challenge screen - for SMS OTP verification
+ *
+ * Corresponds to: /u/login/sms-otp-challenge
+ */
+import type { ScreenContext, ScreenResult, ScreenDefinition } from "./types";
+/**
+ * Create the sms-otp-challenge screen
+ */
+export declare function smsOtpChallengeScreen(context: ScreenContext): Promise<ScreenResult>;
+/**
+ * Screen definition for the sms-otp-challenge screen
+ */
+export declare const smsOtpChallengeScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/try-connection-result.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Try-Connection Result screen — diagnostic page that renders the outcome
+ * of a connection test (initiated via `POST /api/v2/connections/{id}/try`).
+ *
+ * Corresponds to: /u2/try-connection-result
+ *
+ * The result is read from `loginSession.state_data` — the connection
+ * callback writes it there before redirecting here.
+ */
+import type { ScreenContext, ScreenResult, ScreenDefinition } from "./types";
+export declare function tryConnectionResultScreen(context: ScreenContext): Promise<ScreenResult>;
+export declare const tryConnectionResultScreenDefinition: ScreenDefinition;

package/dist/types/routes/universal-login/screens/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Types for built-in screens
+ */
+import { Context } from "hono";
+import { UiScreen, Tenant, Theme, Connection, CustomText } from "@authhero/adapter-interfaces";
+import { EnrichedClient } from "../../../helpers/client";
+import { Bindings, Variables } from "../../../types";
+/**
+ * Branding information for screen rendering
+ */
+export interface ScreenBranding {
+    logo_url?: string;
+    favicon_url?: string;
+    powered_by_logo_url?: string;
+    colors?: {
+        primary?: string;
+        page_background?: string | {
+            type?: string;
+            start?: string;
+            end?: string;
+            angle_deg?: number;
+        };
+    };
+    font?: {
+        url?: string;
+    };
+}
+/**
+ * Context passed to screen factories
+ */
+export interface ScreenContext {
+    /** The Hono context */
+    ctx: Context<{
+        Bindings: Bindings;
+        Variables: Variables;
+    }>;
+    /** The current tenant */
+    tenant: Tenant;
+    /** The current client application - uses EnrichedClient which has full connection objects */
+    client: EnrichedClient;
+    /** Theme configuration */
+    theme?: Theme;
+    /** Branding configuration */
+    branding?: ScreenBranding;
+    /** Available connections for this client */
+    connections: Connection[];
+    /** The login state parameter */
+    state: string;
+    /** Pre-filled values for form fields */
+    prefill?: Record<string, string | undefined>;
+    /** Error messages to display */
+    errors?: Record<string, string>;
+    /** Screen-level messages to display (errors, success, info, warnings) */
+    messages?: Array<{
+        text: string;
+        type: "error" | "success" | "info" | "warning";
+    }>;
+    /** Additional screen-specific data */
+    data?: Record<string, unknown>;
+    /** Route prefix for universal login routes (e.g., "/u" or "/u2") */
+    routePrefix?: string;
+    /** Custom texts for the current language */
+    customText?: CustomText;
+    /** Current language code (e.g., 'en', 'es') */
+    language?: string;
+    /** Prompt screen ID for custom text namespacing (e.g., 'login-id', 'signup') */
+    promptScreen?: string;
+    /** Screen name for extracting screen-specific custom text from nested structure */
+    screenName?: string;
+}
+/**
+ * Structured WebAuthn ceremony data sent to the widget instead of raw script.
+ * The widget validates the shape and performs the ceremony natively.
+ */
+export interface WebAuthnCeremony {
+    type: "webauthn-registration" | "webauthn-authentication" | "webauthn-authentication-conditional";
+    options: {
+        challenge: string;
+        rp?: {
+            id: string;
+            name: string;
+        };
+        rpId?: string;
+        user?: {
+            id: string;
+            name: string;
+            displayName: string;
+        };
+        pubKeyCredParams?: Array<{
+            alg: number;
+            type: string;
+        }>;
+        timeout?: number;
+        attestation?: string;
+        authenticatorSelection?: {
+            residentKey?: string;
+            userVerification?: string;
+        };
+        excludeCredentials?: Array<{
+            id: string;
+            type: string;
+            transports?: string[];
+        }>;
+        userVerification?: string;
+        allowCredentials?: Array<{
+            id: string;
+            type: string;
+            transports?: string[];
+        }>;
+    };
+    successAction: string;
+}
+/**
+ * Result from a screen factory
+ */
+export interface ScreenResult {
+    /** The screen definition for the widget */
+    screen: UiScreen;
+    /** Branding to apply */
+    branding?: ScreenBranding;
+    /** Optional inline script to inject at page level (e.g. WebAuthn ceremony) */
+    extraScript?: string;
+    /** Structured WebAuthn ceremony data for widget-based flows */
+    ceremony?: WebAuthnCeremony;
+}
+/**
+ * A screen factory creates a UiScreen from context
+ * Always async for consistency (even if the implementation is sync)
+ */
+export type ScreenFactory = (context: ScreenContext) => Promise<ScreenResult>;
+/**
+ * Handler for screen form submissions
+ */
+export interface ScreenHandler {
+    /** Handle GET request - returns the screen (can be sync or async) */
+    get: ScreenFactory;
+    /** Handle POST request - process form data and return next screen or redirect */
+    post?: (context: ScreenContext, data: Record<string, unknown>) => Promise<{
+        screen: ScreenResult;
+    } | {
+        redirect: string;
+        cookies?: string[];
+    } | {
+        error: string;
+        screen: ScreenResult;
+    } | {
+        response: Response;
+    }>;
+}
+/**
+ * Screen definition including factory and optional handler
+ */
+export interface ScreenDefinition {
+    /** Unique screen ID (matches route path) */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** The screen handler */
+    handler: ScreenHandler;
+}
+/**
+ * Get the correct login path based on the tenant's identifier_first setting.
+ * Returns "/u2/login" for password-first or "/u2/login/identifier" for identifier-first.
+ */
+export declare function getLoginPath(context: ScreenContext): Promise<string>;

package/dist/types/routes/universal-login/signup.d.ts

@@ -0,0 +1,54 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Bindings, Variables } from "../../types";
+export declare const signupRoutes: OpenAPIHono<{
+    Bindings: Bindings;
+    Variables: Variables;
+}, {
+    "/": {
+        $get: {
+            input: {
+                query: {
+                    state: string;
+                    code?: string | undefined;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 200;
+        };
+    };
+} & {
+    "/": {
+        $post: {
+            input: {
+                query: {
+                    state: string;
+                };
+            } & {
+                form: {
+                    password: string;
+                    "re-enter-password": string;
+                    code?: string | undefined;
+                };
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        } | {
+            input: {
+                query: {
+                    state: string;
+                };
+            } & {
+                form: {
+                    password: string;
+                    "re-enter-password": string;
+                    code?: string | undefined;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 302;
+        };
+    };
+}, "/">;

package/dist/types/routes/universal-login/u2-form-node.d.ts

@@ -0,0 +1,93 @@
+/**
+ * U2 Form Node Routes - Widget-based form node rendering
+ *
+ * These routes serve form nodes with SSR + hydration for the widget-based
+ * universal login experience.
+ *
+ * Routes:
+ * - GET /u2/forms/:formId/nodes/:nodeId - Render form node with widget SSR
+ * - POST /u2/forms/:formId/nodes/:nodeId - Process form submission
+ */
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Bindings, Variables } from "../../types";
+export declare const u2FormNodeRoutes: OpenAPIHono<{
+    Bindings: Bindings;
+    Variables: Variables;
+}, {
+    "/:formId/nodes/:nodeId": {
+        $get: {
+            input: {
+                param: {
+                    formId: string;
+                    nodeId: string;
+                };
+            } & {
+                query: {
+                    state: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 200;
+        } | {
+            input: {
+                param: {
+                    formId: string;
+                    nodeId: string;
+                };
+            } & {
+                query: {
+                    state: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 404;
+        };
+    };
+} & {
+    "/:formId/nodes/:nodeId": {
+        $post: {
+            input: {
+                param: {
+                    formId: string;
+                    nodeId: string;
+                };
+            } & {
+                query: {
+                    state: string;
+                };
+            } & {
+                json: {
+                    data: Record<string, any>;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 404;
+        } | {
+            input: {
+                param: {
+                    formId: string;
+                    nodeId: string;
+                };
+            } & {
+                query: {
+                    state: string;
+                };
+            } & {
+                json: {
+                    data: Record<string, any>;
+                };
+            };
+            output: {
+                screen: any;
+                branding: any;
+            } | {
+                redirect: string;
+            };
+            outputFormat: "json";
+            status: 200;
+        };
+    };
+}, "/">;