authhero 5.8.0 → 5.9.0

package/dist/types/helpers/run-outbox-relay.d.ts

@@ -0,0 +1,58 @@
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import type { WebhookInvoker } from "../types/AuthHeroConfig";
+export interface RunOutboxRelayConfig {
+    /** Same `DataAdapters` passed to `init()`. Must include `outbox` to drain. */
+    dataAdapter: DataAdapters;
+    /**
+     * Issuer URL used when minting per-tenant `auth-service` tokens (typically
+     * your `env.ISSUER`). Webhook handlers that validate `iss` against this
+     * URL will accept tokens from both the inline dispatcher and this cron
+     * relay.
+     */
+    issuer: string;
+    /**
+     * Optional webhook invoker — same shape as the one accepted by `init()`.
+     * When provided, cron-drained `hook.*` events go through this invoker,
+     * matching the inline per-request dispatch path exactly.
+     */
+    webhookInvoker?: WebhookInvoker;
+    /** Days to retain processed events before cleanup. Default 7. */
+    retentionDays?: number;
+    /** Forwarded to `drainOutbox`. */
+    batchSize?: number;
+    /** Forwarded to `drainOutbox`. */
+    maxRetries?: number;
+    /** Webhook HTTP timeout (ms), when the default invoker is used. */
+    webhookTimeoutMs?: number;
+}
+/**
+ * One-call outbox relay for cron / scheduled handlers.
+ *
+ * Internally:
+ * 1. Skips gracefully when `dataAdapter.outbox` is undefined.
+ * 2. Builds the same destination array as the inline dispatcher
+ *    (`LogsDestination`, `WebhookDestination`, `RegistrationFinalizerDestination`).
+ * 3. Mints per-tenant service tokens via the same in-process path
+ *    (`createServiceTokenCore`) that the request-time webhookInvoker uses,
+ *    driven by the supplied dataAdapter.
+ * 4. Runs `drainOutbox`, then `cleanupOutbox`.
+ *
+ * This is intended to be the entire body of a consumer's scheduled handler
+ * for outbox maintenance — consumers should not need to call `drainOutbox` /
+ * `cleanupOutbox` / `createDefaultDestinations` directly.
+ *
+ * @example
+ * ```ts
+ * export default {
+ *   async scheduled(_event, env) {
+ *     await runOutboxRelay({
+ *       dataAdapter,
+ *       issuer: env.ISSUER,
+ *       webhookInvoker,   // same function passed to init()
+ *       retentionDays: 7,
+ *     });
+ *   },
+ * };
+ * ```
+ */
+export declare function runOutboxRelay(config: RunOutboxRelayConfig): Promise<void>;

package/dist/types/helpers/saml.d.ts

@@ -0,0 +1 @@
+export * from "@authhero/saml";

package/dist/types/helpers/scope-claims.d.ts

@@ -0,0 +1,4 @@
+import type { User } from "@authhero/adapter-interfaces";
+export declare function getStandardClaim(user: User, claim: string): unknown | undefined;
+export declare function buildScopeClaims(user: User, scopes: string[]): Record<string, unknown>;
+export declare function buildRequestedClaims(user: User, claimNames: Iterable<string>): Record<string, unknown>;

package/dist/types/helpers/scopes-permissions.d.ts

