Login state injection (lws-login)

Collaboration diagram for Login state injection (lws-login):

Macros
#define	LWS_LOGIN_HDR_STATE   "x-lws-login-state"
#define	LWS_LOGIN_HDR_ADMIN   "x-lws-login-admin"
#define	LWS_LOGIN_HDR_GRANT_LEVEL   "x-lws-login-grant-level"
#define	LWS_LOGIN_HDR_SUB   "x-lws-login-sub"

Enumerations
enum	lws_login_state {   LWS_LOGIN_STATE_ANON = 0 , LWS_LOGIN_STATE_NO_GRANT = 1 , LWS_LOGIN_STATE_USER = 2 , LWS_LOGIN_STATE_APP_ADMIN = 3 ,   LWS_LOGIN_STATE_GLOBAL_ADMIN = 4 }

Detailed Description

Login state injection

When a mount is guarded by the lws-login bouncer plugin, the bouncer authenticates the request, decides the requestor's role from the verified JWT grants, and stamps the cooked, trusted result onto the browser-side wsi as "extra onward headers" (set with lws_http_add_onward_header() after lws_http_zap_header() anti-spoofs any client-supplied copy). The HTTP/WS proxy paths then forward these to the backend app behind the mount, so the app does no JWT/grant work of its own – it just reads the headers.

The authoritative summary is the single header LWS_LOGIN_HDR_STATE, whose value is the stringified lws_login_state. The finer-grained LWS_LOGIN_HDR_GRANT_LEVEL (the raw integer grant level the bouncer used to decide the role for this mount) and LWS_LOGIN_HDR_SUB (the subject identity) are also injected for apps that want the detail. LWS_LOGIN_HDR_ADMIN is kept for back-compat and is exactly equivalent to state == LWS_LOGIN_STATE_GLOBAL_ADMIN.

Crucially, LWS_LOGIN_STATE_APP_ADMIN (admin of THIS app only) and LWS_LOGIN_STATE_GLOBAL_ADMIN (the TOFU "*" / "god" account, admin of the whole system) are distinct: a backend must not treat an app admin as a system-wide admin. The states are strictly ordered by privilege, so state >= LWS_LOGIN_STATE_APP_ADMIN selects "any kind of admin" and state == LWS_LOGIN_STATE_GLOBAL_ADMIN selects "system-wide only".

These headers are only trustworthy when they reach the backend through the bouncer's proxy path: the bouncer zaps any client-supplied copy first. A backend reachable directly (bypassing the mount) must not trust them.

Macro Definition Documentation

LWS_LOGIN_HDR_STATE

#define LWS_LOGIN_HDR_STATE   "x-lws-login-state"

#include <lws-http.h>

Definition at line 704 of file lws-http.h.

LWS_LOGIN_HDR_ADMIN

#define LWS_LOGIN_HDR_ADMIN   "x-lws-login-admin"

#include <lws-http.h>

Definition at line 705 of file lws-http.h.

LWS_LOGIN_HDR_GRANT_LEVEL

#define LWS_LOGIN_HDR_GRANT_LEVEL   "x-lws-login-grant-level"

#include <lws-http.h>

Definition at line 706 of file lws-http.h.

LWS_LOGIN_HDR_SUB

#define LWS_LOGIN_HDR_SUB   "x-lws-login-sub"

#include <lws-http.h>

Definition at line 707 of file lws-http.h.

Enumeration Type Documentation

lws_login_state

enum lws_login_state

#include <lws-http.h>

enum lws_login_state - summary role of the identity reaching a backend

Value of LWS_LOGIN_HDR_STATE as injected by the lws-login bouncer into backend apps behind a protected mount. Members are ordered by privilege; higher == strictly more authority.

Enumerator
LWS_LOGIN_STATE_ANON	No valid JWT. Only observable on mounts with unauth-allow=1.
LWS_LOGIN_STATE_NO_GRANT	Valid JWT, but no grant (and no "*" wildcard) for this service.
LWS_LOGIN_STATE_USER	Holds this service's grant at level >= 1 but < 2, no "*".
LWS_LOGIN_STATE_APP_ADMIN	Holds this service's grant at level >= 2, no "*": admin of THIS app only, NOT a system-wide admin.
LWS_LOGIN_STATE_GLOBAL_ADMIN	Holds the "*" wildcard grant (the TOFU "god" account): admin of the whole system. Any "*" level >= 1 qualifies.

Definition at line 716 of file lws-http.h.

                     {
        LWS_LOGIN_STATE_ANON = 0,
        LWS_LOGIN_STATE_NO_GRANT = 1,
        LWS_LOGIN_STATE_USER = 2,
        LWS_LOGIN_STATE_APP_ADMIN = 3,
        LWS_LOGIN_STATE_GLOBAL_ADMIN = 4,
};