Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

2.7 KB
Raw Blame
#![deny(missing_docs)]
//! The whatsmeow device store of a linked WhatsApp account, in Postgres.
//!
//! [`PgWhatsAppStore`] implements every store trait of `whatsmeow::store` for
//! one account: Signal identities, sessions, prekeys and sender keys, app
//! state keys and versions, contacts, chat settings, message secrets, privacy
//! tokens, event buffers and LID mappings, plus the device's own keys
//! ([`whatsmeow::store::DeviceContainer`]). [`PgWhatsAppStore::load_device`]
//! hands out a [`whatsmeow::store::Device`] backed by it.
//!
//! # Threat model
//!
//! The store holds the keys of a person's WhatsApp account. With the noise
//! and identity keys and the sessions, anyone can impersonate the linked
//! device: read the person's new messages and send as them, until they unlink
//! it. So every value is encrypted at rest:
//!
//! - **Per-account data key** ([`cipher`]): AES-256-GCM, a fresh random nonce
//!   per write, and associated data binding each ciphertext to its account,
//!   store and key. A value copied to another row, store or account fails to
//!   decrypt.
//! - **Wrapped by KMS** ([`kms`]): the data key is generated by KMS once per
//!   account and stored only wrapped, under an encryption context naming the
//!   user and the account. A replica unwraps it once when it takes the
//!   account's lease and holds it in memory (zeroized on drop, never logged or
//!   serialized) until the store is dropped. A database dump alone decrypts
//!   nothing; every unwrap is an IAM-gated, CloudTrail-recorded KMS call.
//! - **Plaintext lookup keys**: Signal addresses, JIDs (which contain phone
//!   numbers), message IDs, prekey IDs, app state index MACs and timestamps
//!   stay plaintext so they can be indexed. Values (keys, sessions, sender
//!   keys, app state keys, versions and value MACs, names, settings, secrets,
//!   tokens, event plaintexts, and which LID belongs to which phone number)
//!   are all sealed.
//!
//! What this does not protect against: a process holding the lease has the
//! plaintext data key, and whatsmeow's [`whatsmeow::store::Device`] holds the
//! device's private keys in memory for the whole connection.
//!
//! # Fencing
//!
//! A store is opened for the lease epoch its caller holds. Every write checks
//! `whatsapp_linked_account.lease_epoch` in the same transaction and fails
//! with [`WhatsAppStoreError::Fenced`] (see [`is_fenced`] for whatsmeow's
//! errors) once another replica has taken the account over.
//!
//! Deleting the account or its device row deletes the keys; it does not
//! unlink the device at WhatsApp. A "disconnect" surface must log out first.

pub mod cipher;
mod error;
pub mod kms;
mod store;

pub use error::{WhatsAppStoreError, is_fenced};
pub use store::PgWhatsAppStore;