@peterbud/nuxt-aegis 1.1.0-alpha.1 → 1.1.0-alpha.2

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-aegis",
   "configKey": "nuxtAegis",
-  "version": "1.1.0-alpha.1",
+  "version": "1.1.0-alpha.2",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -316,7 +316,15 @@ const module$1 = defineNuxtModule({
     addTypeTemplate({
       filename: "types/nuxt-aegis-nitro.d.ts",
       getContents: () => {
-        return `import type { NitroAegisAuth } from ${JSON.stringify(typesPath)}
+        return `import type { 
+  NitroAegisAuth,
+  UserInfoHookPayload,
+  SuccessHookPayload,
+  ImpersonateCheckPayload,
+  ImpersonateFetchTargetPayload,
+  ImpersonateStartPayload,
+  ImpersonateEndPayload
+} from ${JSON.stringify(typesPath)}
 
 type NuxtAegisRouteRules = {
   /**
@@ -335,6 +343,36 @@ declare module 'nitropack/types' {
   interface NitroRouteConfig {
     nuxtAegis?: NuxtAegisRouteRules
   }
+  interface NitroRuntimeHooks {
+    /**
+     * Hook called after fetching user info from the provider, before storing it.
+     * Use this to transform or validate the OAuth provider response.
+     */
+    'nuxt-aegis:userInfo': (payload: UserInfoHookPayload) => Promise<void> | void
+    /**
+     * Hook called after successful authentication.
+     * Use this for logging, analytics, or database operations.
+     */
+    'nuxt-aegis:success': (payload: SuccessHookPayload) => Promise<void> | void
+    /**
+     * Hook called to determine if a user is allowed to impersonate others.
+     * Return true to allow, false to deny.
+     */
+    'nuxt-aegis:impersonate:check': (payload: ImpersonateCheckPayload) => Promise<boolean> | boolean
+    /**
+     * Hook called to fetch the target user's data for impersonation.
+     * Must return the target user's data or null if not found.
+     */
+    'nuxt-aegis:impersonate:fetchTarget': (payload: ImpersonateFetchTargetPayload) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null
+    /**
+     * Hook called after impersonation starts successfully (fire-and-forget for audit logging).
+     */
+    'nuxt-aegis:impersonate:start': (payload: ImpersonateStartPayload) => Promise<void> | void
+    /**
+     * Hook called after impersonation ends successfully (fire-and-forget for audit logging).
+     */
+    'nuxt-aegis:impersonate:end': (payload: ImpersonateEndPayload) => Promise<void> | void
+  }
 }
 
 declare module 'nitropack' {
@@ -348,6 +386,10 @@ declare module 'nitropack' {
 
 export {}`;
       }
+    }, {
+      nuxt: true,
+      nitro: true,
+      node: true
     });
   }
 });

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

@@ -1,10 +1,10 @@
 import type { ComputedRef } from 'vue';
-import type { TokenPayload } from '../../types/index.js';
+import type { BaseTokenClaims } from '../../types/index.js';
 /**
  * Return type for the useAuth composable
- * @template T - Token payload type extending TokenPayload (defaults to TokenPayload)
+ * @template T - Token payload type extending BaseTokenClaims (defaults to BaseTokenClaims)
  */
-interface UseAuthReturn<T extends TokenPayload = TokenPayload> {
+interface UseAuthReturn<T extends BaseTokenClaims = BaseTokenClaims> {
     /** Reactive property indicating whether a user is logged in */
     isLoggedIn: ComputedRef<boolean>;
     /** Reactive property indicating the authentication state is being initialized */
@@ -60,7 +60,7 @@ interface UseAuthReturn<T extends TokenPayload = TokenPayload> {
  * - logout() - End user session
  * - refresh() - Restore authentication state
  *
- * @template T - Custom token payload type extending TokenPayload
+ * @template T - Custom token payload type extending BaseTokenClaims
  * @returns {UseAuthReturn<T>} Authentication state and methods
  *
  * @example
@@ -71,15 +71,15 @@ interface UseAuthReturn<T extends TokenPayload = TokenPayload> {
  * // With custom claims
  * import type { CustomTokenClaims } from '#nuxt-aegis'
  *
- * type AppTokenPayload = CustomTokenClaims<{
+ * type AppTokenClaims = CustomTokenClaims<{
  *   role: string
  *   permissions: string[]
  *   organizationId: string
  * }>
  *
- * const { user, login, logout } = useAuth<AppTokenPayload>()
+ * const { user, login, logout } = useAuth<AppTokenClaims>()
  * // user.value?.role is now type-safe
  * ```
  */
-export declare function useAuth<T extends TokenPayload = TokenPayload>(): UseAuthReturn<T>;
+export declare function useAuth<T extends BaseTokenClaims = BaseTokenClaims>(): UseAuthReturn<T>;
 export {};

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

@@ -1,4 +1,4 @@
-import type { TokenPayload } from '../../types/index.js';
+import type { BaseTokenClaims } from '../../types/index.js';
 /**
  * Filter out time-sensitive JWT metadata claims that cause hydration mismatches
  *
@@ -14,4 +14,4 @@ import type { TokenPayload } from '../../types/index.js';
  * @param user - Token payload with all claims
  * @returns Token payload with only stable user data
  */
-export declare function filterTimeSensitiveClaims(user: TokenPayload): TokenPayload;
+export declare function filterTimeSensitiveClaims(user: BaseTokenClaims): BaseTokenClaims;

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

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

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

@@ -2,7 +2,6 @@ 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");
@@ -54,14 +53,7 @@ export default defineNitroPlugin((nitroApp) => {
         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 customClaims = storedRefreshToken.customClaims || {};
       const ssrTokenExpiry = tokenRefreshConfig?.ssrTokenExpiry || "5m";
       const ssrAccessToken = await generateToken(
         userPayload,

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

@@ -95,20 +95,28 @@ export function defineOAuthEventHandler(implementation, {
       if (_onUserInfo) {
         providerUserInfo = await _onUserInfo(providerUserInfo, tokens, event);
       } else {
-        const handler = useAegisHandler();
-        if (handler?.onUserInfo) {
+        const handler2 = useAegisHandler();
+        if (handler2?.onUserInfo) {
           const hookPayload = {
             providerUserInfo,
             tokens,
             provider: implementation.runtimeConfigKey,
             event
           };
-          const transformedUser = await handler.onUserInfo(hookPayload);
+          const transformedUser = await handler2.onUserInfo(hookPayload);
           if (transformedUser) {
             providerUserInfo = transformedUser;
           }
         }
       }
+      const handler = useAegisHandler();
+      if (handler?.onUserPersist) {
+        const enrichedData = await handler.onUserPersist(providerUserInfo, {
+          provider: implementation.runtimeConfigKey,
+          event
+        });
+        providerUserInfo = { ...providerUserInfo, ...enrichedData };
+      }
       let resolvedCustomClaims;
       if (_customClaims) {
         if (typeof _customClaims === "function") {
@@ -116,6 +124,8 @@ export function defineOAuthEventHandler(implementation, {
         } else {
           resolvedCustomClaims = _customClaims;
         }
+      } else if (handler?.customClaims) {
+        resolvedCustomClaims = await handler.customClaims(providerUserInfo);
       }
       if (_onSuccess) {
         await _onSuccess({

package/dist/runtime/server/routes/me.get.d.ts

@@ -2,5 +2,5 @@
  * GET /api/user/me
  * Returns the current authenticated user's information
  */
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../types/index.js").TokenPayload>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../types/index.js").BaseTokenClaims>>;
 export default _default;

package/dist/runtime/server/routes/password/change.post.js

@@ -93,10 +93,23 @@ export default defineEventHandler(async (event) => {
     });
   }
   const newHashedPassword = handler.password.hashPassword ? await handler.password.hashPassword(newPassword) : await hashPassword(newPassword);
-  await handler.password.upsertUser({
-    ...user,
-    hashedPassword: newHashedPassword
-  });
+  if (handler.onUserPersist) {
+    await handler.onUserPersist(
+      {
+        ...user,
+        hashedPassword: newHashedPassword
+      },
+      {
+        provider: "password",
+        event
+      }
+    );
+  } else {
+    throw createError({
+      statusCode: 500,
+      message: "onUserPersist handler is required for password authentication"
+    });
+  }
   const refreshCookieName = config.nuxtAegis?.tokenRefresh?.cookie?.cookieName || "nuxt-aegis-refresh";
   const currentRefreshToken = getCookie(event, refreshCookieName);
   let currentTokenHash;

package/dist/runtime/server/routes/password/register-verify.get.js

@@ -50,19 +50,27 @@ export default defineEventHandler(async (event) => {
     });
   }
   try {
-    await handler.password.upsertUser({
+    let userData = {
       email,
       hashedPassword
-    });
-    const user = await handler.password.findUser(email);
-    if (!user) {
-      throw new Error("User not found after creation");
+    };
+    if (handler.onUserPersist) {
+      const enrichedData = await handler.onUserPersist(userData, {
+        provider: "password",
+        event
+      });
+      userData = { ...userData, ...enrichedData };
+    } else {
+      throw createError({
+        statusCode: 500,
+        message: "onUserPersist handler is required for password authentication"
+      });
     }
     await retrieveAndDeleteMagicCode(code);
     const providerUserInfo = {
-      sub: user.id || user.email,
+      sub: userData.id || userData.email,
       provider: "password",
-      ...user
+      ...userData
     };
     const authCode = generateAuthCode();
     await storeAuthCode(

package/dist/runtime/server/routes/password/reset-complete.post.js

@@ -60,10 +60,23 @@ export default defineEventHandler(async (event) => {
         message: "User not found"
       });
     }
-    await handler.password.upsertUser({
-      ...user,
-      hashedPassword
-    });
+    if (handler.onUserPersist) {
+      await handler.onUserPersist(
+        {
+          ...user,
+          hashedPassword
+        },
+        {
+          provider: "password",
+          event
+        }
+      );
+    } else {
+      throw createError({
+        statusCode: 500,
+        message: "onUserPersist handler is required for password authentication"
+      });
+    }
     return { success: true };
   } catch (error) {
     logger.error("Password reset failed", error);

package/dist/runtime/server/routes/refresh.post.js

@@ -7,7 +7,6 @@ import {
   revokeRefreshToken
 } from "../utils/refreshToken.js";
 import { setRefreshTokenCookie } from "../utils/cookies.js";
-import { processCustomClaims } from "../utils/customClaims.js";
 import { useRuntimeConfig } from "#imports";
 export default defineEventHandler(async (event) => {
   const config = useRuntimeConfig(event);
@@ -56,14 +55,7 @@ export default defineEventHandler(async (event) => {
     }
     const providerUserInfo = storedRefreshToken.providerUserInfo;
     const provider = storedRefreshToken.provider;
-    let customClaims = {};
-    const providerConfig = config.nuxtAegis?.providers?.[provider];
-    if (providerConfig && "customClaims" in providerConfig) {
-      const customClaimsConfig = providerConfig.customClaims;
-      if (customClaimsConfig) {
-        customClaims = await processCustomClaims(providerUserInfo, customClaimsConfig);
-      }
-    }
+    const customClaims = storedRefreshToken.customClaims || {};
     const payload = {
       sub: String(providerUserInfo.sub || providerUserInfo.email || providerUserInfo.id || ""),
       email: providerUserInfo.email,
@@ -81,6 +73,8 @@ export default defineEventHandler(async (event) => {
       tokenRefreshConfig,
       hashedRefreshToken,
       // Pass previous token hash for rotation tracking
+      customClaims,
+      // Preserve custom claims in new refresh token
       event
     );
     if (newRefreshToken) {

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

@@ -1,5 +1,5 @@
 import type { H3Event } from 'h3';
-import type { TokenPayload } from '../../types/index.js';
+import type { BaseTokenClaims } from '../../types/index.js';
 /**
  * Generate authentication tokens from user data with optional custom claims
  * This is the recommended way to generate tokens after successful OAuth authentication
@@ -42,19 +42,19 @@ export declare function generateAuthTokens(event: H3Event, providerUserInfo: Rec
  * @example
  * ```typescript
  * // With custom claims typing
- * interface MyTokenPayload extends TokenPayload {
+ * type AppTokenClaims = CustomTokenClaims<{
  *   role: string
  *   permissions: string[]
- * }
+ * }>
  *
  * export default defineEventHandler((event) => {
- *   const authedEvent = requireAuth<MyTokenPayload>(event)
+ *   const authedEvent = requireAuth<AppTokenClaims>(event)
  *   // TypeScript knows about role and permissions
  *   return { role: authedEvent.context.user.role }
  * })
  * ```
  */
-export declare function requireAuth<T extends TokenPayload = TokenPayload>(event: H3Event): H3Event & {
+export declare function requireAuth<T extends BaseTokenClaims = BaseTokenClaims>(event: H3Event): H3Event & {
     context: {
         user: T;
     };
@@ -79,16 +79,16 @@ export declare function requireAuth<T extends TokenPayload = TokenPayload>(event
  * @example
  * ```typescript
  * // With custom claims typing
- * interface MyTokenPayload extends TokenPayload {
+ * export type AppTokenClaims = CustomTokenClaims<{
  *   role: string
  *   permissions: string[]
- * }
+ * }>
  *
  * export default defineEventHandler((event) => {
- *   const user = getAuthUser<MyTokenPayload>(event)
+ *   const user = getAuthUser<AppTokenClaims>(event)
  *   // TypeScript knows about role and permissions
  *   return { role: user.role, permissions: user.permissions }
  * })
  * ```
  */
-export declare function getAuthUser<T extends TokenPayload = TokenPayload>(event: H3Event): T | null;
+export declare function getAuthUser<T extends BaseTokenClaims = BaseTokenClaims>(event: H3Event): T | null;

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

@@ -25,6 +25,8 @@ export async function generateAuthTokens(event, providerUserInfo, provider, cust
     tokenRefreshConfig,
     void 0,
     // No previous token hash for initial auth
+    customClaims,
+    // Store resolved custom claims for consistent refresh
     event
   );
   return {

package/dist/runtime/server/utils/handler.d.ts

@@ -1,14 +1,82 @@
 import type { H3Event } from 'h3';
 import type { UserInfoHookPayload } from '../../types/hooks.js';
-import type { TokenPayload } from '../../types/token.js';
+import type { BaseTokenClaims } from '../../types/token.js';
 import type { PasswordUser } from '../../types/providers.js';
+/**
+ * Context passed to onUserPersist handler
+ */
+export interface UserPersistContext {
+    /** Provider name (e.g., 'google', 'github', 'password') */
+    provider: string;
+    /** H3 event for server context access */
+    event: H3Event;
+}
 export interface AegisHandler {
     /**
      * Transform user data after fetching from OAuth provider.
-     * Replaces `nuxt-aegis:userInfo` hook.
      * Return the modified user object to use it.
      */
     onUserInfo?: (payload: UserInfoHookPayload) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined;
+    /**
+     * Persist user data to your database and return enriched user information.
+     *
+     * Called for:
+     * - OAuth authentication: After provider data transformation, before JWT generation
+     * - Password authentication: After registration, password change, or reset
+     *
+     * The returned object is merged into the user data and used for JWT claims.
+     *
+     * @param user - User data to persist (provider-specific fields vary)
+     * @param context - Context with provider name and H3 event
+     * @returns Enriched user object with database fields (e.g., userId, role, permissions)
+     *
+     * @example
+     * ```typescript
+     * onUserPersist: async (user, { provider, event }) => {
+     *   // For password provider, user includes hashedPassword
+     *   if (provider === 'password') {
+     *     const dbUser = await db.users.upsert({
+     *       where: { email: user.email },
+     *       update: { hashedPassword: user.hashedPassword },
+     *       create: { email: user.email, hashedPassword: user.hashedPassword },
+     *     })
+     *     return { userId: dbUser.id, role: dbUser.role }
+     *   }
+     *
+     *   // For OAuth providers, link or create user
+     *   const dbUser = await db.users.upsert({
+     *     where: { email: user.email },
+     *     update: { lastLogin: new Date() },
+     *     create: { email: user.email, name: user.name, picture: user.picture },
+     *   })
+     *   return { userId: dbUser.id, role: dbUser.role, permissions: dbUser.permissions }
+     * }
+     * ```
+     */
+    onUserPersist?: (user: Record<string, unknown>, context: UserPersistContext) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Generate custom claims for JWT tokens.
+     *
+     * Called after onUserPersist, receives the merged user data.
+     * This is the recommended location for adding database-driven claims.
+     *
+     * Provider-level customClaims (defined in route handlers) take precedence over this.
+     *
+     * @param user - Complete user object including data from onUserPersist
+     * @returns Custom claims to add to the JWT
+     *
+     * @example
+     * ```typescript
+     * customClaims: async (user) => {
+     *   return {
+     *     role: user.role,
+     *     permissions: user.permissions,
+     *     organizationId: user.organizationId,
+     *   }
+     * }
+     * ```
+     */
+    customClaims?: (user: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
     /**
      * Password authentication handler.
      * Required if password provider is enabled.
@@ -20,11 +88,6 @@ export interface AegisHandler {
          * Return null if user is not found.
          */
         findUser: (email: string) => Promise<PasswordUser | null> | PasswordUser | null;
-        /**
-         * Create or update a user.
-         * Called after successful registration or password change.
-         */
-        upsertUser: (user: PasswordUser) => Promise<void> | void;
         /**
          * Send a verification code to the user.
          * Called during registration, login, and password reset.
@@ -63,7 +126,7 @@ export interface AegisHandler {
          * If not defined, defaults to allowing if fetchTarget returns a user.
          * You can throw an error here to provide a specific message.
          */
-        canImpersonate?: (requester: TokenPayload, targetId: string, event: H3Event) => Promise<boolean> | boolean;
+        canImpersonate?: (requester: BaseTokenClaims, targetId: string, event: H3Event) => Promise<boolean> | boolean;
     };
 }
 /**

package/dist/runtime/server/utils/impersonation.d.ts

@@ -1,5 +1,5 @@
 import type { H3Event } from 'h3';
-import type { TokenPayload } from '../../types/index.js';
+import type { BaseTokenClaims } from '../../types/index.js';
 /**
  * Check if the requester is allowed to impersonate other users
  * @param requester - The user requesting impersonation
@@ -7,7 +7,7 @@ import type { TokenPayload } from '../../types/index.js';
  * @param event - H3 event for context
  * @throws 403 error if impersonation is not allowed
  */
-export declare function checkImpersonationAllowed(requester: TokenPayload, targetUserId: string, event: H3Event): Promise<void>;
+export declare function checkImpersonationAllowed(requester: BaseTokenClaims, targetUserId: string, event: H3Event): Promise<void>;
 /**
  * Fetch target user data for impersonation
  * @param requester - The user requesting impersonation
@@ -17,7 +17,7 @@ export declare function checkImpersonationAllowed(requester: TokenPayload, targe
  * @throws 404 error if user not found
  * @throws 500 error if hook is not implemented
  */
-export declare function fetchTargetUser(requester: TokenPayload, targetUserId: string, event: H3Event): Promise<Record<string, unknown>>;
+export declare function fetchTargetUser(requester: BaseTokenClaims, targetUserId: string, event: H3Event): Promise<Record<string, unknown>>;
 /**
  * Generate an impersonated JWT token
  * @param requester - The user performing impersonation
@@ -26,7 +26,7 @@ export declare function fetchTargetUser(requester: TokenPayload, targetUserId: s
  * @param _event - H3 event for context
  * @returns JWT access token (no refresh token)
  */
-export declare function generateImpersonatedToken(requester: TokenPayload, targetUserData: Record<string, unknown>, reason: string | undefined, _event: H3Event): Promise<string>;
+export declare function generateImpersonatedToken(requester: BaseTokenClaims, targetUserData: Record<string, unknown>, reason: string | undefined, _event: H3Event): Promise<string>;
 /**
  * Start impersonation session
  * @param requester - The user requesting impersonation (must be admin)
@@ -35,14 +35,14 @@ export declare function generateImpersonatedToken(requester: TokenPayload, targe
  * @param event - H3 event for context
  * @returns Access token for impersonated session (no refresh token)
  */
-export declare function startImpersonation(requester: TokenPayload, targetUserId: string, reason: string | undefined, event: H3Event): Promise<string>;
+export declare function startImpersonation(requester: BaseTokenClaims, targetUserId: string, reason: string | undefined, event: H3Event): Promise<string>;
 /**
  * End impersonation and restore original user session
  * @param currentToken - Current JWT token (must contain impersonation context)
  * @param event - H3 event for context
  * @returns Object with new access token and refresh token ID
  */
-export declare function endImpersonation(currentToken: TokenPayload, event: H3Event): Promise<{
+export declare function endImpersonation(currentToken: BaseTokenClaims, event: H3Event): Promise<{
     accessToken: string;
     refreshTokenId: string;
 }>;

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

@@ -1,6 +1,7 @@
 import { createError } from "h3";
 import { generateToken } from "./jwt.js";
-import { useRuntimeConfig, useNitroApp } from "#imports";
+import { useRuntimeConfig } from "#imports";
+import { useNitroApp } from "nitropack/runtime";
 import { createLogger } from "./logger.js";
 import { generateAndStoreRefreshToken } from "./refreshToken.js";
 import { useAegisHandler } from "./handler.js";
@@ -226,6 +227,8 @@ export async function endImpersonation(currentToken, event) {
     refreshTokenConfig,
     void 0,
     // No previous token
+    customClaims,
+    // Store custom claims for restored session
     event
   );
   if (!refreshTokenId) {

package/dist/runtime/server/utils/jwt.d.ts

@@ -1,4 +1,4 @@
-import type { TokenConfig, TokenPayload } from '../../types/index.js';
+import type { TokenConfig, BaseTokenClaims } from '../../types/index.js';
 /**
  * Generate a JWT token with the given payload and custom claims
  * @param payload - Base token payload containing user information
@@ -6,7 +6,7 @@ import type { TokenConfig, TokenPayload } from '../../types/index.js';
  * @param customClaims - Optional custom claims to add to the token
  * @returns Signed JWT token
  */
-export declare function generateToken(payload: TokenPayload, config: TokenConfig, customClaims?: Record<string, unknown>): Promise<string>;
+export declare function generateToken(payload: BaseTokenClaims, config: TokenConfig, customClaims?: Record<string, unknown>): Promise<string>;
 /**
  * Update an existing JWT token with additional claims
  * @param token - Existing JWT token to update
@@ -21,4 +21,4 @@ export declare function updateTokenWithClaims(token: string, claims: Record<stri
  * @param secret - Secret key used to sign the token
  * @returns Decoded token payload or null if verification fails
  */
-export declare function verifyToken(token: string, secret: string, checkExpiration?: boolean): Promise<TokenPayload | null>;
+export declare function verifyToken(token: string, secret: string, checkExpiration?: boolean): Promise<BaseTokenClaims | null>;

package/dist/runtime/server/utils/refreshToken.d.ts

@@ -60,10 +60,11 @@ export declare function revokeRefreshToken(tokenHash: string, event?: H3Event):
  * @param provider - Provider name (e.g., 'google', 'github', 'microsoft', 'auth0')
  * @param config - Token refresh configuration
  * @param previousTokenHash - Hash of previous refresh token for rotation tracking
+ * @param customClaims - Resolved custom claims from initial authentication
  * @param event - H3Event for Nitro storage access
  * @returns The generated refresh token string
  */
-export declare function generateAndStoreRefreshToken(providerUserInfo: Record<string, unknown>, provider: string, config: TokenRefreshConfig, previousTokenHash?: string, event?: H3Event): Promise<string | undefined>;
+export declare function generateAndStoreRefreshToken(providerUserInfo: Record<string, unknown>, provider: string, config: TokenRefreshConfig, previousTokenHash?: string, customClaims?: Record<string, unknown>, event?: H3Event): Promise<string | undefined>;
 /**
  * Delete all refresh tokens for a specific user
  * Used during password change or account deletion

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

@@ -77,7 +77,7 @@ export async function revokeRefreshToken(tokenHash, event) {
   data.isRevoked = true;
   await storeRefreshTokenData(tokenHash, data, event);
 }
-export async function generateAndStoreRefreshToken(providerUserInfo, provider, config, previousTokenHash, event) {
+export async function generateAndStoreRefreshToken(providerUserInfo, provider, config, previousTokenHash, customClaims, event) {
   const refreshToken = randomBytes(32).toString("base64url");
   const expiresIn = config.cookie?.maxAge || 604800;
   await storeRefreshTokenData(hashRefreshToken(refreshToken), {
@@ -87,8 +87,10 @@ export async function generateAndStoreRefreshToken(providerUserInfo, provider, c
     previousTokenHash,
     providerUserInfo,
     // Store complete OAuth provider user data
-    provider
+    provider,
     // Store provider name for custom claims refresh
+    customClaims
+    // Store resolved custom claims for consistent refresh
   }, event);
   return refreshToken;
 }

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

@@ -1,6 +1,6 @@
 import type { NuxtAegisRuntimeConfig, RedirectConfig, LoggingConfig } from './config.js';
 import type { TokenRefreshConfig } from './refresh.js';
-import type { TokenPayload } from './token.js';
+import type { BaseTokenClaims } from './token.js';
 import type { ClientMiddlewareConfig } from './routes.js';
 import type { SuccessHookPayload } from './hooks.js';
 /**
@@ -41,7 +41,7 @@ declare module 'h3' {
          * Authenticated user data from JWT token
          * Available when request is authenticated via the auth middleware
          */
-        user?: TokenPayload;
+        user?: BaseTokenClaims;
         /**
          * Original user data before impersonation
          * Available when impersonation is active

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

@@ -1,5 +1,5 @@
 import type { H3Event } from 'h3';
-import type { TokenPayload } from './token.js';
+import type { BaseTokenClaims } from './token.js';
 /**
  * Nitro hook type definitions for Nuxt Aegis
  * These hooks allow users to customize authentication behavior via server plugins
@@ -52,7 +52,7 @@ export interface SuccessHookPayload {
  */
 export interface ImpersonateCheckPayload {
     /** JWT payload of the user requesting impersonation */
-    requester: TokenPayload;
+    requester: BaseTokenClaims;
     /** Target user ID to impersonate */
     targetUserId: string;
     /** Optional reason for impersonation (for audit) */
@@ -72,7 +72,7 @@ export interface ImpersonateCheckPayload {
  */
 export interface ImpersonateFetchTargetPayload {
     /** JWT payload of the user requesting impersonation */
-    requester: TokenPayload;
+    requester: BaseTokenClaims;
     /** Target user ID to impersonate */
     targetUserId: string;
     /** H3 event for server context access */
@@ -84,9 +84,9 @@ export interface ImpersonateFetchTargetPayload {
  */
 export interface ImpersonateStartPayload {
     /** JWT payload of the user who initiated impersonation */
-    requester: TokenPayload;
+    requester: BaseTokenClaims;
     /** JWT payload of the impersonated user */
-    targetUser: TokenPayload;
+    targetUser: BaseTokenClaims;
     /** Reason for impersonation */
     reason?: string;
     /** H3 event for server context access */
@@ -104,9 +104,9 @@ export interface ImpersonateStartPayload {
  */
 export interface ImpersonateEndPayload {
     /** JWT payload of the restored original user */
-    restoredUser: TokenPayload;
+    restoredUser: BaseTokenClaims;
     /** JWT payload of the user who was being impersonated */
-    impersonatedUser: TokenPayload;
+    impersonatedUser: BaseTokenClaims;
     /** H3 event for server context access */
     event: H3Event;
     /** Client IP address (for audit) */

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

@@ -3,7 +3,7 @@
  * 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 { BaseTokenClaims, 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';

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

@@ -21,11 +21,16 @@ export interface ImpersonationContext {
     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
+ * Base JWT token claims interface
+ *
+ * Defines the standard JWT claims that are always present in tokens.
+ * This serves as the foundation for CustomTokenClaims, which extends these
+ * base claims with your application-specific custom claims.
+ *
+ * Use CustomTokenClaims<T> to add your own claims on top of these base claims.
+ * This is what gets stored in the JWT and attached to event.context.user.
  */
-export interface TokenPayload {
+export interface BaseTokenClaims {
     /** Subject identifier (user ID) - required claim */
     sub: string;
     /** User email address */
@@ -71,6 +76,8 @@ export interface RefreshTokenData {
     providerUserInfo: Record<string, unknown>;
     /** Provider name for dynamic custom claims generation during refresh (e.g., 'google', 'github', 'microsoft', 'auth0') */
     provider: string;
+    /** Resolved custom claims from initial authentication - reused during token refresh to maintain consistency */
+    customClaims?: Record<string, unknown>;
 }
 /**
  * Response from token refresh operation
@@ -114,30 +121,39 @@ export type JSONValue = string | number | boolean | null | undefined | string[]
 /**
  * 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.
+ * Combines BaseTokenClaims (standard JWT claims like sub, email, name) with your
+ * application-specific custom claims. This is the primary type you'll use when
+ * working with authenticated users in your application.
+ *
+ * The relationship:
+ * - BaseTokenClaims: Standard JWT claims (sub, email, name, iss, exp, etc.)
+ * - CustomTokenClaims<T>: BaseTokenClaims + your custom claims (role, permissions, etc.)
+ *
+ * Ensures type safety by preventing override of standard JWT claims and ensuring
+ * all custom claims are JSON-serializable.
  *
- * @template T - Record of custom claims to add to the token payload
+ * @template T - Record of custom claims to add to the base token claims
  *
  * @example
  * ```typescript
- * // Define your custom claims
- * type AppTokenPayload = CustomTokenClaims<{
+ * // Define your custom claims on top of base claims
+ * type AppTokenClaims = CustomTokenClaims<{
  *   role: string
  *   permissions: string[]
  *   organizationId: string
  * }>
  *
- * // Use with useAuth
- * const { user } = useAuth<AppTokenPayload>()
- * console.log(user.value?.role) // Type-safe access
+ * // Use with useAuth - you get both base claims (sub, email, name)
+ * // and your custom claims (role, permissions, organizationId)
+ * const { user } = useAuth<AppTokenClaims>()
+ * console.log(user.value?.email) // Base claim
+ * console.log(user.value?.role) // Custom claim - Type-safe access
  * ```
  *
  * @example
  * ```typescript
  * // With nested objects (one level)
- * type AppTokenPayload = CustomTokenClaims<{
+ * type AppTokenClaims = CustomTokenClaims<{
  *   role: string
  *   metadata: {
  *     tenantId: string
@@ -149,27 +165,27 @@ export type JSONValue = string | number | boolean | null | undefined | 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;
+export type CustomTokenClaims<T extends Record<string, JSONValue>> = BaseTokenClaims & T;
 /**
  * Utility type to extract only custom claims from a token payload
  *
- * Removes all standard TokenPayload fields, leaving only your custom claims.
+ * Removes all standard BaseTokenClaims fields, leaving only your custom claims.
  * Useful for type composition and claim validation.
  *
- * @template T - A token payload type extending TokenPayload
+ * @template T - A token payload type extending BaseTokenClaims
  *
  * @example
  * ```typescript
- * type AppTokenPayload = CustomTokenClaims<{
+ * type AppTokenClaims = CustomTokenClaims<{
  *   role: string
  *   permissions: string[]
  * }>
  *
- * type CustomClaims = ExtractClaims<AppTokenPayload>
+ * type CustomClaims = ExtractClaims<AppTokenClaims>
  * // Result: { role: string, permissions: string[] }
  * ```
  */
-export type ExtractClaims<T extends TokenPayload> = Omit<T, keyof TokenPayload>;
+export type ExtractClaims<T extends BaseTokenClaims> = Omit<T, keyof BaseTokenClaims>;
 /**
  * Custom claims callback function
  * Receives the full OAuth provider user data and tokens

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterbud/nuxt-aegis",
-  "version": "1.1.0-alpha.1",
+  "version": "1.1.0-alpha.2",
   "description": "Nuxt module for authentication with JWT token generation and session management.",
   "publishConfig": {
     "access": "public"