@payez/next-mvp 3.0.0

package/src/auth/utils/idp-client.ts

@@ -0,0 +1,444 @@
+/**
+ * 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
+ */
+
+import type {
+  IdpLoginResponse,
+  IdpOAuthCallbackResponse,
+  IdpRefreshResponse,
+  LoginCredentials,
+} from '../types/auth-types';
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+/**
+ * Get IDP base URL. Throws if not configured.
+ */
+export function getIdpUrl(): string {
+  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.
+ */
+export function getClientId(): string {
+  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
+ */
+export async function idpLogin(
+  credentials: LoginCredentials,
+  clientHeaders?: { ip?: string; userAgent?: string }
+): Promise<IdpLoginResponse> {
+  const idpUrl = getIdpUrl();
+  const clientId = getClientId();
+
+  const headers: Record<string, string> = {
+    '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: number, responseData: any): string {
+  // 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
+ */
+export async function idpOAuthCallback(oauthData: {
+  provider: string;
+  providerAccountId: string;
+  email: string;
+  name?: string;
+  image?: string;
+  accessToken?: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}): Promise<IdpOAuthCallbackResponse> {
+  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
+ */
+export async function idpRefreshToken(
+  refreshToken: string,
+  mfaContext?: {
+    amr?: string[];
+    acr?: string;
+    twoFactorVerified?: boolean;
+    twoFactorMethod?: string;
+    twoFactorCompletedAt?: number;
+  }
+): Promise<IdpRefreshResponse> {
+  const idpUrl = getIdpUrl();
+  const clientId = getClientId();
+
+  const requestBody: Record<string, any> = {
+    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
+ */
+export async function idpVerify2FA(
+  accessToken: string,
+  code: string,
+  method: 'email' | 'sms' | 'totp'
+): Promise<{ success: boolean; error?: { code: string; message: string } }> {
+  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')
+ */
+export async function idpSend2FACode(
+  accessToken: string,
+  method: 'email' | 'sms'
+): Promise<{ success: boolean; error?: { code: string; message: string } }> {
+  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/src/auth/utils/index.ts

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

package/src/auth/utils/token-utils.ts

@@ -0,0 +1,244 @@
+/**
+ * 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 { jwtDecode, decodeJwtHeader, extractKidFromToken, JwtHeader } from '../../lib/jwt-decode';
+import type { DecodedIdpAccessToken } from '../types/auth-types';
+
+// Re-export header utilities for consumers
+export { decodeJwtHeader, extractKidFromToken, type JwtHeader } from '../../lib/jwt-decode';
+
+// ============================================================================
+// TOKEN DECODING
+// ============================================================================
+
+/**
+ * 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 function decodeIdpAccessToken(token: string): DecodedIdpAccessToken | null {
+  try {
+    return jwtDecode<DecodedIdpAccessToken>(token);
+  } catch (error) {
+    console.error('[TOKEN_UTILS] Failed to decode access token:', error);
+    return 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 function decodeIdpAccessTokenFull(token: string): {
+  header: JwtHeader;
+  payload: DecodedIdpAccessToken;
+  bearerKeyId: string | undefined;
+} | null {
+  try {
+    const header = decodeJwtHeader(token);
+    const payload = jwtDecode<DecodedIdpAccessToken>(token);
+
+    if (!header || !payload) {
+      return null;
+    }
+
+    return {
+      header,
+      payload,
+      bearerKeyId: header.kid,
+    };
+  } catch (error) {
+    console.error('[TOKEN_UTILS] Failed to decode access token (full):', error);
+    return null;
+  }
+}
+
+/**
+ * Extract user email from decoded token.
+ * Handles multiple possible claim names used by IDP.
+ */
+export function extractEmailFromToken(decoded: DecodedIdpAccessToken): string {
+  return (
+    decoded.email ||
+    decoded['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'] ||
+    ''
+  );
+}
+
+/**
+ * Extract roles from decoded token.
+ * Handles both 'role' and 'roles' claims, and both string and array formats.
+ */
+export function extractRolesFromToken(decoded: DecodedIdpAccessToken): string[] {
+  const rolesClaim = decoded.role || decoded.roles;
+
+  if (!rolesClaim) {
+    return [];
+  }
+
+  if (Array.isArray(rolesClaim)) {
+    return rolesClaim;
+  }
+
+  if (typeof rolesClaim === 'string') {
+    // Could be a single role or JSON array string
+    try {
+      const parsed = JSON.parse(rolesClaim);
+      return Array.isArray(parsed) ? parsed : [rolesClaim];
+    } catch {
+      return [rolesClaim];
+    }
+  }
+
+  return [];
+}
+
+/**
+ * Extract AMR (Authentication Methods References) from decoded token.
+ */
+export function extractAmrFromToken(decoded: DecodedIdpAccessToken): string[] {
+  const amr = decoded.amr;
+
+  if (!amr) {
+    return [];
+  }
+
+  if (Array.isArray(amr)) {
+    return amr;
+  }
+
+  if (typeof amr === 'string') {
+    try {
+      const parsed = JSON.parse(amr);
+      return Array.isArray(parsed) ? parsed : [amr];
+    } catch {
+      return [amr];
+    }
+  }
+
+  return [];
+}
+
+// ============================================================================
+// EXPIRY CHECKING
+// ============================================================================
+
+/**
+ * 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 function tokenNeedsRefresh(
+  expiresAt: number | undefined,
+  bufferMs: number = 5 * 60 * 1000
+): boolean {
+  if (!expiresAt) {
+    return true; // No expiry info = assume needs refresh
+  }
+
+  const timeUntilExpiry = expiresAt - Date.now();
+  return timeUntilExpiry <= bufferMs;
+}
+
+/**
+ * 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 function tokenIsExpired(expiresAt: number | undefined): boolean {
+  if (!expiresAt) {
+    return true;
+  }
+  return Date.now() >= expiresAt;
+}
+
+/**
+ * Calculate milliseconds until token expires.
+ *
+ * @param expiresAt - Token expiry timestamp (Unix milliseconds)
+ * @returns Milliseconds until expiry, or 0 if already expired
+ */
+export function msUntilExpiry(expiresAt: number | undefined): number {
+  if (!expiresAt) {
+    return 0;
+  }
+  return Math.max(0, expiresAt - Date.now());
+}
+
+/**
+ * Convert Unix seconds (from JWT exp claim) to milliseconds.
+ */
+export function expClaimToMs(exp: number): number {
+  // JWT exp is in seconds, we use milliseconds internally
+  return exp * 1000;
+}
+
+// ============================================================================
+// TOKEN VALIDATION
+// ============================================================================
+
+/**
+ * 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 function validateTokenExpiry(
+  accessToken: string,
+  cachedExpiresAt: number | undefined
+): { valid: boolean; actualExpiresAt: number | null; mismatch: boolean } {
+  try {
+    const parts = accessToken.split('.');
+    if (parts.length !== 3) {
+      return { valid: false, actualExpiresAt: null, mismatch: false };
+    }
+
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    const actualExpiresAt = payload.exp ? payload.exp * 1000 : null;
+
+    if (!actualExpiresAt) {
+      return { valid: false, actualExpiresAt: null, mismatch: false };
+    }
+
+    const now = Date.now();
+    const isExpired = actualExpiresAt < now;
+
+    // Check for mismatch between cached and actual expiry
+    const mismatch = cachedExpiresAt
+      ? Math.abs(actualExpiresAt - cachedExpiresAt) > 1000 // Allow 1 second tolerance
+      : false;
+
+    if (mismatch) {
+      console.warn('[TOKEN_UTILS] Token expiry mismatch detected:', {
+        cached: cachedExpiresAt ? new Date(cachedExpiresAt).toISOString() : 'none',
+        actual: new Date(actualExpiresAt).toISOString(),
+        diff: cachedExpiresAt ? actualExpiresAt - cachedExpiresAt : 'N/A',
+      });
+    }
+
+    return {
+      valid: !isExpired,
+      actualExpiresAt,
+      mismatch,
+    };
+  } catch (error) {
+    console.error('[TOKEN_UTILS] Failed to validate token expiry:', error);
+    return { valid: false, actualExpiresAt: null, mismatch: false };
+  }
+}