@payez/next-mvp 4.0.0 → 4.0.1

package/dist/lib/app-slug.js

@@ -1,172 +0,0 @@
-"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. better-auth.ts (where auth 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:
- * - better-auth.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 the auth config sets:
- * - 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 config cookies.sessionToken.name logic
-    if (process.env.NODE_ENV === 'production') {
-        return getSecureSessionCookieName();
-    }
-    return getSessionCookieName();
-}
-/**
- * Validates that cookie names are consistent with the auth config.
- * 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().
- * Auth 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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1,16 +0,0 @@
-"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

@@ -1,64 +0,0 @@
-/**
- * =============================================================================
- * 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

@@ -1,235 +0,0 @@
-"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

@@ -1,75 +0,0 @@
-/**
- * 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: string;
-    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[];