@payez/next-mvp 4.0.1 → 4.0.2

package/dist/middleware/rbac-check.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Page RBAC Check Module
+ *
+ * Checks page-level permissions via Vibe API through the IDP Proxy.
+ * Uses in-memory cache to reduce API calls.
+ * Fails closed (DENY) on errors or timeout.
+ *
+ * All requests route through the IDP Vibe Proxy ({IDP_URL}/api/vibe/proxy)
+ * which injects proper HMAC credentials for the Vibe API.
+ *
+ * @version 2.0.0
+ * @since page-rbac-2026-01
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearRBACCache = clearRBACCache;
+exports.checkPagePermission = checkPagePermission;
+exports.isRBACEnabled = isRBACEnabled;
+// ============================================================================
+// WEB CRYPTO HELPERS (Edge Runtime compatible)
+// ============================================================================
+const encoder = new TextEncoder();
+async function sha256Hex(input) {
+    const data = encoder.encode(input);
+    const hash = await crypto.subtle.digest('SHA-256', data);
+    return Array.from(new Uint8Array(hash))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+async function hmacSha256Base64(key, message) {
+    const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(message));
+    return btoa(String.fromCharCode(...new Uint8Array(signature)));
+}
+function base64ToUint8Array(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+// ============================================================================
+// CACHE
+// ============================================================================
+const rbacCache = new Map();
+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.
+ */
+async function getCacheKey(clientId, path, roles) {
+    const sortedRoles = [...roles].sort().join(',');
+    const input = JSON.stringify({ clientId, path, roles: sortedRoles });
+    const hash = await sha256Hex(input);
+    return hash.substring(0, 32);
+}
+/**
+ * Get cached RBAC result if valid.
+ */
+function getCachedResult(key) {
+    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, result) {
+    // 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).
+ */
+function clearRBACCache() {
+    rbacCache.clear();
+}
+// ============================================================================
+// RBAC CHECK (via IDP Proxy)
+// ============================================================================
+/**
+ * Check if user has permission to access a page.
+ *
+ * Routes through IDP Vibe Proxy ({IDP_URL}/api/vibe/proxy) which injects
+ * proper HMAC credentials. The Vibe RBAC endpoint requires client context
+ * that only the proxy can provide.
+ *
+ * FAIL CLOSED: If proxy 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 slug for multi-tenancy
+ * @param userClaims - Optional claims for claim-based authorization
+ * @returns RBAC result with allowed/denied status
+ */
+async function checkPagePermission(path, userRoles, clientId, userClaims) {
+    // Check cache first
+    const cacheKey = await getCacheKey(clientId, path, userRoles);
+    const cached = getCachedResult(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const idpUrl = process.env.NEXT_PUBLIC_IDP_URL || process.env.IDP_URL;
+    const vibeClientId = process.env.VIBE_CLIENT_ID;
+    const hmacKey = process.env.VIBE_HMAC_KEY || process.env.IDP_SIGNING_KEY;
+    if (!idpUrl) {
+        console.error('[RBAC] IDP_URL not configured');
+        return {
+            allowed: false,
+            reason: 'rbac_not_configured',
+            redirect: '/error?code=rbac_not_configured',
+        };
+    }
+    // Build RBAC endpoint with query params
+    // Vibe route is /v1/rbac/check (no /api/ prefix)
+    const params = new URLSearchParams();
+    params.set('path', path);
+    params.set('roles', userRoles.join(','));
+    if (userClaims && Object.keys(userClaims).length > 0) {
+        const claimsParam = Object.entries(userClaims)
+            .map(([type, value]) => `${type}:${value}`)
+            .join(',');
+        params.set('claims', claimsParam);
+    }
+    const rbacEndpoint = `/v1/rbac/check?${params.toString()}`;
+    // Build proxy request
+    const proxyUrl = `${idpUrl}/api/vibe/proxy`;
+    const timestamp = Math.floor(Date.now() / 1000);
+    const headers = {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+    };
+    if (vibeClientId) {
+        headers['X-Vibe-Client-Id'] = vibeClientId;
+    }
+    // Sign with HMAC (same format as vibe-client: timestamp|method|endpoint)
+    if (hmacKey && vibeClientId) {
+        const stringToSign = `${timestamp}|GET|${rbacEndpoint}`;
+        const keyBuffer = base64ToUint8Array(hmacKey);
+        const signature = await hmacSha256Base64(keyBuffer, stringToSign);
+        headers['X-Vibe-Timestamp'] = String(timestamp);
+        headers['X-Vibe-Signature'] = signature;
+    }
+    // Proxy body format: { endpoint, method, data }
+    const proxyBody = {
+        endpoint: rbacEndpoint,
+        method: 'GET',
+        data: null,
+    };
+    try {
+        // 2 second timeout - fail closed
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 2000);
+        const response = await fetch(proxyUrl, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(proxyBody),
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            console.error('[RBAC] Proxy error:', response.status, response.statusText);
+            return {
+                allowed: false,
+                reason: 'rbac_api_error',
+                redirect: '/error?code=rbac_error',
+            };
+        }
+        const body = await response.json();
+        // Vibe API wraps responses: { success: true, data: { allowed, reason, ... } }
+        // Unwrap the .data property if present, otherwise use body directly
+        const result = body?.data ?? body;
+        // Cache the result
+        setCachedResult(cacheKey, result);
+        return result;
+    }
+    catch (error) {
+        // Fail closed on any error
+        if (error.name === 'AbortError') {
+            console.error('[RBAC] Proxy timeout (2s exceeded)');
+            return {
+                allowed: false,
+                reason: 'rbac_timeout',
+                redirect: '/error?code=rbac_timeout',
+            };
+        }
+        console.error('[RBAC] Proxy error:', error);
+        return {
+            allowed: false,
+            reason: 'rbac_service_unavailable',
+            redirect: '/error?code=rbac_unavailable',
+        };
+    }
+}
+/**
+ * Check if RBAC is enabled for this deployment.
+ */
+function isRBACEnabled() {
+    return process.env.VIBE_RBAC_ENABLED === 'true';
+}

package/dist/middleware/twofa-presets.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 declare const TwoFactorPresets: {
+    /**
+     * No 2FA required - route is accessible with just authentication
+     * Use for: 2FA onboarding routes, profile viewing, non-sensitive operations
+     */
+    readonly NONE: TwoFactorRequirements;
+    /**
+     * Basic 2FA - any authentication method acceptable
+     * Use for: Standard protected routes
+     */
+    readonly BASIC: TwoFactorRequirements;
+    /**
+     * Standard 2FA - password + additional factor
+     * Use for: Most application features
+     */
+    readonly STANDARD: TwoFactorRequirements;
+    /**
+     * High security - password + MFA required
+     * Use for: Admin operations, settings changes
+     */
+    readonly HIGH_SECURITY: TwoFactorRequirements;
+    /**
+     * Admin operations - strict requirements
+     * Use for: User management, system configuration
+     */
+    readonly ADMIN: TwoFactorRequirements;
+    /**
+     * Financial operations - maximum security
+     * Use for: Payment processing, fund transfers
+     */
+    readonly FINANCIAL: TwoFactorRequirements;
+};
+/**
+ * AMR (Authentication Methods Reference) values
+ */
+export declare const AMRValues: {
+    /** Password authentication */
+    readonly PASSWORD: "pwd";
+    /** Multi-factor authentication completed */
+    readonly MFA: "mfa";
+    /** SMS verification */
+    readonly SMS: "sms";
+    /** Time-based one-time password (authenticator app) */
+    readonly TOTP: "totp";
+    /** One-time password (generic) */
+    readonly OTP: "otp";
+    /** Email verification */
+    readonly EMAIL: "email";
+    /** Hardware key */
+    readonly HARDWARE_KEY: "hwk";
+    /** Biometric */
+    readonly BIOMETRIC: "bio";
+};
+/**
+ * ACR (Authentication Context Class Reference) levels
+ */
+export declare const ACRLevels: {
+    /** No authentication */
+    readonly NONE: "0";
+    /** Single factor (password only) */
+    readonly SINGLE_FACTOR: "1";
+    /** Multi-factor authentication */
+    readonly MULTI_FACTOR: "2";
+    /** Hardware-backed MFA */
+    readonly HARDWARE_MFA: "3";
+    /** Maximum assurance (hardware + biometric) */
+    readonly MAXIMUM: "4";
+};
+/**
+ * Validate AMR claims against requirements
+ */
+export declare function validateAMR(actualAMR: string[], requirements: TwoFactorRequirements): boolean;
+/**
+ * Validate ACR level against requirements
+ */
+export declare function validateACR(actualACR: string, minACR?: string): boolean;
+/**
+ * Check if 2FA requirements are met
+ */
+export declare function checkTwoFactorRequirements(requirements: TwoFactorRequirements, sessionStatus: {
+    twoFactorComplete?: boolean;
+    authenticationMethods?: string[];
+    authenticationLevel?: string;
+}): {
+    satisfied: boolean;
+    reason?: string;
+};
+export default TwoFactorPresets;

package/dist/middleware/twofa-presets.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACRLevels = exports.AMRValues = exports.TwoFactorPresets = void 0;
+exports.validateAMR = validateAMR;
+exports.validateACR = validateACR;
+exports.checkTwoFactorRequirements = checkTwoFactorRequirements;
+/**
+ * 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 },
+ * });
+ * ```
+ */
+exports.TwoFactorPresets = {
+    /**
+     * No 2FA required - route is accessible with just authentication
+     * Use for: 2FA onboarding routes, profile viewing, non-sensitive operations
+     */
+    NONE: {
+        requires2FA: false
+    },
+    /**
+     * Basic 2FA - any authentication method acceptable
+     * Use for: Standard protected routes
+     */
+    BASIC: {
+        requires2FA: true,
+        minACR: '1',
+        allowedAMR: ['pwd', 'mfa', 'sms', 'totp', 'otp']
+    },
+    /**
+     * Standard 2FA - password + additional factor
+     * Use for: Most application features
+     */
+    STANDARD: {
+        requires2FA: true,
+        minACR: '2',
+        requiredAMR: ['pwd'],
+        allowedAMR: ['pwd', 'mfa', 'sms', 'totp', 'otp']
+    },
+    /**
+     * High security - password + MFA required
+     * Use for: Admin operations, settings changes
+     */
+    HIGH_SECURITY: {
+        requires2FA: true,
+        minACR: '2',
+        requiredAMR: ['pwd', 'mfa']
+    },
+    /**
+     * Admin operations - strict requirements
+     * Use for: User management, system configuration
+     */
+    ADMIN: {
+        requires2FA: true,
+        minACR: '3',
+        requiredAMR: ['pwd', 'mfa']
+    },
+    /**
+     * Financial operations - maximum security
+     * Use for: Payment processing, fund transfers
+     */
+    FINANCIAL: {
+        requires2FA: true,
+        minACR: '4',
+        requiredAMR: ['pwd', 'mfa', 'totp']
+    }
+};
+/**
+ * AMR (Authentication Methods Reference) values
+ */
+exports.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'
+};
+/**
+ * ACR (Authentication Context Class Reference) levels
+ */
+exports.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'
+};
+/**
+ * Validate AMR claims against requirements
+ */
+function validateAMR(actualAMR, requirements) {
+    // 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
+ */
+function validateACR(actualACR, minACR) {
+    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
+ */
+function checkTwoFactorRequirements(requirements, sessionStatus) {
+    // 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 };
+}
+exports.default = exports.TwoFactorPresets;

package/dist/models/DecodedAccessToken.d.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;
+}

package/dist/models/DecodedAccessToken.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/models/SessionModel.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Session Model - Redis Session Data Structure
+ *
+ * This is the single source of truth for session data stored in Redis.
+ * The session contains all authentication state - the JWT cookie only
+ * stores the session ID (redisSessionId).
+ *
+ * FIELD NAMING CONVENTIONS:
+ * - idp* prefix: Tokens from PayEz IDP (identity provider)
+ * - oauth* prefix: Tokens from external OAuth providers (Google, etc.)
+ * - mfa* prefix: Multi-factor authentication related fields
+ *
+ * @version 2.0.0 - Normalized field names
+ * @since auth-refactor-2026-01
+ */
+/**
+ * Session data stored in Redis.
+ *
+ * This interface uses normalized field names for clarity.
+ * All tokens and user data live here - the browser only gets the session ID.
+ */
+export interface SessionData {
+    /** User ID from IDP (sub claim) */
+    userId: string;
+    /** User's email address */
+    email: string;
+    /** Display name (from OAuth profile or IDP) */
+    name?: string;
+    /** User's roles/permissions */
+    roles: string[];
+    /** IDP access token (JWT) - used for API calls to PayEz services */
+    idpAccessToken?: string;
+    /** IDP refresh token - used to get new access tokens */
+    idpRefreshToken?: string;
+    /** When the IDP access token expires (Unix timestamp ms) */
+    idpAccessTokenExpires: number;
+    /** When the IDP refresh token expires (Unix timestamp ms) */
+    idpRefreshTokenExpires?: number;
+    /** Decoded IDP access token claims (for quick access without re-decoding) */
+    decodedAccessToken?: any;
+    /**
+     * Bearer Key ID (kid from JWT header).
+     * Identifies which IDP signing key was used for this token.
+     * CRITICAL: This is from the JWT HEADER, not client_id from payload.
+     */
+    bearerKeyId?: string;
+    /** Whether MFA has been verified for this session */
+    mfaVerified: boolean;
+    /** The MFA method used (email, sms, totp) */
+    mfaMethod?: 'email' | 'sms' | 'totp';
+    /** When MFA was completed (Unix timestamp ms) */
+    mfaCompletedAt?: number;
+    /** When MFA verification expires (Unix timestamp ms) */
+    mfaExpiresAt?: number;
+    /** How long MFA is valid in hours */
+    mfaValidityHours?: number;
+    /** Authentication methods from token (amr claim) */
+    authenticationMethods?: string[];
+    /** Authentication level from token (acr claim) */
+    authenticationLevel?: string;
+    /** Which OAuth provider was used (google, apple, microsoft, etc.) */
+    oauthProvider?: string;
+    /** Access token from OAuth provider */
+    oauthProviderToken?: string;
+    /** Refresh token from OAuth provider */
+    oauthProviderRefreshToken?: string;
+    /** IDP client ID this user belongs to */
+    idpClientId?: string;
+    /** Merchant ID (typically same as client ID) */
+    merchantId?: string;
+    /**
+     * Allow any additional fields for backward compatibility.
+     * During migration, old sessions may have legacy field names.
+     */
+    [key: string]: any;
+}
+/**
+ * Session model class for working with session data.
+ *
+ * Provides typed access to session fields with normalized names.
+ */
+export declare class SessionModel {
+    userId: string;
+    email: string;
+    name?: string;
+    roles: string[];
+    idpAccessToken?: string;
+    idpRefreshToken?: string;
+    idpAccessTokenExpires: number;
+    idpRefreshTokenExpires?: number;
+    decodedAccessToken?: any;
+    bearerKeyId?: string;
+    mfaVerified: boolean;
+    mfaMethod?: 'email' | 'sms' | 'totp';
+    mfaCompletedAt?: number;
+    mfaExpiresAt?: number;
+    mfaValidityHours?: number;
+    authenticationMethods?: string[];
+    authenticationLevel?: string;
+    oauthProvider?: string;
+    oauthProviderToken?: string;
+    oauthProviderRefreshToken?: string;
+    idpClientId?: string;
+    merchantId?: string;
+    constructor(data: SessionData);
+    /**
+     * Check if the IDP access token has expired.
+     */
+    isAccessTokenExpired(): boolean;
+    /**
+     * Check if the IDP refresh token has expired.
+     */
+    isRefreshTokenExpired(): boolean;
+    /**
+     * Check if MFA has expired.
+     */
+    isMfaExpired(): boolean;
+    /**
+     * Convert to plain object for storage.
+     */
+    toJSON(): SessionData;
+}