[Guardian] Add rotate_kps: setup-mode KP rotation

Adds the rotate_kps gRPC handler. Each current KP submits an encrypted
old share along with a state portion describing the rotation target
(new KP pubkeys, new N, new T, current commitments, current seq).
T-of-N digest-matched across submissions; the same digest is bound as
HPKE AAD on the encrypted share.

On reaching the current threshold the enclave:
- reconstructs the BTC key in memory from the old shares,
- re-splits it with fresh randomness for the new KP set using the
  new (n, t),
- writes CurrentKeyState { seq = current_seq + 1, encrypted_shares,
  secret_sharing_config } to key_state/.

Asymmetric rotation (new N/T differs from old) is supported.

Cross-checks: the KP-supplied current_share_commitments must match
what the enclave was given at operator_init (via SecretSharingConfig);
each old share is verified against those commitments before reaching
the digest-match step.

Tests cover happy path (symmetric + asymmetric), dup share, state
mismatch panic, share-not-matching-commitments, state commitments
not matching enclave, wrong pubkey count, duplicate new pubkeys, and
pre-operator-init rejection.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: mskd12

crates/hashi-guardian/README.md

@@ -18,15 +18,15 @@ Where:
 - `init_suffix` is a semantic label (`oi-attestation-unsigned`, `oi-guardian-info`, `pi-success-share-{share_id}`, `pi-enclave-fully-initialized`).
 - `counter` is a zero-padded decimal sequence number (used in heartbeats only).
 - `seq` (in `withdraw/`) is the zero-padded limiter sequence number consumed by the withdrawal.
-- `sharing_seq` (in `secret_sharing/`) is a zero-padded rotation counter — `setup_new_key` writes `0`; future key-provisioner rotations will append `prev+1`.
+- `sharing_seq` (in `secret_sharing/`) is a zero-padded rotation counter — `setup_new_key` writes `0`; each `rotate_kps` appends `prev+1`.
 - `rand8` is a random 8-hex suffix to avoid key collisions (failures only — successes are uniquely keyed by seq).
 
 ## Stream semantics
 
 - `init` logs are per-session and deterministic by semantic message kind.
 - `heartbeat` logs are hour-partitioned and strictly ordered per session.
 - `withdraw` logs are hour-partitioned. Successes are seq-sorted within a bucket so the KP rotating in the next enclave can recover limiter state by reading the lexicographically last success key.
-- `secret_sharing` logs are flat (not date-partitioned). Each entry is a `SecretSharingLogMessage { encrypted_shares, secret_sharing_config }` written by `setup_new_key` (genesis, `sharing_seq=0`). KPs read the lexicographically last entry to learn the current authoritative commitments and to fetch their encrypted shares.
+- `secret_sharing` logs are flat (not date-partitioned). Each entry is a `SecretSharingLogMessage { encrypted_shares, secret_sharing_config }` written by `setup_new_key` (genesis, `sharing_seq=0`) or `rotate_kps` (each rotation, `sharing_seq=prev+1`). KPs read the lexicographically last entry to learn the current authoritative scheme (commitments + N + T) and to fetch their encrypted shares.
 
 ## Why this layout
 

crates/hashi-guardian/src/enclave.rs

