@icecat-studio/nuxt-auth 0.1.0

package/dist/module.mjs

@@ -0,0 +1,131 @@
+import { defineNuxtModule, createResolver, addPlugin, addRouteMiddleware, addImportsDir, addTypeTemplate } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "@icecat-studio/nuxt-auth",
+    configKey: "auth",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {
+    baseUrl: "/api/auth",
+    endpoints: {
+      login: { path: "/login", method: "post", fetchOptions: {} },
+      logout: { path: "/logout", method: "post", fetchOptions: {} },
+      register: { path: "/register", method: "post", fetchOptions: {} },
+      refresh: { path: "/refresh", method: "post", fetchOptions: {} },
+      user: { path: "/user", method: "get", fetchOptions: {} }
+    },
+    accessToken: {
+      property: "accessToken",
+      cookieName: "auth.access_token",
+      httpOnly: false,
+      secure: true,
+      sameSite: "lax",
+      path: "/",
+      maxAge: 60 * 15,
+      // 15 minutes
+      type: "Bearer",
+      headerName: "Authorization"
+    },
+    refreshToken: {
+      property: "refreshToken",
+      cookieName: "auth.refresh_token",
+      httpOnly: false,
+      secure: true,
+      sameSite: "lax",
+      path: "/",
+      maxAge: 60 * 60 * 24 * 7,
+      // 7 days
+      serverManaged: false,
+      bodyProperty: "refreshToken"
+    },
+    autoRefresh: {
+      enabled: true,
+      pauseOnInactive: true,
+      enableTabCoordination: true,
+      coordinationCookieName: "auth.last_refresh",
+      coordinationThreshold: 5
+      // 5 seconds
+    },
+    user: {
+      property: void 0,
+      autoFetch: true
+    },
+    redirect: {
+      login: "/login",
+      logout: "/",
+      home: "/"
+    },
+    globalMiddleware: false
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const resolvedOptions = defu(options, nuxt.options.auth || {});
+    if (resolvedOptions.autoRefresh?.interval === void 0) {
+      const maxAge = resolvedOptions.accessToken?.maxAge ?? 60 * 15;
+      resolvedOptions.autoRefresh = resolvedOptions.autoRefresh || {};
+      resolvedOptions.autoRefresh.interval = Math.round(maxAge * 0.75);
+    }
+    nuxt.options.runtimeConfig.public.auth = resolvedOptions;
+    addPlugin(resolver.resolve("./runtime/plugins/00.session-init"));
+    if (resolvedOptions.autoRefresh?.enabled !== false && resolvedOptions.endpoints?.refresh !== false) {
+      addPlugin(resolver.resolve("./runtime/plugins/01.token-refresh.client"));
+    }
+    addRouteMiddleware({
+      name: "auth",
+      path: resolver.resolve("./runtime/middleware/auth"),
+      global: true
+    });
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    addTypeTemplate({
+      filename: "types/nuxt-auth.d.ts",
+      getContents: () => `
+        declare module '#app' {
+          interface NuxtApp {
+            $auth: import('${resolver.resolve("./runtime/composables/useAuth")}').Auth
+            $refreshManager?: {
+              start: () => void
+              stop: () => void
+              refresh: () => Promise<void>
+            }
+          }
+        }
+
+        declare module 'nuxt/schema' {
+          interface PublicRuntimeConfig {
+            auth: import('${resolver.resolve("./runtime/types")}').ModuleOptions
+          }
+        }
+
+        declare module '@nuxt/schema' {
+          interface NuxtConfig {
+            auth?: import('${resolver.resolve("./runtime/types")}').ModuleOptions
+          }
+          interface NuxtOptions {
+            auth?: import('${resolver.resolve("./runtime/types")}').ModuleOptions
+          }
+        }
+
+        declare module 'vue-router' {
+          interface RouteMeta {
+            auth?: boolean | 'guest' | 'guestOnly'
+          }
+        }
+
+        declare module '@icecat-studio/nuxt-auth' {
+          interface User {
+            [key: string]: unknown
+          }
+        }
+
+        export {}
+      `
+    });
+  }
+});
+
+export { module as default };

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

