@peterbud/nuxt-aegis 1.1.0-alpha

package/dist/runtime/app/utils/redirectValidation.js

@@ -0,0 +1,21 @@
+import { createLogger } from "./logger.js";
+const logger = createLogger("RedirectValidation");
+export function validateRedirectPath(path) {
+  if (!path || typeof path !== "string") {
+    const error = "Redirect path must be a non-empty string";
+    logger.error(error, { path });
+    throw new Error(error);
+  }
+  const trimmedPath = path.trim();
+  if (trimmedPath.startsWith("http://") || trimmedPath.startsWith("https://") || trimmedPath.startsWith("//")) {
+    const error = 'Redirect path must be a relative path, not an absolute URL. Use paths like "/dashboard" instead of full URLs.';
+    logger.error(error, { path: trimmedPath });
+    throw new Error(error);
+  }
+  if (!trimmedPath.startsWith("/")) {
+    const error = 'Redirect path must start with "/" (e.g., "/dashboard")';
+    logger.error(error, { path: trimmedPath });
+    throw new Error(error);
+  }
+  return trimmedPath;
+}

package/dist/runtime/app/utils/routeMatching.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Convert glob pattern to regex for route matching
+ * @param pattern - Glob pattern (supports *, **, ?)
+ * @returns RegExp for testing paths
+ */
+export declare function globToRegex(pattern: string): RegExp;
+/**
+ * Check if a path matches any of the provided route patterns
+ * @param path - The path to check
+ * @param patterns - Array of glob patterns
+ * @returns true if the path matches any pattern
+ */
+export declare function isRouteMatch(path: string, patterns: string[]): boolean;

package/dist/runtime/app/utils/routeMatching.js

@@ -0,0 +1,10 @@
+export function globToRegex(pattern) {
+  const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "___DOUBLE_STAR___").replace(/\*/g, "[^/]*").replace(/___DOUBLE_STAR___/g, ".*").replace(/\?/g, "[^/]");
+  return new RegExp(`^${regexPattern}$`);
+}
+export function isRouteMatch(path, patterns) {
+  return patterns.some((pattern) => {
+    const regex = globToRegex(pattern);
+    return regex.test(path);
+  });
+}

package/dist/runtime/app/utils/tokenStore.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Get the current access token
+ * @returns The current access token or null if not authenticated
+ */
+export declare function getAccessToken(): string | null;
+/**
+ * Set a new access token in memory
+ * CL-18: Store access token in memory as a reactive reference variable
+ *
+ * @param token - The access token to store
+ */
+export declare function setAccessToken(token: string | null): void;
+/**
+ * Clear the access token from memory
+ * CL-19: Clear token on logout or session end
+ */
+export declare function clearAccessToken(): void;
+/**
+ * Get reactive reference to the token (for internal use)
+ * Useful when you need to watch for token changes
+ *
+ * @returns Reactive reference to the access token
+ */
+export declare function getAccessTokenRef(): import("vue").Ref<string | null, string | null>;

package/dist/runtime/app/utils/tokenStore.js

@@ -0,0 +1,14 @@
+import { ref } from "vue";
+const accessToken = ref(null);
+export function getAccessToken() {
+  return accessToken.value;
+}
+export function setAccessToken(token) {
+  accessToken.value = token;
+}
+export function clearAccessToken() {
+  setAccessToken(null);
+}
+export function getAccessTokenRef() {
+  return accessToken;
+}

package/dist/runtime/app/utils/tokenUtils.d.ts

@@ -0,0 +1,17 @@
+import type { TokenPayload } from '../../types/index.js';
+/**
+ * Filter out time-sensitive JWT metadata claims that cause hydration mismatches
+ *
+ * These claims are automatically regenerated on each token creation, causing different
+ * values between server-rendered and client-refreshed tokens. Filtering them prevents
+ * hydration mismatches while preserving stable user data.
+ *
+ * Filtered claims:
+ * - iat (issued at) - timestamp when token was created
+ * - exp (expiration) - timestamp when token expires
+ * - iss (issuer) - token issuer (constant but not user data)
+ *
+ * @param user - Token payload with all claims
+ * @returns Token payload with only stable user data
+ */
+export declare function filterTimeSensitiveClaims(user: TokenPayload): TokenPayload;

package/dist/runtime/app/utils/tokenUtils.js

