authhero 5.8.1 → 5.9.0

package/dist/types/hooks/pre-defined/account-linking.d.ts

@@ -0,0 +1,73 @@
+import { HookEvent, OnExecutePostLogin } from "../../types/Hooks";
+export interface AccountLinkingOptions {
+    /**
+     * Require `email_verified` on the logged-in user before attempting to link.
+     * Disabling this is almost never what you want — unverified email linking
+     * lets an attacker claim existing accounts by signing up with a matching
+     * email on an unverifying provider.
+     * @default true
+     */
+    requireVerifiedEmail?: boolean;
+    /**
+     * When the link is performed, merge the secondary user's `user_metadata`
+     * into the primary's. Existing keys on the primary are NOT overwritten —
+     * only keys absent from the primary are filled in from the secondary, so
+     * the primary remains the source of truth for any conflicting values.
+     *
+     * `app_metadata` is intentionally never copied to avoid auto-merging into
+     * the admin-only namespace.
+     *
+     * @default false
+     */
+    copyUserMetadata?: boolean;
+}
+/**
+ * Trigger-agnostic event handler used by all `account-linking` template
+ * dispatch sites. It accepts the same shape as `OnExecutePostLogin` but
+ * ignores the trigger-specific `api` object, which lets the same function
+ * back `post-user-login`, `post-user-registration`, and `post-user-update`.
+ */
+export type AccountLinkingHandler = (event: HookEvent) => Promise<void>;
+/**
+ * Idempotently links a user to an existing primary user with the same
+ * (verified) email address. Safe to invoke from any trigger that has a
+ * `user` and a `tenant.id` on the event — `post-user-login`,
+ * `post-user-registration`, or `post-user-update`.
+ *
+ * This is the Auth0-style "Account Linking" action: customers enable it by
+ * creating a template hook with `template_id: "account-linking"`. Because
+ * the implementation is a no-op when linking is already correct, transient
+ * failures self-heal — a later trigger simply retries the link.
+ *
+ * **Behavior:**
+ * - No-op if the user already has `linked_to` set (already a secondary).
+ * - No-op if the user has no email or `email_verified` is false (default).
+ * - Looks up the primary user with the same email via
+ *   `getPrimaryUserByEmail`. If found AND it's not the user themselves,
+ *   sets `linked_to` on the user to point at that primary.
+ * - Never unlinks; if the current user is already the primary it stays so.
+ *
+ * **Idempotency:** repeated calls produce the same end state.
+ *
+ * @example Enable as a config-level post-login hook
+ * ```typescript
+ * import { init, preDefinedHooks } from "authhero";
+ *
+ * init({
+ *   dataAdapter,
+ *   hooks: {
+ *     onExecutePostLogin: preDefinedHooks.accountLinking(),
+ *   },
+ * });
+ * ```
+ *
+ * @example Enable as a per-tenant template hook (admin API)
+ * ```typescript
+ * await data.hooks.create(tenantId, {
+ *   trigger_id: "post-user-registration",
+ *   template_id: "account-linking",
+ *   enabled: true,
+ * });
+ * ```
+ */
+export declare function accountLinking(options?: AccountLinkingOptions): OnExecutePostLogin & AccountLinkingHandler;

package/dist/types/hooks/pre-defined/ensure-username.d.ts

