Gate update calls on the ICP service-discoverability protocol

[aterga]

Summary

canister_update_call could write to any canister id an agent could name — including ids this server had merely found behind a domain, in a response header, an /env.json, or a JS bundle. Provenance like that is evidence about bytes a frontend happened to ship, not a statement by an application about what it comprises, and it should never have authorized a write. That left the financial guard doing double duty as the primary boundary against arbitrary value-moving calls, which is not a job a curated name list can hold.

This makes the ICP service-discoverability protocol the write boundary, in two layers, and reframes #163's guard as defence in depth behind it. A state-changing call runs only when every check in both layers passes.

Layer 1 — the registration gate (crates/imcp2-core/src/authorization.rs, new):

1. The financial guard (Layer 2) does not refuse the method.
2. application_origin is supplied — an https origin, canonicalized.
3. That exact origin is a registered application whose developer accepted the current ICP MCP Developer Terms.
4. That origin serves a well-formed /.well-known/ic-architecture manifest, re-read on every call (no cache).
5. The manifest declares the target canister.
6. Only then does the call execute.

All six must pass, so the order decides only which refusal the caller reads. Layer 2 is evaluated first because it is offline and its refusal is the more useful one: "transfer 1 ICP" should be answered do it in a wallet you control, not that application isn't registered — the latter reads as though registering would make the transfer possible. A value-moving request therefore also never triggers an outbound fetch, and never reveals whether the named origin is registered.

derivation_origin deliberately cannot stand in for application_origin: derivation origins are shared by design — this crate's own registry maps five NNS frontends and eight Oisy hosts onto one each, and target_origin collapses gateway domains — so keying authorization on one would let any frontend in such a set write against a sibling's manifest, and the manifest is served at the application origin anyway.

Layer 2 — the financial guard (compliance.rs, behaviour unchanged) now sits inside that surface. It is origin-blind, so registration cannot launder a value-moving call through it. Per the review discussion, the earlier CMC concern resolves on its own: the CMC is not a registered application and declares no manifest, so canister_update_call cannot reach it at all — the list is now belt to Layer 1's braces rather than the boundary itself.

Registration is two facts, both required. The protocol proves composition and nothing else — serving a manifest establishes no acceptance of terms, no entitlement to expose the canisters listed, no statement about which methods are safe. So this adds the ICP MCP Developer Terms at /developer-terms, addressed to publishers rather than end users, requiring that the publisher is entitled to expose every canister its manifest lists and that its MCP-reachable operations move no value, are safe for an assistant to call, and handle personal data lawfully. REGISTERED_APPLICATIONS records who accepted which revision and when.

Related issues

Builds on #163 (merged into this branch — the diff collapses to just this change once #163 lands). Follows the review discussion on that PR.

Changes

• New authorization.rs — the six-step gate, the RegisteredApplication registry, and DEVELOPER_TERMS_VERSION. The policy lives in authorize_with, with the registry and the manifest fetch injected, so the tests drive the production chain rather than a copy of it.
• New architecture.rs — the protocol itself: /.well-known/ic-architecture parsing (validated version, principal-checked ids, sanitized labels, whole-manifest rejection past the entry cap rather than silent truncation, a 5s read budget) and /.well-known/ii-derivation-origin. Documents which of the five protocol layers this server implements where.
• canister_update_call takes application_origin (required) and echoes it back with declared_as — how the application's own manifest describes the canister that was called.
• The protocol's own files take over from /ai-connect.html, which is removed outright along with parse_meta/attr. /.well-known/ic-architecture is the authorizing composition source; /.well-known/ii-derivation-origin is the identity source, keeping the cross-origin authorization check against the declared origin's ii-alternative-origins (ICPBB-430). candid:service, getApiDoc, and OQL were already implemented and are now documented as the same protocol's interface/behaviour/data layers.
• /.well-known/ic-app.json stays as a read-only fallback. Dropping it (as the first commit did) was a gratuitous regression: apps that shipped it lost their declared canisters from discovery, which the write gate never needed. It ranks below ic-architecture, supplies the declared derivation origin only when an app serves no ii-derivation-origin, and authorizes nothing.
• The header, /env.json, and bundle mining stay as read-only hints, relabelled as such in code, output schema, tool descriptions, and README: they say what may be readable, never what may be written.
• New /developer-terms page, in the same document shell as /terms, with its revision and effective date interpolated from the constant the gate enforces (pinned by a test, so the page and the enforced revision cannot drift). Linked from /terms §4 and the landing-page footer.
• Docs in step: README gains "The ICP service-discoverability protocol", "Update-call authorization", "The Developer Terms" and "Hardened discovery fetches" sections; both directory-submission dossiers, the landing-page copy, SERVER_INSTRUCTIONS, and the local binary's README describe the two-layer posture.
• The manifest fetch reuses the existing site-fetch guards (public-address resolution, connection pinning, redirect policy, capped body) and adds an exact-origin check, since the shared redirect policy permits same-host different-port hops. Because the registry check precedes the fetch, the authorization path only ever fetches curated origins — a caller cannot use an update call to steer the client at an origin of their choosing.

