@peterbud/nuxt-aegis 1.1.0-alpha

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

@@ -0,0 +1,123 @@
+import { randomBytes } from "node:crypto";
+import { useStorage } from "#imports";
+import { createLogger } from "./logger.js";
+const logger = createLogger("AuthCode");
+export function generateAuthCode() {
+  const code = randomBytes(32).toString("base64url");
+  logger.security("Authorization code generated", {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    event: "CODE_GENERATED",
+    codePrefix: `${code.substring(0, 8)}...`
+  });
+  return code;
+}
+export async function storeAuthCode(code, providerUserInfo, providerTokens, provider, customClaims, expiresIn = 60, _event) {
+  const now = Date.now();
+  const authCodeData = {
+    providerUserInfo,
+    providerTokens,
+    expiresAt: now + expiresIn * 1e3,
+    // CS-4: Set expiration timestamp
+    createdAt: now,
+    provider,
+    customClaims
+    // Store resolved custom claims
+  };
+  await useStorage("authCodeStore").setItem(code, authCodeData);
+  logger.security("Authorization code stored", {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    event: "CODE_STORED",
+    codePrefix: `${code.substring(0, 8)}...`,
+    expiresAt: new Date(authCodeData.expiresAt).toISOString(),
+    expiresInSeconds: expiresIn
+  });
+}
+export async function validateAuthCode(code) {
+  const authCodeData = await useStorage("authCodeStore").getItem(code);
+  if (!authCodeData) {
+    logger.security("Authorization code not found", {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "CODE_NOT_FOUND",
+      codePrefix: `${code.substring(0, 8)}...`,
+      severity: "warning"
+    });
+    return null;
+  }
+  if (Date.now() > authCodeData.expiresAt) {
+    logger.security("Authorization code expired", {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "CODE_EXPIRED",
+      codePrefix: `${code.substring(0, 8)}...`,
+      expiresAt: new Date(authCodeData.expiresAt).toISOString(),
+      severity: "warning"
+    });
+    await useStorage("authCodeStore").removeItem(code);
+    return null;
+  }
+  return authCodeData;
+}
+export async function retrieveAndDeleteAuthCode(code) {
+  const authCodeData = await validateAuthCode(code);
+  if (!authCodeData) {
+    logger.security("Invalid authorization code exchange attempt", {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      event: "CODE_EXCHANGE_FAILED",
+      codePrefix: `${code.substring(0, 8)}...`,
+      reason: "invalid_or_expired",
+      severity: "warning"
+    });
+    return null;
+  }
+  await useStorage("authCodeStore").removeItem(code);
+  logger.security("Authorization code successfully exchanged", {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    event: "CODE_EXCHANGE_SUCCESS",
+    codePrefix: `${code.substring(0, 8)}...`,
+    codeAge: Date.now() - authCodeData.createdAt
+  });
+  return authCodeData;
+}
+export async function cleanupExpiredAuthCodes() {
+  const storage = useStorage("authCodeStore");
+  const keys = await storage.getKeys();
+  const now = Date.now();
+  let cleanedCount = 0;
+  for (const key of keys) {
+    const authCodeData = await storage.getItem(key);
+    if (!authCodeData) {
+      continue;
+    }
+    if (now > authCodeData.expiresAt) {
+      await storage.removeItem(key);
+      cleanedCount++;
+      logger.debug("Cleaned up expired authorization code:", `${key.substring(0, 8)}...`);
+    }
+  }
+  if (cleanedCount > 0) {
+    logger.info(`Cleanup completed: ${cleanedCount} expired code(s) removed`);
+  }
+  return cleanedCount;
+}
+export async function getAuthCodeStats() {
+  const storage = useStorage("authCodeStore");
+  const keys = await storage.getKeys();
+  const now = Date.now();
+  let validCount = 0;
+  let expiredCount = 0;
+  for (const key of keys) {
+    const authCodeData = await storage.getItem(key);
+    if (!authCodeData) {
+      continue;
+    }
+    if (now > authCodeData.expiresAt) {
+      expiredCount++;
+    } else {
+      validCount++;
+    }
+  }
+  return {
+    total: keys.length,
+    valid: validCount,
+    expired: expiredCount
+  };
+}

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

