@payez/next-mvp 3.0.0

package/src/components/ui/Footer.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import React from 'react';
+
+export interface FooterProps {
+  /** Company or product name (default: 'PayEz') */
+  companyName?: string;
+  /** Start year for copyright range (shows "2024-2025" format if provided) */
+  startYear?: number;
+  /** Additional links to display */
+  links?: Array<{ label: string; href: string }>;
+  /** Additional CSS classes */
+  className?: string;
+  /** Variant style */
+  variant?: 'minimal' | 'standard';
+}
+
+/**
+ * A themeable footer component with dynamic copyright year.
+ *
+ * @example
+ * ```tsx
+ * // Minimal footer
+ * <Footer />
+ *
+ * // With company name and start year
+ * <Footer companyName="Acme Inc" startYear={2020} />
+ *
+ * // With links
+ * <Footer
+ *   links={[
+ *     { label: 'Privacy', href: '/privacy' },
+ *     { label: 'Terms', href: '/terms' }
+ *   ]}
+ * />
+ * ```
+ */
+export function Footer({
+  companyName = 'PayEz',
+  startYear,
+  links = [],
+  className = '',
+  variant = 'minimal'
+}: FooterProps) {
+  const currentYear = new Date().getFullYear();
+  const yearDisplay = startYear && startYear < currentYear
+    ? `${startYear}-${currentYear}`
+    : `${currentYear}`;
+
+  const baseStyles = 'w-full py-4 text-sm';
+
+  const variantStyles = {
+    minimal: 'text-center text-gray-500 dark:text-gray-400',
+    standard: 'border-t border-gray-200 dark:border-gray-700 text-gray-500 dark:text-gray-400'
+  };
+
+  if (variant === 'minimal') {
+    return (
+      <footer className={`${baseStyles} ${variantStyles[variant]} ${className}`}>
+        <p>
+          &copy; {yearDisplay} {companyName}. All rights reserved.
+        </p>
+      </footer>
+    );
+  }
+
+  return (
+    <footer className={`${baseStyles} ${variantStyles[variant]} ${className}`}>
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="flex flex-col sm:flex-row justify-between items-center gap-4">
+          <p>
+            &copy; {yearDisplay} {companyName}. All rights reserved.
+          </p>
+          {links.length > 0 && (
+            <nav className="flex gap-4" aria-label="Footer links">
+              {links.map((link, index) => (
+                <a
+                  key={`${index}-${link.label}`}
+                  href={link.href}
+                  className="hover:text-gray-700 dark:hover:text-gray-200 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 dark:focus:ring-offset-gray-900 rounded transition-colors"
+                >
+                  {link.label}
+                </a>
+              ))}
+            </nav>
+          )}
+        </div>
+      </div>
+    </footer>
+  );
+}
+
+export default Footer;

package/src/config/env.ts

