@solidxai/core 0.1.13-beta.18 → 0.1.13-beta.19

package/src/services/authentication.service.ts

@@ -1793,7 +1793,13 @@ export class AuthenticationService {
     }
   }
 
-  async generateTokens(user: User) {
+  /**
+   * @param deviceId optional stable per-device identifier. Supplied by callers
+   * that own a device credential; otherwise a key is minted per login so that
+   * clients with no device concept (the web UI) still get their own bucket
+   * instead of sharing - and evicting - one.
+   */
+  async generateTokens(user: User, deviceId?: string) {
     const sessionId = this.shouldPreventConcurrentLogins()
       ? randomUUID()
       : undefined;
@@ -1802,9 +1808,17 @@ export class AuthenticationService {
     } else {
       await this.activeSessionStorage.clearActiveSession(user.id);
     }
+
+    // Mutually exclusive with sessionId by construction: per-device buckets
+    // exist only when preventConcurrentLogins is off, sessionId only when it
+    // is on.
+    const deviceKey = this.refreshTokenIdsStorage.areConcurrentLoginsAllowed()
+      ? deviceId ?? randomUUID()
+      : undefined;
+
     const [accessToken, refreshToken] = await Promise.all([
-      await this.generateAccessToken(user, sessionId),
-      await this.generateRefreshToken(user),
+      await this.generateAccessToken(user, sessionId, deviceKey),
+      await this.generateRefreshToken(user, undefined, deviceKey),
     ]);
 
     return {
@@ -1813,7 +1827,7 @@ export class AuthenticationService {
     };
   }
 
-  async generateAccessToken(user: User, sessionId?: string) {
+  async generateAccessToken(user: User, sessionId?: string, deviceKey?: string) {
     // const userRoleNames = user.roles.map((role) => role.name).join(';')
     const userRoleNames = user.roles.map((role) => role.name);
     const resolvedSessionId = this.shouldPreventConcurrentLogins()
@@ -1830,18 +1844,36 @@ export class AuthenticationService {
         email: user.email,
         roles: userRoleNames,
         ...(resolvedSessionId ? { sessionId: resolvedSessionId } : {}),
+        // Carried so that bearer-authenticated endpoints which need this
+        // session's refresh token - generateSsoCode, me - can locate its
+        // bucket. The refresh token is not available to them.
+        ...(deviceKey ? { deviceKey } : {}),
       },
     );
 
     return accessToken;
   }
 
-  async generateRefreshToken(user: User, previousRefreshToken?: string) {
+  async generateRefreshToken(
+    user: User,
+    previousRefreshToken?: string,
+    deviceKey?: string,
+  ) {
     const refreshTokenId = randomUUID();
     const refreshTokenTtl =
       this.settingService.getConfigValue<SolidCoreSetting>("refreshTokenTtl");
+
+    // Only per-device tokens carry an epoch - it is what makes bulk
+    // invalidation possible without enumerating buckets. Single-slot tokens
+    // are invalidated by deleting their one key.
+    const epoch = deviceKey
+      ? await this.refreshTokenIdsStorage.getEpoch(user.id)
+      : undefined;
+
     const refreshToken = await this.signToken(user.id, refreshTokenTtl, {
       refreshTokenId,
+      ...(deviceKey ? { deviceKey } : {}),
+      ...(epoch !== undefined ? { epoch } : {}),
     });
 
     // store the refresh token id in the redis storage.
@@ -1849,6 +1881,7 @@ export class AuthenticationService {
       user.id,
       refreshToken,
       previousRefreshToken,
+      deviceKey,
     );
 
     return refreshToken;
@@ -1863,8 +1896,16 @@ export class AuthenticationService {
       const issuer =
         this.settingService.getConfigValue<SolidCoreSetting>("issuer");
 
-      const { sub } = await this.jwtService.verifyAsync<
-        Pick<ActiveUserData, "sub"> & { refreshTokenId: string }
+      // deviceKey/epoch are absent on tokens issued before per-device sessions,
+      // and on tokens issued while preventConcurrentLogins is on. That absence
+      // is the signal the storage layer branches on - no request-body change
+      // and no client change is needed to carry it.
+      const { sub, deviceKey, epoch } = await this.jwtService.verifyAsync<
+        Pick<ActiveUserData, "sub"> & {
+          refreshTokenId: string;
+          deviceKey?: string;
+          epoch?: number;
+        }
       >(refreshTokenDto.refreshToken, {
         secret,
         audience,
@@ -1892,17 +1933,24 @@ export class AuthenticationService {
       //     throw new Error('Refresh token is invalid');
       // }
 
-      const currentRefreshToken =
-        await this.refreshTokenIdsStorage.validateAndRotate(
-          user,
-          refreshTokenDto.refreshToken,
-        );
+      const rotated = await this.refreshTokenIdsStorage.validateAndRotate(
+        user,
+        refreshTokenDto.refreshToken,
+        { deviceKey, epoch },
+      );
 
       await this.userActivityHistoryService.logEvent("tokenRefreshed", user);
 
       return {
-        accessToken: await this.generateAccessToken(user),
-        refreshToken: currentRefreshToken,
+        // The rotated key, not the incoming one: a session migrating out of the
+        // pre-deploy single slot is assigned a bucket here, and the new access
+        // token has to name the same one.
+        accessToken: await this.generateAccessToken(
+          user,
+          undefined,
+          rotated.deviceKey,
+        ),
+        refreshToken: rotated.refreshToken,
       };
     } catch (err: any) {
       if (err instanceof InvalidatedRefreshTokenError) {
@@ -2291,28 +2339,31 @@ export class AuthenticationService {
   //     // Invalidate the refresh token
   //     // await this.refreshTokenIdsStorage.invalidate(user.id);
   // }
-  async logout(refreshToken: string) {
+  async logout(refreshToken: string, allDevices = false) {
     try {
-      // const activeUser = this.requestContextService.getActiveUser();
-      // const userId = activeUser?.sub;
-      // const user = await this.userRepository.findOne({
-      //     where: {
-      //         id: userId,
-      //     }
-      // })
-      // // Invalidate refresh token if you store them
-      // await this.refreshTokenIdsStorage.invalidate(userId); // ← Your existing logic
-      // if (!refreshToken) {
-      //     throw new UnauthorizedException('Refresh token is required');
-      // }
-      const payload = this.jwtService.decode(refreshToken) as any;
-
-      if (!payload || !payload.sub) {
-        throw new UnauthorizedException(ERROR_MESSAGES.INVALID_REFRESH_TOKEN);
+      const payload = await this.verifyRefreshTokenForLogout(refreshToken);
+
+      // Nothing verifiable to act on: forged, malformed, or signed with another
+      // secret. Acting on an unauthenticated `sub` is exactly the hole this
+      // closes - the route is @Public(), so a decoded-but-unverified token let
+      // anyone log out an arbitrary user. Report success either way: logout
+      // must be safe to call blindly from a client error path, and a 401/200
+      // split here would leak whether a token string is genuine (RFC 7009 §2.2
+      // takes the same position for revocation endpoints).
+      if (!payload?.sub) {
+        this.logger.warn("logout called with an unverifiable refresh token");
+        return { message: SUCCESS_MESSAGES.LOGOUT_SUCCESS };
       }
 
       const userId = payload.sub;
-      await this.refreshTokenIdsStorage.invalidate(userId);
+      if (allDevices) {
+        await this.refreshTokenIdsStorage.invalidateAll(userId);
+      } else {
+        // Scoped to the bucket this token belongs to, so signing out on one
+        // device leaves the others alive. A token with no deviceKey names the
+        // single slot, which is the same key as before.
+        await this.refreshTokenIdsStorage.invalidate(userId, payload.deviceKey);
+      }
       await this.activeSessionStorage.clearActiveSession(userId);
       const user = await this.userRepository.findOne({
         where: {
@@ -2320,10 +2371,15 @@ export class AuthenticationService {
         },
       });
       // Log logout event
-      await this.userActivityHistoryService.logEvent("logout", user);
+      if (user) {
+        await this.userActivityHistoryService.logEvent("logout", user);
+      }
 
       return { message: SUCCESS_MESSAGES.LOGOUT_SUCCESS };
     } catch (err: any) {
+      // JWT problems no longer reach here - verifyRefreshTokenForLogout
+      // swallows them - so this is left for genuine infrastructure failures
+      // (cache or database unavailable), where a 500 is the correct answer.
       throw err instanceof UnauthorizedException ||
         err instanceof InternalServerErrorException
         ? err
@@ -2331,6 +2387,31 @@ export class AuthenticationService {
     }
   }
 
+  private async verifyRefreshTokenForLogout(
+    refreshToken: string,
+  ): Promise<{ sub: number; deviceKey?: string } | null> {
+    try {
+      const payload = await this.jwtService.verifyAsync(refreshToken, {
+        secret: this.settingService.getConfigValue<SolidCoreSetting>("secret"),
+        audience:
+          this.settingService.getConfigValue<SolidCoreSetting>("audience"),
+        issuer: this.settingService.getConfigValue<SolidCoreSetting>("issuer"),
+        // Signature, audience and issuer are still enforced; only `exp` is
+        // tolerated. An expired session must still be able to log out - the
+        // previous jwtService.decode() allowed that, and a plain verifyAsync
+        // would throw TokenExpiredError, which the catch above would turn into
+        // a 500 on an ordinary sign-out.
+        ignoreExpiration: true,
+      });
+
+      // Access and refresh tokens share secret, audience and issuer, so only
+      // this claim distinguishes them. Reject an access token presented here.
+      return payload?.refreshTokenId ? payload : null;
+    } catch {
+      return null; // bad signature or malformed
+    }
+  }
+
   async activateUser(userId: number) {
     const user = await this.userService.findOne(userId, {});
     if (!user) {
@@ -2352,9 +2433,14 @@ export class AuthenticationService {
 
     // const tokens = await this.generateTokens(user);
 
-    // Get the refresh token for a user from refresh token storage.
+    // Get the refresh token for a user from refresh token storage. The bucket
+    // is named by the access token's own deviceKey claim; absent for
+    // single-slot sessions, which resolves to the same key as before.
     const refreshTokenState =
-      await this.refreshTokenIdsStorage.getCurrentRefreshTokenState(user.id);
+      await this.refreshTokenIdsStorage.getCurrentRefreshTokenState(
+        user.id,
+        activeUser.deviceKey,
+      );
 
     const response = {
       user: {
@@ -2365,7 +2451,11 @@ export class AuthenticationService {
         id: user.id,
         roles: user.roles.map((role) => role.name),
       },
-      refreshToken: refreshTokenState.currentRefreshToken,
+      // Null-guarded because the cache entry now carries a TTL: once it
+      // expires - or after a logout followed by a call with a still-valid
+      // access token - there is no state to read. Matches the existing
+      // handling in generateSsoCode.
+      refreshToken: refreshTokenState?.currentRefreshToken ?? null,
       // ...tokens
     };
     return response;
@@ -2378,6 +2468,7 @@ export class AuthenticationService {
     const refreshTokenState =
       await this.refreshTokenIdsStorage.getCurrentRefreshTokenState(
         activeUser.sub,
+        activeUser.deviceKey,
       );
     if (!refreshTokenState?.currentRefreshToken) {
       throw new UnauthorizedException("No active session found");

package/src/services/refresh-token-ids-storage.service.ts

@@ -1,133 +1,272 @@
 import { CACHE_MANAGER } from '@nestjs/cache-manager';
 import { Inject, Injectable, forwardRef } from '@nestjs/common';
 import { Cache } from 'cache-manager';
+import { randomUUID } from 'crypto';
+import type { SolidCoreSetting } from 'src/services/settings/default-settings-provider.service';
 import { AuthenticationService } from './authentication.service';
+import { SettingService } from './setting.service';
 
 // TODO: Ideally this should be in a separate file - putting this here for brevity
 export class InvalidatedRefreshTokenError extends Error { }
 
+// How long a rotated-out refresh token stays acceptable. This window is the
+// point of keeping a previous token at all: concurrent requests from one user
+// must not break each other. core-ui's single-flight guard is module-level and
+// therefore per tab, so two tabs crossing the refresh threshold together will
+// both present the same token - the second one is served from here.
+const PREVIOUS_TOKEN_GRACE_MS = 60 * 1000;
+
+// The cache entry must outlive the JWT it holds. If it expired first, refresh
+// would fail with ACCESS_DENIED (InvalidatedRefreshTokenError) rather than the
+// SESSION_EXPIRED that the token's own `exp` produces - the same event
+// reported two different ways.
+const STATE_TTL_BUFFER_SECONDS = 60;
+
 type RefreshTokenState = {
     currentRefreshToken: string;
     previousRefreshToken: string;
+    // Absolute epoch-ms deadline after which previousRefreshToken is refused.
+    // Stored rather than scheduled: an in-process timer is lost when the pod
+    // restarts, which used to leave the rotated-out token valid until the next
+    // rotation instead of for one minute. Optional because entries written
+    // before this field existed will not carry it.
+    previousValidUntil?: number;
+};
+
+/**
+ * The bucket-identifying claims carried on a refresh token. Absent on tokens
+ * issued before per-device sessions existed, and on tokens issued while
+ * preventConcurrentLogins is on - which is exactly how the read path tells the
+ * two schemes apart without consulting any setting.
+ */
+export type RefreshTokenClaims = {
+    deviceKey?: string;
+    epoch?: number;
+};
+
+export type RotatedRefreshToken = {
+    refreshToken: string;
+    // The bucket the rotated token now lives in. Differs from the incoming
+    // deviceKey only when a pre-migration token was just moved into one.
+    deviceKey?: string;
 };
 
 @Injectable()
-// export class RefreshTokenIdsStorageService implements OnApplicationBootstrap, OnApplicationShutdown {
 export class RefreshTokenIdsStorageService {
-    // private redisClient: Redis;
-    // onApplicationBootstrap() {
-    //     // TODO: Ideally, we should move this to the dedicated "RedisModule" instead of initiating the connection here.
-    //     this.redisClient = new Redis({
-    //         // TODO: According to best practices, we should use the environment variables here instead.
-    //         host: 'localhost',
-    //         port: 6379,
-    //     });
-    // }
-    // onApplicationShutdown(signal?: string) {
-    //     return this.redisClient.quit();
-    // }
-
     constructor(
         @Inject(CACHE_MANAGER) private cacheManager: Cache,
         @Inject(forwardRef(() => AuthenticationService))
-        private readonly authenticationService: AuthenticationService
+        private readonly authenticationService: AuthenticationService,
+        private readonly settingService: SettingService,
     ) { }
 
-    async insert(userId: number, refreshToken: string, previousRefreshToken?: string): Promise<void> {
+    /**
+     * The inverse of the `preventConcurrentLogins` setting, and the only place
+     * it is interpreted.
+     *
+     * That setting already promises, when off, that sessions may coexist;
+     * splitting the refresh-token keyspace per device is what finally delivers
+     * it. When it is on, its stated purpose is a single live session, so
+     * per-device keys would be meaningless and the original single slot is kept.
+     *
+     * This governs the WRITE path only. Reads always branch on the token's own
+     * claim, so toggling the setting never invalidates a live session.
+     */
+    areConcurrentLoginsAllowed(): boolean {
+        return !this.settingService.getConfigValue<SolidCoreSetting>("preventConcurrentLogins");
+    }
+
+    async insert(
+        userId: number,
+        refreshToken: string,
+        previousRefreshToken?: string,
+        deviceKey?: string,
+    ): Promise<void> {
         const refreshTokenState: RefreshTokenState = {
             currentRefreshToken: refreshToken,
             previousRefreshToken: previousRefreshToken ?? "",
+            ...(previousRefreshToken
+                ? { previousValidUntil: Date.now() + PREVIOUS_TOKEN_GRACE_MS }
+                : {}),
         };
-        await this.cacheManager.set(this.getKey(userId), refreshTokenState);
+        await this.cacheManager.set(
+            this.getKey(userId, deviceKey),
+            refreshTokenState,
+            this.getStateTtlMs(),
+        );
     }
 
-    async validate(userId: number, refreshToken: string): Promise<boolean> {
-        // TODO: Assume you get this shape out of the cache {"currentRefreshToken": "", "previousRefreshToken": ""}
-        // Then you will compare against the currentRefreshToken.
-        const storedId = await this.cacheManager.get(this.getKey(userId));
-        if (storedId !== refreshToken) {
-            throw new InvalidatedRefreshTokenError();
-        }
-        return storedId === refreshToken;
+    async invalidate(userId: number, deviceKey?: string): Promise<void> {
+        await this.cacheManager.del(this.getKey(userId, deviceKey));
     }
 
-    async invalidate(userId: number): Promise<void> {
+    /**
+     * Bulk invalidation - "log out everywhere", and the right hook for password
+     * change or forced deactivation.
+     *
+     * Per-device buckets cannot be enumerated through cache-manager, so this
+     * bumps a per-user epoch that every per-device token carries as a claim.
+     * One write invalidates every outstanding token without a scan and without
+     * the read-modify-write race an index of device keys would have.
+     */
+    async invalidateAll(userId: number): Promise<void> {
+        const currentEpoch = (await this.getEpoch(userId)) ?? 0;
+        await this.cacheManager.set(
+            this.getEpochKey(userId),
+            currentEpoch + 1,
+            // Outlives every bucket that could hold a pre-bump token: those were
+            // written earlier, so they expire no later than this key does.
+            this.getStateTtlMs(),
+        );
+        // Single-slot mode and pre-migration entries live under the bare key,
+        // which carries no epoch claim - delete it directly.
         await this.cacheManager.del(this.getKey(userId));
     }
 
-    async validateAndRotate(user: any, refreshToken: string): Promise<string> {
-        let valid = false;
-
-        // TODO: Assume you get this shape out of the cache {"currentRefreshToken": "", "previousRefreshToken": ""}
-        // Then you will compare against the currentRefreshToken.
-        const refreshTokenState = await this.cacheManager.get(this.getKey(user.id)) as RefreshTokenState | undefined;
-
-        // Use the authentication service to generate a new refresh token, set it in the currentRefreshToken in scenario 1 and return.
-
-        // if UI.refresh_token is matching with Cache.currentRefreshToken
-        //   then invalidate (updated cache state, no need to delete anything), then generate new token and return.
-        //   also set a setTimeout to run after X minutes, this will simply update the RefreshTokenCacheState to this object {"currentRefreshToken": "R2","justInvalidatedRefreshToken": ""}
-        // valid=true
-
-        //   - if UI.refresh_token is matching Cache.justInvalidatedRefreshToken        
-        //       then use the Cache.currentRefreshToken, generate new access token and return.
-        //       We do not modify the cache state at all.
-        // valid=true
-
-        let newRefreshToken: string | undefined;
-        if (
-            refreshTokenState &&
-            typeof refreshTokenState === 'object' &&
-            'currentRefreshToken' in refreshTokenState &&
-            'previousRefreshToken' in refreshTokenState
-        ) {
-            if (refreshTokenState.currentRefreshToken === refreshToken) {
-                // Scenario 1: Token matches currentRefreshToken
-                valid = true;
-                // Rotate tokens: move current to previous, set new current (simulate generation)
-                newRefreshToken = await this.authenticationService.generateRefreshToken(user, refreshTokenState.currentRefreshToken); // Replace with real token generation logic
-
-
-                //   updated cache state
-                // await this.cacheManager.set(this.getKey(user.id), {
-                //     currentRefreshToken: newRefreshToken,
-                //     previousRefreshToken: refreshTokenState.currentRefreshToken,
-                // });
-
-                // Optionally, set a timeout to clear previousRefreshToken after X minutes
-                setTimeout(async () => {
-                    const state = (await this.cacheManager.get(this.getKey(user.id))) as any;
-                    if (state && state.currentRefreshToken === newRefreshToken) {
-                        await this.cacheManager.set(this.getKey(user.id), {
-                            currentRefreshToken: newRefreshToken,
-                            previousRefreshToken: "",
-                        });
-                    }
-                }, 1 * 60 * 1000); // 5 minutes
-            } else if (refreshTokenState.previousRefreshToken === refreshToken) {
-                // Scenario 2: Token matches previousRefreshToken
-                valid = true;
-                // Do not modify cache
-                // Generate new refresh token based on currentRefreshToken
-                const existingRefreshTokenState = (await this.cacheManager.get(this.getKey(user.id))) as RefreshTokenState | undefined;
-                newRefreshToken = existingRefreshTokenState?.currentRefreshToken;
+    async getEpoch(userId: number): Promise<number | undefined> {
+        return (await this.cacheManager.get<number>(this.getEpochKey(userId))) ?? undefined;
+    }
+
+    async validateAndRotate(
+        user: any,
+        refreshToken: string,
+        claims: RefreshTokenClaims = {},
+    ): Promise<RotatedRefreshToken> {
+        const { deviceKey, epoch } = claims;
+
+        // The read key comes from the token's own claim, never from a setting.
+        // A token issued under either scheme therefore stays valid when
+        // preventConcurrentLogins is toggled - in both directions - and a
+        // pre-migration token still finds the bare key it was written to.
+        const refreshTokenState = await this.cacheManager.get(
+            this.getKey(user.id, deviceKey),
+        ) as RefreshTokenState | undefined;
+
+        if (!this.isRefreshTokenState(refreshTokenState)) {
+            throw new InvalidatedRefreshTokenError();
+        }
+
+        if (deviceKey && !(await this.isEpochCurrent(user.id, epoch))) {
+            throw new InvalidatedRefreshTokenError();
+        }
+
+        // Scenario 1: the live token. Rotate it. generateRefreshToken calls
+        // insert(), which writes the new state and stamps the grace deadline
+        // onto the token being rotated out.
+        if (refreshTokenState.currentRefreshToken === refreshToken) {
+            const nextDeviceKey = this.resolveNextDeviceKey(deviceKey);
+            const rotated = await this.authenticationService.generateRefreshToken(
+                user,
+                refreshToken,
+                nextDeviceKey,
+            );
+
+            if (nextDeviceKey !== deviceKey) {
+                // The session changed buckets - either migrating out of the
+                // pre-deploy single slot, or collapsing back into it because
+                // preventConcurrentLogins was switched on. The new state is
+                // already written; drop the key it came from so nothing is
+                // left behind.
+                await this.cacheManager.del(this.getKey(user.id, deviceKey));
+            }
+
+            return { refreshToken: rotated, deviceKey: nextDeviceKey };
+        }
+
+        // Scenario 2: the token just rotated out. This is the concurrent-request
+        // case the previous slot exists for - a second in-flight request that
+        // was issued the old token before the first one rotated it. Hand back
+        // the live token so it succeeds, provided the grace window is still open.
+        if (refreshTokenState.previousRefreshToken && refreshTokenState.previousRefreshToken === refreshToken) {
+            if (!this.isWithinGraceWindow(refreshTokenState)) {
+                throw new InvalidatedRefreshTokenError();
             }
+            return { refreshToken: refreshTokenState.currentRefreshToken, deviceKey };
         }
 
+        throw new InvalidatedRefreshTokenError();
+    }
 
-        if (!valid) {
-            throw new InvalidatedRefreshTokenError();
+    getCurrentRefreshTokenState(
+        userId: number,
+        deviceKey?: string,
+    ): Promise<RefreshTokenState | undefined> {
+        return this.cacheManager.get(this.getKey(userId, deviceKey));
+    }
+
+    private getKey(userId: number, deviceKey?: string): string {
+        return deviceKey ? `user-${userId}-${deviceKey}` : `user-${userId}`;
+    }
+
+    // Deliberately not `user-${userId}-epoch`, which a device key of the
+    // literal string "epoch" would collide with.
+    private getEpochKey(userId: number): string {
+        return `user-epoch-${userId}`;
+    }
+
+    /**
+     * Which bucket a rotated token should land in. The setting is consulted
+     * first so that turning preventConcurrentLogins ON collapses existing
+     * per-device sessions back into the single slot on their next refresh -
+     * where normal last-login-wins applies, which is what that setting means.
+     * Leaving them in their own buckets would keep concurrent sessions alive
+     * while the setting claimed to forbid them.
+     */
+    private resolveNextDeviceKey(deviceKey?: string): string | undefined {
+        if (!this.areConcurrentLoginsAllowed()) {
+            return undefined;
         }
+        return deviceKey ?? randomUUID();
+    }
 
-        // TODO: return the refresh token either currentRefreshToken
-        return newRefreshToken; // Fallback to the provided tokenId if no new token was generated
+    private async isEpochCurrent(userId: number, epoch?: number): Promise<boolean> {
+        const storedEpoch = await this.getEpoch(userId);
+        // Nothing has ever been bulk-invalidated for this user - or the cache
+        // was flushed, in which case every bucket is gone and the token is
+        // already dead by the read above. Either way, accept.
+        if (storedEpoch === undefined) {
+            return true;
+        }
+        return epoch === storedEpoch;
+    }
+
+    // cache-manager v5 expects milliseconds; refreshTokenTtl is configured in
+    // seconds. Without an explicit TTL these entries never expire - neither
+    // cache path supplies a default - and the keyspace grows without bound.
+    private getStateTtlMs(): number {
+        const refreshTokenTtlSeconds = Number(
+            this.settingService.getConfigValue<SolidCoreSetting>("refreshTokenTtl"),
+        );
+        return (refreshTokenTtlSeconds + STATE_TTL_BUFFER_SECONDS) * 1000;
     }
 
-    private getKey(userId: number): string {
-        return `user-${userId}`;
+    private isRefreshTokenState(state: unknown): state is RefreshTokenState {
+        return (
+            !!state &&
+            typeof state === 'object' &&
+            'currentRefreshToken' in state &&
+            'previousRefreshToken' in state
+        );
     }
 
-    getCurrentRefreshTokenState(userId: number): Promise<RefreshTokenState | undefined> {
-        return this.cacheManager.get(this.getKey(userId));
+    private isWithinGraceWindow(state: RefreshTokenState): boolean {
+        // TRANSITIONAL - safe to delete one refreshTokenTtl after this ships.
+        //
+        // Entries written before previousValidUntil existed carry no deadline
+        // to test. They are accepted so that the deploy rejects nobody: a tab
+        // that legitimately rotated moments earlier keeps working. The cost is
+        // that for such an entry the previous token stays acceptable until its
+        // own JWT `exp` rather than for 60s - which is exactly how the old code
+        // already behaved whenever its in-process timer was lost to a restart,
+        // so this is an unfixed pre-existing case, not a new one.
+        //
+        // It self-heals: the user's next rotation writes a new-format state
+        // with a deadline. Once every pre-deploy entry has rotated or expired
+        // (one refreshTokenTtl), this branch is unreachable - drop it, and the
+        // undefined case becomes a rejection.
+        if (state.previousValidUntil === undefined) {
+            return true;
+        }
+        return Date.now() < state.previousValidUntil;
     }
 }