incokit_e2ee/lib.rs
1//! # incokit-e2ee
2//!
3//! The end-to-end-encryption core extracted verbatim from the
4//! [Incokit](https://incokit.com) desktop app. This is the exact code that
5//! seals your profiles, proxies, and cookies before they ever leave your
6//! machine — published so you don't have to take our word for it.
7//!
8//! ## What it does
9//!
10//! - **Master key** — a random 256-bit key, never sent to any server. It is
11//! wrapped by a PIN-derived key and (separately) a recovery key, both via
12//! Argon2id. Only the wrapped blobs are stored remotely.
13//! - **Symmetric encryption** — AES-256-GCM with a fresh random 96-bit nonce
14//! per message ([`encryption`]).
15//! - **Per-entity keys** — every profile/proxy/row gets its own key via
16//! HKDF-SHA256 from the master key, scoped by [`namespace::KeyNamespace`].
17//! A key for one entity cannot decrypt another's blob.
18//! - **Sharing** — profile keys are sealed for another user with X25519
19//! ECDH + HKDF + AES-256-GCM ([`keys`]). The server only ever sees
20//! ciphertext and public keys.
21//! - **Wire format** — `"e2ee:" + base64(nonce || ciphertext || tag)`
22//! ([`sealed`]), self-describing and forward-compatible.
23//! - **Key hygiene** — [`session::SessionKey`] zeroizes on drop and refuses
24//! to be cloned, debugged, or serialized.
25//!
26//! ## Threat model (read this)
27//!
28//! We sell antidetect software, not snake oil, so here is the honest version.
29//!
30//! **What this protects:** the confidentiality and integrity of profile data
31//! at rest on the server and in transit. A server operator, a database leak,
32//! or a network observer sees only AES-256-GCM ciphertext and public keys.
33//! Tampering is detected (the GCM auth tag fails). A key derived for one
34//! entity, user, or namespace cannot open another's data.
35//!
36//! **What it does NOT protect, and we won't pretend otherwise:**
37//!
38//! - **A weak PIN.** The PIN wraps the master key through Argon2id, but a
39//! 6-digit PIN is a 10⁶ space. The [`oprf`] module is a hash-based blind,
40//! **not** a true OPRF — see its module docs for the exact limitation and
41//! why we rely on server-side rate limiting (and plan a ristretto255 VOPRF
42//! / OPAQUE upgrade). If your threat model includes an attacker who can
43//! brute-force the PIN offline against a stolen wrapped blob, raise the PIN
44//! entropy.
45//! - **A compromised endpoint.** If malware owns the machine while the app is
46//! unlocked, the master key is in memory. E2EE is not endpoint security.
47//! - **Metadata.** Row existence, sizes, and timing are not hidden.
48//!
49//! ## Status
50//!
51//! Primitives are standard and come from audited crates (RustCrypto,
52//! `x25519-dalek`, `argon2`). This crate has **not** had an independent
53//! third-party audit. Read the code, run `cargo test`, and judge for
54//! yourself — that's the whole point of publishing it.
55//!
56//! ## Crate layout
57//!
58//! | Module | Responsibility |
59//! |--------|----------------|
60//! | [`encryption`] | AES-256-GCM, Argon2id key derivation, master-key wrap/unwrap |
61//! | [`keys`] | X25519 sharing, profile-key wrap, recovery-key format |
62//! | [`namespace`] | Per-entity HKDF key derivation |
63//! | [`sealed`] | `"e2ee:"` wire format (bytes/string/JSON) |
64//! | [`entity`] | [`EncryptedEntity`] trait + per-entity seal/unseal helpers |
65//! | [`session`] | [`SessionKey`] — zeroizing master-key handle |
66//! | [`oprf`] | PIN blind/finalize (hash-based; see limitations) |
67//! | [`error`] | [`CryptoError`] / [`CryptoResult`] |
68//! | [`keychain`] | Optional OS-keychain storage (feature `keychain`) |
69
70#![forbid(unsafe_code)]
71
72pub mod encryption;
73pub mod entity;
74pub mod error;
75pub mod keys;
76pub mod namespace;
77pub mod oprf;
78pub mod sealed;
79pub mod session;
80
81#[cfg(feature = "keychain")]
82pub mod keychain;
83
84pub use entity::EncryptedEntity;
85pub use error::{CryptoError, CryptoResult};
86pub use namespace::KeyNamespace;
87pub use session::SessionKey;