Document the session token in the fragment, the /api/tokens endpoint, and the print spool and paper

[ehfd]

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, and it reads no PAPERSIZE.

• Needs, all in the release after 2.0.0:
  • selkies-project/selkies@44f4832, which takes the session token from the URL fragment;
  • selkies-project/selkies@f3f7df5, the print spool's default under XDG_STATE_HOME;
  • selkies-project/selkies@d3c14d5, the printer's default paper from PAPERSIZE.

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.

The printing table:

• SELKIES_PRINT_SPOOL_PATH's default is now empty, which resolves to selkies/print under XDG_STATE_HOME, else under ~/.local/state. The images set no XDG_STATE_HOME and HOME=/config, so their spool stays at /config/.local/state/selkies/print.
• PAPERSIZE sets the default paper of the Selkies printer, for a document that names no size of its own: one of the sizes its PPD offers, matched ignoring case. Unset, or a size it does not offer, keeps A4.

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.
• The printing rows, in lscr.io/linuxserver/webtop:ubuntu-kde run with -e PAPERSIZE=letter: the Selkies process (/lsiopy/bin/selkies, user abc, through the service's with-contenv) carries PAPERSIZE=letter and HOME=/config and no XDG_STATE_HOME, and its spool is /config/.local/state/selkies/print. The queue's handling of PAPERSIZE is the release's, covered by its own tests (Letter at 612x792 through lp, A4 at 595x842 without it).
• mkdocs build --strict again after rebasing on main (with docs/requirements.txt and d2 0.9.0): no warnings or errors.
• Not run: an image built with the release this waits for.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.