Skip to main content

Module admission_roster

Module admission_roster 

Source
Expand description

#1652 — derived native admission roster: deployment service identities (and their local tenant) resolved from the live accepted-state store at admission time, replacing the DID-valued quic.moql_subject_tenants map. Derived native admission roster (#1652): deployment service identities resolved from the live accepted-state store at admission time, not from DID-valued process configuration.

Formerly quic.moql_subject_tenants embedded every deployment DID in config.toml, so each service-identity re-initialization (R1: reviewed store wipe + re-provision, all DIDs change) left every running process pinned to stale DIDs until the boot projector re-wrote the file AND every container restarted. The tenant is a pure roster projection — metal writes did = "local" uniformly for all eight services — so it is now DERIVED: DID → accepted state → capsule #<name> service entry ∩ the registered factory roster, held UNIQUELY across the store ⇒ tenant [LOCAL_TENANT]; everything else ⇒ unresolved, deny.

§Why unique-holder, not name-match alone

The store is not a pure deployment roster: the public ingestAt9pCandidate RPC admits foreign, self-certifying capsules whose #id entries are arbitrary strings, and provisioned and ingested states share one write path — provenance is not distinguishable in the store. A foreign capsule that NAMES a factory service (e.g. #event) therefore cannot be told apart from a deployment identity by its content. The derivation closes that self-selection the only way store data allows:

  • a name admits a tenant only while EXACTLY ONE accepted state in the whole store derives it — beside the genuine identity a squatter makes the name ambiguous, and ambiguity denies (fail-closed, loud: the collision is warned so an operator sees the injected record). This is the offline roster validator’s cross-state uniqueness ensure!, and project_bootstrap_endpoint’s ambiguity rule, applied per lookup;
  • the deriving state must carry the deployment invariants the offline provisioner guarantees and foreign genesis-only records lack: successor epoch (epoch > 0) and a bounded expiry that has not lapsed (an expired state — genuine or foreign — never derives and never counts toward uniqueness).

Residual (deliberate, flagged in #1652): if a deployment name has NO genuine accepted state (decommissioned service) and an attacker ingests a capsule claiming it, that name derives for the attacker. Operating with names in quic.event_publishers that have no live deployment state is a deployment inconsistency this PR refuses at Event spawn ([require_publisher_roster]) and the tenant grant remains bounded to the fixed local namespace. Fully distinguishing provenance needs a provisioner-signed roster the admission path can verify — a maintainer design decision recorded in #1652, not something this change invents.

Resolution enumerates the store’s verified states through the same verification as the per-DID admission read, behind a TTL cache ([CachedRoster]): the live-session recheck runs every 100 ms per session, so the polling path serves a bounded-stale snapshot instead of re-verifying the whole store at 10 Hz per session. Revocation by state REMOVAL stays immediate (the per-DID admission authority recheck is uncached); the cache bounds only how quickly roster-side changes — churn re-binding, name reassignment, squatter arrival — become visible (≤ TTL).

This mirrors the hosted-account tenant index (HostedAccountStore::resolve_tenant_for_hosted_did) and the MoqConnectAuthz resolver-closure shape: the tenant never comes from the peer, its proof, or a token — only server-side resolution over verified accepted state. Failure inheritance is identical to authentication: a store read failure yields an empty roster, and an empty roster denies.

Structs§

CachedRoster
TTL-bounded cached roster projection (the resolve_tenant_for_hosted_did shape): lookups serve a snapshot for at most ROSTER_CACHE_TTL, then one refresh runs while concurrent lookups keep serving the current snapshot. After the synchronous first load (spawn path — data must exist before serving), every refresh runs on a background thread and publishes atomically: the loader opens RocksDB and verifies every state, the 100 ms currentness watchdog reaches lookups from async current-thread runtimes, and public ingestion can amplify the store — so no runtime thread ever executes the scan. Readers never take a lock across a scan; the snapshot mutex is touched only long enough to read or swap an Arc.

Constants§

LOCAL_TENANT
The single tenant of the fixed native Event/Streams namespace. The Event tree is the fixed local namespace (local/events); every deployment service identity maps to it and no other tenant is derivable.
ROSTER_CACHE_TTL
How long a roster snapshot is served before the next lookup refreshes it. Bounds the visibility delay of roster-side changes (churn, reassignment, squatter arrival); state removal is caught immediately by the uncached per-DID authority recheck regardless.

Traits§

DeploymentRosterSource
The deployment-roster side of the accepted-state authority: enumerates every verified accepted state so grant derivation can enforce the cross-store uniqueness a per-DID read cannot see. Implemented by the process’s cached projection; a blanket Fn impl covers fixtures.

Functions§

derived_service_name
The deployment service name an accepted state proves, if any.
derived_tenant_resolver
The admission tenant resolver: tenant LOCAL_TENANT iff the verified subject is a current, uniquely-held deployment service identity.
require_admitted_service_binding
Client-side membership self-check: the process’s own proof must resolve to SOME uniquely-held deployment service. CLI/embedded processes bootstrap with one of the deployment identities (whichever the process was provisioned as), so — like the former require_event_tenant, which accepted any local-bound DID — the check is roster membership, not equality with a specific service.
require_publisher_roster
Spawn-time Event publisher roster check (#1652): every name in quic.event_publishers must be carried by EXACTLY ONE live accepted state — the same unique-holder rule the runtime resolution enforces, so spawn fails loudly instead of starting with a publisher that every lookup would deny (a name with no holder is a deployment misconfiguration — typo, decommissioned service; a name with two holders is an ingested squatter beside the genuine identity). It does NOT establish provenance: a sole foreign claimant of an unheld name satisfies it exactly as it satisfies the derivation, which is the maintainer provenance-binding decision recorded in #1652 (see the module doc residual); closing that here is not possible from store data alone.
require_service_self_binding
Spawn-time self-binding (#1652): the live roster must resolve the process’s OWN admission proof to exactly this service. Refusal propagates and the service never spawns — the fail-closed shape of the former empty-tenant-map refusal, now “the checkpoint store must bind my DID to my name”. The store is guaranteed present at spawn (the accepted-state source refuses to open without it), so failure here is a provisioning mismatch, not a degraded mode to run in.
roster_service_name
Resolve did to its deployment service name against the live roster, enforcing unique holdership: the DID’s state must derive a name, and no OTHER state may derive the same name. A collision is warned loudly — an ingested record squatting a deployment name is an operator-visible event, not a silent deny.
roster_tenant
DID → derived tenant against the live roster: LOCAL_TENANT iff the subject uniquely proves a deployment service identity.

Type Aliases§

RosterEntry
One projected accepted state, keyed by its DID: the roster universe the derivation enumerates (provisioned deployment identities and foreign ingested records alike).