feat: reject update calls for delegations with queries-only permissions

[aterga]

Queries-only permissions on delegations

This is the consolidated read-only-sessions feature (the previously stacked alternatives #10447/#10452, which carried the restriction in certified sender_info attributes, were closed in favor of this more lightweight approach).

What it does

Request delegations gain an optional permissions field, mirroring the existing targets field. It is modeled as a typed enum DelegationPermissions whose variants are encoded on the wire (and in the representation-independent hash) as text:

• permissions absent or "all" (DelegationPermissions::All) → the sender can execute all functions — queries, replicated queries, and updates (today's semantics; byte-for-byte identical hash for existing delegations without the field).
• "queries" (DelegationPermissions::Queries) → the sender can only execute queries: requests to /call endpoints (updates and replicated queries) authenticated through such a chain are rejected during ingress validation with the new RequestValidationError::UpdateCallNotPermittedByDelegation; query and read_state requests remain permitted.
• Any other value → because the field is a closed enum, an unsupported value fails to deserialize, so the request is rejected when it is decoded (before validation). There is no dedicated validator error for it.

A restriction anywhere in the chain applies to the whole chain (like targets, restrictions only accumulate). The matching interface-spec change (dfinity/developer-docs#292) models the field as the union Queries | All | Unrestricted, which this enum mirrors exactly.

Why this can't be bypassed, and why it's backward compatible

• The field is part of the delegation's representation-independent hash, i.e. covered by the delegation signature. A dapp holding the session key cannot strip the field — doing so changes the hash and invalidates the signature.
• Old replicas fail closed: they parse the delegation without the unknown field (serde ignores unknown map keys), recompute the hash without it, and signature verification fails. A restricted delegation is unusable on un-upgraded replicas rather than silently unrestricted. Rollout: replicas first, issuers (Internet Identity) after.
• Delegations without the field are completely unaffected, so existing agents, dapps, and issuers need no changes. Agents only need to round-trip the new field once they want to carry restricted delegations; an agent that drops it fails closed.
• The enforcement point is HttpRequestVerifier<SignedIngressContent> — the same verifier used by the ingress manager for block validation, so a malicious boundary node or replica cannot smuggle a restricted update call into a block.

Rationale

Enables issuers like Internet Identity to sign read-only delegations: sessions that can read on the user's behalf (query calls) but cannot change state (update calls), enforced by the protocol regardless of the client's cooperation. II sets this field from a "Read-only mode" checkbox in the authorize flow (II-side changes prepared separately).

Historical precedent: the interface spec already extended the delegation map with an optional restriction field once — the senders field (added Dec 2021, never implemented by the replica, removed in interface-spec#246). This PR follows the same formal pattern (verify_delegations accumulation), but implementation-first.

Changes

• ic-types: typed DelegationPermissions { Queries, All } enum (serialized as "queries"/"all"); optional Delegation.permissions field included in the signed bytes (hash_of_map key "permissions"); chainable with_targets/with_permissions builder methods (replacing the former new_with_targets/new_with_permissions constructors so a delegation can carry both).
• ic-validator: DelegationRestrictions (targets + queries-only) threaded through delegation-chain validation; update-call rejection via RequestValidationError::UpdateCallNotPermittedByDelegation. The /call path uses the shared validate_request_content (no special-casing) and checks the restriction afterwards.
• ic-validator-ingress-message: the new error variant mirrored.
• ic-validator-http-request-test-utils: delegate_to_with_permissions chain-builder support.
• Tests: signed-bytes golden test for the new field; CBOR encoding + round-trip tests; a decode-rejection test (delegation_permissions_rejects_unsupported_value) covering unsupported values including case/whitespace variants; validator-level e2e tests (update-rejected / query-and-read_state-permitted / "all"-permitted / restriction-mid-chain / combined targets+permissions); and a system test (requests_with_delegation_permissions in rs/tests/crypto/ingress_verification_test.rs, tagged long_test) exercising the full HTTP path against a real replica.

Caveats / follow-ups

• Calls to query methods submitted via the /call path (replicated queries) are rejected for "queries" delegations by design — the "all" vocabulary makes this explicit.
• Interface-spec change in docs: extend interface spec with delegation permissions field developer-docs#292; II-side issuance and agent (@icp-sdk/core) round-tripping of the field prepared/pending.

cargo test -p ic-types -p ic-validator -p ic-validator-ingress-message passes and clippy is clean; downstream consumers (ic-http-endpoints-public, ic-ingress-manager, ic-canister-client, ic-state-machine-tests) and both affected system-test binaries compile.

https://claude.ai/code/session_01BQNgPJKgxWohrJ6owwJBzz

[Copilot]

Pull request overview

This PR extends IC request delegations with an optional permissions field to support queries-only delegations that are enforced during ingress validation (rejecting /call update requests), while remaining backward compatible for existing delegations and failing closed on unsupported permission values.

Changes:

• Add Delegation.permissions to ic-types, include it in the delegation’s signed bytes, and expose constructors/accessors.
• Thread delegation permission restrictions through ic-validator delegation-chain validation and reject update calls when any delegation in the chain has permissions = "queries".
• Add test utilities and end-to-end tests covering acceptance/rejection behavior across request types and invalid permission values.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
rs/validator/tests/ingress_validation.rs	Adds a golden signed-bytes test covering the new permissions field hashing.
rs/validator/src/ingress_validation/tests.rs	Updates unit tests to match the new validate_signature return type (restrictions vs targets).
rs/validator/src/ingress_validation.rs	Implements delegation permissions parsing, restriction accumulation, and update-call rejection.
rs/validator/ingress_message/tests/validate_request.rs	Adds e2e tests verifying update rejection and query/read_state acceptance for queries-only delegations.
rs/validator/ingress_message/src/lib.rs	Exposes the new validation/authentication error variants in the standalone validator API.
rs/validator/ingress_message/src/internal/mod.rs	Maps new ic_validator error variants into ic_validator_ingress_message equivalents.
rs/validator/http_request_test_utils/src/lib.rs	Extends delegation-chain builder utilities to create delegations with permissions.
rs/types/types/src/messages/http/tests.rs	Updates CBOR serialization tests to include the new permissions field (null or string).
rs/types/types/src/messages/http.rs	Adds Delegation.permissions, constructor/accessor, and includes it in signed-bytes hashing when present.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 937ddbe.

Security Overview

• 🔎 Scanned files: 12 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/f5e9d2bb-29a4-4b64-902a-391d65fd8b2d?scanId=afe8aa02-6647-4418-bb39-bb7bdc6c5fbd&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► rs/tests/consensus/request_auth_malicious_replica_test.rs     Update Delegation::new_with_targets to Delegation::new().with_targets() ► rs/tests/crypto/ingress_verification_test.rs     Add test for delegation permissions ► rs/types/types/src/messages.rs     Add DelegationPermissions enum ► rs/types/types/src/messages/http.rs     Implement DelegationPermissions enum and add to Delegation struct     Add with_permissions method to Delegation     Add tests for DelegationPermissions CBOR serialization and deserialization     Add tests for DelegationPermissions rejecting unsupported values ► rs/validator/http_request_test_utils/src/lib.rs     Add delegate_to_with_permissions method to DirectAuthenticationScheme     Add delegate_to_with_permissions method to DelegationChainBuilder ► rs/validator/ingress_message/src/internal/mod.rs     Map RequestValidationError::UpdateCallNotPermittedByDelegation ► rs/validator/ingress_message/src/lib.rs     Add RequestValidationError::UpdateCallNotPermittedByDelegation     Update HttpRequestVerifier trait and implementations to handle delegation permissions ► rs/validator/ingress_message/tests/validate_request.rs     Add tests for delegation permissions ► rs/validator/src/ingress_validation.rs     Implement DelegationRestrictions struct     Update validate_signature and validate_delegations to handle delegation permissions     Add UpdateCallNotPermittedByDelegation error ► rs/validator/src/ingress_validation/tests.rs     Add tests for delegation permissions
Refactor	► rs/types/types/src/messages/http.rs     Simplify Delegation::new_with_targets to Delegation::new().with_targets()

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

[pierugo-dfinity]

Mostly me ranting about Claude's comments

[aterga]

Thanks @pierugo-dfinity — addressed all of these in 0ecc183:

• Trimmed the verbose doc comments on DelegationPermissions, with_targets, and with_permissions to the concise one-liners you suggested.
• Dropped the broken #authentication anchor (the link now points at the spec page).
• Removed the "Unsupported values…" comment in the system test (artifact of an earlier refactor, no longer relevant — unsupported values are a closed-enum decode concern covered elsewhere).
• Rewrote the confusing "Both remaining outcomes…" comments to "Query calls / read_state requests are permitted regardless of the outcome."

---

Generated by Claude Code