najm-auth 1.1.39 → 1.1.41

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) */
@@ -706,6 +720,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 +736,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 +790,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 +821,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 +867,7 @@ declare class TokenService {
      */
     refreshTokens(): Promise<{
         userId: string;
+        tokenFamily: string;
         roles: string[];
         permissions: string[];
         accessToken: string;
@@ -838,14 +875,51 @@ 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 secure password reset token
      * Returns both the plain token (to send via email) and userId for identification
@@ -962,6 +1036,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;
     }>;