# Architecture

`delegated` separates signed claims from trusted runtime facts.

## Participants

- **Issuer:** decides authority and signs a `DelegatedCapability` with Ed25519.
- **Bearer:** transports the signed capability. Possession is sufficient to present it.
- **Resource server:** owns trusted issuer configuration, derives the operation that will execute,
  checks mutable security state, and acts only after an allow decision.

The bearer is untrusted. The request envelope cannot select a verification key or describe the
operation being authorized.

## Data flow

1. The issuer builds a capability containing agent/delegator assertions, audiences, actions,
   optional resources, optional maximum delegation depth, lifetime, nonce, and key identifier.
2. The resource server receives a strict `DelegatedRequest` containing that capability.
3. The resource server constructs `OperationContext` from its route, tool dispatcher, validated
   target, and trusted delegation metadata.
4. `Evaluator` resolves `(issuer, key_id)` using `IssuerKeyResolver` and verifies the signature.
5. The evaluator checks lifetime, revocation, emergency deny, and exact operation binding.
6. The evaluator atomically consumes the issuer-scoped nonce.
7. The host persists the returned `AuditEvent` and executes only an allow decision.

## Security boundaries

| Input | Trust level | Source |
|---|---|---|
| Request bytes | Untrusted | Bearer/network |
| Capability claims | Trusted only after signature verification | Trusted issuer |
| `OperationContext` | Trusted | Resource server |
| Issuer keys | Trusted | Host configuration/key service |
| Revocation/replay state | Trusted | Host state backend |
| Evaluation time | Trusted | Host clock |

## Public extension points

- `IssuerKeyResolver`: integrate pinned configuration, KMS-backed metadata, or a verified key
  registry. It returns verification keys, not signing keys.
- `TrustStateStore`: integrate shared revocation, emergency-deny, and replay storage. Nonce
  check-and-insert must be atomic.
- `AuditSink`: integrate durable logging. Use `evaluate_and_audit` when failure to persist must
  prevent an allow from being returned.

The included in-memory implementations are references for tests and single-process services, not
distributed production storage.
