@payez/next-mvp 3.0.0

package/src/models/SessionModel.ts

@@ -0,0 +1,258 @@
+/**
+ * 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
+ */
+
+// ============================================================================
+// NORMALIZED SESSION DATA (v2)
+// ============================================================================
+
+/**
+ * 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 {
+  // -------------------------------------------------------------------------
+  // Core Identity
+  // -------------------------------------------------------------------------
+
+  /** 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 Tokens (from PayEz Identity Provider)
+  // -------------------------------------------------------------------------
+
+  /** 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;
+
+  // -------------------------------------------------------------------------
+  // MFA (Multi-Factor Authentication) State
+  // -------------------------------------------------------------------------
+
+  /** 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;
+
+  // -------------------------------------------------------------------------
+  // OAuth Provider Tokens (Google, Microsoft, etc.)
+  // -------------------------------------------------------------------------
+
+  /** 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;
+
+  // -------------------------------------------------------------------------
+  // Multi-Tenant IDP Assignment
+  // -------------------------------------------------------------------------
+
+  /** IDP client ID this user belongs to */
+  idpClientId?: string;
+
+  /** Merchant ID (typically same as client ID) */
+  merchantId?: string;
+
+  // -------------------------------------------------------------------------
+  // Legacy Field Support (for backward compatibility)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Allow any additional fields for backward compatibility.
+   * During migration, old sessions may have legacy field names.
+   */
+  [key: string]: any;
+}
+
+
+// ============================================================================
+// SESSION MODEL CLASS
+// ============================================================================
+
+/**
+ * Session model class for working with session data.
+ *
+ * Provides typed access to session fields with normalized names.
+ */
+export class SessionModel {
+  // Core Identity
+  userId: string;
+  email: string;
+  name?: string;
+  roles: string[];
+
+  // IDP Tokens
+  idpAccessToken?: string;
+  idpRefreshToken?: string;
+  idpAccessTokenExpires: number;
+  idpRefreshTokenExpires?: number;
+  decodedAccessToken?: any;
+  bearerKeyId?: string;
+
+  // MFA State
+  mfaVerified: boolean;
+  mfaMethod?: 'email' | 'sms' | 'totp';
+  mfaCompletedAt?: number;
+  mfaExpiresAt?: number;
+  mfaValidityHours?: number;
+  authenticationMethods?: string[];
+  authenticationLevel?: string;
+
+  // OAuth Provider
+  oauthProvider?: string;
+  oauthProviderToken?: string;
+  oauthProviderRefreshToken?: string;
+
+  // Multi-Tenant
+  idpClientId?: string;
+  merchantId?: string;
+
+  constructor(data: SessionData) {
+    // 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(): boolean {
+    return Date.now() >= this.idpAccessTokenExpires;
+  }
+
+  /**
+   * Check if the IDP refresh token has expired.
+   */
+  isRefreshTokenExpired(): boolean {
+    if (!this.idpRefreshTokenExpires) return false;
+    return Date.now() >= this.idpRefreshTokenExpires;
+  }
+
+  /**
+   * Check if MFA has expired.
+   */
+  isMfaExpired(): boolean {
+    if (!this.mfaExpiresAt) return false;
+    return Date.now() > this.mfaExpiresAt;
+  }
+
+  /**
+   * Convert to plain object for storage.
+   */
+  toJSON(): SessionData {
+    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,
+    };
+  }
+}

package/src/pages/admin-login/page.tsx

