Module auth 

Stage 4 authentication + RBAC.

Two principal kinds carry a role: interactive users (password login → opaque bearer session) and machine API keys (worker ingest + external integration). Tokens are random 256-bit values; only their SHA-256 is stored, so a database leak does not expose usable credentials. Passwords are argon2id PHC hashes.

The Principal extractor resolves the caller from the Authorization: Bearer (or X-API-Key) header. When auth_enabled is false (the default single-tenant LAN appliance mode) it yields a synthetic admin so the existing open API and tooling keep working; when true it requires a valid token and 401s otherwise. Handlers then assert capabilities with Principal::require.

Structs

Principal

The resolved caller for a request.

Enums

PrincipalKind

Role

Constants

APIKEY_PREFIX

SESSION_COOKIE

Name of the HttpOnly session cookie set on login.

SESSION_PREFIX

Functions

audit

Append an immutable audit-log entry (best-effort; never fails the caller).

clear_session_cookie

Build the Set-Cookie value that clears the session cookie (logout).

dummy_password_hash

A throwaway argon2id hash used to equalize login timing for unknown/disabled users (so the presence of an account cannot be inferred from response latency). Computed once, lazily.

ensure_bootstrap

First-run bootstrap: when auth is enabled and no users exist yet, seed an admin from env.

hash_password

hex_encode

issue_session

Issue a login session for a user, returning the bearer token (shown once) and its expiry.

random_token

Generate a prefixed 256-bit random token (the full secret returned to the caller once).

revoke_session

Revoke a session by its bearer token (idempotent).

session_cookie

Build the Set-Cookie value that stores a session token in an HttpOnly, SameSite=Strict cookie. HttpOnly keeps it unreadable to JS (no XSS exfiltration); SameSite=Strict blocks CSRF; the SPA is same-origin with the API so the cookie still reaches the media plane (<img>/<video>/HLS).

token_from_headers

Extract the bearer token from Authorization: Bearer <t> or the X-API-Key header.

token_hash

SHA-256 hex of a token string — the at-rest representation of sessions / API keys.

verify_password