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/tests/ProtectedRoute.test.tsx

@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+import { ProtectedRoute } from '@/components/ProtectedRoute';
+import { ToastProvider } from '@/hooks/useToast';
+import { AuthProvider } from '@/hooks/useAuth';
+import { setToken } from '@/api/client';
+import { ToastViewport } from '@/components/Toast';
+
+// Mock the auth API so AuthProvider hydrates without network.
+vi.mock('@/api/auth', () => ({
+  login: vi.fn(),
+  logout: vi.fn(),
+  fetchMe: vi.fn(),
+}));
+
+import { fetchMe } from '@/api/auth';
+
+function setup() {
+  return render(
+    <MemoryRouter initialEntries={['/admin']}>
+      <ToastProvider>
+        <AuthProvider>
+          <Routes>
+            <Route path="/login" element={<div>LOGIN PAGE</div>} />
+            <Route path="/engagements" element={<div>ENGAGEMENTS</div>} />
+            <Route element={<ProtectedRoute roles={['admin']} />}>
+              <Route path="/admin" element={<div>ADMIN AREA</div>} />
+            </Route>
+          </Routes>
+          <ToastViewport />
+        </AuthProvider>
+      </ToastProvider>
+    </MemoryRouter>,
+  );
+}
+
+describe('ProtectedRoute', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    vi.mocked(fetchMe).mockReset();
+  });
+
+  afterEach(() => {
+    setToken(null);
+  });
+
+  it('redirects unauthenticated users to /login', async () => {
+    // No token → unauthenticated, no /me call.
+    setup();
+    expect(await screen.findByText('LOGIN PAGE')).toBeInTheDocument();
+  });
+
+  it('admins reach the admin page', async () => {
+    setToken('fake-token');
+    vi.mocked(fetchMe).mockResolvedValue({
+      id: 1,
+      username: 'alice',
+      role: 'admin',
+      created_at: '2026-01-01',
+    });
+    setup();
+    expect(await screen.findByText('ADMIN AREA')).toBeInTheDocument();
+  });
+
+  it('non-admins get redirected and see an access denied toast', async () => {
+    setToken('fake-token');
+    vi.mocked(fetchMe).mockResolvedValue({
+      id: 2,
+      username: 'bob',
+      role: 'soc',
+      created_at: '2026-01-01',
+    });
+    setup();
+    expect(await screen.findByText('ENGAGEMENTS')).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.getByTestId('toast')).toHaveTextContent('Accès refusé');
+    });
+  });
+});

frontend/tests/StatusBadge.test.tsx

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { StatusBadge } from '@/components/StatusBadge';
+
+describe('StatusBadge', () => {
+  it.each(['planned', 'active', 'closed'] as const)('renders %s label and data attr', (status) => {
+    render(<StatusBadge status={status} />);
+    const badge = screen.getByTestId('status-badge');
+    expect(badge).toHaveAttribute('data-status', status);
+    expect(badge.textContent?.toLowerCase()).toBe(status);
+  });
+});

frontend/tests/Toast.test.tsx

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { act, render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ToastProvider, useToast } from '@/hooks/useToast';
+import { ToastViewport } from '@/components/Toast';
+
+function Pusher() {
+  const { push } = useToast();
+  return (
+    <div>
+      <button onClick={() => push('Session expirée', 'error')}>Push session</button>
+    </div>
+  );
+}
+
+describe('Toast', () => {
+  it('renders pushed toasts and lets the user dismiss them manually', async () => {
+    const user = userEvent.setup();
+    render(
+      <ToastProvider>
+        <Pusher />
+        <ToastViewport />
+      </ToastProvider>,
+    );
+
+    await user.click(screen.getByRole('button', { name: /push session/i }));
+    const toast = await screen.findByTestId('toast');
+    expect(toast).toHaveTextContent('Session expirée');
+    expect(toast).toHaveAttribute('data-kind', 'error');
+
+    await user.click(screen.getByRole('button', { name: /dismiss/i }));
+    await waitFor(() => {
+      expect(screen.queryByTestId('toast')).toBeNull();
+    });
+  });
+
+  it('auto-dismisses after the timeout', async () => {
+    // Override the 4s default by polling the DOM up to 6s. Real timers keep
+    // user-event happy; the toast hook clears itself via setTimeout.
+    const user = userEvent.setup();
+    render(
+      <ToastProvider>
+        <Pusher />
+        <ToastViewport />
+      </ToastProvider>,
+    );
+
+    await user.click(screen.getByRole('button', { name: /push session/i }));
+    expect(await screen.findByTestId('toast')).toBeInTheDocument();
+
+    await waitFor(
+      () => {
+        expect(screen.queryByTestId('toast')).toBeNull();
+      },
+      { timeout: 6000 },
+    );
+    // Quiet act() warning by flushing any pending state.
+    await act(async () => {
+      await Promise.resolve();
+    });
+  }, 10_000);
+});

