feat: new canister setting status_visibility

[raymondk]

Stacked on #744. Replaces #727, which bundled this with the two fixes below it.

What

Adds support for the status_visibility canister setting introduced in dfinity/ic#10667, which controls who may read a canister's status through the management canister's canister_status endpoint — the running state, cycles balance, memory usage, and the settings themselves.

It takes the same three forms as log_visibility:

settings:
  status_visibility: controllers        # default
  # status_visibility: public
  # status_visibility:
  #   allowed_viewers: ["aaaaa-aa", "2vxsx-fae"]

and the same flag shapes on icp canister settings update:

--status-visibility <controllers|public>
--add-status-viewer / --remove-status-viewer / --set-status-viewer <PRINCIPAL>

The relative edits (--add-*-viewer, --remove-*-viewer) are refused while the setting is public, which carries no allowed viewers list for them to be relative to. That rule is applied to the pre-existing log flags too, which is a behaviour change — see below.

icp canister status and icp canister settings show now report it, in both their default and --json output. It is applied at creation and kept in sync by icp canister settings sync.

How

The three visibility settings the management canister exposes (log_visibility, snapshot_visibility, status_visibility) are structurally identical but are distinct Candid types. Rather than duplicate the manifest type, the parser, the set-wise comparison, the add/remove merge, and the renderer per setting, this introduces one shared Visibility enum in icp::canister::visibility with conversions to and from each Candid type, and a small visibility_setting! macro that declares the per-setting manifest newtype so parse errors and the generated JSON schema still name the specific setting.

That replaces the hand-written LogVisibilityDef (about 110 lines of Deserialize/JsonSchema boilerplate) and makes each further visibility setting a few lines. Downstream, log_visibility_eq became visibility_eq, the four settings update flags share one VisibilityFlags::resolve, and canister status / settings show share one format_visibility.

VisibilityFlags::resolve stays pure — it neither reads the network nor prints — and carries the setting's names so its refusal and its warnings can say which setting they are about. The two warnings live at the callsite, alongside the existing maybe_warn_on_env_vars_change.

log_visibility behaviour is unchanged: same manifest forms, same unknown log_visibility value error text, same $defs/LogVisibility schema name, same rendering.

Relative viewer edits on a public canister

public grants access to everyone, so it carries no allowed viewers list for --add-*-viewer / --remove-*-viewer to be relative to. They started one from empty instead, which meant --add-log-viewer P on a public canister took access away from everyone but P, and --remove-log-viewer P took it away from everyone including P. Neither flag says to change the policy at all, so there was nothing to warn about — the edit had no meaning to carry out.

They are now refused while the setting is public, and the error names the two flags that do state a policy outright:

Log visibility is currently public, so there is no allowed viewers list for
--add-log-viewer to edit. Use `--set-log-viewer <PRINCIPAL>` to replace the
public policy with an explicit list, or `--log-visibility controllers` to
revoke public access on its own.

current policy	--add / --remove	--set-*-viewer	--*-visibility
public	refused — no list to edit	allowed, warns it revokes public access	allowed
controllers	allowed — a list built from it only grants on top	allowed	allowed
allowed_viewers	allowed	allowed	allowed

--set-*-viewer stays legal on a public canister for the same reason the relative edits are not: it states the whole new list, so what it revokes is on its face. It warns rather than refuses, as does removing the last viewer — both are reversible by any controller, and a prompt would break scripted use.

This is breaking for --add-log-viewer / --remove-log-viewer, which shipped with the old behaviour. canister_settings_update_log_visibility asserted the add-to-a-public-canister case succeeding; it now asserts the refusal, followed by the --set-log-viewer that expresses it. The status flags are new, so they were never able to behave otherwise.

Adding a viewer to a controllers canister is unaffected: a list built from controllers grants access on top of the controllers rather than taking any away, so the edit means what it says.

Dependency bump and replica compatibility

ic-management-canister-types 0.8.0 → 0.9.0, which is where StatusVisibility landed. That version also adds minimum_incoming_canister_call_cycles to CanisterSettings and requires candid 0.10.35 (hence the lockfile churn). Both new settings are sent as None, leaving them unchanged.

DefiniteCanisterSettings gained a non-optional status_visibility, so a CLI built against 0.9.0 requires a replica that returns it — otherwise canister_status fails to decode, which affects icp deploy, icp canister status, and icp canister settings show/sync, not just the new setting.

