@payez/next-mvp 3.0.0

package/dist/lib/startup-init.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Startup Initialization for MVP
+ *
+ * This module ensures that critical initialization tasks are completed
+ * before the application serves requests.
+ *
+ * Now uses unified IDP client config for:
+ * - NEXTAUTH_SECRET
+ * - OAuth provider configuration
+ * - Auth settings (2FA, session timeouts, etc.)
+ */
+import 'server-only';
+import { type IDPClientConfig } from './idp-client-config';
+/**
+ * Initialize the application startup sequence (async)
+ * Handles async initialization like fetching secrets from IDP
+ */
+export declare function ensureInitialized(): Promise<void>;
+/**
+ * Synchronously log startup status
+ * Can be called before async initialization is complete
+ */
+export declare function logStartupStatus(): void;
+/**
+ * Get the cached IDP config after initialization.
+ * Returns null if not yet initialized.
+ */
+export declare function getStartupIDPConfig(): IDPClientConfig | null;
+/**
+ * Check if initialization failed (NEXTAUTH_SECRET couldn't be retrieved)
+ */
+export declare function isInitializationFailed(): boolean;
+/**
+ * Get the last initialization error
+ */
+export declare function getInitializationError(): Error | null;
+/**
+ * Check if the app is ready to handle auth requests
+ */
+export declare function isAppReady(): boolean;

