Cookies, sessions, and CSRF

A browser session for WebSocket can begin with an HTTP login and cookie flow. Lily's connection points are normalized Upgrade headers and identity middleware. Do not assume ready-made equivalents of HTTP cookie or CSRF builder APIs exist here.

Session flow#

1. Configure login, session storage, and cookie creation in your HTTP application.
2. The browser sends an Upgrade request according to its cookie rules.
3. Identity middleware passes the Cookie header to your application's cookie/session verifier.
4. The verifier produces a valid Principal, owned tenant information, and expiry if needed.
5. Message guards enforce scopes, roles, and object permissions for each operation.

The HTTP side of cookies is covered in cookies, and the session model in authorization and sessions. These configure the separate HTTP application; a WebSocket session does not automatically attach to the same state.

Read the cookie#

Access the header inside the identity callback:

let cookie_header = exchange.request().headers()
    .get_custom_header("cookie");

This value is raw header text. Select the cookie using a trusted cookie parser and session store; reject missing, expired, or revoked sessions before 101. Do not treat a subject obtained by simple string splitting as a verified Principal. Adapt the verifier interface in the authentication example to the session result.

The browser WebSocket constructor has no arbitrary-header option. Whether cookies are sent depends on browser cookie and access rules; the opening handshake standard defines this flow. This API has no hook for adding arbitrary Set-Cookie headers to a successful 101 response; create/renew sessions through HTTP.

Cross-site access policy#

An exact Origin allow-list, session verification, and an additional handshake/session-binding policy when your application requires one work together. Origin does not replace authentication. Adding a csrf_token field to a DTO does not itself provide verification or cross-site protection either.

This version has no built-in WS-CSRF middleware/store API. Do not copy the HTTP CsrfService/CsrfGuard example into the WS builder. Explicitly define which sessions can open which connections, session revocation, and renewal in your application protocol.

Long-lived connections#

Renewing an HTTP session does not automatically change an open socket's Principal. After verifying new credentials, use revision-checked refresh. Expiry and revocation are separate events; your verifier/store policy tracks revocation state.

A general-purpose query accessor or credentials hidden in a subprotocol name are not authentication paths supplied by this crate. Build the browser example with a session flow and the service client with explicit Authorization-header verification.