authhero 5.8.1 → 5.9.0

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

@@ -0,0 +1,173 @@
+/**
+ * U2 Universal Login - Client-side widget routes
+ *
+ * This module creates the u2 app which provides a client-side widget-based
+ * universal login experience. It's meant to run in parallel with /u/ routes
+ * and will eventually replace them.
+ *
+ * Routes:
+ * - /u2/screen/:screenId - Screen API (GET/POST)
+ * - /u2/login/identifier - Identifier screen
+ * - /u2/login/email-otp-challenge - Email OTP code verification
+ * - /u2/login/sms-otp-challenge - SMS OTP code verification
+ * - /u2/enter-password - Password authentication
+ * - /u2/signup - New user registration
+ * - /u2/reset-password/request - Password reset request
+ * - /u2/reset-password - Set new password
+ */
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { AuthHeroConfig, Bindings, Variables } from "../../types";
+export default function createU2App(config: AuthHeroConfig): OpenAPIHono<{
+    Bindings: Bindings;
+    Variables: Variables;
+}, import("hono/types").MergeSchemaPath<{
+    [x: string]: {
+        $get: {
+            input: {
+                query: {
+                    state: string;
+                    error?: string | undefined;
+                    error_description?: string | undefined;
+                    ui_locales?: string | undefined;
+                };
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+} & {
+    [x: string]: {
+        $post: {
+            input: {
+                query: {
+                    state: string;
+                    error?: string | undefined;
+                    error_description?: string | undefined;
+                    ui_locales?: string | undefined;
+                };
+            } & {
+                form: Record<string, string>;
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        } | {
+            input: {
+                query: {
+                    state: string;
+                    error?: string | undefined;
+                    error_description?: string | undefined;
+                    ui_locales?: string | undefined;
+                };
+            } & {
+                form: Record<string, string>;
+            };
+            output: {};
+            outputFormat: string;
+            status: 302;
+        };
+    };
+} & {
+    "/guardian/enroll": {
+        $get: {
+            input: {
+                query: {
+                    ticket: string;
+                };
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        } | {
+            input: {
+                query: {
+                    ticket: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 302;
+        };
+    };
+}, "/"> & import("hono/types").MergeSchemaPath<{
+    "/: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;
+        };
+    };
+}, "/forms"> & import("hono/types").MergeSchemaPath<{}, "/screen">, "/">;
+export { screenApiRoutes } from "./screen-api";
+export { u2Routes } from "./u2-routes.tsx";
+export { u2FormNodeRoutes } from "./u2-form-node.tsx";

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

@@ -0,0 +1,98 @@
+/**
+ * U2 Routes - Universal login with SSR + hydration + client-side navigation
+ *
+ * These routes serve HTML pages with server-side rendered authhero-widget
+ * that hydrates on the client for interactivity and client-side navigation.
+ *
+ * Routes:
+ * - GET /u2/login/identifier - Identifier screen (first screen of login flow)
+ * - GET /u2/login/email-otp-challenge - Email OTP code verification
+ * - GET /u2/login/sms-otp-challenge - SMS OTP code verification
+ * - GET /u2/enter-password - Password authentication
+ * - GET /u2/signup - New user registration
+ * - GET /u2/reset-password/request - Password reset request
+ * - GET /u2/reset-password - Set new password
+ * - GET /u2/impersonate - User impersonation
+ *
+ * Each route:
+ * 1. Fetches screen data server-side
+ * 2. Server-side renders the widget with declarative shadow DOM
+ * 3. Hydrates on client for interactivity
+ * 4. Supports client-side navigation between screens
+ */
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Bindings, Variables } from "../../types";
+export declare const u2Routes: OpenAPIHono<{
+    Bindings: Bindings;
+    Variables: Variables;
+}, {
+    [x: string]: {
+        $get: {
+            input: {
+                query: {
+                    state: string;
+                    error?: string | undefined;
+                    error_description?: string | undefined;
+                    ui_locales?: string | undefined;
+                };
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        };
+    };
+} & {
+    [x: string]: {
+        $post: {
+            input: {
+                query: {
+                    state: string;
+                    error?: string | undefined;
+                    error_description?: string | undefined;
+                    ui_locales?: string | undefined;
+                };
+            } & {
+                form: Record<string, string>;
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        } | {
+            input: {
+                query: {
+                    state: string;
+                    error?: string | undefined;
+                    error_description?: string | undefined;
+                    ui_locales?: string | undefined;
+                };
+            } & {
+                form: Record<string, string>;
+            };
+            output: {};
+            outputFormat: string;
+            status: 302;
+        };
+    };
+} & {
+    "/guardian/enroll": {
+        $get: {
+            input: {
+                query: {
+                    ticket: string;
+                };
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        } | {
+            input: {
+                query: {
+                    ticket: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 302;
+        };
+    };
+}, "/">;

package/dist/types/routes/universal-login/u2-widget-page.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Shared widget page rendering for U2 routes.
+ *
+ * v3 — Logo inside widget by default + adaptive chip chrome.
+ *
+ * Changes vs. v2:
+ *  - Logo renders INSIDE the widget card by default (Auth0-style). The
+ *    widget's own shadow DOM emits the logo from `branding.logo_url`, so
+ *    the page doesn't add an outer-container duplicate. Set
+ *    `logoPosition="chip"` to render the floating-chip variant instead.
+ *  - Chips adapt to dark/light page mode (translucent dark vs. translucent
+ *    white). Tokens are CSS variables flipped via a `data-mode` attribute,
+ *    so a single ruleset handles both directions.
+ *  - When there's no background image, chips drop their pill surface and
+ *    render as plain text (matches a clean solid-bg layout).
+ *  - Privacy/Terms is now a real chip in the with-image case so it doesn't
+ *    float as orphan text.
+ *
+ *   ┌─────────────────────────────────────┐
+ *   │ [logo*]                 [settings]  │   *only when logoPosition=chip
+ *   │                                     │
+ *   │            ┌──────────┐             │
+ *   │            │ [logo]   │             │   <- widget's own header (default)
+ *   │            │  widget  │             │
+ *   │            └──────────┘             │
+ *   │                                     │
+ *   │ [trust]                    [legal]  │
+ *   └─────────────────────────────────────┘
+ *
+ * Slot story (forward-looking): the chips carry `data-ah-slot` attrs so a
+ * future Liquid template can reposition any element via `{% slot %}` tags.
+ * `logoPosition` is the prop-level shortcut for the most common override.
+ */
+import type { Branding, Theme } from "@authhero/adapter-interfaces";
+export type DarkModePreference = "auto" | "light" | "dark";
+export type LogoPosition = "widget" | "chip" | "none";
+/**
+ * Resolve the dark-mode preference for the current request.
+ *
+ * Priority: per-user `ah-dark-mode` cookie > tenant `branding.dark_mode` > "auto".
+ * The cookie lets a user override the tenant default for the rest of their session.
+ */
+export declare function resolveDarkMode(ctx: any, branding: Branding | null | undefined): DarkModePreference;
+export type WidgetPageProps = {
+    widgetHtml: string;
+    screenId: string;
+    branding?: {
+        colors?: {
+            primary?: string;
+            page_background?: string | {
+                type?: string;
+                start?: string;
+                end?: string;
+                angle_deg?: number;
+            };
+        };
+        logo_url?: string;
+        favicon_url?: string;
+        font?: {
+            url?: string;
+        };
+    };
+    theme?: any;
+    themePageBackground?: {
+        background_color?: string;
+        background_image_url?: string;
+        page_layout?: string;
+    };
+    clientName: string;
+    poweredByLogo?: {
+        url: string;
+        darkUrl?: string;
+        alt: string;
+        href?: string;
+        height?: number;
+    };
+    language?: string;
+    availableLanguages?: string[];
+    termsAndConditionsUrl?: string;
+    darkMode?: DarkModePreference;
+    /**
+     * Where to render the tenant logo on the page.
+     * - "widget" (default): inside the widget card, via the widget's own header.
+     * - "chip": floating pill in the top-left page corner. The widget's
+     *   internal logo should also be suppressed in this mode (callers use
+     *   `derivePageLogoPlacement` to clone the theme accordingly before SSR).
+     * - "none": no logo on the page or in the widget.
+     *
+     * If not provided, defaults to `theme.page_background.logo_placement`,
+     * falling back to "widget".
+     */
+    logoPosition?: LogoPosition;
+    /** Optional inline script injected at page level (e.g. WebAuthn ceremony) */
+    extraScript?: string;
+    /**
+     * When set, replaces the default body content (widget + chips) with a
+     * pre-expanded HTML fragment. Used by the universal-login custom-template
+     * path: the tenant's template is run through `applyUniversalLoginTemplate`
+     * and the resulting body markup is injected here, while the page shell
+     * (html/head, dark-mode runtime, background tint, body styling) is still
+     * managed by this component.
+     */
+    customBodyHtml?: string;
+};
+export declare function LogoChip({ logoUrl, clientName, }: {
+    logoUrl?: string | null;
+    clientName: string;
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element;
+export declare function DarkModeToggle({ darkMode }: {
+    darkMode: DarkModePreference;
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element;
+export declare function LanguagePicker({ language, availableLanguages, }: {
+    language?: string;
+    availableLanguages: string[];
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element | null;
+export declare function SettingsChip({ darkMode, language, availableLanguages, }: {
+    darkMode: DarkModePreference;
+    language?: string;
+    availableLanguages?: string[];
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element;
+export declare function PoweredByChip({ url, href, alt, height, }: {
+    url: string;
+    href?: string;
+    alt?: string;
+    height?: number;
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element | null;
+export declare function LegalChip({ termsAndConditionsUrl, language, }: {
+    termsAndConditionsUrl?: string;
+    language?: string;
+}): import("hono/jsx/jsx-dev-runtime").JSX.Element | null;
+export declare function WidgetPage({ widgetHtml, screenId, branding, theme, themePageBackground, clientName, poweredByLogo, language, availableLanguages, termsAndConditionsUrl, darkMode, logoPosition, extraScript, customBodyHtml, }: WidgetPageProps): import("hono/jsx/jsx-dev-runtime").JSX.Element;
+/**
+ * Reads `theme.page_background.logo_placement` and returns the resolved
+ * page-level `logoPosition` plus a theme variant suitable for passing to
+ * the widget SSR. When placement is "chip" or "none" we override
+ * `theme.widget.logo_position = "none"` so the widget's internal header
+ * logo is suppressed — otherwise we'd render a duplicate (chip + widget
+ * header) or a logo when the caller asked for none.
+ *
+ * Callers should pass the returned `theme` to `JSON.stringify` for the
+ * widget's `theme` attribute, and forward `logoPosition` to `WidgetPage`.
+ */
+export declare function derivePageLogoPlacement<T extends {
+    page_background?: {
+        logo_placement?: LogoPosition;
+    };
+    widget?: {
+        logo_position?: string;
+    };
+} | null | undefined>(theme: T): {
+    logoPosition: LogoPosition;
+    theme: T;
+};
+export declare function renderWidgetSSR(params: {
+    screenId: string;
+    screenJson: string;
+    brandingJson?: string;
+    themeJson?: string;
+    state: string;
+    authParamsJson: string;
+}): Promise<string>;
+export declare function extractBrandingProps(branding: Branding | null | undefined): WidgetPageProps["branding"];
+export declare function renderWidgetPageResponse(ctx: any, opts: {
+    screenId: string;
+    screenJson: string;
+    brandingJson?: string;
+    themeJson?: string;
+    state: string;
+    authParamsJson: string;
+    branding: Branding | null | undefined;
+    theme: Theme | null | undefined;
+    clientName: string;
+    poweredByLogo?: WidgetPageProps["poweredByLogo"];
+    language?: string;
+    availableLanguages?: string[];
+    termsAndConditionsUrl?: string;
+    darkMode?: DarkModePreference;
+    logoPosition?: LogoPosition;
+    extraScript?: string;
+    /**
+     * Optional tenant-uploaded body template. When provided, the body is
+     * built via `applyUniversalLoginTemplate(customTemplateBody, ...)`
+     * instead of the default chip layout. The shell (html/head, runtime,
+     * bg tint) is unchanged.
+     */
+    customTemplateBody?: string;
+}): Promise<Response>;

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

@@ -0,0 +1,55 @@
+/**
+ * Universal Login Template — slot-based body markup.
+ *
+ * Tenants opt into custom chrome by uploading a body fragment that uses these
+ * slot tokens. The default body (`DEFAULT_UNIVERSAL_LOGIN_TEMPLATE`) is
+ * what's served when no custom template is stored, and is what tenants
+ * should copy and edit.
+ *
+ * The page shell (`<!DOCTYPE>`, `<html>`, `<head>`, body styles, dark-mode
+ * runtime, background tint) is fixed in code — it's not part of the tenant
+ * template. This keeps tenants out of CSS/runtime authoring and limits
+ * customization to layout: hide a chip by deleting its token, reorder by
+ * moving them.
+ *
+ * Slot tokens:
+ *   `{%- auth0:widget -%}`             — widget container (required)
+ *   `{%- authhero:logo -%}`            — logo chip (top-left)
+ *   `{%- authhero:settings -%}`        — settings chip (top-right), wraps the
+ *                                        dark-mode toggle + language picker
+ *   `{%- authhero:dark-mode-toggle -%}`— dark-mode button only
+ *   `{%- authhero:language-picker -%}` — language picker only
+ *   `{%- authhero:powered-by -%}`      — powered-by chip (bottom-left)
+ *   `{%- authhero:legal -%}`           — legal/terms chip (bottom-right)
+ */
+import { type DarkModePreference } from "./u2-widget-page";
+export declare const REQUIRED_SLOT = "{%- auth0:widget -%}";
+/**
+ * Canonical default body. Mirrors the layout the JSX `WidgetPage` emits.
+ * Tenants who want to hide a chip should copy this, delete a slot, and PUT
+ * it back via `PUT /api/v2/branding/templates/universal-login`.
+ */
+export declare const DEFAULT_UNIVERSAL_LOGIN_TEMPLATE = "{%- auth0:widget -%}\n{%- authhero:logo -%}\n{%- authhero:settings -%}\n{%- authhero:powered-by -%}\n{%- authhero:legal -%}\n";
+export type TemplateSlotOptions = {
+    widgetHtml: string;
+    logoUrl?: string | null;
+    clientName: string;
+    darkMode: DarkModePreference;
+    language?: string;
+    availableLanguages?: string[];
+    poweredBy?: {
+        url: string;
+        href?: string;
+        alt?: string;
+        height?: number;
+    };
+    termsAndConditionsUrl?: string;
+};
+/**
+ * Expand slot tokens in a template body. Unknown tokens are left in place
+ * (so tenants can spot typos in their templates).
+ */
+export declare function applyUniversalLoginTemplate(template: string, opts: TemplateSlotOptions & {
+    screenId: string;
+    widgetContainerStyle?: string;
+}): string;

package/dist/types/routes/universal-login/validate-email.d.ts

@@ -0,0 +1,20 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Bindings, Variables } from "../../types";
+export declare const validateEmailRoutes: OpenAPIHono<{
+    Bindings: Bindings;
+    Variables: Variables;
+}, {
+    "/": {
+        $get: {
+            input: {
+                query: {
+                    state: string;
+                    code: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 200;
+        };
+    };
+}, "/">;

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

@@ -0,0 +1,81 @@
+/**
+ * Widget Routes - Universal Login with built-in screens (SSR + Hydration)
+ *
+ * These routes serve the widget UI for each screen in the login flow.
+ * The widget is server-side rendered for instant display, then hydrated
+ * on the client for interactivity.
+ *
+ * Route pattern: /u/widget/:screenId?state=...
+ *
+ * Available screens:
+ * - /u/widget/identifier - Email/username input (first screen)
+ * - /u/widget/email-otp-challenge - Email OTP code verification
+ * - /u/widget/sms-otp-challenge - SMS OTP code verification
+ * - /u/widget/enter-password - Password authentication
+ * - /u/widget/signup - New user registration
+ * - /u/widget/forgot-password - Password reset request
+ * - /u/widget/reset-password - Set new password
+ */
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Bindings, Variables } from "../../types";
+export declare const widgetRoutes: OpenAPIHono<{
+    Bindings: Bindings;
+    Variables: Variables;
+}, {
+    "/:screenId": {
+        $get: {
+            input: {
+                param: {
+                    screenId: string;
+                };
+            } & {
+                query: {
+                    state: string;
+                };
+            };
+            output: Response;
+            outputFormat: "json";
+            status: import("hono/utils/http-status").StatusCode;
+        } | {
+            input: {
+                param: {
+                    screenId: string;
+                };
+            } & {
+                query: {
+                    state: string;
+                };
+            };
+            output: {};
+            outputFormat: string;
+            status: 404;
+        };
+    };
+} & {
+    "/:screenId": {
+        $post: {
+            input: {
+                param: {
+                    screenId: string;
+                };
+            } & {
+                query: {
+                    state: string;
+                    action?: string | undefined;
+                };
+            } & {
+                json: {
+                    data: Record<string, any>;
+                };
+            };
+            output: {
+                screen: any;
+                branding?: any;
+            } | {
+                redirect: string;
+            };
+            outputFormat: "json";
+            status: 200;
+        };
+    };
+}, "/">;

package/dist/types/seed.d.ts

@@ -0,0 +1,86 @@
+import { DataAdapters } from "@authhero/adapter-interfaces";
+/**
+ * Management API scopes for the AuthHero Management API
+ */
+export declare const MANAGEMENT_API_SCOPES: {
+    description: string;
+    value: string;
+}[];
+export interface SeedOptions {
+    /**
+     * The admin user's username
+     */
+    adminUsername: string;
+    /**
+     * The admin user's email address (optional)
+     */
+    adminEmail?: string;
+    /**
+     * The admin user's password (will be hashed with bcrypt)
+     */
+    adminPassword: string;
+    /**
+     * The tenant ID to create (defaults to "control_plane")
+     */
+    tenantId?: string;
+    /**
+     * The tenant name (defaults to "Control Plane")
+     */
+    tenantName?: string;
+    /**
+     * The audience URL for the tenant.
+     * For the main/management tenant, defaults to `urn:authhero:management`.
+     */
+    audience?: string;
+    /**
+     * Whether this is the control plane tenant (the main management tenant).
+     * If true, the audience will default to `urn:authhero:management`.
+     * @default true
+     */
+    isControlPlane?: boolean;
+    /**
+     * The default client ID (defaults to "default")
+     */
+    clientId?: string;
+    /**
+     * Callback URLs for the default client
+     */
+    callbacks?: string[];
+    /**
+     * Allowed logout URLs for the default client
+     */
+    allowedLogoutUrls?: string[];
+    /**
+     * Whether to log progress (defaults to true)
+     */
+    debug?: boolean;
+    /**
+     * The issuer URL (used to construct the Management API identifier)
+     */
+    issuer?: string;
+}
+export interface SeedResult {
+    tenantId: string;
+    userId: string;
+    username: string;
+    clientId: string;
+    clientSecret: string;
+}
+/**
+ * Seed the AuthHero database with initial data.
+ * Creates a default tenant, admin user, password connection, and default client.
+ *
+ * @example
+ * ```ts
+ * import { seed } from "authhero";
+ * import createAdapters from "@authhero/kysely-adapter";
+ *
+ * const adapters = createAdapters(db);
+ *
+ * await seed(adapters, {
+ *   adminUsername: "admin",
+ *   adminPassword: "admin",
+ * });
+ * ```
+ */
+export declare function seed(adapters: DataAdapters, options: SeedOptions): Promise<SeedResult>;