@@ -0,0 +1,57 @@
+export const ENV_CONFIG = {
+  CLIENT_ID: process.env.CLIENT_ID,
+  INTERNAL_URL: process.env.IDP_URL,
+  IDP_CLIENT_ID: (() => { const raw = process.env.NEXT_PUBLIC_IDP_CLIENT_ID || process.env.IDP_CLIENT_ID; const n = raw ? parseInt(raw, 10) : undefined; return Number.isFinite(n as any) ? (n as number) : undefined; })(),
+  IDP_URL: process.env.IDP_URL,
+  API_URL: process.env.IDP_URL,
+  PAYEZ_CORE_BASE_URL: process.env.NEXT_PUBLIC_PAYEZ_CORE_BASE_URL,
+  SUPPORT_EMAIL: 'support@PayEz.net',
+  LOG_LEVEL: process.env.LOG_LEVEL || 'info',
+  LOG_CONSOLE: process.env.LOG_CONSOLE === 'true' || process.env.NODE_ENV === 'development',
+  GRAYLOG_HOST: process.env.GRAYLOG_HOST || '10.6.10.5',
+  GRAYLOG_PORT: parseInt(process.env.GRAYLOG_PORT || '12201'),
+
+  // Redis key prefix for multi-tenant session isolation
+  // Each application should have a unique prefix to prevent session conflicts
+  // Example: 'cryptaply:', 'website-membership:', 'myapp:'
+  // Leave empty ('') for backward compatibility
+  REDIS_KEY_PREFIX: process.env.REDIS_KEY_PREFIX || '',
+
+  // Redirect URLs - configurable per-tenant
+  // LOGOUT_REDIRECT_URL: Where to redirect after logout (default: '/')
+  // UNAUTHENTICATED_REDIRECT_URL: Where to redirect unauthenticated users from root (default: '/account-auth/login')
+  LOGOUT_REDIRECT_URL: process.env.LOGOUT_REDIRECT_URL || '/',
+  UNAUTHENTICATED_REDIRECT_URL: process.env.UNAUTHENTICATED_REDIRECT_URL || '/account-auth/login',
+} as const;
+
+export const API_ENDPOINTS = {
+  account: {
+    profile: '/api/account/profile',
+    updateProfile: '/api/account/profile',
+    maskedInfo: '/api/account/masked-info',
+    sendResetCode: '/api/account/send-reset-code',
+    verifyResetCode: '/api/account/verify-reset-code',
+    resetPassword: '/api/account/reset-password',
+    changePassword: '/api/account/change-password',
+    validatePassword: '/api/account/validate-password'
+  },
+  externalAuth: {
+    login: '/api/ExternalAuth/login',
+    refresh: '/api/ExternalAuth/refresh',
+    validate: '/api/ExternalAuth/validate',
+    verifyCode: '/api/ExternalAuth/verify-code',
+    revoke: '/api/ExternalAuth/revoke',
+    roles: (username: string) => `/api/ExternalAuth/roles/${username}`,
+    jwks: '/api/ExternalAuth/.well-known/jwks.json',
+    openidConfig: '/api/ExternalAuth/.well-known/openid-configuration',
+    passwordless: {
+      sms: { start: '/api/ExternalAuth/passwordless/sms/start', login: '/api/ExternalAuth/passwordless/sms/login', resend: '/api/ExternalAuth/passwordless/sms/resend' },
+      email: { start: '/api/ExternalAuth/passwordless/email/start', login: '/api/ExternalAuth/passwordless/email/login', resend: '/api/ExternalAuth/passwordless/email/resend' }
+    },
+    lead: { registration: '/api/ExternalAuth/lead/registration', verify: '/api/ExternalAuth/lead/verify' }
+  },
+  progressiveAuth: {
+    step1: '/api/ProgressiveAuth/step1', step2: '/api/ProgressiveAuth/step2', step3: '/api/ProgressiveAuth/step3', step4: '/api/ProgressiveAuth/step4', step5: '/api/ProgressiveAuth/step5', verifyEmail: '/api/ProgressiveAuth/verify-email'
+  },
+  azureAuth: { login: '/auth/azure/login', logout: '/auth/azure/logout' }
+} as const;

package/src/config/logger.ts

