graham.systems
Encrypted, ephemeral, private memos on atproto
docs: add package READMEs
+52
-5
packages/consumer/README.md
+52
-5
packages/consumer/README.md
···
1
-
# `@cistern/consumer`
1
+
# @cistern/consumer
2
+
3
+
Consumer client for retrieving, decrypting, and deleting Cistern items.
4
+
5
+
## Usage
6
+
7
+
### Generate Keypair
8
+
9
+
```typescript
10
+
import { createConsumer, serializeKey } from "@cistern/consumer";
11
+
12
+
const consumer = await createConsumer({
13
+
handle: "user.bsky.social",
14
+
appPassword: "xxxx-xxxx-xxxx-xxxx",
15
+
});
16
+
17
+
const keypair = await consumer.generateKeyPair();
18
+
19
+
console.log(`Public key URI: ${keypair.publicKey}`);
20
+
console.log(`Private key: ${serializeKey(keypair.privateKey)}`);
21
+
```
22
+
23
+
### Use Existing Keypair
24
+
25
+
```typescript
26
+
import { createConsumer } from "@cistern/consumer";
27
+
28
+
const consumer = await createConsumer({
29
+
handle: "user.bsky.social",
30
+
appPassword: "xxxx-xxxx-xxxx-xxxx",
31
+
keypair: {
32
+
publicKey: "at://did:plc:abc123/app.cistern.lexicon.pubkey/3jzfcijpj2z",
33
+
privateKey: "base64-encoded-private-key",
34
+
},
35
+
});
36
+
```
2
37
3
-
The Consumer module is responsible for the following:
38
+
### List Items (Polling)
4
39
5
-
- Generating key pairs
6
-
- Retrieving and decrypting items
7
-
- Subscribing to Jetstream to monitor for items
40
+
```typescript
41
+
for await (const item of consumer.listItems()) {
42
+
console.log(`[${item.tid}] ${item.text}`);
43
+
await consumer.deleteItem(item.tid);
44
+
}
45
+
```
46
+
47
+
### Subscribe to Items (Real-time)
48
+
49
+
```typescript
50
+
for await (const item of consumer.subscribeToItems()) {
51
+
console.log(`[${item.tid}] ${item.text}`);
52
+
await consumer.deleteItem(item.tid);
53
+
}
54
+
```
+11
packages/crypto/README.md
+11
packages/crypto/README.md
···
1
+
# @cistern/crypto
2
+
3
+
Post-quantum cryptographic primitives for Cistern.
4
+
5
+
## Algorithm
6
+
7
+
**`x_wing-xchacha20_poly1305-sha3_512`**
8
+
9
+
- **X-Wing KEM**: Post-quantum hybrid key encapsulation (ML-KEM-768 + X25519)
10
+
- **XChaCha20-Poly1305**: Authenticated encryption
11
+
- **SHA3-512**: Content integrity verification
+10
packages/lexicon/README.md
+10
packages/lexicon/README.md
···
1
+
# @cistern/lexicon
2
+
3
+
AT Protocol lexicon definitions and TypeScript types for Cistern records.
4
+
5
+
## Record Types
6
+
7
+
| Collection | Description |
8
+
|------------|-------------|
9
+
| `app.cistern.lexicon.pubkey` | Public key records with human-readable names, referenced by items via AT-URI |
10
+
| `app.cistern.lexicon.item` | Encrypted item records containing ciphertext, nonce, algorithm metadata, and public key reference |
+34
packages/producer/README.md
+34
packages/producer/README.md
···
1
+
# @cistern/producer
2
+
3
+
Producer client for creating and encrypting Cistern items.
4
+
5
+
## Usage
6
+
7
+
```typescript
8
+
import { createProducer } from "@cistern/producer";
9
+
10
+
const producer = await createProducer({
11
+
handle: "user.bsky.social",
12
+
appPassword: "xxxx-xxxx-xxxx-xxxx",
13
+
});
14
+
15
+
for await (const pubkey of producer.listPublicKeys()) {
16
+
console.log(`${pubkey.name}: ${pubkey.uri}`);
17
+
}
18
+
19
+
producer.selectPublicKey(pubkey);
20
+
21
+
const itemUri = await producer.createItem("Hello, world!");
22
+
```
23
+
24
+
Or, if you already have a public key record ID:
25
+
26
+
```typescript
27
+
const producer = await createProducer({
28
+
handle: "user.bsky.social",
29
+
appPassword: "xxxx-xxxx-xxxx-xxxx",
30
+
publicKey: "3jzfcijpj2z",
31
+
});
32
+
33
+
const itemUri = await producer.createItem("Hello, world!");
34
+
```