Restrict update calls to canisters an app declares (service discoverability)

[aterga]

Summary

Reading the Internet Computer is open; writing is not. A state-changing call runs against someone's live application, and a canister being publicly callable is not a statement by its operators that they want an agent driving it.

canister_update_call is now made only to a canister the owning app declares in its service-discoverability manifest at /.well-known/ic-architecture. Per the published guide, publishing that manifest is exactly how an app's operators opt in: it says "these are my canisters; an agent handed my URL may work them out and use them". An app that publishes none stays fully readable and discoverable, but cannot be written to through this server.

The manifest lives at the app's origin, not on chain, so canister_update_call takes a new app_url argument (open_app already returns it) naming the app whose manifest authorizes the write, falling back to derivation_origin when the app serves its manifest at that same origin. A successful call echoes declared_by/declared_at, so a write's provenance is visible in the reply, not only to the gate.

Supporting protocol work in discover was needed because the gate keys on the protocol rather than on this server's earlier proposal: /.well-known/ic-architecture is now read during discovery, and /.well-known/ii-derivation-origin (Layer 5) now takes precedence over the legacy manifest's derivation_origin field. Without that second piece, an app that follows the published guide and pins a custom derivation origin would resolve to the wrong principal — a bug this change would otherwise have created, since it makes the protocol the thing writes key on.

This pairs with dfinity/developer-docs#372 (merged), which states on the guide itself that publishing the Layer 1 manifest is the act that opts an app in to ICP MCP, under its terms and privacy policy. The doc and the gate now say the same thing.

What this gate is not, stated in the module doc and the README so nobody over-claims it:

• It is not proof of ownership. Whoever controls a domain controls what its manifest says, so a manifest can name a canister its publisher does not own. What it establishes is that someone published a document, at an origin the caller named, claiming that canister as part of their app, and that a write can be traced back to that claim. It bounds blast radius; it does not stop a determined attacker.
• It is not a substitute for the canister's own authorization. The IC still decides what the calling principal may do; this decides what this server is willing to send.
• It is not a read restriction. canister_query, get_canister_candid, get_canister_api_doc, the OQL surface and every discovery tool are untouched.

Related issues

None linked.

Changes