@@ -0,0 +1,62 @@
+import { getLoggingConfigSync, startConfigWatching, addConfigWatcher } from './logging-config';
+import { LoggingConfig } from '../types/logging';
+import { createVibeLogTransport } from './vibe-log-transport';
+
+let loggingConfig: LoggingConfig = getLoggingConfigSync();
+startConfigWatching();
+
+const isEdgeRuntime = (): boolean => {
+  return typeof (globalThis as any).EdgeRuntime !== 'undefined' || process.env.NEXT_RUNTIME === 'edge';
+};
+const isBrowser = (): boolean => typeof window !== 'undefined';
+
+interface Logger { error: (message: string, meta?: any) => void; warn: (message: string, meta?: any) => void; info: (message: string, meta?: any) => void; http: (message: string, meta?: any) => void; debug: (message: string, meta?: any) => void; }
+
+class EdgeLogger implements Logger {
+  private logLevel: string = loggingConfig.logLevel; private levelOrder: string[] = Object.keys(loggingConfig.levels);
+  private shouldLog(level: string): boolean { const currentLevelIndex = this.levelOrder.indexOf(this.logLevel); const messageLevelIndex = this.levelOrder.indexOf(level); return messageLevelIndex <= currentLevelIndex; }
+  private format(level: string, message: string, meta?: any) { const timestamp = new Date().toISOString(); const metaString = meta ? ` ${JSON.stringify(meta)}` : ''; return `[${timestamp}] ${level.toUpperCase()}: ${message}${metaString}`; }
+  error(m: string, meta?: any) { if (this.shouldLog('error')) console.error(this.format('error', m, meta)); }
+  warn(m: string, meta?: any) { if (this.shouldLog('warn')) console.warn(this.format('warn', m, meta)); }
+  info(m: string, meta?: any) { if (this.shouldLog('info')) console.info(this.format('info', m, meta)); }
+  http(m: string, meta?: any) { if (this.shouldLog('http')) console.log(this.format('http', m, meta)); }
+  debug(m: string, meta?: any) { if (this.shouldLog('debug')) console.debug(this.format('debug', m, meta)); }
+}
+
+const createLogger = (): any => {
+  if (isEdgeRuntime()) return new EdgeLogger();
+  if (isBrowser()) return { error: (m: string, meta?: any) => console.error(m, meta), warn: (m: string, meta?: any) => console.warn(m, meta), info: (m: string, meta?: any) => console.info(m, meta), http: (m: string, meta?: any) => console.log(m, meta), debug: (m: string, meta?: any) => console.debug(m, meta) };
+  try {
+    const winston = require('winston');
+    const transports: any[] = [];
+    if (loggingConfig.console.enabled) {
+      transports.push(new winston.transports.Console({ format: winston.format.combine(winston.format.colorize({ all: true }), winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.printf(({ timestamp, level, message, ...meta }: any) => { const metaString = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : ''; return `[${timestamp}] ${level}: ${message}${metaString}`; })) }));
+    }
+    // Add Vibe log transport (sends warn/error to Redis for drain to Vibe)
+    const vibeTransport = createVibeLogTransport({ minLevel: 'warn' });
+    if (vibeTransport) {
+      transports.push(vibeTransport);
+      console.log('[LOGGER] Vibe Redis transport ENABLED - logs will buffer to Redis');
+    } else {
+      console.log('[LOGGER] Vibe Redis transport DISABLED - no REDIS_URL configured');
+    }
+    return winston.createLogger({ level: loggingConfig.logLevel, levels: loggingConfig.levels, format: winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.json()), transports, exitOnError: false });
+  } catch (error) { console.warn('Failed to initialize Winston logger, falling back to EdgeLogger:', error); return new EdgeLogger(); }
+};
+
+let logger: any;
+if (!globalThis.process?.browser) {
+  logger = createLogger();
+  addConfigWatcher((updatedConfig) => { loggingConfig = updatedConfig; if (logger && logger.level !== undefined) { logger.level = loggingConfig.logLevel; } });
+} else { logger = console; }
+
+export const log = { error: (m: string, meta?: any) => logger.error(m, meta), warn: (m: string, meta?: any) => logger.warn(m, meta), info: (m: string, meta?: any) => logger.info(m, meta), http: (m: string, meta?: any) => logger.http(m, meta), debug: (m: string, meta?: any) => logger.debug(m, meta) };
+export { logger };
+export const authLogger = { error: (m: string, meta?: any) => logger.error(`[AUTH] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[AUTH] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[AUTH] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[AUTH] ${m}`, meta) };
+export const idpLogger = { error: (m: string, meta?: any) => logger.error(`[IDP] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[IDP] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[IDP] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[IDP] ${m}`, meta) };
+export const apiLogger = { error: (m: string, meta?: any) => logger.error(`[API] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[API] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[API] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[API] ${m}`, meta) };
+export const circuitBreakerLogger = { error: (m: string, meta?: any) => logger.error(`[CIRCUIT-BREAKER] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[CIRCUIT-BREAKER] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[CIRCUIT-BREAKER] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[CIRCUIT-BREAKER] ${m}`, meta) };
+export const tokenLogger = { error: (m: string, meta?: any) => logger.error(`[TOKEN] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[TOKEN] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[TOKEN] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[TOKEN] ${m}`, meta) };
+export const tokenSyncLogger = { error: (m: string, meta?: any) => logger.error(`[TOKEN-SYNC] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[TOKEN-SYNC] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[TOKEN-SYNC] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[TOKEN-SYNC] ${m}`, meta) };
+export const tokenRefreshLogger = { error: (m: string, meta?: any) => logger.error(`[TOKEN-REFRESH] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[TOKEN-REFRESH] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[TOKEN-REFRESH] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[TOKEN-REFRESH] ${m}`, meta) };
+export const redisLogger = { error: (m: string, meta?: any) => logger.error(`[REDIS] ${m}`, meta), warn: (m: string, meta?: any) => logger.warn(`[REDIS] ${m}`, meta), info: (m: string, meta?: any) => logger.info(`[REDIS] ${m}`, meta), debug: (m: string, meta?: any) => logger.debug(`[REDIS] ${m}`, meta) };

