Skip to main content

Module mac_seam

Module mac_seam 

Source
Expand description

9P reference-monitor contract (S2 / #568, epic #547).

hyprstream-9p owns the 9P operation choke point but deliberately does not depend on the application crate that owns MAC policy loading and the AVC. This module is the dependency-inversion boundary: the application verifies a sender-bound access token once at Tattach, then the translator applies the label, token, and IFC gates before asking an injected local policy monitor (the application’s AVC/PDP adapter).

The mediation ordering is intentional and non-optional:

Tattach: verify sender-bound token -> SessionContext (cached per fid)
each op: resolve content-truth label -> token scope -> IFC -> local AVC/PDP

No token, expired token, unlabeled object, or non-dominating subject reaches the policy monitor, so a permissive policy implementation cannot bypass the mandatory token/IFC floor. Per-op cost is a fid-table lookup plus a local AVC call — never UCAN chain validation or Casbin matching.

§Production activation posture

Translator can run without a ReferenceMonitor for tests and embeddings, but every production constructor installs one. The mount-ticket paths derive a unified VerifiedAttach from verified Claims and key material, while fixed-subject transports remain floor-only until they gain a credential carrier. The operator activation control widens or narrows the subject context; it never removes mediation.

§Mediation is over the name, not the object (read before relying on it)

The monitor is authoritative over the path a fid is tagged with, not over the object the backend resolves that fid to. [ReferenceMonitor:: authorize] resolves the label from ObjectRef::Path(components) (the cached walked path), while the backend independently resolves the fid to an actual object/handle. Nothing in this contract binds the labeled name to the served object: the invariant “the label checked is the label of the object served” holds only if the label resolver and the backend resolve names identically. That is a convention, not an enforced invariant — so the honest statement of #568’s “complete mediation” claim is:

Every dispatched op is routed through the monitor, and the monitor’s label resolver agrees with the backend’s name resolution for the served namespace. The first half is by construction; the second is a precondition.

Concretely, this name↔object gap is not covered today:

  • Partial walks — the backend reports its exact reached request prefix, and the translator rejects a result whose QID count disagrees with that prefix. MountBackend emits one QID per bound component; ModelBackend rejects multi-name walks until it can provide that same contract. This prevents the former one-leaf-QID/deep-fid mismatch, but still relies on the label resolver and backend agreeing on what a reported path names.
  • Path traversal / .. — hyprstream-9p performs no .. canonicalization; wnames are concatenated verbatim into the cached path. Not exploitable against MemoryBackend/MountBackend (they resolve component-wise from a root), but a future resolver that does not canonicalize identically to the backend reopens this gap. Any resolver wired at activation must canonicalize or reject .., or the label lookup and the backend resolution can diverge.
  • Bind / symlink / mount indirection — the VFS supports bind mounts and per-process bind namespaces. If a path component resolves through an indirection the string-keyed resolver does not model, the label checked is for the name and the bytes served are for the target. ObjectRef::Cid exists precisely to close this (content-addressed refs bind the label to the object, not the name); the 9P seam feeds ObjectRef::Path.

Closing the name↔object TOCTOU by making the monitor authoritative over the fid/object (e.g. resolving labels from the backend’s reached object, or via ObjectRef::Cid) is activation-blocking and tracked with #699. Until then, treat “complete mediation by construction” as the two-independent-resolutions-agree claim above, not as object authority.

Structs§

AnonymousAuthenticator
Fail-closed authenticator: every attach resolves to a deny-only session. Used by ReferenceMonitor constructions that have not been given an application authenticator, and by tests.
DenyAllDecider
Fail-closed fallback for layers that cannot construct the production resolver-backed, audited decider.
DenyUnlabeledResolver
Fail-closed label resolver for a mount with no content/static label source. A real export injects the genesis/manifest resolver owned by the application. Returning None is a mandatory deny (design §1 invariant 2).
ReferenceMonitor
The reference monitor a Translator mediates every dispatched op through once installed. Bundles the three injection points so enforcement is all-or-nothing: there is no translator state in which the token gate runs but the label resolver is absent, or vice versa.
SessionContext
Attach-scoped state cached onto every fid derived from the attach fid.
VerifiedAttach
One credential verification result shared by both enforcement sides of a 9P attach. The MAC session and the VFS subject cannot be supplied independently.
VerifiedAttachIdentity
Stable principal or credential identity returned by an AttachAuthenticator after verification.
VerifiedTokenScope
A verified, sender-bound access-token scope cached for one 9P attach.

Enums§

Action
The 9P operation an AccessDecider is asked to authorize.
ObjectRef
A reference to the object being labeled, as available to whatever calls ObjectLabelResolver::resolve — before any object bytes are read. Mirrors the two carriers #699 actually has data for at this layer: a walked path (matches Mount::walk’s &[&str] component slice in hyprstream-vfs, without this crate depending on that crate) or a content identifier (a manifest CID / CAS hash).
ReferenceMonitorDenyReason
Denial gates owned by ReferenceMonitor rather than the local decider.

Traits§

AccessDecider
Authorizes one operation against a subject’s cached [SecurityContext] and exact walked object reference.
AttachAuthenticator
Verifies the Tattach credential and returns the session cached per fid.
ObjectLabelResolver
The keyed seam the reference monitor (S2/#568) calls before constructing an ObjectCtx for the PDP: “resolve this walked reference to its security label.” Distinct from [LabeledObject] (which answers for an object you already hold) — this answers for a reference you are about to walk.

Functions§

anonymous_floor
The anonymous security floor. It is not authorization: a session at this floor still has no VerifiedTokenScope and is denied.