authhero 8.27.0 → 9.1.0

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

@@ -15,3 +15,39 @@ export interface ResolveSigningKeysOptions {
     type?: string;
 }
 export declare function resolveSigningKeys(keys: KeysAdapter, tenantId: string, modeOption: SigningKeyModeOption | undefined, opts: ResolveSigningKeysOptions): Promise<SigningKey[]>;
+/** A key is signable only if it carries private material, not just a cert. */
+export declare function isSignable(key: SigningKey): boolean;
+export interface EnsureSigningKeyOptions {
+    /**
+     * When set, the key is created tenant-scoped (`tenant_id` stamped) and the
+     * existence check is scoped to that tenant. Omit for a control-plane key
+     * (no `tenant_id`), which `resolveSigningKeys` resolves in both modes — as
+     * the primary key in `"control-plane"` mode and as the fallback in
+     * `"tenant"` mode. Control-plane scope is the right default for a freshly
+     * provisioned WFP tenant.
+     */
+    tenantId?: string;
+    /** Cert CN. Falls back to the tenant id, then to `"authhero"`. */
+    name?: string;
+    /** Defaults to `"jwt_signing"`. */
+    type?: SigningKey["type"];
+}
+export interface EnsureSigningKeyResult {
+    /** True when a new key was minted; false when a signable key already existed. */
+    created: boolean;
+    key: SigningKey;
+}
+/**
+ * Guarantees the target scope holds at least one *signable* key — one carrying
+ * private material (`pkcs7` + `cert`), not merely a projected public verify key.
+ *
+ * A freshly provisioned WFP tenant inherits only the control plane's public
+ * keys (private material stripped at the boundary), so it can serve JWKS and
+ * `/authorize` but 500s at `/oauth/token` with nothing to sign — issue #1181.
+ * Calling this at provision time closes that gap by minting the tenant's own
+ * RS256 key locally (private material never crosses the control-plane boundary).
+ *
+ * Create-if-missing and idempotent: a scope that already has a signable key is
+ * left untouched, so it is safe to call on every provision and re-sync.
+ */
+export declare function ensureSigningKey(keys: KeysAdapter, opts?: EnsureSigningKeyOptions): Promise<EnsureSigningKeyResult>;

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

