najm-auth 3.4.0 → 4.0.1

package/dist/index.d.ts

@@ -659,6 +659,11 @@ interface SessionCookieData {
      * (password change/reset, logout-all) without hitting the database.
      */
     sessionVersion: number;
+    /**
+     * The refresh session this snapshot belongs to, so a single-device logout —
+     * which deliberately leaves the per-user version alone — can still reach it.
+     */
+    tokenFamily: string;
     /** Epoch ms when the cookie was written */
     iat: number;
 }
@@ -677,8 +682,10 @@ declare class CookieManager {
     getCookieName(): string;
     /**
      * Write a signed session cookie containing user data, roles, and permissions.
-     * The cookie is HMAC-signed with the configured session secret so it is tamper-proof
-     * but readable without a database query. Short TTL (5 min) ensures freshness.
+     * The cookie is HMAC-signed with the configured session secret, so its claims
+     * can be parsed without a database query. Authorization still verifies the
+     * session version and positive family liveness; a valid signature alone is
+     * never a revocation check. Short TTL (5 min) bounds claim staleness.
      */
     setSessionCookie(data: Omit<SessionCookieData, 'iat'>): void;
     /**
@@ -715,6 +722,12 @@ declare class UserRepository {
         role?: string | null;
     }) | undefined>;
     create(data: NewUser): Promise<User>;
+    /**
+     * Ids of everyone holding a role. Used to end sessions when the role's
+     * permission set changes: tokens carry permissions as claims, so the holders
+     * keep exercising the old set until their sessions do.
+     */
+    getIdsByRole(roleId: string): Promise<string[]>;
     update(id: string, data: Partial<NewUser>): Promise<User | undefined>;
     updateLastLogin(id: string): Promise<User>;
     incrementFailedAttempts(id: string): Promise<User>;
@@ -754,6 +767,7 @@ declare class UserValidator {
      * Check if user exists by email
      */
     checkUserExistsByEmail(email: string): Promise<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -762,9 +776,8 @@ declare class UserValidator {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
-        status: "active" | "inactive" | "pending";
+        status: "active" | "pending" | "inactive";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -776,6 +789,7 @@ declare class UserValidator {
      * Check if email exists in database
      */
     checkEmailExists(email: string): Promise<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -784,9 +798,8 @@ declare class UserValidator {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
-        status: "active" | "inactive" | "pending";
+        status: "active" | "pending" | "inactive";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -948,64 +961,6 @@ declare class RoleService {
     getRoleIdByName(name: any): Promise<string>;
 }
 
-type SanitizedUser = Omit<User, 'password' | 'failedLoginAttempts' | 'lockoutUntil'> & {
-    role?: string | null;
-    permissions?: string[];
-};
-declare class UserService {
-    private roleValidator;
-    private roleService;
-    private userRepository;
-    private userValidator;
-    private encryptionService;
-    private i18nService;
-    private authConfig;
-    private t;
-    constructor(roleValidator: RoleValidator, roleService: RoleService, userRepository: UserRepository, userValidator: UserValidator, encryptionService: EncryptionService, i18nService: I18nService, authConfig: AuthConfig);
-    private sanitizeUser;
-    private sanitizeUsers;
-    private requireUser;
-    private resolveUserRole;
-    getAll(options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<SanitizedUser[]>;
-    getById(id: string): Promise<SanitizedUser>;
-    getByEmail(email: string): Promise<SanitizedUser>;
-    /**
-     * Find user by email without throwing - returns null if not found
-     * Used for timing-safe authentication
-     */
-    findByEmail(email: string): Promise<(User & {
-        role?: string | null;
-    }) | undefined>;
-    findByEmailInsensitive(email: string): Promise<(User & {
-        role?: string | null;
-    }) | undefined>;
-    findByPhone(phone: string): Promise<UserWithPermissions>;
-    getAuthRecordById(id: string): Promise<User | undefined>;
-    create(data: Record<string, any>, options?: {
-        validatePasswordStrength?: boolean;
-    }): Promise<SanitizedUser>;
-    update(id: string, data: Record<string, any>): Promise<SanitizedUser>;
-    delete(id: string): Promise<SanitizedUser>;
-    deleteAll(): Promise<SanitizedUser[]>;
-    getRoleName(id: string): Promise<string | null>;
-    updateLastLogin(id: string): Promise<void>;
-    incrementFailedAttempts(id: string): Promise<number>;
-    resetFailedAttempts(id: string): Promise<void>;
-    setLockout(id: string, until: string): Promise<void>;
-    assignRole(id: string, roleId?: string, roleName?: string): Promise<SanitizedUser>;
-    removeRole(id: string): Promise<SanitizedUser>;
-    seedAdminUser(config?: {
-        email?: string;
-        password?: string;
-        name?: string;
-    }): Promise<SanitizedUser>;
-    updateLang(language: string): Promise<string>;
-    getLang(): Promise<string>;
-}
-
 declare class TokenRepository {
     db: TDb;
     private schema;
@@ -1031,7 +986,7 @@ declare class TokenRepository {
     }): Promise<any>;
     /**
      * Rotate an existing refresh-token family with compare-and-swap semantics.
-     * This can never insert a family deleted by a concurrent logout.
+     * This can never update a family durably revoked by a concurrent logout.
      */
     rotateRefreshToken(tokenData: {
         userId: string;
@@ -1054,9 +1009,15 @@ declare class TokenRepository {
     markPreviousUsed(tokenFamily: string, previousHash: string): Promise<any>;
     /** Look up a single session's token row by its family identifier. */
     getByFamily(tokenFamily: string): Promise<any>;
-    /** Revoke a single session (one family). */
+    /**
+     * Durably revoke one family without depending on physical deletion.
+     *
+     * The row remains as a tombstone until its original refresh expiry. This is
+     * what prevents a later cache loss from turning a failed/omitted cleanup
+     * delete into a valid database-backed recovery session.
+     */
     revokeFamily(tokenFamily: string): Promise<any>;
-    /** Revoke every session for a user (password change/reset, logout-all). */
+    /** Durably revoke every active family for a user. */
     revokeAllForUser(userId: string): Promise<any>;
     /**
      * Opportunistic cleanup: with one row per family (no unique userId), expired
@@ -1073,6 +1034,193 @@ declare class TokenRepository {
     getUser(userId: string): Promise<any>;
 }
 
+/**
+ * The single owner of "this credential is no longer good".
+ *
+ * Every path that changes a user's security state — status, password, role,
+ * permissions, deletion — has to reach the same code, or one of them will be
+ * forgotten and an already-issued token will outlive the change that was
+ * supposed to end it. That is the shape of the defect this service closes.
+ *
+ * It deliberately depends on the repository rather than TokenService: TokenService
+ * needs to call it too, and going through the service would close a DI cycle.
+ */
+declare class SessionInvalidationService {
+    private cache;
+    private tokens;
+    private config;
+    constructor(cache: CacheService, tokens: TokenRepository);
+    /**
+     * Fields whose change ends existing sessions. Everything absent from this set
+     * — display name, avatar, language — is a profile edit and must leave the
+     * user signed in, on every device.
+     */
+    static readonly SECURITY_FIELDS: readonly ["password", "status", "role", "roleId", "email", "emailVerified", "phone"];
+    /** Whether an update payload touches anything that must end sessions. */
+    static affectsSecurityState(data: Record<string, unknown> | null | undefined): boolean;
+    private get accessTokenTtlMs();
+    private get refreshTokenTtlMs();
+    sessionVersionKey(userId: string): string;
+    revokedFamilyKey(tokenFamily: string): string;
+    /**
+     * Positive liveness marker for one session family.
+     *
+     * The signed session snapshot is authorized against this rather than against
+     * the absence of a revocation marker, so losing the cache cannot make a
+     * logged-out family look valid again: with no marker the fast path simply
+     * declines and the request falls through to the database-backed resolver.
+     */
+    familyKey(tokenFamily: string): string;
+    userCacheKey(userId: string): string;
+    parseSessionVersion(raw: string | null): number;
+    getSessionVersion(userId: string): Promise<number>;
+    /**
+     * Extend the version key's lifetime without rewriting its value.
+     *
+     * Token issuance used to `set()` the version it had just read, which meant an
+     * invalidation landing between that read and that write was silently undone —
+     * the revoked version came back and the old tokens verified again. Only the
+     * expiry is touched here, so a concurrent bump always survives.
+     */
+    touchSessionVersion(userId: string): Promise<void>;
+    /**
+     * Invalidate every access token already issued for a user, and drop the
+     * cached user record so the next read sees the new state rather than a stale
+     * snapshot that is merely truthy.
+     *
+     * The bump is an atomic increment, so concurrent invalidations cannot read
+     * the same version and write the same successor back.
+     */
+    invalidateAccessTokens(userId: string): Promise<number>;
+    dropUserCache(userId: string): Promise<void>;
+    /**
+     * End every session a user holds: access tokens by version, refresh sessions
+     * by row, and each family's liveness marker.
+     *
+     * Callers run this AFTER their database mutation has committed. Running it
+     * before would leave a window in which a concurrent login re-established a
+     * session against the state the mutation was about to remove; running it
+     * after a rollback merely signs the user out again, which is safe.
+     */
+    invalidateUser(userId: string): Promise<void>;
+    /**
+     * Record that a family is live, and whose it is. Called wherever the family's
+     * refresh row is written.
+     *
+     * The marker stores the owning user rather than a bare flag so a reader can
+     * confirm, in the same single lookup, that the family it was handed actually
+     * belongs to the identity claiming it.
+     *
+     * Revocation always wins. A refresh that rotated its row, was descheduled,
+     * and resumed after a logout would otherwise re-mark its family live and
+     * hand the browser back the session it had just ended — the database row is
+     * gone by then, but nothing on the fast path reads the database. So this
+     * writes, then re-reads the revocation marker and withdraws the write if one
+     * appeared. Combined with `markFamilyRevoked` setting the revocation marker
+     * *before* clearing liveness, every interleaving of the two converges on
+     * revoked: whichever of the pair observes the other, the liveness key ends
+     * up deleted.
+     *
+     * @returns whether the family is live after this call.
+     */
+    markFamilyIssued(tokenFamily: string, userId: string): Promise<boolean>;
+    /**
+     * What one lookup can say about a family, in a single batched cache read.
+     *
+     * The three answers are deliberately distinct. `revoked` is authoritative and
+     * must deny. `unknown` means the cache cannot vouch for the family — it was
+     * evicted, or the cache was lost — and must send the caller to an
+     * authoritative, database-backed check rather than being read either way.
+     * Only `live` is a positive assertion, and only for the named user.
+     */
+    familyStatus(tokenFamily: string | undefined, userId?: string): Promise<'live' | 'revoked' | 'unknown'>;
+    /**
+     * Whether a family is positively known to be live, and — when a user is
+     * given — to belong to that user.
+     *
+     * `false` means "not proven live" — revoked, mismatched, or simply not in
+     * cache. Callers must treat it as a reason to fall back to an authoritative
+     * check, never as proof of validity in the other direction.
+     */
+    isFamilyLive(tokenFamily: string, userId?: string): Promise<boolean>;
+    private readMany;
+    /**
+     * Keep revocation through both credential lifetimes. If deleting the refresh
+     * row fails, its still-valid cookie must remain denied after access expires.
+     */
+    markFamilyRevoked(tokenFamily: string): Promise<void>;
+    isFamilyRevoked(tokenFamily: string): Promise<boolean>;
+}
+
+type SanitizedUser = Omit<User, 'password' | 'failedLoginAttempts' | 'lockoutUntil'> & {
+    role?: string | null;
+    permissions?: string[];
+};
+declare class UserService {
+    private roleValidator;
+    private roleService;
+    private userRepository;
+    private userValidator;
+    private encryptionService;
+    private i18nService;
+    private authConfig;
+    private sessionInvalidation?;
+    private t;
+    constructor(roleValidator: RoleValidator, roleService: RoleService, userRepository: UserRepository, userValidator: UserValidator, encryptionService: EncryptionService, i18nService: I18nService, authConfig: AuthConfig, sessionInvalidation?: SessionInvalidationService);
+    /**
+     * End the user's sessions after a security-relevant mutation has committed.
+     *
+     * Deactivating, deleting, or re-roling an account through the generic
+     * endpoints used to leave every already-issued token working until it
+     * expired. Invalidation belongs here, next to the write, so no caller can
+     * forget it — the application-level commands that already revoke keep doing
+     * so, and a second call is harmless.
+     */
+    private invalidateSessions;
+    private sanitizeUser;
+    private sanitizeUsers;
+    private requireUser;
+    private resolveUserRole;
+    getAll(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SanitizedUser[]>;
+    getById(id: string): Promise<SanitizedUser>;
+    getByEmail(email: string): Promise<SanitizedUser>;
+    /**
+     * Find user by email without throwing - returns null if not found
+     * Used for timing-safe authentication
+     */
+    findByEmail(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
+    findByEmailInsensitive(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
+    findByPhone(phone: string): Promise<UserWithPermissions>;
+    getAuthRecordById(id: string): Promise<User | undefined>;
+    create(data: Record<string, any>, options?: {
+        validatePasswordStrength?: boolean;
+    }): Promise<SanitizedUser>;
+    update(id: string, data: Record<string, any>): Promise<SanitizedUser>;
+    delete(id: string): Promise<SanitizedUser>;
+    deleteAll(): Promise<SanitizedUser[]>;
+    getRoleName(id: string): Promise<string | null>;
+    updateLastLogin(id: string): Promise<void>;
+    incrementFailedAttempts(id: string): Promise<number>;
+    resetFailedAttempts(id: string): Promise<void>;
+    setLockout(id: string, until: string): Promise<void>;
+    assignRole(id: string, roleId?: string, roleName?: string): Promise<SanitizedUser>;
+    removeRole(id: string): Promise<SanitizedUser>;
+    seedAdminUser(config?: {
+        email?: string;
+        password?: string;
+        name?: string;
+    }): Promise<SanitizedUser>;
+    updateLang(language: string): Promise<string>;
+    getLang(): Promise<string>;
+}
+
 declare class CredentialSetupRequirementRepository {
     private db;
     private schema;
@@ -1085,22 +1233,28 @@ declare class CredentialSetupRequirementRepository {
     complete(userId: string, purpose: string): Promise<CredentialSetupRequirementRow | undefined>;
 }
 
+type SetPasswordTokenType = 'reset' | 'invite';
+interface ConsumedSetPasswordToken {
+    userId: string;
+    type: SetPasswordTokenType;
+}
 declare class TokenService {
     private tokenRepository;
     private cookieManager;
     private cache;
     private credentialSetupRequirements?;
+    private sessions?;
     private config;
     private t;
-    constructor(tokenRepository: TokenRepository, cookieManager: CookieManager, cache: CacheService, credentialSetupRequirements?: CredentialSetupRequirementRepository);
+    constructor(tokenRepository: TokenRepository, cookieManager: CookieManager, cache: CacheService, credentialSetupRequirements?: CredentialSetupRequirementRepository, sessions?: SessionInvalidationService);
+    /** The shared invalidation contract — see SessionInvalidationService. */
+    private get invalidation();
     /**
      * Get blacklist key prefix
      */
     private get blacklistPrefix();
     private get resetTokenPrefix();
-    private get sessionVersionPrefix();
     private sessionVersionKey;
-    private accessTokenTtlMs;
     private expiresAt;
     private getCacheValues;
     private parseSessionVersion;
@@ -1117,6 +1271,7 @@ declare class TokenService {
     private static readonly PREVIOUS_GRACE_SECONDS;
     private clearRefreshSessionCookies;
     private rejectRefreshSession;
+    private assertRefreshFamilyAllowed;
     private readRefreshSessionCookie;
     /**
      * Read the refresh cookie and return the userId it belongs to.
@@ -1143,8 +1298,20 @@ declare class TokenService {
         roles: any[];
         permissions: any;
         sessionVersion: number;
+        tokenFamily: string;
     }>;
     getUser(auth: string): Promise<any>;
+    /**
+     * A user record is only an authorization if the account is still usable.
+     *
+     * A valid signature and an unrevoked version say the *token* is intact; they
+     * say nothing about whether the account behind it was since deactivated or
+     * deleted. Session invalidation is what normally ends such a token, but this
+     * check is what makes a truthy cached record insufficient on its own — so a
+     * missed invalidation, or a record filled into cache moments before the
+     * change, still cannot authorize a request.
+     */
+    private requireActiveUser;
     getUserById(userId: string): Promise<any>;
     private hashToken;
     getTokenExpire(token: string): number | undefined;
@@ -1156,9 +1323,22 @@ declare class TokenService {
      * session was invalidated after it was written.
      */
     getSessionVersion(userId: string): Promise<number>;
+    /**
+     * Whether one session family is positively known to be live.
+     *
+     * `false` means "not proven live" — logged out, or simply not in cache — and
+     * is a reason to fall back to an authoritative check, never on its own a
+     * reason to treat a session as valid.
+     */
+    isSessionFamilyLive(tokenFamily: string | undefined, userId?: string): Promise<boolean>;
     /**
      * Generate access token with unique jti for blacklist support.
      * Includes roles/permissions for client-side RBAC/PBAC.
+     *
+     * The token only verifies while its `tokenFamily` is a live session — see
+     * verifyAccessToken. A token minted without one, or for a family that has
+     * been revoked, is refused by design rather than trusted on its signature.
+     * Use generateTokens() to establish a family.
      */
     generateAccessToken(data: {
         userId: string;
@@ -1233,30 +1413,24 @@ declare class TokenService {
     revokeFamily(tokenFamily: string): Promise<any>;
     /**
      * Opportunistic cleanup of expired/abandoned sessions. With one row per
-     * family (no unique userId), abandoned logins would otherwise accumulate.
+     * family (no unique userId), expired live rows and revocation tombstones
+     * would otherwise accumulate.
      * Best-effort — never let cleanup failure break the calling flow.
      */
     deleteExpiredSessions(): Promise<void>;
     invalidateUserAccessTokens(userId: string): Promise<number>;
     getUserFromCookie(): Promise<any>;
-    private get revokedFamilyPrefix();
     private revokedFamilyKey;
-    /**
-     * Mark a family as revoked in cache for the access-token TTL, so every
-     * access token minted for that family (not just the presented one) is
-     * rejected by verifyAccessToken until it would have expired anyway.
-     */
-    private markFamilyRevoked;
     /**
      * Revoke only the suspect family — NOT the whole user. Bumping the global
      * per-user session version here would kill every device's access tokens on a
-     * single family's reuse detection. Instead drop the family's refresh row and
-     * mark the family revoked so its access tokens stop verifying.
+     * single family's reuse detection. Instead durably mark the family revoked
+     * so database recovery and its access tokens both stop verifying.
      */
     private revokeSuspectRefreshFamily;
     /**
      * Logout the CURRENT session only — blacklist the presented access token,
-     * mark its family revoked, and delete that family's refresh row. Other
+     * mark its family revoked in cache and durably in the token row. Other
      * devices/sessions for the same user keep working. Use a password change or
      * reset (revoke-all) to terminate every session.
      *
@@ -1296,8 +1470,26 @@ declare class TokenService {
         userId: string;
     }>;
     /**
-     * Verify password reset token
-     * Returns userId if valid, throws error if expired/invalid
+     * Verify and CONSUME a password reset or invite token.
+     *
+     * Consumption is a single atomic compare-and-delete, so exactly one of any
+     * number of concurrent callers holding the same link is told to proceed. The
+     * earlier `get()` then `del()` pair left a window in which two callers both
+     * read the same jti, both passed, and both went on to set a password.
+     *
+     * The comparison also means a stale token cannot delete the jti of a newer
+     * one that superseded it — the newer link keeps working.
+     *
+     * Callers must finish validating the replacement password BEFORE calling
+     * this: consumption is deliberately irreversible, so a token burned by a
+     * request that then failed validation would cost the user their link for
+     * nothing.
+     */
+    consumeSetPasswordToken(token: string): Promise<ConsumedSetPasswordToken>;
+    /**
+     * Backward-compatible user-id-only reset/invite token consumption.
+     * Prefer `consumeSetPasswordToken()` when the caller must distinguish an
+     * account invitation from an ordinary password reset.
      */
     verifyResetToken(token: string): Promise<string>;
     private getUserSessionVersion;
@@ -1312,8 +1504,8 @@ declare const createUserDto: z.ZodObject<{
     emailVerified: z.ZodDefault<z.ZodBoolean>;
     status: z.ZodOptional<z.ZodEnum<{
         active: "active";
-        inactive: "inactive";
         pending: "pending";
+        inactive: "inactive";
     }>>;
 }, z.core.$strip>;
 declare const updateUserDto: z.ZodObject<{
@@ -1325,8 +1517,8 @@ declare const updateUserDto: z.ZodObject<{
     emailVerified: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     status: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
         active: "active";
-        inactive: "inactive";
         pending: "pending";
+        inactive: "inactive";
     }>>>;
 }, z.core.$strip>;
 declare const registerDto: z.ZodObject<{
@@ -1696,19 +1888,24 @@ declare class AuthService {
 }
 
 /**
- * Composite key: resolved client address + hashed normalized identity.
- * Buckets rate limits per client+credential combo so different users
- * on the same address (e.g. localhost, NAT) don't share a single bucket.
- *
- * The address arrives already resolved through the configured trusted-proxy
- * boundary; this module must never parse forwarding headers itself.
+ * Login's bucket. `loginDto` accepts either field, and the service reads
+ * `identifier` first, so the key follows the same order.
  */
 declare const authIdentityRateLimitKey: (ctx: Context, keyContext?: RateLimitKeyContext) => Promise<string>;
+/**
+ * Bucket for routes whose DTO declares `email` and nothing else — password
+ * reset requests and public registration. Deliberately does NOT fall back to
+ * `identifier`: that field is discarded by validation, so honouring it would
+ * hand a caller a fresh allowance per invented value while every request still
+ * targeted the one email the handler reads.
+ */
+declare const authEmailRateLimitKey: (ctx: Context, keyContext?: RateLimitKeyContext) => Promise<string>;
 declare class AuthController {
     private authService;
     constructor(authService: AuthService);
     loginUser(body: LoginDto): Promise<LoginResult>;
     inviteUser(body: InviteUserDto): Promise<Omit<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -1717,9 +1914,8 @@ declare class AuthController {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
-        status: "active" | "inactive" | "pending";
+        status: "active" | "pending" | "inactive";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -1742,6 +1938,7 @@ declare class AuthController {
         message: string;
     }>;
     userProfile(authorization?: string): Promise<Omit<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -1750,9 +1947,8 @@ declare class AuthController {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
-        status: "active" | "inactive" | "pending";
+        status: "active" | "pending" | "inactive";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -1772,6 +1968,14 @@ declare class AuthController {
 }
 
 declare class AuthGuard {
+    /**
+     * A resolved principal is not automatically an authorized one.
+     *
+     * The resolvers ahead of this guard already reject deactivated accounts, so
+     * this is the backstop for anything that publishes a principal by another
+     * route: a truthy user record must still be an active one to pass. Records
+     * whose projection omits `status` are unchanged.
+     */
     canActivate(user: any): boolean;
 }
 declare const isAuth: () => ClassDecorator & MethodDecorator;
@@ -2096,7 +2300,18 @@ declare class PermissionService {
     private permissionRepository;
     private permissionValidator;
     private roleService;
-    constructor(permissionRepository: PermissionRepository, permissionValidator: PermissionValidator, roleService: RoleService);
+    private userRepository?;
+    private sessionInvalidation?;
+    constructor(permissionRepository: PermissionRepository, permissionValidator: PermissionValidator, roleService: RoleService, userRepository?: UserRepository, sessionInvalidation?: SessionInvalidationService);
+    /**
+     * End the sessions of everyone holding a role whose permission set changed.
+     *
+     * Access tokens and signed session snapshots both carry permissions as
+     * claims, so a permission removed from a role stays exercisable until the
+     * sessions that captured it end. This is an infrequent administrative
+     * action, and the work is proportional to the role's membership.
+     */
+    private invalidateRoleHolders;
     getAll(): Promise<{
         id: string;
         name: string;
@@ -2833,4 +3048,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, AUTH_CORE_MODULE, en as AUTH_EN, AUTH_LOCALES, AUTH_LOGIN_RATE_LIMIT_ENV, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthLoginRateLimitConfig, type AuthPluginConfig, AuthQueries, type AuthRateLimitEnvironment, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_CODES, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupChangeDto, type CredentialSetupCode, type CredentialSetupConfig, CredentialSetupController, type CredentialSetupOptions, type CredentialSetupPasswordOptions, type CredentialSetupPending, CredentialSetupRepository, CredentialSetupRequirementRepository, type CredentialSetupRequirementRow, CredentialSetupRequirementService, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, DEFAULT_AUTH_LOGIN_RATE_LIMIT, DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME, DEFAULT_CREDENTIAL_SETUP_TTL_MS, type DefineRolesOptions, type EmailParam, EncryptionService, type GitHubOAuthConfig, type GoogleOAuthConfig, IdentityConfig, type IdentityResolver, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, type LoginResult, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, PASSWORD_SETUP_PURPOSE, PUBLIC_REGISTRATION_MODULE, PasswordSetupService, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, type ProvisionUserWithPasswordInput, type ProvisionUserWithSetupInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, RegistrationController, type ResetPasswordDto, type ResolvedCredentialSetupConfig, ResolvedIdentityConfig, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createIdentityResolver, createPermissionDto, createRoleDto, createTokenDto, createUserDto, credentialSetupChangeDto, credentialSetupError, defaultCredentialSetupPasswordSchema, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, normalizeSetupPurpose, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, resolveAuthLoginRateLimitConfig, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };
+export { AUTH_CONFIG, AUTH_CORE_MODULE, en as AUTH_EN, AUTH_LOCALES, AUTH_LOGIN_RATE_LIMIT_ENV, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthLoginRateLimitConfig, type AuthPluginConfig, AuthQueries, type AuthRateLimitEnvironment, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_CODES, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, type ConsumedSetPasswordToken, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupChangeDto, type CredentialSetupCode, type CredentialSetupConfig, CredentialSetupController, type CredentialSetupOptions, type CredentialSetupPasswordOptions, type CredentialSetupPending, CredentialSetupRepository, CredentialSetupRequirementRepository, type CredentialSetupRequirementRow, CredentialSetupRequirementService, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, DEFAULT_AUTH_LOGIN_RATE_LIMIT, DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME, DEFAULT_CREDENTIAL_SETUP_TTL_MS, type DefineRolesOptions, type EmailParam, EncryptionService, type GitHubOAuthConfig, type GoogleOAuthConfig, IdentityConfig, type IdentityResolver, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, type LoginResult, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, PASSWORD_SETUP_PURPOSE, PUBLIC_REGISTRATION_MODULE, PasswordSetupService, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, type ProvisionUserWithPasswordInput, type ProvisionUserWithSetupInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, RegistrationController, type ResetPasswordDto, type ResolvedCredentialSetupConfig, ResolvedIdentityConfig, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, SessionInvalidationService, type SetPasswordTokenType, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authEmailRateLimitKey, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createIdentityResolver, createPermissionDto, createRoleDto, createTokenDto, createUserDto, credentialSetupChangeDto, credentialSetupError, defaultCredentialSetupPasswordSchema, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, normalizeSetupPurpose, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, resolveAuthLoginRateLimitConfig, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };