najm-auth 1.1.38 → 1.1.39

package/README.md

@@ -121,8 +121,9 @@ auth({
   database?: string                        // Default: 'default'
   blacklistPrefix?: string                 // Default: 'auth:blacklist:'
 
-  // Registration
-  defaultRole?: string | null              // Auto-assign role to new users
+  // Registration
+  defaultRole?: string | null              // Auto-assign role to new users
+  bcryptRounds?: number                    // Default: 10 (valid: 4-31)
 
   // Frontend
   frontendUrl?: string                     // Password reset link base URL
@@ -155,7 +156,7 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `GET` | `/users` | List all users |
+| `GET` | `/users?limit=50&offset=0` | List users (limit 1-100) |
 | `GET` | `/users/:id` | Get user by ID |
 | `POST` | `/users` | Create new user |
 | `PUT` | `/users/:id` | Update user |
@@ -510,8 +511,8 @@ Auth routes have built-in rate limiting to prevent brute force attacks.
 |-------|-------|--------|--------------|
 | `POST /auth/register` | 5 | 15 minutes | IP |
 | `POST /auth/login` | 5 | 15 minutes | IP |
-| `GET /auth/refresh` | 10 | 15 minutes | IP |
-| `GET /auth/logout` | 10 | 15 minutes | User ID |
+| `POST /auth/refresh` | 15 | 15 minutes | Cookie fingerprint |
+| `POST /auth/logout` | 10 | 15 minutes | User ID |
 | `GET /auth/me` | 30 | 1 minute | User ID |
 | `POST /auth/forgot-password` | 3 | 15 minutes | IP |
 | `POST /auth/reset-password` | 5 | 15 minutes | IP |
@@ -590,17 +591,20 @@ async resetPassword(token: string, newPassword: string) {
 }
 ```
 
-### Session Management
-
-- Single refresh token per user (upsert on login)
-- Previous sessions invalidated on new login
-- Use `@RateLimit` on logout for DDoS protection
+### Session Management
+
+- Sessions are single-device: the token table stores one refresh row per user, so a new login replaces the previous device's refresh session
+- A stale refresh token presented after the 120-second rotation grace window revokes the active refresh session as reuse protection
+- The signed session cookie is accepted for up to its configured TTL (5 minutes by default) without a database or revocation-cache read
+- Use `@RateLimit` on logout for DDoS protection
 
 ### Token Blacklist
 
 - Built-in cache-based blacklist for immediate revocation
 - Supports Redis via `cache()` plugin configuration
-- Default: in-memory store (suitable for single-instance servers)
+- Default: in-memory store (development/single-process only; entries are lost on restart)
+- Use Redis in production when immediate revocation must survive restarts or propagate across instances
+- Session-version revocation keys are cache-backed and TTL-bound to active access tokens
 
 ### Timing Attack Prevention
 
@@ -635,7 +639,8 @@ Test files include:
 - ✅ Set `FRONTEND_URL` environment variable
 - ✅ Enable HTTPS in production
 - ✅ Store secrets in environment variables (never in code)
-- ✅ Use Redis for token blacklist in distributed systems
+- ✅ Use Redis for token blacklist/session-version revocation in production and distributed systems
+- ✅ Trust forwarded IP headers only behind a known proxy; otherwise provide a custom rate-limit key generator
 - ✅ Enable rate limiting on all auth routes
 - ✅ Log authentication events for audit trails
 - ✅ Test ownership scoping rules with multi-user scenarios

package/dist/index.d.ts

@@ -65,6 +65,8 @@ interface AuthConfig {
     registrationMode: 'active' | 'pending';
     /** Per-account lockout settings */
     lockout: LockoutConfig;
+    /** Bcrypt work factor (default: 10) */
+    bcryptRounds: number;
     /** Session cookie cache settings */
     session: SessionCookieConfig;
 }
@@ -104,6 +106,8 @@ type AuthPluginConfig = {
     registrationMode?: 'active' | 'pending';
     /** Per-account lockout settings */
     lockout?: Partial<LockoutConfig>;
+    /** Bcrypt work factor (default: 10, valid range: 4-31) */
+    bcryptRounds?: number;
     /** Session cookie cache settings (optional — sensible defaults applied) */
     session?: Partial<SessionCookieConfig>;
     /** Optional config forwarded to validation() dependency */
@@ -139,13 +143,20 @@ interface TokenPair {
     refreshTokenExpiresAt?: number;
 }
 /**
- * User data structure for authentication
+ * User data structure for authentication.
+ *
+ * This is the minimal contract the `USER` ALS token is guaranteed to satisfy
+ * on every resolution path (Bearer token, refresh cookie, and the signed
+ * session-cookie hot path). Guards and handlers must not rely on fields
+ * outside this contract — the DB-backed paths include more, the session
+ * cookie does not.
  */
 interface AuthUser {
     id: string;
     email: string;
     name?: string | null;
     role?: string;
+    status?: string;
     permissions?: string[];
 }
 
@@ -343,6 +354,7 @@ declare function getAuthLocale(lang: string): Record<string, any>;
 declare const AUTH_SUPPORTED_LANGUAGES: string[];
 
 declare class EncryptionService {
+    private config?;
     private encryptionKey;
     constructor(encryptionKey?: string | null);
     hashPassword(password: string): Promise<string>;
@@ -352,11 +364,13 @@ declare class EncryptionService {
 }
 
 interface SessionCookieData {
+    /** Must satisfy the AuthUser contract — see AuthUser in ../types. */
     user: {
         id: string;
         email: string;
         name?: string | null;
         role?: string;
+        status?: string;
     };
     roles: string[];
     permissions: string[];
@@ -402,24 +416,25 @@ declare class UserRepository {
     private get users();
     private get roles();
     /** Shared query helper */
+    private queryHelper?;
     private get q();
-    getAll(): Promise<UserWithPermissions[]>;
+    getAll(limit?: number, offset?: number): Promise<UserWithPermissions[]>;
     getById(id: string): Promise<UserWithPermissions | undefined>;
+    existsById(id: string): Promise<boolean>;
     getRawById(id: string): Promise<User | undefined>;
     getByEmail(email: string): Promise<(User & {
         role?: string | null;
     }) | undefined>;
     create(data: NewUser): Promise<User>;
-    update(id: string, data: Partial<NewUser>): Promise<User>;
+    update(id: string, data: Partial<NewUser>): Promise<User | undefined>;
     updateLastLogin(id: string): Promise<User>;
     incrementFailedAttempts(id: string): Promise<User>;
     resetFailedAttempts(id: string): Promise<User>;
     setLockout(id: string, until: string): Promise<User>;
-    delete(id: string): Promise<User>;
+    delete(id: string): Promise<User | undefined>;
     deleteAll(): Promise<User[]>;
     getRoleNameById(userId: string): Promise<string | null>;
     findByPhone(phone: string): Promise<UserWithPermissions | undefined>;
-    getUserPassword(email: string): Promise<string | undefined>;
     getUserPermissions(userId: string): Promise<string[]>;
     updatePhone(id: string, phone: string): Promise<User>;
 }
@@ -441,7 +456,7 @@ declare class UserValidator {
     /**
      * Check if user exists by ID
      */
-    checkUserExists(id: string): Promise<UserWithPermissions>;
+    checkUserExists(id: string): Promise<boolean>;
     /**
      * Check if user exists by email
      */
@@ -643,11 +658,16 @@ declare class UserService {
     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(): Promise<SanitizedUser[]>;
+    getAll(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SanitizedUser[]>;
     getById(id: string): Promise<SanitizedUser>;
     getByEmail(email: string): Promise<SanitizedUser>;
     /**
@@ -663,7 +683,6 @@ declare class UserService {
     delete(id: string): Promise<SanitizedUser>;
     deleteAll(): Promise<SanitizedUser[]>;
     getRoleName(id: string): Promise<string | null>;
-    getPassword(email: string): Promise<string | undefined>;
     updateLastLogin(id: string): Promise<void>;
     incrementFailedAttempts(id: string): Promise<number>;
     resetFailedAttempts(id: string): Promise<void>;
@@ -684,8 +703,8 @@ declare class TokenRepository {
     private schema;
     private get tokens();
     private get users();
-    private get roles();
     /** Shared query helper */
+    private queryHelper?;
     private get q();
     storeRefreshToken(tokenData: {
         userId: string;
@@ -696,7 +715,15 @@ declare class TokenRepository {
         previousValidUntil?: string | null;
         previousUsedAt?: string | null;
     }): Promise<any>;
-    markPreviousUsed(userId: string): Promise<any>;
+    /**
+     * Claim the previous-token grace slot. Conditional on BOTH the stored
+     * previousHash still matching the presented token AND previousUsedAt being
+     * NULL. Gating on the hash (not just the flag) closes the rotation race: the
+     * winner's rotation rewrites previousHash via storeRefreshToken, so a loser
+     * whose UPDATE lands after that rotation no longer matches and gets zero
+     * rows — exactly one caller ever claims the slot.
+     */
+    markPreviousUsed(userId: string, previousHash: string): Promise<any>;
     getRefreshTokenWithFamily(userId: string): Promise<any>;
     revokeToken(userId: string): Promise<any>;
     revokeByFamily(tokenFamily: string): Promise<any>;
@@ -723,6 +750,11 @@ declare class TokenService {
     private get blacklistPrefix();
     private get resetTokenPrefix();
     private get sessionVersionPrefix();
+    private sessionVersionKey;
+    private accessTokenTtlMs;
+    private expiresAt;
+    private getCacheValues;
+    private parseSessionVersion;
     extractAccessToken(authorization: string): string;
     /**
      * Verify access token and check blacklist
@@ -731,29 +763,24 @@ declare class TokenService {
     verifyAccessToken(token: string): Promise<JwtPayload>;
     verifyRefreshToken(token: string): string;
     private static readonly PREVIOUS_GRACE_SECONDS;
-    /**
-     * Validate a refresh token as an active session:
-     * 1. Verify JWT signature and type claim
-     * 2. Compare hash against current stored token
-     * 3. If mismatch, check previous hash within short grace window
-     * 4. Reject anything older or outside the grace window
-     */
-    validateRefreshSession(refreshToken: string): Promise<{
-        userId: string;
-        rotatedTokens?: {
-            refreshToken: string;
-            tokenFamily: string;
-        };
-    }>;
     /**
      * Read the refresh cookie and return the userId it belongs to.
      * Validates against current/previous token state with bounded recovery.
      * Throws if the cookie is missing, invalid, or outside the grace window.
+     *
+     * Intentionally side-effect-free: unlike refreshTokens(), a mismatch here
+     * does NOT revoke the suspect family. This is a read path (e.g. GET
+     * /auth/me) — a stray stale cookie on a read must not be able to destroy
+     * the active session. Reuse detection and revocation belong to the
+     * rotation path only.
      */
     resolveUserFromCookie(): Promise<string>;
     getUser(auth: string): Promise<any>;
+    getUserById(userId: string): Promise<any>;
     private hashToken;
     getTokenExpire(token: string): number | undefined;
+    decodeAccessToken(token: string): JwtPayload | null;
+    private signAccessToken;
     /**
      * Generate access token with unique jti for blacklist support.
      * Includes roles/permissions for client-side RBAC/PBAC.
@@ -766,10 +793,14 @@ declare class TokenService {
     /**
      * Generate refresh token with unique jti
      */
+    private signRefreshToken;
     generateRefreshToken(data: {
         userId: string;
     }): string;
     generateTokens(userId: string, tokenFamily?: string): Promise<{
+        userId: string;
+        roles: string[];
+        permissions: string[];
         accessToken: string;
         refreshToken: string;
         accessTokenExpiresAt: number;
@@ -799,6 +830,9 @@ declare class TokenService {
      * Compares provided token with hashed version in database
      */
     refreshTokens(): Promise<{
+        userId: string;
+        roles: string[];
+        permissions: string[];
         accessToken: string;
         refreshToken: string;
         accessTokenExpiresAt: number;
@@ -806,6 +840,8 @@ declare class TokenService {
     }>;
     revokeToken(userId: string): Promise<any>;
     invalidateUserAccessTokens(userId: string): Promise<number>;
+    getUserFromCookie(): Promise<any>;
+    private revokeSuspectRefreshFamily;
     /**
      * Logout user - blacklist access token and revoke refresh token
      */
@@ -883,6 +919,10 @@ declare const assignRoleParams: z.ZodObject<{
     userId: z.ZodString;
     roleId: z.ZodString;
 }, z.core.$strip>;
+declare const userListQuery: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
 type CreateUserDto = z.infer<typeof createUserDto>;
 type UpdateUserDto = z.infer<typeof updateUserDto>;
 type UserIdParam = z.infer<typeof userIdParam>;
@@ -894,26 +934,25 @@ type LanguageParam = z.infer<typeof languageParam>;
 type EmailParam = z.infer<typeof emailParam>;
 type UserIdInParam = z.infer<typeof userIdInParam>;
 type AssignRoleParams = z.infer<typeof assignRoleParams>;
+type UserListQuery = z.infer<typeof userListQuery>;
 
 declare class AuthService {
     private tokenService;
     private userService;
     private userValidator;
+    private encryptionService;
     private cookieManager;
     private i18nService;
     private emailService;
     private config;
     private t;
     private logger;
-    private static readonly DUMMY_HASH;
-    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService);
+    private dummyHash?;
+    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, encryptionService: EncryptionService, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService);
     private isLockoutActive;
     private nextLockoutUntil;
-    /**
-     * Decode JWT payload without verification (token was just generated by us).
-     * Used to extract accurate roles/permissions for the session cookie cache.
-     */
-    private decodeAccessToken;
+    private getDummyHash;
+    warmupPasswordHash(): Promise<void>;
     registerUser(body: CreateUserDto): Promise<SanitizedUser>;
     loginUser(body: LoginDto): Promise<TokenPair & {
         user: SanitizedUser;
@@ -934,10 +973,7 @@ declare class AuthService {
      * fall back to cookie when no Authorization header is present.
      *
      * Refreshes the session cookie cache only when authoritative roles/permissions
-     * are available (from the access token JWT). When called via the refresh-cookie
-     * fallback, we cannot reliably populate permissions without a DB round-trip,
-     * so we leave the existing cache alone — it will be refreshed by the next
-     * login/refresh cycle.
+     * are available from the access token.
      */
     getMe(authorization?: string): Promise<SanitizedUser & {
         language: string;
@@ -953,7 +989,6 @@ declare class AuthService {
     }>;
 }
 
-declare const setConfiguredCookieName: (name: string) => void;
 declare class AuthController {
     private authService;
     constructor(authService: AuthService);
@@ -1013,6 +1048,11 @@ declare class AuthResolver {
         role?: string;
         permissions?: string[];
     } | false>;
+    resolveFromSessionCookie(): Promise<{
+        user: any;
+        role?: string;
+        permissions?: string[];
+    } | false>;
     /**
      * Resolve the current user from the refresh cookie (cookie-only flow,
      * e.g. Next.js Server Components calling /auth/me with just the cookie).
@@ -1027,6 +1067,7 @@ declare class AuthResolver {
         permissions?: string[];
     } | false>;
     activate(): Promise<void>;
+    onReady(): Promise<void>;
 }
 
 interface RunAsUser {
@@ -1691,6 +1732,7 @@ declare class AuthQueries {
         createdAt: any;
         updatedAt: any;
     };
+    getUserWithPermissions(where: any): Promise<any | undefined>;
     /**
      * Get permissions for a user by their userId
      */
@@ -1769,7 +1811,7 @@ type RevokeTokenDto = z.infer<typeof revokeTokenDto>;
 declare class UserController {
     private userService;
     constructor(userService: UserService);
-    getUsers(): Promise<SanitizedUser[]>;
+    getUsers(query: UserListQuery): Promise<SanitizedUser[]>;
     getLang(): Promise<{
         language: string;
     }>;
@@ -1808,6 +1850,8 @@ interface SeedUserConfig {
 interface AuthSeedConfig {
     adminEmail: string;
     adminPass: string;
+    /** Bcrypt work factor (default: 10) */
+    bcryptRounds?: number;
     roles?: Array<{
         name: string;
         description?: string;
@@ -1830,6 +1874,8 @@ interface SeedAuthDataConfig {
     adminEmail: string;
     /** Admin password (required) */
     adminPassword: string;
+    /** Bcrypt work factor (default: 10) */
+    bcryptRounds?: number;
     /** Additional users to seed (optional) */
     users?: SeedUserConfig[];
     /** Custom roles (optional - uses defaults if omitted) */
@@ -1922,4 +1968,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, 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 DefineRolesOptions, type EmailParam, EncryptionService, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, 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, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, setConfiguredCookieName, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, verifyTokenDto, where };
+export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, 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 DefineRolesOptions, type EmailParam, EncryptionService, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, 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, 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, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };