1  # Delegation
  2  
  3  How authority flows from a human operator to an AI agent (or any automated system), and how verifiers trace actions back to the authorizing human.
  4  
  5  ## The delegation model
  6  
  7  Auths delegation is a cryptographic chain of signed attestations. Each link in the chain grants a subset of the parent's capabilities to a child entity. Capabilities can only narrow at each hop — never widen.
  8  
  9  ```mermaid
 10  graph TD
 11      H["<b>Human</b><br/>did:keri:EHuman..."]
 12  
 13      H -- "signs attestation" --> A
 14  
 15      A["<b>AI Agent</b><br/>did:keri:EAgent...<br/><br/>capabilities: sign:commit, deploy:staging<br/>signer_type: Agent<br/>delegated_by: did:keri:EHuman..."]
 16  
 17      A -- "delegates subset" --> S
 18  
 19      S["<b>Sub-Agent</b><br/>did:keri:ESubAgent...<br/><br/>capabilities: deploy:staging<br/>signer_type: Agent<br/>delegated_by: did:keri:EAgent..."]
 20  ```
 21  
 22  ## Step 1: Human creates identity and links a device
 23  
 24  The human operator creates a KERI identity and links their device:
 25  
 26  ```bash
 27  auths init
 28  ```
 29  
 30  This produces an inception event and a device attestation:
 31  
 32  ```json
 33  {
 34    "version": 1,
 35    "issuer": "did:keri:EHuman123...",
 36    "subject": "did:key:z6MkHumanDevice...",
 37    "capabilities": ["sign:commit", "deploy:staging", "deploy:production"],
 38    "signer_type": "Human",
 39    "expires_at": null
 40  }
 41  ```
 42  
 43  The human's attestation has no `delegated_by` — this is the root of the chain.
 44  
 45  ## Step 2: Human issues attestation to an AI agent
 46  
 47  The human creates a scoped, time-limited attestation granting specific capabilities to an agent:
 48  
 49  ```bash
 50  auths attestation issue \
 51    --subject did:key:z6MkAgentDevice... \
 52    --signer-type Agent \
 53    --capabilities "sign:commit,deploy:staging" \
 54    --delegated-by did:keri:EHuman123... \
 55    --expires-in 24h
 56  ```
 57  
 58  The resulting attestation:
 59  
 60  ```json
 61  {
 62    "version": 1,
 63    "issuer": "did:keri:EHuman123...",
 64    "subject": "did:key:z6MkAgentDevice...",
 65    "capabilities": ["sign:commit", "deploy:staging"],
 66    "signer_type": "Agent",
 67    "delegated_by": "did:keri:EHuman123...",
 68    "expires_at": "2026-03-05T12:00:00Z",
 69    "identity_signature": "aabb...",
 70    "device_signature": "ccdd..."
 71  }
 72  ```
 73  
 74  Notice:
 75  
 76  - **Capabilities narrowed**: The agent gets `sign:commit` and `deploy:staging`, but not `deploy:production`.
 77  - **Time-bounded**: The attestation expires in 24 hours.
 78  - **`delegated_by`** points to the human's identity, creating the accountability link.
 79  - **Dual-signed**: Both the human's identity key and the agent's device key sign the attestation.
 80  
 81  ## Step 3: Agent acts and signs artifacts
 82  
 83  The agent uses its attestation to sign commits, deploy to staging, or perform any action within its granted capabilities. Each signature is produced by the agent's own private key.
 84  
 85  If the agent needs to delegate further — for example, spawning a sub-agent for a specific task — it issues a new attestation with further-narrowed capabilities:
 86  
 87  ```json
 88  {
 89    "version": 1,
 90    "issuer": "did:keri:EAgent456...",
 91    "subject": "did:key:z6MkSubAgent...",
 92    "capabilities": ["deploy:staging"],
 93    "signer_type": "Agent",
 94    "delegated_by": "did:keri:EAgent456...",
 95    "expires_at": "2026-03-05T06:00:00Z"
 96  }
 97  ```
 98  
 99  The sub-agent's capabilities are a strict subset of the parent agent's. The expiration is shorter. The chain grows but authority only shrinks.
100  
101  ## Step 4: Verifier walks the chain
102  
103  When a relying party receives a signed artifact, it verifies the full attestation chain using `verify_chain()`:
104  
105  ```bash
106  auths verify --attestation-chain chain.json
107  ```
108  
109  The verifier checks, from leaf to root:
110  
111  1. **Sub-Agent → Agent**: Is the sub-agent's attestation signed by the agent? Are the sub-agent's capabilities a subset of the agent's? Is it expired?
112  2. **Agent → Human**: Is the agent's attestation signed by the human? Are the capabilities valid? Is it expired?
113  3. **Human → KEL**: Does the human's identity key match the current key in the Key Event Log?
114  
115  If any link fails — invalid signature, expired attestation, capability not granted — the entire chain is rejected.
116  
117  The verification is a pure computation. No network call. No central authority. The verifier needs only the attestation chain and the root public key.
118  
119  ## Capability narrowing
120  
121  Capabilities follow a strict narrowing rule across delegation hops:
122  
123  | Hop | Entity | Capabilities |
124  |-----|--------|-------------|
125  | Root | Human | `sign:commit`, `deploy:staging`, `deploy:production` |
126  | Hop 1 | Agent | `sign:commit`, `deploy:staging` |
127  | Hop 2 | Sub-Agent | `deploy:staging` |
128  
129  A child can never grant capabilities it does not possess. The OIDC bridge enforces this at token exchange time through intersection-based scope-down: the issued JWT contains only the intersection of the chain-granted capabilities and the capabilities the agent requests.
130  
131  ## Cloud access via OIDC
132  
133  Once an agent has a valid attestation chain, it can exchange it for a standard JWT through the [OIDC bridge](../architecture/oidc-bridge.md):
134  
135  1. Agent presents its attestation chain to the bridge's `/token` endpoint
136  2. Bridge verifies the chain cryptographically (no IdP callback)
137  3. Bridge issues a standard RS256 JWT with the agent's capabilities as claims
138  4. Agent uses the JWT with AWS STS, GCP Workload Identity, or Azure AD
139  
140  The JWT includes `keri_prefix`, `capabilities`, and `delegated_by` provenance — so cloud-side audit logs can trace the action back through the full delegation chain to the originating human.