[lwshang]

Draft / proof of concept. Part 1 of 2 of the icp-cli extensions PoC. Not meant to merge as is.

What

A new crate, icp-extension: the host side of icp-cli extensions. These are third-party commands (icp <name> …) shipped as a single wasm component and run in a wasmtime sandbox.

• extension.wit: the icp:extension@0.1.0 world.
  • The extension exports describe (what it is and which commands it has, as data) and run (run one parsed command).
  • It imports canister-call (as the resolved identity, on the resolved network), confirm and open-url.
• runtime.rs: loads the component and picks the ABI from its icp:extension/types@<version> import, the same way the sync-plugin runtime does.
  • No compute limit: extensions are interactive and may poll for minutes.
  • On mainnet, decided by root key, a call to a canister the extension didn't declare is refused. On any other network calls are unrestricted, so local canister IDs need no configuration.
• validate.rs: install-time checks on what an extension declares (reserved flags such as -e/-n/-k/--identity, duplicates, argument shapes, groups), so nothing it declares can break icp's clap tree.
• tests/fixtures/hello-extension: a test extension exercising every import and export.

The sandbox has no preopened directories, no env, no args, no stdin and no sockets. stdout/stderr go to the terminal. Clocks and randomness are WASI defaults.

Why

Integrations like CyclePay change faster than icp-cli should. With an extension boundary they can ship on their own schedule without icp-cli carrying their code. The design notes are in the linked report. The key choice is that the extension declares its commands, and icp-cli parses them: extensions never handle argv, and help, errors and completion stay consistent with built-in commands.

Tests

cargo test -p icp-extension: describe, errors, confirm/open-url, the "no network" refusal, and the mainnet allowlist versus unrestricted local calls (with a mock CanisterCalls).

Stacked under #840, which wires this into the CLI.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Install-time validation still accepts declarations that can conflict with host options or violate clap’s command-tree requirements.

5 open issues

• Reserve network option group IDs as argument names · New
• Reject leading hyphens in long argument names · New
• Validate defaults against allowed possible values · New
• Reject required positionals after optional positionals · New
• Mark call operands as required · New

What changed in this PR

Adds the proof-of-concept icp-extension host crate for running third-party WebAssembly commands in a Wasmtime sandbox. This provides the runtime foundation; CLI integration is deferred to part 2.

Changes:

• Defines the extension interface, command metadata, and host callbacks.
• Adds sandboxed execution, mainnet canister allowlisting, and install-time declaration validation.
• Adds a test extension and runtime tests for callbacks, errors, and network restrictions.

File	Description
crates/​icp-extension/​tests/​fixtures/​hello-extension/​src/​lib.rs	Implements the test extension’s commands and callbacks.
crates/​icp-extension/​tests/​fixtures/​hello-extension/​Cargo.toml	Defines the standalone fixture crate.
crates/​icp-extension/​tests/​fixtures/​hello-extension/​Cargo.lock	Locks fixture dependencies.
crates/​icp-extension/​tests/​fixtures/​hello-extension/​build.rs	Tracks interface changes for fixture rebuilds.
crates/​icp-extension/​src/​validate.rs	Validates extension declarations and adds validation tests.
crates/​icp-extension/​src/​runtime.rs	Implements loading, execution, host callbacks, and runtime tests.
crates/​icp-extension/​src/​lib.rs	Exposes runtime APIs and metadata types.
crates/​icp-extension/​extension.wit	Defines the versioned extension contract.
crates/​icp-extension/​Cargo.toml	Declares runtime and test dependencies.
crates/​icp-extension/​build.rs	Builds the fixture when the WebAssembly target is installed.
Cargo.toml	Registers the workspace dependency.
Cargo.lock	Records the new crate’s dependencies.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Unrestricted URL delegation exposes unintended host capabilities, and management-canister requests lack the effective routing target they require.

2 open issues

• Validate terminal URLs before opening guest-controlled input · New
• Route management calls to the target canister · New

5 resolved since last review

• Reject required positionals after optional positionals
• Validate defaults against allowed possible values
• Reject leading hyphens in long argument names
• Reserve network option group IDs as argument names
• Mark call operands as required

_{Review effort: Balanced}