@@ -0,0 +1,86 @@
+import { OnExecutePostLogin } from "../../types/Hooks";
+export interface EnsureUsernameOptions {
+    /**
+     * The connection name used for username accounts.
+     * @default Strategy.USERNAME_PASSWORD
+     */
+    connection?: string;
+    /**
+     * The provider used for username accounts.
+     * @default USERNAME_PASSWORD_PROVIDER
+     */
+    provider?: string;
+    /**
+     * Maximum number of attempts to find a unique username before giving up.
+     * @default 10
+     */
+    maxRetries?: number;
+}
+/**
+ * Slugify a string into a valid username.
+ *
+ * - Lowercases and normalizes unicode (NFD + strip diacritics)
+ * - Replaces non-alphanumeric characters with hyphens
+ * - Collapses consecutive hyphens
+ * - Trims leading/trailing hyphens
+ * - Returns undefined if the result is empty
+ */
+export declare function slugify(input: string): string | undefined;
+/**
+ * Extract candidate usernames from a user's profile fields.
+ *
+ * Tries the following fields in order:
+ * 1. nickname
+ * 2. name
+ * 3. Local part of email (before @)
+ * 4. phone_number
+ *
+ * Each value is slugified. Duplicates are removed while preserving order.
+ */
+export declare function extractCandidateUsernames(user: {
+    nickname?: string | null;
+    name?: string | null;
+    email?: string | null;
+    phone_number?: string | null;
+}): string[];
+/**
+ * Creates a post-login hook that ensures every user has a username.
+ *
+ * **Behavior:**
+ * - If the user is a username-type account (username-password provider), it verifies
+ *   the `username` field is set. If not, it picks one from the profile fields.
+ * - If the user logged in via another provider (email, social, SMS), it checks
+ *   whether a linked username account already exists. If not, it creates a new
+ *   username account and links it to the current user.
+ *
+ * **Username candidate extraction (in order):**
+ * 1. `nickname`
+ * 2. `name`
+ * 3. Local part of `email` (before `@`)
+ * 4. `phone_number`
+ *
+ * Each candidate is slugified (lowercased, non-alphanum replaced with hyphens).
+ * If the slug is taken, numeric suffixes are tried (e.g. `john`, `john2`, `john3`).
+ *
+ * @example
+ * ```typescript
+ * import { init, preDefinedHooks } from "authhero";
+ *
+ * const { app } = init({
+ *   dataAdapter,
+ *   hooks: {
+ *     onExecutePostLogin: preDefinedHooks.ensureUsername(),
+ *   },
+ * });
+ * ```
+ *
+ * @example Custom connection name
+ * ```typescript
+ * preDefinedHooks.ensureUsername({
+ *   connection: "my-username-connection",
+ *   provider: USERNAME_PASSWORD_PROVIDER,
+ *   maxRetries: 20,
+ * })
+ * ```
+ */
+export declare function ensureUsername(options?: EnsureUsernameOptions): OnExecutePostLogin;

package/dist/types/hooks/pre-defined/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pre-defined hooks library for AuthHero.
+ *
+ * These are ready-to-use hooks that implement common authentication patterns.
+ * Users can connect them via the `hooks` configuration in AuthHeroConfig.
+ *
+ * @example
+ * ```typescript
+ * import { init, preDefinedHooks } from "authhero";
+ *
+ * const { app } = init({
+ *   dataAdapter,
+ *   hooks: {
+ *     onExecutePostLogin: preDefinedHooks.ensureUsername(),
+ *   },
+ * });
+ * ```
+ */
+export { ensureUsername } from "./ensure-username";
+export type { EnsureUsernameOptions } from "./ensure-username";
+export { setPreferredUsername } from "./set-preferred-username";
+export { accountLinking } from "./account-linking";
+export type { AccountLinkingOptions } from "./account-linking";

package/dist/types/hooks/pre-defined/set-preferred-username.d.ts

@@ -0,0 +1,26 @@
+import { OnExecuteCredentialsExchange } from "../../types/Hooks";
+/**
+ * Creates a credentials-exchange hook that sets the `preferred_username`
+ * claim on both access and ID tokens.
+ *
+ * The username is resolved from the primary user or any linked identity.
+ * If no username is found, the hook does nothing.
+ *
+ * **Resolution order:**
+ * 1. `user.username` — direct username on the primary user
+ * 2. `user.preferred_username` — existing preferred_username field
+ * 3. Linked identities — first identity with `username` or `profileData.username`
+ *
+ * @example
+ * ```typescript
+ * import { init, preDefinedHooks } from "authhero";
+ *
+ * const { app } = init({
+ *   dataAdapter,
+ *   hooks: {
+ *     onExecuteCredentialsExchange: preDefinedHooks.setPreferredUsername(),
+ *   },
+ * });
+ * ```
+ */
+export declare function setPreferredUsername(): OnExecuteCredentialsExchange;