@@ -0,0 +1,38 @@
+import { Context } from "hono";
+import { GrantType } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+interface BaseScopesAndPermissionsParams {
+    tenantId: string;
+    clientId: string;
+    audience: string;
+    requestedScopes: string[];
+    organizationId?: string;
+}
+interface ClientCredentialsScopesAndPermissionsParams extends BaseScopesAndPermissionsParams {
+    grantType: GrantType.ClientCredential;
+    userId?: never;
+}
+interface UserBasedScopesAndPermissionsParams extends BaseScopesAndPermissionsParams {
+    grantType?: GrantType.AuthorizationCode | GrantType.RefreshToken | GrantType.Password | GrantType.Passwordless | GrantType.OTP | undefined;
+    userId: string;
+}
+export type CalculateScopesAndPermissionsParams = ClientCredentialsScopesAndPermissionsParams | UserBasedScopesAndPermissionsParams;
+export interface ScopesAndPermissionsResult {
+    scopes: string[];
+    permissions: string[];
+    token_lifetime: number;
+    token_lifetime_for_web: number;
+}
+/**
+ * Calculates the scopes and permissions for a user based on the audience and resource server configuration.
+ * This function implements Auth0-like behavior for RBAC and token dialects.
+ *
+ * @param ctx - The Hono context
+ * @param params - Parameters containing tenant ID, user ID, audience, and requested scopes
+ * @returns Object containing calculated scopes and permissions
+ */
+export declare function calculateScopesAndPermissions(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: CalculateScopesAndPermissionsParams): Promise<ScopesAndPermissionsResult>;
+export {};

package/dist/types/helpers/server-timing.d.ts

@@ -0,0 +1,12 @@
+import { Context } from "hono";
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+/**
+ * Adds server-timing middleware logging to all adapter methods
+ * This wraps each method of the data adapter to measure its execution time
+ * and adds it to the server-timing header
+ */
+export declare function addTimingLogs(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters): DataAdapters;

package/dist/types/helpers/service-token.d.ts

@@ -0,0 +1,54 @@
+import { Context } from "hono";
+import { KeysAdapter, TenantsDataAdapter } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+import { SigningKeyModeOption } from "../types/AuthHeroConfig";
+declare const AUTH_SERVICE_CLIENT_ID = "auth-service";
+export interface ServiceTokenResponse {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+}
+export interface CreateServiceTokenCoreParams {
+    tenants: TenantsDataAdapter;
+    keys: KeysAdapter;
+    tenantId: string;
+    scope: string;
+    issuer: string;
+    expiresInSeconds?: number;
+    customClaims?: Record<string, unknown>;
+    /**
+     * Optional per-tenant signing-key bucket selector. When unset the
+     * tenant uses the shared control-plane keys (legacy behavior) which
+     * keeps existing outbox/cron callers working without any change.
+     */
+    signingKeyMode?: SigningKeyModeOption;
+}
+/**
+ * Ctx-free service token minter. Produces a signed JWT for the `auth-service`
+ * client using the tenant's current JWT signing key. Intended to be shared
+ * between the request-time outbox dispatcher and the cron `runOutboxRelay`
+ * helper so both paths emit tokens with identical issuer, subject, tenant
+ * binding, and signing key.
+ */
+export declare function createServiceTokenCore(params: CreateServiceTokenCoreParams): Promise<ServiceTokenResponse>;
+export declare function createServiceToken(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenant_id: string, scope: string, expiresInSeconds?: number, customClaims?: Record<string, unknown>): Promise<{
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+}>;
+/**
+ * Bound ctx-free token factory for outbox destinations. Mirrors the shape
+ * expected by `WebhookDestination` and `createDefaultDestinations` but uses
+ * `createServiceTokenCore` under the hood so the inline per-request outbox
+ * dispatcher and the cron `runOutboxRelay` emit identical tokens.
+ */
+export declare function makeOutboxServiceTokenFactory(deps: {
+    tenants: TenantsDataAdapter;
+    keys: KeysAdapter;
+    issuer: string;
+    signingKeyMode?: SigningKeyModeOption;
+}): (tenantId: string, scope?: string) => Promise<string>;
+export { AUTH_SERVICE_CLIENT_ID };

package/dist/types/helpers/set-tenant-id.d.ts