• Mainnet: every subnet runs a version carrying the feature (checked in feat: new canister setting status_visibility #727: all 42 on 59c42492 or 79c01052).
• Local networks: the pinned launcher 15.0.0-2026-08-20-03-30 carries it, as does 15.0.0-2026-08-13-03-55; anything older does not. Contributors with a target/test-fixture older than that must re-run scripts/download_test_network_launcher.sh, or every status-reading test fails with field status_visibility is not optional field.

ic-utils still builds against 0.8, so its CanisterSettings is now a distinct type. The one call site that handed settings to ic-utils was the legacy management-canister fallback, which #744 already moved off it.

Documented access policy

status_visibility is not controller-only under controllers: subnet administrators always retain access, and a canister reading its own status is exempt. log_visibility has neither carve-out — check_log_visibility_permission is a bare has_access(caller, controllers). The schema descriptions are therefore per-setting rather than shared, the reference documents the two always-allowed callers, and canister settings show no longer claims the caller must be a controller (a non-controller granted status access can now run it).

Testing

Unit tests for the shared pieces, which is where the logic now lives:

• icp::canister::visibility — both manifest forms parse, round-trip through serialization, and convert to and from both Candid types; each setting names itself in its parse error.
• VisibilityFlags::resolve — fixed policy wins over viewer edits, --set replaces, --add/--remove apply to the current list, adding a present viewer does not duplicate it, removal keeps the order of the viewers it leaves behind, an edit against controllers starts from empty, and only viewer edits require fetching the current settings.
• The public refusal — each of --add, --remove, and both together, checking that the error names the flags that were passed and both ways out, and that --set is still allowed there.
• canister status --json — the tagged {"type","value"} shape is pinned, since that output goes through a hand-written Serialize impl rather than a derive.

Against a local network:

• canister_settings_update_status_visibility (new) — every flag, checked both in settings show and in what it actually grants: a non-controller is refused and falls back to the public information, then reads the full status once added as a viewer or once the status is public, and is refused again when it is revoked. Also the refusal and the two warnings against a live replica, which is where they can be exercised end to end, and that an update naming neither visibility group leaves both untouched rather than resetting them.
• canister_settings_update_log_visibility (extended) — the refusal on a public canister, and the warning --set-log-viewer prints in its place. The rest of the test is unchanged.
• canister_settings_sync_log_visibility (extended) — a single sync drives both settings from the manifest, which is the case that matters: either change alone would satisfy the "settings already match" check that decides whether to send an update. The three manifest forms themselves are already covered there for log_visibility and go through the same shared parser, so they are not repeated per setting.
• canister_settings_show (extended) — --json carries the new field.

Not in this PR

snapshot_visibility is still passed as None. Its type has shipped since 0.8.0 and the existing TODOs called it out for a follow-up; with this shared machinery in place it is now a short one.

The two commands that report settings disagree on JSON shape, and settings show --json renders numeric settings as Nat limb arrays. Both predate this PR and are filed as #728.

[Copilot]

Pull request overview

Adds end-to-end support for the management canister’s status_visibility setting.

Changes:

• Introduces shared visibility parsing, conversion, comparison, and formatting.
• Supports status visibility in manifests, creation, synchronization, updates, and status output.
• Updates dependencies, schemas, documentation, and integration coverage.

Reviewed changes

Copilot reviewed 18 out of 20 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Cargo.toml	Upgrades management canister types.
Cargo.lock	Locks upgraded dependencies.
CHANGELOG.md	Documents feature and compatibility impact.
crates/icp/src/canister/mod.rs	Adds status visibility to settings.
crates/icp/src/canister/visibility.rs	Implements shared visibility model.
crates/icp/src/project.rs	Resolves manifest status visibility.
crates/icp/src/operations/settings.rs	Synchronizes visibility settings.
crates/icp-cli/src/commands/canister/create.rs	Applies visibility during creation.
crates/icp-cli/src/commands/canister/mod.rs	Shares human-readable formatting.
crates/icp-cli/src/commands/canister/status.rs	Reports status visibility.
crates/icp-cli/src/commands/canister/settings/show.rs	Displays status visibility.
crates/icp-cli/src/commands/canister/settings/update.rs	Adds visibility update flags.
crates/icp-cli/tests/canister_settings_tests.rs	Adds replica integration coverage.
docs/reference/canister-settings.md	Documents access policies and forms.
docs/reference/cli.md	Documents new CLI flags.
docs/reference/configuration.md	Adds configuration example.
docs/schemas/icp-yaml-schema.json	Adds project schema support.
docs/schemas/canister-yaml-schema.json	Adds canister schema support.
docs/schemas/environment-yaml-schema.json	Adds environment schema support.

---

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

[lwshang]

crates/icp-cli/tests/assets/__pycache__/limit_transfer.cpython-312.pyc looks unintentional — it isn't matched by .gitignore, so it'll show up as churn for anyone who runs the Python asset. git rm --cached it and add __pycache__/ to .gitignore.

[raymondk]

@lwshang — thanks, all four review points are addressed. Three commits on top of the stack:

• 69baf35 — the __pycache__ one: git rm --cached'd crates/icp-cli/tests/assets/__pycache__/limit_transfer.cpython-312.pyc and added __pycache__/ to .gitignore, exactly as you suggested. It came in with 554a8eb by accident.
• 5e85733 — the warnings, the retain fix, and the VisibilityFlags::resolve unit tests the description had claimed.
• 18b533f — refuses --add-*-viewer / --remove-*-viewer while the setting is public, which is where I ended up going one step further than your suggestion. Reasoning is in the thread on update.rs; the short version is that those edits have no meaning on a public canister rather than being merely costly, so refusing beats warning. It is breaking for the pre-existing log flags — worth a look if you disagree with that trade.

I've replied on each thread but left them open for you to resolve.

The PR description is updated to match: the public rule and its breaking-change note have their own section, and the testing claims now describe tests that exist.