claw_crypto/lib.rs
1//! Cryptographic helpers for Claw VCS capsules and agent identities.
2//!
3//! This crate provides Ed25519 signing, capsule signature verification,
4//! XChaCha20-Poly1305 private-field encryption, and key derivation helpers.
5//! It does not decide policy trust; callers must still decide which keys and
6//! evidence are acceptable.
7//!
8//! # Example
9//!
10//! ```rust
11//! use claw_core::hash::content_hash;
12//! use claw_core::object::TypeTag;
13//! use claw_core::types::{CapsulePublic, Evidence};
14//! use claw_crypto::capsule::{build_capsule, verify_capsule};
15//! use claw_crypto::keypair::KeyPair;
16//!
17//! let keypair = KeyPair::from_bytes(&[7; 32])?;
18//! let revision_id = content_hash(TypeTag::Revision, b"revision payload");
19//! let encryption_key = [42; 32];
20//!
21//! let public_fields = CapsulePublic {
22//! agent_id: "agent-1".to_string(),
23//! agent_version: Some("1.0.0".to_string()),
24//! toolchain_digest: None,
25//! env_fingerprint: None,
26//! evidence: vec![Evidence {
27//! name: "unit-tests".to_string(),
28//! status: "pass".to_string(),
29//! duration_ms: 120,
30//! artifact_refs: vec![],
31//! summary: None,
32//! revision_id: Some(revision_id),
33//! command: Some("cargo test".to_string()),
34//! exit_code: Some(0),
35//! started_at_ms: Some(1_000),
36//! ended_at_ms: Some(1_100),
37//! environment_digest: Some("sha256:env".to_string()),
38//! runner_identity: Some("runner-a".to_string()),
39//! log_digest: Some("sha256:log".to_string()),
40//! artifact_digest: None,
41//! expires_at_ms: Some(2_000),
42//! trust_domain: Some("ci".to_string()),
43//! signature: None,
44//! }],
45//! };
46//!
47//! let capsule = build_capsule(
48//! &revision_id,
49//! public_fields,
50//! Some(b"private build metadata"),
51//! Some(&encryption_key),
52//! &keypair,
53//! )?;
54//!
55//! assert!(verify_capsule(&capsule, &keypair.public_key_bytes())?);
56//! # Ok::<(), Box<dyn std::error::Error>>(())
57//! ```
58//!
59#![deny(missing_docs)]
60
61/// Capsule construction, signing, and signature verification.
62pub mod capsule;
63/// Symmetric private-field encryption helpers.
64pub mod encrypt;
65/// Error types returned by crypto operations.
66pub mod error;
67/// BLAKE3-based key derivation helpers.
68pub mod kdf;
69/// Ed25519 keypair creation and serialization.
70pub mod keypair;
71/// Recipient envelope encryption helpers for private capsule fields.
72pub mod recipient;
73/// Ed25519 signing helpers.
74pub mod sign;
75/// Ed25519 signature verification helpers.
76pub mod verify;
77
78pub use error::CryptoError;