authhero 8.18.0 → 8.20.0

package/dist/types/authentication-flows/passwordless.d.ts

@@ -414,7 +414,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
                     } | undefined;
                 } | undefined;
                 passkey_options?: {
-                    challenge_ui?: "button" | "both" | "autofill" | undefined;
+                    challenge_ui?: "both" | "autofill" | "button" | undefined;
                     local_enrollment_enabled?: boolean | undefined;
                     progressive_enrollment_enabled?: boolean | undefined;
                 } | undefined;

package/dist/types/helpers/audit-target-types.d.ts

@@ -0,0 +1,6 @@
+/** Target entity types whose id identifies an affected user. For these, the
+ *  flat log's `user_id` is the target (the user the operation acted on) rather
+ *  than the actor — matching Auth0, e.g. "Delete a User" logs the deleted user.
+ *  Shared by `helpers/logging.ts` (write path) and
+ *  `outbox-destinations/logs.ts` (outbox transform) so the two never drift. */
+export declare const USER_TARGET_TYPES: Set<string>;

package/dist/types/helpers/default-destinations.d.ts

@@ -1,13 +1,15 @@
-import { DataAdapters } from "@authhero/adapter-interfaces";
+import { CodeExecutor, DataAdapters } from "@authhero/adapter-interfaces";
 import { EventDestination } from "./outbox-relay";
 import { type GetServiceToken } from "./outbox-destinations/webhooks";
 import type { WebhookInvoker } from "../types/AuthHeroConfig";
 export interface CreateDefaultDestinationsConfig {
     /**
-     * Data adapter — only the `logs`, `hooks`, `users`, and `logStreams`
-     * adapters are used by the built-in destinations.
+     * Data adapter — the `logs`, `hooks`, `users`, and `logStreams` adapters are
+     * used by the built-in destinations. When `codeExecutor` is set, the
+     * `actions`, `hookCode`, and `actionExecutions` adapters are also required so
+     * `CodeHookDestination` can resolve and run tenant code hooks.
      */
-    dataAdapter: Pick<DataAdapters, "logs" | "hooks" | "users" | "logStreams">;
+    dataAdapter: Pick<DataAdapters, "logs" | "hooks" | "users" | "logStreams"> & Partial<Pick<DataAdapters, "actions" | "hookCode" | "actionExecutions" | "multiTenancyConfig">>;
     /**
      * Produces a Bearer access token for the given tenant, used when POSTing
      * `hook.*` events to the configured webhook URLs.
@@ -37,6 +39,14 @@ export interface CreateDefaultDestinationsConfig {
      * deliveries don't diverge from inline per-request ones.
      */
     webhookInvoker?: WebhookInvoker;
+    /**
+     * Code executor — same instance passed to `init({ codeExecutor })`. When
+     * provided (and `dataAdapter` carries `actions`, `hookCode`, and
+     * `actionExecutions`), a `CodeHookDestination` is added so cron-drained
+     * `hook.*` events also run tenant code hooks. Without it, code hooks that
+     * failed per-request delivery would be silently skipped on retry.
+     */
+    codeExecutor?: CodeExecutor;
 }
 /**
  * Build the same array of outbox destinations that authhero's per-request

package/dist/types/helpers/hook-events.d.ts

@@ -1,20 +1,40 @@
 import { Context } from "hono";
-import { User } from "@authhero/adapter-interfaces";
+import { OutboxEventInsert, User } from "@authhero/adapter-interfaces";
 import { Bindings, Variables } from "../types";
+type HookCtx = Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>;
 /**
- * Enqueue a `hook.{triggerId}` event to the outbox so the `WebhookDestination`
- * (and future `CodeHookDestination`) can dispatch the hook asynchronously with
- * retries instead of firing inline while the request is being served.
- *
- * Mirrors the synchronous-push pattern used by `logMessage`: the promise from
- * `outbox.create` is pushed onto `ctx.var.outboxEventPromises` so the outbox
- * middleware can await it in its finally block and then relay the resulting
- * event IDs.
+ * Whether the outbox is configured for this request. When false, hook dispatch
+ * falls back to inline webhook invocation (no retry / dead-letter).
+ */
+export declare function outboxEnabled(ctx: HookCtx): boolean;
+/**
+ * Build a `hook.{triggerId}` outbox event with a caller-assigned id, or
+ * `undefined` when the outbox is not configured (the caller then falls back to
+ * inline dispatch via {@link dispatchPostHookInline}).
  *
- * When the outbox is not configured, falls back to inline webhook invocation
- * (via `waitUntil`) so tenants without outbox still receive webhook calls.
+ * The returned event is meant to be handed to an event-emitting user write
+ * (`rawCreate` / `remove`) via its `outboxEvents` option so it commits in the
+ * same atomic unit as the business row (issue #1057). Because the id is fixed
+ * up front, the caller can relay it with {@link relayOutboxEvent} once the
+ * write commits without needing a return value from the adapter.
  */
