@payez/next-mvp 4.8.1 → 4.8.3

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

@@ -1,364 +1,364 @@
-/**
- * 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;
-  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
-// ============================================================================
-
-/**
- * idpOAuthCallback REMOVED 2026-08-05 (NextPert, BAPert 20168 / QAPert 20166).
- *
- * It POSTed to /api/ExternalAuth/oauth-callback with provider, email, name,
- * tokens and client_id — ALL ASSERTIONS, no id_token, nothing verifiable. After
- * the 170003 fix (13436d56e) that call can only ever return 401.
- *
- * It was a SECOND caller of the same endpoint, and only the first
- * (better-auth.ts, card 138635) was hardened — the same duplicated-integration
- * trap the viability code documents ("adding the relay to just one would leave
- * an app that mounts THIS one still blind").
- *
- * It had no call sites and was not reachable through the package exports map
- * (no ./auth/utils key, no wildcard), so removing it breaks nothing. Deleted
- * rather than fixed, because an unreachable function whose only outcome is a
- * 401 that LOOKS like a security success is a trap for whoever finds it next.
- */
-
-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');
-      // PAY-1427: never the raw upstream body (the refresh.ts:528 twin PR 139 fixed). Status + length only.
-      console.error('[IDP_CLIENT] Token refresh failed:', { status: response.status, bodyLength: errorText.length });
-      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',
-      },
-    };
-  }
-}
+/**
+ * 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;
+  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
+// ============================================================================
+
+/**
+ * idpOAuthCallback REMOVED 2026-08-05 (NextPert, BAPert 20168 / QAPert 20166).
+ *
+ * It POSTed to /api/ExternalAuth/oauth-callback with provider, email, name,
+ * tokens and client_id — ALL ASSERTIONS, no id_token, nothing verifiable. After
+ * the 170003 fix (13436d56e) that call can only ever return 401.
+ *
+ * It was a SECOND caller of the same endpoint, and only the first
+ * (better-auth.ts, card 138635) was hardened — the same duplicated-integration
+ * trap the viability code documents ("adding the relay to just one would leave
+ * an app that mounts THIS one still blind").
+ *
+ * It had no call sites and was not reachable through the package exports map
+ * (no ./auth/utils key, no wildcard), so removing it breaks nothing. Deleted
+ * rather than fixed, because an unreachable function whose only outcome is a
+ * 401 that LOOKS like a security success is a trap for whoever finds it next.
+ */
+
+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');
+      // PAY-1427: never the raw upstream body (the refresh.ts:528 twin PR 139 fixed). Status + length only.
+      console.error('[IDP_CLIENT] Token refresh failed:', { status: response.status, bodyLength: errorText.length });
+      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',
+      },
+    };
+  }
+}