authhero 9.0.0 → 9.1.0

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

@@ -83,6 +83,7 @@ export declare function passwordlessGrantUser(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?: {
@@ -549,8 +550,8 @@ export declare function passwordlessGrantUser(ctx: Context<{
         } | undefined;
         authenticated_at?: string | undefined;
     };
-    connectionType: "email" | "sms" | "username";
-    authConnection: "email" | "sms" | "username";
+    connectionType: "username" | "email" | "sms";
+    authConnection: "username" | "email" | "sms";
     session_id: string | undefined;
     authParams: {
         client_id: string;

package/dist/types/constants.d.ts

@@ -3,6 +3,8 @@ export declare const JWKS_CACHE_TIMEOUT_IN_SECONDS: number;
 export declare const SILENT_AUTH_MAX_AGE_IN_SECONDS: number;
 export declare const UNIVERSAL_AUTH_SESSION_EXPIRES_IN_SECONDS: number;
 export declare const SILENT_COOKIE_NAME = "auth-token";
+export declare const LAST_USED_CONNECTION_COOKIE_NAME = "last-used-connection";
+export declare const LAST_USED_CONNECTION_MAX_AGE_IN_SECONDS: number;
 export declare const OTP_EXPIRATION_TIME: number;
 export declare const EMAIL_VERIFICATION_EXPIRATION_TIME: number;
 export declare const AUTHORIZATION_CODE_EXPIRES_IN_SECONDS: number;

package/dist/types/generated/locale-types.d.ts

@@ -101,6 +101,7 @@ export interface LoginScreen {
     federatedConnectionButtonText: (vars: {
         connectionName: string;
     }) => string;
+    lastUsedText: () => string;
     footerLinkText: () => string;
     footerText: () => string;
     forgotPasswordText: () => string;
@@ -162,6 +163,7 @@ export interface LoginIdScreen {
     federatedConnectionButtonText: (vars: {
         connectionName: string;
     }) => string;
+    lastUsedText: () => string;
     footerLinkText: () => string;
     footerText: () => string;
     forgotPasswordText: () => string;

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

@@ -500,8 +500,8 @@ export declare const enrichedClientSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>>>;
         enabled_clients: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
-        response_type: z.ZodOptional<z.ZodCustom<import("@authhero/adapter-interfaces").AuthorizationResponseType, import("@authhero/adapter-interfaces").AuthorizationResponseType>>;
-        response_mode: z.ZodOptional<z.ZodCustom<import("@authhero/adapter-interfaces").AuthorizationResponseMode, import("@authhero/adapter-interfaces").AuthorizationResponseMode>>;
+        response_type: z.ZodOptional<z.ZodEnum<typeof import("@authhero/adapter-interfaces").AuthorizationResponseType>>;
+        response_mode: z.ZodOptional<z.ZodEnum<typeof import("@authhero/adapter-interfaces").AuthorizationResponseMode>>;
         is_domain_connection: z.ZodOptional<z.ZodBoolean>;
         show_as_button: z.ZodOptional<z.ZodBoolean>;
         metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;

package/dist/types/helpers/revoke-user-sessions.d.ts

@@ -0,0 +1,15 @@
+import { Context } from "hono";
+import { Bindings, Variables } from "../types";
+/**
+ * Revoke all of a user's sessions and the refresh tokens issued under them.
+ * Used when a user is blocked — Auth0 terminates a user's sessions on block —
+ * and reused by SCIM deactivation (Phase 2, #1191).
+ *
+ * Returns the number of refresh tokens revoked. Sessions are gathered up front
+ * (across pages) before any mutation, so revoking in place cannot interfere
+ * with pagination.
+ */
+export declare function revokeUserSessions(ctx: Context<{
+    Bindings: Bindings;
+    Variables: Variables;
+}>, tenant_id: string, user_id: string): Promise<number>;

package/dist/types/helpers/scim/default-mapping.d.ts

@@ -0,0 +1,10 @@
+import { ScimMappingEntry } from "@authhero/adapter-interfaces";
+/**
+ * Default SCIM ↔ AuthHero attribute mapping, mirroring Auth0's default
+ * inbound-provisioning mapping. `scim` is the SCIM resource attribute path,
+ * `auth0` the AuthHero user field. The `active` → `blocked` entry maps SCIM
+ * account status onto AuthHero's block flag; the inversion (active=false ⇒
+ * blocked=true) is applied by the provisioning layer in Phase 2, not here.
+ */
+export declare const DEFAULT_SCIM_MAPPING: ScimMappingEntry[];
+export declare const DEFAULT_USER_ID_ATTRIBUTE = "externalId";

package/dist/types/helpers/scim/discovery.d.ts

@@ -0,0 +1,49 @@
+import { ScimListResponse } from "./responses";
+/**
+ * Static SCIM discovery documents (RFC 7643 §5–7). The capability set mirrors
+ * what AuthHero actually implements and what Auth0 advertises: PATCH and
+ * filtering yes; bulk, sort, etag, changePassword no.
+ */
+/**
+ * Largest page the `/Users` endpoints return, advertised as
+ * `filter.maxResults` in ServiceProviderConfig. The route clamps `count` to
+ * this so the advertised ceiling and the served page size can't drift apart.
+ */
+export declare const SCIM_MAX_RESULTS = 200;
+export declare function serviceProviderConfig(location: string): {
+    schemas: string[];
+    documentationUri: string;
+    patch: {
+        supported: boolean;
+    };
+    bulk: {
+        supported: boolean;
+        maxOperations: number;
+        maxPayloadSize: number;
+    };
+    filter: {
+        supported: boolean;
+        maxResults: number;
+    };
+    changePassword: {
+        supported: boolean;
+    };
+    sort: {
+        supported: boolean;
+    };
+    etag: {
+        supported: boolean;
+    };
+    authenticationSchemes: {
+        type: string;
+        name: string;
+        description: string;
+        primary: boolean;
+    }[];
+    meta: {
+        resourceType: string;
+        location: string;
+    };
+};
+export declare function resourceTypes(baseUrl: string): ScimListResponse<unknown>;
+export declare function schemas(baseUrl: string): ScimListResponse<unknown>;

package/dist/types/helpers/scim/filter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Minimal SCIM 2.0 filter support (RFC 7644 §3.4.2.2), scoped to what Okta and
+ * Microsoft Entra actually send when provisioning: equality (`eq`) on a small
+ * set of attributes, optionally combined with `and` / `or` and parentheses.
+ * Anything outside this subset throws `UnsupportedFilterError`, which the route
+ * layer turns into a SCIM 501 error — we never silently mis-evaluate a filter.
+ *
+ * Auth0's inbound SCIM documents exactly this operator set (eq / and / or), so
+ * the subset is also the parity target.
+ */
+export declare class UnsupportedFilterError extends Error {
+}
+export declare class InvalidFilterError extends Error {
+}
+export type ScimFilterValue = string | boolean | number;
+export type ScimFilterNode = {
+    type: "eq";
+    attribute: string;
+    value: ScimFilterValue;
+} | {
+    type: "and";
+    left: ScimFilterNode;
+    right: ScimFilterNode;
+} | {
+    type: "or";
+    left: ScimFilterNode;
+    right: ScimFilterNode;
+};
+/**
+ * Recursive-descent parser. Grammar (precedence: or < and < comparison):
+ *   filter     := orExpr
+ *   orExpr     := andExpr ( "or" andExpr )*
+ *   andExpr    := primary ( "and" primary )*
+ *   primary    := "(" filter ")" | comparison
+ *   comparison := ATTR "eq" VALUE
+ */
+export declare function parseScimFilter(input: string): ScimFilterNode;
+/**
+ * Evaluate a parsed filter against a flat attribute map (a SCIM resource
+ * projected to the attributes we support: `userName`, `externalId`, `active`,
+ * `emails.value`/`emails`). Attribute matching is case-insensitive on the name
+ * (SCIM attribute names are case-insensitive), and so is string value
+ * comparison: `userName` and `emails.value` are `caseExact: false` in our
+ * schema, and the targeted `userName` lookup is case-insensitive too, so an
+ * exact comparison here would make the same filter behave differently
+ * depending on which path served it.
+ */
+export declare function evaluateScimFilter(node: ScimFilterNode, attributes: Record<string, ScimFilterValue | undefined>): boolean;
+/**
+ * If the filter is a single `attr eq "value"` (the overwhelmingly common IdP
+ * case — lookup before create), return that pair so the route can do a
+ * targeted DB lookup instead of scanning the connection. Returns null for
+ * compound filters.
+ */
+export declare function asSingleEquality(node: ScimFilterNode): {
+    attribute: string;
+    value: ScimFilterValue;
+} | null;

package/dist/types/helpers/scim/mint-token.d.ts

@@ -0,0 +1,11 @@
+export interface GeneratedScimToken {
+    token_id: string;
+    token: string;
+    token_hash: string;
+}
+/**
+ * SHA-256 hex of the raw bearer token. The SCIM auth middleware (Phase 2)
+ * hashes the presented token the same way and looks it up via `getByHash`.
+ */
+export declare function hashScimToken(token: string): Promise<string>;
+export declare function mintScimToken(): Promise<GeneratedScimToken>;

package/dist/types/helpers/scim/patch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal SCIM 2.0 PATCH support (RFC 7644 §3.5.2), scoped to what Okta and
+ * Microsoft Entra send when provisioning users: `add` / `replace` / `remove`
+ * with either no path (a value object merged into the resource), a simple
+ * dotted path (`active`, `name.givenName`, `displayName`), or a single
+ * value-filtered multi-valued path (`emails[type eq "work"].value`).
+ *
+ * Operates on and returns a plain SCIM resource object; the route layer maps
+ * the patched resource back to AuthHero user fields. Anything outside the
+ * supported shape throws, which the route turns into a SCIM 400/501.
+ */
+export declare class InvalidPatchError extends Error {
+}
+export declare class UnsupportedPatchError extends Error {
+}
+export interface ScimPatchOperation {
+    op: string;
+    path?: string;
+    value?: unknown;
+}
+type Json = Record<string, unknown>;
+export declare function applyScimPatch(resource: Json, operations: ScimPatchOperation[]): Json;
+export {};

package/dist/types/helpers/scim/responses.d.ts

@@ -0,0 +1,36 @@
+import { ContentfulStatusCode } from "hono/utils/http-status";
+export declare const SCIM_ERROR_URN = "urn:ietf:params:scim:api:messages:2.0:Error";
+export declare const SCIM_LIST_URN = "urn:ietf:params:scim:api:messages:2.0:ListResponse";
+export declare const SCIM_PATCH_OP_URN = "urn:ietf:params:scim:api:messages:2.0:PatchOp";
+export declare const SCIM_CONTENT_TYPE = "application/scim+json";
+export interface ScimErrorBody {
+    schemas: string[];
+    detail: string;
+    status: string;
+    scimType?: string;
+}
+/**
+ * SCIM error object (RFC 7644 §3.12). `status` is a string, and `scimType` is
+ * only meaningful for 400s (e.g. `uniqueness`, `invalidFilter`).
+ */
+export declare function scimErrorBody(status: number, detail: string, scimType?: string): ScimErrorBody;
+/**
+ * Thrown from SCIM middleware/helpers; rendered by the SCIM app's `onError`
+ * into a proper SCIM error object with the SCIM content type.
+ */
+export declare class ScimError extends Error {
+    status: ContentfulStatusCode;
+    scimType?: string;
+    constructor(status: ContentfulStatusCode, detail: string, scimType?: string);
+}
+export interface ScimListResponse<T> {
+    schemas: string[];
+    totalResults: number;
+    startIndex: number;
+    itemsPerPage: number;
+    Resources: T[];
+}
+/**
+ * SCIM ListResponse envelope (RFC 7644 §3.4.2). `startIndex` is 1-based.
+ */
+export declare function scimListResponse<T>(resources: T[], totalResults: number, startIndex: number, itemsPerPage: number): ScimListResponse<T>;

package/dist/types/helpers/scim/user-mapping.d.ts

@@ -0,0 +1,76 @@
+import { User } from "@authhero/adapter-interfaces";
+import { ScimFilterValue } from "./filter";
+export declare const SCIM_USER_SCHEMA_URN = "urn:ietf:params:scim:schemas:core:2.0:User";
+export interface ScimEmail {
+    value: string;
+    primary?: boolean;
+    type?: string;
+}
+export interface ScimUserResource {
+    schemas: string[];
+    id: string;
+    externalId?: string;
+    userName?: string;
+    name?: {
+        givenName?: string;
+        familyName?: string;
+    };
+    displayName?: string;
+    emails?: ScimEmail[];
+    active: boolean;
+    meta: {
+        resourceType: "User";
+        created?: string;
+        lastModified?: string;
+        location: string;
+    };
+}
+/**
+ * The subset of user fields SCIM writes. `blocked` carries the inverse of the
+ * SCIM `active` attribute (active:false → blocked:true); `externalId` is
+ * persisted out-of-band in the scim_external_ids table by the route, not on
+ * the user row.
+ */
+export interface MappedUserFields {
+    email?: string;
+    username?: string;
+    given_name?: string;
+    family_name?: string;
+    name?: string;
+    blocked?: boolean;
+    externalId?: string;
+}
+/**
+ * Project an AuthHero user to a SCIM User resource. Mirrors Auth0's default
+ * mapping: SCIM `id` is the AuthHero `user_id`, `active` is the inverse of
+ * `blocked`, and `externalId` comes from the connection's external-id table.
+ */
+export declare function userToScimResource(user: User, externalId: string | undefined, location: string): ScimUserResource;
+/**
+ * Map a SCIM User resource (as sent on create/replace, or the result of
+ * applying a PATCH) to AuthHero user fields. `userName` becomes `email` when it
+ * looks like an address, otherwise `username`. `active` maps to the inverse of
+ * `blocked`.
+ *
+ * Attributes the resource does not carry are **omitted from the result**, not
+ * set to `undefined`: the callers spread this straight into `users.update`, and
+ * an explicit key would be indistinguishable from "clear this field". Absent
+ * therefore means "leave unchanged" — a partial PATCH never unblocks a user or
+ * wipes their name.
+ */
+export declare function scimResourceToUserFields(resource: {
+    userName?: string;
+    externalId?: string;
+    name?: {
+        givenName?: string;
+        familyName?: string;
+    };
+    displayName?: string;
+    emails?: ScimEmail[];
+    active?: boolean;
+}): MappedUserFields;
+/**
+ * Flatten a user (+ its externalId) to the attribute map the filter evaluator
+ * expects. Keys mirror the SCIM attribute names real IdPs filter on.
+ */
+export declare function userToFilterAttributes(user: User, externalId: string | undefined): Record<string, ScimFilterValue | undefined>;

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, }: GetPrimaryUserByEmailParams): Promise<User | undefined>;
+export declare function getPrimaryUserByEmail({ userAdapter, tenant_id, email, warnOnMultiplePrimaries, }: GetPrimaryUserByEmailParams): Promise<User | undefined>;
+interface GetLastUsedUserByEmailParams {
+    userAdapter: UserDataAdapter;
+    tenant_id: string;
+    email: string;
+}
+/**
+ * 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;

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