najm-auth 1.1.44 → 2.0.1

package/README.md

@@ -503,11 +503,13 @@ await seedAuthData({
 
 ---
 
-## Rate Limiting
-
-Auth routes have built-in rate limiting to prevent brute force attacks.
-
-| Route | Limit | Window | Key Strategy |
+## Rate Limiting
+
+Auth routes have built-in rate limiting to prevent brute force attacks.
+The auth plugin registers `najm-rate` as a dependency, so these decorator-level
+limits are active when `auth()` is registered.
+
+| Route | Limit | Window | Key Strategy |
 |-------|-------|--------|--------------|
 | `POST /auth/register` | 5 | 15 minutes | IP |
 | `POST /auth/login` | 5 | 15 minutes | IP |
@@ -575,9 +577,22 @@ throw new HttpError(403, 'Insufficient permissions for this action');
 
 ---
 
-## Security Considerations
-
-### Password Reset Tokens
+## Security Considerations
+
+### Security Defaults
+
+- JWT access and refresh secrets are required and must pass minimum strength
+  checks.
+- Refresh tokens rotate by session family and suspected family compromise does
+  not revoke unrelated user sessions.
+- Password reset and password change revoke existing user sessions.
+- Login uses a dummy password hash for missing users to reduce timing leaks.
+- Forgot-password responses avoid email enumeration.
+- Auth routes register `najm-rate` and ship route-level brute-force limits.
+- Session cookies are signed, short-lived, and checked against session version
+  invalidation.
+
+### Password Reset Tokens
 
 ⚠️ **Current behavior:** Reset tokens use JWT expiry (default 1h) for single-use validation. To add database-backed single-use tokens:
 

package/dist/client/index.js

@@ -138,7 +138,7 @@ function decodeToken(token) {
 }
 __name(decodeToken, "decodeToken");
 function isTokenExpired(decoded) {
-  if (!decoded.exp) return false;
+  if (!decoded.exp) return true;
   return Date.now() / 1e3 >= decoded.exp;
 }
 __name(isTokenExpired, "isTokenExpired");

package/dist/index.d.ts

@@ -63,6 +63,10 @@ interface AuthConfig {
     frontendUrl: string;
     /** Registration mode: 'active' auto-activates, 'pending' requires admin approval (default: 'active') */
     registrationMode: 'active' | 'pending';
+    /** When true, users with emailVerified=false are blocked from logging in (default: false) */
+    requireVerifiedEmail: boolean;
+    /** Cookie path for the refresh token. Scope to the refresh endpoint to limit exposure (default: '/') */
+    refreshCookiePath: string;
     /** Per-account lockout settings */
     lockout: LockoutConfig;
     /** Bcrypt work factor (default: 10) */
@@ -112,6 +116,10 @@ type AuthPluginConfig = {
     frontendUrl?: string;
     /** Registration mode: 'active' auto-activates new users, 'pending' requires admin approval (default: 'active') */
     registrationMode?: 'active' | 'pending';
+    /** Block login for users whose email is not verified (default: false) */
+    requireVerifiedEmail?: boolean;
+    /** Cookie path for the refresh token (default: '/'). Set e.g. '/auth' to keep it off unrelated routes. */
+    refreshCookiePath?: string;
     /** Per-account lockout settings */
     lockout?: Partial<LockoutConfig>;
     /** Bcrypt work factor (default: 10, valid range: 4-31) */
@@ -199,7 +207,8 @@ var auth = {
 		unauthorized: "Unauthorized access",
 		sessionExpired: "Session has expired",
 		accountLocked: "Account is temporarily locked. Please try again later.",
-		accountInactive: "Account is inactive. Please contact support."
+		accountInactive: "Account is inactive. Please contact support.",
+		emailNotVerified: "Please verify your email address before signing in."
 	},
 	success: {
 		login: "Login successful",
@@ -242,7 +251,9 @@ var roles = {
 		notFound: "Role not found",
 		exists: "Role already exists",
 		nameRequired: "Role name is required",
-		cannotDeleteSystem: "Cannot delete system role"
+		cannotDeleteSystem: "Cannot delete system role",
+		cannotRenameSystem: "Cannot rename the system admin role",
+		roleInUse: "Cannot delete a role that is assigned to users"
 	},
 	success: {
 		created: "Role created successfully",
@@ -302,6 +313,7 @@ declare const AUTH_LOCALES: {
                 sessionExpired: string;
                 accountLocked: string;
                 accountInactive: string;
+                emailNotVerified: string;
             };
             success: {
                 login: string;
@@ -345,6 +357,8 @@ declare const AUTH_LOCALES: {
                 exists: string;
                 nameRequired: string;
                 cannotDeleteSystem: string;
+                cannotRenameSystem: string;
+                roleInUse: string;
             };
             success: {
                 created: string;
@@ -406,6 +420,12 @@ interface SessionCookieData {
     };
     roles: string[];
     permissions: string[];
+    /**
+     * Per-user session version captured when the cookie was written. Lets the
+     * fast-path reader reject a cookie whose session has since been invalidated
+     * (password change/reset, logout-all) without hitting the database.
+     */
+    sessionVersion: number;
     /** Epoch ms when the cookie was written */
     iat: number;
 }
@@ -413,6 +433,7 @@ declare class CookieManager {
     private config;
     private cookieService;
     private get cookieName();
+    private get refreshCookiePath();
     private get sessionCookieName();
     private get sessionMaxAge();
     private get sessionSecret();
@@ -565,6 +586,9 @@ declare class RoleRepository {
     db: TDb;
     private schema;
     private get roles();
+    private get users();
+    /** True if any user currently references this role (blocks deletion). */
+    hasUsers(roleId: string): Promise<boolean>;
     getAll(): Promise<RoleEntity[]>;
     getById(id: string): Promise<RoleEntity | undefined>;
     getByName(name: string): Promise<RoleEntity | undefined>;
@@ -625,6 +649,7 @@ declare class RoleValidator {
 declare class RoleService {
     private roleRepository;
     private roleValidator;
+    private t;
     constructor(roleRepository: RoleRepository, roleValidator: RoleValidator);
     getAll(): Promise<{
         id: string;
@@ -654,14 +679,17 @@ declare class RoleService {
         createdAt: string;
         updatedAt: string;
     }>;
-    update(id: any, data: any): Promise<{
+    update(id: string, data: {
+        name?: string;
+        description?: string;
+    }): Promise<{
         id: string;
         name: string;
         description: string;
         createdAt: string;
         updatedAt: string;
     }>;
-    delete(id: any): Promise<{
+    delete(id: string): Promise<{
         id: string;
         name: string;
         description: string;
@@ -831,6 +859,12 @@ declare class TokenService {
     getTokenExpire(token: string): number | undefined;
     decodeAccessToken(token: string): JwtPayload | null;
     private signAccessToken;
+    /**
+     * Current per-user session version (0 when never invalidated). The signed
+     * session cookie stamps this so a fast-path reader can reject a cookie whose
+     * session was invalidated after it was written.
+     */
+    getSessionVersion(userId: string): Promise<number>;
     /**
      * Generate access token with unique jti for blacklist support.
      * Includes roles/permissions for client-side RBAC/PBAC.
@@ -855,6 +889,7 @@ declare class TokenService {
         tokenFamily: string;
         roles: string[];
         permissions: string[];
+        sessionVersion: number;
         accessToken: string;
         refreshToken: string;
         accessTokenExpiresAt: number;
@@ -888,6 +923,7 @@ declare class TokenService {
         tokenFamily: string;
         roles: string[];
         permissions: string[];
+        sessionVersion: number;
         accessToken: string;
         refreshToken: string;
         accessTokenExpiresAt: number;
@@ -995,6 +1031,12 @@ declare const updateUserDto: z.ZodObject<{
         inactive: "inactive";
     }>>>;
 }, z.core.$strip>;
+declare const registerDto: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    email: z.ZodString;
+    password: z.ZodString;
+    image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
 declare const inviteUserDto: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     email: z.ZodString;
@@ -1038,6 +1080,7 @@ declare const userListQuery: z.ZodObject<{
 }, z.core.$strip>;
 type CreateUserDto = z.infer<typeof createUserDto>;
 type UpdateUserDto = z.infer<typeof updateUserDto>;
+type RegisterDto = z.infer<typeof registerDto>;
 type InviteUserDto = z.infer<typeof inviteUserDto>;
 type UserIdParam = z.infer<typeof userIdParam>;
 type LoginDto = z.infer<typeof loginDto>;
@@ -1080,7 +1123,7 @@ declare class AuthService {
     private nextLockoutUntil;
     private getDummyHash;
     warmupPasswordHash(): Promise<void>;
-    registerUser(body: CreateUserDto): Promise<SanitizedUser>;
+    registerUser(body: RegisterDto): Promise<SanitizedUser>;
     /**
      * Admin-initiated account creation. The user is created with a random,
      * unusable password (the schema requires one) and then emailed a one-time
@@ -1090,7 +1133,9 @@ declare class AuthService {
      * Email is best-effort: a send failure logs a warning but never rolls back
      * account creation (and with the console provider, nothing is actually sent).
      */
-    inviteUser(body: ProvisionUserInput): Promise<SanitizedUser>;
+    inviteUser(body: ProvisionUserInput): Promise<SanitizedUser & {
+        emailSent: boolean;
+    }>;
     /**
      * Create a login for a person record. The branch is intentional and is the
      * single rule callers rely on:
@@ -1147,11 +1192,32 @@ declare class AuthService {
 declare class AuthController {
     private authService;
     constructor(authService: AuthService);
-    registerUser(body: CreateUserDto): Promise<SanitizedUser>;
+    registerUser(body: RegisterDto): Promise<SanitizedUser>;
     loginUser(body: LoginDto): Promise<TokenPair & {
         user: SanitizedUser;
     }>;
-    inviteUser(body: InviteUserDto): Promise<SanitizedUser>;
+    inviteUser(body: InviteUserDto): Promise<Omit<{
+        id: string;
+        name: string;
+        createdAt: string;
+        updatedAt: string;
+        email: string;
+        emailVerified: boolean;
+        phone: string;
+        phoneVerified: boolean;
+        password: string;
+        image: string;
+        status: "active" | "pending" | "inactive";
+        roleId: string;
+        lastLogin: string;
+        failedLoginAttempts: number;
+        lockoutUntil: string;
+    }, "password" | "failedLoginAttempts" | "lockoutUntil"> & {
+        role?: string | null;
+        permissions?: string[];
+    } & {
+        emailSent: boolean;
+    }>;
     refreshTokens(): Promise<TokenPair>;
     logoutUser(userId: string, authorization?: string): Promise<{
         data: any;
@@ -2131,4 +2197,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 InviteUserDto, 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, type ProvisionUserInput, 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, inviteUserDto, 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 };
+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 InviteUserDto, 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, type ProvisionUserInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, 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, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };