Skip to content

fix(auth): web session hardening — token types, revocation, cookies, CORS, auth throttle (#315) - #316

Open
benders wants to merge 2 commits into
mainfrom
feature/315-session-hardening
Open

benders wants to merge 2 commits into
mainfrom
feature/315-session-hardening

Conversation

@benders

@benders benders commented Nov 13, 2026

Copy link
Copy Markdown
Owner

Closes #315. SECURITY.md H2, H5, M3 (items 1, 2, 4), H1 (cookie part).

Changes

Tokens

  • JWTs carry type. verifyToken accepts access only, verifyRefreshToken accepts refresh only; HS256 pinned on verify.
  • users.token_version (new column, additive migration), embedded as tv. A mismatch is rejected on every request and on refresh. Bumped on password change, admin-status change, logout, and by reset-password.sh.
  • requireAuth and requireOwner now share one verification path, authenticateSession.
  • The token= query-string source is gone (nothing used it).

Cookies

  • All three sign-in sites (login, refresh, invite redeem) go through issueSession. Secure is set when the request arrived over HTTPS (X-Forwarded-Proto from the proxy).

CORS

  • Cookie-authenticated API: same-origin only, unless an origin is listed in CORS_ALLOWED_ORIGINS.
  • /rest/*: *, never credentialed — keeps browser-based Subsonic clients working; no cookie is read there.

Throttling

  • AuthThrottle, shared by /admin/login and Subsonic u+p / u+t+s: 10 failures per (client address, username) and 100 per address, per 10 minutes. Failures only; a success clears the pair; blocked attempts are not counted.
  • Refusals: login 429; Subsonic JSON envelope error 0; Subsonic binary 429. All with Retry-After.
  • TRUST_PROXY → Fastify trustProxy. Limits key on request.ip only. A one-time warning is logged when a forwarding header shows up with TRUST_PROXY unset.
  • The invite limiter uses the same primitives and address.
  • Login decrypts a decoy for unknown usernames.

Behaviour changes to know about

  • Logout signs the user out on every device. Revocation is per user; there is no per-session state.
  • Existing sessions: access tokens minted before this change have no type and are rejected once; the SPA recovers with a silent refresh. Refresh tokens stay valid.
  • Operators behind a reverse proxy should set TRUST_PROXY (e.g. loopback,uniquelocal). Unset, all clients share one throttle bucket: 10 bad passwords for a username lock that username for everyone for up to 10 minutes.
  • An admin changing their own password stays signed in on that browser (cookies re-issued); their other sessions end.

Deliberately not done

  • No per-username lockout across addresses — it would let anyone who knows a username stop that user streaming.
  • Refresh-token reuse detection / per-session revocation — needs per-session state.
  • User-invite simplification (drop the HMAC layer) — a refactor with no security effect; left for a separate change.
  • HSTS and a TLS boot warning (rest of H1).

Testing

  • New hub/test/session-hardening.test.ts (31 tests): refresh token rejected as bearer and cookie, access token rejected at refresh, untyped token rejected, no query-string JWT, revocation on password change / admin change / logout, self password change, cookie flags, lockout and its scoping, shared budget across login and Subsonic, TRUST_PROXY on and off, CORS default and allowlist, config parsing, column migration.
  • pnpm verify locally: typecheck, lint (zero output), hub unit 1064/1064, frontend 193/193, integration 19 passed. The 3 dlna-ssdp integration tests fail locally only — the dev Mac cannot send UDP multicast (EHOSTUNREACH); they run in CI.
  • pnpm test:federation not run locally (two live hubs share a 2 GB Docker VM — the OOM pitfall); relying on the CI federation job.
  • reset-password.sh change is syntax-checked only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01M98ML9i5X7crjKVomscTNt

benders and others added 2 commits November 12, 2026 18:04
… CORS, auth throttle (#315)

- JWTs carry a type; verifyToken accepts access tokens only, so a refresh
  token is good only at /admin/refresh. HS256 pinned on verify.
- users.token_version, embedded as the tv claim; bumped on password change,
  admin-status change and logout. requireAuth and requireOwner share one
  verification path (authenticateSession).
- No JWT from the query string.
- Session cookies set through one helper; Secure when the request arrived
  over HTTPS.
- CORS: no cross-origin access to the cookie-authenticated API unless listed
  in CORS_ALLOWED_ORIGINS; /rest/* answers any origin, never credentialed.
- Failed-password throttle shared by /admin/login and Subsonic auth, keyed
  on request.ip; TRUST_PROXY sets Fastify trustProxy. Invite limiter moved
  onto the same primitives.
- Login decrypts a decoy for unknown usernames.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M98ML9i5X7crjKVomscTNt
…falls (#315)

Also passes TRUST_PROXY and CORS_ALLOWED_ORIGINS through docker-compose.yml,
documents them in example.env, and makes reset-password.sh bump
token_version so a recovery reset revokes existing sessions.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M98ML9i5X7crjKVomscTNt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Web session hardening: CORS, cookie flags, token types and revocation, auth throttling

1 participant