@@ -21,12 +21,84 @@ export declare function getUserByProvider({ userAdapter, tenant_id, username, pr
  * same millisecond).
  */
 export declare function compareUsersByAge(a: User, b: User): number;
+/**
+ * Order users by how recently they were used to log in (most recent first).
+ *
+ * Distinct from {@link compareUsersByAge}: that encodes the *linking* policy
+ * ("the older account is canonical"), while this answers "which of these
+ * accounts is the person actually using?" — the question behind the login
+ * screen's last-used-strategy hint.
+ *
+ * Users that have never logged in sort last. Ties fall back to
+ * `compareUsersByAge` so the ordering is fully deterministic.
+ */
+export declare function compareUsersByLastLogin(a: User, b: User): number;
+interface UserExistsByEmailParams {
+    userAdapter: UserDataAdapter;
+    tenant_id: string;
+    email: string;
+}
+/**
+ * True when any user row carries this email — primary or secondary.
+ *
+ * The login screens' signup gates only need to know whether an account exists
+ * for the address, never which row is canonical. Asking that narrower question
+ * directly (rather than via {@link getPrimaryUserByEmail}) keeps them correct
+ * on tenants running with user linking off, where several unlinked primaries
+ * legitimately share an email, and avoids throwing on a dangling `linked_to`.
+ */
+export declare function userExistsByEmail({ userAdapter, tenant_id, email, }: UserExistsByEmailParams): Promise<boolean>;
 interface GetPrimaryUserByEmailParams {
     userAdapter: UserDataAdapter;
     tenant_id: string;
     email: string;
+    /**
+     * Log when more than one primary shares the email. Only meaningful on
+     * account-linking paths, where duplicate primaries mean linking failed to
+     * converge. With `userLinkingMode: "off"` several primaries per email is the
+     * expected steady state (it's Auth0's default behaviour), so read paths
+     * leave this off rather than logging an error on every login.
+     */
+    warnOnMultiplePrimaries?: boolean;
+}
+export declare function getPrimaryUserByEmail({ userAdapter, tenant_id, email, warnOnMultiplePrimaries, }: GetPrimaryUserByEmailParams): Promise<User | undefined>;
+interface GetLastUsedUserByEmailParams {
+    userAdapter: UserDataAdapter;
+    tenant_id: string;
+    email: string;
 }
-export declare function getPrimaryUserByEmail({ userAdapter, tenant_id, email, }: GetPrimaryUserByEmailParams): Promise<User | undefined>;
+/**
+ * The account for `email` that was most recently logged in to.
+ *
+ * Used for UI hints that describe *this person's habits* — chiefly the
+ * last-used-strategy shortcut on the identifier screen. When linking is off, an
+ * email can map to several primaries (say a password account and a Google one);
+ * picking the oldest, as {@link getPrimaryUserByEmail} does, would hand back
+ * whichever account they happened to create first and hint at a login method
+ * they may have abandoned. Picking by `last_login` follows the account actually
+ * in use.
+ *
+ * Deliberately *not* provider-biased: preferring the password account would
+ * push habitual social users to the password screen.
+ *
+ * When only secondaries match, the cluster root is returned — login updates
+ * land on the primary, so that's where the hint lives. Unlike
+ * `getPrimaryUserByEmail` a dangling `linked_to` yields `undefined` rather than
+ * throwing; callers fall back to the tenant's default strategy, which is the
+ * right outcome for a hint.
+ */
+export declare function getLastUsedUserByEmail({ userAdapter, tenant_id, email, }: GetLastUsedUserByEmailParams): Promise<User | undefined>;
+/**
+ * Resolve a user to the primary of its linked cluster. Follows a single
+ * `linked_to` hop — the linking invariants keep clusters one level deep
+ * (see {@link repointPrimary}) — and falls back to the given user on a
+ * dangling link so callers never lose the identity they started with.
+ *
+ * Used by the forms engine so that post-login profile forms evaluate
+ * router conditions against, and stamp submitted values onto, the primary
+ * identity even when the session points at a secondary.
+ */
+export declare function resolvePrimaryUser(userAdapter: UserDataAdapter, tenant_id: string, user: User): Promise<User>;
 interface RepointPrimaryParams {
     userAdapter: UserDataAdapter;
     tenant_id: string;
@@ -44,6 +116,49 @@ interface RepointPrimaryParams {
  * the linking logic recursively.
  */
 export declare function repointPrimary({ userAdapter, tenant_id, formerPrimary, newPrimaryId, }: RepointPrimaryParams): Promise<void>;
+/**
+ * True for identities whose *login identifier* is the email address: the native
+ * username-password providers (`auth0`/`auth2`) and the passwordless `email`
+ * connection. For these, `email` is a credential — it's how the login row is
+ * found (`getUserByProvider`), so it must stay consistent across a linked
+ * cluster.
+ *
+ * Social identities carry `email` as ordinary profile data (re-synced from the
+ * IdP on every login) and sms identities are keyed by `phone_number`, so neither
+ * is email-identified and neither should have its `email` rewritten by a cascade.
+ */
+export declare function isEmailIdentifiedUser(user: Pick<User, "provider" | "connection">): boolean;
+interface CascadeEmailParams {
+    userAdapter: UserDataAdapter;
+    tenant_id: string;
+    /** The cluster root (primary) user_id — its secondaries are enumerated. */
+    primaryUserId: string;
+    /** The row whose email the caller already updated; skipped by the cascade. */
+    sourceUserId: string;
+    email: string;
+    email_verified: boolean;
+}
+/**
+ * Propagate an email change across every *email-identified* identity in a linked
+ * cluster so a merged user keeps a single login email.
+ *
+ * Because account-linking matches on a shared email, at link time every
+ * email-identified identity in a cluster carries the same address. The only way
+ * they diverge is a later email change on one of them — and when they diverge,
+ * the login row for the *other* email-identified identities still carries the
+ * old address, so the user can no longer sign in with the address now shown on
+ * their profile (the classic "changed my email, can't log in with my password"
+ * bug).
+ *
+ * This re-establishes the invariant: only email-identified rows are touched
+ * ({@link isEmailIdentifiedUser}); sms (`phone_number`) and social (provider
+ * sub) identifiers are never rewritten. `sourceUserId` is skipped (the caller
+ * already wrote it). Each cascaded write goes through the normal decorated
+ * `update`, so every affected identity emits its own `user.updated` event for
+ * downstream propagation, and `email_verified` moves in lock-step so the whole
+ * cluster shares one verification state.
+ */
+export declare function cascadeEmailToLinkedIdentities({ userAdapter, tenant_id, primaryUserId, sourceUserId, email, email_verified, }: CascadeEmailParams): Promise<void>;
 interface GetPrimaryUserByProviderParams {
     userAdapter: UserDataAdapter;
     tenant_id: string;

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

@@ -60,11 +60,19 @@ 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.
+ *
+ * Awaits each replayed call. Most registered methods are synchronous (they
+ * mutate a token or throw), but some do async work — notably
+ * `user.setLinkedTo` at `post-user-login`, which paginates and writes user rows
+ * to perform the link. Since replay runs *after* the isolate returns, the login
+ * response is built from whatever this resolves to; awaiting guarantees such
+ * work completes before the caller proceeds. Synchronous methods return
+ * non-thenables, so awaiting them is a no-op.
  */
 export declare function replayApiCalls(apiCalls: Array<{
     method: string;
     args: unknown[];
-}>, api: CodeHookApi): void;
+}>, api: CodeHookApi): Promise<void>;
 export type HandleCodeHookOutcome = {
     result: ActionExecutionResult;
     logs: CodeExecutionLog[];

package/dist/types/hooks/helpers/post-login-account-linking.d.ts

@@ -0,0 +1,52 @@
+import { Context } from "hono";
+import { DataAdapters, User } from "@authhero/adapter-interfaces";
+import { Bindings, Variables } from "../../types";
+/**
+ * The `user` namespace exposed to `post-user-login` code hooks. `setLinkedTo`
+ * is the programmable account-linking verb (issue #1184): an action reads
+ * `event.link_candidates` and calls `api.user.setLinkedTo(candidate.user_id)`.
+ */
+export type PostLoginUserApi = {
+    user: {
+        setLinkedTo: (primaryUserId: string) => Promise<void>;
+    };
+};
+/**
+ * Builds the guarded `api.user.setLinkedTo` implementation for the
+ * `post-user-login` trigger, plus a getter for the resulting primary user id.
+ *
+ * The recording proxy captures the action's `setLinkedTo(id)` call; the host
+ * replays it against this implementation *after* the isolate returns
+ * (`replayApiCalls`, which awaits — so the DB writes complete before the login
+ * response is built).
+ *
+ * Guards, all enforced server-side so a malicious/buggy action cannot escalate:
+ *  - **Candidate allowlist.** `primaryUserId` must be one of `candidates`
+ *    (the same set serialized into `event.link_candidates`). Without this an
+ *    action could link the current user to an arbitrary `user_id` —
+ *    account-takeover. Rejections log `FAILED_HOOK` and mutate nothing.
+ *  - **Verified-email gate.** When `requireVerifiedEmail` (the default), the
+ *    logging-in user must have a verified email, regardless of what the action
+ *    asserts.
+ *  - **Direction.** Older account wins (`compareUsersByAge`): if the logging-in
+ *    user pre-dates the target, the target is demoted via `repointPrimary`
+ *    (avoiding 2-hop chains) instead.
+ *  - **Idempotency.** A no-op when the user is already linked to the target.
+ */
+export declare function createPostLoginUserApi(params: {
+    ctx: Context<{
+        Bindings: Bindings;
+        Variables: Variables;
+    }>;
+    data: DataAdapters;
+    tenantId: string;
+    user: User;
+    /** Resolved candidate primaries (same set as `event.link_candidates`). */
+    candidates: User[];
+    /** @default true */
+    requireVerifiedEmail?: boolean;
+}): {
+    api: PostLoginUserApi;
+    /** The user id of the primary after linking, or null if nothing linked. */
+    getLinkedPrimaryId: () => string | null;
+};

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

@@ -20,6 +20,26 @@ export interface AccountLinkingOptions {
      * @default false
      */
     copyUserMetadata?: boolean;
+    /**
+     * When the link is performed, fill in *absent* root profile fields on the
+     * primary from the secondary — e.g. a secondary that has a `birthdate` the
+     * primary lacks, or a phone number an email primary doesn't carry.
+     *
+     * Fill-if-absent only: a field already set on the primary is never
+     * overwritten (primary stays authoritative), matching `copyUserMetadata`.
+     * Identifier and verification fields are never touched — `email`,
+     * `email_verified`, `phone_verified`, `username`, `provider`, `connection`
+     * are excluded — so this can't rewrite a login identifier. In particular an
+     * sms primary already carries a `phone_number`, so its identifier is never
+     * filled over; the promotion only reaches a primary that has no phone yet.
+     *
+     * Off by default to match Auth0, which keeps a linked identity's own
+     * attributes under `identities[].profileData` rather than promoting them to
+     * the merged user's root profile.
+     *
+     * @default false
+     */
+    copyProfileFields?: boolean;
 }
 /**
  * Trigger-agnostic event handler used by all `account-linking` template

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

@@ -61,6 +61,7 @@ export declare function createUserHooks(ctx: Context<{
     verify_email?: boolean | undefined;
     last_ip?: string | undefined;
     last_login?: string | undefined;
+    blocked?: boolean | undefined;
     registration_completed_at?: string | undefined;
     email?: string | undefined;
     identities?: {