Files
minstrel/docs/security.md
T
bvandeusenandClaude Opus 5.5 55c7497ca7
release / go (push) Successful in 1m54s
release / web (push) Failing after 5s
release / integration (push) Failing after 3m44s
release / govulncheck (push) Successful in 20s
release / Attach APK to the Release (tag releases only) (push) Canceled after 0s
release / Build + push container image (push) Canceled after 0s
release / Verify release artifacts (tag releases only) (push) Canceled after 0s
release / Build signed APK (push) Canceled after 19s
release / android (push) Canceled after 2m37s
feat: Minstrel stops acquiring music and drops Discover
Minstrel is now a viewer of the library it is pointed at. Finding,
downloading and filing music moves out of it.

Removed from the server:
- the request flow (requests, approval, auto-approve) and the wanted list,
  follows, release profiles and release blocks;
- searching indexers, the download clients, the importer, the album
  lifecycle and missing-file re-acquisition;
- the catalogue's discography, search and art (the MusicBrainz release and
  track-list cache stays, for the duplicate resolver);
- Discover: its suggestions of artists not in the library, snoozes, the
  candidate-artist tag enrichment and its tuning scope;
- writes to acquisition tables from moving the library folder and from
  merging duplicates, the want-list join on Suspect sources, the sealing of
  acquisition credentials, and the release-group lookup only
  re-acquisition used.

Settling a wrong-slot duplicate no longer sets the release aside: the
copies go and their slots show as missing until a good copy is in the
library.

Removed from the web: Admin > Acquisition and Requests, /requests,
/discover, Follow on the artist page, the auto-approve toggle, and the
Collection's wanted-list tabs. The Collection is now the library's health:
an overview, Reports, Duplicates, Suspect sources and Missing files. The
README and docs no longer describe getting music.

The tables stay for now; a later migration drops them. The request
notification kinds and the Android screens are still to go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 20:51:14 -05:00

126 lines
6.2 KiB
Markdown

# Security notes
What Minstrel does to protect accounts, and the reasoning behind the
decisions that look odd at first. For deployment steps, see
[hosting](./hosting.md).
## Accounts and sessions
- **Passwords** are stored as bcrypt hashes.
- **Login, registration and password reset are rate-limited:** 10 failed
sign-ins per account and 50 per address per 15 minutes, with similar limits
on register, forgot-password and reset. The Subsonic `/rest` API shares the
login limits. An unknown username takes as long to reject as a wrong
password, so timing doesn't reveal which accounts exist.
- **Sessions** are random 256-bit tokens; the server stores only their
SHA-256. A session ends after 30 days unused or 365 days in total. Changing
your password signs out your other devices; a password reset, or an admin
resetting it, signs out all of them.
- **API keys** (the OpenSubsonic `apiKey`) are stored as SHA-256 too, so a
key is shown once, when you generate it in Settings, and can only be
replaced after that.
- **The first account** on an empty server needs the setup token from the
server log (see [hosting](./hosting.md#first-account)).
- **Password-reset links** are built only from the configured public address,
never from the request's `Host` header.
## Requests
- Request bodies are capped at 4 MiB and must arrive within 30 seconds.
Streams and the live-event connection are unaffected.
- Every response carries `X-Content-Type-Options: nosniff`,
`Referrer-Policy: strict-origin-when-cross-origin`, a restrictive
`Permissions-Policy` and `X-Frame-Options: DENY`. The web app also gets a
`Content-Security-Policy` that allows only its own scripts, by hash.
- Media responses are `Cache-Control: private`, so a shared cache never keeps
one user's audio or artwork for another.
## CSRF: SameSite cookies plus JSON-only writes
There are no CSRF tokens. The session cookie is `SameSite=Strict`, so
browsers don't send it with requests that start on another site. That leaves
one gap: SameSite treats every subdomain of the same registrable domain as the
same site, so a different app on `other.example.com` could still send a
request carrying the cookie. To close it, any state-changing `/api` request
authenticated by the cookie must have a JSON body (`Content-Type:
application/json`) or no body at all. An HTML form or a script on another
origin can't send JSON without a CORS preflight, and Minstrel answers no
cross-origin preflight. Requests authenticated with a bearer token or the
Subsonic query parameters carry nothing a browser attaches on its own, so
they aren't checked.
## Credentials Minstrel has to read back
Some credentials can't be hashed, because Minstrel has to send or compare the
value itself:
- the AcoustID key, and the cover-art and tag provider keys;
- the SMTP password;
- the secret key of the S3 bucket backups go to;
- each user's ListenBrainz token and Subsonic password.
These are encrypted in the database (AES-256-GCM). Each column has its own key,
derived from the stream secret (`MINSTREL_STREAM_SECRET`, or the
`stream_secret` file in the data directory), and each value is bound to its
row. The stream secret is never stored in the database, so a copy of the
database alone doesn't reveal any of them. None of them is ever sent back to a
browser: Settings only shows whether one is set.
**Keep the stream secret with the data directory, and don't change it
casually.** If it changes, every stored credential reads as not set, and each
one has to be entered again in Settings (Subsonic passwords generated again).
Minstrel logs a warning for each one that no longer opens.
## Subsonic sign-in
Classic Subsonic clients sign in with `t` and `s`: the MD5 of the password
followed by a random salt. To check that, the server has to know the password
itself, so supporting this sign-in method means storing a password Minstrel
can read: the Subsonic password, encrypted as described above.
- **The recommended way in is the API key.** Clients that support the
OpenSubsonic `apiKey` should use it. The key is stored hashed and can be
replaced at any time in Settings.
- **The Subsonic password is never your login password.** Minstrel generates
it (**Settings → Subsonic password**), shows it once, and lets you replace
or turn it off. Because it is random, even someone holding both the database
and the stream secret gains access to this server's Subsonic API and nothing
else: it can't be a password you also use somewhere else.
- **`t`/`s` and `p=` sign-in are off for an account until it has a Subsonic
password.** Plain `p=` sign-in is additionally off server-wide unless
`subsonic.allow_plaintext_password` is enabled.
- `minstrel admin reset-password` changes only the login password. Older
versions also copied it into the Subsonic password; upgrading clears every
Subsonic password once, so those copies are gone. An account that used
`t`/`s` sign-in needs a new Subsonic password generated in Settings.
## Android allows plain HTTP
The Android app permits cleartext connections, for two reasons that can't be
narrowed to a list of hosts. The server address is whatever the user types,
and many self-hosted servers run plain HTTP on a LAN. And UPnP, DLNA and
Sonos speakers are controlled over plain HTTP at addresses that are only
known once they're discovered. The reasoning lives in
`android/app/src/main/res/xml/network_security_config.xml`.
This doesn't weaken app updates: an APK altered in transit fails the
platform's signature check. It does mean a server reached over plain HTTP
across the internet exposes the session cookie in transit, which is why the
[hosting guide](./hosting.md) puts public servers behind HTTPS.
On the phone, the session cookie is encrypted with a key held in the Android
Keystore, so a copy of the app's files doesn't yield a usable session.
## Build pipeline
Nothing is published unless every check passes: the Go, integration, web and
Android test suites, `govulncheck` against the toolchain that builds the
image, and `npm audit` on every web dependency, build tooling included. See
`.gitea/workflows/release.yml`.
## Reporting a problem
Open an issue on the
[repository](https://git.fabledsword.com/bvandeusen/minstrel/issues), or
contact the maintainer privately first if it's something that shouldn't be
public until fixed.