ui/_docs/00_problem/security_approach.md

# Security Approach — Azaion UI

> Output of `/document` Step 6e. Retrospective security view of the SPA
> grounded in code (`src/auth/AuthContext.tsx`, `src/api/client.ts`,
> `src/api/sse.ts`), config (`nginx.conf`, `Dockerfile`,
> `.woodpecker/build-arm.yml`), and the verified architecture
> (`_docs/02_document/architecture.md` § 7). Every claim cites its evidence.

**Status**: synthesised-from-verified-docs (Step 6e — `/document`)
**Date**: 2026-05-10

---

## Threat model summary

The UI is **operator-internal**, not public. The trust model is:

- **Trusted**: the suite services (reached via nginx reverse-proxy on the
  same origin); the suite's identity provider (`admin/`); the operator's
  authenticated browser session.
- **Untrusted**: the browser itself (XSS-resistant design — bearer in
  memory only); operator network if not on the suite VPN; OpenWeatherMap
  (currently exfiltrated to via a hardcoded key — finding); OSM tile
  servers (read-only third-party).

Primary threats considered: **token theft via XSS**; **CSRF via cookie
auto-attach**; **bearer leakage via SSE query string**; **secret leakage in
bundle**; **privilege escalation via missing client-side route gates**;
**clickjacking / framing**.

---

## 1. Authentication

### Login

- `POST /api/admin/auth/login` with `{ email, password }`.
- `admin/` service responds with:
  - **Bearer JWT** in the response body — held in `AuthContext` memory
    only (never written to `localStorage` / `sessionStorage`, P3).
  - **`Secure HttpOnly SameSite=Strict` refresh cookie** — issued by
    server, scoped to the suite origin.

Source: `src/auth/AuthContext.tsx`; `architecture.md` § 7.

### Session bootstrap (cold load)

- On mount, `AuthContext` attempts `GET /api/admin/auth/refresh` to obtain
  a new bearer.
- **Bug**: this call is missing `credentials:'include'` — the HttpOnly
  refresh cookie is NOT sent → cold-load refresh fails → user is
  redirected to `/login` even with a valid cookie. **Step 4 fix
  candidate**.

Source: `src/auth/AuthContext.tsx:24`; `04_verification_log.md` F2.

### 401-retry path

- The `01_api-transport` `client.ts` wraps every authenticated `fetch`.
  On 401 it issues `POST /api/admin/auth/refresh` **with**
  `credentials:'include'`, replaces the bearer in `AuthContext`, and
  retries the original request.
- This path is correct and is the working refresh mechanism today.

Source: `src/api/client.ts:44`; `04_verification_log.md` F2.

### Logout

- `POST /api/admin/auth/logout` — clears the bearer in memory; server
  invalidates the refresh cookie.

Source: `src/auth/AuthContext.tsx`.

### Pre-port (legacy WPF)

- The WPF-era encrypted-creds command-line handoff (binary-split key
  fragments + DPAPI) is **intentionally not ported** — the browser cannot
  participate in that handoff and the suite identity infrastructure now
  lives server-side. P8.

Source: `_docs/legacy/wpf-era.md` §11.

---

## 2. Authorization

- RBAC is **server-enforced** — every authenticated endpoint validates
  `User.role` + `permissions[]` server-side.
- The UI inspects `AuthUser.role` to render or hide nav links and pages,
  but does **NOT** treat the result as a security gate.
- Browser is treated as untrusted; every action confirms with the server.

### Findings

- **`/admin` route lacks a client-side role-gate** (PRIORITY — security
  finding, AC-22). Server-side 403 IS the authoritative gate, but a
  non-admin user navigating to `/admin` today sees the broken admin UI
  flicker before the server rejects requests. **Step 4 / Step 8 fix.**
- **`/settings` route gate is more nuanced** — there is no explicit
  `SETTINGS` permission code in the suite spec; gating relies on
  server-side 403. Treat as a soft gate (don't expose the link in the
  Header for non-admins) rather than a hard redirect.

Source: `architecture.md` § 7 Authorization; `App.tsx`.

---

## 3. Token handling

