@meistrari/auth-nuxt 3.18.0 → 3.19.0

package/dist/runtime/helpers/refresh-scheduler.d.ts

@@ -0,0 +1,39 @@
+import type { RefreshOutcome } from './refresh-orchestrator.js';
+import type { RefreshPolicy } from './refresh-policy.js';
+/** Timer surface the scheduler drives (see `worker-timer.ts`) */
+export interface SchedulerTimer {
+    set: (delayMs: number, callback: () => void) => void;
+    clear: () => void;
+}
+export interface RefreshSchedulerDeps {
+    ensureFreshToken: (options?: {
+        force?: boolean;
+    }) => Promise<RefreshOutcome>;
+    /** Reads the live access token — must not be a stale captured ref */
+    readAccessToken: () => string | null;
+    parseTokenExpiry: (token: string) => number | null;
+    policy: RefreshPolicy;
+    timer: SchedulerTimer;
+    /**
+     * Invoked exactly once, only on a definitive auth failure (401/404).
+     * This is the scheduler's single exit; every other outcome reschedules
+     */
+    onAuthFailure: (error: unknown) => void | Promise<void>;
+    now?: () => number;
+    random?: () => number;
+    /** Optional sink for unexpected tick errors (defaults to console.error) */
+    onUnexpectedError?: (error: unknown) => void;
+}
+export interface RefreshScheduler {
+    /** Starts the loop with an immediate tick */
+    start: () => void;
+    /** Stops the loop and clears any pending timer */
+    stop: () => void;
+    /**
+     * Runs a tick now, replacing any pending timer. Safe to spam from
+     * `visibilitychange`/`online`/`focus` listeners: in-flight dedup and
+     * the orchestrator's freshness pre-check make redundant kicks free.
+     */
+    kick: () => void;
+}
+export declare function createRefreshScheduler(deps: RefreshSchedulerDeps): RefreshScheduler;

package/dist/runtime/helpers/refresh-scheduler.js

@@ -0,0 +1,90 @@
+import { computeBackoffDelay, computeNextRefreshDelay } from "./refresh-policy.js";
+export function createRefreshScheduler(deps) {
+  const {
+    ensureFreshToken,
+    readAccessToken,
+    parseTokenExpiry,
+    policy,
+    timer,
+    onAuthFailure,
+    now = () => Date.now(),
+    random = Math.random,
+    onUnexpectedError = (error) => console.error("[Tela Auth SDK] Unexpected token refresh scheduler error:", error)
+  } = deps;
+  let stopped = true;
+  let authFailed = false;
+  let running = false;
+  let kickPending = false;
+  let consecutiveFailures = 0;
+  function nextBackoffDelay() {
+    const delay = Math.max(
+      computeBackoffDelay(consecutiveFailures, policy, random),
+      policy.minRefreshIntervalMs
+    );
+    consecutiveFailures = Math.min(consecutiveFailures + 1, 10);
+    return delay;
+  }
+  async function tick() {
+    if (stopped || authFailed || running) {
+      return;
+    }
+    running = true;
+    let delay;
+    try {
+      const outcome = await ensureFreshToken();
+      if (outcome.status === "auth-failed") {
+        authFailed = true;
+        timer.clear();
+        await onAuthFailure(outcome.error);
+        return;
+      }
+      if (outcome.status === "ok") {
+        consecutiveFailures = 0;
+        const token = readAccessToken();
+        const expiry = token ? parseTokenExpiry(token) : null;
+        delay = computeNextRefreshDelay(expiry, now(), policy);
+      } else {
+        delay = nextBackoffDelay();
+      }
+    } catch (error) {
+      onUnexpectedError(error);
+      delay = nextBackoffDelay();
+    } finally {
+      running = false;
+    }
+    if (stopped || authFailed) {
+      return;
+    }
+    if (kickPending) {
+      kickPending = false;
+      void tick();
+      return;
+    }
+    timer.set(delay, () => void tick());
+  }
+  return {
+    start() {
+      if (authFailed) {
+        return;
+      }
+      stopped = false;
+      void tick();
+    },
+    stop() {
+      stopped = true;
+      kickPending = false;
+      timer.clear();
+    },
+    kick() {
+      if (stopped || authFailed) {
+        return;
+      }
+      if (running) {
+        kickPending = true;
+        return;
+      }
+      timer.clear();
+      void tick();
+    }
+  };
+}

