diff --git a/docs/waves/decisions-2026-10-02.md b/docs/waves/decisions-2026-10-02.md new file mode 100644 index 0000000..92004bc --- /dev/null +++ b/docs/waves/decisions-2026-10-02.md @@ -0,0 +1,84 @@ +# Decisions — October 2, 2026 + +Three items, from the security review of 2026-10-01 +(`docs/reference/security-review-2026-10-01.md`). They get `D` ids because they +are internal security calls made mid-build, the same category as `D15` and +`D18`, not features a user asked for. + +Decided by Matt Mabrey, 2026-10-02. + +| Item | Title | Review finding | Task | +|---|---|---|---| +| `D19` | Uploaded files download safely | SEC-01, SEC-15e (BL-035, BL-036) | T16.2 | +| `D20` | One SOP per project | SEC-02 (BL-048) | T16.3 | +| `D21` | Session decode fails closed; PyJWT upgraded | SEC-07 (BL-052) | T16.1 | + +**Schedule:** wave 16. It is **independent of waves 12 to 15**: it touches +`server/` only, and no file in it is changed by a task in those waves except +`server/app.py`, in functions they do not touch (`get_wp_file`, `upsert_sop`, +the SOP baseline readers). Wave 16 may merge before wave 12. + +**Out of this round, by decision:** SEC-06 (session revocation) waits for the +AWS work. All other SEC findings stay as backlog drafts in +`docs/reference/security-review/backlog-drafts.md`. + +--- + +## D19 — Uploaded files download safely + +- **Problem:** an SVG drawing can carry a script. The server sends it back + `inline` with its own content type, on the app's origin, so the script runs + as whoever opens it (SEC-01). Separately, a file name that is not Latin-1 + (for example `Plan é.pdf`) makes the download fail with 500, and CR/LF in a + name reaches the response header (SEC-15e). +- **Decision:** SVG uploads stay **accepted**, but every file that is not a + PDF or a raster image downloads as an **attachment** inside a **sandbox**: + `Content-Disposition: attachment` and + `Content-Security-Policy: sandbox; default-src 'none'`. PDF and raster images + (PNG, JPEG, GIF, WebP, BMP, AVIF) keep opening inline. Every file name goes + out in the RFC 6266 / RFC 5987 form (ASCII fallback plus `filename*`). +- **Why accept SVG instead of refusing it:** no change for the person who + uploads, and no migration for SVGs already stored. The protection is on the + way out, which also covers any SVG already in the database. +- **Must not change:** inline preview of PDF and images (CR-007), the + `Cache-Control` the offline drawing cache relies on, the D8 limits, and the + upload API. + +## D20 — One SOP per project + +- **Problem:** the rule "changing a completed SOP is a Project Admin action" + checks only the SOP row being posted. A `project_user` can post a NEW SOP id + with `complete: true`. Every reader picks "the latest complete SOP", so that + row becomes the baseline every page loads and the source of PM, CM and QA + mail routing (SEC-02, probe S3). +- **Decision:** + 1. A project has one SOP, with the id `sop__`. The browser has + always written that id (`pushSOP` in `project-data.js`). A request with no + id gets it. A request that would CREATE a SOP with any other id on a + project is refused with 400. + 2. Existing SOP rows with other ids (for example rows `seed_demo.py` made) + stay. They can still be updated under the old rules. Nothing is deleted. + 3. While a project has a complete SOP, writing any SOP on that project with + `complete: true`, and changing a complete SOP, needs Project Admin on the + project. + 4. The readers prefer the canonical row: `project_sop_team`, + `project_qa_group`, `project_summary` and `GET /api/sops/latest` with + `complete=true&project_id=` read `sop__` when it is complete, + and fall back to "latest complete" only when it is not. So a rogue row + made before this fix cannot stay the baseline. +- **Must not change:** a project member drafting the SOP and completing it the + first time (allowed today, allowed after); admin access to project-less + SOPs; the response shape of every SOP route. + +## D21 — Session decode fails closed; PyJWT upgraded + +- **Problem:** a crafted 1.6 KB cookie makes PyJWT 2.13.0 raise an error that + `decode_token` does not catch, so an unauthenticated request gets a 500 and + a stack trace in the log (SEC-07, probe S12). `pip-audit` lists 13 + advisories for 2.13.0. +- **Decision:** pin **PyJWT 2.15.1** (`pip-audit`: no known vulnerabilities on + 2026-10-02). `decode_token` treats ANY decode failure, and any cookie longer + than 4096 characters, as "not signed in" (401). It also requires the `exp` + and `sub` claims, which every token this app issues carries. +- **Must not change:** every valid session, the D18 sliding refresh and + ceiling, and the fake Okta test seam. diff --git a/docs/waves/wave-16.md b/docs/waves/wave-16.md new file mode 100644 index 0000000..de155a9 --- /dev/null +++ b/docs/waves/wave-16.md @@ -0,0 +1,118 @@ +# Wave 16 — Urgent security fixes + +**Items:** `D19`, `D20`, `D21` +**Depends on:** nothing. Independent of waves 12 to 15 (see the decision record). +**Decision record:** `docs/waves/decisions-2026-10-02.md` +**Background:** `docs/reference/security-review-2026-10-01.md` + +Four tasks, in build order. All server-side. No page markup or stylesheet +changes, so the 390px / 1440px screenshot rule does not apply; the +browser probes that read files and SOPs are still listed for a run on a +machine with Edge. + +New check for this wave: `tests/security_check.py`. It is self-contained (its +own SQLite database, in-process, no browser), so it runs anywhere. + +--- + +### T16.1 — D21: session decode fails closed; PyJWT 2.15.1 + +- **Items:** `D21` +- **Depends on:** nothing (first task) +- **Blocks:** T16.4 +- **Surface:** `server/` +- **Files:** `server/requirements.txt`, `server/auth.py` (`decode_token`), `tests/security_check.py` (new) + +**Do:** pin `PyJWT==2.15.1`. In `decode_token`, return `None` for an empty or +over-long token (over 4096 characters) and for any exception from +`jwt.decode`. Require the `exp` and `sub` claims. + +**Do not:** change token contents, the cookie, or the D18 refresh. + +**Done when:** + +- [ ] the crafted-cookie request returns 401, not 500 +- [ ] a valid session still works, and the D18 refresh still reissues +- [ ] `pip-audit -r server/requirements.txt` reports no PyJWT advisory +- [ ] smoke test 27/27 + +--- + +### T16.2 — D19: uploaded files download safely + +- **Items:** `D19` +- **Depends on:** nothing +- **Blocks:** T16.4 +- **Surface:** `server/` +- **Files:** `server/files_http.py` (new), `server/app.py` (`get_wp_file`), `tests/security_check.py` + +**Do:** serve PDF and raster images inline as today. Serve every other type, +SVG included, as an attachment with `Content-Security-Policy: sandbox; +default-src 'none'`. Send `X-Content-Type-Options: nosniff` from the API too +(NGINX already does; the dev server does not). Build `Content-Disposition` +with an ASCII fallback and an RFC 5987 `filename*`. Reference code: +`docs/reference/architecture-review/proposals/server/files_http.py` (P-6). + +**Do not:** refuse SVG uploads (decided: accept, download only). Do not change +`Cache-Control`. + +**Done when:** + +- [ ] an SVG downloads as an attachment with the sandbox header +- [ ] PNG, JPEG and PDF still open inline +- [ ] `Plan é.pdf` downloads (was 500) +- [ ] a name with CR/LF produces a valid header +- [ ] `tests/files_check.py` passes on a machine with Edge (CR-007 offline drawings) + +--- + +### T16.3 — D20: one SOP per project + +- **Items:** `D20` +- **Depends on:** nothing +- **Blocks:** T16.4 +- **Surface:** `server/` +- **Files:** `server/app.py` (`upsert_sop`, `latest_sop`, `project_summary`, `project_sop_team`, `project_qa_group`), `tests/security_check.py` + +**Do:** the four rules in D20. One helper picks the project's baseline SOP +(canonical row if complete, else latest complete) and every baseline reader +uses it. + +**Do not:** delete or rename existing SOP rows. Do not change any response shape. + +**Done when:** + +- [ ] a `project_user` cannot create a second SOP on a project (400) or post + `complete: true` while a complete SOP exists (403) +- [ ] a `project_user` can still draft and complete the first SOP of a project +- [ ] a Project Admin can still change the completed SOP +- [ ] POST without an id lands on `sop__` +- [ ] a rogue complete SOP made before the fix no longer drives the baseline + or the QA and PM/CM recipients +- [ ] `tests/sample_check.py` and `tests/critical_reopen_check.py` pass on a + machine with Edge + +--- + +### T16.4 — D19, D20, D21: verification + +- **Items:** `D19`, `D20`, `D21` +- **Depends on:** T16.1 to T16.3 +- **Surface:** verification +- **Files:** this file (verification record) + +**Done when:** + +- [ ] `tests/security_check.py` passes +- [ ] `docs/reference/security-review/sec_probe.py`: S3 and S12 change as + expected; every other line is unchanged +- [ ] the architecture review `equivalence_check.py` (current branch vs wave + 16) is IDENTICAL: the scenario does not use these paths, so it proves the + rest of the work-package flow did not move +- [ ] smoke test 27/27 +- [ ] the browser probes named in T16.2 and T16.3 are listed for a run on a + machine with Edge (not available in the build sandbox) + +## Verification record + +(filled in at T16.4)