| Token | Lifetime | Where it lives | Where it appears on the wire |
|-------|----------|----------------|------------------------------|
| Bearer JWT | Short (server-issued; refreshed on 401) | `AuthContext` React state — **memory only** | `Authorization: Bearer ${token}` header on every authenticated `fetch`; `?token=${bearer}` query string on SSE (`ADR-008`) |
| Refresh token | Long (server-issued) | **`Secure HttpOnly SameSite=Strict` cookie** — never accessible to JS | Cookie header on `POST /api/admin/auth/refresh` (and the broken bootstrap GET — Step 4 fix) |
| `X-Refresh-Token` header | Per-request (long-running video detect) | passed in by `01_api-transport` for endpoints that need it | `X-Refresh-Token: ${value}` per `_docs/10_auth.md`. **Currently NOT sent on `POST /api/detect/${mediaId}` for video** — long videos can blow the access-token TTL → silent failure. Step 4 fix candidate (finding #29). |

### Key invariants (P3)

- Bearer is **never** written to `localStorage` / `sessionStorage` / IndexedDB.
- Refresh token is **never** read from JS — `HttpOnly` enforces this.
- Code-search regression test: zero matches for `localStorage|sessionStorage`
  touching the bearer token in `src/`.

---

## 4. SSE bearer-in-query-string

`EventSource` cannot send arbitrary headers, so `src/api/sse.ts` passes the
bearer in the URL: `?token=${bearer}`.

### Trade-offs

- **Bearer is short-lived** — minimises window of compromise.
- **HTTPS encrypts the URL on the wire** — but the URL still appears in:
  - **nginx access logs** (mitigation: log redaction at the nginx layer —
    Step 6 surface; not configured today).
  - **Browser history** (low risk for SSE URLs, but document).
- **Refresh-rotation breaks open SSE connections** — the URL was created
  with the **old** bearer; no reconnect logic exists today (Step 8
  hardening — AC-24).

Source: `src/api/sse.ts`; `ADR-008`; `architecture.md` § 7.

---

## 5. Secrets management

### Hardcoded OpenWeatherMap API key — P10 violation

- **File**: `mission-planner/src/utils/flightPlanUtils.ts:60`
- **Value**: a 32-char hex key shipped in the production bundle.
- **Risk**: anyone with access to the bundle can extract and reuse the
  key (rate-limit theft; provider account abuse). The key is committed to
  git history.
- **Fix sequence (Step 4 / Phase B)**:
  1. **Rotate** the key at OpenWeatherMap (out-of-band, user action).
  2. **Move to env** — `import.meta.env.VITE_OPENWEATHERMAP_API_KEY`
     read at build time (interim).
  3. **Proxy via suite** — long-term, route the wind compute through
     `flights/` so no key ever reaches the browser (preferred; per
     `architecture.md` § Architecture Vision Open Questions item 8).

### Other secrets

- **No other hardcoded keys** in `src/` per Grep audit at Step 4.
- Suite service URLs are not secrets (they are docker-network hostnames).
- The bearer is the only sensitive value in browser memory, and it is
  short-lived.

Source: P10; `architecture.md` § Architecture Vision; finding (security).

---

## 6. CORS, cookie scope, CSRF

- **Same-origin via nginx**: the SPA is served by the same nginx that
  reverse-proxies `/api/<service>/`. The browser sees a single origin →
  cookies scope cleanly; CORS preflight is unnecessary for the suite
  endpoints.
- **`credentials:'include'`** is required on every authenticated `fetch`
  for the HttpOnly refresh cookie to flow. The 401-retry path
  (`api/client.ts:44`) is correct; the bootstrap refresh
  (`AuthContext.tsx:24`) is **broken**.
- **CSRF**: `SameSite=Strict` on the refresh cookie + bearer-in-header on
  authenticated requests. The bearer header cannot be auto-attached by a
  cross-origin form submit. **No additional CSRF token** is used today —
  the architecture pattern (header-based bearer + SameSite=Strict cookie)
  obviates it.

Source: `src/api/client.ts`; `nginx.conf`; `architecture.md` § 7.

---

## 7. Input validation

- **Server is authoritative.** The UI does not duplicate validation logic
  it cannot guarantee.
- **Numeric inputs in `09_settings`** use `parseInt(v) || 0` — clearing a
  field silently writes `0` (finding B4, AC-26). Step 4 fix.
- **File upload**: `react-dropzone` filters by MIME / extension client-side;
  the server is authoritative on virus scanning and size enforcement
  (`client_max_body_size 500M`).
- **Annotation save** body must include `Source`, `WaypointId`, `videoTime`
  (currently incomplete — finding #32). The wire format is validated by
  the `annotations/` service.

Source: `09_settings/SettingsPage.tsx`; `06_annotations/MediaList.tsx`;
`nginx.conf`; finding B4 / #32.

---

## 8. Output encoding / XSS surface

- React 19 escapes JSX text by default — string content is safe.
- **`dangerouslySetInnerHTML`** is **not used** in `src/` (Grep audit).
- **`HelpModal`** ships hardcoded English strings inline — XSS-safe but
  P6 violation (i18n).
- **Tainted-canvas** risk on annotation download (`AnnotationsPage.handleDownload`
  finding) — cross-origin image data may taint the canvas; the download
  silently fails. Pure UX bug, not a security defect, but flagged.

Source: `06_annotations/AnnotationsPage.tsx`; `HelpModal.tsx`.

---

## 9. Headers / hardening at the nginx layer

### Currently configured

- nginx serves `dist/` and reverse-proxies `/api/<service>/` to suite
  services.
- `client_max_body_size 500M`.

### Currently MISSING (Step 6 surface)

- **`Content-Security-Policy`** — no CSP header. Recommended starting
  point: `default-src 'self'; img-src 'self' https: data:; connect-src
  'self' https://api.openweathermap.org/ https://*.tile.openstreetmap.org/;
  frame-ancestors 'none'; object-src 'none'`.
- **`X-Frame-Options: DENY`** (or covered by CSP `frame-ancestors`) —
  clickjacking protection.
- **`Referrer-Policy: strict-origin-when-cross-origin`**.
- **`Strict-Transport-Security`** — depends on suite ingress; document the
  expected value.
- **`X-Content-Type-Options: nosniff`**.
- **Bearer-redaction** in nginx access logs for SSE URLs.

These are nginx config additions (server-side), not SPA changes — but the
SPA depends on them for hardening. Track at suite level.

Source: `nginx.conf`; `architecture.md` § 7 row "Cross-site / clickjack".

---

## 10. Audit logging

- **Server-side concern** — the `admin/`, `flights/`, `annotations/`, etc.
  services are responsible for audit-event emission.
- The SPA does **not** emit audit events directly. It does not maintain
  any client-side audit log.
- The browser console is the only client-side log surface today; no
  centralized client telemetry (Step 6 surface — `_docs/02_document/deployment/observability.md`).

Source: `architecture.md` § 7 Audit logging.

---

## 11. Image / supply-chain

### Currently in pipeline

- Multi-stage Dockerfile: `oven/bun:1.3.11-alpine` (build) →
  `nginx:alpine` (runtime).
- `bun install --frozen-lockfile` enforces lockfile fidelity.
- `AZAION_REVISION=$CI_COMMIT_SHA` and OCI labels stamped at push time.

### Currently MISSING (Step 6 surface)

- **No vulnerability scan** (Trivy / Grype) on the produced image.
- **No SBOM emission** (Syft / cyclonedx).
- **No image signing** (cosign).
- **No dependency audit step** in CI (`bun audit` equivalent — Bun does
  not yet have a first-party audit; `npm audit --omit=dev` against the
  lockfile is a reasonable substitute).

Source: `.woodpecker/build-arm.yml`; `architecture.md` § 3 "Missing from the
pipeline today".

---

## 12. Findings → Fix Map

| Finding | AC | Fix step |
|---------|----|----------|
| Bootstrap refresh missing `credentials:'include'` (F2) | AC-01 | Step 4 (Code Testability Revision) |
| Bearer-in-query SSE — refresh-rotation breaks subscription | AC-24 | Step 8 (Refactor — optional) or Phase B |
| Hardcoded OpenWeatherMap key (P10) | AC-20 | Step 4 (env move); Phase B (suite proxy) |
| `/admin` route lacks role-gate | AC-22 | Step 4 |
| `09_settings` numeric input writes `0` on empty | AC-26 | Step 4 |
| `09_settings` save handlers leak `saving:true` on PUT failure | AC-27 | Step 4 |
| `AdminPage.handleDeleteClass` lacks ConfirmDialog | AC-30 | Step 4 |
| `MediaList` uses `alert()` | AC-14 | Step 4 |
| `ConfirmDialog` lacks `aria-modal/role=dialog` | AC-15 | Step 4 / Step 8 |
| Header dropdown lacks combobox/expanded/Esc/focus-trap | AC-16 | Step 4 / Step 8 |
| Annotation save body missing `Source`, `WaypointId`, wrong `time` field | AC-05 | Step 4 |
| `X-Refresh-Token` not sent on long-video detect (#29) | — | Step 4 |
| Numeric enum drift (`AnnotationStatus`, `MediaStatus`, `Affiliation`, `CombatReadiness`) | AC-04 | Step 4 (P9 alignment) |
| No CSP / hardening headers in `nginx.conf` | — | Step 6 — track at suite level |
| No vulnerability scan / SBOM / image signing in CI | — | Phase B |

---

## 13. Compliance / standards

The UI does NOT claim conformance to any specific standard today:

- **No WCAG-level declaration** (multiple a11y findings recorded).
- **No SOC2 / ISO27001 controls** are implemented at the SPA layer
  (server-side concern of the suite).
- **No FIPS / specific crypto-mode requirements** at the SPA layer (TLS
  is terminated server-side; bearer JWT signing is server-side).

These are recorded as anti-criteria (AC-N4) — the UI is **internal**,
**operator-only**, and **trusts the suite** for compliance enforcement.
Phase B may revisit if a regulated deployment surface emerges.