scp_platform/lib.rs
1//! Platform abstraction layer for SCP.
2//!
3//! This crate defines the four platform abstraction traits that every SCP
4//! component depends on for device-specific capabilities:
5//!
6//! - [`KeyCustody`] — Cryptographic key management (generation, signing, ECDH,
7//! pseudonym derivation). Production: Secure Enclave (iOS), Android Keystore.
8//! - [`DeviceAttestation`] — Device attestation tokens (App Attest, Play Integrity).
9//! - [`Push`] — Push notification registration and handling (APNs, FCM).
10//! - [`Storage`] — Persistent key-value byte storage (Keychain, encrypted `SQLite`).
11//!
12//! All traits are `Send + Sync` with async methods, designed for injection
13//! through initializers. Production implementations use hardware security;
14//! testing implementations (in-memory, see ADR-006) provide identical API
15//! surfaces with no external dependencies.
16//!
17//! # Architecture
18//!
19//! See ADR-006 ("In-Memory Platform Adapter") in `.docs/adrs/phase-1.md` for
20//! the full design rationale. The trait definitions in this crate are the
21//! authoritative source for all platform adapter contracts.
22//!
23//! # Usage
24//!
25//! Components accept platform traits as generic parameters or trait objects:
26//!
27//! ```rust,ignore
28//! async fn create_identity<K: scp_platform::KeyCustody>(custody: &K) {
29//! let handle = custody.generate_keypair(scp_platform::KeyType::Ed25519).await?;
30//! // ...
31//! }
32//! ```
33
34#![forbid(unsafe_code)]
35
36pub mod encrypted;
37#[cfg(feature = "encrypting")]
38pub mod encrypting_adapter;
39pub mod error;
40// In-memory platform adapters — gated by the `testing` feature, NOT by
41// `software_platform`. This ensures production mobile builds can enable
42// `software_platform` (for crypto primitives) without compiling in insecure
43// in-memory key storage. See GitHub issue #88 and ADR-006.
44#[cfg(feature = "testing")]
45pub mod testing;
46// `software` is an alias for `testing` that matches the historical path. New
47// code should prefer `scp_platform::testing::*`; `software::*` paths remain
48// valid for backwards compatibility.
49#[cfg(feature = "testing")]
50pub use testing as software;
51#[cfg(target_os = "android")]
52pub mod android;
53#[cfg(feature = "apple")]
54pub mod apple;
55#[cfg(feature = "file")]
56pub mod file;
57#[cfg(feature = "filesystem")]
58pub mod filesystem;
59#[cfg(feature = "sqlite")]
60pub mod sqlite;
61#[cfg(feature = "sync")]
62pub mod syncable;
63pub mod traits;
64
65// Re-export all public types for ergonomic access.
66pub use encrypted::EncryptedStorage;
67pub use error::PlatformError;
68pub use traits::{
69 CustodyType, DeviceAttestation, DeviceAttestationToken, KeyCustody, KeyHandle, KeyType,
70 PseudonymKeypair, PublicKey, Push, PushToken, SharedSecret, Signature, Storage, WakeSignal,
71};