package/dist/types/hooks/templatehooks.d.ts

@@ -0,0 +1,29 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+import { User } from "@authhero/adapter-interfaces";
+import { OnExecuteCredentialsExchangeAPI } from "../types/Hooks";
+export declare function isTemplateHook(hook: any): hook is {
+    template_id: string;
+    enabled: boolean;
+};
+/**
+ * Handles a template hook by executing the corresponding pre-defined hook function.
+ * Template hooks map to code-level pre-defined hooks that can be enabled per-tenant
+ * through the admin UI without requiring server configuration changes.
+ *
+ * `metadata` carries the configuring tenant's options for the template — see
+ * `hookBaseCommonProperties.metadata` in the adapter-interfaces Hook schema.
+ * Each template that takes options reads its keys from here.
+ */
+export declare function handleTemplateHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, template_id: string, user: User, metadata?: Record<string, unknown>): Promise<User>;
+/**
+ * Handles a credentials-exchange template hook by executing the corresponding
+ * pre-defined hook function that sets custom claims on tokens.
+ */
+export declare function handleCredentialsExchangeTemplateHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, template_id: string, user: User, api: OnExecuteCredentialsExchangeAPI): Promise<void>;

package/dist/types/hooks/user-deletion.d.ts

@@ -0,0 +1,14 @@
+import { Context } from "hono";
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+/**
+ * Decorator applied by `addDataHooks` to `users.remove`. Runs pre-deletion
+ * hooks (outside any transaction), then executes the unlink-secondaries +
+ * delete-primary inside a single `data.transaction` so the user graph is
+ * never left half-demolished. Post-deletion webhook delivery is handed to
+ * the outbox for retryable dispatch.
+ */
+export declare function createUserDeletionHooks(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters): (tenant_id: string, user_id: string) => Promise<boolean>;

package/dist/types/hooks/user-registration.d.ts

@@ -0,0 +1,88 @@
+import { Context } from "hono";
+import { DataAdapters, User } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+/**
+ * Decorator applied by `addDataHooks` to `users.create`. Runs the full
+ * pre-commit/commit/publish pipeline for a user creation:
+ *
+ *  1. Pre-registration blocking hooks (outside any transaction so webhook
+ *     latency and user-authored code don't hold a DB connection).
+ *  2. `commitUserHook` — the internal transactional step that atomically
+ *     writes the user row (via `rawCreate`) and, when the built-in
+ *     email-based linking path is enabled, also resolves `linked_to` from
+ *     the existing primary inside the same transaction.
+ *  3. Post-registration hooks — webhook delivery is handed to the outbox
+ *     (`enqueuePostHookEvent`) for retryable / idempotent dispatch; code
+ *     hooks currently still run inline with ctx.
+ */
+export declare function createUserHooks(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters): (tenant_id: string, user: User) => Promise<{
+    connection: string;
+    email_verified: boolean;
+    created_at: string;
+    updated_at: string;
+    user_id: string;
+    provider: string;
+    is_social: boolean;
+    login_count: number;
+    name?: string | undefined;
+    username?: string | undefined;
+    given_name?: string | undefined;
+    phone_number?: string | undefined;
+    phone_verified?: boolean | undefined;
+    family_name?: string | undefined;
+    profileData?: string | undefined;
+    address?: {
+        formatted?: string | undefined;
+        street_address?: string | undefined;
+        locality?: string | undefined;
+        region?: string | undefined;
+        postal_code?: string | undefined;
+        country?: string | undefined;
+    } | undefined;
+    nickname?: string | undefined;
+    picture?: string | undefined;
+    locale?: string | undefined;
+    linked_to?: string | undefined;
+    app_metadata?: any;
+    user_metadata?: any;
+    middle_name?: string | undefined;
+    preferred_username?: string | undefined;
+    profile?: string | undefined;
+    website?: string | undefined;
+    gender?: string | undefined;
+    birthdate?: string | undefined;
+    zoneinfo?: string | undefined;
+    verify_email?: boolean | undefined;
+    last_ip?: string | undefined;
+    last_login?: string | undefined;
+    registration_completed_at?: string | undefined;
+    email?: string | undefined;
+    identities?: {
+        connection: string;
+        user_id: string;
+        provider: string;
+        isSocial: boolean;
+        email?: string | undefined;
+        email_verified?: boolean | undefined;
+        phone_number?: string | undefined;
+        phone_verified?: boolean | undefined;
+        username?: string | undefined;
+        access_token?: string | undefined;
+        access_token_secret?: string | undefined;
+        refresh_token?: string | undefined;
+        profileData?: {
+            [x: string]: any;
+            email?: string | undefined;
+            email_verified?: boolean | undefined;
+            name?: string | undefined;
+            username?: string | undefined;
+            given_name?: string | undefined;
+            phone_number?: string | undefined;
+            phone_verified?: boolean | undefined;
+            family_name?: string | undefined;
+        } | undefined;
+    }[] | undefined;
+}>;

