@icecat-studio/nuxt-auth 0.1.0

package/dist/runtime/plugins/00.session-init.js

@@ -0,0 +1,131 @@
+import { defineNuxtPlugin, useAuth, useRuntimeConfig, useState } from "#imports";
+export default defineNuxtPlugin(async () => {
+  const config = useRuntimeConfig().public.auth;
+  const auth = useAuth();
+  const isServerManaged = config.refreshToken.serverManaged;
+  const shouldAutoFetch = config.user.autoFetch && config.endpoints.user;
+  const ssrRefreshResult = useState("auth:ssr-refresh-result", () => null);
+  if (import.meta.dev) {
+    console.log("[Auth] Session initialization starting:", {
+      isServer: import.meta.server,
+      isServerManaged,
+      canRefresh: auth.canRefresh.value,
+      shouldAutoFetch,
+      ssrRefreshResult: ssrRefreshResult.value
+    });
+  }
+  if (import.meta.client && import.meta.dev && ssrRefreshResult.value) {
+    console.log("[Auth] SSR refresh result:", ssrRefreshResult.value);
+  }
+  try {
+    await initializeSession();
+    if (import.meta.dev) {
+      console.log("[Auth] Session initialization completed:", {
+        isServer: import.meta.server,
+        status: auth.status.value,
+        hasAccessToken: !!auth.accessToken.value
+      });
+    }
+  } catch (error) {
+    if (import.meta.dev) {
+      console.error("[Auth] Session initialization failed:", error);
+    }
+  } finally {
+    if (import.meta.client) {
+      ssrRefreshResult.value = null;
+    }
+  }
+  async function initializeSession() {
+    const hasAccessToken = !!auth.accessToken.value;
+    const hasRefreshToken = !!auth.refreshToken.value;
+    if (import.meta.dev) {
+      console.log("[Auth] Checking session state:", {
+        isServer: import.meta.server,
+        hasAccessToken,
+        hasRefreshToken,
+        currentStatus: auth.status.value
+      });
+    }
+    if (auth.canRefresh.value) {
+      if (import.meta.dev) {
+        console.log("[Auth] Attempting refresh on first load", {
+          isServer: import.meta.server,
+          mode: isServerManaged ? "server-managed" : "client-managed"
+        });
+      }
+      if (import.meta.server) {
+        try {
+          await tryRefreshAndFetchUser();
+          ssrRefreshResult.value = {
+            attempted: true,
+            success: true
+          };
+        } catch (error) {
+          ssrRefreshResult.value = {
+            attempted: true,
+            success: false
+          };
+          throw error;
+        }
+        return;
+      }
+      if (ssrRefreshResult.value?.attempted) {
+        if (import.meta.dev) {
+          console.log("[Auth] Skipping client refresh - SSR already attempted", {
+            success: ssrRefreshResult.value.success
+          });
+        }
+        if (ssrRefreshResult.value.success) {
+          await fetchUserIfNeeded();
+        }
+        return;
+      }
+      await tryRefreshAndFetchUser();
+      return;
+    }
+    if (hasAccessToken) {
+      if (import.meta.dev) {
+        console.log("[Auth] Case 3: Has access token - restoring session");
+      }
+      await fetchUserIfNeeded();
+    } else if (import.meta.dev) {
+      console.log("[Auth] No tokens available - skipping session initialization");
+    }
+  }
+  async function tryRefreshAndFetchUser() {
+    try {
+      await auth.refresh();
+      await fetchUserIfNeeded();
+    } catch (error) {
+      if (!isServerManaged) {
+        auth.refreshToken.value = null;
+      }
+      throw error;
+    }
+  }
+  async function fetchUserIfNeeded() {
+    if (import.meta.server) {
+      auth.status.value = "authenticated";
+      return;
+    }
+    if (!auth.accessToken.value && auth.canRefresh.value) {
+      try {
+        await auth.refresh();
+      } catch {
+        return;
+      }
+    }
+    if (shouldAutoFetch) {
+      try {
+        await auth.fetchUser();
+      } catch (error) {
+        if (import.meta.dev) {
+          console.error("[Auth] Failed to fetch user:", error);
+        }
+        auth.status.value = "authenticated";
+      }
+    } else {
+      auth.status.value = "authenticated";
+    }
+  }
+});

package/dist/runtime/plugins/01.token-refresh.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/01.token-refresh.client.js

