@payez/next-mvp 3.0.0

package/src/middleware/rbac-check.ts

@@ -0,0 +1,244 @@
+/**
+ * Page RBAC Check Module
+ *
+ * Checks page-level permissions via Vibe API.
+ * Uses in-memory cache to reduce API calls.
+ * Fails closed (DENY) on errors or timeout.
+ *
+ * @version 1.0.0
+ * @since page-rbac-2026-01
+ */
+
+import { createHmac, createHash } from 'crypto';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface RBACResult {
+  allowed: boolean;
+  requires_2fa?: boolean;
+  requires_elevated_auth?: boolean;
+  reason?: string;
+  required_roles?: string[];
+  required_claims?: Array<{ type: string; value: string }>;
+  matched_rule?: string;
+  redirect?: string;
+  cache_ttl?: number;
+}
+
+interface CacheEntry {
+  result: RBACResult;
+  expires: number;
+}
+
+// ============================================================================
+// CACHE
+// ============================================================================
+
+const rbacCache = new Map<string, CacheEntry>();
+const DEFAULT_CACHE_TTL = 60; // 60 seconds
+const MAX_CACHE_TTL = 300; // 5 minutes max - prevents cache poisoning
+const MAX_CACHE_SIZE = 1000;
+
+/**
+ * Generate cache key for RBAC result.
+ * Uses SHA-256 hash to avoid key collisions and limit key size.
+ */
+function getCacheKey(clientId: string, path: string, roles: string[]): string {
+  const sortedRoles = [...roles].sort().join(',');
+  const input = JSON.stringify({ clientId, path, roles: sortedRoles });
+  return createHash('sha256').update(input).digest('hex').substring(0, 32);
+}
+
+/**
+ * Get cached RBAC result if valid.
+ */
+function getCachedResult(key: string): RBACResult | null {
+  const cached = rbacCache.get(key);
+  if (cached && cached.expires > Date.now()) {
+    return cached.result;
+  }
+  // Clean up expired entry
+  if (cached) {
+    rbacCache.delete(key);
+  }
+  return null;
+}
+
+/**
+ * Cache an RBAC result.
+ */
+function setCachedResult(key: string, result: RBACResult): void {
+  // Prevent unbounded cache growth
+  if (rbacCache.size >= MAX_CACHE_SIZE) {
+    // Remove oldest entries (first 100)
+    const keysToDelete = Array.from(rbacCache.keys()).slice(0, 100);
+    keysToDelete.forEach(k => rbacCache.delete(k));
+  }
+
+  // SECURITY: Clamp TTL to prevent cache poisoning attacks
+  const ttl = Math.min(result.cache_ttl ?? DEFAULT_CACHE_TTL, MAX_CACHE_TTL);
+  rbacCache.set(key, {
+    result,
+    expires: Date.now() + (ttl * 1000),
+  });
+}
+
+/**
+ * Clear cache (for testing or config changes).
+ */
+export function clearRBACCache(): void {
+  rbacCache.clear();
+}
+
+// ============================================================================
+// SIGNATURE
+// ============================================================================
+
+/**
+ * Generate HMAC-SHA256 signature for Vibe API request.
+ * SECURITY: Signing key is required in production.
+ */
+function generateSignature(
+  path: string,
+  clientId: string,
+  timestamp: number
+): string {
+  const signingKey = process.env.VIBE_SIGNING_KEY;
+
+  // SECURITY: Require signing key in production
+  if (!signingKey) {
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error('[RBAC] VIBE_SIGNING_KEY is required in production');
+    }
+    return ''; // Signature optional in dev only
+  }
+
+  const stringToSign = `${timestamp}|GET|/api/v1/rbac/check|${path}|${clientId}`;
+  return createHmac('sha256', Buffer.from(signingKey, 'base64'))
+    .update(stringToSign)
+    .digest('base64');
+}
+
+// ============================================================================
+// RBAC CHECK
+// ============================================================================
+
+/**
+ * Check if user has permission to access a page.
+ *
+ * FAIL CLOSED: If Vibe API is unreachable or times out, access is DENIED.
+ *
+ * @param path - The route path to check
+ * @param userRoles - User's roles from session
+ * @param clientId - Client ID for multi-tenancy
+ * @param userClaims - Optional claims for claim-based authorization
+ * @returns RBAC result with allowed/denied status
+ */
+export async function checkPagePermission(
+  path: string,
+  userRoles: string[],
+  clientId: string,
+  userClaims?: Record<string, string>
+): Promise<RBACResult> {
+  // Check cache first
+  const cacheKey = getCacheKey(clientId, path, userRoles);
+  const cached = getCachedResult(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const vibeApiUrl = process.env.VIBE_API_URL;
+  if (!vibeApiUrl) {
+    console.error('[RBAC] VIBE_API_URL not configured');
+    return {
+      allowed: false,
+      reason: 'rbac_not_configured',
+      redirect: '/error?code=rbac_not_configured',
+    };
+  }
+
+  // Build request URL
+  const url = new URL('/api/v1/rbac/check', vibeApiUrl);
+  url.searchParams.set('path', path);
+  url.searchParams.set('roles', userRoles.join(','));
+
+  // Add claims if provided
+  if (userClaims && Object.keys(userClaims).length > 0) {
+    const claimsParam = Object.entries(userClaims)
+      .map(([type, value]) => `${type}:${value}`)
+      .join(',');
+    url.searchParams.set('claims', claimsParam);
+  }
+
+  // Generate signature
+  const timestamp = Math.floor(Date.now() / 1000);
+  const signature = generateSignature(path, clientId, timestamp);
+
+  // Build headers
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    'X-Client-Id': clientId,
+    'X-Vibe-Client-Id': clientId,
+  };
+
+  if (signature) {
+    headers['X-Vibe-Timestamp'] = String(timestamp);
+    headers['X-Vibe-Signature'] = signature;
+  }
+
+  try {
+    // 2 second timeout - fail closed
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 2000);
+
+    const response = await fetch(url.toString(), {
+      method: 'GET',
+      headers,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      console.error('[RBAC] Vibe API error:', response.status, response.statusText);
+      return {
+        allowed: false,
+        reason: 'rbac_api_error',
+        redirect: '/error?code=rbac_error',
+      };
+    }
+
+    const result: RBACResult = await response.json();
+
+    // Cache the result
+    setCachedResult(cacheKey, result);
+
+    return result;
+  } catch (error: any) {
+    // Fail closed on any error
+    if (error.name === 'AbortError') {
+      console.error('[RBAC] Vibe API timeout (2s exceeded)');
+      return {
+        allowed: false,
+        reason: 'rbac_timeout',
+        redirect: '/error?code=rbac_timeout',
+      };
+    }
+
+    console.error('[RBAC] Vibe API error:', error);
+    return {
+      allowed: false,
+      reason: 'rbac_service_unavailable',
+      redirect: '/error?code=rbac_unavailable',
+    };
+  }
+}
+
+/**
+ * Check if RBAC is enabled for this deployment.
+ */
+export function isRBACEnabled(): boolean {
+  return process.env.VIBE_RBAC_ENABLED === 'true';
+}

