synheart_sensor_agent/
lib.rs

1//! # Synheart Sensor Agent
2//!
3//! **Privacy-first PC background sensor for behavioral research.**
4//!
5//! This library captures keyboard and mouse interaction timing for behavioral
6//! research with strong privacy guarantees. It is a **pure collector** — raw
7//! events are emitted via a channel for downstream processing by
8//! `synheart-session-runtime` via `synheart-core-rust`.
9//!
10//! # Privacy Guarantees
11//!
12//! - **No key content** — only timing and category (typing vs. navigation)
13//! - **No coordinates** — only mouse movement magnitude/speed
14//! - **No raw storage** — events are emitted and discarded immediately
15//! - **Transparency** — all collection is logged and auditable via [`TransparencyLog`]
16//!
17//! # Architecture
18//!
19//! ```text
20//! ┌─────────────────────────────────────────────────────────────┐
21//! │                    Synheart Sensor Agent                     │
22//! ├─────────────────────────────────────────────────────────────┤
23//! │  ┌─────────────┐                     ┌─────────────┐       │
24//! │  │  Collector  │────────────────────▶│ Raw Events  │       │
25//! │  │ (platform)  │                     │  (channel)  │       │
26//! │  └─────────────┘                     └─────────────┘       │
27//! │         │                                                  │
28//! │         ▼                                                  │
29//! │  ┌─────────────┐                                           │
30//! │  │Transparency │                                           │
31//! │  │    Log      │                                           │
32//! │  └─────────────┘                                           │
33//! └─────────────────────────────────────────────────────────────┘
34//!    Pure sensor — windowing, features, and sessions handled by
35//!    synheart-session-runtime via synheart-core-rust orchestration
36//! ```
37//!
38//! # Quick Start
39//!
40//! ```no_run
41//! use synheart_sensor_agent::{collector, transparency};
42//!
43//! // Create a collector (requires Input Monitoring permission on macOS)
44//! let config = collector::CollectorConfig::default();
45//! let mut collector = collector::Collector::new(config);
46//!
47//! // Start collection
48//! collector.start().expect("Failed to start collector");
49//!
50//! // Events can be received from collector.receiver()
51//! ```
52//!
53//! # Platform Support
54//!
55//! The [`collector`] module adapts to the build target:
56//!
57//! - **macOS** — CoreGraphics event tap + NSWorkspace for foreground app detection
58//! - **Windows** — Windows Hooks API for keyboard/mouse + foreground window detection
59//! - **Other** — No-op collector (compiles but does not capture events)
60
61#![cfg_attr(docsrs, feature(doc_cfg))]
62
63/// Platform-specific event collection (keyboard, mouse, shortcuts).
64pub mod collector;
65
66/// Agent configuration and persistence.
67pub mod config;
68
69/// Transparency logging for auditable data collection.
70pub mod transparency;
71
72/// HTTP server for receiving behavioral data from the Chrome extension.
73#[cfg(feature = "server")]
74pub mod server;
75
76// Re-export key types at crate root for convenience
77pub use collector::{Collector, CollectorConfig, CollectorError, SensorEvent};
78pub use config::{Config, SourceConfig};
79pub use transparency::{SharedTransparencyLog, TransparencyLog, TransparencyStats};
80
81// Server re-exports (when enabled)
82#[cfg(feature = "server")]
83pub use server::{run as run_server, ServerConfig};
84
85/// Library version string sourced from `Cargo.toml`.
86pub const VERSION: &str = env!("CARGO_PKG_VERSION");
87
88/// Privacy declaration that can be displayed to users.
89pub const PRIVACY_DECLARATION: &str = r#"
90╔══════════════════════════════════════════════════════════════════╗
91║           SYNHEART SENSOR AGENT - PRIVACY DECLARATION            ║
92╠══════════════════════════════════════════════════════════════════╣
93║                                                                  ║
94║  This agent captures behavioral timing data for research.        ║
95║                                                                  ║
96║  WHAT WE CAPTURE:                                                ║
97║    - When keys are pressed (timing only)                         ║
98║    - Key categories (backspace, enter, etc. - NOT which letter)  ║
99║    - Common shortcut patterns (copy, paste, etc. - timing only)  ║
100║    - How fast the mouse moves (speed only)                       ║
101║    - When clicks and scrolls occur (timing only)                 ║
102║    - Which app is in the foreground (identifier only, no titles) ║
103║                                                                  ║
104║  WHAT WE NEVER CAPTURE:                                          ║
105║    - Which keys you press (no passwords, messages, etc.)         ║
106║    - Where your cursor is (no screen position tracking)          ║
107║    - Window titles, file names, or document content              ║
108║    - Any screen content                                          ║
109║                                                                  ║
110║  Raw events are emitted to the orchestration layer and           ║
111║  discarded immediately. No raw data is stored locally.           ║
112║                                                                  ║
113║  You can view collection statistics anytime with:                ║
114║    synheart-sensor status                                        ║
115║                                                                  ║
116╚══════════════════════════════════════════════════════════════════╝
117"#;
118
119#[cfg(test)]
120mod tests {
121    use super::*;
122
123    #[test]
124    fn test_privacy_declaration_contents() {
125        assert!(PRIVACY_DECLARATION.contains("PRIVACY"));
126        assert!(PRIVACY_DECLARATION.contains("NEVER CAPTURE"));
127        assert!(PRIVACY_DECLARATION.contains("keys you press"));
128    }
129}
synheart_sensor_agent/lib.rs

synheart_sensor_agent/
lib.rs