@@ -0,0 +1,15 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+/**
+ * Sets the tenant_id in context if not already set.
+ * If tenant_id is already set, validates it matches the expected tenant.
+ * Throws if there's a mismatch to prevent cross-tenant attacks.
+ *
+ * @param ctx - Hono context
+ * @param tenantId - The expected tenant ID (e.g., from a client lookup)
+ * @throws HTTPException if tenant_id is already set and doesn't match
+ */
+export declare function setTenantId(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenantId: string): void;

package/dist/types/helpers/signing-keys.d.ts

@@ -0,0 +1,16 @@
+import { SigningKey, KeysAdapter } from "@authhero/adapter-interfaces";
+import { SigningKeyMode, SigningKeyModeOption } from "../types/AuthHeroConfig";
+export declare function resolveSigningKeyMode(option: SigningKeyModeOption | undefined, tenantId: string): Promise<SigningKeyMode>;
+export interface ResolveSigningKeysOptions {
+    /**
+     * `"sign"` returns at most one key — the tenant's newest non-revoked key
+     * if available, else the control-plane fallback. `"publish"` returns the
+     * full set used for JWKS: control-plane only when mode is
+     * `"control-plane"`, tenant ∪ control-plane when mode is `"tenant"` so
+     * tokens signed by either bucket still verify during rotation.
+     */
+    purpose: "sign" | "publish";
+    /** Defaults to `"jwt_signing"`. Pass `"saml_encryption"` for SAML keys. */
+    type?: string;
+}
+export declare function resolveSigningKeys(keys: KeysAdapter, tenantId: string, modeOption: SigningKeyModeOption | undefined, opts: ResolveSigningKeysOptions): Promise<SigningKey[]>;

package/dist/types/helpers/try-connection-client.d.ts

@@ -0,0 +1,15 @@
+import { Bindings } from "../types";
+export declare function getTryConnectionResultPath(): string;
+export declare function getTryConnectionResultUrl(env: Bindings, customDomain?: string): string;
+/**
+ * Idempotently ensure the per-tenant "Try Connection" client exists.
+ *
+ * The client has no explicit connection enablement — `getEnrichedClient`'s
+ * fallback then exposes every tenant connection on it, so the same client
+ * can drive a test for any connection without re-provisioning.
+ *
+ * Its only registered callback is the universal-login result page; the
+ * /authorize handler additionally allows the issuer + universal-login
+ * wildcards which already cover that URL.
+ */
+export declare function ensureTryConnectionClient(env: Bindings, tenantId: string): Promise<string>;

package/dist/types/helpers/user-linking.d.ts

@@ -0,0 +1,14 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+/**
+ * Returns true when the built-in email-based linking path should run.
+ *
+ * The built-in path performs the legacy `getPrimaryUserByEmail` lookup at
+ * user creation and email update. With `userLinkingMode: "off"` it is
+ * skipped entirely and linking only happens via the `account-linking`
+ * template hook.
+ */
+export declare function builtInUserLinkingEnabled(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenant_id: string, client_id?: string): Promise<boolean>;

package/dist/types/helpers/user-session-cleanup.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "hono";
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+export interface UserSessionCleanupParams {
+    tenantId?: string;
+    userId?: string;
+}
+/**
+ * Context-free session cleanup for use in scheduled handlers / cron jobs.
+ * Deletes expired login_sessions, sessions, and refresh_tokens, optionally
+ * scoped to a tenant and/or user.
+ */
+export declare function cleanupSessions(data: DataAdapters, params?: UserSessionCleanupParams): Promise<void>;
+/**
+ * Per-request wrapper around cleanupSessions. Designed to be called with
+ * waitUntil after creating a new login session.
+ */
+export declare function cleanupUserSessions(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: UserSessionCleanupParams): Promise<void>;

package/dist/types/helpers/users.d.ts

