Feature: Authentication & Role-Based Access Control (Auth & RBAC) with Next.js BFF

Summary

Implemented a production-ready Authentication and Role-Based Access Control (RBAC) architecture for data-crawler-fe, adhering to Next.js 16 App Router standards and OWASP security recommendations. Upgraded the session mechanism to a Next.js Backend-For-Frontend (BFF) pattern with HttpOnly, Secure, SameSite=Lax cookies, completely eliminating localStorage token storage to achieve 100% immunity against Cross-Site Scripting (XSS) token exfiltration.

Key Highlights & Changes

1. Security & Next.js BFF Architecture

• HttpOnly Cookies: All authentication tokens (auth_token, refresh_token, user_role) are issued and managed exclusively on the server side via Next.js Route Handlers. JavaScript running in the browser cannot access or exfiltrate tokens.
• Auth Route Handler (/api/auth/[action]): Handles server-side authentication operations (login, logout, me, refresh, etc.), dynamically sets SameSite=Lax cookies, and adapts Secure based on HTTPS/localhost protocols.
• API Proxy Handler (/api/proxy/[...path]): Acts as a reverse proxy for internal crawler and dashboard API endpoints. Automatically injects Authorization: Bearer <token> and handles transparent, server-to-server silent token refreshes.
• Zero Client-Side Token Storage: Removed all localStorage.getItem("auth_token") references from api-client.ts and auth-storage.ts.

2. Auth Context & Session Management

• useAuth Hook & AuthProvider: Centralized authentication state (user, isAuthenticated, isLoading, role, isAdmin).
• TanStack Query Integration: Profile fetching cached with query key ["auth", "me"] and automatic eviction upon receiving auth:unauthorized events.

3. Route Protection & RBAC Middleware

• Next.js Edge Middleware (middleware.ts):
  • Guards internal application routes (redirects unauthenticated users to /login?redirect=...).
  • Automatically redirects authenticated users away from auth pages back to /.
  • Enforces role requirements on protected administrative endpoints (/admin, /users, /audit-logs, /roles), routing unauthorized roles to a dedicated /forbidden (403) page.
  • Sanitized redirect parameters to prevent redirect loops.

4. Authentication Pages & UI/UX

• Full Auth Suite (src/app/(auth)/...):
  • /login: Form with show/hide password toggle, remember-me checkbox, and natural tab key navigation sequence.
  • /register: Real-time password strength checklist (8+ chars, uppercase, lowercase, numbers, special characters).
  • /forgot-password: Password recovery request with a 60-second cooldown resend timer.
  • /reset-password: Token extraction from query parameters and secure password reset.
  • /verify-email: 4-state account activation flow (verifying, success, error, manual token entry).
• AppShell Layout Separation: Completely hides the main dashboard Navbar and footer on auth pages, providing a focused full-screen experience with minimal Brand links and Language/Theme controls.
• Design System & Accessibility:
  • Fixed input text visibility in Light Mode by migrating hardcoded styles to standard CSS variable tokens (text-foreground, bg-background, border-input).
  • Full bilingual support (Vietnamese & English) via useLanguage.
  • Seamless support for 3 theme modes: Light, Dark, and System.