ca-grow-ops-manager/docs/SPRINT-2-AUTH.md

# Sprint 2: Authentication & RBAC

**Date**: 2025-12-09  
**Status**: 🟡 In Progress  
**Duration**: 8-10 hours  
**Priority**: 🔴 Critical

---

## 🎯 Objective

Implement secure authentication and role-based access control (RBAC) to protect all API endpoints and enforce permissions based on user roles.

---

## 📋 Current State

### What Works

- ✅ Basic login endpoint exists (`/api/auth/login`)
- ✅ JWT plugin registered in Fastify
- ✅ User model with Role enum (OWNER, MANAGER, GROWER, STAFF)
- ✅ Frontend AuthContext exists

### What's Missing

- ❌ Password hashing (currently plaintext)
- ❌ JWT token generation and validation
- ❌ Auth middleware to protect routes
- ❌ RBAC middleware for role-based permissions
- ❌ Refresh token logic
- ❌ Proper error handling for auth failures

---

## 🏗️ Implementation Plan

### Phase 1: Backend Auth Core (3-4 hours)

#### Task 2.1: Password Hashing

- [ ] Install bcrypt: `npm install bcrypt @types/bcrypt`
- [ ] Create password utility functions (hash, compare)
- [ ] Update seed script to hash passwords
- [ ] Update login controller to compare hashed passwords

#### Task 2.2: JWT Token Generation

- [ ] Create JWT utility functions (generate access token, generate refresh token)
- [ ] Update login endpoint to return JWT tokens
- [ ] Add token expiry configuration (15min access, 7d refresh)
- [ ] Store refresh tokens in Redis

#### Task 2.3: Auth Middleware

- [ ] Create `authenticate` middleware (verify JWT)
- [ ] Add user info to request object
- [ ] Handle expired tokens
- [ ] Handle invalid tokens

#### Task 2.4: RBAC Middleware

- [ ] Create `authorize(...roles)` middleware
- [ ] Check user role against allowed roles
- [ ] Return 403 Forbidden if unauthorized

---

### Phase 2: Protected Routes (2-3 hours)

#### Task 2.5: Apply Auth to Routes

- [ ] Protect `/api/rooms` (all roles)
- [ ] Protect `/api/batches` (all roles)
- [ ] Protect `/api/timeclock` (all roles)
- [ ] Add role restrictions where needed

#### Task 2.6: Refresh Token Endpoint

- [ ] Create `/api/auth/refresh` endpoint
- [ ] Validate refresh token
- [ ] Generate new access token
- [ ] Return new tokens

#### Task 2.7: Logout Endpoint

- [ ] Create `/api/auth/logout` endpoint
- [ ] Invalidate refresh token in Redis
- [ ] Clear tokens from client

---

### Phase 3: Frontend Integration (2-3 hours)

#### Task 2.8: Update AuthContext

- [ ] Store tokens in localStorage
- [ ] Add token refresh logic
- [ ] Add automatic logout on 401
- [ ] Add token to all API requests

#### Task 2.9: Update API Client

- [ ] Create axios instance with interceptors
- [ ] Add Authorization header to requests
- [ ] Handle 401 (refresh token or logout)
- [ ] Handle 403 (show permission error)

#### Task 2.10: Update Login Flow

- [ ] Store tokens on successful login
- [ ] Redirect to dashboard
- [ ] Handle login errors
- [ ] Add loading states

---

### Phase 4: Testing & Polish (1-2 hours)

#### Task 2.11: Manual Testing

- [ ] Test login with correct credentials
- [ ] Test login with wrong credentials
- [ ] Test protected routes without token
- [ ] Test protected routes with valid token
- [ ] Test token expiry and refresh
- [ ] Test logout

#### Task 2.12: Add More Test Users

- [ ] Create users for each role (MANAGER, GROWER, STAFF)
- [ ] Update seed script
- [ ] Document test credentials

---

## 🔐 Security Considerations

### Password Security

- Use bcrypt with salt rounds = 10
- Never log passwords
- Never return password hashes in API responses

### Token Security

- Access tokens: Short-lived (15 minutes)
- Refresh tokens: Longer-lived (7 days)
- Store refresh tokens in httpOnly cookies (future enhancement)
- Invalidate refresh tokens on logout

### RBAC Rules

- **OWNER**: Full access to everything
- **MANAGER**: Full access except user management
- **GROWER**: Read/write batches, rooms, tasks
- **STAFF**: Read-only + timeclock

---

## 📊 Success Criteria

- [ ] All API endpoints require authentication
- [ ] Passwords are hashed with bcrypt
- [ ] JWT tokens working (access + refresh)
- [ ] Role-based permissions enforced
- [ ] Frontend stores and uses tokens correctly
- [ ] Token refresh works automatically
- [ ] Logout invalidates tokens
- [ ] Multiple test users available (one per role)
- [ ] No security vulnerabilities (no plaintext passwords, no exposed secrets)

---

## 🧪 Testing Checklist

### Backend Tests

- [ ] Login with valid credentials returns tokens
- [ ] Login with invalid credentials returns 401
- [ ] Protected route without token returns 401
- [ ] Protected route with valid token returns data
- [ ] Protected route with expired token returns 401
- [ ] Refresh token endpoint works
- [ ] Logout invalidates refresh token
- [ ] RBAC blocks unauthorized roles

### Frontend Tests

- [ ] Login form submits correctly
- [ ] Tokens stored in localStorage
- [ ] API requests include Authorization header
- [ ] 401 triggers token refresh
- [ ] Logout clears tokens and redirects

---

## 📝 Files to Modify

### Backend

- `backend/package.json` - Add bcrypt dependency
- `backend/src/utils/password.ts` - New file (hash, compare)
- `backend/src/utils/jwt.ts` - New file (generate, verify)
- `backend/src/middleware/auth.ts` - New file (authenticate, authorize)
- `backend/src/controllers/auth.controller.ts` - Update login, add refresh, logout
- `backend/src/routes/*.routes.ts` - Add auth middleware
- `backend/prisma/seed.js` - Hash passwords

### Frontend

- `frontend/src/context/AuthContext.tsx` - Update token handling
- `frontend/src/lib/api.ts` - New file (axios instance with interceptors)
- `frontend/src/pages/LoginPage.tsx` - Update login flow

---

## 🚀 Let's Begin

Starting with **Task 2.1: Password Hashing**...