@peterbud/nuxt-aegis 1.1.0-alpha

package/dist/runtime/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Nuxt Aegis Type Definitions
+ * Main barrel file for all type exports
+ */
+import './augmentations.js';
+export type { TokenPayload, TokenConfig, RefreshTokenData, RefreshResponse, ClaimsValidationConfig, CustomClaimsCallback, ImpersonationContext, CustomTokenClaims, ExtractClaims, } from './token.js';
+export type { OAuthProviderConfig, GoogleProviderConfig, MicrosoftProviderConfig, GithubProviderConfig, Auth0ProviderConfig, MockProviderConfig, CustomProviderConfig, OAuthConfig, } from './providers.js';
+export type { CookieConfig, TokenRefreshConfig, EncryptionConfig, StorageConfig, } from './refresh.js';
+export type { AuthCodeData, TokenExchangeRequest, TokenExchangeResponse, AuthCodeConfig, } from './authCode.js';
+export type { NitroAegisAuth, NuxtAegisRouteRules, ClientMiddlewareConfig, } from './routes.js';
+export type { OnError, OnUserInfo, OnSuccess, OnSuccessParams, } from './callbacks.js';
+export type { UserInfoHookPayload, SuccessHookPayload, ImpersonateCheckPayload, ImpersonateFetchTargetPayload, ImpersonateStartPayload, ImpersonateEndPayload, } from './hooks.js';
+export type { RedirectConfig, EndpointConfig, NuxtAegisRuntimeConfig, ModuleOptions, LoggingConfig, ImpersonationConfig, } from './config.js';

package/dist/runtime/types/index.js

@@ -0,0 +1 @@
+import "./augmentations";

package/dist/runtime/types/providers.d.ts

