Setting Up the JWT Security Spec File

specs/
├── api-contract.md
├── seed-data.json
├── features/
│   └── task-filtering.md
└── security/
    └── security-spec.md

description: Implement a feature described in a markdown spec file anywhere under specs. ...

# Telusko Workflow Engine: Security Specification

## Scope
Defines the authentication and authorisation system for the
Telusko Workflow Engine backend. Replaces existing UX-only role
checks with real server-side security.

## What we are building

### Authentication
- Username + password login via POST /api/auth/login
- Passwords hashed with bcrypt
- Successful login returns a signed JWT (HS256, python-jose library)
- JWT payload: sub (username), role, exp (expiry timestamp)
- Access token expiry: 60 minutes

### Authorisation (RBAC)
- Every /api/tasks endpoint now requires a valid Bearer token
- Unauthorised requests return 401
- Authenticated but unauthorised requests return 403

## Tech stack
- FastAPI OAuth2PasswordBearer for the bearer token scheme
- python-jose[cryptography] for JWT encode/decode
- bcrypt for password hashing
- python-multipart for OAuth2PasswordRequestForm
- Existing SQLAlchemy 2.0 async + SQLite

## New files to create

### backend/app/models/user.py
SQLAlchemy User model with columns:
- id (int, primary key)
- username (str, unique, indexed, max 50 chars)
- password_hash (str, not null)
- role (Enum: admin, content_team, video_editor, uploader)
- created_at (datetime, default utc now)

### backend/app/schemas/user.py
- UserCreate (username, password, role), for admin user creation
- UserResponse (id, username, role, created_at), no password field

### backend/app/schemas/auth.py
- Token (access_token: str, token_type: str defaulting to 'bearer')
- TokenData (username: str, role: str)

### backend/app/security/password.py
- hash_password(plain: str) -> str
- verify_password(plain: str, hashed: str) -> bool

### backend/app/security/jwt.py
- create_access_token(data: dict, expires_delta: timedelta) -> str
- decode_access_token(token: str) -> TokenData
Secret key and algorithm come from environment variables.
Raise 401 HTTPException if the token is invalid or expired.

### backend/app/security/dependencies.py
- get_current_user(token = Depends(oauth2_scheme)) -> User
  Decode JWT, look up user in DB, raise 401 if any step fails
- require_role(*allowed_roles) -> callable
  Returns a dependency that checks current_user.role, raises 403 if not allowed

### backend/app/api/v1/auth.py
- POST /api/auth/login: accepts OAuth2PasswordRequestForm, returns Token, 401 on bad credentials
- POST /api/auth/users (admin only): accepts UserCreate, stores a hashed password
- GET /api/auth/me: returns UserResponse for the current user

## Files to modify

### backend/app/api/v1/tasks.py
- GET /api/tasks: Depends(get_current_user), any authenticated role
- POST /api/tasks: Depends(require_role('admin', 'content_team'))
- PUT /api/tasks/{id}: Depends(get_current_user) + state-advance check
    admin: can advance from any state
    content_team: only from code_ready
    video_editor: from recorded or editing
    uploader: only from uploaded
  If role not allowed: 403 {'detail': 'role X cannot advance from state Y'}
- DELETE /api/tasks/{id}: Depends(require_role('admin'))

### backend/app/main.py
- Include the auth router at prefix /api/auth
- Update CORS allow_headers to include 'Authorization'

## Database
- Generate and apply a new Alembic migration for the users table
- Update backend/seed.py to add five demo users (idempotent):
  admin/admin123 (admin), content/content123 (content_team),
  editor/editor123 (video_editor), uploader/uploader123 (uploader),
  demo/demo123 (video_editor)
  These are demo credentials only. Production must use strong passwords.

## Frontend changes
This spec EXPLICITLY OVERRIDES the CLAUDE.md no-frontend rule.

### frontend/app.js
- Remove the role dropdown logic entirely
- Show a login form when localStorage has no 'telusko_token'
- On successful login, store the token in localStorage as 'telusko_token'
- In apiFetch, add Authorization: Bearer <token> to every request
- On any 401 response, clear the token and show the login form
- Add a logout button that clears localStorage and shows the login form

### frontend/index.html
- Add a hidden login modal at the top of <body>
- Add a logout button in the header

### frontend/styles.css
- Style the login form and logout button to match the existing Kanban UI

## Acceptance criteria
- Unauthenticated GET /api/tasks returns 401
- Login with correct credentials returns 200 with a JWT
- Login with wrong credentials returns 401
- JWT payload contains sub, role, exp
- An expired token returns 401
- A tampered token returns 401
- Content team can create tasks (POST returns 201)
- Uploader cannot create tasks (POST returns 403)
- Admin can delete tasks (DELETE returns 204)
- Uploader cannot delete tasks (DELETE returns 403)
- Video editor cannot advance a code_ready task (PUT returns 403)
- Video editor CAN advance an editing task (PUT returns 200)
- Frontend shows login form on first load
- After login the board renders with real data
- Logout clears token and returns to login form

## Out of scope
- Refresh tokens (separate spec)
- Password reset flow (separate spec)
- Email verification (separate spec)
- Account lockout after failed logins (separate spec)
- HTTPS termination

## Smoke tests (all must pass)
(curl commands for: unauthenticated 401, admin login, authenticated GET,
uploader DELETE 403, bad credentials 401. See the next lesson.)

I want to add authentication and authorisation to this project.
Requirements:
- username + password login, bcrypt hashed passwords
- JWT access tokens, 60 minutes, HS256
- four roles: admin, content_team, video_editor, uploader
- the advance rules from ROLE_CONFIG in frontend/app.js, enforced on the server
- 401 for missing or invalid tokens, 403 for wrong roles
- a login form in the frontend, token in localStorage, logout button

Read CLAUDE.md, specs/api-contract.md and the existing backend code.
Write a spec to specs/security/security-spec.md with: scope, files to create,
files to modify, database changes, frontend changes, acceptance criteria,
out of scope, and curl smoke tests. Do not write any code.