@payez/next-mvp 3.0.0

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;
+}

package/dist/models/SessionModel.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionModel = void 0;
+// ============================================================================
+// SESSION MODEL CLASS
+// ============================================================================
+/**
+ * Session model class for working with session data.
+ *
+ * Provides typed access to session fields with normalized names.
+ */
+class SessionModel {
+    // Core Identity
+    userId;
+    email;
+    name;
+    roles;
+    // IDP Tokens
+    idpAccessToken;
+    idpRefreshToken;
+    idpAccessTokenExpires;
+    idpRefreshTokenExpires;
+    decodedAccessToken;
+    bearerKeyId;
+    // MFA State
+    mfaVerified;
+    mfaMethod;
+    mfaCompletedAt;
+    mfaExpiresAt;
+    mfaValidityHours;
+    authenticationMethods;
+    authenticationLevel;
+    // OAuth Provider
+    oauthProvider;
+    oauthProviderToken;
+    oauthProviderRefreshToken;
+    // Multi-Tenant
+    idpClientId;
+    merchantId;
+    constructor(data) {
+        // Core Identity
+        this.userId = data.userId;
+        this.email = data.email;
+        this.name = data.name;
+        this.roles = data.roles || [];
+        // IDP Tokens
+        this.idpAccessToken = data.idpAccessToken;
+        this.idpRefreshToken = data.idpRefreshToken;
+        this.idpAccessTokenExpires = data.idpAccessTokenExpires;
+        this.idpRefreshTokenExpires = data.idpRefreshTokenExpires;
+        this.decodedAccessToken = data.decodedAccessToken;
+        this.bearerKeyId = data.bearerKeyId;
+        // MFA State
+        this.mfaVerified = data.mfaVerified ?? false;
+        this.mfaMethod = data.mfaMethod;
+        this.mfaCompletedAt = data.mfaCompletedAt;
+        this.mfaExpiresAt = data.mfaExpiresAt;
+        this.mfaValidityHours = data.mfaValidityHours;
+        this.authenticationMethods = data.authenticationMethods;
+        this.authenticationLevel = data.authenticationLevel;
+        // OAuth Provider
+        this.oauthProvider = data.oauthProvider;
+        this.oauthProviderToken = data.oauthProviderToken;
+        this.oauthProviderRefreshToken = data.oauthProviderRefreshToken;
+        // Multi-Tenant
+        this.idpClientId = data.idpClientId;
+        this.merchantId = data.merchantId;
+    }
+    /**
+     * Check if the IDP access token has expired.
+     */
+    isAccessTokenExpired() {
+        return Date.now() >= this.idpAccessTokenExpires;
+    }
+    /**
+     * Check if the IDP refresh token has expired.
+     */
+    isRefreshTokenExpired() {
+        if (!this.idpRefreshTokenExpires)
+            return false;
+        return Date.now() >= this.idpRefreshTokenExpires;
+    }
+    /**
+     * Check if MFA has expired.
+     */
+    isMfaExpired() {
+        if (!this.mfaExpiresAt)
+            return false;
+        return Date.now() > this.mfaExpiresAt;
+    }
+    /**
+     * Convert to plain object for storage.
+     */
+    toJSON() {
+        return {
+            userId: this.userId,
+            email: this.email,
+            name: this.name,
+            roles: this.roles,
+            idpAccessToken: this.idpAccessToken,
+            idpRefreshToken: this.idpRefreshToken,
+            idpAccessTokenExpires: this.idpAccessTokenExpires,
+            idpRefreshTokenExpires: this.idpRefreshTokenExpires,
+            decodedAccessToken: this.decodedAccessToken,
+            bearerKeyId: this.bearerKeyId,
+            mfaVerified: this.mfaVerified,
+            mfaMethod: this.mfaMethod,
+            mfaCompletedAt: this.mfaCompletedAt,
+            mfaExpiresAt: this.mfaExpiresAt,
+            mfaValidityHours: this.mfaValidityHours,
+            authenticationMethods: this.authenticationMethods,
+            authenticationLevel: this.authenticationLevel,
+            oauthProvider: this.oauthProvider,
+            oauthProviderToken: this.oauthProviderToken,
+            oauthProviderRefreshToken: this.oauthProviderRefreshToken,
+            idpClientId: this.idpClientId,
+            merchantId: this.merchantId,
+        };
+    }
+}
+exports.SessionModel = SessionModel;

package/dist/pages/admin-login/page.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Admin Login Page for @payez/next-mvp
+ *
+ * A standalone username/password login page for admin access.
+ * NOT linked from any navigation - only accessible via direct URL.
+ *
+ * USAGE:
+ * 1. Create app/account-auth/admin-login/page.tsx in your Next.js app
+ * 2. Re-export this component:
+ *    export { default } from '@payez/next-mvp/pages/admin-login';
+ *
+ * CUSTOMIZATION:
+ * - Override styles via CSS variables or wrap with your own component
+ * - Provide custom branding via ThemeProvider
+ */
+import React from 'react';
+interface AdminLoginFormProps {
+    /** Optional custom title (default: "Admin Login") */
+    title?: string;
+    /** Optional custom subtitle (default: "Authorized personnel only") */
+    subtitle?: string;
+    /** Optional callback URL override */
+    callbackUrl?: string;
+    /** Optional logo component to render */
+    logo?: React.ReactNode;
+}
+declare function AdminLoginForm({ title, subtitle, callbackUrl: propCallbackUrl, logo, }: AdminLoginFormProps): import("react/jsx-runtime").JSX.Element;
+declare function AdminLoginFallback(): import("react/jsx-runtime").JSX.Element;
+export default function AdminLoginPage(props: AdminLoginFormProps): import("react/jsx-runtime").JSX.Element;
+export { AdminLoginForm, AdminLoginFallback };
+export type { AdminLoginFormProps };