# 05 — Authentication, Authorization & Security Model

Status: **Normative**. Covers account auth, token model, Subsonic compatibility
auth, storage-credential handling, stream-access tokens (used by Chromecast),
RBAC, and the threat model. Cross-referenced by `api/openapi.yaml` security
schemes and by docs 03/04/06.

---

## 1. Principals & roles

| Principal | Description |
|-----------|-------------|
| **User** | A human account. Roles: `admin` or `member`. |
| **Device session** | A refresh-token-backed login of a user on one client (web, Android, Subsonic app). Enumerable & revocable per user. |
| **Stream grant** | Short-lived, narrowly scoped token authorizing GETs of specific media (Chromecast receiver, `<audio>` tags). |

RBAC (enforced in the API layer; matrix duplicated in `api/openapi.yaml`
descriptions):

| Capability | member | admin |
|---|---|---|
| Browse/stream own-visible libraries, manage own playlists/history/settings | ✅ | ✅ |
| Create/edit **libraries** (storage credentials) | ❌ (unless `library.allow_member_create=true` server setting) | ✅ |
| Manage users, server settings, view all sessions | ❌ | ✅ |
| See other users' play history | ❌ | ❌ (privacy by design; aggregate-only stats) |

Library visibility: each library has an ACL (`library_access` table, doc 02) —
owner + explicitly granted users/`everyone`.

## 2. Password storage

- **Argon2id**, parameters: memory 64 MiB, iterations 3, parallelism 2,
  salt 16 B, key 32 B (`golang.org/x/crypto/argon2`). Parameters are encoded
  PHC-style in the hash string so they can be raised later; hashes are
  transparently re-derived on next successful login if parameters changed.
- Login rate limiting: per-IP token bucket 10/min *and* per-account 5 failures
  → 60 s lockout with exponential growth, capped 15 min. Lockouts return the
  identical error as wrong-password (no account enumeration); a `Retry-After`
  is included only after the limiter triggers, which fires for nonexistent
  accounts too.

## 3. Token model (first-party REST API)

JWTs, **EdDSA (Ed25519)** signed. The server generates its keypair on first
boot (stored in the data dir, `0600`); key id (`kid`) in the header enables
rotation (old key kept verifying for 24 h after rotation).

| Token | Lifetime | Transport | Claims |
|---|---|---|---|
| **Access** | 15 min | `Authorization: Bearer` | `sub` (user id), `sid` (session id), `role`, `iat`, `exp`, `iss="fablepool"`, `aud="api"` |
| **Refresh** | 30 d sliding | Body of `POST /auth/refresh`; web client stores it in an `HttpOnly; Secure; SameSite=Strict; Path=/api/v1/auth` cookie, native clients in OS keystore | `sub`, `sid`, `jti`, `aud="refresh"` |

- **Rotation & reuse detection:** every refresh issues a new refresh token and
  marks the old `jti` consumed (table `session_token`). Presenting a consumed
  `jti` ⇒ the whole session (`sid`) is revoked — standard stolen-token tripwire.
- **Revocation:** access tokens are stateless but carry `sid`; the API keeps an
  in-memory revoked-`sid` set (backed by the sessions table, reloaded on boot).
  Logout / "sign out everywhere" / admin disable all act on sessions, so the
  worst-case validity of a stolen access token after revocation is its
  remaining ≤ 15 min only if the revocation set is somehow cold — in practice 0.
- Web login flow returns the access token in the JSON body (kept in memory,
  never persisted) — combined with the cookie-scoped refresh token this keeps
  XSS blast radius to 15 min and CSRF blast radius to the refresh endpoint,
  which is `SameSite=Strict` + origin-checked.

## 4. Subsonic-compatible auth

The Subsonic protocol (we implement API version **1.16.1** at `/rest/*`, spec
mirrored in `api/openapi.yaml`) authenticates every request with either:

1. `u` + `t` + `s` where `t = md5(password + s)` (salted-hash scheme), or
2. `u` + `p` (plain or `enc:` hex) — legacy.

Both require the server to know a **reversible** secret. We will *not* weaken
the primary account password for this. Design:

- Each user may generate one or more **Subsonic app passwords**: random
  20-char (base32, 100-bit) strings, shown once at creation, stored
  **encrypted** (AES-256-GCM under the server master key, §6) — encryption,
  not hashing, because scheme (1) mathematically requires recovering the
  secret. Each app password row: label ("Symfonium on phone"), created_at,
  last_used_at, revocable individually.
- Verification: decrypt candidates for user `u`, check
  `md5(secret + s) == t` (or constant-time compare for scheme 2). Decrypt-all
  is fine: users have ≤ a handful of app passwords.
- Scheme (2) with plain `p` is accepted only over TLS-terminated connections
  (the server refuses it when it can see the request was plaintext HTTP and
  `allow_insecure_subsonic=false`, default).
- Subsonic requests are rate-limited with the same per-account limiter as §2.
- The account's primary password is **never** valid on `/rest/*` — so a
  database-level compromise of the encrypted app passwords cannot escalate to
  the primary credential, and the master account stays Argon2id-only.

## 5. Stream grants (media tokens)

Browsers' `<audio>`, Chromecast receivers, and image tags can't attach
`Authorization` headers reliably. Media endpoints therefore also accept a
**stream grant**: a compact signed token in the query string.

- Format: JWT, same Ed25519 key, `aud="media"`, lifetime **6 h**, claims:
  `sub`, `sid`, and `scope` — either a single `trackId` (Chromecast `LOAD`,
  artwork) or `queueId` (a playback queue snapshot; doc 06 §4) so one grant
  covers gapless queue advancement without re-minting.
- Minted by `POST /api/v1/stream-grants` (authenticated). The Chromecast
  sender mints one per queue and embeds it in the receiver payload
  (`docs/06-chromecast.md` §4.2).
- Grants are bound to `sid`: revoking the session kills outstanding grants
  (checked against the revoked-`sid` set like access tokens).
- Because grants ride in URLs, media responses set
  `Referrer-Policy: no-referrer` and logs **redact** the `grant` query param
  (structured-logging middleware strips it before sink).
- Presigned S3 URLs (doc 04 §6) are the second URL-borne credential class:
  15-min TTL, never logged, never stored, delivered only inside authenticated
  responses or as a 302 to an authenticated/grant-bearing request.

## 6. Storage credential protection

Library credentials (S3 secret keys, WebDAV passwords) are the crown jewels —
they grant access to users' *entire* buckets/shares.

- Encrypted at rest with **AES-256-GCM**; 12-B random nonce per value; AAD =
  `library_id` (binds ciphertext to its row — swap attacks fail to decrypt).
- Master key: 32 B from env `FABLEPOOL_MASTER_KEY` (base64) **or** a key file
  in the data dir created on first boot (`0600`). Env wins; the admin UI warns
  when running on the auto-generated file (backup implications).
- Key rotation: `fablepool admin rotate-master-key` re-encrypts all rows in a
  transaction; old key accepted for decrypt during the run only.
- Credentials are **never** returned by any API. `GET /libraries/{id}` returns
  `has_credentials: true` and the access-key-id's last 4 chars only. Updating
  credentials is write-only (omit = keep).
- In-memory hygiene: decrypted secrets live only inside driver instances;
  drivers are rebuilt on credential change; secrets excluded from `%v`
  formatting via a `redacted` wrapper type implementing `String() string { return "***" }`.

## 7. Transport, headers, and input hardening

- **TLS:** the server can terminate TLS itself (cert paths or ACME via
  `golang.org/x/crypto/acme/autocert`) or sit behind a reverse proxy
  (`trusted_proxies` CIDR list gates `X-Forwarded-*` trust). HSTS
  (`max-age=63072000`) when TLS is on.