package/dist/lib/startup-init.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Startup Initialization for MVP
+ *
+ * This module ensures that critical initialization tasks are completed
+ * before the application serves requests.
+ *
+ * Now uses unified IDP client config for:
+ * - NEXTAUTH_SECRET
+ * - OAuth provider configuration
+ * - Auth settings (2FA, session timeouts, etc.)
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureInitialized = ensureInitialized;
+exports.logStartupStatus = logStartupStatus;
+exports.getStartupIDPConfig = getStartupIDPConfig;
+exports.isInitializationFailed = isInitializationFailed;
+exports.getInitializationError = getInitializationError;
+exports.isAppReady = isAppReady;
+require("server-only");
+const idp_client_config_1 = require("./idp-client-config");
+let initializationStarted = false;
+let initializationComplete = false;
+let initializationFailed = false;
+let initializationPromise = null;
+let lastInitError = null;
+// Cached IDP config for access after initialization
+let cachedIDPConfig = null;
+// Startup backoff to prevent pod restart storms from hammering IDP
+let lastStartupAttemptTime = 0;
+const STARTUP_BACKOFF_MS = 30000; // 30 seconds between startup attempts after failure
+/**
+ * Initialize the application startup sequence (async)
+ * Handles async initialization like fetching secrets from IDP
+ */
+async function ensureInitialized() {
+    // If already initialized, return immediately
+    if (initializationComplete) {
+        return;
+    }
+    // If initialization is in progress, wait for it
+    if (initializationPromise) {
+        return initializationPromise;
+    }
+    // Prevent hammering IDP on rapid pod restarts
+    const now = Date.now();
+    if (initializationFailed && (now - lastStartupAttemptTime) < STARTUP_BACKOFF_MS) {
+        const remainingMs = STARTUP_BACKOFF_MS - (now - lastStartupAttemptTime);
+        console.warn('[STARTUP] In backoff period after previous failure, skipping IDP call', {
+            remainingMs: Math.round(remainingMs),
+            lastError: lastInitError?.message
+        });
+        // Re-throw last error so callers know we're still in failed state
+        throw lastInitError || new Error('Initialization in backoff period');
+    }
+    // Track this attempt time
+    lastStartupAttemptTime = now;
+    // Mark as started
+    initializationStarted = true;
+    // Start initialization
+    initializationPromise = performInitialization();
+    await initializationPromise;
+}
+/**
+ * Synchronously log startup status
+ * Can be called before async initialization is complete
+ */
+function logStartupStatus() {
+    if (!initializationStarted) {
+        console.log('\n');
+        console.log('╔══════════════════════════════════════════════════════════════╗');
+        console.log('║            🚀 PayEz Next MVP - Starting Up                    ║');
+        console.log('║                                                              ║');
+        console.log('║  Async initialization in progress...                         ║');
+        console.log('║  - Resolving NEXTAUTH_SECRET from IDP                       ║');
+        console.log('║  - Verifying environment configuration                       ║');
+        console.log('║                                                              ║');
+        console.log('║  Check logs below for detailed initialization status:        ║');
+        console.log('╚══════════════════════════════════════════════════════════════╝');
+        console.log('');
+    }
+    else if (initializationComplete) {
+        console.log('\n');
+        console.log('╔══════════════════════════════════════════════════════════════╗');
+        console.log('║            ✨ PayEz Next MVP Ready for Requests ✨            ║');
+        console.log('╚══════════════════════════════════════════════════════════════╝');
+        console.log('');
+    }
+    else if (lastInitError) {
+        console.log('\n');
+        console.log('╔══════════════════════════════════════════════════════════════╗');
+        console.log('║  ⚠️  Startup error detected - initialization may still retry  ║');
+        console.log('╚══════════════════════════════════════════════════════════════╝');
+        console.log('');
+    }
+}
+async function performInitialization() {
+    console.log('\n');
+    console.log('╔══════════════════════════════════════════════════════════════╗');
+    console.log('║            PayEz Next MVP - Async Startup                     ║');
+    console.log('╚══════════════════════════════════════════════════════════════╝');
+    console.log('');
+    try {
+        // Step 1: Fetch full client config from IDP (includes secret, providers, settings)
+        console.log('[STARTUP] Step 1/2: Fetching client config from IDP...');
+        try {
+            const config = await (0, idp_client_config_1.getIDPClientConfig)(true);
+            cachedIDPConfig = config;
+            console.log('[STARTUP] Client config loaded successfully');
+            console.log('[STARTUP]    - Client ID:', config.clientId);
+            console.log('[STARTUP]    - Client Slug:', config.clientSlug);
+            console.log('[STARTUP]    - Secret length:', config.nextAuthSecret?.length || 0, 'chars');
+            console.log('[STARTUP]    - OAuth Providers:', config.oauthProviders?.filter(p => p.enabled).map(p => p.provider).join(', ') || 'none');
+            console.log('[STARTUP]    - Require 2FA:', config.authSettings?.require2FA);
+            console.log('[STARTUP]    - Cache TTL:', config.configCacheTtlSeconds, 'seconds');
+            console.log('[STARTUP]    - Base Client URL:', config.baseClientUrl || '(not set)');
+            // Set NEXTAUTH_SECRET from IDP response if not already set
+            if (config.nextAuthSecret && !process.env.NEXTAUTH_SECRET) {
+                process.env.NEXTAUTH_SECRET = config.nextAuthSecret;
+                console.log('[STARTUP] Set NEXTAUTH_SECRET from IDP config');
+            }
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            console.error('[STARTUP] IDP config fetch failed:', errorMsg);
+            // Fall back to legacy secret resolution
+            console.log('[STARTUP] Falling back to legacy NEXTAUTH_SECRET resolution...');
+            const { resolveNextAuthSecret } = await Promise.resolve().then(() => __importStar(require('./nextauth-secret')));
+            const secret = await resolveNextAuthSecret();
+            console.log('[STARTUP] NEXTAUTH_SECRET resolved via fallback');
+            console.log('[STARTUP]    - Secret length:', secret.length, 'chars');
+        }
+        // Step 2: Verify NEXTAUTH_SECRET is available - FAIL FAST if not
+        console.log('[STARTUP] Step 2/2: Verifying NEXTAUTH_SECRET...');
+        const secret = process.env.NEXTAUTH_SECRET;
+        if (!secret || secret.trim() === '') {
+            console.error('');
+            console.error('╔══════════════════════════════════════════════════════════════╗');
+            console.error('║   ❌ FATAL: NEXTAUTH_SECRET NOT AVAILABLE                     ║');
+            console.error('║                                                              ║');
+            console.error('║   The app cannot start without a valid NEXTAUTH_SECRET.      ║');
+            console.error('║   This should be fetched from IDP at startup.                ║');
+            console.error('║                                                              ║');
+            console.error('║   Possible causes:                                           ║');
+            console.error('║   • IDP is not running or unreachable                        ║');
+            console.error('║   • CLIENT_ID is not registered in IDP                       ║');
+            console.error('║   • IDP_URL is incorrect                                     ║');
+            console.error('║   • Network connectivity issue                               ║');
+            console.error('╚══════════════════════════════════════════════════════════════╝');
+            console.error('');
+            throw new Error('FATAL: NEXTAUTH_SECRET not available - cannot start without valid secret from IDP');
+        }
+        console.log('[STARTUP] NEXTAUTH_SECRET verified (' + secret.length + ' chars)');
+        // Step 3: Validate cookie name consistency
+        // This catches bugs where getJwtCookieName() returns a different name than
+        // what auth-options.ts configures, which causes sessions to fail in production
+        const { validateCookieNameConsistency, getSessionCookieName } = await Promise.resolve().then(() => __importStar(require('./app-slug')));
+        validateCookieNameConsistency();
+        console.log('[STARTUP] Cookie name consistency validated:', getSessionCookieName());
+        // All done
+        console.log('');
+        console.log('╔══════════════════════════════════════════════════════════════╗');
+        console.log('║            PayEz Next MVP Ready for Requests                  ║');
+        console.log('╚══════════════════════════════════════════════════════════════╝');
+        console.log('');
+        initializationComplete = true;
+        initializationFailed = false;
+        lastInitError = null;
+    }
+    catch (error) {
+        lastInitError = error instanceof Error ? error : new Error(String(error));
+        initializationFailed = true;
+        const errorMsg = lastInitError.message || 'Unknown error';
+        const isConnectionError = errorMsg.includes('fetch failed') || errorMsg.includes('ECONNREFUSED');
+        const idpUrl = (process.env.IDP_URL || 'NOT SET').padEnd(46);
+        const clientId = (process.env.CLIENT_ID || 'NOT SET').padEnd(43);
+        const connectionLine = isConnectionError
+            ? '║   🔌 CONNECTION REFUSED - IDP appears to be down             ║\n║                                                              ║\n'
+            : '';
+        console.error(`
+╔══════════════════════════════════════════════════════════════╗
+║   ❌ FATAL: NEXTAUTH_SECRET NOT AVAILABLE                     ║
+║                                                              ║
+║   The app cannot start without a valid NEXTAUTH_SECRET.      ║
+║   This should be fetched from IDP at startup.                ║
+║                                                              ║
+${connectionLine}║   Possible causes:                                           ║
+║   • IDP is not running or unreachable                        ║
+║   • CLIENT_ID is not registered in IDP                       ║
+║   • IDP_URL is incorrect                                     ║
+║   • Network connectivity issue                               ║
+║                                                              ║
+║   Current config:                                            ║
+║   • IDP_URL: ${idpUrl}║
+║   • CLIENT_ID: ${clientId}║
+╚══════════════════════════════════════════════════════════════╝
+
+[STARTUP] Error: ${errorMsg}
+`);
+        // Re-throw so callers know initialization failed
+        throw lastInitError;
+    }
+}
+/**
+ * Get the cached IDP config after initialization.
+ * Returns null if not yet initialized.
+ */
+function getStartupIDPConfig() {
+    return cachedIDPConfig;
+}
+/**
+ * Check if initialization failed (NEXTAUTH_SECRET couldn't be retrieved)
+ */
+function isInitializationFailed() {
+    return initializationFailed;
+}
+/**
+ * Get the last initialization error
+ */
+function getInitializationError() {
+    return lastInitError;
+}
+/**
+ * Check if the app is ready to handle auth requests
+ */
+function isAppReady() {
+    return initializationComplete && !initializationFailed;
+}