@@ -0,0 +1,46 @@
+import { User, UserDataAdapter } from "@authhero/adapter-interfaces";
+import { EnrichedClient } from "./client";
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+export declare function getUsersByEmail(userAdapter: UserDataAdapter, tenantId: string, email: string): Promise<User[]>;
+interface GetUserByProviderParams {
+    userAdapter: UserDataAdapter;
+    tenant_id: string;
+    username: string;
+    provider: string;
+}
+export declare function getUserByProvider({ userAdapter, tenant_id, username, provider, }: GetUserByProviderParams): Promise<User | null>;
+interface GetPrimaryUserByEmailParams {
+    userAdapter: UserDataAdapter;
+    tenant_id: string;
+    email: string;
+}
+export declare function getPrimaryUserByEmail({ userAdapter, tenant_id, email, }: GetPrimaryUserByEmailParams): Promise<User | undefined>;
+interface GetPrimaryUserByProviderParams {
+    userAdapter: UserDataAdapter;
+    tenant_id: string;
+    username: string;
+    provider: string;
+}
+export declare function getPrimaryUserByProvider({ userAdapter, tenant_id, username, provider, }: GetPrimaryUserByProviderParams): Promise<User | null>;
+interface GetOrCreateUserByProviderParams {
+    client: EnrichedClient;
+    username: string;
+    provider: string;
+    connection: string;
+    userId?: string;
+    profileData?: Record<string, unknown>;
+    ip?: string;
+    isSocial: boolean;
+    set_user_root_attributes?: "on_each_login" | "on_first_login" | "never_on_login";
+}
+/**
+ * This function will either fetch an existing user for a provider or create it
+ * @param param0
+ * @returns
+ */
+export declare function getOrCreateUserByProvider(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, params: GetOrCreateUserByProviderParams): Promise<User>;
+export {};

package/dist/types/helpers/wait-until.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "hono";
+/**
+ * Register a background promise tied to the current request.
+ *
+ * On Cloudflare Workers (`workerd`), this uses `executionCtx.waitUntil`, which
+ * holds the worker alive until the promise settles but does not block the
+ * response.
+ *
+ * On Node/Bun and in tests we instead collect the promise on the context so a
+ * surrounding middleware can await it before the response leaves. Without this
+ * the response can return before background work (audit log writes, outbox
+ * webhook dispatches) completes, producing flaky test behavior and requests
+ * that occasionally lose tail work if the process exits.
+ */
+export declare function waitUntil(ctx: Context, promise: Promise<unknown>): void;
+/**
+ * Await any `waitUntil` promises registered during the current request. Invoke
+ * from a middleware's finally block (after `await next()`) so non-Workers
+ * runtimes flush background work before returning the response.
+ */
+export declare function flushBackgroundPromises(ctx: Context): Promise<void>;

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

@@ -0,0 +1,16 @@
+import { Context } from "hono";
+import { DataAdapters } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+/**
+ * Wrap a raw `DataAdapters` with lifecycle hooks for user CRUD operations.
+ *
+ * Read methods and non-user entities pass through untouched. `users.create`,
+ * `users.update`, and `users.remove` are replaced with decorated versions
+ * that run pre/post hooks, apply the narrow transactional commits, and
+ * dispatch post-event outbox messages. `users.rawCreate` is NOT decorated —
+ * commit paths call it directly to bypass the hook layer by design.
+ */
+export declare function addDataHooks(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters): DataAdapters;

package/dist/types/hooks/code-executor/local.d.ts

@@ -0,0 +1,13 @@
+import { CodeExecutionResult, CodeExecutor } from "@authhero/adapter-interfaces";
+/**
+ * Local code executor using `new Function()`.
+ * Suitable for local development only — no isolation or sandboxing.
+ */
+export declare class LocalCodeExecutor implements CodeExecutor {
+    execute(params: {
+        code: string;
+        triggerId: string;
+        event: Record<string, unknown>;
+        timeoutMs?: number;
+    }): Promise<CodeExecutionResult>;
+}

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

