@payez/next-mvp 3.0.0

package/dist/auth/callbacks/session.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionCallback = sessionCallback;
+const session_store_1 = require("../../lib/session-store");
+// ============================================================================
+// 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
+ */
+async function sessionCallback({ session, token, }) {
+    // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+    const redisSessionId = token?.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);
+            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,
+                    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);
+            if (sessionData) {
+                return buildSessionFromRedis(session, redisSessionId, 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);
+    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, 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) {
+    try {
+        return await (0, session_store_1.getSession)(sessionId);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build complete session from Redis data.
+ * Uses normalized field names from SessionData.
+ */
+function buildSessionFromRedis(session, sessionId, data) {
+    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, error) {
+    return {
+        ...session,
+        user: {
+            id: '',
+            email: '',
+            roles: [],
+            twoFactorSessionVerified: false,
+            requiresTwoFactor: false,
+        },
+        error,
+    };
+}

package/dist/auth/callbacks/signin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 - 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 declare function signInCallback({ user, account, }: {
+    user: User | any;
+    account: Account | null;
+}): Promise<boolean | string>;

package/dist/auth/callbacks/signin.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signInCallback = signInCallback;
+// ============================================================================
+// 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
+ */
+async function signInCallback({ user, account, }) {
+    // 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;
+    if (token?.requiresTwoFactorRedirect) {
+        // Preserve the original callback URL through 2FA flow
+        const originalCallbackUrl = account?.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/dist/auth/events/index.d.ts

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

package/dist/auth/events/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Auth Events - Public Exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSignOut = void 0;
+var signout_1 = require("./signout");
+Object.defineProperty(exports, "handleSignOut", { enumerable: true, get: function () { return signout_1.handleSignOut; } });

package/dist/auth/events/signout.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SignOut Event Handler
+ *
+ * Cleans up Redis session when user signs out.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+import type { JWT } from 'next-auth/jwt';
+/**
+ * Handle user sign out by deleting Redis session.
+ *
+ * @param token - The JWT token containing the session ID
+ */
+export declare function handleSignOut({ token }: {
+    token: JWT | null;
+}): Promise<void>;

package/dist/auth/events/signout.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * SignOut Event Handler
+ *
+ * Cleans up Redis session when user signs out.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSignOut = handleSignOut;
+const session_store_1 = require("../../lib/session-store");
+// ============================================================================
+// SIGNOUT EVENT
+// ============================================================================
+/**
+ * Handle user sign out by deleting Redis session.
+ *
+ * @param token - The JWT token containing the session ID
+ */
+async function handleSignOut({ token }) {
+    // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+    const redisSessionId = token?.sessionToken || token?.redisSessionId;
+    if (redisSessionId) {
+        try {
+            await (0, session_store_1.deleteSession)(redisSessionId);
+        }
+        catch (error) {
+            console.error('[SIGNOUT_EVENT] Failed to delete session:', error);
+        }
+    }
+}

package/dist/auth/providers/credentials.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Credentials Provider
+ *
+ * Handles email/password authentication via PayEz IDP.
+ * Creates Redis session and returns minimal user object to NextAuth.
+ *
+ * FLOW:
+ * 1. User submits email/password
+ * 2. We call IDP /api/ExternalAuth/login
+ * 3. IDP returns tokens if credentials valid
+ * 4. We create Redis session with tokens
+ * 5. Return user object with redisSessionId to NextAuth
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+/**
+ * Create the CredentialsProvider for NextAuth.
+ *
+ * This provider handles email/password login. The authorize function
+ * is called when a user submits the login form.
+ */
+export declare function createCredentialsProvider(): import("next-auth/providers/credentials").CredentialsConfig<{
+    email: {
+        label: string;
+        type: string;
+    };
+    password: {
+        label: string;
+        type: string;
+    };
+}>;

package/dist/auth/providers/credentials.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Credentials Provider
+ *
+ * Handles email/password authentication via PayEz IDP.
+ * Creates Redis session and returns minimal user object to NextAuth.
+ *
+ * FLOW:
+ * 1. User submits email/password
+ * 2. We call IDP /api/ExternalAuth/login
+ * 3. IDP returns tokens if credentials valid
+ * 4. We create Redis session with tokens
+ * 5. Return user object with redisSessionId to NextAuth
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCredentialsProvider = createCredentialsProvider;
+const credentials_1 = __importDefault(require("next-auth/providers/credentials"));
+const session_store_1 = require("../../lib/session-store");
+const idp_client_1 = require("../utils/idp-client");
+const token_utils_1 = require("../utils/token-utils");
+const auth_types_1 = require("../types/auth-types");
+// NOTE: Using any for sessionData until Phase 3 normalizes types
+// ============================================================================
+// CREDENTIALS PROVIDER
+// ============================================================================
+/**
+ * Create the CredentialsProvider for NextAuth.
+ *
+ * This provider handles email/password login. The authorize function
+ * is called when a user submits the login form.
+ */
+function createCredentialsProvider() {
+    return (0, credentials_1.default)({
+        id: 'credentials',
+        name: 'Credentials',
+        credentials: {
+            email: { label: 'Email', type: 'email' },
+            password: { label: 'Password', type: 'password' },
+        },
+        authorize: authorizeCredentials,
+    });
+}
+/**
+ * Authorize user with email/password.
+ *
+ * This is the core authentication function. It:
+ * 1. Validates credentials with IDP
+ * 2. Decodes the returned tokens
+ * 3. Creates a Redis session
+ * 4. Returns user info for NextAuth JWT
+ *
+ * @param credentials - Email and password from login form
+ * @param req - The incoming request (for IP/UA forwarding)
+ * @returns User object for NextAuth, or null/throws on failure
+ */
+async function authorizeCredentials(credentials, req) {
+    // -------------------------------------------------------------------------
+    // Validate Input
+    // -------------------------------------------------------------------------
+    if (!credentials?.email || !credentials?.password) {
+        throw new Error('Email and password required');
+    }
+    const loginCredentials = {
+        email: credentials.email,
+        password: credentials.password,
+    };
+    // Extract client info for audit logging
+    const clientHeaders = extractClientHeaders(req);
+    // -------------------------------------------------------------------------
+    // Call IDP
+    // -------------------------------------------------------------------------
+    const loginResult = await (0, idp_client_1.idpLogin)(loginCredentials, clientHeaders);
+    if (!loginResult.success || !loginResult.result) {
+        // Build structured error for frontend
+        const errorResponse = buildAuthError(loginResult.error);
+        throw new Error(JSON.stringify(errorResponse));
+    }
+    const { access_token, refresh_token, user: idpUser } = loginResult.result;
+    // -------------------------------------------------------------------------
+    // Decode Token
+    // -------------------------------------------------------------------------
+    const decoded = (0, token_utils_1.decodeIdpAccessToken)(access_token);
+    if (!decoded) {
+        throw new Error('Failed to decode token');
+    }
+    // Extract kid from JWT header (CRITICAL: this is different from client_id in payload)
+    const bearerKeyId = (0, token_utils_1.extractKidFromToken)(access_token);
+    if (bearerKeyId) {
+        console.log('[CREDENTIALS] Extracted bearerKeyId (kid) from JWT header:', bearerKeyId);
+    }
+    else {
+        console.warn('[CREDENTIALS] No kid found in JWT header - token may be unsigned or malformed');
+    }
+    // Extract claims from token
+    const email = (0, token_utils_1.extractEmailFromToken)(decoded);
+    const roles = (0, token_utils_1.extractRolesFromToken)(decoded);
+    const amrClaims = (0, token_utils_1.extractAmrFromToken)(decoded);
+    const acrLevel = decoded.acr || '1';
+    const userId = decoded.sub;
+    // Check if 2FA is complete based on ACR level
+    // ACR=1: Provisional token (requires 2FA)
+    // ACR=2: Full authentication (2FA complete)
+    const mfaVerified = acrLevel === '2';
+    // Decode refresh token expiry if available
+    let refreshTokenExpires;
+    try {
+        const refreshDecoded = (0, token_utils_1.decodeIdpAccessToken)(refresh_token);
+        if (refreshDecoded?.exp) {
+            refreshTokenExpires = (0, token_utils_1.expClaimToMs)(refreshDecoded.exp);
+        }
+    }
+    catch {
+        // Ignore - will use default expiry
+    }
+    // -------------------------------------------------------------------------
+    // Create Redis Session
+    // -------------------------------------------------------------------------
+    // Using normalized field names (session-store handles backward compatibility)
+    const sessionData = {
+        userId,
+        email,
+        roles,
+        // IDP tokens (normalized names)
+        idpAccessToken: access_token,
+        idpRefreshToken: refresh_token,
+        idpAccessTokenExpires: (0, token_utils_1.expClaimToMs)(decoded.exp),
+        idpRefreshTokenExpires: refreshTokenExpires,
+        decodedAccessToken: decoded,
+        // Bearer key ID from JWT header (NOT client_id from payload)
+        bearerKeyId,
+        // MFA state (normalized names)
+        mfaVerified,
+        authenticationMethods: amrClaims,
+        authenticationLevel: acrLevel,
+        // MFA timing info from token
+        mfaCompletedAt: decoded.mfa_time ? (0, token_utils_1.expClaimToMs)(decoded.mfa_time) : undefined,
+        mfaExpiresAt: decoded.mfa_expires ? (0, token_utils_1.expClaimToMs)(decoded.mfa_expires) : undefined,
+        mfaValidityHours: decoded.mfa_validity_hours,
+    };
+    // Determine MFA method from IDP user info
+    let mfaMethod;
+    if (idpUser?.isEmailConfirmed) {
+        mfaMethod = 'email';
+    }
+    else if (idpUser?.isSmsConfirmed) {
+        mfaMethod = 'sms';
+    }
+    if (mfaMethod) {
+        sessionData.mfaMethod = mfaMethod;
+    }
+    // Create the Redis session
+    const redisSessionId = await (0, session_store_1.createSession)(sessionData);
+    // -------------------------------------------------------------------------
+    // Return User Object for NextAuth
+    // -------------------------------------------------------------------------
+    // NextAuth requires 'id' field - we use userId from IDP
+    // The redisSessionId is passed through to the JWT callback
+    return {
+        id: userId,
+        email,
+        roles,
+        redisSessionId: (0, auth_types_1.toRedisSessionId)(redisSessionId),
+        mfaRequired: !mfaVerified,
+        mfaMethod,
+    };
+}
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+/**
+ * Extract client headers from request for audit logging.
+ */
+function extractClientHeaders(req) {
+    const headers = {};
+    // Extract client IP
+    const forwardedFor = req?.headers?.['x-forwarded-for'];
+    const realIp = req?.headers?.['x-real-ip'];
+    if (forwardedFor) {
+        const ip = Array.isArray(forwardedFor) ? forwardedFor[0] : forwardedFor.split(',')[0].trim();
+        headers.ip = ip;
+    }
+    else if (realIp) {
+        headers.ip = Array.isArray(realIp) ? realIp[0] : realIp;
+    }
+    // Extract User-Agent
+    const userAgent = req?.headers?.['user-agent'];
+    if (userAgent) {
+        headers.userAgent = Array.isArray(userAgent) ? userAgent[0] : userAgent;
+    }
+    return headers;
+}
+/**
+ * Build structured error response for frontend.
+ *
+ * The frontend expects a specific error structure to display
+ * appropriate messages and handle things like lockout.
+ */
+function buildAuthError(error) {
+    if (!error) {
+        return {
+            success: false,
+            error: {
+                code: 'AUTH_ERROR',
+                message: 'Authentication failed',
+                details: {},
+            },
+        };
+    }
+    return {
+        success: false,
+        error: {
+            code: error.code || 'AUTH_ERROR',
+            message: error.message || 'Authentication failed',
+            details: error.details || {},
+        },
+    };
+}

package/dist/auth/providers/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Auth Providers - Public Exports
+ */
+export * from './credentials';
+export * from './oauth';

package/dist/auth/providers/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Auth Providers - Public Exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./credentials"), exports);
+__exportStar(require("./oauth"), exports);

package/dist/auth/providers/oauth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OAuth Provider Builder
+ *
+ * Dynamically builds NextAuth OAuth providers from IDP configuration.
+ * Supports Google, Apple, Facebook, GitHub, and Microsoft/Azure AD.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+import type { Provider } from 'next-auth/providers/index';
+import type { IDPClientConfig } from '../../lib/idp-client-config';
+/**
+ * Build NextAuth OAuth providers from IDP configuration.
+ *
+ * The IDP returns a list of enabled OAuth providers with their credentials.
+ * This function maps them to NextAuth provider instances.
+ *
+ * @param config - IDP client configuration containing OAuth provider list
+ * @returns Array of NextAuth Provider instances
+ */
+export declare function buildOAuthProviders(config: IDPClientConfig): Provider[];
+/**
+ * Get list of enabled provider names from config.
+ * Useful for logging and debugging.
+ */
+export declare function getEnabledProviderNames(config: IDPClientConfig): string[];