package/dist/types/hooks/user-update.d.ts

@@ -0,0 +1,16 @@
+import { Context } from "hono";
+import { DataAdapters, UserDataAdapter } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+/**
+ * Decorator applied by `addDataHooks` to `users.update`. Fires pre-update
+ * hooks, then commits the update inside its own `data.transaction(...)` so
+ * the write plus any follow-up email-based account linking are atomic.
+ *
+ * The single-field `linked_to` update fast-path at the top bypasses hooks to
+ * avoid recursion when `commitUserHook` or the account-linking template call
+ * back into `users.update`.
+ */
+export declare function createUserUpdateHooks(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters): UserDataAdapter["update"];

package/dist/types/hooks/validate-signup.d.ts

@@ -0,0 +1,34 @@
+import { Context } from "hono";
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+import { EnrichedClient } from "../helpers/client";
+/**
+ * Validates if an email can be used for signup based on client settings.
+ * This is a lightweight check that can be done early (e.g., on identifier page)
+ * without committing to creating a user.
+ *
+ * Supports code-based hooks via onExecuteValidateRegistrationUsername
+ *
+ * @returns An object with `allowed` boolean and optional `reason` string
+ */
+export declare function validateSignupEmail(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, data: DataAdapters, email: string, connection?: string, options?: {
+    identifierPreflight?: boolean;
+}): Promise<{
+    allowed: boolean;
+    reason?: string;
+}>;
+/**
+ * Pre-user signup hook that runs RIGHT BEFORE user creation.
+ * This runs for ALL signup methods (email/password, code, social, etc.)
+ * and enforces signup policies and invokes webhooks.
+ *
+ * This hook is called from createUserHooks and will throw an HTTPException
+ * if the signup should be blocked.
+ */
+export declare function preUserSignupHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, client: EnrichedClient, data: DataAdapters, email: string, connection?: string): Promise<void>;

package/dist/types/hooks/webhooks.d.ts

@@ -0,0 +1,35 @@
+import { DataAdapters, Hook, User } from "@authhero/adapter-interfaces";
+import { Context } from "hono";
+import { Variables, Bindings } from "../types";
+export declare function invokeHooks(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, hooks: Hook[], data: any & {
+    tenant_id: string;
+}): Promise<void>;
+export declare function postUserRegistrationWebhook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>): (tenant_id: string, user: User) => Promise<User>;
+export declare function preUserRegistrationWebhook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>): (tenant_id: string, email: string) => Promise<void>;
+export declare const preUserSignupWebhook: typeof preUserRegistrationWebhook;
+export declare function postUserLoginWebhook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters): (tenant_id: string, user: User) => Promise<User>;
+export declare function getValidateRegistrationUsernameWebhook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenant_id: string): Promise<Hook | null>;
+export declare const getValidateSignupEmailWebhook: typeof getValidateRegistrationUsernameWebhook;
+export declare function preUserDeletionWebhook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>): (tenant_id: string, user: User) => Promise<User>;
+export declare function postUserDeletionWebhook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>): (tenant_id: string, user: User) => Promise<User>;