@@ -0,0 +1,70 @@
+import { Context } from "hono";
+import { ActionExecutionResult, CodeExecutionLog, DataAdapters, Hook } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+import { HookEvent, OnExecuteCredentialsExchangeAPI } from "../types/Hooks";
+/**
+ * Auth0 uses `post-login` for what we internally call `post-user-login`.
+ * Normalize when writing execution records so the public API matches Auth0.
+ */
+export declare function toAuth0TriggerId(internal: string): string;
+type CodeHook = Extract<Hook, {
+    code_id: string;
+}>;
+export declare function isCodeHook(hook: Hook): hook is CodeHook;
+/**
+ * Build a serializable event object from a HookEvent.
+ * Strips the `ctx` property (Hono context) which cannot be serialized,
+ * and returns a plain JSON-compatible object.
+ */
+export declare function buildSerializableEvent(event: HookEvent, secrets?: Record<string, string>): Record<string, unknown>;
+/**
+ * Replay recorded API calls from code hook execution against real API objects.
+ * Handles calls like "accessToken.setCustomClaim" by navigating the api object.
+ */
+export declare function replayApiCalls(apiCalls: Array<{
+    method: string;
+    args: unknown[];
+}>, api: Record<string, any>): void;
+export type HandleCodeHookOutcome = {
+    result: ActionExecutionResult;
+    logs: CodeExecutionLog[];
+    /** True if api.access.deny was recorded by the executor. */
+    denied: boolean;
+};
+/**
+ * Execute a code hook by fetching the code from the database, running it
+ * through the code executor, and replaying API calls against the real api
+ * object.
+ *
+ * Returns the per-action result (Auth0 shape) so the caller can aggregate
+ * results across all actions on a trigger into a single `action_executions`
+ * record. Returns `null` when the code cannot be located or the executor is
+ * unavailable — the caller decides whether to surface that.
+ */
+export declare function handleCodeHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters, hook: {
+    code_id: string;
+    hook_id: string;
+}, event: HookEvent, triggerId: string, api: Record<string, any>): Promise<HandleCodeHookOutcome | null>;
+/**
+ * Aggregate per-action outcomes into an Auth0-shape execution record and
+ * persist it via the adapter. Returns the generated execution_id (uuid)
+ * so the caller can embed it in the surrounding tenant log.
+ */
+export declare function persistActionExecution(data: DataAdapters, tenant_id: string, triggerId: string, outcomes: HandleCodeHookOutcome[]): Promise<string | null>;
+/**
+ * Execute code hooks for the credentials-exchange trigger.
+ * Filters enabled code hooks from the provided hooks list and executes them.
+ *
+ * Returns the persisted `execution_id` so the caller can embed it in the
+ * surrounding tenant log (the standard token-exchange log entry). The
+ * execution record itself follows Auth0's shape — see
+ * GET /api/v2/actions/executions/:id.
+ */
+export declare function handleCredentialsExchangeCodeHooks(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, hooks: any[], event: HookEvent, api: OnExecuteCredentialsExchangeAPI): Promise<string | null>;
+export {};

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

