docs: align delegation framing with non-strict subset behavior#42
Merged
devonartis merged 3 commits intodevelopfrom Apr 15, 2026
Merged
docs: align delegation framing with non-strict subset behavior#42devonartis merged 3 commits intodevelopfrom
devonartis merged 3 commits intodevelopfrom
Conversation
…riving
commit.template (.gitmessage) only fires when git opens an editor, so
commits made via `git commit -m` or HEREDOC bypass it entirely. That is
why "Co-authored-by: Claude" stopped appearing on commits after 2026-03-30
when the workflow shifted to -m-based commits via Claude Code.
The hook gates on CLAUDECODE=1 so only Claude-driven commits are stamped;
solo commits made in a plain terminal are left untouched. Also normalizes
historical variants ("Claude Opus 4.6", "Claude Sonnet 4.6") to the
canonical "Claude <noreply@anthropic.com>" form.
Co-authored-by: Claude <noreply@anthropic.com>
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>
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Snapshot WarningsEnsure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice. Scanned FilesNone |
Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #41
Summary
authz.ScopeIsSubsetis 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)").golang.md's rule on commenting non-obvious design choices.docs/api.md:1057("same or narrower, never wider") andErrScopeViolation— both already correct, no change needed.Files changed (12 edits, 9 files)
Source code (3 edits, 2 files) — security-relevant, the original target of #41:
internal/deleg/deleg_svc.go:6— package introinternal/deleg/deleg_svc.go:12— delegation rule docstring (+ docs: delegation comments claim "strict subset" / "only narrow" but code is non-strict #41 ref)internal/authz/scope.go:74-78—ScopeIsSubsetdocstring (+ docs: delegation comments claim "strict subset" / "only narrow" but code is non-strict #41 ref)README (2 edits) — front door of the repo:
README.md:39— IAM-comparison table rowREADME.md:43— IAM-comparison table rowDocs (6 edits, 5 files) — every place inheriting the same wrong framing:
docs/security-topology.md:30— security properties bulletdocs/architecture.md:212— Delegation Flow section introdocs/roles.md:97— Agent endpoint tabledocs/common-tasks.md:681— Python helper docstringdocs/common-tasks.md:842— error-help tabledocs/integration-patterns.md:2095— Scope and Delegation checklistDiagram (1 edit, 1 SVG) — gets screenshotted into slides:
docs/diagrams/security-topology.svg:191-192— Scope Attenuation callout labelTest plan
go vet ./...— PASSgo build ./...— PASSgofmt -l .— no files need formattinggo test -short -count=1 ./...— full module, all packages green (cmd/awrit, cmd/broker, internal/admin, internal/app, internal/audit, internal/authz, internal/cfg, internal/deleg, internal/handler, internal/identity, internal/keystore, internal/mutauth, internal/revoke, internal/store, internal/token)go mod verify && go mod tidy— cleangates.sh full(lint, gosec, govulncheck, race tests, docker-build, smoke-l25, sbom) — runs on this PR