Skip to content
CommonLayer
Documentation menu
On this page

ADR-0008: Server-side sessions, hashed tokens, JWTs only for the registry

Status: Accepted (plan decision D8). Implemented in crates/commonlayer-auth.

Context

The portal needs browser authentication with instant revocation (suspension, password reset, "log out everywhere"). Tokens held in browser-readable storage are exposed to any script injection.

Decision

  • Browser sessions are opaque random tokens (32 bytes) in a __Host-cl_session cookie (Secure, HttpOnly, SameSite=Lax, Path=/); only the SHA-256 is stored. Idle timeout 14 days, absolute 90 days, rotation on login and privilege change.
  • CSRF protection is double-submit: a readable cl_csrf cookie derived from the session's secret must be echoed in X-CSRF-Token on unsafe methods, and Origin or Referer must be on the allowlist. Bearer-token requests and signature-verified webhooks are exempt.
  • API tokens are clt_<8 hex>_<secret>, stored as SHA-256, shown once.
  • JWTs are used only for registry tokens (ES256, 5 minutes), because the Docker token-auth protocol requires them.

Consequences

  • Revocation is immediate: deleting or marking a session revoked takes effect on the next request; suspended users' sessions and tokens stop working.
  • One database lookup per authenticated request (session or token plus grants).
  • A development-only relaxation allows a non-__Host- cookie without Secure when the API's public URL is a loopback host; configuration refuses it elsewhere (WP-02).