@@ -0,0 +1,4 @@
+export function filterTimeSensitiveClaims(user) {
+  const { iat, exp, iss, ...stableUser } = user;
+  return stableUser;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Authentication middleware for Nuxt Aegis
+ * Validates JWT tokens and protects routes according to Nitro route rules
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/middleware/auth.js

@@ -0,0 +1,82 @@
+import { defineEventHandler, createError, getRequestURL, getHeader } from "h3";
+import { getRouteRules, useRuntimeConfig } from "#imports";
+import { verifyToken } from "../utils/jwt.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("Middleware");
+export default defineEventHandler(async (event) => {
+  const config = useRuntimeConfig();
+  const requestURL = getRequestURL(event);
+  logger.debug("Auth middleware triggered for URL:", requestURL.pathname);
+  const tokenConfig = config.nuxtAegis?.token;
+  const authPath = config.public.nuxtAegis.authPath;
+  if (requestURL.pathname.startsWith(authPath)) {
+    return;
+  }
+  if (requestURL.pathname.startsWith("/_nuxt/") || requestURL.pathname.startsWith("/api/_")) {
+    return;
+  }
+  const routeRules = await getRouteRules(event);
+  const authConfig = routeRules.nuxtAegis?.auth;
+  const shouldProtect = authConfig === true || authConfig === "required" || authConfig === "protected";
+  const shouldSkip = authConfig === false || authConfig === "public" || authConfig === "skip";
+  if (!shouldProtect || shouldSkip) {
+    return;
+  }
+  let token;
+  const authHeader = getHeader(event, "authorization");
+  if (authHeader?.startsWith("Bearer ")) {
+    token = authHeader.substring(7);
+  }
+  if (!token) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Authentication required"
+    });
+  }
+  if (!tokenConfig || !tokenConfig.secret) {
+    logger.error("Token configuration is missing");
+    throw createError({
+      statusCode: 500,
+      statusMessage: "Internal Server Error",
+      message: "Authentication configuration error"
+    });
+  }
+  const payload = await verifyToken(token, tokenConfig.secret);
+  if (!payload) {
+    logger.debug("Token verification failed for path:", requestURL.pathname);
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Invalid or expired token"
+    });
+  }
+  if (tokenConfig.issuer && payload.iss !== tokenConfig.issuer) {
+    logger.debug("Token issuer mismatch. Expected:", tokenConfig.issuer, "Got:", payload.iss);
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Invalid token issuer"
+    });
+  }
+  if (tokenConfig.audience && payload.aud) {
+    const audienceMatch = Array.isArray(payload.aud) ? payload.aud.includes(tokenConfig.audience) : payload.aud === tokenConfig.audience;
+    if (!audienceMatch) {
+      logger.debug("Token audience mismatch. Expected:", tokenConfig.audience, "Got:", payload.aud);
+      throw createError({
+        statusCode: 401,
+        statusMessage: "Unauthorized",
+        message: "Invalid token audience"
+      });
+    }
+  }
+  const { iat, exp, iss, aud, ...userData } = payload;
+  event.context.user = userData;
+  if (payload.impersonation) {
+    event.context.originalUser = {
+      sub: payload.impersonation.originalUserId,
+      email: payload.impersonation.originalUserEmail,
+      name: payload.impersonation.originalUserName
+    };
+  }
+});

package/dist/runtime/server/plugins/ssr-auth.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Nitro server plugin for SSR authentication
+ * Validates refresh token cookie and generates short-lived access tokens
+ * for authenticated server-side rendering without rotating the refresh token
+ */
+declare const _default: import("nitropack").NitroAppPlugin;
+export default _default;

package/dist/runtime/server/plugins/ssr-auth.js

