Skip to content

Document the session token in the fragment and the /api/tokens endpoint - #48

Draft
ehfd wants to merge 1 commit into
linuxserver:mainfrom
ehfd:selkies-token-fragment
Draft

ehfd wants to merge 1 commit into
linuxserver:mainfrom
ehfd:selkies-token-fragment

Conversation

@ehfd

@ehfd ehfd commented Sep 28, 2026 •

Copy link
Copy Markdown

Do not merge until a Selkies release after 2.0.0 is out and in the images. Selkies 2.0.0 reads the session token only from the query, so the fragment token these pages describe does not work on the current images.

The Selkies pages describe the session token in the fragment, #token=<token> (#display2-right&token=<token> after a display fragment), beside ?token=. A fragment never reaches a request line: the client offers the token on the data WebSocket as the subprotocol selkies.token.<base64url> beside selkies, which the server selects and the image's Nginx passes through.

The rest already holds for 2.0.0 and the v2 images:

  • Tokens are registered with POST /api/tokens and the master token (Authorization, or Selkies-Authorization beside a Basic login), on the Selkies port behind Nginx; the pages name that API where they had the 8083 control port.
  • The data WebSocket is at <subfolder>api/websockets.
  • The Nginx layout table lists the api location of the v2 branches' default.conf (master, ubunturesolute, fedora44, arch, kali, alpine324, dev) in place of the v1 branches' websocket and files locations, and notes that api takes request bodies of any size, unbuffered.

Tested:

  • mkdocs build --strict with docs/requirements.txt: no warnings or errors, as on main.
  • Selkies main (3291323) behind the port 3000 server block of the baseimage's root/defaults/default.conf (master), with its placeholders filled as init-nginx fills them, in nginx 1.31.6: in Chrome, Firefox, and WebKit, /#token= streams, the file listing is served on the cookie alone, the socket request is GET /api/websockets offering selkies, selkies.token.* and answered 101 with selkies, and no request line or Referer that nginx logged carries the token. POST /api/tokens through nginx answers 200. The same holds under a subfolder with the block's auth_basic lines enabled, as PASSWORD enables them, behind a proxy that sets the container's Basic login on every request, as SealSkin's Caddy does. ?token= streams as before.
  • In ghcr.io/linuxserver/webtop:ubuntu-kde itself, running Selkies main (1251515) through the image's dev mode (DEV_MODE=selkies-dashboard), and again with main's built dashboard and package mounted over 2.0.0's: in Chrome 154, Firefox 156, and WebKit, /#token= streams the KDE desktop, the file listing is served on the cookie alone, the socket request is GET /api/websockets with no query, and no line of the image's nginx access log or of the container's log carries the token. The same holds with PASSWORD set, behind a proxy that sets the container's Basic login on every request. ?token= streams as before.
  • Not run: an image built with the release this waits for.

…i/tokens endpoint

Selkies after 2.0.0 takes the session token from the URL fragment as
well as the query, and offers a fragment token on the data WebSocket
as the subprotocol selkies.token.<base64url> beside selkies, so it
never reaches a request line. Selkies 2.0.0 already serves the token
table on its own port at /api/tokens and has no 8083 control port,
and the v2 images' Nginx hands Selkies everything under api/ through
one location, where the pages still had the websocket and files
locations of the v1 images.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

2 participants