From de052a90288eca74d2ef4d4b1eb4da3d19820ad9 Mon Sep 17 00:00:00 2001
From: highlander <highlander@keepkey.com>
Date: Fri, 24 Apr 2026 21:07:37 -0500
Subject: [PATCH 1/6] =?UTF-8?q?feat:=20user-provisioned=20metadata=20signi?=
 =?UTF-8?q?ng=20keys=20=E2=80=94=20slots=204-6=20+=20storage=20v18?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lets KeepKey owners add their own secp256k1 signing keys at runtime so
companies / DAOs can publish their own clear-signing descriptor sets
that members verify on their own device, without firmware updates.

- 3 user slots (4..6) persisted in Storage.pub.metadata_keys, plus
  STORAGE_VERSION bump 17 -> 18 with explicit V17->V18 migration that
  zero-inits the new key array on existing devices.
- AddMetadataKey, RemoveMetadataKey, ListMetadataKeys handlers in
  fsm_msg_metadata.h. Add: 2-step confirm (slot+label, then SHA-256
  fingerprint), then PIN. Remove: confirm shows fingerprint of the key
  being removed (defends against stealth removal on a briefly-unlocked
  device). Slots 0..3 remain firmware-baked and cannot be overwritten.
- signed_metadata.c moves from a hardcoded METADATA_PUBKEYS lookup to a
  unified metadata_get_pubkey() that resolves slot 0..3 from the static
  firmware table and slot 4..6 from storage. Verification confirm screen
  now shows the matching label ("Insight Verified" for slot 0,
  "<label> Verified" for user slots).
- Pulls in device-protocol c7a824d which adds MetadataKeyType + the four
  new wire messages.
---
 deps/device-protocol                       |   2 +-
 include/keepkey/firmware/fsm.h             |   5 +
 include/keepkey/firmware/storage.h         |  32 +++-
 include/keepkey/transport/messages.options |   4 +
 include/keepkey/transport/types.options    |   3 +
 lib/firmware/fsm.c                         |   1 +
 lib/firmware/fsm_msg_metadata.h            | 165 +++++++++++++++++++++
 lib/firmware/messagemap.def                |   6 +
 lib/firmware/signed_metadata.c             |  82 +++++++---
 lib/firmware/storage.c                     | 163 +++++++++++++++++++-
 lib/firmware/storage.h                     |   4 +
 lib/firmware/storage_versions.inc          |   3 +-
 12 files changed, 447 insertions(+), 23 deletions(-)
 create mode 100644 lib/firmware/fsm_msg_metadata.h

diff --git a/deps/device-protocol b/deps/device-protocol
index bf8646b81..c7a824d01 160000
--- a/deps/device-protocol
+++ b/deps/device-protocol
@@ -1 +1 @@
-Subproject commit bf8646b817401d4623e0977ddb4c961b1101121f
+Subproject commit c7a824d011c913aaaf7a44eee5febcfe772ebc49
diff --git a/include/keepkey/firmware/fsm.h b/include/keepkey/firmware/fsm.h
index a33c2703b..630ad578c 100644
--- a/include/keepkey/firmware/fsm.h
+++ b/include/keepkey/firmware/fsm.h
@@ -80,6 +80,11 @@ void fsm_msgApplyPolicies(ApplyPolicies* msg);
 // BIP-85 (chain-agnostic, available in all builds)
 void fsm_msgGetBip85Mnemonic(const GetBip85Mnemonic* msg);
 
+// Insight metadata key management (slots 4..6 user-provisioned)
+void fsm_msgAddMetadataKey(const AddMetadataKey* msg);
+void fsm_msgRemoveMetadataKey(const RemoveMetadataKey* msg);
+void fsm_msgListMetadataKeys(const ListMetadataKeys* msg);
+
 #ifndef BITCOIN_ONLY
 // ethereum
 void fsm_msgEthereumGetAddress(EthereumGetAddress* msg);
diff --git a/include/keepkey/firmware/storage.h b/include/keepkey/firmware/storage.h
index 1a57603b2..1c2e4b5d9 100644
--- a/include/keepkey/firmware/storage.h
+++ b/include/keepkey/firmware/storage.h
@@ -26,7 +26,13 @@
 #include "keepkey/firmware/authenticator.h"
 
 #define STORAGE_VERSION \
-  17 /* Must add case fallthrough in storage_fromFlash after increment*/
+  18 /* Must add case fallthrough in storage_fromFlash after increment*/
+
+/* Number of user-provisioned metadata signing key slots (slots 4..6).
+ * Firmware-baked slots 0..3 live in signed_metadata.c and don't count here. */
+#define METADATA_USER_KEY_COUNT 3
+#define METADATA_USER_KEY_FIRST 4
+#define METADATA_USER_KEY_LAST (METADATA_USER_KEY_FIRST + METADATA_USER_KEY_COUNT - 1)
 #define STORAGE_RETRIES 3
 
 #define RANDOM_SALT_LEN 32
@@ -165,6 +171,30 @@ void storage_getPolicies(PolicyType* policy_data);
 /// \brief Status of policy in storage
 bool storage_isPolicyEnabled(const char* policy_name);
 
