docs: delegation comments claim "strict subset" / "only narrow" but code is non-strict

[devonartis]

Priority: High

Comments contradict behavior on a security-relevant enforcement check. Downstream consumers (including the AgentWrit Python SDK docs) inherited this framing and have been telling users the wrong rule.

Summary

Two places in the broker source claim delegation enforces strict narrowing ("strict subset" / "scopes can only narrow, never expand"). The actual implementation of authz.ScopeIsSubset is a non-strict subset check — equal scopes pass. Same-scope delegation (delegator passes its full scope to a delegate unchanged) is accepted by the broker, which is correct behavior but contradicts the docstrings.

Affected files

internal/deleg/deleg_svc.go line 12 (package docstring):

// The delegated scope must be a strict subset of the delegator's scope
// (attenuation only — scopes can never expand).

"strict subset" is wrong — should be "subset (equal is allowed)."

internal/authz/scope.go lines 74–75 (function docstring above ScopeIsSubset):

// This enforces the attenuation rule:
// scopes can only narrow, never expand.

"can only narrow" is wrong — should be "cannot widen" or "cannot expand beyond what is allowed."

Evidence

The function body at authz/scope.go:76-90 is a standard containment check: every scope in requested must be covered by at least one scope in allowed. Equal scopes satisfy this trivially. There is no strict-less-than check anywhere in the path.

The behavior is also explicitly verified in the SDK acceptance suite — tests/integration/test_acceptance_1_8.py, Story 8 ("Delegate All Scope (No Narrowing)"):

# STORY 8: Agent delegates ALL its scope without narrowing.

This test passes against the broker. Same-scope delegation is accepted.

Recommended fix

Two one-line changes:

1. internal/deleg/deleg_svc.go:12 — replace "strict subset of" with "subset of (equal allowed) —".
2. internal/authz/scope.go:75 — replace "scopes can only narrow, never expand" with "scopes cannot widen beyond what the delegator holds."

Also check

• docs/api.md for the same phrasing on the /v1/delegate endpoint. If it says delegation "narrows" authority, update to "cannot widen authority; equal or narrower is accepted."
• Any audit event descriptions or error messages that imply strict narrowing. ErrScopeViolation = "delegated scope exceeds delegator scope" is already correct — it talks about exceeding, not failing to narrow. Keep it.

Why this matters

• Security-relevant enforcement: if a contributor reads the "strict subset" comment and tries to "fix" ScopeIsSubset to actually enforce strict-less-than, they'll break every production deployment that relies on same-scope delegation (a common pattern — e.g., fan-out to workers that carry the parent's full scope).
• Downstream doc inheritance: the AgentWrit Python SDK docs repeated this framing across README, concepts, developer-guide, sample-apps, and demo guides. We're cleaning those up in a parallel PR (docs/delegation-accuracy), but the broker being the source of truth means the broker's own docs need to be right first.

Severity reasoning

Doc-only change, but high priority because:

1. Comments directly above security-enforcement code must match behavior.
2. Misleads contributors at exactly the spot where "helpful fixes" would cause production regressions.
3. Propagates to downstream SDK and demo docs that depend on this repo as the source of truth.

[devonartis]

Picking this up — branch fix/delegation-narrowing-docs.

Verified the two source locations match the issue exactly. While auditing, found the same wrong framing in 5 more places that aren't named in the issue body — applying the fix to all 7 in one PR rather than leaving the README and security-topology docs lying after the source is corrected:

• internal/deleg/deleg_svc.go:12 (named)
• internal/authz/scope.go:74-75 (named)
• README.md:39 — "permissions only narrow, never expand"
• docs/security-topology.md:30 — "scopes can only narrow, never escalate"
• docs/diagrams/security-topology.svg:191 — "Scopes can only narrow" (image label)
• docs/common-tasks.md:842 — "Ensure delegated scope is a strict subset of your scope" (error-help table)
• docs/integration-patterns.md:2095 — "Delegation always narrows scope (never escalates)" (checklist)

docs/api.md:1057 — flagged in the issue as "also check" — turns out to be already correct ("same or narrower, never wider" properly includes equal). No change needed.

Wording template across all 7: "cannot widen; equal or narrower is accepted." The two source-file docstrings get the longer explanation noting same-scope delegation is a deliberate pattern (e.g., fan-out workers carrying the parent's full authority), with a back-reference to this issue per the project's golang.md rule on commenting design choices.

PR will close this issue on merge.