feat(rust): custom_value_endpoints form for export_encrypted_maps_canister!

[marc0olo]

Implements the Rust half of #423.

What changes

export_encrypted_maps_canister! gains a second form:

// Full canister (unchanged — the 95% case):
ic_vetkeys::export_encrypted_maps_canister!("app", [memory(0), memory(1), memory(2), memory(3)]);

// New: control-plane + state + lifecycle + accessors, but NO value endpoints:
ic_vetkeys::export_encrypted_maps_canister!("app", [memory(0), memory(1), memory(2), memory(3)], custom_value_endpoints);

The custom_value_endpoints form generates the 8 control-plane endpoints, the stable state, #[init]/#[post_upgrade], and two accessors — but omits the 7 value read/write endpoints. Both forms now emit:

fn with_encrypted_maps<R>(f: impl FnOnce(&EncryptedMaps<AccessRights>) -> R) -> R;
fn with_encrypted_maps_mut<R>(f: impl FnOnce(&mut EncryptedMaps<AccessRights>) -> R) -> R;

Why

The generators are all-or-nothing today, so the common "wrap-and-extend" pattern — a canister that stores something linked to each value (e.g. a metadata row per entry) and must own the value endpoints to keep the two stores consistent — can't use the macro at all and hand-writes ~200 lines. custom_value_endpoints lets it generate the safe control-plane passthroughs and write only its custom value endpoints, reusing the library's vetKD/crypto/ACL via the accessors.

Coarse (whole value data-plane) instead of a fine-grained exclude: [list], deliberately — it's one unmissable decision rather than a list you can under-specify. (The exclude list in #423's own body proved the trap: it listed 6 names and omitted get_all_accessible_encrypted_maps, which returns raw values via EncryptedMapData.keyvals — a leak.) It's also forward-safe: a value endpoint added to the library later is hidden from adopters automatically, whereas a baked-in exclude list would silently re-expose it. Full rationale and the alternatives considered are in the #423 thread.

How it simplifies adoption (password_manager_with_metadata)

