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