# AEGIS — Capability-Based Security Model

- **Document ID:** ARCH-08
- **Phase:** B.1 — Structural Foundations
- **Status:** Draft for review (post independent architecture review)
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect
- **Depends on:** ARCH-01 through ARCH-07, CLAUDE.md
- **Consumed by:** ARCH-09 through ARCH-16

---

## 1. Purpose

Specify AEGIS's authorization model. The constitution disallows role-only authorization. Every privileged action requires an explicit, unforgeable, revocable, auditable **capability**. This document defines what a capability is, how it is minted, delegated, verified, revoked, and audited, and how it composes with RBAC for humans.

## 2. Model Summary

- **Object-capability model** for machine-to-machine authorization: a **capability token** is a signed, scoped, expiring, revocable, minimally-privileged bearer credential that proves the holder is entitled to a specific operation on a specific resource, in a specific tenant, at a specific classification.
- **RBAC-for-humans layer** sits on top: humans hold roles that translate (via Identity Engine → Kernel) into a bounded set of held capabilities and delegation rights, subject to session state.
- **Kernel is the sole capability broker.** Only the Kernel mints and verifies capabilities.
- **Data-plane enforcement** (Kafka/Redpanda topic ACLs, ClickHouse row policies) is bound to capabilities so structural enforcement backs up token verification.

## 3. Anatomy of a Capability

A capability is a compact, signed structure. Illustrative fields (final schema in ARCH-09 / ARCH-11):

```
Capability {
  id                : UUID                   // unique per issuance
  version           : uint                   // schema version
  issuer            : DID                    // Kernel identity
  subject           : DID                    // holder identity (engine or human agent)
  tenant            : TenantId               // scoped to a tenant (or a batch, or a global mode)
  operation         : OperationName          // e.g., "Read-Logs"
  resource          : ResourcePredicate      // e.g., "case_id in {…}" or "topic=ingest.raw.*"
  classification_max: ClassificationLevel    // P/I/C/R/HR maximum this cap permits
  constraints       : {                      // additional structured constraints
    time_window     : Interval               // valid_from, valid_until
    concurrency_max : uint                   // parallel-use cap
    rate_max        : Rate                   // e.g., 10/s
    payload_max     : Bytes
    context_tags    : [Tag]                  // e.g., "break-glass", "consent-record:<id>"
  }
  delegable         : bool                   // whether the holder may delegate
  delegation_chain  : [Delegation]           // (issuer→subject)* trail if delegated
  attestation       : ProofSet               // signatures at each step
  audit_ref         : AuditEventId           // link to the audit record for issuance
}
```

Design notes:
- Tokens are **short-lived** (see §7).
- Tokens are **cryptographically signed** by the Kernel and by each delegator (§5).
- Tokens are **verifiable offline** by any component that trusts the Kernel's public key — verification does not require calling the Kernel per token.
- Tokens are **revocable** via the revocation list broadcast on NATS (§8).

## 4. Named Capabilities

A capability's **operation** name is drawn from a fixed, versioned vocabulary. This section defines the v0 vocabulary. Adding a capability requires an architecture-review change; renaming or removing requires a deprecation cycle.

Capabilities are grouped by concern. Every capability is auditable at issuance and at every use.

### 4.1 Ingest and Data

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Publish-Ingest` | Publish to raw ingest topics | Connector Engine (per source) | 15 min |
| `Read-Raw` | Read raw events | Normalization Engine; Case Engine (bundled) | 10 min |
| `Publish-Normalized` | Publish normalized events | Normalization Engine | 15 min |
| `Read-Normalized` | Read normalized events | Detection Engine; AI Engine (scoped); Case Engine | 10 min |
| `Read-Logs` | Broad read of ingested logs (analyst-facing) | Analyst role via Kernel | 5 min |
| `Write-Findings` | Write findings from correlation | Detection Engine | 15 min |
| `Read-Findings` | Read findings | Case Engine; AI Engine (scoped); Analyst | 5 min |

### 4.2 Cases and Timelines

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Write-Case` | Create/update a case | Case Engine; Analyst | 5 min |
| `Append-Timeline` | Append an annotation to a case timeline | Case Engine; Analyst; AI Engine (validated) | 5 min |
| `Export-Case` | Produce a signed evidence bundle for a case | Analyst; Auditor | 2 min (one-shot) |
| `Read-Case` | Read case + timeline | Analyst; Auditor | 5 min |