@@ -0,0 +1,102 @@
+import { defineNuxtPlugin, useAuth, useRuntimeConfig, watch } from "#imports";
+import { useTokenManager } from "../composables/useTokenManager.js";
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig().public.auth;
+  if (!config?.autoRefresh?.enabled || config?.endpoints?.refresh === false) {
+    return;
+  }
+  const auth = useAuth();
+  const tokenManager = useTokenManager();
+  let refreshTimer = null;
+  let isPageVisible = true;
+  let hasStarted = false;
+  const refreshInterval = config.autoRefresh.interval;
+  const pauseOnInactive = config.autoRefresh.pauseOnInactive;
+  const enableTabCoordination = config.autoRefresh.enableTabCoordination;
+  const coordinationThreshold = config.autoRefresh.coordinationThreshold;
+  const stop = () => {
+    if (refreshTimer) {
+      clearTimeout(refreshTimer);
+      refreshTimer = null;
+    }
+  };
+  const shouldSkipDueToCoordination = () => {
+    if (!enableTabCoordination) return false;
+    const lastCoordination = tokenManager.coordinationTimestamp.value;
+    if (!lastCoordination) return false;
+    return Date.now() - lastCoordination < coordinationThreshold * 1e3;
+  };
+  const performRefresh = async () => {
+    if (shouldSkipDueToCoordination()) {
+      if (import.meta.dev) {
+        console.debug("[Auth] Skipping refresh - another tab refreshed recently");
+      }
+      schedule();
+      return;
+    }
+    try {
+      await auth.refresh();
+      schedule();
+    } catch (error) {
+      const responseStatus = error?.response?.status;
+      const isServerRejection = responseStatus !== void 0 && responseStatus >= 400 && responseStatus < 500;
+      if (isServerRejection) {
+        if (import.meta.dev) {
+          console.debug("[Auth] Refresh rejected by server, stopping auto-refresh");
+        }
+      } else {
+        if (import.meta.dev) {
+          console.debug("[Auth] Refresh failed (network), retrying later:", error);
+        }
+        refreshTimer = setTimeout(performRefresh, refreshInterval * 2 * 1e3);
+      }
+    }
+  };
+  const schedule = (immediate = false) => {
+    stop();
+    if (pauseOnInactive && !isPageVisible) {
+      if (import.meta.dev) {
+        console.debug("[Auth] Pausing refresh - page is not visible");
+      }
+      return;
+    }
+    if (auth.canRefresh.value) {
+      if (immediate) {
+        refreshTimer = setTimeout(performRefresh, 0);
+      } else {
+        refreshTimer = setTimeout(performRefresh, refreshInterval * 1e3);
+      }
+    }
+  };
+  nuxtApp.provide("refreshManager", {
+    start: schedule,
+    stop,
+    refresh: () => auth.refresh()
+  });
+  if (auth.loggedIn.value) {
+    schedule();
+    hasStarted = true;
+  }
+  watch(() => auth.loggedIn.value, (isLoggedIn) => {
+    if (isLoggedIn && !hasStarted) {
+      schedule();
+      hasStarted = true;
+    } else if (!isLoggedIn) {
+      stop();
+      hasStarted = false;
+    }
+  });
+  if (pauseOnInactive && typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", () => {
+      isPageVisible = !document.hidden;
+      if (import.meta.dev) {
+        console.debug("[Auth] Page visibility changed:", isPageVisible ? "visible" : "hidden");
+      }
+      if (isPageVisible && hasStarted) {
+        schedule(true);
+      } else if (!isPageVisible) {
+        stop();
+      }
+    });
+  }
+});

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,201 @@
+import type { RouterMethod } from 'h3';
+import type { RequiredDeep } from 'type-fest';
+/**
+ * Base token options shared by access and refresh tokens
+ */
+export interface BaseTokenOptions {
+    /** Property name in API response containing the token. Default: 'accessToken' */
+    property?: string;
+    /** Cookie name. Default: 'auth.{tokenType}_token' */
+    cookieName?: string;
+    /** Prevents client-side access to the cookie. Default: false for accessToken, true for refreshToken */
+    httpOnly?: boolean;
+    /** Ensures cookie is only sent over HTTPS. Default: true in production */
+    secure?: boolean;
+    /** Controls cookie cross-site behavior. Default: 'lax' */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Cookie path. Default: '/' */
+    path?: string;
+    /** Cookie domain */
+    domain?: string;
+    /** Cookie expiration time in seconds */
+    maxAge?: number;
+}
+/**
+ * API endpoint configuration
+ */
+export interface Endpoint {
+    /** API endpoint path */
+    path?: string;
+    /** HTTP method for the request */
+    method?: RouterMethod;
+    /** Additional fetch options for this endpoint */
+    fetchOptions?: RequestInit;
+}
+/**
+ * Access token configuration
+ */
+export interface AccessTokenOptions extends BaseTokenOptions {
+    /** Token type prefix. Default: 'Bearer' */
+    type?: string;
+    /** Authorization header name. Default: 'Authorization' */
+    headerName?: string;
+}
+/**
+ * Refresh token configuration
+ */
+export interface RefreshTokenOptions extends BaseTokenOptions {
+    /** Storage name for localStorage/cookie. Default: 'auth.refresh_token' */
+    name?: string;
+    /**
+     * Indicates that refresh token is managed by the server via httpOnly cookie.
+     * When true, the refresh token won't be sent in the request body.
+     * Default: false
+     */
+    serverManaged?: boolean;
+    /**
+     * Property name used as key when sending refresh token in the request body.
+     * Only used when serverManaged is false.
+     * Default: 'refreshToken'
+     */
+    bodyProperty?: string;
+}
+/**
+ * Auto-refresh configuration
+ */
+export interface AutoRefreshOptions {
+    /** Enable automatic token refresh. Default: true */
+    enabled?: boolean;
+    /**
+     * Token refresh interval in seconds.
+     * When not set, automatically calculated as `accessToken.maxAge * 0.75`.
+     * For example, with default maxAge of 900s (15 min), interval will be 675s (~11 min).
+     */
+    interval?: number;
+    /**
+     * Pause refresh when page is not visible (hidden tab).
+     * Resumes when tab becomes visible again.
+     * Default: true
+     */
+    pauseOnInactive?: boolean;
+    /**
+     * Enable tab coordination to prevent multiple tabs from refreshing simultaneously.
+     * Uses a shared cookie to track the last refresh timestamp across all tabs.
+     * Default: true
+     */
+    enableTabCoordination?: boolean;
+    /**
+     * Cookie name for storing last refresh timestamp for tab coordination.
+     * Default: 'auth.last_refresh'
+     */
+    coordinationCookieName?: string;
+    /**
+     * Minimum time between refreshes across all tabs in seconds.
+     * If a refresh happened in another tab within this threshold, skip refresh.
+     * Default: 5 (5 seconds)
+     */
+    coordinationThreshold?: number;
+}
+/**
+ * User data configuration
+ */
+export interface UserOptions {
+    /**
+     * Property name in API response containing user data.
+     * If not specified or empty string, the entire response will be treated as user data.
+     * Default: undefined (entire response is user)
+     */
+    property?: string;
+    /** Automatically fetch user data on initialization. Default: true */
+    autoFetch?: boolean;
+}
+/**
+ * Redirect target configuration
+ */
+export interface RedirectTarget {
+    /** URL to redirect to */
+    url: string;
+    /**
+     * Use external navigation (allows redirecting to external URLs).
+     * When true, performs a full page reload.
+     * Default: false
+     */
+    external?: boolean;
+}
+/**
+ * Redirect configuration for auth flows
+ */
+export interface RedirectOptions {
+    /** Redirect path after logout or when unauthenticated. Default: '/login' */
+    login?: string | RedirectTarget;
+    /** Redirect path after logout. Default: '/' */
+    logout?: string | RedirectTarget;
+    /** Redirect path after successful login. Default: '/' */
+    home?: string | RedirectTarget;
+}
+/**
+ * Options for login function
+ */
+export interface LoginOptions {
+    /**
+     * Control redirect behavior after successful login:
+     * - false: Disable redirect
+     * - string: Custom redirect URL (overrides config.redirect.home)
+     * - RedirectTarget: Custom redirect with options
+     * - undefined: Use default redirect from config
+     */
+    redirect?: false | string | RedirectTarget;
+}
+/**
+ * Page meta configuration for auth
+ */
+export interface AuthPageMeta {
+    /**
+     * Auth configuration for the page:
+     * - true: Require authentication (redirect to login if not authenticated)
+     * - false: Public page (accessible to everyone)
+     * - 'guest' | 'guestOnly': Only for guests (redirect to home if authenticated)
+     * - undefined: Uses globalMiddleware setting
+     * @default undefined (uses globalMiddleware setting)
+     */
+    auth?: boolean | 'guest' | 'guestOnly';
+}
+/**
+ * Auth module configuration options
+ * These options can be passed in nuxt.config.ts under the 'auth' key
+ */
+export interface ModuleOptions {
+    /** Base URL for all auth API endpoints */
+    baseUrl?: string;
+    /** API endpoint configurations */
+    endpoints?: {
+        /** Login endpoint. Required for authentication */
+        login?: Endpoint;
+        /** Logout endpoint. Set to false to disable */
+        logout?: Endpoint | false;
+        /** Registration endpoint. Set to false to disable */
+        register?: Endpoint | false;
+        /** Token refresh endpoint. Set to false to disable */
+        refresh?: Endpoint | false;
+        /** User data fetch endpoint */
+        user?: Endpoint;
+    };
+    /** Access token configuration */
+    accessToken?: AccessTokenOptions;
+    /** Refresh token configuration */
+    refreshToken?: RefreshTokenOptions;
+    /** Auto-refresh configuration */
+    autoRefresh?: AutoRefreshOptions;
+    /** User data configuration */
+    user?: UserOptions;
+    /** Redirect paths for auth flows */
+    redirect?: RedirectOptions;
+    /** Enable global auth middleware on all pages. Default: false */
+    globalMiddleware?: boolean;
+}
+/**
+ * Module options with all defaults applied
+ * All fields are guaranteed to exist after defu merges with defaults
+ * This is what the composables receive at runtime
+ */
+export type ResolvedModuleOptions = RequiredDeep<ModuleOptions>;