package/dist/runtime/helpers/worker-timer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A single-slot timer backed by an inline Web Worker
+ *
+ * Unlike main-thread timers, Worker timers are NOT throttled when the tab
+ * is in the background, so scheduled refreshes fire reliably. Falls back
+ * to `setTimeout` where Workers are unavailable, tracking the fallback id
+ * so a re-`set()` can never stack duplicate timer loops
+ */
+export interface WorkerLike {
+    onmessage: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    postMessage: (message: unknown) => void;
+    terminate: () => void;
+}
+export interface WorkerTimerDeps {
+    /** Creates the timer worker; injectable for tests. Throw to force fallback */
+    createWorker?: () => WorkerLike;
+    setTimeoutFn?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+    clearTimeoutFn?: (id: ReturnType<typeof setTimeout>) => void;
+}
+export interface WorkerTimer {
+    /** Schedules `callback` after `delayMs`, replacing any pending timer */
+    set: (delayMs: number, callback: () => void) => void;
+    /** Cancels the pending timer, whichever mode it is running in */
+    clear: () => void;
+}
+export declare function createWorkerTimer(deps?: WorkerTimerDeps): WorkerTimer;

package/dist/runtime/helpers/worker-timer.js

@@ -0,0 +1,68 @@
+const WORKER_SCRIPT = "self.onmessage=function(e){setTimeout(function(){postMessage('tick')},e.data)}";
+function createBlobWorker() {
+  const blob = new Blob([WORKER_SCRIPT], { type: "application/javascript" });
+  const blobUrl = URL.createObjectURL(blob);
+  try {
+    return new Worker(blobUrl);
+  } finally {
+    URL.revokeObjectURL(blobUrl);
+  }
+}
+export function createWorkerTimer(deps = {}) {
+  const {
+    createWorker = createBlobWorker,
+    setTimeoutFn = (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimeoutFn = (id) => clearTimeout(id)
+  } = deps;
+  let worker = null;
+  let fallbackId = null;
+  let workerAvailable = true;
+  function clear() {
+    if (worker) {
+      worker.terminate();
+      worker = null;
+    }
+    if (fallbackId !== null) {
+      clearTimeoutFn(fallbackId);
+      fallbackId = null;
+    }
+  }
+  function scheduleFallback(delayMs, callback) {
+    fallbackId = setTimeoutFn(() => {
+      fallbackId = null;
+      callback();
+    }, delayMs);
+  }
+  function set(delayMs, callback) {
+    clear();
+    if (!workerAvailable) {
+      scheduleFallback(delayMs, callback);
+      return;
+    }
+    try {
+      const created = createWorker();
+      created.onmessage = () => {
+        if (worker !== created) {
+          return;
+        }
+        worker = null;
+        created.terminate();
+        callback();
+      };
+      created.onerror = () => {
+        if (worker === created) {
+          worker = null;
+        }
+        created.terminate();
+        workerAvailable = false;
+        scheduleFallback(delayMs, callback);
+      };
+      created.postMessage(delayMs);
+      worker = created;
+    } catch {
+      workerAvailable = false;
+      scheduleFallback(delayMs, callback);
+    }
+  }
+  return { set, clear };
+}

package/dist/runtime/plugins/application-token-refresh.js

@@ -1,12 +1,16 @@
 import { defineNuxtPlugin, navigateTo, useCookie, useRoute, useRuntimeConfig } from "#app";
-import { isTokenExpired } from "@meistrari/auth-core";
+import { RefreshTokenExpiredError } from "@meistrari/auth-core";
 import { useTelaApplicationAuth } from "../composables/application/auth.js";
 import { useApplicationSessionState } from "../composables/state.js";
 import { createNuxtAuthClient } from "../shared.js";
+import { ACCESS_TOKEN_COOKIE, REFRESH_TOKEN_COOKIE, readClientCookie } from "../helpers/client-cookies.js";
+import { useRefreshOrchestrator } from "../helpers/refresh-deps.js";
+import { classifyRefreshStatus, DEFAULT_REFRESH_POLICY, extractHttpStatus } from "../helpers/refresh-policy.js";
+import { createRefreshScheduler } from "../helpers/refresh-scheduler.js";
+import { createWorkerTimer } from "../helpers/worker-timer.js";
 import { parseTokenExpiry } from "../helpers/token.js";
 const SEVEN_DAYS = 60 * 60 * 24 * 7;
 const FIFTEEN_MINUTES = 60 * 15;
-const TWO_MINUTES = 2 * 60 * 1e3;
 export default defineNuxtPlugin({
   name: "tela-application-token-refresh",
   enforce: "post",
@@ -21,108 +25,43 @@ export default defineNuxtPlugin({
     const loginPath = appConfig.application?.loginPath ?? "/login";
     const unauthorizedPath = appConfig.application?.unauthorizedPath ?? "/unauthorized";
     const exemptPaths = [loginPath, unauthorizedPath];
-    const accessTokenCookie = useCookie("tela-access-token", {
+    const accessTokenCookie = useCookie(ACCESS_TOKEN_COOKIE, {
       secure: !import.meta.dev,
       sameSite: "lax",
       maxAge: FIFTEEN_MINUTES
     });
-    const refreshTokenCookie = useCookie("tela-refresh-token", {
+    const refreshTokenCookie = useCookie(REFRESH_TOKEN_COOKIE, {
       httpOnly: true,
       secure: !import.meta.dev,
       sameSite: "lax",
       maxAge: SEVEN_DAYS
     });
-    const authClient = createNuxtAuthClient(appConfig.apiUrl, () => null, () => refreshTokenCookie.value ?? null);
-    let isRefreshing = false;
-    let refreshWorker = null;
-    let workerAvailable = true;
-    async function refreshToken() {
-      if (isRefreshing) {
-        return;
-      }
-      isRefreshing = true;
-      try {
-        if (import.meta.server) {
-          const { accessToken, refreshToken: refreshToken2, user: user2, organization: organization2, assurance: assurance2 } = await authClient.application.refreshAccessToken(refreshTokenCookie.value ?? "");
-          accessTokenCookie.value = accessToken;
-          refreshTokenCookie.value = refreshToken2;
-          state.user.value = user2;
-          state.activeOrganization.value = organization2;
-          state.sessionAssurance.value = assurance2;
-          return true;
-        }
-        const { user, organization, assurance } = await $fetch("/auth/refresh", {
-          method: "POST"
-        });
-        state.user.value = user;
-        state.activeOrganization.value = organization;
-        state.sessionAssurance.value = assurance;
-        return true;
-      } catch {
-        await sdkLogout();
-        if (import.meta.client) {
-          const currentPath = decodeURI(route.path);
-          if (!exemptPaths.includes(currentPath)) {
-            await navigateTo({
-              path: loginPath,
-              query: { returnTo: route.fullPath }
-            });
-          }
-        }
-      } finally {
-        isRefreshing = false;
-      }
-    }
-    function logout() {
+    function clearLocalSession() {
       accessTokenCookie.value = null;
       state.user.value = null;
       state.activeOrganization.value = null;
       state.sessionAssurance.value = null;
     }
-    function scheduleWorkerTimeout(delayMs, callback) {
-      if (refreshWorker) {
-        refreshWorker.terminate();
-        refreshWorker = null;
-      }
-      try {
-        const workerScript = `self.onmessage=function(e){setTimeout(function(){postMessage('tick')},e.data)}`;
-        const blob = new Blob([workerScript], { type: "application/javascript" });
-        const blobUrl = URL.createObjectURL(blob);
-        const worker = new Worker(blobUrl);
-        URL.revokeObjectURL(blobUrl);
-        worker.onmessage = () => {
-          worker.terminate();
-          refreshWorker = null;
-          callback();
-        };
-        worker.onerror = () => {
-          worker.terminate();
-          refreshWorker = null;
-          workerAvailable = false;
-          window.setTimeout(callback, delayMs);
-        };
-        worker.postMessage(delayMs);
-        refreshWorker = worker;
-      } catch {
-        workerAvailable = false;
-        window.setTimeout(callback, delayMs);
-      }
-    }
-    async function scheduleTokenRefresh() {
-      if (!accessTokenCookie.value || isTokenExpired(accessTokenCookie.value, TWO_MINUTES)) {
-        const result = await refreshToken();
-        if (!result) {
+    if (import.meta.server) {
+      let handleServerRefreshFailure = function(error) {
+        const isAuthFailure = error instanceof RefreshTokenExpiredError || classifyRefreshStatus(extractHttpStatus(error)) === "auth";
+        if (isAuthFailure) {
+          console.error("[Tela Auth SDK] Refresh token rejected during SSR, clearing session:", error?.message);
+          refreshTokenCookie.value = null;
+          clearLocalSession();
           return;
         }
+        console.error("[Tela Auth SDK] Transient token refresh failure during SSR, leaving session for client recovery:", error?.message);
+      };
+      const authClient = createNuxtAuthClient(appConfig.apiUrl, () => null, () => refreshTokenCookie.value ?? null);
+      async function refreshOnServer() {
+        const { accessToken, refreshToken, user, organization, assurance } = await authClient.application.refreshAccessToken(refreshTokenCookie.value ?? "");
+        accessTokenCookie.value = accessToken;
+        refreshTokenCookie.value = refreshToken;
+        state.user.value = user;
+        state.activeOrganization.value = organization;
+        state.sessionAssurance.value = assurance;
       }
-      const expiry = parseTokenExpiry(accessTokenCookie.value);
-      if (!expiry) {
-        return;
-      }
-      const nextRefresh = Math.max(expiry - TWO_MINUTES - Date.now(), 0);
-      scheduleWorkerTimeout(nextRefresh, () => void scheduleTokenRefresh());
-    }
-    if (import.meta.server) {
       if (accessTokenCookie.value) {
         try {
           const data = await authClient.application.whoAmI(accessTokenCookie.value, {
@@ -135,23 +74,21 @@ export default defineNuxtPlugin({
           console.error("[Tela Auth SDK] Failed to get user and organization:", error.message);
           if (!refreshTokenCookie.value) {
             console.error("[Tela Auth SDK] Missing refresh token, logging out...");
-            logout();
+            clearLocalSession();
             return;
           }
           try {
-            await refreshToken();
-          } catch (error2) {
-            console.error("[Tela Auth SDK] Failed to refresh token:", error2.message);
-            logout();
+            await refreshOnServer();
+          } catch (refreshError) {
+            handleServerRefreshFailure(refreshError);
           }
         }
       }
       if (!accessTokenCookie.value && refreshTokenCookie.value) {
         try {
-          await refreshToken();
-        } catch (error) {
-          console.error("[Tela Auth SDK] Failed to refresh token:", error.message);
-          logout();
+          await refreshOnServer();
+        } catch (refreshError) {
+          handleServerRefreshFailure(refreshError);
         }
       }
       return;
@@ -169,12 +106,34 @@ export default defineNuxtPlugin({
           console.error("[Tela Auth SDK] Failed to load user info on client startup:", error);
         }
       }
-      void scheduleTokenRefresh();
+      const orchestrator = useRefreshOrchestrator(state);
+      const scheduler = createRefreshScheduler({
+        ensureFreshToken: orchestrator.ensureFreshToken,
+        readAccessToken: () => readClientCookie(ACCESS_TOKEN_COOKIE),
+        parseTokenExpiry,
+        policy: DEFAULT_REFRESH_POLICY,
+        timer: createWorkerTimer(),
+        // Reachable only from a definitive 401/404 — every other
+        // failure keeps the session and reschedules.
+        onAuthFailure: async () => {
+          await sdkLogout();
+          const currentPath = decodeURI(route.path);
+          if (!exemptPaths.includes(currentPath)) {
+            await navigateTo({
+              path: loginPath,
+              query: { returnTo: route.fullPath }
+            });
+          }
+        }
+      });
+      scheduler.start();
       document.addEventListener("visibilitychange", () => {
-        if (document.visibilityState === "visible" && !workerAvailable) {
-          void scheduleTokenRefresh();
+        if (document.visibilityState === "visible") {
+          scheduler.kick();
         }
       });
+      window.addEventListener("online", () => scheduler.kick());
+      window.addEventListener("focus", () => scheduler.kick());
     }
   }
 });

package/dist/runtime/plugins/handshake.js

@@ -2,7 +2,15 @@ import { defineNuxtPlugin, useCookie, useRequestURL, useRuntimeConfig } from "#a
 import { navigateTo, useRoute } from "#imports";
 import { watch } from "vue";
 import { useTelaSession } from "../composables/session.js";
+import { useOrganizationState } from "../composables/state.js";
+import { readClientCookie } from "../helpers/client-cookies.js";
+import { createRefreshOrchestrator } from "../helpers/refresh-orchestrator.js";
+import { DEFAULT_REFRESH_POLICY } from "../helpers/refresh-policy.js";
+import { createRefreshScheduler } from "../helpers/refresh-scheduler.js";
+import { parseTokenExpiry } from "../helpers/token.js";
+import { createWorkerTimer } from "../helpers/worker-timer.js";
 import { createNuxtAuthClient } from "../shared.js";
+const TOKEN_FETCH_TIMEOUT_MS = 15e3;
 export default defineNuxtPlugin({
   name: "tela-auth-handshake",
   enforce: "pre",
@@ -11,13 +19,23 @@ export default defineNuxtPlugin({
   },
   async setup() {
     const authConfig = useRuntimeConfig().public.telaAuth;
-    const { session, user, getToken } = useTelaSession();
+    const { session, user, signOut } = useTelaSession();
     const tokenCookie = useCookie(authConfig.jwtCookieName);
     tokenCookie.value = null;
     const authClient = createNuxtAuthClient(authConfig.apiUrl, () => tokenCookie.value ?? null);
     const query = useRoute().query;
     const nonce = query.nonce;
     const origin = useRequestURL();
+    async function initializeSession() {
+      if (session.value && user.value)
+        return;
+      const sessionData = await authClient.session.getSession();
+      if (!sessionData) {
+        return;
+      }
+      user.value = sessionData.user;
+      session.value = sessionData.session;
+    }
     if (import.meta.server) {
       if (nonce && typeof nonce === "string") {
         if (nonce !== "null") {
@@ -39,43 +57,97 @@ export default defineNuxtPlugin({
         });
         return;
       }
-    } else if (import.meta.client && !session.value) {
-      const token = await getToken();
-      if (token) {
-        tokenCookie.value = token;
+      if (tokenCookie.value) {
+        await initializeSession();
       }
-    }
-    async function initializeSession() {
-      if (session.value && user.value)
-        return;
-      const sessionData = await authClient.session.getSession();
-      if (!sessionData) {
-        return;
-      }
-      user.value = sessionData.user;
-      session.value = sessionData.session;
-    }
-    if (tokenCookie.value) {
-      await initializeSession();
+      return;
     }
     if (import.meta.client) {
-      let tokenRefreshInterval = null;
-      watch(session, async (newVal) => {
-        if (tokenRefreshInterval) {
-          clearTimeout(tokenRefreshInterval);
-          tokenRefreshInterval = null;
+      const readAccessToken = () => readClientCookie(authConfig.jwtCookieName) ?? tokenCookie.value ?? null;
+      async function signOutSafely() {
+        try {
+          await signOut();
+        } catch {
+          const { activeOrganization, activeMember } = useOrganizationState();
+          tokenCookie.value = null;
+          user.value = null;
+          session.value = null;
+          activeOrganization.value = null;
+          activeMember.value = null;
+        }
+      }
+      async function fetchToken() {
+        let timeoutId;
+        const timeout = new Promise((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error("Token fetch timed out")), TOKEN_FETCH_TIMEOUT_MS);
+        });
+        try {
+          const { token } = await Promise.race([authClient.session.getToken(), timeout]);
+          return token;
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      }
+      const orchestrator = createRefreshOrchestrator({
+        performRefresh: async () => {
+          tokenCookie.value = await fetchToken();
+        },
+        readAccessToken,
+        parseTokenExpiry,
+        policy: DEFAULT_REFRESH_POLICY,
+        lockName: "tela-auth-handshake-token-refresh"
+      });
+      let startupRefreshFailed = false;
+      if (!session.value) {
+        const outcome = await orchestrator.ensureFreshToken({ force: true });
+        if (outcome.status === "auth-failed") {
+          await signOutSafely();
+        }
+        startupRefreshFailed = outcome.status === "transient-failed" || outcome.status === "skipped-offline";
+      }
+      if (tokenCookie.value) {
+        await initializeSession();
+      }
+      const scheduler = createRefreshScheduler({
+        ensureFreshToken: orchestrator.ensureFreshToken,
+        readAccessToken,
+        parseTokenExpiry,
+        policy: DEFAULT_REFRESH_POLICY,
+        timer: createWorkerTimer(),
+        // Reachable only from a definitive 401/404 — every other
+        // failure keeps the session and reschedules. Middleware
+        // handles the redirect to the login page after sign-out.
+        onAuthFailure: async () => {
+          await signOutSafely();
         }
+      });
+      watch(session, (newVal) => {
         if (newVal) {
-          async function createTokenRefreshInterval() {
-            const token = await getToken();
-            if (token) {
-              tokenCookie.value = token;
-            }
-            tokenRefreshInterval = window.setTimeout(() => void createTokenRefreshInterval(), 6e4);
-          }
-          await createTokenRefreshInterval();
+          scheduler.start();
+        } else {
+          scheduler.stop();
         }
       }, { immediate: true });
+      if (startupRefreshFailed) {
+        const stopTokenWatch = watch(tokenCookie, async (token) => {
+          if (!token || session.value) {
+            return;
+          }
+          try {
+            await initializeSession();
+            stopTokenWatch();
+          } catch {
+          }
+        });
+        scheduler.start();
+      }
+      document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "visible") {
+          scheduler.kick();
+        }
+      });
+      window.addEventListener("online", () => scheduler.kick());
+      window.addEventListener("focus", () => scheduler.kick());
     }
   },
   hooks: {

package/dist/runtime/server/routes/auth/refresh.d.ts

@@ -9,11 +9,17 @@ import type { FullOrganization, JWTPayloadAssurance, User } from '@meistrari/aut
  * 4. Returns the user and organization data
  *
  * This keeps the refresh token secure by never exposing it to the client.
+ *
+ * Failures are differentiated so the client can react correctly:
+ * - Definitive auth failure → 401 `REFRESH_TOKEN_EXPIRED`, cookies deleted
+ * - Upstream rate limit → 429, cookies kept
+ * - Anything else (outage, network) → 503, cookies kept
  */
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
     success: boolean;
     user: User;
     organization: FullOrganization;
     assurance: JWTPayloadAssurance;
+    accessTokenExpiresAt: number | null;
 }>>;
 export default _default;