@payez/next-mvp 3.0.0

package/dist/lib/app-slug.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * App Slug Utility for `@payez/next-mvp`
+ *
+ * Provides app-specific namespacing for Redis keys and cookies to prevent
+ * collisions when multiple MVP-based apps run on the same host (e.g., localhost).
+ *
+ * The slug is derived from:
+ * 1. APP_SLUG environment variable (preferred)
+ * 2. CLIENT_ID environment variable (fallback)
+ * 3. 'payez' (default fallback)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAppSlug = getAppSlug;
+exports.clearSlugCache = clearSlugCache;
+exports.getSessionPrefix = getSessionPrefix;
+exports.getAnonPrefix = getAnonPrefix;
+exports.getRefreshLockPrefix = getRefreshLockPrefix;
+exports.getSessionCookieName = getSessionCookieName;
+exports.getJwtCookieName = getJwtCookieName;
+exports.validateCookieNameConsistency = validateCookieNameConsistency;
+exports.getSecureSessionCookieName = getSecureSessionCookieName;
+exports.getAnonCookieName = getAnonCookieName;
+exports.getCsrfCookieName = getCsrfCookieName;
+exports.getSecureCsrfCookieName = getSecureCsrfCookieName;
+exports.getCallbackUrlCookieName = getCallbackUrlCookieName;
+let cachedSlug = null;
+/**
+ * Gets the app slug for namespacing.
+ * Caches the result for performance.
+ */
+function getAppSlug() {
+    if (cachedSlug !== null) {
+        return cachedSlug;
+    }
+    // Priority: APP_SLUG > CLIENT_ID > default
+    cachedSlug = process.env.APP_SLUG || process.env.CLIENT_ID || 'payez';
+    return cachedSlug;
+}
+/**
+ * Clears the cached slug (useful for testing).
+ */
+function clearSlugCache() {
+    cachedSlug = null;
+}
+// ============================================================================
+// Redis Key Prefixes
+// ============================================================================
+/**
+ * Gets the prefix for session keys.
+ * Format: {slug}:sess:
+ */
+function getSessionPrefix() {
+    return `${getAppSlug()}:sess:`;
+}
+/**
+ * Gets the prefix for anonymous session keys.
+ * Format: {slug}:anon:
+ */
+function getAnonPrefix() {
+    return `${getAppSlug()}:anon:`;
+}
+/**
+ * Gets the prefix for refresh lock keys.
+ * Format: {slug}:refresh_lock:
+ */
+function getRefreshLockPrefix() {
+    return `${getAppSlug()}:refresh_lock:`;
+}
+// ============================================================================
+// Cookie Names - SINGLE SOURCE OF TRUTH
+// ============================================================================
+//
+// CRITICAL: The session cookie name MUST be consistent between:
+//   1. auth-options.ts (where NextAuth SETS the cookie)
+//   2. getToken() calls (where we READ the cookie)
+//
+// If these don't match, sessions will appear empty in one environment but
+// work in another (e.g., works on localhost but fails in production).
+//
+// The ONLY cookie name for sessions is getSessionCookieName().
+// DO NOT use environment-specific variants for reading cookies.
+// ============================================================================
+/**
+ * THE session cookie name - SINGLE SOURCE OF TRUTH.
+ *
+ * This is used by:
+ * - auth-options.ts (cookies.sessionToken.name)
+ * - getToken() calls (cookieName parameter)
+ * - getJwtCookieName() (alias for consistency)
+ *
+ * Format: {slug}.session-token
+ */
+function getSessionCookieName() {
+    return `${getAppSlug()}.session-token`;
+}
+/**
+ * Gets the JWT cookie name for getToken() calls.
+ *
+ * CRITICAL: This MUST match what auth-options.ts configures:
+ * - Production: __Secure-{slug}.session-token
+ * - Development: {slug}.session-token
+ *
+ * This is the cookie name that getToken() should use to READ the JWT.
+ */
+function getJwtCookieName() {
+    // Must match auth-options.ts cookies.sessionToken.name logic
+    if (process.env.NODE_ENV === 'production') {
+        return getSecureSessionCookieName();
+    }
+    return getSessionCookieName();
+}
+/**
+ * Validates that cookie names are consistent with auth-options.ts.
+ * Call this at startup to catch mismatches early.
+ */
+function validateCookieNameConsistency() {
+    const jwtName = getJwtCookieName();
+    const expectedName = process.env.NODE_ENV === 'production'
+        ? getSecureSessionCookieName()
+        : getSessionCookieName();
+    if (jwtName !== expectedName) {
+        throw new Error(`[FATAL] Cookie name mismatch detected!\n` +
+            `  getJwtCookieName() = "${jwtName}"\n` +
+            `  Expected for ${process.env.NODE_ENV} = "${expectedName}"\n` +
+            `These MUST match or sessions will fail.`);
+    }
+}
+/**
+ * Gets the __Secure- prefixed cookie name.
+ *
+ * WARNING: This is ONLY for clearing cookies during logout.
+ * DO NOT use this for reading cookies - use getSessionCookieName().
+ * NextAuth does NOT automatically use this prefix.
+ *
+ * Format: __Secure-{slug}.session-token
+ */
+function getSecureSessionCookieName() {
+    return `__Secure-${getAppSlug()}.session-token`;
+}
+/**
+ * Gets the anonymous session cookie name.
+ * Format: {slug}_anon_id
+ */
+function getAnonCookieName() {
+    return `${getAppSlug()}_anon_id`;
+}
+/**
+ * Gets the CSRF token cookie name.
+ * Format: {slug}.csrf-token
+ */
+function getCsrfCookieName() {
+    return `${getAppSlug()}.csrf-token`;
+}
+/**
+ * Gets the __Host- prefixed CSRF cookie name.
+ *
+ * WARNING: This is ONLY for clearing cookies during logout.
+ * DO NOT use this for reading cookies - use getCsrfCookieName().
+ *
+ * Format: __Host-{slug}.csrf-token
+ */
+function getSecureCsrfCookieName() {
+    return `__Host-${getAppSlug()}.csrf-token`;
+}
+/**
+ * Gets the callback URL cookie name.
+ * Format: {slug}.callback-url
+ */
+function getCallbackUrlCookieName() {
+    return `${getAppSlug()}.callback-url`;
+}

