clawpowers 2.0.0 → 2.2.0

package/native/crates/verification/src/lib.rs

@@ -0,0 +1,333 @@
+//! Exact verification pipeline for TurboMemory.
+//!
+//! The [`VerificationPipeline`] fetches records from a [`CanonicalStore`],
+//! recomputes content hashes, and checks TTL / quarantine metadata before
+//! returning a typed [`VerificationResult`].
+
+use chrono::{Duration, Utc};
+use clawpowers_canonical::{CanonicalRecord, CanonicalStore, compute_sha256};
+use thiserror::Error;
+use uuid::Uuid;
+
+/// Errors returned by the verification pipeline.
+#[derive(Debug, Error)]
+pub enum VerificationError {
+    /// Underlying canonical store error.
+    #[error("store error: {0}")]
+    Store(#[from] clawpowers_canonical::CanonicalError),
+}
+
+/// A shorthand result type for [`VerificationError`].
+pub type Result<T> = std::result::Result<T, VerificationError>;
+
+// ─── Verification Result ─────────────────────────────────────────────────────
+
+/// The outcome of verifying a single record.
+#[derive(Debug)]
+pub enum VerificationResult {
+    /// Record is present, hash is valid, not expired, and not quarantined.
+    Verified(CanonicalRecord),
+
+    /// The stored hash does not match the recomputed hash.
+    IntegrityFailed {
+        /// Record identifier.
+        id: Uuid,
+        /// Hash value stored in the database.
+        expected_hash: String,
+        /// Hash value computed from the stored content.
+        actual_hash: String,
+    },
+
+    /// The record has a `ttl_seconds` metadata field and the record has
+    /// outlived it.
+    Expired {
+        /// Record identifier.
+        id: Uuid,
+        /// How far past the TTL deadline the record is.
+        ttl_exceeded_by: Duration,
+    },
+
+    /// The record has `"quarantined": true` in its metadata.
+    Quarantined {
+        /// Record identifier.
+        id: Uuid,
+        /// Reason, extracted from `metadata["quarantine_reason"]` if present.
+        reason: String,
+    },
+
+    /// No record with the given id exists in the store.
+    NotFound(Uuid),
+}
+
+// ─── Pipeline ────────────────────────────────────────────────────────────────
+
+/// Verification pipeline wrapping a [`CanonicalStore`].
+pub struct VerificationPipeline {
+    store: CanonicalStore,
+}
+
+impl VerificationPipeline {
+    /// Create a new pipeline backed by `store`.
+    pub fn new(store: CanonicalStore) -> Self {
+        Self { store }
+    }
+
+    /// Access the underlying canonical store.
+    pub fn store(&self) -> &CanonicalStore {
+        &self.store
+    }
+
+    // ── Single Verification ───────────────────────────────────────────────
+
+    /// Verify a single record identified by `id`.
+    ///
+    /// Steps:
+    /// 1. Fetch — [`VerificationResult::NotFound`] if absent.
+    /// 2. Hash check — [`VerificationResult::IntegrityFailed`] on mismatch.
+    /// 3. TTL check — [`VerificationResult::Expired`] if past `metadata["ttl_seconds"]`.
+    /// 4. Quarantine check — [`VerificationResult::Quarantined`] if
+    ///    `metadata["quarantined"] == true`.
+    /// 5. Otherwise [`VerificationResult::Verified`].
+    pub fn verify(&self, id: &Uuid) -> Result<VerificationResult> {
+        // Step 1: Fetch.
+        let record = match self.store.get(id)? {
+            None => return Ok(VerificationResult::NotFound(*id)),
+            Some(r) => r,
+        };
+
+        // Step 2: Hash check.
+        let actual_hash = compute_sha256(&record.content);
+        if actual_hash != record.content_hash {
+            return Ok(VerificationResult::IntegrityFailed {
+                id: *id,
+                expected_hash: record.content_hash.clone(),
+                actual_hash,
+            });
+        }
+
+        // Step 3: TTL check.
+        if let Some(ttl_val) = record.metadata.get("ttl_seconds")
+            && let Some(ttl_secs) = ttl_val.as_i64()
+        {
+            let deadline = record.created_at + Duration::seconds(ttl_secs);
+            let now = Utc::now();
+            if now > deadline {
+                let exceeded_by = now - deadline;
+                return Ok(VerificationResult::Expired {
+                    id: *id,
+                    ttl_exceeded_by: exceeded_by,
+                });
+            }
+        }
+
+        // Step 4: Quarantine check.
+        if record
+            .metadata
+            .get("quarantined")
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false)
+        {
+            let reason = record
+                .metadata
+                .get("quarantine_reason")
+                .and_then(|v| v.as_str())
+                .unwrap_or("unknown")
+                .to_string();
+            return Ok(VerificationResult::Quarantined { id: *id, reason });
+        }
+
+        Ok(VerificationResult::Verified(record))
+    }
+
+    // ── Batch Verification ────────────────────────────────────────────────
+
+    /// Verify a batch of records; each id is verified independently.
+    pub fn verify_batch(&self, ids: &[Uuid]) -> Result<Vec<VerificationResult>> {
+        ids.iter().map(|id| self.verify(id)).collect()
+    }
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clawpowers_canonical::{CanonicalRecord, CanonicalStore};
+    use serde_json::json;
+
+    fn make_pipeline() -> VerificationPipeline {
+        let store = CanonicalStore::in_memory().expect("in-memory store");
+        VerificationPipeline::new(store)
+    }
+
+    fn insert(
+        pipeline: &VerificationPipeline,
+        namespace: &str,
+        content: &str,
+        metadata: serde_json::Value,
+    ) -> Uuid {
+        let rec = CanonicalRecord::new(namespace, content, None, metadata, "test");
+        let id = rec.id;
+        pipeline.store().insert(&rec).expect("insert");
+        id
+    }
+
+    // ── Verified ─────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_verify_valid_record() {
+        let p = make_pipeline();
+        let id = insert(&p, "ns", "hello world", json!({}));
+        match p.verify(&id).expect("verify") {
+            VerificationResult::Verified(r) => assert_eq!(r.id, id),
+            other => panic!("expected Verified, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_verify_correct_hash_is_verified() {
+        let p = make_pipeline();
+        let id = insert(&p, "ns", "content for integrity check", json!({}));
+        assert!(matches!(
+            p.verify(&id).expect("verify"),
+            VerificationResult::Verified(_)
+        ));
+    }
+
+    // ── Not Found ─────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_verify_not_found() {
+        let p = make_pipeline();
+        let missing = Uuid::new_v4();
+        match p.verify(&missing).expect("verify") {
+            VerificationResult::NotFound(id) => assert_eq!(id, missing),
+            other => panic!("expected NotFound, got {other:?}"),
+        }
+    }
+
+    // ── Integrity (via hash comparison) ───────────────────────────────────
+
+    #[test]
+    fn test_verify_integrity_passes_for_fresh_record() {
+        let p = make_pipeline();
+        let id = insert(&p, "ns", "fresh record content", json!({}));
+        // Freshly inserted record should always pass hash check.
+        assert!(matches!(
+            p.verify(&id).expect("v"),
+            VerificationResult::Verified(_)
+        ));
+    }
+
+    #[test]
+    fn test_integrity_check_uses_sha256() {
+        let content = "check sha256 content";
+        let expected_hash = compute_sha256(content);
+        let p = make_pipeline();
+        let rec = CanonicalRecord::new("ns", content, None, json!({}), "test");
+        assert_eq!(rec.content_hash, expected_hash);
+        let id = p.store().insert(&rec).expect("insert");
+        assert!(matches!(
+            p.verify(&id).expect("v"),
+            VerificationResult::Verified(_)
+        ));
+    }
+
+    // ── TTL ───────────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_verify_expired_ttl() {
+        let p = make_pipeline();
+        let id = insert(&p, "ns", "old content", json!({"ttl_seconds": -1}));
+        match p.verify(&id).expect("verify") {
+            VerificationResult::Expired { id: eid, .. } => assert_eq!(eid, id),
+            other => panic!("expected Expired, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_verify_future_ttl_is_valid() {
+        let p = make_pipeline();
+        let id = insert(&p, "ns", "fresh content", json!({"ttl_seconds": 3600}));
+        assert!(matches!(
+            p.verify(&id).expect("v"),
+            VerificationResult::Verified(_)
+        ));
+    }
+
+    #[test]
+    fn test_no_ttl_field_is_valid() {
+        let p = make_pipeline();
+        let id = insert(&p, "ns", "no ttl here", json!({"source": "test"}));
+        assert!(matches!(
+            p.verify(&id).expect("v"),
+            VerificationResult::Verified(_)
+        ));
+    }
+
+    // ── Quarantine ────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_verify_quarantined_with_reason() {
+        let p = make_pipeline();
+        let id = insert(
+            &p,
+            "ns",
+            "suspicious content",
+            json!({"quarantined": true, "quarantine_reason": "policy violation"}),
+        );
+        match p.verify(&id).expect("verify") {
+            VerificationResult::Quarantined { id: qid, reason } => {
+                assert_eq!(qid, id);
+                assert_eq!(reason, "policy violation");
+            }
+            other => panic!("expected Quarantined, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_verify_quarantined_default_reason() {
+        let p = make_pipeline();
+        let id = insert(&p, "ns", "another bad record", json!({"quarantined": true}));
+        match p.verify(&id).expect("verify") {
+            VerificationResult::Quarantined { reason, .. } => assert_eq!(reason, "unknown"),
+            other => panic!("expected Quarantined, got {other:?}"),
+        }
+    }
+
+    // ── Batch ─────────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_verify_batch_mixed_results() {
+        let p = make_pipeline();
+        let valid_id = insert(&p, "ns", "valid batch record", json!({}));
+        let expired_id = insert(&p, "ns", "expired batch", json!({"ttl_seconds": -1}));
+        let missing_id = Uuid::new_v4();
+
+        let results = p
+            .verify_batch(&[valid_id, expired_id, missing_id])
+            .expect("batch");
+        assert_eq!(results.len(), 3);
+        assert!(matches!(results[0], VerificationResult::Verified(_)));
+        assert!(matches!(results[1], VerificationResult::Expired { .. }));
+        assert!(matches!(results[2], VerificationResult::NotFound(_)));
+    }
+
+    #[test]
+    fn test_verify_batch_empty() {
+        let p = make_pipeline();
+        let results = p.verify_batch(&[]).expect("batch");
+        assert!(results.is_empty());
+    }
+
+    #[test]
+    fn test_verify_batch_all_not_found() {
+        let p = make_pipeline();
+        let ids = vec![Uuid::new_v4(), Uuid::new_v4()];
+        let results = p.verify_batch(&ids).expect("batch");
+        assert_eq!(results.len(), 2);
+        for r in results {
+            assert!(matches!(r, VerificationResult::NotFound(_)));
+        }
+    }
+}

package/native/crates/wallet/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "clawpowers-wallet"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+alloy-signer = { workspace = true }
+alloy-signer-local = { workspace = true }
+alloy-primitives = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+zeroize = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+uuid = { workspace = true }
+rand = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true }

package/native/crates/wallet/src/lib.rs

@@ -0,0 +1,261 @@
+//! Key management for the ClawPowers agent wallet system.
+//!
+//! Provides [`AgentWallet`] — a thin wrapper around an `alloy-signer-local`
+//! [`PrivateKeySigner`] that adds identity metadata and guarantees private-key
+//! scrubbing on drop via [`Zeroize`].
+
+use alloy_primitives::{Address, Signature};
+use alloy_signer::SignerSync;
+use alloy_signer_local::PrivateKeySigner;
+use std::time::{SystemTime, UNIX_EPOCH};
+use thiserror::Error;
+use uuid::Uuid;
+use zeroize::Zeroize;
+
+// ── WalletError ───────────────────────────────────────────────────────────────
+
+/// Errors produced by wallet operations.
+#[derive(Debug, Error)]
+pub enum WalletError {
+    /// Failed to parse or import a private key.
+    #[error("Invalid private key: {0}")]
+    InvalidPrivateKey(String),
+    /// Signing operation failed.
+    #[error("Signing failed: {0}")]
+    SigningFailed(String),
+}
+
+// ── AgentWallet ───────────────────────────────────────────────────────────────
+
+/// An agent-controlled Ethereum wallet.
+///
+/// Wraps a [`PrivateKeySigner`] together with a unique wallet ID and creation
+/// timestamp.  On drop the inner signing key is zeroed in memory via the
+/// `ZeroizeOnDrop` impl already present on `k256::ecdsa::SigningKey`.
+///
+/// # Example
+/// ```
+/// use clawpowers_wallet::AgentWallet;
+/// let wallet = AgentWallet::generate();
+/// println!("address: {}", wallet.address());
+/// ```
+pub struct AgentWallet {
+    signer: PrivateKeySigner,
+    /// Unique, stable identifier for this wallet instance.
+    pub wallet_id: Uuid,
+    /// Unix timestamp (seconds since epoch) when this wallet was created.
+    pub created_at_secs: u64,
+    /// Holds a zeroed copy of the raw private key bytes for the explicit
+    /// `Zeroize` impl below.  Cleared on every call to `zeroize()`.
+    key_bytes: [u8; 32],
+}
+
+impl std::fmt::Debug for AgentWallet {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("AgentWallet")
+            .field("wallet_id", &self.wallet_id)
+            .field("created_at_secs", &self.created_at_secs)
+            .field("address", &self.signer.address())
+            .finish_non_exhaustive()
+    }
+}
+
+impl AgentWallet {
+    /// Generates a brand-new random keypair.
+    pub fn generate() -> Self {
+        let signer = PrivateKeySigner::random();
+        let key_bytes = signer.credential().to_bytes().into();
+        Self {
+            signer,
+            wallet_id: Uuid::new_v4(),
+            created_at_secs: Self::now_secs(),
+            key_bytes,
+        }
+    }
+
+    /// Imports an existing private key from a hex string (with or without `0x`
+    /// prefix).
+    ///
+    /// # Errors
+    /// Returns [`WalletError::InvalidPrivateKey`] if the hex is invalid or does
+    /// not represent a valid secp256k1 scalar.
+    pub fn from_private_key(hex: &str) -> Result<Self, WalletError> {
+        let trimmed = hex.trim().strip_prefix("0x").unwrap_or(hex.trim());
+        let signer = trimmed
+            .parse::<PrivateKeySigner>()
+            .map_err(|e| WalletError::InvalidPrivateKey(e.to_string()))?;
+        let key_bytes = signer.credential().to_bytes().into();
+        Ok(Self {
+            signer,
+            wallet_id: Uuid::new_v4(),
+            created_at_secs: Self::now_secs(),
+            key_bytes,
+        })
+    }
+
+    fn now_secs() -> u64 {
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs()
+    }
+
+    /// Returns the Ethereum address corresponding to this wallet's public key.
+    pub fn address(&self) -> Address {
+        self.signer.address()
+    }
+
+    /// Signs an arbitrary byte payload using EIP-191 message hashing.
+    ///
+    /// # Errors
+    /// Returns [`WalletError::SigningFailed`] on cryptographic errors.
+    pub fn sign_message(&self, msg: &[u8]) -> Result<Signature, WalletError> {
+        self.signer
+            .sign_message_sync(msg)
+            .map_err(|e| WalletError::SigningFailed(e.to_string()))
+    }
+}
+
+impl Zeroize for AgentWallet {
+    /// Zeroes the cached private-key bytes held in this struct.
+    ///
+    /// The inner `PrivateKeySigner` (and thereby the `k256::ecdsa::SigningKey`)
+    /// automatically zeroes its own memory on drop via `ZeroizeOnDrop`.
+    fn zeroize(&mut self) {
+        self.key_bytes.zeroize();
+    }
+}
+
+impl Drop for AgentWallet {
+    fn drop(&mut self) {
+        self.zeroize();
+    }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use alloy_primitives::eip191_hash_message;
+
+    /// Helper: known test private key from Ethereum test vectors.
+    const TEST_PRIVKEY: &str = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+
+    #[test]
+    fn test_generate_produces_valid_address() {
+        let w = AgentWallet::generate();
+        // Address must not be the zero address.
+        assert_ne!(w.address(), Address::ZERO);
+    }
+
+    #[test]
+    fn test_generate_unique_ids() {
+        let w1 = AgentWallet::generate();
+        let w2 = AgentWallet::generate();
+        assert_ne!(w1.wallet_id, w2.wallet_id);
+    }
+
+    #[test]
+    fn test_generate_different_keys() {
+        let w1 = AgentWallet::generate();
+        let w2 = AgentWallet::generate();
+        assert_ne!(w1.address(), w2.address());
+    }
+
+    #[test]
+    fn test_from_private_key_valid() {
+        let w = AgentWallet::from_private_key(TEST_PRIVKEY).expect("valid key");
+        // Known address for the Hardhat account #0 key.
+        let expected: Address = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+            .parse()
+            .expect("parse address");
+        assert_eq!(w.address(), expected);
+    }
+
+    #[test]
+    fn test_from_private_key_without_0x_prefix() {
+        let hex_no_prefix = TEST_PRIVKEY.trim_start_matches("0x");
+        let w = AgentWallet::from_private_key(hex_no_prefix).expect("should accept no-0x form");
+        let expected: Address = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+            .parse()
+            .expect("parse address");
+        assert_eq!(w.address(), expected);
+    }
+
+    #[test]
+    fn test_from_private_key_invalid_returns_err() {
+        let result = AgentWallet::from_private_key("not_a_hex_key");
+        assert!(result.is_err());
+        assert!(matches!(result, Err(WalletError::InvalidPrivateKey(_))));
+    }
+
+    #[test]
+    fn test_sign_message_produces_signature() {
+        let w = AgentWallet::from_private_key(TEST_PRIVKEY).expect("valid key");
+        let msg = b"hello clawpowers";
+        let sig = w.sign_message(msg).expect("sign should succeed");
+        // Verify the signature recovers to the correct address.
+        let recovered = sig
+            .recover_address_from_prehash(&eip191_hash_message(msg))
+            .expect("recover address");
+        assert_eq!(recovered, w.address());
+    }
+
+    #[test]
+    fn test_sign_message_deterministic_for_same_key() {
+        let w1 = AgentWallet::from_private_key(TEST_PRIVKEY).expect("valid key");
+        let w2 = AgentWallet::from_private_key(TEST_PRIVKEY).expect("valid key");
+        let msg = b"determinism test";
+        let s1 = w1.sign_message(msg).expect("sign 1");
+        let s2 = w2.sign_message(msg).expect("sign 2");
+        assert_eq!(s1, s2);
+    }
+
+    #[test]
+    fn test_zeroize_clears_key_bytes() {
+        let mut w = AgentWallet::from_private_key(TEST_PRIVKEY).expect("valid key");
+        // Before zeroize, key_bytes should be non-zero.
+        let nonzero_before = w.key_bytes.iter().any(|&b| b != 0);
+        assert!(
+            nonzero_before,
+            "key_bytes should be non-zero before zeroize"
+        );
+
+        w.zeroize();
+        let all_zero = w.key_bytes.iter().all(|&b| b == 0);
+        assert!(
+            all_zero,
+            "key_bytes should be zeroed after explicit zeroize"
+        );
+    }
+
+    #[test]
+    fn test_debug_does_not_expose_private_key() {
+        let w = AgentWallet::from_private_key(TEST_PRIVKEY).expect("valid key");
+        let debug_str = format!("{w:?}");
+        // Make sure the raw private key hex is not in the debug output.
+        assert!(
+            !debug_str.contains("ac0974"),
+            "private key bytes must not appear in Debug output: {debug_str}"
+        );
+    }
+
+    #[test]
+    fn test_wallet_created_at_is_recent() {
+        let before = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs();
+        let w = AgentWallet::generate();
+        let after = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs();
+        assert!(
+            w.created_at_secs >= before && w.created_at_secs <= after,
+            "created_at_secs={} not in [{before}, {after}]",
+            w.created_at_secs
+        );
+    }
+}

package/native/crates/x402/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "clawpowers-x402"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[features]
+default = ["native"]
+native = []
+wasm = []
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+alloy-primitives = { workspace = true }
+alloy-signer = { workspace = true }
+clawpowers-fee = { path = "../fee" }
+clawpowers-tokens = { path = "../tokens" }
+
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+reqwest = { workspace = true }
+tokio = { workspace = true }
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+reqwest = { version = "0.12", features = ["json"] }
+
+[dev-dependencies]
+tokio = { workspace = true }