package/src/config/logging-config.ts

@@ -0,0 +1,82 @@
+import { promises as fs } from 'fs';
+import { watch, existsSync } from 'fs';
+import { LoggingConfig, LogLevel } from '../types/logging';
+
+const isEdgeRuntime = typeof (globalThis as any).EdgeRuntime !== 'undefined' || process.env.NEXT_RUNTIME === 'edge';
+
+class LoggingConfigManager {
+  private config: LoggingConfig | null = null;
+  private configPath: string;
+  private watchers: Set<(config: LoggingConfig) => void> = new Set();
+  private fileWatcher: ReturnType<typeof watch> | null = null;
+  private isEdgeRuntime: boolean;
+  private isBrowser: boolean;
+
+  constructor() {
+    this.isBrowser = typeof window !== 'undefined';
+    this.isEdgeRuntime = typeof (globalThis as any).EdgeRuntime !== 'undefined' || process.env.NEXT_RUNTIME === 'edge';
+    if (this.isEdgeRuntime || this.isBrowser) {
+      this.configPath = '/config/logging.json';
+      this.config = this.getDefaultConfig();
+    } else {
+      const cwd = process.cwd().replace(/\\/g, '/');
+      this.configPath = cwd + '/config/logging.json';
+    }
+  }
+
+  async loadConfig(): Promise<LoggingConfig> {
+    if (this.isEdgeRuntime || this.isBrowser) {
+      if (!this.config) { this.config = this.getDefaultConfig(); }
+      return this.config;
+    }
+    try {
+      const configContent = await fs.readFile(this.configPath, 'utf-8');
+      const rawConfig = JSON.parse(configContent);
+      const config = this.validateAndMergeConfig(rawConfig);
+      this.config = config; this.notifyWatchers(config); return config;
+    } catch (error) {
+      console.warn(`Failed to load logging config from ${this.configPath}:`, error);
+      return this.getDefaultConfig();
+    }
+  }
+
+  async getConfig(): Promise<LoggingConfig> { if (!this.config) { return await this.loadConfig(); } return this.config; }
+  getConfigSync(): LoggingConfig { return this.config || this.getDefaultConfig(); }
+
+  startWatching(): void { if (this.isEdgeRuntime || this.isBrowser) { return; } if (this.fileWatcher) { return; } try { if (!existsSync(this.configPath)) { console.warn(`Logging config file not found at ${this.configPath} — watch disabled`); return; } this.fileWatcher = watch(this.configPath, { persistent: false }, (eventType) => { if (eventType === 'change') { this.loadConfig().catch(console.error); } }); } catch (error) { console.warn('Failed to start watching logging config file:', error); } }
+  stopWatching(): void { if (this.isEdgeRuntime || this.isBrowser) { return; } if (this.fileWatcher) { this.fileWatcher.close(); this.fileWatcher = null; } }
+  addWatcher(callback: (config: LoggingConfig) => void): void { this.watchers.add(callback); }
+  removeWatcher(callback: (config: LoggingConfig) => void): void { this.watchers.delete(callback); }
+  private notifyWatchers(config: LoggingConfig): void { this.watchers.forEach(cb => { try { cb(config); } catch (error) { console.error('Error in logging config watcher:', error); } }); }
+
+  private validateAndMergeConfig(rawConfig: any): LoggingConfig {
+    const defaults = this.getDefaultConfig();
+    const config: LoggingConfig = {
+      logLevel: this.validateLogLevel(rawConfig.logLevel) || this.validateLogLevel(process.env.LOG_LEVEL) || defaults.logLevel,
+      console: { enabled: rawConfig.console?.enabled ?? (process.env.LOG_CONSOLE === 'true' || process.env.NODE_ENV === 'development'), colors: rawConfig.console?.colors ?? defaults.console.colors },
+      graylog: { enabled: false, host: defaults.graylog.host, port: defaults.graylog.port, facility: defaults.graylog.facility, staticMeta: { ...defaults.graylog.staticMeta } },
+      components: { ...defaults.components, ...rawConfig.components },
+      levels: { ...defaults.levels, ...rawConfig.levels }
+    };
+    return config;
+  }
+  private validateLogLevel(level: any): LogLevel | null { const validLevels: LogLevel[] = ['error', 'warn', 'info', 'http', 'debug']; return validLevels.includes(level) ? level : null; }
+  private getHostname(): string { if (this.isEdgeRuntime) return 'edge-runtime'; if (this.isBrowser) return 'browser-client'; try { return require('os').hostname(); } catch { return 'unknown'; } }
+  private getDefaultConfig(): LoggingConfig {
+    return {
+      logLevel: 'info',
+      console: { enabled: process.env.NODE_ENV === 'development', colors: true },
+      graylog: { enabled: false, host: '127.0.0.1', port: 12201, facility: 'next-mvp', staticMeta: { service: 'next-mvp', application: 'next-mvp', version: '1.0.0', environment: process.env.NODE_ENV || 'development', hostname: this.getHostname(), instance: process.env.NEXT_INSTANCE_ID || 'unknown' } },
+      components: { auth: { enabled: true, prefix: '[AUTH]' }, idp: { enabled: true, prefix: '[IDP]' }, api: { enabled: true, prefix: '[API]' }, circuitBreaker: { enabled: true, prefix: '[CIRCUIT-BREAKER]' }, token: { enabled: true, prefix: '[TOKEN]' }, tokenSync: { enabled: true, prefix: '[TOKEN-SYNC]' }, tokenRefresh: { enabled: true, prefix: '[TOKEN-REFRESH]' }, redis: { enabled: true, prefix: '[REDIS]' } },
+      levels: { error: 0, warn: 1, info: 2, http: 3, debug: 4 }
+    };
+  }
+}
+
+export const loggingConfigManager = new LoggingConfigManager();
+export const getLoggingConfig = () => loggingConfigManager.getConfig();
+export const getLoggingConfigSync = () => loggingConfigManager.getConfigSync();
+export const startConfigWatching = () => loggingConfigManager.startWatching();
+export const stopConfigWatching = () => loggingConfigManager.stopWatching();
+export const addConfigWatcher = (callback: (config: LoggingConfig) => void) => loggingConfigManager.addWatcher(callback);
+export const removeConfigWatcher = (callback: (config: LoggingConfig) => void) => loggingConfigManager.removeWatcher(callback);

