docs: extend interface spec with delegation permissions field#292
Open
aterga wants to merge 2 commits into
Open
docs: extend interface spec with delegation permissions field#292aterga wants to merge 2 commits into
aterga wants to merge 2 commits into
Conversation
Specify the optional permissions field of request delegations drafted in dfinity/ic#10449: - https-interface.md: document the permissions field of the delegation map ("queries" restricts the delegation to query calls and read_state requests, "all" is the same as omitting the field, any other value makes the delegation invalid for all kinds of requests) and add permissions to the string-typed fields in the representation- independent hashing section. - abstract-behavior.md: extend SignedDelegation with permissions : Text | Unrestricted and amend verify_envelope / verify_delegations so that unsupported values fail verification for all requests and update calls fail if any delegation in the chain is restricted to queries. - changelog.md: add a 0.63.0 entry for the feature. https://claude.ai/code/session_01WBqBka57Q7xYi4btZYfPqT
|
🤖 Here's your preview: https://k7oic-piaaa-aaaam-ai7uq-cai.icp0.io |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Internet Computer (IC) interface specification to describe a new optional permissions field on request delegations, aligning the spec and formal model with the draft replica implementation semantics (including “whole-chain” restrictions).
Changes:
- Documented the optional
permissionsdelegation field and its semantics in the HTTPS interface spec (including hashing coverage for signatures). - Updated the formal model (
abstract-behavior.md) to modelpermissionsand enforce it inverify_delegations/verify_envelope. - Added a changelog entry for the new field (currently marked as needing release/version/date confirmation).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/references/ic-interface-spec/https-interface.md | Adds permissions to delegation documentation and includes it in hashing examples. |
| docs/references/ic-interface-spec/abstract-behavior.md | Extends the formal SignedDelegation model and updates verification predicates to enforce permissions semantics. |
| docs/references/ic-interface-spec/changelog.md | Adds a new changelog entry describing the permissions delegation field. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+11
to
+13
| <!-- Needs human verification: version number and date of the 0.63.0 entry to be confirmed when the permissions feature is released --> | ||
| ### 0.63.0 (2026-06-12) {$0_63_0} | ||
| * New optional `permissions` field in request delegations restricting the kinds of requests |
The draft status was only visible in an HTML comment, so the rendered changelog presented a provisional version and date as a finalized release. Mark the entry visibly as unreleased and drop the date until the feature ships. https://claude.ai/code/session_01WBqBka57Q7xYi4btZYfPqT
Author
|
Feedback addressed:
Generated by Claude Code |
mraszyk
reviewed
Jun 14, 2026
| targets : [CanisterId] | Unrestricted; | ||
| expiration : Timestamp | ||
| expiration : Timestamp; | ||
| permissions : Text | Unrestricted |
Contributor
There was a problem hiding this comment.
We could consider using an enumeration type here, but a text type is probably easier to handle.
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
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.
Summary
Extends the IC interface spec with the optional
permissionsfield of request delegations, as drafted in the replica implementation in dfinity/ic#10449.https-interface.md(Authentication): documents the newpermissionsfield of the delegation map."queries"restricts the delegation to query calls andread_staterequests; requests to/callendpoints are not accepted if any delegation in the chain carries this value, and a later delegation cannot lift the restriction."all"is the same as omitting the field. Any other value makes the delegation invalid for requests of any kind (fail-closed). Also addspermissionsto the string-typed field examples in the representation-independent hashing section, since the field is covered by the delegation signature.abstract-behavior.md(formal model): extendsSignedDelegationwithpermissions : Text | Unrestricted.verify_delegationsnow requires every delegation'spermissionsfield to hold a supported value, andverify_envelopefails for update calls (content of typeRequest) when any delegation in the chain is restricted to"queries". Becauseverify_envelopecan distinguish update calls from read-only requests by the type of the enclosed content, no changes to the nine call sites ofverify_envelopewere needed.changelog.md: adds a 0.63.0 entry visibly marked "unreleased"; an HTML comment instructs to assign the final version number and release date when the feature ships.Structural decisions
validate_delegationsinrs/validator/src/ingress_validation.rsof the draft implementation, including its test for a restriction sitting in the middle of a chain./callendpoints rather than "update calls" alone, so replicated queries (query methods submitted as update calls) are explicitly covered, matching the implementation which rejects at ingress validation.npm run buildpasses (209 pages).https://claude.ai/code/session_01WBqBka57Q7xYi4btZYfPqT