docs: add three-party flow examples with mermaid diagrams

.agent/plans/2026-05-28-readme-getting-started-update/implementation-plan.md

@@ -0,0 +1,169 @@
+# Implementation Plan: README & Getting Started Documentation Update
+
+## Phase 1: README.md — Three-Party Flow with Mermaid Diagram
+
+### Changes
+
+**File:** `README.md`
+
+Replace the existing "Three-Party Flow" section with an expanded version including:
+
+1. **Mermaid sequence diagram** showing the PS-Asserted (three-party) flow with user consent:
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant Resource
+    participant PS as Person Server
+    participant User
+
+    Agent->>Resource: GET /data (signed, agent token)
+    Resource-->>Agent: 401 + resource_token (aud=PS)
+    Agent->>PS: POST /token (signed, resource_token)
+    PS->>User: Consent prompt (scope, justification)
+    User-->>PS: Grant consent
+    PS-->>Agent: auth_token (aa-auth+jwt)
+    Agent->>Resource: GET /data (signed, auth_token)
+    Resource-->>Agent: 200 OK
+```
+
+2. **Self-hosted agent setup** — concise code showing:
+   - Key generation
+   - Publishing agent metadata (`MapAAuthAgentWellKnown`)
+   - Self-issuing agent tokens via `AgentTokenBuilder`
+   - Building the signed client with challenge handling
+
+3. **Resource-side example** — concise code showing:
+   - Verification middleware registration
+   - Resource metadata publication
+   - Issuing resource tokens (challenge response)
+
+4. **Agent calling the resource** — code showing the full client call and a brief "what happens" explanation
+
+5. **Brief walk-through** of the exchange (numbered list):
+   1. Agent signs GET with agent token → Resource verifies signature, reads `ps` from agent token
+   2. Resource returns 401 with a `resource_token` (audience = PS URL)
+   3. Agent POSTs resource_token to PS's token endpoint (signed request)
+   4. PS validates agent token, prompts user for consent
+   5. User grants consent; PS issues `auth_token` with identity claims
+   6. Agent retries original request signed with auth token
+   7. Resource verifies auth token signature + claims → 200 OK
+
+### Definition of Done
+
+- [x] Mermaid diagram renders correctly (3-party with user consent, 4 participants)
+- [x] Self-hosted agent code example compiles conceptually (uses real SDK types)
+- [x] Resource-side code example uses `UseAAuthVerification`, `MapAAuthWellKnown`, `ResourceTokenBuilder`
+- [x] Agent-calls-resource code example uses `AAuthClientBuilder` with `WithChallengeHandling`
+- [x] Walk-through text uses spec-accurate terminology (Person Server not "auth server", resource_token not "challenge token", auth_token not "access token")
+- [x] No bearer tokens mentioned — every credential is bound to a signing key
+- [x] README remains concise — detailed explanations go in getting-started
+
+---
+
+## Phase 2: Getting Started — Expanded Protocol & Enrollment Guide
+
+### Changes
+
+**File:** `docs/getting-started.md`
+
+Add/expand the following sections after the existing "What Just Happened?" section and before "Self-Issued Agent Tokens":
+
+#### 2a. "Understanding the Protocol Participants" section
+
+Expand on what each party does, with emphasis on the **Agent Provider (AP)**:
+
+- **What an AP does**: Issues agent tokens that bind a signing key to an agent identity. Acts as the trust anchor for agent identity. Analogous to a certificate authority for agents.
+- **Self-hosted vs enrolled**:
+  - Self-hosted: Agent has stable URL → is its own AP → publishes `/.well-known/aauth-agent.json` → self-signs tokens. No external enrollment. Used by web apps, APIs, orchestrators.
+  - Enrolled (external AP): CLI/desktop/mobile agents register with an AP. AP holds public key, agent holds private key locally. Agent token refreshed automatically (SDK manages this).
+- **Key separation**: Agent and AP never share a keystore. Agent holds private key in local `IKeyStore`; AP holds only the public key.
+
+#### 2b. "Key Types & Cryptography" section
+
+- **Ed25519** — required for signing keys (`AAuthKey.Generate()` produces Ed25519)
+- **JWK Thumbprint (S256)** — how keys are identified without exposing the full key
+- **JWT signing** — all AAuth tokens are Ed25519-signed JWTs
+- Note: spec says EdDSA is RECOMMENDED; implementations MUST NOT accept `none`
+
+#### 2c. "Supported Flows" section
+
+Table + brief description of each flow with links:
+
+| Flow | Parties | When to Use | Signing Mode |
+|------|---------|-------------|--------------|
+| Identity-Based | Agent + Resource | API-key replacement, simple access control | `hwk` or `jwks_uri` |
+| Resource-Managed (two-party) | Agent + Resource | Resource handles its own auth (interaction, OAuth) | Any |
+| PS-Asserted (three-party) | Agent + Resource + PS | User consent required, resource delegates auth to PS | `jwt` |
+| Federated (four-party) | Agent + Resource + PS + AS | Cross-domain policy, resource has its own AS | `jwt` |
+
+#### 2d. "Three-Party Flow Deep Dive" section
+
+Detailed walk-through with:
+
+1. **Mermaid diagram** (same as README but more detailed, showing consent interaction)
+2. **Step-by-step explanation** of each message:
+   - What headers are sent
+   - What the resource checks
+   - What the PS validates
+   - How consent works (immediate vs deferred)
+   - What claims the auth token contains
+3. **Self-hosted agent code** (full example with metadata publishing)
+4. **Resource-side code** (full example with verification + token issuance)
+5. **Client code** calling the resource (showing automatic challenge handling)
+
+#### 2e. "Enrollment: Hosted vs CLI/Desktop Agents" section
+
+Restructure existing enrollment content into a clear comparison:
+
+| Aspect | Self-Hosted (Web App/API) | Enrolled (CLI/Desktop) |
+|--------|---------------------------|------------------------|
+| AP needed? | No — agent IS its own AP | Yes — external AP |
+| URL requirement | Stable HTTPS URL | None |
+| Key lifecycle | Generated at startup, published via JWKS | Generated in keystore at enrollment, loaded by handle |
+| Token acquisition | Self-signed at startup | AP refresh endpoint (automatic via SDK) |
+| Metadata | Publishes `/.well-known/aauth-agent.json` | AP publishes it |
+| Code entry point | `MapAAuthAgentWellKnown()` + `AgentTokenBuilder` | `AAuthClientBuilder.Bootstrap().EnrolAsync()` |
+
+### Definition of Done
+
+- [x] "Understanding the Protocol Participants" section explains AP role clearly
+- [x] Self-hosted vs enrolled comparison table present
+- [x] Key types section covers Ed25519, JWK thumbprint, JWT signing
+- [x] Supported flows table covers all 4 modes with correct signing mode requirements
+- [x] Three-party deep dive includes mermaid diagram with user consent
+- [x] Step-by-step explanation covers headers, validation, consent (immediate + deferred)
+- [x] Resource-side code example present (verification + metadata + token issuance)
+- [x] All terminology matches spec exactly (Person Server, resource_token, auth_token, etc.)
+- [x] No references to bearer tokens or OAuth concepts that don't apply
+- [x] Links to detailed docs (signing-modes/overview, workflows/, server/) work correctly
+
+---
+
+## Phase 3: Review & Cross-References
+
+### Changes
+
+1. Ensure README links to the new getting-started sections
+2. Ensure getting-started links to workflow docs, server docs, and signing-modes docs
+3. Verify no terminology drift between README, getting-started, and spec
+4. Ensure code examples are consistent across both files (same patterns, same type names)
+
+### Definition of Done
+
+- [x] README "See Getting Started" link points to correct anchor
+- [x] Getting-started "Next Steps" links all resolve
+- [x] Terminology audit: no "bearer token", "access token" (use "auth token"), "authorization server" (use "Access Server" or "Person Server")
+- [x] Code examples use current SDK API surface (builder pattern, real type names)
+
+---
+
+## Out of Scope
+
+| Item | Reason |
+|------|--------|
+| Updating workflow docs (`docs/workflows/`) | Separate concern; already well-documented |
+| Adding new sample projects | Documentation-only change |
+| Spec conformance testing of examples | Examples are illustrative, not runnable |
+| Mission/governance documentation | Orthogonal layer, not part of basic getting-started |
+| Four-party (federated) detailed example | Complex; three-party is the focus |

.agent/plans/2026-05-28-readme-getting-started-update/research.md

@@ -0,0 +1,134 @@
+# Research: README & Getting Started Documentation Update
+
+## Objective
+
+Update the main `README.md` and `docs/getting-started.md` to include a clear three-party (PS-Asserted) flow example with a mermaid diagram, self-hosted agent setup, resource-side code, and an agent calling the resource. The getting started guide should also expand coverage of AP roles, enrollment models, key types, and supported flows.
+
+## Source Material
+
+### Spec Terminology (draft-hardt-oauth-aauth-protocol)
+
+| Term | Definition |
+|------|------------|
+| **Person** | User or organization on whose behalf an agent acts |
+| **Agent** | HTTP client acting on behalf of a person; identified by `aauth:local@domain` URI |
+| **Agent Provider (AP)** | Server managing agent identity; issues agent tokens binding key → identity; publishes `/.well-known/aauth-agent.json` |
+| **Resource** | Protected API; verifies signatures, issues resource tokens; publishes `/.well-known/aauth-resource.json` |
+| **Person Server (PS)** | Represents the person; manages consent, asserts identity, brokers authorization; publishes `/.well-known/aauth-person.json` |
+| **Access Server (AS)** | Policy engine; issues auth tokens on behalf of a resource; publishes `/.well-known/aauth-access.json` |
+| **Agent Token** | `aa-agent+jwt` — binds agent key → identity; issued by AP or self-issued |
+| **Resource Token** | `aa-resource+jwt` — challenge from resource saying "get auth from my PS/AS" |
+| **Auth Token** | `aa-auth+jwt` — proves user authorized this agent; issued by PS or AS |
+| **Mission** | Scoped authorization context for governance (orthogonal to access modes) |
+
+### Resource Access Modes (spec §Protocol Overview)
+
+1. **Identity-Based** — Agent + Resource only. Resource trusts signed identity directly.
+2. **Resource-Managed (two-party)** — Resource handles auth itself (interaction, OAuth, internal policy).
+3. **PS-Asserted (three-party)** — Resource issues resource token (aud=PS) → agent exchanges at PS → gets auth token → presents to resource.
+4. **Federated (four-party)** — Resource has its own AS; PS federates with AS.
+
+### PS-Asserted Flow (Three-Party) — Spec §PS-Asserted Access
+
+Sequence from spec:
+
+1. Agent sends signed request to resource (Signature-Key: sig=jwt with agent token)
+2. Resource reads PS URL from `ps` claim in agent token
+3. Resource returns 401 + `AAuth-Requirement: requirement=auth-token` with a `resource_token` (aud=PS URL)
+4. Agent POSTs resource token to PS token endpoint (signed request)
+5. PS validates agent token, confirms user consent (immediate or deferred)
+6. PS returns `auth_token` (`aa-auth+jwt`) with identity claims (sub, email, etc.)
+7. Agent retries original request with auth token in Signature-Key
+
+### Signing Modes (spec §Agent Identity + HTTP Signature Keys)
+
+| Mode | Scheme | Use Case |
+|------|--------|----------|
+| Pseudonymous | `sig=hwk` | Rate-limiting by key, no identity needed |
+| Agent Identity | `sig=jwks_uri` | Identity-based access without PS flows |
+| Agent Token | `sig=jwt` | Full PS/AS authorization flows |
+| Key Rotation | `sig=jkt-jwt` | Naming JWT binds ephemeral key to stable identity |
+
+### Agent Token Acquisition (spec §Agent Token)
+
+Two models:
+1. **Self-hosted agents** — Agent has stable URL, publishes own `/.well-known/aauth-agent.json`, self-signs tokens. No external AP.
+2. **Enrolled agents** — CLI/desktop/mobile; register with external AP; AP issues tokens.
+
+Key facts from spec:
+- Agent generates Ed25519 keypair
+- Agent proves identity to AP (platform-specific mechanism)
+- AP issues agent token binding public key to agent identifier
+- Token lifetime: max 24 hours (spec: "SHOULD NOT exceed 24 hours")
+- `cnf.jwk` in agent token contains agent's public key
+- Optional `ps` claim identifies agent's person server
+
+### Self-Hosted Agent Details (spec §Roles + bootstrap spec)
+
+Per spec §Roles: "A self-hosted agent is its own agent provider, self-issuing agent tokens signed by a JWKS-published key the user controls."
+
+Requirements:
+- Stable HTTPS URL
+- Publish `/.well-known/aauth-agent.json` (metadata with `jwks_uri`)
+- Self-sign agent tokens with private key
+- JWKS endpoint publishes the public key
+
+### Resource-Side Verification (SDK)
+
+From SDK docs:
+- `UseAAuthVerification()` middleware verifies HTTP signatures + JWT issuer
+- `ResourceTokenBuilder` issues challenge tokens
+- `AddAAuthResource()` DI registration
+- `MapAAuthWellKnown()` serves discovery metadata
+
+### User Consent in Three-Party Flow
+
+From spec: "PS validates the agent token, confirms user consent (or defers), and returns an auth token."
+
+The PS can:
+- Grant immediately (pre-authorized or auto-consent policy)
+- Defer (202 Accepted with `requirement=interaction`) — agent polls until user consents
+- Deny (403)
+
+The SDK `ChallengeHandler` handles the 401 → exchange → retry cycle automatically. For deferred consent, the handler also handles polling with `InteractionWaitMode`.
+
+## SDK Types Mapping
+
+| Concept | SDK Type |
+|---------|----------|
+| Key generation | `AAuthKey.Generate()` |
+| Key storage | `IKeyStore`, `FileKeyStore` |
+| Client builder | `AAuthClientBuilder` |
+| HTTP signing | `AAuthSigningHandler` |
+| Challenge handling | `ChallengeHandler` |
+| Token exchange | `TokenExchangeClient` |
+| Self-issued tokens | `AgentTokenBuilder`, `SelfIssuedTokenRefresher` |
+| AP enrollment | `AAuthClientBuilder.Bootstrap()` |
+| AP token refresh | `AgentProviderTokenRefresher` |
+| Resource verification | `AAuthVerificationMiddleware`, `AAuthVerifier` |
+| Resource tokens | `ResourceTokenBuilder` |
+| Auth tokens | `AuthTokenBuilder` |
+| Resource metadata | `AAuthResourceMetadataOptions`, `MapAAuthResourceWellKnown()` |
+| Agent metadata | `AAuthAgentMetadataOptions`, `MapAAuthAgentWellKnown()` |
+| DI | `AddAAuthAgent()`, `AddAAuthResource()` |
+
+## Existing Documentation Gaps
+
+### README.md
+
+- Three-party flow example exists but lacks a visual mermaid diagram
+- No resource-side code example
+- No end-to-end walk-through of what happens in the 3-party exchange
+- AP role described only in a sidebar note
+
+### docs/getting-started.md
+
+- Self-hosted agent section exists but could be clearer about WHY self-hosting works (stable URL = own AP)
+- Bootstrap/enrollment section exists but doesn't explain what an AP fundamentally does
+- No resource-side setup example
+- No overview of which flows are supported and when to use each
+- Key types not explicitly enumerated (only Ed25519 mentioned)
+
+## Open Questions
+
+- None — spec, SDK, and existing docs provide sufficient detail.