package/src/config/unauthenticated-routes.ts

@@ -0,0 +1,19 @@
+export interface UnauthenticatedRouteConfig { pattern: string; description: string; allowDuringCircuitBreakerOpen?: boolean; requiresRateLimit?: boolean; }
+export const UNAUTHENTICATED_ROUTES: UnauthenticatedRouteConfig[] = [
+  { pattern: '/account-auth/*', description: 'All authentication pages', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/account-auth/login', description: 'Login page', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/account-auth/verify-code', description: '2FA page', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/api/auth/*', description: 'Auth API endpoints', allowDuringCircuitBreakerOpen: true, requiresRateLimit: true },
+  { pattern: '/api/session/refresh-viability', description: 'Refresh viability check', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/landing', description: 'Public landing', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/service-unavailable', description: 'Service unavailable', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/favicon.ico', description: 'Favicon', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/robots.txt', description: 'Robots.txt', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/sitemap.xml', description: 'Sitemap', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/_next/*', description: 'Next.js assets', allowDuringCircuitBreakerOpen: true },
+  { pattern: '/public/*', description: 'Public assets', allowDuringCircuitBreakerOpen: true }
+];
+export function isUnauthenticatedRoute(pathname: string): boolean { return UNAUTHENTICATED_ROUTES.some(route => route.pattern.endsWith('*') ? pathname.startsWith(route.pattern.slice(0, -1)) : pathname === route.pattern); }
+export function isAllowedDuringCircuitBreakerOpen(pathname: string): boolean { const route = UNAUTHENTICATED_ROUTES.find(route => route.pattern.endsWith('*') ? pathname.startsWith(route.pattern.slice(0, -1)) : pathname === route.pattern); return route?.allowDuringCircuitBreakerOpen === true; }
+export function requiresRateLimit(pathname: string): boolean { const route = UNAUTHENTICATED_ROUTES.find(route => route.pattern.endsWith('*') ? pathname.startsWith(route.pattern.slice(0, -1)) : pathname === route.pattern); return route?.requiresRateLimit === true; }
+export default { UNAUTHENTICATED_ROUTES, isUnauthenticatedRoute, isAllowedDuringCircuitBreakerOpen, requiresRateLimit };

package/src/config/vibe-log-transport.ts

@@ -0,0 +1,250 @@
+/**
+ * Vibe Log Transport for Winston
+ *
+ * Buffers log entries to Redis for async processing by Vibe log drain.
+ * This avoids the "log database errors to database" chicken-and-egg problem.
+ *
+ * Features:
+ * - Async batch writing (doesn't block main thread)
+ * - Configurable minimum log level
+ * - Redis buffering with 1-week TTL
+ * - Graceful degradation on failure
+ */
+
+import Transport from 'winston-transport';
+import { getRedis } from '../lib/redis';
+
+/** Redis key for pending log entries */
+const REDIS_LOG_KEY = 'vibe:logs:pending';
+/** TTL in seconds: 1 week */
+const REDIS_LOG_TTL = 7 * 24 * 60 * 60;
+
+export interface VibeLogTransportOptions extends Transport.TransportStreamOptions {
+  /** Redis URL (optional, uses REDIS_URL env var by default) */
+  redisUrl?: string;
+  /** Vibe client ID (for log metadata) */
+  vibeClientId?: string;
+  /** App slug for identification */
+  appSlug?: string;
+  /** Minimum level to send to Vibe (default: 'warn') */
+  minLevel?: string;
+  /** Batch size before flush (default: 10) */
+  batchSize?: number;
+  /** Flush interval in ms (default: 5000) */
+  flushInterval?: number;
+  /** Enable/disable the transport (default: true if Redis available) */
+  enabled?: boolean;
+}
+
+interface LogEntry {
+  level: string;
+  message: string;
+  timestamp: string;
+  category?: string;
+  meta?: Record<string, any>;
+}
+
+const LEVEL_ORDER: Record<string, number> = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  debug: 4,
+};
+
+/**
+ * Winston transport that buffers logs to Redis for Vibe drain processing
+ */
+export class VibeLogTransport extends Transport {
+  private vibeClientId: string;
+  private appSlug: string;
+  private minLevelNum: number;
+  private batchSize: number;
+  private flushInterval: number;
+  private enabled: boolean;
+  private redisAvailable: boolean = false;
+
+  private batch: LogEntry[] = [];
+  private flushTimer: NodeJS.Timeout | null = null;
+  private isFlushing = false;
+
+  constructor(opts: VibeLogTransportOptions = {}) {
+    super(opts);
+
+    this.vibeClientId = opts.vibeClientId || process.env.VIBE_CLIENT_ID || '';
+    this.appSlug = opts.appSlug || process.env.APP_SLUG || process.env.CLIENT_ID || 'mvp-app';
+    this.minLevelNum = LEVEL_ORDER[opts.minLevel || 'warn'] ?? 1;
+    this.batchSize = opts.batchSize || 10;
+    this.flushInterval = opts.flushInterval || 5000;
+
+    // Enable if Redis URL is configured
+    const redisUrl = opts.redisUrl || process.env.REDIS_URL || '';
+    this.enabled = opts.enabled !== false && !!redisUrl;
+    this.redisAvailable = !!redisUrl;
+
+    if (this.enabled) {
+      this.startFlushTimer();
+    }
+  }
+
+  /**
+   * Winston transport log method
+   */
+  log(info: any, callback: () => void): void {
+    setImmediate(() => this.emit('logged', info));
+
+    if (!this.enabled) {
+      callback();
+      return;
+    }
+
+    const level = info.level?.replace(/\u001b\[\d+m/g, '') || 'info'; // Strip ANSI codes
+    const levelNum = LEVEL_ORDER[level] ?? 2;
+
+    // Only batch if at or above minimum level
+    if (levelNum <= this.minLevelNum) {
+      const entry: LogEntry = {
+        level,
+        message: info.message || '',
+        timestamp: info.timestamp || new Date().toISOString(),
+        category: this.extractCategory(info.message),
+        meta: this.extractMeta(info),
+      };
+
+      this.batch.push(entry);
+
+      // Flush immediately if batch is full or if error/fatal
+      if (this.batch.length >= this.batchSize || level === 'error') {
+        this.flush().catch(() => {}); // Ignore flush errors
+      }
+    }
+
+    callback();
+  }
+
+  /**
+   * Extract category from message prefix like [AUTH], [IDP], etc.
+   */
+  private extractCategory(message: string): string {
+    const match = message.match(/^\[([A-Z-]+)\]/);
+    return match ? match[1].toLowerCase() : 'app';
+  }
+
+  /**
+   * Extract metadata from winston info object
+   */
+  private extractMeta(info: any): Record<string, any> {
+    const { level, message, timestamp, ...rest } = info;
+    return Object.keys(rest).length > 0 ? rest : {};
+  }
+
+  /**
+   * Start the periodic flush timer
+   */
+  private startFlushTimer(): void {
+    if (this.flushTimer) return;
+
+    this.flushTimer = setInterval(() => {
+      if (this.batch.length > 0) {
+        this.flush().catch(() => {});
+      }
+    }, this.flushInterval);
+
+    // Don't prevent process exit
+    if (this.flushTimer.unref) {
+      this.flushTimer.unref();
+    }
+  }
+
+  /**
+   * Flush batch to Vibe
+   */
+  async flush(): Promise<void> {
+    if (this.isFlushing || this.batch.length === 0) return;
+
+    this.isFlushing = true;
+    const entries = [...this.batch];
+    this.batch = [];
+
+    try {
+      await this.sendToVibe(entries);
+    } catch (err) {
+      // On failure, put entries back (up to limit to prevent memory issues)
+      if (this.batch.length < 100) {
+        this.batch = [...entries, ...this.batch].slice(0, 100);
+      }
+      // Log to console as fallback
+      console.error('[VibeLogTransport] Failed to flush logs:', err);
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+
+  /**
+   * Push log entries to Redis for async drain processing
+   */
+  private async sendToVibe(entries: LogEntry[]): Promise<void> {
+    if (entries.length === 0) return;
+
+    const redis = getRedis();
+
+    // Format entries for the drain to process
+    const logRecords = entries.map(e => JSON.stringify({
+      level: e.level,
+      message: e.message,
+      timestamp: e.timestamp,
+      source: 'next-mvp',
+      app_slug: this.appSlug,
+      vibe_client_id: this.vibeClientId,
+      category: e.category,
+      error_code: e.meta?.errorCode || e.meta?.error_code,
+      stack: e.meta?.stack,
+      request_id: e.meta?.requestId || e.meta?.request_id,
+      user_id: e.meta?.userId || e.meta?.user_id,
+      path: e.meta?.path,
+      method: e.meta?.method,
+      status_code: e.meta?.statusCode || e.meta?.status_code,
+      duration_ms: e.meta?.durationMs || e.meta?.duration_ms,
+      meta: e.meta,
+      queued_at: new Date().toISOString(),
+    }));
+
+    // LPUSH all entries (newest first, drain will RPOP for FIFO)
+    await redis.lpush(REDIS_LOG_KEY, ...logRecords);
+
+    // Reset TTL on each write (1 week from last activity)
+    await redis.expire(REDIS_LOG_KEY, REDIS_LOG_TTL);
+  }
+
+  /**
+   * Close transport and flush remaining logs
+   */
+  close(): void {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    // Final flush (best effort)
+    if (this.batch.length > 0) {
+      this.flush().catch(() => {});
+    }
+  }
+}
+
+/**
+ * Create a configured VibeLogTransport instance
+ * Returns null if Redis is not configured (REDIS_URL env var)
+ */
+export function createVibeLogTransport(opts?: VibeLogTransportOptions): VibeLogTransport | null {
+  const transport = new VibeLogTransport(opts);
+
+  // Return null if transport is disabled (no Redis)
+  if (!transport['enabled']) {
+    return null;
+  }
+
+  return transport;
+}
+
+export default VibeLogTransport;

package/src/edge/internal-api-url.ts

@@ -0,0 +1,65 @@
+/**
+ * Internal API URL Utility for Edge Runtime
+ *
+ * INTERNAL_API_URL is REQUIRED. This is the URL for THIS application calling ITSELF.
+ * Used for middleware to call its own API routes (e.g., /api/session/viability).
+ *
+ * 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
+ * - This is NOT about "K8s internal traffic doesn't need TLS" - it's about
+ *   protocol consistency for cookie encryption
+ *
+ * This is NOT for calling the IDP - use IDP_URL for that.
+ *
+ * For local dev, set INTERNAL_API_URL=http://localhost:3000 (or your dev port).
+ *
+ * @module edge/internal-api-url
+ * @version 3.0.0
+ */
+
+import { NextRequest } from 'next/server';
+
+/**
+ * Get the internal API base URL for middleware to call its own API routes.
+ *
+ * THROWS if INTERNAL_API_URL is not set. No fallbacks.
+ *
+ * @param request - The Next.js request object (unused, kept for API compatibility)
+ * @returns Base URL string for constructing internal API calls
+ * @throws Error if INTERNAL_API_URL environment variable is not set
+ *
+ * @example
+ * ```typescript
+ * import { getInternalApiUrl } from '@payez/next-mvp/edge';
+ *
+ * export async function middleware(request: NextRequest) {
+ *   const baseUrl = getInternalApiUrl(request);
+ *   const apiUrl = new URL('/api/session/check', baseUrl);
+ *
+ *   const response = await fetch(apiUrl, {
+ *     headers: {
+ *       'Cookie': request.headers.get('cookie') || ''
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @environment INTERNAL_API_URL - REQUIRED. URL for this app to call ITSELF.
+ *   MUST be HTTP (not HTTPS) - see module docs for why.
+ *   K8s: http://myapp.namespace.svc.cluster.local:80
+ *   Local: http://localhost:3000
+ */
+export function getInternalApiUrl(request: NextRequest): string {
+  const internalUrl = process.env.INTERNAL_API_URL;
+  if (!internalUrl) {
+    throw new Error(
+      '[INTERNAL_API_URL] FATAL: INTERNAL_API_URL environment variable is REQUIRED. ' +
+      'This is for the app to call ITSELF. MUST be HTTP (not HTTPS). ' +
+      'Set to http://myapp.namespace.svc.cluster.local:80 (K8s) or http://localhost:3000 (local).'
+    );
+  }
+  return internalUrl;
+}