@@ -0,0 +1,54 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { LoginOptions } from '../types.js';
+export type AuthStatus = 'idle' | 'loading' | 'refreshing' | 'authenticated' | 'unauthenticated';
+/**
+ * Default user interface - can be augmented via module declaration
+ * @example
+ * // In your project: types/auth.d.ts
+ * declare module '@icecat-studio/nuxt-auth' {
+ *   interface User {
+ *     id: number
+ *     email: string
+ *     name: string
+ *   }
+ * }
+ */
+export interface User {
+    [key: string]: unknown;
+}
+export interface LoginCredentials {
+    [key: string]: unknown;
+}
+export interface RegisterData {
+    [key: string]: unknown;
+}
+/**
+ * Auth composable return type
+ * @template TUser - User type, defaults to User interface
+ */
+export interface Auth<TUser = User> {
+    user: Ref<TUser | null>;
+    status: Ref<AuthStatus>;
+    loggedIn: ComputedRef<boolean>;
+    accessToken: Ref<string | null>;
+    refreshToken: Ref<string | null>;
+    canRefresh: ComputedRef<boolean>;
+    login: (credentials: LoginCredentials, options?: LoginOptions) => Promise<void>;
+    logout: () => Promise<void>;
+    register: (data: RegisterData) => Promise<void>;
+    refresh: () => Promise<void>;
+    fetchUser: () => Promise<void>;
+    getAuthHeaders: () => Record<string, string>;
+}
+/**
+ * Auth composable for managing authentication state
+ * @template TUser - User type, defaults to User interface (can be augmented globally)
+ * @example
+ * // Use with default User type (augmented globally)
+ * const auth = useAuth()
+ *
+ * // Or override with specific type
+ * interface CustomUser { id: number; email: string }
+ * const auth = useAuth<CustomUser>()
+ */
+export declare function useAuth<TUser = User>(): Auth<TUser>;

package/dist/runtime/composables/useAuth.js