@@ -0,0 +1,15 @@
+import type { H3Event } from 'h3';
+import type { CookieConfig } from '../../types/index.js';
+/**
+ * Set the authentication token as an HTTP-only cookie
+ * @param event - H3Event object
+ * @param token - JWT token to set as cookie
+ * @param cookieConfig - Optional cookie configuration
+ */
+export declare function setRefreshTokenCookie(event: H3Event, token: string, cookieConfig?: CookieConfig): void;
+/**
+ * Clear the authentication token cookie
+ * @param event - H3Event object
+ * @param cookieConfig - Optional cookie configuration
+ */
+export declare function clearToken(event: H3Event, cookieConfig?: CookieConfig): void;

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

@@ -0,0 +1,23 @@
+import { setCookie, deleteCookie } from "h3";
+export function setRefreshTokenCookie(event, token, cookieConfig) {
+  if (!token) {
+    throw new Error("Token is required");
+  }
+  const cookieName = cookieConfig?.cookieName || "nuxt-aegis-refresh";
+  const maxAge = cookieConfig?.maxAge || 604800;
+  setCookie(event, cookieName, token, {
+    httpOnly: cookieConfig?.httpOnly ?? true,
+    // SC-3: Set HttpOnly flag
+    secure: cookieConfig?.secure ?? process.env.NODE_ENV === "production",
+    // SC-4: Set Secure flag in production
+    sameSite: cookieConfig?.sameSite || "lax",
+    // SC-5: Set SameSite attribute
+    path: cookieConfig?.path || "/",
+    domain: cookieConfig?.domain,
+    maxAge
+  });
+}
+export function clearToken(event, cookieConfig) {
+  const cookieName = cookieConfig?.cookieName || "nuxt-aegis-refresh";
+  deleteCookie(event, cookieName);
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Custom Claims Processing Utilities
+ * Handles processing of custom claims from static values or callback functions
+ */
+/**
+ * Process custom claims configuration
+ * Supports both static claim objects and callback functions (sync/async)
+ * The same function is used for both initial authentication and token refresh
+ *
+ * @param providerUserInfo - Complete OAuth provider user data
+ * @param customClaimsConfig - Custom claims configuration (static object or callback function)
+ * @returns Processed custom claims object
+ *
+ * @example
+ * // Static claims
+ * const claims = await processCustomClaims(providerUserInfo, { role: 'admin', tier: 'premium' })
+ *
+ * @example
+ * // Callback function
+ * const claims = await processCustomClaims(providerUserInfo, async (providerUserInfo) => {
+ *   const dbUser = await fetchUserFromDB(providerUserInfo.email)
+ *   return { role: dbUser.role, permissions: dbUser.permissions }
+ * })
+ */
+export declare function processCustomClaims(providerUserInfo: Record<string, unknown>, customClaimsConfig?: Record<string, unknown> | ((providerUserInfo: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>)): Promise<Record<string, unknown>>;
+/**
+ * Validate that custom claims don't override reserved JWT claims
+ * @param claims - Custom claims to validate
+ * @returns Filtered claims with reserved claims removed
+ */
+export declare function filterReservedClaims(claims: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Validate that custom claim values are of supported types
+ * @param claims - Custom claims to validate
+ * @returns Filtered claims with only supported value types
+ */
+export declare function validateClaimTypes(claims: Record<string, unknown>): Record<string, unknown>;

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

@@ -0,0 +1,45 @@
+import { createLogger } from "./logger.js";
+const logger = createLogger("CustomClaims");
+export async function processCustomClaims(providerUserInfo, customClaimsConfig) {
+  if (!customClaimsConfig) {
+    return {};
+  }
+  if (typeof customClaimsConfig !== "function") {
+    return customClaimsConfig;
+  }
+  try {
+    const result = customClaimsConfig(providerUserInfo);
+    const claims = result instanceof Promise ? await result : result;
+    if (typeof claims !== "object" || claims === null || Array.isArray(claims)) {
+      logger.warn("Custom claims callback must return an object");
+      return {};
+    }
+    return claims;
+  } catch (error) {
+    logger.error("Error processing custom claims:", error);
+    return {};
+  }
+}
+export function filterReservedClaims(claims) {
+  const reservedClaims = ["iss", "sub", "exp", "iat", "nbf", "jti", "aud"];
+  const filtered = {};
+  Object.entries(claims).forEach(([key, value]) => {
+    if (reservedClaims.includes(key)) {
+      logger.warn(`Cannot override reserved JWT claim: ${key}`);
+    } else {
+      filtered[key] = value;
+    }
+  });
+  return filtered;
+}
+export function validateClaimTypes(claims) {
+  const validated = {};
+  Object.entries(claims).forEach(([key, value]) => {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || Array.isArray(value) || value === null) {
+      validated[key] = value;
+    } else {
+      logger.warn(`Custom claim "${key}" has unsupported type and will be ignored`);
+    }
+  });
+  return validated;
+}

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

@@ -0,0 +1,77 @@
+import type { H3Event } from 'h3';
+import type { UserInfoHookPayload } from '../../types/hooks.js';
+import type { TokenPayload } from '../../types/token.js';
+import type { PasswordUser } from '../../types/providers.js';
+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;
+    /**
+     * Password authentication handler.
+     * Required if password provider is enabled.
+     */
+    password?: {
+        /**
+         * Find a user by email.
+         * Used during login and registration checks.
+         * 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.
+         */
+        sendVerificationCode: (email: string, code: string, action: 'register' | 'login' | 'reset') => Promise<void> | void;
+        /**
+         * Validate password strength.
+         * Override default validation logic.
+         * Return true if valid, or an array of error messages.
+         */
+        validatePassword?: (password: string) => Promise<boolean | string[]> | boolean | string[];
+        /**
+         * Hash a password.
+         * Override default bcrypt hashing.
+         */
+        hashPassword?: (password: string) => Promise<string> | string;
+        /**
+         * Verify a password against a hash.
+         * Override default bcrypt verification.
+         */
+        verifyPassword?: (password: string, hash: string) => Promise<boolean> | boolean;
+    };
+    /**
+     * Impersonation logic.
+     * Replaces `nuxt-aegis:impersonate:check` and `nuxt-aegis:impersonate:fetchTarget` hooks.
+     */
+    impersonation?: {
+        /**
+         * Fetch the target user to be impersonated.
+         * Must return a user object that will be used to generate the JWT.
+         * Return null if user is not found.
+         */
+        fetchTarget: (targetId: string, event: H3Event) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+        /**
+         * Check if the requester is allowed to impersonate the target.
+         * 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;
+    };
+}
+/**
+ * Registers the Aegis handler configuration.
+ * Call this within a server plugin.
+ */
+export declare const defineAegisHandler: (handler: AegisHandler) => void;
+/**
+ * Internal: Retrieves the registered handler.
+ */
+export declare const useAegisHandler: () => AegisHandler | null;

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

@@ -0,0 +1,7 @@
+let _handler = null;
+export const defineAegisHandler = (handler) => {
+  _handler = handler;
+};
+export const useAegisHandler = () => {
+  return _handler;
+};

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

@@ -0,0 +1,48 @@
+import type { H3Event } from 'h3';
+import type { TokenPayload } from '../../types/index.js';
+/**
+ * Check if the requester is allowed to impersonate other users
+ * @param requester - The user requesting impersonation
+ * @param targetUserId - The ID of the user to impersonate
+ * @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>;
+/**
+ * Fetch target user data for impersonation
+ * @param requester - The user requesting impersonation
+ * @param targetUserId - The ID of the user to impersonate
+ * @param event - H3 event for context
+ * @returns User data object with sub, email, name, and custom claims
+ * @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>>;
+/**
+ * Generate an impersonated JWT token
+ * @param requester - The user performing impersonation
+ * @param targetUserData - Target user data from database
+ * @param reason - Optional reason for impersonation
+ * @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>;
+/**
+ * Start impersonation session
+ * @param requester - The user requesting impersonation (must be admin)
+ * @param targetUserId - The ID of the user to impersonate
+ * @param reason - Optional reason for impersonation
+ * @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>;
+/**
+ * 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<{
+    accessToken: string;
+    refreshTokenId: string;
+}>;

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

@@ -0,0 +1,259 @@
+import { createError } from "h3";
+import { generateToken } from "./jwt.js";
+import { useRuntimeConfig, useNitroApp } from "#imports";
+import { createLogger } from "./logger.js";
+import { generateAndStoreRefreshToken } from "./refreshToken.js";
+import { useAegisHandler } from "./handler.js";
+const logger = createLogger("Impersonation");
+function checkImpersonationEnabled() {
+  const config = useRuntimeConfig();
+  if (!config.nuxtAegis?.impersonation?.enabled) {
+    throw createError({
+      statusCode: 404,
+      message: "Impersonation feature is not enabled"
+    });
+  }
+}
+function getClientInfo(event) {
+  const headers = event.node.req.headers;
+  const ip = headers["x-forwarded-for"]?.split(",")[0]?.trim() || headers["x-real-ip"] || event.node.req.socket?.remoteAddress;
+  const userAgent = headers["user-agent"];
+  return { ip, userAgent };
+}
+export async function checkImpersonationAllowed(requester, targetUserId, event) {
+  checkImpersonationEnabled();
+  if (requester.impersonation) {
+    throw createError({
+      statusCode: 403,
+      message: "Cannot impersonate while already impersonating another user"
+    });
+  }
+  const handler = useAegisHandler();
+  if (handler?.impersonation?.canImpersonate) {
+    const allowed = await handler.impersonation.canImpersonate(requester, targetUserId, event);
+    if (!allowed) {
+      throw createError({
+        statusCode: 403,
+        message: "Insufficient permissions to impersonate users"
+      });
+    }
+    return;
+  }
+  if (requester.role !== "admin") {
+    throw createError({
+      statusCode: 403,
+      message: "Insufficient permissions to impersonate users"
+    });
+  }
+}
+export async function fetchTargetUser(requester, targetUserId, event) {
+  const handler = useAegisHandler();
+  if (!handler?.impersonation?.fetchTarget) {
+    throw createError({
+      statusCode: 500,
+      message: "Impersonation requires implementing fetchTarget handler."
+    });
+  }
+  try {
+    const targetUser = await handler.impersonation.fetchTarget(targetUserId, event);
+    if (!targetUser) {
+      throw createError({
+        statusCode: 404,
+        message: `Target user not found: ${targetUserId}`
+      });
+    }
+    return targetUser;
+  } catch (error) {
+    const err = error;
+    if (err.statusCode) {
+      throw error;
+    }
+    throw createError({
+      statusCode: 500,
+      message: err.message || "Failed to fetch target user"
+    });
+  }
+}
+export async function generateImpersonatedToken(requester, targetUserData, reason, _event) {
+  const config = useRuntimeConfig();
+  const tokenConfig = config.nuxtAegis?.token;
+  const impersonationConfig = config.nuxtAegis?.impersonation;
+  if (!tokenConfig || !tokenConfig.secret) {
+    throw createError({
+      statusCode: 500,
+      message: "Token configuration is missing"
+    });
+  }
+  const originalClaims = {};
+  const standardTokenFields = ["sub", "id", "email", "name", "picture", "provider", "iat", "exp", "iss", "aud", "impersonation"];
+  for (const [key, value] of Object.entries(requester)) {
+    if (!standardTokenFields.includes(key)) {
+      originalClaims[key] = value;
+    }
+  }
+  const impersonationContext = {
+    originalUserId: requester.sub,
+    originalUserEmail: requester.email,
+    originalUserName: requester.name,
+    impersonatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    reason,
+    originalClaims
+    // Store all custom claims for restoration
+  };
+  const tokenPayload = {
+    sub: targetUserData.sub || targetUserData.id || targetUserData.email,
+    email: targetUserData.email,
+    name: targetUserData.name,
+    picture: targetUserData.picture,
+    provider: targetUserData.provider,
+    impersonation: impersonationContext
+  };
+  const standardFields = ["sub", "id", "email", "name", "picture", "provider", "iat", "exp", "iss", "aud"];
+  const customClaims = {};
+  for (const [key, value] of Object.entries(targetUserData)) {
+    if (!standardFields.includes(key)) {
+      customClaims[key] = value;
+    }
+  }
+  const impersonationExpiration = impersonationConfig?.tokenExpiration || 900;
+  const modifiedTokenConfig = {
+    ...tokenConfig,
+    expiresIn: impersonationExpiration
+  };
+  const accessToken = await generateToken(tokenPayload, modifiedTokenConfig, customClaims);
+  logger.security("Impersonated token generated", {
+    originalUser: requester.sub,
+    targetUser: tokenPayload.sub,
+    expiresIn: impersonationExpiration
+  });
+  return accessToken;
+}
+export async function startImpersonation(requester, targetUserId, reason, event) {
+  await checkImpersonationAllowed(requester, targetUserId, event);
+  const targetUserData = await fetchTargetUser(requester, targetUserId, event);
+  const accessToken = await generateImpersonatedToken(requester, targetUserData, reason, event);
+  const { ip, userAgent } = getClientInfo(event);
+  const targetPayload = {
+    sub: targetUserData.sub || targetUserData.id || targetUserData.email,
+    email: targetUserData.email,
+    name: targetUserData.name
+  };
+  const startPayload = {
+    requester,
+    targetUser: targetPayload,
+    reason,
+    timestamp: /* @__PURE__ */ new Date(),
+    ip: ip || "",
+    userAgent: userAgent || "",
+    event
+  };
+  try {
+    const nitroApp = useNitroApp();
+    await nitroApp.hooks.callHook("nuxt-aegis:impersonate:start", startPayload);
+  } catch (error) {
+    logger.warn("Impersonation start hook failed (non-blocking)", error);
+  }
+  return accessToken;
+}
+export async function endImpersonation(currentToken, event) {
+  checkImpersonationEnabled();
+  if (!currentToken.impersonation) {
+    throw createError({
+      statusCode: 400,
+      message: "Current session is not impersonated"
+    });
+  }
+  const impersonation = currentToken.impersonation;
+  let originalUserData = null;
+  try {
+    originalUserData = await fetchTargetUser(
+      currentToken,
+      // Pass current token as requester (for context)
+      impersonation.originalUserId,
+      event
+    );
+  } catch (error) {
+    const err = error;
+    if (err.statusCode === 404) {
+      logger.warn("Original user not found in database, using stored context", {
+        userId: impersonation.originalUserId
+      });
+    } else {
+      throw error;
+    }
+  }
+  const config = useRuntimeConfig();
+  const tokenConfig = config.nuxtAegis?.token;
+  if (!tokenConfig || !tokenConfig.secret) {
+    throw createError({
+      statusCode: 500,
+      message: "Token configuration is missing"
+    });
+  }
+  const originalPayload = {
+    sub: originalUserData ? originalUserData.sub || originalUserData.id || originalUserData.email : impersonation.originalUserId,
+    email: originalUserData ? originalUserData.email : impersonation.originalUserEmail,
+    name: originalUserData ? originalUserData.name : impersonation.originalUserName,
+    picture: originalUserData?.picture,
+    provider: originalUserData?.provider || impersonation.originalClaims?.provider
+  };
+  const standardFields = ["sub", "id", "email", "name", "picture", "provider", "iat", "exp", "iss", "aud", "impersonation"];
+  const customClaims = {};
+  if (originalUserData) {
+    for (const [key, value] of Object.entries(originalUserData)) {
+      if (!standardFields.includes(key)) {
+        customClaims[key] = value;
+      }
+    }
+  } else if (impersonation.originalClaims) {
+    const filteredClaims = { ...impersonation.originalClaims };
+    delete filteredClaims.provider;
+    Object.assign(customClaims, filteredClaims);
+  }
+  const accessToken = await generateToken(originalPayload, tokenConfig, customClaims);
+  const refreshTokenConfig = config.nuxtAegis?.tokenRefresh;
+  if (!refreshTokenConfig) {
+    throw createError({
+      statusCode: 500,
+      message: "Token refresh configuration is missing"
+    });
+  }
+  const refreshTokenId = await generateAndStoreRefreshToken(
+    originalUserData || { sub: originalPayload.sub, email: originalPayload.email, name: originalPayload.name },
+    // Store user data (fresh or fallback)
+    "restored-session",
+    // Fake provider name for restored sessions
+    refreshTokenConfig,
+    void 0,
+    // No previous token
+    event
+  );
+  if (!refreshTokenId) {
+    throw createError({
+      statusCode: 500,
+      message: "Failed to generate refresh token"
+    });
+  }
+  logger.security("Impersonation ended, original session restored", {
+    originalUser: originalPayload.sub,
+    wasImpersonating: currentToken.sub
+  });
+  const { ip, userAgent } = getClientInfo(event);
+  const endPayload = {
+    restoredUser: originalPayload,
+    // Restored original user
+    impersonatedUser: currentToken,
+    // Current impersonated user
+    timestamp: /* @__PURE__ */ new Date(),
+    ip: ip || "",
+    userAgent: userAgent || "",
+    event
+  };
+  try {
+    const nitroApp = useNitroApp();
+    await nitroApp.hooks.callHook("nuxt-aegis:impersonate:end", endPayload);
+  } catch (error) {
+    logger.warn("Impersonation end hook failed (non-blocking)", error);
+  }
+  return { accessToken, refreshTokenId };
+}

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

@@ -0,0 +1,24 @@
+import type { TokenConfig, TokenPayload } from '../../types/index.js';
+/**
+ * Generate a JWT token with the given payload and custom claims
+ * @param payload - Base token payload containing user information
+ * @param config - Token configuration including secret and expiration
+ * @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>;
+/**
+ * Update an existing JWT token with additional claims
+ * @param token - Existing JWT token to update
+ * @param claims - Additional claims to merge into the token
+ * @param config - Token configuration
+ * @returns New JWT token with updated claims
+ */
+export declare function updateTokenWithClaims(token: string, claims: Record<string, unknown>, config: TokenConfig): Promise<string>;
+/**
+ * Verify and decode a JWT token
+ * @param token - JWT token to verify
+ * @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>;