Document web sign-in and session hardening
This commit is contained in:
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user