@devopsplaybook.io/common-web 0.5.0 → 0.6.0-beta.13.61e7129

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.6.0] - 2026-10-24
+
+### Added
+
+- Propagate auth state changes: `AuthService` emits `AUTH_UPDATED` when a token
+  is saved, removed, renewed or expires; the authentication store subscribes and
+  refreshes `isAuthenticated`, and cross-tab token changes are synchronised
+  through the `storage` event. The additive `refreshAuthentication()` store
+  action is available for manual refreshes.
+- Opt-in Axios integration through `registerAxiosAuthInterceptors(instance)`:
+  attaches the stored bearer token only when no `Authorization` header is set,
+  clears the session on `401` except for the login endpoint (`/users/session`),
+  and registers once per Axios instance. No layer plugin is auto-registered, so
+  existing applications keep their current behaviour until they opt in.
+- `Config.set()` and `Config.reset()` inject or clear the `SERVER_URL` override
+  (`/api` by default).
+- Document the new event, the opt-in Axios helper and the configuration
+  injection point, including the HTTPS requirement for non-same-origin servers.
+
+### Changed
+
+- `UserService.isInitialized()` resolves `false` on network and HTTP failures
+  instead of rejecting.
+- `RefreshIntervalService.get()` validates the stored value and falls back to
+  `10000`; `set()` normalises valid values and throws `TypeError` for invalid
+  ones. `"0"` remains valid to disable polling.
+
 ## [0.5.0] - 2026-10-24
 
 ### Fixed

package/README.md

@@ -77,6 +77,65 @@ sessions without requiring users to sign in again.
 - Renewed tokens are validated (decodable, non-empty, future `exp`, and
   `exp > iat` when `iat` is present) before they are persisted.
 
+## Authentication state and HTTP integration
+
+`AuthService.saveToken()` and `removeToken()` emit
+`EventTypes.AUTH_UPDATED` on the `EventBus` when the stored token actually
+changes; renewal and expiry go through those methods. The Pinia store subscribes
+to the event and refreshes `isAuthenticated`, so a renewal, a logout in another
+tab or an expired token no longer leaves the UI stale. Call the additive
+`refreshAuthentication()` action for a manual refresh; `ensureAuthenticated()`
+still loads the initial state. The store also listens for the browser `storage`
+event, which synchronises token changes across tabs.
+
+Bearer-token attachment is opt-in: the layer ships only the registration helper
+and does not register a plugin, so existing applications keep their current
+behaviour. Add a client plugin in the consuming application when the default
+Axios instance should authenticate requests and clear the session on `401`:
+
+```ts
+// plugins/auth.client.ts
+import { registerAxiosAuthInterceptors } from "@devopsplaybook.io/common-web/services/AxiosAuthInterceptor";
+
+export default defineNuxtPlugin(() => {
+  registerAxiosAuthInterceptors();
+});
+```
+
+`registerAxiosAuthInterceptors(instance?)` attaches `Authorization: Bearer
+<token>` only when the request has no explicit `Authorization` header, and is
+idempotent per Axios instance (it returns `false` when already registered). It
+preserves an explicit header without renewing the token, and does not clear the
+session on a failed login to a path ending in `/users/session`; a `401` from
+any other endpoint (including `/users/session/refresh`) removes the stored token
+and emits `AUTH_UPDATED`.
+
+### Server URL configuration
+
+`Config.get()` returns `{ SERVER_URL: "/api" }` by default. Inject a different
+base URL, for example from a Nuxt client plugin, and reset it for tests:
+
+```ts
+import Config from "@devopsplaybook.io/common-web/services/Config";
+
+Config.set({ SERVER_URL: "https://api.example.com" });
+await Config.get(); // { SERVER_URL: "https://api.example.com" }
+Config.reset(); // back to "/api"
+```
+
+A non-same-origin `SERVER_URL` receives the bearer token when the opt-in Axios
+integration is used, so it must use HTTPS and allow the application origin
+through CORS.
+
+### Service fallbacks
+
+`UserService.isInitialized()` resolves `false` on network or HTTP errors
+instead of rejecting, so setup code can gate on it safely.
+`RefreshIntervalService.get()` falls back to `"10000"` when the stored value is
+missing or malformed; `set()` normalises valid non-negative integer strings
+(for example `"05000"` becomes `"5000"`) and throws `TypeError` otherwise.
+`"0"` is valid and keeps polling disabled.
+
 ## 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.5.0",
