Authentication Flow (JWT)

Relevant source files

The following files were used as context for generating this wiki page:

• PLAN.md
• backend/src/middleware/auth.ts
• frontend/src/pages/LoginPage.tsx
• frontend/src/api/endpoints.ts
• frontend/src/components/Layout.tsx
• backend/src/modules/users/users.routes.ts

Introduction

The MuteTaxes_Backend authentication system is designed as a demonstration-focused, username-only login mechanism utilizing JSON Web Tokens (JWT). Its primary purpose is to identify users so that the system can perform relationship-based access control (ReBAC) checks via OpenFGA.

The flow ensures that users are authenticated before accessing protected resources, with a specific distinction for "Super Admin" users who manage the overall system configuration. Authentication state is managed on the frontend via local storage and a specialized context, while the backend validates tokens through middleware.

Sources: PLAN.md:14-18, PLAN.md:120-125, frontend/src/pages/LoginPage.tsx:55-58

System Architecture

Authentication Components

The authentication architecture is split between the React frontend and the Express backend.

Component	Responsibility	Relevant Files
Frontend API	Executes login requests and manages the Bearer token in headers.	frontend/src/api/endpoints.ts
Auth Middleware	Extracts and verifies JWTs from incoming request headers.	backend/src/middleware/auth.ts
Login Page	Provides the user interface for username-only entry.	frontend/src/pages/LoginPage.tsx
Protected Routes	Validates token presence before rendering components or allowing API access.	frontend/src/App.tsx, backend/src/modules/users/users.routes.ts

Sources: backend/src/middleware/auth.ts:1-21, frontend/src/api/endpoints.ts:39-44, PLAN.md:120-125

Login Logic and Data Flow

The system uses a simplified "Demo Auth" strategy where a valid username results in the issuance of a JWT. The token contains the user's unique ID and username as its payload.

The diagram above illustrates the login sequence and subsequent authenticated requests using the JWT.
Sources: PLAN.md:120-125, backend/src/middleware/auth.ts:1-21, frontend/src/pages/LoginPage.tsx:13-33

Backend Implementation

JWT Verification Middleware

The backend uses a standard middleware pattern to protect routes. It expects an Authorization header formatted as Bearer <token>.

• Verification: The middleware calls verifyToken to decode the payload.
• Request Augmentation: Upon successful verification, the user's id and username are attached to the request object as req.user.
• Error Handling: If the token is missing or invalid, the server returns a 401 Unauthorized response.

Sources: backend/src/middleware/auth.ts:9-21

Super Admin Authorization

Certain endpoints, particularly those related to user and role management, require higher privileges. These routes use both authenticate and requireSuperAdmin middleware. For example, the user management routes are protected to ensure only a Super Admin can create new users or assign roles.

Sources: backend/src/modules/users/users.routes.ts:8-10, frontend/src/components/Layout.tsx:64-80

Frontend Implementation

Token Management

The frontend utilizes a login function that communicates with the /auth/login endpoint. When the response is received, the token is stored (typically in localStorage as per the project plan) and used for all subsequent apiFetch calls.

export const login = (username: string) =>
  apiFetch<LoginResponse>("/auth/login", {
    method: "POST",
    body: JSON.stringify({ username })
  });

Sources: frontend/src/api/endpoints.ts:39-44, PLAN.md:18

User Interface Feedback

The UI dynamically adapts based on the authentication state:

• LoginPage: Redirects to home if a token is already present.
• Layout: Displays the current username and a "Log out" button which clears the authentication state.
• Navigation: Sidebar links for administrative tasks (Users, Roles, Tables) are only visible if the user is identified as a Super Admin.

Sources: frontend/src/pages/LoginPage.tsx:13-17, frontend/src/components/Layout.tsx:28-40, frontend/src/components/Layout.tsx:70-80

Summary

The Authentication Flow in MuteTaxes_Backend provides a streamlined JWT-based identity system. It bridges the gap between simple user identification and complex relationship-based authorization by providing the necessary user context for OpenFGA checks. By storing the user ID within the JWT sub claim, the backend can consistently verify permissions across all protected API modules.

Sources: PLAN.md:14-18, backend/src/middleware/auth.ts:17-18