docs(adr): 0005 policy & authorization model (per-action Rules) - #136
Merged
Conversation
Records the decision to replace the flat Policy god-struct with a small, default-deny, per-action typed rule list (user-facing: "Rules"), kept as a single pure evaluate() with native U256 caps. No general policy engine enforces wei caps (Cedar/OPA/Biscuit are 64-bit-limited; verified 2026-06-23 against primary specs). Standards posture: adopt-the-shape (RFC 9396, ERC-7715/7710), reference-for-vocabulary (NIST SP 800-162 PEP/PDP/PAP/PIP), reject-as-dependency (Cedar as design bar only, Biscuit unaudited). One vocabulary, two enforcers: #48 software-enforced vs #33 chain-enforced stay distinct. Grounded by a primary-source deep-research pass and two codex adversarial reviews (the second caught spec bugs in an earlier draft, now fixed). Reconciles docs/agent-authorization-map.md (PEP/PDP/PAP/PIP + Rules section) and cross-refs ADR-0002 (session-key grants reuse this vocabulary).
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.
What
Adds ADR-0005 — Policy and authorization model, the decision record behind replacing the flat
Policygod-struct with a small, default-deny, per-action typed rule list (user-facing: "Rules"),kept as a single pure
evaluate()with nativeU256caps.Docs-only. The executable work is tracked in #135.
Why this shape (the "why for others")
(2026-06-23) confirmed Cedar (
Long= i64), Biscuit (signed 64-bit, fail-on-overflow) and peers are~58 orders of magnitude short of
uint256wei. Caps stay in native RustU256.vocabulary (NIST SP 800-162 PEP/PDP/PAP/PIP), reject-as-dependency (Cedar as design bar only;
Biscuit unaudited). No single standard fits — the fit is a composition.
#48(software) and#33(chain) reuse the Rules vocabulary butstay distinct enforcers — software is never "cannot exceed."
Process
Grounded by the deep-research pass above and two codex adversarial reviews — the second reviewed an
earlier draft of this very ADR and caught real spec bugs (dead
Swapfields, a smuggledShieldenforcement, the
Allowlistserde/migration flip, an under-counted blast radius, a versioned-breakgap, and a per-action-vs-global daily-cap incoherence). All are fixed in the committed text; the
architecture survived.
Changes
docs/adr/0005-policy-and-authorization-model.md— new.docs/agent-authorization-map.md— reconciled (PEP/PDP/PAP/PIP + a "Rules" section), date bumped.docs/adr/0002-agent-wallet-and-session-keys.md— cross-refs 0005 as the vocabulary source.Status
ADR is Proposed; it promotes to Accepted when the #135 foundation merges with
evaluate/evaluate_orderparity green.Refs #135.