Documentation
¶
Overview ¶
Package capability is the agent's least-privilege model: a Grant names exactly what a run is permitted to do, and an Admitter enforces it at the dispatch waist so an action outside the grant is denied before any side effect. It is the data half of governance, the policy the waist's Admitter consults; the sandbox is where an admitted action then runs under real OS-level confinement.
The grant is carried on the context, like the observability bundle, so a run binds its policy once and every action it dispatches is checked against the same grant without threading it through call signatures. A context with no grant bound is permissive, which keeps the standalone agent zero-config; a host opts into least privilege by binding a grant, and from then on the posture is default-deny: only the listed actions are admitted.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Into ¶
Into returns a context carrying g, so the dispatch waist's Admitter reads the run's policy from the context rather than from a parameter. Binding it once at the top of a run applies it to every action that run dispatches.
func PrincipalFromContext ¶
PrincipalFromContext returns the principal bound to ctx, or "" when none is set.
func WithPrincipal ¶
WithPrincipal binds the principal a run acts as: the specific identity on whose authority it runs, which agent in a fan-out or which human in a multi-user host. It is distinct from the coarse actor kind (agent/human/system): the actor says what sort of thing acted, the principal says exactly who. Bind it once at the top of a run, alongside the grant, and events the run records carry it for audit. The empty principal is the standalone agent itself, the zero-config default.
Types ¶
type Admitter ¶
type Admitter struct{}
Admitter is the dispatch.Admitter that enforces the capability grant bound to an action's context. It is the governance gate at the waist: with a grant bound it admits only the actions the grant permits and denies the rest with a Forbidden fault, before the handler runs and so before any side effect. With no grant bound it admits everything, so the standalone agent runs unconstrained until a host binds a policy. It is stateless and safe to share.
type ContainmentGate ¶
type ContainmentGate struct {
// contains filtered or unexported fields
}
ContainmentGate is the dispatch hook that refuses an action whose trust level needs stronger isolation than the run's sandbox provides. It is the containment half of admission: where the Admitter checks that a grant permits the action by name, this checks that the host can actually contain the work. Trusted work (the agent's own tools) runs at any tier; semi-trusted work (a model-authored command) needs the kernel-confined tier; untrusted work needs the hardware boundary. On a host that cannot meet the requirement the action is refused before it runs, never downgraded, so a model-authored command cannot execute on a host that cannot isolate it.
func NewContainmentGate ¶
func NewContainmentGate(sb sandbox.Sandbox) ContainmentGate
NewContainmentGate builds a gate that measures each action's trust against sb's containment.
func (ContainmentGate) After ¶
After is a no-op: the gate only decides admission, it holds no resource to release.
type Grant ¶
type Grant struct {
// contains filtered or unexported fields
}
Grant is the set of actions a run may perform, addressed by action name (the dispatch action a tool resolves to). The zero Grant denies everything; a Grant from NewGrant denies everything except the names it lists; AllowAll admits any action, the explicit "trusted run" policy distinct from no policy at all. A Grant is immutable once built and safe to share across goroutines.
Nothing is admitted implicitly: calling the model is an action like any other (mission.ActionModelGenerate), so a least-privilege grant lists it explicitly and the grant stays the complete, auditable record of what a run may do. A run that should not call the model simply does not grant the action.
func AllowAll ¶
func AllowAll() Grant
AllowAll returns a grant that admits every action. It is the explicit trusted-run policy: bind it when a run is fully privileged, as distinct from binding no grant at all (which is also permissive but signals "no policy set").
func FromContext ¶
FromContext returns the grant bound to ctx and whether one was present. Absent a grant the caller should treat the run as unconstrained (no policy set), which is what the Admitter does.
func NewGrant ¶
NewGrant builds a default-deny grant that admits exactly the named actions. Duplicates and empty names are ignored.
func (Grant) Actions ¶
Actions returns the granted action names in sorted order (empty when the grant is AllowAll or deny-all), for audit and introspection.
func (Grant) Intersect ¶
Intersect returns the grant admitting only the actions that BOTH grants allow. It is the no-escalation operator for delegated authority across a boundary: a caller's grant intersected with the target's own local grant yields exactly the authority the target is willing to act on for that caller, never more than either side admits. AllowAll is the identity for the operator (AllowAll intersect g is g), so a fully trusted caller is bounded by the target's local grant and a fully trusted target is bounded by the caller's grant; two AllowAll grants intersect to AllowAll. Unlike Narrow, this preserves an AllowAll operand rather than collapsing it to its (empty) action list.
func (Grant) Narrow ¶
Narrow returns the grant admitting only the actions that both this grant and the requested set allow: the intersection. It is how authority is delegated without escalation. A child run is given parent.Narrow(requested...), so its grant can never exceed the parent's, only equal or shrink it. Narrowing AllowAll yields exactly the requested actions (a trusted parent still hands a child a least-privilege grant, not blanket trust); narrowing with no actions, or with only actions the parent denies, yields deny-all.
func (Grant) Unrestricted ¶
Unrestricted reports whether the grant admits every action (AllowAll).
Source Files