package/dist/types/i18n/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * i18n with custom text override support
+ *
+ * Loads Auth0-format locale JSON files at build time and provides
+ * screen-scoped translation functions.
+ *
+ * Usage:
+ * ```typescript
+ * import { createTranslation } from '../i18n';
+ *
+ * const { m } = createTranslation('login-id', 'login-id', 'nb', customTextFromDb);
+ * m.title()  // "Velkommen" (or custom override if set)
+ * m.description({ companyName: 'Acme', clientName: 'App' })
+ * ```
+ */
+import type { CustomText } from "@authhero/adapter-interfaces";
+import type { ScreenMap } from "../generated/locale-types";
+export type { ScreenMap } from "../generated/locale-types";
+export type { Locale } from "../generated/locale-types";
+export type TranslationMap = Record<string, (variables?: Record<string, unknown>) => string>;
+export declare const locales: readonly ["cs", "da", "en", "fi", "it", "nb", "pl", "sv"];
+export declare const baseLocale: "en";
+/**
+ * Native display names for each supported locale. Used by the language picker
+ * in the universal-login chrome. Keys must stay in sync with `locales` above —
+ * adding a locale here without a JSON file (or vice versa) will leave the
+ * picker showing a raw code instead of a name.
+ */
+export declare const LOCALE_DISPLAY_NAMES: Record<(typeof locales)[number], string>;
+/**
+ * Resolve a locale code to its native display name, falling back to the
+ * raw code when the locale is not recognised.
+ */
+export declare function getLocaleDisplayName(lang: string): string;
+/**
+ * Create a screen-scoped translation object.
+ *
+ * Returns a typed object matching the generated ScreenMap when prompt/screen
+ * are known string literals, or a generic TranslationMap for dynamic keys.
+ *
+ * @param prompt - The prompt ID (e.g., 'login-id', 'signup')
+ * @param screen - The screen ID (e.g., 'login-id', 'signup')
+ * @param locale - The locale code (e.g., 'nb', 'en', 'sv')
+ * @param customText - Optional custom text overrides from database
+ */
+export declare function createTranslation<P extends string, S extends string>(prompt: P, screen: S, locale: string, customText?: CustomText): {
+    m: `${P}.${S}` extends keyof ScreenMap ? ScreenMap[`${P}.${S}`] : TranslationMap;
+    locale: (typeof locales)[number];
+};
+/**
+ * Check if a locale is supported.
+ */
+export declare function isLocaleSupported(locale: string): boolean;
+/**
+ * Get locale defaults for a specific prompt and language.
+ * Used by the management API prompts endpoint.
+ *
+ * Returns the nested screen → key → value structure for the given prompt,
+ * falling back to English if the requested language isn't available.
+ */
+export declare function getLocaleDefaults(prompt: string, language: string): Record<string, Record<string, string>>;
+export interface LocaleDefaultsEntry {
+    prompt: string;
+    language: string;
+    custom_text: Record<string, Record<string, string>>;
+}
+/**
+ * Enumerate every bundled locale default as a flat list of
+ * `{ prompt, language, custom_text }` entries, optionally filtered by
+ * language and/or prompt. Powers the `/api/v2/prompts/custom-text/defaults`
+ * endpoint so the admin UI can render placeholders and discover which
+ * forms exist without round-tripping per (prompt, language) pair.
+ */
+export declare function getAllLocaleDefaults(filter?: {
+    language?: string;
+    prompt?: string;
+}): LocaleDefaultsEntry[];