Skip to content

docs: extend interface spec with delegation permissions field#292

Open
aterga wants to merge 2 commits into
mainfrom
claude/gracious-cerf-zou2uv
Open

docs: extend interface spec with delegation permissions field#292
aterga wants to merge 2 commits into
mainfrom
claude/gracious-cerf-zou2uv

Conversation

@aterga

@aterga aterga commented Jun 12, 2026

Copy link
Copy Markdown

Summary

Extends the IC interface spec with the optional permissions field of request delegations, as drafted in the replica implementation in dfinity/ic#10449.

  • https-interface.md (Authentication): documents the new permissions field of the delegation map. "queries" restricts the delegation to query calls and read_state requests; requests to /call endpoints 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 adds permissions to 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): extends SignedDelegation with permissions : Text | Unrestricted. verify_delegations now requires every delegation's permissions field to hold a supported value, and verify_envelope fails for update calls (content of type Request) when any delegation in the chain is restricted to "queries". Because verify_envelope can distinguish update calls from read-only requests by the type of the enclosed content, no changes to the nine call sites of verify_envelope were 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

  • The whole-chain semantics ("queries" anywhere in the chain restricts the entire chain; unsupported values reject all request kinds) mirror validate_delegations in rs/validator/src/ingress_validation.rs of the draft implementation, including its test for a restriction sitting in the middle of a chain.
  • The restriction is phrased against /call endpoints 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 build passes (209 pages).

https://claude.ai/code/session_01WBqBka57Q7xYi4btZYfPqT

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
@github-actions github-actions Bot added the interface-spec Changes to the IC interface specification label Jun 12, 2026
@github-actions

github-actions Bot commented Jun 12, 2026

Copy link
Copy Markdown

🤖 Here's your preview: https://k7oic-piaaa-aaaam-ai7uq-cai.icp0.io

@aterga aterga marked this pull request as ready for review June 12, 2026 16:26
@aterga aterga requested review from a team as code owners June 12, 2026 16:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 permissions delegation field and its semantics in the HTTPS interface spec (including hashing coverage for signatures).
  • Updated the formal model (abstract-behavior.md) to model permissions and enforce it in verify_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

aterga commented Jun 12, 2026

Copy link
Copy Markdown
Author

Feedback addressed:

  • The changelog entry no longer presents a provisional release as final: the heading now reads 0.63.0 (unreleased) in the rendered changelog, the fabricated date is gone, and the HTML comment instructs to assign the final version and release date when the feature ships.

Generated by Claude Code

targets : [CanisterId] | Unrestricted;
expiration : Timestamp
expiration : Timestamp;
permissions : Text | Unrestricted

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could consider using an enumeration type here, but a text type is probably easier to handle.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

interface-spec Changes to the IC interface specification

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants