fix(auth): prevent unexpected session logout

migrations/0001_init.sql

@@ -132,6 +132,11 @@ CREATE TABLE IF NOT EXISTS refresh_tokens (
   expires_at INTEGER NOT NULL,
   device_identifier TEXT,
   device_session_stamp TEXT,
+  security_stamp TEXT,
+  created_at INTEGER,
+  last_used_at INTEGER,
+  absolute_expires_at INTEGER,
+  client_type TEXT,
   FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
 );
 CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user ON refresh_tokens(user_id);

src/config/limits.ts

@@ -3,12 +3,14 @@
     // Access token lifetime in seconds.
     // 访问令牌有效期（秒）。
     accessTokenTtlSeconds: 7200,
-    // Refresh token lifetime in milliseconds.
+    // Refresh sessions use a reusable opaque token with a sliding idle lifetime.
-    // 刷新令牌有效期（毫秒）。
+    // 刷新会话使用可复用的随机令牌，并按客户端采用滑动空闲期限。
-    refreshTokenTtlMs: 365 * 24 * 60 * 60 * 1000,
+    refreshTokenWebSlidingTtlMs: 30 * 24 * 60 * 60 * 1000,
-    // Grace window for previous refresh token after rotation (ms).
+    refreshTokenDefaultSlidingTtlMs: 30 * 24 * 60 * 60 * 1000,
-    // 刷新令牌轮换后的旧令牌宽限窗口（毫秒）。
+    refreshTokenMobileSlidingTtlMs: 90 * 24 * 60 * 60 * 1000,
-    refreshTokenOverlapGraceMs: 30 * 60 * 1000,
+    // Hard upper bound for one login session, regardless of sliding refreshes.
+    // 单次登录会话的绝对最长寿命，不因滑动续期突破该上限。
+    refreshTokenAbsoluteTtlMs: 365 * 24 * 60 * 60 * 1000,
     // Refresh token random byte length.
     // 刷新令牌随机字节长度。
     refreshTokenRandomBytes: 32,
@@ -62,6 +64,9 @@
     // Refresh-token grant budget per IP per minute.
     // refresh_token 授权每 IP 每分钟请求配额。
     refreshTokenRequestsPerMinute: 30,
+    // Coarser IP budget; the per-session budget above remains the primary guard.
+    // 更宽松的 IP 总预算；主要保护仍由每个 refresh session 的预算承担。
+    refreshTokenRequestsPerIpMinute: 300,
     // Passwordless/auth-request creation budget per IP/email/device per minute.
     // 免密/设备审批请求创建接口每 IP/邮箱/设备每分钟配额。
     authRequestRequestsPerMinute: 5,
@@ -159,3 +164,10 @@
     cipherKeyEncryptionFeatureEnabled: true,
   },
 } as const;
+
+export function getRefreshTokenSlidingTtlMs(clientType?: string | null): number {
+  const normalized = String(clientType || '').trim().toLowerCase();
+  if (normalized === 'web') return LIMITS.auth.refreshTokenWebSlidingTtlMs;
+  if (normalized === 'mobile') return LIMITS.auth.refreshTokenMobileSlidingTtlMs;
+  return LIMITS.auth.refreshTokenDefaultSlidingTtlMs;
+}

src/handlers/identity.ts

@@ -3,7 +3,7 @@ import { StorageService } from '../services/storage';
 import { AuthService } from '../services/auth';
 import { RateLimitService, getClientIdentifier } from '../services/ratelimit';
 import { jsonResponse, errorResponse, identityErrorResponse } from '../utils/response';
-import { LIMITS } from '../config/limits';
+import { getRefreshTokenSlidingTtlMs, LIMITS } from '../config/limits';
 import { findMatchingTotpCounter, isTotpEnabled } from '../utils/totp';
 import { createRefreshToken } from '../utils/jwt';
 import { readAuthRequestDeviceInfo } from '../utils/device';
@@ -42,6 +42,10 @@ const YUBICO_KEY_CONFIG_KEY = 'globalSettings__yubico__key';
 const TWO_FACTOR_PROVIDER_RECOVERY_CODE_RESPONSE = '-1';
 const TWO_FACTOR_PROVIDER_RECOVERY_CODE_ANDROID_REQUEST = 100;
 