@@ -0,0 +1,82 @@
+import { defineNitroPlugin } from "nitropack/runtime";
+import { getCookie } from "h3";
+import { hashRefreshToken, getRefreshTokenData } from "../utils/refreshToken.js";
+import { generateToken } from "../utils/jwt.js";
+import { processCustomClaims } from "../utils/customClaims.js";
+import { useRuntimeConfig } from "#imports";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("SSR:Auth");
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("request", async (event) => {
+    const config = useRuntimeConfig(event);
+    const authPath = config.public.nuxtAegis?.authPath || "/auth";
+    const requestPath = event.node?.req?.url || event.path || "";
+    if (requestPath.startsWith(authPath) || requestPath.startsWith("/_nuxt/") || requestPath.startsWith("/api/") || requestPath.includes("/favicon.ico") || requestPath.includes("/__")) {
+      return;
+    }
+    logger.debug("SSR auth hook triggered for URL:", requestPath);
+    if (event.context.user) {
+      logger.debug("SSR auth skipped: user already authenticated in context");
+      return;
+    }
+    if (!config.public.nuxtAegis?.enableSSR) {
+      return;
+    }
+    const startTime = performance.now();
+    const cookieConfig = config.nuxtAegis?.tokenRefresh?.cookie;
+    const tokenConfig = config.nuxtAegis?.token;
+    const tokenRefreshConfig = config.nuxtAegis?.tokenRefresh;
+    if (!tokenConfig?.secret) {
+      logger.debug("SSR auth skipped: token secret not configured");
+      return;
+    }
+    const cookieName = cookieConfig?.cookieName || "nuxt-aegis-refresh";
+    const refreshToken = getCookie(event, cookieName);
+    if (!refreshToken) {
+      logger.debug("SSR auth skipped: no refresh token cookie found");
+      return;
+    }
+    try {
+      const hashedToken = hashRefreshToken(refreshToken);
+      const storedRefreshToken = await getRefreshTokenData(hashedToken, event);
+      const isRevoked = storedRefreshToken?.isRevoked || false;
+      const isExpired = storedRefreshToken?.expiresAt ? Date.now() > storedRefreshToken.expiresAt : true;
+      if (!storedRefreshToken || isRevoked || isExpired) {
+        logger.debug("SSR auth skipped: refresh token invalid, revoked, or expired");
+        return;
+      }
+      const providerUserInfo = storedRefreshToken.providerUserInfo;
+      const provider = storedRefreshToken.provider;
+      const userPayload = {
+        sub: String(providerUserInfo.sub || providerUserInfo.email || providerUserInfo.id || ""),
+        email: providerUserInfo.email,
+        name: providerUserInfo.name,
+        picture: providerUserInfo.picture,
+        provider
+      };
+      let customClaims = {};
+      const providerConfig = config.nuxtAegis?.providers?.[provider];
+      if (providerConfig && "customClaims" in providerConfig && providerConfig.customClaims) {
+        customClaims = await processCustomClaims(
+          providerUserInfo,
+          providerConfig.customClaims
+        );
+      }
+      const ssrTokenExpiry = tokenRefreshConfig?.ssrTokenExpiry || "5m";
+      const ssrAccessToken = await generateToken(
+        userPayload,
+        {
+          ...tokenConfig,
+          expiresIn: ssrTokenExpiry
+        },
+        customClaims
+      );
+      event.context.ssrAccessToken = ssrAccessToken;
+      event.context.user = userPayload;
+      const duration = Math.round(performance.now() - startTime);
+      logger.debug(`SSR auth completed in ${duration}ms for user: ${userPayload.email}`);
+    } catch (error) {
+      logger.error("SSR auth failed:", error);
+    }
+  });
+});

package/dist/runtime/server/providers/auth0.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthConfig, Auth0ProviderConfig } from '../../types/index.js';
+/**
+ * Create an Auth0 OAuth event handler
+ * @param options - Configuration object
+ * @param options.config - Auth0 OAuth provider configuration
+ * @param options.onError - Error callback function
+ * @param options.customClaims - Custom claims to add to JWT
+ * @param options.onUserInfo - User transformation hook
+ * @param options.onSuccess - Success callback hook
+ * @returns Event handler for Auth0 OAuth authentication
+ */
+export declare function defineOAuthAuth0EventHandler({ config, onError, customClaims, onUserInfo, onSuccess, }: OAuthConfig<Auth0ProviderConfig>): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;

package/dist/runtime/server/providers/auth0.js