-export declare function enqueuePostHookEvent(ctx: Context<{
-    Bindings: Bindings;
-    Variables: Variables;
-}>, tenantId: string, triggerId: string, user: User): void;
+export declare function buildPostHookEvent(ctx: HookCtx, tenantId: string, triggerId: string, user: User): OutboxEventInsert | undefined;
+/**
+ * Relay an outbox event that has already been persisted (atomically with its
+ * business write) so the outbox middleware picks it up for delivery. Mirrors
+ * the synchronous-push pattern used by `logMessage`: the id is pushed onto
+ * `ctx.var.outboxEventPromises`, which the outbox middleware drains and hands
+ * to `processOutboxEvents`.
+ */
+export declare function relayOutboxEvent(ctx: HookCtx, id: string): void;
+/**
+ * Fallback dispatch for when the outbox is not configured: invoke the
+ * post-hook webhooks inline (fire-and-forget via `waitUntil`). No retry /
+ * dead-letter support in this mode — configure the outbox for durable
+ * delivery.
+ */
+export declare function dispatchPostHookInline(ctx: HookCtx, tenantId: string, triggerId: string, user: User): void;
+export {};

package/dist/types/helpers/outbox-destinations/code-hooks.d.ts

@@ -0,0 +1,56 @@
+import { AuditEvent, CodeExecutor } from "@authhero/adapter-interfaces";
+import { EventDestination } from "../outbox-relay";
+import { CodeHookData } from "../../hooks/codehooks";
+interface CodeHookInvocation {
+    eventId: string;
+    tenantId: string;
+    triggerId: string;
+    /** Serialized user snapshot from the audit event (`target.after`). */
+    user?: unknown;
+    /** Serialized request context from the audit event. */
+    request?: unknown;
+}
+/**
+ * Delivers `hook.*` outbox events to tenant-authored **code hooks** (actions)
+ * for the matching `trigger_id`. Runs alongside `WebhookDestination` — both
+ * accept the same `hook.*` events — so a single registration/deletion event
+ * fans out to webhooks *and* code hooks. The fan-out is not retried
+ * independently: the relay retries the whole outbox event, running its
+ * destinations in order and stopping at the first failure, so a code-hook
+ * failure here causes earlier destinations (e.g. webhooks) to run again on the
+ * retry. Every destination on the event must therefore be idempotent.
+ *
+ * Reliability model: unlike the previous inline execution (best-effort,
+ * at-most-once, failures logged and dropped), code hooks delivered here are
+ * **at-least-once**. If any code hook for the trigger fails, `deliver` throws
+ * so the relay retries the whole event with backoff and, after `maxRetries`,
+ * dead-letters it. A retry re-runs every code hook for the trigger, so the
+ * event id is passed to user code as `event.idempotency_key` for dedupe.
+ *
+ * Must be listed AFTER `WebhookDestination` and BEFORE
+ * `RegistrationFinalizerDestination` so `registration_completed_at` is only
+ * flipped on a pass where every webhook *and* code hook succeeded.
+ *
+ * Constructed per-request (via `getDestinations(ctx)`) so it can close over
+ * `ctx.env.codeExecutor`. The same class is used by the cron `drainOutbox`
+ * safety net when a `codeExecutor` is supplied to `createDefaultDestinations`.
+ * When no executor is configured, code hooks cannot run (nor be deployed), so
+ * `deliver` is a no-op success — matching the inline `handleCodeHook` which
+ * returns `null` without an executor.
+ */
+export declare class CodeHookDestination implements EventDestination {
+    name: string;
+    private data;
+    private codeExecutor?;
+    constructor(data: CodeHookData, codeExecutor?: CodeExecutor);
+    accepts(event: AuditEvent): boolean;
+    transform(event: AuditEvent): CodeHookInvocation;
+    deliver(invocations: CodeHookInvocation[]): Promise<void>;
+    /**
+     * Fetch every hook for the tenant, paging past the adapter's default page
+     * size. `hooks.list` returns only the first page by default, so a tenant with
+     * more enabled code hooks than one page would silently skip the rest.
+     */
+    private listAllHooks;
+}
+export {};

package/dist/types/helpers/password-connection.d.ts

