@payez/next-mvp 3.0.0

package/src/lib/idp-client-config.ts

@@ -0,0 +1,442 @@
+/**
+ * IDP Client Configuration
+ *
+ * Fetches full client configuration from IDP including:
+ * - OAuth provider credentials (from Key Vault)
+ * - 2FA/MFA settings
+ * - Session configuration
+ * - NextAuth secret
+ * - Branding
+ *
+ * CACHING STRATEGY:
+ * 1. In-memory cache (fastest, but lost on module reload in dev)
+ * 2. Redis cache (survives module reloads, shared across instances)
+ * 3. IDP fetch (when both caches miss)
+ *
+ * NO FALLBACKS. If IDP doesn't respond correctly, we fail loud.
+ *
+ * @version 2.0.0 - Added Redis-backed caching
+ */
+
+import 'server-only';
+import { randomUUID } from 'crypto';
+import redis from './redis';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OAuthProviderConfig {
+    provider: string;
+    enabled: boolean;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string;
+    additionalParams?: Record<string, any>;
+}
+
+export interface AuthSettings {
+    require2FA: boolean;
+    allowed2FAMethods: string[];
+    mfaGracePeriodHours: number;
+    mfaRememberDeviceDays: number;
+    sessionTimeoutMinutes: number;
+    idleTimeoutMinutes: number;
+    allowRememberMe: boolean;
+    rememberMeDays: number;
+    lockoutThreshold: number;
+    lockoutDurationMinutes: number;
+}
+
+export interface BrandingConfig {
+    theme?: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    logoUrl?: string;
+}
+
+export interface IDPClientConfig {
+    clientId: number;
+    clientSlug: string;
+    nextAuthSecret: string;
+    configCacheTtlSeconds: number;
+    oauthProviders: OAuthProviderConfig[];
+    authSettings: AuthSettings;
+    branding: BrandingConfig;
+    baseClientUrl?: string; // Public base URL - sets IDENTITY_CLIENT_BASE_EXTERNAL_URL
+}
+
+// ============================================================================
+// Cache & Fetch Deduplication
+// ============================================================================
+
+let cachedConfig: IDPClientConfig | null = null;
+let cacheExpiry: number = 0;
+let pendingFetch: Promise<IDPClientConfig> | null = null; // Prevents parallel fetches
+
+// ============================================================================
+// Redis Cache Configuration
+// ============================================================================
+
+const REDIS_CONFIG_KEY_PREFIX = 'idp_config:';
+
+function getRedisConfigKey(): string {
+    const clientId = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_CLIENT_ID || 'default';
+    return `${REDIS_CONFIG_KEY_PREFIX}${clientId}`;
+}
+
+interface RedisCachedConfig {
+    config: IDPClientConfig;
+    expiresAt: number;
+}
+
+async function getConfigFromRedis(): Promise<IDPClientConfig | null> {
+    try {
+        const key = getRedisConfigKey();
+        const cached = await redis.get(key);
+        if (!cached) return null;
+
+        const parsed: RedisCachedConfig = JSON.parse(cached);
+        if (Date.now() >= parsed.expiresAt) {
+            // Expired, delete it
+            await redis.del(key);
+            return null;
+        }
+
+        return parsed.config;
+    } catch (error) {
+        console.warn('[IDP_CONFIG] Failed to read from Redis cache:', error);
+        return null;
+    }
+}
+
+async function setConfigInRedis(config: IDPClientConfig): Promise<void> {
+    try {
+        const key = getRedisConfigKey();
+        const ttlSeconds = config.configCacheTtlSeconds || 300;
+        const data: RedisCachedConfig = {
+            config,
+            expiresAt: Date.now() + (ttlSeconds * 1000)
+        };
+        // Store with TTL slightly longer than the logical expiry to allow for clock skew
+        await redis.set(key, JSON.stringify(data), 'EX', ttlSeconds + 10);
+    } catch (error) {
+        console.warn('[IDP_CONFIG] Failed to write to Redis cache:', error);
+    }
+}
+
+// ============================================================================
+// Circuit Breaker & Backoff State
+// ============================================================================
+
+let consecutiveFailures = 0;
+let lastFailureTime = 0;
+const MAX_FAILURES = 3;
+const CIRCUIT_OPEN_MS = 300000; // 5 minutes
+const MAX_BACKOFF_MS = 30000; // 30 seconds max backoff
+
+// ============================================================================
+// Main Functions
+// ============================================================================
+
+/**
+ * Get IDP client configuration with multi-tier caching.
+ *
+ * Caching layers (checked in order):
+ * 1. In-memory cache (fastest, lost on module reload in dev)
+ * 2. Redis cache (survives module reloads)
+ * 3. IDP fetch (when both caches miss)
+ *
+ * THROWS if IDP is unavailable or misconfigured. No fallbacks.
+ */
+export async function getIDPClientConfig(forceRefresh: boolean = false): Promise<IDPClientConfig> {
+    const now = Date.now();
+
+    // Layer 1: Return in-memory cached if still valid (skip if forceRefresh)
+    if (!forceRefresh && cachedConfig && now < cacheExpiry) {
+        return cachedConfig;
+    }
+
+    // If a fetch is already in progress, wait for it instead of starting another
+    if (pendingFetch) {
+        return pendingFetch;
+    }
+
+    // Layer 2: Check Redis cache (skip if forceRefresh - startup should always get fresh data)
+    if (!forceRefresh) {
+        const redisConfig = await getConfigFromRedis();
+        if (redisConfig) {
+            // Restore to in-memory cache
+            cachedConfig = redisConfig;
+            cacheExpiry = Date.now() + ((redisConfig.configCacheTtlSeconds || 300) * 1000);
+
+            // Set NEXTAUTH_SECRET from cached config
+            if (redisConfig.nextAuthSecret) {
+                process.env.NEXTAUTH_SECRET = redisConfig.nextAuthSecret;
+            }
+
+            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from cached config
+            // AUTH_TRUST_HOST=true tells NextAuth to derive OAuth callback URLs from headers.
+            if (redisConfig.baseClientUrl) {
+                process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = redisConfig.baseClientUrl;
+            }
+
+            return redisConfig;
+        }
+    }
+
+    // Layer 3: Fetch from IDP
+    const idpUrl = process.env.IDP_URL;
+    const clientIdStr = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_CLIENT_ID;
+
+    if (!idpUrl) {
+        throw new Error('[IDP_CONFIG] FATAL: IDP_URL must be set');
+    }
+    if (!clientIdStr) {
+        throw new Error('[IDP_CONFIG] FATAL: CLIENT_ID or NEXT_PUBLIC_CLIENT_ID must be set');
+    }
+
+    // Start fetch and store promise so concurrent callers wait for same result
+    pendingFetch = fetchConfigFromIDP(idpUrl, clientIdStr)
+        .then(async config => {
+            // Cache with TTL from response (default 5 minutes)
+            cachedConfig = config;
+            cacheExpiry = Date.now() + ((config.configCacheTtlSeconds || 300) * 1000);
+
+            // Store in Redis for persistence across module reloads
+            await setConfigInRedis(config);
+
+            // Set NEXTAUTH_SECRET from config
+            if (config.nextAuthSecret) {
+                process.env.NEXTAUTH_SECRET = config.nextAuthSecret;
+            } else {
+                throw new Error('[IDP_CONFIG] FATAL: IDP did not return nextAuthSecret');
+            }
+
+            // Set IDENTITY_CLIENT_BASE_EXTERNAL_URL from config
+            // AUTH_TRUST_HOST=true tells NextAuth to derive OAuth callback URLs from headers.
+            if (config.baseClientUrl) {
+                process.env.IDENTITY_CLIENT_BASE_EXTERNAL_URL = config.baseClientUrl;
+                console.log("[IDP_CONFIG] Set IDENTITY_CLIENT_BASE_EXTERNAL_URL:", config.baseClientUrl);
+            }
+
+            return config;
+        })
+        .finally(() => {
+            pendingFetch = null; // Clear so next cache miss can fetch again
+        });
+
+    return pendingFetch;
+}
+
+/**
+ * Clear the config cache (useful for testing or forced refresh)
+ */
+export function clearConfigCache(): void {
+    cachedConfig = null;
+    cacheExpiry = 0;
+}
+
+/**
+ * Get enabled OAuth providers from config
+ */
+export function getEnabledProviders(config: IDPClientConfig): OAuthProviderConfig[] {
+    return config.oauthProviders?.filter(p => p.enabled) || [];
+}
+
+// ============================================================================
+// Internal Functions
+// ============================================================================
+
+async function fetchConfigFromIDP(idpUrl: string, clientIdStr: string): Promise<IDPClientConfig> {
+    // =========================================================================
+    // Circuit Breaker Check
+    // =========================================================================
+    if (consecutiveFailures >= MAX_FAILURES) {
+        const timeSinceFailure = Date.now() - lastFailureTime;
+        if (timeSinceFailure < CIRCUIT_OPEN_MS) {
+            // Circuit is open - return stale cache if available
+            if (cachedConfig) {
+                return cachedConfig;
+            }
+            throw new Error(`[IDP_CONFIG] Circuit breaker OPEN - no cached config available. Retry in ${Math.round((CIRCUIT_OPEN_MS - timeSinceFailure) / 1000)}s`);
+        }
+        // Half-open state: allow one request to test
+        consecutiveFailures = MAX_FAILURES - 1;
+    }
+
+    // =========================================================================
+    // Exponential Backoff Check
+    // =========================================================================
+    if (consecutiveFailures > 0) {
+        const backoffMs = Math.min(1000 * Math.pow(2, consecutiveFailures), MAX_BACKOFF_MS);
+        const timeSinceFailure = Date.now() - lastFailureTime;
+        if (timeSinceFailure < backoffMs) {
+            const remainingMs = backoffMs - timeSinceFailure;
+            // Return stale cache during backoff if available
+            if (cachedConfig) {
+                return cachedConfig;
+            }
+            throw new Error(`[IDP_CONFIG] In backoff period - retry in ${Math.round(remainingMs)}ms`);
+        }
+    }
+
+    try {
+    // Step 1: Get signed client assertion from IDP
+    const signingUrl = `${idpUrl.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+
+    const signingPayload = {
+        issuer: clientIdStr,
+        subject: clientIdStr,
+        audience: 'urn:payez:externalauth:clientconfig',
+        expires_in: 60
+    };
+
+    const signingResp = await fetch(signingUrl, {
+        method: 'POST',
+        headers: {
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+        },
+        body: JSON.stringify(signingPayload),
+        cache: 'no-store'
+    } as RequestInit);
+
+    if (!signingResp.ok) {
+        const txt = await signingResp.text().catch(() => 'Unknown error');
+        throw new Error(`[IDP_CONFIG] FATAL: Failed to sign client assertion: ${signingResp.status} - ${txt}`);
+    }
+
+    const signingBody: any = await signingResp.json().catch(() => null);
+
+    if (!signingBody) {
+        throw new Error('[IDP_CONFIG] FATAL: IDP returned empty or invalid JSON for sign-client-assertion');
+    }
+
+    // Per PayEz API standard: response is { success, data: { client_assertion }, ... }
+    // But IDP might use camelCase (clientAssertion) - check both
+    const client_assertion = (
+        signingBody?.data?.client_assertion ??
+        signingBody?.data?.clientAssertion
+    ) as string | undefined;
+
+    if (!client_assertion) {
+        console.error('[IDP_CONFIG] FATAL: Full response body:', JSON.stringify(signingBody, null, 2));
+        throw new Error(`[IDP_CONFIG] FATAL: IDP response missing client_assertion. Got keys: ${JSON.stringify(Object.keys(signingBody?.data || signingBody || {}))}`);
+    }
+
+    // Step 2: Fetch client config using the assertion
+    const configUrl = `${idpUrl.replace(/\/$/, '')}/api/ExternalAuth/client-config`;
+
+    const configResp = await fetch(configUrl, {
+        method: 'POST',
+        headers: {
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+        },
+        body: JSON.stringify({ client_assertion }),
+        cache: 'no-store'
+    } as RequestInit);
+
+    if (!configResp.ok) {
+        const txt = await configResp.text().catch(() => 'Unknown error');
+        throw new Error(`[IDP_CONFIG] FATAL: Failed to fetch client config: ${configResp.status} - ${txt}`);
+    }
+
+    const configBody: any = await configResp.json().catch(() => null);
+
+    if (!configBody) {
+        throw new Error('[IDP_CONFIG] FATAL: IDP returned empty or invalid JSON for client-config');
+    }
+
+    // Per PayEz API standard: response is wrapped in { success, data: {...} }
+    const configData = configBody?.data;
+
+    if (!configData || typeof configData !== 'object') {
+        console.error('[IDP_CONFIG] FATAL: Full config response body:', JSON.stringify(configBody, null, 2));
+        throw new Error('[IDP_CONFIG] FATAL: IDP client-config response missing data envelope');
+    }
+
+    // Validate required fields - handle both number and string client_id
+    const rawClientId = configData.clientId ?? configData.client_id;
+    if (rawClientId === undefined || rawClientId === null) {
+        throw new Error(`[IDP_CONFIG] FATAL: IDP response missing clientId/client_id. Got: ${JSON.stringify(Object.keys(configData))}`);
+    }
+
+    // Map response to our interface (IDP always returns snake_case)
+    const config: IDPClientConfig = {
+        clientId: typeof rawClientId === 'string' ? parseInt(rawClientId, 10) : rawClientId,
+        clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
+        nextAuthSecret: configData.nextAuthSecret ?? configData.next_auth_secret ?? '',
+        configCacheTtlSeconds: configData.configCacheTtlSeconds ?? configData.config_cache_ttl_seconds ?? 300,
+        oauthProviders: (configData.oauthProviders ?? configData.oauth_providers ?? []).map((p: any) => ({
+            provider: p.provider ?? '',
+            enabled: p.enabled ?? false,
+            clientId: p.clientId ?? p.client_id ?? '',
+            clientSecret: p.clientSecret ?? p.client_secret ?? '',
+            scopes: p.scopes,
+            additionalParams: p.additionalParams ?? p.additional_params
+        })),
+        authSettings: {
+            require2FA: (() => {
+                // Check nested locations first (canonical)
+                const nested = configData.authSettings?.require2FA ?? configData.auth_settings?.require_2fa;
+                if (nested !== undefined) return nested;
+                // TRANSITION FALLBACK: Check top-level (deprecated)
+                const topLevel = configData.require2FA ?? configData.require_2fa;
+                if (topLevel !== undefined) {
+                    console.warn('[IDP_CONFIG] DEPRECATION: require2FA found at top-level. Should be nested under auth_settings. Update IDP.');
+                    return topLevel;
+                }
+                return true; // Default to true for security
+            })(),
+            allowed2FAMethods: configData.authSettings?.allowed2FAMethods ?? configData.auth_settings?.allowed_2fa_methods ?? ['email', 'sms'],
+            mfaGracePeriodHours: configData.authSettings?.mfaGracePeriodHours ?? configData.auth_settings?.mfa_grace_period_hours ?? 24,
+            mfaRememberDeviceDays: configData.authSettings?.mfaRememberDeviceDays ?? configData.auth_settings?.mfa_remember_device_days ?? 30,
+            sessionTimeoutMinutes: configData.authSettings?.sessionTimeoutMinutes ?? configData.auth_settings?.session_timeout_minutes ?? 60,
+            idleTimeoutMinutes: configData.authSettings?.idleTimeoutMinutes ?? configData.auth_settings?.idle_timeout_minutes ?? 15,
+            allowRememberMe: configData.authSettings?.allowRememberMe ?? configData.auth_settings?.allow_remember_me ?? true,
+            rememberMeDays: configData.authSettings?.rememberMeDays ?? configData.auth_settings?.remember_me_days ?? 30,
+            lockoutThreshold: configData.authSettings?.lockoutThreshold ?? configData.auth_settings?.lockout_threshold ?? 5,
+            lockoutDurationMinutes: configData.authSettings?.lockoutDurationMinutes ?? configData.auth_settings?.lockout_duration_minutes ?? 15
+        },
+        branding: {
+            theme: configData.branding?.theme,
+            primaryColor: configData.branding?.primaryColor ?? configData.branding?.primary_color,
+            secondaryColor: configData.branding?.secondaryColor ?? configData.branding?.secondary_color,
+            logoUrl: configData.branding?.logoUrl ?? configData.branding?.logo_url
+        },
+        baseClientUrl: configData.baseClientUrl ?? configData.base_client_url ?? configData.BaseClientUrl
+    };
+
+    // Debug: log what we got for baseClientUrl
+    console.log(`[IDP_CONFIG] Parsed baseClientUrl:`, config.baseClientUrl, `| raw keys:`, Object.keys(configData).filter(k => k.toLowerCase().includes('client')));
+
+    // Validate we got what we need
+    if (!config.clientId) {
+        throw new Error('[IDP_CONFIG] FATAL: clientId is 0 or missing after parsing');
+    }
+    if (!config.nextAuthSecret) {
+        throw new Error('[IDP_CONFIG] FATAL: nextAuthSecret is empty after parsing');
+    }
+
+    // Success - reset failure tracking
+    consecutiveFailures = 0;
+    return config;
+
+    } catch (error) {
+        // Track failure for circuit breaker
+        consecutiveFailures++;
+        lastFailureTime = Date.now();
+        console.error('[IDP_CONFIG] Fetch failed', {
+            consecutiveFailures,
+            maxFailures: MAX_FAILURES,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+    }
+}

package/src/lib/idp-fetch.ts

@@ -0,0 +1,101 @@
+import { NextRequest } from 'next/server';
+import { getTokenTestAware } from './test-aware-get-token';
+import { getSession } from './session-store';
+import { internalRefresh } from './internal-api';
+
+/**
+ * Centralized IDP fetch helper
+ * - Injects Bearer from Redis session
+ * - If access token is expired/near-expiry, triggers one refresh and retries fetch once
+ * - Returns parsed JSON and HTTP status
+ */
+export interface IdpFetchResult<T = any> {
+  ok: boolean;
+  status: number;
+  json: T | null;
+  attemptedRefresh: boolean;
+}
+
+function buildHeaders(req: NextRequest, bearer?: string, extra?: Record<string, string>) {
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    ...extra,
+  };
+  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
+  if (xfwd) headers['X-Forwarded-For'] = xfwd.split(',')[0].trim();
+  const ua = req.headers.get('user-agent');
+  if (ua) headers['User-Agent'] = ua;
+  if (bearer) headers['Authorization'] = `Bearer ${bearer}`;
+  return headers;
+}
+
+async function ensureFreshAccessToken(req: NextRequest): Promise<{ sessionToken?: string; accessToken?: string }> {
+  const token = await getTokenTestAware(req);
+  // Support both field names: sessionToken (auth.ts JWT) and redisSessionId (legacy)
+  const sessionToken = (token?.sessionToken || token?.redisSessionId) as string | undefined;
+  console.log('[IDP_FETCH] ensureFreshAccessToken:', {
+    hasToken: !!token,
+    sessionToken: sessionToken?.substring(0, 20) + '...',
+    pathname: req.nextUrl.pathname
+  });
+  if (!sessionToken) {
+    console.warn('[IDP_FETCH] No sessionToken found in JWT - Bearer token will NOT be sent!');
+    return {};
+  }
+  let session = await getSession(sessionToken);
+  console.log('[IDP_FETCH] Redis session lookup:', {
+    hasSession: !!session,
+    hasAccessToken: !!session?.idpAccessToken,
+    bearerKeyId: session?.bearerKeyId || 'NOT_SET',
+    idpClientId: session?.idpClientId || 'NOT_SET',
+  });
+  if (!session?.idpAccessToken) return { sessionToken };
+  const now = Date.now();
+  const timeLeft = (session.idpAccessTokenExpires ?? now) - now;
+  // Treat tokens as effectively expired if within 5 minutes of expiry
+  if (timeLeft > 5 * 60 * 1000) {
+    return { sessionToken, accessToken: session.idpAccessToken };
+  }
+  // attempt refresh once via centralized internal API helper
+  try {
+    await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+  } catch {}
+  session = await getSession(sessionToken);
+  return { sessionToken, accessToken: session?.idpAccessToken };
+}
+
+export async function idpFetchJSON<T = any>(
+  req: NextRequest,
+  targetUrl: string,
+  init: RequestInit = {}
+): Promise<IdpFetchResult<T>> {
+  let attemptedRefresh = false;
+  let { accessToken, sessionToken } = await ensureFreshAccessToken(req);
+
+  const makeCall = async (bearer?: string) => {
+    const res = await fetch(targetUrl, {
+      ...init,
+      headers: buildHeaders(req, bearer, init.headers as any),
+    });
+    let json: any = null;
+    try { json = await res.json(); } catch { json = null; }
+    return { res, json } as const;
+  };
+
+  // First attempt
+  let { res, json } = await makeCall(accessToken);
+  if ((res.status === 401 || res.status === 403) && sessionToken && !attemptedRefresh) {
+    attemptedRefresh = true;
+    try {
+      // Use centralized internal API helper for server-to-server calls
+      const rf = await internalRefresh(req.headers.get('cookie') || '', sessionToken);
+      if (rf.ok) {
+        const fresh = await getSession(sessionToken);
+        ({ res, json } = await makeCall(fresh?.idpAccessToken));
+      }
+    } catch {}
+  }
+
+  return { ok: res.ok, status: res.status, json: json as T | null, attemptedRefresh };
+}