@@ -0,0 +1,99 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+import { FORM_FIELD_TYPES, LoginSession, Node, User } from "@authhero/adapter-interfaces";
+import { EnrichedClient } from "../helpers/client";
+export { FORM_FIELD_TYPES };
+export declare function isFormHook(hook: any): hook is {
+    form_id: string;
+    enabled: boolean;
+};
+/**
+ * Resolves a template string like "{{context.user.email}}", "{{user.id}}", or "{{$form.gender}}" to its actual value
+ */
+export declare function resolveTemplateField(field: string, context: ResolveContext): string | undefined;
+/**
+ * Context passed to resolveNode and condition evaluation
+ */
+export interface ResolveContext {
+    user: User;
+    submittedFields?: Record<string, string>;
+}
+/**
+ * Flow action type used during resolution
+ */
+interface FlowAction {
+    type: string;
+    action?: string;
+    params?: {
+        target?: "change-email" | "account" | "custom";
+        custom_url?: string;
+        user_id?: string;
+        connection_id?: string;
+        changes?: Record<string, unknown>;
+    };
+}
+/**
+ * Flow fetcher function type for async flow resolution
+ */
+export type FlowFetcher = (flowId: string) => Promise<{
+    actions?: FlowAction[];
+} | null>;
+/**
+ * Pending user update action to be executed by the caller
+ */
+export interface PendingUserUpdate {
+    user_id: string;
+    changes: Record<string, string>;
+}
+/**
+ * Builds userUpdates object from a PendingUserUpdate's changes map.
+ * Handles dot-notation key prefixes:
+ *  - "metadata.X" → user_metadata.X
+ *  - "address.X"  → address.X  (nested OIDC address claim)
+ *  - anything else → top-level user field
+ */
+export declare function buildUserUpdates(changes: Record<string, string>, existingUser: {
+    user_metadata?: unknown;
+    address?: unknown;
+}): Record<string, unknown>;
+/**
+ * Merge multiple PendingUserUpdate entries by user_id so that overlapping
+ * changes (e.g. two updates both touching metadata.*) are accumulated into
+ * a single changes map per user.  This avoids the stale-snapshot problem
+ * where each call to buildUserUpdates would spread the *original* user
+ * object, causing later writes to overwrite earlier ones.
+ */
+export declare function mergeUserUpdates(updates: PendingUserUpdate[]): PendingUserUpdate[];
+/**
+ * Result type for node resolution
+ */
+type ResolveNodeResult = {
+    type: "step";
+    nodeId: string;
+    userUpdates?: PendingUserUpdate[];
+} | {
+    type: "redirect";
+    target: string;
+    customUrl?: string;
+    userUpdates?: PendingUserUpdate[];
+} | {
+    type: "end";
+    userUpdates?: PendingUserUpdate[];
+} | null;
+/**
+ * Resolves the target redirect URL based on the target type
+ */
+export declare function getRedirectUrl(target: "change-email" | "account" | "custom", customUrl: string | undefined, state: string): string;
+/**
+ * Resolves the first displayable node by following ROUTER, ACTION, and FLOW nodes
+ */
+export declare function resolveNode(nodes: Node[], startNodeId: string, context: ResolveContext, flowFetcher?: FlowFetcher, maxDepth?: number): Promise<ResolveNodeResult>;
+/**
+ * Handles a form hook: validates the form exists and returns a redirect Response to the first node.
+ * If the form resolves to 'end' or no step node is found, returns the user to continue normal auth flow.
+ * Throws if the form or start node is missing.
+ */
+export declare function handleFormHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, form_id: string, loginSession: LoginSession, user?: User, client?: EnrichedClient): Promise<User | Response>;

package/dist/types/hooks/helpers/token-api.d.ts

@@ -0,0 +1,17 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../../types";
+/**
+ * Build the `token` API surface that user-authored hook code receives. A thin
+ * wrapper over `createServiceToken` that hides the underlying context so the
+ * hook runtime cannot mint tokens for arbitrary tenants.
+ */
+export declare function createTokenAPI(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenant_id: string): {
+    createServiceToken: (params: {
+        scope: string;
+        expiresInSeconds?: number;
+        customClaims?: Record<string, unknown>;
+    }) => Promise<string>;
+};

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