Today that example (~250 lines) forgoes the generator and hand-writes 11 endpoints; ~120–130 of those lines are the 8 passthroughs + init/post_upgrade/state setup that the generator already produces. With custom_value_endpoints those collapse to a 3-line macro call and only the 3 genuine *_with_metadata endpoints stay hand-written — roughly halving the file, keeping the passthroughs frontend-compatible by construction, and never emitting the raw value mutators (so the value↔metadata invariant can't be bypassed at the boundary).

Which endpoints, and the rationale

• Omitted (value data-plane, 7): writes insert_encrypted_value, remove_encrypted_value, remove_map_values; reads get_encrypted_value, get_encrypted_values_for_map, get_all_accessible_encrypted_values, get_all_accessible_encrypted_maps.
• Only the 3 writes can break an adopter invariant (correctness). The 4 reads are dropped for API-surface hygiene (no metadata-less value view beside the wrapped one). Documented in the macro rustdoc.
• Kept (control-plane, 8): none read or write values — set_user_rights/remove_user touch only the ACL, no value cascade — so they're always safe to emit.

Interface / release impact

• The full form is unchanged. Endpoints are factored into inner macros, but export_candid! emits methods alphabetically, so the generated .did is identical — verified by diffing the extracted candid (method set identical) and by interface-sync regenerating declarations from the committed .did (untouched). No frontend files or .did change; no frontend release.
• Additive/minor change. Recorded under an Unreleased changelog heading; the version number is assigned at release time (no Cargo.toml bump in this PR).

Docs

• Macro rustdoc documents both forms, the omitted set with the write=correctness / read=hygiene rationale, the accessors, a metadata example, and the escape hatch if a write-only-wrap-keeping-reads need appears.
• Crate README (the docs.rs landing page) gains a "Ready-made EncryptedMaps canister" section pointing to the macro and both forms — it previously didn't mention the generator at all.
• Reference-canister READMEs: the new custom canister gets its own README, cross-linked from the full reference canister's README.

Implementation & verification

• Factored the macro into __export_encrypted_maps_{common,control_plane_endpoints,value_endpoints}! helpers composed by the two public arms.
• Added a reference canister ic-vetkeys-encrypted-maps-custom-canister that dogfoods the new form + accessors; wired into the CI wasm build.
• Verified: full-form .did identical; encrypted_maps reference tests 19/19; doctests pass and cargo doc -D warnings clean; cargo fmt --check and CI-style cargo clippy -- -Dwarnings clean; custom canister builds host + wasm.

Motoko gets the mirrored layered mixin in a separate PR.

[Copilot]

Pull request overview

Adds an opt-in “control-plane only” form to the Rust ic_vetkeys::export_encrypted_maps_canister! macro to support wrap-and-extend canisters that must own their value endpoints (e.g., to maintain linked side-state such as per-entry metadata), while keeping the existing full-canister form unchanged.

Changes:

• Extend export_encrypted_maps_canister! with a custom_value_endpoints form and add with_encrypted_maps / with_encrypted_maps_mut accessors.
• Factor macro expansion into shared/common + control-plane endpoints + value endpoints helper macros.
• Add a reference “custom canister” crate and wire it into the workspace and CI wasm build; update docs/changelog accordingly.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Cargo.toml	Adds the new custom reference canister crate to the workspace members.
Cargo.lock	Records dependency graph updates for the new canister package.
backend/rs/ic_vetkeys/src/encrypted_maps/canister.rs	Implements the new macro form, factors endpoint generation, and documents the two forms + accessors.
backend/rs/ic_vetkeys/README.md	Adds a “Ready-made EncryptedMaps canister” section referencing the macro and new form.
backend/rs/ic_vetkeys/CHANGELOG.md	Notes the additive macro form under “Unreleased”.
backend/rs/canisters/ic_vetkeys_encrypted_maps_custom_canister/src/lib.rs	New reference canister exercising the custom_value_endpoints form with custom value endpoints.
backend/rs/canisters/ic_vetkeys_encrypted_maps_custom_canister/README.md	Documentation for the new custom reference canister.
backend/rs/canisters/ic_vetkeys_encrypted_maps_custom_canister/Cargo.toml	New crate manifest for the custom reference canister.
backend/rs/canisters/ic_vetkeys_encrypted_maps_canister/README.md	Cross-links to the new custom canister and macro form for wrap-and-extend use cases.
.github/workflows/backend-rust.yml	Builds the new custom canister in CI for wasm32 target.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

backend/rs/ic_vetkeys/src/encrypted_maps/canister.rs:15

• The docstring says the custom_value_endpoints form provides a single accessor, but the macro emits two functions (with_encrypted_maps and with_encrypted_maps_mut). Update wording to avoid confusion.

//!   hooks and a [`with_encrypted_maps`]/[`with_encrypted_maps_mut`] accessor,

[mraszyk]

How about not injecting #[init]/#[post_upgrade], but exposing functions that could be invoked from #[init]/#[post_upgrade] so that people could define their own #[init]/#[post_upgrade]?

[marc0olo]

On the #[init]/#[post_upgrade] suggestion (@mraszyk): it's a fair composability point, so rather than decide unilaterally we'd like a couple more opinions before merging. One data point in the meantime: the motivating password_manager_with_metadata would get simpler under the current injected custom form — its #[init]/#[post_upgrade] only call init_encrypted_maps(key_name) and keep a KEY_NAME cell to feed the key back on upgrade, but the injected #[post_upgrade] already re-attaches by loading the key from EncryptedMaps' own config cell, and the metadata store self-initializes in its thread-local. So it would drop both hooks and the KEY_NAME cell entirely.

Exposing setup fns instead would help adopters who need custom init args or post-upgrade migration logic (none in the current use case), at the cost of more lifecycle boilerplate and reintroducing the 'forgot #[post_upgrade] → traps after upgrade' footgun we fixed in #421. Leaving it open for input; the other review comments are addressed.