Skip to main content

Module mac

Module mac 

Source
Expand description

Mandatory Access Control — the Policy Decision Point (PDP) for the 9P/VFS surface.

This is ticket S4 (#570) of the native-MAC security epic (#547): the data-plane authorization engine. It implements, against an assumed S1 lattice interface:

  • lattice — a thin re-export of S1’s canonical types (#567): the structured SecurityLabel (Level × Assurance × CompartmentSet, Copy + Ord + Hash, no Default), the Lattice policy object (closed compartment name↔bit vocabulary, versioned), and SecurityContext. Dominance/join are INTRINSIC to the label, not trait methods — the PDP floor calls them directly. (The original S4 stub lattice was deleted at reconciliation; see the lattice module docs.)
  • te — the type-enforcement evaluator: a TOTAL, default-deny (subject_ctx, object_label, action) → Decision over the compiled TE matrix AND the independent lattice floor. Small + verifiable. This is the PDP core.
  • avc — the Access Vector Cache: the fast local decision cache the PEP (S2) calls per op. Sub-µs hits (hash lookup, no Casbin, no signature verify, no lattice walk on a hit). Defines how an OAuth access token maps to a cached decision (token = distributed AVC entry).
  • compiled — compiled-policy distribution + signing: PolicyService hashes + signs the TE matrix (hybrid EdDSA + ML-DSA-65 COSE composite); the loader rejects any unsigned/mismatched/unapproved policy. Verification happens ONCE at load, never per op.

§The control-plane / data-plane split (be explicit)

CONTROL PLANE (authoring / compilation store)      DATA PLANE (per-op enforcement)
─────────────────────────────────────────────      ───────────────────────────────────
UCAN                  the grant/delegation source
Casbin Enforcer       policy STORE + AUTHORING      ── NEVER on the per-op hot path ──
  (auth::policy_manager::PolicyManager)
S5 UCAN→TE compiler   lowers Casbin/UCAN → matrix──► TeMatrix         (compiled object code)
PolicyService         compiles + SIGNS policy ─────► compiled::SignedPolicy
                                                     │ loader verifies ONCE
                                                     ▼
                                                     te::LatticeTeEvaluator  (the PDP)
                                                     avc::CachingAvc          (the cache)
                                                     ▲ PEP (S2) calls per op

Casbin stays control-plane. The existing casbin::Enforcer in [crate::auth::policy_manager::PolicyManager] remains the policy store and authoring surface (RBAC/ABAC string matching, templates, add_policy/apply_template). Its enforce() string-matcher is never invoked per op — that would blow the latency budget and enlarge the TCB. Instead, S5’s compiler lowers the authored policy into the compact te::TeMatrix (interned-id allow-set, O(1) lookup), which this PDP evaluates. The mandatory lattice floor is independent of Casbin entirely (design §5a: “the lattice is NOT encoded in Casbin”).

§TCB note

The per-op TCB is intentionally tiny: a hash lookup (avc), and on a miss a set lookup plus one intrinsic SecurityLabel::can_access call (te). All heavy/bug-prone logic (Casbin matching, UCAN chain validation, compilation, signature verification) is concentrated off the hot path — in PolicyService and the compiled loader, the one audited place (design §2).

Re-exports§

pub use avc::Avc;
pub use avc::AvcKey;
pub use avc::CachingAvc;
pub use avc::TokenScope;
pub use audit::audit_signing_input;
pub use audit::AuditError;
pub use audit::AuditRecord;
pub use audit::AuditSigner;
pub use audit::AuditSink;
pub use audit::AuditVerifier;
pub use audit::AuditedAvc;
pub use audit::DecisionReason;
pub use audit::NullAuditSink;
pub use audit::WalAuditStore;
pub use compiled::sign_policy;
pub use compiled::CompiledPolicy;
pub use compiled::PolicyApproval;
pub use compiled::PolicyDistError;
pub use compiled::PolicyLoader;
pub use compiled::PolicySigner;
pub use compiled::PolicyVerifier;
pub use compiled::SignedPolicy;
pub use lattice::ifc_join;
pub use te::Action;
pub use te::Decision;
pub use te::LatticeTeEvaluator;
pub use te::ObjectCtx;
pub use te::ObjectType;
pub use te::SubjectCtx;
pub use te::SubjectType;
pub use te::TeEvaluator;
pub use te::TeMatrix;
pub use te::TeRule;
pub use compiler::authorize;
pub use compiler::authorize_at;
pub use compiler::check_no_escalation;
pub use compiler::compile;
pub use compiler::compile_policy;
pub use compiler::missing_permission;
pub use compiler::AccessRequest;
pub use compiler::CompileError;
pub use compiler::PermissionMap;
pub use compiler::PrivilegeEscalation;
pub use genesis::floor_label;
pub use genesis::genesis_lattice;
pub use genesis::CompositeObjectLabelResolver;
pub use genesis::GeneratedNodeCoverage;
pub use genesis::GenesisGate;
pub use genesis::ManifestLabelSource;
pub use genesis::NamespaceEnumerator;
pub use genesis::NoManifests;
pub use genesis::SitePolicy;
pub use dispatch_labels::policy_methods;
pub use dispatch_labels::DeclaredDispatchPep;
pub use dispatch_labels::DeclaredDispatchTable;
pub use dispatch_labels::DispatchMethodId;
pub use dispatch_labels::DispatchMethodPolicy;
pub use dispatch_labels::ServiceSubjectClearance;
pub use dispatch_labels::BOOTSTRAP_SERVICE_CLEARANCE;
pub use dispatch_labels::SERVICE_SUBJECT_PREFIX;
pub use moq_audit::audited_moq_event_pep;
pub use moq_audit::production_moq_event_pep;
pub use moq_audit::production_moq_event_pep_with_clearance;
pub use moq_audit::MoqAuditSinkAdapter;
pub use moq_audit::VerifiedClaimsMoqClearanceSource;
pub use pds_pep::production_pds_account_read_authorizer;
pub use pds_pep::EnrollmentPdsClearanceSource;
pub use pds_pep::PdsAccountObjectLabelResolver;
pub use pds_pep::PdsAccountReadPep;
pub use pds_pep::PdsClearanceSource;
pub use pds_pep::production_pds_account_record_store;
pub use pds_pep::PdsDirectoryMount;
pub use cas_pep::domain_label;
pub use cas_pep::production_cas_pep;
pub use cas_pep::seal_label;
pub use cas_pep::CasClearanceSource;
pub use cas_pep::CasObjectLabelResolver;
pub use cas_pep::CasPep;
pub use cas_pep::DenyAllClearanceSource;
pub use cas_pep::MacCasAuthorizer;
pub use cas_pep::VerifiedClaimsCasClearanceSource;
pub use pep::enrollment_ninep_reference_monitor;
pub use pep::production_ninep_decider;
pub use pep::production_ninep_reference_monitor;
pub use pep::production_vfs_pep;
pub use pep::EnrollmentClearanceSource;
pub use pep::NinePAccessDecider;
pub use pep::NinePClearanceSource;
pub use pep::VerifiedClaimsSubjects;
pub use pep::VerifiedClearanceSessionFactory;
pub use pep::VfsAccessDecider;
pub use bootload::compile_sign_load_install;
pub use bootload::install_baseline_boot_policy;
pub use bootload::BootPolicyError;

Modules§

audit
S7 (#573, epic #547) — tamper-evident, complete audit of every MAC authorization decision, with OpenTelemetry fan-out.
avc
Access Vector Cache — the fast local decision cache the PEP consults per op (S4 / #570).
bootload
S4 policy bootload (#570): the missing daemon-boot step that installs a verified CompiledPolicy so the MAC PDP inputs are real.
cas_pep
CAS-native MAC Policy Enforcement Point (#1270, epic #1267 T3).
compiled
Compiled-policy distribution + signing (S4 / #570).
compiler
UCAN → Type Enforcement policy compiler (S5 / #571).
dispatch_labels
Typed RPC dispatch labels — the focused #1499 boot-labeling slice.
enrollment_journal
Enrollment-intent journal (#698 Phase 2) — the durable, append-only record of intent to enroll a provisioned subject into the MAC clearance table.
enrollment_reconcile
Enrollment reconciler (#698 Phase 2, code slice 2) — the single-writer protected-controller action that folds the durable enrollment-intent journal into the NEXT unsigned boot-policy generation for the offline trust sign-mac-boot-policy ceremony.
exchange
MAC S6 — runtime grant path: UCAN grant-request → access/refresh tokens. Part of the native-MAC program.
genesis
Production genesis labeling — content, enumeration, resolution, and the boot-time coverage gate for the native-MAC data plane (S1 activation, #567, epic #547).
lattice
Lattice surface for the PDP — re-export of S1’s canonical types (#567).
moq_audit
Signed-WAL adapter for MoQ/event-plane MAC denials.
pds_pep
Audited MAC adapter for the tenant account-record read store (#1319).
pep
Authoritative 9P policy-enforcement point.
permission_map
The production PermissionMap (#676): the S3 scope ↔ S5 TE-rule vocabulary, injective and exact.
public_exemptions
Reviewed registry of HTTP routes intentionally exempt from native MAC mediation — the “public / declassifier exemption registry” (issue #1273, epic #1267, audit item NEW-PUBLIC-EXEMPTIONS).
te
Type-Enforcement evaluator — the Policy Decision Point hot-path core (S4 / #570).

Structs§

Compartment
A need-to-know compartment name (the categories axis vocabulary).
CompartmentSet
A fixed bitset of compartment bits — the powerset-lattice axis, packed so SecurityLabel stays Copy + Ord + Hash.
EnrollmentSubjectContextResolver
The SubjectContextResolver for a delegated actor, backed by the signed policy’s enrollment table (CompiledPolicy::clearance_for, #698 PR A).
Lattice
The active lattice policy: the closed compartment vocabulary (name↔bit) and the version. Levels and assurances are fixed by their enums (TCB), so only the open dimension — compartments — needs a registry.
LatticeCodecError
Failure decoding a Lattice from its canonical byte form: either the CBOR itself was malformed or the decoded vocabulary was rejected (see LatticeDecodeError). Carries a rendered message; the distinction is not load-bearing for callers, which fail closed either way.
LatticeVersion
Monotonic lattice policy version. Crypto-agility / policy-agility rule (design §14): the suite/lattice is pinned and versioned; migration is a deliberate version bump, never an in-band negotiation. Labels and the (UCAN, bundle_hash) approval (S5) bind this version so a label minted under v1 can’t be silently reinterpreted under v2.
SecurityContext
A verified subject’s security context = the clearance label the monitor compares against object labels.
SecurityLabel
A complete security label: a point in the product lattice Level × Assurance × CompartmentSet.

Enums§

Assurance
Crypto-assurance axis (#548) — a total order derived from verified key material, never claimed.
LabelError
Reasons a label fails the well-formedness policy. All are fail-closed.
LatticeDecodeError
Reasons a serialized Lattice is rejected on decode. All fail-closed: a malformed wire vocabulary never silently becomes a smaller/different lattice.
Level
Multi-Level-Security sensitivity level — a total order (the MLS axis).
ScopeAction
VerifiedKeyMaterial
How a principal’s key material was verified, used to derive (never trust) an Assurance. Produced by the envelope/claims verification layer — this type is the seam between “what crypto verified” and “what the lattice sees”.

Constants§

MAX_COMPARTMENTS
Number of distinct compartments representable in a label.

Traits§

SubjectContextClaims
Seam for carrying a subject clearance on the verified claims/envelope.

Functions§

compiled_policy
The installed CompiledPolicy, if any. None on a node that hasn’t loaded one — callers MUST fail closed (see exchange_enrollment_resolver), never substitute a permissive default.
exchange_enrollment_resolver
Construct the SubjectContextResolver the HTTP grant path resolves delegated actors’ MAC context through (#698 Decision D).
exchange_ucan_verifier
Construct the [UcanVerifier] the HTTP grant path uses to validate a presented UCAN’s signatures.
install_production_rpc_dispatch_pep
Install the mandatory RPC-dispatch PEP using the process activation control. Verified identity-aware contexts are the default; explicit incident narrowing remains available without removing the monitor.