+typedef struct _MetadataKeyType MetadataKeyType;
+
+/// \brief Add or replace a user-provisioned metadata signing key.
+/// \param slot Must be in [METADATA_USER_KEY_FIRST, METADATA_USER_KEY_LAST].
+/// \param pubkey 33-byte compressed secp256k1 public key.
+/// \param label Null-terminated, ≤16 chars. Displayed during verification.
+/// \returns true on success, false on invalid slot/pubkey/label.
+bool storage_setMetadataKey(uint32_t slot, const uint8_t* pubkey,
+                            const char* label);
+
+/// \brief Remove a user-provisioned metadata signing key.
+/// \returns true if a key was removed, false if slot was empty/invalid.
+bool storage_removeMetadataKey(uint32_t slot);
+
+/// \brief Look up a user-provisioned metadata signing key.
+/// \param pubkey_out Receives 33 bytes on success.
+/// \param label_out Receives null-terminated string (buffer must be ≥17 bytes).
+/// \returns true if slot is populated.
+bool storage_getMetadataKey(uint32_t slot, uint8_t pubkey_out[33],
+                            char label_out[17]);
+
+/// \brief Number of populated user-provisioned metadata key slots (0..3).
+uint32_t storage_getMetadataKeyCount(void);
+
 uint32_t storage_getAutoLockDelayMs(void);
 void storage_setAutoLockDelayMs(uint32_t auto_lock_delay_ms);
 
diff --git a/include/keepkey/transport/messages.options b/include/keepkey/transport/messages.options
index 29a1fcea6..dbb18f3af 100644
--- a/include/keepkey/transport/messages.options
+++ b/include/keepkey/transport/messages.options
@@ -105,6 +105,10 @@ SignedIdentity.signature		max_size:65
 
 ApplyPolicies.policy			max_count:6
 
+AddMetadataKey.pubkey       max_size:33
+AddMetadataKey.label        max_size:16
+MetadataKeysList.keys       max_count:7
+
 # not used in firmware
 FirmwareUpload.payload_hash  max_size:32
 FirmwareUpload.payload			max_size:0
diff --git a/include/keepkey/transport/types.options b/include/keepkey/transport/types.options
index 307732f4b..ad30d3ea5 100644
--- a/include/keepkey/transport/types.options
+++ b/include/keepkey/transport/types.options
@@ -46,3 +46,6 @@ IdentityType.port			max_size:6
 IdentityType.path			max_size:256
 
 PolicyType.policy_name    max_size:15
