@payez/next-mvp 3.0.0

package/src/lib/app-slug.ts

@@ -0,0 +1,178 @@
+/**
+ * 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)
+ */
+
+let cachedSlug: string | null = null;
+
+
+/**
+ * Gets the app slug for namespacing.
+ * Caches the result for performance.
+ */
+export function getAppSlug(): string {
+  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).
+ */
+export function clearSlugCache(): void {
+  cachedSlug = null;
+}
+
+// ============================================================================
+// Redis Key Prefixes
+// ============================================================================
+
+/**
+ * Gets the prefix for session keys.
+ * Format: {slug}:sess:
+ */
+export function getSessionPrefix(): string {
+  return `${getAppSlug()}:sess:`;
+}
+
+/**
+ * Gets the prefix for anonymous session keys.
+ * Format: {slug}:anon:
+ */
+export function getAnonPrefix(): string {
+  return `${getAppSlug()}:anon:`;
+}
+
+/**
+ * Gets the prefix for refresh lock keys.
+ * Format: {slug}:refresh_lock:
+ */
+export function getRefreshLockPrefix(): string {
+  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
+ */
+export function getSessionCookieName(): string {
+  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.
+ */
+export function getJwtCookieName(): string {
+  // 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.
+ */
+export function validateCookieNameConsistency(): void {
+  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
+ */
+export function getSecureSessionCookieName(): string {
+  return `__Secure-${getAppSlug()}.session-token`;
+}
+
+/**
+ * Gets the anonymous session cookie name.
+ * Format: {slug}_anon_id
+ */
+export function getAnonCookieName(): string {
+  return `${getAppSlug()}_anon_id`;
+}
+
+/**
+ * Gets the CSRF token cookie name.
+ * Format: {slug}.csrf-token
+ */
+export function getCsrfCookieName(): string {
+  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
+ */
+export function getSecureCsrfCookieName(): string {
+  return `__Host-${getAppSlug()}.csrf-token`;
+}
+
+/**
+ * Gets the callback URL cookie name.
+ * Format: {slug}.callback-url
+ */
+export function getCallbackUrlCookieName(): string {
+  return `${getAppSlug()}.callback-url`;
+}

package/src/lib/demo-mode.ts

@@ -0,0 +1,13 @@
+/**
+ * Demo mode utilities
+ * When DEMO_MODE=true, auth package is installed but not enforced
+ */
+
+export function isDemoMode(): boolean {
+  return process.env.DEMO_MODE === 'true' || process.env.NEXT_PUBLIC_DEMO_MODE === 'true';
+}
+
+export function isAuthConfigured(): boolean {
+  if (isDemoMode()) return false;
+  return !!(process.env.NEXTAUTH_SECRET || (process.env.NEXT_CLIENT_ID && process.env.NEXT_CLIENT_PRIVATE_KEY_PEM));
+}

package/src/lib/geolocation.ts

@@ -0,0 +1,265 @@
+/**
+ * =============================================================================
+ * 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'
+ *
+ * =============================================================================
+ */
+
+// -----------------------------------------------------------------------------
+// TYPES
+// -----------------------------------------------------------------------------
+
+export interface LocationInfo {
+  city?: string;
+  region?: string;
+  country?: string;
+  countryCode?: string;
+  latitude?: number;
+  longitude?: number;
+  timezone?: string;
+  isp?: string;
+}
+
+// -----------------------------------------------------------------------------
+// CACHE CONFIGURATION
+// -----------------------------------------------------------------------------
+
+// In-memory cache for IP geolocation (reduces API calls)
+const geoCache = new Map<string, { location: LocationInfo | null; timestamp: number }>();
+const CACHE_TTL = 1000 * 60 * 60; // 1 hour
+
+// Cache for public IP lookup (to avoid repeated calls)
+let cachedPublicIP: { ip: string; timestamp: number } | null = 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)
+ */
+export function isPrivateIP(ip: string): boolean {
+  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.
+ */
+export async function getPublicIP(): Promise<string | null> {
+  // 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.
+ */
+export function extractClientIP(headers: Headers): string {
+  // 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
+ */
+export async function getLocationFromIP(ip: string, resolvePublicIP: boolean = true): Promise<LocationInfo | null> {
+  // 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: LocationInfo = {
+      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
+ */
+export function formatLocation(location?: LocationInfo | null): string {
+  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
+ */
+export function getCountryFlag(countryCode?: string): string {
+  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)
+ */
+export function clearGeoCache(): void {
+  geoCache.clear();
+}