@payez/next-mvp 3.0.0

package/dist/auth/utils/idp-client.js

@@ -0,0 +1,383 @@
+"use strict";
+/**
+ * IDP Client Utilities
+ *
+ * Functions for calling PayEz IDP API endpoints.
+ * Handles login, OAuth callback, token refresh, and 2FA verification.
+ *
+ * URL USAGE:
+ * - IDP_URL: Used for all calls to the PayEz Identity Provider
+ * - INTERNAL_API_URL: NOT used here - that's for calling THIS app's own endpoints
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIdpUrl = getIdpUrl;
+exports.getClientId = getClientId;
+exports.idpLogin = idpLogin;
+exports.idpOAuthCallback = idpOAuthCallback;
+exports.idpRefreshToken = idpRefreshToken;
+exports.idpVerify2FA = idpVerify2FA;
+exports.idpSend2FACode = idpSend2FACode;
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+/**
+ * Get IDP base URL. Throws if not configured.
+ */
+function getIdpUrl() {
+    const url = process.env.IDP_URL;
+    if (!url) {
+        throw new Error('[IDP_CLIENT] FATAL: IDP_URL environment variable is REQUIRED');
+    }
+    return url.replace(/\/$/, ''); // Remove trailing slash
+}
+/**
+ * Get client ID for this application.
+ */
+function getClientId() {
+    const clientId = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_CLIENT_ID;
+    if (!clientId) {
+        throw new Error('[IDP_CLIENT] FATAL: CLIENT_ID environment variable is REQUIRED');
+    }
+    return clientId;
+}
+// ============================================================================
+// LOGIN
+// ============================================================================
+/**
+ * Authenticate user with email/password via IDP.
+ *
+ * @param credentials - User's email and password
+ * @param clientHeaders - Headers to forward (IP, User-Agent for audit)
+ * @returns IDP login response with tokens or error
+ */
+async function idpLogin(credentials, clientHeaders) {
+    const idpUrl = getIdpUrl();
+    const clientId = getClientId();
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-Client-Id': clientId,
+    };
+    // Forward client IP for audit logging
+    if (clientHeaders?.ip) {
+        headers['X-Forwarded-For'] = clientHeaders.ip;
+    }
+    // Forward User-Agent for audit logging
+    if (clientHeaders?.userAgent) {
+        headers['User-Agent'] = clientHeaders.userAgent;
+    }
+    try {
+        const response = await fetch(`${idpUrl}/api/ExternalAuth/login`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                username_or_email: credentials.email,
+                password: credentials.password,
+                client_id: clientId,
+            }),
+        });
+        const data = await response.json();
+        // Unwrap PayEz response envelope if present
+        const responseData = data.data || data;
+        if (!response.ok || !responseData.result || !responseData.success) {
+            return {
+                success: false,
+                error: responseData.error || {
+                    code: `HTTP_${response.status}`,
+                    message: getLoginErrorMessage(response.status, responseData),
+                },
+            };
+        }
+        return {
+            success: true,
+            result: responseData.result,
+        };
+    }
+    catch (error) {
+        console.error('[IDP_CLIENT] Login request failed:', error);
+        return {
+            success: false,
+            error: {
+                code: 'NETWORK_ERROR',
+                message: 'Failed to connect to authentication service',
+            },
+        };
+    }
+}
+/**
+ * Get user-friendly error message for login failures.
+ */
+function getLoginErrorMessage(status, responseData) {
+    // Check for structured error from IDP
+    if (responseData?.error?.message) {
+        return responseData.error.message;
+    }
+    // Fallback to HTTP status-based messages
+    switch (status) {
+        case 401:
+            return 'Invalid email or password. Please try again.';
+        case 403:
+            return 'Account access denied. Please contact support.';
+        case 429:
+            return 'Too many login attempts. Please try again later.';
+        default:
+            if (status >= 500) {
+                return 'Authentication service is temporarily unavailable.';
+            }
+            return 'Authentication failed. Please try again.';
+    }
+}
+// ============================================================================
+// OAUTH CALLBACK
+// ============================================================================
+/**
+ * Register/authenticate OAuth user with IDP.
+ *
+ * Called after OAuth provider (Google, etc.) redirects back.
+ * Creates or retrieves IDP user and returns IDP tokens.
+ *
+ * @param oauthData - Data from OAuth provider
+ * @returns IDP response with tokens and user info
+ */
+async function idpOAuthCallback(oauthData) {
+    const idpUrl = getIdpUrl();
+    const clientId = getClientId();
+    try {
+        const response = await fetch(`${idpUrl}/api/ExternalAuth/oauth-callback`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Client-Id': clientId,
+            },
+            body: JSON.stringify({
+                provider: oauthData.provider,
+                provider_account_id: oauthData.providerAccountId,
+                email: oauthData.email,
+                name: oauthData.name || '',
+                image: oauthData.image || '',
+                access_token: oauthData.accessToken || '',
+                refresh_token: oauthData.refreshToken || '',
+                expires_at: oauthData.expiresAt || 0,
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            console.error('[IDP_CLIENT] OAuth callback failed:', response.status, errorText);
+            return {
+                success: false,
+                error: {
+                    code: `HTTP_${response.status}`,
+                    message: 'OAuth registration failed',
+                },
+            };
+        }
+        const data = await response.json();
+        const responseData = data.data || data;
+        // Normalize snake_case to camelCase
+        return {
+            success: responseData.success !== false,
+            data: responseData.success !== false
+                ? {
+                    accessToken: responseData.accessToken || responseData.access_token,
+                    refreshToken: responseData.refreshToken || responseData.refresh_token,
+                    isNewUser: responseData.isNewUser ?? responseData.is_new_user ?? false,
+                    user: responseData.user
+                        ? {
+                            userId: responseData.user.userId || responseData.user.user_id,
+                            email: responseData.user.email || responseData.user.Email,
+                            fullName: responseData.user.fullName || responseData.user.full_name || responseData.user.name,
+                            roles: responseData.user.roles || [],
+                        }
+                        : undefined,
+                }
+                : undefined,
+            error: responseData.error,
+        };
+    }
+    catch (error) {
+        console.error('[IDP_CLIENT] OAuth callback request failed:', error);
+        return {
+            success: false,
+            error: {
+                code: 'NETWORK_ERROR',
+                message: 'Failed to connect to authentication service',
+            },
+        };
+    }
+}
+// ============================================================================
+// TOKEN REFRESH
+// ============================================================================
+/**
+ * Refresh an expired access token using the refresh token.
+ *
+ * @param refreshToken - The refresh token from previous login
+ * @param mfaContext - MFA context to preserve across refresh
+ * @returns New tokens or error
+ */
+async function idpRefreshToken(refreshToken, mfaContext) {
+    const idpUrl = getIdpUrl();
+    const clientId = getClientId();
+    const requestBody = {
+        refresh_token: refreshToken,
+    };
+    // Include MFA context so new token preserves authentication level
+    if (mfaContext) {
+        if (mfaContext.amr) {
+            requestBody.amr = mfaContext.amr;
+        }
+        if (mfaContext.acr) {
+            requestBody.acr = mfaContext.acr;
+        }
+        if (mfaContext.twoFactorVerified) {
+            requestBody.two_factor_verified = true;
+        }
+        if (mfaContext.twoFactorMethod) {
+            requestBody.two_factor_method = mfaContext.twoFactorMethod;
+        }
+        if (mfaContext.twoFactorCompletedAt) {
+            requestBody.two_factor_completed_at = new Date(mfaContext.twoFactorCompletedAt).toISOString();
+        }
+    }
+    try {
+        const response = await fetch(`${idpUrl}/api/ExternalAuth/refresh`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Client-Id': clientId,
+            },
+            body: JSON.stringify(requestBody),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            console.error('[IDP_CLIENT] Token refresh failed:', response.status, errorText);
+            return {
+                success: false,
+                error: {
+                    code: `HTTP_${response.status}`,
+                    message: response.status === 401 ? 'Refresh token expired' : 'Token refresh failed',
+                },
+            };
+        }
+        const data = await response.json();
+        if (data.success === false) {
+            return {
+                success: false,
+                error: data.error || { code: 'REFRESH_FAILED', message: 'Token refresh failed' },
+            };
+        }
+        const tokenData = data.data || data;
+        return {
+            success: true,
+            data: {
+                access_token: tokenData.access_token,
+                refresh_token: tokenData.refresh_token,
+                expires_in: tokenData.expires_in || 3600,
+            },
+        };
+    }
+    catch (error) {
+        console.error('[IDP_CLIENT] Token refresh request failed:', error);
+        return {
+            success: false,
+            error: {
+                code: 'NETWORK_ERROR',
+                message: 'Failed to connect to authentication service',
+            },
+        };
+    }
+}
+// ============================================================================
+// 2FA VERIFICATION
+// ============================================================================
+/**
+ * Verify 2FA code with IDP.
+ *
+ * @param sessionToken - Redis session ID
+ * @param code - The 2FA code entered by user
+ * @param method - The 2FA method ('email' | 'sms' | 'totp')
+ * @returns Success status and updated tokens
+ */
+async function idpVerify2FA(accessToken, code, method) {
+    const idpUrl = getIdpUrl();
+    const clientId = getClientId();
+    try {
+        const response = await fetch(`${idpUrl}/api/ExternalAuth/verify-2fa`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Client-Id': clientId,
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({
+                code,
+                method,
+            }),
+        });
+        if (!response.ok) {
+            const data = await response.json().catch(() => ({}));
+            return {
+                success: false,
+                error: data.error || {
+                    code: `HTTP_${response.status}`,
+                    message: response.status === 401 ? 'Invalid code' : '2FA verification failed',
+                },
+            };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        console.error('[IDP_CLIENT] 2FA verification failed:', error);
+        return {
+            success: false,
+            error: {
+                code: 'NETWORK_ERROR',
+                message: 'Failed to connect to authentication service',
+            },
+        };
+    }
+}
+/**
+ * Request a new 2FA code to be sent.
+ *
+ * @param accessToken - User's access token
+ * @param method - How to send the code ('email' | 'sms')
+ */
+async function idpSend2FACode(accessToken, method) {
+    const idpUrl = getIdpUrl();
+    const clientId = getClientId();
+    try {
+        const response = await fetch(`${idpUrl}/api/ExternalAuth/send-2fa-code`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Client-Id': clientId,
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({ method }),
+        });
+        if (!response.ok) {
+            const data = await response.json().catch(() => ({}));
+            return {
+                success: false,
+                error: data.error || {
+                    code: `HTTP_${response.status}`,
+                    message: 'Failed to send 2FA code',
+                },
+            };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        console.error('[IDP_CLIENT] Send 2FA code failed:', error);
+        return {
+            success: false,
+            error: {
+                code: 'NETWORK_ERROR',
+                message: 'Failed to connect to authentication service',
+            },
+        };
+    }
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Auth Utilities - Public Exports
+ */
+export * from './token-utils';
+export * from './idp-client';

package/dist/auth/utils/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Auth Utilities - 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("./token-utils"), exports);
+__exportStar(require("./idp-client"), exports);

