@meistrari/auth-nuxt 3.17.0 → 3.18.1

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@meistrari/auth-nuxt",
   "configKey": "telaAuth",
-  "version": "3.17.0",
+  "version": "3.18.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/composables/admin.d.ts

@@ -1,4 +1,4 @@
-import type { AdminApplicationRecord, AdminApplicationEntitlementRecord, AdminOrganization, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminOrganizationOptions, GetAdminOrganizationOptions, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminUsersOptions, ListAdminUsersResult, UpdateAdminOrganizationOptions } from '@meistrari/auth-core';
+import type { AdminApplicationRecord, AdminApplicationEntitlementRecord, AdminOrganization, AdminOrganizationTeamRecord, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminOrganizationOptions, CreateAdminOrganizationTeamOptions, GetAdminOrganizationOptions, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminOrganizationTeamsOptions, ListAdminOrganizationTeamsResult, ListAdminUsersOptions, ListAdminUsersResult, UpdateAdminOrganizationOptions } from '@meistrari/auth-core';
 export interface UseTelaAdminReturn {
     /**
      * Lists users from the Better Auth `user` table as a global admin.
@@ -52,6 +52,18 @@ export interface UseTelaAdminReturn {
      * @returns The paginated organization member listing
      */
     listOrganizationMembers: (options: ListAdminOrganizationMembersOptions) => Promise<ListAdminOrganizationMembersResult>;
+    /**
+     * Lists teams for a single organization as a global admin.
+     * @param options - Organization ID, pagination, search, and ordering options
+     * @returns The paginated organization team listing
+     */
+    listOrganizationTeams: (options: ListAdminOrganizationTeamsOptions) => Promise<ListAdminOrganizationTeamsResult>;
+    /**
+     * Creates a team for a single organization as a global admin.
+     * @param options - Organization ID, team name, and optional member user IDs
+     * @returns The created organization team
+     */
+    createOrganizationTeam: (options: CreateAdminOrganizationTeamOptions) => Promise<AdminOrganizationTeamRecord>;
     /**
      * Creates an organization as a global admin without joining it.
      * @param options - Organization name and optional slug, logo, metadata, and settings

package/dist/runtime/composables/admin.js

@@ -130,6 +130,12 @@ export function useTelaAdmin() {
   async function listOrganizationMembers(options) {
     return await authClient.admin.listOrganizationMembers(options);
   }
+  async function listOrganizationTeams(options) {
+    return await authClient.admin.listOrganizationTeams(options);
+  }
+  async function createOrganizationTeam(options) {
+    return await authClient.admin.createOrganizationTeam(options);
+  }
   async function createOrganization(options) {
     return await authClient.admin.createOrganization(options);
   }
@@ -145,6 +151,8 @@ export function useTelaAdmin() {
     listOrganizations,
     getOrganization,
     listOrganizationMembers,
+    listOrganizationTeams,
+    createOrganizationTeam,
     createOrganization,
     updateOrganization
   };

package/dist/runtime/composables/application/auth.d.ts

@@ -60,15 +60,27 @@ export interface UseTelaApplicationAuthReturn {
      * for new access and refresh tokens. The server updates the cookies and returns
      * the user and organization data.
      *
-     * @throws {RefreshTokenExpiredError} If no refresh token is available or refresh fails
+     * Concurrent calls (including the SDK plugin's background refresh) share
+     * one in-flight request, and transient failures are retried with backoff
+     * before this rejects.
+     *
+     * @throws {RefreshTokenExpiredError} If the refresh token is definitively expired or revoked (401/404)
+     * @throws {ApplicationError} If the refresh failed transiently (network failure, outage, rate limit) —
+     * the session is still valid and the call can be retried. Check `error.status` for the HTTP status,
+     * `undefined` meaning no HTTP response was received.
      */
     refreshToken: () => Promise<void>;
     /**
      * Retrieves the current access token.
      * If the token is expired, or close to expiry, it will be refreshed automatically.
      *
+     * Stale-while-revalidate: when a refresh fails transiently (network
+     * failure, outage) but the current token is still valid, the current
+     * token is returned instead of throwing.
+     *
      * @returns The current access token
-     * @throws {RefreshTokenExpiredError} If the token is expired and cannot be refreshed
+     * @throws {RefreshTokenExpiredError} If the refresh token is definitively expired or revoked (401/404)
+     * @throws {ApplicationError} If the refresh failed transiently and the current token is hard-expired
      */
     getToken: () => Promise<string | null | undefined>;
 }

