graham.systems
+39
-12
README.md
+39
-12
README.md
···
1
1
# Cistern
2
2
3
-
Cistern is an attempt at implementing a private, personal quick-capture system
4
-
on AT Protocol. Cistern "items" are encrypted, so that they are only readable by
5
-
the holder of the correct secret key—stored off-protocol. These items are
6
-
intended to be ephemeral, and to be deleted after they've been read.
3
+
Cistern 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
+
5
+
The 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
+
9
+
Cistern is a Deno monorepo consisting of five packages:
10
+
11
+
### `@cistern/crypto`
12
+
Core 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`
15
+
AT 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`
18
+
Common utilities and authentication logic. Handles DID resolution via Slingshot service and creates authenticated RPC clients using app passwords.
19
+
20
+
### `@cistern/producer`
21
+
Creates 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`
24
+
Retrieves, 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
+
28
+
Private 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
+
32
+
Run all unit tests:
33
+
```bash
34
+
deno test --allow-env
35
+
```
7
36
8
-
The intention is for Cistern to bridge the gap between where ideas are had and
9
-
where they can be stored long-term. For example, let's say you have an idea
10
-
while at a restaurant. You create an item using your phone, and once you're back
11
-
at your desk and you open Obsidian, that item is automatically pulled from your
12
-
PDS, decrypted, and deleted from your PDS. If your notebook was open at the time
13
-
you created your item, the Cistern Obsidian plugin would have been notified of
14
-
the new item via the Jetstream, and so you would find your memo waiting for you
15
-
once you got home.
37
+
Run end-to-end tests (requires AT Protocol credentials):
38
+
```bash
39
+
CISTERN_HANDLE="your.bsky.social" \
40
+
CISTERN_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx" \
41
+
deno test --allow-env --allow-net e2e.test.ts
42
+
```