docs/security.md
Security
lodesong is a thin client in front of your Navidrome. The server in this repo (apps/api/src) is the only thing that
talks to Navidrome, and the browser never sees a credential.
How login works
- The login form posts the username and password to
/auth/login. - The server computes a Subsonic token (
md5(password + salt)), checks it against Navidrome withping, and throws the password away. - It stores a session in SQLite (
$DATA_DIR/sessions.db):- the session key is a random 256-bit value; only its SHA-256 is stored
- the Subsonic token and salt are encrypted with AES-256-GCM, keyed from
SESSION_SECRET(or a random secret generated once in$DATA_DIR/session.secret)
- The browser gets an
HttpOnly; SameSite=Laxcookie (plusSecurebehind HTTPS). JavaScript can't read it. - Every
/rest/*call goes through the server's proxy, which adds the session's credentials upstream.
Sessions expire after SESSION_IDLE_DAYS (default 30) without use. You can list and sign out your other devices from
the user menu (sessions). Rotating SESSION_SECRET signs everyone out.
What the proxy enforces
- Fixed upstream. Navidrome's address comes only from
NAVIDROME_URLor theNAVIDROME_SERVERSallowlist, never from the request, so the server can't be used as an open proxy (SSRF). - Allowlisted endpoints. Only the Subsonic endpoints the app uses are forwarded (
ENDPOINTSinapps/api/src/api.ts). Admin endpoints likedeleteUserorcreateUserreturn 404. - No client credentials.
u,p,t,s,apiKey,candvare stripped from every request and set by the server. - CSRF. Every call except media (
stream,download,getCoverArt,getAvatar, which are read-only and loaded by<img>/<audio>) must carryx-lodesong: 1. Another site can't send that header without a CORS preflight, which the server never allows. - Login backoff. After three failures, each failed attempt doubles the wait (1 s, 2 s, 4 s … 15 min), per client IP
and per username. Set
TRUST_PROXY=1behind a reverse proxy so the real client IP is used.
In the browser
- No tokens in
localStorage, URLs or browser history. Only the username is remembered, to draw the shell instantly. Stream and cover URLs carry no credentials, which also makes them cacheable. - Content Security Policy in
index.html:default-src 'self'. Scripts only from this origin plus one inline boot script, allowed by its SHA-256 (bun scripts/csp.tsprints it; a unit test fails if it drifts). Styles allow inline because components position popovers withstyleattributes. - The production server also sends the CSP as a header, with
frame-ancestors 'none'andX-Frame-Options: DENY(no clickjacking), plusPermissions-Policy. Referrer-Policy: no-referrerandX-Content-Type-Options: nosniffon the page and every API response.- Logging out (or signing in as someone else) deletes the server session, the cookie, the saved queue, the cached library data (IndexedDB) and the offline audio and covers (service worker caches).
Threat model
| threat | covered by |
|---|---|
| XSS steals credentials | nothing to steal: httpOnly cookie, no tokens in JS-reachable storage; strict CSP limits XSS itself |
| a leaked URL (history, logs, screenshots) | URLs carry no credentials |
| stolen database or backup | session keys are hashed; Subsonic tokens are encrypted with a secret that isn't in the database |
| CSRF from another site | SameSite=Lax cookie + required custom header on every state-changing call |
| password guessing | per-IP and per-user exponential backoff |
| using the server to reach other hosts | upstream fixed by config, endpoint allowlist |
| clickjacking | frame-ancestors 'none' + X-Frame-Options: DENY |
| a session on a lost device | idle expiry, revoke from the sessions list, or rotate SESSION_SECRET |
Navidrome itself still accepts the Subsonic token for as long as the password is unchanged; change your Navidrome password to invalidate every token at once.
Found something? Open a private security advisory on GitHub rather than an issue.