@@ -72,7 +72,7 @@ pub struct Scratchpad {
     pub shares: tokio::sync::Mutex<Vec<Share>>,
     /// Secret-sharing scheme (commitments + N + T) set by operator_init.
     pub secret_sharing_config: OnceLock<SecretSharingConfig>,
-    /// Hash of the state in ProvisionerInitRequest
+    /// Hash of the state in ProvisionerInitRequest (non-setup mode) (or) RotateKps (setup mode)
     pub state_hash: OnceLock<[u8; 32]>,
     /// Set once operator_init has successfully written all logs to S3.
     /// This prevents heartbeats from being emitted before operator_init logs.
@@ -490,14 +490,24 @@ impl Enclave {
             .map_err(|_| InvalidInputs("Secret sharing config already set".into()))
     }
 
-    pub fn state_hash(&self) -> Option<&[u8; 32]> {
-        self.scratchpad.state_hash.get()
-    }
-
-    pub fn set_state_hash(&self, hash: [u8; 32]) -> GuardianResult<()> {
-        self.scratchpad
-            .state_hash
-            .set(hash)
-            .map_err(|_| InvalidInputs("State hash already set".into()))
+    /// Match `state_hash` against the previously-stored hash from earlier
+    /// submissions in the same multi-KP flow. Sets it on the first call;
+    /// panics on mismatch (any divergence between KPs means at least one is
+    /// malicious or misconfigured — refuse to proceed).
+    pub fn check_or_set_state_hash(&self, state_hash: [u8; 32]) -> GuardianResult<()> {
+        match self.scratchpad.state_hash.get() {
+            Some(existing) if *existing != state_hash => {
+                panic!("State hash mismatch")
+            }
+            Some(_) => info!("State hash matches existing."),
+            None => {
+                self.scratchpad
+                    .state_hash
+                    .set(state_hash)
+                    .map_err(|_| InvalidInputs("State hash already set".into()))?;
+                info!("State hash set.");
+            }
+        }
+        Ok(())
     }
 }

crates/hashi-guardian/src/init.rs

@@ -5,8 +5,8 @@ use crate::getters::get_attestation;
 use crate::Enclave;
 use crate::S3Logger;
 use hashi_types::guardian::crypto::combine_shares;
-use hashi_types::guardian::crypto::commit_share;
 use hashi_types::guardian::crypto::decrypt_share;
+use hashi_types::guardian::crypto::k256_sk_to_btc_keypair;
 use hashi_types::guardian::crypto::Share;
 use hashi_types::guardian::InitLogMessage::OIAttestationUnsigned;
 use hashi_types::guardian::InitLogMessage::OIGuardianInfo;
@@ -138,21 +138,11 @@ pub async fn provisioner_init(
     let ssc = enclave
         .secret_sharing_config()
         .expect("secret sharing config should be set after operator_init");
-    verify_share(&share, ssc.commitments())?;
+    ssc.commitments().verify_share(&share)?;
     info!("Share verified.");
 
     // 3) Set state_hash OR make sure whatever was previously set matches. Panics upon mismatch.
-    info!("Checking state hash.");
-    match enclave.state_hash() {
-        Some(existing_state_hash) if *existing_state_hash != state_hash => {
-            panic!("State hash mismatch")
-        }
-        Some(_) => info!("State hash matches existing."),
-        None => {
-            enclave.set_state_hash(state_hash)?;
-            info!("State hash set.");
-        }
-    }
+    enclave.check_or_set_state_hash(state_hash)?;
 
     // MILESTONE: At this point, we are sure it is a legitimate payload (both share & config)
 
@@ -206,7 +196,8 @@ async fn finalize_init(
     incoming_state: ProvisionerInitState,
 ) {
     info!("Threshold reached, combining shares.");
-    let enclave_btc_keypair = combine_shares(shares, threshold).expect("Unable to combine shares");
+    let enclave_k256_sk = combine_shares(shares, threshold).expect("Unable to combine shares");
+    let enclave_btc_keypair = k256_sk_to_btc_keypair(&enclave_k256_sk);
 
     info!("Setting enclave keypair.");
     enclave
@@ -235,13 +226,6 @@ async fn finalize_init(
     info!("Enclave initialization complete.");
 }
 
-fn verify_share(share: &Share, commitments: &ShareCommitments) -> GuardianResult<()> {
-    commitments
-        .contains(&commit_share(share))
-        .then_some(())
-        .ok_or_else(|| InvalidInputs("No matching share found".into()))
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

crates/hashi-guardian/src/lib.rs

@@ -12,6 +12,7 @@ pub mod enclave;
 pub mod getters;
 pub mod heartbeat;
 pub mod init;
+pub mod rotate;
 pub mod rpc;
 pub mod s3_logger; // used by the monitor
 pub mod setup;
@@ -30,6 +31,8 @@ pub use test_utils::create_operator_initialized_enclave;
 #[cfg(any(test, feature = "test-utils"))]
 pub use test_utils::mock_logger;
 #[cfg(any(test, feature = "test-utils"))]
+pub use test_utils::mock_logger_capturing;
+#[cfg(any(test, feature = "test-utils"))]
 pub use test_utils::mock_logger_with_layout;
 #[cfg(any(test, feature = "test-utils"))]
 pub use test_utils::FullyInitializedArgs;

crates/hashi-guardian/src/main.rs

@@ -17,10 +17,10 @@ use tonic_health::server::health_reporter;
 use tracing::info;
 
 /// Enclave initialization.
-/// `setup_new_key` is gated to SETUP_MODE=true; `provisioner_init` and
-/// `standard_withdrawal` are gated to SETUP_MODE=false. Everything else
-/// (operator_init, get_guardian_info, …) is available in both modes. See the
-/// per-route gates in `rpc.rs`.
+/// `setup_new_key` and `rotate_kps` are gated to SETUP_MODE=true;
+/// `provisioner_init` and `standard_withdrawal` are gated to SETUP_MODE=false.
+/// Everything else (operator_init, get_guardian_info, …) is available in
+/// both modes. See the per-route gates in `rpc.rs`.
 #[tokio::main]
 async fn main() -> Result<()> {
     hashi_types::telemetry::TelemetryConfig::new()
@@ -35,9 +35,9 @@ async fn main() -> Result<()> {
         .unwrap_or(false);
 
     if setup_mode {
-        info!("Setup mode: setup_new_key enabled; provisioner_init/standard_withdrawal disabled.");
+        info!("Setup mode: setup_new_key/rotate_kps enabled; provisioner_init/standard_withdrawal disabled.");
     } else {
-        info!("Normal mode: provisioner_init/standard_withdrawal enabled; setup_new_key disabled.");
+        info!("Normal mode: provisioner_init/standard_withdrawal enabled; setup_new_key/rotate_kps disabled.");
     }
 
     let signing_keys = GuardianSignKeyPair::new(rand::thread_rng());