feat(common): isolate Tempo session key storage (#14878)

* feat: isolate Tempo session key storage

* fix: clear expired Tempo session keys

* fix: clear terminal Tempo session keys

Author: 0xKarl98

crates/common/src/tempo/session.rs

@@ -1,6 +1,6 @@
 //! Tempo session registry and local lifecycle metadata.
 
-use super::{registry::*, tempo_home};
+use super::{KeyType, registry::*, tempo_home};
 use alloy_primitives::{Address, B256, Selector};
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
@@ -43,6 +43,30 @@ pub struct SessionTokenLimit {
     pub limit: String,
 }
 
+/// Private key material for a temporary session access key.
+///
+/// Session keys live with their lifecycle record in `wallet/sessions.toml`.
+/// Persistent Tempo wallet login keys remain in `wallet/keys.toml`, so creating
+/// or cleaning up a session cannot replace a user's long-lived access key.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+pub struct SessionKeyMaterial {
+    #[serde(default)]
+    pub key_type: KeyType,
+    /// Hex-encoded private key for the temporary session access key.
+    pub key: String,
+    /// RLP-encoded signed key authorization, if the key still needs inline
+    /// provisioning on first use.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub key_authorization: Option<String>,
+}
+
+impl SessionKeyMaterial {
+    /// Returns `true` when the entry carries a non-empty private key.
+    pub fn has_inline_key(&self) -> bool {
+        !self.key.trim().is_empty()
+    }
+}
+
 /// A single selector rule in a session scope.
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
 pub struct SessionSelectorRule {
@@ -78,13 +102,27 @@ pub struct SessionEntry {
     pub limits: Vec<SessionTokenLimit>,
     #[serde(default)]
     pub status: SessionStatus,
+    /// Session-scoped key material. This is intentionally separate from
+    /// `wallet/keys.toml`, which stores persistent access keys.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub key: Option<SessionKeyMaterial>,
 }
 
 impl SessionEntry {
     /// Returns `true` if the session has passed its expiry timestamp.
     pub const fn is_expired_at(&self, now: u64) -> bool {
         now >= self.expiry
     }
+
+    /// Returns `true` if this session has usable local key material.
+    pub fn has_inline_key(&self) -> bool {
+        self.key.as_ref().is_some_and(SessionKeyMaterial::has_inline_key)
+    }
+
+    /// Returns `true` if this session is active, unexpired, and has key material.
+    pub fn has_live_key_at(&self, now: u64) -> bool {
+        self.status == SessionStatus::Active && !self.is_expired_at(now) && self.has_inline_key()
+    }
 }
 
 /// Top-level registry persisted in `wallet/sessions.toml`.
@@ -113,12 +151,31 @@ impl SessionRecord {
         self.sessions.len() != before
     }
 
+    /// Returns a session by id.
+    pub fn get(&self, session_id: B256) -> Option<&SessionEntry> {
+        self.sessions.iter().find(|session| session.session_id == session_id)
+    }
+
+    /// Returns an active session with usable local key material by id.
+    pub fn live_key(&self, session_id: B256, now: u64) -> Option<&SessionEntry> {
+        self.get(session_id).filter(|session| session.has_live_key_at(now))
+    }
+
     /// Mark expired live entries as expired. Returns the number updated.
     pub fn mark_expired(&mut self, now: u64) -> usize {
         let mut updated = 0;
         for session in &mut self.sessions {
-            if session.status.is_live() && session.is_expired_at(now) {
+            let should_expire = session.status.is_live() && session.is_expired_at(now);
+            let should_clear_key =
+                session.key.is_some() && (should_expire || session.status.is_terminal());
+
+            if should_expire {
                 session.status = SessionStatus::Expired;
+            }
+            if should_clear_key {
+                session.key = None;
+            }
+            if should_expire || should_clear_key {
                 updated += 1;
             }
         }
@@ -146,6 +203,11 @@ pub fn read_session_record() -> Option<SessionRecord> {
     }
 }
 
+/// Read a live session-scoped key entry by session id.
+pub fn read_live_session_key(session_id: B256, now: u64) -> Option<SessionEntry> {
+    read_session_record()?.live_key(session_id, now).cloned()
+}
+
 /// Atomically upsert a [`SessionEntry`] into the session registry.
 pub fn upsert_session_entry(entry: SessionEntry) -> eyre::Result<()> {
     let path =
@@ -168,6 +230,21 @@ pub fn remove_session_entry(session_id: B256) -> eyre::Result<bool> {
     Ok(removed)
 }
 
+/// Mark expired live sessions in the registry and persist the status updates.
+pub fn mark_expired_session_entries(now: u64) -> eyre::Result<usize> {
+    let path =
+        session_registry_path().ok_or_else(|| eyre::eyre!("could not resolve tempo home"))?;
+    let Some(mut record) = read_toml_file::<SessionRecord>(&path, "tempo sessions")? else {
+        return Ok(0);
+    };
+
+    let updated = record.mark_expired(now);
+    if updated != 0 {
+        write_toml_file_atomic(&path, &record, SESSIONS_HEADER)?;
+    }
+    Ok(updated)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -193,6 +270,18 @@ mod tests {
                 limit: "0".to_string(),
             }],
             status,
+            key: None,
+        }
+    }
+
+    fn sample_entry_with_key(session_id: B256, expiry: u64, status: SessionStatus) -> SessionEntry {
+        SessionEntry {
+            key: Some(SessionKeyMaterial {
+                key_type: KeyType::Secp256k1,
+                key: "0xdeadbeef".to_string(),
+                key_authorization: Some("0xfeed".to_string()),
+            }),
+            ..sample_entry(session_id, expiry, status)
         }
     }
 
@@ -254,17 +343,142 @@ mod tests {
 
     #[test]
     fn session_entry_roundtrips_scope_limits_and_status() {
-        let entry = sample_entry(B256::from([0x66; 32]), 1234, SessionStatus::Revoking);
+        let entry = sample_entry_with_key(B256::from([0x66; 32]), 1234, SessionStatus::Revoking);
         let toml = toml::to_string(&entry).unwrap();
         let decoded: SessionEntry = toml::from_str(&toml).unwrap();
 
         assert_eq!(decoded.session_id, entry.session_id);
         assert_eq!(decoded.scope.len(), 1);
         assert_eq!(decoded.limits.len(), 1);
         assert_eq!(decoded.status, SessionStatus::Revoking);
+        assert_eq!(decoded.key.as_ref().unwrap().key, "0xdeadbeef");
+        assert!(decoded.has_inline_key());
         assert!(decoded.is_expired_at(1234));
     }
 
+    #[test]
+    fn live_session_key_requires_key_material_live_status_and_unexpired_entry() {
+        let live_id = B256::from([0x01; 32]);
+        let expired_id = B256::from([0x02; 32]);
+        let revoked_id = B256::from([0x03; 32]);
+        let no_key_id = B256::from([0x04; 32]);
+        let pending_id = B256::from([0x05; 32]);
+
+        let record = SessionRecord {
+            sessions: vec![
+                sample_entry_with_key(live_id, 200, SessionStatus::Active),
+                sample_entry_with_key(expired_id, 100, SessionStatus::Active),
+                sample_entry_with_key(revoked_id, 200, SessionStatus::Revoked),
+                sample_entry(no_key_id, 200, SessionStatus::Active),
+                sample_entry_with_key(pending_id, 200, SessionStatus::Pending),
+            ],
+        };
+
+        assert_eq!(record.live_key(live_id, 100).unwrap().session_id, live_id);
+        assert!(record.live_key(expired_id, 100).is_none());
+        assert!(record.live_key(revoked_id, 100).is_none());
+        assert!(record.live_key(no_key_id, 100).is_none());
+        assert!(record.live_key(pending_id, 100).is_none());
+    }
+
+    #[test]
+    fn session_key_storage_does_not_replace_persistent_keys_file() {
+        with_tempo_home(|| {
+            let keys_path = crate::tempo::tempo_keys_path().unwrap();
+            fs::create_dir_all(keys_path.parent().unwrap()).unwrap();
+            let original_keys = r#"[[keys]]
+wallet_type = "local"
+wallet_address = "0x0000000000000000000000000000000000000001"
+chain_id = 4217
+key_type = "secp256k1"
+key_address = "0x0000000000000000000000000000000000000001"
+key = "0x1111"
+expiry = 999
+"#;
+            fs::write(&keys_path, original_keys).unwrap();
+
+            let session_id = B256::from([0x99; 32]);
+            upsert_session_entry(sample_entry_with_key(session_id, 200, SessionStatus::Active))
+                .unwrap();
+
+            assert_eq!(fs::read_to_string(&keys_path).unwrap(), original_keys);
+            let session = read_live_session_key(session_id, 100).unwrap();
+            assert_eq!(session.key.unwrap().key, "0xdeadbeef");
+        });
+    }
+
+    #[test]
+    fn removing_session_key_preserves_persistent_key() {
+        with_tempo_home(|| {
+            let keys_path = crate::tempo::tempo_keys_path().unwrap();
+            fs::create_dir_all(keys_path.parent().unwrap()).unwrap();
+            let original_keys = r#"[[keys]]
+wallet_type = "local"
+wallet_address = "0x0000000000000000000000000000000000000001"
+chain_id = 4217
+key_type = "secp256k1"
+key_address = "0x0000000000000000000000000000000000000001"
+key = "0x1111"
+"#;
+            fs::write(&keys_path, original_keys).unwrap();
+
+            let session_id = B256::from([0xaa; 32]);
+            upsert_session_entry(sample_entry_with_key(session_id, 200, SessionStatus::Active))
+                .unwrap();
+            assert!(remove_session_entry(session_id).unwrap());
+
+            assert_eq!(fs::read_to_string(&keys_path).unwrap(), original_keys);
+            assert!(read_session_record().unwrap().is_empty());
+        });
+    }
+
+    #[test]
+    fn mark_expired_session_entries_persists_status_without_touching_keys_file() {
+        with_tempo_home(|| {
+            let keys_path = crate::tempo::tempo_keys_path().unwrap();
+            fs::create_dir_all(keys_path.parent().unwrap()).unwrap();
+            let original_keys = "[[keys]]\nkey = \"0x1111\"\n";
+            fs::write(&keys_path, original_keys).unwrap();
+
+            let session_id = B256::from([0xbb; 32]);
+            upsert_session_entry(sample_entry_with_key(session_id, 100, SessionStatus::Active))
+                .unwrap();
+
+            assert_eq!(mark_expired_session_entries(100).unwrap(), 1);
+            let record = read_session_record().unwrap();
+            let session = record.get(session_id).unwrap();
+            assert_eq!(session.status, SessionStatus::Expired);
+            assert!(session.key.is_none());
+            assert!(read_live_session_key(session_id, 100).is_none());
+            assert_eq!(fs::read_to_string(&keys_path).unwrap(), original_keys);
+        });
+    }
+
+    #[test]
+    fn mark_expired_session_entries_clears_terminal_session_keys() {
+        with_tempo_home(|| {
+            let expired_id = B256::from([0xbc; 32]);
+            let revoked_id = B256::from([0xbd; 32]);
+            let failed_id = B256::from([0xbe; 32]);
+
+            upsert_session_entry(sample_entry_with_key(expired_id, 100, SessionStatus::Expired))
+                .unwrap();
+            upsert_session_entry(sample_entry_with_key(revoked_id, 200, SessionStatus::Revoked))
+                .unwrap();
+            upsert_session_entry(sample_entry_with_key(failed_id, 200, SessionStatus::Failed))
+                .unwrap();
+
+            assert_eq!(mark_expired_session_entries(100).unwrap(), 3);
+            let record = read_session_record().unwrap();
+            for session_id in [expired_id, revoked_id, failed_id] {
+                assert!(record.get(session_id).unwrap().key.is_none());
+            }
+            assert_eq!(record.get(expired_id).unwrap().status, SessionStatus::Expired);
+            assert_eq!(record.get(revoked_id).unwrap().status, SessionStatus::Revoked);
+            assert_eq!(record.get(failed_id).unwrap().status, SessionStatus::Failed);
+        });
+    }
+
     #[test]
     fn upsert_fails_closed_when_session_file_is_corrupt() {
         with_tempo_home(|| {
@@ -294,4 +508,17 @@ mod tests {
             assert_eq!(fs::read_to_string(&path).unwrap(), original);
         });
     }
+
+    #[test]
+    fn mark_expired_fails_closed_when_session_file_is_corrupt() {
+        with_tempo_home(|| {
+            let path = session_registry_path().unwrap();
+            fs::create_dir_all(path.parent().unwrap()).unwrap();
+            fs::write(&path, "sessions = [").unwrap();
+            let original = fs::read_to_string(&path).unwrap();
+
+            assert!(mark_expired_session_entries(100).is_err());
+            assert_eq!(fs::read_to_string(&path).unwrap(), original);
+        });
+    }
 }