diff --git a/docs/PHASE7_SQUIRREL_AB.md b/docs/PHASE7_SQUIRREL_AB.md deleted file mode 100644 index c49c64bf..00000000 --- a/docs/PHASE7_SQUIRREL_AB.md +++ /dev/null @@ -1,53 +0,0 @@ -# Phase 7: Squirrel vs NSIS A/B - -NSIS is the shipped Windows installer and **stays the default**. Squirrel is a -candidate only — it wins, and replaces NSIS, **only if** it is measurably faster -*and* its auto-update rollback works on real Win 10/11 machines. Otherwise NSIS -stays. This doc is the procedure to make that call with data, not vibes. - -## Build both from the same commit - -```powershell -# NSIS (default, what ships today) -pwsh scripts\build-app-win.ps1 -Sign # -> electron\dist\OpenSwarm-Setup-x64.exe - -# Squirrel (candidate), same staged tree / same SHA -pwsh scripts\build-app-win.ps1 -Sign -Squirrel -``` - -The `-Squirrel` switch only overrides `win.target` (via -`--config.win.target=squirrel`); signing, extraResources, and the bundled -python/node/router are identical, so any measured difference is the installer -itself, not the payload. Confirm both report the same provenance sha (Settings --> About -> Build, or the `[provenance]` line in backend.log). - -## Measure on REAL Windows 10 and 11 (x64), clean machines - -For each installer, on a fresh VM/box (no prior OpenSwarm install): - -| Metric | How | -|---|---| -| Install time | wall-clock from launching the installer to the app window appearing | -| First paint | `[perf] first-paint` in backend.log (`scripts/perf/parse-timing.js`) | -| Backend ready | `[perf] backend-http-ready` | -| Crashes | any crash on first launch; check `%APPDATA%\OpenSwarm\Crashpad` | -| Auto-update | install an older build, then this one; confirm it detects, downloads, installs on quit, relaunches on the new version | -| Rollback | after an update, force a downgrade/rollback path; confirm the previous version comes back cleanly and the feed isn't corrupted | - -Run each 3x per OS and take the median. Compare against the Phase 0 baseline -(file count 11,247 / 1.2 GB) and NSIS's own numbers. - -## Decision gate - -- Squirrel **wins** only if: median install + first-paint + backend-ready are - faster than NSIS on BOTH Win 10 and Win 11, AND auto-update works, AND rollback - works (including rebuilding whatever feed Squirrel's differential updates need). -- Any of those fail -> **NSIS stays**, revert the target, keep `-Squirrel` as a - dead experiment flag or remove it. - -## Why this is the last phase - -Squirrel changes the update feed format and rollback semantics. Switching it in -without the rollback feed rebuilt strands users on a broken updater — the exact -failure the rest of this plan exists to prevent. So it goes last, behind a flag, -and only on proof. diff --git a/docs/SECRET_ROTATION.md b/docs/SECRET_ROTATION.md deleted file mode 100644 index c9ad1b96..00000000 --- a/docs/SECRET_ROTATION.md +++ /dev/null @@ -1,44 +0,0 @@ -# Secret rotation + history purge - -The repo history contains real credentials that were committed long ago (the -ones `.gitleaksignore` acknowledges). CI is green because those findings are -allowlisted, but **allowlisting hides them, it does not remove them** — they're -still in `git log` and still shipped in the app today. This is the real fix. - -> Requires repo **admin** + access to the provider consoles + a **force-push** -> (history rewrite). The agent can't do any of those, so this is a human runbook. - -## 1. Rotate first (this is what actually kills the exposure) - -Rotating invalidates the leaked value immediately, so even though it stays in -history it becomes useless. Do this before bothering with the purge. - -| Secret | Where it leaked (commit) | Rotate where | -|--------|--------------------------|--------------| -| Google OAuth client secret | `backend/apps/tools_lib/{oauth_providers,tools_lib}.py` (7239f70, 7c3da1a, cbefe89) | Google Cloud Console → APIs & Services → Credentials → the OAuth client → **Reset secret** | -| PostHog API key | `backend/apps/analytics/collector.py` (8d09e46, b6f45e8) | PostHog → Project settings → rotate project API key (note: ingest keys are public by design — rotate only if it's a private key) | -| 9router client secrets | `9router/**` (cf775b4, history-only; dir now fetched from npm) | Whichever provider each `clientSecret` belongs to; bump `ROUTER_VERSION` if the npm package itself shipped one | - -After rotating, update wherever the build injects them (the `GOOGLE_OAUTH_*` -GitHub Actions secrets + `backend/.env` production-injection step) to the new -values, and cut a release so users get the rotated build. - -## 2. Purge from history (optional, after rotation) - -Redact the values from every commit with [git-filter-repo](https://github.com/newren/git-filter-repo): - -```bash -# expressions.txt: one `OLD_SECRET==>REDACTED` per line (the real old values) -git filter-repo --replace-text expressions.txt -``` - -Then the destructive part (admin only): - -- `git push --force --all` and `git push --force --tags` (this is why the agent - can't do it — force-push is denied and it rewrites every downstream commit hash). -- Everyone re-clones (old clones still hold the secrets). -- Re-create any protected-branch/tag rulesets if the rewrite trips them. - -Because rotation (step 1) already neutralizes the secret, the purge is about -hygiene, not urgency. Once both are done, drop the matching fingerprints from -`.gitleaksignore`.