@@ -0,0 +1,57 @@
+import { defineOAuthEventHandler, defineOAuthProvider, validateAuthorizationParams } from "./oauthBase.js";
+function getAuth0DomainUrl(domain) {
+  return domain.startsWith("https://") ? domain : `https://${domain}`;
+}
+const auth0Implementation = defineOAuthProvider({
+  runtimeConfigKey: "auth0",
+  defaultConfig: {
+    scopes: ["openid", "profile", "email"]
+  },
+  // These will be dynamically set based on the domain in buildAuthQuery
+  authorizeUrl: "",
+  tokenUrl: "",
+  userInfoUrl: "",
+  extractUser: (userResponse) => userResponse,
+  buildAuthQuery: (config, redirectUri, state) => {
+    if (!config.domain) {
+      throw new Error("Auth0 domain is required in configuration");
+    }
+    const domainUrl = getAuth0DomainUrl(config.domain);
+    auth0Implementation.authorizeUrl = config.authorizeUrl || `${domainUrl}/authorize`;
+    auth0Implementation.tokenUrl = config.tokenUrl || `${domainUrl}/oauth/token`;
+    auth0Implementation.userInfoUrl = config.userInfoUrl || `${domainUrl}/userinfo`;
+    const customParams = validateAuthorizationParams(config.authorizationParams, "auth0");
+    return {
+      // Custom parameters first (can be overridden by defaults)
+      ...customParams,
+      // Default OAuth parameters (take precedence)
+      response_type: "code",
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      scope: config.scopes?.join(" ") || "openid profile email",
+      state: state || ""
+    };
+  },
+  buildTokenBody: (config, code, redirectUri) => ({
+    code,
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: redirectUri,
+    grant_type: "authorization_code"
+  })
+});
+export function defineOAuthAuth0EventHandler({
+  config = {},
+  onError,
+  customClaims,
+  onUserInfo,
+  onSuccess
+}) {
+  return defineOAuthEventHandler(auth0Implementation, {
+    config,
+    onError,
+    customClaims,
+    onUserInfo,
+    onSuccess
+  });
+}

package/dist/runtime/server/providers/github.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthConfig, GithubProviderConfig } from '../../types/index.js';
+/**
+ * Create a GitHub OAuth event handler
+ * @param options - Configuration object
+ * @param options.config - GitHub OAuth provider configuration
+ * @param options.onError - Error callback function
+ * @param options.customClaims - Custom claims to add to JWT
+ * @param options.onUserInfo - User transformation hook
+ * @param options.onSuccess - Success callback hook
+ * @returns Event handler for GitHub OAuth authentication
+ */
+export declare function defineOAuthGithubEventHandler({ config, onError, customClaims, onUserInfo, onSuccess, }: OAuthConfig<GithubProviderConfig>): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;

package/dist/runtime/server/providers/github.js

@@ -0,0 +1,44 @@
+import { defineOAuthEventHandler, defineOAuthProvider, validateAuthorizationParams } from "./oauthBase.js";
+const githubImplementation = defineOAuthProvider({
+  runtimeConfigKey: "github",
+  defaultConfig: {
+    scopes: ["user:email"]
+  },
+  authorizeUrl: "https://github.com/login/oauth/authorize",
+  tokenUrl: "https://github.com/login/oauth/access_token",
+  userInfoUrl: "https://api.github.com/user",
+  extractUser: (userResponse) => userResponse,
+  buildAuthQuery: (config, redirectUri, state) => {
+    const customParams = validateAuthorizationParams(config.authorizationParams, "github");
+    return {
+      // Custom parameters first (can be overridden by defaults)
+      ...customParams,
+      // Default OAuth parameters (take precedence)
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      scope: config.scopes?.join(" ") || "user:email",
+      state: state || ""
+    };
+  },
+  buildTokenBody: (config, code, redirectUri) => ({
+    code,
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: redirectUri
+  })
+});
+export function defineOAuthGithubEventHandler({
+  config,
+  onError,
+  customClaims,
+  onUserInfo,
+  onSuccess
+}) {
+  return defineOAuthEventHandler(githubImplementation, {
+    config,
+    onError,
+    customClaims,
+    onUserInfo,
+    onSuccess
+  });
+}

package/dist/runtime/server/providers/google.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthConfig, GoogleProviderConfig } from '../../types/index.js';
+/**
+ * Create a Google OAuth event handler
+ * @param options - Configuration object
+ * @param options.config - Google OAuth provider configuration
+ * @param options.onError - Error callback function
+ * @param options.customClaims - Custom claims to add to JWT
+ * @param options.onUserInfo - User transformation hook
+ * @param options.onSuccess - Success callback hook
+ * @returns Event handler for Google OAuth authentication
+ */
+export declare function defineOAuthGoogleEventHandler({ config, onError, customClaims, onUserInfo, onSuccess, }: OAuthConfig<GoogleProviderConfig>): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;

package/dist/runtime/server/providers/google.js

