@devopsplaybook.io/common-web 0.4.0-beta.11.4c5668d → 0.5.0-beta.12.6909540

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented here.
 This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-10-24
+
+### Fixed
+
+- Treat corrupt or undecodable stored JWTs as signed out: clear every auth key,
+  emit `AUTH_UPDATED`, and return `null` instead of throwing.
+- Bound session renewal: 10 s request timeout, at most one retry after a 500 ms
+  backoff for network/5xx failures, and a 30 s per-token failure cooldown so a
+  failing refresh endpoint is not retried on every authenticated call.
+- Clear the session and emit `AUTH_UPDATED` when session renewal returns
+  401/403 (revoked session).
+- Validate renewed JWTs (decodable, non-empty, future `exp`, `exp > iat`) before
+  persisting them; keep the newer token when it changes during renewal.
+- Make `AuthService` storage access SSR-safe: no `localStorage` access outside
+  the browser; `getToken()` returns `null` and save/remove are no-ops.
+- Cover the failure paths of session renewal and token handling with tests.
+
 ## [0.4.0] - 2026-10-24
 
 ### Changed

package/README.md

@@ -42,8 +42,10 @@ required. The `playground/` directory demonstrates a consuming app.
 - `useAppHeight()` updates `--app-height` from `visualViewport` when available
   and cleans up resize listeners on unmount.
 - `useOfflineStatus()` returns a reactive `isOnline` ref.
-- Browser services are available through package deep imports, for example
-  `@devopsplaybook.io/common-web/services/AuthService`.
+- Services are browser-only and available through package deep imports, for
+  example `@devopsplaybook.io/common-web/services/AuthService`. `AuthService`
+  guards every `localStorage` access, so during SSR `getToken()` resolves
+  `null` and `saveToken()` / `removeToken()` are no-ops.
 - `createAuthenticationStore()` returns the Pinia store definition; `Pinia`
   must be available in the consuming app.
 
@@ -55,6 +57,26 @@ When an authenticated token has entered the final 20% of its lifetime,
 returning it from `getToken()` or `getAuthHeader()`. This extends active
 sessions without requiring users to sign in again.
 
+`getToken()` never rejects because of the stored or renewed token:
+
+- A corrupt or undecodable token is treated as signed out: every auth key is
+  removed, `AUTH_UPDATED` is emitted and `null` is returned. Expired tokens are
+  removed and return `null`.
+- A `401` or `403` from the refresh endpoint means the session was revoked:
+  the session is cleared, `AUTH_UPDATED` is emitted and `null` is returned.
+- Timeouts and invalid renewal responses perform a single request. Network
+  errors and `5xx` responses retry once after a 500 ms backoff.
+- When renewal still fails, the still-valid current token is returned and
+  further renewal attempts for that token are paused for 30 seconds, so a slow
+  or failing refresh endpoint is not retried on every authenticated call. The
+  worst case is about 20.5 seconds per call for network/`5xx` failures and
+  about 10 seconds for timeouts or invalid responses.
+- Renewal requests time out after 10 seconds and concurrent calls share a
+  single request. A token saved while a renewal is in flight wins over the
+  renewed value.
+- Renewed tokens are validated (decodable, non-empty, future `exp`, and
+  `exp > iat` when `iat` is present) before they are persisted.
+
 ## Tokens and app-shell styles
 
 The layer loads `assets/css/tokens.css` and `assets/css/app-shell.css`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-web",
