Merge pull request #13 from devonartis/docs/delegation-accuracy

docs: tech editor pass + delegation accuracy fix

Author: devonartis

README.md

@@ -15,6 +15,20 @@
   Built on Ed25519 challenge-response and the <a href="https://github.com/devonartis/AI-Security-Blueprints/blob/main/patterns/ephemeral-agent-credentialing/versions/v1.3.md">Ephemeral Agent Credentialing v1.3</a> pattern.
 </p>
 
+<p align="center">
+  <a href="#why-agentwrit">Why</a> ·
+  <a href="#installation">Install</a> ·
+  <a href="#prerequisites">Prerequisites</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#agent-lifecycle">Lifecycle</a> ·
+  <a href="#medassist-ai-demo">Demo</a> ·
+  <a href="#scope-format">Scopes</a> ·
+  <a href="#delegation">Delegation</a> ·
+  <a href="#error-handling">Errors</a> ·
+  <a href="#architecture">Architecture</a> ·
+  <a href="#documentation">Docs</a>
+</p>
+
 ---
 
 ## Why AgentWrit?
@@ -24,9 +38,9 @@ AI agents need credentials to access databases, APIs, and file systems. Most tea
 - **Ephemeral identities** — every agent gets a unique Ed25519 keypair, generated in memory and never persisted to disk
 - **Task-scoped tokens** — credentials are limited to exactly what the agent needs (`read:data:customers`, not `read:*:*`)
 - **Short-lived by default** — tokens expire in minutes, not hours or days
-- **Delegation chains** — agents can delegate narrower permissions to other agents, enforced at every hop
+- **Delegation chains** — agents can delegate a subset of their permissions to other agents; the broker rejects any attempt to widen
 