Testing

cargo test --locked --workspace --all-targets: 173 core (up from 153) + 52 + 11 + 9 + 20 local, all green. The five properties from the review, each driving the real gate with an injected registry and fetch:

• a canister found only through bundle mining, /env.json, a header, or /ai-connect.html cannot receive updates — and the same id is writable from the application that declares it, so the refusal is about the missing declaration, not the id;
• a canister the manifest declares, whose origin lacks a current Terms acceptance, cannot — asserted together with a fetch count of zero, which turns "the registry is checked before anything is fetched" into a pinned property;
• a registered non-financial app can, and the echo names what authorized it;
• a financial method stays blocked on a registered app — including when the app declares the ICP ledger in its own manifest — and the financial refusal is byte-identical registered, unregistered, and with no origin at all;
• revocation, a Terms-revision bump, and a manifest that drops a canister each fail closed on the next call (and reverse in both directions, so nothing latches); an unreadable manifest fails closed and says it is retryable, distinguishably from a denial.

Also: an empty registry authorizes nothing and says so; membership compares parsed principals; origin canonicalization accepts equivalent spellings and refuses non-https / user-info / another port without fetching; end-to-end proofs through a real MCP client in imcp2-local; and a test asserting both the tool description and SERVER_INSTRUCTIONS teach the gate.

• cargo build --locked --all-targets
• cargo test --locked --all-targets (and --workspace --all-targets)
• cargo fmt --all / cargo clippy --all-targets (tree is warning-free) — see note below
• npm test --prefix monitoring/mcp-status (dashboard unchanged)

cargo clippy --all-targets is unchanged from the pre-change baseline: 6 warnings, all pre-existing (map_or simplifications ×5, one redundant closure), none in new code — verified by measuring the same command against the merge base. cargo fmt --all is deliberately not run: on a pristine tree it rewrites 3283 lines across 15 files it should not touch, so the repo is not currently rustfmt-clean and running it would bury this change in unrelated churn. The two new files are rustfmt-clean; touched regions match their surroundings. Worth fixing separately.

Review round already applied

The second commit is the result of an adversarial pass over the first: 32 candidate findings, 28 refuted on the code, 4 confirmed and fixed. Beyond the layer reordering and the ic-app.json restoration above, it fixes two real bugs — is_app_data_candidate compared a label to "frontend" by equality, so a manifest-declared frontend (the protocol's own example folds to "the frontend (frontend)") was handed out as an app data canister; and parse_derivation_origin accepted a bare host, so any one-token 200 body became a bogus cross-origin claim that then hard-failed app resolution. It also corrects prose that had drifted from the code: "revocation takes effect on the very next call" (true of caching, misleading about a compiled-in table), "only registry origins are ever fetched" (true of the write path, not of discovery), and two directory-submission walkthroughs that told reviewers to observe update-call outcomes the gate makes unreachable.

Two things for you to confirm

1. The registry ships empty, so no application can receive an update call until a publisher actually accepts the Developer Terms and a reviewed change adds a row. That is the honest fail-closed default — I can't record an acceptance that hasn't happened — but it means update calls are off on merge, and the directory-submission docs now say so plainly. If some app should ship registered, that's a row plus the acceptance to point at.
2. imcp2-local inherits the gate, so writing to your own canister through the local binary is refused unless it is registered. I chose uniform enforcement over a per-deployment escape hatch (no bypass to misuse), and said so plainly in its README — but the local binary's primary user is the canister owner, so this is a real product trade-off rather than a detail.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SzGAjX3k9utczAg2Jw8yQX

[Copilot]

Pull request overview

Adds protocol-based authorization for update calls, backed by application registration, live architecture manifests, and developer terms.

Changes:

• Gates writes by registered origin and declared canister.
• Adds service-discoverability parsing and identity resolution.
• Updates documentation, terms, and financial safeguards.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/main.rs	Serves Developer Terms.
src/assets/terms.html	Links registration terms.
src/assets/developer-terms.html	Defines publisher obligations.
README.md	Documents discovery and authorization.
docs/openai-directory-submission.md	Updates compliance guidance.
docs/anthropic-directory-submission.md	Updates compliance guidance.
crates/imcp2-local/src/server.rs	Tests local gate behavior.
crates/imcp2-local/README.md	Documents local enforcement.
crates/imcp2-core/src/tools.rs	Integrates the write gate.
crates/imcp2-core/src/lib.rs	Exposes authorization constants.
crates/imcp2-core/src/identities.rs	Updates identity documentation.
crates/imcp2-core/src/discover.rs	Adds protocol discovery and identity files.
crates/imcp2-core/src/compliance.rs	Expands financial-call refusals.
crates/imcp2-core/src/calls.rs	Adds authorization arguments and output.
crates/imcp2-core/src/authorization.rs	Implements registration authorization.
crates/imcp2-core/src/architecture.rs	Parses and fetches architecture manifests.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.