package/dist/runtime/utils/helpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Type guard to check if value is an object with index signature
+ * @param value - The value to check
+ * @returns True if the value is an indexable object
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Get nested property value from an object using dot notation
+ * @param obj - The object to get the value from
+ * @param path - The path to the property (e.g., 'data.user.profile')
+ * @returns The value at the specified path or undefined
+ */
+export declare function getNestedProperty(obj: unknown, path: string): unknown;
+/**
+ * Set nested property value in an object using dot notation
+ * @param obj - The object to set the value in
+ * @param path - The path to the property (e.g., 'data.user.profile')
+ * @param value - The value to set
+ */
+export declare function setNestedProperty(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Check if a value is defined and not null
+ * @param value - The value to check
+ * @returns True if the value is defined and not null
+ */
+export declare function isDefined<T>(value: T | null | undefined): value is T;
+/**
+ * Safely parse JSON string
+ * @param str - The string to parse
+ * @param fallback - The fallback value if parsing fails
+ * @returns The parsed value or fallback
+ */
+export declare function safeJsonParse<T = unknown>(str: string, fallback?: T | null): T | null;

package/dist/runtime/utils/helpers.js

@@ -0,0 +1,37 @@
+export function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function getNestedProperty(obj, path) {
+  if (!isObject(obj)) {
+    return void 0;
+  }
+  return path.split(".").reduce((current, key) => {
+    if (isObject(current)) {
+      return current[key];
+    }
+    return void 0;
+  }, obj);
+}
+export function setNestedProperty(obj, path, value) {
+  const keys = path.split(".");
+  const lastKey = keys.pop();
+  if (!lastKey)
+    return;
+  const target = keys.reduce((current, key) => {
+    if (!current[key] || !isObject(current[key])) {
+      current[key] = {};
+    }
+    return current[key];
+  }, obj);
+  target[lastKey] = value;
+}
+export function isDefined(value) {
+  return value !== null && value !== void 0;
+}
+export function safeJsonParse(str, fallback = null) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return fallback;
+  }
+}

