1ad85de1f1
The proxy forwards an HMAC-derived session id (X-Pipelines-Session) on /connect and POST /files; the server trusts it only on token-authenticated requests and keys elevation by it, so reconnects stay elevated up to a 24 h cap. Terminals rely on their su -l login. The app no longer forgets the elevation on disconnect and asks again only on a fresh refusal.
294 lines
16 KiB
Markdown
294 lines
16 KiB
Markdown
# 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 need one password confirmation per signed-in web session:
|
||
- `chat_shell_run`, `chat_shell_input`;
|
||
- `rename_path`, `move_path`, `delete_path`;
|
||
- `POST /files`.
|
||
|
||
Terminals (`terminal_open`, `terminal_input`) are not gated: each terminal
|
||
starts `su -l`, which asks for the OS account password itself.
|
||
|
||
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
|
||
session'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.
|
||
|
||
How long it lasts (2026-11-10 change):
|
||
- The Go server cannot see the cookie, so the proxy tells it which session a
|
||
request belongs to. On `/connect` upgrades and `POST /files` the proxy sets
|
||
`X-Pipelines-Session` to `AuthStore.sessionId(token)`: an HMAC, under the
|
||
cookie secret, of the token's generation, the revoke-all time and the token
|
||
id. It is never the cookie. Any client-supplied copy of the header is dropped.
|
||
- The server trusts the header only on a request that carried the configured
|
||
server token (`request_boundary.go`); otherwise it is removed and ignored.
|
||
- Elevation is keyed by that id. Every connection and reconnect of the same
|
||
browser or app sign-in stays elevated, up to a cap of 24 hours
|
||
(`PIPELINES_ELEVATION_MINUTES`, 1–43200).
|
||
- The session ending ends it. Logout revokes the token id. A password change
|
||
bumps the generation and secret. Revoke-all invalidates every older token.
|
||
In each case the proxy closes the session's sockets and refuses its cookie,
|
||
and the next sign-in derives a new id, so the old elevation is never named
|
||
again. It expires in server memory at the cap; a server restart forgets it.
|
||
- A connection without a trusted session id (no server token configured, or a
|
||
direct local client) elevates only itself, until it closes, as before.
|
||
|
||
Uploads travel outside the websocket. An elevated session's upload is allowed
|
||
through its `X-Pipelines-Session`. The `X-Pipelines-Elevation` token also still
|
||
works. It lives only in memory and lasts as long as its elevation: a session's
|
||
token survives reconnects, a connection-only token dies with its connection. A
|
||
refused upload gets 403 `{"code":"elevation_required"}`.
|
||
|
||
Peer relay: the relay sends a remote machine only its own peer cookie and a
|
||
fixed header list, never `X-Pipelines-Session`. The remote proxy derives its
|
||
own id from that cookie, so each machine elevates through its own gateway with
|
||
its own password. It stays elevated for as long as the relay's sign-in to that
|
||
machine lasts.
|
||
|
||
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. The app then retries the refused request.
|
||
Concurrent refusals share one dialog. The app no longer forgets the elevation
|
||
when the connection drops. It asks again only when the server answers a fresh
|
||
`elevation_required`: the session ended, the cap passed, or an older server
|
||
that elevates one connection. So it asks at most once per machine per app run
|
||
while the session is valid.
|
||
|
||
## 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
|
||
|
||
- Terminals are not gated by elevation (since 2026-11-10). A terminal's `su -l`
|
||
login is the barrier. Once a terminal is logged in, any connection of a
|
||
signed-in session can read it (`terminal_output`) and type into it
|
||
(`terminal_input`).
|
||
- Session elevation lives in server memory keyed by the derived id. A revoked
|
||
session's entry is never named again, but it stays in memory until its cap.
|
||
- `/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
|
||
```
|
||
|
||
## Session-long elevation, terminals ungated (2026-11-10, later)
|
||
|
||
The operator asked to be asked for the password once, not for every command,
|
||
and not before opening a terminal. The change is described under "Step-up
|
||
re-authentication" above.
|
||
|
||
Checks:
|
||
- `umask 022 && go test ./internal/server ./internal/protocol ./internal/servertoken ./cmd/...`:
|
||
ok (server 97 s). New: `elevation_session_test.go`. It covers: elevation
|
||
survives a new connection of the same session, a different or absent
|
||
session is not elevated, the header is ignored without the proxy token,
|
||
the boundary strips the header, and the cap expires. `elevation_test.go`
|
||
now checks that terminals are not gated.
|
||
- `cd web && node --test test/`: tests 51, pass 51. New: `test/sessionId.test.mjs`.
|
||
It covers: the id is derived and stable per token, a forged header is dropped,
|
||
the id is sent on `/connect` and `POST /files` but not on `GET /files`, and
|
||
the id changes after another sign-in, a logout and a password change.
|
||
- `cd app && tool/analyze.sh`: clean.
|
||
- `tool/memwatch/full.sh 'test/core test/features/chat/files test/features/terminal test/features/settings/security'`:
|
||
PASS, 217 passed. New: `test/core/servers/elevation/session_elevation_test.dart`.
|
||
It covers: no prompt on reconnect, and one prompt per run per machine with a
|
||
second prompt only after a fresh refusal.
|
||
- `test/application` still has its 51 baseline failures (pending timers).
|
||
|
||
Scratch end-to-end:
|
||
- an isolated `HOME`;
|
||
- a scratch DB;
|
||
- OS-chosen loopback ports;
|
||
- the built server plus `web/serve.mjs` with a scratch server token;
|
||
- a tagged operator session.
|
||
|
||
```
|
||
login: 303 pipelines_session
|
||
connection 1: chat_shell_run before elevate: {"type":"error","code":"elevation_required",...}
|
||
connection 1: elevate: {"type":"elevated","elevation":{"seconds":86400,"token":"<redacted>"}}
|
||
connection 1: chat_shell_run after elevate: chat_shell_run running
|
||
connection 1 closed
|
||
connection 2 (reconnect, no elevate sent): chat_shell_run: chat_shell_run running
|
||
chat_shell_runs: [{"command":"echo first-connection-ok","status":"exited","exit_code":0,"output":"first-connection-ok"},{"command":"echo reconnected-no-elevate-ok","status":"exited","exit_code":0,"output":"reconnected-no-elevate-ok"}]
|
||
fresh sign-in: chat_shell_run is still gated: elevation_required
|
||
fresh sign-in, no elevate: terminal_open: terminal_open running
|
||
terminal output: "Password:"
|
||
terminal_close: terminal_close closed
|
||
password occurrences in server.log / web.log: 0 / 0
|
||
```
|