refactor: adopt ic-utils with_canister_settings in create_mgmt (#661)

* refactor: adopt ic-utils with_canister_settings in create_mgmt

Bump the agent-rs crates (ic-agent, ic-utils, ic-identity-hsm) to 0.49.1
and ic-management-canister-types to 0.8.0 so create_mgmt can use the new
CreateCanisterBuilder API from dfinity/agent-rs#737.

create_mgmt now builds the call via
ManagementCanister::create_canister().with_canister_settings(...), and
routes to the target subnet with with_effective_subnet_id(subnet) instead
of resolving a canister id from the subnet's ranges. This drops the manual
Encode!/update/Decode! dance and the canister-range lookup; the function
now takes the subnet Principal directly. Validated end-to-end by the
canister_create_cloud_engine integration test.

Also handle the breaking changes the bump introduces:
- CanisterSettings/DefiniteCanisterSettings gained snapshot_visibility;
  add it to the two exhaustive settings literals (left None with a TODO to
  make it configurable like log_visibility in a follow-up PR).
- ic_agent::identity::Delegation gained permissions; add permissions: None
  to the three literal constructions.
- ManagementCanister::canister_status now returns QueryOrUpdateCall; use
  .call() in the canister top-up test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: explain why imported delegations use permissions: None

The wire DelegationChain from the cli-backend canister has no permissions
field and the CLI only ever signs unrestricted delegations, so every
delegation reconstructed here was signed with permissions absent. Because
the field is skip_serializing_if'd out of the signable hash when None,
reproducing it as None yields the exact signed bytes and the chain still
verifies in DelegatedIdentity::new. Documents this to preempt the concern
that None drops a signed field.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lwshang

Cargo.lock

@@ -53,15 +53,15 @@ hex = { version = "0.4.3", features = ["serde"] }
 hmac = { version = "0.13", features = ["zeroize"] }
 hybrid-array = { version = "0.4.10", features = ["zeroize"] }
 httptest = "0.16.3"
-ic-agent = { version = "0.47.0" }
+ic-agent = { version = "0.49.1" }
 ic-ed25519 = "0.6.0"
 ic-ledger-types = "0.16.0"
-ic-management-canister-types = { version = "0.7.1" }
-ic-utils = { version = "0.47.0" }
+ic-management-canister-types = { version = "0.8.0" }
+ic-utils = { version = "0.49.1" }
 icp = { path = "crates/icp" }
 icp-canister-interfaces = { path = "crates/icp-canister-interfaces" }
 icp-sync-plugin = { path = "crates/icp-sync-plugin" }
-ic-identity-hsm = "0.47.0"
+ic-identity-hsm = "0.49.1"
 icrc-ledger-types = "0.1.10"
 indexmap = { version = "2", features = ["serde"] }
 indicatif = "0.18.0"

Cargo.toml

@@ -305,6 +305,10 @@ pub(crate) async fn exec(ctx: &Context, args: &UpdateArgs) -> Result<(), anyhow:
         log_memory_limit: args.log_memory_limit.as_ref().map(|m| Nat::from(m.get())),
         log_visibility,
         environment_variables,
+        // TODO: expose snapshot_visibility as a `settings update` flag (with
+        // set/add/remove-viewer sub-flags), mirroring log_visibility. Tracked for
+        // a follow-up PR; until then, leave it unchanged.
+        snapshot_visibility: None,
     };
 
     proxy_management::update_settings(

crates/icp-cli/src/commands/canister/settings/update.rs

@@ -57,6 +57,7 @@ pub(crate) async fn exec(ctx: &Context, args: &SignArgs) -> Result<(), SignError
         pubkey: target_pubkey.clone(),
         expiration,
         targets: args.canisters.clone(),
+        permissions: None,
     };
 
     let sig = identity

crates/icp-cli/src/commands/identity/delegation/sign.rs

@@ -3,16 +3,14 @@ use std::time::Duration;
 
 use bigdecimal::{BigDecimal, ToPrimitive};
 use candid::{Decode, Encode, IDLArgs, IDLValue, Nat, Principal};
-use ic_agent::{
-    Agent, AgentError,
-    agent::{Subnet, SubnetType},
-};
+use ic_agent::{Agent, AgentError, agent::SubnetType};
 use ic_ledger_types::{
     AccountIdentifier, Memo, Subaccount, Tokens, TransferArgs, TransferError, TransferResult,
 };
 use ic_management_canister_types::{
-    CanisterIdRecord, CanisterSettings, CreateCanisterArgs as MgmtCreateCanisterArgs,
+    CanisterSettings, CreateCanisterArgs as MgmtCreateCanisterArgs,
 };
