@peterbud/nuxt-aegis 1.1.0-alpha

package/README.md

@@ -0,0 +1,166 @@
+# Nuxt Aegis
+
+[![Build](https://github.com/peterbud/nuxt-aegis/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/peterbud/nuxt-aegis/actions/workflows/ci.yml)
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+**OAuth-based authentication with JWT token management for Nuxt 3/4**
+
+> [!WARNING]
+> **Experimental Module**: Nuxt Aegis is currently in active development and should be considered as work in progress. It is **not recommended for production use** at this time. APIs and features may change without notice.
+
+Nuxt Aegis is a a Nuxt module that orchestrates the authentication flow between external identity providers (Google, GitHub, Auth0, etc.) and your application. It handles the complexity of OAuth 2.0, JWT token generation, and automatic token refresh, letting you focus on your application logic.
+
+
+## Why Nuxt Aegis?
+
+Unlike cookie-based solutions that lock your API to the browser, Nuxt Aegis uses **industry-standard JWT bearer tokens**. This means your API is ready for:
+- 📱 Mobile applications
+- 🖥️ CLI tools
+- 🌐 Third-party integrations
+- ⚡ Universal access across platforms
+
+### How It Works
+
+1. **Authentication (Identity) Provider** (e.g., Google) authenticates the user.
+2. **Nuxt Aegis** verifies the identity retrieves the user information, and issues it's own application specific JWT.
+3. **Your App** receives the JWT token and uses it for authorization.
+
+You get full control over user data persistence while Aegis handles the security lifecycle.
+
+## ✨ Key Features
+
+- 🔐 **OAuth 2.0 & OpenID Connect** - Built-in support for Google, GitHub, Auth0, and Microsoft Entra ID.
+- 🔑 **Password Authentication** - Secure username/password flow with magic link verification.
+- 🎫 **JWT Management** - Automatic token generation, validation, and signing (HS256/RS256).
+- 🔄 **Auto-Refresh** - Seamless background token refresh with secure HTTP-only cookies.
+- 🛡️ **Route Protection** - Declarative middleware for both server API routes and client-side pages.
+- 🧪 **Mock Provider** - Built-in testing provider to simulate auth flows without external services.
+- 🎨 **Custom Claims** - Easily inject application-specific data (roles, permissions or similar) into tokens.
+- 🎭 **Impersonation** - Support for user impersonation with full audit logging
+- ⚙️ **SSR Friendly** - Works seamlessly with Nuxt's server-side rendering.
+- 🥽 **Type Safe** - Written in TypeScript with full type definitions for a great developer experience.
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+npx nuxi module add nuxt-aegis
+```
+
+### 2. Configure
+
+Add the module and provider configuration to `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['nuxt-aegis'],
+  
+  nuxtAegis: {
+    token: {
+      secret: process.env.NUXT_AEGIS_TOKEN_SECRET!,
+    },
+    providers: {
+      google: {
+        clientId: process.env.GOOGLE_CLIENT_ID!,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      },
+    },
+  },
+})
+```
+
+### 3. Create Auth Route
+
+Create a server route handler to initialize the provider:
+
+```typescript
+// server/routes/auth/google.get.ts
+export default defineOAuthGoogleEventHandler({
+  onUserInfo: (providerUserInfo, _tokens, _event) => {
+    return {
+      id: providerUserInfo.sub as string,
+      email: providerUserInfo.email,
+      name: providerUserInfo.name,
+    }
+  },
+})
+```
+
+### 4. Use in Components
+
+Access authentication state anywhere in your app:
+
+```vue
+<script setup lang="ts">
+const { user, isLoggedIn, login, logout } = useAuth()
+</script>
+
+<template>
+  <div v-if="isLoggedIn">
+    <h1>Welcome, {{ user?.name }}!</h1>
+    <button @click="logout()">Logout</button>
+  </div>
+  <button v-else @click="login('google')">
+    Login with Google
+  </button>
+</template>
+```
+
+## 📖 Documentation
+
+Ready to dive deeper? Check out the full documentation:
+
+- **[Getting Started](./docs/getting-started/installation.md)** - Installation and setup guides.
+- **[Providers](./docs/providers/)** - Configure Google, GitHub, Auth0, Password, and Mock providers.
+- **[Route Protection](./docs/guides/route-protection.md)** - Learn how to protect your pages and API routes.
+- **[Custom Claims](./docs/guides/custom-claims.md)** - Add custom data to your JWTs.
+- **[API Reference](./docs/api/)** - Detailed API documentation.
+
+## Contributing
+
+Contributions are welcome! Please see the [Requirements Specification](/specs/requirements.md) for detailed technical requirements.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Lint & type check
+pnpm lint
+```
+
+## License
+
+[MIT License](./LICENSE)
+
+## Acknowledgments
+
+- Built with [Nuxt Module Builder](https://github.com/nuxt/module-builder)
+- JWT handling powered by [jose](https://github.com/panva/jose)
+- Heavily inspired by the [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils) and  Nuxt community
+
+Made with ❤️ for the Nuxt community
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-aegis/latest.svg\?style\=flat\&colorA\=020420\&colorB\=00DC82
+[npm-version-href]: https://npmjs.com/package/@peterbud/nuxt-aegis
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-aegis.svg\?style\=flat\&colorA\=020420\&colorB\=00DC82
+[npm-downloads-href]: https://npm.chart.dev/@peterbud/nuxt-aegis
+
+[license-src]: https://img.shields.io/npm/l/nuxt-aegis.svg\?style\=flat\&colorA\=020420\&colorB\=00DC82
+[license-href]: https://npmjs.com/package/@peterbud/nuxt-aegis
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420\?logo\=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,6 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { ModuleOptions } from '../dist/runtime/types/index.js';
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-aegis",
+  "configKey": "nuxtAegis",
+  "version": "1.1.0-alpha",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,354 @@
+import { defineNuxtModule, updateRuntimeConfig, useLogger, createResolver, addPlugin, addImports, extendPages, addServerImportsDir, addServerImports, addServerHandler, addServerPlugin, addRouteMiddleware, addTemplate } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-aegis",
+    configKey: "nuxtAegis"
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {
+    devtools: true,
+    token: {
+      secret: "",
+      // Must be provided by user or generated
+      expiresIn: "1h",
+      // Access token expiry
+      algorithm: "HS256",
+      issuer: "nuxt-aegis",
+      audience: ""
+    },
+    tokenRefresh: {
+      enabled: true,
+      automaticRefresh: true,
+      cookie: {
+        cookieName: "nuxt-aegis-refresh",
+        maxAge: 60 * 60 * 24 * 7,
+        // 7 days
+        secure: true,
+        sameSite: "lax",
+        httpOnly: true,
+        path: "/"
+      },
+      encryption: {
+        enabled: false,
+        // SC-16: Encryption disabled by default
+        algorithm: "aes-256-gcm"
+        // SC-17: Default encryption algorithm
+      },
+      storage: {
+        driver: "fs",
+        // RS-10: Default to filesystem storage
+        prefix: "refresh:",
+        base: "./.data/refresh-tokens"
+      },
+      ssrTokenExpiry: "5m"
+      // SSR token expiry (short-lived)
+    },
+    authCode: {
+      expiresIn: 60
+      // CS-4, CF-9: Authorization code expiry in seconds (default 60s)
+    },
+    redirect: {
+      logout: "/",
+      success: "/",
+      error: "/"
+    },
+    clientMiddleware: {
+      enabled: false,
+      global: false,
+      redirectTo: "/login",
+      loggedOutRedirectTo: "/",
+      publicRoutes: []
+    },
+    endpoints: {
+      authPath: "/auth",
+      loginPath: "/auth",
+      callbackPath: "/auth/callback",
+      logoutPath: "/auth/logout",
+      refreshPath: "/auth/refresh",
+      userInfoPath: "/api/user/me"
+    },
+    logging: {
+      level: "info",
+      security: false
+    }
+  },
+  setup(options, nuxt) {
+    options.enableSSR = options.enableSSR ?? (nuxt.options.ssr === true ? true : false);
+    updateRuntimeConfig({
+      public: {
+        nuxtAegis: {
+          authPath: options.endpoints?.authPath || "/auth",
+          loginPath: options.endpoints?.loginPath || options.endpoints?.authPath || "/auth",
+          callbackPath: options.endpoints?.callbackPath || "/auth/callback",
+          logoutPath: options.endpoints?.logoutPath || "/auth/logout",
+          refreshPath: options.endpoints?.refreshPath || "/auth/refresh",
+          userInfoPath: options.endpoints?.userInfoPath || "/api/user/me",
+          redirect: options.redirect,
+          tokenRefresh: options.tokenRefresh,
+          clientMiddleware: options.clientMiddleware,
+          logging: options.logging,
+          enableSSR: options.enableSSR
+        }
+      },
+      nuxtAegis: options
+    });
+    const runtimeConfig = nuxt.options.runtimeConfig;
+    if (options.enableSSR && nuxt.options.ssr === false) {
+      const logger2 = useLogger("nuxt-aegis");
+      logger2.warn(
+        "nuxtAegis.enableSSR is true but Nuxt SSR is disabled. SSR authentication will not work. Set ssr: true in nuxt.config.ts or disable enableSSR."
+      );
+    }
+    const resolver = createResolver(import.meta.url);
+    if (options.tokenRefresh?.encryption?.enabled) {
+      const encryptionKey = options.tokenRefresh.encryption.key || process.env.NUXT_AEGIS_ENCRYPTION_KEY;
+      if (!encryptionKey) {
+        throw new Error(
+          "[Nuxt Aegis] Encryption is enabled but no encryption key is configured. Please set tokenRefresh.encryption.key in nuxt.config.ts or NUXT_AEGIS_ENCRYPTION_KEY environment variable."
+        );
+      }
+      if (!runtimeConfig.nuxtAegis) {
+        runtimeConfig.nuxtAegis = {};
+      }
+      if (!runtimeConfig.nuxtAegis.tokenRefresh) {
+        runtimeConfig.nuxtAegis.tokenRefresh = {};
+      }
+      if (!runtimeConfig.nuxtAegis.tokenRefresh.encryption) {
+        runtimeConfig.nuxtAegis.tokenRefresh.encryption = {};
+      }
+      runtimeConfig.nuxtAegis.tokenRefresh.encryption.key = encryptionKey;
+    }
+    addPlugin(resolver.resolve("./runtime/app/plugins/api.client"));
+    addImports([
+      {
+        name: "useAuth",
+        from: resolver.resolve("./runtime/app/composables/useAuth")
+      }
+    ]);
+    extendPages((pages) => {
+      pages.push({
+        name: "Callback",
+        path: `${runtimeConfig.nuxtAegis?.endpoints?.callbackPath}` || `${runtimeConfig.public.nuxtAegis.authPath}/callback`,
+        file: resolver.resolve("./runtime/app/pages/AuthCallback.vue")
+      });
+    });
+    addServerImportsDir(resolver.resolve("./runtime/server/providers"));
+    addServerImports([
+      // Authentication utilities (from auth.ts)
+      { name: "requireAuth", from: resolver.resolve("./runtime/server/utils/auth") },
+      { name: "getAuthUser", from: resolver.resolve("./runtime/server/utils/auth") },
+      { name: "generateAccessToken", from: resolver.resolve("./runtime/server/utils/auth") },
+      { name: "verifyToken", from: resolver.resolve("./runtime/server/utils/auth") },
+      { name: "generateAuthTokens", from: resolver.resolve("./runtime/server/utils/auth") },
+      // Refresh token management utilities (from refreshToken.ts)
+      { name: "revokeRefreshToken", from: resolver.resolve("./runtime/server/utils/refreshToken") },
+      { name: "deleteUserRefreshTokens", from: resolver.resolve("./runtime/server/utils/refreshToken") },
+      { name: "hashRefreshToken", from: resolver.resolve("./runtime/server/utils/refreshToken") },
+      // Cookie utilities (from cookies.ts)
+      { name: "setRefreshTokenCookie", from: resolver.resolve("./runtime/server/utils/cookies") },
+      { name: "getRefreshTokenFromCookie", from: resolver.resolve("./runtime/server/utils/cookies") },
+      // Custom claims utilities (from customClaims.ts)
+      { name: "applyCustomClaims", from: resolver.resolve("./runtime/server/utils/customClaims") },
+      // Handler utilities (from handler.ts)
+      { name: "defineAegisHandler", from: resolver.resolve("./runtime/server/utils/handler") },
+      { name: "useAegisHandler", from: resolver.resolve("./runtime/server/utils/handler") }
+    ]);
+    addServerHandler({
+      route: runtimeConfig.public.nuxtAegis.userInfoPath,
+      handler: resolver.resolve("./runtime/server/routes/me.get"),
+      method: "get"
+    });
+    addServerHandler({
+      route: runtimeConfig.public.nuxtAegis.logoutPath,
+      handler: resolver.resolve("./runtime/server/routes/logout.post"),
+      method: "post"
+    });
+    addServerHandler({
+      route: `${runtimeConfig.public.nuxtAegis.authPath}/token`,
+      handler: resolver.resolve("./runtime/server/routes/token.post"),
+      method: "post"
+    });
+    addServerHandler({
+      route: runtimeConfig.public.nuxtAegis.refreshPath,
+      handler: resolver.resolve("./runtime/server/routes/refresh.post"),
+      method: "post"
+    });
+    if (options.impersonation?.enabled) {
+      addServerHandler({
+        route: `${runtimeConfig.public.nuxtAegis.authPath}/impersonate`,
+        handler: resolver.resolve("./runtime/server/routes/impersonate.post"),
+        method: "post"
+      });
+      addServerHandler({
+        route: `${runtimeConfig.public.nuxtAegis.authPath}/unimpersonate`,
+        handler: resolver.resolve("./runtime/server/routes/unimpersonate.post"),
+        method: "post"
+      });
+    }
+    if (options.providers?.password) {
+      const passwordRoutes = [
+        { path: "password/register", file: "register.post", method: "post" },
+        { path: "password/register-verify", file: "register-verify.get", method: "get" },
+        { path: "password/login", file: "login.post", method: "post" },
+        { path: "password/login-verify", file: "login-verify.get", method: "get" },
+        { path: "password/reset-request", file: "reset-request.post", method: "post" },
+        { path: "password/reset-verify", file: "reset-verify.get", method: "get" },
+        { path: "password/reset-complete", file: "reset-complete.post", method: "post" },
+        { path: "password/change", file: "change.post", method: "post" }
+      ];
+      for (const route of passwordRoutes) {
+        addServerHandler({
+          route: `${runtimeConfig.public.nuxtAegis.authPath}/${route.path}`,
+          handler: resolver.resolve(`./runtime/server/routes/password/${route.file}`),
+          method: route.method
+        });
+      }
+    }
+    addServerHandler({
+      handler: resolver.resolve("./runtime/server/middleware/auth"),
+      middleware: true
+    });
+    if (options.enableSSR) {
+      addServerPlugin(resolver.resolve("./runtime/server/plugins/ssr-auth"));
+      addPlugin(resolver.resolve("./runtime/app/plugins/api.server"));
+      addPlugin(resolver.resolve("./runtime/app/plugins/ssr-state.server"));
+    }
+    const logger = useLogger("nuxt-aegis");
+    if (options.clientMiddleware?.enabled) {
+      const cm = options.clientMiddleware;
+      if (cm.global) {
+        const userPublicRoutes = cm.publicRoutes || [];
+        const redirectRoutes = [cm.redirectTo, cm.loggedOutRedirectTo];
+        const allPublicRoutes = [.../* @__PURE__ */ new Set([...userPublicRoutes, ...redirectRoutes])];
+        options.clientMiddleware.publicRoutes = allPublicRoutes;
+        if (allPublicRoutes.length === 0) {
+          throw new Error(
+            "[nuxt-aegis] clientMiddleware.global is enabled but no publicRoutes are configured. At minimum, the redirectTo and loggedOutRedirectTo routes will be automatically included."
+          );
+        }
+      } else {
+        const userPublicRoutes = cm.publicRoutes || [];
+        if (userPublicRoutes.length > 0) {
+          logger.warn(
+            "[nuxt-aegis] clientMiddleware.publicRoutes is configured but will be ignored because clientMiddleware.global is false. The auth-logged-in middleware will only run on pages where you explicitly add it via definePageMeta({ middleware: ['auth-logged-in'] })."
+          );
+        }
+      }
+      addRouteMiddleware({
+        name: "auth-logged-in",
+        path: resolver.resolve("./runtime/app/middleware/auth-logged-in"),
+        global: options.clientMiddleware.global === true
+      });
+      addRouteMiddleware({
+        name: "auth-logged-out",
+        path: resolver.resolve("./runtime/app/middleware/auth-logged-out"),
+        global: false
+      });
+    }
+    const isProduction = process.env.NODE_ENV === "production";
+    if (!isProduction) {
+      const mockConfig = options.providers?.mock;
+      if (mockConfig) {
+        addServerHandler({
+          route: `${runtimeConfig.public.nuxtAegis.authPath}/mock/authorize`,
+          handler: resolver.resolve("./runtime/server/routes/mock/authorize.get"),
+          method: "get"
+        });
+        addServerHandler({
+          route: `${runtimeConfig.public.nuxtAegis.authPath}/mock/token`,
+          handler: resolver.resolve("./runtime/server/routes/mock/token.post"),
+          method: "post"
+        });
+        addServerHandler({
+          route: `${runtimeConfig.public.nuxtAegis.authPath}/mock/userinfo`,
+          handler: resolver.resolve("./runtime/server/routes/mock/userinfo.get"),
+          method: "get"
+        });
+      }
+    }
+    if (!nuxt.options.nitro) {
+      nuxt.options.nitro = {};
+    }
+    if (!nuxt.options.nitro.experimental) {
+      nuxt.options.nitro.experimental = {};
+    }
+    nuxt.options.nitro.experimental.tasks = true;
+    nuxt.hook("nitro:config", (nitroConfig) => {
+      nitroConfig.scanDirs = nitroConfig.scanDirs || [];
+      nitroConfig.scanDirs.push(resolver.resolve("./runtime"));
+    });
+    if (!nuxt.options.nitro.scheduledTasks) {
+      nuxt.options.nitro.scheduledTasks = {};
+    }
+    nuxt.options.nitro.scheduledTasks["0 2 * * *"] = [
+      "cleanup:refresh-tokens",
+      "cleanup:magic-codes",
+      "cleanup:reset-sessions"
+    ];
+    if (!nuxt.options.nitro.storage) {
+      nuxt.options.nitro.storage = {};
+    }
+    const storageConfig = options.tokenRefresh?.storage || {};
+    nuxt.options.nitro.storage.refreshTokenStore = defu(nuxt.options.nitro.storage.refreshTokenStore, {
+      driver: storageConfig.driver || "fs",
+      base: storageConfig.base || "./.data/refresh-tokens"
+    });
+    nuxt.options.nitro.storage.authCodeStore = defu(nuxt.options.nitro.storage.authCodeStore, {
+      driver: "memory"
+    });
+    nuxt.options.nitro.storage.magicCodeStore = defu(nuxt.options.nitro.storage.magicCodeStore, {
+      driver: "memory"
+    });
+    nuxt.options.nitro.storage.resetSessionStore = defu(nuxt.options.nitro.storage.resetSessionStore, {
+      driver: "memory"
+    });
+    nuxt.hook("pages:routerOptions", (routerOptions) => {
+      routerOptions.files.push({
+        path: resolver.resolve("./runtime/app/router.options")
+      });
+    });
+    const typesPath = resolver.resolve("./runtime/types");
+    addTemplate({
+      filename: "types/nuxt-aegis.d.ts",
+      write: true,
+      getContents: () => {
+        return `import type { NitroAegisAuth, CustomTokenClaims } from ${JSON.stringify(typesPath)}
+
+type NuxtAegisRouteRules = {
+  /**
+   * Authentication requirement for this route
+   * - true | 'required' | 'protected': Route requires authentication
+   * - false | 'public' | 'skip': Route is public and skips authentication
+   * - undefined: Route is not protected (opt-in behavior)
+   */
+  auth?: NitroAegisAuth
+}
+
+declare module 'nitropack/types' {
+  interface NitroRouteRules {
+    nuxtAegis?: NuxtAegisRouteRules
+  }
+  interface NitroRouteConfig {
+    nuxtAegis?: NuxtAegisRouteRules
+  }
+}
+
+declare module 'nitropack' {
+  interface NitroRouteRules {
+    nuxtAegis?: NuxtAegisRouteRules
+  }
+  interface NitroRouteConfig {
+    nuxtAegis?: NuxtAegisRouteRules
+  }
+}
+
+// Export user-facing types for direct import
+export { type CustomTokenClaims }`;
+      }
+    });
+  }
+});
+
+export { module$1 as default };

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

