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/PDPNo 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.
MountBackendemits one QID per bound component;ModelBackendrejects 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-9pperforms no..canonicalization;wnamesare concatenated verbatim into the cached path. Not exploitable againstMemoryBackend/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::Cidexists precisely to close this (content-addressed refs bind the label to the object, not the name); the 9P seam feedsObjectRef::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§
- Anonymous
Authenticator - Fail-closed authenticator: every attach resolves to a deny-only session.
Used by
ReferenceMonitorconstructions that have not been given an application authenticator, and by tests. - Deny
AllDecider - Fail-closed fallback for layers that cannot construct the production resolver-backed, audited decider.
- Deny
Unlabeled Resolver - 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
Noneis a mandatory deny (design §1 invariant 2). - Reference
Monitor - The reference monitor a
Translatormediates 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. - Session
Context - Attach-scoped state cached onto every fid derived from the attach fid.
- Verified
Attach - One credential verification result shared by both enforcement sides of a 9P attach. The MAC session and the VFS subject cannot be supplied independently.
- Verified
Attach Identity - Stable principal or credential identity returned by an
AttachAuthenticatorafter verification. - Verified
Token Scope - A verified, sender-bound access-token scope cached for one 9P attach.
Enums§
- Action
- The 9P operation an
AccessDecideris asked to authorize. - Object
Ref - 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 (matchesMount::walk’s&[&str]component slice inhyprstream-vfs, without this crate depending on that crate) or a content identifier (a manifest CID / CAS hash). - Reference
Monitor Deny Reason - Denial gates owned by
ReferenceMonitorrather than the local decider.
Traits§
- Access
Decider - Authorizes one operation against a subject’s cached [
SecurityContext] and exact walked object reference. - Attach
Authenticator - Verifies the
Tattachcredential and returns the session cached per fid. - Object
Label Resolver - The keyed seam the reference monitor (S2/#568) calls before constructing
an
ObjectCtxfor 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
VerifiedTokenScopeand is denied.