@@ -0,0 +1,46 @@
+import { defineOAuthEventHandler, defineOAuthProvider, validateAuthorizationParams } from "./oauthBase.js";
+const googleImplementation = defineOAuthProvider({
+  runtimeConfigKey: "google",
+  defaultConfig: {
+    scopes: ["openid", "profile", "email"]
+  },
+  authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+  tokenUrl: "https://oauth2.googleapis.com/token",
+  userInfoUrl: "https://www.googleapis.com/oauth2/v3/userinfo",
+  extractUser: (userResponse) => userResponse,
+  buildAuthQuery: (config, redirectUri, state) => {
+    const customParams = validateAuthorizationParams(config.authorizationParams, "google");
+    return {
+      // Custom parameters first (can be overridden by defaults)
+      ...customParams,
+      // Default OAuth parameters (take precedence)
+      response_type: "code",
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      scope: config.scopes?.join(" ") || "openid profile email",
+      state: state || ""
+    };
+  },
+  buildTokenBody: (config, code, redirectUri) => ({
+    code,
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: redirectUri,
+    grant_type: "authorization_code"
+  })
+});
+export function defineOAuthGoogleEventHandler({
+  config,
+  onError,
+  customClaims,
+  onUserInfo,
+  onSuccess
+}) {
+  return defineOAuthEventHandler(googleImplementation, {
+    config,
+    onError,
+    customClaims,
+    onUserInfo,
+    onSuccess
+  });
+}

package/dist/runtime/server/providers/mock.d.ts

@@ -0,0 +1,37 @@
+import type { OAuthConfig, MockProviderConfig } from '../../types/index.js';
+/**
+ * Create a Mock OAuth event handler
+ *
+ * Wraps the OAuth handler to:
+ * 1. Check if mock provider is allowed (blocks production)
+ * 2. Validate configuration
+ * 3. Dynamically set base URL for mock endpoints
+ * 4. Pass through user selection and error simulation parameters
+ *
+ * Usage:
+ * ```typescript
+ * // server/routes/auth/mock.get.ts
+ * export default defineOAuthMockEventHandler({
+ *   customClaims: {
+ *     role: 'user',
+ *     permissions: ['read', 'write'],
+ *   },
+ * })
+ * ```
+ *
+ * User Selection:
+ * - Navigate to /auth/mock to use default user
+ * - Navigate to /auth/mock?user=admin to use specific persona
+ *
+ * Error Simulation:
+ * - Navigate to /auth/mock?mock_error=access_denied to test error handling
+ *
+ * @param options - Configuration object
+ * @param options.config - Mock provider configuration (optional, uses runtime config)
+ * @param options.onError - Error callback function
+ * @param options.customClaims - Custom claims to add to JWT
+ * @param options.onUserInfo - User transformation hook
+ * @param options.onSuccess - Success callback hook
+ * @returns Event handler for Mock OAuth authentication
+ */
+export declare function defineOAuthMockEventHandler({ config, onError, customClaims, onUserInfo, onSuccess, }: OAuthConfig<MockProviderConfig>): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;

package/dist/runtime/server/providers/mock.js

