@peterbud/nuxt-aegis 1.1.0-alpha

package/dist/runtime/server/utils/resetSessionStore.js

@@ -0,0 +1,29 @@
+import { randomBytes } from "node:crypto";
+import { useStorage } from "#imports";
+import { createLogger } from "./logger.js";
+const logger = createLogger("ResetSession");
+export async function createResetSession(email, ttl = 300) {
+  const storage = useStorage();
+  const sessionId = randomBytes(32).toString("base64url");
+  const now = Date.now();
+  const data = {
+    email: email.toLowerCase(),
+    expiresAt: now + ttl * 1e3
+  };
+  await storage.setItem(`reset:${sessionId}`, data);
+  logger.debug(`Reset session created for ${email}`);
+  return sessionId;
+}
+export async function validateAndDeleteResetSession(sessionId) {
+  const storage = useStorage();
+  const key = `reset:${sessionId}`;
+  const data = await storage.getItem(key);
+  if (!data) {
+    return null;
+  }
+  await storage.removeItem(key);
+  if (Date.now() > data.expiresAt) {
+    return null;
+  }
+  return data.email;
+}

package/dist/runtime/tasks/cleanup/magic-codes.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("nitropack").Task<{
+    totalProcessed: number;
+    deleted: number;
+    lookupKeysDeleted: number;
+    orphanedKeysDeleted: number;
+    skipped: number;
+    errors: number;
+    timestamp: string;
+}>;
+export default _default;

package/dist/runtime/tasks/cleanup/magic-codes.js

