diff --git a/CHANGELOG.md b/CHANGELOG.md index 0db27bd..e2667ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed — Architecture component mapping + signing key documentation (2026-04-13) - Pattern component table now maps all 8 EAC v1.3 components with correct numbering. Component 6 (Mutual Authentication) documented as present but not wired. Component 7 (Delegation) and 8 (Observability) added. +- Package count corrected (14→15) and `mutauth` added to directory layout. Clarified distinction: `mutauth` package is agent-to-agent auth (Component 6, planned); server-side mTLS transport (`AA_TLS_MODE=mtls` in `cmd/broker/serve.go`) is separate and working. - Security Assumptions: removed false claim that "all previously issued tokens become unverifiable after restart (new signing keys)." The signing key is persistent via `internal/keystore` — tokens survive restarts. Single-broker note corrected to describe the actual split-brain risk (in-memory state, not signing keys). ### Fixed — SPDX identifier + gate + middleware diagram (2026-04-13) diff --git a/docs/architecture.md b/docs/architecture.md index ad1b8ea..2ca72cc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # Architecture — How AgentWrit Works Inside -Two binaries, one Go module, fourteen internal packages. This page shows how every component connects — from HTTP request to signed JWT to audit record. +Two binaries, one Go module, fifteen internal packages. This page shows how every component connects — from HTTP request to signed JWT to audit record. **Prerequisites:** [Concepts](concepts.md) helps, but isn't required. @@ -90,6 +90,7 @@ agentwrit/ | |-- handler/ # HTTP handlers for all broker endpoints + security_hdl.go (SecurityHeaders) | |-- identity/ # Challenge-response registration, SPIFFE IDs | |-- keystore/ # Ed25519 signing key persistence (PKCS8 PEM) +| |-- mutauth/ # Agent-to-agent mutual authentication (Component 6 — not wired into broker; server-side mTLS is in cmd/broker/serve.go via AA_TLS_MODE=mtls) | |-- obs/ # Structured logging | |-- problemdetails/ # RFC 7807 errors, request ID, body limits | |-- revoke/ # Four-level token revocation @@ -126,7 +127,7 @@ Each service is initialized in `cmd/broker/main.go` with explicit constructor in ## Pattern Components Mapped to Code -The 8-component Ephemeral Agent Credentialing pattern maps to Go packages. Components 1–5, 7, and 8 are fully implemented. Component 6 (Agent-to-Agent Mutual Authentication) has a package (`mutauth`) but is not wired into the broker — it is planned work. +The 8-component Ephemeral Agent Credentialing pattern maps to Go packages. Components 1–5, 7, and 8 are fully implemented. Component 6 (Agent-to-Agent Mutual Authentication) has a package (`mutauth`) but is not wired into the broker — it is planned work. Note: server-side mTLS transport (via `AA_TLS_MODE=mtls`) is implemented in `cmd/broker/serve.go` using Go stdlib `crypto/tls` and is independent of the `mutauth` package. The `mutauth` package implements the pattern's agent-to-agent authentication handshake, which is a different concern. | Pattern Component | Go Packages | Key Types | Key Functions | |---|---|---|---| @@ -139,7 +140,7 @@ The 8-component Ephemeral Agent Credentialing pattern maps to Go packages. Compo | 3. Zero-Trust Enforcement | `authz`, `handler` | `ValMw`, `RateLimiter` | `ValMw.Wrap()`, `ValMw.RequireScope()`, `ValMw.RequireAnyScope()`, `ScopeIsSubset()` | | 4. Automatic Expiration & Revocation | `revoke`, `token`, `handler` | `RevSvc`, `Revoker`, `RevokeHdl`, `ReleaseHdl` | `RevSvc.Revoke()`, `RevSvc.RevokeByJTI()`, `RevSvc.IsRevoked()`, `RevSvc.LoadFromEntries()` | | 5. Immutable Audit Logging | `audit`, `handler` | `AuditLog`, `AuditEvent`, `AuditHdl`, `RecordOption` | `AuditLog.Record()`, `AuditLog.Query()`, `WithOutcome()`, `WithResource()` | -| 6. Mutual Authentication | `mutauth` *(not wired)* | `MutAuthHdl`, `Discovery`, `Heartbeat` | Package exists but is not registered in `cmd/broker/main.go`. Planned. | +| 6. Mutual Authentication | `mutauth` *(not wired)* | `MutAuthHdl`, `Discovery`, `Heartbeat` | Agent-to-agent auth handshake. Package exists but is not registered in `cmd/broker/main.go`. Planned. (Server-side mTLS is separate — see `cmd/broker/serve.go`.) | | 7. Delegation Chain Verification | `deleg`, `handler` | `DelegSvc`, `DelegHdl`, `DelegRecord` | `DelegSvc.Delegate()` | | 8. Operational Observability | `obs`, `handler` | `HealthHdl`, `MetricsHdl` | `obs.Ok()`, `obs.Warn()`, `obs.Fail()`, `obs.Trace()`, `/v1/health`, `/v1/metrics` |