@@ -0,0 +1,20 @@
+/**
+ * Public surface of the hooks subsystem. Implementation lives in sibling
+ * files split by trigger:
+ *   - user-registration.ts  — createUserHooks (decorator applied to users.create)
+ *   - user-update.ts        — createUserUpdateHooks (decorator applied to users.update)
+ *   - user-deletion.ts      — createUserDeletionHooks (decorator applied to users.remove)
+ *   - validate-signup.ts    — validateSignupEmail + preUserSignupHook
+ *   - post-user-login.ts    — postUserLoginHook (+ Auth0-compat event builder)
+ *   - addDataHooks.ts       — the decorator assembler wrapped around a DataAdapters
+ *   - helpers/token-api.ts  — createTokenAPI, shared by every trigger
+ *
+ * Internal implementation helpers (`createUserHooks`, `createUserUpdateHooks`,
+ * `createUserDeletionHooks`) are intentionally NOT re-exported — callers go
+ * through `addDataHooks`.
+ */
+export { addDataHooks } from "./addDataHooks";
+export { validateSignupEmail, preUserSignupHook } from "./validate-signup";
+export { postUserLoginHook } from "./post-user-login";
+export { validateSignupEmail as validateRegistrationUsername } from "./validate-signup";
+export { preUserSignupHook as preUserRegistrationHook } from "./validate-signup";

package/dist/types/hooks/link-users.d.ts

@@ -0,0 +1,29 @@
+import { DataAdapters, User } from "@authhero/adapter-interfaces";
+export interface CommitUserResult {
+    user: User;
+    created: boolean;
+}
+export interface CommitUserOptions {
+    /**
+     * When true, attempt the legacy email-based primary lookup inside the
+     * commit transaction. When the user has a verified email and no
+     * `linked_to` is already set (e.g. by a pre-user-registration hook), the
+     * commit will automatically point `linked_to` at the existing primary
+     * user with the same email.
+     *
+     * Disable this to make linking opt-in via the `account-linking` template
+     * hook (the current direction of travel — long-term the legacy lookup
+     * goes away entirely).
+     */
+    resolveEmailLinkedPrimary?: boolean;
+}
+/**
+ * Commits a new user inside a transaction. Validates `linked_to` (if set),
+ * runs `rawCreate`, and recovers from concurrent-create races.
+ *
+ * Optionally performs the legacy email→primary auto-link lookup inside the
+ * same transaction (see {@link CommitUserOptions.resolveEmailLinkedPrimary}).
+ * Whether it runs is decided by the caller via
+ * `builtInUserLinkingEnabled(ctx, tenant_id, client_id)`.
+ */
+export declare function commitUserHook(data: DataAdapters): (tenant_id: string, user: User, options?: CommitUserOptions) => Promise<CommitUserResult>;

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

@@ -0,0 +1,16 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+import { LoginSession, User } from "@authhero/adapter-interfaces";
+export declare function isPageHook(hook: any): hook is {
+    page_id: string;
+    enabled: boolean;
+    permission_required?: string;
+};
+/**
+ * Handles a page hook: checks if user has required permission and returns a redirect Response to the page.
+ * If user doesn't have the required permission, returns the user without redirect.
+ */
+export declare function handlePageHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, page_id: string, loginSession: LoginSession, user: User, permission_required?: string): Promise<User | Response>;

package/dist/types/hooks/post-user-login.d.ts

@@ -0,0 +1,29 @@
+import { Context } from "hono";
+import { DataAdapters, LoginSession, User } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../types";
+import { EnrichedClient } from "../helpers/client";
+/**
+ * Checks for post-user-login hooks (form, page, template, code, or webhook)
+ * and handles them in that order. Also:
+ *  - logs the successful login,
+ *  - increments the user's `login_count`.
+ *
+ * Delivery reliability for `post-user-registration` is the outbox's concern
+ * (retry + dead-letter), not the login path's. Recovery of dead-lettered
+ * events is a separate admin/cron responsibility so a user's first login
+ * can't double-enqueue while the original event is still pending.
+ *
+ * Returns either the (possibly updated) user or a `Response` when a hook
+ * redirects, takes over the login, or renders a form.
+ */
+export declare function postUserLoginHook(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, data: DataAdapters, tenant_id: string, user: User, loginSession?: LoginSession, params?: {
+    client?: EnrichedClient;
+    authParams?: any;
+    authStrategy?: {
+        strategy: string;
+        strategy_type: string;
+    };
+}): Promise<User | Response>;