Module cookie_session 

Encrypted client-side session cookies.

The primitive that lets stateless SSO plugins (openid-connect, cas-auth, authz-casdoor) run interactive login flows without any server-side session store: the session payload (tokens, claims, or the transient auth-flow state) is sealed into an authenticated, encrypted cookie with an embedded expiry. Any gateway instance sharing the signing secret can open any cookie, so this works across a horizontally-scaled deployment with no coordination.

Sealing uses AES-256-GCM (via ring) with a per-message random nonce; the 256-bit key is derived from the configured secret by SHA-256, so a secret of any length is accepted. The expiry is part of the authenticated plaintext, so it cannot be tampered with.

Trade-offs inherent to client-side sessions (shared with APISIX’s default cookie sessions): there is no cheap server-side revocation before expiry (use short lifetimes), and cookies are capped near 4 KB, so only essential data should be stored.

Structs

CookieAttrs

Attributes for building a Set-Cookie header value.

CookieSealer

Seals and opens encrypted session cookies with a fixed derived key.

Enums

CookieError

Failure opening a sealed cookie. Every variant means “treat the request as unauthenticated” — callers should never distinguish these to a client.

SameSite

SameSite attribute for a Set-Cookie header.

Functions

build_set_cookie

Builds a Set-Cookie header value for name=value with attrs.

delete_cookie

A Max-Age=0 deletion cookie for name.

now_unix 🔒

path_covers

Whether a cookie scoped to cookie_path is sent by the browser on a request to request_path (RFC 6265 §5.1.4 path-match): an exact match, or cookie_path is a prefix ending at a / boundary. / (or empty) covers everything.

read_cookie

Reads a named cookie from a Cookie header value (a=1; b=2).