Encrypted, ephemeral, private memos on atproto
graham.systems
1# Cistern
2
3Cistern is a private, end-to-end encrypted quick-capture system built on AT Protocol. Items are encrypted using post-quantum cryptography and stored temporarily in your Personal Data Server (PDS), then automatically retrieved and deleted after consumption.
4
5The system bridges the gap between where ideas are captured and where they are stored long-term. Create an encrypted item on your phone, and it automatically appears in your desktop application, decrypted and ready to use.
6
7## Architecture
8
9Cistern is a Deno monorepo consisting of five packages:
10
11### `@cistern/crypto`
12Core cryptographic operations using post-quantum algorithms. Implements X-Wing key encapsulation with XChaCha20-Poly1305 authenticated encryption and SHA3-512 integrity verification. Handles keypair generation, encryption, and decryption.
13
14### `@cistern/lexicon`
15AT Protocol schema definitions for Cistern record types. Defines `app.cistern.lexicon.pubkey` (public key records) and `app.cistern.lexicon.item` (encrypted item records). Includes code generation from JSON schemas.
16
17### `@cistern/shared`
18Common utilities and authentication logic. Handles DID resolution via Slingshot service and creates authenticated RPC clients using app passwords.
19
20### `@cistern/producer`
21Creates and encrypts items for storage. Manages public key selection, encrypts plaintext content, and uploads encrypted items to the PDS as AT Protocol records.
22
23### `@cistern/consumer`
24Retrieves, decrypts, and deletes items. Generates keypairs, manages private keys locally, retrieves items via polling or real-time streaming (Jetstream), and handles item deletion after consumption.
25
26## Security Model
27
28Private keys never leave the consumer device. Public keys are stored in the PDS as records, while private keys remain off-protocol. Only the holder of the matching private key can decrypt items encrypted with the corresponding public key.
29
30## Testing
31
32Run all unit tests:
33```bash
34deno test --allow-env
35```
36
37Run end-to-end tests (requires AT Protocol credentials):
38```bash
39CISTERN_HANDLE="your.bsky.social" \
40CISTERN_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx" \
41deno test --allow-env --allow-net e2e.test.ts
42```