Skip to main content

Module authority

cellos_core

Module authority 

Source
Expand description

Typed authority validator (Authority Model §14 + ADG).

§Status — preview

This module ships under the CELLOS_AUTHORITY_VALIDATOR_PREVIEW=1 policy authorized by the ADR-0005 SLA council (see Plans/cellos-code-complete-roadmap.md §7 Phase B1). At time of landing, ADR-0005 is Proposed; the council recommended pre-merging the B2 validator scaffold behind this preview flag if the ADR-0005 Accept SLA (deadline 2026-05-20) slips, so post-1.0 work has a stable foundation to rest on.

What lands here (B2-1 / B2-2 / B2-3 + T3.A / F2):

What deliberately does NOT land here (B3, post-1.0):

  • No producer (event-builder, supervisor admission, sni_proxy) wires these types in yet. The CloudEvent emitters keep producing today’s untyped shape until the post-1.0 wiring slice replaces them.
  • No JSON Schema integration with contracts/schemas/. The schema cell-observability-l7-authority-evidence-v1.schema.json lands as part of B3 (post-1.0).

§DeclaredAuthority — F2 / T3.A

ADR-0006 defines the fourth variant DeclaredAuthority (Tier ceiling 1, epistemic status EpistemicStatus::Declared) for guest-side cellos-telemetry declarations forwarded over the per-cell vsock channel. The mono-class envelope (RuleClass::GuestAgentDeclaration) prevents host-side classes from co-occurring inside the same typed authority. The companion GuestEventBuilder trait pins the rule-class at compile time via a const-asserted check, so a guest event-builder cannot accidentally route through a stronger class.

§Doctrine gates

  • D9 (mechanical separation): the three types share no common base trait, expose no From / Into conversions between each other, and each carry their own validated AuthorityDerivation. Merging two stacks is a compile error, not a runtime contract.
  • D11 (no I/O in cellos-core): the validator is pure. It takes plain values, returns Result. No tokio, no reqwest, no syscalls.

§Overview

The Authority Derivation Graph (ADG) — see docs/authority-derivation-graph.md — is the canonical record of how an authority emission was computed. Every typed authority MUST carry an AuthorityDerivation and the validator enforces six invariants on construction:

  1. Confidence non-inflation — output.confidence ≤ max(inputs.confidence).
  2. Tier ceiling — output.tier ≤ min(rule_class_tier_ceiling).
  3. Epistemic determinism — output.epistemic_status is the unique image of the rule-class set under the canonical mapping.
  4. ADG presence — emissions cannot construct without an ADG (gated by builder API and refused by the validator if inputs or rules_applied is empty).
  5. Rule → class consistency — every applied rule’s declared class matches the canonical mapping.
  6. Type-class compatibility — ObservedAuthority cannot carry CRYPTOGRAPHIC_PROOF rules; ProvenAuthority cannot be built without one; ImposedAuthority requires IMPOSED_INTERCEPTION.

See submodule [validator] for the typed-authority constructors and [crate::authority::tests] (cfg(test)-only) for the property tests.

Re-exports§

pub use derivation_result::validate_authority_derivation;
pub use derivation_result::AuthorityValidationResult;
pub use declared::validate_declared_authority_surface;
pub use declared::DeclaredAuthoritySurface;

Modules§

declared
F2 — guest-declared capability surface and the subset validator the host runs before accepting in-VM telemetry.
derivation_result
T2-B21 — typed result variants for verify_authority_derivation.

Structs§

AppliedRule
One rule that fired during derivation.
AuthorityDerivation
The complete ADG sub-object. Serializable for downstream events.
AuthorityInput
One evidence atom consumed by a derivation. Mirrors the ADG inputs[] schema; see docs/authority-derivation-graph.md.
AuthorityOutput
The derived (tier, confidence, epistemic_status, binding_status) tuple.
DeclaredAuthority
Authority asserted by a guest-side declaration (in-VM cellos-telemetry agent over the per-cell vsock channel) per ADR-0006.
ImposedAuthority
Authority asserted by CellOS having terminated TLS in-line and observed plaintext that the workload would not have shown without termination.
ObservedAuthority
Authority derived from CellOS’s own observation of bytes inside the cell’s network namespace.
ProvenAuthority
Authority derived from cryptographic verification of a claim CellOS did not author.

Enums§

AuthorityInputType
Canonical input types — a strict subset of those listed in the ADG doc.
BindingStatus
Binding status per docs/authority-model.md §6.
EpistemicStatus
Capability-tier and confidence semantics from docs/authority-model.md §5b.
ProvenAuthorityArtifact
Verified-signature artifact backing a ProvenAuthority. Storing the artifact alongside the derivation prevents ProvenAuthority from being constructed from a derivation that claims CryptographicProof without actually carrying the proof material.
Rule
Named rules per docs/authority-derivation-graph.md. Adding a new rule requires updating that document AND canonical_class_for_rule.
RuleClass
Rule-class drives EpistemicStatus; this is the canonical enum from docs/authority-derivation-graph.md.
ValidationError
Errors the validator can return. Each variant names the specific §9 invariant it violates so debug logs and tests can distinguish them.

Traits§

GuestEventBuilder
Compile-fail gate for guest event-builders (ADR-0006 / O2 doctrine red-line). Implementors declare their canonical RuleClass as an associated constant; a const-asserted check in Self::rule_class makes any class other than RuleClass::GuestAgentDeclaration a compilation error at the call site.

Functions§

canonical_class_for_rule
The canonical rule-name → rule-class mapping. Mirrors the table in docs/authority-derivation-graph.md.
epistemic_for_class_set
The deterministic class-set → epistemic-status mapping per docs/authority-derivation-graph.md:
max_tier_for_class
Tier ceiling per rule-class — the canonical mapping. The ADG doc and docs/authority-model.md §5b pin these numbers; do not change them without an ADR amendment.