-This SDK is the Python client for the [AgentWrit broker](https://github.com/devonartis/agentwrit). The broker is the credential authority; this SDK makes it easy to integrate from Python.
+This SDK is the Python client for the [AgentWrit broker](https://github.com/devonartis/agentwrit) — the broker is the credential authority, and this SDK is how your Python code talks to it.
 
 ## Installation
 
@@ -50,19 +64,53 @@ cd agentwrit-python
 uv sync --all-extras
 ```
 
-**Requirements:** Python 3.10+ and a running [AgentWrit broker](https://github.com/devonartis/agentwrit) instance.
+**Requirements:** Python 3.10+. The SDK also needs a broker and credentials — see [Prerequisites](#prerequisites).
+
+## Prerequisites
+
+The SDK is a client. It does **not** run the broker, and it does **not** mint its own credentials. Before any code in [Quick Start](#quick-start) will work, you need three things:
+
+**1. A reachable AgentWrit broker.**
+The broker is a separate service that issues and validates tokens.
+
+- *Have a platform team running one?* Ask them for the broker URL.
+- *Running it yourself?* Stand one up locally — the [broker repo](https://github.com/devonartis/agentwrit) ships a `docker compose` setup. From this repo:
+  ```bash
+  docker compose up -d   # pulls devonartis/agentwrit from Docker Hub
+  ```
+
+**2. App credentials (`client_id` + `client_secret`).**
+These are issued by the **broker operator/admin** when they register your app and set its scope ceiling. The SDK cannot create them for you.
+
+- *Have a broker admin?* Ask them to register your app and send you the `client_id` and `client_secret`.
+- *You are the admin?* Use the included setup script (it registers an app and prints both values):
+  ```bash
+  export AGENTWRIT_ADMIN_SECRET="<your-broker-admin-secret>"
+  uv run python demo/setup.py
+  ```
+
+**3. Environment variables set** on the process that uses the SDK:
+```bash
+export AGENTWRIT_BROKER_URL="http://localhost:8080"   # from step 1
+export AGENTWRIT_CLIENT_ID="<from step 2>"
+export AGENTWRIT_CLIENT_SECRET="<from step 2>"
+```
+
+> Auth is lazy — the SDK doesn't talk to the broker until your first `create_agent()` call. If that call raises `AuthenticationError`, your `client_id` or `client_secret` is wrong (or the operator rotated them). If it raises `TransportError`, the broker URL is unreachable.
 
 ## Quick Start
 
+> Assumes [Prerequisites](#prerequisites) are met — broker reachable, app registered, env vars set.
+
 ```python
 import os
 from agentwrit import AgentWritApp, validate
 
 # Connect to the broker (lazy — no auth until first create_agent)
 app = AgentWritApp(
     broker_url=os.environ["AGENTWRIT_BROKER_URL"],
-    client_id=os.environ["AGENTWRIT_CLIENT_ID"],
-    client_secret=os.environ["AGENTWRIT_CLIENT_SECRET"],
+    client_id=os.environ["AGENTWRIT_CLIENT_ID"],          # from broker admin
+    client_secret=os.environ["AGENTWRIT_CLIENT_SECRET"],  # from broker admin
 )
 
 # Create an agent with specific scope
@@ -101,7 +149,7 @@ print(agent.expires_in)    # 300 (seconds)
 # Renew — new token, same identity, old token revoked
 agent.renew()
 
-# Delegate — give narrower scope to another agent
+# Delegate — pass a subset of scope to another agent (equal or narrower)
 delegated = agent.delegate(delegate_to=other.agent_id, scope=["read:data:x"])
 
 # Release — self-revoke, idempotent
@@ -112,7 +160,7 @@ agent.release()
 
 The [`demo/`](demo/) directory contains **MedAssist AI** — an interactive healthcare demo that showcases every AgentWrit capability against a live broker.
 
-**What it does:** A FastAPI web app where you enter a patient ID and a plain-language request. A local LLM (OpenAI-compatible) chooses which tools to call. The app dynamically creates broker agents with only the scopes those tools need, for that specific patient. You see scope enforcement, cross-patient denial, delegation, token renewal, and release — all in a real-time execution trace.
+**What it does:** A FastAPI web app where you enter a patient ID and a plain-language request. A local LLM (OpenAI-compatible) chooses which tools to call, and the app dynamically creates broker agents with only the scopes those tools need for that specific patient. Every step — scope enforcement, cross-patient denial, delegation, token renewal, release — appears in a real-time execution trace.
 
 **What it demonstrates:**
 
@@ -169,7 +217,7 @@ scope_is_subset(["read:logs:customers"], ["read:data:*"])     # False (logs != d
 
 ## Delegation
 
-Agents delegate narrower scope to other agents. Authority can only narrow, never widen.
+Agents delegate a subset of their scope to other agents. Delegation cannot widen authority — equal or narrower scope is accepted; any scope the delegator doesn't hold is rejected.
 
 ```python
 # A has broad scope
@@ -243,7 +291,7 @@ Application (your code — AgentWritApp)
   │  creates agents within ceiling
   ▼
 Agent (ephemeral SPIFFE identity + scoped JWT)
-  │  scope can only narrow on delegation
+  │  delegation cannot widen scope (equal or narrower allowed)
   ▼
 Delegated Agent (sub-agent, max 5 hops)
 ```

demo/BEGINNERS_GUIDE.md

@@ -14,7 +14,7 @@ Traditional setups often give every service (or every “agent”) the **same lo
 - **What task** they are doing,
 - **Which scopes** they are allowed to use (often **per patient**, per action).
 
-The **broker** is the authority: it registers apps, mints tokens, validates them, supports **delegation** (narrowing authority), **renewal**, **release**, and **revocation**, and writes an **audit trail**.
+The **broker** is the authority: it registers apps, mints tokens, validates them, supports **delegation** (passing scope to another agent — equal or narrower, never widening), **renewal**, **release**, and **revocation**, and writes an **audit trail**.
 
 ---
 
@@ -144,7 +144,7 @@ flowchart LR
 
 ## 7. Diagram: delegation (prescription write)
 
-Delegation is **authority narrowing**: the clinical agent already has `write:prescriptions:{pid}`; it asks the broker to issue a **delegated token** for the prescription agent’s SPIFFE ID with **only** that scope (or a subset).
+Delegation is **bounded authority transfer** — the broker rejects any attempt to widen past the delegator's scope. In this demo, the clinical agent already has `write:prescriptions:{pid}` and asks the broker to issue a **delegated token** for the prescription agent's SPIFFE ID with that same scope (or a narrower subset). Equal-scope and narrower delegation are both valid; widening is rejected.
 
 ```mermaid
 flowchart LR

demo/PRESENTERS_GUIDE.md

@@ -57,7 +57,7 @@ Do **4–6** runs in this order so the room sees escalation, not repetition.
 **What to point at:**  
 - **Clinical** agent, then **billing**, then **prescription** as the LLM calls tools.  
 - **Delegation** step when a prescription write is allowed: clinical delegates `write:prescriptions:{pid}` to the Rx agent.  
-- That is **authority narrowing**, not “same API key everywhere.”
+- That is **bounded authority transfer** — the broker rejects any widening past the delegator's scope — not “same API key everywhere.”
 
 ---
 

demo/templates/operator.html

@@ -38,7 +38,7 @@ <h2>Broker Health</h2>
         <!-- Scope Ceiling -->
         <div class="panel">
             <h2>App Scope Ceiling</h2>
-            <p class="description">The maximum scopes this application can grant to agents. Set by the operator at app registration. Each agent gets a strict subset, scoped to a specific patient.</p>
+            <p class="description">The maximum scopes this application can grant to agents. Set by the operator at app registration. Each agent gets a subset of this ceiling, typically scoped to a specific patient.</p>
             <div class="scope-list">
                 {% for scope in scope_ceiling %}
                 <span class="scope-badge ceiling">{{ scope }}</span>

docs/api-reference.md

@@ -1,6 +1,8 @@
 # API Reference
 
-Complete reference for the AgentWrit Python SDK public API.
+Complete reference for the AgentWrit Python SDK public API. Companion to [Getting Started](getting-started.md) and [Developer Guide](developer-guide.md).
+
+[AgentWritApp](#agentwritapp) · [Agent](#agent) · [Module Functions](#module-level-functions) · [Data Classes](#data-classes) · [Exceptions](#exceptions) · [Broker Endpoints](#broker-endpoint-mapping)
 
 ---
 
@@ -97,7 +99,18 @@ Shortcut for `agentwrit.validate(app.broker_url, token)`.
 app.close() -> None
 ```
 
-Closes the underlying HTTP transport. Call this when you're done with the app to release connections.
+Closes the underlying HTTP transport. Call this when you're done with the app to release the connection pool.
+
+> `AgentWritApp` is **not** a context manager — `with AgentWritApp(...) as app:` will raise `AttributeError`. Use a `try/finally` instead:
+>
+> ```python
+> app = AgentWritApp(...)
+> try:
+>     agent = app.create_agent(...)
+>     # ... use agent ...
+> finally:
+>     app.close()
+> ```
 
 ---
 
@@ -255,7 +268,7 @@ from agentwrit import AgentClaims
 | `exp` | `int` | Expiration (Unix timestamp) |
 | `nbf` | `int` | Not before (Unix timestamp) |
 | `iat` | `int` | Issued at (Unix timestamp) |
-| `jti` | `str` | Unique token ID (32 hex chars) |
+| `jti` | `str` | Unique token ID (broker-assigned; format is broker-defined, do not assume a fixed length) |
 | `scope` | `list[str]` | Granted scope |
 | `task_id` | `str` | Task identifier |
 | `orch_id` | `str` | Orchestrator identifier |
@@ -320,6 +333,25 @@ RFC 7807 structured error from the broker.
 | `request_id` | `str \| None` | Broker-generated trace ID |
 | `hint` | `str \| None` | Optional guidance for resolution |
 
+#### Known `error_code` values
+
+> Observed broker behavior at the time of writing. The broker's [api.md](https://github.com/devonartis/agentwrit/blob/main/docs/api.md) is the authoritative source — consult it for additions or renames.
+
+| `error_code` | HTTP | Fires when |
+|--------------|------|------------|
+| `invalid_request` | 400 | Malformed JSON, missing required field, invalid format |
+| `invalid_ttl` | 400 | Requested `token_ttl` outside the broker's allowed range |
+| `unauthorized` | 401 | Missing / invalid / expired credentials; failed token verification; Bearer header missing or malformed |
+| `forbidden` | 403 | Admin-side app-not-found or scope-ceiling check during admin launch-token creation |
+| `insufficient_scope` | 403 | Caller's token is valid but lacks the scope required for this endpoint (emitted by the validation middleware) — **or** the token has been revoked |
+| `scope_violation` | 403 | `/v1/register` or `/v1/delegate` rejected the requested scope as exceeding the caller's authority |
+| `not_found` | 404 | App or delegate agent does not exist |
+| `payload_too_large` | 413 | Request body exceeded 1 MB |
+| `rate_limited` | 429 | Rate limit hit on the auth endpoints |
+| `internal_error` | 500 | Server-side failure (launch-token creation, registration, delegation, etc.) |
+
+> **Watch the 403 split.** Both `scope_violation` and `insufficient_scope` surface as `AuthorizationError` in the SDK. If you switch on `error_code`, handle both: `scope_violation` covers "your request exceeded your authority"; `insufficient_scope` covers "your token doesn't have the scope this endpoint needs, or the token was revoked."
+
 ### RegisterResult
 
 ```python
@@ -365,9 +397,11 @@ Raised on HTTP 401. App credentials are invalid.
 
 ### AuthorizationError
 
-Raised on HTTP 403. Scope violation — either:
-- Requested scope exceeds app ceiling (during `create_agent()`)
-- Delegated scope exceeds delegator's scope (during `delegate()`)
+Raised on HTTP 403. Three distinct sub-cases, all surface through this class — inspect `e.problem.error_code` to differentiate:
+
+- **Scope ceiling violation** — requested scope exceeds the app's ceiling during `create_agent()` (`error_code: scope_violation`)
+- **Delegation violation** — delegated scope exceeds delegator's scope, or exceeds broker-enforced delegation depth, during `delegate()` (`error_code: scope_violation`)
+- **Token revocation or insufficient scope at the endpoint** — caller's token was revoked, or lacks the scope the endpoint requires (`error_code: insufficient_scope`)
 
 ### RateLimitError