@@ -0,0 +1,16 @@
+import type { EnrichedClient } from "./client";
+/**
+ * Resolve the tenant's database (username/password) connection for a client.
+ *
+ * The reset-password flows need the real connection name/id because a user's
+ * stored `user.connection` may be the hardcoded "Username-Password-Authentication"
+ * fallback rather than the tenant's actual connection. Centralised here so the
+ * HTML route and the screen handler resolve it identically.
+ *
+ * @param fallbackConnection connection name to use when the client has no
+ *   database connection (typically `user.connection`).
+ */
+export declare function resolvePasswordConnection(client: EnrichedClient, fallbackConnection: string): {
+    connection: string;
+    connectionId?: string;
+};

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

@@ -1,4 +1,4 @@
-import { DataAdapters } from "@authhero/adapter-interfaces";
+import { CodeExecutor, DataAdapters } from "@authhero/adapter-interfaces";
 import type { WebhookInvoker } from "../types/AuthHeroConfig";
 export interface RunOutboxRelayConfig {
     /** Same `DataAdapters` passed to `init()`. Must include `outbox` to drain. */
@@ -24,6 +24,13 @@ export interface RunOutboxRelayConfig {
     maxRetries?: number;
     /** Webhook HTTP timeout (ms), when the default invoker is used. */
     webhookTimeoutMs?: number;
+    /**
+     * Optional code executor — same instance passed to `init({ codeExecutor })`.
+     * When provided, cron-drained `hook.*` events also run tenant code hooks, so
+     * a code hook that failed per-request delivery is retried rather than
+     * silently skipped.
+     */
+    codeExecutor?: CodeExecutor;
 }
 /**
  * One-call outbox relay for cron / scheduled handlers.

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

@@ -1,22 +1,62 @@
 import { Context } from "hono";
-import { ActionExecutionResult, CodeExecutionLog, DataAdapters, Hook } from "@authhero/adapter-interfaces";
+import { ActionExecutionResult, CodeExecutionLog, CodeExecutor, DataAdapters, Hook } from "@authhero/adapter-interfaces";
 import { Bindings, Variables } from "../types";
 import { HookEvent, OnExecuteCredentialsExchangeAPI } from "../types/Hooks";
+import { EnrichedClient } from "../helpers/client";
 /**
  * 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;
+/**
+ * The subset of `DataAdapters` needed to resolve and run a code hook and to
+ * persist its execution record. Narrowed so `CodeHookDestination` and the cron
+ * `createDefaultDestinations` helper can construct it without depending on the
+ * full adapter surface.
+ */
+export type CodeHookData = Pick<DataAdapters, "hooks" | "actions" | "hookCode" | "actionExecutions" | "multiTenancyConfig">;
 type CodeHook = Extract<Hook, {
     code_id: string;
 }>;
 export declare function isCodeHook(hook: Hook): hook is CodeHook;
+/**
+ * Loosened event shape accepted by `buildSerializableEvent` / `executeCodeHook`.
+ *
+ * The inline hook call sites pass a full `HookEvent`. The `CodeHookDestination`
+ * (which runs from the outbox relay, after the request has closed) has no live
+ * `ctx` and reconstructs the event from the persisted audit event, so `user`
+ * and `request` arrive as already-serialized `unknown` values. Both are
+ * assignable to this type.
+ */
+export type CodeHookEventInput = {
+    ctx?: unknown;
+    client?: Pick<EnrichedClient, "client_id" | "name" | "client_metadata"> | null;
+} & Record<string, unknown>;
 /**
  * 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>;
+export declare function buildSerializableEvent(event: CodeHookEventInput, secrets?: Record<string, string>): Record<string, unknown>;
+/**
+ * The namespaced API surface exposed to code hooks. User code records calls of
+ * the form `<namespace>.<method>(...)` (e.g. `accessToken.setCustomClaim`,
+ * `access.deny`), which {@link replayApiCalls} replays against the real
+ * namespace objects. Each top-level key is a namespace whose members are the
+ * callable methods for that namespace — so the shape is nested (namespace →
+ * method → function) rather than a flat `any` surface. Concrete per-trigger API
+ * types (`OnExecute*API`) structurally satisfy this.
+ *
+ * The method args stay permissive (`any[]`): this surface is a dynamic
+ * dispatcher — {@link replayApiCalls} looks methods up by string and applies
+ * the recorded `unknown[]` args, while call sites register concretely-typed
+ * methods (`(key: string, value: unknown) => void`, …). A stricter `unknown[]`
+ * args tuple would reject those concrete registrations (parameter
+ * contravariance). The return type is still narrowed to `unknown`.
+ */
+export type CodeHookApiMethod = (...args: any[]) => unknown;
+export type CodeHookApiNamespace = Record<string, CodeHookApiMethod>;
+export type CodeHookApi = Record<string, CodeHookApiNamespace>;
 /**
  * Replay recorded API calls from code hook execution against real API objects.
  * Handles calls like "accessToken.setCustomClaim" by navigating the api object.
@@ -24,22 +64,51 @@ export declare function buildSerializableEvent(event: HookEvent, secrets?: Recor
 export declare function replayApiCalls(apiCalls: Array<{
     method: string;
     args: unknown[];
-}>, api: Record<string, any>): void;
+}>, api: CodeHookApi): void;
 export type HandleCodeHookOutcome = {
     result: ActionExecutionResult;
     logs: CodeExecutionLog[];
     /** True if api.access.deny was recorded by the executor. */
     denied: boolean;
 };