### 4.3 Detection Rules

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Read-Rules` | Read Sigma rules | Detection Engine; Security Engineer | 10 min |
| `Author-Rule` | Create or modify a rule | Security Engineer | 5 min |
| `Delete-Rule` | Delete a rule | Security Engineer + break-glass | 2 min (one-shot) |
| `Approve-Rule` | Approve a rule change (4-eyes) | Security Engineer (other than author) | 5 min |

### 4.4 AI

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Invoke-AI-L1` | Invoke deterministic engine | AI Engine (any classification) | 10 min |
| `Invoke-AI-L2` | Invoke local model | AI Engine (P/I/C/R; HR requires stricter Safety Layer bound) | 10 min |
| `Invoke-AI-L3` | Invoke hosted frontier model | AI Engine (P/I/C only by default; R with consent; HR forbidden by default) | 5 min |
| `Read-Evidence` (case-scoped) | Read case-scoped evidence for AI reasoning | AI Engine (scoped to a case, time-boxed) | 5 min |
| `Publish-Recommendation` | Publish an AI recommendation to Safety Layer | AI Engine | 10 min |
| `Publish-Validated-Recommendation` | Publish validated rec to Case Engine | Safety Layer | 10 min |

### 4.5 Policy and Identity

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Modify-Policy` | Alter policy rules | Admin + 4-eyes | 2 min (one-shot) |
| `Read-Policy` | Read policy corpus | Analyst; Auditor; Engines | 10 min |
| `Modify-RBAC` | Change role assignments | Admin + 4-eyes | 2 min (one-shot) |
| `Create-User` | Provision a user | Admin | 5 min |
| `Delete-User` | Delete a user (subject to legal-hold) | Admin + break-glass | 2 min (one-shot) |

### 4.6 Secrets and Keys

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Read-Secret` | Retrieve a secret from the vault | Named engine + specific secret ID | 60 sec (one-shot) |
| `Rotate-Secret` | Rotate a secret | Admin + 4-eyes | 5 min (one-shot) |
| `Sign-Bundle` | Sign an evidence bundle | Case Engine + Kernel | 60 sec (one-shot) |
| `Sign-Audit-Batch` | Sign a Layer-B audit batch | Audit Engine | 60 sec (one-shot) |

### 4.7 Connectors and Plugins

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Create-Connector` | Add or configure a connector | Admin | 5 min |
| `Enable-Connector` | Enable a configured connector | Admin | 5 min |
| `Install-Plugin` | Install a signed plugin | Admin + 4-eyes | 5 min (one-shot) |
| `Grant-Plugin-Capability` | Grant a plugin a scoped capability | Admin + 4-eyes | 5 min (one-shot) |
| `Kill-Plugin` | Halt a plugin execution | Admin; automated Detection anomaly | 60 sec (one-shot) |

### 4.8 Recovery and Response

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Read-Snapshot` | Read backup snapshot metadata | Recovery Engine; Admin | 5 min |
| `Write-Snapshot` | Create a snapshot | Recovery Engine | 5 min |
| `Execute-Recovery` | Execute a restore | Admin + 4-eyes + break-glass | 2 min (one-shot) |
| `Propose-Response` | Emit a proposed response action | Case Engine; AI Engine (validated) | 5 min |
| `Execute-Response` (Phase 3) | Execute an automated response | Response Engine + 4-eyes + policy gate | N/A in v0 |

