Skip to content

Security: zorcerer/heddohon

SECURITY.md

Security

Heddohon sits between the public internet and a music server that usually lives on a private network. This document covers the controls it implements, where they stop, and what it expects from the operator. Every claim here can be checked against the source.

Reporting a vulnerability

Report privately through GitHub's Report a vulnerability button on the Security tab. Include what you did, what happened and what you expected. A reproduction against a local instance is the most useful thing you can send. There is no bounty.

Threat model

  • Hostile: the public internet, anyone who can reach the login page, any signed-in account acting against another, and the library itself (metadata, cover art, lyrics), since anyone with write access to a shared library controls it.
  • Semi-trusted: the upstream music server. Heddohon trusts it for content and keeps control of what executes in the browser (see Proxied media).
  • Trusted: the operator, the host, the reverse proxy and the container environment.
  • Out of scope: anyone with shell access to the host or read access to the data volume. Credential encryption protects a stolen database file; an attacker running code beside the process can decrypt what it decrypts.

Design

The browser only talks to Heddohon, and Heddohon fetches every byte from the music server itself. The upstream address stays inside the server process: it appears in no page, bundle or error message, and the login page receives only each server's label and kind. The upstream credential leaves the process only as a request to the music server. The one host you expose is Heddohon.

Heddohon also contacts a PostgreSQL server when HEDDOHON_DATABASE_URL names one (see PostgreSQL). The other hosts it contacts are LRCLIB, only with HEDDOHON_LYRICS_LRCLIB=true, and the AutoEq results on GitHub, only with HEDDOHON_AUTOEQ=true, Discord, only with HEDDOHON_DISCORD=true, ListenBrainz, only with HEDDOHON_LISTENBRAINZ=true, and MusicBrainz, only with HEDDOHON_NEW_RELEASES=true; all five are off by default. And the hosts of the internet radio stations the music server lists, when a listener plays one; that is on unless HEDDOHON_RADIO=false. See Lyrics from LRCLIB, Headphone corrections from AutoEq, Plays sent to Discord and ListenBrainz, New releases from MusicBrainz and Internet radio.

The five third-party switches and the MCP endpoint are saved by the first-run setup, and an account the music server lists as an administrator (asked of the music server on each save) turns them on and off under Settings, Server, Features (?/saveFeatures). Each is saved to setup.json, taken with the next request, and logged as features-switched at warn. A variable set in the environment takes precedence, and the switch is shown locked. The addresses they fetch from are read from the environment alone. An administrator is shown once on the home page which of them are off.

Two things besides a browser send Heddohon requests, each only where the operator turns it on: the Heddohon plugin running inside Navidrome, with a token the operator sets (see Plays from the Navidrome plugin), and an AI assistant's client, with a token an account makes (see AI assistants (MCP)).

PostgreSQL

With HEDDOHON_DATABASE_URL set, the database is on a PostgreSQL server instead of in the data directory. What is stored does not change: credentials sealed with AES-256-GCM, session and share tokens as HMAC digests, so a dump of the database or its backups yields neither a working session nor a working link nor a music-server password.

  • The database password comes from HEDDOHON_DATABASE_PASSWORD, a file (HEDDOHON_DATABASE_PASSWORD_FILE) or the URL. It is not logged: the startup line names host:port/database, and configuration errors name the variable without its value.
  • Transport. TLS follows the URL's sslmode or HEDDOHON_DATABASE_SSL. Without it, sealed credentials and token digests cross the network in the clear, which still does not expose a usable secret, and settings and queues do.
  • Queries are parameterised as with SQLite. The one place a list is interpolated is the import's column list, which is a constant.
  • Own schema. Tables live in a heddohon schema, set as the search path at connection start-up. In the default public schema of a shared database, CREATE TABLE IF NOT EXISTS would have adopted another application's accounts or settings table.
  • Unencrypted connections are reported once at start-up as database-unencrypted, from pg_stat_ssl.
  • Concurrency. The sign-in throttle is one upsert that locks its row, as on SQLite. The share-link ceiling holds an advisory lock on the account while it counts and inserts: measured before that, 160 simultaneous creations made 103 links against a ceiling of 100.
  • Caching. Sessions and settings are held in memory for 5 seconds, and dropped on sign-out, credential change and settings save within the process. A counter moved after each of those writes keeps a read that was already in flight from caching what it saw, which would otherwise have honoured a signed-out session for another 5 seconds. Expiry is checked on every request against the held row. A second process sharing the database is not supported, and would honour a session ended through the first for up to 5 seconds.

Lyrics from LRCLIB

With HEDDOHON_LYRICS_LRCLIB=true, opening the lyrics of a track the music server has no synced lyrics for makes the server request <HEDDOHON_LYRICS_LRCLIB_URL>/api/get with the track's artist, title, album and length. That is what LRCLIB learns: which tracks are listened to on this deployment, from its address. No account name, credential or upstream detail is sent.

  • Server-side only. The browser's policy is unchanged; it talks to Heddohon.
  • Bounded. 5 seconds, 256 KB, redirects refused. A failure reads as "no lyrics" and is logged as lrclib-failed.
  • Cached in memory: 500 entries, 24 hours for a hit and 1 hour for a miss, so reopening lyrics does not ask again.
  • Treated as text. The lines are rendered escaped like every other string, and the view labels them "LRCLIB".

Plays sent to Discord and ListenBrainz

With HEDDOHON_DISCORD=true, an account can paste a Discord webhook address in Settings, and each play that counts (past half the track, or four minutes) is posted to that channel. With HEDDOHON_LISTENBRAINZ=true, each account can paste a ListenBrainz user token of its own, and the server sends what is playing at the start of a track and a listen when the play counts. Navidrome can also scrobble to ListenBrainz itself: Settings refuses to link the one while the other is linked, since both would send each play twice. What each service learns is this server's address and the title, artist and album of the track, and Discord its cover. The account's user name is not sent: it is what the sign-in page accepts, and a channel can have many readers.

  • The account chooses the channel, not the host. A webhook address must match Discord's own form. Only its id and token are kept, and the request goes to HEDDOHON_DISCORD_URL with those two in the path, so nothing typed into the form decides where the server connects.
  • Checked before it is kept. The webhook is read from Discord, and the token is put to ListenBrainz's validate-token. One that is refused is not stored.
  • Sealed, and not sent back. A webhook address posts to its channel and a token writes to its profile, so both are sealed with AES-256-GCM under a key of their own (integration). Settings shows the webhook's name or the ListenBrainz user. Neither secret is in any page or log line: a test links both with the log at debug, plays a track, and searches every answer the server gave, its output, and every file in the data directory for them.
  • Sent to one place. A token goes in the Authorization header of a request to HEDDOHON_LISTENBRAINZ_URL and nowhere else, with redirects refused. That address is the operator's: an http:// one sends tokens unencrypted.
  • Library text is shown as text. Titles, artists and albums are written by whoever can edit the library. Markdown in them is escaped, so a title cannot become a link in the channel, and allowed_mentions is empty, so none of them pings anyone.
  • The cover is sent as a file. A cover here is behind a session, so there is no address to give Discord. The server reads it at 256px with the account's own credential, from the cover cache where it is held, and attaches it to the post. Only JPEG, PNG, WebP and GIF are attached, up to 1 MB, under a file name this server sets. A cover of another type, SVG included, is left out and the post goes without one. Discord keeps the image with the message, where unlinking does not reach it.
  • Under "Report playback". With that setting off, nothing is sent.
  • Dropped with the credential. When another user signs in under the account's name, or its password changes, what it had linked is removed, so a name given to someone else does not send that person's plays to the previous holder's channel or profile.
  • Limited per account. Posts for counted plays: a burst of 5, then one every 20 seconds. "Playing now": 5, then one every 5 seconds. Attempts to link that reach either service: 5, then one every 2 minutes. Every request leaves from this server's address, and Discord refuses an address that sends it 10,000 failed requests in 10 minutes, for every account behind it.
  • A bare address in a tag is still an address. Discord turns one into a link wherever it appears in a message, and escaping does not prevent it.
  • Bounded. 5 seconds, 16 KB read of an answer, redirects refused. A webhook Discord answers with 401 or 404, or a token ListenBrainz answers with 401, is unlinked. Failures are logged as integration-failed and do not hold up or fail the play.

Headphone corrections from AutoEq

With HEDDOHON_AUTOEQ=true, the server requests two things from HEDDOHON_AUTOEQ_URL (by default the results directory of jaakkopasanen/AutoEq on raw.githubusercontent.com): INDEX.md, once a day, and the ParametricEQ.txt of each headphone someone chooses in Settings. That is what the host learns: this server's address, and which headphones were chosen. No account name, credential or upstream detail is sent.

  • Server-side only. The browser's policy is unchanged; it talks to Heddohon.
  • Only paths the index lists. /api/autoeq/profile?id= answers 404 for an id that is not in the index, without a request upstream. An index entry whose path has an empty, . or .. segment is dropped when the index is read, from the network or from the data directory.
  • Bounded. 10 seconds, 4 MB for the index and 16 KB for a profile, 20,000 entries, redirects refused. A failed index fetch leaves the held copy in use and is tried again after 5 minutes; both are logged as autoeq-failed.
  • Parsed to numbers. A profile is returned as a preamp and up to 20 filters, each a type from three, a frequency from 10 Hz to 24 kHz, a gain within 30 dB and a Q from 0.1 to 30. None of the fetched text is passed on. The browser checks the same ranges again before building the filters, for a profile from the server, from an imported file and from its own storage.
  • Cached. The index in memory and in HEDDOHON_DATA_DIR/autoeq-index.json for 24 hours, refreshed with If-None-Match; 500 profiles in memory for 24 hours, a failure for 5 minutes.
  • Both routes need a session. Search matches in memory and makes no request upstream once the index is held.

New releases from MusicBrainz

With HEDDOHON_NEW_RELEASES=true, or the box ticked in the first-run setup (which saves it to setup.json), an account can turn on a "New releases" shelf for its home page under Settings, History; it is off for every account until it does. For an account that has, the server reads the ten artists it played most in the last year from its history, and asks HEDDOHON_MUSICBRAINZ_URL (by default musicbrainz.org) for the albums and EPs of each: by the MusicBrainz id the music server keeps for the artist, or by its name where it keeps none. That is what MusicBrainz learns: this server's address, and the names or ids of those artists. No account name, credential or upstream detail is sent.

  • Server-side only. The browser's policy is unchanged; the shelf links to MusicBrainz's pages and loads nothing from there.
  • The library is read first, within the request. The artists' ids and the albums the library holds are read through the account's credential while the home page loads; only the questions to MusicBrainz, which need no credential, may go on after it: a decrypted credential lives for one request.
  • One request a second, as MusicBrainz asks, in one queue for the process, under a User-Agent naming Heddohon. 10 seconds and 1 MB an answer, redirects refused, 3 pages of 100 release groups an artist.
  • Cached. What an artist has released, and the id a name finds, for a day, for every account alike (it is the same for all); 2000 of each. The shelf per account: made as the account turns it on, shown at once after that, and made again behind the one shown once it is a day old (one older than a week is not shown). All of it is kept in HEDDOHON_DATA_DIR/new-releases.json, mode 0600, written at most every 5 seconds, so a restart starts from it; it is a cache, rebuilt where it is missing, and not in a backup. Failures are logged as new-releases-failed.
  • Text only. Titles are cut to 300 characters and rendered as text.

Internet radio