+use ic_utils::interfaces::ManagementCanister;
 use icp::parsers::to_token_unit_amount;
 use icp::signal::stop_signal;
 use icp_canister_interfaces::{
@@ -216,7 +214,7 @@ impl CreateOperation {
             .await
             .context(GetSubnetSnafu)?;
         let cid = if let Some(SubnetType::CloudEngine) = subnet_info.subnet_type() {
-            self.create_mgmt(settings, &subnet_info).await?
+            self.create_mgmt(settings, selected_subnet).await?
         } else {
             self.create_ledger(settings, selected_subnet).await?
         };
@@ -278,32 +276,22 @@ impl CreateOperation {
     async fn create_mgmt(
         &self,
         settings: &CanisterSettings,
-        selected_subnet: &Subnet,
+        subnet: Principal,
     ) -> Result<Principal, CreateOperationError> {
-        let arg = MgmtCreateCanisterArgs {
-            settings: Some(settings.clone()),
-            sender_canister_version: None,
-        };
-
-        // Call management canister create_canister
-        let resp = self
-            .inner
-            .agent
-            .update(&Principal::management_canister(), "create_canister")
-            .with_arg(Encode!(&arg).context(CandidEncodeSnafu)?)
-            .with_effective_canister_id(
-                *selected_subnet
-                    .iter_canister_ranges()
-                    .next()
-                    .context(CreateCanisterSnafu {
-                        message: "subnet did not contain canister ranges",
-                    })?
-                    .start(),
-            )
+        // Call the management canister's create_canister, routing the request to
+        // the target subnet by its id (subnet-scoped, so no canister on that
+        // subnet is needed to derive an effective canister id) and forwarding the
+        // settings as a whole via `with_canister_settings`. Subnet-scoped routing
+        // requires subnet-administrator permissions, which the CloudEngine path has.
+        let mgmt = ManagementCanister::create(&self.inner.agent);
+        let (canister_id,) = mgmt
+            .create_canister()
+            .with_effective_subnet_id(subnet)
+            .with_canister_settings(settings.clone())
+            .call_and_wait()
             .await
             .context(AgentSnafu)?;
-        let resp: CanisterIdRecord = Decode!(&resp, CanisterIdRecord).context(CandidDecodeSnafu)?;
-        Ok(resp.canister_id)
+        Ok(canister_id)
     }
 
     async fn create_proxy(

crates/icp-cli/src/operations/create.rs

@@ -200,6 +200,10 @@ pub(crate) async fn sync_settings(
         log_memory_limit: log_memory_limit.as_ref().map(|m| Nat::from(m.get())),
         environment_variables: environment_variable_setting,
         controllers: controllers_setting,
+        // TODO: make snapshot_visibility configurable from the manifest and synced
+        // here, mirroring log_visibility (Controllers/Public/AllowedViewers).
+        // Tracked for a follow-up PR; until then, leave it unchanged.
+        snapshot_visibility: None,
     };
 
     proxy_management::update_settings(

crates/icp-cli/src/operations/settings.rs

@@ -56,7 +56,13 @@ async fn canister_top_up() {
 
     let agent = ctx.agent();
     let mgmt = ManagementCanister::create(&agent);
-    let canister_balance = mgmt.canister_status(&canister_id).await.unwrap().0.cycles;
+    let canister_balance = mgmt
+        .canister_status(&canister_id)
+        .call()
+        .await
+        .unwrap()
+        .0
+        .cycles;
 
     ctx.icp()
         .current_dir(&project_dir)
@@ -102,6 +108,12 @@ async fn canister_top_up() {
         ))
         .success();
 
-    let new_canister_balance = mgmt.canister_status(&canister_id).await.unwrap().0.cycles;
+    let new_canister_balance = mgmt
+        .canister_status(&canister_id)
+        .call()
+        .await
+        .unwrap()
+        .0
+        .cycles;
     assert!((canister_balance + 10 * TRILLION) - new_canister_balance < 100_000_000_u128);
 }

crates/icp-cli/tests/canister_top_up_tests.rs

@@ -76,6 +76,13 @@ pub fn to_agent_types(
                     pubkey,
                     expiration,
                     targets,
+                    // The wire `DelegationChain` carries no request-kind
+                    // permissions, and the delegations the CLI signs are always
+                    // unrestricted, so every delegation here was signed with
+                    // `permissions` absent. `None` reproduces the exact signed
+                    // bytes (it is `skip_serializing_if`'d out of the hash), so
+                    // the chain still verifies in `DelegatedIdentity::new`.
+                    permissions: None,
                 },
                 signature,
             })

crates/icp/src/identity/delegation.rs

@@ -477,6 +477,7 @@ fn create_pem_session_and_build_identity(
         pubkey: session_pubkey.clone(),
         expiration,
         targets: None,
+        permissions: None,
     };
 
     let sig = identity