# Capability Lease

*A narrow authorization for one run, with an expiry and budgets. Child leases can only be narrower.*

> **A Capability Lease** is an authorization for specific data and specific operations, with an explicit expiry and budgets. It is issued to **one run** and is the only way a run touches the NAS. A child lease can only be narrower than its parent.

**AN-04** · Conformance level: L1 Authority · Cluster: Authority

## The problem

RBAC and ACLs assume stable users with broad, lasting permissions. An agent needs permissions cut to the task that stop when the task ends. Worse, long-lived credentials often sit where the agent can reach them: in the April 2026 incident the token was in an unrelated file, created to manage domains but able to do anything.

## How it works

- **Who holds the key.** Long-lived credentials stay with the orchestrator or the owner; a run receives a lease, not a key. The model never sees a long-lived credential.
- **A lease is an access token.** Its `authorization_details` ([RFC 9396](https://www.rfc-editor.org/rfc/rfc9396)) describe paths, actions and the branch; it is requested by the owner or orchestrator through [token exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693), the `act` claim records the delegation chain, and the NAS keeps state for revocation and budget counting.
- **Only narrowing.** A child lease must be a subset of its parent, checked by the NAS at minting time.
- **Budgets.** Bytes read and written, request counts and optionally egress bytes and a spending cap, counted at the gateway. They are a **circuit breaker**, not exact billing.
- **Policy envelope.** The owner sets a range in advance; leases inside it are issued automatically and anything outside goes to a [Human Gate](https://agentnas.com/concepts/human-gate/). Long-lived access is expressed as an envelope, not as a long-lived lease.
- **B and C are declared explicitly.** A lease states the highest sensitivity it may read and whether it may write to protected trees or send data out. These are inputs to [Trust Labels](https://agentnas.com/concepts/trust-labels/).
- **Revocation.** A short TTL (4 hours by default, 24 at most) plus immediate revocation, which cascades to child leases.
- **`purpose` is recorded, not enforced:** free text cannot be checked by a machine.

## Start small

- Write a `nas lease create` command: for each role, issue a token with a path prefix, actions and a TTL, hand it to the sandbox in an environment variable, and have the NAS enforce prefix and actions.
- This already stops the first half of that kind of incident: the token cannot do anything outside the lease.
- Budgets, delegation chains and policy envelopes can come later.

## Interface sketch

Illustrative only. Field names may change before specification v0.3.

*lease.json*

```json
{
  "lease_id": "lse_7Qk3",
  "run": "run_91ab",
  "principal": "agt_cleo",
  "on_behalf_of": "usr_wei",
  "parent": null,
  "purpose": "Draft the Q4 release notes",
  "paths": ["/shared/launch/**", "/agents/cleo/workspace/**"],
  "actions": ["read", "write", "propose"],
  "branch": "cleo/run_91ab",
  "sensitivity_max": "private",
  "egress": false,
  "requires_gate": ["merge", "delete", "share"],
  "budgets": { "bytes_read": 200000000, "bytes_written": 5000000, "requests": 5000 },
  "expires_at": "2026-11-12T16:00:00Z"
}
```

## What the specification asks for

- A lease MUST have an expiry and MUST NOT be renewed beyond the maximum TTL; renewal requires a new issuance.
- A child lease MUST be a subset of its parent, and the NAS MUST verify this when minting.
- Revoking a lease MUST cascade to all of its child leases.
- Long-lived access MUST be expressed as a policy envelope and MUST NOT be made a long-lived lease.
- A lease MUST declare its sensitivity ceiling and whether it allows egress and protected writes.
- Long-lived credentials MUST NOT be exposed to a model or a run.

## Borrowed, and what is new

What follows is all established parts. **What is new:** taking the **shape of a run and a task** as the unit and putting the branch, budgets and the Rule of Two properties into one lease. Tokens and capability models themselves are not new.

- [OAuth Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693)
- [OAuth Rich Authorization Requests (RFC 9396)](https://www.rfc-editor.org/rfc/rfc9396)
- [Biscuit](https://github.com/biscuit-auth/biscuit)
- [UCAN](https://ucan.xyz/specification/)
- [IETF attenuating agent tokens draft](https://datatracker.ietf.org/doc/draft-niyikiza-oauth-attenuating-agent-tokens/)

## Honest limits

- It only covers operations inside the NAS and cannot govern what an agent does elsewhere.
- `purpose` cannot be enforced, and budgets are approximate.
- A lease cannot prevent misuse **within legitimate authority**; that is the work of branches and gates.

## Open questions

- How can `purpose` move from free text to structured intent a machine can check?
- How are budgets accounted for under federation?

## Questions

### How is a lease different from an API key?

An API key is a long-lived shared secret, and its holder can do whatever the account can. A lease is bound to one run, limits paths, actions and time, and can only be narrowed; it stops working at expiry and can be revoked at any time.

### Why not just use OAuth?

It is OAuth: a lease is an access token, requested through token exchange (RFC 8693) and described with rich authorization requests (RFC 9396). Agent NAS only adds what OAuth does not specify: the run as the unit, and putting the branch, budgets and Rule of Two properties into one authorization.

### What happens to a run when its lease expires?

The mount turns read-only and is then unmounted; new requests are refused and recorded. The branch is kept until its own TTL expires, so finished work is not lost and can still be merged after review.

## Related concepts

- [Human Gate](https://agentnas.com/concepts/human-gate/): Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff.
- [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two.
- [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read.

---

Canonical URL: https://agentnas.com/concepts/capability-lease/
Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0