@payez/next-mvp 3.0.0

package/src/auth/callbacks/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Auth Callbacks - Public Exports
+ */
+
+export { jwtCallback } from './jwt';
+export { sessionCallback } from './session';
+export { signInCallback } from './signin';

package/src/auth/callbacks/jwt.ts

@@ -0,0 +1,382 @@
+/**
+ * JWT Callback
+ *
+ * Minimal token strategy - only store redisSessionId in JWT.
+ * All session data lives in Redis, not in the browser cookie.
+ *
+ * HANDLES:
+ * - Initial sign-in (credentials): Store redisSessionId from authorize()
+ * - Initial sign-in (OAuth): Register with IDP, create session, store redisSessionId
+ * - Subsequent requests: Validate session exists, return token
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+
+import type { JWT } from 'next-auth/jwt';
+import type { User, Account } from 'next-auth';
+import { createHmac } from 'crypto';
+import { createSession, getSession } from '../../lib/session-store';
+import { getIDPClientConfig } from '../../lib/idp-client-config';
+import { idpOAuthCallback } from '../utils/idp-client';
+import {
+  decodeIdpAccessToken,
+  extractAmrFromToken,
+  expClaimToMs,
+  extractKidFromToken,
+} from '../utils/token-utils';
+// NOTE: Using any for sessionData until Phase 3 normalizes types
+
+// ============================================================================
+// VIBE ROLE FETCHING
+// ============================================================================
+
+/**
+ * Generate HMAC signature for Vibe API request.
+ */
+function generateVibeSignature(
+  endpoint: string,
+  clientId: string,
+  timestamp: number
+): string {
+  const signingKey = process.env.VIBE_SIGNING_KEY;
+  if (!signingKey) {
+    return '';
+  }
+
+  const stringToSign = `${timestamp}|GET|${endpoint}|${clientId}`;
+  return createHmac('sha256', Buffer.from(signingKey, 'base64'))
+    .update(stringToSign)
+    .digest('base64');
+}
+
+/**
+ * Fetch user's roles from Vibe API.
+ * Returns empty array on failure (non-blocking).
+ * Uses HMAC signature for authentication when signing key is configured.
+ */
+async function fetchVibeRoles(userId: string, clientId: string): Promise<string[]> {
+  const vibeApiUrl = process.env.VIBE_API_URL;
+  if (!vibeApiUrl) {
+    return [];
+  }
+
+  const endpoint = `/api/v1/users/${userId}/roles`;
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signature = generateVibeSignature(endpoint, clientId, timestamp);
+
+  // Build headers with optional signature
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    'X-Client-Id': clientId,
+    'X-Vibe-Client-Id': clientId,
+  };
+
+  if (signature) {
+    headers['X-Vibe-Timestamp'] = String(timestamp);
+    headers['X-Vibe-Signature'] = signature;
+  }
+
+  try {
+    const response = await fetch(
+      `${vibeApiUrl}${endpoint}`,
+      {
+        method: 'GET',
+        headers,
+        // 2 second timeout
+        signal: AbortSignal.timeout(2000),
+      }
+    );
+
+    if (!response.ok) {
+      console.warn('[JWT_CALLBACK] Failed to fetch Vibe roles:', response.status);
+      return [];
+    }
+
+    const data = await response.json();
+    const roles = data.roles?.map((r: any) => r.role_name || r) || [];
+    console.log('[JWT_CALLBACK] Fetched Vibe roles:', roles);
+    return roles;
+  } catch (error) {
+    console.warn('[JWT_CALLBACK] Error fetching Vibe roles (continuing with IDP roles only):', error);
+    return [];
+  }
+}
+
+/**
+ * Merge IDP roles with Vibe roles, deduplicating.
+ */
+function mergeRoles(idpRoles: string[], vibeRoles: string[]): string[] {
+  return [...new Set([...idpRoles, ...vibeRoles])];
+}
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+interface JwtCallbackParams {
+  token: JWT;
+  user?: User | any;
+  account?: Account | null;
+  trigger?: 'signIn' | 'signUp' | 'update';
+}
+
+interface JwtCallbackResult extends JWT {
+  /** Redis session ID - the key to look up session data */
+  redisSessionId?: string;
+  /** User ID from IDP */
+  sub: string;
+  /** Error code if session validation failed */
+  error?: string;
+  /** Flag for OAuth users who need immediate 2FA redirect */
+  requiresTwoFactorRedirect?: boolean;
+}
+
+// ============================================================================
+// JWT CALLBACK
+// ============================================================================
+
+/**
+ * JWT callback - builds the NextAuth JWT token.
+ *
+ * MINIMAL TOKEN STRATEGY:
+ * - Only store redisSessionId (key to Redis session)
+ * - All tokens and user data live in Redis
+ * - Browser cookie stays small and secure
+ *
+ * @param params - JWT callback parameters from NextAuth
+ * @returns JWT payload to store in browser cookie
+ */
+export async function jwtCallback({
+  token,
+  user,
+  account,
+  trigger,
+}: JwtCallbackParams): Promise<JwtCallbackResult> {
+  console.log('[JWT_CALLBACK] Called with:', {
+    trigger,
+    hasAccount: !!account,
+    provider: account?.provider,
+    hasUser: !!user,
+    userEmail: user?.email,
+    existingRedisSessionId: token?.redisSessionId ? 'yes' : 'no',
+  });
+
+  // -------------------------------------------------------------------------
+  // OAuth Sign-In: Register with IDP and create session
+  // -------------------------------------------------------------------------
+
+  if (account && account.provider !== 'credentials') {
+    console.log('[JWT_CALLBACK] Handling OAuth sign-in for provider:', account.provider);
+    return handleOAuthSignIn(token, user, account);
+  }
+
+  // -------------------------------------------------------------------------
+  // Credentials Sign-In: Session already created in authorize()
+  // -------------------------------------------------------------------------
+
+  if (user && (user as any).redisSessionId) {
+    // Credentials authorize() returns redisSessionId
+    const redisSessionId = (user as any).redisSessionId;
+
+    return {
+      ...token,
+      redisSessionId,
+            sub: user.id || token.sub || 'unknown',
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Subsequent Requests: Validate session exists
+  // -------------------------------------------------------------------------
+
+  const redisSessionId = (user as any)?.redisSessionId || token?.redisSessionId || token?.redisSessionId;
+
+  if (!redisSessionId) {
+    return { ...token, error: 'NoSession', sub: token.sub || 'unknown' };
+  }
+
+  // Validate session still exists in Redis
+  try {
+    const sessionData = await getSession(redisSessionId as string);
+
+    if (!sessionData) {
+      // Session expired or deleted
+      return { ...token, error: 'SessionNotFound', sub: token.sub || 'unknown' };
+    }
+
+    // Check if refresh token has expired (session should be terminated)
+    if (sessionData.idpRefreshTokenExpires && Date.now() >= sessionData.idpRefreshTokenExpires) {
+      return { ...token, error: 'RefreshTokenExpired', sub: token.sub || 'unknown' };
+    }
+
+    // Check if MFA has expired (requires step-up authentication)
+    if (sessionData.mfaExpiresAt && Date.now() > sessionData.mfaExpiresAt) {
+      return {
+        ...token,
+        redisSessionId,
+                sub: sessionData.userId,
+        error: 'MfaExpired',
+      };
+    }
+  } catch (error) {
+    console.error('[JWT_CALLBACK] Session validation error:', error);
+    return { ...token, error: 'SessionError', sub: token.sub || 'unknown' };
+  }
+
+  // Session is valid - return minimal token
+  return {
+    ...token,
+    redisSessionId,
+        sub: token.sub || 'unknown',
+  };
+}
+
+// ============================================================================
+// OAUTH SIGN-IN HANDLER
+// ============================================================================
+
+/**
+ * Handle OAuth sign-in by registering with IDP and creating session.
+ */
+async function handleOAuthSignIn(
+  token: JWT,
+  user: User | any,
+  account: Account
+): Promise<JwtCallbackResult> {
+  console.log('[JWT_CALLBACK] handleOAuthSignIn starting for:', {
+    provider: account.provider,
+    email: user?.email,
+    providerAccountId: account.providerAccountId,
+  });
+
+  try {
+  // Call IDP to register/authenticate OAuth user
+  const idpResult = await idpOAuthCallback({
+    provider: account.provider,
+    providerAccountId: account.providerAccountId,
+    email: user?.email || '',
+    name: user?.name || '',
+    image: user?.image || '',
+    accessToken: account.access_token,
+    refreshToken: account.refresh_token,
+    expiresAt: account.expires_at,
+  });
+
+  // Build session data using normalized field names
+  let sessionData: any;
+  let mfaVerified = false;
+
+  if (idpResult.success && idpResult.data?.accessToken) {
+    // IDP integration succeeded - we have IDP tokens
+    const decoded = decodeIdpAccessToken(idpResult.data.accessToken);
+    const amrClaims = decoded ? extractAmrFromToken(decoded) : [];
+    const acrLevel = decoded?.acr || '1';
+
+    // Extract kid from JWT header (CRITICAL: different from client_id in payload)
+    const bearerKeyId = extractKidFromToken(idpResult.data.accessToken);
+    if (bearerKeyId) {
+      console.log('[JWT_CALLBACK] Extracted bearerKeyId (kid) from JWT header:', bearerKeyId);
+    } else {
+      console.warn('[JWT_CALLBACK] No kid found in JWT header');
+    }
+
+    // Check if MFA is required for this client
+    try {
+      const clientConfig = await getIDPClientConfig();
+      const require2FA = clientConfig?.authSettings?.require2FA ?? true;
+      mfaVerified = !require2FA; // If MFA not required, mark as verified
+    } catch {
+      // Default to requiring MFA if config unavailable
+      mfaVerified = false;
+    }
+
+    sessionData = {
+      userId: idpResult.data.user?.userId?.toString() || account.providerAccountId,
+      email: idpResult.data.user?.email || user?.email || '',
+      name: idpResult.data.user?.fullName || user?.name || '',
+      roles: idpResult.data.user?.roles || [],
+      // IDP tokens (normalized names)
+      idpAccessToken: idpResult.data.accessToken,
+      idpRefreshToken: idpResult.data.refreshToken,
+      idpAccessTokenExpires: decoded?.exp ? expClaimToMs(decoded.exp) : Date.now() + 3600000,
+      decodedAccessToken: decoded || undefined,
+      // Bearer key ID from JWT header (NOT client_id from payload)
+      bearerKeyId,
+      // MFA state (normalized names)
+      mfaVerified,
+      authenticationMethods: amrClaims,
+      authenticationLevel: acrLevel,
+      // OAuth provider info (normalized names)
+      oauthProvider: account.provider,
+      oauthProviderToken: account.access_token,
+      oauthProviderRefreshToken: account.refresh_token,
+      // Multi-tenant info
+      idpClientId: decoded?.client_id,
+      merchantId: decoded?.merchant_id,
+    };
+  } else {
+    // IDP integration failed - create OAuth-only session
+    // This allows OAuth login to work even if IDP is unavailable
+    mfaVerified = true; // OAuth IS multi-factor (Google/Microsoft handle MFA)
+    sessionData = {
+      userId: account.providerAccountId,
+      email: user?.email || '',
+      name: user?.name || '',
+      roles: [],
+      mfaVerified: true, // OAuth IS multi-factor
+      oauthProvider: account.provider,
+      oauthProviderToken: account.access_token,
+      oauthProviderRefreshToken: account.refresh_token,
+      idpAccessTokenExpires: account.expires_at
+        ? account.expires_at * 1000
+        : Date.now() + 3600000,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // ROLE MERGING: Fetch Vibe roles and merge with IDP roles
+  // -------------------------------------------------------------------------
+  const clientId = sessionData.idpClientId || process.env.IDP_CLIENT_ID || '';
+  if (clientId && sessionData.userId) {
+    const vibeRoles = await fetchVibeRoles(sessionData.userId, clientId);
+    // SECURITY: Filter out protected IDP-level role prefixes to prevent injection
+    const safeVibeRoles = vibeRoles.filter(r => !r.startsWith('payez_'));
+    const idpRoles = sessionData.roles || [];
+    sessionData.roles = mergeRoles(idpRoles, safeVibeRoles);
+    console.log('[JWT_CALLBACK] Merged roles:', {
+      idpRoles,
+      vibeRoles,
+      safeVibeRoles,
+      merged: sessionData.roles,
+    });
+  }
+
+  // Create Redis session
+  console.log('[JWT_CALLBACK] Creating Redis session for:', {
+    userId: sessionData.userId,
+    email: sessionData.email,
+    mfaVerified: sessionData.mfaVerified,
+    roles: sessionData.roles,
+  });
+
+  const redisSessionId = await createSession(sessionData);
+
+  console.log('[JWT_CALLBACK] Redis session created:', {
+    redisSessionId: redisSessionId ? redisSessionId.substring(0, 8) + '...' : 'NONE',
+  });
+
+  // Check if immediate MFA redirect is needed
+  const needsImmediateTwoFactor = !mfaVerified;
+
+  return {
+    ...token,
+    redisSessionId,
+        sub: sessionData.userId,
+    requiresTwoFactorRedirect: needsImmediateTwoFactor,
+  };
+  } catch (error) {
+    console.error('[JWT_CALLBACK] handleOAuthSignIn FAILED:', error);
+    return { ...token, error: 'OAuthSignInFailed', sub: token.sub || 'unknown' };
+  }
+}

package/src/auth/callbacks/session.ts

@@ -0,0 +1,243 @@
+/**
+ * Session Callback
+ *
+ * Builds the NextAuth session from Redis session data.
+ * The JWT only contains redisSessionId - all user data comes from Redis.
+ *
+ * FLOW:
+ * 1. Extract redisSessionId from JWT token
+ * 2. Fetch session data from Redis
+ * 3. Build NextAuth session with user info
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+
+import type { Session } from 'next-auth';
+import type { JWT } from 'next-auth/jwt';
+import { getSession } from '../../lib/session-store';
+// NOTE: Using SessionData from models until Phase 3 normalizes names
+import type { SessionData } from '../../models/SessionModel';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+interface SessionCallbackParams {
+  session: Session;
+  token: JWT & {
+    /** Redis session ID - the key to look up session data */
+    redisSessionId?: string;
+    error?: string;
+  };
+}
+
+interface AppSessionUser {
+  id: string;
+  email: string;
+  name?: string;
+  roles: string[];
+  // MFA status
+  twoFactorSessionVerified: boolean;
+  requiresTwoFactor: boolean;
+  // MFA claims from IDP token
+  authenticationMethods?: string[];
+  authenticationLevel?: string;
+  mfaCompletedAt?: number;
+  mfaExpiresAt?: number;
+  mfaValidityHours?: number;
+  // OAuth provider info
+  oauthProvider?: string;
+  // Multi-tenant IDP info
+  idpClientId?: string;
+  merchantId?: string;
+  // JWT signing key (from header, NOT client_id from payload)
+  bearerKeyId?: string;
+}
+
+interface AppSession extends Omit<Session, 'user'> {
+  user: AppSessionUser;
+  sessionToken?: string;
+  accessToken?: string;
+  refreshToken?: string;
+  accessTokenExpires?: number;
+  error?: string;
+}
+
+// ============================================================================
+// SESSION CALLBACK
+// ============================================================================
+
+/**
+ * Session callback - builds NextAuth session from Redis.
+ *
+ * This callback is called whenever getSession() or useSession() is used.
+ * It fetches the full session from Redis and exposes it to the client.
+ *
+ * @param params - Session callback parameters from NextAuth
+ * @returns AppSession with user data from Redis
+ */
+export async function sessionCallback({
+  session,
+  token,
+}: SessionCallbackParams): Promise<AppSession> {
+  // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+  const redisSessionId = (token as any)?.sessionToken || token?.redisSessionId;
+
+  console.log('[SESSION_CALLBACK] Entry:', {
+    hasToken: !!token,
+    redisSessionId: redisSessionId || 'MISSING',
+    tokenError: token?.error || 'none',
+    tokenKeys: token ? Object.keys(token) : [],
+  });
+
+  // -------------------------------------------------------------------------
+  // Handle Token Errors
+  // -------------------------------------------------------------------------
+
+  if (token.error) {
+    console.log('[SESSION_CALLBACK] Token has error:', token.error);
+    // Special case: MFA expired - return partial session for step-up flow
+    if (token.error === 'MfaExpired' && redisSessionId) {
+      const sessionData = await safeGetSession(redisSessionId as string);
+      if (sessionData) {
+        return {
+          ...session,
+          user: {
+            id: sessionData.userId,
+            email: sessionData.email,
+            name: sessionData.name,
+            roles: sessionData.roles || [],
+            twoFactorSessionVerified: false,
+            requiresTwoFactor: true,
+            authenticationMethods: sessionData.authenticationMethods,
+            authenticationLevel: sessionData.authenticationLevel,
+            mfaExpiresAt: sessionData.mfaExpiresAt,
+          },
+          sessionToken: redisSessionId as string,
+          accessToken: sessionData.idpAccessToken,
+          refreshToken: sessionData.idpRefreshToken,
+          error: 'MfaExpired',
+        };
+      }
+    }
+
+    // For other errors, try to recover session data if possible
+    if (redisSessionId) {
+      const sessionData = await safeGetSession(redisSessionId as string);
+      if (sessionData) {
+        return buildSessionFromRedis(session, redisSessionId as string, sessionData);
+      }
+    }
+
+    // No recovery possible - return error session
+    return buildErrorSession(session, token.error);
+  }
+
+  // -------------------------------------------------------------------------
+  // Validate Session Token
+  // -------------------------------------------------------------------------
+
+  if (!redisSessionId) {
+    console.log('[SESSION_CALLBACK] No redisSessionId - returning error session');
+    return buildErrorSession(session, 'NoSessionToken');
+  }
+
+  // -------------------------------------------------------------------------
+  // Fetch Session from Redis
+  // -------------------------------------------------------------------------
+
+  const sessionData = await safeGetSession(redisSessionId as string);
+
+  if (!sessionData) {
+    console.log('[SESSION_CALLBACK] Redis session not found for:', redisSessionId);
+    return buildErrorSession(session, 'SessionNotFound');
+  }
+
+  console.log('[SESSION_CALLBACK] Redis session found:', {
+    userId: sessionData.userId,
+    email: sessionData.email,
+    roles: sessionData.roles,
+    hasAccessToken: !!sessionData.idpAccessToken,
+  });
+
+  const result = buildSessionFromRedis(session, redisSessionId as string, sessionData);
+  console.log('[SESSION_CALLBACK] Returning:', {
+    userId: result.user.id,
+    roles: result.user.roles,
+    hasAccessToken: !!result.accessToken,
+  });
+  return result;
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Safely fetch session from Redis, returning null on error.
+ */
+async function safeGetSession(
+  sessionId: string
+): Promise<SessionData | null> {
+  try {
+    return await getSession(sessionId);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build complete session from Redis data.
+ * Uses normalized field names from SessionData.
+ */
+function buildSessionFromRedis(
+  session: Session,
+  sessionId: string,
+  data: SessionData
+): AppSession {
+  return {
+    ...session,
+    user: {
+      id: data.userId,
+      email: data.email,
+      name: data.name,
+      roles: data.roles || [],
+      // MFA state (normalized field name)
+      twoFactorSessionVerified: data.mfaVerified,
+      requiresTwoFactor: !data.mfaVerified,
+      authenticationMethods: data.authenticationMethods,
+      authenticationLevel: data.authenticationLevel,
+      mfaCompletedAt: data.mfaCompletedAt,
+      mfaExpiresAt: data.mfaExpiresAt,
+      mfaValidityHours: data.mfaValidityHours,
+      oauthProvider: data.oauthProvider,
+      idpClientId: data.idpClientId,
+      merchantId: data.merchantId,
+      // Bearer key ID from JWT header (may be undefined for old sessions)
+      bearerKeyId: data.bearerKeyId,
+    },
+    sessionToken: sessionId,
+    // IDP tokens (normalized field names)
+    accessToken: data.idpAccessToken,
+    refreshToken: data.idpRefreshToken,
+    accessTokenExpires: data.idpAccessTokenExpires,
+  };
+}
+
+/**
+ * Build error session with empty user.
+ */
+function buildErrorSession(session: Session, error: string): AppSession {
+  return {
+    ...session,
+    user: {
+      id: '',
+      email: '',
+      roles: [],
+      twoFactorSessionVerified: false,
+      requiresTwoFactor: false,
+    },
+    error,
+  };
+}

package/src/auth/callbacks/signin.ts

@@ -0,0 +1,56 @@
+/**
+ * SignIn Callback
+ *
+ * Handles post-authentication actions like 2FA redirect.
+ * Called after credentials or OAuth authentication succeeds.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+
+import type { User, Account } from 'next-auth';
+
+// ============================================================================
+// SIGNIN CALLBACK
+// ============================================================================
+
+/**
+ * SignIn callback - handle 2FA redirect for OAuth users.
+ *
+ * When require2FA is true for the client, OAuth users need to be
+ * redirected to the verify-code page immediately after OAuth login.
+ *
+ * @param params - SignIn callback parameters from NextAuth
+ * @returns true to allow sign-in, or a URL string to redirect
+ */
+export async function signInCallback({
+  user,
+  account,
+}: {
+  user: User | any;
+  account: Account | null;
+}): Promise<boolean | string> {
+  // Only handle OAuth providers (credentials flow handles 2FA separately)
+  if (!account?.provider || account.provider === 'credentials') {
+    return true;
+  }
+
+  // Check if OAuth user needs 2FA redirect
+  const token = user as any;
+  if (token?.requiresTwoFactorRedirect) {
+    // Preserve the original callback URL through 2FA flow
+    const originalCallbackUrl = (account as any)?.callbackUrl || '/';
+
+    // Don't redirect back to auth pages after 2FA
+    const safeCallbackUrl = originalCallbackUrl.startsWith('/account-auth/')
+      ? '/'
+      : originalCallbackUrl;
+
+    const encodedCallback = encodeURIComponent(safeCallbackUrl);
+
+    // Return redirect URL - NextAuth will redirect here instead of completing sign-in
+    return `/account-auth/verify-code?callbackUrl=${encodedCallback}`;
+  }
+
+  return true;
+}

package/src/auth/events/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Auth Events - Public Exports
+ */
+
+export { handleSignOut } from './signout';