@@ -0,0 +1,129 @@
+import { eventHandler, getRequestURL } from "h3";
+import { defineOAuthEventHandler, defineOAuthProvider, validateAuthorizationParams } from "./oauthBase.js";
+import { useRuntimeConfig } from "#imports";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("MockProvider");
+let hasLoggedWarning = false;
+function checkMockProviderAllowed(config) {
+  const isProduction = process.env.NODE_ENV === "production";
+  const isTest = process.env.VITEST === "true" || process.env.NODE_ENV === "test";
+  if (isTest) {
+    return;
+  }
+  if (isProduction && !config.enableInProduction) {
+    throw new Error(
+      "[nuxt-aegis] Mock provider is not available in production. This is a security feature. Never use mock authentication in production. If you absolutely must enable it (NOT RECOMMENDED), set enableInProduction: true in your mock provider config."
+    );
+  }
+  if (isProduction && config.enableInProduction) {
+    if (!hasLoggedWarning) {
+      logger.error(
+        "\u26A0\uFE0F  Mock provider is enabled in PRODUCTION mode. This is extremely dangerous and should never be done in a real production environment!"
+      );
+      hasLoggedWarning = true;
+    }
+  }
+  if (!isProduction && !hasLoggedWarning) {
+    logger.warn(
+      "\u26A0\uFE0F  Mock authentication provider is active. This is for development/testing only and should never be used in production."
+    );
+    hasLoggedWarning = true;
+  }
+}
+function validateMockConfig(config) {
+  if (!config.mockUsers || Object.keys(config.mockUsers).length === 0) {
+    throw new Error(
+      '[nuxt-aegis] Mock provider requires mockUsers configuration. Define at least one user persona in your nuxt.config.ts:\n\nnuxtAegis: {\n  providers: {\n    mock: {\n      clientId: "mock-client",\n      clientSecret: "mock-secret",\n      mockUsers: {\n        user: {\n          sub: "mock-user-001",\n          email: "user@example.com",\n          name: "Test User"\n        }\n      }\n    }\n  }\n}'
+    );
+  }
+  for (const [userId, userData] of Object.entries(config.mockUsers)) {
+    if (!userData.sub) {
+      throw new Error(`[nuxt-aegis] Mock user '${userId}' is missing required field: sub`);
+    }
+    if (!userData.email) {
+      throw new Error(`[nuxt-aegis] Mock user '${userId}' is missing required field: email`);
+    }
+    if (!userData.name) {
+      throw new Error(`[nuxt-aegis] Mock user '${userId}' is missing required field: name`);
+    }
+  }
+  if (config.defaultUser && !config.mockUsers[config.defaultUser]) {
+    throw new Error(
+      `[nuxt-aegis] Mock provider defaultUser '${config.defaultUser}' does not exist in mockUsers. Available users: ${Object.keys(config.mockUsers).join(", ")}`
+    );
+  }
+}
+const mockImplementation = defineOAuthProvider({
+  runtimeConfigKey: "mock",
+  defaultConfig: {
+    scopes: ["openid", "profile", "email"]
+  },
+  // These will be overridden dynamically with the actual server URL
+  authorizeUrl: "__MOCK_BASE_URL__/auth/mock/authorize",
+  tokenUrl: "__MOCK_BASE_URL__/auth/mock/token",
+  userInfoUrl: "__MOCK_BASE_URL__/auth/mock/userinfo",
+  extractUser: (userResponse) => userResponse,
+  buildAuthQuery: (config, redirectUri, state) => {
+    const customParams = validateAuthorizationParams(config.authorizationParams, "mock");
+    return {
+      // Custom parameters first (can be overridden by defaults)
+      ...customParams,
+      // Default OAuth parameters (take precedence)
+      response_type: "code",
+      client_id: config.clientId,
+      redirect_uri: redirectUri,
+      scope: config.scopes?.join(" ") || "openid profile email",
+      state: state || ""
+    };
+  },
+  buildTokenBody: (config, code, redirectUri) => ({
+    code,
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: redirectUri,
+    grant_type: "authorization_code"
+  })
+});
+export function defineOAuthMockEventHandler({
+  config,
+  onError,
+  customClaims,
+  onUserInfo,
+  onSuccess
+}) {
+  return eventHandler(async (event) => {
+    const requestURL = getRequestURL(event);
+    const baseUrl = `${requestURL.protocol}//${requestURL.host}`;
+    const { getQuery } = await import("h3");
+    const incomingQuery = getQuery(event);
+    const userParam = incomingQuery.user;
+    const mockErrorParam = incomingQuery.mock_error;
+    mockImplementation.authorizeUrl = `${baseUrl}/auth/mock/authorize`;
+    mockImplementation.tokenUrl = `${baseUrl}/auth/mock/token`;
+    mockImplementation.userInfoUrl = `${baseUrl}/auth/mock/userinfo`;
+    const runtimeConfig = useRuntimeConfig(event);
+    const mockConfig = runtimeConfig.nuxtAegis?.providers?.mock;
+    if (mockConfig) {
+      checkMockProviderAllowed(mockConfig);
+      validateMockConfig(mockConfig);
+    }
+    const enhancedConfig = config || mockConfig;
+    if (enhancedConfig && (userParam || mockErrorParam)) {
+      const additionalParams = {};
+      if (userParam) additionalParams.user = userParam;
+      if (mockErrorParam) additionalParams.mock_error = mockErrorParam;
+      enhancedConfig.authorizationParams = {
+        ...enhancedConfig.authorizationParams,
+        ...additionalParams
+      };
+    }
+    const oauthHandler = defineOAuthEventHandler(mockImplementation, {
+      config: enhancedConfig,
+      onError,
+      customClaims,
+      onUserInfo,
+      onSuccess
+    });
+    return oauthHandler(event);
+  });
+}