package/dist/lib/test-aware-get-token.d.ts

@@ -0,0 +1,2 @@
+import { NextRequest } from 'next/server';
+export declare function getTokenTestAware(req: NextRequest): Promise<any>;

package/dist/lib/test-aware-get-token.js

@@ -0,0 +1,81 @@
+"use strict";
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTokenTestAware = getTokenTestAware;
+const jwt_1 = require("next-auth/jwt");
+const logger_1 = require("../config/logger");
+const nextauth_secret_1 = require("./nextauth-secret");
+const app_slug_1 = require("./app-slug");
+async function getTokenTestAware(req) {
+    let secret = process.env.NEXTAUTH_SECRET;
+    if (!secret || secret.trim() === '') {
+        try {
+            secret = await (0, nextauth_secret_1.resolveNextAuthSecret)();
+        }
+        catch (e) {
+            logger_1.logger.error('[GET_TOKEN] Failed to resolve NEXTAUTH_SECRET', { error: e instanceof Error ? e.message : String(e) });
+            return null;
+        }
+    }
+    if (process.env.TEST_MODE === 'true') {
+        try {
+            // Use app-slug prefixed cookie name (must match auth-options.ts)
+            const cookieName = (0, app_slug_1.getSessionCookieName)();
+            const cookies = req.headers.get('cookie');
+            if (!cookies) {
+                logger_1.logger.debug('[GET_TOKEN] No cookies in request');
+                return null;
+            }
+            const cookieValue = cookies.split(';').find(c => c.trim().startsWith(`${cookieName}=`))?.split('=')[1];
+            if (!cookieValue) {
+                logger_1.logger.debug('[GET_TOKEN] Session token cookie not found');
+                return null;
+            }
+            const { jwtVerify } = await Promise.resolve().then(() => __importStar(require('jose')));
+            const secretKey = new TextEncoder().encode(secret);
+            const { payload } = await jwtVerify(cookieValue, secretKey);
+            logger_1.logger.debug('[GET_TOKEN] TEST_MODE token decoded:', { hasPayload: !!payload, redisSessionId: payload.redisSessionId, sub: payload.sub });
+            return payload;
+        }
+        catch (error) {
+            logger_1.logger.error('[GET_TOKEN] TEST_MODE token decode error:', { error: error instanceof Error ? error.message : String(error) });
+            return null;
+        }
+    }
+    // Use app-slug prefixed cookie name (must match auth-options.ts)
+    // In production, NextAuth uses __Secure- prefix for cookies
+    const cookieName = process.env.NODE_ENV === 'production' ? (0, app_slug_1.getSecureSessionCookieName)() : (0, app_slug_1.getSessionCookieName)();
+    return await (0, jwt_1.getToken)({ req, secret, cookieName });
+}