@@ -0,0 +1,229 @@
+/**
+ * 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
+ */
+
+'use client';
+
+import React, { useState } from 'react';
+import { signIn } from 'next-auth/react';
+import { useSearchParams } from 'next/navigation';
+import { Suspense } from 'react';
+import { useBranding, useColors } from '../../theme/useTheme';
+
+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;
+}
+
+function AdminLoginForm({
+  title = 'Admin Login',
+  subtitle = 'Authorized personnel only',
+  callbackUrl: propCallbackUrl,
+  logo,
+}: AdminLoginFormProps) {
+  const searchParams = useSearchParams();
+  const callbackUrl = propCallbackUrl || searchParams?.get('callbackUrl') || '/dashboard';
+
+  const branding = useBranding();
+  const colors = useColors();
+
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [showPassword, setShowPassword] = useState(false);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const result = await signIn('credentials', {
+        email,
+        password,
+        redirect: false,
+        callbackUrl,
+      });
+
+      if (result?.error) {
+        // Parse structured error if available
+        try {
+          const errorData = JSON.parse(result.error);
+          setError(errorData.message || errorData.error?.message || 'Invalid credentials');
+        } catch {
+          if (result.error === 'CredentialsSignin') {
+            setError('Invalid email or password');
+          } else {
+            setError(result.error);
+          }
+        }
+      } else if (result?.ok) {
+        // Redirect to verify-code for 2FA or directly to callback
+        window.location.href = `/account-auth/verify-code?callbackUrl=${encodeURIComponent(callbackUrl)}`;
+      }
+    } catch (err) {
+      setError('An unexpected error occurred');
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-slate-700 via-slate-800 to-slate-900 p-4">
+      <div className="bg-white rounded-2xl shadow-2xl p-8 max-w-md w-full">
+        {/* Logo */}
+        {logo && (
+          <div className="flex justify-center mb-6">
+            {logo}
+          </div>
+        )}
+
+        {/* Title */}
+        <h1 className="text-2xl font-bold text-center mb-2 text-slate-900">
+          {title}
+        </h1>
+        <p className="text-center mb-8 text-slate-600">
+          {subtitle}
+        </p>
+
+        {/* Error */}
+        {error && (
+          <div className="mb-6 px-4 py-3 rounded-lg bg-red-500 text-white text-center text-sm">
+            {error}
+          </div>
+        )}
+
+        {/* Login Form */}
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <div>
+            <label
+              htmlFor="admin-email"
+              className="block text-sm font-medium mb-2 text-slate-700"
+            >
+              Email
+            </label>
+            <input
+              id="admin-email"
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              required
+              disabled={isLoading}
+              autoComplete="email"
+              className="w-full px-4 py-3 rounded-lg border border-slate-300 bg-white text-slate-900 placeholder-slate-400 focus:outline-none focus:ring-2 focus:ring-slate-500 focus:border-transparent disabled:opacity-50 disabled:cursor-not-allowed"
+              placeholder="admin@example.com"
+            />
+          </div>
+
+          <div>
+            <label
+              htmlFor="admin-password"
+              className="block text-sm font-medium mb-2 text-slate-700"
+            >
+              Password
+            </label>
+            <div className="relative">
+              <input
+                id="admin-password"
+                type={showPassword ? 'text' : 'password'}
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                required
+                disabled={isLoading}
+                autoComplete="current-password"
+                className="w-full px-4 py-3 pr-12 rounded-lg border border-slate-300 bg-white text-slate-900 placeholder-slate-400 focus:outline-none focus:ring-2 focus:ring-slate-500 focus:border-transparent disabled:opacity-50 disabled:cursor-not-allowed"
+                placeholder="Enter your password"
+              />
+              <button
+                type="button"
+                onClick={() => setShowPassword(!showPassword)}
+                className="absolute right-3 top-1/2 transform -translate-y-1/2 text-slate-500 hover:text-slate-700"
+                aria-label={showPassword ? 'Hide password' : 'Show password'}
+              >
+                {showPassword ? (
+                  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" className="w-5 h-5">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13.875 18.825A10.05 10.05 0 0112 19c-4.478 0-8.268-2.943-9.543-7a9.97 9.97 0 011.563-3.029m5.858.908a3 3 0 114.243 4.243M9.878 9.878l4.242 4.242M9.878 9.878L6.464 6.464m7.535 7.535l3.415 3.414M3 3l3.464 3.464M21 21l-3.415-3.414" />
+                  </svg>
+                ) : (
+                  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" className="w-5 h-5">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z" />
+                  </svg>
+                )}
+              </button>
+            </div>
+          </div>
+
+          <button
+            type="submit"
+            disabled={isLoading}
+            className="w-full py-3 px-4 rounded-lg font-semibold text-white transition-colors bg-slate-700 hover:bg-slate-800 disabled:bg-slate-400 disabled:cursor-not-allowed"
+          >
+            {isLoading ? (
+              <span className="flex items-center justify-center">
+                <svg className="animate-spin -ml-1 mr-3 h-5 w-5 text-white" fill="none" viewBox="0 0 24 24">
+                  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                  <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                </svg>
+                Signing in...
+              </span>
+            ) : (
+              'Sign In'
+            )}
+          </button>
+        </form>
+
+        {/* Security notice */}
+        <p className="mt-6 text-center text-xs text-slate-500">
+          This login is for authorized administrators only.
+          <br />
+          All access attempts are logged.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function AdminLoginFallback() {
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-slate-700 via-slate-800 to-slate-900">
+      <div className="text-center">
+        <svg className="animate-spin h-10 w-10 mx-auto text-white" fill="none" viewBox="0 0 24 24">
+          <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+          <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+        </svg>
+        <p className="mt-4 text-slate-400">Loading...</p>
+      </div>
+    </div>
+  );
+}
+
+export default function AdminLoginPage(props: AdminLoginFormProps) {
+  return (
+    <Suspense fallback={<AdminLoginFallback />}>
+      <AdminLoginForm {...props} />
+    </Suspense>
+  );
+}
+
+export { AdminLoginForm, AdminLoginFallback };
+export type { AdminLoginFormProps };