Document web sign-in and session hardening

This commit is contained in:
2026-11-10 01:21:28 +00:00
parent 9702d68d2d
commit 31317be258
+214
View File
@@ -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$<salt>$<key>"` (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.<generation>.<issued ms>.<expires s>.<id>.<HMAC>`.
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
`<auth file>.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":"<redacted>"}}
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
```