package/dist/lib/token-expiry.d.ts

@@ -0,0 +1,14 @@
+export interface TokenExpiryOptions {
+    accessToken?: string;
+    refreshToken?: string;
+    preferJwt?: boolean;
+    fallbackAccessMs?: number;
+    fallbackRefreshMs?: number;
+}
+export interface TokenExpiryResult {
+    accessTokenExpires: number;
+    refreshTokenExpires?: number;
+    decodedAccessToken?: any;
+    decodedRefreshToken?: any;
+}
+export declare function computeTokenExpiries(opts: TokenExpiryOptions): TokenExpiryResult;

package/dist/lib/token-expiry.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeTokenExpiries = computeTokenExpiries;
+const jwt_decode_1 = require("./jwt-decode");
+const logger_1 = require("../config/logger");
+function computeTokenExpiries(opts) {
+    const { accessToken, refreshToken, preferJwt = true, fallbackAccessMs, fallbackRefreshMs } = opts;
+    let decodedAccessToken;
+    let decodedRefreshToken;
+    let accessMs;
+    let refreshMs;
+    if (preferJwt && accessToken) {
+        try {
+            decodedAccessToken = (0, jwt_decode_1.jwtDecode)(accessToken);
+            if (decodedAccessToken?.exp)
+                accessMs = decodedAccessToken.exp * 1000;
+        }
+        catch (e) {
+            logger_1.logger.warn('[TOKEN_EXPIRY] Failed to decode access token', { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    if (accessMs === undefined && typeof fallbackAccessMs === 'number')
+        accessMs = fallbackAccessMs;
+    if (preferJwt && refreshToken) {
+        try {
+            decodedRefreshToken = (0, jwt_decode_1.jwtDecode)(refreshToken);
+            if (decodedRefreshToken?.exp)
+                refreshMs = decodedRefreshToken.exp * 1000;
+        }
+        catch (e) {
+            logger_1.logger.warn('[TOKEN_EXPIRY] Failed to decode refresh token', { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    if (refreshMs === undefined && typeof fallbackRefreshMs === 'number')
+        refreshMs = fallbackRefreshMs;
+    if (typeof accessMs !== 'number')
+        accessMs = Date.now();
+    return { accessTokenExpires: accessMs, refreshTokenExpires: refreshMs, decodedAccessToken, decodedRefreshToken };
+}

package/dist/lib/token-lifecycle.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Token Lifecycle Management for @payez/next-mvp
+ *
+ * Ensures tokens are fresh before making API calls.
+ * Checks expiration and triggers refresh if needed.
+ *
+ * Pattern: Check first, refresh if needed, fail gracefully if refresh fails.
+ *
+ * HANDLES CONCURRENT REFRESH: When multiple API calls arrive simultaneously
+ * with expired tokens, only one will actually perform the refresh. Others
+ * receive 409 (conflict) and wait for the refresh to complete, then use
+ * the freshly refreshed tokens.
+ *
+ * REQUIRED: Your app must expose the refresh route:
+ * ```typescript
+ * // app/api/auth/refresh/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/refresh';
+ * ```
+ *
+ * @version 2.0.0
+ */
+import { NextRequest } from 'next/server';
+import { SessionData } from './session-store';
+export interface TokenResult {
+    success: true;
+    accessToken: string;
+    sessionData: SessionData;
+}
+export interface TokenError {
+    success: false;
+    error: 'NO_SESSION' | 'NO_TOKEN' | 'EXPIRED' | 'REFRESH_FAILED' | 'SESSION_EXPIRED_NO_REFRESH';
+    message: string;
+    terminal?: boolean;
+}
+export type EnsureFreshTokenResult = TokenResult | TokenError;
+export declare function ensureFreshToken(request: NextRequest): Promise<EnsureFreshTokenResult>;
+/**
+ * Get authorization header from fresh token.
+ * Convenience wrapper for API routes.
+ *
+ * @param request - The incoming NextRequest
+ * @returns Authorization header string or null if token unavailable
+ *
+ * @example
+ * ```typescript
+ * const authHeader = await getFreshAuthHeader(request);
+ * if (!authHeader) {
+ *   return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+ * }
+ * ```
+ */
+export declare function getFreshAuthHeader(request: NextRequest): Promise<string | null>;