docs: align delegation framing with non-strict subset behavior

Closes #41

Comments and docs in 9 places claimed delegation enforces strict
narrowing ("strict subset", "only narrow", "narrower-scoped"). The
actual code in authz.ScopeIsSubset is a non-strict containment check:
equal scopes pass. Same-scope delegation is a deliberate pattern
(e.g., fan-out to workers carrying the parent's full authority) and
is verified by the SDK acceptance suite (Story 8: "Delegate All
Scope (No Narrowing)").

Wording template applied: "cannot widen; equal or narrower is
accepted." The two source-file docstrings (deleg_svc.go, scope.go)
get a longer explanation noting same-scope delegation is intentional,
with a back-reference to issue #41 per golang.md's rule on commenting
non-obvious design choices.

Changes (12 distinct edits across 9 files):

  Source code (3 edits, 2 files)
  - internal/deleg/deleg_svc.go:6   "narrower-scoped token" → "scope-attenuated token (equal or narrower)"
  - internal/deleg/deleg_svc.go:12  "strict subset" → "cannot widen; equal or narrower" (+ rationale + #41 ref)
  - internal/authz/scope.go:74-78   "scopes can only narrow, never expand" → "requested scopes cannot widen allowed scopes" (+ rationale + #41 ref)

  README (2 edits)
  - README.md:39  "permissions only narrow, never expand" → "permissions cannot widen, only equal or narrower"
  - README.md:43  "delegate narrower-scoped tokens" → "delegate scope-attenuated tokens (equal or narrower)"

  Docs (6 edits, 5 files)
  - docs/security-topology.md:30      "scopes can only narrow, never escalate" → "scopes cannot widen; equal or narrower is accepted"
  - docs/architecture.md:212          "delegates a narrower-scoped token" → "delegates a scope-attenuated token (equal or narrower)"
  - docs/roles.md:97                  "Create a narrower-scoped token" → "Create a scope-attenuated token (equal or narrower)"
  - docs/common-tasks.md:681          docstring "narrower-scoped token" → "scope-attenuated token (equal or narrower)"
  - docs/common-tasks.md:842          error table "strict subset of your scope" → "does not widen your scope (equal or narrower is accepted)"
  - docs/integration-patterns.md:2095 checklist "always narrows scope" → "does not widen scope (equal or narrower)"

  Diagram (1 edit, 1 SVG, 2 text elements)
  - docs/diagrams/security-topology.svg:191-192  "Scopes can only narrow / Never escalate" → "Scopes cannot widen / Equal or narrower"

Verified already-correct (no change needed):
- docs/api.md:1057 "same or narrower, never wider" — accurate
- ErrScopeViolation = "delegated scope exceeds delegator scope" — accurate (talks about exceeding, not failing-to-narrow)

Local gates run pre-push: build, vet, format, contamination, unit-tests
(all packages), go-mod-verify — all PASS. Lint/gosec/govulncheck run
authoritatively in CI.

Co-authored-by: Claude <noreply@anthropic.com>

Author: devonartis

README.md

@@ -36,11 +36,11 @@ Traditional IAM was built for humans and long-running services — not for AI ag
 | Traditional IAM for agents | AgentWrit |
 |---|---|
 | Agents get static API keys or service account credentials designed for long-running services | Each agent requests a token scoped to one task |
-| Credentials are over-permissioned because scoping per-task is manual and fragile | Scope attenuation is automatic — permissions only narrow, never expand |
+| Credentials are over-permissioned because scoping per-task is manual and fragile | Scope attenuation is automatic — permissions cannot widen, only equal or narrower |
 | Leaked credential exposes everything the service account can access | Leaked token exposes one task, already expiring in minutes |
 | Revoking a static key means rotating it everywhere it's used | Revocation is instant at 4 levels — token, agent, task, or delegation chain |
 | No visibility into which agent used which credential for which task | Every credential event is audited per-agent, per-task in a tamper-evident hash chain |
-| No native concept of agent-to-agent delegation | Delegation is built in — Agent A can delegate narrower-scoped tokens to Agent B with full chain tracking |
+| No native concept of agent-to-agent delegation | Delegation is built in — Agent A can delegate scope-attenuated tokens to Agent B (equal or narrower) with full chain tracking |
 
 > **What the audit trail covers:** The broker logs credential lifecycle events — issue, renew, revoke, delegate, release, auth failures, and scope violations. It does not see what the agent does with the token at the resource server.
 

docs/architecture.md

@@ -209,7 +209,7 @@ sequenceDiagram
 
 ### Delegation Flow
 
-Agent A delegates a narrower-scoped token to Agent B:
+Agent A delegates a scope-attenuated token to Agent B (equal or narrower scope; widening is rejected):
 
 ```mermaid
 sequenceDiagram

docs/common-tasks.md

@@ -678,7 +678,7 @@ import requests
 BROKER = "http://localhost:8080"
 
 def delegate_token(broker, my_token, delegate_agent_id, scope, ttl=60):
-    """Delegate a narrower-scoped token to another agent."""
+    """Delegate a scope-attenuated token to another agent (equal or narrower)."""
     resp = requests.post(
         f"{broker}/v1/delegate",
         headers={"Authorization": f"Bearer {my_token}"},
@@ -839,7 +839,7 @@ try {
 | Status | Meaning | Action |
 |--------|---------|--------|
 | 400 | Invalid request (bad format, missing fields) | Verify `delegate_to` is a valid SPIFFE ID and `scope` is an array |
-| 403 | Scope escalation or widening attempted | Ensure delegated scope is a strict subset of your scope |
+| 403 | Scope escalation or widening attempted | Ensure delegated scope does not widen your scope (equal or narrower is accepted) |
 | 404 | Delegate agent not found in broker | Verify the agent's SPIFFE ID is correct and it has registered |
 | 401 | Your token is invalid or expired | Renew or re-register to get a fresh token |
 

docs/diagrams/security-topology.svg

@@ -2092,7 +2092,7 @@ When implementing AgentWrit patterns, verify:
 ### Scope and Delegation
 
 - [ ] Scope ceilings are enforced at the broker level
-- [ ] Delegation always narrows scope (never escalates)
+- [ ] Delegation does not widen scope (equal or narrower)
 - [ ] Delegation depth is limited (maximum 5 hops)
 - [ ] Scope format is validated: `action:resource:identifier`
 - [ ] Wildcard scope (`*`) is used narrowly and intentionally

docs/integration-patterns.md

@@ -94,7 +94,7 @@ write:logs:agent-run-42
 | `POST /v1/token/validate` | External services check this token to decide if the agent is authorized |
 | `POST /v1/token/renew` | Extend the session — same scope, same original TTL, old token revoked first |
 | `POST /v1/token/release` | Self-revoke when the task is done |
-| `POST /v1/delegate` | Create a narrower-scoped token for another registered agent |
+| `POST /v1/delegate` | Create a scope-attenuated token (equal or narrower) for another registered agent |
 
 **What the agent cannot do:** call any admin or app endpoint. It has no `admin:*` or `app:*` scopes. The broker enforces this.
 

docs/roles.md

@@ -27,7 +27,7 @@ Scopes only move in one direction: down. Every boundary is enforced at issuance
 
 - **Challenge-response** — Ed25519 keypair per agent instance. No shared secrets at the agent level.
 - **Hash-chain audit** — tamper-evident trail with 24 event types. Each record hashes the previous.
-- **Scope attenuation** — scopes can only narrow, never escalate. Delegation preserves the original principal.
+- **Scope attenuation** — scopes cannot widen; equal or narrower is accepted. Delegation preserves the original principal.
 - **Token TTL** — default 5 minutes, max 24 hours (configurable). Per-app override available. Revocable at 4 levels.
 
 ---

docs/security-topology.md

@@ -72,7 +72,10 @@ func scopeCovers(requested, allowed string) bool {
 // least one scope in allowed. A scope is covered when its action and
 // resource match and either the identifiers are equal or the allowed
 // identifier is the wildcard "*". This enforces the attenuation rule:
-// scopes can only narrow, never expand.
+// requested scopes cannot widen allowed scopes. Equal is accepted
+// (same-scope delegation is a deliberate pattern); narrower is accepted;
+// broader is rejected. See issue #41 for why this is not a strict-subset
+// check.
 func ScopeIsSubset(requested, allowed []string) bool {
 	for _, req := range requested {
 		covered := false

internal/authz/scope.go

@@ -3,14 +3,18 @@
 // Package deleg provides scope-attenuated token delegation with chain
 // verification and depth limiting.
 //
-// Delegation allows an authenticated agent to issue a narrower-scoped token
-// to another registered agent. The delegated token carries a delegation
+// Delegation allows an authenticated agent to issue a scope-attenuated
+// token to another registered agent (equal or narrower scope; widening
+// is rejected). The delegated token carries a delegation
 // chain that records the full provenance (who delegated what scope, and
 // when). Delegation depth is capped at [maxDelegDepth] (5) to prevent
 // unbounded chains.
 //
-// The delegated scope must be a strict subset of the delegator's scope
-// (attenuation only — scopes can never expand).
+// The delegated scope cannot widen the delegator's scope; equal or
+// narrower is accepted. Same-scope delegation is a deliberate pattern
+// (e.g., fan-out to workers carrying the parent's full authority) and
+// is allowed by [authz.ScopeIsSubset]. See issue #41 for why this is
+// not a strict-subset check.
 package deleg
 
 import (