Module: Authentication

Relevant source files

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

• PLAN.md
• backend/src/modules/users/auth.routes.ts
• frontend/src/api/endpoints.ts
• frontend/src/pages/LoginPage.tsx
• backend/src/seed.ts
• backend/src/routes/index.ts

Introduction

The Authentication module provides a specialized, "username-only" login system designed for the MuteTaxes Relationship-Based Access Control (ReBAC) prototype. Its primary purpose is to identify users and issue JSON Web Tokens (JWT) to facilitate demonstration of dynamic permissions without the overhead of traditional password management.

The module serves as the entry point for both the super_admin (seeded via database) and regular users created during the demo. Once authenticated, the system uses the identity established here to perform authorization checks against OpenFGA and local database records.

Sources: PLAN.md:12-14, frontend/src/pages/LoginPage.tsx:43-46

Architecture and Data Flow

Authentication Flow

The authentication process follows a simplified request-response cycle. The frontend collects a username, which the backend validates against the PostgreSQL database. If the user exists, a JWT is generated and returned to the client for subsequent authorized requests.

The following sequence diagram illustrates the login process:

The flow ensures that only existing users can obtain a token, while the "Super Admin" is established through the initial seeding process.
Sources: PLAN.md:112-123, backend/src/modules/users/auth.routes.ts:10-25

Key Components

Component	Description
POST /auth/login	Endpoint accepting a JSON body with a username string.
JWT Service	Signs tokens using a JWT_SECRET and user ID as the payload.
localStorage	Client-side storage for the JWT token in the React frontend.
super_admin	A unique seeded account used to initialize roles and permissions.

Sources: PLAN.md:15-18, backend/src/modules/users/auth.routes.ts:12-24, frontend/src/api/endpoints.ts:38-42

Implementation Details

Backend Routes and Logic

The authentication logic is encapsulated within the authRoutes module. It relies on Prisma to verify the existence of the username provided in the request body.

// backend/src/modules/users/auth.routes.ts:12-25
authRoutes.post("/login", async (req, res) => {
  const { username } = req.body as { username?: string };
  if (!username) return res.status(400).json({ error: "Username is required" });

  const user = await prisma.user.findUnique({ where: { username } });
  if (!user) return res.status(401).json({ error: "Invalid username" });

  const token = jwt.sign({ userId: user.id }, env.jwtSecret);
  return res.json({
    token,
    user: { id: user.id, username: user.username }
  });
});

Sources: backend/src/modules/users/auth.routes.ts:12-25, backend/src/routes/index.ts:12

Initial System Seeding

To allow first-time access, the system includes a seeding script that creates the super_admin user and role. This script also establishes the initial relationship in the database and OpenFGA.

• Database: Creates a user with the username super_admin.
• OpenFGA: Maps the super_admin user ID to the superadmin role member relation.

Sources: backend/src/seed.ts:31-48, backend/src/seed.ts:74-78

Client-Side Integration

The frontend utilizes a LoginPage component that interacts with the login API endpoint. Upon successful login, the AuthContext is updated, and the user is redirected to the home page.

// frontend/src/api/endpoints.ts:38-42
export const login = (username: string) =>
  apiFetch<LoginResponse>("/auth/login", {
    method: "POST",
    body: JSON.stringify({ username })
  });

Sources: frontend/src/api/endpoints.ts:38-42, frontend/src/pages/LoginPage.tsx:16-29

Conclusion

The Authentication module provides the foundational identity layer for the MuteTaxes backend. By utilizing a simplified username-only approach coupled with standard JWT issuance, it allows the project to focus on its core objective: demonstrating relationship-based authorization through OpenFGA integration. All authenticated sessions rely on the user ID embedded in the JWT to perform subsequent permission checks across the system.