mimic/tasks/todo.md

Sprint 1 — Auth + CRUD Engagement

Branche : sprint/1-auth-engagements Statut : 🟢 PLAN APPROUVÉ (spec-reviewer 2026-05-26) — prêt pour dispatch backend-builder Base : main Objectif : poser l'infrastructure (Flask + SQLite + React + Docker + Makefile + tests) ET livrer une première feature de bout en bout testable sur l'UI — login + admin gère les comptes + tout utilisateur authentifié peut créer/lister/éditer/supprimer des engagements.

---

1. User stories

US-1 — En tant qu'admin, je bootstrap le premier compte admin

Pourquoi : sinon impossible d'utiliser l'application au premier démarrage.

Critères d'acceptation

• AC-1.1 : la commande make create-admin USER=alice PASS=p4ssw0rd crée un user alice avec le rôle admin et le password hashé (argon2).
• AC-1.2 : la commande échoue proprement (exit ≠ 0, message clair) si le username existe déjà.
• AC-1.3 : la commande échoue si le password fait moins de 8 caractères.
• AC-1.4 : la commande s'exécute via docker exec mimic flask create-admin … (le Makefile encapsule cet appel).

US-2 — En tant qu'utilisateur, je me connecte et me déconnecte

Pourquoi : porte d'entrée de l'application.

Critères d'acceptation

• AC-2.1 : POST /api/auth/login {username, password} retourne {access_token, user: {id, username, role}} (200) si credentials valides.
• AC-2.2 : 401 si credentials invalides, avec un message générique ("Invalid credentials") — pas de fuite username vs password.
• AC-2.3 : POST /api/auth/logout invalide le token côté client (UI supprime le token). Côté serveur : optionnel V1, on accepte un logout client-side.
• AC-2.4 : page /login affiche le formulaire ; soumission OK → redirection /engagements. Soumission KO → message d'erreur visible.
• AC-2.5 : navigation vers /engagements sans token → redirection /login.
• AC-2.6 : si une requête API retourne 401 (token expiré ou invalide), l'intercepteur axios purge le token et redirige vers /login avec un toast "Session expirée".

US-3 — En tant qu'admin, je gère les comptes utilisateurs

Pourquoi : créer redteam/soc accounts depuis l'UI.

Critères d'acceptation

• AC-3.1 : GET /api/users (admin only) → liste [{id, username, role, created_at}].
• AC-3.2 : POST /api/users {username, password, role} (admin only) → 201 + objet user (sans password_hash). 400 si username existe ou password < 8 chars.
• AC-3.3 : PATCH /api/users/<id> {role?, password?} (admin only) → 200, modifie role et/ou password.
• AC-3.4 : DELETE /api/users/<id> (admin only) → 204. Refuse de supprimer le dernier admin (409).
• AC-3.5 : tout autre rôle (redteam/soc) appelant ces endpoints reçoit 403.
• AC-3.6 : page /admin/users (admin only) liste les users avec actions "Créer", "Modifier rôle", "Reset password", "Supprimer".
• AC-3.7 : un user redteam/soc qui visite /admin/users est redirigé vers /engagements avec un toast "Accès refusé".

US-4 — En tant qu'utilisateur authentifié, je gère les engagements

Pourquoi : la feature métier centrale du Sprint 1.

Critères d'acceptation

• AC-4.1 : GET /api/engagements (auth) → [{id, name, description, start_date, end_date, status, created_at, created_by}].
• AC-4.2 : POST /api/engagements {name, description?, start_date, end_date?, status?} (auth) → 201. Valide : name non vide, start_date parseable, end_date >= start_date si fournie, status ∈ {planned, active, closed} (défaut planned).
• AC-4.3 : GET /api/engagements/<id> (auth) → 200 + objet, 404 si inconnu.
• AC-4.4 : PATCH /api/engagements/<id> (auth, redteam ou admin) → 200, modifie les champs fournis.
• AC-4.5 : DELETE /api/engagements/<id> (admin ou redteam) → 204.
• AC-4.6 : un user soc peut lire (GET) mais pas créer/modifier/supprimer (403).
• AC-4.7 : page /engagements liste les engagements avec colonnes (name, status badge, dates, created_by). Boutons "Nouveau", "Voir", "Éditer", "Supprimer" selon rôle.
• AC-4.8 : page /engagements/new et /engagements/<id>/edit (formulaire avec validation côté client + erreurs API affichées).
• AC-4.9 : page /engagements/<id> (détail), placeholder "Simulations à venir au Sprint 2".