Navidrome keeps a list of internet radio stations, set by its administrators: a name and the address of a stream on another host. Jellyfin has no such list. The browser's policy allows media from this origin only, so a station is played through Heddohon: GET /api/radio/<id>/stream fetches the stream and passes the bytes on. This is the one place the server fetches an address it was not configured with. HEDDOHON_RADIO=false removes the page and the route.

  • Only a listed station. The id is looked up in the music server's list for the signed-in account. Nothing a request carries is fetched, and the stream address is not sent to the browser.
  • http or https only, without a user name or password in the address.
  • Public addresses only. A station on a loopback, private, link-local, carrier-grade NAT or multicast address is refused, by address and by name: every address the host resolves to is checked inside the connection's own lookup, and each request dials a connection of its own, so the address checked is the address dialled. The IPv6 ranges that carry an IPv4 address inside them (IPv4-mapped and IPv4-compatible, NAT64, 6to4, Teredo) are refused with them. This is what keeps a station from being used to read a service on the server's own network. HEDDOHON_RADIO_PRIVATE=true allows them, for a stream served on the local network.
  • Redirects are followed up to three times, each hop held to the same rules. An .m3u or .pls playlist counts as one: up to 64 KB of it is read for its first address.
  • Where a hop leads is written by whoever answered it, not by the music server's administrator. With HEDDOHON_RADIO_PRIVATE=true, a hop served from a public address still leads only to public ones, so a station on the internet cannot redirect this server to the network it sits on. Only a hop that was itself on a private address may lead to another. Until 0.5.0 the setting applied to every hop. CodeQL reports this fetch as server-side request forgery (js/request-forgery): following a station's redirect is a request whose address a remote host chose, which is what the feature does, within these rules.
  • Audio only. A response whose type is not audio/* or application/ogg is dropped unread and answered 502. An HLS playlist is not played.
  • Bounded. 10 seconds to the first byte, cut after 30 seconds without data, 4 streams per account at once. The stream ends with the listener's request and with their session.
  • What the station's host learns is this server's address, not the listener's. The request carries no cookie and no account detail.
  • What reaches the browser is the station's bytes under the type it sent, with X-Content-Type-Options: nosniff as on every response. A station's own page is linked only if it is an http or https address, in a new tab with rel="noopener noreferrer".
  • Failures are logged as radio-failed with the station's id and the reason; the browser is told only that the station could not be played.
  • Nothing is reported to the music server for a station, it is not added to the listening history, and a queue holding one is not saved.

Linking Last.fm and ListenBrainz

On Navidrome, Settings can link the account to Last.fm and ListenBrainz, which Navidrome then scrobbles to. The Subsonic API has no call for it, so Heddohon signs in to Navidrome's own API (POST /auth/login, with the stored password) and calls the endpoints Navidrome's web interface uses (/api/lastfm/link, /api/listenbrainz/link). The code is src/lib/server/backends/navidrome.ts. Jellyfin accounts, and Subsonic servers that are not Navidrome, are shown neither. Last.fm needs Navidrome 0.62.0 or later, the first to sign the link token it sends through last.fm.

  • Nothing new is stored here. A ListenBrainz token is sent to Navidrome in one request, which checks it with ListenBrainz and stores it. The Last.fm API key and secret are Navidrome's configuration; the user grants access on last.fm to Navidrome's key.
  • Navidrome session tokens are held in memory for 30 minutes, keyed by an HMAC of the username and password, at most 1000. Navidrome allows 5 sign-ins per 20 seconds per client address by default, and every account reaches it from Heddohon's address, so a token per request would lock the endpoint. A password change misses the cache and signs in afresh. A token Navidrome refuses is replaced once.
  • A restored queue reads Navidrome's own /api/song, through the same session token, for up to 100 song ids a request (songsByIds in navidrome.ts): 1000 saved tracks cost one sign-in and 10 requests instead of 1000 getSong calls. The ids are the account's own saved queue and the answer is read with the account's token; nothing from it is stored. A batch that fails, and a sign-in Navidrome refuses or limits, falls back to the per-id Subsonic calls. The endpoint is Navidrome's interface API, not a documented one, checked against 0.64.2 on 2026-11-04.
  • The Last.fm return is a GET that changes state upstream. last.fm sends the browser to /settings/lastfm with its token, beside Navidrome's signed link token (uid, valid 5 minutes, naming the Navidrome user) and a state that is an HMAC, under its own key, of the Heddohon account and the link token. The route is behind the session gate and refuses a state that does not match the session's account before anything reaches Navidrome, so a callback URL sent to another person, or a link token taken from elsewhere, links nothing. The session cookie is SameSite=Lax, which a top-level navigation from last.fm carries.
  • Kept out of the log. token, uid and state are removed from logged paths and queries by redact, including inside next when the callback is sent to sign in first. The upstream call is logged by path only, as every upstream call is.
  • The browser is sent to last.fm by the page, not by a redirect. form-action 'self' refuses a cross-origin redirect after a form post, and the policy is unchanged.
  • These endpoints are Navidrome's interface API, not a documented one, checked against its source on 2026-09-25. A change there shows as the section not appearing (scrobbler-failed in the log), not as an error elsewhere.

Smart playlists

On Navidrome, an account makes and edits smart playlists: rules Navidrome keeps and evaluates itself (added 2026-10-20). Heddohon calls the same /api/playlist endpoints Navidrome's web interface uses, through the session token above (navidrome.ts), and plays the result through the Subsonic API like any playlist. Subsonic servers that are not Navidrome are offered none.

On Jellyfin, which has no smart playlists, Heddohon keeps the rules and fills an ordinary Jellyfin playlist from them (smartplaylists.ts, added 2026-11-05). The rules are stored in smart_playlists, by account and playlist; the songs are worked out from the library listing read with that account's own credential, when the playlist is made, when its rules change, and when its page opens more than 15 minutes after the last time, and they are written into the playlist only when they changed. Other Jellyfin apps see the playlist and its songs, not the rules. A rating rule is refused on Jellyfin, which keeps no ratings.

  • The browser never sends Navidrome's rules. It sends the editor's model, which checkRules in src/lib/smartrules.ts holds to 12 fields, 10 operators and the bounds under Input bounds, and the server writes Navidrome's JSON from what passed. Navidrome 0.64.2 stores a rule on a field it does not know and answers 200, so this check is the only one. Fields that read other playlists (inPlaylist) or file paths are not offered.
  • Only the account's own credential is used, so what a rule matches is what that user may read, and a play count or a rating is that user's. Navidrome refuses a change to another user's playlist with 403, which ends no session, and refuses any change to a smart playlist's songs.
  • Rules a file defines are not changed here (409): Navidrome would take the change and import the .nsp file over it at its next scan.
  • On Navidrome nothing is stored here. The rules live in Navidrome. On Jellyfin the rules and the ids last written are stored here, with no credential, and go with the account when it is deleted.
  • A Jellyfin smart playlist takes no edit to its songs by hand (409 from /api/playlists/[id]/tracks, an error from the MCP tools, and readOnly in their listing): Jellyfin would take it, and the next evaluation would put the songs back.

Plays from the Navidrome plugin

Navidrome tells a scrobbler plugin of every play of a user, whichever app made it, and keeps a scrobble history that only a plugin can read. The Heddohon plugin (heddohon-navidrome-plugin, a repository of its own, installed in Navidrome as heddohon.ndp) posts each play to POST /api/plugin/navidrome, and Heddohon notes it in that account's listening history. An account can also import its whole scrobble history from Settings. It is off unless HEDDOHON_NAVIDROME_PLUGIN_TOKEN is set: without it the route answers 404.

A plugin cannot be reached from outside Navidrome, so every exchange is a request from Navidrome to Heddohon. Heddohon makes no request to the plugin.

  • The route is outside the session gate and takes the token in its place, as Authorization: Bearer. The token is the operator's, at least 32 characters, and may not be the value of HEDDOHON_SECRET. It is compared as two HMAC digests in constant time, and a request without it is answered 401 before its body is read. A session cookie does not open the route.
  • The origin check applies to it as to every write. The plugin sends Origin with the address it is configured with, so the check has no exception for this path. A browser cannot set that header, and the route reads no cookie.
  • What the token allows: adding plays to a history. A play names a user, a song id and a time. It is noted for the account that user name signs in to, and only when that account's stored credential still signs in to Navidrome and can read the song. The row holds the song as Navidrome describes it to that account, so the request supplies no text that is stored or shown. A time more than 5 minutes ahead of the server's clock is refused; a time in the past is taken, since Navidrome sends a play again after an outage with its original time.
  • What it does not allow. Nothing is read through the route: every answer is the list of user names with an import open, which is empty unless an account has just asked for one. It changes no setting, session or credential, and reaches no account on Jellyfin.
  • A stored credential is opened without a request of its account, for the one song lookup a play needs, as a shared link opens its owner's. A credential Navidrome rejects drops the play and does not end the account's sessions from here; the account's next request does that.
  • A page of scrobble history is taken only for an import that is open, which only the account itself opens, from Settings, in a request with its session. The songs are read then, under that session's credential, and a scrobble of a song not among them is skipped. A page for any other user is ignored. An import with no page for 2 minutes is closed.
  • An account can turn it off under Settings, History ("Plays from other apps"). Its own plays are noted as before.
  • What an app is playing now is held in memory, for the account's own browsers. Navidrome reports each client's track, whether it plays or is paused, and where it is in it, and the plugin passes that on with the client's name. Under the Devices button the account sees its other apps and can play an app's track here from that point ("Continue here"). It is taken under the same rule as a play: the account's stored credential has to sign in and read the song, and the track shown is the one Navidrome describes. The app's name is the one text taken from the request. It is cleaned as a display name is, cut to 32 characters, and sent to that account's browsers alone, which show it as text. Navidrome's id for the client is not sent: the browsers are given a digest of it. An entry ends when Navidrome reports the app stopped or its session expired, 20 seconds past the end of the track where neither arrives, and after 30 minutes paused. Nothing of it is written to disk, and no command is sent to an app: Navidrome has no way to send one. Other accounts see none of it unless the account turned on "Include what I play in other apps"; see Listening now. Heddohon's own plays come back from Navidrome the same way and are left out by its client name.
  • Bounds: 100 plays a message, 2000 scrobbles a page, the 512 KB body cap, ids under 256 characters, 4 imports open at once, 8 apps held for an account, a position of at most a day.
  • The plugin asks Navidrome for four permissions: HTTP to any host (Heddohon is usually on a private address, which Navidrome otherwise refuses a plugin), the users assigned to it, their scrobble history, and a schedule for its poll every 15 seconds. It contacts only the address in its settings, does not follow redirects, so the token goes nowhere else, and sends a user name, a song id and a time per play, and for what a client is playing now the user name, the song id, the state, the position and the client's id and name. Navidrome's administrator chooses which users it covers.
  • The token is stored by Navidrome, in the plugin's settings, where Navidrome's administrators can read it. Where Navidrome reaches Heddohon over plain http, the token crosses that network in the clear: give the plugin an https:// address unless both are on one host or one private network.
  • Kept in this process's memory: when the plugin was last heard from, and the imports that are open. With several processes behind a load balancer an import completes only when the plugin's requests reach the process that opened it.

AI assistants (MCP)

With HEDDOHON_MCP=true, /api/mcp answers the Model Context Protocol over its Streamable HTTP transport, and Settings, AI, offers each account tokens for it. A client given one (Claude Code, for one) can read the account's library, favourites, playlists, history and listening statistics, and, if the token allows it, make, rename and delete playlists, change their entries, and set favourites and ratings. It is off by default: without it the route answers 404 and Settings does not offer tokens. Where the environment does not set the variable, the first-run setup saves it, and an account the music server lists as an administrator turns it on and off under Settings, AI (?/saveMcp, asked of the music server on each request, as for the saved addresses). The change is taken with the next request and logged as mcp-switched at warn. Turned off, tokens already made stay listed to their accounts and open nothing.

  • The token is the one authority. A client sends it as Authorization: Bearer. It is hhmcp_ and 256 random bits, shown once, when it is made; the database keeps its HMAC digest under a key of its own, as for a session. A session cookie does not open the route, and a token does not open any other route.
  • The route is served ahead of the origin check, the one write path that is. A client is not a browser and sends no Origin. An Origin that is sent has to be the server's own, as the protocol asks against DNS rebinding, and is refused with 403 otherwise. The route reads no cookie, and a page on another site cannot send the Authorization header or the application/json body the route requires without a preflight, which this server does not answer. The exception matches the path exactly as sent: the same route reached as /api/%6Dcp goes through the origin check and the session gate like any other request, and then still needs the token.
  • What a token reaches is its account's, through that account's stored credential on the music server, as a page does. A token made without "May change the library" is not offered a tool that writes, and a call to one is refused as a tool that does not exist. Nothing plays audio through the route, and it reaches no other account, no setting, no session and no shared link.
  • Every token ends with the account's sessions: a sign-in with a changed password, a Jellyfin name given to another user, and a credential the music server rejects, including during a tool call. The account withdraws one, or sees when each was last used (to the minute), under Settings. A token has no expiry of its own.
  • Answers carry no upstream detail. A failed call says that the music server has nothing with that id, did not complete it, or no longer accepts the account, in fixed words.
  • What an assistant reads leaves this server for whoever runs its model. That is the reason the variable is off by default, and the Settings section says so above the button that makes a token.
  • Bounds: 20 tokens an account, a name of 64 characters, and the bounds of the matching pages and API routes for each argument (see Input bounds). One JSON-RPC message a request: a batch is refused.
  • Left out of a backup with the sessions, so a token withdrawn after the backup was made does not work again on a server restored from it.

Sound analysis

Sound analysis (issue #312) measures how each song sounds on Heddohon's own server. It is off by default: HEDDOHON_ANALYSIS=true, or the first-run setup or an administrator under Settings, Features or Settings, Server, Sound analysis, turns it on. Off, nothing of it runs and Settings shows no account card for it; an account already named stays sealed and unused.

What it is doing is an administrator's to see. Settings, Server, Sound analysis asks /api/analysis every 5 seconds while it is open, and only an account the music server lists as an administrator gets an answer, asked of the music server on each request. The answer names the song being read, which any account in the library may not see; the controls (pause, pace, hours, retry, reset, the switch) spend the server's processor or its results. A stop on an error is written to the log at the default level (analysis-stopped) and puts a dot on the links to Settings for an administrator.

One album now. An administrator can have an album measured from its menu (/api/analysis/album/<id>), ahead of the library and while the job is paused, though never while someone listens. The album's songs are read with that administrator's own login; the analysis account reads only their audio, so AnalysisSource stays a list of songs and a reader of audio. Each administrator has one album waiting at most.

It reads the library as an account of its own. Analysis runs with no request behind it, so it cannot use anyone's session. An administrator of the music server makes an ordinary account for it there and names it under Settings, Server. That account is the one shared account on the music server Heddohon keeps, and the one exception to invariant 10's "no service account"; it was chosen over holding an administrator's credential (decided 2026-11-12). What holds it to analysis alone:

  • It is not a Heddohon account. Its login is a row in meta, sealed with AES-256-GCM under a key of its own purpose (analysis-account), not a row in accounts. It never makes a session, so it has no cookie, MCP token, shared link, second factor or single sign-on link, and cannot be given one.
  • It cannot sign in to Heddohon. The sign-in form refuses its name, in any case, before the music server is asked, so its password is never tried. The form gives the answer a wrong password gets and counts it in the throttle, so it does not tell a visitor which name is the analysis account; the log says so (sign-in-refused-analysis-account). Quick Connect, which names the user only once Jellyfin answers, refuses it there, as an approval that ran out.
  • Its login is opened in one module. analysis/account.ts is the only reader of the sealed value, and hands out an AnalysisSource: two methods, list songs and read one song's original bytes. The credential stays inside it. A test fails if another module names the sealing purpose or builds a source.
  • It must be able to do little. Saving it signs it in and asks the music server what it may do. An administrator is refused, as is an account that may not play, or one the server will not say about (getUser on Subsonic, Policy on Jellyfin). Any right beyond listing and playing (sharing, uploading, deleting, settings) is named on the card for the administrator to take away.
  • It is dedicated. A name that already has a Heddohon account is refused, so it inherits nothing, and once named it cannot sign in to gain anything.
  • The password is not shown again. The card offers a 32-character password made from the browser's random source (about 190 bits) to set on the music server first. Once saved, Settings shows the name, who named it and when, never the password or a token.

What Heddohon cannot do is stop that account signing in to the music server's own interface or another app with its password: that is the music server's to allow. The card says so.

A shared result, an account's view. A song is measured once and the result is shared by every account: numbers about a file, as Subsonic covers are shared (invariant 10's other exception). Anything that shows songs from it looks each one up with the asking account's own login first, and drops what the music server says that account cannot see. Volume levelling (levelled in analysis/results.ts) adds a gain only to a song the music server has just sent for the account's own login. The player's Track details (/api/sound/<id>) is the first route to ask for a result on its own: a song the account's login does not get from the music server answers 404, and a result is given only for the file the music server now lists.

Where it is kept. The results are in analysis.db in the data directory, a SQLite file of their own, whichever database the server runs on. It holds the music server's song ids and numbers, and no titles. It is not in the backup and can be deleted with no loss but the time to measure again. The analysis account's sealed login is in the main database's meta, and is in the backup like every other sealed credential.

It never writes to the library, and reads audio only through the music server's API. ffmpeg decodes it in a child process at the lowest priority, fed on its standard input: nothing of the music server is on its command line, where ps would show it.

Credentials at rest

  • Upstream credentials are sealed with AES-256-GCM before they reach the database.
  • Keys are derived with scrypt (N = 2¹⁵, r = 8, p = 1) from HEDDOHON_SECRET and a salt of the install's own: 32 random bytes in crypto-salt in the data directory, made on the first start whose database holds no account, written 0600, never regenerated, and packed into a database backup beside heddohon.db. The database records which salt sealed it (a row in meta holding a SHA-256 of the salt, or constant), on SQLite and PostgreSQL alike. An install whose database already held accounts when this was added keeps the constant salt it was written with, rather than being locked out. A salt file that is missing, cannot be parsed, or does not match that record is refused at start, never replaced: the server answers 500 and /healthz reports misconfigured until the right crypto-salt is restored. Separate keys cover encryption, session digests, share-link digests, known-device cookies, Last.fm link state, cast addresses, the comparison of the Navidrome plugin's token, MCP token digests, and the sound analysis account's login.
  • Each seal uses a fresh 12-byte random IV. The tag is verified on open, and a blob with a wrong version, part count, IV length or tag length is rejected.
  • Changing HEDDOHON_SECRET makes every stored credential unreadable and signs everyone out. Use it to revoke everything at once.

Subsonic stores the password. The protocol needs it on every request (md5(password + salt)), so the sealed value is the password itself. Jellyfin issues a token at sign-in and Heddohon discards the password.

First-run setup

A deployment started without HEDDOHON_SECRET, or without the address of any music server, serves one page, /setup, and its endpoint, /api/setup. Every other page redirects to it and every other request is answered 503. A deployment that is set up serves neither: both are behind the session gate like any other route, and /setup sends a signed-in account to the home page. HEDDOHON_SETUP=false switches the page off, and a start without the two values is then the error it was before 0.7.0.

  • The code. At start, a deployment that is not set up makes a code of 20 characters from a 32-character alphabet (100 bits, from the system's random source) and prints it to standard output, which is the container's log. It is held in memory, is not written to the log files in the data directory, and is replaced at every start. Every call to the endpoint carries it and is refused with 401 without it. It is compared as SHA-256 digests in constant time.
  • Wrong codes are not counted. A count that dropped the code after some number of wrong ones would let anyone who can reach the page lock the operator out until a restart. At 100 bits the code is not found by guessing, and a wrong one costs the server one hash. A request body over 16 KB is refused.
  • What the code allows. Asking one address whether a music server answers there, connecting once to a PostgreSQL server to see whether it takes the connection, and saving sixteen values: the secret, the address and name of each music server, the default theme, whether shared links, downloads, lyrics from LRCLIB and AI assistants (MCP) are on, the size of the cover cache, the PostgreSQL address, user, password and TLS mode, and the addresses the deployment is opened at (Cross-origin writes). The list is SETUP_NAMES in config.ts. The third-party addresses, HEDDOHON_RADIO_PRIVATE and the plugin's token are read from the environment alone.
  • The database test. It connects with the address, user and password given, asks SHOW server_version, and disconnects, within five seconds. The answer is the version or why it failed, in words; the password is in no answer and no log. Saving with PostgreSQL connects again first and saves nothing if that fails. A saved password is in setup.json with the secret, and HEDDOHON_DATABASE_PASSWORD in the environment keeps it out.
  • The probe. It sends one unauthenticated request (ping for Subsonic, /System/Info/Public for Jellyfin) to an http or https address, does not follow a redirect, reads at most 64 KB and waits at most 5 seconds. It answers yes or no, and on yes the server's kind and version reduced to letters, digits and . + -. Nothing else of what the address sent is returned, so it does not read a host on the server's network. It does tell whoever has the code whether something answers at an address and port.
  • Cross-origin. The endpoint is not held to the Origin check under Cross-origin writes: that check needs ORIGIN, which a deployment being set up behind a proxy has not been given. It accepts application/json alone, which a page on another origin cannot send without a preflight that is not answered, it reads no cookie, and the code is in every call.
  • Saving. The values are written to setup.json in the data directory, mode 0600, by a rename over the old file. The secret is 48 random bytes, made by the server and shown once on the page. The setup then ends: the code is discarded and the page and its endpoint are gone. An address is saved only where the environment names no music server.
  • Precedence. A variable in the environment takes precedence over a saved value. A setup.json that cannot be read or parsed is a configuration error and not an empty file, so the setup is not offered again over a deployment that has accounts. Deleting the file offers it again, behind a new code.
  • The health probe answers 200 with "status": "setup" while the setup is waiting. A failing probe would have an orchestrator restart the container, and each start makes a new code.

The secret saved by the setup is in the data directory, beside the database it protects. Anyone who can read that directory, or a backup of the whole directory, can decrypt the stored music-server credentials (Credentials at rest):

Music server What is read with the secret and the database
Navidrome, Subsonic The password of every account that has signed in, in full. The protocol needs it with each request, so the password is what is sealed.
Jellyfin An access token for each account, and not its password, which is discarded at sign-in. The token opens that account on the Jellyfin server until it is revoked there.

The same holds for a secret set in the environment once someone has both it and the database; the setup's secret differs in that one directory holds both. The last step of the setup says all of this, and gives the line to move the secret to the environment (HEDDOHON_SECRET=...). The ZIP made under Database backup does not contain setup.json.

Taking the secret out of the file. The same step has a button that removes the secret from setup.json, for an operator who has copied it. It calls the setup's endpoint with a token of 192 bits that the server made with the secret and gave to that page alone. The token is good once and for 30 minutes, and for those minutes the endpoint answers that call and no other; outside them it is behind the session gate. The server keeps the secret in memory until it stops, so nobody is signed out. Started again without HEDDOHON_SECRET in its environment, it asks for the setup again and makes a new secret, and the credentials sealed under the old one cannot be read: every account signs in again.

The code and the saved addresses cross the network as the sign-in password does: in the clear on a deployment reached over plain http. Do the setup on the local network or behind TLS.

Database backup

An account the music server lists as an administrator can download the database as a ZIP from Settings, Storage (POST /api/backup). The archive holds heddohon.db, a SQLite database in one file whichever database the server runs on, a backup.json with the row count of each table, and a README.txt with the steps to restore.

  • Who. The music server is asked whether the account is an administrator on each request, as for a cover fill, and "not known" (a Subsonic server without getUser) is refused. With two music servers configured, an administrator of either gets the rows of both.
  • What it holds. Every account's rows: the music-server credential and the linked services sealed as above, the digests of shared links, settings, saved queues, listening history and profiles. Whoever holds the file can read every account's user name, settings and listening history.
  • What it does not hold. HEDDOHON_SECRET, so the file alone opens no credential and forges no link. Sign-ins, MCP tokens and the sign-in throttle, so a session or a token ended after the backup was made does not work again on a server restored from it; everyone signs in once. Covers and logs.
  • A write, by its method. It is a POST, so the cross-origin check applies and a link on another site cannot start one in an administrator's browser. The answer is private, no-store.
  • Bounded. One is made at a time, and a second request is answered 429. The copy is written to a directory of its own in the data directory (mode 0700), read into memory and removed, and a database past 512MB is refused with 409.
  • Logged. backup-made at warn, with the account and the size.
  • A consistent copy. On SQLite it is SQLite's online backup, which includes what is still in heddohon.db-wal. On PostgreSQL every table is read in one REPEATABLE READ transaction.

Restoring is putting heddohon.db in the data directory with the same HEDDOHON_SECRET. A test restores an archive into an empty data directory, signs in, and reads back a setting saved before the backup. Restoring into an empty PostgreSQL database was run by hand against PostgreSQL 15 on 2026-10-08; the tree has no PostgreSQL suite.

Sessions

The cookie is a 256-bit random token with no payload. The database stores only HMAC-SHA256(token), so reading the database yields no usable cookie.

Property Value
Name __Host-heddohon_session when Secure, heddohon_session otherwise
Flags HttpOnly, SameSite=Lax, Path=/, host-only, Secure (see below)
Lifetime HEDDOHON_SESSION_HOURS, 30 days (720 hours) unless set
Extension Activity updates last_seen_at only; expires_at is fixed at creation

Expiry is checked on every request, and an expired row is deleted when presented. A session token copied from a browser works until that expiry, so the lifetime is also how long a copied token is good for; Settings lists the account's sessions and ends any of them, and a deployment that wants a shorter window sets HEDDOHON_SESSION_HOURS. Signing out deletes the server-side record. When the upstream rejects a stored credential, every session for that account is destroyed.

A reused Jellyfin user name starts a new account. Accounts are matched by name. When a Jellyfin sign-in returns a user id other than the one stored for that name, the earlier user's sessions, links, settings and queue are removed before the new credential is stored, and account-user-replaced is logged.

A changed Subsonic password ends the other sessions. Subsonic reports no user id, so a name given to someone else and a password change look the same. When a sign-in stores a password other than the one held, the account's existing sessions are destroyed first and account-password-changed is logged. Links, settings and the queue are kept; see Known gaps.

Secure flag. HEDDOHON_COOKIE_SECURE=auto (the default) turns it on for https requests, when NODE_ENV=production, or when the host is not loopback. The shipped image sets NODE_ENV=production, so a deployment reached over plain http needs HEDDOHON_COOKIE_SECURE=false, with one exception. A request that arrives on a saved http:// address (Cross-origin writes) whose host is on the local network gets its cookie without Secure: a browser does not send a Secure cookie back over plain http, so nobody could sign in there. The local network is a private, loopback, link-local or carrier-grade NAT address, localhost, a name with no dot, and names ending .local, .lan, .internal or .home.arpa. A saved http:// address on any other name keeps Secure, and HEDDOHON_COOKIE_SECURE=true keeps it everywhere. A session cookie without Secure crosses that network in the clear, as the password does when it is typed.

Settings lists the account's sessions that have not expired, most recently used first: when each signed in and was last used (to the minute), and a label for the browser, such as "Firefox on Android". The label is the browser's family and the platform, taken from the User-Agent header at sign-in; the header itself is not stored, and versions and device models are not kept. A header it does not recognise stores nothing, and the list says "Unknown browser". A session signed in before the current one can be signed out from the list, or all of those at once; a browser that signed in later is signed out from that browser. That keeps a stolen session from signing its owner out again each time they sign back in, and lets the owner's fresh sign-in end it. The page names each session by a handle, 16 hex characters of a SHA-256 of the stored digest, so it holds neither the token nor the digest, and a handle is matched against the signed-in account's own sessions only: one from another account, or none at all, ends nothing. Ending a session deletes its row and cuts any audio or download it is receiving, and the next request from that browser goes to the sign-in page.

At most 50 sessions per account. A sign-in past that ends the account's oldest session. A correct password is not throttled, so without it any account holder could add rows without limit.

Usernames are matched on ASCII case only, as Navidrome compares them, on SQLite and PostgreSQL alike. PostgreSQL's lower() follows the database locale, where a name written with the Kelvin sign (U+212A) matched kate, so it is compared under the "C" collation.

Controlling another browser reaches the same account only. With HEDDOHON_REMOTE_CONTROL on (the default), each signed-in browser with the player open holds /api/remote/events open, and is told the other browsers of its account: a random id per stream, a browser name ("Firefox on Linux"), and what each is playing. POST /api/remote sends a command (play, pause, skip, seek, volume, or a queue of up to 1000 track ids) to one of them; the target is looked up among the signing-in account's own streams, so an id from another account reaches nothing. POST /api/remote/state is taken only from the session that opened the stream it names. A stream is tied to its session like audio: signing out, being signed out from Settings and the session expiring end it. An account holds at most 20 streams. Anyone signed in to the account can already play and change its queue, so this gives a browser no access it lacked; it lets one browser of the account start sound on another. The registry is in the process's memory.

One cookie name is read. Accepting both names would let a sibling subdomain plant heddohon_session with Domain=.example.com and pin a session that signing out cannot clear. Browsers refuse a __Host- cookie with a Domain, which closes that. Switching between the two names signs sessions out once.

Second factor at sign-in

Added 20 October 2026 (issue #225). An account can add a TOTP app, passkeys, or both, under Settings, Security. Heddohon holds no password of its own, so the factor is asked for after the music server accepts the password (or a Jellyfin Quick Connect approval), and guards the sign-in here whatever the music server does. The code is in lib/server/twofactor.ts, totp.ts, webauthn.ts and cbor.ts; tests/e2e/twofactor.test.mjs and tests/browser/twofactor.test.mjs cover what follows.

A password alone changes nothing. For an account with a factor, the music server's answer is held in sign_in_steps, sealed under a key of its own, and the browser gets a heddohon_sign_in_step cookie (__Host- where Secure, HttpOnly, SameSite=Strict, 5 minutes) holding a 256-bit token, stored as its HMAC. The account's stored credential, its other sessions and the device cookie's generation change only once the factor is given; before that, a changed Subsonic password could have signed every other browser out. A correct password still clears the username throttle, and the page then asks for the factor, which tells whoever typed it that the password is right.

Limit Value
A held sign-in 5 minutes; 5 factors sent, then it is dropped and the password is asked for again
Held sign-ins per account 10, the newest kept
Wrong factors per account 5 in 15 minutes, across every held sign-in and every proof (2fa:<account> in login_attempts); a right one clears it
TOTP HMAC-SHA1, 6 digits, 30 seconds, one step either side; a 160-bit secret sealed under its own key
Replay a code's step is stored as taken, by one conditional update, and a code at or before it is refused
Recovery codes 10, each 10 characters of 32 (50 bits), stored as HMACs and deleted as used
Passkeys per account 20; a name of 64 characters
WebAuthn challenge 32 random bytes, 5 minutes, taken once (stored as an HMAC, deleted as it is answered); one live per held sign-in, and per account and purpose
Passkey sign-ins started 30 per address and 600 in all in 15 minutes

With three codes valid at a time, 5 guesses in 15 minutes is 480 a day, and the chance that a day of guessing finds a code is about 1 in 700. Each wrong factor logs second-factor-rejected, and the throttle second-factor-throttled, both at warn, for fail2ban. The throttle is per account, so whoever has the password can keep its holder from signing in for 15 minutes at a time.

Passkeys are checked here without a library. Registration and sign-in check the client data's type and origin (event.url.origin), the challenge (its purpose, and the account or held sign-in it was given for), the hash of the relying party id (the address's host name) and user presence. Sign-in checks the signature with the stored key (ES256, Ed25519, or RS256 of 2048 to 4096 bits) and refuses a signature counter that does not move forward unless both sides are 0, as synced passkeys send. Attestation is not asked for or checked, so nothing here depends on the make of authenticator. The CBOR reader takes the subset WebAuthn uses, 32 levels deep at most, with every length checked against what remains before anything is allocated, out of 16 KB at most. A passkey's user handle is the account's id. Passkeys are offered only on an https address with a host name, or localhost, which is where a browser allows them; a passkey made on one address does not work on another.

A passkey signs in on its own from the sign-in page, with user verification required (a PIN or a fingerprint on the authenticator), through the credential stored at the account's last password sign-in. The music server is asked first whether that credential still works (checkCredential: ping on Subsonic, the user on Jellyfin), so a password changed there, or a token revoked, ends it until the next password sign-in.

A change needs a proof. Turning on an app, adding a passkey, removing either, making new recovery codes and an administrator's reset each need, in the same request, one of the account's factors (a code, a recovery code or a passkey) where it has one, and its music server password where it has none, counted as a sign-in is. A session left open is then not enough to put a factor on an account and lock its holder out. Adding a factor, and removing the last one, ends every other session of the account, those signed in after this one included.

Recovery codes are made with the first factor and shown once. Removing the last factor removes them.

Requiring a factor. HEDDOHON_REQUIRE_TWO_FACTOR=true, or an administrator under Settings, Security (saved in setup.json), holds every account to one. An account without one reaches /settings (a read, and the save, endSession and endOtherSessions actions only), /api/two-factor, /api/settings and /logout; a page elsewhere answers 303 to /settings?tab=security, and anything else 403 second_factor_required. Its MCP tokens open nothing meanwhile. Whether an account has a factor is held for 5 seconds; a second process on the same PostgreSQL database sees a change up to 5 seconds late. While it is required, the last factor cannot be removed. Shared links and now-playing links already made keep working.

An administrator can clear another account's factors, by name, on the same music server, with a proof of their own (and, while a factor is required, only with a factor of their own). The account's sessions and MCP tokens end with them, and two-factor-cleared is logged. An administrator's own factors are removed as anyone's are.

A new Jellyfin user under a name (another user id) starts without the earlier user's factors, which are removed with the rest of that account.

What a factor does not cover. MCP tokens, shared links, cast addresses and the now-playing link are made by a signed-in session and keep working without a second factor, as before. The music server's own sign-in, and every other client of it, are unchanged.

Single sign-on (OpenID Connect)

Added 22 October 2026 (issue #202). With HEDDOHON_OIDC_ISSUER and a client registered at an OpenID Connect provider, an account can link its identity there under Settings, Security, and then sign in from the sign-in page through the provider. The code is in lib/server/oidc.ts and the routes /login/oidc, /login/oidc/callback and /api/oidc; tests/e2e/oidc.test.mjs covers what follows.

The provider never vouches for a music server account. Heddohon holds no password of its own, and the provider holds none of the music server's. An identity is linked to an account by a session of that account, with the same proof adding a passkey takes (a factor where it has one, its music server password where it has none). A sign-in through the provider then opens the credential stored at the account's last password sign-in, after asking the music server whether it still takes it (checkCredential), as a passkey on its own does. Nothing maps a claim to a user name, so an administrator of the provider, or a person who can change their own name or email address there, cannot point an identity at an account they did not sign in to here.

An identity is the token's iss and sub, held in oidc_links, unique both ways: one identity an account, and one account an identity. Only the openid scope is asked for, and no other claim is stored. A second account that tries to link an identity already linked is refused (oidc-rejected, linked to another account) and has to have it unlinked there first.

The round trip. The authorization code flow with PKCE (S256), a 256-bit state and a 256-bit nonce. The state, the nonce, the verifier, the redirect address, the purpose and, for a link, the account are held in a heddohon_oidc cookie (__Host- where Secure, HttpOnly, SameSite=Lax, 10 minutes), sealed with AES-256-GCM under a key of its own; nothing is written to the database before the browser comes back. Lax is needed: the provider sends the browser back with a navigation from its own site. The return is refused before the token endpoint is asked unless its state matches the cookie's, so a return sent to another browser does nothing, and the cookie is cleared on any return. A link completes only where the browser is still signed in to the account that started it.

The ID token is checked by hand with node:crypto, as WebAuthn is: the signature against the provider's published keys (RS256, RS384, RS512, PS256, PS384, PS512 with RSA keys of 2048 bits or more; ES256, ES384, ES512 on their own curves; EdDSA with Ed25519), a key whose use is enc or whose alg is another refused; none and the HMAC algorithms refused; a crit header refused; then iss equal to the discovery document's issuer, this client in aud (and as azp where there are several audiences or an azp), exp and iat within 60 seconds of this server's clock, the nonce sent, and a sub of 1 to 255 characters. The discovery document's issuer has to be the configured one, a trailing slash aside. Discovery is held for an hour (a failure for 30 seconds, and starts at one moment share one request), and the keys are read again for a kid not held at most once a minute. Every request to the provider has a 10-second timeout, a 256 KB cap on the answer, and refuses redirects, so the client secret goes to the token endpoint the discovery document names and nowhere else. The secret is sent in a Basic header unless the provider lists only client_secret_post, and a public client (no secret) sends its id alone and is held to PKCE.

A second factor is still asked for. The provider's sign-in stands in for the password, not for the factor: an account with one goes through beginStep as a password sign-in does. The step's cookie is SameSite=Strict, and a browser does not send it on a redirect that is part of a navigation the provider's site started, so the callback answers that case with a page that moves on to /login by itself (onwards).

A link goes when a new Jellyfin user holds the account's name, and when a password sign-in stores a password other than the one held: on Subsonic a name given to someone else looks the same as a password change. The same person links again from Settings. An unlink takes no proof, since it only takes a way in away.

Limit Value
A pending sign-in or link 10 minutes, one per browser
Returns from the provider 30 per address and 600 in all in 15 minutes (oidc: in login_attempts); each return that passes the state check is one request to the token endpoint
ID token 16 KB; a sub of 255 characters
Code and state in a return 2048 and 128 characters
Provider answers 256 KB each, 10 seconds; 100 published keys read

oidc-linked, oidc-unlinked, oidc-rejected (with the step and the reason) and oidc-throttled are logged at warn, oidc-failed when the provider cannot be read, and a sign-in through it as signed-in with method=oidc. code and state are redacted from logged addresses, as the Last.fm callback's parameters are.

What it does not cover. The provider's own security (its sign-in, its factors, who it lets have an account) is the provider's. An identity linked on a Jellyfin account goes on signing in for as long as Jellyfin takes the stored token, which a password change on Jellyfin may not end; the same holds for a passkey.

Shared links

A signed-in account can make a link to one song, one album or one playlist. Anyone who has the link can listen to it without an account. The link is /share/<token>. HEDDOHON_SHARING=false turns the feature off: new links are refused with a 403, and every route under /share answers without resolving the token, so existing links stop opening. It is read at startup; the restart that applies it ends any stream in progress. Rows are kept, and open again once it is true.

Property Value
Token 256 random bits, base64url, 43 characters
Stored HMAC-SHA256(token) under its own key, the kind (song, album or playlist), its id, the owner and the expiry
Lifetime 1, 7 or 30 days, chosen when the link is made; anything else is refused
Live links per account 100
Withdrawal The owner, from Settings, one link or all of them; streams in progress through the link are aborted, including one still looking its track up
Routes /share/<token> (page), /share/<token>/stream[/<n>], /share/<token>/cover[/<n>]
Tracks served An album's or playlist's first 500, by position <n> from 0

What a link grants. The token is a bearer credential for one item: a song, an album or a playlist. Its holder gets the item's name and artist, and for each of its tracks the title, artist, album, year, duration and audio format, the cover and the audio as stored. The routes read the kind and the id from the row and fetch with the owner's stored credential, inside the process. The one thing a request names is a track's position, <n>: digits only, below 500, looked up in the album or playlist as the owner's account returns it on that request, so it cannot reach a track outside the item. Anything else in that place is a 404. No route under /share takes an id, a path or a write from the request, and every mutating method there is refused by the origin check or answers 405. The owner's credential, the upstream address and the upstream ids of the item, its tracks, their albums, artists and covers are not sent to the browser.

A playlist link is the playlist as its owner has it. A track the owner adds or removes, or a new order, is what the link serves from then on: at once for an edit made in Heddohon, and within five minutes for one made elsewhere (see below). The share dialog says so. A link without a kind, made before albums and playlists could be shared, is a song link.

Only an account's own playlist can be linked to. Navidrome and Jellyfin list another user's public playlist to every account. A link to one would serve that user's name and tracks to anyone, which that user could neither see nor withdraw, so making one is refused with 403 and an existing one stops opening. Navidrome names a playlist's owner. Jellyfin 12.1.0 names none, and a playlist is taken for the account's own when /Playlists/{id}/Users answers it, which Jellyfin does for the owner alone. Until 2026-10-15 a Jellyfin playlist was taken for the account's own whoever had made it.

What a link is to is held for five minutes. The album, playlist or song is read with the owner's credential when a link is first used and held in memory for five minutes per link, so a range request or a track change through the link does not read a whole playlist from the music server again. Measured before this: 50 parallel requests for one position in a 5000-entry playlist made 100 upstream calls and fetched 59.7MB. The token, expiry and withdrawal are still checked on every request. A change made outside Heddohon, including a library the owner can no longer see, reaches the link within those five minutes.

Only the owner's own playlists. Navidrome lists another user's public playlist to every account; a link made to one would publish that user's playlist, as they edit it, where they cannot see or withdraw it. A link to a playlist whose owner is someone else is refused with a 403, and one that changes hands later stops opening. Jellyfin reports no owner and lists only playlists the account may open.

Of the kind it names. On Jellyfin, an album link must name an album, a playlist link a playlist and a song link a track. An album link made with a library's id listed every track in the library.

  • /share is a public route. The session gate does not apply under it. A path that leaves /share after decoding, such as /share/%2e%2e/api/..., is routed and gated as the path it resolves to.
  • Made only for what its owner can see. Creating a link looks the song, album or playlist up with the owner's credential first, so an arbitrary id does not become a row.
  • The owner's account is used for playback. Upstream, a play through a link is a request by the owner's account. Heddohon does not report these plays to the music server. The audio is sent as the original file; transcoding settings belong to an account and are not applied.
  • Shared media is stricter than an account's. A body whose type is not audio/* for the stream or image/* for the cover is refused with a 404 instead of being relayed as a download. A Subsonic server answers stream.view with a rejected credential by sending its error envelope as a 200, and that envelope does not reach the visitor. Responses carry the same sandbox CSP as other media, with private, no-store on audio and private, max-age=300 on covers, so a withdrawn link stops working in the browser that played it. Shared covers bypass the cover cache.
  • A pasted link is previewed by the app it is pasted into. The page carries Open Graph tags: the title, the artist and the address of the cover under the link. A messaging service that draws a preview fetches the page and the cover as any holder of the link can, and keeps its own copy of the title and the image. Withdrawing the link does not reach that copy. The audio is not part of a preview.
  • Kept out of search indexes. The page answers noindex, nofollow, as a header and as a tag, to every reader but the fetchers that draw a preview, known by the name they send (Discord, Slack, Telegram, WhatsApp, Facebook, X, LinkedIn, Mastodon). Those keep no index, and Discord draws no preview of a page that says noindex. /robots.txt allows /share/ and nothing else, so a search engine that finds a link can read the page and its noindex.
  • Every stream request is checked three ways. The token is resolved, and the track is looked up in the owner's song, album or playlist as the owner's credential returned it at most five minutes before, so a track the owner can no longer see stops playing within that time even where the upstream's audio endpoint does not apply library permissions. A stream is registered against its link before its track is looked up and aborted when the link is withdrawn, and the expiry is checked on each chunk. A browser plays a track as one open-ended range, so a check at the start of the request alone let a withdrawn link deliver the whole file.
  • Signing out does not withdraw links. A link plays through the stored credential, not a session. Settings has "Withdraw all".
  • Library text is capped at 300 characters on the page, since it is written by whoever can edit the library and served to anyone with a link. It is turned into text first, whatever type the music server sent, and the audio format is capped at 16.
  • A rejected owner credential reads as unavailable. The link answers 404 on its media and a fixed message on its page. Requests through a link do not destroy the owner's sessions; the owner's own next request does that, as usual. The link works again once the owner signs in and the stored credential is replaced.
  • The owner's username is shown only to signed-in visitors. Shown to anyone with a link, it would publish a username the sign-in page accepts.
  • The token is shown once. Only the digest is stored, so a copy of the database yields no working link. Settings lists links by the song they point at and cannot show them again. Titles are not stored with the link; Settings looks them up with the owner's credential.
  • One answer for every dead link. Unknown, malformed, expired and withdrawn tokens get the same page and 404 on both media routes. An expired row is deleted when presented. A token that is not 43 base64url characters is refused before it is digested.
  • Separate from sessions. The share digest and the session digest use different keys, so a session token presented as a share token, or a share token presented as a session cookie, matches nothing.
  • Withdrawal is scoped to the owner. The delete matches on the row id and the owner's account together, and another account's id answers 404, the same as an unknown one. Creating and withdrawing sit behind the origin check below.
  • Kept out of logs. Every string field of every log line passes through a filter that replaces the segment after /share/ with -, after any extra slashes, spaces, quotes or percent signs. It removes percent-encoding layer by layer until the text stops changing, and a malformed escape does not stop it, so double encoding and a stray %E0 in the same query do not carry a token past it. Error stacks are filtered the same way. Share log lines carry the row id and whether the visitor was anonymous, signed in or the owner, never the token.
  • Client errors are not written at error level. A 400 or 405, which an anonymous visitor can cause at will under /share, is a debug line without a stack. Only 5xx responses write an error line and a stack.
  • Kept out of other places. Pages are sent with private, no-store and x-robots-tag: noindex, nofollow. referrer-policy: same-origin keeps the path out of the Referer header for any other origin, and the page's one external link carries rel="noreferrer".

Not limited. Opening a link and streaming through it are not rate limited. Guessing a token means guessing 256 random bits. What a link's holder can do is fetch that one file as often as they like, which costs the deployment and the music server bandwidth. Cap it at the proxy for wide exposure, as with account streams.

A link works for whoever it is forwarded to, for as long as it is live. The share dialog asks the owner to share only music they have the right to share.

Cast addresses

A Chromecast or an AirPlay receiver fetches the audio itself and carries no session cookie. While a browser casts, each track is played from a cast address, /cast/<token>, a public route. What it is limited to:

  • A token names one track, one account and one session. It is the account id, the session's handle, the track id and an expiry, signed with HMAC-SHA256 under a key derived for this purpose alone. Changing any part fails the signature. Nothing is stored.
  • It lasts 6 hours, and never past the session's own expiry. The browser asks for new ones after 5.
  • It ends with the session. Each request looks the session up by its handle; signing out, being signed out from Settings and the session expiring make every address the session was given answer 404, and a stream in progress is cut as the browser's own are.
  • Every refusal is the same 404: malformed, forged, expired, a session that has ended, or a track the account cannot play.
  • It is kept out of the log, as share tokens are (redact in log.ts).
  • It may be read cross-origin. The receiver plays it from a page of its own on another origin, so a successful answer on this route alone carries Cross-Origin-Resource-Policy: cross-origin and Access-Control-Allow-Origin: *. It is sent without credentials, and the token in the path is the whole of the authority. Every other response keeps same-origin.
  • Anyone who holds the address can play that track until it expires or the session ends, the receiver and anything on the network path included. Over plain http the address is visible on the network, as the session cookie is.

POST /api/cast issues addresses for up to 1000 track ids to a signed-in browser. It makes no upstream call; an id the account cannot play gets an address that answers 404.

Profile pages

Added 20 October 2026. An account has a page at /people/<handle>: four albums it picks, a bio, its display name and picture, and, where it turns each on, the albums it played lately and its most played artists of the last 30 days, from this server's history. lib/server/profilepage.ts has it; tests/e2e/profiles.test.mjs covers what follows.

  • Who sees it. The account itself, always. The other accounts signed in here, once it is listed (off until the account turns it on); /people lists those. Anyone holding its public link, /p/<token>, while there is one. A handle that is not listed answers 404 to another account, as one that does not exist does.
  • What is shown is read, not sent. The editor sends album ids; each is read through the account's own credential before it is kept, and the title, artist, year and cover id kept are that read's. An id the account cannot read is refused. The bio is plain text of 280 characters with control and direction characters removed, shown as text.
  • Covers by place. A cover on the page is served through the owner's stored credential, as a shared link's is, at /api/people/<handle>/cover/<slot> (signed in) or /p/<token>/cover/<slot> (the link): f0 to f3 for the albums, r0 to r7 for the recent ones while they are shown. The address never carries a cover id, so a viewer reaches the covers the page shows and no other. Cover ids are not sent to the browser. On a different kind of music server from the viewer's, albums and artists do not link into the library.
  • The public link is hhpr_ and 43 random characters, stored as an HMAC under a key of its own, shown once as it is made; a new one replaces it. The public page has the owner's display name, Listener where none is set (the user name signs in to the music server and to Heddohon, so a link held by anyone does not carry it), picture, bio, albums and the lists the owner turned on, with noindex, without the handle and without links into the library. Its covers carry private, max-age=300, its picture the same.
  • What ends it. A password change seen at sign-in (on Subsonic, also how a name passed to someone else looks) unlists the page and withdraws its link; every session ending (destroyAllSessions) withdraws the link; a new Jellyfin user under the name removes the page.
  • Switched off (HEDDOHON_PROFILES=false, or an administrator under Settings, Server, Features), every route of it answers 404 as for a page that does not exist, public links included, People leaves the rail and the home page loses the picture that leads to it. What was saved stays, and comes back with the switch.
  • Name and picture. They are the profile's that "Listening now" shows. Since they are the page's too, an account sets them whether or not HEDDOHON_LISTENERS is on; being shown in that list is still offered only where it is. A picture is served to signed-in accounts by its handle as before.

Now-playing link

An account can make a link that shows what it is playing, for an OBS browser source or Home Assistant, under Settings, Account. It has three public routes, each taking the token in its path in place of a session: /now/<token> (a page on a see-through background), /api/now-playing/<token> (JSON) and /api/now-playing/<token>/cover. What it is limited to:

  • What it shows is the account's own track while it plays: title, artist, album, length, position, and the cover. Paused or with nothing playing, the JSON is { "playing": false }, the page is empty and the cover answers 404. It reads the reports the account's own browsers send over the remote control's streams, and its other apps only where the account shows those to other accounts already (listeningOtherApps). Without HEDDOHON_REMOTE_CONTROL there is nothing to show, and every route answers 404.
  • One link an account, made and withdrawn by the account. The token is hhnp_ and 256 random bits; only its HMAC digest is stored, under a key of its own, and it is shown once. A new link replaces the old, which stops working at once.
  • It ends with the account's sessions (destroyAllSessions): a password changed on the music server, a credential it refuses, or a user name reused by someone else withdraws it, as it does MCP tokens.
  • The cover is read through the account's stored credential, as a shared link's is, by the cover id the account's browser reported; the request names no cover. It carries the shared media's headers (private, max-age=300).
  • Every refusal is the same 404: malformed, withdrawn, never made. Answers are no-store, and the token is kept out of the log (redact).
  • Anyone who holds the link sees what the account plays for as long as the link stands. Settings says so beside the button.

Listening together

A signed-in browser can start a live session and hand out its link, /together/<token>, a public route. Anyone with the link hears what the host plays, as it plays, without an account. What it is limited to:

  • It needs HEDDOHON_SHARING and HEDDOHON_REMOTE_CONTROL on. With either off, every /together route answers 404.
  • The token is 24 random bytes. Sessions are looked up by an HMAC digest of it. The token is held in the process's memory with the session, so the host can show the link again, and nothing is written to disk.
  • A listener plays only the track the session is on. The audio and cover routes take ?song=, and answer 404 for any id but the one the host last reported, through the host's account. The file is sent as it is stored.
  • It ends when the host ends it, after 12 hours, or when the host's session ends (signing out, being signed out from Settings, the session expiring). A stream in progress is cut with the host's session.
  • Listeners send reactions only. One of five emoji, from a listener whose event stream is open, at most one a second. There are no names or messages. A reaction names its listener by the id sent to that listener's page alone; the others are shown a separate tag, which a reaction cannot be sent with.
  • Bounds: 50 listeners without an account a session, four streams per signed-in account, and four per address without an account (an IPv6 address by its /64). The host's own browser is always let in, and signed-in accounts are not counted in the 50.
  • The per-address count depends on the deployment. The address is adapter-node's getClientAddress(): the connection's own, or the header named in ADDRESS_HEADER. A forwarding header that ADDRESS_HEADER does not name is never read, and its presence changes nothing, since anyone can send one. Behind a proxy without ADDRESS_HEADER, every visitor has the proxy's address: where that address is loopback or private the count is left off, and the 50 still hold; where it is public, every visitor shares its four, which fails closed. The log says address-header-unset once when a request with a forwarding header arrives without ADDRESS_HEADER, and together-one-address once when five or more visitors of one party arrive from one uncounted address. With ADDRESS_HEADER set to a header the proxy appends to rather than overwrites, or XFF_DEPTH set too low, a visitor writes their own address there and the count does not apply to them. See the operator checklist.
  • 200 sessions in the process, one per host session. The host's reports carry text for the listeners' page (title, artist, album, 300 characters each), shown as text.
  • The token is kept out of the log, as share tokens are.

What a listener learns is what plays and when: title, artist, album, cover and position, for as long as they hold the link. They are also shown what is up next in the host's queue: the title and artist of the next 50 tracks, and for a track a member added, the member's name.

Members and the shared queue

A listener signed in to this Heddohon on the host's music server can join as a member and add tracks to the host's queue. A visitor with no account, and an account on the other server of a deployment with two, listen as before and add nothing.

  • Joining is a press, and it shows a name. The page says "Join as " and that the name is shown. Until then the visitor's stream is a listener's. POST /together/<token>/join needs the session, and names a stream the same account opened: listener ids once went to everyone with a reaction, so a stream is not joined by its id alone. The name is the account's user name on the music server. The host sees the members whose page is open; everyone with the link sees the name on the tracks a member added. Other accounts are given an id made for the party, never the account's id.
  • A track is looked up twice before it is accepted, by the id the member sends. With the member's credential first: a member adds what their own account can read, so a track id cannot be used to ask what the host's account holds. Then with the host's credential, since the audio for everyone comes through the host's account: a track it cannot read answers "Not in the host's library". The track is sent to the host's browser as the host's account reads it. Only the host's browser is sent the track's id; listeners are sent a title and an artist, and the audio route still answers only for the track that is playing.
  • The host's player holds the queue. An addition goes into the host's browser queue after the current track and earlier additions, and does not start or stop playback. The host removes or moves any track there. What listeners are shown is what the host's browser reports, with additions found in it by track id.
  • A member takes back only their own additions.
  • The host removes a member for the rest of the party. Every stream the account has open ends, its additions not yet in the host's queue are dropped, and every /together route for that party refuses the account's sessions, the audio and the cover included. The link itself still opens without a session, as it does for anyone: removal ends what the account could do as a member, and ending the party is what closes the link.
  • Bounds: one addition every 2 seconds per member, counted before the lookups and whether or not the track is accepted, so a refused track costs as much as an accepted one; 50 additions waiting per member; 500 per party.
  • A member's session ending leaves its stream a listener's, and adding needs the session on every request.

GET /api/search?q= answers a signed-in account with the songs its own library holds for a query, 24 at most. It is what a member's search box calls; the search page reads the same through its loader.

Listening now

Accounts signed in to one Heddohon can see what each other is playing. An account is shown only after it turns "Show others what I play" on, in the popup or under Settings, Account. What it is limited to:

  • It needs HEDDOHON_LISTENERS and HEDDOHON_REMOTE_CONTROL on. With either off, /api/profile and the routes under it answer 404, and nothing is sent.
  • Off for every account until the account turns it on. An account that is not shown still sees the accounts that are.
  • Who sees it: every signed-in account on this Heddohon, on either music server of a deployment with two. It is sent down the event stream a signed-in browser already holds open, so it needs a session and ends with it.
  • What is shown, while a track is playing and for no longer: the display name, or the account's user name on the music server where none is set; the picture; the track's title, artist, album and cover id; its length and position; the track's and the album's ids; and which kind of music server the account is on. A pause, a closed browser, signing out and turning the switch off each take the account out of the list at once. Nothing of it is written to disk: the list is in the process's memory.
  • What it plays in other apps is shown only where it turns that on too. With the Navidrome plugin installed, Navidrome reports what every app signed in as the account is playing (see Plays from the Navidrome plugin). An account that is shown is shown with what it plays in Heddohon and nothing else, until it also turns on "Include what I play in other apps" under Settings, Account, which is off for every account until then. With it on, the account is in the list while an app plays, with no browser of its own open here, under the same fields as above: the track is looked up under the account's own credential, and the app's name is not shown to others. Turning either switch off takes it out at once. Most apps tell Navidrome that a track started and nothing after it, so such a track is shown until it would have ended, through a pause or a stop.
  • The account's id is not sent. Other accounts know a profile by a handle, 12 random bytes made with the profile row.
  • Library permissions still decide what a viewer can open. A title and an artist are shown to an account whose library does not hold the track. The cover, the album page and "Play it here" are fetched with the viewer's own credential, and the music server refuses what the viewer may not read.
  • The display name is text. At most 32 characters, with control characters and the marks that set text direction removed, shown through Svelte's escaping and never placed in HTML by the server. A name that is the user name of another account on this Heddohon is refused when it is saved.
  • The picture is a JPEG of at most 96 KB and 512 pixels a side. The browser sends one it has cut square and scaled to 256 pixels, drawn again from the pixels, which leaves out the file's metadata. The server checks what it is sent whoever made it: the bytes have to start a JPEG, and the size it declares is read from its frame header, since a few kilobytes can declare 65535 pixels a side and every viewer's browser would decode them. Before the frame header only tables, application data and comments are stepped over; any other marker is refused, FF 00 among them, which libjpeg drops and this check would otherwise have skipped as a segment with a frame hidden inside. It is kept in the database and served to signed-in accounts from /api/profile/avatar/<handle> as image/jpeg, with nosniff and Content-Security-Policy: default-src 'none'; sandbox, as proxied media is.
  • A changed password switches it off. On Subsonic a user name given to another person looks the same as a password change, so the switch goes off with the sessions and whoever signs in next is shown only after turning it on. The display name and the picture stay, as settings do. Where the music server reports a different user under the name (Jellyfin), the profile is removed.
  • Bounds: the list is sent to everyone at most once in 250 ms; 100 accounts in one list.

Two display names can be the same, and a name is compared with user names only when it is saved: an account that signs in for the first time later can have the user name another account already goes by.

Cross-origin writes

SvelteKit's CSRF check covers form content types only, and every state-changing call in Heddohon is JSON. An explicit origin check covers them:

  • It applies to every mutating request, on every path but /api/mcp (below). A check scoped to /api/ was bypassable, because SvelteKit routes on the decoded path: PATCH /%61pi/settings reached /api/settings without matching the prefix.
  • A missing Origin is refused. Browsers always send it on non-GET/HEAD requests. Scripted calls need -H "origin: <your site>". The Navidrome plugin sends it too; its route is checked like the rest. The one exception is the MCP endpoint, whose client sends none and which takes a token in place of a cookie; see AI assistants (MCP).

SameSite=Lax is a second layer underneath.

The address a request is served on. Both checks compare Origin with the address the server takes itself to be at. That is ORIGIN where the environment sets it. Otherwise it is https:// and the request's Host, which is wrong for a deployment opened over plain http on a local network, and every write there is refused. So an address can be saved, by the first-run setup or by an administrator under Settings, Storage:

  • A request whose Host is the host of a saved address is served as from that address, scheme included. The built server tells the adapter so in two headers of its own (x-heddohon-protocol, x-heddohon-host), the way a reverse proxy would, and removes whatever a client sent under those names. Where the operator sets ORIGIN, PROTOCOL_HEADER or HOST_HEADER, the saved list is not used.
  • ORIGIN in the environment is every request's address, whatever its Host, given to the adapter in the same two headers. adapter-node 5 read ORIGIN itself; adapter-node 6, which SvelteKit 3 needs, takes an address only at build time, and an image is built before it is deployed. Decided by the maintainer on 2026-11-05 to keep ORIGIN exactly as before: every request is pinned to it, so the origin check compares Origin with the same address. An ORIGIN that is not an address answers every request with a 400, as adapter-node 5 did.
  • No check is relaxed. SvelteKit's and this one both run as before, against that address. A saved address is matched against Host, which names the server the request was sent to, so a page on another site is refused whatever is saved: it sends the deployment's Host and its own Origin.
  • The list is changed only by an account the music server lists as an administrator, and a change that leaves out the address it was sent from is refused, since every later write from there would be.
  • The setup's last step and the administrator's form name each saved address on which the sign-in cookie goes out without Secure (Sessions).

Forwarded headers. X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP and Forwarded are read from no request; their presence only writes address-header-unset to the log once. Nothing in Heddohon is allowed or refused by where a request says it comes from: it has no list of addresses that are let through, and a request that claims to be from 127.0.0.1 is treated as any other. The local network in the cookie rule is the host of an address the operator saved, and not the client's. A client address is used only to count: the sign-in throttle and the listen-together streams per address. It is the connection's own unless the operator sets adapter-node's ADDRESS_HEADER; set where the proxy does not overwrite that header, a client can name any address there and avoid the per-address counts, and the count per username and the 50 listeners still apply (Known gaps). The host and scheme a request is served on come from ORIGIN, given to the adapter in x-heddohon-host and x-heddohon-protocol for every request, or from adapter-node's HOST_HEADER and PROTOCOL_HEADER where the operator sets them. With none of the three set, a saved address is matched against Host and passed to the adapter in two headers of Heddohon's own, x-heddohon-host and x-heddohon-protocol, which are removed from every incoming request first (savedOrigin in vite.config.ts); otherwise Host with https assumed.

Sign-in throttling

Every sign-in is proxied to the music server from Heddohon's address, so the upstream's own lockout or fail2ban sees a single client. Heddohon throttles before the upstream is called.

Key Limit Window
Username on one music server, from a browser not known for it 10 attempts 15 minutes
Source address (an IPv6 address by its /64), from a browser not known for it 60 attempts 15 minutes
Known device, at the account it is known for 10 attempts 15 minutes
  • An attempt is counted before the upstream call and refunded if the call gives no verdict, so concurrent requests each pay for their check.
  • Only a rejected credential counts. An unreachable server locks nobody out.
  • A successful sign-in clears the username or device counter. Counters live in SQLite and survive restarts.
  • Per music server. With both servers configured, alice on Navidrome and alice on Jellyfin have separate counters and separate device cookies, so a sign-in to one clears nothing for the other.
  • Known devices. A successful sign-in leaves a heddohon_device cookie (__Host- where Secure, HttpOnly, 180 days): a random id and an HMAC over the id, the music server kind, the username and a generation that moves when a sign-in stores a new password or a new Jellyfin user under the name, so a cookie earned by a previous holder stops counting as known. A browser carrying a valid one for the server and username it is signing in as is counted against that device alone. Guesses from elsewhere run up the username and address counters, which that browser does not read, so they cannot lock its owner out. A tampered cookie counts as none. A browser that has never signed in as the account is still refused while the username is throttled; that is the cost of throttling before the upstream is asked.
  • Usernames over 256 characters and passwords over 1024 are refused before anything is counted, so the throttle table holds no key longer than that.
  • The address counter is skipped when the client address is loopback or RFC1918, which is what a proxy on the same host or Docker network looks like. Counting there would put every visitor in one bucket. A line is logged when this happens.
  • Failures give the same response for an unknown user and a wrong password.
  • Username keys are folded as Jellyfin folds them, upper case then lower, so letters it treats as one (σ, ς and Σ) share one counter.

Proxied media

The upstream reports a content type for covers and audio, and the browser applies it to a response from Heddohon's origin. A library file described as text/html would run script with full access to the signed-in API. Three controls prevent that:

  • Constrained type. The upstream type is reduced to one bare type/subtype, with no parameters and no second type, and that is what is sent. Covers must be image/* and streams audio/*. Anything else is sent as application/octet-stream, which browsers download; on a shared link it is refused with a 404.
  • Sandboxed responses. Every media response carries Content-Security-Policy: default-src 'none'; sandbox, which leaves <img> and <audio> working and makes a scripted SVG inert if opened directly.
  • Header allowlist. Only content type, length, range, accept-ranges, etag and last-modified are copied. Content-Disposition is set by Heddohon. The upstream can set no other header.
  • Range support is never claimed on the upstream's behalf. An upstream that answers a range with the whole file from byte 0 (Navidrome, while a transcode is running) is relayed as a 200 without Accept-Ranges, or, for a range from further in, as the bytes asked for (rangeIgnored in proxy.ts).

Transcodes held in memory

A transcode is read whole from the music server once and answered in ranges from memory (transcodes.ts), so that a dropped stream can be resumed. The read continues after the request that started it, which makes it a way to spend the music server's CPU and this process's memory, and it is bounded:

Bound Value
Reads in progress, per account / in all 2 / 4
Memory held, reads in progress included 192MB
One transcode 64MB
Held after the last request 15 minutes

A request past a bound is relayed as it comes, tied to its own connection. Entries are keyed by account, song, codec and bitrate and dropped with the account's sessions, so one account is never answered from another's read.

Downloads

/api/download/<id> sends the same bytes as /api/stream, untranscoded, with Content-Disposition: attachment. The filename is built from the artist and title tags, which anyone who can edit the library writes: path separators, the characters Windows refuses, quotes and every control character (CR and LF included) are removed, it is cut to 150 characters, and the extension must be 1 to 5 lowercase letters or digits. It is sent twice, as ASCII and as RFC 6266's UTF-8 form. HEDDOHON_DOWNLOADS=false removes the route and the link; it is not copy protection, since a signed-in browser is sent the file to play it.

Cover cache

Covers are cached under $HEDDOHON_DATA_DIR/covers (see Configuration). Audio is never written to disk.

  • Session required. The cache is read after the session check.
  • Cache key: backend, viewer, cover id and size. On Subsonic the viewer is a constant and one copy serves every account, since Navidrome shows all accounts one library. On Jellyfin the viewer is the upstream user id, because Jellyfin restricts libraries per user. The viewer is a fixed-width hash, so a crafted cover id cannot impersonate another viewer.
  • Stored headers match the proxy: sandbox CSP, nosniff, inline disposition, and a content type taken from the stored extension. Only five raster types are cached; SVGs are proxied each time.
  • Any account can clear it. Settings shows whether the account is an administrator and who a clear affects. The only cost of clearing is that covers are fetched upstream again.
  • Only an administrator can fill it. "Cache every cover" in Settings (POST /api/cover-fill) reads every album, artist and playlist and has the music server render each cover at up to four sizes. It is refused unless the music server answers that the account is an administrator, asked on each start; a server that does not answer is refused too. One fill runs at a time per process, 4 covers at once, and it stops at HEDDOHON_COVER_CACHE_MB. It runs after its request has been answered, so it holds the account's decrypted credential in memory until it ends: the one place a credential outlives its request. Stopping it, or destroyAllSessions for the account (a rejected or changed credential), ends it. On Jellyfin it fills only the administrator's own entries, since the key carries the viewer.
  • A request from another site is served, not stored. Sec-Fetch-Site decides: same-origin, none (a typed or bookmarked navigation) and a request without the header are kept; cross-site and same-site are not. The cookie is SameSite=Lax, so a cross-site navigation arrives signed in, and another site could otherwise fill the cache with covers of its choosing. The cover is still served: refusing it would answer whether the visitor is signed in.
  • Kept filled, the server starts a fill itself. An administrator can switch on "Keep it filled" (PUT /api/cover-fill, the same gate). The server then starts a fill once a day and after a restart, with no request behind it, by opening that account's stored credential, as a shared link reads through its owner's. It goes on after the account signs out. Each start asks the music server again whether the account is an administrator, and switches itself off when the answer is no or the account is gone. One account per music server holds it, recorded in the meta table by account id. It has no expiry of its own. It is switched off when the account's stored credential is replaced, by another user under the name or by a changed password, so it never runs with the sign-in of someone who did not switch it on. The account it runs as can switch it off without being an administrator.
  • Cached bytes persist until swept, cleared or the volume is deleted. Set HEDDOHON_COVER_CACHE_MB=0 to disable it.

Injection and rendering

  • SQL: every statement is parameterised.
  • Upstream URLs: host, port and scheme come from the environment, validated at startup against a scheme allowlist. Subsonic ids go through URLSearchParams. Jellyfin path ids go through encodeURIComponent plus a guard against .., which encodeURIComponent leaves intact.
  • Filesystem: the cover id is the only request value in a path. It is used as the filename only if it matches ^[A-Za-z0-9._-]{1,128}$ and is neither . nor ..; otherwise the first 32 hex characters of its SHA-256 are used. The extension comes from a five-type allowlist.
  • XSS: the source has no {@html}, innerHTML, eval or new Function. All music server strings render as escaped text, and every href and src is an app-built relative path.
  • Redirects: ?next= is parsed against a placeholder origin and kept only if it stays on that origin and its pathname does not start with //. The second test catches /.//example.tld, which normalises to a protocol-relative path.
  • Settings: rebuilt field by field. Unknown keys are dropped, enums allowlisted, numbers clamped and booleans type-checked.
  • Transcoding: codec and bitrate are read from stored settings. The mode query parameter only makes the original and transcoded streams distinct URLs for the browser cache.

Input bounds

Input Cap
Request body 512 KB (BODY_SIZE_LIMIT)
Track ids per lookup 1000, each under 256 characters
Concurrent upstream calls per fan-out 8
Songs per playlist write 1000
Playlist name 200 characters
Saved queue 1000 ids
Live share links per account 100
Share link lifetime 1, 7 or 30 days
Page size 100
Sign-in username / password 256 / 1024 characters
Any id in a JSON body or a path under 256 characters
Albums read for one play of an artist 200
Sessions per account 50; the oldest ends
Second factor code 64 characters; six digits from an app, or a recovery code of 10 characters of a-z 2-7, spaces and dashes ignored
A return from the identity provider code 2048 and state 128 characters; an ID token of 16 KB, its sub 255 characters
Second factors see Second factor at sign-in: 5 a held sign-in, 5 wrong ones an account in 15 minutes, 10 held sign-ins an account, 20 passkeys an account
Passkey answer a credential id of 1023 bytes; client data 4 KB, attestation 16 KB, authenticator data 4 KB, signature 1 KB, user handle 64 bytes; CBOR 32 levels deep
Passkey name 64 characters, cut; the request's 300
Playlist positions per removal 1000, deduplicated
Star rating a whole number from 0 to 5
Smart playlist rules 1 to 20 rules, each a field and an operator from an allowlist (lib/smartrules.ts); text 1 to 200 characters; a year 0 to 9999, a rating 0 to 5, a play count to 1,000,000, a length to 86,400 s, days 1 to 36,500; 1 to 1000 songs or no limit
Remote control streams per account 20
Remote command one of nine types; a seek from 0 to 86400 s, a volume from 0 to 1, a queue of 1 to 1000 ids
Remote state text (title, artist, album) 300 characters, cut
Display name 32 characters, cut; control and direction characters removed
Profile picture a JPEG of at most 96 KB and 512 pixels a side
Profile handle in a path 24 hexadecimal characters
"Listening now" list 100 accounts; sent at most once in 250 ms
Cast addresses per request 1 to 1000 track ids
Cast address lifetime 6 hours, never past the session
Listen-together session 12 hours, never past the host's session; 50 listeners without an account, 4 streams per account or per address; 200 sessions a process
Listen-together reaction one of five emoji, one a second per listener
Listen-together addition a track id of 1 to 255 characters; one every 2 seconds per member; 50 waiting per member, 500 per party
Listen-together queue report 1000 tracks; titles and artists kept for the first 50, 300 characters each, cut
/api/search query 2 to 200 characters, cut; 24 songs
Genre id in a path 200 characters; on Jellyfin a GUID, since GenreIds takes a list
Cover size one of ten, 64 to 1536
"On this day" date and time zone a real YYYY-MM-DD within a year of the server's; an offset of -720 to 840 minutes
Transcode codec mp3, opus, aac
Transcode bitrate 96, 128, 192, 256, 320 kbps
ListenBrainz token 1 to 128 of A-Z a-z 0-9 - (ListenBrainz issues 36)
Discord webhook address 300 characters; https://, discord.com or discordapp.com (or their ptb and canary hosts), an id of 15 to 22 digits and a token of 40 to 100 of A-Z a-z 0-9 _ -
Last.fm callback uid / token / state 2048 / 256 / 64 characters
MCP tokens per account 20; a name of 64 characters, cut, with control and format characters removed
MCP tool arguments ids of 1 to 255 characters; a search of 2 to 200 characters and 50 of each kind; 200 albums, 1000 artists, 100 songs or 100 plays a page; 1000 songs or positions a playlist write; a playlist name of 200 characters; a rating from 0 to 5
MCP request one JSON-RPC message, within the 512 KB body cap
Library report an account the music server lists as an administrator; one at a time on the server; kept in memory a day; 50 entries a list
One album analysed now (/api/analysis/album/<id>) an account the music server lists as an administrator, asked on every request (a GET from anyone else answers { offered: false }); the album read with that account's own login; one album waiting for each administrator, 409 while it does; 404 with the feature off or no analysis account named
Sound analysis settings (/api/analysis) an account the music server lists as an administrator, asked on every request; paused and on booleans, pace one of full, gentle and background, whileListening pause or continue, hours null or two whole minutes from 0 to 1439; on refused while HEDDOHON_ANALYSIS is set in the environment; an action of retry or reset
Daily mixes 3 a day for an account, 40 songs each, made at most once a day from this server's history and kept in daily_mixes
Listening history export the account's own plays; format csv or json, from and to whole epoch milliseconds up to 8.64e15, from before to; read 2000 plays a query and written as read. A CSV field that starts with =, +, -, @, a tab or a carriage return takes a ' in front, so a spreadsheet does not run a track name as a formula
Playlist import 1000 tracks a request, each with a title; title, artist and album cut to 300 characters; a length above 0 and under 86400 s or none. Each track is up to two searches of 20 songs on the music server, 8 tracks at a time, stopped when the browser goes. Nothing is written until the playlist is created through /api/playlists
Playlist export format one of m3u, m3u-titles and csv; a playlist the account can read. An M3U line holds no line break; CSV fields as in the history export
Now-playing link one an account; a token of hhnp_ and 43 characters, 64 at most before it is looked up
Profile page 4 albums, each an id of 1 to 255 characters read through the account's credential, once each; a bio of 280 characters (the request's 1120); 8 recent albums and 8 artists
Profile link one an account; a token of hhpr_ and 43 characters, 64 at most before it is looked up; a cover slot f0 to f3 or r0 to r7
Navidrome plugin token at least 32 characters, and not HEDDOHON_SECRET
Navidrome plugin message 100 plays, or a page of 2000 scrobbles; a user name and a song id of 1 to 255 characters; a time in whole seconds, at most 5 minutes ahead
Scrobble history imports open at once 4; closed after 2 minutes without a page
Navidrome plugin playback report one of five states; a position from 0 to 86400 s; a player id of 1 to 255 characters; a player name cut to 300 characters, then cleaned and cut to 32
Other apps held for an account 8, the one longest unheard dropped; 500 looked-up tracks held for 10 minutes
Upstream timeout 20 s to headers, and 20 s more for a JSON body (HEDDOHON_UPSTREAM_TIMEOUT_MS)
Upstream JSON answer 64 MB, refused while it arrives

Response headers

Sent on every response, including early 401, 403 and 500 responses, the files served from disk (/_app/*, /service-worker.js, static/) and SvelteKit's own trailing-slash redirects:

x-content-type-options: nosniff
referrer-policy: same-origin
x-frame-options: SAMEORIGIN
strict-transport-security: max-age=31536000; includeSubDomains
permissions-policy: camera=(), microphone=(self), geolocation=(), payment=()
cross-origin-opener-policy: same-origin
cross-origin-resource-policy: same-origin

adapter-node answers files from disk before any SvelteKit hook runs, so the build puts a middleware ahead of it that sets the same list (hardenedAdapter in vite.config.ts; the values are in lib/headers.ts). offline.html, the one HTML file in static/, also gets default-src 'none' with its script and its inline stylesheet allowed from this origin.

microphone=(self) lets this origin ask for the microphone, and no frame from another origin; the app's pages admit no frames at all (frame-src 'none'). Chrome and Edge list audio outputs by name only once a page holds that permission, and the output control asks for it only when "List outputs" is pressed. The stream it opens is stopped as soon as it is granted and read by nothing (lib/client/output.svelte.ts).

Authenticated pages and private JSON get Cache-Control: private, no-store and Vary: Cookie. Unexpected errors return a fixed message and the detail is logged server-side. The music server's own error text and the network error behind an unreachable server (which names its host and port) are logged and replaced with a fixed message.

App pages carry a Content-Security-Policy, configured in vite.config.ts so that SvelteKit can nonce or hash its own inline bootstrap script:

default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline';
style-src-attr 'unsafe-inline'; img-src 'self'; font-src 'self';
media-src 'self'; connect-src 'self'; manifest-src 'self'; worker-src 'self';
object-src 'none'; frame-src 'none'; base-uri 'self'; form-action 'self';
frame-ancestors 'self'

Everything the app loads is served from its own origin: the bundles, the two bundled font families, covers from /api/cover, audio from /api/stream, and fetches to /api/*. The source carries no external origin, no data: or blob: URL.

The one worker is the service worker in src/service-worker/index.ts. It answers a page load that fails, or a 502 to 504 without the x-heddohon header every Heddohon response carries (a reverse proxy's page for a stopped Heddohon), with a static offline page, sent with the same headers as any other page. It passes every other request to the network without reading it, and caches only the offline page and its script, so no account's data is stored by it. The audio output saved in the browser is forgotten on the sign-in page.

style-src-attr is listed separately because a directive carrying a nonce or a hash ignores unsafe-inline, and SvelteKit adds one to style-src. Attributes are governed by style-src-attr when it is present, and nothing adds a nonce there. Custom properties written onto the document root by lib/client/artwork.ts are unaffected either way, since CSP does not govern changes made through the CSSOM.

upgrade-insecure-requests is absent, because a plain-http deployment is supported (see HEDDOHON_COOKIE_SECURE).

Media responses carry their own stricter policy; see Proxied media.

Container

The server runs as an unprivileged user, and the image is multi-stage, keeping the build toolchain out of the runtime layer.

The container starts as root for its entrypoint alone (docker-entrypoint.sh), which gives the data directory to the user the server will run as and drops to that user before Node starts: PUID and PGID where set, otherwise the directory's owner, otherwise node (1000:1000). Docker creates a missing bind-mount source owned by root, and an image that started unprivileged could not write it until someone ran chown on the host. The server is started through setpriv with its supplementary groups cleared, no inheritable capabilities and no_new_privs set, so it has no capability and cannot gain one through a set-uid file. The tree is given only when the directory itself is another user's. Root is used for the server only where PUID=0 asks for it by number. Started with --user or user:, the entrypoint has no root: it runs the server as that user and changes nothing, as the image did before 0.7.0, and the directory is then the operator's to give. tests/docker/entrypoint.sh checks each of these in the image's base. Secrets are supplied at run time, and .dockerignore excludes .env, .git and node_modules.

Logging

Logs go to stdout and stderr, and the same lines to a file a day in HEDDOHON_DATA_DIR/logs, kept for HEDDOHON_LOG_KEEP_DAYS days (7 unless set; 0 writes none). See Configuration. The files are created with mode 0640 and hold what the level set below puts in the log, so whoever can read the data directory can read them.

  • Default: failures only.
  • info: adds username and client address on sign-in attempts, for fail2ban.
  • debug: adds path, status and duration for every request. Paths contain library ids, so treat a debug log as a listening history.

Values reach the log from anonymous requests (a username, an Origin header). In either format, control characters, Unicode format characters (bidi overrides, zero-width characters) and line separators are written as \uXXXX escapes, so a value cannot recolour a terminal, forge a line or display as something else.

Passwords, session tokens and upstream query strings are never logged. A Subsonic URL carries the username, salt and token, so upstream lines log only the pathname. The end-to-end suite greps a live log for the test password, a session token and any u, t, s or p query parameter.

Known gaps

Open issues

  • style-src-attr allows unsafe-inline. The page shell and the components that size themselves in markup emit style attributes, so style attributes are admitted unconditionally. Script execution is not affected. Removing it means moving those values out of markup and into the stylesheet.

  • A reused Navidrome user name keeps the earlier user's links, settings and queue. If a Subsonic user is deleted and the name given to someone else, the earlier user's sessions end when the new user signs in (see Sessions), and the earlier user's links go on playing through the new user's credential for any song the new user can see. The Subsonic API reports no user id to tell this apart from a password change, where the links belong to the same person. Withdraw them from Settings, or with "Withdraw all", when a name is reused.

  • A reused Navidrome user name keeps the earlier user's second factors, for the same reason: the new holder is asked for the earlier holder's code and cannot sign in until an administrator clears them (Settings, Security). It fails closed.

  • A changed HEDDOHON_SECRET makes TOTP apps and recovery codes unusable, as it does the stored credentials: the secret is sealed, and the codes are HMACs, under keys derived from it. Passkeys keep working. Where every administrator is shut out by this, the operator removes an account's factors in the database: DELETE FROM totp WHERE account_id = ..., and the same for recovery_codes and passkeys.

  • Passkeys in the desktop app depend on Electron's WebAuthn support, which differs by platform. A TOTP app works there. The Android app is Chrome (a Trusted Web Activity) and takes passkeys as Chrome does.

  • Upstream redirects from http to https are followed to any port on the same host, so that Jellyfin's 8096 to 8920 upgrade works.

  • A cover that misses the cache is read into memory before its size is checked.

  • A listen-together link can still be filled for visitors without an account by someone holding it from many addresses, or from one address where getClientAddress() does not tell visitors apart (behind a proxy without ADDRESS_HEADER). The host and signed-in accounts still get in; ending the party and starting another gives a new link.

  • File permissions: the data directory uses the default umask, and /app is writable by the node user.

Accepted by design

  • Library authorization is the upstream's job. Playlist and favourite actions use your upstream credential, so accounts are isolated as far as the music server isolates them. Heddohon's own data (settings, queue) is keyed strictly on the session's account.
  • A shared link reads through its owner's account. Its holder needs no account and gets one song with the owner's library permissions. That is the purpose of a link; see Shared links for what it is limited to.
  • Shared Subsonic cover cache assumes one library per Navidrome server. Where Navidrome limits libraries per user, a cover from a library an account cannot see is served to it from the cache if it asks by the exact cover id, since a hit is answered without asking Navidrome. A fill ("Cache every cover") stores every cover its administrator sees; without one, only covers somebody has opened are stored.
  • Suggestion shelves are held for 30 days. "You might like" on album and artist pages is kept per account for 30 days (an hour when empty), so an item in a library the account has since lost can stay on a shelf, as a name and a cover, until then. Opening it asks the music server, which refuses.
  • A Subsonic playlist is moved by rewriting it. Subsonic has no move, so the playlist is written back whole. A move is refused when the server counts more entries than it lists (a missing file, or a library the account cannot see, which the rewrite would drop), and one that lost an entry added elsewhere in the meantime is reported as a conflict rather than hidden.
  • Per-IP rate limiting belongs at the proxy. Behind one, set limits there or configure adapter-node's ADDRESS_HEADER and XFF_DEPTH, and only if the proxy overwrites that header.
  • /healthz is unauthenticated and shows backend kinds, session lifetime and a build id. Restrict it at the proxy if needed.
  • The version is shown to anonymous visitors on the sign-in page, and in /healthz as a build id. It tells a visitor which release is running.
  • /manifest.webmanifest is unauthenticated, since browsers fetch it without cookies. It returns HEDDOHON_APP_NAME, fixed colours, icon paths and three shortcut paths.
  • /.well-known/assetlinks.json is unauthenticated, since Android's browsers fetch it without cookies. It names the Android app's package and the SHA-256 of the certificate the released app is signed with, plus any in HEDDOHON_ANDROID_FINGERPRINTS. What it grants: an app signed with one of those keys may show this origin in the browser without the address bar (a Trusted Web Activity). The page still runs in the browser, under its policy, with the browser's cookies; the app is given no session and reads nothing of the page. Someone holding the release key could publish an app that shows a Heddohon server without an address bar, which is what the released app does; they could not show another site as this one, since the file vouches only for the origin that serves it.
  • Whoever holds the Navidrome plugin's token can add plays to a history. Any account on Navidrome whose stored credential still works, any song that account can read, at any time in the past, 100 a request, with one lookup on the music server for each. The same holder can say an account's app is playing a song that account can read, which that account's browsers show and, where it turned on "Include what I play in other apps", the other accounts' too. Navidrome stores the token where its administrators can read it. The plays are counted in that account's statistics and shown to nobody else. See Plays from the Navidrome plugin. The variable unset, the route does not exist.
  • Whoever holds an MCP token reads the account's library, until the account withdraws it or its sessions end: there is no expiry. A token that may change the library can also delete the account's playlists. What an assistant reads goes to whoever runs its model, and a client keeps the token in its own configuration, in plain text for Claude Code. Calls are not throttled beyond what the music server takes. See AI assistants (MCP). Turned off, the route does not exist.
  • Concurrent streams per account are uncapped. Cap them at the proxy for wide exposure.
  • Authentication is as strong as the upstream account. There is no second factor or sign-in notification. Settings lists the account's sessions and signs out any of them, or all but the current one; see Sessions.
  • The database is unencrypted at rest, whether a SQLite file or PostgreSQL. Credentials inside it are sealed; usernames, settings and queues are plaintext.
  • npm audit --omit=dev under-reports. SvelteKit is a devDependency bundled into build/, so audit the built output. Currently affected: cookie@0.6.0 (GHSA-pxg6-pf52-xh8x, low), which needs untrusted cookie names that Heddohon never handles.

Operator checklist

The same steps in the order to do them, with less of the reasoning, are in SETUP.md.

  1. Generate a secret with openssl rand -base64 48 (32 characters minimum). Changing it signs everyone out.
  2. Set ORIGIN to your public https:// URL. A wrong value fails closed and breaks writes.
  3. Terminate TLS at the proxy. HSTS is always sent.
  4. Keep the music server private. Only Heddohon needs to reach it.
  5. Keep the data volume private. It holds sealed credentials and session digests. With PostgreSQL the same applies to the database and its backups, and the connection should use HEDDOHON_DATABASE_SSL=verify-full (or require on a trusted network) when the server is not on the same host.
  6. Rate limit and restrict /healthz at the proxy. The offline page does not depend on it.
  7. Rebuild to update. Dependencies are pinned by range and the base image is a floating tag.
  8. Publish the port on loopback behind a proxy (127.0.0.1:3000:3000). Docker's port rules pass host firewalls such as ufw.
  9. For the Navidrome plugin, a token of its own: openssl rand -hex 32, in HEDDOHON_NAVIDROME_PLUGIN_TOKEN and in the plugin's settings, and an https:// address for the plugin where Navidrome is on another network. Leave the variable unset where the plugin is not installed.
  10. Keep backups private, and the secret somewhere else. An archive from Settings holds every account's listening history and sealed credentials. It restores only with the HEDDOHON_SECRET it was made under, which is not in it.
  11. After a first-run setup, move the secret to the environment. The setup saves it in setup.json in the data directory, where a copy of that directory is enough to read the stored credentials. Set HEDDOHON_SECRET to the value the last step shows, remove it from the file, and restart. Where every value is set in the environment, HEDDOHON_SETUP=false keeps the setup page from being served if one is ever left out.
  12. Turn on AI assistants only where the accounts may hand their library to one. Each account then decides for itself, and what an assistant reads goes to its model's provider. An administrator of the music server can turn it on under Settings, AI, unless HEDDOHON_MCP is set in the environment; set it to false there to keep it off. Behind a proxy that restricts paths, /api/mcp takes POST, and GET and DELETE answer 405.
  13. Behind a proxy, tell adapter-node where the visitor's address is. Set ADDRESS_HEADER to a header the proxy sets itself (X-Real-IP from nginx, or X-Forwarded-For with XFF_DEPTH set to the number of proxies in front that add to it, counting each that the request passes through). The sign-in throttle and the listen-together count per address use it. Left unset, every visitor behind the proxy has its address: on a loopback or private one the per-address counts are left off, and on a public one everyone shares them (the sign-in backstop of 60 failures in 15 minutes, and four listen-together streams). The log says address-header-unset either way. Set to a header the client controls, a visitor names any address and both counts stop applying to them. The same goes for HOST_HEADER and PROTOCOL_HEADER: leave them unset unless the proxy overwrites them, and set ORIGIN instead where the address is fixed. Set ADDRESS_HEADER only where every request comes through the proxy: adapter-node answers 500 to a request without it, and to one carrying fewer X-Forwarded-For entries than XFF_DEPTH.
  14. Let Heddohon's security headers through the proxy. A proxy that sets Content-Security-Policy, Referrer-Policy, Cross-Origin-Resource-Policy or Permissions-Policy on every site replaces Heddohon's: the nonce-based script policy, same-origin referrers and the sandbox on media. Attach such a header set to the sites that need it rather than to every site.
  15. If you turn on sound analysis, make an ordinary account for it on the music server, with only the rights to list and play, give it the password Settings suggests, and use that account for nothing else.

Audit history

Most reviews were AI-assisted and all were checked by the author. A professional third-party audit has yet to be done. Findings were reproduced against a running build before being fixed.

14 September 2026

Three parallel source audits plus request-level testing against a running build. Every fix is covered by the verification suite.

Severity Finding Fix
Critical Origin check bypassable with a percent-encoded path Check applies to every path
High No sign-in rate limiting Throttling added
High Media proxy relayed upstream content type, allowing HTML from this origin Type constrained, responses sandboxed
Medium Jellyfin playlist delete could delete any item Item type verified first
Medium Secure flag keyed on NODE_ENV alone Request scheme and host also read
Medium Errors echoed internal detail Logged server-side
Low Missing Origin accepted on writes Refused
Low Security headers missing from early returns Added
Low .. reached a Jellyfin path segment Id guard
Info Unvalidated sort preference; prototype-chain lookup in theme fallback Fixed

Also examined: token generation and storage, key derivation, GCM usage, expiry, SQL parameterisation, template escaping, header relay, mass assignment, input bounds, secrets in the bundle and git history, and SSRF from user input.

15 September 2026

Four parallel source audits covering the cover cache, transcoding and logging, each told to verify this file's claims. Every fix is covered by the verification suite.

Severity Finding Fix
High Throttle read before and wrote after the upstream call, so concurrent attempts shared one check Attempt counted first, refunded without a verdict
Medium /healthz returned config errors naming the upstream address and secret length Detail logged, response generic
Medium Cookie lacked __Host-, allowing a sibling subdomain to pin a session Prefixed when Secure, one name read
Medium Secure derived from ORIGIN, which adapter-node does not require Derived from scheme, NODE_ENV and host
Medium Cover cache ignored Jellyfin per-user library limits Viewer added to the key
Medium Authenticated responses had no Cache-Control or Vary private, no-store and Vary: Cookie
Medium Shared address bucket behind a proxy let 60 failures block all sign-ins Applied only to real client addresses
Medium ?next= accepted /\example.tld and /<TAB>/example.tld Parsed and held to this origin
Low Account rows matched case-sensitively COLLATE NOCASE

Also examined: token entropy, HMAC lookup timing, the session lifetime against a client-set Max-Age, IV uniqueness, behaviour on an unset, short or changed secret, the build-time placeholder secret, credential exposure in load returns and the bundle, all 31 logging call sites, the header allowlist, route gate bypasses, null origin handling, the size and mode parameters, and cover cache traversal and key injectivity.

17 September 2026

Follow-up review of the 15 September tree. These fixes are not yet in the verification suite.

Severity Finding Fix
Medium ?next=/.//example.tld (also /..//, /%2e//) redirected off-site Pathnames starting with // refused, server and client
Low Subsonic /api/songs and artist play opened one upstream call per id or album At most 8 in flight
Low Failed sign-in returned upstream error text to anonymous visitors Fixed message, detail logged

Open findings from all three reviews are listed under Known gaps.

22 September 2026

Content-Security-Policy added to app pages, which was the largest item left open by the three reviews above. Not yet in the verification suite.

Severity Finding Fix
Medium App pages carried no Content-Security-Policy default-src 'none' with same-origin sources, configured in vite.config.ts so SvelteKit nonces its own inline bootstrap script

Checked against a running build: pages, covers and playback load with the policy enforced. The residual style-src-attr 'unsafe-inline' is listed under Known gaps.

23 September 2026

Review and request-level testing of shared links, which open without an account, against a mock upstream with hostile metadata, content types and headers. Fixed before release; 82 functional and 47 attack checks pass.

Severity Finding Fix
Medium A malformed escape after a share token put the raw token in the error log at the default level, through SvelteKit's "Failed to decode URI" message Every log field and stack filtered; 4xx no longer logged as errors
Low The log filter decoded once, so double encoding or one malformed escape let a token through at debug Decoded layer by layer, tolerant of bad escapes
Low Anonymous 400 and 405 responses under /share each wrote an error line and a stack Logged at debug
Low Withdrawing or expiring a link did not stop a stream already in progress Streams registered per link and aborted; expiry checked per chunk
Low The stream route did not check that the owner could still see the song Song looked up on every stream request
Low image/png, text/html passed the media type prefix check Type reduced to one essence and sent as that

Follow-up the same day, closing an item left open since 15 September:

Severity Finding Fix
Medium Upstream redirects were followed to any address, replaying a Jellyfin login body there and, through shared links, serving the target's body to anonymous visitors Followed only within the configured origin, or from http to https on the same host, for at most 5 hops; anything else fails and is logged as upstream-redirect-refused
Low The two font subsets under 4 KB were inlined as data: URLs, which font-src 'self' refused Assets are never inlined
Low Svelte rendered onload and onerror as inline handler attributes, which script-src refused, so a cover that failed before hydration kept its broken image Listeners attached from script

Whole-application review the same day, request-level, with a battery kept beside the functional suites:

Severity Finding Fix
Medium Ten wrong guesses from anywhere locked the account's owner out for 15 minutes, repeatably, since the username throttle is checked before the upstream Known-device cookie: a browser that has signed in as the account is counted on its own
Medium Anonymous sign-in attempts stored their username as a throttle key at any length; a 400 KB username wrote a 400 KB row, without limit behind a proxy Username 256 and password 1024 characters, checked before counting
Low Terminal escapes and bidi overrides in a username or Origin header were written raw to the text log Control and format characters escaped in both log formats
Low /api/star, /api/playback, /api/tracks and playlist writes forwarded ids of any length upstream; playlist removal took any number of positions Ids under 256 characters; 1000 positions, deduplicated
Low The session gate's redirects lacked the hardening headers Answered with them, except client-side data requests, which keep SvelteKit's JSON redirect
Low The player's silent priming sample was a data: URL, which media-src 'self' refused, so the second audio element was never unlocked for autoplay Served as /silence.wav
Low The LRCLIB client read the whole response before applying its 256 KB cap Cap applied while the body streams; tested with a 2 MB answer sent without a length

Held: ten open-redirect spellings of next, login CSRF, null and look-alike origins, GET and cross-origin logout, markup in next, error pages and search, a session token with a trailing NUL, forged Quick Connect state, CORS on OPTIONS, and the hardening headers on 404, 401 and public pages.

Also examined: escaping the gate from /share by path normalisation (.., encoded dots and slashes, backslashes, ;, NUL, double encoding, absolute-form targets, __data.json), methods other than GET and HEAD, ids or paths in the query, upstream ids and usernames in anonymous HTML and data, HTML, SVG and error-envelope bodies, relayed Set-Cookie, Location and CORS headers, expiry during range requests, cross-account listing and withdrawal, origin checks on the JSON API and the settings action, the 100-link cap under 160 parallel creates, share and session token interchange, and script in library text on the share page, its title and Settings.

24 September 2026

Source review of the server code and request-level testing of a production build against mock Subsonic and Jellyfin servers, with both configured. The suite and the mocks are now kept in the repository under tests/; 142 checks pass, and each fix below has a check that failed before it.

Severity Finding Fix
Medium With both servers configured, the username throttle and the known-device cookie were shared by the two accounts of one name, and a sign-in to one reset the counter for guesses at the other Counters and device signatures carry the server kind
Medium When a music server name passed to a new user, the new credential was stored on the earlier user's row, and the earlier user's sessions and links used it A changed Jellyfin user id ends the row's sessions and links and clears its settings and queue first. A changed Subsonic password ends the row's sessions; links are listed under Known gaps
Low /healthz on an invalid configuration answered without the hardening headers Hardened

Re-verified: every fix in the tables above, by request where the suite covers it and by source otherwise. The revocation gap was found to cover twelve handlers rather than five, and its entry is corrected.

25 September 2026

Source review of every server-side change since the review of 24 September, before v0.2.0: Last.fm and ListenBrainz linking (the Navidrome session cache, the settings actions and the /settings/lastfm return), range handling and the transcode buffer in the media proxy, the cover cache's file index and streamed writes, the favourites sort, the artist, favourites and genre listings, and part on /api/tracks. The client changes were checked for HTML sinks (there are none), the Content-Security-Policy and hooks.server.ts are unchanged, npm audit --omit=dev reports nothing, and the whole git history was searched for committed secrets (none).

Severity Finding Fix
Medium A transcode read went on after its request with no limit on reads in progress, so a loop of HEAD requests from a signed-in account started a transcode on the music server and a copy in memory for every song Reads limited to 2 per account and 4 in all, memory capped with reads in progress counted, 64MB per transcode; past a bound the transcode is relayed
Low A transcode held for an account was not dropped when a music server name passed to a new user, who could be answered from the earlier user's read for 15 minutes Dropped with the account's sessions
Info npm audit lists cookie before 0.7.0 inside SvelteKit (GHSA-pxg6-pf52-xh8x): names, paths and domains are not checked for out-of-range characters Not reachable: every cookie name and path here is fixed. Left for SvelteKit to update

The Last.fm return was checked against a session from another account, a changed state and no session (refused, redirected to sign-in), and its query against the log at debug (redacted); the suites cover each.

28 September 2026

Source review and request-level testing of everything added since the review of 25 September: links to albums and playlists, the signed-in browsers list, the album, artist and suggestion caches, instant mix, playlist reordering, the favourites orders, the offline page, the audio output and its microphone permission, the settings tabs, and the :dev and prune workflows. Five reviews ran in parallel against a production build with mock Subsonic and Jellyfin servers, one of them black-box. The PostgreSQL finding was reproduced on postgres:16-alpine. Each fix has a check that failed before it.

Severity Finding Fix
Medium Every request through a link read the whole album or playlist from the music server: 50 anonymous requests for one position in a 5000-entry playlist made 100 upstream calls and fetched 59.7MB What a link is to is held for 5 minutes per link
Medium On PostgreSQL, lower() follows the locale, so a user named with a Kelvin sign signed in to kate's account row and took over its settings, queue and links Names are compared under the "C" collation, and the index rebuilt
Medium A Jellyfin artist id the server could not parse left AlbumArtistIds empty, so one play of "artist x" read every album and made 4001 upstream calls Albums, artists and playlists are looked up by id and checked for their type before anything is listed by them
Low On Jellyfin, a link's kind was not checked against the item, so an "album" link to a library published the whole library The same type checks; Ids lookups limited to the ids asked for and to tracks
Low A link withdrawn while its track was being looked up still delivered the file The stream is registered before the lookup
Low A link could be made to another user's public Navidrome playlist, which then followed that user's edits Refused unless the account owns the playlist
Low Playing an artist read every album, with no cap, and went on after the browser left; one request could empty every account's details cache 200 albums, stopped on abort, read past the cache; each cache holds at most a quarter of its bound for one account and sweeps expired entries
Low A request that resolved its session just before a new Jellyfin user took over the name could store the old user's answers for the new one Cache keys carry the upstream user
Low A Subsonic reorder rewrote the playlist from a list that leaves out missing and hidden entries, deleting them, and lost an entry added in between Refused when the counts differ; a lost entry is reported
Low The music server's error text, and the network error naming its host and port, reached the browser Logged, replaced by a fixed message
Low Any account holder could open sessions without limit (300 in 1.5s) 50 per account, the oldest ending
Low Signing out on a plain-http deployment sent a Secure deletion, which the browser ignores Deleted as it was set
Low A known-device cookie outlived a password change and a reused Jellyfin name Signed over a generation that moves with them
Low Letters Jellyfin folds together (σ, ς, Σ) split the username throttle Keys folded as Jellyfin folds them
Low A stolen session could sign its owner out again each time they signed back in A session ends only sessions that began before it
Low Files served from disk, SvelteKit's trailing-slash redirects and the offline page carried none of the hardening headers Set ahead of the static file server at build time, and on the offline page by the worker
Low A skipped :dev run joined the workflow's concurrency group and cancelled the build in progress; a fork can name its branch dev Concurrency on the job; the head repository is checked
Low The Docker Hub token with delete rights went to every image workflow, whose actions were pinned by tag Actions pinned by commit; the prune workflow reads its own DOCKERHUB_PRUNE_TOKEN
Low The prune workflow went on when a kept image could not be read The run stops
Info Remote sign-out did not stop a stream in progress; a Quick Connect sign-in left the old session listed; a share token after a stray character reached a debug log; the stored client_pseudonym was a User-Agent fingerprint; ids in paths had no length cap; the release workflow did not wait for the suites; ?lastfm= read the prototype chain; the offline page read /healthz, which the checklist advises restricting; the saved audio output outlived signing out; yarn was left in the image Each fixed as described in the sections above

29 September 2026

Independent source review at 5d92332: 54 route handlers, five parallel sweeps, each finding re-verified. Nothing above Low. The PostgreSQL finding was shown from the source and pg-pool's documented behaviour; no server was run. The other three have a check that failed before the fix.

Severity Finding Fix
Low The PostgreSQL pool had no 'error' listener (the line had been damaged into a comment), so an idle connection the server dropped ended the process The listener logs database-connection-lost and the pool reconnects on the next query
Low The upstream timeout stopped when headers arrived, so a JSON answer that stalled or never ended was read with no deadline and no size limit JSON bodies are read under a second HEDDOHON_UPSTREAM_TIMEOUT_MS and refused past 64 MB; streams keep no limit after their headers
Low The sign-in address counter was keyed on the full IPv6 address: 300 attempts from one /64 with a new address each were all allowed IPv6 addresses are counted by their /64, for sign-in and Quick Connect
Info The error page SvelteKit builds when an endpoint fails went out without a Content-Security-Policy; its text is fixed and it has no script HTML without a policy is given default-src 'none' with inline styles only

13 October 2026

Review of the first-run setup (setup.ts, /setup, /api/setup, the saved values in config.ts) before it was merged. Each finding has a check in tests/e2e/setup.test.mjs.

Severity Finding Fix
Low Ten wrong codes dropped the code until a restart, so anyone who could reach the page could lock the operator out of the setup Wrong codes are not counted; the code is 100 bits
Low The probe read the whole answer and then cut it to 64 KB, so an address that never stopped sending was read until the 5-second timeout, at whatever rate it sent Reading stops at 64 KB
Info The page's data said which of the secret and the music server was missing, before the code Told with the first right code
Info A music-server address was saved where the environment already named one, and would have taken effect if that variable were later removed Saved only where the environment names none

The same day, the saved addresses and the cover cache's size were added to what the setup and an administrator can save. Checked in tests/e2e/setup.test.mjs: a write from another site is refused with an address saved, with the server's own two headers forged, and as a form; a saved http:// address on a public name keeps Secure; a host nothing was saved for is taken to be https as before; and an account that is not an administrator cannot change either. A first version of this change switched SvelteKit's own check of Origin off and rewrote the request's address in the hook. It was not merged: the address is given to the adapter instead, and both checks stay.

Looked at and left as it is: the probe tells whoever has the code whether something answers at an address and port, which is what entering a music server's address is; and the secret the setup makes is kept in the data directory, which First-run setup and the last step of the setup state.

15 October 2026

Found while adding public and private playlists, with a check each in tests/e2e/app.test.mjs (whose a playlist is, and who sees it).

Severity Finding Fix
Medium On Jellyfin a link could be made to another user's public playlist, which served that user's name and tracks to anyone, out of their reach to withdraw. Jellyfin 12.1.0 lists another user's public playlist to every account and names no owner, and a playlist without one was taken for the sharer's own Refused with 403; a playlist is the account's own when /Playlists/{id}/Users answers it, which Jellyfin does for the owner alone
Low Navidrome's error 50 ("not authorized for the given operation") was taken for a rejected password. A change to another user's playlist through a path that ends sessions on one (a rating, an MCP tool) signed the account out everywhere and withdrew its MCP tokens A refusal of its own (forbidden), answered 403, which ends nothing; Jellyfin's 403 likewise
Info Navidrome 0.64.2 lists an administrator every user's private playlists, and the playlists page showed them Left out: an account sees its own playlists and the public ones

The same day, a pass over the whole app as an outside tester would make it, against the test rig's Navidrome 0.64.2 and Jellyfin 12.1.0, two accounts each. Found and fixed with it: an account's first visit of the day, before it had played anything, kept an empty set of daily mixes for the rest of the day; and Jellyfin's playlists were asked whose they are twice per playlist each time the add-to-playlist list opened (held ten minutes now). Looked at and found holding:

  • next after sign-in, in twelve forms (//host, /\host, encoded slashes and backslashes, a tab, javascript:, CR and LF, a full-width dot): every one lands on a path of this site.
  • The origin check against null, a trailing slash, a capital scheme, a missing port and a suffixed host; a form action posted as text/plain from another site; x-heddohon-host and x-heddohon-protocol, X-Forwarded-* and Host sent by the client on a deployment with a saved address. All refused.
  • Ids with ../, &u=, CR and LF, and 300 characters on the stream, cover, download and lyrics routes: passed to the music server as one encoded value, or refused. An answer that is not audio or an image (Navidrome's error, which names its version) is sent as application/octet-stream with nosniff and the sandbox, to the signed-in account alone.
  • One Navidrome account against another's private playlist (read, add, make public, delete, link), link, session handle, MCP token and library report; the same on Jellyfin against a public playlist. Each refused, and none signs the account out. Jellyfin 12.1.0 itself names another user's private playlist to /Items?Ids=; Heddohon reads a playlist's tracks through /Playlists/{id}/Items, which refuses, so neither the page nor a link opens it.
  • Radio addresses as ::ffff:7f00:1, 0:0:0:0:0:ffff:a00:1, ::ffff:a9fe:a9fe, 0x7f.1, 2130706433, 127.1, :: and fd00::1: each taken for private. The connection is made to the address checked.
  • A cast address after its session signs out: 404. The hardening headers on media, /api/mcp, /healthz and JSON answers; no Server or X-Powered-By.

Reported by the maintainer later the same day, with a check each in tests/e2e/app.test.mjs:

Severity Finding Fix
Medium Anyone with a listen-together link could lock everyone out of it, the host included. The 50-listener cap was checked before who was connecting, and /together/<token>/events is public: one visitor holding 50 streams open was refused to every listener and member, and to the host's own browser after its next reload, until the party ended. The host's removal works per account, and the visitor had none The host's browser is always let in. A signed-in account holds up to four streams and is not counted in the 50, which are for visitors without an account, four per address where the address tells visitors apart. What remains is under Known gaps
Low A reaction was accepted for any listener id, and every reaction showed its sender's id to the whole party: anyone in it could react as another listener and spend that listener's one a second The id is sent to the listener's own page alone; the party is shown a separate tag, which a reaction is not accepted with

Asked about at the same time and found holding: a radio station's redirect. Redirects are followed by hand, at most three, and every hop, a playlist's entry included, goes through the same address check as the station's own address. The connection's DNS lookup is the guarded one, so the address checked is the address connected to, and a hop served from a public address leads only to public ones.

Raised by the maintainer on the fix above, and handled the same day:

Severity Finding Fix
Low Behind a proxy on a public address without ADDRESS_HEADER, every visitor had the proxy's address. The listen-together count would have let four visitors into every party, and the sign-in backstop already counted every visitor's failures together, 60 in 15 minutes for the whole deployment. A loopback or private proxy address was already left out First counted by no address when a forwarding header came without ADDRESS_HEADER, which the audit below undid: it fails closed now, and the log says address-header-unset. ADDRESS_HEADER and XFF_DEPTH are item 13 of the operator checklist, with what a header the client controls does
Info IPv6 visitors could take a fresh address for each stream Already counted by /64, as the sign-in throttle is; now checked for the listen-together count too

A review of every request header the server reads, the same day, at the maintainer's request. Each use was traced to what it decides:

Severity Finding Fix
Medium Introduced the same day and fixed before a release: a request carrying X-Forwarded-For, Forwarded or X-Real-IP without ADDRESS_HEADER set was counted by no address. A client reaching the server directly could send one and leave the sign-in backstop per address, which is what stops one password tried against many usernames, and the listen-together count per address The headers' presence changes no count. The connection's address is counted as before, failing closed behind an unconfigured public proxy, and the log says address-header-unset once

Found holding:

  • Origin on every write (hooks.server.ts), compared with the address the request is served on, and on /api/mcp where one is sent. A DNS rebinding page on plain http is served as https:// its own host, which its Origin never matches.
  • The saved addresses (savedOrigin): x-heddohon-host and x-heddohon-protocol from a client are deleted before the adapter reads them, and are only set for a Host that is exactly a saved host, to that saved address. A forged Host changes the address of the forger's own request alone: the cookie name and Secure it is answered with, never a check against another site. With ORIGIN set, the two headers carry ORIGIN on every request, whatever a client sent. With HOST_HEADER or PROTOCOL_HEADER set and no ORIGIN, the two headers are read by nothing.
  • Authorization on /api/mcp (an HMAC digest looked up) and on /api/plugin/navidrome (compared in constant time).
  • Range, If-None-Match and If-Modified-Since, passed to the music server as sent (a header value cannot carry a line break) or compared with an ETag; the range this server serves itself is parsed strictly, and a malformed one is ignored.
  • Content-Length on the avatar upload, checked again against the body read, under adapter-node's 512 KB body limit.
  • User-Agent: a device label shown to the account's own browsers as text, and on a shared link whether x-robots-tag: noindex is sent.
  • Host and Origin in the address form under Settings: a guard against saving a list without the address the administrator is on, after the write has passed the origin check.
  • ADDRESS_HEADER set and missing from a request (a visit that did not come through the proxy): adapter-node answers 500 for the sign-in and the listen-together stream; the operator checklist says to set it only where every request comes through the proxy.

16 October 2026

Asked by the maintainer: is a profile picture kept without its metadata, and can a display name run as markup? Each with a check, in tests/e2e/app.test.mjs (a picture is kept without its metadata) and tests/browser/panel-and-remote.test.mjs (an account that chooses to be shown).

Severity Finding Fix
Low A picture sent to PUT /api/profile/avatar by hand, rather than through Settings, was stored and served as sent: EXIF with a phone's GPS position and serial number, XMP, comments, JFIF's thumbnail, and up to 96 KB of anything after the end marker, to every account it was shown to. The browser's own picture is drawn again on a canvas and had none of these (checked in Chromium, WebKit and Firefox) Every segment is walked, the scans included, and only what draws the picture is kept: the tables, the frame, the scans, the ICC colour profile and Adobe's colour transform. The size check is made on what is kept

Found holding: a display name of <img src=x onerror=alert(1)> is shown as that text in the pill's label and in the popup, and no element is made from it; the source has no {@html} or innerHTML, and the page's policy has no 'unsafe-inline' for scripts besides. A user name from the music server (the listen-together queue's "Added by", the Join button) goes through the same escaping.

20 October 2026

The second factor (issue #225), reviewed as it was written. Each item with a check in tests/e2e/twofactor.test.mjs; four of the checks were undone in the code on purpose and failed as they should (the replay check, user verification for a passkey alone, the account stored before the factor, and the Settings actions open to an account without one).

Severity Finding Fix
Medium Every Settings action was open to an account held to setting up a factor, and makeMcpToken there gave it a token that reads the library past the gate Only save, endSession and endOtherSessions are taken from it, and its MCP tokens open nothing while it has no factor
Low A held sign-in and a WebAuthn challenge were rows without a cap for whoever had the password, or a signed-in session: each lasted 5 minutes, and a correct password clears the sign-in throttle 10 held sign-ins an account, the newest kept; one live challenge per held sign-in and per account and purpose

Found holding: a passkey answer for another origin, another relying party, a spent challenge, a counter that went back, a forged signature, another account's user handle, and a sign-in challenge sent as a second step, are each refused; a TOTP code is taken once when sent twice at the same moment (one conditional update); recovery codes and the secret are not in the database in the clear; and the held sign-in holds the password sealed.

There aren't any published security advisories