Runtime Capability System
The capability system is the security foundation of ElastOS Runtime. Every action (reading a file, writing state, making a network call, invoking a provider) requires a valid capability token. Nothing happens by default. For the conceptual overview, see Design Principles.
Ambient Authority vs. Scoped Tokens
PC2 v1 uses ambient authority: one session token grants access to everything. When you log in, every service, file, and API is available to every part of the system.
Runtime v2 uses scoped capability tokens: each token grants access to one specific resource for one specific action, with time limits and use-count limits. Instead of "logged in = full access," every individual action must be explicitly authorized.
12-Step Token Validation
Every capability token invocation goes through 12 validation checks:
- Signature verification -- Ed25519 signature on the token is valid
- Holder matches -- the requesting capsule matches the token's designated holder
- Resource scope -- the requested resource matches the token's resource scope
- Action matches -- the requested operation matches the token's allowed action
- Not expired -- the token's time limit has not passed
- Use count -- the token's maximum use count has not been exceeded
- Epoch is current -- the token was issued in the current epoch (not mass-revoked) 8-12. Additional validation checks (not fully public yet)
If any check fails, the action is denied. There is no partial pass.
Epoch Mechanism
The runtime maintains a monotonic epoch counter. Incrementing the epoch invalidates ALL previously issued tokens at once -- a kill switch for compromised capsules. New tokens must be requested under the new epoch.
Precise Access Tokens
Capability tokens are scoped along four dimensions:
| Dimension | What It Controls |
|---|---|
| Read | Access to read from a specific path or resource |
| Write | Access to write to a specific path or resource |
| Network | Access to make network calls to specific endpoints |
| Provider | Access to invoke a specific provider contract |
Tokens are granular. Some examples:
- An agent might receive a read token for
localhost://Users/self/Documents/Calendar/*; it can read calendar entries but nothing else. - A capsule might get read access to Notes and write access only to Drafts; it can consume existing notes but only create new content in a specific directory.
- A viewer might receive read access to Pictures without any access to Documents.
Tokens are also short-lived where appropriate. An agent performing a one-time task can receive a token that expires after use, rather than holding a persistent grant.
Auditable and Revocable
- Auditable. The runtime logs capability grants and exercises in an append-only audit trail. You can see what tokens were issued, to whom, and when they were used.
- Revocable. Tokens can be revoked at any time. A revoked token immediately stops working; the runtime validates tokens at the enforcement boundary, not at grant time.
- Fail-closed. If a token is missing, expired, or revoked, the action fails. The runtime does not attempt to infer intent or fall back to a permissive mode.
Runtime-Side Validation
Capability validation happens in the runtime, not inside the capsule or agent:
- Capsules cannot bypass validation by modifying their own code.
- The runtime is the single enforcement point for all capability checks.
- Validation occurs at the boundary between the capsule and the system; every call crosses this boundary and is checked.