package/dist/runtime/utils/redirect.d.ts

@@ -0,0 +1,7 @@
+import type { RedirectTarget } from '../types.js';
+/**
+ * Handle redirect with support for both string URLs and RedirectTarget objects
+ * @param redirectConfig - URL string or RedirectTarget with external option
+ * @returns Navigation result or undefined if no redirect config provided
+ */
+export declare function handleRedirect(redirectConfig?: string | RedirectTarget): string | false | void | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric | Promise<false | void | import("vue-router").NavigationFailure>;

package/dist/runtime/utils/redirect.js

@@ -0,0 +1,6 @@
+import { navigateTo } from "#imports";
+export function handleRedirect(redirectConfig) {
+  if (!redirectConfig) return;
+  const target = typeof redirectConfig === "string" ? { url: redirectConfig, external: false } : redirectConfig;
+  return navigateTo(target.url, { external: target.external });
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { type ModuleOptions } from '../dist/runtime/types.js'
+
+export { default } from './module.mjs'

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@icecat-studio/nuxt-auth",
+  "version": "0.1.0",
+  "description": "Modern authentication module for Nuxt 3+ with token-based auth, auto-refresh, SSR support, and smart tab coordination",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/icecatstudio/nuxt-auth"
+  },
+  "keywords": [
+    "nuxt",
+    "nuxt3",
+    "nuxt-module",
+    "authentication",
+    "auth",
+    "jwt",
+    "token",
+    "refresh-token",
+    "ssr",
+    "session",
+    "login",
+    "authorization"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "Icecat Studio",
+    "url": "https://github.com/icecatstudio"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:client": "npm run dev:prepare && AUTH_MODE=client-managed nuxi dev playground",
+    "dev:server": "npm run dev:prepare && AUTH_MODE=server-managed nuxi dev playground",
+    "dev:no-refresh": "npm run dev:prepare && AUTH_MODE=no-refresh nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.1.3",
+    "defu": "^6.1.4"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^2.6.5",
+    "@nuxt/eslint-config": "^1.9.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.1.3",
+    "@nuxt/test-utils": "^3.19.2",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.37.0",
+    "nuxt": "^4.1.3",
+    "type-fest": "^5.0.1",
+    "typescript": "~5.9.3",
+    "vitest": "^3.2.4",
+    "vue-tsc": "^3.1.0"
+  }
+}