synheart_sensor_agent/
lib.rs

1//! Synheart Sensor Agent - Privacy-first behavioral sensor for research.
2//!
3//! This library provides tools for capturing keyboard and mouse interaction
4//! timing for behavioral research, with strong privacy guarantees.
5//!
6//! # Privacy Guarantees
7//!
8//! - **No key content**: We never capture which keys are pressed, only timing
9//! - **No coordinates**: We never capture cursor position, only movement magnitude
10//! - **No raw storage**: Raw events are not stored beyond the current window
11//! - **Transparency**: All collection is logged and auditable
12//!
13//! # Architecture
14//!
15//! ```text
16//! ┌─────────────────────────────────────────────────────────────┐
17//! │                    Synheart Sensor Agent                     │
18//! ├─────────────────────────────────────────────────────────────┤
19//! │  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐       │
20//! │  │  Collector  │──▶│  Windowing  │──▶│  Features   │       │
21//! │  │   (macOS)   │   │  (10s bins) │   │ (compute)   │       │
22//! │  └─────────────┘   └─────────────┘   └─────────────┘       │
23//! │         │                                    │              │
24//! │         ▼                                    ▼              │
25//! │  ┌─────────────┐                     ┌─────────────┐       │
26//! │  │Transparency │                     │    HSI      │       │
27//! │  │    Log      │                     │  Snapshot   │       │
28//! │  └─────────────┘                     └─────────────┘       │
29//! └─────────────────────────────────────────────────────────────┘
30//! ```
31//!
32//! # Example
33//!
34//! ```no_run
35//! use synheart_sensor_agent::{collector, core, transparency};
36//!
37//! // Create a collector (requires Input Monitoring permission)
38//! let config = collector::CollectorConfig::default();
39//! let mut collector = collector::Collector::new(config);
40//!
41//! // Start collection
42//! collector.start().expect("Failed to start collector");
43//!
44//! // Events can be received from collector.receiver()
45//! ```
46
47pub mod collector;
48pub mod config;
49pub mod core;
50pub mod transparency;
51
52#[cfg(feature = "flux")]
53pub mod flux;
54
55#[cfg(feature = "gateway")]
56pub mod gateway;
57
58#[cfg(feature = "server")]
59pub mod server;
60
61// Re-export key types at crate root for convenience
62pub use collector::{Collector, CollectorConfig, CollectorError, SensorEvent};
63pub use config::{Config, SourceConfig};
64pub use core::{compute_features, HsiBuilder, HsiSnapshot, WindowFeatures, WindowManager};
65pub use transparency::{SharedTransparencyLog, TransparencyLog, TransparencyStats};
66
67// Flux re-exports (when enabled)
68#[cfg(feature = "flux")]
69pub use flux::{EnrichedSnapshot, SensorFluxProcessor};
70
71// Gateway re-exports (when enabled)
72#[cfg(feature = "gateway")]
73pub use gateway::{
74    BlockingGatewayClient, GatewayClient, GatewayConfig, GatewayError, GatewayResponse,
75};
76
77// Server re-exports (when enabled)
78#[cfg(feature = "server")]
79pub use server::{run as run_server, ServerConfig};
80
81/// Library version.
82pub const VERSION: &str = env!("CARGO_PKG_VERSION");
83
84/// Privacy declaration that can be displayed to users.
85pub const PRIVACY_DECLARATION: &str = r#"
86╔══════════════════════════════════════════════════════════════════╗
87║           SYNHEART SENSOR AGENT - PRIVACY DECLARATION            ║
88╠══════════════════════════════════════════════════════════════════╣
89║                                                                  ║
90║  This agent captures behavioral timing data for research.        ║
91║                                                                  ║
92║  ✓ WHAT WE CAPTURE:                                              ║
93║    • When keys are pressed (timing only)                         ║
94║    • Key categories (backspace, enter, etc. - NOT which letter)  ║
95║    • Common shortcut patterns (copy, paste, etc. - timing only)  ║
96║    • How fast the mouse moves (speed only)                       ║
97║    • When clicks and scrolls occur (timing only)                 ║
98║    • Which app is in the foreground (identifier only, no titles) ║
99║                                                                  ║
100║  ✗ WHAT WE NEVER CAPTURE:                                        ║
101║    • Which keys you press (no passwords, messages, etc.)         ║
102║    • Where your cursor is (no screen position tracking)          ║
103║    • Window titles, file names, or document content              ║
104║    • Any screen content                                          ║
105║                                                                  ║
106║  All data is processed locally. Raw events are discarded         ║
107║  after feature extraction (every 10 seconds).                    ║
108║                                                                  ║
109║  You can view collection statistics anytime with:                ║
110║    synheart-sensor status                                        ║
111║                                                                  ║
112╚══════════════════════════════════════════════════════════════════╝
113"#;
114
115#[cfg(test)]
116mod tests {
117    use super::*;
118
119    #[test]
120    fn test_privacy_declaration_contents() {
121        assert!(PRIVACY_DECLARATION.contains("PRIVACY"));
122        assert!(PRIVACY_DECLARATION.contains("NEVER CAPTURE"));
123        assert!(PRIVACY_DECLARATION.contains("keys you press"));
124    }
125}
synheart_sensor_agent/lib.rs

synheart_sensor_agent/
lib.rs