package/src/middleware/twofa-presets.ts

@@ -0,0 +1,224 @@
+/**
+ * Two-Factor Authentication Presets for MVP Middleware
+ *
+ * Provides granular control over 2FA requirements per route.
+ * Allows routes to require authentication but NOT require 2FA completion,
+ * which is essential for 2FA onboarding flows.
+ *
+ * Ported from website-membership's TwoFactorPresets pattern.
+ *
+ * @version 2.6.29
+ * @since auth-ready-v2
+ */
+
+/**
+ * Two-Factor Authentication Requirements
+ */
+export interface TwoFactorRequirements {
+  /** Whether 2FA is required for this route */
+  requires2FA: boolean;
+  /** Minimum Authentication Context Class Reference level (optional) */
+  minACR?: string;
+  /** Required Authentication Method References - ALL must be present (optional) */
+  requiredAMR?: string[];
+  /** Allowed Authentication Method References - at least ONE must be present (optional) */
+  allowedAMR?: string[];
+}
+
+/**
+ * Route configuration with 2FA requirements
+ */
+export interface RouteConfig {
+  /** Whether authentication is required */
+  requiresAuth: boolean;
+  /** 2FA requirements for this route */
+  twoFactorRequirements?: TwoFactorRequirements;
+}
+
+/**
+ * Common 2FA requirement presets
+ *
+ * @example
+ * ```typescript
+ * // Configure routes with different 2FA requirements
+ * configureRoutes({
+ *   '/api/account/send-code': { requiresAuth: true, twoFactorRequirements: TwoFactorPresets.NONE },
+ *   '/api/admin/users': { requiresAuth: true, twoFactorRequirements: TwoFactorPresets.HIGH_SECURITY },
+ * });
+ * ```
+ */
+export const TwoFactorPresets = {
+  /**
+   * No 2FA required - route is accessible with just authentication
+   * Use for: 2FA onboarding routes, profile viewing, non-sensitive operations
+   */
+  NONE: {
+    requires2FA: false
+  } as TwoFactorRequirements,
+
+  /**
+   * Basic 2FA - any authentication method acceptable
+   * Use for: Standard protected routes
+   */
+  BASIC: {
+    requires2FA: true,
+    minACR: '1',
+    allowedAMR: ['pwd', 'mfa', 'sms', 'totp', 'otp']
+  } as TwoFactorRequirements,
+
+  /**
+   * Standard 2FA - password + additional factor
+   * Use for: Most application features
+   */
+  STANDARD: {
+    requires2FA: true,
+    minACR: '2',
+    requiredAMR: ['pwd'],
+    allowedAMR: ['pwd', 'mfa', 'sms', 'totp', 'otp']
+  } as TwoFactorRequirements,
+
+  /**
+   * High security - password + MFA required
+   * Use for: Admin operations, settings changes
+   */
+  HIGH_SECURITY: {
+    requires2FA: true,
+    minACR: '2',
+    requiredAMR: ['pwd', 'mfa']
+  } as TwoFactorRequirements,
+
+  /**
+   * Admin operations - strict requirements
+   * Use for: User management, system configuration
+   */
+  ADMIN: {
+    requires2FA: true,
+    minACR: '3',
+    requiredAMR: ['pwd', 'mfa']
+  } as TwoFactorRequirements,
+
+  /**
+   * Financial operations - maximum security
+   * Use for: Payment processing, fund transfers
+   */
+  FINANCIAL: {
+    requires2FA: true,
+    minACR: '4',
+    requiredAMR: ['pwd', 'mfa', 'totp']
+  } as TwoFactorRequirements
+} as const;
+
+/**
+ * AMR (Authentication Methods Reference) values
+ */
+export const AMRValues = {
+  /** Password authentication */
+  PASSWORD: 'pwd',
+  /** Multi-factor authentication completed */
+  MFA: 'mfa',
+  /** SMS verification */
+  SMS: 'sms',
+  /** Time-based one-time password (authenticator app) */
+  TOTP: 'totp',
+  /** One-time password (generic) */
+  OTP: 'otp',
+  /** Email verification */
+  EMAIL: 'email',
+  /** Hardware key */
+  HARDWARE_KEY: 'hwk',
+  /** Biometric */
+  BIOMETRIC: 'bio'
+} as const;
+
+/**
+ * ACR (Authentication Context Class Reference) levels
+ */
+export const ACRLevels = {
+  /** No authentication */
+  NONE: '0',
+  /** Single factor (password only) */
+  SINGLE_FACTOR: '1',
+  /** Multi-factor authentication */
+  MULTI_FACTOR: '2',
+  /** Hardware-backed MFA */
+  HARDWARE_MFA: '3',
+  /** Maximum assurance (hardware + biometric) */
+  MAXIMUM: '4'
+} as const;
+
+/**
+ * Validate AMR claims against requirements
+ */
+export function validateAMR(
+  actualAMR: string[],
+  requirements: TwoFactorRequirements
+): boolean {
+  // If no AMR requirements, valid
+  if (!requirements.requiredAMR?.length && !requirements.allowedAMR?.length) {
+    return true;
+  }
+
+  // If required methods specified, all must be present
+  if (requirements.requiredAMR && requirements.requiredAMR.length > 0) {
+    return requirements.requiredAMR.every(method => actualAMR.includes(method));
+  }
+
+  // If allowed methods specified, at least one must be present
+  if (requirements.allowedAMR && requirements.allowedAMR.length > 0) {
+    return actualAMR.some(method => requirements.allowedAMR!.includes(method));
+  }
+
+  return true;
+}
+
+/**
+ * Validate ACR level against requirements
+ */
+export function validateACR(actualACR: string, minACR?: string): boolean {
+  if (!minACR) {
+    return true;
+  }
+
+  const actualLevel = parseInt(actualACR, 10) || 0;
+  const minLevel = parseInt(minACR, 10) || 1;
+
+  return actualLevel >= minLevel;
+}
+
+/**
+ * Check if 2FA requirements are met
+ */
+export function checkTwoFactorRequirements(
+  requirements: TwoFactorRequirements,
+  sessionStatus: {
+    twoFactorComplete?: boolean;
+    authenticationMethods?: string[];
+    authenticationLevel?: string;
+  }
+): { satisfied: boolean; reason?: string } {
+  // If 2FA not required, always satisfied
+  if (!requirements.requires2FA) {
+    return { satisfied: true };
+  }
+
+  // Check if 2FA is complete
+  if (!sessionStatus.twoFactorComplete) {
+    return { satisfied: false, reason: '2FA not completed' };
+  }
+
+  // Check AMR if specified
+  const amr = sessionStatus.authenticationMethods || [];
+  if (!validateAMR(amr, requirements)) {
+    return { satisfied: false, reason: 'AMR requirements not met' };
+  }
+
+  // Check ACR if specified
+  const acr = sessionStatus.authenticationLevel || '0';
+  if (!validateACR(acr, requirements.minACR)) {
+    return { satisfied: false, reason: 'ACR level insufficient' };
+  }
+
+  return { satisfied: true };
+}
+
+export default TwoFactorPresets;

package/src/models/DecodedAccessToken.ts

@@ -0,0 +1,17 @@
+export interface DecodedAccessToken {
+    iss: string;
+    aud: string;
+    sub: string;
+    jti: string;
+    iat: number;
+    nbf: number;
+    exp: number;
+    user_id: string;
+    client_id: string;
+    token_type: string;
+    scope: string;
+    roles: string[];
+    amr: string[];
+    acr: string;
+    [key: string]: any;
+}