Crate pb_mapper_auth 

Authentication state for protocol-v2 connections and administrator operations.

How a temporary credential works

Nothing secret is stored per key. A temporary credential is derived from the root key, the server instance id, and the key id, so the server can verify a credential it holds no copy of, and a key id is all the state a key needs:

issue:  root key + instance id + key id  --HKDF-->  credential handed to the client
verify: root key + instance id + key id  --HKDF-->  compare against what was presented

Because the material is derived, invalidating every key at once is a matter of changing an input: a root rotation replaces the root key, a state reset replaces the instance id. Neither has to touch individual keys.

Where the state lives

                   key_id = generation:slot
                            |
  request ──> derive & compare ──> slots[slot]  ── lifecycle: Free/Active/
                                       │            Expired/Revoked, expires_at
                                       │
                                  Weak lease ──> Arc lease, owned by the actor's
                                       ^          timing wheel — the single place
                                       │          a lease's lifetime ends
  AuthContext (also Weak) ─────────────┘

The slot table is a preallocated array indexed straight off the key id, so verification costs an array index and churn does not grow memory. The SlotState docs below cover the table’s layout, why generations exist, and why dead rows linger. Leases (leases.rs) owns the three structures a key’s lifetime spans; timing_wheel.rs schedules the expiries.

Where mutations happen

AuthRuntime (facade) ──channel──> one actor ──> encrypted snapshot + WAL

Every mutation is serialized through a single actor, so a request authorized before a root rotation cannot execute against the state that replaced it.

The facade and model types stay in this root module; runtime checks, actor mutations, persistence, expiry scheduling, and tests live in the children.

Structs

AuthConfig

AuthContext

AuthFailure

AuthLease

AuthRuntime

AuthStatus

Generation

Which tenant of a slot a credential belongs to. Bumped every time the row is reissued, and never reset, so a retired credential can never match the row that replaced it.

IssuedTemporaryKey

KeyId

The identity a client presents: a SlotIndex paired with the Generation of the row it was issued from.

KeyPage

LegacyConnectionGuard

SlotIndex

Which row of the slot table a credential lives in.

TemporaryKeyMetadata

Enums

LegacyProtocolPolicy

Constants

ADMIN_KEY_ID

The administrator, which owns no slot and never expires.

ADMIN_NAMESPACE

The namespace administrator connections operate in. Tenant namespaces are the key id that owns them, so this mirrors ADMIN_KEY_ID.

DEFAULT_AUTH_STATE_DIR

DEFAULT_MAX_TEMP_KEY_TTL

DEFAULT_TEMP_KEY_CAPACITY

MAX_TEMP_KEY_CAPACITY

MAX_TEMP_KEY_TTL

MIN_TEMP_KEY_TTL

Functions

acquire_state_dir_lock

default_auth_state_dir

derive_temporary_key

discard_staged_admin_key

Drop a staged candidate once the rotation it belongs to is durably recorded at the live key file.

encrypted_auth_state_exists

generate_admin_key

initialize_admin_key

stage_admin_key_candidate

Write a root-rotation candidate to the staged sibling of path, returning the staged path.

staged_admin_key_path

The sibling path a root-rotation candidate is staged at, next to the live administrator key file path.

write_admin_key_file