package/dist/auth/utils/token-utils.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Token Utilities
+ *
+ * JWT decoding and expiry checking utilities.
+ * Extracted from auth-options.ts for clarity.
+ *
+ * @version 1.0.0
+ * @since auth-refactor-2026-01
+ */
+import { JwtHeader } from '../../lib/jwt-decode';
+import type { DecodedIdpAccessToken } from '../types/auth-types';
+export { decodeJwtHeader, extractKidFromToken, type JwtHeader } from '../../lib/jwt-decode';
+/**
+ * Decode an IDP access token and extract claims.
+ *
+ * @param token - The JWT access token from IDP
+ * @returns Decoded token claims, or null if decode fails
+ */
+export declare function decodeIdpAccessToken(token: string): DecodedIdpAccessToken | null;
+/**
+ * Decode both JWT header and payload from an IDP access token.
+ * Returns the signing key ID (kid) along with payload claims.
+ *
+ * @param token - The JWT access token from IDP
+ * @returns Object with header (including kid) and payload, or null if decode fails
+ */
+export declare function decodeIdpAccessTokenFull(token: string): {
+    header: JwtHeader;
+    payload: DecodedIdpAccessToken;
+    bearerKeyId: string | undefined;
+} | null;
+/**
+ * Extract user email from decoded token.
+ * Handles multiple possible claim names used by IDP.
+ */
+export declare function extractEmailFromToken(decoded: DecodedIdpAccessToken): string;
+/**
+ * Extract roles from decoded token.
+ * Handles both 'role' and 'roles' claims, and both string and array formats.
+ */
+export declare function extractRolesFromToken(decoded: DecodedIdpAccessToken): string[];
+/**
+ * Extract AMR (Authentication Methods References) from decoded token.
+ */
+export declare function extractAmrFromToken(decoded: DecodedIdpAccessToken): string[];
+/**
+ * Check if a token expiry timestamp indicates the token needs refresh.
+ *
+ * @param expiresAt - Token expiry timestamp (Unix milliseconds)
+ * @param bufferMs - How early to trigger refresh (default 5 minutes)
+ * @returns true if token is expired or will expire within buffer period
+ */
+export declare function tokenNeedsRefresh(expiresAt: number | undefined, bufferMs?: number): boolean;
+/**
+ * Check if a token is completely expired (past its exp time).
+ *
+ * @param expiresAt - Token expiry timestamp (Unix milliseconds)
+ * @returns true if token is expired
+ */
+export declare function tokenIsExpired(expiresAt: number | undefined): boolean;
+/**
+ * Calculate milliseconds until token expires.
+ *
+ * @param expiresAt - Token expiry timestamp (Unix milliseconds)
+ * @returns Milliseconds until expiry, or 0 if already expired
+ */
+export declare function msUntilExpiry(expiresAt: number | undefined): number;
+/**
+ * Convert Unix seconds (from JWT exp claim) to milliseconds.
+ */
+export declare function expClaimToMs(exp: number): number;
+/**
+ * Validate that an access token's actual JWT exp matches what we have cached.
+ * This catches cases where the token was refreshed but cache wasn't updated.
+ *
+ * @param accessToken - The JWT access token
+ * @param cachedExpiresAt - What we think the expiry is (Unix ms)
+ * @returns Object with validation result and actual expiry
+ */
+export declare function validateTokenExpiry(accessToken: string, cachedExpiresAt: number | undefined): {
+    valid: boolean;
+    actualExpiresAt: number | null;
+    mismatch: boolean;
+};