- **CORS:** REST API default-denies cross-origin; admin-configurable allowed
  origins (needed only for third-party web clients). `/rest/*` Subsonic
  endpoints allow `*` with no credentials mode — Subsonic web clients depend
  on it and auth rides in the query string by protocol design.
- **Security headers** on the web app: `Content-Security-Policy` (self +
  `media-src` allowing the configured S3 endpoints for presigned playback +
  `https://www.gstatic.com` for the Cast sender SDK), `X-Content-Type-Options:
  nosniff`, `frame-ancestors 'none'`.
- **Path traversal:** the storage path validator (doc 03 §2.3) rejects `.`/
  `..`/backslashes/control chars; DB-stored paths are additionally re-validated
  on read (defense in depth — a compromised scanner can't plant escape paths).
- **SSRF via library config:** WebDAV `base_url` and S3 `endpoint` are
  attacker-ish input (any library-creating user). Default policy blocks
  private/link-local/loopback IP ranges after DNS resolution (re-checked at
  dial time, not just config time, to beat DNS rebinding) unless the admin
  sets `allow_private_endpoints=true` (the common self-hosted case — NAS on
  LAN — so the toggle is prominent in setup docs).
- **XML hardening (WebDAV):** the PROPFIND parser sets strict `encoding/xml`
  limits — Go's decoder does not resolve external entities (no XXE by
  construction); we additionally cap response bodies at 64 MiB and token
  depth at 64.
- **Request limits:** JSON bodies ≤ 1 MiB; playlist import files ≤ 8 MiB;
  global per-IP rate limit (default 600 req/min) with separate, tighter
  buckets for auth endpoints (§2).
- **Audit log:** append-only table for security-relevant events (logins,
  failures, token reuse trips, library credential changes, role changes,
  master-key rotations) with actor, IP, user agent.

## 8. Threat model summary

| # | Threat | Vector | Mitigations |
|---|--------|--------|-------------|
| T1 | Account takeover | credential stuffing | Argon2id, per-account+per-IP limits, uniform errors, audit log |
| T2 | Token theft (XSS) | web client compromise | 15-min in-memory access tokens; HttpOnly SameSite=Strict refresh cookie; CSP |
| T3 | Refresh replay | leaked refresh token | rotation + reuse detection ⇒ session kill (§3) |
| T4 | Storage credential exfiltration | DB dump / backup leak | AES-GCM at rest, master key outside DB, write-only API, AAD row binding |
| T5 | Media URL leakage | shared/logged URLs | 15-min presign TTL, 6-h sid-bound grants, log redaction, no-referrer |
| T6 | SSRF | malicious library endpoint | private-range deny + rebinding-safe dial-time checks (§7) |
| T7 | Path traversal | crafted keys/hrefs | strict path validator at driver boundary + on DB read |
| T8 | XXE / XML bombs | hostile WebDAV server | Go xml (no DTD/entities), body & depth caps |
| T9 | Resource exhaustion | transcode/scan abuse | transcode semaphore + queue timeout, scan concurrency caps, rate limits |
| T10 | Subsonic secret compromise | DB dump | app passwords are random per-app secrets, isolated from primary credential; individually revocable |
| T11 | Cast snooping on LAN | receiver payload sniffing | grants over TLS to server; scope-limited 6-h grant; no refresh material ever reaches the receiver (doc 06 §6) |

## 9. Privacy notes

- Play history powers recommendations (doc 07) and is strictly per-user; users
  can pause recording (`incognito` flag honored across REST and Subsonic
  scrobble paths) and bulk-delete history. Deletion cascades into the
  recommendation feature store within one rebuild cycle (doc 07 §8).
- The server makes **no** third-party network calls (no telemetry, no external
  metadata services) except the user-configured storage backends and, if
  enabled, ACME. This is a stated project guarantee; any future optional
  metadata enrichment must be opt-in and documented here first.