Add phased-execution planning structure

Introduce .agents/ (PLAN.md with locked architectural anchors, phase roadmap under phases/todo/) and AGENTS.md rules for agents working in the repo. Queues the pending phases: fix history XSS, simulate fetch commands, and nginx security headers.
2026-09-18 17:23:41 -04:00
parent 010758b3e9
commit a2f331e526
13 changed files with 963 additions and 0 deletions
@@ -0,0 +1,44 @@
+# Phase 02 — Remove unvalidated client fetch from curl/wget (audit M-2)
+
+**Story:** n/a
+**Context:** `.agents/PLAN.md` §2 (principle 5 — fun is safe) & §3 (terminal
+modules), `.agents/remediation_plan.md` finding M-2
+
+## Objective
+The fake terminal's `curl`/`wget` commands run a real, unvalidated
+`fetch(url)` from the visitor's browser — a client-side request-forgery
+primitive (and cookie-attached once the site ever has auth) that is also
+silently broken in production (CSP `connect-src` falls back to
+`default-src 'self'`, blocking every external fetch). Replace the real
+fetch with **simulated output** consistent with the rest of the fake
+terminal: zero network I/O, deterministic, echoes the requested URL.
+
+**Chosen approach** (audit recommendation, owner-approved 2026-09-18):
+simulate. The rejected alternative (real fetch + https-only allowlist +
+`connect-src` + `credentials: 'omit'`) is documented for the record but out
+of scope.
+
+## Dependencies
+— (none)
+
+## Tasks
+1. `01_simulate_fetch_output.md` — Add `simulatedCurlOutput(url)` / `simulatedWgetOutput(url)` to `terminal-commands.js`; replace both `fetch()` calls in `terminal.js` with the simulated outputs.
+2. `02_fetch_regression_test.md` — Add Playwright tests proving curl/wget render simulated output, make **zero** non-origin network requests, and still unlock the `web_navigator` achievement.
+
+## Testing & Quality
+- Unit/integration: the regression tests must cover (a) `curl <url>`
+  renders the simulated block and echoes the URL, (b) `wget <url>` same,
+  (c) no request to any non-origin host occurs (request listener),
+  (d) `web_navigator` achievement/toast still fires.
+- Coverage: **>90%** on new/modified code (the two simulator functions +
+  both branches).
+- E2E: full Playwright suite green.
+
+## Completion Criteria
+- [ ] `grep -n "fetch(" src/terminal.js` returns no matches (the only
+      `fetch(` in `src/` must be gone)
+- [ ] `simulatedCurlOutput` / `simulatedWgetOutput` present in
+      `src/terminal-commands.js`
+- [ ] new regression tests present in `tests/e2e/` and passing
+- [ ] `./build.sh && npm test` fully green (46+ tests)
+- [ ] no behavior change in completed work (terminal, vim, achievements, menu)