### 4.9 Audit and Reports

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Read-Audit` | Read audit records | Auditor; Admin (scoped) | 5 min |
| `Export-Reports` | Produce a signed report | Auditor; Admin | 2 min (one-shot) |
| `Read-Telemetry` | Read AEGIS-self telemetry | Ops; Admin | 5 min |

### 4.10 Break-Glass and Admin

| Capability | Meaning | Typical holder | Default TTL |
|---|---|---|---|
| `Request-BreakGlass` | Initiate a break-glass request | Any human with role | 5 min (one-shot) |
| `Approve-BreakGlass` | Approve a break-glass request | Approver role (distinct from requester) | 2 min (one-shot) |
| `Break-Glass-Session` | Elevated session capability (composition of scoped capabilities) | Requester after approval | ≤ 30 min, always ≤ requested duration |
| `Freeze-Kernel-Issuance` | Halt new capability issuance (incident kill-switch) | Owner + 4-eyes | 60 sec (one-shot); revocable via ceremony |
| `Rotate-Kernel-Identity` | Trigger Kernel identity rotation | Owner + Z0 approvers | 5 min (one-shot) |

TTLs above are defaults; policy may shorten. TTLs may not be extended without an audited policy exception.

## 5. Delegation

Capabilities are **delegable** only if `delegable = true` at issuance. Delegation rules:

- **Attenuation only.** A delegated capability may be more restrictive than the parent, never broader (narrower `resource`, shorter `time_window`, lower `classification_max`, lower `rate_max`, etc.).
- **Signed chain.** Every delegation adds a signature by the delegator; verification walks the chain and requires each step's signer to be a valid holder at delegation time.
- **Chain length bound.** Default max chain length is 3 to keep verification simple; longer chains require an explicit policy exception.
- **Revocation is transitive.** Revoking a parent revokes every delegated child.
- **Tenant boundaries not crossable by delegation.** Cross-tenant reach still requires break-glass.

## 6. Verification

Two-tier verification:

1. **Kernel verification (authoritative).** On operations requiring fresh authorization (issuance, break-glass, modify-policy, delete, execute-recovery), the Kernel verifies the token, the delegation chain, the revocation state, the requesting identity's freshness, and consults the Policy Engine.
2. **Engine-side verification (cached / offline).** For cached tokens with a valid TTL, engines verify signature + delegation chain + tenant match + classification match + expiry, and enforce constraints locally. The Kernel is not on the hot path.

**Data-plane enforcement backs up token verification.** Even if a token is bypassed, Kafka topic ACLs and ClickHouse row policies constrain what an engine identity can do. Two independent enforcement layers, not one.

## 7. TTL and Refresh

TTLs are chosen to bound revocation exposure while not overwhelming the Kernel. Guidelines:

- **One-shot capabilities** (destructive, high-risk) — expire on use or in ≤ 60s, whichever first.
- **Privileged capabilities** — ≤ 5 minutes.
- **Broad read capabilities** — ≤ 10 minutes.
- **Publish/consume (broker-backed)** — ≤ 15 minutes (broker ACL is the backstop).
- **Session-derived human capabilities** — bounded by session TTL; refreshed on interaction; MFA re-prompt on interval or on sensitivity uplift.

Refresh is automatic and requires the engine to still be attested and unrevoked.

## 8. Revocation

- **Individual revocation.** Kernel writes to the revocation list and broadcasts on NATS.
- **Batch revocation.** Whole delegation subtree, all capabilities issued to an identity, or all capabilities of an operation class.
- **Emergency revocation.** `Freeze-Kernel-Issuance` capability halts new issuance globally; combined with mass revocation of active tokens is the incident kill-switch.
- **Propagation delay.** Bounded by TTL + broadcast latency; typically < 1s in-cluster, ≤ TTL under NATS outage.
- **Data-plane backstop.** Broker ACLs and DB row policies are updated in the same transaction as the revocation write; even if a client caches a stale token, it will hit ACL denials.

## 9. RBAC for Humans

Humans hold **roles**, not capabilities directly. Identity Engine translates role + session context into a bounded set of *held-and-delegable* capabilities, which the Kernel issues on demand.

v0 roles (revised from ARCH-02 to match capability model):

| Role | Purpose | Held capabilities (illustrative) |
|---|---|---|
| **Owner** | Ultimate admin | All admin caps; requires 4-eyes on destructive ops; can approve break-glass |
| **Admin** | Tenant administration | Modify-RBAC, Create-Connector, Install-Plugin, Read-Audit, Rotate-Secret |
| **Security Engineer** | Detection engineering | Author-Rule, Approve-Rule, Read-Logs, Read-Normalized, Read-Findings |
| **Analyst** | Case investigation | Read-Logs, Read-Findings, Read-Case, Append-Timeline, Write-Case, Request-BreakGlass |
| **Auditor** | Read-only + evidence export | Read-Audit, Read-Case, Export-Reports |
| **Read-Only** | Observability | Read-* subset |

Attribute-based extensions (ABAC) allowed for scoping (case-scoped, time-scoped, resource-scoped) — encoded as capability constraints, not new roles.

## 10. Audit Contract

Every capability event produces a Layer-A audit record. Distinct event types:

- `capability.issued`
- `capability.delegated`
- `capability.verified` (batched to avoid audit-flood; per-N summary + anomaly alerts)
- `capability.denied`
- `capability.revoked`
- `capability.expired`
- `break_glass.requested`, `break_glass.approved`, `break_glass.denied`, `break_glass.consumed`, `break_glass.expired`
- `capability.freeze` (incident kill-switch)

Anomaly detection watches for: unusual issuance patterns, unusual delegation depth, capability drift by an identity, denied-then-immediately-retried patterns, break-glass overuse.

## 11. UI Surface

Analysts should not see raw tokens. The UI surfaces capabilities as:
- **Human-readable operation labels** with the tenant/resource scope.
- **Session capability inventory** on demand (`/capabilities`).
- **Break-glass request UX** with clear justification prompts and approval flow.
- **4-eyes prompts** integrated inline for admin operations.
- **Audit view** for capability history per identity.

## 12. Interoperability with External Systems

- **OIDC** claims can be mapped to roles; roles then map to capabilities per §9. Mapping is versioned per tenant.
- **SAML/SCIM** (v1) similarly mapped.
- **Machine credentials** for connectors are provisioned with narrow capabilities and short TTLs; connector renewal is auditable.

## 13. Independent Architecture Review

### 13.1 Hidden Assumptions

| Assumption | Handling |
|---|---|
| Capability tokens fit in typical HTTP/gRPC headers. | Compact CBOR-encoded tokens with truncated signatures where safe; long chains truncated by chain-length bound (§5). |
| Broker ACLs can be updated in near-real-time. | Kafka/Redpanda ACL updates are fast; ClickHouse row policies are per-user; testing verifies. |
| Engines can reliably discover the current revocation list. | Two channels: NATS broadcast (primary) + Kernel pull on TTL refresh (backup). Signed revocation list header prevents forged "empty" list. |
| Humans will not be capability-fatigued by frequent 4-eyes prompts. | 4-eyes reserved for destructive/highly-privileged actions; guidelines documented in ARCH-12. |

### 13.2 SPOFs

| Finding | Response |
|---|---|
| **F-1.** *Kernel is the only capability broker — outage halts issuance.* | Cached tokens absorb outages up to TTL; HA Kernel per ARCH-06; degraded-mode allows read-only continuation of cached-capability operations. |
| **F-2.** *Revocation list broadcast lag can leave stale tokens active.* | Bounded by TTL (§7); data-plane backstops constrain effective damage; anomaly detection watches for behavior mismatched to revocation state. |
| **F-3.** *Broker ACL update service is a SPOF.* | Kernel writes ACL updates through Storage Engine to the broker's control plane; failures are retried; audit-visible; degraded-mode blocks new grants until healed. |

### 13.3 Privilege Escalation

| Finding | Response |
|---|---|
| **F-4.** *Delegation lets a holder grant broader than they hold.* | Attenuation-only rule + Kernel enforcement + signed chain + property tests. Structural. |
| **F-5.** *Compromised engine mints delegated tokens to a puppet.* | The puppet is another identity; capabilities scoped to that puppet do not expand reach; every delegation audited; anomalous delegation graph alerts. |
| **F-6.** *Break-glass approver colludes with requester.* | Multi-party approval required for the highest-risk operations; approver role separation enforced; approvals themselves logged with reasons; post-hoc review by Auditor. |
| **F-7.** *Human retains a session capability past their termination.* | Identity revocation cascades to capability revocation immediately; session cache TTLs shorter than typical HR delay; termination runbook explicit. |

### 13.4 Trust-Boundary Violations

| Finding | Response |
|---|---|
| **F-8.** *Token intended for tenant A used in tenant B request.* | Tenant scope is bound to the caller's identity, not the token payload; Kernel refuses tenant mismatch. |
| **F-9.** *Cached token used after classification uplift of the resource.* | Classification is evaluated per operation at boundary crossing; if resource's classification exceeds token's `classification_max`, refusal. |
| **F-10.** *Token replayed after operation completes (one-shot bypass).* | One-shot tokens are marked consumed in a Kernel-side used-token bloom (with periodic reset via TTL); replay is detected within the TTL window. Beyond TTL, expiry catches. |

### 13.5 Bottlenecks

| Finding | Response |
|---|---|
| **F-11.** *Every op with a fresh Kernel round-trip would saturate the Kernel.* | Cached tokens per D-05-2 mean most ops are engine-local verify; issuance rate is bounded by TTL rotation; Kernel target throughput met per ARCH-06 §8. |
| **F-12.** *Delegation chains slow verification for deeply delegated tokens.* | Max chain length = 3; verification is O(chain); benchmarks in ARCH-12. |
| **F-13.** *Broker ACL churn under many short-lived capabilities is heavy.* | ACLs align to identity + operation class + resource-prefix, not to per-issuance token; churn is on the order of identity/config changes, not per-token. |

### 13.6 Supply Chain Risks

| Finding | Response |
|---|---|
| **F-14.** *Vulnerable CBOR/JWS library taints token handling.* | Hash-pinned dependencies; own thin wrapper for signature verification; property tests. |
| **F-15.** *Rego-like policy engine dependency compromise.* | Policy Engine is replaceable per C-12; independent of capability model; kill-switch (§4.10) freezes new issuance if compromise suspected. |

### 13.7 AI-Specific Risks

| Finding | Response |
|---|---|
| **F-16.** *AI Engine tricked into requesting `Invoke-AI-L3` for HR data via prompt injection.* | Classification is not derivable from the prompt; comes from the data-plane metadata; Kernel refuses request that violates classification policy; Safety Layer refuses too. |
| **F-17.** *Prompt-injected instructions try to induce `Publish-Recommendation` bypass into `Publish-Validated-Recommendation`.* | AI Engine cannot hold `Publish-Validated-Recommendation`; that capability is exclusive to the Safety Layer. Impossible by construction. |
| **F-18.** *A plugin embedded in a case attempts to obtain `Read-Audit`.* | Plugins have only capabilities explicitly granted by admin + 4-eyes; audit is not grantable to plugins in v0. |

### 13.8 Operational Risks

| Finding | Response |
|---|---|
| **F-19.** *Alert fatigue from `capability.verified` events.* | Verified events are batched/aggregated and only trigger alerts on anomaly patterns. Issuance, denial, delegation, revoke, and break-glass events remain individual. |
| **F-20.** *Broken policy locks out even admins.* | A minimal invariant policy set — including "admins can always request break-glass with the right approval quorum" — is baked into the Kernel and cannot be removed via UI; changes require Owner + Z0 approval per ARCH-06. |
| **F-21.** *Capability schema evolution breaks older engines.* | Versioned tokens; wire-compat within major; deprecation cycle documented. |

## 14. Decisions

### D-08-1. Object-capability tokens + RBAC for humans

- **Advantages.** Fine-grained; unforgeable; delegable; revocable; auditable; enforced at both control and data plane.
- **Disadvantages.** More concepts than pure RBAC; UI must surface humanely.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** *Neutral to positive* — cached verification is fast; issuance rate is bounded.
- **Operational Complexity.** *Moderate* — capability inventory and audit views required.
- **Maintainability.** *Positive* — the vocabulary is enumerated; adding an operation is a review-gated change.
- **Scalability.** *Positive.*
- **Alternative Designs.** *(a) RBAC-only.* Cannot express per-resource, per-time, per-classification scoping without proliferating roles. Rejected. *(b) Pure ABAC.* Powerful but expresses less structurally; harder to reason about revocation. Rejected as primary. *(c) OAuth 2 scopes.* Not fine-grained enough; not delegable with attenuation. Rejected as primary.
- **Reason.** Object-capability best fits constitutional constraint #3 and integrates cleanly with Kernel + boundary contract.

### D-08-2. Attenuation-only delegation with signed chain

- **Advantages.** Structural prevention of privilege inflation; auditable chain.
- **Disadvantages.** Slightly larger tokens; verification cost O(chain).
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** *Small.*
- **Operational Complexity.** *Moderate.*
- **Maintainability.** *Positive.*
- **Scalability.** *Positive.*
- **Alternatives.** *No attenuation (delegate = re-issue).* Loses history; rejected. *Amplifying delegation.* Explicit anti-pattern; rejected.
- **Reason.** Historical attenuation is the definitional safety property of ocap systems.

### D-08-3. Data-plane backstop (broker + DB) bound to capabilities

- **Advantages.** Second layer of enforcement; defense in depth; limits damage of forged/stolen tokens.
- **Disadvantages.** ACL churn management.
- **Security Impact.** *Strongly positive.*
- **Performance Impact.** *Neutral.*
- **Operational Complexity.** *Moderate* — automated by Kernel-driven config.
- **Maintainability.** *Positive.*
- **Scalability.** *Positive.*
- **Alternatives.** *Token-only enforcement.* Trusts client-side verification alone; rejected.
- **Reason.** Belt-and-braces is our constitutional posture.

### D-08-4. Named capability vocabulary as an architectural artifact

- **Advantages.** Clarity; auditability; change is deliberate; UI is coherent.
- **Disadvantages.** Adding a capability is heavier than adding a role or scope.
- **Security Impact.** *Positive.*
- **Performance Impact.** Neutral.
- **Operational Complexity.** *Positive net* — smaller vocabulary is easier to reason about.
- **Maintainability.** *Positive.*
- **Scalability.** N/A.
- **Alternatives.** *Free-form scope strings.* Drifts, hard to audit; rejected.
- **Reason.** Explicit vocabulary is the honest surface for privilege in a security-critical system.

## 15. Open Questions

- Q-08-1. Token encoding — CBOR-JWS/JOSE vs. protobuf + Ed25519 native. Recommendation: **protobuf + Ed25519** for speed and simplicity, wrap-compatible for JOSE consumers if needed. Resolved in ARCH-09/12.
- Q-08-2. Consumed-token bloom retention window. Resolved in ARCH-11 / ARCH-13.
- Q-08-3. Exact policy DSL choice. Resolved in ARCH-12.
- Q-08-4. Human-facing 4-eyes UX (in-UI approval vs. side-channel signing). Resolved in Phase C or ARCH-16.

## 16. Change Log

- **0.1 (2026-07-10)** — Initial draft after independent architecture review.