authhero 9.6.1 → 9.6.4

package/dist/types/helpers/dcr/metadata-mapping.d.ts

@@ -24,10 +24,10 @@ export declare const dcrRequestSchema: z.ZodObject<{
     response_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
     token_endpoint_auth_method: z.ZodOptional<z.ZodEnum<{
         none: "none";
-        private_key_jwt: "private_key_jwt";
         client_secret_post: "client_secret_post";
         client_secret_basic: "client_secret_basic";
         client_secret_jwt: "client_secret_jwt";
+        private_key_jwt: "private_key_jwt";
     }>>;
     jwks_uri: z.ZodOptional<z.ZodString>;
     jwks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;

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

@@ -3,6 +3,18 @@ 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[]>;
+/**
+ * Every user sharing `email`, across all pages.
+ *
+ * {@link getUsersByEmail} returns a single ten-row page, which is fine for the
+ * Auth0-shaped `/users-by-email` endpoint but not for a uniqueness check:
+ * {@link findEmailConflict} *filters* candidates by connection and cluster, so a
+ * truncated page can hide the one row that genuinely conflicts and let a
+ * duplicate through. An address legitimately spans many rows (one per provider
+ * in a linked cluster), so ten is well within reach. Mirrors the pagination loop
+ * in `resolveLinkCandidates`.
+ */
+export declare function getAllUsersByEmail(userAdapter: UserDataAdapter, tenantId: string, email: string): Promise<User[]>;
 interface GetUserByProviderParams {
     userAdapter: UserDataAdapter;
     tenant_id: string;
@@ -89,33 +101,71 @@ interface GetLastUsedUserByEmailParams {
  */
 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.
+ * Walk `linked_to` from `userId` to the root of its cluster.
+ *
+ * Correct data resolves in a single hop — {@link linkUserTo} is the only writer
+ * of `linked_to` and it keeps clusters flat. This follows the chain anyway, and
+ * loudly, because pre-existing rows written before that invariant was enforced
+ * can still be several hops deep: degrading to the right answer beats handing a
+ * caller a mid-chain identity that reads as a different person.
+ *
+ * Returns `userId` unchanged when it is a root, is unknown to the adapter, or
+ * carries a dangling link, so callers never lose the identity they started
+ * with. Cycles and over-deep chains stop at the last id reached.
+ */
+export declare function resolveClusterRootId(userAdapter: UserDataAdapter, tenant_id: string, userId: string): Promise<string>;
+/**
+ * Resolve a user to the primary of its linked cluster, falling back to the
+ * given user when the link is dangling so callers never lose the identity they
+ * started with.
+ *
+ * This is the single resolver every read path should use — token minting
+ * (authorization-code, refresh-token, silent, token-exchange, password), the
+ * forms engine, and anything else that needs the canonical identity behind a
+ * session. Resolving through {@link resolveClusterRootId} means a cluster that
+ * is already corrupt degrades to the correct answer instead of minting a token
+ * for a mid-chain `sub`.
  */
 export declare function resolvePrimaryUser(userAdapter: UserDataAdapter, tenant_id: string, user: User): Promise<User>;
-interface RepointPrimaryParams {
+interface LinkUserToParams {
+    /**
+     * Must be an *undecorated* adapter. {@link linkUserTo} is what the user-update
+     * decorator's `linked_to` fast-path calls, so handing it a decorated adapter
+     * would make its own writes re-enter that fast-path and recurse. Hook code
+     * holding `ctx.env.data` should not call this — a plain
+     * `users.update(id, { linked_to })` already routes through here.
+     */
     userAdapter: UserDataAdapter;
     tenant_id: string;
-    formerPrimary: User;
-    newPrimaryId: string;
+    /** The user being demoted to a secondary. */
+    userId: string;
+    /** The intended primary. Resolved to its own cluster root first. */
+    primaryId: string;
 }
 /**
- * Demote `formerPrimary` to a secondary of `newPrimaryId`. Any users
- * currently linked to `formerPrimary` are repointed first so the resulting
- * graph remains a single hop deep — `getPrimaryUserByProvider` and similar
- * resolvers only follow one `linked_to` step.
- *
- * Each write is a single-field `linked_to` update so the user-update
- * decorator's fast-path bypasses the pre/post hooks and we don't re-enter
- * the linking logic recursively.
+ * Demote `userId` to a secondary of `primaryId`'s cluster — the one and only
+ * way `linked_to` is ever set (issue #1250).
+ *
+ * Two things have to happen together for the graph to stay a single hop deep,
+ * and doing either without the other silently corrupts it:
+ *
+ *  - **Resolve the target.** Linking onto a row that is itself a secondary
+ *    would build a second hop, so the real root is resolved first.
+ *  - **Repoint the children.** Any users already linked to `userId` are moved
+ *    onto the root *before* `userId` is demoted. Skipping this strands them
+ *    behind a now-secondary parent, where no resolver can reach them and they
+ *    disappear from the API entirely.
+ *
+ * Callers get this for free: the decorator routes every single-field
+ * `linked_to` update through here, so a bare
+ * `users.update(id, { linked_to })` — from the management API, a consumer's
+ * hook, or internal linking code — is safe by construction rather than by
+ * remembering to call the right helper.
+ *
+ * Returns the cluster root `userId` was actually linked to, which may differ
+ * from the requested `primaryId`.
  */
-export declare function repointPrimary({ userAdapter, tenant_id, formerPrimary, newPrimaryId, }: RepointPrimaryParams): Promise<void>;
+export declare function linkUserTo({ userAdapter, tenant_id, userId, primaryId, }: LinkUserToParams): Promise<string>;
 /**
  * True for identities whose *login identifier* is the email address: the native
  * username-password providers (`auth0`/`auth2`) and the passwordless `email`
@@ -128,6 +178,47 @@ export declare function repointPrimary({ userAdapter, tenant_id, formerPrimary,
  * is email-identified and neither should have its `email` rewritten by a cascade.
  */
 export declare function isEmailIdentifiedUser(user: Pick<User, "provider" | "connection">): boolean;
+interface EmailConflictParams {
+    /** Every user sharing the new address, as returned by {@link getUsersByEmail}. */
+    candidates: User[];
+    /** The identity whose email is being changed. */
+    target: Pick<User, "user_id" | "provider" | "connection">;
+    /**
+     * The cluster root of the patched user. `target` may be the root itself or one
+     * of its linked secondaries (when the caller passed `connection`).
+     */
+    clusterRootId: string;
+}
+/**
+ * Find the user, if any, that genuinely blocks changing `target`'s email to an
+ * address already present on other rows.
+ *
+ * Two rows sharing an email is only a *conflict* when it makes a login ambiguous,
+ * and login lookups are always provider-scoped (`getUserByProvider` filters on
+ * `email:x provider:y`). So the check is scoped the way Auth0 scopes it — per
+ * connection — with one hard floor from the storage layer:
+ *
+ * - **Same provider** → always a conflict, cluster-mate or not. The
+ *   `(tenant_id, provider, email)` unique index makes a second row with that
+ *   address unrepresentable, so the write cannot succeed; a 409 is the honest
+ *   answer where allowing it would surface as a constraint-violation 500.
+ * - **Same connection, different provider** → a conflict *between* clusters. Two
+ *   `Username-Password-Authentication` rows (the `auth0`/`auth2` pair) sharing an
+ *   address are competing login rows for one credential. Unknown/custom
+ *   connections are included, so tenant-specific database connections keep the
+ *   protection they have today.
+ * - **Different connection** → not a conflict. An `sms` identity is keyed by
+ *   `phone_number` and a social identity by its provider sub, so their `email` is
+ *   ordinary profile data that can't shadow an email login. This mirrors the
+ *   `phone_number` carve-out on the same route (#1162) and matches Auth0, where
+ *   one address may exist across connections.
+ * - **Cluster-mates** (the root and its secondaries) → not a conflict, provider
+ *   permitting: they are the same person, and `cascadeEmailToLinkedIdentities`
+ *   deliberately converges the cluster onto one address right after this check.
+ *   Because AuthHero keeps secondaries as real rows (Auth0 folds them into the
+ *   primary's `identities[]`), they'd otherwise surface here as "another user".
+ */
+export declare function findEmailConflict({ candidates, target, clusterRootId, }: EmailConflictParams): User | undefined;
 interface CascadeEmailParams {
     userAdapter: UserDataAdapter;
     tenant_id: string;

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

@@ -29,8 +29,9 @@ export type PostLoginUserApi = {
  *    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.
+ *    user pre-dates the target, the target is demoted instead. Either way the
+ *    write goes through the update decorator's `linkUserTo` chokepoint, which
+ *    keeps the cluster a single hop deep.
  *  - **Idempotency.** A no-op when the user is already linked to the target.
  */
 export declare function createPostLoginUserApi(params: {