+function identityJsonResponse(data: unknown, status: number = 200): Response {
+  return jsonResponse(data, status, { 'Cache-Control': 'no-store', Pragma: 'no-cache' });
+}
+
 function resolveTotpSecret(userSecret: string | null): string | null {
   if (userSecret && isTotpEnabled(userSecret)) {
     return userSecret;
@@ -60,6 +64,33 @@ async function resolveDeviceSession(
   return { identifier: deviceInfo.deviceIdentifier, sessionStamp };
 }
 
+function resolveRefreshClientType(request: Request, body: Record<string, string>): string {
+  if (shouldUseWebSession(request)) return 'web';
+  const clientId = String(body.client_id || '').trim().toLowerCase();
+  if (clientId === 'mobile') return 'mobile';
+  if (clientId === 'browser' || clientId === 'desktop' || clientId === 'cli') return clientId;
+  return clientId || 'other';
+}
+
+async function persistAndResolveDeviceSession(
+  storage: StorageService,
+  userId: string,
+  deviceInfo: ReturnType<typeof readAuthRequestDeviceInfo>
+): Promise<{ identifier: string; sessionStamp: string } | null> {
+  const candidate = await resolveDeviceSession(storage, userId, deviceInfo);
+  if (!candidate) return null;
+  await storage.upsertDevice(
+    userId,
+    candidate.identifier,
+    deviceInfo.deviceName,
+    deviceInfo.deviceType,
+    candidate.sessionStamp
+  );
+  const persisted = await storage.getDevice(userId, candidate.identifier);
+  if (!persisted?.sessionStamp) throw new Error('Failed to persist device session');
+  return { identifier: persisted.deviceIdentifier, sessionStamp: persisted.sessionStamp };
+}
+
 function readDevicePushToken(body: Record<string, string>): string {
   return String(readBodyValue(body, ['devicePushToken', 'DevicePushToken', 'device_push_token']) || '').trim();
 }
@@ -163,7 +194,7 @@ function withWebRefreshCookie(request: Request, response: Response, refreshToken
   headers.append(
     'Set-Cookie',
     refreshToken
-      ? buildRefreshCookie(request, refreshToken, Math.floor(LIMITS.auth.refreshTokenTtlMs / 1000))
+      ? buildRefreshCookie(request, refreshToken, Math.floor(getRefreshTokenSlidingTtlMs('web') / 1000))
       : buildClearedRefreshCookie(request)
   );
   return new Response(response.body, {
@@ -173,30 +204,6 @@ function withWebRefreshCookie(request: Request, response: Response, refreshToken
   });
 }
 
-async function revokePresentedAccessTokenSession(request: Request, env: Env, storage: StorageService): Promise<void> {
-  const authHeader = request.headers.get('Authorization');
-  if (!authHeader) return;
-
-  const auth = new AuthService(env);
-  const verified = await auth.verifyAccessTokenWithUser(authHeader);
-  if (!verified) return;
-
-  const deviceIdentifier = String(verified.payload.did || '').trim();
-  if (deviceIdentifier) {
-    const nextSessionStamp = generateUUID();
-    await storage.rotateDeviceSessionStamp(verified.user.id, deviceIdentifier, nextSessionStamp);
-    await storage.deleteRefreshTokensByDevice(verified.user.id, deviceIdentifier);
-    AuthService.invalidateDeviceCache(verified.user.id, deviceIdentifier);
-    return;
-  }
-
-  verified.user.securityStamp = generateUUID();
-  verified.user.updatedAt = new Date().toISOString();
-  await storage.saveUser(verified.user);
-  await storage.deleteRefreshTokensByUserId(verified.user.id);
-  AuthService.invalidateUserCache(verified.user.id);
-}
-
 function buildPreloginResponse(
   email: string,
   kdfType: number,
@@ -267,7 +274,7 @@ async function twoFactorRequiredResponse(
   };
 
   // Bitwarden clients rely on these fields to trigger the 2FA UI flow.
-  return jsonResponse(
+  return identityJsonResponse(
     {
       error: 'invalid_grant',
       error_description: message,
@@ -341,8 +348,20 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
 
   const grantType = body.grant_type;
   const clientIdentifier = getClientIdentifier(request);
-  if (!clientIdentifier) {
+  if (!clientIdentifier && grantType !== 'refresh_token') {
-    return identityErrorResponse('Client IP is required', 'invalid_request', 403);
+    await safeWriteAuditEvent(env, {
+      action: 'auth.client_ip.missing',
+      category: 'auth',
+      level: 'error',
+      targetType: 'tokenEndpoint',
+      metadata: { grantType, reason: 'client_ip_missing', ...auditRequestMetadata(request) },
+    });
+    return identityErrorResponse(
+      'Authentication is temporarily unavailable',
+      'temporarily_unavailable',
+      503,
+      { 'Retry-After': '5' }
+    );
   }
 
   if (grantType === 'password') {
@@ -359,7 +378,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       // Bitwarden clients expect OAuth-style error fields.
       return identityErrorResponse('Email and password are required', 'invalid_request', 400);
     }
-    const loginIdentifier = await loginRateLimitKey(clientIdentifier, grantType, email);
+    const loginIdentifier = await loginRateLimitKey(clientIdentifier!, grantType, email);
 
     // Check login lockout before user lookup to reduce user-enumeration signal
     const loginCheck = await rateLimit.checkLoginAttempt(loginIdentifier);
@@ -550,15 +569,8 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
     }
 
     // Persist device only after successful password + (optional) 2FA verification.
-    const deviceSession = await resolveDeviceSession(storage, user.id, deviceInfo);
+    const deviceSession = await persistAndResolveDeviceSession(storage, user.id, deviceInfo);
     if (deviceSession) {
-      await storage.upsertDevice(
-        user.id,
-        deviceSession.identifier,
-        deviceInfo.deviceName,
-        deviceInfo.deviceType,
-        deviceSession.sessionStamp
-      );
       await persistIdentityDevicePushToken(env, storage, user.id, deviceSession, deviceInfo.deviceType, body);
     }
 
@@ -569,7 +581,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
     }
 
     const accessToken = await auth.generateAccessToken(user, deviceSession);
-    const refreshToken = await auth.generateRefreshToken(user.id, deviceSession);
+    const refreshToken = await auth.generateRefreshToken(user, deviceSession, resolveRefreshClientType(request, body));
     const accountKeys = buildAccountKeys(user);
     const userDecryptionOptions = buildUserDecryptionOptions(user);
     await safeWriteAuditEvent(env, {
@@ -612,14 +624,14 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       userDecryptionOptions: userDecryptionOptions,
     };
 
-    const baseResponse = jsonResponse(response);
+    const baseResponse = identityJsonResponse(response);
     return shouldUseWebSession(request)
       ? withWebRefreshCookie(request, baseResponse, refreshToken)
       : baseResponse;
 
   } else if (grantType === 'webauthn') {
     const token = String(body.token || '').trim();
-    const loginIdentifier = await loginRateLimitKey(clientIdentifier, grantType, token || 'missing-token');
+    const loginIdentifier = await loginRateLimitKey(clientIdentifier!, grantType, token || 'missing-token');
     const loginCheck = await rateLimit.checkLoginAttempt(loginIdentifier);
     if (!loginCheck.allowed) {
       return identityErrorResponse(
@@ -673,22 +685,15 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
     }
 
     const deviceInfo = readAuthRequestDeviceInfo(body, request);
-    const deviceSession = await resolveDeviceSession(storage, user.id, deviceInfo);
+    const deviceSession = await persistAndResolveDeviceSession(storage, user.id, deviceInfo);
     if (deviceSession) {
-      await storage.upsertDevice(
-        user.id,
-        deviceSession.identifier,
-        deviceInfo.deviceName,
-        deviceInfo.deviceType,
-        deviceSession.sessionStamp
-      );
       await persistIdentityDevicePushToken(env, storage, user.id, deviceSession, deviceInfo.deviceType, body);
     }
 
     await rateLimit.clearLoginAttempts(loginIdentifier);
 
     const accessToken = await auth.generateAccessToken(user, deviceSession);
-    const refreshToken = await auth.generateRefreshToken(user.id, deviceSession);
+    const refreshToken = await auth.generateRefreshToken(user, deviceSession, resolveRefreshClientType(request, body));
     const userVerificationToken = await createPasskeyUserVerificationToken(env, user.id, 'backup.settings.repair');
     const accountKeys = buildAccountKeys(user);
     const webAuthnPrfOption = buildAccountPasskeyTokenUserDecryptionOption(credential);
@@ -734,7 +739,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       userDecryptionOptions: userDecryptionOptions,
     };
 
-    const baseResponse = jsonResponse(response);
+    const baseResponse = identityJsonResponse(response);
     return shouldUseWebSession(request)
       ? withWebRefreshCookie(request, baseResponse, refreshToken)
       : baseResponse;
@@ -751,7 +756,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       return identityErrorResponse('Parameter error', 'invalid_request', 400);
     }
     const uid = clientId.slice(5);
-    const loginIdentifier = await loginRateLimitKey(clientIdentifier, grantType, uid);
+    const loginIdentifier = await loginRateLimitKey(clientIdentifier!, grantType, uid);
 
     // Check login lockout before user lookup to reduce user-enumeration signal
     const loginCheck = await rateLimit.checkLoginAttempt(loginIdentifier);
@@ -805,15 +810,8 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
     }
 
     // Persist device only after successful client credential verification.
-    const deviceSession = await resolveDeviceSession(storage, user.id, deviceInfo);
+    const deviceSession = await persistAndResolveDeviceSession(storage, user.id, deviceInfo);
     if (deviceSession) {
-      await storage.upsertDevice(
-        user.id,
-        deviceSession.identifier,
-        deviceInfo.deviceName,
-        deviceInfo.deviceType,
-        deviceSession.sessionStamp
-      );
       await persistIdentityDevicePushToken(env, storage, user.id, deviceSession, deviceInfo.deviceType, body);
     }
 
@@ -821,7 +819,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
     await rateLimit.clearLoginAttempts(loginIdentifier);
 
     const accessToken = await auth.generateAccessToken(user, deviceSession);
-    const refreshToken = await auth.generateRefreshToken(user.id, deviceSession);
+    const refreshToken = await auth.generateRefreshToken(user, deviceSession, resolveRefreshClientType(request, body));
     const accountKeys = buildAccountKeys(user);
     const userDecryptionOptions = buildUserDecryptionOptions(user);
     await safeWriteAuditEvent(env, {
@@ -863,7 +861,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       userDecryptionOptions: userDecryptionOptions,
     };
 
-    const baseResponse = jsonResponse(response);
+    const baseResponse = identityJsonResponse(response);
     return shouldUseWebSession(request)
       ? withWebRefreshCookie(request, baseResponse, refreshToken)
       : baseResponse;
@@ -880,7 +878,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
 
     const sendId = String(body.send_id || body.sendId || '').trim();
     if (!sendId) {
-      return jsonResponse(
+      return identityJsonResponse(
         {
           error: 'invalid_request',
           error_description: 'send_id is required',
@@ -905,13 +903,13 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       passwordHashB64,
       password,
       rateLimit,
-      clientIdentifier
+      clientIdentifier || undefined
     );
     if ('error' in result) {
       return result.error;
     }
 
-    return jsonResponse({
+    return identityJsonResponse({
       access_token: result.token,
       expires_in: LIMITS.auth.sendAccessTokenTtlSeconds,
       token_type: 'Bearer',
@@ -919,19 +917,6 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       unofficialServer: true,
     });
   } else if (grantType === 'refresh_token') {
-    const refreshLimit = await rateLimit.consumeBudget(
-      `${clientIdentifier}:identity-refresh`,
-      LIMITS.rateLimit.refreshTokenRequestsPerMinute
-    );
-    if (!refreshLimit.allowed) {
-      return identityErrorResponse(
-        `Rate limit exceeded. Try again in ${refreshLimit.retryAfterSeconds} seconds.`,
-        'TooManyRequests',
-        429
-      );
-    }
-
-    // Refresh token
     const refreshToken = String(body.refresh_token || '').trim() || (
       shouldUseWebSession(request)
         ? parseCookieValue(request, WEB_REFRESH_COOKIE)
@@ -941,7 +926,72 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       return identityErrorResponse('Refresh token is required', 'invalid_request', 400);
     }
 
-    const result = await auth.refreshAccessTokenDetailed(refreshToken);
+    const refreshTokenHash = await sha256Hex(refreshToken);
+    try {
+      const sessionLimit = await rateLimit.consumeBudget(
+        `refresh-session:${refreshTokenHash}`,
+        LIMITS.rateLimit.refreshTokenRequestsPerMinute
+      );
+      const ipLimit = clientIdentifier
+        ? await rateLimit.consumeBudget(
+            `refresh-ip:${clientIdentifier}`,
+            LIMITS.rateLimit.refreshTokenRequestsPerIpMinute
+          )
+        : null;
+      const rejected = !sessionLimit.allowed ? sessionLimit : (ipLimit && !ipLimit.allowed ? ipLimit : null);
+      if (rejected) {
+        const retryAfter = Math.max(1, rejected.retryAfterSeconds || 1);
+        return identityErrorResponse(
+          `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+          'temporarily_unavailable',
+          429,
+          { 'Retry-After': String(retryAfter) }
+        );
+      }
+    } catch (error) {
+      await safeWriteAuditEvent(env, {
+        action: 'auth.refresh.failed.rate_limit_unavailable',
+        category: 'auth',
+        level: 'error',
+        targetType: 'refreshToken',
+        metadata: { grantType, reason: 'rate_limit_unavailable', error: error instanceof Error ? error.message : String(error), ...auditRequestMetadata(request) },
+      });
+      return identityErrorResponse(
+        'Session refresh is temporarily unavailable',
+        'temporarily_unavailable',
+        503,
+        { 'Retry-After': '5' }
+      );
+    }
+
+    if (!clientIdentifier) {
+      await safeWriteAuditEvent(env, {
+        action: 'auth.client_ip.missing',
+        category: 'auth',
+        level: 'warn',
+        targetType: 'refreshToken',
+        metadata: { grantType, reason: 'client_ip_missing', webSession: shouldUseWebSession(request), ...auditRequestMetadata(request) },
+      });
+    }
+
+    let result: Awaited<ReturnType<AuthService['refreshAccessTokenDetailed']>>;
+    try {
+      result = await auth.refreshAccessTokenDetailed(refreshToken);
+    } catch (error) {
+      await safeWriteAuditEvent(env, {
+        action: 'auth.refresh.failed.temporarily_unavailable',
+        category: 'auth',
+        level: 'error',
+        targetType: 'refreshToken',
+        metadata: { grantType, reason: 'storage_or_worker_error', error: error instanceof Error ? error.message : String(error), webSession: shouldUseWebSession(request), ...auditRequestMetadata(request) },
+      });
+      return identityErrorResponse(
+        'Session refresh is temporarily unavailable',
+        'temporarily_unavailable',
+        503,
+        { 'Retry-After': '5' }
+      );
+    }
     if (!result.ok) {
       await safeWriteAuditEvent(env, {
         actorUserId: result.userId ?? null,
@@ -963,18 +1013,10 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
         : invalidResponse;
     }
 
-    // Keep a short overlap window for old refresh token to absorb
-    // concurrent refresh requests from multiple client contexts.
-    await storage.constrainRefreshTokenExpiry(
-      refreshToken,
-      Date.now() + LIMITS.auth.refreshTokenOverlapGraceMs
-    );
-
     const { accessToken, user, device } = result;
     if (device?.identifier) {
       await storage.touchDeviceLastSeen(user.id, device.identifier);
     }
-    const newRefreshToken = await auth.generateRefreshToken(user.id, device);
     const accountKeys = buildAccountKeys(user);
     const userDecryptionOptions = buildUserDecryptionOptions(user);
 
@@ -982,7 +1024,7 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       access_token: accessToken,
       expires_in: LIMITS.auth.accessTokenTtlSeconds,
       token_type: 'Bearer',
-      ...(shouldUseWebSession(request) ? { web_session: true } : { refresh_token: newRefreshToken }),
+      ...(shouldUseWebSession(request) ? { web_session: true } : { refresh_token: refreshToken }),
       Key: user.key,
       PrivateKey: user.privateKey,
       AccountKeys: accountKeys,
@@ -1001,9 +1043,9 @@ export async function handleToken(request: Request, env: Env): Promise<Response>
       userDecryptionOptions: userDecryptionOptions,
     };
 
-    const baseResponse = jsonResponse(response);
+    const baseResponse = identityJsonResponse(response);
     return shouldUseWebSession(request)
-      ? withWebRefreshCookie(request, baseResponse, newRefreshToken)
+      ? withWebRefreshCookie(request, baseResponse, refreshToken)
       : baseResponse;
   }
 
@@ -1036,7 +1078,7 @@ export async function handlePrelogin(request: Request, env: Env): Promise<Respon
   const kdfMemory = user?.kdfMemory ?? null;
   const kdfParallelism = user?.kdfParallelism ?? null;
 
-  return jsonResponse(buildPreloginResponse(email, kdfType, kdfIterations, kdfMemory, kdfParallelism));
+  return identityJsonResponse(buildPreloginResponse(email, kdfType, kdfIterations, kdfMemory, kdfParallelism));
 }
 
 // POST /identity/connect/revocation
@@ -1044,12 +1086,6 @@ export async function handlePrelogin(request: Request, env: Env): Promise<Respon
 // RFC 7009 allows returning 200 even if token is unknown.
 export async function handleRevocation(request: Request, env: Env): Promise<Response> {
   const storage = new StorageService(env.DB);
-  try {
-    await revokePresentedAccessTokenSession(request, env, storage);
-  } catch {
-    // RFC 7009 revocation is best-effort and should not reveal token state.
-  }
-
   let body: Record<string, string>;
   const contentType = request.headers.get('content-type') || '';
   try {
@@ -1060,7 +1096,7 @@ export async function handleRevocation(request: Request, env: Env): Promise<Resp
       body = await request.json();
     }
   } catch {
-    return new Response(null, { status: 200 });
+    return new Response(null, { status: 200, headers: { 'Cache-Control': 'no-store', Pragma: 'no-cache' } });
   }
 
   const token = String(body.token || '').trim() || (
@@ -1072,7 +1108,10 @@ export async function handleRevocation(request: Request, env: Env): Promise<Resp
     await storage.deleteRefreshToken(token);
   }
 
-  const baseResponse = new Response(null, { status: 200 });
+  const baseResponse = new Response(null, {
+    status: 200,
+    headers: { 'Cache-Control': 'no-store', Pragma: 'no-cache' },
+  });
   return shouldUseWebSession(request)
     ? withWebRefreshCookie(request, baseResponse, null)
     : baseResponse;

src/services/auth.ts

@@ -1,5 +1,6 @@
 import { Env, JWTPayload, User } from '../types';
 import { verifyJWT, createJWT, createRefreshToken } from '../utils/jwt';
+import { getRefreshTokenSlidingTtlMs, LIMITS } from '../config/limits';
 import { StorageService } from './storage';
 
 // Server-side iterations for second-layer hashing.
@@ -28,11 +29,12 @@ export type RefreshAccessTokenFailureReason =
   | 'token_not_found_or_expired'
   | 'user_missing'
   | 'user_inactive'
+  | 'security_stamp_mismatch'
   | 'device_missing'
   | 'device_session_mismatch';
 
 export type RefreshAccessTokenResult =
-  | { ok: true; accessToken: string; user: User; device: { identifier: string; sessionStamp: string } | null }
+  | { ok: true; accessToken: string; user: User; device: { identifier: string; sessionStamp: string } | null; expiresAt: number }
   | {
       ok: false;
       reason: RefreshAccessTokenFailureReason;
@@ -190,9 +192,23 @@ export class AuthService {
   }
 
   // Generate refresh token
-  async generateRefreshToken(userId: string, device?: { identifier: string; sessionStamp: string } | null): Promise<string> {
+  async generateRefreshToken(
+    user: User,
+    device?: { identifier: string; sessionStamp: string } | null,
+    clientType: string = 'other'
+  ): Promise<string> {
     const token = createRefreshToken();
-    await this.storage.saveRefreshToken(token, userId, undefined, device?.identifier ?? null, device?.sessionStamp ?? null);
+    const now = Date.now();
+    await this.storage.saveRefreshToken(
+      token,
+      user.id,
+      now + getRefreshTokenSlidingTtlMs(clientType),
+      device?.identifier ?? null,
+      device?.sessionStamp ?? null,
+      user.securityStamp,
+      clientType,
+      now + LIMITS.auth.refreshTokenAbsoluteTtlMs
+    );
     return token;
   }
 
@@ -251,25 +267,42 @@ export class AuthService {
       return { ok: false, reason: 'user_inactive', userId: user.id, deviceIdentifier: record.deviceIdentifier };
     }
 
+    if (record.securityStamp && record.securityStamp !== user.securityStamp) {
+      await this.storage.deleteRefreshToken(refreshToken);
+      return { ok: false, reason: 'security_stamp_mismatch', userId: user.id, deviceIdentifier: record.deviceIdentifier };
+    }
+    if (!record.securityStamp) {
+      await this.storage.bindRefreshTokenSecurityStamp(refreshToken, user.securityStamp);
+    }
+
     let device: { identifier: string; sessionStamp: string } | null = null;
-    if (!record.deviceIdentifier || !record.deviceSessionStamp) {
+    if (record.deviceIdentifier) {
-      await this.storage.deleteRefreshToken(refreshToken);
+      const boundDevice = await this.storage.getDevice(user.id, record.deviceIdentifier);
-      return { ok: false, reason: 'device_missing', userId: user.id, deviceIdentifier: record.deviceIdentifier };
+      if (!boundDevice) {
+        await this.storage.deleteRefreshToken(refreshToken);
+        return { ok: false, reason: 'device_missing', userId: user.id, deviceIdentifier: record.deviceIdentifier };
+      }
+      if (record.deviceSessionStamp && boundDevice.sessionStamp !== record.deviceSessionStamp) {
+        await this.storage.deleteRefreshToken(refreshToken);
+        return { ok: false, reason: 'device_session_mismatch', userId: user.id, deviceIdentifier: record.deviceIdentifier };
+      }
+      if (!record.deviceSessionStamp) {
+        await this.storage.bindRefreshTokenDeviceStamp(refreshToken, boundDevice.sessionStamp);
+      }
+      device = { identifier: boundDevice.deviceIdentifier, sessionStamp: boundDevice.sessionStamp };
     }
 
-    const boundDevice = await this.storage.getDevice(user.id, record.deviceIdentifier);
+    const now = Date.now();
-    if (!boundDevice) {
+    const expiresAt = Math.min(
-      await this.storage.deleteRefreshToken(refreshToken);
+      now + getRefreshTokenSlidingTtlMs(record.clientType),
-      return { ok: false, reason: 'device_missing', userId: user.id, deviceIdentifier: record.deviceIdentifier };
+      record.absoluteExpiresAt || (now + LIMITS.auth.refreshTokenAbsoluteTtlMs)
+    );
+    const extended = await this.storage.extendRefreshTokenExpiry(refreshToken, expiresAt, now);
+    if (!extended) {
+      return { ok: false, reason: 'token_not_found_or_expired', userId: user.id, deviceIdentifier: record.deviceIdentifier };
     }
-    if (boundDevice.sessionStamp !== record.deviceSessionStamp) {
-      await this.storage.deleteRefreshToken(refreshToken);
-      return { ok: false, reason: 'device_session_mismatch', userId: user.id, deviceIdentifier: record.deviceIdentifier };
-    }
-    device = { identifier: boundDevice.deviceIdentifier, sessionStamp: boundDevice.sessionStamp };
-
     const accessToken = await this.generateAccessToken(user, device);
-    return { ok: true, accessToken, user, device };
+    return { ok: true, accessToken, user, device, expiresAt };
   }
 
   async refreshAccessToken(

src/services/storage-device-repo.ts

@@ -45,7 +45,8 @@ export async function upsertDevice(
   await db
     .prepare(
       'INSERT INTO devices(user_id, device_identifier, name, type, session_stamp, encrypted_user_key, encrypted_public_key, encrypted_private_key, push_uuid, banned, banned_at, device_note, last_seen_at, created_at, updated_at) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?, ?, ?) ' +
-        'ON CONFLICT(user_id, device_identifier) DO UPDATE SET name=excluded.name, type=excluded.type, session_stamp=excluded.session_stamp, ' +
+        'ON CONFLICT(user_id, device_identifier) DO UPDATE SET name=excluded.name, type=excluded.type, ' +
+        'session_stamp=CASE WHEN devices.session_stamp IS NULL OR devices.session_stamp = ? THEN excluded.session_stamp ELSE devices.session_stamp END, ' +
         'encrypted_user_key=COALESCE(excluded.encrypted_user_key, encrypted_user_key), ' +
         'encrypted_public_key=COALESCE(excluded.encrypted_public_key, encrypted_public_key), ' +
         'encrypted_private_key=COALESCE(excluded.encrypted_private_key, encrypted_private_key), ' +
@@ -66,7 +67,8 @@ export async function upsertDevice(
       existingDevice?.deviceNote ?? null,
       now,
       now,
-      now
+      now,
+      ''
     )
     .run();
 }

src/services/storage-refresh-token-repo.ts

@@ -11,16 +11,34 @@ export async function saveRefreshToken(
   userId: string,
   expiresAtMs: number,
   deviceIdentifier?: string | null,
-  deviceSessionStamp?: string | null
+  deviceSessionStamp?: string | null,
+  securityStamp?: string | null,
+  clientType?: string | null,
+  absoluteExpiresAtMs?: number | null
 ): Promise<void> {
   await maybeCleanupExpiredRefreshTokens(Date.now());
   const tokenKey = await refreshTokenKey(token);
+  const now = Date.now();
   await db
     .prepare(
-      'INSERT INTO refresh_tokens(token, user_id, expires_at, device_identifier, device_session_stamp) VALUES(?, ?, ?, ?, ?) ' +
+      'INSERT INTO refresh_tokens(token, user_id, expires_at, device_identifier, device_session_stamp, security_stamp, created_at, last_used_at, absolute_expires_at, client_type) ' +
-        'ON CONFLICT(token) DO UPDATE SET user_id=excluded.user_id, expires_at=excluded.expires_at, device_identifier=excluded.device_identifier, device_session_stamp=excluded.device_session_stamp'
+        'VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ' +
+        'ON CONFLICT(token) DO UPDATE SET user_id=excluded.user_id, expires_at=excluded.expires_at, device_identifier=excluded.device_identifier, ' +
+        'device_session_stamp=excluded.device_session_stamp, security_stamp=excluded.security_stamp, last_used_at=excluded.last_used_at, ' +
+        'absolute_expires_at=excluded.absolute_expires_at, client_type=excluded.client_type'
+    )
+    .bind(
+      tokenKey,
+      userId,
+      expiresAtMs,
+      deviceIdentifier ?? null,
+      deviceSessionStamp ?? null,
+      securityStamp ?? null,
+      now,
+      now,
+      absoluteExpiresAtMs ?? null,
+      clientType ?? null
     )
-    .bind(tokenKey, userId, expiresAtMs, deviceIdentifier ?? null, deviceSessionStamp ?? null)
     .run();
 }
 
@@ -36,12 +54,25 @@ export async function getRefreshTokenRecord(
   const tokenKey = await refreshTokenKey(token);
 
   const row = await db
-    .prepare('SELECT user_id, expires_at, device_identifier, device_session_stamp FROM refresh_tokens WHERE token = ?')
+    .prepare(
+      'SELECT user_id, expires_at, device_identifier, device_session_stamp, security_stamp, created_at, last_used_at, absolute_expires_at, client_type ' +
+        'FROM refresh_tokens WHERE token = ?'
+    )
     .bind(tokenKey)
-    .first<{ user_id: string; expires_at: number; device_identifier: string | null; device_session_stamp: string | null }>();
+    .first<{
+      user_id: string;
+      expires_at: number;
+      device_identifier: string | null;
+      device_session_stamp: string | null;
+      security_stamp: string | null;
+      created_at: number | null;
+      last_used_at: number | null;
+      absolute_expires_at: number | null;
+      client_type: string | null;
+    }>();
 
   if (!row) return null;
-  if (row.expires_at && row.expires_at < now) {
+  if ((row.expires_at && row.expires_at < now) || (row.absolute_expires_at && row.absolute_expires_at < now)) {
     await deleteRefreshTokenRecord(token);
     return null;
   }
@@ -50,9 +81,62 @@ export async function getRefreshTokenRecord(
     expiresAt: row.expires_at,
     deviceIdentifier: row.device_identifier ?? null,
     deviceSessionStamp: row.device_session_stamp ?? null,
+    securityStamp: row.security_stamp ?? null,
+    createdAt: row.created_at ?? null,
+    lastUsedAt: row.last_used_at ?? null,
+    absoluteExpiresAt: row.absolute_expires_at ?? null,
+    clientType: row.client_type ?? null,
   };
 }
 
+export async function extendRefreshTokenExpiry(
+  db: D1Database,
+  refreshTokenKey: RefreshTokenKeyFn,
+  token: string,
+  requestedExpiresAtMs: number,
+  nowMs: number
+): Promise<boolean> {
+  const tokenKey = await refreshTokenKey(token);
+  const result = await db
+    .prepare(
+      'UPDATE refresh_tokens SET ' +
+        'expires_at = CASE ' +
+        'WHEN absolute_expires_at IS NOT NULL AND absolute_expires_at < ? THEN absolute_expires_at ' +
+        'ELSE ? END, ' +
+        'last_used_at = ? ' +
+        'WHERE token = ? AND expires_at >= ? AND (absolute_expires_at IS NULL OR absolute_expires_at >= ?)'
+    )
+    .bind(requestedExpiresAtMs, requestedExpiresAtMs, nowMs, tokenKey, nowMs, nowMs)
+    .run();
+  return Number(result.meta.changes ?? 0) > 0;
+}
+
+export async function bindRefreshTokenSecurityStamp(
+  db: D1Database,
+  refreshTokenKey: RefreshTokenKeyFn,
+  token: string,
+  securityStamp: string
+): Promise<void> {
+  const tokenKey = await refreshTokenKey(token);
+  await db
+    .prepare('UPDATE refresh_tokens SET security_stamp = ? WHERE token = ? AND (security_stamp IS NULL OR security_stamp = ?)')
+    .bind(securityStamp, tokenKey, '')
+    .run();
+}
+
+export async function bindRefreshTokenDeviceStamp(
+  db: D1Database,
+  refreshTokenKey: RefreshTokenKeyFn,
+  token: string,
+  deviceSessionStamp: string
+): Promise<void> {
+  const tokenKey = await refreshTokenKey(token);
+  await db
+    .prepare('UPDATE refresh_tokens SET device_session_stamp = ? WHERE token = ? AND (device_session_stamp IS NULL OR device_session_stamp = ?)')
+    .bind(deviceSessionStamp, tokenKey, '')
+    .run();
+}
+
 export async function deleteRefreshToken(db: D1Database, refreshTokenKey: RefreshTokenKeyFn, token: string): Promise<void> {
   const tokenKey = await refreshTokenKey(token);
   await db.prepare('DELETE FROM refresh_tokens WHERE token = ?').bind(token).run();
@@ -71,30 +155,3 @@ export async function deleteRefreshTokensByDevice(db: D1Database, userId: string
     .run();
   return Number(result.meta.changes ?? 0);
 }
-
-export async function constrainRefreshTokenExpiry(
-  db: D1Database,
-  refreshTokenKey: RefreshTokenKeyFn,
-  token: string,
-  maxExpiresAtMs: number
-): Promise<void> {
-  const tokenKey = await refreshTokenKey(token);
-
-  await db
-    .prepare(
-      'UPDATE refresh_tokens ' +
-        'SET expires_at = CASE WHEN expires_at > ? THEN ? ELSE expires_at END ' +
-        'WHERE token = ?'
-    )
-    .bind(maxExpiresAtMs, maxExpiresAtMs, tokenKey)
-    .run();
-
-  await db
-    .prepare(
-      'UPDATE refresh_tokens ' +
-        'SET expires_at = CASE WHEN expires_at > ? THEN ? ELSE expires_at END ' +
-        'WHERE token = ?'
-    )
-    .bind(maxExpiresAtMs, maxExpiresAtMs, token)
-    .run();
-}

src/services/storage-schema.ts

@@ -74,11 +74,20 @@ const SCHEMA_STATEMENTS: readonly string[] = [
   'ALTER TABLE sends ADD COLUMN emails TEXT',
 
   'CREATE TABLE IF NOT EXISTS refresh_tokens (' +
-  'token TEXT PRIMARY KEY, user_id TEXT NOT NULL, expires_at INTEGER NOT NULL, device_identifier TEXT, device_session_stamp TEXT, ' +
+  'token TEXT PRIMARY KEY, user_id TEXT NOT NULL, expires_at INTEGER NOT NULL, device_identifier TEXT, device_session_stamp TEXT, security_stamp TEXT, created_at INTEGER, last_used_at INTEGER, absolute_expires_at INTEGER, client_type TEXT, ' +
   'FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE)',
   'CREATE INDEX IF NOT EXISTS idx_refresh_tokens_user ON refresh_tokens(user_id)',
   'ALTER TABLE refresh_tokens ADD COLUMN device_identifier TEXT',
   'ALTER TABLE refresh_tokens ADD COLUMN device_session_stamp TEXT',
+  'ALTER TABLE refresh_tokens ADD COLUMN security_stamp TEXT',
+  'ALTER TABLE refresh_tokens ADD COLUMN created_at INTEGER',
+  'ALTER TABLE refresh_tokens ADD COLUMN last_used_at INTEGER',
+  'ALTER TABLE refresh_tokens ADD COLUMN absolute_expires_at INTEGER',
+  'ALTER TABLE refresh_tokens ADD COLUMN client_type TEXT',
+  "UPDATE refresh_tokens SET security_stamp = (SELECT users.security_stamp FROM users WHERE users.id = refresh_tokens.user_id) WHERE security_stamp IS NULL OR security_stamp = ''",
+  "UPDATE refresh_tokens SET created_at = CAST(strftime('%s','now') AS INTEGER) * 1000 WHERE created_at IS NULL",
+  "UPDATE refresh_tokens SET last_used_at = created_at WHERE last_used_at IS NULL",
+  'UPDATE refresh_tokens SET absolute_expires_at = expires_at WHERE absolute_expires_at IS NULL',
 
   'CREATE TABLE IF NOT EXISTS invites (' +
   'code TEXT PRIMARY KEY, created_by TEXT NOT NULL, used_by TEXT, expires_at TEXT NOT NULL, status TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, ' +
@@ -118,6 +127,8 @@ const SCHEMA_STATEMENTS: readonly string[] = [
   'ALTER TABLE devices ADD COLUMN last_seen_at TEXT',
   'CREATE INDEX IF NOT EXISTS idx_devices_user_last_seen ON devices(user_id, last_seen_at)',
   'CREATE INDEX IF NOT EXISTS idx_devices_user_push ON devices(user_id, push_token)',
+  "UPDATE refresh_tokens SET device_session_stamp = (SELECT devices.session_stamp FROM devices WHERE devices.user_id = refresh_tokens.user_id AND devices.device_identifier = refresh_tokens.device_identifier) WHERE device_identifier IS NOT NULL AND (device_session_stamp IS NULL OR device_session_stamp = '') AND EXISTS (SELECT 1 FROM devices WHERE devices.user_id = refresh_tokens.user_id AND devices.device_identifier = refresh_tokens.device_identifier)",
+  "UPDATE refresh_tokens SET client_type = CASE WHEN EXISTS (SELECT 1 FROM devices WHERE devices.user_id = refresh_tokens.user_id AND devices.device_identifier = refresh_tokens.device_identifier AND devices.type IN (0, 1)) THEN 'mobile' WHEN EXISTS (SELECT 1 FROM devices WHERE devices.user_id = refresh_tokens.user_id AND devices.device_identifier = refresh_tokens.device_identifier AND devices.type = 14) THEN 'web' ELSE 'other' END WHERE client_type IS NULL OR client_type = ''",
 
   'CREATE TABLE IF NOT EXISTS auth_requests (' +
   'id TEXT PRIMARY KEY, user_id TEXT NOT NULL, organization_id TEXT, type INTEGER NOT NULL, request_device_identifier TEXT NOT NULL, request_device_type INTEGER NOT NULL, ' +

src/services/storage.ts

@@ -87,10 +87,12 @@ import {
   saveSend as saveStoredSend,
 } from './storage-send-repo';
 import {
-  constrainRefreshTokenExpiry as constrainStoredRefreshTokenExpiry,
+  bindRefreshTokenDeviceStamp as bindStoredRefreshTokenDeviceStamp,
+  bindRefreshTokenSecurityStamp as bindStoredRefreshTokenSecurityStamp,
   deleteRefreshToken as deleteStoredRefreshToken,
   deleteRefreshTokensByDevice as deleteStoredRefreshTokensByDevice,
   deleteRefreshTokensByUserId as deleteStoredRefreshTokensByUserId,
+  extendRefreshTokenExpiry as extendStoredRefreshTokenExpiry,
   getRefreshTokenRecord as findStoredRefreshTokenRecord,
   saveRefreshToken as saveStoredRefreshToken,
 } from './storage-refresh-token-repo';
@@ -162,7 +164,7 @@ const STORAGE_SCHEMA_VERSION_KEY = 'schema.version';
 // Bump this whenever src/services/storage-schema.ts or migrations/0001_init.sql
 // changes. Existing D1 installs only rerun ensureStorageSchema() when this value
 // differs from config.schema.version.
-const STORAGE_SCHEMA_VERSION = '2026-07-05-passkey-2fa';
+const STORAGE_SCHEMA_VERSION = '2026-07-13-refresh-session-reuse';
 const REQUIRED_SCHEMA_TABLES = ['webauthn_credentials', 'webauthn_challenges', 'auth_requests', 'totp_login_replays'] as const;
 
 // D1-backed storage.
@@ -632,9 +634,13 @@ export class StorageService {
     userId: string,
     expiresAtMs?: number,
     deviceIdentifier?: string | null,
-    deviceSessionStamp?: string | null
+    deviceSessionStamp?: string | null,
+    securityStamp?: string | null,
+    clientType?: string | null,
+    absoluteExpiresAtMs?: number | null
   ): Promise<void> {
-    const expiresAt = expiresAtMs ?? (Date.now() + LIMITS.auth.refreshTokenTtlMs);
+    const now = Date.now();
+    const expiresAt = expiresAtMs ?? (now + LIMITS.auth.refreshTokenDefaultSlidingTtlMs);
     await saveStoredRefreshToken(
       this.db,
       this.refreshTokenKey.bind(this),
@@ -643,7 +649,10 @@ export class StorageService {
       userId,
       expiresAt,
       deviceIdentifier,
-      deviceSessionStamp
+      deviceSessionStamp,
+      securityStamp,
+      clientType,
+      absoluteExpiresAtMs ?? (now + LIMITS.auth.refreshTokenAbsoluteTtlMs)
     );
   }
 
@@ -717,11 +726,16 @@ export class StorageService {
     return deleteStoredRefreshTokensByDevice(this.db, userId, deviceIdentifier);
   }
 
-  // Keep a short overlap window for rotated refresh token to reduce
+  async extendRefreshTokenExpiry(token: string, requestedExpiresAtMs: number, nowMs: number = Date.now()): Promise<boolean> {
-  // multi-context refresh races (e.g. browser extension popup/background).
+    return extendStoredRefreshTokenExpiry(this.db, this.refreshTokenKey.bind(this), token, requestedExpiresAtMs, nowMs);
-  // Expiry is only tightened, never extended.
+  }
-  async constrainRefreshTokenExpiry(token: string, maxExpiresAtMs: number): Promise<void> {
+
-    await constrainStoredRefreshTokenExpiry(this.db, this.refreshTokenKey.bind(this), token, maxExpiresAtMs);
+  async bindRefreshTokenSecurityStamp(token: string, securityStamp: string): Promise<void> {
+    await bindStoredRefreshTokenSecurityStamp(this.db, this.refreshTokenKey.bind(this), token, securityStamp);
+  }
+
+  async bindRefreshTokenDeviceStamp(token: string, deviceSessionStamp: string): Promise<void> {
+    await bindStoredRefreshTokenDeviceStamp(this.db, this.refreshTokenKey.bind(this), token, deviceSessionStamp);
   }
 
   private async trustedTwoFactorTokenKey(token: string): Promise<string> {

src/types/index.ts

@@ -402,6 +402,11 @@ export interface RefreshTokenRecord {
   expiresAt: number;
   deviceIdentifier: string | null;
   deviceSessionStamp: string | null;
+  securityStamp: string | null;
+  createdAt: number | null;
+  lastUsedAt: number | null;
+  absoluteExpiresAt: number | null;
+  clientType: string | null;
 }
 
 export interface TrustedDeviceTokenSummary {

src/utils/response.ts

@@ -144,7 +144,12 @@ export function unsupportedResponse(message: string = 'This feature is not suppo
 }
 
 // Identity endpoint error response (for /identity/connect/token)
-export function identityErrorResponse(message: string, error: string = 'invalid_grant', status: number = 400): Response {
+export function identityErrorResponse(
+  message: string,
+  error: string = 'invalid_grant',
+  status: number = 400,
+  headers: Record<string, string> = {}
+): Response {
   return jsonResponse(
     {
       error: error,
@@ -154,7 +159,8 @@ export function identityErrorResponse(message: string, error: string = 'invalid_
         Object: 'error',
       },
     },
-    status
+    status,
+    { 'Cache-Control': 'no-store', Pragma: 'no-cache', ...headers }
   );
 }
 

webapp/src/App.tsx

@@ -253,6 +253,8 @@ export default function App() {
   const [lockTimeoutMinutes, setLockTimeoutMinutesState] = useState<LockTimeoutMinutes>(() => readLockTimeoutMinutes());
   const [sessionTimeoutAction, setSessionTimeoutActionState] = useState<SessionTimeoutAction>(() => readSessionTimeoutAction());
   const [unlockPreparing, setUnlockPreparing] = useState(() => initialBootstrap.phase === 'locked' && !initialBootstrap.session?.email);
+  const [lockedSessionRefreshError, setLockedSessionRefreshError] = useState('');
+  const [lockedSessionRetryKey, setLockedSessionRetryKey] = useState(0);
 
   const [confirm, setConfirm] = useState<AppConfirmState | null>(null);
   const [mobileLayout, setMobileLayout] = useState(false);
@@ -269,6 +271,7 @@ export default function App() {
   const [vaultDecryptError, setVaultDecryptError] = useState('');
   const [sendsDecryptDone, setSendsDecryptDone] = useState(false);
   const sessionRef = useRef<SessionState | null>(initialBootstrap.session);
+  const lockedSessionRetryAttemptRef = useRef(0);
   const silentRefreshVaultRef = useRef<() => Promise<void>>(async () => {});
   const refreshAuthorizedDevicesRef = useRef<() => Promise<void>>(async () => {});
   const refreshPendingAuthRequestsRef = useRef<() => Promise<void>>(async () => {});
@@ -503,13 +506,15 @@ export default function App() {
     if (phase !== 'locked' || !session) return;
     if (IS_DEMO_MODE) return;
     let cancelled = false;
+    let retryTimerId: number | null = null;
     void (async () => {
       const result = await hydrateLockedSession(session, profile);
       if (cancelled) return;
-      if (!result.session) {
+      if (result.kind === 'expired') {
         setSession(null);
         setProfile(null);
         setUnlockPreparing(false);
+        setLockedSessionRefreshError('');
         setPhase('login');
         if (location !== '/login') navigate('/login');
         return;
@@ -518,11 +523,43 @@ export default function App() {
       if (result.profile) {
         setProfile(stripProfileSecrets(result.profile));
       }
+      if (result.kind === 'transient') {
+        setUnlockPreparing(false);
+        setLockedSessionRefreshError(result.message || t('txt_session_refresh_temporarily_unavailable'));
+        const retrySchedule = [2_000, 5_000, 15_000, 30_000, 60_000];
+        const scheduledDelay = retrySchedule[Math.min(lockedSessionRetryAttemptRef.current, retrySchedule.length - 1)];
+        lockedSessionRetryAttemptRef.current += 1;
+        const retryAfterMs = Math.min(60_000, Math.max(scheduledDelay, result.retryAfterMs || 0));
+        retryTimerId = window.setTimeout(() => {
+          setLockedSessionRetryKey((value) => value + 1);
+        }, retryAfterMs);
+        return;
+      }
+      lockedSessionRetryAttemptRef.current = 0;
+      setLockedSessionRefreshError('');
     })();
     return () => {
       cancelled = true;
+      if (retryTimerId !== null) window.clearTimeout(retryTimerId);
     };
-  }, [phase, session?.email, location, navigate]);
+  }, [phase, session?.email, location, navigate, lockedSessionRetryKey]);
+
+  useEffect(() => {
+    if (!lockedSessionRefreshError || phase !== 'locked') return;
+    const retryNow = () => {
+      lockedSessionRetryAttemptRef.current = 0;
+      setLockedSessionRetryKey((value) => value + 1);
+    };
+    const handleVisibility = () => {
+      if (document.visibilityState === 'visible') retryNow();
+    };
+    window.addEventListener('online', retryNow);
+    document.addEventListener('visibilitychange', handleVisibility);
+    return () => {
+      window.removeEventListener('online', retryNow);
+      document.removeEventListener('visibilitychange', handleVisibility);
+    };
+  }, [lockedSessionRefreshError, phase]);
 
   async function finalizeLogin(login: CompletedLogin) {
     loginScopedBackupRepairAuthRef.current =
@@ -536,6 +573,7 @@ export default function App() {
     setSession(login.session);
     setProfile(login.profile);
     setUnlockPreparing(false);
+    setLockedSessionRefreshError('');
     setPendingTotp(null);
     setPendingTotpMode(null);
     setPendingPasskeyPassword(null);
@@ -884,6 +922,7 @@ export default function App() {
     setPendingTotpMode(null);
     setTotpCode('');
     setUnlockPreparing(false);
+    setLockedSessionRefreshError('');
     setPhase('locked');
     navigate('/lock');
   }
@@ -2221,6 +2260,7 @@ export default function App() {
           unlockPlaceholder={IS_DEMO_MODE ? t('txt_demo_unlock_placeholder') : undefined}
           unlockReady={!!session?.email}
           unlockPreparing={unlockPreparing}
+          sessionRefreshError={lockedSessionRefreshError}
           loginValues={loginValues}
           pendingPasskeyPasswordEmail={pendingPasskeyPassword?.email || null}
           passkeyPassword={passkeyPassword}
@@ -2261,6 +2301,11 @@ export default function App() {
           onLogout={logoutNow}
           onTogglePasswordHint={() => void handleTogglePasswordHint()}
           onShowLockedPasswordHint={handleShowLockedPasswordHint}
+          onRetrySessionRefresh={() => {
+            lockedSessionRetryAttemptRef.current = 0;
+            setLockedSessionRefreshError('');
+            setLockedSessionRetryKey((value) => value + 1);
+          }}
         />
         <AppGlobalOverlays
           toasts={toasts}

webapp/src/components/AuthViews.tsx

@@ -27,6 +27,7 @@ interface AuthViewsProps {
   pendingAction: 'login' | 'passkey' | 'register' | 'unlock' | null;
   unlockReady: boolean;
   unlockPreparing: boolean;
+  sessionRefreshError?: string;
   loginValues: LoginValues;
   pendingPasskeyPasswordEmail?: string | null;
   passkeyPassword: string;
@@ -50,6 +51,7 @@ interface AuthViewsProps {
   onLogout: () => void;
   onTogglePasswordHint: () => void;
   onShowLockedPasswordHint: () => void;
+  onRetrySessionRefresh: () => void;
 }
 
 function PasswordField(props: {
@@ -155,6 +157,19 @@ export default function AuthViews(props: AuthViewsProps) {
             {props.unlockPreparing ? (
               <p className="muted standalone-muted">{t('txt_loading')}</p>
             ) : null}
+            {props.sessionRefreshError ? (
+              <div className="offline-mode-notice" role="alert" aria-live="polite">
+                <AlertTriangle size={18} />
+                <div>
+                  <strong>{props.sessionRefreshError}</strong>
+                  <div>
+                    <button type="button" className="auth-link-btn" onClick={props.onRetrySessionRefresh}>
+                      {t('txt_refresh')}
+                    </button>
+                  </div>
+                </div>
+              </div>
+            ) : null}
             <button type="submit" className="btn btn-primary full" disabled={unlockBusy || passkeyBusy || props.unlockPreparing || !props.unlockReady}>
               <Unlock size={16} className="btn-icon" />
               {unlockBusy ? t('txt_unlocking') : props.unlockPreparing ? t('txt_loading') : t('txt_unlock')}

webapp/src/lib/api/auth.ts

@@ -42,6 +42,7 @@ interface RefreshFailure {
   ok: false;
   transient: boolean;
   error: string;
+  retryAfterMs?: number;
 }
 
 interface RefreshSuccess {
@@ -333,8 +334,8 @@ export async function loginWithAccountPasskeyAssertion(assertion: AccountPasskey
   return json;
 }
 
-function isTransientRefreshStatus(status: number): boolean {
+function isPermanentRefreshFailure(status: number, errorCode: string | undefined): boolean {
-  return status === 0 || status === 429 || status >= 500;
+  return status === 400 && (errorCode === 'invalid_grant' || errorCode === 'invalid_request');
 }
 
 export async function refreshAccessToken(session: SessionState): Promise<RefreshResult> {
@@ -346,6 +347,8 @@ export async function refreshAccessToken(session: SessionState): Promise<Refresh
   try {
     const resp = await fetch('/identity/connect/token', {
       method: 'POST',
+      cache: 'no-store',
+      credentials: 'same-origin',
       headers: {
         'Content-Type': 'application/x-www-form-urlencoded',
         ...(session.authMode === 'web-cookie' ? { [WEB_SESSION_HEADER]: '1' } : {}),
@@ -354,15 +357,19 @@ export async function refreshAccessToken(session: SessionState): Promise<Refresh
     });
     if (!resp.ok) {
       const json = await parseJson<TokenError>(resp);
+      const retryAfterSeconds = Number(resp.headers.get('Retry-After') || 0);
       return {
         ok: false,
-        transient: isTransientRefreshStatus(resp.status),
+        transient: !isPermanentRefreshFailure(resp.status, json?.error),
-        error: translateServerError(json?.error_description || json?.error, t('txt_session_refresh_failed')),
+        error: translateServerError(json?.error_description || json?.error, t('txt_session_refresh_temporarily_unavailable')),
+        ...(Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+          ? { retryAfterMs: retryAfterSeconds * 1000 }
+          : {}),
       };
     }
     const json = await parseJson<TokenSuccess>(resp);
     if (!json?.access_token) {
-      return { ok: false, transient: false, error: t('txt_session_refresh_failed') };
+      return { ok: false, transient: true, error: t('txt_session_refresh_temporarily_unavailable') };
     }
     return { ok: true, token: json };
   } catch (error) {
@@ -400,6 +407,8 @@ export async function revokeCurrentSession(session: SessionState | null): Promis
   }
   await fetch('/identity/connect/revocation', {
     method: 'POST',
+    cache: 'no-store',
+    credentials: 'same-origin',
     headers: {
       'Content-Type': 'application/x-www-form-urlencoded',
       ...(session?.accessToken ? { Authorization: `Bearer ${session.accessToken}` } : {}),

webapp/src/lib/app-auth.ts

@@ -199,26 +199,43 @@ function decodeJwtExp(accessToken: string | undefined): number | null {
   }
 }
 
-async function maybeRefreshSession(session: SessionState): Promise<SessionState | null> {
+type SessionRefreshOutcome =
-  if (!session.refreshToken && session.authMode !== 'web-cookie') return session.accessToken ? session : null;
+  | { kind: 'success'; session: SessionState }
+  | { kind: 'transient'; session: SessionState; message: string; retryAfterMs?: number }
+  | { kind: 'expired' };
+
+async function maybeRefreshSession(session: SessionState): Promise<SessionRefreshOutcome> {
+  if (!session.refreshToken && session.authMode !== 'web-cookie') {
+    return session.accessToken ? { kind: 'success', session } : { kind: 'expired' };
+  }
   const exp = decodeJwtExp(session.accessToken);
   const nowSeconds = Math.floor(Date.now() / 1000);
 
   if (session.accessToken && exp !== null && exp - nowSeconds > 60) {
-    return session;
+    return { kind: 'success', session };
   }
 
   const refreshed = await refreshAccessToken(session);
   if (!refreshed.ok) {
-    if (refreshed.transient) return session;
+    if (refreshed.transient) {
-    return session.accessToken && exp !== null && exp > nowSeconds ? session : null;
+      return {
+        kind: 'transient',
+        session,
+        message: refreshed.error || t('txt_session_refresh_temporarily_unavailable'),
+        retryAfterMs: refreshed.retryAfterMs,
+      };
+    }
+    return { kind: 'expired' };
   }
 
   return {
-    ...session,
+    kind: 'success',
-    accessToken: refreshed.token.access_token,
+    session: {
-    refreshToken: refreshed.token.refresh_token || session.refreshToken,
+      ...session,
-    authMode: refreshed.token.web_session ? 'web-cookie' : (session.authMode || 'token'),
+      accessToken: refreshed.token.access_token,
+      refreshToken: refreshed.token.refresh_token || session.refreshToken,
+      authMode: refreshed.token.web_session ? 'web-cookie' : (session.authMode || 'token'),
+    },
   };
 }
 
@@ -388,25 +405,41 @@ export async function bootstrapAppSession(initial: InitialAppBootstrapState = re
 export async function hydrateLockedSession(
   session: SessionState,
   fallbackProfile: Profile | null = null
-): Promise<{ session: SessionState | null; profile: Profile | null }> {
+): Promise<
+  | { kind: 'ready'; session: SessionState; profile: Profile | null }
+  | { kind: 'transient'; session: SessionState; profile: Profile | null; message: string; retryAfterMs?: number }
+  | { kind: 'expired'; session: null; profile: null }
+> {
   const hasOfflineUnlock = hasOfflineUnlockRecord(session.email);
   if (hasOfflineUnlock && browserReportsOffline()) {
     return {
+      kind: 'ready',
       session,
       profile: fallbackProfile || loadOfflineProfileSnapshot(session.email),
     };
   }
 
-  const refreshedSession = await maybeRefreshSession(session);
+  const refreshOutcome = await maybeRefreshSession(session);
-  if (!refreshedSession?.accessToken) {
+  if (refreshOutcome.kind === 'expired') {
+    return { kind: 'expired', session: null, profile: null };
+  }
+  if (refreshOutcome.kind === 'transient') {
     if (hasOfflineUnlock && (browserReportsOffline() || !(await probeNodeWardenService()))) {
       return {
+        kind: 'ready',
         session,
         profile: fallbackProfile || loadOfflineProfileSnapshot(session.email),
       };
     }
-    return { session: null, profile: null };
+    return {
+      kind: 'transient',
+      session,
+      profile: fallbackProfile,
+      message: refreshOutcome.message,
+      retryAfterMs: refreshOutcome.retryAfterMs,
+    };
   }
+  const refreshedSession = refreshOutcome.session;
   try {
     const profile = await getProfile(
       createAuthedFetch(
@@ -415,11 +448,13 @@ export async function hydrateLockedSession(
       )
     );
     return {
+      kind: 'ready',
       session: refreshedSession,
       profile,
     };
   } catch {
     return {
+      kind: 'ready',
       session: refreshedSession,
       profile: fallbackProfile,
     };

webapp/src/lib/i18n/locales/de.ts

@@ -981,6 +981,7 @@ const de: Record<string, string> = {
   "txt_save_profile_failed": "Fehler beim Speichern des Profils",
   "txt_search_sends": "Sendungen suchen...",
   "txt_session_refresh_failed": "Sitzungsaktualisierung fehlgeschlagen. Bitte melden Sie sich erneut an.",
+  "txt_session_refresh_temporarily_unavailable": "Die Sitzung kann vorübergehend nicht geprüft werden. Die Anmeldung bleibt erhalten und wird erneut versucht.",
   "txt_search_your_secure_vault": "Ihren sicheren Tresor durchsuchen...",
   "txt_search_items_count": "In {count} Einträgen suchen...",
   "txt_clear_search": "Suche löschen",

webapp/src/lib/i18n/locales/en.ts

@@ -1004,6 +1004,7 @@ const en: Record<string, string> = {
   "txt_save_profile_failed": "Save profile failed",
   "txt_search_sends": "Search sends...",
   "txt_session_refresh_failed": "Session refresh failed. Please sign in again.",
+  "txt_session_refresh_temporarily_unavailable": "Session verification is temporarily unavailable. Your login is preserved and will retry.",
   "txt_search_your_secure_vault": "Search your secure vault...",
   "txt_search_items_count": "Search within {count} items...",
   "txt_clear_search": "Clear search",

webapp/src/lib/i18n/locales/es.ts

@@ -981,6 +981,7 @@ const es: Record<string, string> = {
   "txt_save_profile_failed": "Error al guardar perfil",
   "txt_search_sends": "Buscar envíos...",
   "txt_session_refresh_failed": "Error al actualizar la sesión. Inicia sesión de nuevo.",
+  "txt_session_refresh_temporarily_unavailable": "La sesión no se puede verificar temporalmente. Tu inicio de sesión se conserva y se volverá a intentar.",
   "txt_search_your_secure_vault": "Buscar en su bóveda segura...",
   "txt_search_items_count": "Buscar entre {count} elementos...",
   "txt_clear_search": "Limpiar búsqueda",

webapp/src/lib/i18n/locales/fi.ts

@@ -981,6 +981,7 @@ const fi: Record<string, string> = {
   "txt_save_profile_failed": "Profiilin tallennus epäonnistui",
   "txt_search_sends": "Hae lähetyksiä...",
   "txt_session_refresh_failed": "Istunnon päivitys epäonnistui. Kirjaudu sisään uudelleen.",
+  "txt_session_refresh_temporarily_unavailable": "Istuntoa ei voida tarkistaa juuri nyt. Kirjautuminen säilytetään ja tarkistusta yritetään uudelleen.",
   "txt_search_your_secure_vault": "Hae turvallisesta holvistasi...",
   "txt_search_items_count": "Hae {count} nimikkeen joukosta...",
   "txt_clear_search": "Tyhjennä haku",

webapp/src/lib/i18n/locales/fr.ts

@@ -981,6 +981,7 @@ const fr: Record<string, string> = {
   "txt_save_profile_failed": "L'enregistrement du profil a échoué",
   "txt_search_sends": "Rechercher des envois...",
   "txt_session_refresh_failed": "L'actualisation de la session a échoué. Veuillez vous reconnecter.",
+  "txt_session_refresh_temporarily_unavailable": "La session ne peut pas être vérifiée temporairement. Votre connexion est conservée et une nouvelle tentative sera effectuée.",
   "txt_search_your_secure_vault": "Recherchez dans votre coffre-fort sécurisé...",
   "txt_search_items_count": "Rechercher parmi {count} éléments...",
   "txt_clear_search": "Effacer la recherche",

webapp/src/lib/i18n/locales/it.ts

@@ -981,6 +981,7 @@ const it: Record<string, string> = {
   "txt_save_profile_failed": "Salvataggio Profilo fallito",
   "txt_search_sends": "Cerca invii...",
   "txt_session_refresh_failed": "Aggiornamento della sessione fallito. Per favore, accedi di nuovo.",
+  "txt_session_refresh_temporarily_unavailable": "La sessione non può essere verificata temporaneamente. L'accesso viene mantenuto e verrà effettuato un nuovo tentativo.",
   "txt_search_your_secure_vault": "Cerca nella tua cassaforte sicura...",
   "txt_search_items_count": "Cerca in {count} elementi...",
   "txt_clear_search": "Cancella Ricerca",

webapp/src/lib/i18n/locales/ru.ts

@@ -981,6 +981,7 @@ const ru: Record<string, string> = {
   "txt_save_profile_failed": "Сохранить профиль не удалось",
   "txt_search_sends": "Поиск отправляет...",
   "txt_session_refresh_failed": "Не удалось обновить сеанс. Войдите снова.",
+  "txt_session_refresh_temporarily_unavailable": "Сеанс временно не удаётся проверить. Вход сохранён, проверка будет повторена.",
   "txt_search_your_secure_vault": "Найдите свое безопасное хранилище...",
   "txt_search_items_count": "Поиск по {count} элементам...",
   "txt_clear_search": "Очистить поиск",

webapp/src/lib/i18n/locales/sv.ts

@@ -981,6 +981,7 @@ const sv: Record<string, string> = {
   "txt_save_profile_failed": "Misslyckades med att spara profil",
   "txt_search_sends": "Sök sändningar...",
   "txt_session_refresh_failed": "Sessionsuppdatering misslyckades. Vänligen logga in igen.",
+  "txt_session_refresh_temporarily_unavailable": "Sessionen kan inte verifieras tillfälligt. Inloggningen bevaras och ett nytt försök görs.",
   "txt_search_your_secure_vault": "Sök i ditt säkra valv...",
   "txt_search_items_count": "Sök bland {count} objekt...",
   "txt_clear_search": "Rensa sökning",

webapp/src/lib/i18n/locales/zh-CN.ts

@@ -984,6 +984,7 @@ const zhCN: Record<string, string> = {
   "txt_save_profile_failed": "保存资料失败",
   "txt_search_sends": "搜索 Send...",
   "txt_session_refresh_failed": "会话刷新失败，请重新登录",
+  "txt_session_refresh_temporarily_unavailable": "暂时无法验证会话，登录状态已保留，稍后会自动重试",
   "txt_search_your_secure_vault": "搜索你的密码库...",
   "txt_search_items_count": "共 {count} 项中搜索...",
   "txt_clear_search": "清空搜索",

webapp/src/lib/i18n/locales/zh-TW.ts

@@ -984,6 +984,7 @@ const zhTW: Record<string, string> = {
   "txt_save_profile_failed": "保存資料失敗",
   "txt_search_sends": "搜索 Send...",
   "txt_session_refresh_failed": "會話刷新失敗，請重新登入",
+  "txt_session_refresh_temporarily_unavailable": "暫時無法驗證會話，登入狀態已保留，稍後會自動重試",
   "txt_search_your_secure_vault": "搜索你的密碼庫...",
   "txt_search_items_count": "在共 {count} 項中搜索...",
   "txt_clear_search": "清空搜索",