feat(vetkeys): adopt EncryptedMaps mixins in the Motoko examples (ic-vetkeys 0.6.0) (#1475)

* feat(vetkeys): adopt EncryptedMaps mixins in the Motoko password managers

mops ic-vetkeys 0.6.0 adds the Motoko counterpart to the Rust macro, closing the
Motoko half of dfinity/vetkeys#423:

- `EncryptedMapsCanister` (mo:ic-vetkeys/encrypted_maps/Canister) contributes the
  complete Encrypted Maps endpoint set. `password_manager` drops from 228 lines
  of hand-written delegation to ~15.
- `EncryptedMapsControlPlaneCanister` (.../ControlPlaneCanister) contributes the
  control-plane endpoints and the in-scope `encryptedMaps` object but none of the
  value read/write endpoints. `password_manager_with_metadata` uses it, so the
  plain insert/remove mutators — which would write a value with no metadata row
  and desync the two stores — are never exposed, while the canister keeps its own
  `*_with_metadata` endpoints.

Neither mixin declares stable state: the actor declares the `EncryptedMapsState`
and passes it in, keeping the persistent state a plain, visible stable variable
the canister owns and can migrate.

Both password managers become plain persistent actors that resolve the vetKD key
name from the `VETKD_KEY_NAME` canister environment variable (defaulting to
test_key_1 so init stays total), replacing the `actor class (keyName : Text)` and
its `init_args`. This follows the upstream reference canisters and removes the
actor class from the main canister. `icp.yaml` sets the variable under
`settings.environment_variables`; the generated Candid loses its `(text)` init
argument but exposes an identical 11-method interface.

Domain separators now name their own example: both Motoko password managers
shared `password_manager_example_app`, and are now `password_manager_app` and
`password_manager_with_metadata_app`, matching the Rust examples.

0.6.0 requires moc 1.13.0 and mo:core 2.6.1 (raised from 1.11.0 / 2.5.0), so all
five Motoko examples pinning ic-vetkeys move together. The new toolchain
surfaces warnings in basic_ibe, basic_bls_signing and basic_vetkd: dot notation
(auto-fixed), the deprecated Nat64.fromNat / Nat8.fromNat / Blob.fromArray, and
never-reassigned `var`s. Changing those to `let` needs no migration — matching
stable fields may differ in mutability.

Verified: mops check clean for all five; all backends build; local icp deploy
e2e on both password managers — insert/update/read with metadata, vault sharing
via the mixin-generated control plane, values and metadata surviving an upgrade,
and `insert_encrypted_value` correctly absent from the metadata canister
(IC0536).

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

* feat(vetkeys): resolve the vetKD key name from VETKD_KEY_NAME everywhere

The two password managers moved to the `VETKD_KEY_NAME` canister environment
variable when they adopted the Encrypted Maps mixins, which left the other
Motoko vetKeys examples on `actor class (keyName : Text)` + `init_args` — two
conventions side by side in one directory. This converts the rest:

- basic_ibe, basic_bls_signing: actor class parameter -> env var
- basic_vetkd: the key name was hardcoded to `test_key_1`; it is now
  configurable through the same variable
- encrypted_notes_app_vetkd: also drops the actor class. Its
  `shared ({ caller = initializer })` binding was never used, so nothing needed
  replacing.

Each canister is now a plain actor reading the key at install with a
`?? "test_key_1"` default, so init stays total. `icp.yaml` sets the variable
under `settings.environment_variables`, and the READMEs document it — including
that the key cannot be changed once a canister holds data, since it feeds vetKD
key derivation.

Regenerated the committed Candid: every service loses its `(text)` init
argument, and the method sets are unchanged. basic_vetkd's file was previously
hand-formatted, so it also picks up the generator's parameter names and ordering.

Verified: mops check clean; local icp deploy for all four — IBE public key, BLS
sign + list, symmetric key verification, and a note round trip. Confirmed the
variable is genuinely delivered to the canister rather than silently falling
back to the default, by deploying basic_ibe with VETKD_KEY_NAME=no_such_key and
watching vetKD reject that key name.

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

* docs(vetkeys): align key-name docs and comments with actual behaviour

The `icp.yaml` comment claimed the key is read at install time, which is only
true for the password managers: they bake it into the stable EncryptedMapsState,
so a later change is ignored. The other four hold it in a `transient`, re-read on
every upgrade, so a changed variable does take effect — and orphans everything
encrypted under the old key. The code comments and READMEs of those four said
only "do not change it" without saying what happens; they now state it.

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

* fix(vetkeys): capture the vetKD key name in stable state, not a transient

basic_ibe, basic_bls_signing, basic_vetkd and encrypted_notes_app_vetkd held the
key name in a `transient`, which is re-read on every upgrade — so editing
VETKD_KEY_NAME and redeploying silently re-keyed the canister and orphaned
everything encrypted under the old key, with a green deploy and no error.

Dropping `transient` makes it a stable variable captured at the first install,
matching the password managers, where the key is baked into the EncryptedMapsState.
A later change to the variable is now ignored instead of destructive; only a
reinstall, which drops all data, switches keys.

This takes away no capability. Changing the key already destroyed the ability to
read the data — a migration could rewrite the field, but the canister only ever
sees ciphertext and cannot re-encrypt, so it would just yield a canister that
cannot read its own store. Real re-keying needs application-level key rotation,
which these examples do not implement and which their READMEs already note.

All six examples now behave identically, so the code comments, the icp.yaml
comments and the README paragraph are one shared wording that states when the key
is read, that later changes are ignored, and why reinstall is the only escape.

Verified: mops check and icp project show clean for all six; deployed basic_ibe,
then upgraded it with VETKD_KEY_NAME=no_such_key and confirmed the IBE public key
is unchanged — the misconfiguration is ignored rather than silently orphaning data.

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

* docs(vetkeys): make the Motoko canister headers doc comments

Mirrors the review feedback on #1474 for the Motoko side. The header block
describing each canister becomes `///`, matching how cert-var, random_maze and
canister_factory already document their `main.mo`.

Only the two headers change. Inline notes on individual declarations stay `//`:
they are implementation notes, not interface documentation.

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

* docs(vetkeys): finish the password_manager doc comment block

Review catch on #1475: the last two lines of the header stayed `//`, truncating
the doc comment mid-sentence. The script that converted the block ended it at the
first "actor " it found, which matched the words "this actor declares" inside the
prose rather than the declaration.

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

---------

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

Author: marc0olo

motoko/vetkeys/basic_bls_signing/README.md

@@ -21,7 +21,9 @@ To confirm the canister can only produce signatures in the intended way, users n
 
 ### (Optionally) choose a different master key
 
-This example uses `test_key_1` by default. To use a different [available master key](https://docs.internetcomputer.org/concepts/vetkeys/#api-overview), change the `init_args` value in `icp.yaml` before deploying.
+This example uses `test_key_1` by default. To use a different [available master key](https://docs.internetcomputer.org/concepts/vetkeys/#api-overview), change the `VETKD_KEY_NAME` environment variable in `icp.yaml` before the first deploy.
+
+The key name is read once at the first install and captured in stable state: it feeds vetKD key derivation, so a different key cannot decrypt what the old one encrypted — and since the canister only ever sees ciphertext, it cannot re-encrypt either. Changing the variable on a later upgrade is therefore silently ignored; only `icp deploy --mode reinstall`, which drops all data, switches keys. Re-keying live data would need application-level key rotation, which these examples do not implement.
 
 ### Install
 

motoko/vetkeys/basic_bls_signing/backend/backend.did

@@ -1,13 +1,11 @@
-type _anon_class_13_1 = 
- service {
-   getMySignatures: () -> (vec Signature) query;
-   getMyVerificationKey: () -> (blob);
-   signMessage: (message: text) -> (blob);
- };
 type Signature = 
  record {
    message: text;
    signature: blob;
    timestamp: nat64;
  };
-service : (keyName: text) -> _anon_class_13_1
+service : {
+  getMySignatures: () -> (vec Signature) query;
+  getMyVerificationKey: () -> (blob);
+  signMessage: (message: text) -> (blob);
+}

motoko/vetkeys/basic_bls_signing/backend/main.mo

@@ -6,11 +6,26 @@ import Time "mo:core/Time";
 import Map "mo:core/Map";
 import Array "mo:core/Array";
 import List "mo:core/List";
-import Nat8 "mo:core/Nat8";
+import Nat "mo:core/Nat";
 import VetKeys "mo:ic-vetkeys";
 import Order "mo:core/Order";
+import Runtime "mo:core/Runtime";
+
+actor {
+    // The vetKD key name this canister derives from. Set the `VETKD_KEY_NAME`
+    // canister environment variable (see `icp.yaml`) to pick a different key; it
+    // defaults to `test_key_1` so a deploy can never leave the canister
+    // half-initialized.
+    //
+    // This is a stable variable on purpose, so it is captured at the first install
+    // and never re-read: changing the environment variable later is silently
+    // ignored, and only a reinstall — which drops all data — switches keys. The key
+    // feeds vetKD derivation, so a different key cannot decrypt what the old one
+    // encrypted, and this canister only ever sees ciphertext and so cannot
+    // re-encrypt. Were it `transient` instead, a changed variable would take effect
+    // on the next upgrade and silently orphan the stored data.
+    let keyName = Runtime.envVar<system>("VETKD_KEY_NAME") ?? "test_key_1";
 
-actor class (keyName : Text) = {
     // Types
     type Signature = {
         message : Text;
@@ -37,7 +52,7 @@ actor class (keyName : Text) = {
     };
 
     // Signatures are retained across upgrades: this actor field is not declared `transient`.
-    private var signatures = Map.empty<SignatureKey, Signature>();
+    private let signatures = Map.empty<SignatureKey, Signature>();
 
     // Helper function to get current timestamp
     private func getTimestamp() : Nat64 {
@@ -47,19 +62,18 @@ actor class (keyName : Text) = {
     // Helper function to create context for vetKD
     private func context(signer : Principal) : Blob {
         // Domain separator for this app
-        let domainSeparator : [Nat8] = Blob.toArray(Text.encodeUtf8("basic_bls_signing_app"));
-        let domainSeparatorLength : [Nat8] = [Nat8.fromNat(domainSeparator.size())]; // Length of domain separator
+        let domainSeparator : [Nat8] = Text.encodeUtf8("basic_bls_signing_app").toArray();
+        let domainSeparatorLength : [Nat8] = [domainSeparator.size().toNat8()]; // Length of domain separator
 
         // Combine domain separator length, domain separator, and signer principal
-        let signerBytes = Principal.toBlob(signer);
-        let signerArray = Blob.toArray(signerBytes);
+        let signerBytes = signer.toBlob();
+        let signerArray = signerBytes.toArray();
 
-        let contextArray = Array.concat<Nat8>(
-            Array.concat<Nat8>(domainSeparatorLength, domainSeparator),
+        let contextArray = domainSeparatorLength.concat(domainSeparator).concat(
             signerArray,
         );
 
-        Blob.fromArray(contextArray);
+        contextArray.toBlob();
     };
 
     // Helper function to get key ID
@@ -73,7 +87,7 @@ actor class (keyName : Text) = {
     // Sign a message using BLS
     public shared ({ caller }) func signMessage(message : Text) : async Blob {
         let signatureBytes = await VetKeys.ManagementCanister.signWithBls(
-            Text.encodeUtf8(message),
+            message.encodeUtf8(),
             context(caller),
             keyId(),
         );
@@ -87,26 +101,26 @@ actor class (keyName : Text) = {
 
         // Handle potential timestamp collisions by incrementing until we find a free slot
         var timestampForMapKey = timestamp;
-        while (Map.get(signatures, signatureKeyCompare, { signer = caller; timestamp = timestampForMapKey }) != null) {
+        while (signatures.get(signatureKeyCompare, { signer = caller; timestamp = timestampForMapKey }) != null) {
             timestampForMapKey += 1;
         };
 
-        ignore Map.insert(signatures, signatureKeyCompare, { signer = caller; timestamp = timestampForMapKey }, signature);
+        ignore signatures.insert(signatureKeyCompare, { signer = caller; timestamp = timestampForMapKey }, signature);
 
         signatureBytes;
     };
 
     // Get all signatures for the current caller
     public shared query ({ caller }) func getMySignatures() : async [Signature] {
-        var callerSignatures = List.empty<Signature>();
+        let callerSignatures = List.empty<Signature>();
 
-        for ((key, value) in Map.entries(signatures)) {
+        for ((key, value) in signatures.entries()) {
             if (Principal.equal(key.signer, caller)) {
-                List.add(callerSignatures, value);
+                callerSignatures.add(value);
             };
         };
 
-        List.toArray(callerSignatures);
+        callerSignatures.toArray();
     };
 
     // Get verification key for the current caller

motoko/vetkeys/basic_bls_signing/icp.yaml

@@ -2,9 +2,13 @@ canisters:
   - name: backend
     recipe:
       type: "@dfinity/motoko@v5.0.0"
-    init_args:
-      type: text
-      value: "(\"test_key_1\")"
+    settings:
+      # The vetKD master key this canister derives from, read by the canister via
+      # `Runtime.envVar("VETKD_KEY_NAME")` and captured in stable state at the first
+      # install. Set it before deploying: a later change is silently ignored, and
+      # only a reinstall — which drops all data — switches keys.
+      environment_variables:
+        VETKD_KEY_NAME: "test_key_1"
 
   - name: frontend
     recipe:

motoko/vetkeys/basic_bls_signing/mops.toml

@@ -1,9 +1,9 @@
 [toolchain]
-moc = "1.11.0"
+moc = "1.13.0"
 
 [dependencies]
-core = "2.5.0"
-ic-vetkeys = "0.5.0"
+core = "2.6.1"
+ic-vetkeys = "0.6.0"
 
 [moc]
 # M0236: use context dot notation

motoko/vetkeys/basic_ibe/README.md

@@ -22,7 +22,9 @@ Note that generally it is possible for a canister to request a decryption key to
 
 ### (Optionally) choose a different master key
 
-This example uses `test_key_1` by default. To use a different [available master key](https://docs.internetcomputer.org/concepts/vetkeys/#api-overview), change the `init_args` value in `icp.yaml` before deploying.
+This example uses `test_key_1` by default. To use a different [available master key](https://docs.internetcomputer.org/concepts/vetkeys/#api-overview), change the `VETKD_KEY_NAME` environment variable in `icp.yaml` before the first deploy.
+
+The key name is read once at the first install and captured in stable state: it feeds vetKD key derivation, so a different key cannot decrypt what the old one encrypted — and since the canister only ever sees ciphertext, it cannot re-encrypt either. Changing the variable on a later upgrade is therefore silently ignored; only `icp deploy --mode reinstall`, which drops all data, switches keys. Re-keying live data would need application-level key rotation, which these examples do not implement.
 
 ### Install
 

motoko/vetkeys/basic_ibe/backend/backend.did

@@ -1,11 +1,3 @@
-type _anon_class_13_1 = 
- service {
-   getIbePublicKey: () -> (blob);
-   getMyEncryptedIbeKey: (transportKey: blob) -> (blob);
-   getMyMessages: () -> (Inbox) query;
-   removeMyMessageByIndex: (messageIndex: nat64) -> (Result);
-   sendMessage: (request: SendMessageRequest) -> (Result);
- };
 type SendMessageRequest = 
  record {
    encryptedMessage: blob;
@@ -23,4 +15,10 @@ type Message =
    timestamp: nat64;
  };
 type Inbox = record {messages: vec Message;};
-service : (keyNameString: text) -> _anon_class_13_1
+service : {
+  getIbePublicKey: () -> (blob);
+  getMyEncryptedIbeKey: (transportKey: blob) -> (blob);
+  getMyMessages: () -> (Inbox) query;
+  removeMyMessageByIndex: (messageIndex: nat64) -> (Result);
+  sendMessage: (request: SendMessageRequest) -> (Result);
+}

motoko/vetkeys/basic_ibe/backend/main.mo

@@ -9,8 +9,23 @@ import Nat64 "mo:core/Nat64";
 import Nat "mo:core/Nat";
 import Result "mo:core/Result";
 import Int "mo:core/Int";
+import Runtime "mo:core/Runtime";
+
+actor {
+  // The vetKD key name this canister derives from. Set the `VETKD_KEY_NAME`
+  // canister environment variable (see `icp.yaml`) to pick a different key; it
+  // defaults to `test_key_1` so a deploy can never leave the canister
+  // half-initialized.
+  //
+  // This is a stable variable on purpose, so it is captured at the first install
+  // and never re-read: changing the environment variable later is silently
+  // ignored, and only a reinstall — which drops all data — switches keys. The key
+  // feeds vetKD derivation, so a different key cannot decrypt what the old one
+  // encrypted, and this canister only ever sees ciphertext and so cannot
+  // re-encrypt. Were it `transient` instead, a changed variable would take effect
+  // on the next upgrade and silently orphan the stored data.
+  let keyNameString = Runtime.envVar<system>("VETKD_KEY_NAME") ?? "test_key_1";
 
-actor class (keyNameString : Text) {
   // Types
   type Message = {
     sender : Principal;
@@ -64,7 +79,7 @@ actor class (keyNameString : Text) {
   let DOMAIN_SEPARATOR : Text = "basic_ibe_example_dapp";
 
   // State
-  var inboxes = Map.empty<Principal, Inbox>();
+  let inboxes = Map.empty<Principal, Inbox>();
 
   // Management canister actor
   let vetKdSystemApi : VetKdSystemApi = actor ("aaaaa-aa");
@@ -74,22 +89,22 @@ actor class (keyNameString : Text) {
     let message : Message = {
       sender = caller;
       encryptedMessage = request.encryptedMessage;
-      timestamp = Nat64.fromNat(Int.abs(Time.now()));
+      timestamp = Int.abs(Time.now()).toNat64();
     };
 
     let receiver = request.receiver;
-    let currentInbox = switch (Map.get(inboxes, Principal.compare, receiver)) {
+    let currentInbox = switch (inboxes.get(receiver)) {
       case (?inbox) { inbox };
       case null { { messages = [] } };
     };
 
     if (currentInbox.messages.size() >= MAX_MESSAGES_PER_INBOX) {
-      return #Err("Inbox for " # Principal.toText(receiver) # " is full");
+      return #Err("Inbox for " # receiver.toText() # " is full");
     };
 
-    let newMessages = Array.concat(currentInbox.messages, [message]);
+    let newMessages = currentInbox.messages.concat([message]);
     let newInbox : Inbox = { messages = newMessages };
-    ignore Map.insert(inboxes, Principal.compare, receiver, newInbox);
+    ignore inboxes.insert(receiver, newInbox);
 
     #Ok();
   };
@@ -101,7 +116,7 @@ actor class (keyNameString : Text) {
       name = keyNameString;
     };
 
-    let context = Text.encodeUtf8(DOMAIN_SEPARATOR);
+    let context = DOMAIN_SEPARATOR.encodeUtf8();
     let request : VetKdPublicKeyArgs = {
       canister_id = null;
       context = context;
@@ -119,8 +134,8 @@ actor class (keyNameString : Text) {
       name = keyNameString;
     };
 
-    let context = Text.encodeUtf8(DOMAIN_SEPARATOR);
-    let input = Principal.toBlob(caller);
+    let context = DOMAIN_SEPARATOR.encodeUtf8();
+    let input = caller.toBlob();
     let request : VetKdDeriveKeyArgs = {
       context = context;
       input = input;
@@ -134,20 +149,20 @@ actor class (keyNameString : Text) {
 
   // Get the caller's messages
   public shared query ({ caller }) func getMyMessages() : async Inbox {
-    switch (Map.get(inboxes, Principal.compare, caller)) {
+    switch (inboxes.get(caller)) {
       case (?inbox) { inbox };
       case null { { messages = [] } };
     };
   };
 
   // Remove a message by index
   public shared ({ caller }) func removeMyMessageByIndex(messageIndex : Nat64) : async Result<(), Text> {
-    let currentInbox = switch (Map.get(inboxes, Principal.compare, caller)) {
+    let currentInbox = switch (inboxes.get(caller)) {
       case (?inbox) { inbox };
       case null { { messages = [] } };
     };
 
-    let index = Nat64.toNat(messageIndex);
+    let index = messageIndex.toNat();
     if (index >= currentInbox.messages.size()) {
       return #Err("Message index out of bounds");
     };
@@ -158,13 +173,13 @@ actor class (keyNameString : Text) {
 
     for (i in messages.keys()) {
       if (i != index) {
-        List.add(newMessagesList, messages[i]);
+        newMessagesList.add(messages[i]);
       };
     };
 
-    let newMessages = List.toArray(newMessagesList);
+    let newMessages = newMessagesList.toArray();
     let newInbox : Inbox = { messages = newMessages };
-    ignore Map.insert(inboxes, Principal.compare, caller, newInbox);
+    ignore inboxes.insert(caller, newInbox);
 
     #Ok();
   };

motoko/vetkeys/basic_ibe/icp.yaml

@@ -2,9 +2,13 @@ canisters:
   - name: backend
     recipe:
       type: "@dfinity/motoko@v5.0.0"
-    init_args:
-      type: text
-      value: "(\"test_key_1\")"
+    settings:
+      # The vetKD master key this canister derives from, read by the canister via
+      # `Runtime.envVar("VETKD_KEY_NAME")` and captured in stable state at the first
+      # install. Set it before deploying: a later change is silently ignored, and
+      # only a reinstall — which drops all data — switches keys.
+      environment_variables:
+        VETKD_KEY_NAME: "test_key_1"
 
   - name: frontend
     recipe:

motoko/vetkeys/basic_ibe/mops.toml

@@ -1,9 +1,9 @@
 [toolchain]
-moc = "1.11.0"
+moc = "1.13.0"
 
 [dependencies]
-core = "2.5.0"
-ic-vetkeys = "0.5.0"
+core = "2.6.1"
+ic-vetkeys = "0.6.0"
 
 [moc]
 # M0236: use context dot notation