@@ -0,0 +1,212 @@
+import type { CustomClaimsCallback, OnError, OnUserInfo, OnSuccess } from './index.js';
+/**
+ * OAuth provider configuration types
+ * Defines configuration interfaces for all supported OAuth providers
+ */
+/**
+ * Base OAuth provider configuration
+ */
+export interface OAuthProviderConfig {
+    /** OAuth client ID from the provider */
+    clientId: string;
+    /** OAuth client secret from the provider */
+    clientSecret: string;
+    /** OAuth scopes to request from the provider */
+    scopes?: string[];
+    /** Authorization endpoint URL (override provider default) */
+    authorizeUrl?: string;
+    /** Token endpoint URL (override provider default) */
+    tokenUrl?: string;
+    /** User info endpoint URL (override provider default) */
+    userInfoUrl?: string;
+    /** Redirect URI for OAuth callback (defaults to authPath + '/providers/[provider]') */
+    redirectUri?: string;
+    /**
+     * Custom query parameters to append to the authorization URL
+     *
+     * These parameters will be included when redirecting to the OAuth provider's authorization endpoint.
+     * Custom parameters override default parameters, but critical OAuth parameters (client_id, redirect_uri,
+     * code, grant_type) are protected and cannot be overridden for security reasons.
+     *
+     * @example
+     * // Google-specific parameters
+     * authorizationParams: {
+     *   access_type: 'offline',    // Request refresh token
+     *   prompt: 'consent',         // Force consent screen
+     * }
+     *
+     * @example
+     * // Auth0-specific parameters
+     * authorizationParams: {
+     *   prompt: 'login',           // Force login screen
+     *   screen_hint: 'signup',     // Show signup page
+     * }
+     */
+    authorizationParams?: Record<string, string>;
+}
+/**
+ * Google OAuth provider configuration
+ */
+export interface GoogleProviderConfig extends Partial<OAuthProviderConfig> {
+    /** Google OAuth client ID */
+    clientId: string;
+    /** Google OAuth client secret */
+    clientSecret: string;
+    /** Google OAuth scopes (default: ['openid', 'profile', 'email']) */
+    scopes?: string[];
+}
+/**
+ * Microsoft OAuth provider configuration
+ */
+export interface MicrosoftProviderConfig extends Partial<OAuthProviderConfig> {
+    /** Microsoft OAuth client ID */
+    clientId: string;
+    /** Microsoft OAuth client secret */
+    clientSecret: string;
+    /** Microsoft tenant ID or 'common', 'organizations', 'consumers' (default: 'common') */
+    tenant?: string;
+    /** Microsoft OAuth scopes (default: ['openid', 'profile', 'email']) */
+    scopes?: string[];
+}
+/**
+ * GitHub OAuth provider configuration
+ */
+export interface GithubProviderConfig extends Partial<OAuthProviderConfig> {
+    /** GitHub OAuth client ID */
+    clientId: string;
+    /** GitHub OAuth client secret */
+    clientSecret: string;
+    /** GitHub OAuth scopes (default: ['user:email']) */
+    scopes?: string[];
+}
+/**
+ * Auth0 OAuth provider configuration
+ */
+export interface Auth0ProviderConfig extends Partial<OAuthProviderConfig> {
+    /** Auth0 OAuth client ID */
+    clientId: string;
+    /** Auth0 OAuth client secret */
+    clientSecret: string;
+    /** Auth0 domain (e.g., 'your-tenant.auth0.com' or 'your-tenant.us.auth0.com') */
+    domain?: string;
+    /** Auth0 OAuth scopes (default: ['openid', 'profile', 'email']) */
+    scopes?: string[];
+}
+/**
+ * Password provider configuration
+ */
+export interface PasswordProviderConfig {
+    /** Magic code time-to-live in seconds (default: 600 = 10 minutes) */
+    magicCodeTTL?: number;
+    /** Maximum magic code verification attempts (default: 5) */
+    magicCodeMaxAttempts?: number;
+    /** Password hashing rounds (default: 12) */
+    passwordHashRounds?: number;
+    /** Password policy configuration */
+    passwordPolicy?: {
+        /** Minimum password length (default: 8) */
+        minLength?: number;
+        /** Require uppercase letter (default: true) */
+        requireUppercase?: boolean;
+        /** Require lowercase letter (default: true) */
+        requireLowercase?: boolean;
+        /** Require number (default: true) */
+        requireNumber?: boolean;
+        /** Require special character (default: false) */
+        requireSpecial?: boolean;
+    };
+}
+/**
+ * Password user interface
+ */
+export interface PasswordUser {
+    /** User ID (optional) */
+    id?: string;
+    /** User email */
+    email: string;
+    /** Hashed password */
+    hashedPassword: string;
+    /** Additional user properties */
+    [key: string]: unknown;
+}
+/**
+ * Mock provider configuration (for testing)
+ */
+export interface MockProviderConfig extends Partial<OAuthProviderConfig> {
+    /** Mock OAuth client ID (required, can be any string) */
+    clientId: string;
+    /** Mock OAuth client secret (required, can be any string) */
+    clientSecret: string;
+    /**
+     * Mock user personas for testing different user scenarios
+     * Each key is a user identifier, value contains user profile data
+     * Required fields: sub (subject), email, name
+     *
+     * @example
+     * mockUsers: {
+     *   admin: {
+     *     sub: 'mock-user-admin',
+     *     email: 'admin@example.com',
+     *     name: 'Admin User',
+     *     role: 'admin',
+     *   },
+     *   user: {
+     *     sub: 'mock-user-001',
+     *     email: 'user@example.com',
+     *     name: 'Regular User',
+     *   },
+     * }
+     */
+    mockUsers: Record<string, {
+        /** Subject identifier (required) */
+        sub: string;
+        /** User email (required) */
+        email: string;
+        /** User display name (required) */
+        name: string;
+        /** Additional custom claims */
+        [key: string]: unknown;
+    }>;
+    /**
+     * Default user to return when no ?user= parameter specified
+     * Must match a key in mockUsers
+     */
+    defaultUser?: string;
+    /**
+     * Allow mock provider in production (NOT RECOMMENDED)
+     * Default: false
+     * @deprecated For testing purposes only - never use in production
+     */
+    enableInProduction?: boolean;
+}
+/**
+ * Custom OAuth provider configuration
+ */
+export interface CustomProviderConfig extends OAuthProviderConfig {
+    /** Unique name identifier for the custom provider */
+    name: string;
+}
+/**
+ * OAuth configuration wrapper
+ */
+export interface OAuthConfig<TConfig> {
+    config?: Partial<TConfig>;
+    onError?: OnError;
+    /**
+     * Custom claims to add to the generated JWT
+     * Can be a static object or a callback function that receives user and tokens
+     */
+    customClaims?: Record<string, string | number | boolean | Array<string | number | boolean> | null> | CustomClaimsCallback;
+    /**
+     * User information transformation hook (provider-level)
+     * Called after fetching user info from the provider, before storing it
+     * Allows provider-specific user object shaping
+     */
+    onUserInfo?: OnUserInfo;
+    /**
+     * Success hook (provider-level)
+     * Called after successful authentication, before generating authorization CODE
+     * Use for side effects like database storage
+     */
+    onSuccess?: OnSuccess;
+}

