[Guardian] KP-rotation prep: N/T runtime + SecretSharingConfig (#591)

Prep for KP rotation. No new RPC surface.
  
  Moves the secret-sharing scheme from compile-time constants
  (`THRESHOLD = 3`, `NUM_OF_SHARES = 5`) to runtime-configurable
  operator-supplied state. N and T now flow through
  `OperatorInitRequest.secret_sharing_config`, bundled with the
  share commitments and a new `sharing_seq` (versions instances:
  setup writes 0, future rotations append prev+1).

  Adds a new flat `secret_sharing/` S3 log stream — entries are
  `SecretSharingLogMessage { encrypted_shares, secret_sharing_config }`
  written by `setup_new_key` today and by `rotate_kps` in the
  follow-up. KPs read the lex-last entry to learn the current
  authoritative scheme and fetch their encrypted shares.

  `GuardianInfo` returns the full `SecretSharingConfig` so KPs can
  cross-check the enclave's stored state against S3 off-enclave.
  Crypto tests parameterized over (2,2), (3,2), (5,3), (10,7).
  Object locks unified at 7 days; session IDs truncated to 16
  hex chars in S3 keys.

  Stacked PR #592 adds `rotate_kps` on top.

Author: mskd12

crates/hashi-guardian/README.md

@@ -10,23 +10,28 @@ Canonical key layout:
 - `heartbeat/{yyyy}/{mm}/{dd}/{hh}/{session_id}-{counter:020}.json`
 - `withdraw/{yyyy}/{mm}/{dd}/{hh}/success-{seq:020}-{session_id}-wid{wid}.json`
 - `withdraw/{yyyy}/{mm}/{dd}/{hh}/failure-{session_id}-wid{wid}-{rand8}.json`
+- `secret_sharing/{sharing_seq:020}-{session_id}.json`
 
 Where:
 
-- `session_id` is the enclave ephemeral signing pubkey bytes encoded as lowercase hex.
-- `init_suffix` is a semantic label (`oi-attestation-unsigned`, `oi-guardian-info`, `setup-new-key-success`, `pi-success-share-{share_id}`, `pi-enclave-fully-initialized`).
+- `session_id` is the first 16 hex chars of the enclave ephemeral signing pubkey (lowercase). Acts as a short per-session tag in keys; full pubkey verification still happens via the signed log payload (`SESSION_ID_HEX_LEN` in `hashi-types`).
+- `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` is the limiter sequence number consumed by this withdrawal; zero-padded so lexicographic order within an hour bucket equals seq order.
+- `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`.
 - `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.
 
 ## Why this layout
 
 - `init/{session_id}-...` keeps init logs session-addressable.
 - `heartbeat/...` and `withdraw/...` date partitions support efficient hour-based polling.
-- Prefixes (`init`, `heartbeat`, `withdraw`) allow independent S3 deletion policies.
+- `secret_sharing/` is flat because the consumer always wants "latest"; a lex sort over the whole prefix is cheap and gives that directly.
+- Zero-padding (`{seq:020}` in `withdraw/`, `{sharing_seq:020}` in `secret_sharing/`) makes lexicographic order over the keys equal seq order. The signed log payload embeds the same value, so a fetched object's filename and content can be cross-checked.
+- Prefixes (`init`, `heartbeat`, `withdraw`, `secret_sharing`) allow independent S3 deletion policies.

crates/hashi-guardian/src/enclave.rs

@@ -70,8 +70,8 @@ pub struct Scratchpad {
     /// The received shares
     /// TODO: Investigate if it can be moved to std::sync::Mutex
     pub shares: tokio::sync::Mutex<Vec<Share>>,
-    /// The share commitments
-    pub share_commitments: OnceLock<ShareCommitments>,
+    /// Secret-sharing scheme (commitments + N + T) set by operator_init.
+    pub secret_sharing_config: OnceLock<SecretSharingConfig>,
     /// Hash of the state in ProvisionerInitRequest
     pub state_hash: OnceLock<[u8; 32]>,
     /// Set once operator_init has successfully written all logs to S3.
@@ -372,7 +372,7 @@ impl Enclave {
 
     pub fn is_operator_init_complete(&self) -> bool {
         self.config.is_operator_init_complete()
-            && self.scratchpad.share_commitments.get().is_some()
+            && self.scratchpad.secret_sharing_config.get().is_some()
             && self
                 .scratchpad
                 .operator_init_logging_complete
@@ -382,7 +382,7 @@ impl Enclave {
 
     pub fn is_operator_init_partially_complete(&self) -> bool {
         self.config.is_operator_init_partially_complete()
-            || self.scratchpad.share_commitments.get().is_some()
+            || self.scratchpad.secret_sharing_config.get().is_some()
     }
 
     pub fn is_fully_initialized(&self) -> bool {
@@ -420,7 +420,7 @@ impl Enclave {
 
     pub fn info(&self) -> GuardianInfo {
         GuardianInfo {
-            share_commitments: self.share_commitments().ok().cloned(),
+            secret_sharing_config: self.secret_sharing_config().ok().cloned(),
             bucket_info: self
                 .config
                 .s3_logger()
@@ -463,6 +463,11 @@ impl Enclave {
         self.write_log(LogMessage::Heartbeat { seq }).await
     }
 
+    pub async fn log_secret_sharing(&self, state: SecretSharingLogMessage) -> GuardianResult<()> {
+        self.write_log(LogMessage::SecretSharing(Box::new(state)))
+            .await
+    }
+
     // ========================================================================
     // Scratchpad (Initialization-only data)
     // ========================================================================
@@ -471,18 +476,18 @@ impl Enclave {
         &self.scratchpad.shares
     }
 
-    pub fn share_commitments(&self) -> GuardianResult<&ShareCommitments> {
+    pub fn secret_sharing_config(&self) -> GuardianResult<&SecretSharingConfig> {
         self.scratchpad
-            .share_commitments
+            .secret_sharing_config
             .get()
-            .ok_or(InvalidInputs("Share commitments not set".into()))
+            .ok_or(InvalidInputs("Secret sharing config not set".into()))
     }
 
-    pub fn set_share_commitments(&self, commitments: ShareCommitments) -> GuardianResult<()> {
+    pub fn set_secret_sharing_config(&self, cfg: SecretSharingConfig) -> GuardianResult<()> {
         self.scratchpad
-            .share_commitments
-            .set(commitments)
-            .map_err(|_| InvalidInputs("Share commitments already set".into()))
+            .secret_sharing_config
+            .set(cfg)
+            .map_err(|_| InvalidInputs("Secret sharing config already set".into()))
     }
 
     pub fn state_hash(&self) -> Option<&[u8; 32]> {

crates/hashi-guardian/src/init.rs

@@ -35,7 +35,7 @@ pub async fn operator_init(
     }
     info!("Enclave state validated.");
 
-    let (config, commitments, network) = request.into_parts();
+    let (config, secret_sharing_config, network) = request.into_parts();
     let logger = S3Logger::new_checked(&config).await?;
     info!("S3 connectivity check complete.");
 
@@ -51,16 +51,21 @@ pub async fn operator_init(
         .set_bitcoin_network(network)
         .expect("Unable to set network");
 
-    info!("Storing {} share commitments.", commitments.len());
-    for (i, share_commitment) in commitments.iter().enumerate() {
+    info!(
+        "Storing secret-sharing config: n={}, t={}, {} commitments.",
+        secret_sharing_config.num_shares(),
+        secret_sharing_config.threshold(),
+        secret_sharing_config.commitments().len()
+    );
+    for (i, share_commitment) in secret_sharing_config.commitments().iter().enumerate() {
         info!(
             "Share {}: ID {} Digest {:x?}.",
             i, share_commitment.id, share_commitment.digest
         );
     }
     enclave
-        .set_share_commitments(commitments)
-        .expect("Unable to set share commitments");
+        .set_secret_sharing_config(secret_sharing_config)
+        .expect("Unable to set secret sharing config");
 
     // Log to S3!
     // 1) Attestation and pub key help authenticate all subsequent enclave-signed messages.
@@ -130,10 +135,10 @@ pub async fn provisioner_init(
 
     // 2) Verify the share against the commitment
     info!("Verifying share against commitment.");
-    let share_commitments = enclave
-        .share_commitments()
-        .expect("share commitments should be set after operator_init");
-    verify_share(&share, share_commitments)?;
+    let ssc = enclave
+        .secret_sharing_config()
+        .expect("secret sharing config should be set after operator_init");
+    verify_share(&share, ssc.commitments())?;
     info!("Share verified.");
 
     // 3) Set state_hash OR make sure whatever was previously set matches. Panics upon mismatch.
@@ -160,10 +165,8 @@ pub async fn provisioner_init(
     }
     received_shares.push(share);
     let current_share_count = received_shares.len();
-    info!(
-        "Total shares received: {}/{}.",
-        current_share_count, THRESHOLD
-    );
+    let threshold = ssc.threshold();
+    info!("Total shares received: {current_share_count}/{threshold}.");
 
     // Note: This S3 log does not serve any security purpose.
     enclave
@@ -175,7 +178,7 @@ pub async fn provisioner_init(
         .expect("Unable to log ProvisionerInitSuccess");
 
     // 5) If we have enough shares, finish initialization: combine shares & set config
-    if current_share_count >= THRESHOLD {
+    if current_share_count >= threshold {
         let shares_vec: Vec<Share> = received_shares.iter().cloned().collect();
         finalize_init(&shares_vec, &enclave, request.into_state()).await;
         // Log to S3 indicating that withdrawals can be expected henceforth
@@ -202,7 +205,11 @@ async fn finalize_init(
     incoming_state: ProvisionerInitState,
 ) {
     info!("Threshold reached, combining shares.");
-    let enclave_btc_keypair = combine_shares(shares).expect("Unable to combine shares");
+    let threshold = enclave
+        .secret_sharing_config()
+        .expect("secret sharing config set during operator_init")
+        .threshold();
+    let enclave_btc_keypair = combine_shares(shares, threshold).expect("Unable to combine shares");
 
     info!("Setting enclave keypair.");
     enclave
@@ -242,15 +249,17 @@ fn verify_share(share: &Share, commitments: &ShareCommitments) -> GuardianResult
 mod tests {
     use super::*;
     use crate::OperatorInitTestArgs;
-    use hashi_types::guardian::crypto::NUM_OF_SHARES;
     use hashi_types::guardian::test_utils::create_btc_keypair;
     use k256::SecretKey;
 
+    const TEST_N: usize = 5;
+    const TEST_T: usize = 3;
+
     /// Helper: Generate test shares and initialized enclave
     /// Returns (shares, enclave)
     async fn setup_test_shares_and_enclave() -> (Vec<Share>, Arc<Enclave>) {
         let sk = SecretKey::random(&mut rand::thread_rng());
-        let shares = split_secret(&sk, &mut rand::thread_rng());
+        let shares = split_secret(&sk, TEST_N, TEST_T, &mut rand::thread_rng()).unwrap();
         let share_commitments = ShareCommitments::from_shares(&shares).unwrap();
         let enclave = Enclave::create_operator_initialized_with(
             OperatorInitTestArgs::default().with_commitments(share_commitments),
@@ -264,8 +273,8 @@ mod tests {
         let (shares, enclave) = setup_test_shares_and_enclave().await;
         let init_state = ProvisionerInitState::mock_for_testing(None);
 
-        // Simulate THRESHOLD KPs calling provisioner_init
-        for (i, share) in shares.iter().enumerate().take(NUM_OF_SHARES) {
+        // Simulate KPs calling provisioner_init
+        for (i, share) in shares.iter().enumerate().take(TEST_N) {
             let request = ProvisionerInitRequest::build_from_share_and_state(
                 share,
                 enclave.encryption_public_key(),
@@ -276,12 +285,11 @@ mod tests {
             let result = provisioner_init(enclave.clone(), request).await;
 
             // Check behavior based on whether we've reached/exceeded threshold
-            if i == THRESHOLD - 1 {
+            if i == TEST_T - 1 {
                 // At exactly threshold (first time), call should succeed
                 assert!(
                     result.is_ok(),
-                    "Should succeed at threshold (iteration {})",
-                    i
+                    "Should succeed at threshold (iteration {i})"
                 );
                 assert!(
                     enclave.config.is_enclave_btc_keypair_set(),
@@ -291,14 +299,9 @@ mod tests {
                     enclave.config.is_hashi_btc_master_pubkey_set(),
                     "Hashi BTC key should be set after threshold"
                 );
-            } else if i >= THRESHOLD {
+            } else if i >= TEST_T {
                 // After threshold, subsequent init calls should fail
-                assert!(
-                    result.is_err(),
-                    "Should fail at iteration {}: {:?}",
-                    i,
-                    result
-                );
+                assert!(result.is_err(), "Should fail at iteration {i}: {result:?}");
                 assert!(
                     enclave.config.is_enclave_btc_keypair_set(),
                     "Bitcoin key should still be set"
@@ -317,7 +320,7 @@ mod tests {
             }
         }
 
-        println!("Successfully initialized enclave with {} shares", THRESHOLD);
+        println!("Successfully initialized enclave with {TEST_T} shares");
     }
 
     #[tokio::test]

crates/hashi-guardian/src/main.rs

@@ -17,8 +17,10 @@ use tonic_health::server::health_reporter;
 use tracing::info;
 
 /// Enclave initialization.
-/// SETUP_MODE=true: only get_attestation, operator_init and setup_new_key are enabled.
-/// SETUP_MODE=false: all endpoints except setup_new_key are enabled.
+/// `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`.
 #[tokio::main]
 async fn main() -> Result<()> {
     hashi_types::telemetry::TelemetryConfig::new()
@@ -33,9 +35,9 @@ async fn main() -> Result<()> {
         .unwrap_or(false);
 
     if setup_mode {
-        info!("Setup mode: setup_new_key route available, provisioner_init disabled.");
+        info!("Setup mode: setup_new_key enabled; provisioner_init/standard_withdrawal disabled.");
     } else {
-        info!("Normal mode: provisioner_init route available, setup_new_key disabled.");
+        info!("Normal mode: provisioner_init/standard_withdrawal enabled; setup_new_key disabled.");
     }
 
     let signing_keys = GuardianSignKeyPair::new(rand::thread_rng());