+  "version": "0.6.0-beta.13.61e7129",
   "description": "Shared Nuxt layer for DevOpsPlaybook web applications",
   "license": "ISC",
   "engines": {

package/services/AuthService.ts

@@ -49,15 +49,20 @@ export class AuthService {
   static async saveToken(token: string): Promise<void> {
     const storage = AuthService.storage();
     if (!storage) return;
+    const previous = storage.getItem(AUTH_TOKEN_KEY);
     storage.setItem(AUTH_TOKEN_KEY, token);
     for (const key of LEGACY_TOKEN_KEYS) storage.removeItem(key);
+    if (previous !== token) AuthService.emitAuthUpdated();
   }
 
   static async removeToken(_token?: string): Promise<void> {
     const storage = AuthService.storage();
     if (!storage) return;
-    storage.removeItem(AUTH_TOKEN_KEY);
-    for (const key of LEGACY_TOKEN_KEYS) storage.removeItem(key);
+    const keys = [AUTH_TOKEN_KEY, ...LEGACY_TOKEN_KEYS];
+    const present = keys.filter((key) => storage.getItem(key) !== null);
+    if (present.length === 0) return;
+    for (const key of keys) storage.removeItem(key);
+    AuthService.emitAuthUpdated();
   }
 
   static async getToken(): Promise<string | null> {
@@ -131,7 +136,10 @@ export class AuthService {
 
   private static async clearSession(): Promise<void> {
     await AuthService.removeToken();
-    EventBus.emit(EventTypes.AUTH_UPDATED);
+  }
+
+  private static emitAuthUpdated(): void {
+    EventBus.emit(EventTypes.AUTH_UPDATED, undefined);
   }
 
   private static async renewToken(token: string): Promise<string | null> {

package/services/AxiosAuthInterceptor.ts

@@ -0,0 +1,55 @@
+import axios, { AxiosHeaders } from "axios";
+import type { AxiosInstance } from "axios";
+import { AuthService } from "./AuthService";
+
+const REGISTRATION_MARKER = Symbol.for("common-web.axios-auth");
+
+type MarkedAxiosInstance = AxiosInstance & {
+  [key: symbol]: unknown;
+};
+
+function isLoginRequest(url: unknown): boolean {
+  if (typeof url !== "string" || url.length === 0) return false;
+  try {
+    const { pathname } = new URL(url, "http://localhost");
+    return pathname.replace(/\/+$/, "").endsWith("/users/session");
+  } catch {
+    return false;
+  }
+}
+
+export function registerAxiosAuthInterceptors(
+  instance: AxiosInstance = axios,
+): boolean {
+  const marked = instance as MarkedAxiosInstance;
+  if (marked[REGISTRATION_MARKER]) {
+    return false;
+  }
+  marked[REGISTRATION_MARKER] = true;
+
+  instance.interceptors.request.use(async (config) => {
+    const headers = AxiosHeaders.from(config.headers);
+    if (headers.get("Authorization") != null) {
+      return config;
+    }
+
+    const token = await AuthService.getToken();
+    if (token) {
+      headers.set("Authorization", `Bearer ${token}`);
+      config.headers = headers;
+    }
+    return config;
+  });
+
+  instance.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (error?.response?.status === 401 && !isLoginRequest(error?.config?.url)) {
+        await AuthService.removeToken();
+      }
+      return Promise.reject(error);
+    },
+  );
+
+  return true;
+}

package/services/Config.ts

@@ -2,8 +2,20 @@ export interface AppConfig {
   SERVER_URL: string;
 }
 
+const DEFAULT_CONFIG: AppConfig = { SERVER_URL: "/api" };
+
 export default class Config {
+  private static overrides: Partial<AppConfig> = {};
+
   static async get(): Promise<AppConfig> {
-    return { SERVER_URL: "/api" };
+    return { ...DEFAULT_CONFIG, ...Config.overrides };
+  }
+
+  static set(config: Partial<AppConfig>): void {
+    Config.overrides = { ...Config.overrides, ...config };
+  }
+
+  static reset(): void {
+    Config.overrides = {};
   }
 }

package/services/RefreshIntervalService.ts

@@ -3,10 +3,28 @@ export class RefreshIntervalService {
   static readonly DEFAULT = "10000";
 
   static get(): string {
-    return localStorage.getItem(RefreshIntervalService.KEY) ?? RefreshIntervalService.DEFAULT;
+    const stored = localStorage.getItem(RefreshIntervalService.KEY);
+    if (stored === null) return RefreshIntervalService.DEFAULT;
+    return (
+      RefreshIntervalService.normalise(stored) ??
+      RefreshIntervalService.DEFAULT
+    );
   }
 
   static set(value: string): void {
-    localStorage.setItem(RefreshIntervalService.KEY, value);
+    const normalised = RefreshIntervalService.normalise(value);
+    if (normalised === null) {
+      throw new TypeError(
+        `Invalid refresh interval: ${String(value)} (expected a non-negative integer string)`,
+      );
+    }
+    localStorage.setItem(RefreshIntervalService.KEY, normalised);
+  }
+
+  private static normalise(value: string): string | null {
+    if (!/^\d+$/.test(value)) return null;
+    const numeric = Number(value);
+    if (!Number.isSafeInteger(numeric)) return null;
+    return String(numeric);
   }
 }

package/services/UserService.ts

@@ -3,10 +3,14 @@ import Config from "./Config";
 
 export class UserService {
   static async isInitialized(): Promise<boolean> {
-    const config = await Config.get();
-    const response = await axios.get<{ initialized: boolean }>(
-      `${config.SERVER_URL}/users/status/initialization`,
-    );
-    return response.data.initialized;
+    try {
+      const config = await Config.get();
+      const response = await axios.get<{ initialized: boolean }>(
+        `${config.SERVER_URL}/users/status/initialization`,
+      );
+      return response.data.initialized === true;
+    } catch {
+      return false;
+    }
   }
 }

package/stores/AuthenticationStore.ts

@@ -1,18 +1,41 @@
 import { acceptHMRUpdate, defineStore } from "pinia";
-import { AuthService } from "../services/AuthService";
+import { ref } from "vue";
+import { EventBus, EventTypes } from "../composables/EventBus";
+import { AUTH_TOKEN_KEY, AuthService } from "../services/AuthService";
+
+let storageSyncRegistered = false;
+
+function registerStorageSync(): void {
+  if (storageSyncRegistered) return;
+  storageSyncRegistered = true;
+  window.addEventListener("storage", (event) => {
+    if (event.key === null || event.key === AUTH_TOKEN_KEY) {
+      EventBus.emit(EventTypes.AUTH_UPDATED, undefined);
+    }
+  });
+}
 
 export function createAuthenticationStore() {
-  return defineStore("AuthenticationStore", {
-    state: () => ({
-      isAuthenticated: false,
-    }),
-
-    actions: {
-      async ensureAuthenticated(): Promise<boolean> {
-        this.isAuthenticated = await AuthService.isAuthenticated();
-        return this.isAuthenticated;
-      },
-    },
+  return defineStore("AuthenticationStore", () => {
+    const isAuthenticated = ref(false);
+
+    async function refreshAuthentication(): Promise<void> {
+      isAuthenticated.value = await AuthService.isAuthenticated();
+    }
+
+    async function ensureAuthenticated(): Promise<boolean> {
+      await refreshAuthentication();
+      return isAuthenticated.value;
+    }
+
+    if (typeof window !== "undefined") {
+      EventBus.on(EventTypes.AUTH_UPDATED, () => {
+        void refreshAuthentication();
+      });
+      registerStorageSync();
+    }
+
+    return { isAuthenticated, ensureAuthenticated, refreshAuthentication };
   });
 }