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>

frontend/src/hooks/useAuth.tsx

@@ -0,0 +1,112 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import { login as apiLogin, logout as apiLogout, fetchMe } from '@/api/auth';
+import { getToken, registerUnauthorizedHandler, setToken } from '@/api/client';
+import type { Role, User } from '@/api/types';
+import { useToast } from './useToast';
+
+interface AuthContextValue {
+  user: User | null;
+  status: 'loading' | 'authenticated' | 'unauthenticated';
+  login: (username: string, password: string) => Promise<void>;
+  logout: () => Promise<void>;
+  isAdmin: boolean;
+  isRedteam: boolean;
+  isSoc: boolean;
+  canEditEngagements: boolean;
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+export function AuthProvider({ children }: { children: ReactNode }): JSX.Element {
+  const [user, setUser] = useState<User | null>(null);
+  const [status, setStatus] = useState<'loading' | 'authenticated' | 'unauthenticated'>('loading');
+  const { push } = useToast();
+
+  // Bootstrap: if a token exists in storage, try to recover the session.
+  useEffect(() => {
+    const token = getToken();
+    if (!token) {
+      setStatus('unauthenticated');
+      return;
+    }
+    let cancelled = false;
+    fetchMe()
+      .then((u) => {
+        if (cancelled) return;
+        setUser(u);
+        setStatus('authenticated');
+      })
+      .catch(() => {
+        // 401 interceptor already purges token + triggers redirect/toast.
+        if (cancelled) return;
+        setUser(null);
+        setStatus('unauthenticated');
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // Register the global 401 handler once.
+  useEffect(() => {
+    registerUnauthorizedHandler(() => {
+      setUser(null);
+      setStatus('unauthenticated');
+      push('Session expirée', 'error');
+      // Hard redirect so any in-flight query state is cleared.
+      if (window.location.pathname !== '/login') {
+        window.location.assign('/login');
+      }
+    });
+  }, [push]);
+
+  const login = useCallback(async (username: string, password: string) => {
+    const resp = await apiLogin(username, password);
+    setToken(resp.access_token);
+    // Hydrate full user (with created_at) via /me.
+    const me = await fetchMe();
+    setUser(me);
+    setStatus('authenticated');
+  }, []);
+
+  const logout = useCallback(async () => {
+    try {
+      await apiLogout();
+    } catch {
+      // Logout is best-effort server-side; the client purge below is what matters.
+    }
+    setToken(null);
+    setUser(null);
+    setStatus('unauthenticated');
+  }, []);
+
+  const value = useMemo<AuthContextValue>(() => {
+    const role: Role | undefined = user?.role;
+    return {
+      user,
+      status,
+      login,
+      logout,
+      isAdmin: role === 'admin',
+      isRedteam: role === 'redteam',
+      isSoc: role === 'soc',
+      canEditEngagements: role === 'admin' || role === 'redteam',
+    };
+  }, [user, status, login, logout]);
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth(): AuthContextValue {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used inside AuthProvider');
+  return ctx;
+}

frontend/src/hooks/useEngagements.ts

@@ -0,0 +1,50 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import {
+  createEngagement,
+  deleteEngagement,
+  fetchEngagement,
+  listEngagements,
+  patchEngagement,
+} from '@/api/engagements';
+import type { EngagementInput } from '@/api/types';
+
+const KEY = ['engagements'] as const;
+
+export function useEngagementsList() {
+  return useQuery({ queryKey: KEY, queryFn: listEngagements });
+}
+
+export function useEngagement(id: number | undefined) {
+  return useQuery({
+    queryKey: [...KEY, id],
+    queryFn: () => fetchEngagement(id as number),
+    enabled: typeof id === 'number' && !Number.isNaN(id),
+  });
+}
+
+export function useCreateEngagement() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (input: EngagementInput) => createEngagement(input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: KEY }),
+  });
+}
+
+export function usePatchEngagement(id: number) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (input: Partial<EngagementInput>) => patchEngagement(id, input),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: KEY });
+      qc.invalidateQueries({ queryKey: [...KEY, id] });
+    },
+  });
+}
+
+export function useDeleteEngagement() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (id: number) => deleteEngagement(id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: KEY }),
+  });
+}

frontend/src/hooks/useToast.tsx

@@ -0,0 +1,58 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+
+export type ToastKind = 'info' | 'success' | 'error';
+
+export interface Toast {
+  id: number;
+  message: string;
+  kind: ToastKind;
+}
+
+interface ToastContextValue {
+  toasts: Toast[];
+  push: (message: string, kind?: ToastKind) => void;
+  dismiss: (id: number) => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+const DEFAULT_DURATION_MS = 4000;
+
+export function ToastProvider({ children }: { children: ReactNode }): JSX.Element {
+  const [toasts, setToasts] = useState<Toast[]>([]);
+  const counterRef = useRef(0);
+
+  const dismiss = useCallback((id: number) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  const push = useCallback(
+    (message: string, kind: ToastKind = 'info') => {
+      counterRef.current += 1;
+      const id = counterRef.current;
+      setToasts((prev) => [...prev, { id, message, kind }]);
+      setTimeout(() => dismiss(id), DEFAULT_DURATION_MS);
+    },
+    [dismiss],
+  );
+
+  const value = useMemo(() => ({ toasts, push, dismiss }), [toasts, push, dismiss]);
+
+  return <ToastContext.Provider value={value}>{children}</ToastContext.Provider>;
+}
+
+export function useToast(): ToastContextValue {
+  const ctx = useContext(ToastContext);
+  if (!ctx) {
+    throw new Error('useToast must be used inside ToastProvider');
+  }
+  return ctx;
+}

frontend/src/hooks/useUsers.ts

@@ -0,0 +1,33 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { createUser, deleteUser, listUsers, patchUser } from '@/api/users';
+import type { UserCreateInput, UserPatchInput } from '@/api/types';
+
+const KEY = ['users'] as const;
+
+export function useUsersList() {
+  return useQuery({ queryKey: KEY, queryFn: listUsers });
+}
+
+export function useCreateUser() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (input: UserCreateInput) => createUser(input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: KEY }),
+  });
+}
+
+export function usePatchUser() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, input }: { id: number; input: UserPatchInput }) => patchUser(id, input),
+    onSuccess: () => qc.invalidateQueries({ queryKey: KEY }),
+  });
+}
+
+export function useDeleteUser() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (id: number) => deleteUser(id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: KEY }),
+  });
+}