lib/session-token

Secure-mode session token, shared by both transports and the dashboard.

The token arrives in the page URL, in one of two places:

• the fragment, as a token= item beside the keyword that picks the display or the sharing role (#token=<t>, #display2-right&token=<t>). A browser never sends a fragment, so neither the page load nor a proxy in front of it records the token, and a token that arrives here is kept out of every URL the client requests afterwards as well;
• the query (?token=<t>), which is in the page's request line already, so the requests that follow it carry it the same way. A page with both uses the fragment's. In secure mode the WebSocket handshakes and every other /api/ route want the token, so every caller presents it through one of these:
• scripts put Authorization: Bearer <token> on their fetch/XHR calls (sessionAuthHeaders); the server accepts it beside Basic auth too, since a script's header replaces the browser's cached Basic credentials;
• the data socket offers a fragment token as a WebSocket subprotocol (sessionTokenProtocols) and a query token as ?token= on its URL, and the WebRTC signaling socket sends either in its hello message;
• URLs the browser navigates to rather than fetches, such as the file-manager listing the dashboards open in an iframe, carry a query token as ?token= (withSessionToken), and the listing keeps it on its own links, which is what serves a page embedded cross-site, where the cookie cannot follow; a fragment token leaves them to the cookie;
• a same-site cookie scoped to the API prefix (installSessionCookie) covers anything the browser requests on its own, such as a download link or a listing opened by hand. It is a session cookie, so closing the browser clears it, and the next page load with a token overwrites it. The fragment's keyword and the links other pages take are page-url.js's. A server outside secure mode ignores every carrier.

VariablesCopy Anchor Link

SESSION_TOKEN_COOKIECopy Anchor Link

const SESSION_TOKEN_COOKIE: "selkies_token" = 'selkies_token';

Defined in: lib/session-token.js:44

Name of the API-scoped session cookie.

SESSION_TOKEN_PROTOCOLCopy Anchor Link

const SESSION_TOKEN_PROTOCOL: "selkies" = 'selkies';

Defined in: lib/session-token.js:50

Subprotocol a handshake presenting its token offers first, and the one the server selects: the token rides a second subprotocol, never echoed back.

SESSION_TOKEN_PROTOCOL_PREFIXCopy Anchor Link

const SESSION_TOKEN_PROTOCOL_PREFIX: "selkies.token." = 'selkies.token.';

Defined in: lib/session-token.js:53

Prefix of the subprotocol that carries the token, base64url without padding.

FunctionsCopy Anchor Link

sessionTokenInFragment()Copy Anchor Link

function sessionTokenInFragment(): boolean;

Defined in: lib/session-token.js:60

Whether the page's session token came in the fragment, which keeps it out of every URL the client requests.

ReturnsCopy Anchor Link

boolean

getSessionToken()Copy Anchor Link

function getSessionToken(): string;

Defined in: lib/session-token.js:70

Reads the session token from the page URL: the fragment's token= item, or else the ?token= query parameter.

ReturnsCopy Anchor Link

string

The token, or '' when the page has none (legacy mode, or a context without a location).

sessionAuthHeaders()Copy Anchor Link

function sessionAuthHeaders(headers?): Record<string, string>;

Defined in: lib/session-token.js:87

Request headers with the Bearer token added when the page holds one.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Record<string, string>

A plain header object.

withSessionToken()Copy Anchor Link

function withSessionToken(url): string;

Defined in: lib/session-token.js:105

A same-origin URL with a query token appended as ?token=, for URLs the browser navigates to (an iframe src, a link) rather than fetches. A token that came in the fragment is left to the cookie, so no request line ever carries it.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string

The URL as given without a query token, else resolved and tokened.

base64url()Copy Anchor Link

function base64url(text): string;

Defined in: lib/session-token.js:124

base64url of a string's UTF-8 bytes, without padding, which keeps any token inside the characters a subprotocol name allows.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string

sessionTokenProtocols()Copy Anchor Link

function sessionTokenProtocols(): string[];

Defined in: lib/session-token.js:138

The subprotocols the data socket offers so that its handshake carries a fragment token without a URL: selkies, which the server selects, then the token behind selkies.token., which the server reads and never echoes. A query token rides the socket URL instead, so a page opened with one depends on nothing new from a proxy in front.

ReturnsCopy Anchor Link

string[]

The two subprotocols, or none without a fragment token.

installSessionCookie()Copy Anchor Link

function installSessionCookie(): void;

Defined in: lib/session-token.js:152

Mirrors the page's token into the API-scoped session cookie.

Called once by each core at load. A page without a token leaves any existing cookie alone, since another tab may still be using it; a cookie write the browser blocks leaves the other carriers, which is why this is best-effort.

ReturnsCopy Anchor Link

void