package/dist/runtime/types/refresh.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Token refresh and cookie configuration types
+ */
+/**
+ * Refresh cookie configuration
+ */
+export interface CookieConfig {
+    /** Name of the refresh cookie (default: 'nuxt-aegis-refresh') */
+    cookieName?: string;
+    /** Refresh cookie max age in seconds (default: 604800 - 7 days) */
+    maxAge?: number;
+    /** Enable secure flag for cookies (default: true in production) */
+    secure?: boolean;
+    /** SameSite cookie attribute (default: 'lax') */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /** HttpOnly flag for cookies (default: true) */
+    httpOnly?: boolean;
+    /** Cookie path (default: '/') */
+    path?: string;
+    /** Cookie domain (optional) */
+    domain?: string;
+}
+/**
+ * Encryption configuration for refresh token storage
+ */
+export interface EncryptionConfig {
+    /** SC-16: Enable encryption-at-rest for user data (default: false) */
+    enabled?: boolean;
+    /** SC-18: Encryption key (loaded from environment variable) */
+    key?: string;
+    /** SC-17: Encryption algorithm (default: 'aes-256-gcm') */
+    algorithm?: 'aes-256-gcm';
+}
+/**
+ * Storage configuration for refresh tokens
+ */
+export interface StorageConfig {
+    /** RS-10: Storage driver to use (default: 'fs' for filesystem) */
+    driver?: 'fs' | 'redis' | 'memory';
+    /** Key prefix for refresh tokens in storage (default: 'refresh:') */
+    prefix?: string;
+    /** Base path for filesystem storage (default: './.data/refresh-tokens') */
+    base?: string;
+}
+/**
+ * Token refresh configuration
+ */
+export interface TokenRefreshConfig {
+    /** Enable automatic token refresh (default: true) */
+    enabled?: boolean;
+    /** Automatically refresh tokens in the background (default: true) */
+    automaticRefresh?: boolean;
+    /** Refresh token cookie configuration */
+    cookie?: CookieConfig;
+    /** Encryption configuration for stored user data */
+    encryption?: EncryptionConfig;
+    /** Storage configuration */
+    storage?: StorageConfig;
+    /** Token lifetime for server-generated access tokens during SSR (default: '5m') */
+    ssrTokenExpiry?: string;
+}

package/dist/runtime/types/routes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Route protection configuration types
+ */
+/**
+ * Authentication requirement for Nitro route rules
+ * - true | 'required' | 'protected': Route requires authentication
+ * - false | 'public' | 'skip': Route is public and skips authentication
+ */
+export type NitroAegisAuth = boolean | 'required' | 'protected' | 'public' | 'skip';
+/**
+ * Nuxt Aegis route rules configuration
+ */
+export interface NuxtAegisRouteRules {
+    auth?: NitroAegisAuth;
+}
+/**
+ * Client-side middleware configuration for route protection
+ */
+export interface ClientMiddlewareConfig {
+    /** Enable client-side route protection middleware (default: false) */
+    enabled: boolean;
+    /** Register middleware globally for all routes (default: false) */
+    global?: boolean;
+    /** Redirect destination for unauthenticated users (required when enabled) */
+    redirectTo: string;
+    /** Redirect destination for authenticated users on logged-out pages (required when enabled) */
+    loggedOutRedirectTo: string;
+    /** Array of route patterns excluded from authentication (glob patterns supported) */
+    publicRoutes?: string[];
+}

