Module operator 

The operator (kernel spec §3): the one owner, their password, the public_url setting, and the one-time setup link that sets them up.

• One owner. It exists from the first start (the kernel’s migrations create it, plan 3b-iii decision 1); setup sets it up, once, and a second setup is refused. Every query names that owner (kernel spec §1), bound when the operator opens (db::kernel_owner).
• The setup token lives in memory only. A restart before setup issues a new one, and the old one is dead by construction (kernel spec §3.1). Only its SHA-256 is kept.
• Passwords are Argon2id PHC strings (password-auth). Hashing and verifying are CPU- and memory-heavy (about 19 MiB each), so they run on a blocking thread and at most MAX_CONCURRENT_HASHES at once.
• Recovery (the admin socket, kernel spec §4.2): a password reset and a public_url reset each end every session, and so its streams.

Every time is seconds since the Unix epoch, passed in by the caller.

Structs

AuthSession

One signed-in session, as Settings lists them (kernel spec §3.2).

Authenticated

A request’s session, once its cookie checks out.

Operator

PublicUrl

Where browsers reach the collector (umbrella spec §7.5): https://, or http:// to a loopback address, with no path, query or credentials. Kept as its origin exactly as a browser serialises it in Origin (lowercase scheme and host, no default port, no trailing slash), so the two compare as plain strings.

SetupLink

Where the setup link was written (Operator::announce_setup). Debug leaves the token out: a failing assertion or a log line must not show it.

Enums

PublicUrlChange

The outcome of Operator::change_public_url.

Reset

The outcome of Operator::reset_password and reset_public_url.

SetupOutcome

The outcome of Operator::set_up.

Constants

MAX_CONCURRENT_HASHES

Argon2 runs at most this many at once, whatever the number of clients.

MAX_PASSWORD_BYTES

The longest password accepted, in bytes: hashing is bounded by it.

MAX_SESSION_COOKIES

At most this many hennery_session cookies of a request are tried, so one request cannot cost many session lookups.

MIN_PASSWORD_CHARS

The shortest password setup accepts, in characters.

SESSION_COOKIE

The session cookie’s name (kernel spec §3.2).

SESSION_SLIDE_SECS

A session’s expiry slides at most this often, so a busy client does not write to the database on every request.

SESSION_TTL_SECS

A signed-in session lives this long past its last use (kernel spec §3.2).

SETUP_TOKEN_TTL_SECS

A setup link is valid this long (kernel spec §3.1).

SETUP_URL_FILE

The file in the data directory that holds the setup link until setup (kernel spec §1, §3.1).

STEP_UP_SECS

A password check is fresh enough for step-up this long (kernel spec §3.4).

Functions

cleared_cookie

Set-Cookie that removes the session cookie.

session_cookie

Set-Cookie for a session (kernel spec §3.2): HttpOnly, SameSite=Strict, Path=/, for SESSION_TTL_SECS, and Secure unless public_url is loopback http://.

session_tokens

Every session token in a request’s Cookie headers, in order, at most MAX_SESSION_COOKIES. There can be more than one: a sibling subdomain can set a cookie of the same name for the parent domain, and the browser may send it first. Taking only the first would let it sign the owner out.