+
+MetadataKeyType.pubkey      max_size:33
+MetadataKeyType.label       max_size:16
diff --git a/lib/firmware/fsm.c b/lib/firmware/fsm.c
index 394bdbb49..31ec9ab12 100644
--- a/lib/firmware/fsm.c
+++ b/lib/firmware/fsm.c
@@ -294,3 +294,4 @@ void fsm_msgClearSession(ClearSession* msg) {
 #include "fsm_msg_tron.h"
 #include "fsm_msg_solana.h"
 #include "fsm_msg_bip85.h"
+#include "fsm_msg_metadata.h"
diff --git a/lib/firmware/fsm_msg_metadata.h b/lib/firmware/fsm_msg_metadata.h
new file mode 100644
index 000000000..e29e854d5
--- /dev/null
+++ b/lib/firmware/fsm_msg_metadata.h
@@ -0,0 +1,165 @@
+/*
+ * This file is part of the KeepKey project.
+ *
+ * Copyright (C) 2026 KeepKey
+ *
+ * This library is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this library.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/* User-provisioned metadata signing key management. Handlers for
+ * AddMetadataKey, RemoveMetadataKey, ListMetadataKeys. Slots 4..6 are
+ * user-writable; slots 0..3 are firmware-baked and not enumerated here. */
+
+static void metadata_pubkey_fingerprint(const uint8_t pubkey[33],
+                                        char fp_out[9]) {
+  uint8_t digest[32];
+  sha256_Raw(pubkey, 33, digest);
+  /* First 4 bytes → 8 hex chars. Stable, short enough for OLED. */
+  for (int i = 0; i < 4; i++) {
+    snprintf(fp_out + i * 2, 3, "%02x", digest[i]);
+  }
+  fp_out[8] = '\0';
+}
+
+void fsm_msgAddMetadataKey(const AddMetadataKey *msg) {
+  CHECK_INITIALIZED
+
+  if (msg->slot < METADATA_USER_KEY_FIRST ||
+      msg->slot > METADATA_USER_KEY_LAST) {
+    fsm_sendFailure(FailureType_Failure_SyntaxError,
+                    "slot must be in user range (4..6)");
+    layoutHome();
+    return;
+  }
+  if (msg->pubkey.size != 33 ||
+      (msg->pubkey.bytes[0] != 0x02 && msg->pubkey.bytes[0] != 0x03)) {
+    fsm_sendFailure(FailureType_Failure_SyntaxError,
+                    "pubkey must be 33-byte compressed secp256k1");
+    layoutHome();
+    return;
+  }
+  if (msg->label[0] == '\0') {
+    fsm_sendFailure(FailureType_Failure_SyntaxError, "label must not be empty");
+    layoutHome();
+    return;
+  }
+
+  char fp[9];
+  metadata_pubkey_fingerprint(msg->pubkey.bytes, fp);
+
+  /* Confirm 1: slot + label. Lets user abort cheaply before PIN. */
+  if (!confirm(ButtonRequestType_ButtonRequest_Other, "Add Insight Key",
+               "Slot %lu\n%s", (unsigned long)msg->slot, msg->label)) {
+    fsm_sendFailure(FailureType_Failure_ActionCancelled,
+                    "Add metadata key cancelled");
+    layoutHome();
+    return;
+  }
+
+  /* Confirm 2: fingerprint. User verifies against company-published value
+   * out-of-band. Truncating to 8 hex chars is intentional — full SHA256
+   * doesn't fit and the threat model here is mistake/typo, not collision. */
+  if (!confirm(ButtonRequestType_ButtonRequest_Other, "Verify Key Fingerprint",
+               "fp:\n%s", fp)) {
+    fsm_sendFailure(FailureType_Failure_ActionCancelled,
+                    "Add metadata key cancelled");
+    layoutHome();
+    return;
+  }
+
+  CHECK_PIN_UNCACHED
+
+  if (!storage_setMetadataKey(msg->slot, msg->pubkey.bytes, msg->label)) {
+    fsm_sendFailure(FailureType_Failure_ActionCancelled,
+                    "Could not store metadata key");
+    layoutHome();
+    return;
+  }
+  storage_commit();
+
+  fsm_sendSuccess("Metadata key added");
+  layoutHome();
+}
+
+void fsm_msgRemoveMetadataKey(const RemoveMetadataKey *msg) {
+  CHECK_INITIALIZED
+
+  if (msg->slot < METADATA_USER_KEY_FIRST ||
+      msg->slot > METADATA_USER_KEY_LAST) {
+    fsm_sendFailure(FailureType_Failure_SyntaxError,
+                    "slot must be in user range (4..6)");
+    layoutHome();
+    return;
+  }
+
+  uint8_t pubkey[33];
+  char label[17];
+  if (!storage_getMetadataKey(msg->slot, pubkey, label)) {
+    fsm_sendFailure(FailureType_Failure_DataError, "slot is empty");
+    layoutHome();
+    return;
+  }
+
+  /* Show fingerprint of the key being removed — defends against stealth
+   * removal where an attacker briefly accesses an unlocked device. */
+  char fp[9];
+  metadata_pubkey_fingerprint(pubkey, fp);
+
+  if (!confirm(ButtonRequestType_ButtonRequest_Other, "Remove Insight Key",
+               "Slot %lu: %s\nfp: %s", (unsigned long)msg->slot, label, fp)) {
+    fsm_sendFailure(FailureType_Failure_ActionCancelled,
+                    "Remove metadata key cancelled");
+    layoutHome();
+    return;
+  }
+
+  CHECK_PIN_UNCACHED
+
+  if (!storage_removeMetadataKey(msg->slot)) {
+    fsm_sendFailure(FailureType_Failure_ActionCancelled,
+                    "Could not remove metadata key");
+    layoutHome();
+    return;
+  }
+  storage_commit();
+
+  fsm_sendSuccess("Metadata key removed");
+  layoutHome();
+}
+
+void fsm_msgListMetadataKeys(const ListMetadataKeys *msg) {
+  (void)msg;
+  RESP_INIT(MetadataKeysList);
+
+  size_t count = 0;
+  for (uint32_t slot = METADATA_USER_KEY_FIRST; slot <= METADATA_USER_KEY_LAST;
+       ++slot) {
+    uint8_t pubkey[33];
+    char label[17];
+    if (!storage_getMetadataKey(slot, pubkey, label)) continue;
+
+    MetadataKeyType *k = &resp->keys[count++];
+    memzero(k, sizeof(*k));
+    k->has_slot = true;
+    k->slot = slot;
+    k->has_pubkey = true;
+    k->pubkey.size = 33;
+    memcpy(k->pubkey.bytes, pubkey, 33);
+    k->has_label = true;
+    strlcpy(k->label, label, sizeof(k->label));
+  }
+  resp->keys_count = count;
+
+  msg_write(MessageType_MessageType_MetadataKeysList, resp);
+}
diff --git a/lib/firmware/messagemap.def b/lib/firmware/messagemap.def
index 39792f28e..29c953816 100644
--- a/lib/firmware/messagemap.def
+++ b/lib/firmware/messagemap.def
@@ -36,6 +36,10 @@
 
     MSG_IN(MessageType_MessageType_GetBip85Mnemonic,               GetBip85Mnemonic,            fsm_msgGetBip85Mnemonic)
 
+    MSG_IN(MessageType_MessageType_AddMetadataKey,                 AddMetadataKey,              fsm_msgAddMetadataKey)
+    MSG_IN(MessageType_MessageType_RemoveMetadataKey,              RemoveMetadataKey,           fsm_msgRemoveMetadataKey)
+    MSG_IN(MessageType_MessageType_ListMetadataKeys,               ListMetadataKeys,            fsm_msgListMetadataKeys)
+
 #ifndef BITCOIN_ONLY
     MSG_IN(MessageType_MessageType_EthereumGetAddress,              EthereumGetAddress,          fsm_msgEthereumGetAddress)
     MSG_IN(MessageType_MessageType_EthereumSignTx,                  EthereumSignTx,              fsm_msgEthereumSignTx)
@@ -119,6 +123,8 @@
 
     MSG_OUT(MessageType_MessageType_Bip85Mnemonic,                  Bip85Mnemonic,               NO_PROCESS_FUNC)
 
+    MSG_OUT(MessageType_MessageType_MetadataKeysList,               MetadataKeysList,            NO_PROCESS_FUNC)
+
 #ifndef  BITCOIN_ONLY
     MSG_OUT(MessageType_MessageType_EthereumAddress,                EthereumAddress,             NO_PROCESS_FUNC)
     MSG_OUT(MessageType_MessageType_EthereumTxRequest,              EthereumTxRequest,           NO_PROCESS_FUNC)
diff --git a/lib/firmware/signed_metadata.c b/lib/firmware/signed_metadata.c
index f8d4b0ad6..48fc6e141 100644
--- a/lib/firmware/signed_metadata.c
+++ b/lib/firmware/signed_metadata.c
@@ -3,6 +3,7 @@
 #include "keepkey/board/confirm_sm.h"
 #include "keepkey/board/util.h"
 #include "keepkey/firmware/ethereum.h"
+#include "keepkey/firmware/storage.h"
 #include "trezor/crypto/address.h"
 #include "trezor/crypto/bignum.h"
 #include "trezor/crypto/ecdsa.h"
@@ -17,30 +18,33 @@
 
 static bool metadata_available = false;
 static SignedMetadata stored_metadata;
+static char stored_metadata_label[17];
 
 /*
- * Metadata verification public keys.
- * Slot 0: active production key
- * Slot 1: rotation target
- * Slots 2-3: reserved
+ * Firmware-baked metadata verification public keys (slots 0..3).
+ * User-provisioned keys live in storage at slots 4..6 (see storage.h).
  *
- * Keys are derived via KeepKey SignIdentity at keepkey.com/insight.
- * Only the public key is stored here — the signing mnemonic is held
- * offline and never appears in source code.
+ * Slot 0: active production key — the "Insight" key managed by KeepKey
+ * Slot 1: rotation target
+ * Slot 2: reserved
+ * Slot 3: CI test key, DEBUG_LINK only
  *
- * To rotate: generate new key with pioneer-insight keygen,
- * replace the slot below, ship firmware update.
+ * Slot 0 is derived via KeepKey SignIdentity at keepkey.com/insight.
+ * Only public keys are stored here; the signing mnemonic is held offline.
+ * To rotate: generate new key with pioneer-insight keygen, replace the
+ * slot below, ship firmware update.
  */
-static const uint8_t METADATA_PUBKEYS[METADATA_MAX_KEYS][33] = {
-    /* Key 0: production */
+static const uint8_t METADATA_FIRMWARE_PUBKEYS[METADATA_MAX_KEYS][33] = {
+    /* Slot 0: production */
     {0x02, 0x18, 0x62, 0x1d, 0x9c, 0x14, 0x47, 0x34, 0x58, 0x71, 0x3b,
      0xd3, 0xe6, 0x72, 0xe5, 0x34, 0x80, 0xaa, 0x70, 0x32, 0xca, 0x9b,
      0x67, 0x35, 0x63, 0x95, 0xe8, 0x87, 0x09, 0xbb, 0x45, 0x22, 0x6a},
-    /* Key 1: rotation slot */
+    /* Slot 1: rotation */
     {0x00},
+    /* Slot 2: reserved */
     {0x00},
 #if DEBUG_LINK
-    /* Key 3: CI test key — only available in emulator/debug builds */
+    /* Slot 3: CI test key — only available in emulator/debug builds */
     {0x02, 0xe3, 0xb3, 0x01, 0x5c, 0x47, 0xdd, 0xca, 0xab, 0xe4, 0xf8,
      0xe8, 0x72, 0xf1, 0xed, 0x8f, 0x09, 0xca, 0x14, 0x5a, 0x8d, 0x81,
      0x77, 0x0d, 0x92, 0x21, 0x3d, 0x56, 0xda, 0x31, 0xab, 0x51, 0x07},
@@ -49,6 +53,33 @@ static const uint8_t METADATA_PUBKEYS[METADATA_MAX_KEYS][33] = {
 #endif
 };
 
+/* Display labels for firmware-baked slots. User slots get their label from
+ * storage. Empty string means "no label" — confirm screen falls back to a
+ * generic header. */
+static const char METADATA_FIRMWARE_LABELS[METADATA_MAX_KEYS][17] = {
+    "Insight",
+    "",
+    "",
+#if DEBUG_LINK
+    "CI Test",
+#else
+    "",
+#endif
+};
+
+/* Look up a pubkey + label by slot. Slots 0..3 are firmware-baked,
+ * 4..6 come from storage. Returns false if the slot is unprovisioned. */
+static bool metadata_get_pubkey(uint8_t slot, uint8_t pubkey_out[33],
+                                char label_out[17]) {
+  if (slot < METADATA_MAX_KEYS) {
+    if (METADATA_FIRMWARE_PUBKEYS[slot][0] == 0x00) return false;
+    memcpy(pubkey_out, METADATA_FIRMWARE_PUBKEYS[slot], 33);
+    strlcpy(label_out, METADATA_FIRMWARE_LABELS[slot], 17);
+    return true;
+  }
+  return storage_getMetadataKey(slot, pubkey_out, label_out);
+}
+
 static bool read_u8(const uint8_t **cursor, const uint8_t *end, uint8_t *out) {
   if ((size_t)(end - *cursor) < 1) {
     return false;
@@ -192,6 +223,7 @@ bool signed_metadata_available(void) { return metadata_available; }
 
 void signed_metadata_clear(void) {
   memzero(&stored_metadata, sizeof(stored_metadata));
+  memzero(stored_metadata_label, sizeof(stored_metadata_label));
   metadata_available = false;
 }
 
@@ -199,12 +231,14 @@ MetadataClassification signed_metadata_process(const uint8_t *payload,
                                                size_t payload_len,
                                                uint8_t key_id) {
   uint8_t digest[32];
+  uint8_t pubkey[33];
+  char label[17];
   size_t signed_len;
 
   signed_metadata_clear();
 
-  if (key_id >= METADATA_MAX_KEYS || METADATA_PUBKEYS[key_id][0] == 0x00 ||
-      !payload || payload_len < 65) {
+  if (!payload || payload_len < 65 ||
+      !metadata_get_pubkey(key_id, pubkey, label)) {
     return METADATA_MALFORMED;
   }
 
@@ -217,12 +251,13 @@ MetadataClassification signed_metadata_process(const uint8_t *payload,
   signed_len = payload_len - sizeof(stored_metadata.signature) - 1;
   sha256_Raw(payload, signed_len, digest);
 
-  if (ecdsa_verify_digest(&secp256k1, METADATA_PUBKEYS[key_id],
-                          stored_metadata.signature, digest) != 0) {
+  if (ecdsa_verify_digest(&secp256k1, pubkey, stored_metadata.signature,
+                          digest) != 0) {
     signed_metadata_clear();
     return METADATA_MALFORMED;
   }
 
+  strlcpy(stored_metadata_label, label, sizeof(stored_metadata_label));
   metadata_available = true;
   return stored_metadata.classification;
 }
@@ -272,12 +307,21 @@ bool signed_metadata_confirm(void) {
     return false;
   }
 
-  /* Screen 1: Verified method — use review_with_icon for trust indicator */
+  /* Screen 1: Verified method — use review_with_icon for trust indicator.
+   * Header reflects the key source: firmware slot 0 → "Insight Verified",
+   * user slots → "<label> Verified" so the user sees which entity vouched
+   * for the metadata. Empty label falls back to "Verified". */
+  char header[24];
+  if (stored_metadata_label[0] != '\0') {
+    snprintf(header, sizeof(header), "%s Verified", stored_metadata_label);
+  } else {
+    strlcpy(header, "Verified", sizeof(header));
+  }
   memset(body, 0, sizeof(body));
   snprintf(body, sizeof(body), "Verified call:\n%s",
            stored_metadata.method_name);
   if (!confirm_with_icon(ButtonRequestType_ButtonRequest_ConfirmOutput,
-                         VERIFIED_ICON, "Insight Verified", "%s", body)) {
+                         VERIFIED_ICON, header, "%s", body)) {
     return false;
   }
 
diff --git a/lib/firmware/storage.c b/lib/firmware/storage.c
index 81ab7d976..7d3a16b53 100644
--- a/lib/firmware/storage.c
+++ b/lib/firmware/storage.c
@@ -1080,6 +1080,73 @@ void storage_readStorageV17(Storage* storage, const char* ptr, size_t len) {
   memcpy(storage->encrypted_sec, ptr + 1501, sizeof(storage->encrypted_sec));
 }
 
+/* V18: V17 layout + user-provisioned metadata signing keys.
+ *
+ * The metadata block lives in the V17 reserved region (offsets 501..1496).
+ * Per slot encoding (51 bytes): used(1) + pubkey(33) + label(17 nul-padded).
+ * Header: count(4 LE). Total used: 4 + 3*51 = 157 bytes at ptr+501..657. */
+#define V18_META_OFFSET 501
+#define V18_META_SLOT_SIZE 51
+#define V18_META_TOTAL (4 + METADATA_USER_KEY_COUNT * V18_META_SLOT_SIZE)
+
+static void v18_write_metadata_keys(char* ptr, const Storage* storage) {
+  uint32_t cnt = storage->pub.metadata_keys_count;
+  if (cnt > METADATA_USER_KEY_COUNT) cnt = METADATA_USER_KEY_COUNT;
+  write_u32_le(ptr + V18_META_OFFSET, cnt);
+  for (unsigned i = 0; i < METADATA_USER_KEY_COUNT; ++i) {
+    char* slot_ptr = ptr + V18_META_OFFSET + 4 + i * V18_META_SLOT_SIZE;
+    const MetadataKeyType* k = &storage->pub.metadata_keys[i];
+    bool used = k->has_pubkey && k->has_label && k->pubkey.size == 33;
+    write_u8(slot_ptr, used ? 1 : 0);
+    if (used) {
+      memcpy(slot_ptr + 1, k->pubkey.bytes, 33);
+      memset(slot_ptr + 34, 0, 17);
+      strlcpy(slot_ptr + 34, k->label, 17);
+    } else {
+      memset(slot_ptr + 1, 0, 50);
+    }
+  }
+}
+
+static void v18_read_metadata_keys(Storage* storage, const char* ptr) {
+  uint32_t cnt = read_u32_le(ptr + V18_META_OFFSET);
+  if (cnt > METADATA_USER_KEY_COUNT) cnt = 0;  // corrupt: reset
+  for (unsigned i = 0; i < METADATA_USER_KEY_COUNT; ++i) {
+    const char* slot_ptr = ptr + V18_META_OFFSET + 4 + i * V18_META_SLOT_SIZE;
+    MetadataKeyType* k = &storage->pub.metadata_keys[i];
+    memzero(k, sizeof(*k));
+    if (read_u8(slot_ptr) == 1) {
+      k->has_slot = true;
+      k->slot = METADATA_USER_KEY_FIRST + i;
+      k->has_pubkey = true;
+      k->pubkey.size = 33;
+      memcpy(k->pubkey.bytes, slot_ptr + 1, 33);
+      k->has_label = true;
+      memcpy(k->label, slot_ptr + 34, 16);
+      k->label[16] = '\0';
+    }
+  }
+  /* Recompute count from used flags — count field is advisory. */
+  uint32_t used_count = 0;
+  for (unsigned i = 0; i < METADATA_USER_KEY_COUNT; ++i) {
+    if (storage->pub.metadata_keys[i].has_pubkey) used_count++;
+  }
+  storage->pub.metadata_keys_count = used_count;
+  (void)cnt;
+}
+
+void storage_writeStorageV18(char* ptr, size_t len, const Storage* storage) {
+  if (len < V18_META_OFFSET + V18_META_TOTAL) return;
+  storage_writeStorageV17(ptr, len, storage);
+  v18_write_metadata_keys(ptr, storage);
+}
+
+void storage_readStorageV18(Storage* storage, const char* ptr, size_t len) {
+  if (len < V18_META_OFFSET + V18_META_TOTAL) return;
+  storage_readStorageV17(storage, ptr, len);
+  v18_read_metadata_keys(storage, ptr);
+}
+
 void storage_readCacheV1(Cache* cache, const char* ptr, size_t len) {
   if (len < 65 + 10) return;
   cache->root_seed_cache_status = read_u8(ptr);
@@ -1148,6 +1215,18 @@ void storage_writeV17(char* flash, size_t len, const ConfigFlash* src) {
   storage_writeStorageV17(flash + 44, 852, &src->storage);
 }
 
+void storage_readV18(ConfigFlash* dst, const char* flash, size_t len) {
+  if (len < 1024) return;
+  storage_readMeta(&dst->meta, flash, 44);
+  storage_readStorageV18(&dst->storage, flash + 44, 852);
+}
+
+void storage_writeV18(char* flash, size_t len, const ConfigFlash* src) {
+  if (len < 1024) return;
+  storage_writeMeta(flash, 44, &src->meta);
+  storage_writeStorageV18(flash + 44, 852, &src->storage);
+}
+
 StorageUpdateStatus storage_fromFlash(SessionState* ss, ConfigFlash* dst,
                                       const char* flash) {
   memzero(dst, sizeof(*dst));
@@ -1201,6 +1280,17 @@ StorageUpdateStatus storage_fromFlash(SessionState* ss, ConfigFlash* dst,
     case StorageVersion_17:
       storage_readV17(dst, flash, STORAGE_SECTOR_LEN);
       dst->storage.version = STORAGE_VERSION;
+      /* V17→V18 migration: existing devices come up with no user-provisioned
+       * metadata keys. memzero(dst) at function entry already zeroed the
+       * fields, but be explicit so refactors don't silently break the
+       * invariant that v17-on-flash → empty user-key set. */
+      dst->storage.pub.metadata_keys_count = 0;
+      memzero(dst->storage.pub.metadata_keys,
+              sizeof(dst->storage.pub.metadata_keys));
+      return dst->storage.version == version ? SUS_Valid : SUS_Updated;
+    case StorageVersion_18:
+      storage_readV18(dst, flash, STORAGE_SECTOR_LEN);
+      dst->storage.version = STORAGE_VERSION;
       return dst->storage.version == version ? SUS_Valid : SUS_Updated;
 
     case StorageVersion_NONE:
@@ -1472,7 +1562,7 @@ void storage_commit(void) {
     // commit what was in storage->encrypted_sec
   }
 
-  storage_writeV17(flash_temp, sizeof(flash_temp), &shadow_config);
+  storage_writeV18(flash_temp, sizeof(flash_temp), &shadow_config);
 
   memcpy(&shadow_config, STORAGE_MAGIC_STR, STORAGE_MAGIC_LEN);
 
@@ -2104,6 +2194,77 @@ bool storage_isPolicyEnabled_impl(const PolicyType ps[POLICY_COUNT],
   return false;
 }
 
+static bool metadata_slot_index(uint32_t slot, unsigned* idx_out) {
+  if (slot < METADATA_USER_KEY_FIRST || slot > METADATA_USER_KEY_LAST) {
+    return false;
+  }
+  *idx_out = slot - METADATA_USER_KEY_FIRST;
+  return true;
+}
+
+bool storage_setMetadataKey(uint32_t slot, const uint8_t* pubkey,
+                            const char* label) {
+  unsigned idx;
+  if (!metadata_slot_index(slot, &idx) || pubkey == NULL || label == NULL) {
+    return false;
+  }
+  /* Reject empty label — fingerprint-only display is hostile UX. */
+  if (label[0] == '\0') return false;
+  /* Reject uncompressed/invalid public-key prefix. */
+  if (pubkey[0] != 0x02 && pubkey[0] != 0x03) return false;
+
+  MetadataKeyType* k = &shadow_config.storage.pub.metadata_keys[idx];
+  bool was_empty = !k->has_pubkey;
+  memzero(k, sizeof(*k));
+  k->has_slot = true;
+  k->slot = slot;
+  k->has_pubkey = true;
+  k->pubkey.size = 33;
+  memcpy(k->pubkey.bytes, pubkey, 33);
+  k->has_label = true;
+  strlcpy(k->label, label, sizeof(k->label));
+
+  if (was_empty &&
+      shadow_config.storage.pub.metadata_keys_count < METADATA_USER_KEY_COUNT) {
+    shadow_config.storage.pub.metadata_keys_count++;
+  }
+  return true;
+}
+
+bool storage_removeMetadataKey(uint32_t slot) {
+  unsigned idx;
+  if (!metadata_slot_index(slot, &idx)) return false;
+
+  MetadataKeyType* k = &shadow_config.storage.pub.metadata_keys[idx];
+  if (!k->has_pubkey) return false;
+
+  memzero(k, sizeof(*k));
+  if (shadow_config.storage.pub.metadata_keys_count > 0) {
+    shadow_config.storage.pub.metadata_keys_count--;
+  }
+  return true;
+}
+
+bool storage_getMetadataKey(uint32_t slot, uint8_t pubkey_out[33],
+                            char label_out[17]) {
+  unsigned idx;
+  if (!metadata_slot_index(slot, &idx) || pubkey_out == NULL ||
+      label_out == NULL) {
+    return false;
+  }
+
+  const MetadataKeyType* k = &shadow_config.storage.pub.metadata_keys[idx];
+  if (!k->has_pubkey || k->pubkey.size != 33) return false;
+
+  memcpy(pubkey_out, k->pubkey.bytes, 33);
+  strlcpy(label_out, k->has_label ? k->label : "", 17);
+  return true;
+}
+
+uint32_t storage_getMetadataKeyCount(void) {
+  return shadow_config.storage.pub.metadata_keys_count;
+}
+
 bool storage_noBackup(void) { return shadow_config.storage.pub.no_backup; }
 
 void storage_setNoBackup(void) { shadow_config.storage.pub.no_backup = true; }
diff --git a/lib/firmware/storage.h b/lib/firmware/storage.h
index 10b84217b..2c7a0b195 100644
--- a/lib/firmware/storage.h
+++ b/lib/firmware/storage.h
@@ -70,6 +70,10 @@ typedef struct _Storage {
     bool authdata_encrypted;
     uint8_t random_salt[32];
     uint8_t authdata_fingerprint[32];
+    /* User-provisioned Insight metadata signing keys (slots 4..6).
+     * Slots 0..3 are firmware-baked in signed_metadata.c. */
+    uint32_t metadata_keys_count;
+    MetadataKeyType metadata_keys[METADATA_USER_KEY_COUNT];
   } pub;
 
   bool has_sec;
diff --git a/lib/firmware/storage_versions.inc b/lib/firmware/storage_versions.inc
index a2e6eda30..a6c15e4ec 100644
--- a/lib/firmware/storage_versions.inc
+++ b/lib/firmware/storage_versions.inc
@@ -22,7 +22,8 @@ STORAGE_VERSION_ENTRY(13)
 STORAGE_VERSION_ENTRY(14)
 STORAGE_VERSION_ENTRY(15)
 STORAGE_VERSION_ENTRY(16)
-STORAGE_VERSION_LAST(17)
+STORAGE_VERSION_ENTRY(17)
+STORAGE_VERSION_LAST(18)
 
 
 #undef STORAGE_VERSION_ENTRY

From 5fe12d212dd2e98cdb7ded3429aad562bf55f1f6 Mon Sep 17 00:00:00 2001
From: highlander <highlander@keepkey.com>
Date: Fri, 24 Apr 2026 21:14:22 -0500
Subject: [PATCH 2/6] style: clang-format storage.h header

---
 include/keepkey/firmware/storage.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/include/keepkey/firmware/storage.h b/include/keepkey/firmware/storage.h
index 1c2e4b5d9..b49657da5 100644
--- a/include/keepkey/firmware/storage.h
+++ b/include/keepkey/firmware/storage.h
@@ -32,7 +32,8 @@
  * Firmware-baked slots 0..3 live in signed_metadata.c and don't count here. */
 #define METADATA_USER_KEY_COUNT 3
 #define METADATA_USER_KEY_FIRST 4
-#define METADATA_USER_KEY_LAST (METADATA_USER_KEY_FIRST + METADATA_USER_KEY_COUNT - 1)
+#define METADATA_USER_KEY_LAST \
+  (METADATA_USER_KEY_FIRST + METADATA_USER_KEY_COUNT - 1)
 #define STORAGE_RETRIES 3
 
 #define RANDOM_SALT_LEN 32

From b1dbdd5003e5bee509350e230f9f4591b3d406df Mon Sep 17 00:00:00 2001
From: highlander <highlander@keepkey.com>
Date: Fri, 24 Apr 2026 21:32:13 -0500
Subject: [PATCH 3/6] fix: widen header buffer to 32 to satisfy
 -Werror=format-truncation

---
 lib/firmware/signed_metadata.c | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/lib/firmware/signed_metadata.c b/lib/firmware/signed_metadata.c
index 48fc6e141..709d70a9a 100644
--- a/lib/firmware/signed_metadata.c
+++ b/lib/firmware/signed_metadata.c
@@ -310,8 +310,9 @@ bool signed_metadata_confirm(void) {
   /* Screen 1: Verified method — use review_with_icon for trust indicator.
    * Header reflects the key source: firmware slot 0 → "Insight Verified",
    * user slots → "<label> Verified" so the user sees which entity vouched
-   * for the metadata. Empty label falls back to "Verified". */
-  char header[24];
+   * for the metadata. Empty label falls back to "Verified".
+   * Sized for max 16-char label + " Verified" (9) + null = 26, rounded up. */
+  char header[32];
   if (stored_metadata_label[0] != '\0') {
     snprintf(header, sizeof(header), "%s Verified", stored_metadata_label);
   } else {

From d22f12035930db919cd87e4cf02aee44f56ae63a Mon Sep 17 00:00:00 2001
From: highlander <highlander@keepkey.com>
Date: Fri, 24 Apr 2026 22:49:26 -0500
Subject: [PATCH 4/6] fix: replace nonexistent FailureType_Failure_DataError
 with Failure_Other

---
 lib/firmware/fsm_msg_metadata.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/firmware/fsm_msg_metadata.h b/lib/firmware/fsm_msg_metadata.h
index e29e854d5..f6fd2dd12 100644
--- a/lib/firmware/fsm_msg_metadata.h
+++ b/lib/firmware/fsm_msg_metadata.h
@@ -106,7 +106,7 @@ void fsm_msgRemoveMetadataKey(const RemoveMetadataKey *msg) {
   uint8_t pubkey[33];
   char label[17];
   if (!storage_getMetadataKey(msg->slot, pubkey, label)) {
-    fsm_sendFailure(FailureType_Failure_DataError, "slot is empty");
+    fsm_sendFailure(FailureType_Failure_Other, "slot is empty");
     layoutHome();
     return;
   }

From 3a3f086736f6bcdfbea0e86723711ac6c031240d Mon Sep 17 00:00:00 2001
From: highlander <highlander@keepkey.com>
Date: Fri, 24 Apr 2026 22:57:09 -0500
Subject: [PATCH 5/6] fix: bump label max_size 16->17 (nanopb sizes char[N], N
 includes null)

---
 include/keepkey/transport/messages.options | 2 +-
 include/keepkey/transport/types.options    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/keepkey/transport/messages.options b/include/keepkey/transport/messages.options
index dbb18f3af..0ab4073ff 100644
--- a/include/keepkey/transport/messages.options
+++ b/include/keepkey/transport/messages.options
@@ -106,7 +106,7 @@ SignedIdentity.signature		max_size:65
 ApplyPolicies.policy			max_count:6
 
 AddMetadataKey.pubkey       max_size:33
-AddMetadataKey.label        max_size:16
+AddMetadataKey.label        max_size:17
 MetadataKeysList.keys       max_count:7
 
 # not used in firmware
diff --git a/include/keepkey/transport/types.options b/include/keepkey/transport/types.options
index ad30d3ea5..b1a126a26 100644
--- a/include/keepkey/transport/types.options
+++ b/include/keepkey/transport/types.options
@@ -48,4 +48,4 @@ IdentityType.path			max_size:256
 PolicyType.policy_name    max_size:15
 
 MetadataKeyType.pubkey      max_size:33
-MetadataKeyType.label       max_size:16
+MetadataKeyType.label       max_size:17

From 70d2173e880add4cdf197a2d44257a5bc41501b3 Mon Sep 17 00:00:00 2001
From: highlander <highlander@keepkey.com>
Date: Sat, 25 Apr 2026 01:54:05 -0500
Subject: [PATCH 6/6] test(storage): substitute STORAGE_VERSION at
 encrypted_sec_version offset (1541)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The expected_flash had a hardcoded 0x11 at flash[1541] (encrypted_sec_version
LE u32 byte 0). Bumping STORAGE_VERSION 17->18 made that mismatch — fixed
by using the STORAGE_VERSION macro like the test does at flash[44] and [508],
and updated the printf substitution loop so future bumps stay green.
---
 unittests/firmware/storage.cpp | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/unittests/firmware/storage.cpp b/unittests/firmware/storage.cpp
index d0b87c5c5..c3cee1847 100644
--- a/unittests/firmware/storage.cpp
+++ b/unittests/firmware/storage.cpp
@@ -544,7 +544,7 @@ TEST(Storage, StorageRoundTrip) {
 #if 0
     printf("        ");
     for (int i = 0; i < flash.size(); i++) {
-        if (i == 44 || i == 508)
+        if (i == 44 || i == 508 || i == 1541)
             printf("STORAGE_VERSION,");
         else
             printf("0x%02hhx,", flash[i]);
@@ -653,7 +653,7 @@ TEST(Storage, StorageRoundTrip) {
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
         0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
-        0x00, 0x00, 0x00, 0x00, 0x00, 0x11, 0x00, 0x00, 0x00, 0xe4, 0x8d, 0xfe, 0xcf, 0xd0, 0x54, 0x71,
+        0x00, 0x00, 0x00, 0x00, 0x00, STORAGE_VERSION, 0x00, 0x00, 0x00, 0xe4, 0x8d, 0xfe, 0xcf, 0xd0, 0x54, 0x71,
         0x50, 0xcb, 0x12, 0x84, 0xfa, 0x5f, 0xbf, 0xcb, 0x09, 0xca, 0x00, 0xf1, 0x37, 0xe4, 0x8f, 0x5e,
         0xf9, 0x81, 0x57, 0x26, 0xb6, 0x7b, 0x8e, 0x03, 0x44, 0x9a, 0x2a, 0x7c, 0xf4, 0x3c, 0x79, 0x87,
         0x5d, 0x26, 0xae, 0x9b, 0x4b, 0xb4, 0xd2, 0xc4, 0x67, 0x97, 0xe7, 0x6b, 0x6c, 0x4c, 0xbe, 0x68,