najm-auth 4.2.1 → 4.2.3

package/dist/client/index.js

@@ -552,7 +552,9 @@ var NajmAuthClient = class _NajmAuthClient {
       if (generation !== this.authGeneration) return;
       const shouldOpenCircuit = this.registerRefreshFailure(err);
       if (shouldOpenCircuit) {
-        await this.requestServerLogout().catch(() => void 0);
+        if (!(err instanceof AuthError && err.status === 401)) {
+          await this.requestServerLogout().catch(() => void 0);
+        }
         this.resetState();
         this.emit("sessionExpired", null);
         if (err instanceof AuthError && err.status === 401) {

package/dist/client/server/index.js

@@ -1281,7 +1281,9 @@ var NajmAuthClient = class _NajmAuthClient {
       if (generation !== this.authGeneration) return;
       const shouldOpenCircuit = this.registerRefreshFailure(err);
       if (shouldOpenCircuit) {
-        await this.requestServerLogout().catch(() => void 0);
+        if (!(err instanceof AuthError && err.status === 401)) {
+          await this.requestServerLogout().catch(() => void 0);
+        }
         this.resetState();
         this.emit("sessionExpired", null);
         if (err instanceof AuthError && err.status === 401) {

package/dist/index.d.ts

@@ -1281,6 +1281,22 @@ interface SetPasswordToken {
     userId: string;
     jti: string;
 }
+/**
+ * The outcome of a refresh. `refreshToken` is absent only when the request
+ * presented a token that a release before 4.2.3 had just replaced: that
+ * rotation's token cannot be rebuilt, and its own response set the cookie.
+ */
+interface RefreshedSession {
+    userId: string;
+    tokenFamily: string;
+    roles: string[];
+    permissions: string[];
+    sessionVersion: number;
+    accessToken: string;
+    accessTokenExpiresAt: number;
+    refreshToken?: string;
+    refreshTokenExpiresAt?: number;
+}
 declare class TokenService {
     private tokenRepository;
     private cookieManager;
@@ -1394,6 +1410,13 @@ declare class TokenService {
      * family so rotation/revocation can target a single session.
      */
     private signRefreshToken;
+    /**
+     * The refresh token that replaces `replaced`. Its jti is derived from the
+     * replaced token and its lifetime is the one the family row records, so a
+     * request that presents the replaced token inside the grace window can
+     * rebuild the token its rotation issued and hand the browser that one.
+     */
+    private successorRefreshToken;
     generateRefreshToken(data: {
         userId: string;
         tokenFamily?: string;
@@ -1431,24 +1454,35 @@ declare class TokenService {
     storeRefreshToken(userId: string, refreshToken: string, tokenFamily: string): Promise<void>;
     /**
      * Rotate only the family row observed by refreshTokens(). This conditional
-     * update fails closed if logout deleted the family or another refresh won.
+     * update returns null if logout deleted the family or another refresh won.
+     * The row records the new token's own expiry, which serveReplacedToken
+     * reads back to rebuild it.
      */
     private rotateTokens;
     /**
-     * Refresh tokens with secure token comparison
-     * Compares provided token with hashed version in database
-     */
-    refreshTokens(): Promise<{
-        userId: string;
-        tokenFamily: string;
-        roles: string[];
-        permissions: string[];
-        sessionVersion: number;
-        accessToken: string;
-        refreshToken: string;
-        accessTokenExpiresAt: number;
-        refreshTokenExpiresAt: number;
-    }>;
+     * Rotate the refresh token the cookie presents.
+     *
+     * Browser tabs share one cookie jar, so several requests can present the
+     * same token at once: tabs whose access tokens were issued together, or a
+     * tab and a server render. The first rotates it and sets the new cookie.
+     * The others present the token it replaced within the grace window and get
+     * that same new token back without a second rotation, so however many there
+     * are, and in whatever order their responses land, the browser ends up with
+     * the one current token and none is mistaken for a stolen one. The same path
+     * recovers a rotation whose response never reached the browser. Reuse after
+     * the window, or of a token the family never issued, revokes the family.
+     */
+    refreshTokens(): Promise<RefreshedSession>;
+    /** Whether `presentedHash` is the token this family replaced less than the grace window ago. */
+    private withinGraceWindow;
+    /**
+     * Serve a request that presented the token another request just replaced.
+     * It rotates nothing: it returns a new access token and the refresh token
+     * that rotation issued, rebuilt from the replaced one. A current token that
+     * is not that successor (a rotation by an earlier release) is left alone and
+     * only the access token is returned.
+     */
+    private serveReplacedToken;
     private requireActiveRefreshUser;
     /** Revoke every refresh session for a user (password change/reset, logout-all). */
     revokeAllForUser(userId: string): Promise<any>;
@@ -1917,7 +1951,9 @@ declare class AuthService {
     establishSession(user: SanitizedUser): Promise<TokenPair & {
         user: SanitizedUser;
     }>;
-    refreshTokens(): Promise<TokenPair>;
+    refreshTokens(): Promise<Omit<TokenPair, 'refreshToken'> & {
+        refreshToken?: string;
+    }>;
     /**
      * Reissue the short-lived signed session snapshot from a fully validated
      * refresh session. This path never creates or returns access/refresh tokens
@@ -2059,7 +2095,9 @@ declare class AuthController {
     } & {
         emailSent: boolean;
     }>;
-    refreshTokens(): Promise<TokenPair>;
+    refreshTokens(): Promise<Omit<TokenPair, "refreshToken"> & {
+        refreshToken?: string;
+    }>;
     recoverSession(recoveryRequest: string | undefined, ctx: Context): Promise<{
         recovered: true;
     }>;
@@ -3207,4 +3245,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 AdministrativeDelivery, 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 OwnedWhere, type OwnershipConditionMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipReadContext, 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 SetPasswordToken, type SetPasswordTokenType, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TemporaryCredentialReset, 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, ownershipCondition, 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 AdministrativeDelivery, 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 OwnedWhere, type OwnershipConditionMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipReadContext, 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 RefreshedSession, 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 SetPasswordToken, type SetPasswordTokenType, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TemporaryCredentialReset, 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, ownershipCondition, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, resolveAuthLoginRateLimitConfig, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };

package/dist/index.js

@@ -2040,7 +2040,7 @@ UserService = __decorate10([
 import { Injectable as Injectable7, Inject as Inject9 } from "najm-core";
 import { I18n as I18n5 } from "najm-i18n";
 import { CacheService as CacheService2 } from "najm-cache";
-import { createHash } from "crypto";
+import { createHash, createHmac } from "crypto";
 import jwt from "jsonwebtoken";
 import { nanoid as nanoid4 } from "nanoid";
 import timestring3 from "timestring";
@@ -2118,6 +2118,24 @@ CredentialSetupRequirementRepository = __decorate11([
 // src/credentialSetup/types.ts
 var PASSWORD_SETUP_PURPOSE = "password";
 
+// src/shared/storedTime.ts
+function storedTimeMs(value) {
+  if (value instanceof Date)
+    return value.getTime();
+  const text3 = value.trim().replace(" ", "T");
+  const time = text3.split("T")[1];
+  if (!time)
+    return Date.parse(text3);
+  if (/Z$/i.test(time))
+    return Date.parse(text3);
+  const offset = /([+-])(\d{2}):?(\d{2})?$/.exec(time);
+  if (!offset)
+    return Date.parse(`${text3}Z`);
+  const [zone, sign, hours, minutes = "00"] = offset;
+  return Date.parse(`${text3.slice(0, -zone.length)}${sign}${hours}:${minutes}`);
+}
+__name(storedTimeMs, "storedTimeMs");
+
 // src/tokens/TokenService.ts
 import { Err as Err7 } from "najm-core";
 var __decorate12 = function(decorators, target, key, desc) {
@@ -2294,11 +2312,7 @@ var TokenService = class TokenService2 {
       this.rejectRefreshSession();
     }
     const presentedHash = this.hashToken(refreshToken);
-    if (presentedHash === stored.token) {
-      return { userId, tokenFamily };
-    }
-    const canRecover = stored.previousHash && presentedHash === stored.previousHash && stored.previousValidUntil && new Date(stored.previousValidUntil).getTime() > Date.now() && !stored.previousUsedAt;
-    if (canRecover) {
+    if (presentedHash === stored.token || this.withinGraceWindow(stored, presentedHash)) {
       return { userId, tokenFamily };
     }
     this.rejectRefreshSession();
@@ -2425,10 +2439,22 @@ var TokenService = class TokenService2 {
     const token = jwt.sign({ ...data, jti, type: "refresh", exp: expiresAt }, this.config.jwt.refreshSecret);
     return { token, expiresAt };
   }
+  /**
+   * The refresh token that replaces `replaced`. Its jti is derived from the
+   * replaced token and its lifetime is the one the family row records, so a
+   * request that presents the replaced token inside the grace window can
+   * rebuild the token its rotation issued and hand the browser that one.
+   */
+  successorRefreshToken(replaced, data, expiresAt) {
+    const jti = createHmac("sha256", this.config.jwt.refreshSecret).update(`successor:${replaced}`).digest("base64url").slice(0, 16);
+    const iat = expiresAt - Math.floor(timestring3(this.config.jwt.refreshExpiresIn, "s"));
+    const token = jwt.sign({ ...data, jti, type: "refresh", iat, exp: expiresAt }, this.config.jwt.refreshSecret);
+    return { token, expiresAt };
+  }
   generateRefreshToken(data) {
     return this.signRefreshToken({ userId: data.userId, tokenFamily: data.tokenFamily ?? nanoid4(16) }).token;
   }
-  async createTokenPair(userId, family) {
+  async createTokenPair(userId, family, replaced) {
     const { roleName, permissions } = await this.tokenRepository.getRoleAndPermissions(userId);
     const accessTokenData = {
       userId,
@@ -2437,7 +2463,7 @@ var TokenService = class TokenService2 {
       tokenFamily: family
     };
     const access = await this.signAccessToken(accessTokenData);
-    const refresh = this.signRefreshToken({ userId, tokenFamily: family });
+    const refresh = replaced ? this.successorRefreshToken(replaced, { userId, tokenFamily: family }, this.expiresAt(this.config.jwt.refreshExpiresIn)) : this.signRefreshToken({ userId, tokenFamily: family });
     return {
       userId,
       tokenFamily: family,
@@ -2519,35 +2545,44 @@ var TokenService = class TokenService2 {
   }
   /**
    * Rotate only the family row observed by refreshTokens(). This conditional
-   * update fails closed if logout deleted the family or another refresh won.
+   * update returns null if logout deleted the family or another refresh won.
+   * The row records the new token's own expiry, which serveReplacedToken
+   * reads back to rebuild it.
    */
-  async rotateTokens(userId, tokenFamily, expectedCurrentHash) {
-    const generated = await this.createTokenPair(userId, tokenFamily);
-    const expireInSecond = timestring3(this.config.jwt.refreshExpiresIn, "s");
+  async rotateTokens(userId, tokenFamily, replaced, expectedCurrentHash) {
+    const generated = await this.createTokenPair(userId, tokenFamily, replaced);
     const rotated = await this.tokenRepository.rotateRefreshToken({
       userId,
       token: this.hashToken(generated.refreshToken),
       tokenFamily,
-      expiresAt: new Date(Date.now() + expireInSecond * 1e3).toISOString(),
+      expiresAt: new Date(generated.refreshTokenExpiresAt * 1e3).toISOString(),
       previousHash: expectedCurrentHash,
       previousValidUntil: new Date(Date.now() + TokenService_1.PREVIOUS_GRACE_SECONDS * 1e3).toISOString(),
       previousUsedAt: null
     }, expectedCurrentHash);
-    if (!rotated?.length) {
-      Err7(this.t("errors.refreshTokenInvalid"), 401);
-    }
+    if (!rotated?.length)
+      return null;
     if (!await this.invalidation.markFamilyIssued(tokenFamily, userId)) {
       this.rejectRefreshSession();
     }
     return generated;
   }
   /**
-   * Refresh tokens with secure token comparison
-   * Compares provided token with hashed version in database
+   * Rotate the refresh token the cookie presents.
+   *
+   * Browser tabs share one cookie jar, so several requests can present the
+   * same token at once: tabs whose access tokens were issued together, or a
+   * tab and a server render. The first rotates it and sets the new cookie.
+   * The others present the token it replaced within the grace window and get
+   * that same new token back without a second rotation, so however many there
+   * are, and in whatever order their responses land, the browser ends up with
+   * the one current token and none is mistaken for a stolen one. The same path
+   * recovers a rotation whose response never reached the browser. Reuse after
+   * the window, or of a token the family never issued, revokes the family.
    */
   async refreshTokens() {
     const { refreshToken, userId, tokenFamily } = this.readRefreshSessionCookie();
-    const stored = await this.tokenRepository.getByFamily(tokenFamily);
+    let stored = await this.tokenRepository.getByFamily(tokenFamily);
     await this.assertRefreshFamilyAllowed(tokenFamily, userId);
     if (!stored || stored.userId !== userId) {
       this.rejectRefreshSession();
@@ -2555,19 +2590,52 @@ var TokenService = class TokenService2 {
     const presentedHash = this.hashToken(refreshToken);
     await this.requireActiveRefreshUser(userId, tokenFamily);
     if (presentedHash === stored.token) {
-      return this.rotateTokens(userId, tokenFamily, stored.token);
-    }
-    const canRecover = stored.previousHash && presentedHash === stored.previousHash && stored.previousValidUntil && new Date(stored.previousValidUntil).getTime() > Date.now() && !stored.previousUsedAt;
-    if (canRecover) {
-      const claimed = await this.tokenRepository.markPreviousUsed(tokenFamily, presentedHash);
-      if (!claimed?.length) {
-        Err7(this.t("errors.refreshTokenInvalid"), 401);
+      const rotated = await this.rotateTokens(userId, tokenFamily, refreshToken, stored.token);
+      if (rotated)
+        return rotated;
+      stored = await this.tokenRepository.getByFamily(tokenFamily);
+      if (stored?.userId === userId && this.withinGraceWindow(stored, presentedHash)) {
+        return this.serveReplacedToken(userId, tokenFamily, refreshToken, stored);
       }
-      return this.rotateTokens(userId, tokenFamily, stored.token);
+      return Err7(this.t("errors.refreshTokenInvalid"), 401);
+    }
+    if (this.withinGraceWindow(stored, presentedHash)) {
+      return this.serveReplacedToken(userId, tokenFamily, refreshToken, stored);
     }
     await this.revokeSuspectRefreshFamily(userId, tokenFamily);
     this.rejectRefreshSession();
   }
+  /** Whether `presentedHash` is the token this family replaced less than the grace window ago. */
+  withinGraceWindow(stored, presentedHash) {
+    return Boolean(stored.previousHash && presentedHash === stored.previousHash && stored.previousValidUntil && storedTimeMs(stored.previousValidUntil) > Date.now());
+  }
+  /**
+   * Serve a request that presented the token another request just replaced.
+   * It rotates nothing: it returns a new access token and the refresh token
+   * that rotation issued, rebuilt from the replaced one. A current token that
+   * is not that successor (a rotation by an earlier release) is left alone and
+   * only the access token is returned.
+   */
+  async serveReplacedToken(userId, tokenFamily, replaced, stored) {
+    const successor = this.successorRefreshToken(replaced, { userId, tokenFamily }, Math.floor(storedTimeMs(stored.expiresAt) / 1e3));
+    const refresh = this.hashToken(successor.token) === stored.token ? successor : void 0;
+    const { roleName, permissions } = await this.tokenRepository.getRoleAndPermissions(userId);
+    const roles = roleName ? [roleName] : [];
+    const access = await this.signAccessToken({ userId, roles, permissions: permissions ?? [], tokenFamily });
+    if (!await this.invalidation.markFamilyIssued(tokenFamily, userId)) {
+      this.rejectRefreshSession();
+    }
+    return {
+      userId,
+      tokenFamily,
+      roles,
+      permissions: permissions ?? [],
+      sessionVersion: access.sessionVersion,
+      accessToken: access.token,
+      accessTokenExpiresAt: access.expiresAt,
+      ...refresh && { refreshToken: refresh.token, refreshTokenExpiresAt: refresh.expiresAt }
+    };
+  }
   async requireActiveRefreshUser(userId, tokenFamily) {
     const user = await this.tokenRepository.getUser(userId);
     if (!user || user.status !== "active") {
@@ -2692,11 +2760,7 @@ var TokenService = class TokenService2 {
       if (!stored || stored.userId !== userId)
         return null;
       const presentedHash = this.hashToken(refreshToken);
-      if (presentedHash === stored.token) {
-        return decoded.tokenFamily;
-      }
-      const canRecover = stored.previousHash && presentedHash === stored.previousHash && stored.previousValidUntil && new Date(stored.previousValidUntil).getTime() > Date.now() && !stored.previousUsedAt;
-      return canRecover ? decoded.tokenFamily : null;
+      return presentedHash === stored.token || this.withinGraceWindow(stored, presentedHash) ? decoded.tokenFamily : null;
     } catch {
       return null;
     }
@@ -3503,7 +3567,7 @@ var AuthService = class AuthService2 {
   isLockoutActive(lockoutUntil) {
     if (!lockoutUntil)
       return false;
-    return new Date(lockoutUntil).getTime() > Date.now();
+    return storedTimeMs(lockoutUntil) > Date.now();
   }
   nextLockoutUntil() {
     const durationMs = timestring4(this.config.lockout.duration, "ms");
@@ -3783,7 +3847,8 @@ var AuthService = class AuthService2 {
   }
   async refreshTokens() {
     const generated = await this.tokenService.refreshTokens();
-    this.cookieManager.setRefreshToken(generated.refreshToken);
+    if (generated.refreshToken)
+      this.cookieManager.setRefreshToken(generated.refreshToken);
     const user = await this.tokenService.getUserById(generated.userId);
     if (user) {
       this.cookieManager.setSessionCookie({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "4.2.1",
+  "version": "4.2.3",
   "description": "Authentication and authorization library for najm framework",
   "type": "module",
   "files": [