najm-auth 1.1.39 → 1.1.42

package/README.md

@@ -9,7 +9,7 @@ Production-ready authentication and authorization library for the Najm framework
 - ✅ Permission-based access control (PBAC) with wildcards
 - ✅ Row-level ownership scoping for multi-tenant apps
 - ✅ Built-in password reset flow with email support
-- ✅ Multi-dialect support (PostgreSQL, SQLite, MySQL)
+- ✅ Multi-dialect support (PostgreSQL, SQLite)
 - ✅ Type-safe decorators with TypeScript
 - ✅ Rate limiting on auth endpoints
 - ✅ Internationalization (i18n) for all messages
@@ -103,7 +103,7 @@ FRONTEND_URL=https://app.example.com
 ```typescript
 auth({
   // Database
-  dialect?: 'pg' | 'sqlite' | 'mysql'    // Default: 'pg'
+  dialect?: 'pg' | 'sqlite'              // Default: 'pg' (RETURNING-capable engines only)
   schema?: AuthSchema                      // Override dialect schema
 
   // JWT
@@ -121,9 +121,9 @@ auth({
   database?: string                        // Default: 'default'
   blacklistPrefix?: string                 // Default: 'auth:blacklist:'
 
-  // Registration
-  defaultRole?: string | null              // Auto-assign role to new users
-  bcryptRounds?: number                    // Default: 10 (valid: 4-31)
+  // 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
@@ -156,7 +156,7 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 
 | Method | Path | Description |
 |--------|------|-------------|
-| `GET` | `/users?limit=50&offset=0` | List users (limit 1-100) |
+| `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 |
@@ -591,12 +591,12 @@ async resetPassword(token: string, newPassword: string) {
 }
 ```
 
-### 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
+### Session Management
+
+- Sessions are multi-device: the token table stores one refresh row per login session (keyed by a unique `tokenFamily`), so a user can stay logged in on several devices at once. Logout and rotation are scoped to the current session; password change/reset revoke every session
+- A stale refresh token presented after the 120-second rotation grace window revokes only that session's family 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
 

package/dist/index.d.ts

@@ -76,7 +76,7 @@ interface AuthConfig {
  */
 /**
  * Auth schema shape (dialect-agnostic)
- * Import from 'najm-auth/pg', 'najm-auth/sqlite', or 'najm-auth/mysql'
+ * Import from 'najm-auth/pg' or 'najm-auth/sqlite'.
  */
 interface AuthSchema {
     users: any;
@@ -86,9 +86,17 @@ interface AuthSchema {
     rolePermissions: any;
 }
 type AuthPluginConfig = {
-    /** Database dialect (default: 'pg'). Auto-selects the correct schema. */
-    dialect?: 'pg' | 'sqlite' | 'mysql';
-    /** Database schema tables (optional, overrides dialect). Use authSchema from 'najm-auth/sqlite' or 'najm-auth/mysql' */
+    /**
+     * Database dialect (default: 'pg'). Auto-selects the correct schema.
+     * Only RETURNING-capable engines are supported — the auth data layer
+     * relies on `.returning()` for every write. MySQL is not supported.
+     */
+    dialect?: 'pg' | 'sqlite';
+    /**
+     * Database schema tables (optional, overrides dialect). Use authSchema
+     * from 'najm-auth/pg' or 'najm-auth/sqlite'. A custom schema must still be
+     * backed by a RETURNING-capable engine (Postgres or SQLite).
+     */
     schema?: AuthSchema;
     /** JWT configuration (secrets can be set via env vars) */
     jwt?: Partial<JwtConfig>;
@@ -124,6 +132,12 @@ interface JwtPayload {
     userId: string;
     /** Unique token ID for blacklist-based revocation */
     jti: string;
+    /**
+     * Refresh-token session/family identifier. Present on both refresh tokens
+     * (required) and access tokens (so a single family's revocation can reject
+     * every access token minted for that session, not just the presented one).
+     */
+    tokenFamily?: string;
     /** Per-user access token generation version for mass invalidation */
     sessionVersion?: number;
     /** User roles (included for client-side RBAC) */
@@ -194,7 +208,16 @@ var auth = {
 		passwordChanged: "Password changed successfully",
 		passwordResetSent: "If that email exists, a reset link has been sent",
 		passwordReset: "Password has been reset successfully",
+		accountInviteSent: "Invitation sent successfully",
 		tokenRefreshed: "Token refreshed successfully"
+	},
+	emails: {
+		passwordReset: {
+			subject: "Reset your password"
+		},
+		accountInvite: {
+			subject: "You've been invited — set up your account"
+		}
 	}
 };
 var users = {
@@ -287,8 +310,17 @@ declare const AUTH_LOCALES: {
                 passwordChanged: string;
                 passwordResetSent: string;
                 passwordReset: string;
+                accountInviteSent: string;
                 tokenRefreshed: string;
             };
+            emails: {
+                passwordReset: {
+                    subject: string;
+                };
+                accountInvite: {
+                    subject: string;
+                };
+            };
         };
         users: {
             errors: {
@@ -706,6 +738,12 @@ declare class TokenRepository {
     /** Shared query helper */
     private queryHelper?;
     private get q();
+    /**
+     * Upsert the refresh-token row for a session, keyed on `tokenFamily` (the
+     * per-login session identifier, unique). A brand-new login inserts a fresh
+     * family row; a refresh rotation updates only that family's row, leaving the
+     * user's other sessions untouched.
+     */
     storeRefreshToken(tokenData: {
         userId: string;
         token: string;
@@ -716,17 +754,26 @@ declare class TokenRepository {
         previousUsedAt?: string | null;
     }): 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.
+     * Claim the previous-token grace slot for a single family. 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 (and resets previousUsedAt to NULL), so a loser whose
+     * UPDATE lands after that rotation no longer matches and gets zero rows —
+     * exactly one caller ever claims the slot.
+     */
+    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). */
+    revokeFamily(tokenFamily: string): Promise<any>;
+    /** Revoke every session for a user (password change/reset, logout-all). */
+    revokeAllForUser(userId: string): Promise<any>;
+    /**
+     * Opportunistic cleanup: with one row per family (no unique userId), expired
+     * and abandoned sessions accumulate. Delete every expired row.
      */
-    markPreviousUsed(userId: string, previousHash: string): Promise<any>;
-    getRefreshTokenWithFamily(userId: string): Promise<any>;
-    revokeToken(userId: string): Promise<any>;
-    revokeByFamily(tokenFamily: string): Promise<any>;
+    deleteExpired(): Promise<any>;
     isUserExists(userId: string): Promise<boolean>;
     getRoleNameById(userId: string): Promise<string>;
     getUserPermissions(userId: string): Promise<string[]>;
@@ -761,7 +808,10 @@ declare class TokenService {
      * Throws error if token is invalid, expired, or blacklisted
      */
     verifyAccessToken(token: string): Promise<JwtPayload>;
-    verifyRefreshToken(token: string): string;
+    verifyRefreshToken(token: string): {
+        userId: string;
+        tokenFamily: string;
+    };
     private static readonly PREVIOUS_GRACE_SECONDS;
     /**
      * Read the refresh cookie and return the userId it belongs to.
@@ -789,16 +839,20 @@ declare class TokenService {
         userId: string;
         roles?: string[];
         permissions?: string[];
+        tokenFamily?: string;
     }): Promise<string>;
     /**
-     * Generate refresh token with unique jti
+     * Generate refresh token with unique jti. The token carries its session's
+     * family so rotation/revocation can target a single session.
      */
     private signRefreshToken;
     generateRefreshToken(data: {
         userId: string;
+        tokenFamily?: string;
     }): string;
     generateTokens(userId: string, tokenFamily?: string): Promise<{
         userId: string;
+        tokenFamily: string;
         roles: string[];
         permissions: string[];
         accessToken: string;
@@ -831,6 +885,7 @@ declare class TokenService {
      */
     refreshTokens(): Promise<{
         userId: string;
+        tokenFamily: string;
         roles: string[];
         permissions: string[];
         accessToken: string;
@@ -838,14 +893,57 @@ declare class TokenService {
         accessTokenExpiresAt: number;
         refreshTokenExpiresAt: number;
     }>;
-    revokeToken(userId: string): Promise<any>;
+    /** Revoke every refresh session for a user (password change/reset, logout-all). */
+    revokeAllForUser(userId: string): Promise<any>;
+    /** Revoke a single refresh session (one family). */
+    revokeFamily(tokenFamily: string): Promise<any>;
+    /**
+     * Opportunistic cleanup of expired/abandoned sessions. With one row per
+     * family (no unique userId), abandoned logins 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.
+     */
     private revokeSuspectRefreshFamily;
     /**
-     * Logout user - blacklist access token and revoke refresh token
+     * Logout the CURRENT session only — blacklist the presented access token,
+     * mark its family revoked, and delete that family's refresh row. Other
+     * devices/sessions for the same user keep working. Use a password change or
+     * reset (revoke-all) to terminate every session.
+     *
+     * The family is resolved from, in order: a verified Bearer access token's
+     * `tokenFamily` claim, then a verified refresh cookie whose hash still
+     * matches the current family row. If neither is available, fall back to
+     * revoke-all.
      */
     logout(userId: string, authorization?: string): Promise<void>;
+    /**
+     * Resolve a logout target from the refresh cookie only if the cookie maps to
+     * the user's current/valid family row. This mirrors resolveUserFromCookie()
+     * without throwing, because logout can still fall back to revoke-all.
+     */
+    private resolveRefreshCookieFamily;
+    /**
+     * Generate a one-time set-password token (used by both password reset and
+     * account invites). Stores the jti in cache so the token can only be used
+     * once, with a TTL matching the JWT expiry.
+     */
+    private generateSetPasswordToken;
     /**
      * Generate secure password reset token
      * Returns both the plain token (to send via email) and userId for identification
@@ -854,6 +952,15 @@ declare class TokenService {
         token: string;
         userId: string;
     }>;
+    /**
+     * Generate secure account-invite token.
+     * Longer expiry (3d) than reset because an invited user may not check
+     * their email immediately. Consumed via the same reset-password endpoint.
+     */
+    generateInviteToken(userId: string): Promise<{
+        token: string;
+        userId: string;
+    }>;
     /**
      * Verify password reset token
      * Returns userId if valid, throws error if expired/invalid
@@ -888,6 +995,12 @@ declare const updateUserDto: z.ZodObject<{
         inactive: "inactive";
     }>>>;
 }, z.core.$strip>;
+declare const inviteUserDto: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    email: z.ZodString;
+    roleId: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
 declare const userIdParam: z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>;
@@ -925,6 +1038,7 @@ declare const userListQuery: z.ZodObject<{
 }, z.core.$strip>;
 type CreateUserDto = z.infer<typeof createUserDto>;
 type UpdateUserDto = z.infer<typeof updateUserDto>;
+type InviteUserDto = z.infer<typeof inviteUserDto>;
 type UserIdParam = z.infer<typeof userIdParam>;
 type LoginDto = z.infer<typeof loginDto>;
 type ChangePasswordDto = z.infer<typeof changePasswordDto>;
@@ -954,6 +1068,16 @@ declare class AuthService {
     private getDummyHash;
     warmupPasswordHash(): Promise<void>;
     registerUser(body: CreateUserDto): 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
+     * link to set their own. They can't log in until they do, since they never
+     * learn the random password.
+     *
+     * 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: InviteUserDto): Promise<SanitizedUser>;
     loginUser(body: LoginDto): Promise<TokenPair & {
         user: SanitizedUser;
     }>;
@@ -962,6 +1086,13 @@ declare class AuthService {
         data: any;
         message: string;
     }>;
+    /**
+     * Prune expired refresh sessions for every user. Login already prunes
+     * opportunistically; expose this so consumers can also run it from a
+     * scheduled job (cron / queue) to reclaim rows from users who never return.
+     * Best-effort — safe to call repeatedly.
+     */
+    pruneExpiredSessions(): Promise<void>;
     getUserProfile(userData: AuthUser): Promise<AuthUser & {
         language: string;
     }>;
@@ -996,6 +1127,7 @@ declare class AuthController {
     loginUser(body: LoginDto): Promise<TokenPair & {
         user: SanitizedUser;
     }>;
+    inviteUser(body: InviteUserDto): Promise<SanitizedUser>;
     refreshTokens(): Promise<TokenPair>;
     logoutUser(userId: string, authorization?: string): Promise<{
         data: any;
@@ -1968,4 +2100,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, 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 };
+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, 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 };