@payez/next-mvp 3.0.0

package/src/lib/internal-api.ts

@@ -0,0 +1,171 @@
+/**
+ * Centralized internal API helper for the app to call ITSELF.
+ *
+ * IMPORTANT: All calls from the Next.js server to its own API routes MUST use
+ * these functions. Never use req.url, req.nextUrl.origin, or construct URLs
+ * from the incoming request.
+ *
+ * WHY HTTP IS REQUIRED (not optional):
+ * - This is the app calling its OWN backend within the same pod/container
+ * - NextAuth cookies are encrypted based on request protocol
+ * - TLS is terminated at ingress, so the pod receives HTTP internally
+ * - Using HTTPS here causes cookie decryption failures and 403 errors
+ * - This is NOT about "K8s traffic doesn't need TLS" - it's about
+ *   protocol consistency for cookie/session encryption
+ *
+ * Environment:
+ * - INTERNAL_API_URL: Required in production (e.g., http://service.namespace.svc.cluster.local:80)
+ * - Falls back to http://localhost:3200 in development only
+ */
+
+/**
+ * Get the internal API base URL for the app to call itself.
+ *
+ * @throws Error in production if INTERNAL_API_URL is not set
+ * @returns The base URL (no trailing slash)
+ */
+export function getInternalApiUrl(): string {
+  const url = process.env.INTERNAL_API_URL;
+  if (url) return url.replace(/\/$/, ''); // strip trailing slash
+
+  if (process.env.NODE_ENV !== 'production') {
+    return 'http://localhost:3200';
+  }
+
+  throw new Error(
+    '[INTERNAL_API_URL] FATAL: INTERNAL_API_URL environment variable is REQUIRED in production. ' +
+    'This is for the app to call ITSELF. MUST be HTTP (not HTTPS) due to cookie encryption. ' +
+    'Set to http://service.namespace.svc.cluster.local:80'
+  );
+}
+
+/**
+ * Options for internal fetch calls
+ */
+export interface InternalFetchOptions extends Omit<RequestInit, 'headers'> {
+  /** Additional headers to include */
+  headers?: Record<string, string>;
+  /** Cookie header to forward (typically from req.headers.get('cookie')) */
+  cookie?: string;
+  /** Session token for x-session-token header */
+  sessionToken?: string;
+  /** Request ID for tracing */
+  requestId?: string;
+  /** Parse response as JSON (default: true) */
+  parseJson?: boolean;
+}
+
+/**
+ * Result of an internal fetch call
+ */
+export interface InternalFetchResult<T = unknown> {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  data: T | null;
+  response: Response;
+}
+
+/**
+ * Make a fetch call to an internal API route (app calling itself).
+ *
+ * @param path - The API path (e.g., '/api/auth/refresh')
+ * @param options - Fetch options
+ * @returns The fetch result with parsed data
+ *
+ * @example
+ * ```ts
+ * // Simple GET
+ * const result = await internalFetch('/api/health');
+ *
+ * // POST with session
+ * const result = await internalFetch('/api/auth/refresh', {
+ *   method: 'POST',
+ *   cookie: req.headers.get('cookie') || '',
+ *   sessionToken: token.redisSessionId,
+ *   body: JSON.stringify({ refresh_token: refreshToken }),
+ * });
+ * ```
+ */
+export async function internalFetch<T = unknown>(
+  path: string,
+  options: InternalFetchOptions = {}
+): Promise<InternalFetchResult<T>> {
+  const {
+    headers: extraHeaders = {},
+    cookie,
+    sessionToken,
+    requestId,
+    parseJson = true,
+    ...fetchOptions
+  } = options;
+
+  const baseUrl = getInternalApiUrl();
+  const url = `${baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+
+  // Build headers
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    'Content-Type': 'application/json',
+    ...extraHeaders,
+  };
+
+  if (cookie) {
+    headers['Cookie'] = cookie;
+  }
+  if (sessionToken) {
+    headers['X-Session-Token'] = sessionToken;
+  }
+  if (requestId) {
+    headers['X-Request-Id'] = requestId;
+  }
+
+  const response = await fetch(url, {
+    ...fetchOptions,
+    headers,
+  });
+
+  let data: T | null = null;
+  if (parseJson) {
+    try {
+      data = await response.json() as T;
+    } catch {
+      data = null;
+    }
+  }
+
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    data,
+    response,
+  };
+}
+
+/**
+ * Trigger a token refresh via the internal API.
+ * This is a convenience wrapper for the common refresh pattern.
+ *
+ * @param cookie - The cookie header from the incoming request
+ * @param sessionToken - The session token
+ * @param refreshToken - Optional refresh token to include in body
+ * @param requestId - Optional request ID for tracing
+ * @returns Whether the refresh was successful
+ */
+export async function internalRefresh(
+  cookie: string,
+  sessionToken: string,
+  refreshToken?: string,
+  requestId?: string
+): Promise<{ ok: boolean; status: number }> {
+  const result = await internalFetch('/api/auth/refresh', {
+    method: 'POST',
+    cookie,
+    sessionToken,
+    requestId,
+    body: refreshToken ? JSON.stringify({ refresh_token: refreshToken }) : undefined,
+  });
+
+  return { ok: result.ok, status: result.status };
+}

package/src/lib/jwt-decode-client.ts

@@ -0,0 +1,45 @@
+/**
+ * Client-safe JWT decode (no Node.js dependencies)
+ * This is a lightweight version for browser usage
+ */
+
+// Decode base64url
+function base64urlDecode(base64url: string): string {
+  try {
+    // Convert base64url to base64
+    let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+    // Add padding if needed
+    while (base64.length % 4) {
+      base64 += '=';
+    }
+    return atob(base64);
+  } catch (e) {
+    throw new Error('Invalid base64url encoding');
+  }
+}
+
+/**
+ * Simple JWT decode for client-side use (no signature verification)
+ * @param token - JWT token string
+ * @returns Decoded payload or null if invalid
+ */
+export function jwtDecode<T = any>(token: string): T | null {
+  if (!token) return null;
+
+  try {
+    const parts = token.split('.');
+    if (parts.length < 2) {
+      console.error('[JWT] Invalid token format');
+      return null;
+    }
+
+    const payload = parts[1];
+    const decoded = base64urlDecode(payload);
+    const parsedPayload = JSON.parse(decoded);
+
+    return parsedPayload;
+  } catch (e) {
+    console.error('[JWT] Decode failed:', e instanceof Error ? e.message : 'Unknown error');
+    return null;
+  }
+}

package/src/lib/jwt-decode.ts

@@ -0,0 +1,83 @@
+import { jwtDecode as originalJwtDecode } from 'jwt-decode';
+
+// Define JwtPayload interface since jwt-decode v4 doesn't export it
+export interface JwtPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string[] | string;
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    jti?: string;
+}
+
+/**
+ * JWT Header structure.
+ * Contains metadata about the token including the signing key ID.
+ */
+export interface JwtHeader {
+    /** Algorithm used to sign the token (e.g., 'RS256', 'HS256') */
+    alg: string;
+    /** Token type (typically 'JWT') */
+    typ?: string;
+    /** Key ID - identifies which key was used to sign this token */
+    kid?: string;
+    /** Content type */
+    cty?: string;
+}
+
+/**
+ * Decode JWT payload (standard claims).
+ * This is a thin wrapper around jwt-decode library.
+ */
+export function jwtDecode<T = JwtPayload>(token: string): T {
+    return originalJwtDecode<T>(token);
+}
+
+/**
+ * Decode JWT header to extract kid, alg, and other header claims.
+ *
+ * The JWT header contains critical information:
+ * - kid: Key ID used to sign the token (needed for key governance)
+ * - alg: Algorithm used for signing
+ * - typ: Token type
+ *
+ * @param token - The JWT token string
+ * @returns Decoded header or null if decoding fails
+ */
+export function decodeJwtHeader(token: string): JwtHeader | null {
+    try {
+        if (!token || typeof token !== 'string') {
+            return null;
+        }
+
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            console.warn('[JWT_DECODE] Invalid JWT structure - expected 3 parts, got', parts.length);
+            return null;
+        }
+
+        // Decode base64url header (part 0)
+        const headerB64 = parts[0].replace(/-/g, '+').replace(/_/g, '/');
+        const headerJson = typeof atob !== 'undefined'
+            ? atob(headerB64)
+            : Buffer.from(headerB64, 'base64').toString('utf-8');
+
+        return JSON.parse(headerJson) as JwtHeader;
+    } catch (error) {
+        console.error('[JWT_DECODE] Failed to decode JWT header:', error);
+        return null;
+    }
+}
+
+/**
+ * Extract just the kid (Key ID) from a JWT token.
+ * Convenience function for when you only need the key ID.
+ *
+ * @param token - The JWT token string
+ * @returns The kid value or undefined if not present/decodable
+ */
+export function extractKidFromToken(token: string): string | undefined {
+    const header = decodeJwtHeader(token);
+    return header?.kid;
+}

package/src/lib/nextauth-secret.ts

@@ -0,0 +1,126 @@
+import 'server-only';
+import { validateNextAuthSecret } from './secret-validation';
+import { randomUUID } from 'crypto';
+
+let cachedSecret: string | null = null;
+let lastFetchedAt = 0;
+
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from IDP broker endpoint - IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for subsequent calls
+ */
+export async function resolveNextAuthSecret(): Promise<string> {
+  // Check if already in environment
+  if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+    // Silent - already configured
+    return process.env.NEXTAUTH_SECRET;
+  }
+
+  // Check if cached and fresh (within 5 minutes)
+  if (cachedSecret && Date.now() - lastFetchedAt < 5 * 60 * 1000) {
+    return cachedSecret;
+  }
+
+  // Broker mode: fetch from IDP (IDP handles all Key Vault/signing)
+  const base = process.env.IDP_URL;
+  if (!base) throw new Error('IDP_URL environment variable is required');
+
+  const clientIdStr = process.env.CLIENT_ID;
+  if (!clientIdStr || clientIdStr.trim() === '') throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
+
+  // Determine if clientId is numeric or string
+  const isNumeric = /^[0-9]+$/.test(clientIdStr);
+  const clientId = isNumeric ? parseInt(clientIdStr, 10) : clientIdStr;
+
+  // Step 1: Request IDP to sign a client assertion (IDP has the keys, not us)
+
+  const signingUrl = new URL(`${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`);
+  // Client ID passed via X-Client-Id header, not query string
+
+  const signingPayload = {
+    issuer: clientIdStr,
+    subject: clientIdStr,
+    audience: 'urn:payez:externalauth:nextauthsecret',
+    expires_in: 60
+  };
+
+  const signingResp = await fetch(signingUrl.toString(), {
+    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(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
+  }
+
+  const signingBody: any = await signingResp.json().catch(() => ({}));
+  const client_assertion = (
+    signingBody?.data?.client_assertion ??
+    signingBody?.data?.clientAssertion ??
+    signingBody?.client_assertion ??
+    signingBody?.clientAssertion ??
+    signingBody?.data?.ClientAssertion ??
+    signingBody?.ClientAssertion
+  ) as string | undefined;
+
+  if (!client_assertion || typeof client_assertion !== 'string') {
+    throw new Error('IDP did not return a valid signed client assertion');
+  }
+
+  // Step 2: Use the signed assertion to fetch the NextAuth secret
+
+  const proxyUrl = new URL(`${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`);
+
+  const proxyResp = await fetch(proxyUrl.toString(), {
+    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 (!proxyResp.ok) {
+    const txt = await proxyResp.text().catch(() => 'Unknown error');
+    throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
+  }
+
+  const proxyBody: any = await proxyResp.json().catch(() => ({}));
+
+  const secret = (proxyBody?.data?.secret ?? proxyBody?.secret) as string | undefined;
+  const configuration = (proxyBody?.data?.configuration ?? proxyBody?.configuration) as any | undefined;
+
+  // Configuration is available but we don't log it verbosely
+
+  if (!secret || typeof secret !== 'string') {
+    throw new Error('Proxy did not return a valid NextAuth secret');
+  }
+
+  const validation = validateNextAuthSecret(secret);
+  if (!validation.valid) {
+    throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+  }
+
+  cachedSecret = secret;
+  lastFetchedAt = Date.now();
+  process.env.NEXTAUTH_SECRET = secret;
+
+  console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+
+  return secret;
+}

package/src/lib/rate-limit-service.ts

@@ -0,0 +1,9 @@
+import redis from '../lib/redis';
+import { logger } from '../config/logger';
+
+export interface RateLimitRule { endpoint: string; period: string; limit: number; }
+export interface RateLimitResult { isAllowed: boolean; requestCount: number; limit: number; retryAfterSeconds?: number; failedAttempts?: number; }
+
+export function createPayEzRateLimitResponse(retryAfterSeconds: number, remainingAttempts: number = 0) {
+  return { success: false, message: 'Too many failed attempts', user_info: null, errors: [ { code: 'RateLimitExceeded', message: 'Too many failed authentication attempts', resolution: `Please try again in ${retryAfterSeconds} seconds`, remainingAttempts } ] };
+}

package/src/lib/redis.ts

@@ -0,0 +1,27 @@
+// E:\Repos\PayEz-Next-MVP\packages\next-mvp\src\lib\redis.ts
+import Redis, { RedisOptions } from 'ioredis';
+
+let client: Redis | null = null;
+
+function createClient(): Redis {
+  const url = process.env.REDIS_URL;
+
+  if (url && url.trim() !== '') {
+    // Use a standard configuration for better Docker compatibility
+    return new Redis(url);
+  }
+
+  // No REDIS_URL set, create a client that will fail fast.
+  return new Redis({ lazyConnect: true });
+}
+
+export function getRedis(): Redis {
+  if (!client) {
+    client = createClient();
+  }
+  return client;
+}
+
+const redis = getRedis();
+export { redis };
+export default redis;

package/src/lib/refresh-token-validator.ts

@@ -0,0 +1,64 @@
+import { jwtDecode } from './jwt-decode';
+import { tokenRefreshLogger } from '../config/logger';
+
+interface RefreshTokenPayload { exp: number; iat: number; jti: string; user_id: string; token_type: string; binding: string; }
+
+export function isRefreshTokenValid(token: string): boolean {
+  if (!token) return false;
+  try { const decoded = jwtDecode<RefreshTokenPayload>(token); if (!decoded) return false; const now = Math.floor(Date.now() / 1000); if (decoded.exp < now) return false; if (decoded.token_type !== 'refresh_token') return false; return true; } catch { return false; }
+}
+
+export function isRefreshTokenExpiring(token: string, bufferMinutes: number = 60): boolean {
+  if (!token) return true;
+  try { const decoded = jwtDecode<RefreshTokenPayload>(token); if (!decoded?.exp) return true; const now = Math.floor(Date.now() / 1000); const buffer = bufferMinutes * 60; return decoded.exp <= (now + buffer); } catch { return true; }
+}
+
+export function getRefreshTokenExpiration(token: string): number | null {
+  if (!token) return null; try { const decoded = jwtDecode<RefreshTokenPayload>(token); if (!decoded?.exp) return null; return decoded.exp * 1000; } catch { return null; }
+}
+
+export function getRefreshTokenTimeRemaining(token: string): number | null {
+  if (!token) return null; try { const decoded = jwtDecode<RefreshTokenPayload>(token); if (!decoded?.exp) return null; const now = Math.floor(Date.now() / 1000); const timeRemaining = decoded.exp - now; return timeRemaining > 0 ? timeRemaining : null; } catch { return null; }
+}
+
+export interface RefreshViabilityCheck {
+  canRefresh: boolean;
+  reason: 'valid_refresh_token' | 'no_refresh_token' | 'refresh_token_expired' | 'session_missing';
+  timeRemaining?: number;
+  expiresAt?: string;
+  accessTokenExpired?: boolean;
+  accessTokenTimeRemaining?: number;
+}
+
+export function checkRefreshViability(sessionData: any): RefreshViabilityCheck {
+  if (!sessionData) return { canRefresh: false, reason: 'session_missing' };
+  let accessTokenExpired = false; let accessTokenTimeRemaining: number | undefined;
+  if (sessionData.idpAccessTokenExpires) {
+    const now = Date.now(); let expiresAtMs = sessionData.idpAccessTokenExpires;
+    if (typeof expiresAtMs === 'string') expiresAtMs = parseInt(expiresAtMs, 10);
+    if (expiresAtMs < 1000000000000) expiresAtMs = expiresAtMs * 1000;
+    accessTokenTimeRemaining = Math.floor((expiresAtMs - now) / 1000);
+    const bufferSec = 5 * 60; // 5 minutes pre-expiry buffer
+    accessTokenExpired = accessTokenTimeRemaining <= bufferSec;
+    tokenRefreshLogger.debug('[REFRESH_VIABILITY] Access token expiration check', { now, expiresAtMs, accessTokenTimeRemaining, bufferSec, accessTokenExpired });
+  }
+  if (!sessionData.idpRefreshToken) return { canRefresh: false, reason: 'no_refresh_token', accessTokenExpired, accessTokenTimeRemaining };
+  if (sessionData.idpRefreshTokenExpires) {
+    let refreshExpMs = sessionData.idpRefreshTokenExpires;
+    if (typeof refreshExpMs === 'string') refreshExpMs = parseInt(refreshExpMs, 10);
+    if (refreshExpMs < 1000000000000) refreshExpMs = refreshExpMs * 1000;
+    const nowMs = Date.now(); const timeRemainingSec = Math.floor((refreshExpMs - nowMs) / 1000);
+    if (timeRemainingSec <= 0) return { canRefresh: false, reason: 'refresh_token_expired', accessTokenExpired, accessTokenTimeRemaining };
+    return { canRefresh: true, reason: 'valid_refresh_token', timeRemaining: timeRemainingSec, expiresAt: new Date(refreshExpMs).toISOString(), accessTokenExpired, accessTokenTimeRemaining };
+  }
+  try {
+    const decoded = jwtDecode<RefreshTokenPayload>(sessionData.idpRefreshToken); const nowSec = Math.floor(Date.now() / 1000);
+    if (!decoded?.exp || decoded.token_type !== 'refresh_token') return { canRefresh: false, reason: 'refresh_token_expired', accessTokenExpired, accessTokenTimeRemaining };
+    const timeRemaining = decoded.exp - nowSec; if (timeRemaining <= 0) return { canRefresh: false, reason: 'refresh_token_expired', accessTokenExpired, accessTokenTimeRemaining };
+    const expiresAtIso = new Date(decoded.exp * 1000).toISOString();
+    return { canRefresh: true, reason: 'valid_refresh_token', timeRemaining, expiresAt: expiresAtIso, accessTokenExpired, accessTokenTimeRemaining };
+  } catch (error) {
+    tokenRefreshLogger.debug('[REFRESH_VIABILITY] Failed to decode refresh token for viability', { error: error instanceof Error ? error.message : String(error) });
+    return { canRefresh: false, reason: 'refresh_token_expired', accessTokenExpired, accessTokenTimeRemaining };
+  }
+}