@@ -0,0 +1,242 @@
+import { computed, useNuxtApp, useRuntimeConfig, useState } from "#imports";
+import { getNestedProperty, isObject } from "../utils/helpers.js";
+import { handleRedirect } from "../utils/redirect.js";
+import { useTokenManager } from "./useTokenManager.js";
+export function useAuth() {
+  const nuxtApp = useNuxtApp();
+  if (nuxtApp.$auth) {
+    return nuxtApp.$auth;
+  }
+  const config = useRuntimeConfig().public.auth;
+  const tokenManager = useTokenManager();
+  const user = useState("auth:user", () => null);
+  const status = useState("auth:status", () => "idle");
+  const refreshEnabled = config.endpoints.refresh !== false;
+  const canRefresh = computed(() => {
+    return refreshEnabled && (config.refreshToken.serverManaged || !!tokenManager.refreshToken.value);
+  });
+  const loggedIn = computed(() => {
+    if (canRefresh.value) {
+      return status.value === "authenticated" || status.value === "refreshing";
+    }
+    return status.value === "authenticated" && !!tokenManager.accessToken.value;
+  });
+  const setUser = (newUser) => {
+    user.value = newUser;
+    status.value = newUser ? "authenticated" : "unauthenticated";
+  };
+  const handleUserResponse = async (data) => {
+    if (config.user?.property) {
+      const userData = getNestedProperty(data, config.user.property);
+      if (userData && isObject(userData)) {
+        setUser(userData);
+        return;
+      }
+    }
+    if (config.user?.autoFetch !== false && config.endpoints?.user) {
+      await fetchUser();
+    } else {
+      status.value = "authenticated";
+    }
+  };
+  const login = async (credentials, options) => {
+    if (!config.endpoints?.login) {
+      throw new Error("Login endpoint is not configured");
+    }
+    status.value = "loading";
+    try {
+      const data = await $fetch(`${config.baseUrl}${config.endpoints.login.path}`, {
+        ...config.endpoints.login.fetchOptions,
+        method: config.endpoints.login.method,
+        body: credentials
+      });
+      tokenManager.setTokensFromResponse(data);
+      tokenManager.updateCoordinationCookie();
+      await handleUserResponse(data);
+      if (options?.redirect === false) {
+        return;
+      }
+      if (options?.redirect) {
+        handleRedirect(options.redirect);
+        return;
+      }
+      if (config.redirect?.home) {
+        handleRedirect(config.redirect.home);
+      }
+    } catch (error) {
+      status.value = "unauthenticated";
+      throw error;
+    }
+  };
+  const logout = async () => {
+    if (config.endpoints?.logout) {
+      try {
+        await $fetch(`${config.baseUrl}${config.endpoints.logout.path}`, {
+          ...config.endpoints.logout.fetchOptions,
+          method: config.endpoints.logout.method,
+          headers: tokenManager.getAuthHeaders()
+        });
+      } catch (error) {
+        console.error("[Auth] Logout request failed:", error);
+      }
+    }
+    tokenManager.clearTokens();
+    setUser(null);
+    tokenManager.clearCoordinationCookie();
+    if (import.meta.client && "$refreshManager" in nuxtApp) {
+      const refreshManager = nuxtApp.$refreshManager;
+      refreshManager?.stop();
+    }
+    handleRedirect(config.redirect?.logout);
+  };
+  const register = async (data) => {
+    if (!config.endpoints?.register) {
+      throw new Error("Register endpoint is not configured");
+    }
+    status.value = "loading";
+    try {
+      const response = await $fetch(`${config.baseUrl}${config.endpoints.register.path}`, {
+        ...config.endpoints.register.fetchOptions,
+        method: config.endpoints.register.method,
+        body: data
+      });
+      const accessTokenValue = config.accessToken?.property ? getNestedProperty(response, config.accessToken.property) : null;
+      if (accessTokenValue && typeof accessTokenValue === "string") {
+        tokenManager.setTokensFromResponse(response);
+        tokenManager.updateCoordinationCookie();
+        await handleUserResponse(response);
+        handleRedirect(config.redirect?.home);
+      } else {
+        status.value = "unauthenticated";
+        handleRedirect(config.redirect?.login);
+      }
+    } catch (error) {
+      status.value = "unauthenticated";
+      throw error;
+    }
+  };
+  let refreshPromise = null;
+  const refresh = async () => {
+    if (refreshPromise) {
+      if (import.meta.dev) {
+        console.debug("[Auth] Refresh already in progress, reusing existing request");
+      }
+      return refreshPromise;
+    }
+    refreshPromise = doRefresh();
+    try {
+      return await refreshPromise;
+    } finally {
+      refreshPromise = null;
+    }
+  };
+  const doRefresh = async () => {
+    if (!config.endpoints?.refresh) {
+      throw new Error("Refresh endpoint is not configured or disabled");
+    }
+    if (!config.refreshToken.serverManaged && !tokenManager.refreshToken.value) {
+      throw new Error("No refresh token available");
+    }
+    if (import.meta.dev) {
+      console.log("[Auth] Starting token refresh:", {
+        isServer: import.meta.server,
+        serverManaged: config.refreshToken.serverManaged,
+        endpoint: `${config.baseUrl}${config.endpoints.refresh.path}`
+      });
+    }
+    status.value = "refreshing";
+    try {
+      const body = config.refreshToken.serverManaged ? void 0 : { [config.refreshToken.bodyProperty]: tokenManager.refreshToken.value };
+      const headers = {};
+      if (import.meta.server) {
+        const event = nuxtApp.ssrContext?.event;
+        if (event) {
+          const cookieHeader = event.node.req.headers.cookie;
+          if (cookieHeader) {
+            headers.cookie = cookieHeader;
+            if (import.meta.dev) {
+              console.log("[Auth] Forwarding cookies on SSR:", cookieHeader);
+            }
+          }
+        }
+      }
+      const data = await $fetch(`${config.baseUrl}${config.endpoints.refresh.path}`, {
+        ...config.endpoints.refresh.fetchOptions,
+        method: config.endpoints.refresh.method,
+        body,
+        headers: {
+          ...config.endpoints.refresh.fetchOptions?.headers,
+          ...headers
+        }
+      });
+      tokenManager.setTokensFromResponse(data);
+      tokenManager.updateCoordinationCookie();
+      status.value = "authenticated";
+      if (import.meta.dev) {
+        console.log("[Auth] Token refresh successful:", {
+          isServer: import.meta.server,
+          hasAccessToken: !!tokenManager.accessToken.value
+        });
+      }
+    } catch (error) {
+      if (import.meta.dev) {
+        console.error("[Auth] Token refresh failed:", {
+          isServer: import.meta.server,
+          error
+        });
+      }
+      const responseStatus = error?.response?.status;
+      const isServerRejection = responseStatus !== void 0 && responseStatus >= 400 && responseStatus < 500;
+      if (isServerRejection) {
+        tokenManager.clearTokens();
+        tokenManager.clearCoordinationCookie();
+      }
+      status.value = isServerRejection ? "unauthenticated" : "authenticated";
+      throw error;
+    }
+  };
+  const fetchUser = async () => {
+    if (!config.endpoints?.user) {
+      throw new Error("User endpoint is not configured");
+    }
+    if (!tokenManager.accessToken.value) {
+      if (!canRefresh.value) {
+        status.value = "unauthenticated";
+      }
+      return;
+    }
+    if (status.value !== "authenticated") {
+      status.value = "loading";
+    }
+    try {
+      const data = await $fetch(`${config.baseUrl}${config.endpoints.user.path}`, {
+        ...config.endpoints.user.fetchOptions,
+        method: config.endpoints.user.method,
+        headers: tokenManager.getAuthHeaders()
+      });
+      const userData = config.user?.property ? getNestedProperty(data, config.user.property) : data;
+      if (isObject(userData)) {
+        setUser(userData);
+      }
+    } catch (error) {
+      status.value = "unauthenticated";
+      throw error;
+    }
+  };
+  const auth = {
+    user,
+    status,
+    loggedIn,
+    canRefresh,
+    accessToken: tokenManager.accessToken,
+    refreshToken: tokenManager.refreshToken,
+    login,
+    logout,
+    register,
+    refresh,
+    fetchUser,
+    getAuthHeaders: tokenManager.getAuthHeaders
+  };
+  nuxtApp.provide("auth", auth);
+  return auth;
+}

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