package/dist/lib/demo-mode.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Demo mode utilities
+ * When DEMO_MODE=true, auth package is installed but not enforced
+ */
+export declare function isDemoMode(): boolean;
+export declare function isAuthConfigured(): boolean;

package/dist/lib/demo-mode.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Demo mode utilities
+ * When DEMO_MODE=true, auth package is installed but not enforced
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDemoMode = isDemoMode;
+exports.isAuthConfigured = isAuthConfigured;
+function isDemoMode() {
+    return process.env.DEMO_MODE === 'true' || process.env.NEXT_PUBLIC_DEMO_MODE === 'true';
+}
+function isAuthConfigured() {
+    if (isDemoMode())
+        return false;
+    return !!(process.env.NEXTAUTH_SECRET || (process.env.NEXT_CLIENT_ID && process.env.NEXT_CLIENT_PRIVATE_KEY_PEM));
+}

package/dist/lib/geolocation.d.ts

@@ -0,0 +1,64 @@
+/**
+ * =============================================================================
+ * GEOLOCATION UTILITY
+ * =============================================================================
+ *
+ * Server-side utility for resolving IP addresses to geographic locations.
+ * Uses ip-api.com (free tier: 45 requests/minute).
+ *
+ * USAGE:
+ * ------
+ * import { getLocationFromIP, extractClientIP } from '@payez/next-mvp/lib/geolocation';
+ *
+ * const ip = extractClientIP(request.headers);
+ * const location = await getLocationFromIP(ip);
+ * console.log(location?.city); // 'Mountain View'
+ *
+ * =============================================================================
+ */
+export interface LocationInfo {
+    city?: string;
+    region?: string;
+    country?: string;
+    countryCode?: string;
+    latitude?: number;
+    longitude?: number;
+    timezone?: string;
+    isp?: string;
+}
+/**
+ * Check if an IP address is private/local (not routable on the internet)
+ */
+export declare function isPrivateIP(ip: string): boolean;
+/**
+ * Fetch the public IP address of the server/network.
+ * Useful for development when the detected IP is a private/local IP.
+ */
+export declare function getPublicIP(): Promise<string | null>;
+/**
+ * Extract the client IP from request headers.
+ * Handles various proxy headers in order of priority.
+ */
+export declare function extractClientIP(headers: Headers): string;
+/**
+ * Get geographic location from an IP address.
+ * Uses ip-api.com free tier (45 req/min, no API key required).
+ * Results are cached for 1 hour.
+ *
+ * @param ip - The IP address to look up
+ * @param resolvePublicIP - If true and IP is private, attempt to resolve the public IP
+ * @returns Location info or null if lookup failed
+ */
+export declare function getLocationFromIP(ip: string, resolvePublicIP?: boolean): Promise<LocationInfo | null>;
+/**
+ * Format a location object as a readable string
+ */
+export declare function formatLocation(location?: LocationInfo | null): string;
+/**
+ * Get country flag emoji from country code
+ */
+export declare function getCountryFlag(countryCode?: string): string;
+/**
+ * Clear the geolocation cache (useful for testing)
+ */
+export declare function clearGeoCache(): void;