frontend/tests/UsersAdminPage.test.tsx

@@ -0,0 +1,106 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import MockAdapter from 'axios-mock-adapter';
+import { apiClient } from '@/api/client';
+import { UsersAdminPage } from '@/pages/UsersAdminPage';
+import { renderWithProviders } from './utils';
+import type { User } from '@/api/types';
+
+// Mock useAuth so the page sees a logged-in admin without hydrating from network.
+vi.mock('@/hooks/useAuth', () => ({
+  useAuth: () => ({
+    user: { id: 1, username: 'alice', role: 'admin', created_at: '2026-01-01' } as User,
+    status: 'authenticated',
+    login: vi.fn(),
+    logout: vi.fn(),
+    isAdmin: true,
+    isRedteam: false,
+    isSoc: false,
+    canEditEngagements: true,
+  }),
+}));
+
+const USERS: User[] = [
+  { id: 1, username: 'alice', role: 'admin', created_at: '2026-01-01' },
+  { id: 2, username: 'bob', role: 'redteam', created_at: '2026-02-01' },
+  { id: 3, username: 'carol', role: 'soc', created_at: '2026-03-01' },
+];
+
+describe('UsersAdminPage', () => {
+  let mock: MockAdapter;
+
+  beforeEach(() => {
+    mock = new MockAdapter(apiClient);
+    mock.onGet('/users').reply(200, USERS);
+  });
+
+  afterEach(() => {
+    mock.restore();
+  });
+
+  it('renders the list of users from the API', async () => {
+    renderWithProviders(<UsersAdminPage />);
+    expect(await screen.findByText('alice')).toBeInTheDocument();
+    expect(screen.getByText('bob')).toBeInTheDocument();
+    expect(screen.getByText('carol')).toBeInTheDocument();
+  });
+
+  it('creates a user via POST /users and refreshes the list', async () => {
+    const newUser: User = { id: 4, username: 'dan', role: 'soc', created_at: '2026-04-01' };
+    const postSpy = vi.fn().mockReturnValue([201, newUser]);
+    mock.onPost('/users').reply((config) => postSpy(JSON.parse(config.data)));
+
+    const user = userEvent.setup();
+    renderWithProviders(<UsersAdminPage />);
+
+    await screen.findByText('alice');
+
+    await user.type(screen.getByLabelText(/^username/i), 'dan');
+    await user.type(screen.getByLabelText(/^password/i), 'sup3rs4fe!');
+    // role default is 'redteam'; switch to 'soc' to match newUser
+    await user.selectOptions(screen.getByLabelText(/^role/i), 'soc');
+
+    // After POST, hooks invalidate and the list refetches → return the new list
+    mock.onGet('/users').reply(200, [...USERS, newUser]);
+
+    await user.click(screen.getByRole('button', { name: /^create$/i }));
+
+    await waitFor(() => {
+      expect(postSpy).toHaveBeenCalledWith({
+        username: 'dan',
+        password: 'sup3rs4fe!',
+        role: 'soc',
+      });
+    });
+    expect(await screen.findByText('dan')).toBeInTheDocument();
+  });
+
+  it('opens the password reset form for the row that was clicked (fragment-key regression guard)', async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<UsersAdminPage />);
+
+    await screen.findByText('bob');
+
+    // The "Reset password" button for bob lives in bob's row.
+    const bobRow = screen.getByText('bob').closest('tr');
+    expect(bobRow).not.toBeNull();
+    await user.click(within(bobRow as HTMLElement).getByRole('button', { name: /reset password/i }));
+
+    // The reset form for bob (and bob only) must appear.
+    expect(await screen.findByLabelText(/new password for bob/i)).toBeInTheDocument();
+    expect(screen.queryByLabelText(/new password for carol/i)).toBeNull();
+    expect(screen.queryByLabelText(/new password for alice/i)).toBeNull();
+  });
+
+  it('disables the delete button on the current user own row', async () => {
+    renderWithProviders(<UsersAdminPage />);
+    await screen.findByText('alice');
+
+    const aliceRow = screen.getByText('alice').closest('tr') as HTMLElement;
+    const bobRow = screen.getByText('bob').closest('tr') as HTMLElement;
+
+    expect(within(aliceRow).getByRole('button', { name: /delete/i })).toBeDisabled();
+    expect(within(bobRow).getByRole('button', { name: /delete/i })).toBeEnabled();
+  });
+});