@@ -0,0 +1,85 @@
+import type { ComputedRef } from 'vue';
+import type { TokenPayload } from '../../types/index.js';
+/**
+ * Return type for the useAuth composable
+ * @template T - Token payload type extending TokenPayload (defaults to TokenPayload)
+ */
+interface UseAuthReturn<T extends TokenPayload = TokenPayload> {
+    /** Reactive property indicating whether a user is logged in */
+    isLoggedIn: ComputedRef<boolean>;
+    /** Reactive property indicating the authentication state is being initialized */
+    isLoading: ComputedRef<boolean>;
+    /** Reactive property containing the current user's data */
+    user: ComputedRef<T | null>;
+    /** Error state for authentication operations */
+    error: ComputedRef<string | null>;
+    /** Reactive property indicating if currently impersonating another user */
+    isImpersonating: ComputedRef<boolean>;
+    /** Reactive property containing original user data when impersonating */
+    originalUser: ComputedRef<{
+        originalUserId: string;
+        originalUserEmail?: string;
+        originalUserName?: string;
+    } | null>;
+    /** Method to initiate the authentication flow */
+    login: (provider?: string, redirectTo?: string) => Promise<void>;
+    /** Method to end the user session */
+    logout: (redirectTo?: string) => Promise<void>;
+    /** Method to refresh the authentication state */
+    refresh: () => Promise<void>;
+    /** Method to impersonate another user (admin only) */
+    impersonate: (targetUserId: string, reason?: string) => Promise<void>;
+    /** Method to stop impersonation and restore original session */
+    stopImpersonation: () => Promise<void>;
+}
+/**
+ * Composable for managing authentication state and actions
+ *
+ * This composable provides methods for OAuth authentication using a CODE-based flow:
+ *
+ * Authentication Flow:
+ * 1. login() redirects to OAuth provider authentication page
+ * 2. Provider redirects back with short-lived authorization CODE (60s)
+ * 3. AuthCallback page exchanges CODE for JWT tokens via /auth/token
+ * 4. Access token stored in memory (reactive ref, cleared on refresh)
+ * 5. Refresh token stored as HttpOnly, Secure cookie
+ *
+ * Token Storage:
+ * - Access token in memory only (NOT sessionStorage)
+ * - Automatically cleared on page refresh/window close
+ * - Refresh token cookie used to obtain new access token after refresh
+ *
+ * State Management:
+ * - isLoggedIn reactive property (true when user authenticated)
+ * - isLoading reactive property (true during state initialization)
+ * - user reactive property (null when not authenticated)
+ * - State synchronized reactively across all components
+ *
+ * Methods:
+ * - login(provider) - Initiate OAuth flow
+ * - logout() - End user session
+ * - refresh() - Restore authentication state
+ *
+ * @template T - Custom token payload type extending TokenPayload
+ * @returns {UseAuthReturn<T>} Authentication state and methods
+ *
+ * @example
+ * ```typescript
+ * // Without custom claims (default)
+ * const { user, login, logout } = useAuth()
+ *
+ * // With custom claims
+ * import type { CustomTokenClaims } from '#build/types/nuxt-aegis'
+ *
+ * type AppTokenPayload = CustomTokenClaims<{
+ *   role: string
+ *   permissions: string[]
+ *   organizationId: string
+ * }>
+ *
+ * const { user, login, logout } = useAuth<AppTokenPayload>()
+ * // user.value?.role is now type-safe
+ * ```
+ */
+export declare function useAuth<T extends TokenPayload = TokenPayload>(): UseAuthReturn<T>;
+export {};