feat: sprint 1 — auth + CRUD engagements

Ship the first feature end-to-end on the UI: users log in with JWT,
admins manage user accounts, and any authenticated user (per RBAC)
can create, list, view, edit, and delete engagements.

Backend (Flask + SQLAlchemy + SQLite, 63 pytest)
- User / Engagement models, Alembic 0001 initial schema
- argon2 password hashing, JWT bearer (60-min TTL), @login_required
  and @role_required decorators
- 13 API endpoints under /api/*, including last-admin protection on
  DELETE/PATCH user and JSON 404 on unknown /api/* paths
- `flask create-admin` CLI with duplicate / short-password handling

Frontend (React + Vite + Tailwind + TanStack Query, 20 vitest)
- Inter font bundled locally (no CDN), DESIGN.md tokens in Tailwind
- LoginPage / EngagementsList / EngagementForm / EngagementDetail /
  UsersAdmin pages with role-aware UI
- Layout, ProtectedRoute, StatusBadge, FormField, LoadingState,
  ErrorState, EmptyState, Toast + provider
- Axios client: Bearer interceptor, 401 → purge + /login + "Session
  expirée" toast, 403 → "Accès refusé" toast (declarative <Navigate>
  for already-authed users, Fragment-keyed admin user rows)

Deployment
- Single multistage Dockerfile (node:20-alpine → python:3.12-slim)
- docker/entrypoint.sh runs `flask db upgrade` before `flask run`
- Makefile: build/start/stop/restart/update/logs/create-admin/
  update-mitre/test-{backend,frontend,e2e}/clean
- .env.example documenting MIMIC_JWT_SECRET / MIMIC_DB_PATH / MIMIC_PORT
- SQLite at /data/mimic.sqlite on named volume mimic-data

Acceptance suite (Playwright, 36 tests, all 27 ACs)
- e2e/ scaffold with playwright.config + auth/api fixtures
- One spec per user story (us1-bootstrap through us6-deployment)
- Portable via MIMIC_CONTAINER_CMD / MIMIC_BASE_URL (docker or podman)

Docs
- README.md with quick-start and architecture overview
- CHANGELOG.md updated with Sprint 1 deliverables
- pyrightconfig.json so the Python LSP sees backend/.venv and
  resolves the `backend.app.*` absolute imports

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/app/auth/__init__.py

@@ -0,0 +1,13 @@
+"""Auth helpers (JWT, hashing, decorators)."""
+from backend.app.auth.decorators import login_required, role_required
+from backend.app.auth.hashing import hash_password, verify_password
+from backend.app.auth.jwt import decode_token, encode_token
+
+__all__ = [
+    "hash_password",
+    "verify_password",
+    "encode_token",
+    "decode_token",
+    "login_required",
+    "role_required",
+]

backend/app/auth/decorators.py

@@ -0,0 +1,67 @@
+"""Auth decorators that gate routes on a valid JWT and (optionally) role."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+import jwt
+from flask import g, jsonify, request
+
+from backend.app.auth.jwt import decode_token
+from backend.app.extensions import db
+from backend.app.models import User
+
+
+def _extract_token() -> str | None:
+    header = request.headers.get("Authorization", "")
+    if not header.startswith("Bearer "):
+        return None
+    return header.removeprefix("Bearer ").strip() or None
+
+
+def login_required(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Require a valid JWT. Populates `g.current_user` with the User row."""
+
+    @wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        token = _extract_token()
+        if not token:
+            return jsonify({"error": "Missing or invalid Authorization header"}), 401
+        try:
+            payload = decode_token(token)
+        except jwt.ExpiredSignatureError:
+            return jsonify({"error": "Token expired"}), 401
+        except jwt.PyJWTError:
+            return jsonify({"error": "Invalid token"}), 401
+
+        try:
+            user_id = int(payload["sub"])
+        except (KeyError, TypeError, ValueError):
+            return jsonify({"error": "Invalid token payload"}), 401
+
+        user = db.session.get(User, user_id)
+        if user is None:
+            return jsonify({"error": "User no longer exists"}), 401
+
+        g.current_user = user
+        return fn(*args, **kwargs)
+
+    return wrapper
+
+
+def role_required(*roles: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Require the current user to hold one of the given role names."""
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(fn)
+        @login_required
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            user = g.current_user
+            if user.role.value not in roles:
+                return jsonify({"error": "Forbidden"}), 403
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

backend/app/auth/hashing.py

@@ -0,0 +1,23 @@
+"""Password hashing using argon2."""
+from __future__ import annotations
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+_hasher = PasswordHasher()
+
+
+def hash_password(password: str) -> str:
+    """Return an argon2 hash of `password`."""
+    return _hasher.hash(password)
+
+
+def verify_password(password_hash: str, password: str) -> bool:
+    """Return True iff `password` matches `password_hash`."""
+    try:
+        return _hasher.verify(password_hash, password)
+    except VerifyMismatchError:
+        return False
+    except Exception:
+        # Malformed hash or other argon2 error — treat as auth failure.
+        return False

backend/app/auth/jwt.py

@@ -0,0 +1,34 @@
+"""JWT encode/decode helpers."""
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt
+from flask import current_app
+
+
+def encode_token(user_id: int, role: str) -> str:
+    """Return a signed JWT for the given user."""
+    now = datetime.now(UTC)
+    exp_minutes = current_app.config["JWT_EXP_MINUTES"]
+    payload: dict[str, Any] = {
+        "sub": str(user_id),
+        "role": role,
+        "iat": int(now.timestamp()),
+        "exp": int((now + timedelta(minutes=exp_minutes)).timestamp()),
+    }
+    return jwt.encode(
+        payload,
+        current_app.config["JWT_SECRET"],
+        algorithm=current_app.config["JWT_ALGORITHM"],
+    )
+
+
+def decode_token(token: str) -> dict[str, Any]:
+    """Decode + validate a JWT. Raises jwt.PyJWTError on failure."""
+    return jwt.decode(
+        token,
+        current_app.config["JWT_SECRET"],
+        algorithms=[current_app.config["JWT_ALGORITHM"]],
+    )