@@ -0,0 +1,13 @@
+import type { AvailableRouterMethod, NitroFetchOptions, NitroFetchRequest } from 'nitropack';
+/**
+ * Returns a `$fetch`-like function that automatically:
+ * - Adds Authorization headers
+ * - Forwards cookies on SSR (for httpOnly tokens)
+ * - On 401: refreshes token and retries the request (client-only)
+ *
+ * @example
+ * const authFetch = useAuthFetch()
+ * const data = await authFetch('/api/orders')
+ * const user = await authFetch<User>('/api/me')
+ */
+export declare function useAuthFetch(): <ResT = undefined, ReqT extends NitroFetchRequest = NitroFetchRequest, Method extends AvailableRouterMethod<ReqT> = ResT extends undefined ? "get" extends AvailableRouterMethod<ReqT> ? "get" : AvailableRouterMethod<ReqT> : AvailableRouterMethod<ReqT>>(request: ReqT, opts?: NitroFetchOptions<ReqT, Method>) => Promise<import("nitropack").TypedInternalResponse<ReqT, ResT, "get">>;

package/dist/runtime/composables/useAuthFetch.js

@@ -0,0 +1,57 @@
+import { useNuxtApp, useRuntimeConfig } from "#imports";
+import { useAuth } from "./useAuth.js";
+export function useAuthFetch() {
+  const auth = useAuth();
+  const nuxtApp = useNuxtApp();
+  const config = useRuntimeConfig().public.auth;
+  async function authFetch(request, opts) {
+    if (!auth.accessToken.value && auth.canRefresh.value) {
+      await auth.refresh();
+    }
+    try {
+      return await $fetch(request, withAuthHeaders(opts));
+    } catch (error) {
+      if (import.meta.client && isFetchError(error, 401)) {
+        try {
+          await auth.refresh();
+          return await $fetch(request, withAuthHeaders(opts));
+        } catch {
+          throw error;
+        }
+      }
+      throw error;
+    }
+  }
+  function withAuthHeaders(opts) {
+    const headers = {
+      ...toPlainHeaders(opts?.headers),
+      ...auth.getAuthHeaders()
+    };
+    if (import.meta.server) {
+      const event = nuxtApp.ssrContext?.event;
+      const cookieHeader = event?.node.req.headers.cookie;
+      if (cookieHeader) {
+        headers.cookie = cookieHeader;
+      }
+    }
+    return { ...opts, headers };
+  }
+  return authFetch;
+}
+function isFetchError(error, status) {
+  return typeof error === "object" && error !== null && "response" in error && error.response?.status === status;
+}
+function toPlainHeaders(headers) {
+  if (!headers) return {};
+  if (headers instanceof Headers) {
+    const plain = {};
+    headers.forEach((value, key) => {
+      plain[key] = value;
+    });
+    return plain;
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return { ...headers };
+}

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

@@ -0,0 +1,16 @@
+import type { Ref } from 'vue';
+export interface TokenManager {
+    accessToken: Ref<string | null>;
+    refreshToken: Ref<string | null>;
+    coordinationTimestamp: Readonly<Ref<number | null>>;
+    getAuthHeaders: () => Record<string, string>;
+    setTokensFromResponse: (data: unknown) => void;
+    clearTokens: () => void;
+    hasTokens: () => {
+        access: boolean;
+        refresh: boolean;
+    };
+    updateCoordinationCookie: () => void;
+    clearCoordinationCookie: () => void;
+}
+export declare function useTokenManager(): TokenManager;

package/dist/runtime/composables/useTokenManager.js

@@ -0,0 +1,103 @@
+import { useCookie, useRuntimeConfig, ref } from "#imports";
+import { getNestedProperty } from "../utils/helpers.js";
+export function useTokenManager() {
+  const config = useRuntimeConfig().public.auth;
+  const accessToken = useCookie(config.accessToken.cookieName, {
+    httpOnly: config.accessToken.httpOnly,
+    secure: config.accessToken.secure,
+    sameSite: config.accessToken.sameSite,
+    path: config.accessToken.path,
+    domain: config.accessToken.domain,
+    maxAge: config.accessToken.maxAge,
+    default: () => null
+  });
+  const refreshToken = config.endpoints?.refresh !== false && !config.refreshToken.serverManaged ? useCookie(config.refreshToken.cookieName, {
+    httpOnly: config.refreshToken.httpOnly,
+    secure: config.refreshToken.secure,
+    sameSite: config.refreshToken.sameSite,
+    path: config.refreshToken.path,
+    domain: config.refreshToken.domain,
+    maxAge: config.refreshToken.maxAge,
+    default: () => null
+  }) : ref(null);
+  const coordinationCookie = config.autoRefresh?.enableTabCoordination ? useCookie(config.autoRefresh.coordinationCookieName, {
+    maxAge: config.autoRefresh.interval * 2,
+    // 2x refresh interval (already in seconds)
+    sameSite: "lax",
+    default: () => null
+  }) : null;
+  const getAuthHeaders = () => {
+    const token = accessToken.value;
+    if (!token) return {};
+    const headerName = config.accessToken.headerName;
+    const tokenType = config.accessToken.type;
+    return {
+      [headerName]: `${tokenType} ${token}`
+    };
+  };
+  const setTokensFromResponse = (data) => {
+    if (config.accessToken.property) {
+      const token = getNestedProperty(data, config.accessToken.property);
+      if (token && typeof token === "string") {
+        accessToken.value = token;
+      }
+    }
+    if (config.endpoints?.refresh !== false && !config.refreshToken.serverManaged && config.refreshToken.property) {
+      const token = getNestedProperty(data, config.refreshToken.property);
+      if (token && typeof token === "string") {
+        refreshToken.value = token;
+      }
+    }
+  };
+  const clearTokens = () => {
+    accessToken.value = null;
+    if (config.endpoints?.refresh !== false && !config.refreshToken.serverManaged) {
+      refreshToken.value = null;
+    }
+  };
+  const hasTokens = () => {
+    return {
+      access: !!accessToken.value,
+      refresh: !!refreshToken.value
+    };
+  };
+  const updateCoordinationCookie = () => {
+    if (coordinationCookie) {
+      const previousValue = coordinationCookie.value;
+      coordinationCookie.value = Date.now();
+      if (import.meta.dev) {
+        console.log("[TokenManager] Updated coordination cookie:", {
+          previousTimestamp: previousValue,
+          newTimestamp: coordinationCookie.value,
+          timeSinceLast: previousValue ? Date.now() - previousValue : "N/A",
+          isServer: import.meta.server
+        });
+      }
+    } else if (import.meta.dev) {
+      console.log("[TokenManager] Coordination cookie not enabled");
+    }
+  };
+  const clearCoordinationCookie = () => {
+    if (coordinationCookie) {
+      if (import.meta.dev) {
+        console.log("[TokenManager] Clearing coordination cookie:", {
+          previousTimestamp: coordinationCookie.value,
+          isServer: import.meta.server
+        });
+      }
+      coordinationCookie.value = null;
+    }
+  };
+  const coordinationTimestamp = coordinationCookie ?? ref(null);
+  return {
+    accessToken,
+    refreshToken,
+    coordinationTimestamp,
+    getAuthHeaders,
+    setTokensFromResponse,
+    clearTokens,
+    hasTokens,
+    updateCoordinationCookie,
+    clearCoordinationCookie
+  };
+}

package/dist/runtime/middleware/auth.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").RouteMiddleware;
+export default _default;

package/dist/runtime/middleware/auth.js

@@ -0,0 +1,31 @@
+import { defineNuxtRouteMiddleware, useAuth, useRuntimeConfig } from "#imports";
+import { handleRedirect } from "../utils/redirect.js";
+export default defineNuxtRouteMiddleware(async (to) => {
+  const auth = useAuth();
+  const config = useRuntimeConfig().public.auth;
+  const authMeta = to.meta.auth;
+  if (authMeta === false) {
+    return;
+  }
+  if ((authMeta === "guest" || authMeta === "guestOnly") && auth.loggedIn.value) {
+    return handleRedirect(config.redirect.home);
+  }
+  const requiresAuth = authMeta === true || authMeta === void 0 && config.globalMiddleware;
+  if (requiresAuth && !auth.loggedIn.value) {
+    if (auth.canRefresh.value) {
+      try {
+        await auth.refresh();
+      } catch {
+      }
+    }
+    if (!auth.loggedIn.value) {
+      return handleRedirect(config.redirect.login);
+    }
+  }
+  if (auth.loggedIn.value && !auth.accessToken.value && auth.canRefresh.value) {
+    try {
+      await auth.refresh();
+    } catch {
+    }
+  }
+});

package/dist/runtime/plugins/00.session-init.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;