frontend/tests/apiClient.test.tsx

@@ -0,0 +1,57 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import MockAdapter from 'axios-mock-adapter';
+import { apiClient, getToken, registerUnauthorizedHandler, setToken } from '@/api/client';
+
+describe('apiClient interceptors', () => {
+  let mock: MockAdapter;
+
+  beforeEach(() => {
+    mock = new MockAdapter(apiClient);
+    setToken(null);
+  });
+
+  afterEach(() => {
+    mock.restore();
+    setToken(null);
+  });
+
+  it('attaches Bearer token from storage', async () => {
+    setToken('abc123');
+    mock.onGet('/auth/me').reply((config) => {
+      expect(config.headers?.Authorization).toBe('Bearer abc123');
+      return [200, { id: 1, username: 'alice', role: 'admin', created_at: '2026-01-01' }];
+    });
+
+    const resp = await apiClient.get('/auth/me');
+    expect(resp.status).toBe(200);
+  });
+
+  it('purges token and calls the registered handler on 401', async () => {
+    setToken('expired');
+    const handler = vi.fn();
+    registerUnauthorizedHandler(handler);
+
+    mock.onGet('/engagements').reply(401, { error: 'token expired' });
+
+    await expect(apiClient.get('/engagements')).rejects.toMatchObject({
+      response: { status: 401 },
+    });
+
+    expect(getToken()).toBeNull();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // Reset to avoid leaking into other tests.
+    registerUnauthorizedHandler(() => {});
+  });
+
+  it('leaves the token intact on non-401 errors', async () => {
+    setToken('still-valid');
+    mock.onGet('/users').reply(403, { error: 'forbidden' });
+
+    await expect(apiClient.get('/users')).rejects.toMatchObject({
+      response: { status: 403 },
+    });
+
+    expect(getToken()).toBe('still-valid');
+  });
+});

frontend/tests/states.test.tsx

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { LoadingState } from '@/components/LoadingState';
+import { ErrorState } from '@/components/ErrorState';
+import { EmptyState } from '@/components/EmptyState';
+
+describe('LoadingState', () => {
+  it('shows the default label', () => {
+    render(<LoadingState />);
+    expect(screen.getByTestId('loading-state')).toHaveTextContent('Loading');
+  });
+
+  it('shows a custom label', () => {
+    render(<LoadingState label="Fetching things…" />);
+    expect(screen.getByTestId('loading-state')).toHaveTextContent('Fetching things…');
+  });
+});
+
+describe('ErrorState', () => {
+  it('renders message and triggers retry', async () => {
+    const onRetry = vi.fn();
+    render(<ErrorState message="Boom" onRetry={onRetry} />);
+    expect(screen.getByTestId('error-state')).toHaveTextContent('Boom');
+    await userEvent.click(screen.getByRole('button', { name: /retry/i }));
+    expect(onRetry).toHaveBeenCalledTimes(1);
+  });
+
+  it('omits retry button when no handler given', () => {
+    render(<ErrorState message="Boom" />);
+    expect(screen.queryByRole('button', { name: /retry/i })).toBeNull();
+  });
+});
+
+describe('EmptyState', () => {
+  it('renders title, description and action', () => {
+    render(<EmptyState title="Nothing here" description="Add one" action={<button>Create</button>} />);
+    const node = screen.getByTestId('empty-state');
+    expect(node).toHaveTextContent('Nothing here');
+    expect(node).toHaveTextContent('Add one');
+    expect(screen.getByRole('button', { name: /create/i })).toBeInTheDocument();
+  });
+});

frontend/tests/utils.tsx

@@ -0,0 +1,33 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { render, type RenderOptions } from '@testing-library/react';
+import { MemoryRouter, type MemoryRouterProps } from 'react-router-dom';
+import type { ReactElement, ReactNode } from 'react';
+import { ToastProvider } from '@/hooks/useToast';
+
+interface WrapperOptions {
+  routerProps?: MemoryRouterProps;
+}
+
+export function makeQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, gcTime: 0, staleTime: 0 },
+      mutations: { retry: false },
+    },
+  });
+}
+
+export function renderWithProviders(
+  ui: ReactElement,
+  { routerProps, ...rtlOptions }: WrapperOptions & Omit<RenderOptions, 'wrapper'> = {},
+) {
+  const client = makeQueryClient();
+  const Wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={client}>
+      <MemoryRouter {...routerProps}>
+        <ToastProvider>{children}</ToastProvider>
+      </MemoryRouter>
+    </QueryClientProvider>
+  );
+  return { ...render(ui, { wrapper: Wrapper, ...rtlOptions }), client };
+}