• New discoverability module — the policy and every refusal text, sitting alongside compliance (the financial-methods gate). Refusals distinguish their causes (no origin given / origin unreachable / no manifest published / published but this canister is not in it, which lists what the app does declare); each names the standard path, links the guide, points at skill://service-discoverability for the deploy-time recipe, and states that reads are unaffected.
• canister_update_call gains app_url and returns declared_by/declared_at. The gate runs after the financial-methods refusal and before fetching the target's Candid, so a canister that will not be written to is not touched at all.
• discover reads /.well-known/ic-architecture (ranked just under the App Connect main-backend meta, above the legacy path) and /.well-known/ii-derivation-origin. The well-known probes on each path run concurrently, so honouring both the protocol and the legacy path costs no extra round trip. Manifest labels fall back to the protocol's name when no role is given.
• Fail-closed on the SPA catch-all the guide calls out as the most common misconfiguration (it answers /.well-known/* with index.html, at 200, so status alone would not catch it). A body that is not a manifest document reads as "publishes none" rather than "declares nothing", and an HTML first line is not an origin, so a mis-served Layer 5 file leaves the app deriving against its visible origin instead of garbage. The refusal names the misconfiguration and its fix.
• Redirect pinning — a manifest is honoured only when the origin that answered is the origin that was probed, so a 3xx cannot let one origin borrow another's declaration and make declared_by a true-looking but wrong statement.
• Canister-principal rule — the guide says an id "must be a canister principal"; the gate enforces that (10-byte opaque, 0x01 tag) rather than merely "parses as a principal". Notably this stops a manifest declaring the management canister aaaaa-aa, whose blob is empty and which Principal::from_text accepts.
• Sanitized, capped error echo — a transport error can carry a hostile origin's TLS certificate subject or redirect URL straight into the model's context; it goes through a control-char scrub capped at 200 chars.
• Over-long manifests are reported, not silently truncated — entries past the 100-entry read cap are declared, so refusing one as "not declared" would be a false statement about the app; the refusal blames the manifest's length instead.
• Docs: README gains a "Writes are gated on the discoverability manifest" section; the app-declared-metadata section leads with the protocol; the tool table, typical flow, and derivation-origin precedence notes are updated; and the SSRF section records that canister_update_call makes an untrusted outbound fetch, which became true the moment the gate landed. The server-level instructions gain a "WRITES GO ONLY TO APPS THAT OPTED IN" paragraph. A note on mgmt_call records why the deferred management writes sit outside this gate.
• Merged main (3473724), which moved under this branch. No textual conflict, but that series touched tools.rs, IcTools::new and the README, so the merge was verified rather than assumed: it builds and the full suite passes.

Open questions for the maintainer

Deliberately not decided in this PR:

1. Nothing published on the standard path yet. Probed live: opencloud.org and oisy.com answer 200 text/html on every well-known path; the only origin that authorizes anything is MULTI/DEX, and only via the legacy ic-app.json. So the legacy fallback is load-bearing today — dropping it would make the write tool dead everywhere. Kept, with a tracing::warn naming the origin on every legacy authorization so retirement can be decided on evidence. When does legacy stop authorizing, and on what trigger?
2. The submission docs' demo app. opencloud.org publishes no manifest, so the worked examples in docs/anthropic-directory-submission.md and docs/openai-directory-submission.md — including the "exercise canister_update_call" checklist item — are unsatisfiable against it. Either that app publishes a manifest, or those examples move to one that does. Not edited here.
3. Privacy policy — timely, since main just re-dated it to August 28. Two specific spots in docs/icp-mcp-privacy-policy-draft.md:
   • "Websites you ask the Service to look up. When you ask it to find the application behind a web address, the Service fetches metadata from that address…" is now incomplete. The Service also fetches from the app's address when you act: every update call reads that app's manifest before the write. The trigger widens from "when you ask it to look up an app" to "when you look up an app, or act on one".
   • "The authorization is not restricted to particular applications." stays true of the credential (a per-app identity is derived for whichever app is named), but a reader will take it to mean the assistant can act at any application, and that is no longer so — actions now reach only apps that publish a manifest. Arguably a sentence in the assistant's favour, but it should say so rather than overstate.
     Legally reviewed text with a published dated version at src/assets/privacy-policy.html; flagged, not edited.
4. Derivation-origin coupling. The sharpest remaining hole: app_url=https://evil.example (whose manifest declares canister V) plus derivation_origin=https://gooddapp.com writes to V signed as the user's good-app principal. Closing it means requiring the app origin's own resolved derivation origin to match — which needs a multi-origin set (13 of 17 known-app entries have derivation_origin != application_origin; NNS's is a different canister) or it false-refuses NNS and Oisy. Worth doing, but it is a behaviour change that deserves its own decision.
5. System-canister denylist. manage_neuron on NNS governance is irreversible and value-moving and is not covered by compliance.rs. A denylist would refuse it even to an app that legitimately declares it (the NNS dapp being exactly that case). This is a pre-existing compliance.rs gap that the gate narrows but does not close.
6. Manifest version. Currently ignored. Refusing an unknown major fails closed but bricks every write the day 2.0.0 ships; the spec's own evolution rule is "unknown fields must be ignored". MULTI/DEX omits the field entirely.

Testing

• cargo build --locked --all-targets
• cargo test --locked --all-targets — 264 pass, 0 fail, on the merge with current main. New: 14 unit tests over the refusal texts and the gate's fail-closed parsing, 3 live-network tests over the gate itself, and 2 pinning the gate's statement on the tool description, the input schema, and the server instructions. Negative pins assert no gate refusal borrows the vocabulary of the read-only-session rejection ("reconnect", "Actions & questions") or of the financial-methods refusal ("oisy.com"), since either would send the user to fix something that is not broken.
• cargo clippy --locked --workspace --all-targets — 11 warnings, 10 pre-existing. The one added is repeat().take() in a new test, matching the identical idiom in the test 80 lines above it; repeat_n there would leave two adjacent tests spelling the same thing differently.
• Verified live against the reference app and three others, including that all four answer /.well-known/ic-architecture with the SPA shell today — the exact case the fail-closed tests pin.
• cargo fmt --all — deliberately not run: main already carries 491 rustfmt deviations, the house style is hand-formatted, and CI does not check it, so reformatting would bury the change.
• npm test --prefix monitoring/mcp-status — not applicable, the dashboard is unchanged.

Checklist

• I have read the Contributing guidelines.
• Docs (README / comments) updated for any user-visible change.
• No secrets, credentials, or internal-only information are included.