wave 16: planning docs for D19, D20, D21
D19 - uploaded files download safely (SEC-01, SEC-15e)
D20 - one SOP per project (SEC-02)
D21 - session decode fails closed, PyJWT 2.15.1 (SEC-07)
From the security review of 2026-10-01. Decision record and task
breakdown only in this commit - no code yet.
(cherry picked from commit 1c221a122e)
This commit is contained in:
84
docs/waves/decisions-2026-10-02.md
Normal file
84
docs/waves/decisions-2026-10-02.md
Normal file
@@ -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__<project_id>`. 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__<project_id>` 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.
|
||||
118
docs/waves/wave-16.md
Normal file
118
docs/waves/wave-16.md
Normal file
@@ -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__<project_id>`
|
||||
- [ ] 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)
|
||||
Reference in New Issue
Block a user