Skip to main content

hyprstream_core/mac/
lattice.rs

1//! Lattice surface for the PDP — **re-export of S1's canonical types** (#567).
2//!
3//! S4 (#570) originally developed the TE evaluator + AVC against a *stub* lattice
4//! (`StubLinearLattice` + a local `SecurityLabel(u32)` + a `Lattice` dominance
5//! trait) so the two streams could proceed in parallel. **S1 has landed**
6//! (`feature/security-mac-ucan` @ `406ff9fdc`) with the real, canonical types in
7//! [`hyprstream_rpc::auth::mac`], and this file is now a thin re-export so the rest
8//! of the PDP (`te.rs`, `avc.rs`, `compiled.rs`) consumes S1 directly. The stub is
9//! deleted.
10//!
11//! ## What changed at reconciliation (the S1 contract, as landed)
12//!
13//! - [`SecurityLabel`] is no longer an opaque `u32` interned id. It is S1's
14//!   **structured value** — a point in the product lattice
15//!   `Level × Assurance × CompartmentSet` — and is `Copy + Ord + Hash`
16//!   (compartments are a packed `u64` bitset), so it still keys the AVC directly
17//!   with no interning indirection. Crucially it has **no `Default`**: an
18//!   unlabeled subject/object is `Option::None` ⇒ deny, never a permissive
19//!   default.
20//! - Dominance (`⊒`) and join (`⊔`) are **intrinsic** to the value
21//!   ([`SecurityLabel::can_access`], [`SecurityLabel::join`] /
22//!   [`SecurityLabel::join_all`]), and re-exposed on
23//!   [`SecurityContext::can_access`] for a verified subject. They are NOT methods
24//!   on a `Lattice` trait — content truth, no policy argument. The old
25//!   `Lattice::can_access`/`join` trait is gone; the PDP floor now calls the
26//!   intrinsic order (see `te.rs`).
27//! - [`Lattice`] is now S1's **policy object** (the closed, versioned compartment
28//!   name↔bit vocabulary). The PDP holds it to (a) align its TE matrix columns to
29//!   the exact bits a label carries via [`Lattice::compartment_names`], (b)
30//!   [`validate`](Lattice::validate) labels at enrollment/seal, and (c) embed it,
31//!   via [`Lattice::to_bytes`], inside the signed `CompiledPolicy` so every
32//!   process reconstructs the **identical** bit map ([`compiled`](crate::mac::compiled)).
33//!   [`LatticeVersion`] is bound to `CompiledPolicy.generation`.
34//!
35//! The MAC floor (per-op `subject.ctx ⊒ object.label` + IFC join) is computed
36//! against the intrinsic order and is **independent of any grant/token/UCAN**
37//! (design §3, §10).
38
39// Re-export S1's canonical MAC types from the RPC crate (the TCB seam). Everything
40// the PDP needs flows through here so a future S1 shape change is a one-file edit.
41pub use hyprstream_rpc::auth::mac::{
42    Assurance, Compartment, CompartmentSet, LabelError, Lattice, LatticeCodecError,
43    LatticeDecodeError, LatticeVersion, Level, SecurityContext, SecurityLabel,
44    SubjectContextClaims, VerifiedKeyMaterial, MAX_COMPARTMENTS,
45};
46
47/// IFC convenience: join a slice of input labels into the derived label (design
48/// §3 — sealed at rollup). Thin forwarder over S1's intrinsic
49/// [`SecurityLabel::join_all`]. Non-empty joins use the per-axis algebraic identity
50/// `(Public, PqHybrid, {})`; empty input instead yields the fail-closed
51/// `(Public, Unverified, {})`, which the seal/rollup policy (S2) must treat as
52/// suspicious. This is the function S6/seal-time labeling calls; it lives here so
53/// PDP callers have a single entry-point without reaching across crates.
54#[inline]
55#[must_use]
56pub fn ifc_join(inputs: &[SecurityLabel]) -> SecurityLabel {
57    SecurityLabel::join_all(inputs.iter())
58}
59
60#[cfg(test)]
61#[allow(clippy::unwrap_used)]
62mod tests {
63    use super::*;
64
65    fn lattice() -> Lattice {
66        Lattice::new(
67            LatticeVersion(1),
68            [
69                Compartment::new("pii"),
70                Compartment::new("finance"),
71                Compartment::new("tenant:acme"),
72            ],
73        )
74    }
75
76    #[test]
77    fn intrinsic_dominance_is_product_order() {
78        let l = lattice();
79        let cleared = l
80            .label(
81                Level::Secret,
82                Assurance::PqHybrid,
83                [Compartment::new("pii"), Compartment::new("finance")],
84            )
85            .unwrap();
86        let needs_pii = l
87            .label(
88                Level::Confidential,
89                Assurance::Classical,
90                [Compartment::new("pii")],
91            )
92            .unwrap();
93        // dominates on every axis (level ≥, assurance ≥, compartments ⊇).
94        assert!(cleared.can_access(&needs_pii));
95        assert!(!needs_pii.can_access(&cleared));
96    }
97
98    #[test]
99    fn ifc_join_combines_blp_confidentiality_and_biba_integrity() {
100        let l = lattice();
101        let secret = l
102            .label(
103                Level::Secret,
104                Assurance::PqHybrid,
105                [Compartment::new("pii")],
106            )
107            .unwrap();
108        let public = l.label(Level::Public, Assurance::Classical, []).unwrap();
109        let derived = ifc_join(&[secret, public]);
110
111        // Confidentiality and compartments take their upper bounds.
112        assert!(derived.level >= secret.level && derived.level >= public.level);
113        assert!(secret.compartments.is_subset(derived.compartments));
114        assert!(public.compartments.is_subset(derived.compartments));
115        // Biba provenance integrity takes the floor (weakest input).
116        assert!(derived.assurance <= secret.assurance);
117        assert!(derived.assurance <= public.assurance);
118        assert_eq!(derived.assurance, Assurance::Classical);
119
120        // The algebraic identity is (Public, PqHybrid, {}), but an empty input
121        // is deliberately fail-closed rather than returning that identity.
122        let algebraic_identity =
123            SecurityLabel::new(Level::Public, Assurance::PqHybrid, CompartmentSet::EMPTY);
124        assert_eq!(ifc_join(&[algebraic_identity, secret]), secret);
125        let empty = ifc_join(&[]);
126        assert_eq!(empty.level, Level::Public);
127        assert_eq!(empty.assurance, Assurance::Unverified);
128        assert!(empty.compartments.is_empty());
129        assert_ne!(empty, algebraic_identity);
130    }
131
132    #[test]
133    fn lattice_validate_and_bytes_roundtrip() {
134        // The desync-proof property compiled.rs relies on: same bytes → identical
135        // bit assignment in every process.
136        let l = lattice();
137        let restored = Lattice::from_bytes(&l.to_bytes()).unwrap();
138        assert_eq!(restored.compartment_names(), l.compartment_names());
139        let label = l
140            .label(
141                Level::Internal,
142                Assurance::Classical,
143                [Compartment::new("tenant:acme")],
144            )
145            .unwrap();
146        assert!(restored.validate(&label).is_ok());
147        assert_eq!(restored.bit_of(&Compartment::new("tenant:acme")), Some(2));
148    }
149}