-  "version": "0.4.0-beta.11.4c5668d",
+  "version": "0.5.0-beta.12.6909540",
   "description": "Shared Nuxt layer for DevOpsPlaybook web applications",
   "license": "ISC",
   "engines": {

package/services/AuthService.ts

@@ -1,10 +1,17 @@
 import axios from "axios";
 import { jwtDecode } from "jwt-decode";
+import { EventBus, EventTypes } from "../composables/EventBus";
 import Config from "./Config";
+import { Timeout } from "./Timeout";
 
 export const AUTH_TOKEN_KEY = "auth_token";
 const LEGACY_TOKEN_KEYS = ["AUTH_TOKEN", "AUTH_TOKEN_KEY"] as const;
 
+const RENEWAL_TIMEOUT_MS = 10_000;
+const RENEWAL_RETRY_DELAY_MS = 500;
+const RENEWAL_FAILURE_COOLDOWN_MS = 30_000;
+const RENEWAL_MAX_ATTEMPTS = 2;
+
 interface AuthTokenClaims {
   exp?: number;
   iat?: number;
@@ -16,42 +23,53 @@ export interface AuthHeaders {
   };
 }
 
+class SessionRenewalError extends Error {
+  retryable: boolean;
+  status?: number;
+
+  constructor(message: string, retryable: boolean, status?: number) {
+    super(message);
+    this.name = "SessionRenewalError";
+    this.retryable = retryable;
+    this.status = status;
+  }
+}
+
 export class AuthService {
   private static renewal:
     | { token: string; promise: Promise<string | null> }
     | null = null;
 
+  private static renewalFailure: { token: string; at: number } | null = null;
+
   static async isAuthenticated(): Promise<boolean> {
     return Boolean(await AuthService.getToken());
   }
 
   static async saveToken(token: string): Promise<void> {
-    localStorage.setItem(AUTH_TOKEN_KEY, token);
-    for (const key of LEGACY_TOKEN_KEYS) localStorage.removeItem(key);
+    const storage = AuthService.storage();
+    if (!storage) return;
+    storage.setItem(AUTH_TOKEN_KEY, token);
+    for (const key of LEGACY_TOKEN_KEYS) storage.removeItem(key);
   }
 
   static async removeToken(_token?: string): Promise<void> {
-    localStorage.removeItem(AUTH_TOKEN_KEY);
-    for (const key of LEGACY_TOKEN_KEYS) localStorage.removeItem(key);
+    const storage = AuthService.storage();
+    if (!storage) return;
+    storage.removeItem(AUTH_TOKEN_KEY);
+    for (const key of LEGACY_TOKEN_KEYS) storage.removeItem(key);
   }
 
   static async getToken(): Promise<string | null> {
-    let token = localStorage.getItem(AUTH_TOKEN_KEY);
+    const token = AuthService.readToken();
+    if (!token) return null;
 
-    if (!token) {
-      for (const legacyKey of LEGACY_TOKEN_KEYS) {
-        token = localStorage.getItem(legacyKey);
-        if (token) {
-          localStorage.setItem(AUTH_TOKEN_KEY, token);
-          localStorage.removeItem(legacyKey);
-          break;
-        }
-      }
+    const decoded = AuthService.tryDecode(token);
+    if (!decoded) {
+      await AuthService.clearSession();
+      return null;
     }
 
-    if (!token) return null;
-
-    const decoded = jwtDecode<AuthTokenClaims>(token);
     const now = Date.now() / 1000;
     if (typeof decoded.exp === "number" && decoded.exp <= now) {
       await AuthService.removeToken();
@@ -77,12 +95,59 @@ export class AuthService {
       : {};
   }
 
+  private static storage(): Storage | null {
+    return typeof localStorage === "undefined" ? null : localStorage;
+  }
+
+  private static readToken(): string | null {
+    const storage = AuthService.storage();
+    if (!storage) return null;
+
+    let token = storage.getItem(AUTH_TOKEN_KEY);
+
+    if (!token) {
+      for (const legacyKey of LEGACY_TOKEN_KEYS) {
+        token = storage.getItem(legacyKey);
+        if (token) {
+          storage.setItem(AUTH_TOKEN_KEY, token);
+          storage.removeItem(legacyKey);
+          break;
+        }
+      }
+    }
+
+    return token;
+  }
+
+  private static tryDecode(token: string): AuthTokenClaims | null {
+    try {
+      const decoded = jwtDecode<AuthTokenClaims>(token);
+      if (typeof decoded !== "object" || decoded === null) return null;
+      return decoded;
+    } catch {
+      return null;
+    }
+  }
+
+  private static async clearSession(): Promise<void> {
+    await AuthService.removeToken();
+    EventBus.emit(EventTypes.AUTH_UPDATED);
+  }
+
   private static async renewToken(token: string): Promise<string | null> {
     const existing = AuthService.renewal;
     if (existing?.token === token) {
       return existing.promise;
     }
 
+    const failure = AuthService.renewalFailure;
+    if (
+      failure?.token === token &&
+      Date.now() - failure.at < RENEWAL_FAILURE_COOLDOWN_MS
+    ) {
+      return AuthService.readToken();
+    }
+
     const promise = AuthService.requestTokenRenewal(token);
     AuthService.renewal = { token, promise };
     try {
@@ -98,21 +163,137 @@ export class AuthService {
     token: string,
   ): Promise<string | null> {
     const config = await Config.get();
+
+    for (let attempt = 1; attempt <= RENEWAL_MAX_ATTEMPTS; attempt += 1) {
+      try {
+        const renewedToken = await AuthService.requestRenewedToken(
+          config.SERVER_URL,
+          token,
+        );
+
+        const storedToken = AuthService.readToken();
+        if (storedToken !== token) return storedToken;
+
+        await AuthService.saveToken(renewedToken);
+        return renewedToken;
+      } catch (error) {
+        const renewalError = AuthService.asRenewalError(error);
+
+        if (renewalError.status === 401 || renewalError.status === 403) {
+          const storedToken = AuthService.readToken();
+          if (storedToken !== token) return storedToken;
+          await AuthService.clearSession();
+          return null;
+        }
+
+        if (!renewalError.retryable || attempt === RENEWAL_MAX_ATTEMPTS) {
+          return AuthService.handleRenewalFailure(token);
+        }
+
+        await Timeout.wait(RENEWAL_RETRY_DELAY_MS);
+      }
+    }
+
+    return AuthService.handleRenewalFailure(token);
+  }
+
+  private static async requestRenewedToken(
+    serverUrl: string,
+    token: string,
+  ): Promise<string> {
     const response = await axios.post<{ token?: unknown }>(
-      `${config.SERVER_URL}/users/session/refresh`,
+      `${serverUrl}/users/session/refresh`,
       {},
-      { headers: { Authorization: `Bearer ${token}` } },
+      {
+        headers: { Authorization: `Bearer ${token}` },
+        timeout: RENEWAL_TIMEOUT_MS,
+      },
     );
+
     const renewedToken = response.data?.token;
-    if (typeof renewedToken !== "string" || renewedToken.length === 0) {
-      throw new Error("Session renewal response did not include a token");
+    if (
+      typeof renewedToken !== "string" ||
+      renewedToken.trim().length === 0
+    ) {
+      throw new SessionRenewalError(
+        "Session renewal response did not include a token",
+        false,
+      );
     }
 
-    if (localStorage.getItem(AUTH_TOKEN_KEY) !== token) {
-      return localStorage.getItem(AUTH_TOKEN_KEY);
+    const decoded = AuthService.tryDecode(renewedToken);
+    if (!decoded) {
+      throw new SessionRenewalError(
+        "Session renewal returned an invalid token",
+        false,
+      );
+    }
+
+    const now = Date.now() / 1000;
+    if (
+      typeof decoded.exp !== "number" ||
+      !Number.isFinite(decoded.exp) ||
+      decoded.exp <= now
+    ) {
+      throw new SessionRenewalError(
+        "Session renewal returned a token without a valid expiry",
+        false,
+      );
+    }
+
+    if (
+      typeof decoded.iat === "number" &&
+      decoded.exp <= decoded.iat
+    ) {
+      throw new SessionRenewalError(
+        "Session renewal returned a token with an inconsistent claim window",
+        false,
+      );
     }
 
-    await AuthService.saveToken(renewedToken);
     return renewedToken;
   }
+
+  private static asRenewalError(error: unknown): SessionRenewalError {
+    if (error instanceof SessionRenewalError) return error;
+
+    const candidate = error as
+      | { code?: unknown; response?: { status?: unknown } }
+      | null
+      | undefined;
+    const status =
+      typeof candidate?.response?.status === "number"
+        ? candidate.response.status
+        : undefined;
+
+    if (status === 401 || status === 403) {
+      return new SessionRenewalError(
+        "Session renewal was rejected",
+        false,
+        status,
+      );
+    }
+
+    if (candidate?.code === "ECONNABORTED" || candidate?.code === "ETIMEDOUT") {
+      return new SessionRenewalError("Session renewal timed out", false, status);
+    }
+
+    if (typeof status === "number") {
+      return new SessionRenewalError(
+        `Session renewal failed with status ${status}`,
+        status >= 500,
+        status,
+      );
+    }
+
+    return new SessionRenewalError("Session renewal failed", true, status);
+  }
+
+  private static handleRenewalFailure(token: string): string | null {
+    const storedToken = AuthService.readToken();
+    if (storedToken !== token) return storedToken;
+
+    AuthService.renewalFailure = { token, at: Date.now() };
+    return token;
+  }
 }