authhero 9.6.3 → 9.7.0

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

@@ -1,4 +1,4 @@
-import { AuthorizationResponseType, AuthParams, LoginSession, RefreshToken, User, TokenResponse } from "@authhero/adapter-interfaces";
+import { AuthorizationResponseType, AuthParams, LoginSession, LoginSessionAuthStrategy, RefreshToken, User, TokenResponse } from "@authhero/adapter-interfaces";
 import { EnrichedClient } from "../helpers/client";
 import { Context } from "hono";
 import { Bindings, Variables } from "../types";
@@ -82,6 +82,22 @@ export interface CreateRefreshTokenParams {
     login_id: string;
     scope: string;
     audience?: string;
+    /**
+     * The authenticated session this token is issued under — Auth0's
+     * `session_id`. Stored so revoking a session can revoke its tokens in one
+     * hop, and so the refresh grant never has to resolve it through the
+     * short-lived login session. Optional: flows without a session still mint
+     * tokens, and the column is nullable for exactly that reason.
+     */
+    session_id?: string;
+    /**
+     * Auth-event facts, denormalised from the login session. All are immutable
+     * for the life of the token; keeping them here means the grant no longer
+     * degrades silently when the login session has been cleaned up.
+     */
+    organization?: string;
+    auth_connection?: string;
+    auth_strategy?: LoginSessionAuthStrategy;
 }
 export interface CreatedRefreshToken {
     row: RefreshToken;

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

@@ -372,7 +372,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
                             active?: boolean | undefined;
                         } | undefined;
                         signup?: {
-                            status?: "optional" | "required" | "disabled" | undefined;
+                            status?: "required" | "optional" | "disabled" | undefined;
                             verification?: {
                                 active?: boolean | undefined;
                             } | undefined;
@@ -389,7 +389,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
                             active?: boolean | undefined;
                         } | undefined;
                         signup?: {
-                            status?: "optional" | "required" | "disabled" | undefined;
+                            status?: "required" | "optional" | "disabled" | undefined;
                         } | undefined;
                         validation?: {
                             max_length?: number | undefined;
@@ -406,7 +406,7 @@ export declare function passwordlessGrantUser(ctx: Context<{
                             active?: boolean | undefined;
                         } | undefined;
                         signup?: {
-                            status?: "optional" | "required" | "disabled" | undefined;
+                            status?: "required" | "optional" | "disabled" | undefined;
                         } | undefined;
                     } | undefined;
                 } | undefined;
@@ -554,8 +554,8 @@ export declare function passwordlessGrantUser(ctx: Context<{
         } | undefined;
         authenticated_at?: string | undefined;
     };
-    connectionType: "sms" | "email" | "username";
-    authConnection: "sms" | "email" | "username";
+    connectionType: "email" | "username" | "sms";
+    authConnection: "email" | "username" | "sms";
     session_id: string | undefined;
     authParams: {
         client_id: string;

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/revoke-user-refresh-tokens.d.ts

@@ -0,0 +1,21 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+/**
+ * Soft-revoke every active refresh token belonging to a user.
+ *
+ * Unlike the single-token admin delete (which also hard-removes the row), this
+ * keeps the rows around with `revoked_at` set so the admin UI and the audit
+ * trail can still show what was invalidated and when.
+ *
+ * Delegates to the adapter so the match is a pair of exact predicates rather
+ * than a `q` filter: the Lucene grammar splits on ` OR ` before tokenizing, so
+ * a user id containing ` OR user_id:<other> OR ` would widen a `q`-based
+ * revoke to another user's tokens. The adapter also skips already-revoked
+ * rows, so a concurrent revocation cannot overwrite an existing timestamp.
+ *
+ * Returns the number of tokens revoked.
+ */
+export declare function revokeUserRefreshTokens(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenant_id: string, user_id: string): Promise<number>;

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

@@ -101,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`

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: {