package/dist/lib/geolocation.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * =============================================================================
+ * GEOLOCATION UTILITY
+ * =============================================================================
+ *
+ * Server-side utility for resolving IP addresses to geographic locations.
+ * Uses ip-api.com (free tier: 45 requests/minute).
+ *
+ * USAGE:
+ * ------
+ * import { getLocationFromIP, extractClientIP } from '@payez/next-mvp/lib/geolocation';
+ *
+ * const ip = extractClientIP(request.headers);
+ * const location = await getLocationFromIP(ip);
+ * console.log(location?.city); // 'Mountain View'
+ *
+ * =============================================================================
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrivateIP = isPrivateIP;
+exports.getPublicIP = getPublicIP;
+exports.extractClientIP = extractClientIP;
+exports.getLocationFromIP = getLocationFromIP;
+exports.formatLocation = formatLocation;
+exports.getCountryFlag = getCountryFlag;
+exports.clearGeoCache = clearGeoCache;
+// -----------------------------------------------------------------------------
+// CACHE CONFIGURATION
+// -----------------------------------------------------------------------------
+// In-memory cache for IP geolocation (reduces API calls)
+const geoCache = new Map();
+const CACHE_TTL = 1000 * 60 * 60; // 1 hour
+// Cache for public IP lookup (to avoid repeated calls)
+let cachedPublicIP = null;
+const PUBLIC_IP_CACHE_TTL = 1000 * 60 * 30; // 30 minutes
+// -----------------------------------------------------------------------------
+// HELPERS
+// -----------------------------------------------------------------------------
+/**
+ * Check if an IP address is private/local (not routable on the internet)
+ */
+function isPrivateIP(ip) {
+    if (!ip)
+        return true;
+    // IPv6 loopback
+    if (ip === '::1')
+        return true;
+    // IPv4 loopback
+    if (ip === '127.0.0.1' || ip.startsWith('127.'))
+        return true;
+    // Private IPv4 ranges
+    if (ip.startsWith('192.168.'))
+        return true;
+    if (ip.startsWith('10.'))
+        return true;
+    if (ip.startsWith('172.')) {
+        const secondOctet = parseInt(ip.split('.')[1], 10);
+        if (secondOctet >= 16 && secondOctet <= 31)
+            return true;
+    }
+    // Link-local
+    if (ip.startsWith('169.254.'))
+        return true;
+    return false;
+}
+/**
+ * Fetch the public IP address of the server/network.
+ * Useful for development when the detected IP is a private/local IP.
+ */
+async function getPublicIP() {
+    // Check cache first
+    if (cachedPublicIP && Date.now() - cachedPublicIP.timestamp < PUBLIC_IP_CACHE_TTL) {
+        return cachedPublicIP.ip;
+    }
+    // List of services to try (all return plain text IP)
+    const services = [
+        'https://api.ipify.org',
+        'https://icanhazip.com',
+        'https://ifconfig.me/ip',
+        'https://ipecho.net/plain',
+    ];
+    for (const service of services) {
+        try {
+            const response = await fetch(service, {
+                signal: AbortSignal.timeout(3000),
+            });
+            if (response.ok) {
+                const ip = (await response.text()).trim();
+                // Validate it looks like an IP
+                if (ip && /^[\d.]+$/.test(ip) || /^[a-f0-9:]+$/i.test(ip)) {
+                    cachedPublicIP = { ip, timestamp: Date.now() };
+                    console.log(`[geolocation] Public IP resolved: ${ip}`);
+                    return ip;
+                }
+            }
+        }
+        catch {
+            // Try next service
+            continue;
+        }
+    }
+    console.warn('[geolocation] Failed to resolve public IP from all services');
+    return null;
+}
+/**
+ * Extract the client IP from request headers.
+ * Handles various proxy headers in order of priority.
+ */
+function extractClientIP(headers) {
+    // Try headers in order of reliability
+    const forwardedFor = headers.get('x-forwarded-for');
+    if (forwardedFor) {
+        // Take the first IP (original client)
+        const firstIP = forwardedFor.split(',')[0]?.trim();
+        if (firstIP)
+            return firstIP;
+    }
+    const realIP = headers.get('x-real-ip');
+    if (realIP)
+        return realIP.trim();
+    const cfConnectingIP = headers.get('cf-connecting-ip'); // Cloudflare
+    if (cfConnectingIP)
+        return cfConnectingIP.trim();
+    const trueClientIP = headers.get('true-client-ip'); // Akamai/Cloudflare
+    if (trueClientIP)
+        return trueClientIP.trim();
+    // Fallback
+    return '127.0.0.1';
+}
+// -----------------------------------------------------------------------------
+// MAIN FUNCTION
+// -----------------------------------------------------------------------------
+/**
+ * Get geographic location from an IP address.
+ * Uses ip-api.com free tier (45 req/min, no API key required).
+ * Results are cached for 1 hour.
+ *
+ * @param ip - The IP address to look up
+ * @param resolvePublicIP - If true and IP is private, attempt to resolve the public IP
+ * @returns Location info or null if lookup failed
+ */
+async function getLocationFromIP(ip, resolvePublicIP = true) {
+    // Handle private/local IPs
+    if (isPrivateIP(ip)) {
+        // In development, try to get the actual public IP for geolocation
+        if (resolvePublicIP) {
+            const publicIP = await getPublicIP();
+            if (publicIP && !isPrivateIP(publicIP)) {
+                console.log(`[geolocation] Private IP ${ip} -> using public IP ${publicIP}`);
+                // Recursively call with public IP (but don't resolve again to prevent loops)
+                return getLocationFromIP(publicIP, false);
+            }
+        }
+        // Fallback to local indicator
+        return {
+            city: 'Local',
+            region: 'Development',
+            country: 'Local',
+            countryCode: 'LO',
+        };
+    }
+    // Check cache
+    const cached = geoCache.get(ip);
+    if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+        return cached.location;
+    }
+    try {
+        // ip-api.com free endpoint
+        const response = await fetch(`http://ip-api.com/json/${ip}?fields=status,message,country,countryCode,region,regionName,city,lat,lon,timezone,isp`, {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            console.error(`[geolocation] HTTP error: ${response.status}`);
+            return null;
+        }
+        const data = await response.json();
+        if (data.status !== 'success') {
+            console.warn(`[geolocation] Lookup failed for ${ip}: ${data.message}`);
+            // Cache the failure to avoid repeated lookups
+            geoCache.set(ip, { location: null, timestamp: Date.now() });
+            return null;
+        }
+        const location = {
+            city: data.city,
+            region: data.regionName,
+            country: data.country,
+            countryCode: data.countryCode,
+            latitude: data.lat,
+            longitude: data.lon,
+            timezone: data.timezone,
+            isp: data.isp,
+        };
+        // Cache the result
+        geoCache.set(ip, { location, timestamp: Date.now() });
+        return location;
+    }
+    catch (error) {
+        console.error(`[geolocation] Error looking up ${ip}:`, error);
+        return null;
+    }
+}
+/**
+ * Format a location object as a readable string
+ */
+function formatLocation(location) {
+    if (!location)
+        return 'Unknown';
+    const parts = [location.city, location.region, location.countryCode].filter(Boolean);
+    return parts.length > 0 ? parts.join(', ') : 'Unknown';
+}
+/**
+ * Get country flag emoji from country code
+ */
+function getCountryFlag(countryCode) {
+    if (!countryCode || countryCode === 'LO')
+        return '🏠'; // Local/development
+    try {
+        // Convert country code to flag emoji (e.g., 'US' -> 🇺🇸)
+        const codePoints = countryCode
+            .toUpperCase()
+            .split('')
+            .map(char => 127397 + char.charCodeAt(0));
+        return String.fromCodePoint(...codePoints);
+    }
+    catch {
+        return '🌍';
+    }
+}
+/**
+ * Clear the geolocation cache (useful for testing)
+ */
+function clearGeoCache() {
+    geoCache.clear();
+}

package/dist/lib/idp-client-config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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';
+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;
+}
+/**
+ * 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 declare function getIDPClientConfig(forceRefresh?: boolean): Promise<IDPClientConfig>;
+/**
+ * Clear the config cache (useful for testing or forced refresh)
+ */
+export declare function clearConfigCache(): void;
+/**
+ * Get enabled OAuth providers from config
+ */
+export declare function getEnabledProviders(config: IDPClientConfig): OAuthProviderConfig[];