US-5 — En tant qu'utilisateur, l'UI respecte DESIGN.md

Pourquoi : non négociable selon SPEC.md.

Critères d'acceptation

• AC-5.1 : la palette, typographie, espacements, composants (boutons, inputs, badges) suivent strictement DESIGN.md.
• AC-5.2 : layout responsive desktop-first (≥ 1024px), pas de breakage visible jusqu'à 1280×720 minimum.
• AC-5.3 : états loading / error / empty implémentés pour la liste d'engagements et la liste d'users.

US-6 — Le livrable se déploie via Docker + Makefile

Pourquoi : exigence SPEC.md.

Critères d'acceptation

• AC-6.1 : make build produit l'image docker mimic:latest (Dockerfile multistage : Node build → Python runtime).
• AC-6.2 : make start lance le container, l'app est accessible sur http://localhost:5000 (front + API).
• AC-6.3 : make stop, make restart, make logs fonctionnent.
• AC-6.4 : SQLite persisté via volume nommé mimic-data (la DB survit à make restart).
• AC-6.5 : make test-backend, make test-frontend, make test-e2e exécutent les suites respectives.

---

2. Brief technique — Backend Builder

Scope strict : backend/, Dockerfile, Makefile (en collab avec ce sprint uniquement).

Livrables

1. Structure :

   backend/
     __init__.py              # ⚠️ requis pour que `backend.app:create_app` soit importable depuis /app dans le Dockerfile
     app/
       __init__.py            # create_app() factory
       config.py              # DevConfig / ProdConfig (SECRET_KEY, JWT_SECRET, SQLALCHEMY_DATABASE_URI)
       extensions.py          # db = SQLAlchemy(), migrate = Migrate()
       cli.py                 # @app.cli.command("create-admin")
       models/
         __init__.py
         user.py              # User(id, username, password_hash, role, created_at)
         engagement.py        # Engagement(id, name, description, start_date, end_date, status, created_at, created_by)
       auth/
         __init__.py
         jwt.py               # encode_token / decode_token
         hashing.py           # argon2 hash & verify
         decorators.py        # @login_required, @role_required("admin")
       api/
         __init__.py
         auth.py              # /login, /logout, /me
         users.py             # CRUD users (admin)
         engagements.py       # CRUD engagements
       serializers.py         # to_dict() helpers — engagement renvoie created_by={id, username}, jamais l'objet User brut
       errors.py              # uniform JSON error handler
     migrations/              # alembic init + 0001 initial schema
     tests/
       conftest.py            # app fixture, db fixture, auth helpers
       test_auth.py           # login OK + 401 invalid + 401 token expiré
       test_users.py          # CRUD admin only, 403 redteam/soc, last-admin protection (AC-3.4)
       test_engagements.py    # CRUD redteam/admin, 403 soc en write, serializer created_by
       test_cli_create_admin.py  # success + duplicate username (AC-1.2) + password < 8 chars (AC-1.3)
     pyproject.toml
     requirements.txt         # flask, flask-sqlalchemy, flask-migrate, pyjwt, argon2-cffi, ruff, mypy, pytest
   

2. Endpoints : voir critères AC-2 / AC-3 / AC-4.

3. Modèles : voir SPEC.md § Modèle de données.

4. Config :

   • SQLALCHEMY_DATABASE_URI = f"sqlite:///{os.environ.get('MIMIC_DB_PATH', '/data/mimic.sqlite')}" — l'env var MIMIC_DB_PATH du Dockerfile surcharge le chemin si présent (utile pour tests ou changement de mount).
   • JWT_SECRET lu depuis env var MIMIC_JWT_SECRET, requis (raise si absent en Prod).
   • JWT_EXP_MINUTES = 60.

5. CLI : flask create-admin <user> <pass> (avec validations AC-1.2/1.3).

6. Serializer engagement : la réponse JSON expose created_by sous forme {"id": <int>, "username": <str>} — pas l'objet User complet, pas seulement l'id.

7. Tests : couverture success / failure / edge sur chaque endpoint et CLI. Les AC-1.2 et AC-1.3 doivent avoir leur propre test dans test_cli_create_admin.py.

8. Lint / typing : ruff clean, mypy clean sur app/.

Règles