package/dist/runtime/types/token.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Token-related type definitions
+ * Handles JWT tokens, payloads, and token validation
+ */
+/**
+ * Impersonation context stored in JWT
+ * Contains essential information about the original user when impersonating
+ */
+export interface ImpersonationContext {
+    /** Original user ID (sub) who is performing the impersonation */
+    originalUserId: string;
+    /** Original user email */
+    originalUserEmail?: string;
+    /** Original user name */
+    originalUserName?: string;
+    /** Timestamp when impersonation started */
+    impersonatedAt: string;
+    /** Optional reason for impersonation (debugging, support, etc.) */
+    reason?: string;
+    /** Original user's complete claims (role, permissions, etc.) for restoration */
+    originalClaims?: Record<string, unknown>;
+}
+/**
+ * JWT Token payload interface
+ * Represents the decoded JWT token structure with standard and custom claims
+ * This is what gets stored in the JWT and attached to event.context.user
+ */
+export interface TokenPayload {
+    /** Subject identifier (user ID) - required claim */
+    sub: string;
+    /** User email address */
+    email?: string;
+    /** User full name */
+    name?: string;
+    /**
+     * User profile picture URL.
+     * Pay attention if it's a base64 string image, it can create huge payloads
+     * Better to use a URL pointing to the image location or leave it empty
+     */
+    picture?: string;
+    /** Provider name (e.g., 'google', 'github', 'microsoft', 'auth0', 'password', 'mock') */
+    provider?: string;
+    /** Issuer claim - identifies who issued the token */
+    iss?: string;
+    /** Audience claim - identifies the recipients of the token */
+    aud?: string | string[];
+    /** Issued at timestamp - when the token was created */
+    iat?: number;
+    /** Expiration timestamp - when the token expires */
+    exp?: number;
+    /** Impersonation context if this token represents an impersonated session */
+    impersonation?: ImpersonationContext;
+    /** Additional custom claims */
+    [key: string]: unknown;
+}
+/**
+ * Refresh token stored data interface
+ * Represents the data stored alongside a refresh token
+ * on the server side for validation and management
+ */
+export interface RefreshTokenData {
+    /** Subject identifier, links the token back to the specific user account */
+    sub: string;
+    /** Timestamp when the refresh token expires */
+    expiresAt: number;
+    /** Allows for immediate revocation if the user logs out, changes a password, or a security event occurs */
+    isRevoked: boolean;
+    /** Hash of the previous refresh token for rotation tracking */
+    previousTokenHash?: string;
+    /** Complete OAuth provider user data - NOT the JWT payload. This is the full user object from the provider (Google, GitHub, etc.) */
+    providerUserInfo: Record<string, unknown>;
+    /** Provider name for dynamic custom claims generation during refresh (e.g., 'google', 'github', 'microsoft', 'auth0') */
+    provider: string;
+}
+/**
+ * Response from token refresh operation
+ */
+export interface RefreshResponse {
+    success: boolean;
+    message: string;
+    accessToken?: string;
+}
+/**
+ * Token configuration
+ */
+export interface TokenConfig {
+    /** JWT secret key */
+    secret: string;
+    /** JWT expiration time (in seconds or as a string) */
+    expiresIn?: string | number;
+    /** JWT algorithm (default: 'HS256') */
+    algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512';
+    /** JWT issuer claim */
+    issuer?: string;
+    /** JWT audience claim */
+    audience?: string;
+}
+/**
+ * Claims validation configuration
+ */
+export interface ClaimsValidationConfig {
+    /** Required claims that must be present in the JWT */
+    requiredClaims?: string[];
+    /** Custom claim validation rules */
+    customRules?: Record<string, (value: unknown) => boolean>;
+}
+/**
+ * JSON-compatible value type for JWT custom claims
+ * Supports primitives, arrays, and one level of object nesting
+ */
+export type JSONValue = string | number | boolean | null | undefined | string[] | number[] | {
+    [key: string]: string | number | boolean | null | undefined | string[] | number[];
+};
+/**
+ * Helper type for creating custom token payloads with type safety
+ *
+ * Extends TokenPayload with custom claims while ensuring type safety.
+ * Prevents overriding standard JWT claims and ensures all custom claims
+ * are JSON-serializable.
+ *
+ * @template T - Record of custom claims to add to the token payload
+ *
+ * @example
+ * ```typescript
+ * // Define your custom claims
+ * type AppTokenPayload = CustomTokenClaims<{
+ *   role: string
+ *   permissions: string[]
+ *   organizationId: string
+ * }>
+ *
+ * // Use with useAuth
+ * const { user } = useAuth<AppTokenPayload>()
+ * console.log(user.value?.role) // Type-safe access
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With nested objects (one level)
+ * type AppTokenPayload = CustomTokenClaims<{
+ *   role: string
+ *   metadata: {
+ *     tenantId: string
+ *     plan: string
+ *   }
+ * }>
+ * ```
+ *
+ * @warning Never include sensitive data like passwords, API keys, or secrets in JWT tokens
+ * @warning Keep token payloads small (< 1KB recommended) for performance
+ */
+export type CustomTokenClaims<T extends Record<string, JSONValue>> = TokenPayload & T;
+/**
+ * Utility type to extract only custom claims from a token payload
+ *
+ * Removes all standard TokenPayload fields, leaving only your custom claims.
+ * Useful for type composition and claim validation.
+ *
+ * @template T - A token payload type extending TokenPayload
+ *
+ * @example
+ * ```typescript
+ * type AppTokenPayload = CustomTokenClaims<{
+ *   role: string
+ *   permissions: string[]
+ * }>
+ *
+ * type CustomClaims = ExtractClaims<AppTokenPayload>
+ * // Result: { role: string, permissions: string[] }
+ * ```
+ */
+export type ExtractClaims<T extends TokenPayload> = Omit<T, keyof TokenPayload>;
+/**
+ * Custom claims callback function
+ * Receives the full OAuth provider user data and tokens
+ * Returns claims to add to the JWT (must be JWT-compatible types)
+ *
+ * @param providerUserInfo - Complete user object from OAuth provider
+ * @param tokens - OAuth tokens from the provider
+ * @returns Record of custom claims to add to the JWT
+ */
+export type CustomClaimsCallback<TProviderUserInfo = any, TTokens = any> = (providerUserInfo: TProviderUserInfo, tokens: TTokens) => Record<string, string | number | boolean | Array<string | number | boolean> | null> | Promise<Record<string, string | number | boolean | Array<string | number | boolean> | null>>;

package/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@peterbud/nuxt-aegis",
+  "version": "1.1.0-alpha",
+  "description": "Nuxt module for authentication with JWT token generation and session management.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peterbud/nuxt-aegis.git"
+  },
+  "author": "Peter Budai",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "keywords": [
+    "vue",
+    "nuxt",
+    "authentication",
+    "nuxt-module",
+    "oauth"
+  ],
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "nuxt-module-build prepare && nuxt-module-build build",
+    "prepack": "nuxt-module-build build",
+    "dev": "pnpm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "docs:dev": "pnpm --filter docs docs:dev",
+    "release": "pnpm run lint && pnpm run test && pnpm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.2.1",
+    "consola": "^3.4.2",
+    "defu": "^6.1.4",
+    "jose": "^6.1.3",
+    "ufo": "^1.6.1"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/eslint-config": "^1.11.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.2.1",
+    "@nuxt/test-utils": "^3.21.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.1",
+    "nuxt": "^4.2.1",
+    "typescript": "~5.9.3",
+    "vitest": "^3.2.4",
+    "vue-tsc": "^3.1.5"
+  },
+  "pnpm": {
+    "overrides": {
+      "vue-router": "4.4.5"
+    }
+  },
+  "packageManager": "pnpm@10.17.1"
+}