Authentication & User Permissions

📌 What is this for? (Quick Summary for New Interns)

In Simple Words:
Anyone with internet access could find our API address, but we cannot allow unauthorized people to send high-voltage commands to the pod.

This page explains how we lock down the system:

1. We use AWS Cognito to store usernames and passwords.
2. When you log in, Cognito gives your browser a signed digital passport (called a JWT token).
3. Every time your browser asks the cloud for data or clicks a button, it presents this token.
4. We separate users into Admins, Engineers, and Managers so that viewers cannot accidentally launch the pod.

---

1. Our Production Cognito Settings

When setting up your local development environment or deploying a new dashboard, always use these exact settings in your .env file:

• Region: ap-south-1 (Mumbai)
• User Pool ID: ap-south-1_IXNCZVwj4
• App Client ID: 5eup0104notrn3fn4415u3fq3b

⚠️ IMPORTANT WARNING FOR NEW DEVELOPERS:
In the past, someone used an old staging pool (bg6ZECDii). If you put bg6ZECDii in your .env, you will be able to log in, but all API calls will fail with a 401 Unauthorized error because our API Gateway only accepts tokens from ap-south-1_IXNCZVwj4.
Always make sure VITE_USER_POOL_ID=IXNCZVwj4 is set!

---

2. The 3 User Roles (Who Can Do What?)

We divide users into three groups:

Role Name	What They Can Do	Who Is It For?
Admin	Full control: Can enable high voltage, launch the pod, trigger emergency stops, add/delete users, and export CSV logs.	System Leads & Operations Heads
Engineer	Vehicle control: Can enable battery, launch, stop, and monitor live sensors. Cannot manage user accounts.	Test Engineers on the track
Manager	View-only: Can watch live charts, video feeds, and 3D simulation. All buttons to launch or power the pod are completely disabled.	Observers, Guests, & Executives

---

3. How the Backend Enforces This

Even if a clever user modifies their browser code to enable a grayed-out button, the backend Lambda code checks the token cryptographically:

// Server-side check inside PodDashboardRouter
const groups = claims["cognito:groups"] || [];
const canControl = groups.includes("Admin") || groups.includes("Engineer");

if (action === "SEND_CONTROL" && !canControl) {
  return {
    statusCode: 403,
    body: JSON.stringify({ error: "Control access denied. Engineer or Admin required." })
  };
}

If the token doesn't have Admin or Engineer, the command is rejected immediately with 403 Forbidden.