diff --git a/docs/notes/auth-hardening.md b/docs/notes/auth-hardening.md new file mode 100644 index 00000000..fb16a477 --- /dev/null +++ b/docs/notes/auth-hardening.md @@ -0,0 +1,214 @@ +# Web sign-in and session hardening (2026-11-10) + +This change covers the sign-in, session, password and step-up code: `web/serve.mjs`, +`web/src/{authStore,loginLimiter,passwordPolicy,sessionSockets,webSecurity}.js`, +`scripts/password.py`, `internal/server/{elevation,webauth_*}.go`, +`internal/protocol/elevation.go`, plus the app's `lib/core/servers/elevation/` +and `lib/features/settings/security/`. The server trust boundary, network +binding, update signing and the `su -l` terminal belong to other changes. + +## Behaviour + +**Password storage.** `web-auth.json` (0600) now holds +`password_hash: "scrypt$N$r$p$$"` (unpadded base64url, N=32768, r=8, +p=1, 32-byte key), `password_weak`, `secret` and `generation`. Node +(`crypto.scrypt`), Python (`hashlib.scrypt`) and Go (a small RFC 7914 +implementation checked against the RFC vectors) all verify the same hash. Every +comparison is constant time. The first time the proxy loads a file that still +holds a plaintext `password`, it rewrites the file atomically with the hash. The +password itself does not change. A plaintext written over a running proxy's file +counts as a password change and signs everyone out. + +**Sessions.** A token is `v2.....`. +It is valid only when all of these hold: +- the signature checks out; +- `generation` matches the file; +- it has not expired; +- it was issued after `not_before`; +- its id is not on the signed-out list. + +Changes that end sessions: +- **`./password`**: stores a new hash, rotates `secret` and bumps `generation`. + Every device is signed out. +- **`./password --revoke-all`**: same rotation, but keeps the password. +- **Settings → Sign-in security → Sign out everywhere**: calls + `POST /api/sessions/revoke-all`, which sets `not_before` in + `.sessions.json` (0600, written only by the proxy). +- **Logout**: now `POST /logout`, same-origin only. It adds the token id to the + signed-out list, which is kept until the token expires. The list holds at most + 10000 entries; when full, the soonest-expiring entries are dropped first. + `GET /logout` only shows a Sign out button. + +Every upgraded socket (`/connect` and relayed peer sockets) remembers its token. +The proxy closes it on logout or revocation, when the file changes, and on a +5-second sweep (`PIPELINES_WEB_SWEEP_MS`), so expired sessions are cut too. Tokens +from before this change are no longer accepted. + +**New passwords** (`./password`, first install) must be either: +- 16 or more characters, or +- 4 or more distinct random words, separated by spaces or dashes, 15 characters + or more in all. + +Common words, keyboard runs and repeated characters do not count towards the +length. The rule lives in `scripts/password.py` and `web/src/passwordPolicy.js`. +An existing password that fails the rule still works: +- the file records `password_weak: true`; +- Settings shows a warning; +- `./password` prints a one-time warning before its prompts. + +**Brute force.** +- **Per client**: 5 free failures, then the wait doubles from 1 s up to 15 min. +- **Server-wide**: a sliding window of 50 failures per 5 min blocks every client. +- **Bounds**: at most 1024 tracked clients, least recent evicted first; idle + entries expire after 1 h. +- **Concurrency**: at most 4 scrypt checks run at once; the rest get 429. + +A login is charged to its socket address. The one exception is a request that +arrives from loopback and carries `Tailscale-*` headers (that is, `tailscale +serve`). That request is charged to `Tailscale-User-Login`, or failing that to +the first `X-Forwarded-For` address. These headers are trusted only in that +case. A local process could forge them, but it already runs on the machine, and +the server-wide window still applies. + +**Form hygiene and headers.** +- **Login CSRF**: `POST /login`, `POST /logout` and the revoke-all endpoint + refuse a foreign `Origin`, `Origin: null`, or a cross-site `Sec-Fetch-Site`. + Native clients send no Origin and are accepted. +- **Redirect target**: `next` must be a single `/` followed by a character other + than `/` or `\`, with no backslash or control characters anywhere. Anything + else becomes `/`. +- **Every response**: `X-Content-Type-Options: nosniff`, + `Referrer-Policy: same-origin`, `X-Frame-Options: SAMEORIGIN` and + `CSP frame-ancestors 'self'`. The app's own HTML previews are sandboxed + `srcdoc` iframes, so they keep working. +- **Sign-in and sign-out pages**: `X-Frame-Options: DENY` and a CSP of + `default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; + form-action 'self'; frame-ancestors 'none'; base-uri 'none'`. +- **HSTS** only when `x-forwarded-proto` is `https`. +- **Cookie**: over https it is `__Host-pipelines_session` with `Secure`; over + plain http it is still `pipelines_session`. The proxy, the peer relay and the + native app accept both names. + +**Step-up re-authentication.** A session alone can no longer run a shell. The +following now need a password confirmation on the same websocket connection +within the last 15 minutes (`PIPELINES_ELEVATION_MINUTES`, 1–720): +- `chat_shell_run`, `chat_shell_input`; +- `rename_path`, `move_path`, `delete_path`; +- `terminal_open`, `terminal_input`; +- `POST /files`. + +The flow: +- The client sends `{"type":"elevate","password":…}`. The Go server reads the + auth file read-only: it must be a regular file, owned by the user, mode 0600. +- On success the reply is `elevated` with `{expires_at, seconds, token}`. +- A refused request gets `{"type":"error","code":"elevation_required"}`. +- A wrong password gets `elevation_failed`. Each wrong password doubles that + connection's wait (1 s, up to 1 min). 10 failures per 5 min across the server + block all attempts. Only one scrypt check runs at a time. + +Uploads travel outside the websocket. They carry the token in +`X-Pipelines-Elevation`. The token lives only in memory and dies when its +connection closes or expires. A refused upload gets 403 +`{"code":"elevation_required"}`. The peer relay forwards the header, so each +machine elevates through its own gateway with its own password. + +When does the gate apply? +- **Auth file exists**: the gate is on. +- **No auth file** (a bare server without the web proxy, or tests): nothing is + gated, and `elevate` answers `elevation_unavailable`. +- **Auth file exists but is unusable**: the gate stays closed (fail closed). + +In the app, one native dialog per machine (Material, or Cupertino on Apple +platforms) asks for the password once. The app then retries the refused request. +Concurrent refusals share one dialog. The elevation is forgotten when the +connection drops. + +## What the operator must do on the live install + +1. Install the updated app builds (APK, desktop) together with or before the + proxy. Over https, older app builds only recognise the old cookie name and + cannot sign in. +2. Deploy as usual (`./install`, then restart when no run or chat is active). + - The proxy migrates `~/.config/pipelines/web-auth.json` to a hash on its + first start. The password stays the same. + - Old-format session cookies are refused, so each browser, phone and peer + machine signs in once. + - The server needs the restart too, to start gating. `manage.py` now passes + `PIPELINES_WEB_AUTH_FILE` to it. +3. If Settings or `./password` reports the password as weak, run `./password` + on the server (in a terminal) and choose one that meets the rule. This signs + every device out. +4. After a lost device, run `./password --revoke-all`, or use Settings → Sign + out everywhere. +5. Repeat on each machine; each one keeps its own password and its own + elevation. + +The installer accepts both the hashed and the plaintext format. It writes only +hashes for new installs and applies the strength rule to a newly chosen +password. The ntfy `phone-reader` account keeps its own password. On a reinstall +with a hashed file, an existing ntfy account is preserved and a new one is asked +for on the terminal. + +## Not covered / residual + +- `terminal_output` (attaching to and reading an existing terminal) is not + gated. Typing into one (`terminal_input`) is. +- `/chat-uploads` (chat attachments into the chat's upload area) is not gated. +- The server-wide login window can lock the real operator out during an attack. + That is the trade-off that bounds guessing. +- The peer relay's `/api/peers` POST was not reviewed here. It belongs to the + trust-boundary change. + +## Verification (2026-11-10) + +- `cd web && node --test test/`: tests 34, pass 34, fail 0. + - New: `test/authStore.test.mjs`, `test/authProxy.test.mjs`. + - Updated: `authReload.test.mjs` (a changed password now signs the old cookie + out). +- `python3 -m unittest scripts.test_password`: Ran 16 tests, OK. +- `python3 -m unittest scripts.test_setup_native scripts.test_uninstall`: Ran 70 + tests, OK. +- `umask 022 && go test ./internal/protocol ./cmd/pipelines-server ./internal/server`: + all ok (`internal/server` 70.5 s). + - New: `elevation_test.go`, `webauth_scrypt_test.go` (RFC 7914 vectors and + Node/Python hashes). +- `cd app && tool/analyze.sh`: `analyze: clean`. +- `tool/memwatch/full.sh 'test/core/servers/elevation test/features/chat/files test/features/settings/security test/core/session/post_login_cookie_test.dart test/core/transport'`: + PASS, 93 passed, 0 failed. + - The wider `test/core test/features/chat test/features/terminal test/features/settings` + run: PASS, 1495 passed. + - `test/application`: 51 failures. An untouched HEAD fails the same 51 + (pending launch-update timer). + +Scratch end-to-end used: +- an isolated `HOME` with its own plaintext weak auth file; +- a scratch DB, OS-chosen ports, `PIPELINES_MDNS=off`; +- a tagged operator session inserted into the scratch DB. + +Output: + +``` +auth file keys after proxy start: ['password_hash', 'password_weak', 'secret'] weak= True +login with the existing (migrated) password: 303 pipelines_session +/api/session weak_password: true +chat_shell_run before elevate: {"type":"error","code":"elevation_required",...} +elevate wrong password: {"type":"error","code":"elevation_failed","error":"wrong password"} +elevate right password: {"type":"elevated","elevation":{"seconds":900,"token":""}} +chat_shell_run after elevate: {"type":"chat_shell_run","run":{"status":"running","command":"echo elevated-shell-ok"}} +chat_shell_runs: [{"command":"echo elevated-shell-ok","status":"exited","exit_code":0,"output":"elevated-shell-ok"}] +--- changing the password with scripts/password.py +auth file keys after change: ['generation', 'password_hash', 'password_weak', 'secret'] generation= 1 +websocket closed after the password change: true 47 ms +old cookie still signed in: false +old password login: 401 +new password login: 303 +/api/session weak_password: false +new connection is not elevated: {"type":"error","code":"elevation_required",...} +elevate with the new password: {"type":"elevated",...} +logout: 303 +websocket closed after logout: true +logged-out cookie still signed in: false +--- ./password --revoke-all +Every browser and device was signed out; sign in again with the same password. +password occurrences in server.log / web.log: 0 / 0 +```