+/**
+ * Core code-hook execution, decoupled from the Hono request `ctx`.
+ *
+ * Given an explicit executor, data adapter, and tenant, fetches the code,
+ * runs it, and replays the recorded API calls against `api`. Shared by the
+ * inline `handleCodeHook` wrapper (request-time) and by `CodeHookDestination`
+ * (outbox relay, after the request has closed).
+ *
+ * Always returns an outcome — including a `code_not_found` / `execution_failed`
+ * outcome — so the caller can persist an `action_executions` record. It only
+ * throws for `api.access.deny`, which surfaces as a thrown `HTTPException` from
+ * the replayed API call; callers that must abort the flow catch it.
+ *
+ * `idempotencyKey`, when set, is exposed to user code as `event.idempotency_key`.
+ * The outbox is at-least-once, so a retried hook event re-runs the code; authors
+ * performing non-idempotent side effects can dedupe on this key.
+ */
+export declare function executeCodeHook(params: {
+    codeExecutor: CodeExecutor;
+    data: CodeHookData;
+    tenantId: string;
+    hook: {
+        code_id: string;
+        hook_id?: string;
+    };
+    event: CodeHookEventInput;
+    triggerId: string;
+    api: CodeHookApi;
+    idempotencyKey?: string;
+}): Promise<HandleCodeHookOutcome>;
 /**
  * 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.
+ * Thin request-time wrapper over `executeCodeHook` that resolves the executor
+ * and tenant from `ctx`. Returns `null` when the code executor is unavailable
+ * or the tenant can't be resolved — the caller decides whether to surface that.
  */
 export declare function handleCodeHook(ctx: Context<{
     Bindings: Bindings;
@@ -47,13 +116,13 @@ export declare function handleCodeHook(ctx: Context<{
 }>, data: DataAdapters, hook: {
     code_id: string;
     hook_id: string;
-}, event: HookEvent, triggerId: string, api: Record<string, any>): Promise<HandleCodeHookOutcome | null>;
+}, event: HookEvent, triggerId: string, api: CodeHookApi): 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>;
+export declare function persistActionExecution(data: Pick<DataAdapters, "actionExecutions">, 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.

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

@@ -1,4 +1,4 @@
-import { DataAdapters, User } from "@authhero/adapter-interfaces";
+import { DataAdapters, OutboxEventInsert, User } from "@authhero/adapter-interfaces";
 export interface CommitUserResult {
     user: User;
     created: boolean;
@@ -16,6 +16,14 @@ export interface CommitUserOptions {
      * goes away entirely).
      */
     resolveEmailLinkedPrimary?: boolean;
+    /**
+     * Post-registration outbox events to persist in the same atomic unit as the
+     * user row (issue #1057). Forwarded to `rawCreate`'s `outboxEvents` option so
+     * the event and the user commit together — a race-loser whose `rawCreate`
+     * rolls back never leaves a stranded event. The caller relays the event ids
+     * (via `relayOutboxEvent`) only after `created === true`.
+     */
+    outboxEvents?: OutboxEventInsert[];
 }
 /**
  * Commits a new user inside a transaction. Validates `linked_to` (if set),

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

@@ -8,11 +8,14 @@ import { Bindings, Variables } from "../types";
  *  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
+ *     writes the user row (via `rawCreate`), the post-registration outbox
+ *     event (via `rawCreate`'s `outboxEvents` option, so business row and
+ *     event commit together — issue #1057), and, when the built-in
+ *     email-based linking path is enabled, resolves `linked_to` from the
+ *     existing primary inside the same transaction.
+ *  3. Post-registration hooks — the already-persisted event id is relayed
+ *     (`relayOutboxEvent`) for retryable / idempotent webhook dispatch, or
+ *     `dispatchPostHookInline` runs when the outbox isn't configured; code
  *     hooks currently still run inline with ctx.
  */
 export declare function createUserHooks(ctx: Context<{