@@ -0,0 +1,79 @@
+import { defineTask, useStorage } from "nitropack/runtime";
+import { createLogger } from "../../server/utils/logger.js";
+const logger = createLogger("Task:CleanupMagicCodes");
+export default defineTask({
+  meta: {
+    name: "cleanup:magic-codes",
+    description: "Clean up expired magic codes and their lookup keys"
+  },
+  async run() {
+    logger.info("Starting magic code cleanup task...");
+    const storage = useStorage();
+    const now = Date.now();
+    const allKeys = await storage.getKeys();
+    const magicCodeKeys = allKeys.filter((key) => key.startsWith("magic:"));
+    const lookupKeys = allKeys.filter((key) => key.startsWith("magic-lookup:"));
+    let deletedCount = 0;
+    let errorCount = 0;
+    let skippedCount = 0;
+    const deletedLookupKeys = /* @__PURE__ */ new Set();
+    for (const key of magicCodeKeys) {
+      try {
+        const data = await storage.getItem(key);
+        if (!data) {
+          skippedCount++;
+          continue;
+        }
+        if (data.expiresAt < now) {
+          await storage.removeItem(key);
+          deletedCount++;
+          const lookupKey = `magic-lookup:${data.email}:${data.type}`;
+          deletedLookupKeys.add(lookupKey);
+          logger.debug(`Deleted expired magic code for ${data.email} (${data.type})`);
+        }
+      } catch (error) {
+        errorCount++;
+        logger.error(`Error processing magic code ${key}:`, error);
+      }
+    }
+    let lookupDeletedCount = 0;
+    for (const lookupKey of deletedLookupKeys) {
+      try {
+        await storage.removeItem(lookupKey);
+        lookupDeletedCount++;
+      } catch (error) {
+        errorCount++;
+        logger.error(`Error deleting lookup key ${lookupKey}:`, error);
+      }
+    }
+    let orphanedCount = 0;
+    for (const lookupKey of lookupKeys) {
+      try {
+        const code = await storage.getItem(lookupKey);
+        if (code) {
+          const magicCodeKey = `magic:${code}`;
+          const exists = await storage.getItem(magicCodeKey);
+          if (!exists) {
+            await storage.removeItem(lookupKey);
+            orphanedCount++;
+            logger.debug(`Deleted orphaned lookup key: ${lookupKey}`);
+          }
+        }
+      } catch (error) {
+        errorCount++;
+        logger.error(`Error processing lookup key ${lookupKey}:`, error);
+      }
+    }
+    const result = {
+      totalProcessed: magicCodeKeys.length,
+      deleted: deletedCount,
+      lookupKeysDeleted: lookupDeletedCount,
+      orphanedKeysDeleted: orphanedCount,
+      skipped: skippedCount,
+      errors: errorCount,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    logger.info(`Magic code cleanup completed: ${deletedCount} codes deleted, ${lookupDeletedCount} lookup keys deleted, ${orphanedCount} orphaned keys deleted, ${skippedCount} skipped, ${errorCount} errors`);
+    return { result };
+  }
+});

package/dist/runtime/tasks/cleanup/refresh-tokens.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("nitropack").Task<{
+    totalProcessed: number;
+    deleted: number;
+    expired: number;
+    revoked: number;
+    skipped: number;
+    errors: number;
+    timestamp: string;
+}>;
+export default _default;

package/dist/runtime/tasks/cleanup/refresh-tokens.js

@@ -0,0 +1,55 @@
+import { defineTask, useStorage } from "nitropack/runtime";
+import { getRefreshTokenData } from "../../server/utils/refreshToken.js";
+import { createLogger } from "../../server/utils/logger.js";
+const logger = createLogger("Task:CleanupRefreshTokens");
+export default defineTask({
+  meta: {
+    name: "cleanup:refresh-tokens",
+    description: "Clean up expired and revoked refresh tokens from storage"
+  },
+  async run() {
+    logger.info("Starting refresh token cleanup task...");
+    const storage = useStorage("refreshTokenStore");
+    const keys = await storage.getKeys();
+    const now = Date.now();
+    let deletedCount = 0;
+    let revokedCount = 0;
+    let expiredCount = 0;
+    let errorCount = 0;
+    let skippedCount = 0;
+    for (const tokenHash of keys) {
+      try {
+        const data = await getRefreshTokenData(tokenHash);
+        if (!data) {
+          skippedCount++;
+          continue;
+        }
+        if (data.expiresAt < now || data.isRevoked) {
+          await storage.removeItem(tokenHash);
+          deletedCount++;
+          if (data.isRevoked) {
+            revokedCount++;
+            logger.debug(`Deleted revoked refresh token: ${tokenHash.substring(0, 8)}...`);
+          } else {
+            expiredCount++;
+            logger.debug(`Deleted expired refresh token: ${tokenHash.substring(0, 8)}...`);
+          }
+        }
+      } catch (error) {
+        errorCount++;
+        logger.error(`Error processing token ${tokenHash.substring(0, 8)}...:`, error);
+      }
+    }
+    const result = {
+      totalProcessed: keys.length,
+      deleted: deletedCount,
+      expired: expiredCount,
+      revoked: revokedCount,
+      skipped: skippedCount,
+      errors: errorCount,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    logger.info(`Refresh token cleanup completed: ${deletedCount} deleted (${expiredCount} expired, ${revokedCount} revoked), ${skippedCount} skipped, ${errorCount} errors`);
+    return { result };
+  }
+});

package/dist/runtime/tasks/cleanup/reset-sessions.d.ts

@@ -0,0 +1,8 @@
+declare const _default: import("nitropack").Task<{
+    totalProcessed: number;
+    deleted: number;
+    skipped: number;
+    errors: number;
+    timestamp: string;
+}>;
+export default _default;

package/dist/runtime/tasks/cleanup/reset-sessions.js

@@ -0,0 +1,45 @@
+import { defineTask, useStorage } from "nitropack/runtime";
+import { createLogger } from "../../server/utils/logger.js";
+const logger = createLogger("Task:CleanupResetSessions");
+export default defineTask({
+  meta: {
+    name: "cleanup:reset-sessions",
+    description: "Clean up expired password reset sessions"
+  },
+  async run() {
+    logger.info("Starting reset session cleanup task...");
+    const storage = useStorage();
+    const allKeys = await storage.getKeys();
+    const resetKeys = allKeys.filter((key) => key.startsWith("reset:"));
+    const now = Date.now();
+    let deletedCount = 0;
+    let errorCount = 0;
+    let skippedCount = 0;
+    for (const key of resetKeys) {
+      try {
+        const data = await storage.getItem(key);
+        if (!data) {
+          skippedCount++;
+          continue;
+        }
+        if (data.expiresAt < now) {
+          await storage.removeItem(key);
+          deletedCount++;
+          logger.debug(`Deleted expired reset session for ${data.email}`);
+        }
+      } catch (error) {
+        errorCount++;
+        logger.error(`Error processing reset session ${key}:`, error);
+      }
+    }
+    const result = {
+      totalProcessed: resetKeys.length,
+      deleted: deletedCount,
+      skipped: skippedCount,
+      errors: errorCount,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    logger.info(`Reset session cleanup completed: ${deletedCount} deleted, ${skippedCount} skipped, ${errorCount} errors`);
+    return { result };
+  }
+});

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

@@ -0,0 +1,73 @@
+import type { NuxtAegisRuntimeConfig, RedirectConfig, LoggingConfig } from './config.js';
+import type { TokenRefreshConfig } from './refresh.js';
+import type { TokenPayload } from './token.js';
+import type { ClientMiddlewareConfig } from './routes.js';
+import type { SuccessHookPayload } from './hooks.js';
+/**
+ * Module augmentations for external libraries
+ */
+declare module '@nuxt/schema' {
+    interface RuntimeConfig {
+        nuxtAegis?: NuxtAegisRuntimeConfig;
+    }
+    interface PublicRuntimeConfig {
+        nuxtAegis: {
+            authPath: string;
+            loginPath: string;
+            callbackPath: string;
+            logoutPath: string;
+            refreshPath: string;
+            userInfoPath: string;
+            redirect: RedirectConfig;
+            tokenRefresh: TokenRefreshConfig;
+            clientMiddleware?: ClientMiddlewareConfig;
+            logging: LoggingConfig;
+            enableSSR: boolean;
+        };
+    }
+}
+declare module 'nitropack' {
+    interface NitroRuntimeHooks {
+        /**
+         * Hook called after successful authentication.
+         * Use this for logging, analytics, or database operations.
+         */
+        'nuxt-aegis:success': (payload: SuccessHookPayload) => Promise<void> | void;
+    }
+}
+declare module 'h3' {
+    interface H3EventContext {
+        /**
+         * Authenticated user data from JWT token
+         * Available when request is authenticated via the auth middleware
+         */
+        user?: TokenPayload;
+        /**
+         * Original user data before impersonation
+         * Available when impersonation is active
+         */
+        originalUser?: {
+            sub: string;
+            email?: string;
+            name?: string;
+        };
+    }
+}
+declare module '#app' {
+    interface NuxtApp {
+        /**
+         * Custom $fetch instance with automatic bearer token injection
+         * Configured by the Nuxt Aegis plugin
+         */
+        $api: typeof $fetch;
+    }
+}
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        /**
+         * Custom $fetch instance with automatic bearer token injection
+         * Configured by the Nuxt Aegis plugin
+         */
+        $api: typeof $fetch;
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Authorization Code Flow Types
+ * Types for the CODE-based authentication flow
+ */
+/**
+ * Authorization code data stored in the key-value store
+ */
+export interface AuthCodeData {
+    /** Complete OAuth provider user data (NOT the JWT payload) - used for custom claims generation */
+    providerUserInfo: Record<string, unknown>;
+    /** Provider tokens received from OAuth provider */
+    providerTokens: {
+        /** OAuth provider access token */
+        access_token: string;
+        /** Optional OAuth provider refresh token */
+        refresh_token?: string;
+        /** Optional OAuth provider ID token (OpenID Connect) */
+        id_token?: string;
+        /** Optional token expiration time in seconds */
+        expires_in?: number;
+    };
+    /** Timestamp when the code expires (milliseconds since epoch) */
+    expiresAt: number;
+    /** Timestamp when the code was created (milliseconds since epoch) */
+    createdAt: number;
+    /** Provider name (e.g., 'google', 'github', 'microsoft', 'auth0') */
+    provider: string;
+    /** Resolved custom claims (already processed from static or callback config) */
+    customClaims?: Record<string, unknown>;
+}
+/**
+ * Request body for token exchange endpoint
+ * Client sends this to /auth/token to exchange CODE for tokens
+ */
+export interface TokenExchangeRequest {
+    /** Authorization code received from OAuth callback */
+    code: string;
+}
+/**
+ * Response from token exchange endpoint
+ * Server returns access token in JSON response body
+ */
+export interface TokenExchangeResponse {
+    /** JWT access token for API authentication */
+    accessToken: string;
+    /** Token type, always "Bearer" for JWT */
+    tokenType: 'Bearer';
+    /** Optional expiration time in seconds */
+    expiresIn?: number;
+}
+/**
+ * Configuration for authorization code flow
+ */
+export interface AuthCodeConfig {
+    /**
+     * Expiration time for authorization codes in seconds
+     * @default 60
+     */
+    expiresIn: number;
+}

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

@@ -0,0 +1,54 @@
+import type { H3Error, H3Event } from 'h3';
+/**
+ * Callback and error handler type definitions
+ */
+/**
+ * Error handler callback type
+ */
+export type OnError = (event: H3Event, error: H3Error) => Promise<void> | void;
+/**
+ * User information transformation hook
+ * Called after fetching user info from the provider, before storing it
+ * Allows provider-specific user object shaping
+ *
+ * This receives the complete OAuth provider response, NOT the JWT payload
+ *
+ * @param providerUserInfo - Complete user object from OAuth provider
+ * @param tokens - Provider tokens (access_token, refresh_token, id_token, expires_in)
+ * @param event - H3 event for server context access
+ * @returns Transformed user object that will be stored and used for custom claims
+ */
+export type OnUserInfo = (providerUserInfo: Record<string, unknown>, tokens: {
+    access_token: string;
+    refresh_token?: string;
+    id_token?: string;
+    expires_in?: number;
+}, event: H3Event) => Promise<Record<string, unknown>> | Record<string, unknown>;
+/**
+ * Success hook parameters
+ */
+export interface OnSuccessParams {
+    /** Transformed provider user data (post-onUserInfo transformation) */
+    providerUserInfo: Record<string, unknown>;
+    /** Provider tokens */
+    tokens: {
+        access_token: string;
+        refresh_token?: string;
+        id_token?: string;
+        expires_in?: number;
+    };
+    /** Provider name (e.g., 'google', 'github', 'microsoft', 'auth0') */
+    provider: string;
+    /** H3 event for server context access */
+    event: H3Event;
+}
+/**
+ * Success hook type
+ * Called after successful authentication, before generating authorization CODE
+ * Provider-agnostic hook for side effects like database storage
+ *
+ * This receives the transformed OAuth provider data, NOT the JWT payload
+ *
+ * @param params - Success hook parameters
+ */
+export type OnSuccess = (params: OnSuccessParams) => Promise<void> | void;

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

@@ -0,0 +1,129 @@
+import type { GoogleProviderConfig, MicrosoftProviderConfig, GithubProviderConfig, Auth0ProviderConfig, MockProviderConfig, CustomProviderConfig, PasswordProviderConfig } from './providers.js';
+import type { TokenConfig, ClaimsValidationConfig } from './token.js';
+import type { TokenRefreshConfig } from './refresh.js';
+import type { ClientMiddlewareConfig } from './routes.js';
+import type { AuthCodeConfig } from './authCode.js';
+/**
+ * Module and runtime configuration types
+ */
+/**
+ * Redirect URL configuration
+ */
+export interface RedirectConfig {
+    /** Redirect URL after logout (default: '/') */
+    logout?: string;
+    /** Redirect URL after successful authentication (default: '/') */
+    success?: string;
+    /** Redirect URL when authentication fails (default: '/') */
+    error?: string;
+}
+/**
+ * API endpoint path configuration
+ */
+export interface EndpointConfig {
+    /** Base path for authentication API routes (default: '/auth') */
+    authPath?: string;
+    /** Base path for login endpoints without provider (default: '/auth'). Login URLs are constructed as '[loginPath]/[provider]' */
+    loginPath?: string;
+    /** Path for callback endpoints (default: '/auth/callback') */
+    callbackPath?: string;
+    /** Path for logout endpoint (default: '/auth/logout') */
+    logoutPath?: string;
+    /** Path for token refresh endpoint (default: '/auth/refresh') */
+    refreshPath?: string;
+    /** Path for user info endpoint (default: '/api/user/me') */
+    userInfoPath?: string;
+}
+/**
+ * Logging configuration
+ */
+export interface LoggingConfig {
+    /** Log level: 'silent' | 'error' | 'warn' | 'info' | 'debug' (default: 'info') */
+    level?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
+    /** Enable security event logging (default: false, enabled when level is 'debug') */
+    security?: boolean;
+}
+/**
+ * Impersonation configuration
+ */
+export interface ImpersonationConfig {
+    /** Enable user impersonation feature (default: false, opt-in for security) */
+    enabled?: boolean;
+    /** Token expiration time for impersonated sessions in seconds (default: 900 = 15 minutes) */
+    tokenExpiration?: number;
+}
+/**
+ * Runtime config for Nuxt Aegis
+ */
+export interface NuxtAegisRuntimeConfig {
+    token?: TokenConfig;
+    tokenRefresh?: TokenRefreshConfig;
+    authCode?: AuthCodeConfig;
+    endpoints?: EndpointConfig;
+    authPath?: string;
+    logging?: LoggingConfig;
+    impersonation?: ImpersonationConfig;
+    providers?: {
+        google?: GoogleProviderConfig;
+        microsoft?: MicrosoftProviderConfig;
+        github?: GithubProviderConfig;
+        auth0?: Auth0ProviderConfig;
+        mock?: MockProviderConfig;
+        password?: PasswordProviderConfig;
+    };
+}
+/**
+ * Nuxt Aegis module configuration options
+ */
+export interface ModuleOptions {
+    /** Enable Nuxt DevTools integration (default: true) */
+    devtools?: boolean;
+    /**
+     * OAuth provider configurations
+     * Configure one or more authentication providers
+     */
+    providers?: {
+        /** Google OAuth provider configuration */
+        google?: GoogleProviderConfig;
+        /** Microsoft OAuth provider configuration */
+        microsoft?: MicrosoftProviderConfig;
+        /** GitHub OAuth provider configuration */
+        github?: GithubProviderConfig;
+        /** Auth0 OAuth provider configuration */
+        auth0?: Auth0ProviderConfig;
+        /** Mock OAuth provider configuration (development/testing only) */
+        mock?: MockProviderConfig;
+        /** Password provider configuration */
+        password?: PasswordProviderConfig;
+        /** Custom OAuth provider configurations */
+        custom?: CustomProviderConfig[];
+    };
+    /** Token configuration */
+    token?: TokenConfig;
+    /** Token refresh configuration */
+    tokenRefresh?: TokenRefreshConfig;
+    /**
+     * Authorization code configuration (CODE-based flow)
+     * Default: 60 seconds (recommended for security)
+     */
+    authCode?: AuthCodeConfig;
+    /** Redirect URL configuration */
+    redirect?: RedirectConfig;
+    /** Client-side middleware configuration for route protection */
+    clientMiddleware?: ClientMiddlewareConfig;
+    /** Claims validation configuration */
+    claimsValidation?: ClaimsValidationConfig;
+    /** API endpoint path configuration */
+    endpoints?: EndpointConfig;
+    /** Logging configuration */
+    logging?: LoggingConfig;
+    /** Impersonation configuration (opt-in feature) */
+    impersonation?: ImpersonationConfig;
+    /**
+     * Enable SSR-compatible authentication state restoration
+     * When true (default), authentication state will be restored on client after SSR hydration
+     * When false, plugin skips execution after server-side rendering (backward compatibility)
+     * @default true
+     */
+    enableSSR?: boolean;
+}

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

@@ -0,0 +1,118 @@
+import type { H3Event } from 'h3';
+import type { TokenPayload } from './token.js';
+/**
+ * Nitro hook type definitions for Nuxt Aegis
+ * These hooks allow users to customize authentication behavior via server plugins
+ */
+/**
+ * Payload for the nuxt-aegis:userInfo hook
+ * Called after fetching user info from the provider, before storing it
+ *
+ * This receives the complete OAuth provider response, NOT the JWT payload
+ */
+export interface UserInfoHookPayload {
+    /** Complete user object from OAuth provider (e.g., Google, GitHub, Microsoft) */
+    providerUserInfo: Record<string, unknown>;
+    /** Provider tokens */
+    tokens: {
+        access_token: string;
+        refresh_token?: string;
+        id_token?: string;
+        expires_in?: number;
+    };
+    /** Provider name (e.g., 'google', 'github', 'microsoft', 'auth0') */
+    provider: string;
+    /** H3 event for server context access */
+    event: H3Event;
+}
+/**
+ * Payload for the nuxt-aegis:success hook
+ * Called after successful authentication
+ *
+ * This receives the transformed OAuth provider data, NOT the JWT payload
+ */
+export interface SuccessHookPayload {
+    /** Transformed provider user data (post-userInfo hook transformation) */
+    providerUserInfo: Record<string, unknown>;
+    /** Provider tokens */
+    tokens: {
+        access_token: string;
+        refresh_token?: string;
+        id_token?: string;
+        expires_in?: number;
+    };
+    /** Provider name (e.g., 'google', 'github', 'microsoft', 'auth0') */
+    provider: string;
+    /** H3 event for server context access */
+    event: H3Event;
+}
+/**
+ * Payload for the nuxt-aegis:impersonate:check hook
+ * Called to determine if a user is allowed to impersonate others
+ */
+export interface ImpersonateCheckPayload {
+    /** JWT payload of the user requesting impersonation */
+    requester: TokenPayload;
+    /** Target user ID to impersonate */
+    targetUserId: string;
+    /** Optional reason for impersonation (for audit) */
+    reason?: string;
+    /** H3 event for server context access */
+    event: H3Event;
+    /** Client IP address (for audit) */
+    ip: string;
+    /** User agent string (for audit) */
+    userAgent: string;
+}
+/**
+ * Payload for the nuxt-aegis:impersonate:fetchTarget hook
+ * Called to fetch the target user's data
+ *
+ * This hook MUST be implemented by the user to return the target user's data
+ */
+export interface ImpersonateFetchTargetPayload {
+    /** JWT payload of the user requesting impersonation */
+    requester: TokenPayload;
+    /** Target user ID to impersonate */
+    targetUserId: string;
+    /** H3 event for server context access */
+    event: H3Event;
+}
+/**
+ * Payload for the nuxt-aegis:impersonate:start hook
+ * Called after impersonation starts successfully (fire-and-forget for audit logging)
+ */
+export interface ImpersonateStartPayload {
+    /** JWT payload of the user who initiated impersonation */
+    requester: TokenPayload;
+    /** JWT payload of the impersonated user */
+    targetUser: TokenPayload;
+    /** Reason for impersonation */
+    reason?: string;
+    /** H3 event for server context access */
+    event: H3Event;
+    /** Client IP address (for audit) */
+    ip: string;
+    /** User agent string (for audit) */
+    userAgent: string;
+    /** Timestamp of impersonation */
+    timestamp: Date;
+}
+/**
+ * Payload for the nuxt-aegis:impersonate:end hook
+ * Called after impersonation ends successfully (fire-and-forget for audit logging)
+ */
+export interface ImpersonateEndPayload {
+    /** JWT payload of the restored original user */
+    restoredUser: TokenPayload;
+    /** JWT payload of the user who was being impersonated */
+    impersonatedUser: TokenPayload;
+    /** H3 event for server context access */
+    event: H3Event;
+    /** Client IP address (for audit) */
+    ip: string;
+    /** User agent string (for audit) */
+    userAgent: string;
+    /** Timestamp when impersonation ended */
+    timestamp: Date;
+}