synheart-sensor-agent 0.4.0

Privacy-first PC background sensor for behavioral research
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! # Synheart Sensor Agent
//!
//! **Privacy-first PC background sensor for behavioral research.**
//!
//! This library captures keyboard and mouse interaction timing for behavioral
//! research with strong privacy guarantees. It is a **pure collector** — raw
//! events are emitted via a channel for downstream processing by
//! `synheart-session-runtime` via `synheart-core-rust`.
//!
//! # Privacy Guarantees
//!
//! - **No key content** — only timing and category (typing vs. navigation)
//! - **No coordinates** — only mouse movement magnitude/speed
//! - **No raw storage** — events are emitted and discarded immediately
//! - **Transparency** — all collection is logged and auditable via [`TransparencyLog`]
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │                    Synheart Sensor Agent                     │
//! ├─────────────────────────────────────────────────────────────┤
//! │  ┌─────────────┐                     ┌─────────────┐       │
//! │  │  Collector  │────────────────────▶│ Raw Events  │       │
//! │  │ (platform)  │                     │  (channel)  │       │
//! │  └─────────────┘                     └─────────────┘       │
//! │         │                                                  │
//! │         ▼                                                  │
//! │  ┌─────────────┐                                           │
//! │  │Transparency │                                           │
//! │  │    Log      │                                           │
//! │  └─────────────┘                                           │
//! └─────────────────────────────────────────────────────────────┘
//!    Pure sensor — windowing, features, and sessions handled by
//!    synheart-session-runtime via synheart-core-rust orchestration
//! ```
//!
//! # Quick Start
//!
//! ```no_run
//! use synheart_sensor_agent::{collector, transparency};
//!
//! // Create a collector (requires Input Monitoring permission on macOS)
//! let config = collector::CollectorConfig::default();
//! let mut collector = collector::Collector::new(config);
//!
//! // Start collection
//! collector.start().expect("Failed to start collector");
//!
//! // Events can be received from collector.receiver()
//! ```
//!
//! # Platform Support
//!
//! The [`collector`] module adapts to the build target:
//!
//! - **macOS** — CoreGraphics event tap + NSWorkspace for foreground app detection
//! - **Windows** — Windows Hooks API for keyboard/mouse + foreground window detection
//! - **Other** — No-op collector (compiles but does not capture events)

#![cfg_attr(docsrs, feature(doc_cfg))]

/// Platform-specific event collection (keyboard, mouse, shortcuts).
pub mod collector;

/// Agent configuration and persistence.
pub mod config;

/// Transparency logging for auditable data collection.
pub mod transparency;

/// HTTP server for receiving behavioral data from the Chrome extension.
#[cfg(feature = "server")]
pub mod server;

// Re-export key types at crate root for convenience
pub use collector::{Collector, CollectorConfig, CollectorError, SensorEvent};
pub use config::{Config, SourceConfig};
pub use transparency::{SharedTransparencyLog, TransparencyLog, TransparencyStats};

// Server re-exports (when enabled)
#[cfg(feature = "server")]
pub use server::{run as run_server, ServerConfig};

/// Library version string sourced from `Cargo.toml`.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Privacy declaration that can be displayed to users.
pub const PRIVACY_DECLARATION: &str = r#"
╔══════════════════════════════════════════════════════════════════╗
║           SYNHEART SENSOR AGENT - PRIVACY DECLARATION            ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  This agent captures behavioral timing data for research.        ║
║                                                                  ║
║  WHAT WE CAPTURE:                                                ║
║    - When keys are pressed (timing only)                         ║
║    - Key categories (backspace, enter, etc. - NOT which letter)  ║
║    - Common shortcut patterns (copy, paste, etc. - timing only)  ║
║    - How fast the mouse moves (speed only)                       ║
║    - When clicks and scrolls occur (timing only)                 ║
║    - Which app is in the foreground (identifier only, no titles) ║
║                                                                  ║
║  WHAT WE NEVER CAPTURE:                                          ║
║    - Which keys you press (no passwords, messages, etc.)         ║
║    - Where your cursor is (no screen position tracking)          ║
║    - Window titles, file names, or document content              ║
║    - Any screen content                                          ║
║                                                                  ║
║  Raw events are emitted to the orchestration layer and           ║
║  discarded immediately. No raw data is stored locally.           ║
║                                                                  ║
║  You can view collection statistics anytime with:                ║
║    synheart-sensor status                                        ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝
"#;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_privacy_declaration_contents() {
        assert!(PRIVACY_DECLARATION.contains("PRIVACY"));
        assert!(PRIVACY_DECLARATION.contains("NEVER CAPTURE"));
        assert!(PRIVACY_DECLARATION.contains("keys you press"));
    }
}