@payez/next-mvp 3.4.0 → 3.6.0

package/src/api-handlers/admin/stats.ts

@@ -0,0 +1,240 @@
+/**
+ * Admin Stats API Handler
+ *
+ * Aggregates dashboard statistics from users, Redis sessions, and audit logs.
+ * Uses service account HMAC auth for Vibe API requests.
+ *
+ * @version 1.0
+ * @requires Admin role (vibe_app_admin or payez_admin)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getServerSession } from 'next-auth';
+import { getStartupIDPConfig } from '../../lib/startup-init';
+import { getRedis } from '../../lib/redis';
+import { ADMIN_ROLES } from '../../lib/roles';
+
+interface VibeRequestOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+}
+
+async function checkAdminRole(getAuthOptions: () => Promise<any>): Promise<{ isAdmin: boolean; error?: NextResponse }> {
+  const authOptions = await getAuthOptions();
+  const session = await getServerSession(authOptions) as any;
+
+  if (!session?.user) {
+    return {
+      isAdmin: false,
+      error: NextResponse.json({ success: false, error: 'Please sign in' }, { status: 401 }),
+    };
+  }
+
+  const userRoles = (session.user?.roles as string[]) || [];
+  const hasAdminRole = ADMIN_ROLES.some(role => userRoles.includes(role));
+
+  if (!hasAdminRole) {
+    return {
+      isAdmin: false,
+      error: NextResponse.json({ success: false, error: 'Admin access required' }, { status: 403 }),
+    };
+  }
+
+  return { isAdmin: true };
+}
+
+async function vibeServiceRequest<T = unknown>(
+  endpoint: string,
+  options: VibeRequestOptions
+): Promise<{ ok: boolean; status: number; data: T | null; error?: string }> {
+  const idpUrl = process.env.NEXT_PUBLIC_IDP_URL || process.env.IDP_URL;
+  const clientId = process.env.VIBE_CLIENT_ID;
+  const signingKey = process.env.VIBE_HMAC_KEY;
+
+  if (!idpUrl || !clientId || !signingKey) {
+    return { ok: false, status: 500, data: null, error: 'Vibe not configured' };
+  }
+
+  const timestamp = Math.floor(Date.now() / 1000);
+  const stringToSign = `${timestamp}|${options.method}|${endpoint}`;
+
+  const crypto = await import('crypto');
+  const signature = crypto
+    .createHmac('sha256', Buffer.from(signingKey, 'base64'))
+    .update(stringToSign)
+    .digest('base64');
+
+  const proxyUrl = `${idpUrl}/api/vibe/proxy`;
+
+  const idpConfig = getStartupIDPConfig();
+  const idpClientId = idpConfig?.clientSlug || idpConfig?.clientId;
+
+  try {
+    const res = await fetch(proxyUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Vibe-Client-Id': clientId,
+        'X-Vibe-Timestamp': String(timestamp),
+        'X-Vibe-Signature': signature,
+        ...(idpClientId && { 'X-Client-Id': idpClientId }),
+      },
+      body: JSON.stringify({
+        endpoint,
+        method: options.method,
+        data: options.body ?? null,
+      }),
+      cache: 'no-store',
+    });
+
+    if (res.status === 204) return { ok: true, status: 204, data: null };
+    if (!res.ok) {
+      const errorText = await res.text();
+      return { ok: false, status: res.status, data: null, error: errorText };
+    }
+
+    const body = await res.json();
+    return { ok: true, status: res.status, data: body };
+  } catch (error) {
+    return { ok: false, status: 0, data: null, error: String(error) };
+  }
+}
+
+export interface AdminStatsHandlerConfig {
+  getAuthOptions: () => Promise<any>;
+  appSlug?: string;
+}
+
+/**
+ * GET /api/admin/stats - Dashboard statistics
+ * Aggregates users + tier breakdown, active Redis sessions, and recent audit activity.
+ */
+export function createStatsHandler(config: AdminStatsHandlerConfig) {
+  const getSessionPrefix = () => {
+    const appSlug = config.appSlug || process.env.APP_SLUG || process.env.CLIENT_ID || 'app';
+    return `${appSlug}:sess:`;
+  };
+
+  return {
+    async GET(_request: NextRequest) {
+      const adminCheck = await checkAdminRole(config.getAuthOptions);
+      if (adminCheck.error) return adminCheck.error;
+
+      try {
+        // Fetch from 3 sources in parallel
+        const [usersResult, sessionCount, auditResult] = await Promise.allSettled([
+          // 1. Users + tier breakdown via HMAC proxy (Vibe collection query)
+          vibeServiceRequest<any>('/v1/collections/vibe_app/tables/users/query', {
+            method: 'POST',
+            body: { page: 1, pageSize: 500, orderBy: 'created_at', orderDirection: 'desc' },
+          }),
+
+          // 2. Active sessions from Redis
+          (async () => {
+            const redis = getRedis();
+            const sessionPrefix = getSessionPrefix();
+            const sessionKeys: string[] = [];
+            let cursor = '0';
+            do {
+              const [newCursor, keys] = await redis.scan(cursor, 'MATCH', `${sessionPrefix}*`, 'COUNT', 100);
+              cursor = newCursor;
+              sessionKeys.push(...keys.filter((k: string) => !k.includes(':ver:')));
+            } while (cursor !== '0');
+            return sessionKeys.length;
+          })(),
+
+          // 3. Recent audit activity via HMAC proxy
+          vibeServiceRequest<any>('/v1/audit?pageSize=10&sortDir=desc', { method: 'GET' }),
+        ]);
+
+        // Parse users — deduplicate by user_id
+        let totalUsers = 0;
+        let tierBreakdown: Record<string, number> = {};
+        if (usersResult.status === 'fulfilled' && usersResult.value.ok && usersResult.value.data) {
+          const data = usersResult.value.data;
+          const rawUsers = data.data || data.documents || data.users || [];
+
+          // Deduplicate by user_id (keeps latest document_id)
+          const userMap = new Map();
+          for (const u of rawUsers) {
+            const uid = u.user_id || u.id || u.document_id;
+            const existing = userMap.get(uid);
+            if (!existing || (u.document_id || '') > (existing.document_id || '')) {
+              userMap.set(uid, u);
+            }
+          }
+          const uniqueUsers = Array.from(userMap.values());
+          totalUsers = uniqueUsers.length;
+
+          // Build tier breakdown from deduplicated users (unless API provides one)
+          tierBreakdown = data.tierBreakdown || data.tiers || {};
+          if (Object.keys(tierBreakdown).length === 0) {
+            for (const user of uniqueUsers) {
+              const tier = user.tier || 'free';
+              tierBreakdown[tier] = (tierBreakdown[tier] || 0) + 1;
+            }
+          }
+        }
+
+        // Parse active sessions count
+        let activeSessions = 0;
+        if (sessionCount.status === 'fulfilled') {
+          activeSessions = sessionCount.value;
+        }
+
+        // Parse audit events for recent activity
+        let recentActivity: any[] = [];
+        if (auditResult.status === 'fulfilled' && auditResult.value.ok && auditResult.value.data) {
+          const data = auditResult.value.data;
+
+          // Handle multiple possible response shapes
+          let events: any[] = [];
+          if (Array.isArray(data)) {
+            events = data;
+          } else if (Array.isArray(data.data)) {
+            events = data.data;
+          } else if (Array.isArray(data.entries)) {
+            events = data.entries;
+          } else if (Array.isArray(data.items)) {
+            events = data.items;
+          } else if (Array.isArray(data.documents)) {
+            events = data.documents;
+          } else if (data.success && Array.isArray(data.results)) {
+            events = data.results;
+          }
+
+          recentActivity = events.slice(0, 5).map((e: any) => ({
+            id: e.audit_log_id || e.id || e.document_id,
+            type: e.category || e.type || 'admin',
+            action: e.action || e.event || e.message || 'Unknown action',
+            actor: e.admin_email || e.actor || e.user || e.actor_email || 'System',
+            target: e.target_type ? `${e.target_type}:${e.target_id}` : (e.target || e.target_user),
+            details: e.description || e.details,
+            timestamp: e.created_at || e.timestamp || e.date,
+            success: e.is_success ?? e.success ?? true,
+          }));
+        }
+
+        // Calculate tier percentages
+        const tiers = Object.entries(tierBreakdown).map(([name, count]) => ({
+          name,
+          count: count as number,
+          pct: totalUsers > 0 ? Math.round(((count as number) / totalUsers) * 100) : 0,
+        }));
+
+        return NextResponse.json({
+          totalUsers,
+          activeSessions,
+          tiers,
+          recentActivity,
+        });
+      } catch (error: any) {
+        console.error('[admin/stats] Error:', error);
+        return NextResponse.json(
+          { error: error.message || 'Internal error' },
+          { status: 500 }
+        );
+      }
+    },
+  };
+}

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

