feat: hot key, cold key and guardian key

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Fixes
 
+* [FIX][all] **Activating a device key on a migrated Guardian account no longer permanently breaks its sync.** After a structural rotation (`update_signers` for replace-hot-key, or the follow-up `update_procedure_threshold`), the wallet now pushes the new on-chain state back to the guardian. The OpenZeppelin multisig client only re-registers post-execution state on the guardian for `switch_guardian`; for the other structural ops it submitted the transaction on-chain but left the guardian serving the pre-rotation blob, so every subsequent ~3s guardian sync saw guardian-commitment ≠ on-chain and threw on `ensureSafeToOverwriteLocalState` — permanently, until a full reinstall. The re-registration runs before the hot-key pointer swap arms the sync, and the guardian sync now self-heals a lagging guardian by re-registering the current state once per run (which also recovers already-broken accounts without a reinstall). The legacy-Guardian migration additionally verifies the re-derived cold key matches the on-chain signer before flagging an account for activation. (#227)
+* [FIX][all] **Guardian sync no longer spams "missing hotPublicKey" errors for un-activated accounts.** `syncGuardianAccounts` now only syncs Guardian accounts that actually carry a hot key, instead of every account not flagged `requiresHotKeyRotation`. A legacy single-signer Guardian record that hasn't been migrated yet — e.g. in the brief window after a wallet upgrade (new code, old storage) and before the forced re-unlock runs the migration — has no hot key, so `getOrCreateMultisigService` threw on it every ~3s AutoSync tick. There's genuinely no hot-bound service to build for such accounts, so they're skipped; recovery still happens via the migration → Activate Device Key banner path on the next unlock. (#227)
+* [FIX][all] **Guardian operator endpoint is now tracked per account, and structural Guardian ops recover from a submit-then-local-apply failure.** Each Guardian account persists its own `guardianEndpoint` (set at create/recovery, updated on switch-guardian) instead of a single global setting, so two Guardian accounts on different operators no longer collide — older records without the field fall back to the legacy global value. Separately, when a `replace-hot-key` or `switch-guardian` transaction lands on chain but the local apply step throws, the wallet now runs the same finalization the happy path would (swapping the hot-key pointer, or re-registering on the new guardian and persisting its endpoint) instead of cancelling — which previously stranded the account signing with a rotated-out key or talking to the old guardian. (#227)
 * [FIX][all] **Guardian co-sign transactions are now serialized per account.** The Guardian co-signs one delta per account at a time, so concurrent same-account transactions (e.g. auto-consume racing a user claim, or rapid successive claims) made the Guardian's expected commitment diverge from on-chain — stalling its canonicalization for minutes and returning `409 ConflictPendingDelta` while a prior delta was still finalizing, which surfaced as a Guardian claim/send that never completes. Guardian transactions now take a per-account lock so at most one is ever in flight, and proposal creation waits out a transient `409` (a prior delta mid-canonicalization) instead of failing the transaction. (#297)
 
 ## 1.15.2 (2026-06-22)
@@ -33,6 +36,8 @@
 
 ### Features
 
+* [FEATURE][all] 3-key Guardian: cold co-signs `switch_guardian` (on-chain threshold-2 satisfied via `procedureThresholds`) and a new Settings → Rotate Device Key flow lets users replace the hot signer in-place via a single cold-signed `update_signers` proposal, persisting the new ciphertext before submission and finalizing `WalletAccount.hotPublicKey` (plus releasing the old SE/StrongBox wrapper) only after on-chain inclusion. Settings → Switch Guardian now requires an explicit confirmation step before initiating, mirroring the Rotate Device Key flow so the user acknowledges that the switch is cold-signed + guardian-co-signed. Guardian import-by-seed does lookup + adopt only (`MultisigClient.recoverByKey` per HD index until first miss); each adopted account is flagged `requiresHotKeyRotation` and the home view surfaces an Activate Device Key banner with a one-click CTA that fires the same cold-signed `update_signers` rotation — the banner self-hides once `Vault.swapHotKey` lands. The `swapHotKey` message now carries only `newHotPubKey`; the vault resolves the previous hot from the persisted `WalletAccount`, so the initial post-recovery activation and subsequent rotations share one code path.
+* [FEATURE][all] 3-key Guardian accounts. Guardian creation now provisions a hot ECDSA key (random, lives outside the WASM keystore behind a new `secure-hot-key` facade — extension/desktop use a JS fallback; iOS wraps the secret under a per-account Secure Enclave P-256 key via `HotKeyPlugin.swift`; Android wraps it under a per-account StrongBox-backed RSA-OAEP key via `HotKeyPlugin.kt` with biometric-gated unwrap, identical wire format on both platforms) plus an HD-derived cold ECDSA key (kept in the SDK keystore for cold-routed flows) alongside the existing guardian co-signer. Threshold stays at 1 (hot OR cold + guardian); cold-only routing for `update_signers` / `update_guardian` / `update_procedure_threshold` is enforced client-side per the Phase 0 SDK reading. Storage adds `accColdSecretKeyStrgKey` and `WalletAccount.{hotPublicKey,coldPublicKey}` so role-aware `signWord` (Phase 3) can dispatch hot vs cold by storage entity. Hard cutover from the 1-of-1 Falcon scheme — pre-cutover Guardian accounts are unreachable from this build.
 * [FEATURE][all] Guardian integration. Adds Guardian-backed accounts (1-of-1 multisig with on-chain Guardian signature verification), onboarding create/import flows with a dedicated recovery-method screen that accepts a custom guardian URL, Settings → Guardian Settings with an on-chain switch-guardian proposal that re-registers post-switch state with the new endpoint, service-worker routing for Guardian transaction signing via `MultisigService`, frontend Guardian sync outside the WASM lock, and per-stage progress labels (`creating-proposal`, `signing-proposal`, `submitting`, `registering-guardian`) in the transaction modal.
 * [FEATURE][all] **Default auth scheme for new accounts switched from Falcon to ECDSA.** Existing accounts are unaffected — Miden seals the auth component at on-chain creation and can never rotate it, so any account previously created stays Falcon and continues signing with its existing keystore secret. Restore paths handle both schemes: mnemonic-only restore (`Vault.spawn`) probes the chain under each scheme to find the user's actual hdIndex=0 account; encrypted-file restore reads the new optional `authScheme` field on `WalletAccount` (legacy entries with no field default to Falcon, matching the historical default 1:1). Private-key import detects the scheme from the deserialized `AuthSecretKey` via the SDK's per-scheme accessor. New accounts created post-upgrade get ECDSA stamped into their `WalletAccount` record. Encrypted-file format change is purely additive — old files round-trip through restore as Falcon. (#229)
 

CLAUDE.md

@@ -122,6 +122,12 @@ xcrun simctl spawn booted notifyutil -p com.apple.BiometricKit_Sim.fingerTouch.m
 - Grey bar at bottom → `100dvh` doesn't account for safe areas. Use `100%` + `env(safe-area-inset-*)` padding on `mobile.html` body.
 - Debug UI text should be `select-text` so errors are copyable.
 
+### Adding Swift files to the App target
+The App target in `ios/App/App.xcodeproj/project.pbxproj` does NOT auto-discover Swift files in the `App/` source directory. New files must be registered in four sections: `PBXBuildFile`, `PBXFileReference`, the App `PBXGroup` children, and the `PBXSourcesBuildPhase` files list. Pattern: see `LocalBiometricPlugin.swift` or `HotKeyPlugin.swift` entries.
+
+### Adding a custom Capacitor plugin (iOS)
+Capacitor on this app uses **manual** registration — not the `CAPBridgedPlugin` auto-discovery you'd get on a stock Capacitor app. After creating `MyPlugin.swift` and wiring it into the four pbxproj sections above, you also have to call `bridge?.registerPluginInstance(MyPlugin())` inside `capacitorDidLoad()` in `ios/App/App/AppViewController.swift`. Skip this step and JS calls land as `{"code":"UNIMPLEMENTED"}` even though the class compiled fine.
+
 ### Native navbar overlay
 Mobile hides React footer and renders bottom nav as native pill (iOS: `MidenNavbarOverlayWindow` `UIWindow`; Android: two-instance `NavbarOverlayManager` with Activity-scoped + Dialog-scoped `NavbarView`). Plugin methods: `showNativeNavbar`, `setNavbarSecondaryRow`, `setNavbarAction`, `morphNavbar{Out,In}`. Events: `nativeNavbarTap`, `nativeNavbarSecondaryTap`, `nativeNavbarActionTap`. Wiring: `src/app/providers/DappBrowserProvider.tsx`. Android gotchas: don't use `MATCH_PARENT` children in `WRAP_CONTENT` parents (1878px buttons); `Dialog.setLayout` must follow `setContentView`; shadow must be on the view owning the background drawable.
 

__mocks__/@openzeppelin/miden-multisig-client.ts

@@ -59,6 +59,16 @@ export const buildMultisigStorageSlots = jest.fn();
 export const buildGuardianStorageSlots = jest.fn();
 export const storageLayoutBuilder = jest.fn();
 
+// Update-signers + summary builders used by createReplaceHotKeyProposal. The
+// real implementations touch WASM; tests mock-or-spy as needed.
+export const buildUpdateSignersTransactionRequest = jest.fn(async () => ({
+  request: { kind: 'update-signers-request' },
+  salt: { toHex: () => 'salt-hex' }
+}));
+export const executeForSummary = jest.fn(async () => ({
+  serialize: () => new Uint8Array([0xab])
+}));
+
 export class StorageLayoutBuilder {
   constructor(..._args: unknown[]) {}
 }

__mocks__/lib/miden/back/vault.ts

@@ -43,6 +43,10 @@ export class Vault {
     return state.accounts;
   }
 
+  // Best-effort on-unlock migration of legacy single-key Guardian accounts to
+  // the 3-key model — a no-op in the mock (no real accounts/keys to migrate).
+  async migrateLegacyGuardianAccounts() {}
+
   async fetchSettings() {
     return state.settings;
   }

android/app/build.gradle

@@ -65,6 +65,10 @@ dependencies {
     implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
     // Biometric authentication for hardware security
     implementation 'androidx.biometric:biometric:1.1.0'
+    // secp256k1 ECDSA + Keccak-256 for the Guardian hot-key signing path
+    // (HotKeyPlugin). Keystore wraps the 32-byte k256 secret with RSA-OAEP;
+    // BouncyCastle handles everything outside the Keystore boundary.
+    implementation 'org.bouncycastle:bcprov-jdk18on:1.78.1'
 }
 
 apply from: 'capacitor.build.gradle'

android/app/proguard-rules.pro

@@ -70,6 +70,12 @@
 -keep class com.niceforyou.capacitor.barcodescanner.** { *; }
 -keep class com.google.mlkit.vision.barcode.** { *; }
 
+# BouncyCastle (secp256k1 + Keccak-256) — used by HotKeyPlugin for the
+# Guardian hot-key signing path. Keep the low-level crypto + asn1 classes
+# we touch reflectively via JCE provider lookup paths.
+-keep class org.bouncycastle.** { *; }
+-keep class com.miden.wallet.HotKeyPlugin { *; }
+
 # Don't warn about missing classes in optional dependencies
 -dontwarn org.conscrypt.**
 -dontwarn org.bouncycastle.**