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.
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.
- 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.
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)).
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 nameshost:port/database, and configuration errors name the variable without its value. - Transport. TLS follows the URL's
sslmodeorHEDDOHON_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
heddohonschema, set as the search path at connection start-up. In the defaultpublicschema of a shared database,CREATE TABLE IF NOT EXISTSwould have adopted another application'saccountsorsettingstable. - Unencrypted connections are reported once at start-up as
database-unencrypted, frompg_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.
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".
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_URLwith 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 atdebug, 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
Authorizationheader of a request toHEDDOHON_LISTENBRAINZ_URLand nowhere else, with redirects refused. That address is the operator's: anhttp://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_mentionsis 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-failedand do not hold up or fail the play.
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.jsonfor 24 hours, refreshed withIf-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.
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-Agentnaming 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 asnew-releases-failed. - Text only. Titles are cut to 300 characters and rendered as text.
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=trueallows them, for a stream served on the local network. - Redirects are followed up to three times, each hop held to the same
rules. An
.m3uor.plsplaylist 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/*orapplication/oggis 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: nosniffas on every response. A station's own page is linked only if it is an http or https address, in a new tab withrel="noopener noreferrer". - Failures are logged as
radio-failedwith 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.
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 (songsByIdsinnavidrome.ts): 1000 saved tracks cost one sign-in and 10 requests instead of 1000getSongcalls. 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/lastfmwith its token, beside Navidrome's signed link token (uid, valid 5 minutes, naming the Navidrome user) and astatethat is an HMAC, under its own key, of the Heddohon account and the link token. The route is behind the session gate and refuses astatethat 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 isSameSite=Lax, which a top-level navigation from last.fm carries. - Kept out of the log.
token,uidandstateare removed from logged paths and queries byredact, including insidenextwhen 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-failedin the log), not as an error elsewhere.
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
checkRulesinsrc/lib/smartrules.tsholds 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.nspfile 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 (
409from/api/playlists/[id]/tracks, an error from the MCP tools, andreadOnlyin their listing): Jellyfin would take it, and the next evaluation would put the songs back.
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 ofHEDDOHON_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
Originwith 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.
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 ishhmcp_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. AnOriginthat 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 theAuthorizationheader or theapplication/jsonbody 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/%6Dcpgoes 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 (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 inaccounts. 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.tsis the only reader of the sealed value, and hands out anAnalysisSource: 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 (
getUseron Subsonic,Policyon 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.
- 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_SECRETand a salt of the install's own: 32 random bytes incrypto-saltin the data directory, made on the first start whose database holds no account, written 0600, never regenerated, and packed into a database backup besideheddohon.db. The database records which salt sealed it (a row inmetaholding a SHA-256 of the salt, orconstant), 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/healthzreportsmisconfigureduntil the rightcrypto-saltis 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_SECRETmakes 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.
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_NAMESinconfig.ts. The third-party addresses,HEDDOHON_RADIO_PRIVATEand 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 insetup.jsonwith the secret, andHEDDOHON_DATABASE_PASSWORDin the environment keeps it out. - The probe. It sends one unauthenticated request (
pingfor Subsonic,/System/Info/Publicfor 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
Origincheck under Cross-origin writes: that check needsORIGIN, which a deployment being set up behind a proxy has not been given. It acceptsapplication/jsonalone, 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.jsonin 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.jsonthat 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.
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-madeatwarn, 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.
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.
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.
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.
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.
/shareis a public route. The session gate does not apply under it. A path that leaves/shareafter 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 orimage/*for the cover is refused with a 404 instead of being relayed as a download. A Subsonic server answersstream.viewwith 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, withprivate, no-storeon audio andprivate, max-age=300on 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 saysnoindex./robots.txtallows/share/and nothing else, so a search engine that finds a link can read the page and itsnoindex. - 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%E0in 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-storeandx-robots-tag: noindex, nofollow.referrer-policy: same-originkeeps the path out of theRefererheader for any other origin, and the page's one external link carriesrel="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.
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 (
redactinlog.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-originandAccess-Control-Allow-Origin: *. It is sent without credentials, and the token in the path is the whole of the authority. Every other response keepssame-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.
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);
/peoplelists 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):f0tof3for the albums,r0tor7for 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,Listenerwhere 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, withnoindex, without the handle and without links into the library. Its covers carryprivate, 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_LISTENERSis 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.
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). WithoutHEDDOHON_REMOTE_CONTROLthere 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.
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_SHARINGandHEDDOHON_REMOTE_CONTROLon. With either off, every/togetherroute 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 inADDRESS_HEADER. A forwarding header thatADDRESS_HEADERdoes not name is never read, and its presence changes nothing, since anyone can send one. Behind a proxy withoutADDRESS_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 saysaddress-header-unsetonce when a request with a forwarding header arrives withoutADDRESS_HEADER, andtogether-one-addressonce when five or more visitors of one party arrive from one uncounted address. WithADDRESS_HEADERset to a header the proxy appends to rather than overwrites, orXFF_DEPTHset 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.
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>/joinneeds 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
/togetherroute 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.
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_LISTENERSandHEDDOHON_REMOTE_CONTROLon. With either off,/api/profileand 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 00among 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>asimage/jpeg, withnosniffandContent-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.
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/settingsreached/api/settingswithout matching the prefix. - A missing
Originis 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
Hostis 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 setsORIGIN,PROTOCOL_HEADERorHOST_HEADER, the saved list is not used. ORIGINin the environment is every request's address, whatever itsHost, given to the adapter in the same two headers. adapter-node 5 readORIGINitself; 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 keepORIGINexactly as before: every request is pinned to it, so the origin check comparesOriginwith the same address. AnORIGINthat 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'sHostand its ownOrigin. - 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.
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,
aliceon Navidrome andaliceon 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_devicecookie (__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.
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 beimage/*and streamsaudio/*. Anything else is sent asapplication/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-Dispositionis 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 (rangeIgnoredinproxy.ts).
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.
/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.
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,inlinedisposition, 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 atHEDDOHON_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, ordestroyAllSessionsfor 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-Sitedecides:same-origin,none(a typed or bookmarked navigation) and a request without the header are kept;cross-siteandsame-siteare not. The cookie isSameSite=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 themetatable 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=0to disable it.
- 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 throughencodeURIComponentplus a guard against.., whichencodeURIComponentleaves 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,evalornew Function. All music server strings render as escaped text, and everyhrefandsrcis 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
modequery parameter only makes the original and transcoded streams distinct URLs for the browser cache.
| 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 |
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.
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.
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.
Open issues
-
style-src-attrallowsunsafe-inline. The page shell and the components that size themselves in markup emitstyleattributes, 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_SECRETmakes 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 forrecovery_codesandpasskeys. -
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 withoutADDRESS_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
/appis writable by thenodeuser.
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_HEADERandXFF_DEPTH, and only if the proxy overwrites that header. /healthzis 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
/healthzas a build id. It tells a visitor which release is running. /manifest.webmanifestis unauthenticated, since browsers fetch it without cookies. It returnsHEDDOHON_APP_NAME, fixed colours, icon paths and three shortcut paths./.well-known/assetlinks.jsonis 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 inHEDDOHON_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=devunder-reports. SvelteKit is a devDependency bundled intobuild/, 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.
The same steps in the order to do them, with less of the reasoning, are in SETUP.md.
- Generate a secret with
openssl rand -base64 48(32 characters minimum). Changing it signs everyone out. - Set
ORIGINto your publichttps://URL. A wrong value fails closed and breaks writes. - Terminate TLS at the proxy. HSTS is always sent.
- Keep the music server private. Only Heddohon needs to reach it.
- 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(orrequireon a trusted network) when the server is not on the same host. - Rate limit and restrict
/healthzat the proxy. The offline page does not depend on it. - Rebuild to update. Dependencies are pinned by range and the base image is a floating tag.
- Publish the port on loopback behind a proxy (
127.0.0.1:3000:3000). Docker's port rules pass host firewalls such as ufw. - For the Navidrome plugin, a token of its own:
openssl rand -hex 32, inHEDDOHON_NAVIDROME_PLUGIN_TOKENand in the plugin's settings, and anhttps://address for the plugin where Navidrome is on another network. Leave the variable unset where the plugin is not installed. - 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_SECRETit was made under, which is not in it. - After a first-run setup, move the secret to the environment. The
setup saves it in
setup.jsonin the data directory, where a copy of that directory is enough to read the stored credentials. SetHEDDOHON_SECRETto the value the last step shows, remove it from the file, and restart. Where every value is set in the environment,HEDDOHON_SETUP=falsekeeps the setup page from being served if one is ever left out. - 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_MCPis set in the environment; set it tofalsethere to keep it off. Behind a proxy that restricts paths,/api/mcptakesPOST, andGETandDELETEanswer 405. - Behind a proxy, tell adapter-node where the visitor's address is.
Set
ADDRESS_HEADERto a header the proxy sets itself (X-Real-IPfrom nginx, orX-Forwarded-ForwithXFF_DEPTHset 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 saysaddress-header-unseteither way. Set to a header the client controls, a visitor names any address and both counts stop applying to them. The same goes forHOST_HEADERandPROTOCOL_HEADER: leave them unset unless the proxy overwrites them, and setORIGINinstead where the address is fixed. SetADDRESS_HEADERonly where every request comes through the proxy: adapter-node answers 500 to a request without it, and to one carrying fewerX-Forwarded-Forentries thanXFF_DEPTH. - Let Heddohon's security headers through the proxy. A proxy that sets
Content-Security-Policy,Referrer-Policy,Cross-Origin-Resource-PolicyorPermissions-Policyon every site replaces Heddohon's: the nonce-based script policy,same-originreferrers and the sandbox on media. Attach such a header set to the sites that need it rather than to every site. - 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.
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.
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.
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.
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.
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.
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.
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.
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.
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 |
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 |
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.
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:
nextafter 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 astext/plainfrom another site;x-heddohon-hostandx-heddohon-protocol,X-Forwarded-*andHostsent 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 asapplication/octet-streamwithnosniffand 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,::andfd00::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,/healthzand JSON answers; noServerorX-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:
Originon every write (hooks.server.ts), compared with the address the request is served on, and on/api/mcpwhere one is sent. A DNS rebinding page on plain http is served ashttps://its own host, which itsOriginnever matches.- The saved addresses (
savedOrigin):x-heddohon-hostandx-heddohon-protocolfrom a client are deleted before the adapter reads them, and are only set for aHostthat is exactly a saved host, to that saved address. A forgedHostchanges the address of the forger's own request alone: the cookie name andSecureit is answered with, never a check against another site. WithORIGINset, the two headers carryORIGINon every request, whatever a client sent. WithHOST_HEADERorPROTOCOL_HEADERset and noORIGIN, the two headers are read by nothing. Authorizationon/api/mcp(an HMAC digest looked up) and on/api/plugin/navidrome(compared in constant time).Range,If-None-MatchandIf-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-Lengthon 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 whetherx-robots-tag: noindexis sent.HostandOriginin 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_HEADERset 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.
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.
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.