@@ -11,15 +11,29 @@
  * - Graceful degradation on failure
  */
 
-import Transport from 'winston-transport';
 import { getRedis } from '../lib/redis';
 
+// Dynamic import — winston is a peerDependency and may not be installed.
+// We resolve the base class lazily so builds don't break without it.
+let TransportBase: any;
+try {
+  TransportBase = require('winston-transport');
+} catch {
+  // Fallback: minimal base class for when winston is not installed
+  TransportBase = class {
+    constructor(_opts?: any) {}
+    emit(_event: string, _info: any) {}
+  };
+}
+
 /** 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 {
+export interface VibeLogTransportOptions {
+  /** Winston transport level */
+  level?: string;
   /** Redis URL (optional, uses REDIS_URL env var by default) */
   redisUrl?: string;
   /** Vibe client ID (for log metadata) */
@@ -55,7 +69,7 @@ const LEVEL_ORDER: Record<string, number> = {
 /**
  * Winston transport that buffers logs to Redis for Vibe drain processing
  */
-export class VibeLogTransport extends Transport {
+export class VibeLogTransport extends TransportBase {
   private vibeClientId: string;
   private appSlug: string;
   private minLevelNum: number;

package/src/server/auth-guard.ts

@@ -0,0 +1,170 @@
+/**
+ * Server-Side Auth Guard for Layouts
+ *
+ * Replaces middleware's self-fetch auth checks with direct Redis/function calls.
+ * Call from server-component layouts to protect routes.
+ *
+ * Zero HTTP self-fetches. ~8ms total (Redis + in-memory checks).
+ */
+
+import 'server-only';
+import { redirect } from 'next/navigation';
+import { headers } from 'next/headers';
+import { decodeSession } from './decode-session';
+import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+import type { SessionData } from '../lib/session-store';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AuthGuardOptions {
+  /** Custom checks to run after standard auth validation */
+  checks?: AuthCheck[];
+  /** Override login redirect URL (default: /account-auth/login) */
+  loginUrl?: string;
+  /** Override 2FA redirect URL (default: /account-auth/verify-code) */
+  verifyCodeUrl?: string;
+  /** Override service unavailable URL (default: /service-unavailable) */
+  serviceUnavailableUrl?: string;
+}
+
+export interface AuthCheck {
+  /** Name for logging */
+  name: string;
+  /** Returns redirect URL if check fails, null if passes */
+  check: (session: SessionData, pathname: string) => Promise<string | null>;
+}
+
+export interface AuthGuardResult {
+  userId: string;
+  email: string;
+  roles: string[];
+  sessionData: SessionData;
+  accessToken?: string;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const LOGIN_PAGE = '/account-auth/login';
+const VERIFY_CODE_PAGE = '/account-auth/verify-code';
+const SERVICE_UNAVAILABLE_PAGE = '/service-unavailable';
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+/**
+ * Server-side auth guard. Call from async server layouts.
+ *
+ * Redirects (via next/navigation redirect()) if:
+ * - No session cookie / invalid JWT
+ * - Session not in Redis (stale)
+ * - Session force-invalidated
+ * - 2FA required but not completed / expired
+ * - Any custom check fails
+ *
+ * Returns the authenticated user's session data on success.
+ */
+export async function authGuard(options?: AuthGuardOptions): Promise<AuthGuardResult> {
+  const loginUrl = options?.loginUrl || LOGIN_PAGE;
+  const verifyCodeUrl = options?.verifyCodeUrl || VERIFY_CODE_PAGE;
+  const serviceUnavailableUrl = options?.serviceUnavailableUrl || SERVICE_UNAVAILABLE_PAGE;
+
+  // Get current pathname from headers (set by Next.js)
+  const headerStore = await headers();
+  const pathname = headerStore.get('x-next-pathname') ||
+                   headerStore.get('x-invoke-path') ||
+                   headerStore.get('x-matched-path') ||
+                   '/';
+
+  const callbackUrl = encodeURIComponent(pathname);
+
+  // --- Decode session (cookie → JWT → Redis) ---
+  let decoded: Awaited<ReturnType<typeof decodeSession>>;
+  try {
+    decoded = await decodeSession();
+  } catch (error) {
+    // Redis unreachable or startup failure → fail closed
+    console.error('[AUTH-GUARD] Session decode failed (service error):', error instanceof Error ? error.message : String(error));
+    redirect(serviceUnavailableUrl);
+  }
+
+  // No session at all → redirect to login
+  if (!decoded) {
+    redirect(`${loginUrl}?callbackUrl=${callbackUrl}`);
+  }
+
+  const { sessionData } = decoded;
+
+  // --- Force-invalidated session (admin action, password change) ---
+  if (sessionData.forceInvalidated) {
+    console.warn('[AUTH-GUARD] Session force-invalidated', {
+      userId: sessionData.userId,
+      pathname,
+    });
+    redirect(`${loginUrl}?callbackUrl=${callbackUrl}&reason=invalidated`);
+  }
+
+  // --- 2FA check ---
+  try {
+    const config = await getIDPClientConfig();
+    const requires2FA = config.authSettings?.require2FA ?? true;
+
+    if (requires2FA) {
+      const mfaVerified = sessionData.mfaVerified ?? (sessionData as any).twoFactorComplete ?? false;
+      const mfaExpiresAt = sessionData.mfaExpiresAt || 0;
+      const mfaExpired = mfaExpiresAt > 0 && mfaExpiresAt < Date.now();
+
+      if (!mfaVerified || mfaExpired) {
+        console.log('[AUTH-GUARD] 2FA required', {
+          mfaVerified,
+          mfaExpired,
+          userId: sessionData.userId,
+          pathname,
+        });
+        redirect(`${verifyCodeUrl}?callbackUrl=${callbackUrl}`);
+      }
+    }
+  } catch (error) {
+    // If we can't check 2FA config, fail closed
+    console.error('[AUTH-GUARD] 2FA config check failed:', error instanceof Error ? error.message : String(error));
+    redirect(serviceUnavailableUrl);
+  }
+
+  // --- Custom checks (beta, admin, etc.) ---
+  if (options?.checks) {
+    for (const check of options.checks) {
+      try {
+        const redirectUrl = await check.check(sessionData, pathname);
+        if (redirectUrl) {
+          console.log(`[AUTH-GUARD] Custom check "${check.name}" failed`, {
+            userId: sessionData.userId,
+            pathname,
+            redirectUrl,
+          });
+          redirect(redirectUrl);
+        }
+      } catch (error) {
+        // If the error is a redirect (from next/navigation), re-throw it
+        if (error && typeof error === 'object' && 'digest' in error) {
+          throw error;
+        }
+        console.error(`[AUTH-GUARD] Custom check "${check.name}" error:`, error instanceof Error ? error.message : String(error));
+        redirect(serviceUnavailableUrl);
+      }
+    }
+  }
+
+  // --- All checks passed ---
+  return {
+    userId: sessionData.userId,
+    email: sessionData.email,
+    roles: sessionData.roles || [],
+    sessionData,
+    accessToken: sessionData.idpAccessToken,
+  };
+}

package/src/server/decode-session.ts

@@ -0,0 +1,91 @@
+/**
+ * Server-Side Session Decoder
+ *
+ * Reads the JWT session cookie, decodes it with jose, and fetches the
+ * full session from Redis. Used by authGuard (layouts) and withAuth (API routes).
+ *
+ * Zero HTTP self-fetches. Direct Redis reads only.
+ */
+
+import 'server-only';
+import { cookies } from 'next/headers';
+import { jwtVerify, type JWTPayload } from 'jose';
+import { getSession, type SessionData } from '../lib/session-store';
+import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+import { ensureInitialized } from '../lib/startup-init';
+
+export interface DecodedSession {
+  sessionData: SessionData;
+  jwtPayload: JWTPayload & { sessionToken?: string; redisSessionId?: string };
+}
+
+/**
+ * Decode the session from cookies and Redis.
+ * Returns null if no valid session exists.
+ *
+ * @param requestCookies Optional cookie getter for API route context (NextRequest.cookies).
+ *                       If omitted, uses next/headers cookies() for server components.
+ */
+export async function decodeSession(
+  requestCookies?: { get: (name: string) => { value: string } | undefined }
+): Promise<DecodedSession | null> {
+  try {
+    // Ensure startup initialization is complete (Redis, IDP config, etc.)
+    await ensureInitialized();
+
+    // Get the JWT cookie value
+    const cookieStore = requestCookies || (await cookies());
+    const sessionCookieName = getSessionCookieName();
+    const secureCookieName = getSecureSessionCookieName();
+
+    const cookieValue =
+      cookieStore.get(secureCookieName)?.value ||
+      cookieStore.get(sessionCookieName)?.value;
+
+    if (!cookieValue) {
+      return null;
+    }
+
+    // Get the NextAuth secret from IDP config
+    const config = await getIDPClientConfig();
+    const secret = config.nextAuthSecret;
+    if (!secret) {
+      console.error('[DECODE-SESSION] No nextAuthSecret available from IDP config');
+      return null;
+    }
+
+    // Decode the JWT (same pattern as test-aware-get-token.ts)
+    const secretKey = new TextEncoder().encode(secret);
+    let payload: JWTPayload;
+    try {
+      const result = await jwtVerify(cookieValue, secretKey);
+      payload = result.payload;
+    } catch (jwtError) {
+      // JWT decode failed - cookie may be corrupted or secret rotated
+      console.warn('[DECODE-SESSION] JWT verification failed:', jwtError instanceof Error ? jwtError.message : String(jwtError));
+      return null;
+    }
+
+    // Extract the Redis session ID from JWT payload
+    const sessionToken = (payload as any).sessionToken || (payload as any).redisSessionId;
+    if (!sessionToken) {
+      console.warn('[DECODE-SESSION] JWT payload missing sessionToken/redisSessionId');
+      return null;
+    }
+
+    // Fetch session from Redis (direct, no HTTP)
+    const sessionData = await getSession(sessionToken);
+    if (!sessionData) {
+      return null;
+    }
+
+    return {
+      sessionData,
+      jwtPayload: payload as DecodedSession['jwtPayload'],
+    };
+  } catch (error) {
+    console.error('[DECODE-SESSION] Error:', error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}

package/src/server/slim-middleware.ts

@@ -0,0 +1,117 @@
+/**
+ * Slim Middleware — Cookie-Only Auth Check
+ *
+ * Replaces the self-fetching middleware with a cookie existence check.
+ * All real auth validation happens in server-side layouts (authGuard).
+ *
+ * Zero self-fetches. Zero Redis calls. Zero JWT decoding.
+ * Just: does the session cookie exist? Yes → pass through. No → redirect to login.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface SlimMiddlewareOptions {
+  /** Routes that don't require authentication (glob-style patterns) */
+  publicRoutes?: string[];
+  /** Login page URL (default: /account-auth/login) */
+  loginUrl?: string;
+  /** Additional paths to always bypass (e.g., /api/auth/, /api/session/) */
+  bypassPrefixes?: string[];
+}
+
+// =============================================================================
+// DEFAULT BYPASS PATHS
+// =============================================================================
+
+/** Routes that must always bypass middleware (prevent infinite loops) */
+const DEFAULT_BYPASS_PREFIXES = [
+  '/api/auth/',
+  '/api/session/',
+  '/_next/',
+  '/favicon.ico',
+];
+
+/** Static file extensions to bypass */
+const STATIC_EXTENSIONS = /\.(svg|png|jpg|jpeg|gif|webp|ico|css|js|woff|woff2|ttf|eot|map)$/i;
+
+// =============================================================================
+// MAIN
+// =============================================================================
+
+/**
+ * Create a slim middleware that only checks cookie existence.
+ * Auth validation is deferred to server-side layouts (authGuard).
+ */
+export function createSlimMiddleware(options?: SlimMiddlewareOptions) {
+  const publicRoutes = options?.publicRoutes || [];
+  const loginUrl = options?.loginUrl || '/account-auth/login';
+  const extraBypass = options?.bypassPrefixes || [];
+  const allBypass = [...DEFAULT_BYPASS_PREFIXES, ...extraBypass];
+
+  // Pre-compile public route patterns for fast matching
+  const publicMatchers = publicRoutes.map(pattern => {
+    if (pattern.endsWith('/*')) {
+      const prefix = pattern.slice(0, -2);
+      return (p: string) => p === prefix || p.startsWith(prefix + '/');
+    }
+    if (pattern.endsWith('*')) {
+      const prefix = pattern.slice(0, -1);
+      return (p: string) => p.startsWith(prefix);
+    }
+    if (pattern.startsWith('/*.')) {
+      const ext = pattern.slice(2);
+      return (p: string) => p.endsWith(ext);
+    }
+    return (p: string) => p === pattern;
+  });
+
+  return function middleware(request: NextRequest): NextResponse {
+    const { pathname } = request.nextUrl;
+
+    // 1. Always bypass static/internal routes
+    if (STATIC_EXTENSIONS.test(pathname)) {
+      return NextResponse.next();
+    }
+    for (const prefix of allBypass) {
+      if (pathname.startsWith(prefix)) {
+        return NextResponse.next();
+      }
+    }
+
+    // 2. Check if it's a public route → pass through
+    for (const matcher of publicMatchers) {
+      if (matcher(pathname)) {
+        return NextResponse.next();
+      }
+    }
+
+    // 3. THE ONLY AUTH CHECK: Does a session cookie exist?
+    const sessionCookieName = getSessionCookieName();
+    const secureCookieName = getSecureSessionCookieName();
+    const hasCookie =
+      request.cookies.has(sessionCookieName) ||
+      request.cookies.has(secureCookieName);
+
+    if (!hasCookie) {
+      // No cookie on a protected route → redirect to login
+      // API routes get 401 instead of redirect
+      if (pathname.startsWith('/api/')) {
+        return NextResponse.json(
+          { error: 'Unauthorized', message: 'No session' },
+          { status: 401 }
+        );
+      }
+
+      const callbackUrl = encodeURIComponent(pathname);
+      return NextResponse.redirect(new URL(`${loginUrl}?callbackUrl=${callbackUrl}`, request.url));
+    }
+
+    // Cookie exists → pass through, layout authGuard does the real validation
+    return NextResponse.next();
+  };
+}