package/dist/runtime/composables/application/auth.js

@@ -1,7 +1,9 @@
 import { navigateTo, useCookie, useRuntimeConfig } from "#app";
-import { AuthorizationFlowError, isTokenExpired, RefreshTokenExpiredError, UserNotLoggedInError } from "@meistrari/auth-core";
+import { ApplicationError, AuthorizationFlowError, isTokenExpired, RefreshTokenExpiredError, UserNotLoggedInError } from "@meistrari/auth-core";
 import { useApplicationSessionState } from "../state.js";
-import { willTokenExpireIn } from "../../helpers/token.js";
+import { ACCESS_TOKEN_COOKIE, readClientCookie } from "../../helpers/client-cookies.js";
+import { useRefreshOrchestrator } from "../../helpers/refresh-deps.js";
+import { extractHttpStatus } from "../../helpers/refresh-policy.js";
 import { useTelaOrganization } from "./organization.js";
 const FIFTEEN_MINUTES = 60 * 15;
 const ONE_MINUTE = 60 * 1e3;
@@ -52,18 +54,24 @@ export function useTelaApplicationAuth() {
     state.sessionAssurance.value = null;
     await $fetch("/auth/logout", { method: "POST" });
   }
+  const orchestrator = useRefreshOrchestrator(state);
+  function readAccessToken() {
+    return readClientCookie(ACCESS_TOKEN_COOKIE) ?? accessTokenCookie.value ?? null;
+  }
   async function refreshToken() {
-    try {
-      const result = await $fetch("/auth/refresh", {
-        method: "POST"
-      });
-      state.user.value = result.user;
-      state.activeOrganization.value = result.organization;
-      state.sessionAssurance.value = result.assurance;
-    } catch (error) {
-      console.error("[Auth Refresh] Failed to refresh token:", error);
-      throw new RefreshTokenExpiredError();
+    const outcome = await orchestrator.ensureFreshToken({ force: true });
+    if (outcome.status === "ok") {
+      return;
+    }
+    if (outcome.status === "auth-failed") {
+      console.error("[Auth Refresh] Refresh token expired or revoked:", outcome.error);
+      throw new RefreshTokenExpiredError({ cause: outcome.error, status: extractHttpStatus(outcome.error) });
     }
+    console.error("[Auth Refresh] Transient token refresh failure:", "error" in outcome ? outcome.error : "offline");
+    throw new ApplicationError("Failed to refresh access token", {
+      cause: "error" in outcome ? outcome.error : void 0,
+      status: "error" in outcome ? extractHttpStatus(outcome.error) : void 0
+    });
   }
   async function initSession() {
     if (!accessTokenCookie.value) {
@@ -81,11 +89,22 @@ export function useTelaApplicationAuth() {
     await useTelaOrganization().setActiveOrganization(organizationId);
   }
   async function getToken() {
-    const shouldRefresh = accessTokenCookie.value ? willTokenExpireIn(accessTokenCookie.value, ONE_MINUTE * 2) : true;
-    if (shouldRefresh) {
-      await refreshToken();
+    const outcome = await orchestrator.ensureFreshToken();
+    if (outcome.status === "ok") {
+      return readAccessToken();
+    }
+    if (outcome.status === "auth-failed") {
+      console.error("[Auth Refresh] Refresh token expired or revoked:", outcome.error);
+      throw new RefreshTokenExpiredError({ cause: outcome.error, status: extractHttpStatus(outcome.error) });
+    }
+    const currentToken = readAccessToken();
+    if (currentToken && !isTokenExpired(currentToken)) {
+      return currentToken;
     }
-    return accessTokenCookie.value;
+    throw new ApplicationError("Failed to refresh access token", {
+      cause: "error" in outcome ? outcome.error : void 0,
+      status: "error" in outcome ? extractHttpStatus(outcome.error) : void 0
+    });
   }
   return {
     user: state.user,

package/dist/runtime/helpers/client-cookies.d.ts

@@ -0,0 +1,23 @@
+/** Cookie holding the application access token (readable JWT) */
+export declare const ACCESS_TOKEN_COOKIE = "tela-access-token";
+/** Cookie holding the application refresh token (httpOnly — invisible to JS) */
+export declare const REFRESH_TOKEN_COOKIE = "tela-refresh-token";
+/**
+ * Reads a cookie value straight from `document.cookie`
+ *
+ * This is the source of truth for all token freshness math: `useCookie`
+ * refs captured at setup time can go stale after the server rotates
+ * cookies via `Set-Cookie`, which is exactly when the scheduling math
+ * must not be wrong
+ *
+ * @returns The decoded cookie value, or `null` when absent or on the server
+ */
+export declare function readClientCookie(name: string): string | null;
+/**
+ * Re-syncs the `useCookie` refs for both auth cookies after the server
+ * rotated them, so reactive app code observes the new values.
+ *
+ * Reactive sugar only — freshness logic never depends on it, it always
+ * reads `document.cookie` via {@link readClientCookie}
+ */
+export declare function syncAuthCookieRefs(): void;

package/dist/runtime/helpers/client-cookies.js

@@ -0,0 +1,28 @@
+import { refreshCookie } from "#app";
+export const ACCESS_TOKEN_COOKIE = "tela-access-token";
+export const REFRESH_TOKEN_COOKIE = "tela-refresh-token";
+export function readClientCookie(name) {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const prefix = `${name}=`;
+  for (const part of document.cookie.split(";")) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith(prefix)) {
+      const value = trimmed.slice(prefix.length);
+      try {
+        return decodeURIComponent(value);
+      } catch {
+        return value;
+      }
+    }
+  }
+  return null;
+}
+export function syncAuthCookieRefs() {
+  if (import.meta.server) {
+    return;
+  }
+  refreshCookie(ACCESS_TOKEN_COOKIE);
+  refreshCookie(REFRESH_TOKEN_COOKIE);
+}

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

@@ -0,0 +1,37 @@
+import type { Ref } from 'vue';
+import type { FullOrganization, JWTPayload, User } from '@meistrari/auth-core';
+import type { RefreshOrchestrator, RefreshOrchestratorDeps } from './refresh-orchestrator.js';
+/** Success body of the `/auth/refresh` Nitro route */
+export interface RefreshResponseBody {
+    success: boolean;
+    user: User;
+    organization: FullOrganization;
+    assurance: JWTPayload['assurance'];
+    /** Epoch ms expiry of the freshly issued access token */
+    accessTokenExpiresAt: number | null;
+}
+interface ApplicationSessionState {
+    user: Ref<User | null>;
+    activeOrganization: Ref<FullOrganization | null>;
+    sessionAssurance: Ref<JWTPayload['assurance'] | null>;
+}
+/**
+ * Builds the orchestrator dependencies used by both the token-refresh
+ * plugin and `useTelaApplicationAuth`, so the two call sites can't drift
+ *
+ * `performRefresh` hits the Nitro `/auth/refresh` route with a bounded
+ * timeout (so a held Web Lock always releases), then updates session
+ * state and re-syncs the reactive cookie refs. Cookies themselves are
+ * rotated by the route via `Set-Cookie`
+ */
+export declare function buildRefreshDeps(state: ApplicationSessionState): RefreshOrchestratorDeps;
+/**
+ * Returns the refresh orchestrator for the current environment.
+ *
+ * On the client this is a singleton shared by the plugin and the
+ * composable, so their refreshes dedupe into one in-flight request.
+ * On the server each caller gets a throwaway instance — no state may
+ * leak across requests
+ */
+export declare function useRefreshOrchestrator(state: ApplicationSessionState): RefreshOrchestrator;
+export {};

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

@@ -0,0 +1,35 @@
+import { useCookie } from "#app";
+import { ACCESS_TOKEN_COOKIE, readClientCookie, syncAuthCookieRefs } from "./client-cookies.js";
+import { createRefreshOrchestrator } from "./refresh-orchestrator.js";
+import { DEFAULT_REFRESH_POLICY } from "./refresh-policy.js";
+import { parseTokenExpiry } from "./token.js";
+export function buildRefreshDeps(state) {
+  const accessTokenCookie = useCookie(ACCESS_TOKEN_COOKIE);
+  return {
+    performRefresh: async () => {
+      const result = await $fetch("/auth/refresh", {
+        method: "POST",
+        timeout: 15e3
+      });
+      state.user.value = result.user;
+      state.activeOrganization.value = result.organization;
+      state.sessionAssurance.value = result.assurance;
+      syncAuthCookieRefs();
+    },
+    // document.cookie is the live source of truth on the client; the
+    // useCookie ref covers SSR, where document is unavailable.
+    readAccessToken: () => readClientCookie(ACCESS_TOKEN_COOKIE) ?? accessTokenCookie.value ?? null,
+    parseTokenExpiry,
+    policy: DEFAULT_REFRESH_POLICY
+  };
+}
+let sharedOrchestrator = null;
+export function useRefreshOrchestrator(state) {
+  if (import.meta.server) {
+    return createRefreshOrchestrator(buildRefreshDeps(state));
+  }
+  if (!sharedOrchestrator) {
+    sharedOrchestrator = createRefreshOrchestrator(buildRefreshDeps(state));
+  }
+  return sharedOrchestrator;
+}

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

@@ -0,0 +1,64 @@
+import type { RefreshPolicy } from './refresh-policy.js';
+/**
+ * Result of an {@link RefreshOrchestrator.ensureFreshToken} call
+ *
+ * Always a concrete outcome — the orchestrator never throws and never
+ * resolves to `undefined`, so callers (the scheduler in particular)
+ * can't mistake a concurrent call for a failure
+ */
+export type RefreshOutcome = {
+    status: 'ok';
+    refreshed: boolean;
+} | {
+    status: 'skipped-offline';
+} | {
+    status: 'auth-failed';
+    error: unknown;
+} | {
+    status: 'transient-failed';
+    error: unknown;
+};
+/** Minimal Web Locks surface used by the orchestrator. */
+export interface RefreshLockManager {
+    request: <T>(name: string, callback: () => Promise<T>) => Promise<T>;
+}
+export interface RefreshOrchestratorDeps {
+    /**
+     * Performs one actual refresh: the network call plus any state/cookie
+     * updates. Must reject on failure; the rejection is classified via
+     * `extractHttpStatus`. Must be bounded (pass a fetch timeout) so a
+     * held Web Lock always releases
+     */
+    performRefresh: () => Promise<void>;
+    /** Reads the current access token from the live cookie source of truth */
+    readAccessToken: () => string | null;
+    /** Parses a JWT expiry to epoch ms, `null` when undecodable */
+    parseTokenExpiry: (token: string) => number | null;
+    policy: RefreshPolicy;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    /** Returns `false` only when the browser is known to be offline */
+    isOnline?: () => boolean;
+    /** Web Locks manager; omit/`null` where unavailable (older browsers, SSR) */
+    locks?: RefreshLockManager | null;
+    lockName?: string;
+}
+export interface RefreshOrchestrator {
+    /**
+     * Ensures the access token is fresh, refreshing it if needed
+     *
+     * Concurrent callers share one in-flight promise (a single network
+     * request). Cross-tab callers are serialized by a Web Lock, and a
+     * caller that waited on the lock re-reads the cookie afterwards so it
+     * rides a sibling tab's rotation without its own network call.
+     * Transient failures back off and retry up to the policy cap;
+     * only a definitive 401/404 yields `auth-failed`
+     *
+     * @param options.force - Skip freshness checks and always hit the network
+     */
+    ensureFreshToken: (options?: {
+        force?: boolean;
+    }) => Promise<RefreshOutcome>;
+}
+export declare function createRefreshOrchestrator(deps: RefreshOrchestratorDeps): RefreshOrchestrator;

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

@@ -0,0 +1,85 @@
+import { classifyRefreshStatus, computeBackoffDelay, extractHttpStatus } from "./refresh-policy.js";
+const DEFAULT_LOCK_NAME = "tela-auth-token-refresh";
+export function createRefreshOrchestrator(deps) {
+  const {
+    performRefresh,
+    readAccessToken,
+    parseTokenExpiry,
+    policy,
+    now = () => Date.now(),
+    sleep = async (ms) => await new Promise((resolve) => setTimeout(resolve, ms)),
+    random = Math.random,
+    isOnline = () => typeof navigator === "undefined" || navigator.onLine !== false,
+    locks = typeof navigator !== "undefined" && "locks" in navigator ? navigator.locks : null,
+    lockName = DEFAULT_LOCK_NAME
+  } = deps;
+  let inFlight = null;
+  function isTokenFresh() {
+    const token = readAccessToken();
+    if (!token) {
+      return false;
+    }
+    const expiry = parseTokenExpiry(token);
+    if (expiry === null) {
+      return false;
+    }
+    return expiry - now() > policy.refreshThresholdMs;
+  }
+  async function attemptWithinLock(force) {
+    if (!force && isTokenFresh()) {
+      return { kind: "ok", refreshed: false };
+    }
+    try {
+      await performRefresh();
+      return { kind: "ok", refreshed: true };
+    } catch (error) {
+      return { kind: "error", error };
+    }
+  }
+  async function attempt(force) {
+    if (locks) {
+      try {
+        return await locks.request(lockName, async () => await attemptWithinLock(force));
+      } catch {
+      }
+    }
+    return await attemptWithinLock(force);
+  }
+  async function run(force) {
+    try {
+      for (let retry = 0; ; retry++) {
+        if (!isOnline()) {
+          return { status: "skipped-offline" };
+        }
+        const result = await attempt(force);
+        if (result.kind === "ok") {
+          return { status: "ok", refreshed: result.refreshed };
+        }
+        const kind = classifyRefreshStatus(extractHttpStatus(result.error));
+        if (kind === "auth") {
+          return { status: "auth-failed", error: result.error };
+        }
+        if (retry >= policy.maxImmediateRetries) {
+          return { status: "transient-failed", error: result.error };
+        }
+        await sleep(computeBackoffDelay(retry, policy, random));
+      }
+    } catch (error) {
+      return { status: "transient-failed", error };
+    }
+  }
+  async function ensureFreshToken(options = {}) {
+    if (inFlight) {
+      return await inFlight;
+    }
+    const force = options.force ?? false;
+    if (!force && isTokenFresh()) {
+      return { status: "ok", refreshed: false };
+    }
+    inFlight = run(force).finally(() => {
+      inFlight = null;
+    });
+    return await inFlight;
+  }
+  return { ensureFreshToken };
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Pure refresh policy: failure classification, status extraction,
+ * backoff math, and schedule math
+ */
+/** How a refresh failure should be handled */
+export type RefreshFailureKind = 'auth' | 'transient';
+/** Timing knobs shared by the orchestrator and the scheduler */
+export interface RefreshPolicy {
+    /** Refresh this long before the access token expires (ms) */
+    refreshThresholdMs: number;
+    /** How many immediate in-place retries a single refresh attempt gets */
+    maxImmediateRetries: number;
+    /** Base delay for exponential backoff between retries (ms) */
+    retryBaseDelayMs: number;
+    /** Upper bound for any backoff delay (ms) */
+    retryMaxDelayMs: number;
+    /** Hard floor between two scheduled refreshes (ms) */
+    minRefreshIntervalMs: number;
+}
+/** Default timing policy */
+export declare const DEFAULT_REFRESH_POLICY: RefreshPolicy;
+/**
+ * Classifies a refresh failure by HTTP status
+ *
+ * Only a definitive 401/404 means the session is gone. Everything else —
+ * 429, 5xx, other 4xx, or no status at all (network failure) — is
+ * transient and must never log the user out
+ */
+export declare function classifyRefreshStatus(status: number | undefined): RefreshFailureKind;
+/**
+ * Extracts an HTTP status code from an unknown error shape
+ *
+ * Checks, in order: `status`, `statusCode`, `response.status`, then the
+ * same fields on `cause` (recursively, so wrapped SDK errors still yield
+ * the upstream status). Returns `undefined` for pure transport failures
+ */
+export declare function extractHttpStatus(error: unknown, depth?: number): number | undefined;
+/**
+ * Computes a full-jitter exponential backoff delay
+ *
+ * @param attempt - Zero-based retry attempt number
+ * @param policy - Timing policy providing base and max delays
+ * @param random - Random source in [0, 1); injectable for deterministic tests
+ */
+export declare function computeBackoffDelay(attempt: number, policy: Pick<RefreshPolicy, 'retryBaseDelayMs' | 'retryMaxDelayMs'>, random?: () => number): number;
+/**
+ * Computes the delay until the next scheduled refresh from the access
+ * token's expiry, clamped to a hard minimum interval
+ *
+ * A `null` expiry (missing or undecodable token) and an already-passed
+ * expiry both return `minRefreshIntervalMs` — never 0 — so a stale
+ * cookie read can never spin the scheduler into a hot loop
+ */
+export declare function computeNextRefreshDelay(expiryMs: number | null, nowMs: number, policy: Pick<RefreshPolicy, 'refreshThresholdMs' | 'minRefreshIntervalMs'>): number;

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

@@ -0,0 +1,32 @@
+export const DEFAULT_REFRESH_POLICY = {
+  refreshThresholdMs: 2 * 60 * 1e3,
+  maxImmediateRetries: 3,
+  retryBaseDelayMs: 1e3,
+  retryMaxDelayMs: 3e4,
+  minRefreshIntervalMs: 5e3
+};
+export function classifyRefreshStatus(status) {
+  return status === 401 || status === 404 ? "auth" : "transient";
+}
+export function extractHttpStatus(error, depth = 0) {
+  if (!error || typeof error !== "object" || depth > 4) {
+    return void 0;
+  }
+  const candidate = error;
+  for (const value of [candidate.status, candidate.statusCode, candidate.response?.status]) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return extractHttpStatus(candidate.cause, depth + 1);
+}
+export function computeBackoffDelay(attempt, policy, random = Math.random) {
+  const exponential = Math.min(policy.retryMaxDelayMs, policy.retryBaseDelayMs * 2 ** Math.max(attempt, 0));
+  return Math.floor(random() * exponential);
+}
+export function computeNextRefreshDelay(expiryMs, nowMs, policy) {
+  if (expiryMs === null) {
+    return policy.minRefreshIntervalMs;
+  }
+  return Math.max(expiryMs - policy.refreshThresholdMs - nowMs, policy.minRefreshIntervalMs);
+}

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/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;

package/dist/runtime/server/routes/auth/refresh.js

@@ -1,6 +1,8 @@
 import { createError, useRuntimeConfig } from "#imports";
 import { defineEventHandler, deleteCookie, getCookie, setCookie } from "h3";
+import { parseTokenExpiry } from "../../../helpers/token.js";
 import { createNuxtAuthClient } from "../../../shared.js";
+import { planRefreshFailure, shouldWriteTokens } from "../../utils/refresh-upstream.js";
 export default defineEventHandler(async (event) => {
   const config = useRuntimeConfig();
   const authConfig = config.public.telaAuth;
@@ -12,44 +14,62 @@ export default defineEventHandler(async (event) => {
       message: "No refresh token found"
     });
   }
+  const authClient = createNuxtAuthClient(
+    authConfig.apiUrl,
+    () => null,
+    () => refreshToken
+  );
+  let accessToken;
+  let newRefreshToken;
+  let user;
+  let organization;
+  let assurance;
   try {
-    const authClient = createNuxtAuthClient(
-      authConfig.apiUrl,
-      () => null,
-      () => refreshToken
-    );
-    const { accessToken, refreshToken: newRefreshToken, user, organization, assurance } = await authClient.application.refreshAccessToken(refreshToken);
-    setCookie(event, "tela-access-token", accessToken, {
-      secure: !import.meta.dev,
-      sameSite: "lax",
-      maxAge: 60 * 15,
-      // 15 minutes
-      priority: "high",
-      path: "/"
-    });
-    setCookie(event, "tela-refresh-token", newRefreshToken, {
-      secure: !import.meta.dev,
-      sameSite: "lax",
-      httpOnly: true,
-      maxAge: 60 * 60 * 24 * 7,
-      // 7 days
-      priority: "high",
-      path: "/"
-    });
-    return {
-      success: true,
-      user,
-      organization,
-      assurance
-    };
+    ({ accessToken, refreshToken: newRefreshToken, user, organization, assurance } = await authClient.application.refreshAccessToken(refreshToken));
   } catch (error) {
-    console.error("[Auth Refresh] Token refresh error:", error);
-    deleteCookie(event, "tela-access-token", { path: "/" });
-    deleteCookie(event, "tela-refresh-token", { path: "/" });
+    const plan = planRefreshFailure(error);
+    console.error(`[Auth Refresh] Token refresh error (responding ${plan.statusCode}):`, error);
+    if (plan.deleteCookies) {
+      deleteCookie(event, "tela-access-token", { path: "/" });
+      deleteCookie(event, "tela-refresh-token", { path: "/" });
+    }
     throw createError({
-      statusCode: 401,
-      statusMessage: "Unauthorized",
-      message: "Failed to refresh access token"
+      statusCode: plan.statusCode,
+      statusMessage: plan.statusMessage,
+      message: plan.message
+    });
+  }
+  const currentAccessToken = getCookie(event, "tela-access-token");
+  if (!shouldWriteTokens({ accessToken, refreshToken: newRefreshToken, currentAccessToken })) {
+    console.error("[Auth Refresh] Upstream returned unusable tokens, refusing to overwrite cookies");
+    throw createError({
+      statusCode: 503,
+      statusMessage: "Service Unavailable",
+      message: "REFRESH_UPSTREAM_UNAVAILABLE"
     });
   }
+  setCookie(event, "tela-access-token", accessToken, {
+    secure: !import.meta.dev,
+    sameSite: "lax",
+    maxAge: 60 * 15,
+    // 15 minutes
+    priority: "high",
+    path: "/"
+  });
+  setCookie(event, "tela-refresh-token", newRefreshToken, {
+    secure: !import.meta.dev,
+    sameSite: "lax",
+    httpOnly: true,
+    maxAge: 60 * 60 * 24 * 7,
+    // 7 days
+    priority: "high",
+    path: "/"
+  });
+  return {
+    success: true,
+    user,
+    organization,
+    assurance,
+    accessTokenExpiresAt: parseTokenExpiry(accessToken)
+  };
 });

package/dist/runtime/server/utils/refresh-upstream.d.ts

@@ -0,0 +1,28 @@
+/** How the `/auth/refresh` route should respond to an upstream failure */
+export interface RefreshFailurePlan {
+    statusCode: number;
+    statusMessage: string;
+    message: string;
+    /** Only a definitive auth failure may destroy the session cookies */
+    deleteCookies: boolean;
+}
+/**
+ * Maps an upstream refresh failure to the HTTP response the route should
+ * send, so the browser can distinguish "session revoked" (401, cookies
+ * deleted) from "API briefly down" (429/503, cookies kept).
+ */
+export declare function planRefreshFailure(error: unknown): RefreshFailurePlan;
+/**
+ * Guards cookie writes after a successful upstream refresh
+ *
+ * Rejects empty, undecodable, and already-expired tokens, plus access
+ * tokens strictly older than the one currently in the cookie — a delayed
+ * response must not overwrite a newer rotation. Grace-window reissues
+ * return the same token (equal `exp`), which stays writable.
+ */
+export declare function shouldWriteTokens(input: {
+    accessToken: string | null | undefined;
+    refreshToken: string | null | undefined;
+    currentAccessToken?: string | null;
+    nowMs?: number;
+}): boolean;

package/dist/runtime/server/utils/refresh-upstream.js

@@ -0,0 +1,46 @@
+import { RefreshTokenExpiredError } from "@meistrari/auth-core";
+import { classifyRefreshStatus, extractHttpStatus } from "../../helpers/refresh-policy.js";
+import { parseTokenExpiry } from "../../helpers/token.js";
+export function planRefreshFailure(error) {
+  const status = extractHttpStatus(error);
+  const isAuthFailure = error instanceof RefreshTokenExpiredError || error?.code === "REFRESH_TOKEN_EXPIRED" || status !== void 0 && classifyRefreshStatus(status) === "auth";
+  if (isAuthFailure) {
+    return {
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "REFRESH_TOKEN_EXPIRED",
+      deleteCookies: true
+    };
+  }
+  if (status === 429) {
+    return {
+      statusCode: 429,
+      statusMessage: "Too Many Requests",
+      message: "REFRESH_RATE_LIMITED",
+      deleteCookies: false
+    };
+  }
+  return {
+    statusCode: 503,
+    statusMessage: "Service Unavailable",
+    message: "REFRESH_UPSTREAM_UNAVAILABLE",
+    deleteCookies: false
+  };
+}
+export function shouldWriteTokens(input) {
+  const { accessToken, refreshToken, currentAccessToken, nowMs = Date.now() } = input;
+  if (!accessToken || !refreshToken) {
+    return false;
+  }
+  const expiry = parseTokenExpiry(accessToken);
+  if (expiry === null || expiry <= nowMs) {
+    return false;
+  }
+  if (currentAccessToken) {
+    const currentExpiry = parseTokenExpiry(currentAccessToken);
+    if (currentExpiry !== null && expiry < currentExpiry) {
+      return false;
+    }
+  }
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/auth-nuxt",
-  "version": "3.17.0",
+  "version": "3.18.1",
   "type": "module",
   "exports": {
     ".": {
@@ -36,11 +36,11 @@
     "docs": "nuxt-module-build prepare && typedoc"
   },
   "dependencies": {
-    "@meistrari/auth-core": "1.27.0",
+    "@meistrari/auth-core": "1.28.1",
     "jose": "6.1.3"
   },
   "peerDependencies": {
-    "nuxt": "^3.0.0 || ^4.0.0",
+    "nuxt": "^3.10.0 || ^4.0.0",
     "vue": "^3.0.0"
   },
   "devDependencies": {