• Pas de touche au frontend.
• Pas d'invention de dépendances hors de la liste ci-dessus sans escalade au team-lead.
• Renvoyer le summary attendu (cf. .claude/agents/backend-builder.md).

---

3. Brief technique — Frontend Builder

Scope strict : frontend/ UNIQUEMENT. Le dossier e2e/ est interdit au frontend-builder — il est sous la responsabilité exclusive du test-verifier (scaffolding Playwright + tests).

Livrables

1. Structure :

   frontend/
     package.json             # react, react-dom, react-router-dom, @tanstack/react-query, axios, tailwindcss, vite, typescript, vitest, @testing-library/react
     vite.config.ts           # proxy /api -> http://localhost:5000 en dev
     tailwind.config.ts       # tokens issus de DESIGN.md, font-family principale = "Inter"
     tsconfig.json
     index.html
     src/
       main.tsx
       App.tsx                # router, QueryClientProvider
       api/
         client.ts            # axios + interceptor (Bearer + 401 purge → /login)
         auth.ts              # login, me
         users.ts             # CRUD users
         engagements.ts       # CRUD engagements
         types.ts
       hooks/
         useAuth.ts           # token in memory + localStorage, role helpers (isAdmin, isRedteam, isSoc)
         useEngagements.ts    # TanStack Query hooks
         useUsers.ts
         useToast.ts          # provider + hook pour notifications éphémères
       pages/
         LoginPage.tsx
         EngagementsListPage.tsx
         EngagementFormPage.tsx       # new + edit
         EngagementDetailPage.tsx
         UsersAdminPage.tsx
       components/
         Layout.tsx           # nav, topbar, role-aware menu
         ProtectedRoute.tsx   # redirect to /login if no token, role gate
         StatusBadge.tsx
         FormField.tsx
         EmptyState.tsx
         ErrorState.tsx
         LoadingState.tsx
         Toast.tsx            # composant + ToastProvider (utilisé par AC-2.6 + AC-3.7)
       styles/
         index.css            # tailwind base + DESIGN.md tokens
         fonts.css            # @font-face Inter (bundlée localement dans public/fonts/, AUCUN CDN)
     public/
       fonts/                 # fichiers Inter .woff2 (déposés via npm install + copie post-install, ou commit direct)
     tests/
       components/*.test.tsx  # Vitest
   

2. Police : Inter (substitut Forma DJR Micro choisi par défaut parmi les 3 options DESIGN.md §86-89). Bundlée localement en .woff2, jamais via Google Fonts/CDN. Configurée dans tailwind.config.ts comme font-sans et chargée via @font-face dans styles/fonts.css.

3. Routing :

   • /login
   • /engagements (auth, all roles)
   • /engagements/new (auth, redteam|admin)
   • /engagements/:id (auth, all roles)
   • /engagements/:id/edit (auth, redteam|admin)
   • /admin/users (auth, admin only)
   • / → redirige vers /engagements ou /login

4. Auth : token JWT en mémoire + localStorage ; intercepteur axios ajoute Authorization: Bearer <token> ; 401 → purge token + redirect /login + toast "Session expirée" (AC-2.6).

5. Tests Vitest : 1 test par composant non trivial (états loading/error/empty, comportement des rôles dans ProtectedRoute, Toast déclenché par 401).

Règles

• Lit le summary du backend-builder EN PREMIER.
• Pas d'invention d'endpoints. Mismatch → escalade au team-lead.
• Respect strict de DESIGN.md pour palette/typo/composants.
• Pas de CDN remote au runtime — bundle local (police Inter incluse).
• Interdiction absolue de toucher e2e/ (responsabilité test-verifier).

---

4. Brief — Docker / Makefile (réalisé par le backend-builder)

docker/Dockerfile (multistage)

# Stage 1: build front
FROM node:20-alpine AS frontend-build
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci
COPY frontend/ ./
RUN npm run build

# Stage 2: python runtime
FROM python:3.12-slim
WORKDIR /app
COPY backend/requirements.txt ./backend/
RUN pip install --no-cache-dir -r backend/requirements.txt
COPY backend/ ./backend/
COPY --from=frontend-build /app/frontend/dist ./backend/app/static

ENV FLASK_APP=backend.app:create_app
ENV PYTHONUNBUFFERED=1
ENV PYTHONPATH=/app
# Variables surchargeables au `docker run` :
ENV MIMIC_PORT=5000
ENV MIMIC_DB_PATH=/data/mimic.sqlite

VOLUME ["/data"]
EXPOSE 5000

# Entrypoint : applique les migrations Alembic puis lance Flask
COPY docker/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

docker/entrypoint.sh :

#!/bin/sh
set -e
flask db upgrade
exec flask run --host=0.0.0.0 --port="${MIMIC_PORT:-5000}"

Flask sert backend/app/static en racine / ET expose les blueprints sous /api/*. La DB SQLite vit dans /data/mimic.sqlite (volume nommé mimic-data) — survit à make restart (AC-6.4).

Makefile

Targets requis et leur sémantique :

Target	Action
build	docker build -f docker/Dockerfile -t mimic:latest .
start	docker run -d --name mimic -p $(PORT):5000 -v mimic-data:/data --env-file .env mimic:latest (PORT ?= 5000)
stop	docker stop mimic && docker rm mimic
restart	$(MAKE) stop && $(MAKE) start
update	git pull && $(MAKE) build && $(MAKE) restart
logs	docker logs -f mimic
create-admin	docker exec mimic flask create-admin $(USER) $(PASS) (requiert USER= et PASS=)
update-mitre	placeholder no-op Sprint 1 (@echo "MITRE update: Sprint 2+")
test-backend	docker exec mimic pytest -q backend/tests/ (ou run local en venv)
test-frontend	cd frontend && npm run test -- --run
test-e2e	cd e2e && npx playwright test (container doit être up)
clean	docker rm -f mimic 2>/dev/null; docker volume rm mimic-data 2>/dev/null; rm -rf backend/__pycache__ frontend/node_modules frontend/dist

---

5. Definition of Done — Sprint 1

• Tous les critères d'acceptation des US 1→6 passent.
• pytest, ruff, mypy clean côté backend.
• npm run typecheck, lint, test clean côté frontend.
• Playwright suite verte côté e2e/.
• Image docker se build (make build), démarre (make start), répond sur :5000.
• Code review (Opus) sans BLOCKER ouvert.
• SPEC.md, README.md, CHANGELOG.md à jour.
• PR ouverte sur la branche sprint, validée par l'utilisateur après récap synthétique.

---

6. Risques & questions à clarifier avec l'utilisateur AVANT de coder

1. DESIGN.md : faut-il que je relise DESIGN.md (27 Ko, déjà présent dans le repo) avant que le frontend-builder l'utilise ? OUI
2. Persistance SQLite : DB stockée dans /data/mimic.sqlite montée comme volume nommé mimic-data. OK ? OK
3. Port : 5000 (Flask défaut). Conflit possible avec macOS AirPlay si jamais — on s'en fiche en Linux. Surcharge du port possible via dockerfile et container.
4. CSRF : on est en API JWT pure, pas de cookie session, donc pas de CSRF protection nécessaire côté serveur. OK ? OK
5. Refresh token : exclu V1. JWT court (60 min) ; user devra se reconnecter. OK ? OK
6. Logout : V1 = client-side uniquement (purge du token). Pas de blacklist. OK ? OK
7. CI : pas mentionné dans la spec. Skip pour Sprint 1 ? (à confirmer) On verra plus tard.
8. README.md : actuellement absent. Le team-lead le crée en fin de Sprint 1 avec instructions make build / start / create-admin. OK.

---

7. Plan d'exécution (séquence)

Branche unique pour ce sprint : sprint/1-auth-engagements (pas de sous-branches builders, le sprint est séquentiel).

1. ✅ Spec-reviewer (.claude/agents/spec-reviewer.md, override projet du built-in) valide ce plan vs SPEC.md.
2. 🔵 Backend-builder implémente backend/ + docker/Dockerfile + docker/entrypoint.sh + Makefile, livre son summary (incluant le contrat API).
3. 🔵 Frontend-builder lit le summary backend puis implémente le front (frontend/ UNIQUEMENT, jamais e2e/).
4. 🔵 Code-reviewer relit le diff du sprint (LSP-first, focus bugs/qualité/scope).
5. 🔵 Test-verifier scaffolds e2e/ (Playwright config, package.json, fixtures auth) puis écrit les acceptance tests Playwright et exécute la suite contre le container démarré via make start.
6. 🟢 Team-lead (moi) prépare la PR + récap synthétique → user valide.

Responsabilité e2e/ : exclusivement le test-verifier. Backend-builder et frontend-builder n'y touchent jamais.