Module dashboard_session 

Self-contained dashboard-access session tokens.

A browser reaching a PAIRED agent’s own web dashboard from off-box has no X-ADOS-Key (that key lives in the GCS, not in a casual visitor’s browser). Rather than prompt for the raw key, the dashboard offers a short numeric PIN: the operator enters it, and the agent hands back one of these session tokens, which the dashboard then sends on every /api/* call as X-ADOS-Dashboard-Session. The native control front accepts a valid session as an alternative data-plane credential to X-ADOS-Key.

Like crate::ws_ticket, the token is self-contained and HMAC-signed — the minting surface and the validating surface (the same daemon here, but the shape matches the ws-ticket precedent) share no state, only the key. The key is derived from BOTH the pairing api_key AND the PIN record’s random salt:

K = HMAC-SHA256(api_key, "ados-dashboard-session-v1" || salt)

Folding the salt into the key is what makes a PIN reset revoke every live session: resetting the PIN writes a fresh salt, so K changes and every previously-minted token fails to verify. Re-pairing (a new api_key) revokes them too. The salt is never the pairing key itself, and is namespaced to this use by the domain-separation label.

Wire form (pipe-delimited, like the ws ticket but with no scope field): v1|<issued_at>|<expires_at>|<sig_hex>, where the signature is HMAC-SHA256(K, "v1|<issued_at>|<expires_at>").

Structs

DashboardSession

A minted session: its compact string form plus the parsed expiry, so a mint surface can return { session, expires_at } without re-parsing.

DashboardSessionIssuer

Mints and verifies self-contained dashboard-access sessions, keyed by the pairing api_key + the PIN record’s salt. Build one with DashboardSessionIssuer::from_api_key_and_salt.

Enums

SessionError

Constants

DEFAULT_TTL_SECONDS

Default session lifetime in seconds (24 h): long enough that a dashboard is not re-prompting the operator through a work session, short enough that an abandoned browser tab does not stay authorized forever.

MAX_TTL_SECONDS

Hard cap on a requested session lifetime (7 days), the ceiling a silent activity-refresh re-mints under.

SESSION_KEY_LABEL

Domain-separation label mixed (with the salt) into the pairing key to derive the session key.

Functions

now_unix

Unix seconds, clamped to 0 if the clock predates the epoch (a freshly booted SBC before NTP sync) so minting never aborts the process.