Files
pipelines/docs/notes/auth-hardening.md
T
alan 1ad85de1f1 Keep step-up elevation for the signed-in session and stop gating terminals
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.
2026-11-10 03:00:45 +00:00

16 KiB
Raw Blame History

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