Skip to content

Capability Object

Security artifact — instantiates Definition-Time Context Binding

An unforgeable reference that both names a resource and carries the authority to use it, so holding it is the permission and no ambient privilege is consulted.

A Capability Object fuses designation and authorization into a single unforgeable reference: the thing that says which resource you mean is the same thing that grants permission to act on it. Because authority travels with the reference, a behavior unit runs with exactly the powers it was handed at definition — no more — and the ambient environment is never asked "is this caller allowed?" There is no separate access-control list to consult and no privilege inherited from whoever happens to invoke the code. Its defining move against the archetype is that the authority is the context being bound at definition time: you give a unit the capabilities it needs and nothing else, so it cannot quietly acquire powers from the environment it later lands in.

Example

A photo-editing app wants a third-party plug-in to apply a filter to one image the user selected — and nothing more. The ambient-authority way would run the plug-in with the app's own file access and hope it behaves. The capability way hands the plug-in a single object: a handle that both names that one open image buffer and permits reading and writing it. The plug-in cannot enumerate the user's other files, cannot reach the network, cannot escalate — not because a policy forbids it, but because it was never given a reference that could. When the edit finishes, the app drops the handle and the authority is simply gone. A pre-signed upload URL works the same way: the URL is the permission to write one object for a short window, carried in the reference itself, needing no account login at the far end.

How it works

  • Bundle designation with authority. The reference cannot be separated from the permission; you cannot hold one without the other, and you cannot forge either.
  • Grant, don't consult. A unit acts by presenting the capability it holds, not by being checked against an ambient identity — authority flows by possession, not by lookup.
  • Attenuate on delegation. A capability can be handed on only in equal-or-weaker form (read-write narrowed to read-only, scoped to a sub-resource), so authority can shrink as it travels but never silently grow.

Tuning parameters

  • Granularity of authority — one coarse capability over a whole store, or fine-grained ones per object/operation. Finer means tighter least-authority but more handles to manage.
  • Attenuation depth — how far a capability may be narrowed and re-delegated. Deep attenuation supports rich sharing but complicates reasoning about who can do what.
  • Transferability — freely passable, bound to a holder, or non-delegable. Restricting transfer limits blast radius but reduces composability.
  • Lifetime and expiry — perpetual, session-scoped, or short-window. Shorter lifetimes shrink exposure but demand re-issuance machinery.

When it helps, and when it misleads

Its strength is that it kills a whole class of ambient-authority bugs by construction: a unit literally cannot exceed the powers in its hand, which is the cleanest defense against the confused deputy — a component tricked into misusing authority it holds ambiently on someone else's behalf.[1] The honest failure mode is that capabilities are only as contained as their propagation: a leaked capability is a leaked permission, and once handed out, a bare capability is hard to claw back — which is why revocation is a separate concern, not a property of the object itself. The classic misuse is issuing one broad, long-lived, freely-copyable capability "to keep things simple," which quietly rebuilds the ambient authority it was meant to replace. The discipline is least authority: grant the narrowest, shortest-lived capability that does the job, and route recall through a mechanism built for it.

How it implements the components

  • authority_and_capability_boundary — the object is the boundary: it delimits exactly what powers the unit carries and denies everything outside them.
  • context_minimization_filter — by handing over only the specific capability needed, it filters the unit's authority-context down to the least that works.
  • secure_secret_reference — it stands in for the underlying resource as an unforgeable, non-leaking reference, so the guarded thing is reached through the capability rather than exposed directly.

It does not, by itself, provide refresh or revocation once a capability is out — that is Revocable Authority Token's job — nor does it resolve names to stable identities across a system, which is Dependency Handle Registry.

References

[1] The confused deputy (Norm Hardy) — a program that holds authority on another party's behalf and is tricked into wielding it for a caller who lacks that authority. Capability systems dissolve the problem because authority and designation arrive together, so there is no ambient permission to be confused about. ↩