zzstoatzz.io
chadtmiller.com
+496
docs/plans/2026-01-06-pds-file-reorganization.md
+496
docs/plans/2026-01-06-pds-file-reorganization.md
···
···
1
+
# PDS File Reorganization Implementation Plan
2
+
3
+
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4
+
5
+
**Goal:** Reorganize pds.js into logical domain sections with box-style headers for improved readability.
6
+
7
+
**Architecture:** Reorder existing code into 12 logical domains without changing functionality. Add Unicode box-style section headers. Group related utilities that are currently scattered.
8
+
9
+
**Tech Stack:** JavaScript, JSDoc
10
+
11
+
---
12
+
13
+
## Box Header Format
14
+
15
+
All section headers use this format (80 chars wide):
16
+
```javascript
17
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
18
+
// ║ SECTION NAME ║
19
+
// ║ Brief description of what this section contains ║
20
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
21
+
```
22
+
23
+
---
24
+
25
+
### Task 1: Types & Constants Section
26
+
27
+
**Files:**
28
+
- Modify: `src/pds.js` (lines 17-84, plus scattered constants)
29
+
30
+
**Step 1: Create the new section header and gather all types/constants**
31
+
32
+
Move these items to the top (after the file header comment):
33
+
- `CBOR_FALSE`, `CBOR_TRUE`, `CBOR_NULL`, `CBOR_TAG_CID` (from lines 19-24)
34
+
- `CODEC_DAG_CBOR`, `CODEC_RAW` (from lines 480-481)
35
+
- `TID_CHARS`, `clockId`, `lastTimestamp` (from lines 563-566)
36
+
- `P256_N`, `P256_N_DIV_2` (from lines 638-641)
37
+
- All typedefs: `Env`, `BlockRow`, `RecordRow`, `CommitRow`, `SeqEventRow`, `BlobRow`, `JwtPayload`
38
+
39
+
Add header:
40
+
```javascript
41
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
42
+
// ║ TYPES & CONSTANTS ║
43
+
// ║ Environment bindings, SQL row types, protocol constants ║
44
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
45
+
```
46
+
47
+
**Step 2: Run typecheck to verify no breakage**
48
+
49
+
Run: `npm run typecheck`
50
+
Expected: 0 errors
51
+
52
+
**Step 3: Commit**
53
+
54
+
```bash
55
+
git add src/pds.js
56
+
git commit -m "refactor: consolidate types and constants section"
57
+
```
58
+
59
+
---
60
+
61
+
### Task 2: Utilities Section
62
+
63
+
**Files:**
64
+
- Modify: `src/pds.js`
65
+
66
+
**Step 1: Create utilities section after types/constants**
67
+
68
+
Move these functions together:
69
+
- `errorResponse()` (from line 92)
70
+
- `bytesToHex()` (from line 990)
71
+
- `hexToBytes()` (from line 1001)
72
+
- `bytesToBigInt()` (from line 647)
73
+
- `bigIntToBytes()` (from line 660)
74
+
- `base32Encode()` (from line 538)
75
+
- `base32Decode()` (from line 1237)
76
+
- `base64UrlEncode()` (from line 745)
77
+
- `base64UrlDecode()` (from line 759)
78
+
- `varint()` (from line 1211)
79
+
80
+
Add header:
81
+
```javascript
82
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
83
+
// ║ UTILITIES ║
84
+
// ║ Error responses, byte conversion, base encoding ║
85
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
86
+
```
87
+
88
+
**Step 2: Run typecheck**
89
+
90
+
Run: `npm run typecheck`
91
+
Expected: 0 errors
92
+
93
+
**Step 3: Commit**
94
+
95
+
```bash
96
+
git add src/pds.js
97
+
git commit -m "refactor: consolidate utilities section"
98
+
```
99
+
100
+
---
101
+
102
+
### Task 3: CBOR Encoding Section
103
+
104
+
**Files:**
105
+
- Modify: `src/pds.js`
106
+
107
+
**Step 1: Create CBOR section**
108
+
109
+
Keep together (already grouped, just add new header):
110
+
- `encodeHead()`
111
+
- `cborEncode()`
112
+
- `cborEncodeDagCbor()`
113
+
- `cborDecode()`
114
+
115
+
Replace `// === CBOR ENCODING ===` with:
116
+
```javascript
117
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
118
+
// ║ CBOR ENCODING ║
119
+
// ║ RFC 8949 CBOR and DAG-CBOR for content-addressed data ║
120
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
121
+
```
122
+
123
+
**Step 2: Run typecheck**
124
+
125
+
Run: `npm run typecheck`
126
+
Expected: 0 errors
127
+
128
+
**Step 3: Commit**
129
+
130
+
```bash
131
+
git add src/pds.js
132
+
git commit -m "refactor: add CBOR encoding section header"
133
+
```
134
+
135
+
---
136
+
137
+
### Task 4: Content Identifiers Section
138
+
139
+
**Files:**
140
+
- Modify: `src/pds.js`
141
+
142
+
**Step 1: Create CID/TID section**
143
+
144
+
Group together:
145
+
- `class CID` (from line 238)
146
+
- `createCidWithCodec()` (from line 489)
147
+
- `createCid()` (from line 510)
148
+
- `createBlobCid()` (from line 519)
149
+
- `cidToString()` (from line 528)
150
+
- `cidToBytes()` (from line 1226)
151
+
- `createTid()` (from line 572)
152
+
153
+
Add header:
154
+
```javascript
155
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
156
+
// ║ CONTENT IDENTIFIERS ║
157
+
// ║ CIDs (content hashes) and TIDs (timestamp IDs) ║
158
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
159
+
```
160
+
161
+
**Step 2: Run typecheck**
162
+
163
+
Run: `npm run typecheck`
164
+
Expected: 0 errors
165
+
166
+
**Step 3: Commit**
167
+
168
+
```bash
169
+
git add src/pds.js
170
+
git commit -m "refactor: consolidate content identifiers section"
171
+
```
172
+
173
+
---
174
+
175
+
### Task 5: Cryptography Section
176
+
177
+
**Files:**
178
+
- Modify: `src/pds.js`
179
+
180
+
**Step 1: Create cryptography section**
181
+
182
+
Group together:
183
+
- `sha256()` (from line 1016)
184
+
- `importPrivateKey()` (from line 606)
185
+
- `generateKeyPair()` (from line 705)
186
+
- `compressPublicKey()` (from line 728)
187
+
- `sign()` (from line 675)
188
+
189
+
Add header:
190
+
```javascript
191
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
192
+
// ║ CRYPTOGRAPHY ║
193
+
// ║ P-256 signing with low-S normalization, key management ║
194
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
195
+
```
196
+
197
+
**Step 2: Run typecheck**
198
+
199
+
Run: `npm run typecheck`
200
+
Expected: 0 errors
201
+
202
+
**Step 3: Commit**
203
+
204
+
```bash
205
+
git add src/pds.js
206
+
git commit -m "refactor: create cryptography section"
207
+
```
208
+
209
+
---
210
+
211
+
### Task 6: Authentication Section
212
+
213
+
**Files:**
214
+
- Modify: `src/pds.js`
215
+
216
+
**Step 1: Create authentication section**
217
+
218
+
Group together:
219
+
- `hmacSign()` (from line 777)
220
+
- `createAccessJwt()` (from line 800)
221
+
- `createRefreshJwt()` (from line 829)
222
+
- `verifyJwt()` (from line 876)
223
+
- `verifyAccessJwt()` (from line 919)
224
+
- `verifyRefreshJwt()` (from line 931)
225
+
- `createServiceJwt()` (from line 952)
226
+
227
+
Add header:
228
+
```javascript
229
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
230
+
// ║ AUTHENTICATION ║
231
+
// ║ JWT creation/verification for sessions and service auth ║
232
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
233
+
```
234
+
235
+
**Step 2: Run typecheck**
236
+
237
+
Run: `npm run typecheck`
238
+
Expected: 0 errors
239
+
240
+
**Step 3: Commit**
241
+
242
+
```bash
243
+
git add src/pds.js
244
+
git commit -m "refactor: create authentication section"
245
+
```
246
+
247
+
---
248
+
249
+
### Task 7: Merkle Search Tree Section
250
+
251
+
**Files:**
252
+
- Modify: `src/pds.js`
253
+
254
+
**Step 1: Update MST section header**
255
+
256
+
Keep together (already grouped):
257
+
- `keyDepthCache`
258
+
- `getKeyDepth()`
259
+
- `commonPrefixLen()`
260
+
- `class MST`
261
+
262
+
Replace `// === MERKLE SEARCH TREE ===` with:
263
+
```javascript
264
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
265
+
// ║ MERKLE SEARCH TREE ║
266
+
// ║ MST for ATProto repository structure ║
267
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
268
+
```
269
+
270
+
**Step 2: Run typecheck**
271
+
272
+
Run: `npm run typecheck`
273
+
Expected: 0 errors
274
+
275
+
**Step 3: Commit**
276
+
277
+
```bash
278
+
git add src/pds.js
279
+
git commit -m "refactor: update MST section header"
280
+
```
281
+
282
+
---
283
+
284
+
### Task 8: CAR Files Section
285
+
286
+
**Files:**
287
+
- Modify: `src/pds.js`
288
+
289
+
**Step 1: Update CAR section**
290
+
291
+
Keep only:
292
+
- `buildCarFile()`
293
+
294
+
(Note: `varint()`, `cidToBytes()`, `base32Decode()` moved to earlier sections)
295
+
296
+
Replace `// === CAR FILE BUILDER ===` with:
297
+
```javascript
298
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
299
+
// ║ CAR FILES ║
300
+
// ║ Content Addressable aRchive format for repo sync ║
301
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
302
+
```
303
+
304
+
**Step 2: Run typecheck**
305
+
306
+
Run: `npm run typecheck`
307
+
Expected: 0 errors
308
+
309
+
**Step 3: Commit**
310
+
311
+
```bash
312
+
git add src/pds.js
313
+
git commit -m "refactor: update CAR files section"
314
+
```
315
+
316
+
---
317
+
318
+
### Task 9: Blob Handling Section
319
+
320
+
**Files:**
321
+
- Modify: `src/pds.js`
322
+
323
+
**Step 1: Create blob handling section**
324
+
325
+
Group together:
326
+
- `sniffMimeType()` (from line 105)
327
+
- `findBlobRefs()` (from line 181)
328
+
- `CRAWL_NOTIFY_THRESHOLD`, `lastCrawlNotify` (from lines 207-208)
329
+
- `notifyCrawlers()` (from line 214)
330
+
331
+
Add header:
332
+
```javascript
333
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
334
+
// ║ BLOB HANDLING ║
335
+
// ║ MIME detection, blob reference scanning, crawler notification ║
336
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
337
+
```
338
+
339
+
**Step 2: Run typecheck**
340
+
341
+
Run: `npm run typecheck`
342
+
Expected: 0 errors
343
+
344
+
**Step 3: Commit**
345
+
346
+
```bash
347
+
git add src/pds.js
348
+
git commit -m "refactor: create blob handling section"
349
+
```
350
+
351
+
---
352
+
353
+
### Task 10: Routing Section
354
+
355
+
**Files:**
356
+
- Modify: `src/pds.js`
357
+
358
+
**Step 1: Add routing section header**
359
+
360
+
Before `RouteHandler` callback typedef, add:
361
+
```javascript
362
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
363
+
// ║ ROUTING ║
364
+
// ║ XRPC endpoint definitions ║
365
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
366
+
```
367
+
368
+
This section contains:
369
+
- `RouteHandler` (callback typedef)
370
+
- `Route` (typedef)
371
+
- `pdsRoutes`
372
+
373
+
**Step 2: Run typecheck**
374
+
375
+
Run: `npm run typecheck`
376
+
Expected: 0 errors
377
+
378
+
**Step 3: Commit**
379
+
380
+
```bash
381
+
git add src/pds.js
382
+
git commit -m "refactor: add routing section header"
383
+
```
384
+
385
+
---
386
+
387
+
### Task 11: Personal Data Server Section
388
+
389
+
**Files:**
390
+
- Modify: `src/pds.js`
391
+
392
+
**Step 1: Add PDS class section header**
393
+
394
+
Before `class PersonalDataServer`, add:
395
+
```javascript
396
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
397
+
// ║ PERSONAL DATA SERVER ║
398
+
// ║ Durable Object class implementing ATProto PDS ║
399
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
400
+
```
401
+
402
+
**Step 2: Run typecheck**
403
+
404
+
Run: `npm run typecheck`
405
+
Expected: 0 errors
406
+
407
+
**Step 3: Commit**
408
+
409
+
```bash
410
+
git add src/pds.js
411
+
git commit -m "refactor: add PDS class section header"
412
+
```
413
+
414
+
---
415
+
416
+
### Task 12: Workers Entry Point Section
417
+
418
+
**Files:**
419
+
- Modify: `src/pds.js`
420
+
421
+
**Step 1: Add workers entry point section header**
422
+
423
+
Before `corsHeaders`, add:
424
+
```javascript
425
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
426
+
// ║ WORKERS ENTRY POINT ║
427
+
// ║ Request handling, CORS, auth middleware ║
428
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
429
+
```
430
+
431
+
This section contains:
432
+
- `corsHeaders`
433
+
- `addCorsHeaders()`
434
+
- `getSubdomain()`
435
+
- `requireAuth()`
436
+
- `handleAuthenticatedBlobUpload()`
437
+
- `handleAuthenticatedRepoWrite()`
438
+
- `handleRequest()`
439
+
- `default export`
440
+
441
+
**Step 2: Run typecheck**
442
+
443
+
Run: `npm run typecheck`
444
+
Expected: 0 errors
445
+
446
+
**Step 3: Commit**
447
+
448
+
```bash
449
+
git add src/pds.js
450
+
git commit -m "refactor: add workers entry point section header"
451
+
```
452
+
453
+
---
454
+
455
+
### Task 13: Final Verification
456
+
457
+
**Step 1: Run full typecheck**
458
+
459
+
Run: `npm run typecheck`
460
+
Expected: 0 errors
461
+
462
+
**Step 2: Run tests**
463
+
464
+
Run: `npm test`
465
+
Expected: All tests pass
466
+
467
+
**Step 3: Run e2e tests if available**
468
+
469
+
Run: `npm run test:e2e`
470
+
Expected: All tests pass
471
+
472
+
**Step 4: Final commit if any cleanup needed**
473
+
474
+
```bash
475
+
git add src/pds.js
476
+
git commit -m "refactor: complete pds.js reorganization with box headers"
477
+
```
478
+
479
+
---
480
+
481
+
## Section Order Summary
482
+
483
+
Final file structure (top to bottom):
484
+
1. File header comment
485
+
2. TYPES & CONSTANTS
486
+
3. UTILITIES
487
+
4. CBOR ENCODING
488
+
5. CONTENT IDENTIFIERS
489
+
6. CRYPTOGRAPHY
490
+
7. AUTHENTICATION
491
+
8. MERKLE SEARCH TREE
492
+
9. CAR FILES
493
+
10. BLOB HANDLING
494
+
11. ROUTING
495
+
12. PERSONAL DATA SERVER
496
+
13. WORKERS ENTRY POINT
+23
package-lock.json
+23
package-lock.json
···
9
"version": "0.1.0",
10
"devDependencies": {
11
"@biomejs/biome": "^2.3.11",
12
"wrangler": "^4.54.0"
13
}
14
},
···
288
"engines": {
289
"node": ">=16"
290
}
291
},
292
"node_modules/@cspotcode/source-map-support": {
293
"version": "0.8.1",
···
1563
"dev": true,
1564
"license": "0BSD",
1565
"optional": true
1566
},
1567
"node_modules/undici": {
1568
"version": "7.14.0",
···
9
"version": "0.1.0",
10
"devDependencies": {
11
"@biomejs/biome": "^2.3.11",
12
+
"@cloudflare/workers-types": "^4.20260103.0",
13
+
"typescript": "^5.9.3",
14
"wrangler": "^4.54.0"
15
}
16
},
···
290
"engines": {
291
"node": ">=16"
292
}
293
+
},
294
+
"node_modules/@cloudflare/workers-types": {
295
+
"version": "4.20260103.0",
296
+
"resolved": "https://registry.npmjs.org/@cloudflare/workers-types/-/workers-types-4.20260103.0.tgz",
297
+
"integrity": "sha512-jANmoGpJcXARnwlkvrQOeWyjYD1quTfHcs+++Z544XRHOSfLc4XSlts7snIhbiIGgA5bo66zDhraF+9lKUr2hw==",
298
+
"dev": true,
299
+
"license": "MIT OR Apache-2.0"
300
},
301
"node_modules/@cspotcode/source-map-support": {
302
"version": "0.8.1",
···
1572
"dev": true,
1573
"license": "0BSD",
1574
"optional": true
1575
+
},
1576
+
"node_modules/typescript": {
1577
+
"version": "5.9.3",
1578
+
"resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
1579
+
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
1580
+
"dev": true,
1581
+
"license": "Apache-2.0",
1582
+
"bin": {
1583
+
"tsc": "bin/tsc",
1584
+
"tsserver": "bin/tsserver"
1585
+
},
1586
+
"engines": {
1587
+
"node": ">=14.17"
1588
+
}
1589
},
1590
"node_modules/undici": {
1591
"version": "7.14.0",
+4
-1
package.json
+4
-1
package.json
···
12
"setup": "node scripts/setup.js",
13
"format": "biome format --write . && shfmt -w -i 2 test/*.sh",
14
"lint": "biome lint .",
15
+
"check": "biome check .",
16
+
"typecheck": "tsc --noEmit"
17
},
18
"devDependencies": {
19
"@biomejs/biome": "^2.3.11",
20
+
"@cloudflare/workers-types": "^4.20260103.0",
21
+
"typescript": "^5.9.3",
22
"wrangler": "^4.54.0"
23
}
24
}
+691
-381
src/pds.js
+691
-381
src/pds.js
···
1
-
/**
2
-
* Minimal AT Protocol Personal Data Server (PDS)
3
-
*
4
-
* A single-file implementation of an ATProto PDS for Cloudflare Workers
5
-
* with Durable Objects. Implements the core protocol primitives:
6
-
*
7
-
* - CBOR/DAG-CBOR encoding for content-addressed data
8
-
* - CID generation (CIDv1 with dag-cbor + sha-256)
9
-
* - Merkle Search Tree (MST) for repository structure
10
-
* - P-256 signing with low-S normalization
11
-
* - CAR file building for repo sync
12
-
* - XRPC endpoints for repo operations and sync
13
-
*
14
-
* @see https://atproto.com
15
-
*/
16
17
-
// === CONSTANTS ===
18
// CBOR primitive markers (RFC 8949)
19
const CBOR_FALSE = 0xf4;
20
const CBOR_TRUE = 0xf5;
···
23
// DAG-CBOR CID link tag
24
const CBOR_TAG_CID = 42;
25
26
-
// === ERROR HELPER ===
27
function errorResponse(error, message, status) {
28
return Response.json({ error, message }, { status });
29
}
30
31
-
// === MIME TYPE SNIFFING ===
32
-
// Detect file type from magic bytes (first 12 bytes)
33
-
// Reference: https://en.wikipedia.org/wiki/List_of_file_signatures
34
35
/**
36
-
* Sniff MIME type from file magic bytes
37
-
* @param {Uint8Array|ArrayBuffer} bytes - File bytes (only first 12 needed)
38
-
* @returns {string|null} Detected MIME type or null if unknown
39
*/
40
-
export function sniffMimeType(bytes) {
41
-
const arr = new Uint8Array(bytes.slice(0, 12));
42
-
43
-
// JPEG: FF D8 FF
44
-
if (arr[0] === 0xff && arr[1] === 0xd8 && arr[2] === 0xff) {
45
-
return 'image/jpeg';
46
}
47
48
-
// PNG: 89 50 4E 47 0D 0A 1A 0A
49
-
if (
50
-
arr[0] === 0x89 &&
51
-
arr[1] === 0x50 &&
52
-
arr[2] === 0x4e &&
53
-
arr[3] === 0x47 &&
54
-
arr[4] === 0x0d &&
55
-
arr[5] === 0x0a &&
56
-
arr[6] === 0x1a &&
57
-
arr[7] === 0x0a
58
-
) {
59
-
return 'image/png';
60
}
61
62
-
// GIF: 47 49 46 38 (GIF8)
63
-
if (
64
-
arr[0] === 0x47 &&
65
-
arr[1] === 0x49 &&
66
-
arr[2] === 0x46 &&
67
-
arr[3] === 0x38
68
-
) {
69
-
return 'image/gif';
70
}
71
72
-
// WebP: RIFF....WEBP
73
-
if (
74
-
arr[0] === 0x52 &&
75
-
arr[1] === 0x49 &&
76
-
arr[2] === 0x46 &&
77
-
arr[3] === 0x46 &&
78
-
arr[8] === 0x57 &&
79
-
arr[9] === 0x45 &&
80
-
arr[10] === 0x42 &&
81
-
arr[11] === 0x50
82
-
) {
83
-
return 'image/webp';
84
-
}
85
86
-
// ISOBMFF container: ....ftyp at byte 4 (MP4, AVIF, HEIC, etc.)
87
-
if (
88
-
arr[4] === 0x66 &&
89
-
arr[5] === 0x74 &&
90
-
arr[6] === 0x79 &&
91
-
arr[7] === 0x70
92
-
) {
93
-
// Check brand code at bytes 8-11
94
-
const brand = String.fromCharCode(arr[8], arr[9], arr[10], arr[11]);
95
-
if (brand === 'avif') {
96
-
return 'image/avif';
97
}
98
-
if (brand === 'heic' || brand === 'heix' || brand === 'mif1') {
99
-
return 'image/heic';
100
-
}
101
-
return 'video/mp4';
102
}
103
104
-
return null;
105
-
}
106
107
-
// === BLOB REF DETECTION ===
108
-
// Recursively find blob references in records
109
110
/**
111
-
* Find all blob CID references in a record
112
-
* @param {*} obj - Record value to scan
113
-
* @param {string[]} refs - Accumulator array (internal)
114
-
* @returns {string[]} Array of blob CID strings
115
*/
116
-
export function findBlobRefs(obj, refs = []) {
117
-
if (!obj || typeof obj !== 'object') {
118
-
return refs;
119
-
}
120
-
121
-
// Check if this object is a blob ref
122
-
if (obj.$type === 'blob' && obj.ref?.$link) {
123
-
refs.push(obj.ref.$link);
124
-
}
125
126
-
// Recurse into arrays and objects
127
-
if (Array.isArray(obj)) {
128
-
for (const item of obj) {
129
-
findBlobRefs(item, refs);
130
-
}
131
-
} else {
132
-
for (const value of Object.values(obj)) {
133
-
findBlobRefs(value, refs);
134
}
135
}
136
137
-
return refs;
138
}
139
140
-
// === CRAWLER NOTIFICATION ===
141
-
// Notify relays to come crawl us after writes (like official PDS)
142
-
let lastCrawlNotify = 0;
143
-
const CRAWL_NOTIFY_THRESHOLD = 20 * 60 * 1000; // 20 minutes (matches official PDS)
144
-
145
-
async function notifyCrawlers(env, hostname) {
146
-
const now = Date.now();
147
-
if (now - lastCrawlNotify < CRAWL_NOTIFY_THRESHOLD) {
148
-
return; // Throttle notifications
149
}
150
-
151
-
const relayHost = env.RELAY_HOST;
152
-
if (!relayHost) return;
153
154
-
lastCrawlNotify = now;
155
156
-
// Fire and forget - don't block writes on relay notification
157
-
fetch(`${relayHost}/xrpc/com.atproto.sync.requestCrawl`, {
158
-
method: 'POST',
159
-
headers: { 'Content-Type': 'application/json' },
160
-
body: JSON.stringify({ hostname }),
161
-
}).catch(() => {
162
-
// Silently ignore relay notification failures
163
-
});
164
}
165
166
// === CID WRAPPER ===
167
// Explicit CID type for DAG-CBOR encoding (avoids fragile heuristic detection)
168
169
class CID {
170
constructor(bytes) {
171
if (!(bytes instanceof Uint8Array)) {
172
throw new Error('CID must be constructed with Uint8Array');
···
175
}
176
}
177
178
-
// === CBOR ENCODING ===
179
-
// Minimal deterministic CBOR (RFC 8949) - sorted keys, minimal integers
180
181
/**
182
* Encode CBOR type header (major type + length)
···
210
* @returns {Uint8Array} CBOR-encoded bytes
211
*/
212
export function cborEncode(value) {
213
const parts = [];
214
215
function encode(val) {
216
if (val === null) {
217
parts.push(CBOR_NULL);
···
242
}
243
}
244
245
function encodeInteger(n) {
246
if (n >= 0) {
247
encodeHead(parts, 0, n); // major type 0 = unsigned int
···
254
return new Uint8Array(parts);
255
}
256
257
-
// DAG-CBOR encoder that handles CIDs with tag 42
258
function cborEncodeDagCbor(value) {
259
const parts = [];
260
261
function encode(val) {
262
if (val === null) {
263
parts.push(CBOR_NULL);
···
319
export function cborDecode(bytes) {
320
let offset = 0;
321
322
function read() {
323
const initial = bytes[offset++];
324
const major = initial >> 5;
···
364
}
365
case 5: {
366
// map
367
const obj = {};
368
for (let i = 0; i < length; i++) {
369
-
const key = read();
370
obj[key] = read();
371
}
372
return obj;
···
394
return read();
395
}
396
397
-
// === CID GENERATION ===
398
-
// CID codec constants
399
-
const CODEC_DAG_CBOR = 0x71;
400
-
const CODEC_RAW = 0x55;
401
402
/**
403
* Create a CIDv1 with SHA-256 hash
···
406
* @returns {Promise<Uint8Array>} CID bytes (36 bytes: version + codec + multihash)
407
*/
408
async function createCidWithCodec(bytes, codec) {
409
-
const hash = await crypto.subtle.digest('SHA-256', bytes);
410
const hashBytes = new Uint8Array(hash);
411
412
// CIDv1: version(1) + codec + multihash(sha256)
···
450
}
451
452
/**
453
-
* Encode bytes as base32lower string
454
-
* @param {Uint8Array} bytes - Bytes to encode
455
-
* @returns {string} Base32lower-encoded string
456
*/
457
-
export function base32Encode(bytes) {
458
-
const alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
459
-
let result = '';
460
-
let bits = 0;
461
-
let value = 0;
462
-
463
-
for (const byte of bytes) {
464
-
value = (value << 8) | byte;
465
-
bits += 8;
466
-
while (bits >= 5) {
467
-
bits -= 5;
468
-
result += alphabet[(value >> bits) & 31];
469
-
}
470
-
}
471
-
472
-
if (bits > 0) {
473
-
result += alphabet[(value << (5 - bits)) & 31];
474
-
}
475
-
476
-
return result;
477
}
478
479
-
// === TID GENERATION ===
480
-
// Timestamp-based IDs: base32-sort encoded microseconds + clock ID
481
-
482
-
const TID_CHARS = '234567abcdefghijklmnopqrstuvwxyz';
483
-
let lastTimestamp = 0;
484
-
const clockId = Math.floor(Math.random() * 1024);
485
-
486
/**
487
* Generate a timestamp-based ID (TID) for record keys
488
* Monotonic within a process, sortable by time
···
514
return tid;
515
}
516
517
-
// === P-256 SIGNING ===
518
-
// Web Crypto ECDSA with P-256 curve
519
520
/**
521
* Import a raw P-256 private key for signing
···
546
547
return crypto.subtle.importKey(
548
'pkcs8',
549
-
pkcs8,
550
{ name: 'ECDSA', namedCurve: 'P-256' },
551
false,
552
['sign'],
553
);
554
}
555
556
-
// P-256 curve order N
557
-
const P256_N = BigInt(
558
-
'0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551',
559
-
);
560
-
const P256_N_DIV_2 = P256_N / 2n;
561
-
562
-
function bytesToBigInt(bytes) {
563
-
let result = 0n;
564
-
for (const byte of bytes) {
565
-
result = (result << 8n) | BigInt(byte);
566
-
}
567
-
return result;
568
-
}
569
-
570
-
function bigIntToBytes(n, length) {
571
-
const bytes = new Uint8Array(length);
572
-
for (let i = length - 1; i >= 0; i--) {
573
-
bytes[i] = Number(n & 0xffn);
574
-
n >>= 8n;
575
-
}
576
-
return bytes;
577
-
}
578
-
579
/**
580
* Sign data with ECDSA P-256, returning low-S normalized signature
581
* @param {CryptoKey} privateKey - Web Crypto key from importPrivateKey
···
586
const signature = await crypto.subtle.sign(
587
{ name: 'ECDSA', hash: 'SHA-256' },
588
privateKey,
589
-
data,
590
);
591
const sig = new Uint8Array(signature);
592
···
621
622
// Export private key as raw bytes
623
const privateJwk = await crypto.subtle.exportKey('jwk', keyPair.privateKey);
624
-
const privateBytes = base64UrlDecode(privateJwk.d);
625
626
// Export public key as compressed point
627
const publicRaw = await crypto.subtle.exportKey('raw', keyPair.publicKey);
···
631
return { privateKey: privateBytes, publicKey: compressed };
632
}
633
634
function compressPublicKey(uncompressed) {
635
// uncompressed is 65 bytes: 0x04 + x(32) + y(32)
636
// compressed is 33 bytes: prefix(02 or 03) + x(32)
···
643
return compressed;
644
}
645
646
-
/**
647
-
* Encode bytes as base64url string (no padding)
648
-
* @param {Uint8Array} bytes - Bytes to encode
649
-
* @returns {string} Base64url-encoded string
650
-
*/
651
-
export function base64UrlEncode(bytes) {
652
-
let binary = '';
653
-
for (const byte of bytes) {
654
-
binary += String.fromCharCode(byte);
655
-
}
656
-
const base64 = btoa(binary);
657
-
return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
658
-
}
659
-
660
-
/**
661
-
* Decode base64url string to bytes
662
-
* @param {string} str - Base64url-encoded string
663
-
* @returns {Uint8Array} Decoded bytes
664
-
*/
665
-
export function base64UrlDecode(str) {
666
-
const base64 = str.replace(/-/g, '+').replace(/_/g, '/');
667
-
const pad = base64.length % 4;
668
-
const padded = pad ? base64 + '='.repeat(4 - pad) : base64;
669
-
const binary = atob(padded);
670
-
const bytes = new Uint8Array(binary.length);
671
-
for (let i = 0; i < binary.length; i++) {
672
-
bytes[i] = binary.charCodeAt(i);
673
-
}
674
-
return bytes;
675
-
}
676
677
/**
678
* Create HMAC-SHA256 signature for JWT
···
683
async function hmacSign(data, secret) {
684
const key = await crypto.subtle.importKey(
685
'raw',
686
-
new TextEncoder().encode(secret),
687
{ name: 'HMAC', hash: 'SHA-256' },
688
false,
689
['sign'],
···
691
const sig = await crypto.subtle.sign(
692
'HMAC',
693
key,
694
-
new TextEncoder().encode(data),
695
);
696
return base64UrlEncode(new Uint8Array(sig));
697
}
···
765
* @param {string} jwt - JWT string to verify
766
* @param {string} secret - JWT signing secret
767
* @param {string} expectedType - Expected token type (e.g., 'at+jwt', 'refresh+jwt')
768
-
* @returns {Promise<{header: Object, payload: Object}>} Decoded header and payload
769
* @throws {Error} If token is invalid, expired, or wrong type
770
*/
771
async function verifyJwt(jwt, secret, expectedType) {
···
808
* Verify and decode an access JWT
809
* @param {string} jwt - JWT string to verify
810
* @param {string} secret - JWT signing secret
811
-
* @returns {Promise<Object>} Decoded payload
812
* @throws {Error} If token is invalid, expired, or wrong type
813
*/
814
export async function verifyAccessJwt(jwt, secret) {
···
820
* Verify and decode a refresh JWT
821
* @param {string} jwt - JWT string to verify
822
* @param {string} secret - JWT signing secret
823
-
* @returns {Promise<Object>} Decoded payload
824
* @throws {Error} If token is invalid, expired, or wrong type
825
*/
826
export async function verifyRefreshJwt(jwt, secret) {
···
853
crypto.getRandomValues(jtiBytes);
854
const jti = bytesToHex(jtiBytes);
855
856
const payload = {
857
iss,
858
aud,
···
876
return `${headerB64}.${payloadB64}.${sigB64}`;
877
}
878
879
-
/**
880
-
* Convert bytes to hexadecimal string
881
-
* @param {Uint8Array} bytes - Bytes to convert
882
-
* @returns {string} Hex string
883
-
*/
884
-
export function bytesToHex(bytes) {
885
-
return Array.from(bytes)
886
-
.map((b) => b.toString(16).padStart(2, '0'))
887
-
.join('');
888
-
}
889
-
890
-
/**
891
-
* Convert hexadecimal string to bytes
892
-
* @param {string} hex - Hex string
893
-
* @returns {Uint8Array} Decoded bytes
894
-
*/
895
-
export function hexToBytes(hex) {
896
-
const bytes = new Uint8Array(hex.length / 2);
897
-
for (let i = 0; i < hex.length; i += 2) {
898
-
bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
899
-
}
900
-
return bytes;
901
-
}
902
-
903
-
// === MERKLE SEARCH TREE ===
904
-
// ATProto-compliant MST implementation
905
-
906
-
async function sha256(data) {
907
-
const hash = await crypto.subtle.digest('SHA-256', data);
908
-
return new Uint8Array(hash);
909
-
}
910
911
// Cache for key depths (SHA-256 is expensive)
912
const keyDepthCache = new Map();
···
945
return depth;
946
}
947
948
-
// Compute common prefix length between two byte arrays
949
function commonPrefixLen(a, b) {
950
const minLen = Math.min(a.length, b.length);
951
for (let i = 0; i < minLen; i++) {
···
955
}
956
957
class MST {
958
constructor(sql) {
959
this.sql = sql;
960
}
···
982
entries.push({
983
key,
984
keyBytes: new TextEncoder().encode(key),
985
-
cid: r.cid,
986
depth,
987
});
988
}
···
991
return this.buildTree(entries, maxDepth);
992
}
993
994
async buildTree(entries, layer) {
995
if (entries.length === 0) return null;
996
997
// Separate entries for this layer vs lower layers (subtrees)
998
// Keys with depth == layer stay at this node
999
// Keys with depth < layer go into subtrees (going down toward layer 0)
1000
const thisLayer = [];
1001
let leftSubtree = [];
1002
1003
for (const entry of entries) {
···
1023
}
1024
1025
// Build node with proper ATProto format
1026
const node = { e: [] };
1027
let leftCid = null;
1028
let prevKeyBytes = new Uint8Array(0);
1029
···
1035
leftCid = item.cid;
1036
} else {
1037
// Attach to previous entry's 't' field
1038
-
node.e[node.e.length - 1].t = new CID(cidToBytes(item.cid));
1039
}
1040
} else {
1041
// Entry - compute prefix compression
···
1052
};
1053
1054
node.e.push(e);
1055
-
prevKeyBytes = keyBytes;
1056
}
1057
}
1058
···
1074
}
1075
}
1076
1077
-
// === CAR FILE BUILDER ===
1078
-
1079
-
/**
1080
-
* Encode integer as unsigned varint
1081
-
* @param {number} n - Non-negative integer
1082
-
* @returns {Uint8Array} Varint-encoded bytes
1083
-
*/
1084
-
export function varint(n) {
1085
-
const bytes = [];
1086
-
while (n >= 0x80) {
1087
-
bytes.push((n & 0x7f) | 0x80);
1088
-
n >>>= 7;
1089
-
}
1090
-
bytes.push(n);
1091
-
return new Uint8Array(bytes);
1092
-
}
1093
-
1094
-
/**
1095
-
* Convert base32lower CID string to raw bytes
1096
-
* @param {string} cidStr - CID string with 'b' prefix
1097
-
* @returns {Uint8Array} CID bytes
1098
-
*/
1099
-
export function cidToBytes(cidStr) {
1100
-
// Decode base32lower CID string to bytes
1101
-
if (!cidStr.startsWith('b')) throw new Error('expected base32lower CID');
1102
-
return base32Decode(cidStr.slice(1));
1103
-
}
1104
-
1105
-
/**
1106
-
* Decode base32lower string to bytes
1107
-
* @param {string} str - Base32lower-encoded string
1108
-
* @returns {Uint8Array} Decoded bytes
1109
-
*/
1110
-
export function base32Decode(str) {
1111
-
const alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
1112
-
let bits = 0;
1113
-
let value = 0;
1114
-
const output = [];
1115
-
1116
-
for (const char of str) {
1117
-
const idx = alphabet.indexOf(char);
1118
-
if (idx === -1) continue;
1119
-
value = (value << 5) | idx;
1120
-
bits += 5;
1121
-
if (bits >= 8) {
1122
-
bits -= 8;
1123
-
output.push((value >> bits) & 0xff);
1124
-
}
1125
-
}
1126
-
1127
-
return new Uint8Array(output);
1128
-
}
1129
1130
/**
1131
* Build a CAR (Content Addressable aRchive) file
···
1166
return car;
1167
}
1168
1169
/**
1170
* Route handler function type
1171
* @callback RouteHandler
1172
* @param {PersonalDataServer} pds - PDS instance
1173
* @param {Request} request - HTTP request
1174
* @param {URL} url - Parsed URL
1175
-
* @returns {Promise<Response>} HTTP response
1176
*/
1177
1178
/**
1179
* @typedef {Object} Route
1180
* @property {string} [method] - Required HTTP method (default: any)
1181
* @property {RouteHandler} handler - Handler function
···
1291
},
1292
};
1293
1294
export class PersonalDataServer {
1295
constructor(state, env) {
1296
this.state = state;
1297
this.sql = state.storage.sql;
···
1345
`);
1346
}
1347
1348
async initIdentity(did, privateKeyHex, handle = null) {
1349
await this.state.storage.put('did', did);
1350
await this.state.storage.put('privateKey', privateKeyHex);
···
1373
async getSigningKey() {
1374
const hex = await this.state.storage.get('privateKey');
1375
if (!hex) return null;
1376
-
return importPrivateKey(hexToBytes(hex));
1377
}
1378
1379
-
// Collect MST node blocks for a given root CID
1380
collectMstBlocks(rootCidStr) {
1381
const blocks = [];
1382
const visited = new Set();
1383
1384
const collect = (cidStr) => {
1385
if (visited.has(cidStr)) return;
1386
visited.add(cidStr);
1387
1388
-
const rows = this.sql
1389
.exec(`SELECT data FROM blocks WHERE cid = ?`, cidStr)
1390
-
.toArray();
1391
if (rows.length === 0) return;
1392
1393
const data = new Uint8Array(rows[0].data);
···
1411
return blocks;
1412
}
1413
1414
async createRecord(collection, record, rkey = null) {
1415
const did = await this.getDid();
1416
if (!did) throw new Error('PDS not initialized');
···
1478
const commit = {
1479
did,
1480
version: 3,
1481
-
data: new CID(cidToBytes(dataRoot)), // CID wrapped for explicit encoding
1482
rev,
1483
-
prev: prevCommit?.cid ? new CID(cidToBytes(prevCommit.cid)) : null,
1484
};
1485
1486
// Sign commit (using dag-cbor encoder for CIDs)
1487
const commitBytes = cborEncodeDagCbor(commit);
1488
const signingKey = await this.getSigningKey();
1489
const sig = await sign(signingKey, commitBytes);
1490
1491
const signedCommit = { ...commit, sig };
···
1520
// Add commit block
1521
newBlocks.push({ cid: commitCidStr, data: signedBytes });
1522
// Add MST node blocks (get all blocks referenced by commit.data)
1523
-
const mstBlocks = this.collectMstBlocks(dataRoot);
1524
newBlocks.push(...mstBlocks);
1525
1526
// Sequence event with blocks - store complete event data including rev and time
···
1542
);
1543
1544
// Broadcast to subscribers (both local and via default DO for relay)
1545
-
const evtRows = this.sql
1546
.exec(`SELECT * FROM seq_events ORDER BY seq DESC LIMIT 1`)
1547
-
.toArray();
1548
if (evtRows.length > 0) {
1549
this.broadcastEvent(evtRows[0]);
1550
// Also forward to default DO for relay subscribers
···
1562
body: JSON.stringify({ ...row, evt: evtArray }),
1563
}),
1564
)
1565
-
.catch(() => {}); // Ignore forward errors
1566
}
1567
}
1568
1569
return { uri, cid: recordCidStr, commit: commitCidStr };
1570
}
1571
1572
async deleteRecord(collection, rkey) {
1573
const did = await this.getDid();
1574
if (!did) throw new Error('PDS not initialized');
···
1602
1603
if (stillReferenced.length === 0) {
1604
// Blob is orphaned, delete from R2 and database
1605
-
await this.env.BLOBS.delete(`${did}/${blobCid}`);
1606
this.sql.exec('DELETE FROM blob WHERE cid = ?', blobCid);
1607
}
1608
}
···
1622
const commit = {
1623
did,
1624
version: 3,
1625
-
data: dataRoot ? new CID(cidToBytes(dataRoot)) : null,
1626
rev,
1627
-
prev: prevCommit?.cid ? new CID(cidToBytes(prevCommit.cid)) : null,
1628
};
1629
1630
// Sign commit
1631
const commitBytes = cborEncodeDagCbor(commit);
1632
const signingKey = await this.getSigningKey();
1633
const sig = await sign(signingKey, commitBytes);
1634
1635
const signedCommit = { ...commit, sig };
···
1660
const newBlocks = [];
1661
newBlocks.push({ cid: commitCidStr, data: signedBytes });
1662
if (dataRoot) {
1663
-
const mstBlocks = this.collectMstBlocks(dataRoot);
1664
newBlocks.push(...mstBlocks);
1665
}
1666
···
1680
);
1681
1682
// Broadcast to subscribers
1683
-
const evtRows = this.sql
1684
.exec(`SELECT * FROM seq_events ORDER BY seq DESC LIMIT 1`)
1685
-
.toArray();
1686
if (evtRows.length > 0) {
1687
this.broadcastEvent(evtRows[0]);
1688
// Forward to default DO for relay subscribers
···
1698
body: JSON.stringify({ ...row, evt: evtArray }),
1699
}),
1700
)
1701
-
.catch(() => {}); // Ignore forward errors
1702
}
1703
}
1704
1705
return { ok: true };
1706
}
1707
1708
formatEvent(evt) {
1709
// AT Protocol frame format: header + body
1710
// Use DAG-CBOR encoding for body (CIDs need tag 42 + 0x00 prefix)
···
1712
1713
// Decode stored event to get ops, blocks, rev, and time
1714
const evtData = cborDecode(new Uint8Array(evt.evt));
1715
-
const ops = evtData.ops.map((op) => ({
1716
...op,
1717
cid: op.cid ? new CID(cidToBytes(op.cid)) : null, // Wrap in CID class for tag 42 encoding
1718
}));
···
1740
return frame;
1741
}
1742
1743
async webSocketMessage(ws, message) {
1744
// Handle ping
1745
if (message === 'ping') ws.send('pong');
1746
}
1747
1748
async webSocketClose(_ws, _code, _reason) {
1749
// Durable Object will hibernate when no connections remain
1750
}
1751
1752
broadcastEvent(evt) {
1753
const frame = this.formatEvent(evt);
1754
for (const ws of this.state.getWebSockets()) {
···
1763
async handleAtprotoDid() {
1764
let did = await this.getDid();
1765
if (!did) {
1766
const registeredDids =
1767
(await this.state.storage.get('registeredDids')) || [];
1768
did = registeredDids[0];
···
1770
if (!did) {
1771
return new Response('User not found', { status: 404 });
1772
}
1773
-
return new Response(did, { headers: { 'Content-Type': 'text/plain' } });
1774
}
1775
1776
async handleInit(request) {
1777
const body = await request.json();
1778
if (!body.did || !body.privateKey) {
···
1801
return Response.json({ ok: true, message: 'repo data cleared' });
1802
}
1803
1804
async handleForwardEvent(request) {
1805
const evt = await request.json();
1806
const numSockets = [...this.state.getWebSockets()].length;
···
1813
return Response.json({ ok: true, sockets: numSockets });
1814
}
1815
1816
async handleRegisterDid(request) {
1817
const body = await request.json();
1818
const registeredDids =
1819
(await this.state.storage.get('registeredDids')) || [];
1820
if (!registeredDids.includes(body.did)) {
···
1830
return Response.json({ dids: registeredDids });
1831
}
1832
1833
async handleRegisterHandle(request) {
1834
const body = await request.json();
1835
const { handle, did } = body;
1836
if (!handle || !did) {
1837
return errorResponse('InvalidRequest', 'missing handle or did', 400);
1838
}
1839
const handleMap = (await this.state.storage.get('handleMap')) || {};
1840
handleMap[handle] = did;
1841
await this.state.storage.put('handleMap', handleMap);
1842
return Response.json({ ok: true });
1843
}
1844
1845
async handleResolveHandle(url) {
1846
const handle = url.searchParams.get('handle');
1847
if (!handle) {
1848
return errorResponse('InvalidRequest', 'missing handle', 400);
1849
}
1850
const handleMap = (await this.state.storage.get('handleMap')) || {};
1851
const did = handleMap[handle];
1852
if (!did) {
···
1861
return Response.json({ head: head || null, rev: rev || null });
1862
}
1863
1864
handleDescribeServer(request) {
1865
const hostname = request.headers.get('x-hostname') || 'localhost';
1866
return Response.json({
···
1873
});
1874
}
1875
1876
async handleCreateSession(request) {
1877
const body = await request.json();
1878
const { identifier, password } = body;
···
1899
let did = identifier;
1900
if (!identifier.startsWith('did:')) {
1901
// Try to resolve handle
1902
const handleMap = (await this.state.storage.get('handleMap')) || {};
1903
did = handleMap[identifier];
1904
if (!did) {
···
1931
});
1932
}
1933
1934
async handleGetSession(request) {
1935
const authHeader = request.headers.get('Authorization');
1936
if (!authHeader || !authHeader.startsWith('Bearer ')) {
···
1962
active: true,
1963
});
1964
} catch (err) {
1965
-
return errorResponse('InvalidToken', err.message, 401);
1966
}
1967
}
1968
1969
async handleRefreshSession(request) {
1970
const authHeader = request.headers.get('Authorization');
1971
if (!authHeader || !authHeader.startsWith('Bearer ')) {
···
2003
active: true,
2004
});
2005
} catch (err) {
2006
-
if (err.message === 'Token expired') {
2007
return errorResponse('ExpiredToken', 'Refresh token has expired', 400);
2008
}
2009
-
return errorResponse('InvalidToken', err.message, 400);
2010
}
2011
}
2012
2013
async handleGetPreferences(_request) {
2014
// Preferences are stored per-user in their DO
2015
const preferences = (await this.state.storage.get('preferences')) || [];
2016
return Response.json({ preferences });
2017
}
2018
2019
async handlePutPreferences(request) {
2020
const body = await request.json();
2021
const { preferences } = body;
···
2030
return Response.json({});
2031
}
2032
2033
async getHandleForDid(did) {
2034
// Check if this DID has a handle registered
2035
const handleMap = (await this.state.storage.get('handleMap')) || {};
2036
for (const [handle, mappedDid] of Object.entries(handleMap)) {
2037
if (mappedDid === did) return handle;
···
2039
// Check instance's own handle
2040
const instanceDid = await this.getDid();
2041
if (instanceDid === did) {
2042
-
return await this.state.storage.get('handle');
2043
}
2044
return null;
2045
}
2046
2047
async createServiceAuthForAppView(did, lxm) {
2048
const signingKey = await this.getSigningKey();
2049
return createServiceJwt({
2050
iss: did,
2051
aud: 'did:web:api.bsky.app',
···
2054
});
2055
}
2056
2057
async handleAppViewProxy(request, userDid) {
2058
const url = new URL(request.url);
2059
// Extract lexicon method from path: /xrpc/app.bsky.actor.getPreferences -> app.bsky.actor.getPreferences
···
2075
'Content-Type',
2076
request.headers.get('Content-Type') || 'application/json',
2077
);
2078
-
if (request.headers.get('Accept')) {
2079
-
headers.set('Accept', request.headers.get('Accept'));
2080
}
2081
-
if (request.headers.get('Accept-Language')) {
2082
-
headers.set('Accept-Language', request.headers.get('Accept-Language'));
2083
}
2084
2085
const proxyReq = new Request(appViewUrl.toString(), {
···
2102
headers: responseHeaders,
2103
});
2104
} catch (err) {
2105
return errorResponse(
2106
'UpstreamFailure',
2107
-
`Failed to reach AppView: ${err.message}`,
2108
502,
2109
);
2110
}
2111
}
2112
2113
async handleListRepos() {
2114
const registeredDids =
2115
(await this.state.storage.get('registeredDids')) || [];
2116
const did = await this.getDid();
2117
const repos = did
2118
? [{ did, head: null, rev: null }]
2119
-
: registeredDids.map((d) => ({ did: d, head: null, rev: null }));
2120
return Response.json({ repos });
2121
}
2122
2123
async handleCreateRecord(request) {
2124
const body = await request.json();
2125
if (!body.collection || !body.record) {
···
2144
validationStatus: 'valid',
2145
});
2146
} catch (err) {
2147
-
return errorResponse('InternalError', err.message, 500);
2148
}
2149
}
2150
2151
async handleDeleteRecord(request) {
2152
const body = await request.json();
2153
if (!body.collection || !body.rkey) {
···
2160
}
2161
return Response.json({});
2162
} catch (err) {
2163
-
return errorResponse('InternalError', err.message, 500);
2164
}
2165
}
2166
2167
async handlePutRecord(request) {
2168
const body = await request.json();
2169
if (!body.collection || !body.rkey || !body.record) {
···
2189
validationStatus: 'valid',
2190
});
2191
} catch (err) {
2192
-
return errorResponse('InternalError', err.message, 500);
2193
}
2194
}
2195
2196
async handleApplyWrites(request) {
2197
const body = await request.json();
2198
if (!body.writes || !Array.isArray(body.writes)) {
···
2244
const rev = await this.state.storage.get('rev');
2245
return Response.json({ commit: { cid: head, rev }, results });
2246
} catch (err) {
2247
-
return errorResponse('InternalError', err.message, 500);
2248
}
2249
}
2250
2251
async handleGetRecord(url) {
2252
const collection = url.searchParams.get('collection');
2253
const rkey = url.searchParams.get('rkey');
···
2256
}
2257
const did = await this.getDid();
2258
const uri = `at://${did}/${collection}/${rkey}`;
2259
-
const rows = this.sql
2260
.exec(`SELECT cid, value FROM records WHERE uri = ?`, uri)
2261
-
.toArray();
2262
if (rows.length === 0) {
2263
return errorResponse('RecordNotFound', 'record not found', 404);
2264
}
···
2288
});
2289
}
2290
2291
async handleListRecords(url) {
2292
const collection = url.searchParams.get('collection');
2293
if (!collection) {
···
2304
const query = `SELECT uri, cid, value FROM records WHERE collection = ? ORDER BY rkey ${reverse ? 'DESC' : 'ASC'} LIMIT ?`;
2305
const params = [collection, limit + 1];
2306
2307
-
const rows = this.sql.exec(query, ...params).toArray();
2308
const hasMore = rows.length > limit;
2309
const records = rows.slice(0, limit).map((r) => ({
2310
uri: r.uri,
···
2319
}
2320
2321
handleGetLatestCommit() {
2322
-
const commits = this.sql
2323
.exec(`SELECT cid, rev FROM commits ORDER BY seq DESC LIMIT 1`)
2324
-
.toArray();
2325
if (commits.length === 0) {
2326
return errorResponse('RepoNotFound', 'repo not found', 404);
2327
}
···
2330
2331
async handleGetRepoStatus() {
2332
const did = await this.getDid();
2333
-
const commits = this.sql
2334
.exec(`SELECT cid, rev FROM commits ORDER BY seq DESC LIMIT 1`)
2335
-
.toArray();
2336
if (commits.length === 0 || !did) {
2337
return errorResponse('RepoNotFound', 'repo not found', 404);
2338
}
···
2345
}
2346
2347
handleGetRepo() {
2348
-
const commits = this.sql
2349
.exec(`SELECT cid FROM commits ORDER BY seq DESC LIMIT 1`)
2350
-
.toArray();
2351
if (commits.length === 0) {
2352
return errorResponse('RepoNotFound', 'repo not found', 404);
2353
}
···
2357
const neededCids = new Set();
2358
2359
// Helper to get block data
2360
const getBlock = (cid) => {
2361
-
const rows = this.sql
2362
.exec(`SELECT data FROM blocks WHERE cid = ?`, cid)
2363
-
.toArray();
2364
return rows.length > 0 ? new Uint8Array(rows[0].data) : null;
2365
};
2366
2367
// Collect all reachable blocks starting from commit
2368
const collectBlocks = (cid) => {
2369
if (neededCids.has(cid)) return;
2370
neededCids.add(cid);
···
2412
}
2413
2414
const car = buildCarFile(commitCid, blocksForCar);
2415
-
return new Response(car, {
2416
headers: { 'content-type': 'application/vnd.ipld.car' },
2417
});
2418
}
2419
2420
async handleSyncGetRecord(url) {
2421
const collection = url.searchParams.get('collection');
2422
const rkey = url.searchParams.get('rkey');
···
2425
}
2426
const did = await this.getDid();
2427
const uri = `at://${did}/${collection}/${rkey}`;
2428
-
const rows = this.sql
2429
.exec(`SELECT cid FROM records WHERE uri = ?`, uri)
2430
-
.toArray();
2431
if (rows.length === 0) {
2432
return errorResponse('RecordNotFound', 'record not found', 404);
2433
}
2434
const recordCid = rows[0].cid;
2435
2436
// Get latest commit
2437
-
const commits = this.sql
2438
.exec(`SELECT cid FROM commits ORDER BY seq DESC LIMIT 1`)
2439
-
.toArray();
2440
if (commits.length === 0) {
2441
return errorResponse('RepoNotFound', 'no commits', 404);
2442
}
···
2444
2445
// Build proof chain: commit -> MST path -> record
2446
// Include commit block, all MST nodes on path to record, and record block
2447
const blocks = [];
2448
const included = new Set();
2449
2450
const addBlock = (cidStr) => {
2451
if (included.has(cidStr)) return;
2452
included.add(cidStr);
2453
-
const blockRows = this.sql
2454
.exec(`SELECT data FROM blocks WHERE cid = ?`, cidStr)
2455
-
.toArray();
2456
if (blockRows.length > 0) {
2457
blocks.push({ cid: cidStr, data: new Uint8Array(blockRows[0].data) });
2458
}
···
2462
addBlock(commitCid);
2463
2464
// Get commit to find data root
2465
-
const commitRows = this.sql
2466
.exec(`SELECT data FROM blocks WHERE cid = ?`, commitCid)
2467
-
.toArray();
2468
if (commitRows.length > 0) {
2469
const commit = cborDecode(new Uint8Array(commitRows[0].data));
2470
if (commit.data) {
···
2481
addBlock(recordCid);
2482
2483
const car = buildCarFile(commitCid, blocks);
2484
-
return new Response(car, {
2485
headers: { 'content-type': 'application/vnd.ipld.car' },
2486
});
2487
}
2488
2489
async handleUploadBlob(request) {
2490
// Require auth
2491
const authHeader = request.headers.get('Authorization');
···
2510
try {
2511
await verifyAccessJwt(token, jwtSecret);
2512
} catch (err) {
2513
-
return errorResponse('InvalidToken', err.message, 401);
2514
}
2515
2516
const did = await this.getDid();
···
2547
2548
// Upload to R2 (idempotent - same CID always has same content)
2549
const r2Key = `${did}/${cidStr}`;
2550
-
await this.env.BLOBS.put(r2Key, bodyBytes, {
2551
httpMetadata: { contentType: mimeType },
2552
});
2553
···
2572
});
2573
}
2574
2575
async handleGetBlob(url) {
2576
const did = url.searchParams.get('did');
2577
const cid = url.searchParams.get('cid');
···
2604
2605
// Fetch from R2
2606
const r2Key = `${did}/${cid}`;
2607
-
const object = await this.env.BLOBS.get(r2Key);
2608
2609
if (!object) {
2610
return errorResponse('BlobNotFound', 'blob not found in storage', 404);
···
2613
// Return blob with security headers
2614
return new Response(object.body, {
2615
headers: {
2616
-
'Content-Type': mimeType,
2617
'Content-Length': String(size),
2618
'X-Content-Type-Options': 'nosniff',
2619
'Content-Security-Policy': "default-src 'none'; sandbox",
···
2622
});
2623
}
2624
2625
async handleListBlobs(url) {
2626
const did = url.searchParams.get('did');
2627
const cursor = url.searchParams.get('cursor');
···
2666
});
2667
}
2668
2669
handleSubscribeRepos(request, url) {
2670
const upgradeHeader = request.headers.get('Upgrade');
2671
if (upgradeHeader !== 'websocket') {
···
2675
this.state.acceptWebSocket(server);
2676
const cursor = url.searchParams.get('cursor');
2677
if (cursor) {
2678
-
const events = this.sql
2679
.exec(
2680
`SELECT * FROM seq_events WHERE seq > ? ORDER BY seq`,
2681
parseInt(cursor, 10),
2682
)
2683
-
.toArray();
2684
for (const evt of events) {
2685
server.send(this.formatEvent(evt));
2686
}
···
2688
return new Response(null, { status: 101, webSocket: client });
2689
}
2690
2691
async fetch(request) {
2692
const url = new URL(request.url);
2693
const route = pdsRoutes[url.pathname];
···
2735
.toArray();
2736
2737
for (const { cid } of orphans) {
2738
-
await this.env.BLOBS.delete(`${did}/${cid}`);
2739
this.sql.exec('DELETE FROM blob WHERE cid = ?', cid);
2740
}
2741
2742
}
2743
}
2744
2745
const corsHeaders = {
2746
'Access-Control-Allow-Origin': '*',
2747
'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
···
2749
'Content-Type, Authorization, atproto-accept-labelers, atproto-proxy, x-bsky-topics',
2750
};
2751
2752
function addCorsHeaders(response) {
2753
const newHeaders = new Headers(response.headers);
2754
for (const [key, value] of Object.entries(corsHeaders)) {
···
2762
}
2763
2764
export default {
2765
async fetch(request, env) {
2766
// Handle CORS preflight
2767
if (request.method === 'OPTIONS') {
···
2777
},
2778
};
2779
2780
-
// Extract subdomain from hostname (e.g., "alice" from "alice.foo.workers.dev")
2781
function getSubdomain(hostname) {
2782
const parts = hostname.split('.');
2783
// workers.dev domains: [subdomain?].[worker-name].[account].workers.dev
···
2793
/**
2794
* Verify auth and return DID from token
2795
* @param {Request} request - HTTP request with Authorization header
2796
-
* @param {Object} env - Environment with JWT_SECRET
2797
* @returns {Promise<{did: string} | {error: Response}>} DID or error response
2798
*/
2799
async function requireAuth(request, env) {
···
2828
const payload = await verifyAccessJwt(token, jwtSecret);
2829
return { did: payload.sub };
2830
} catch (err) {
2831
return {
2832
error: Response.json(
2833
{
2834
error: 'InvalidToken',
2835
-
message: err.message,
2836
},
2837
{ status: 401 },
2838
),
···
2840
}
2841
}
2842
2843
async function handleAuthenticatedBlobUpload(request, env) {
2844
const auth = await requireAuth(request, env);
2845
-
if (auth.error) return auth.error;
2846
2847
// Route to the user's DO based on their DID from the token
2848
const id = env.PDS.idFromName(auth.did);
···
2850
return pds.fetch(request);
2851
}
2852
2853
async function handleAuthenticatedRepoWrite(request, env) {
2854
const auth = await requireAuth(request, env);
2855
-
if (auth.error) return auth.error;
2856
2857
const body = await request.json();
2858
const repo = body.repo;
···
2883
return response;
2884
}
2885
2886
async function handleRequest(request, env) {
2887
const url = new URL(request.url);
2888
const subdomain = getSubdomain(url.hostname);
···
2945
if (url.pathname.startsWith('/xrpc/app.bsky.')) {
2946
// Authenticate the user first
2947
const auth = await requireAuth(request, env);
2948
-
if (auth.error) return auth.error;
2949
2950
// Route to the user's DO instance to create service auth and proxy
2951
const id = env.PDS.idFromName(auth.did);
···
1
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
2
+
// ║ ║
3
+
// ║ ██████╗ ██████╗ ███████╗ Personal Data Server ║
4
+
// ║ ██╔══██╗██╔══██╗██╔════╝ for AT Protocol ║
5
+
// ║ ██████╔╝██║ ██║███████╗ ║
6
+
// ║ ██╔═══╝ ██║ ██║╚════██║ ║
7
+
// ║ ██║ ██████╔╝███████║ ║
8
+
// ║ ╚═╝ ╚═════╝ ╚══════╝ ║
9
+
// ║ ║
10
+
// ╠══════════════════════════════════════════════════════════════════════════════╣
11
+
// ║ ║
12
+
// ║ A single-file ATProto PDS for Cloudflare Workers + Durable Objects ║
13
+
// ║ ║
14
+
// ║ Features: ║
15
+
// ║ • CBOR/DAG-CBOR encoding for content-addressed data ║
16
+
// ║ • CID generation (CIDv1 with dag-cbor + sha-256) ║
17
+
// ║ • Merkle Search Tree (MST) for repository structure ║
18
+
// ║ • P-256 signing with low-S normalization ║
19
+
// ║ • JWT authentication (access, refresh, service tokens) ║
20
+
// ║ • CAR file building for repo sync ║
21
+
// ║ • R2 blob storage with MIME detection ║
22
+
// ║ • SQLite persistence via Durable Objects ║
23
+
// ║ ║
24
+
// ║ @see https://atproto.com ║
25
+
// ║ ║
26
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
27
+
28
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
29
+
// ║ TYPES & CONSTANTS ║
30
+
// ║ Environment bindings, SQL row types, protocol constants ║
31
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
32
33
// CBOR primitive markers (RFC 8949)
34
const CBOR_FALSE = 0xf4;
35
const CBOR_TRUE = 0xf5;
···
38
// DAG-CBOR CID link tag
39
const CBOR_TAG_CID = 42;
40
41
+
// CID codec constants
42
+
const CODEC_DAG_CBOR = 0x71;
43
+
const CODEC_RAW = 0x55;
44
+
45
+
// TID generation constants
46
+
const TID_CHARS = '234567abcdefghijklmnopqrstuvwxyz';
47
+
let lastTimestamp = 0;
48
+
const clockId = Math.floor(Math.random() * 1024);
49
+
50
+
// P-256 curve order N (for low-S signature normalization)
51
+
const P256_N = BigInt(
52
+
'0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551',
53
+
);
54
+
const P256_N_DIV_2 = P256_N / 2n;
55
+
56
+
// Crawler notification throttle
57
+
const CRAWL_NOTIFY_THRESHOLD = 20 * 60 * 1000; // 20 minutes (matches official PDS)
58
+
let lastCrawlNotify = 0;
59
+
60
+
/**
61
+
* Cloudflare Workers environment bindings
62
+
* @typedef {Object} Env
63
+
* @property {string} JWT_SECRET - Secret for signing/verifying session JWTs
64
+
* @property {string} [RELAY_HOST] - Relay host to notify of repo updates (e.g., bsky.network)
65
+
* @property {string} [APPVIEW_URL] - AppView URL for proxying app.bsky.* requests
66
+
* @property {string} [APPVIEW_DID] - AppView DID for service auth
67
+
* @property {string} [PDS_PASSWORD] - Password for createSession authentication
68
+
* @property {DurableObjectNamespace} PDS - Durable Object namespace for PDS instances
69
+
* @property {R2Bucket} [BLOB_BUCKET] - R2 bucket for blob storage (legacy name)
70
+
* @property {R2Bucket} [BLOBS] - R2 bucket for blob storage
71
+
*/
72
+
73
+
/**
74
+
* Row from the `blocks` table - stores raw CBOR-encoded data blocks
75
+
* @typedef {Object} BlockRow
76
+
* @property {string} cid - Content ID (CIDv1 base32lower)
77
+
* @property {ArrayBuffer} data - Raw block data (CBOR-encoded)
78
+
*/
79
+
80
+
/**
81
+
* Row from the `records` table - indexes AT Protocol records
82
+
* @typedef {Object} RecordRow
83
+
* @property {string} uri - AT URI (at://did/collection/rkey)
84
+
* @property {string} cid - Content ID of the record block
85
+
* @property {string} collection - Collection NSID (e.g., app.bsky.feed.post)
86
+
* @property {string} rkey - Record key within collection
87
+
* @property {ArrayBuffer} value - CBOR-encoded record value
88
+
*/
89
+
90
+
/**
91
+
* Row from the `commits` table - tracks repo commit history
92
+
* @typedef {Object} CommitRow
93
+
* @property {string} cid - Content ID of the signed commit block
94
+
* @property {string} rev - Revision TID for ordering
95
+
* @property {string|null} prev - Previous commit CID (null for first commit)
96
+
*/
97
+
98
+
/**
99
+
* Row from the `seq_events` table - stores firehose events for subscribeRepos
100
+
* @typedef {Object} SeqEventRow
101
+
* @property {number} seq - Sequence number for cursor-based pagination
102
+
* @property {string} did - DID of the repo that changed
103
+
* @property {string} commit_cid - CID of the commit
104
+
* @property {ArrayBuffer|Uint8Array} evt - CBOR-encoded event with ops, blocks, rev, time
105
+
*/
106
+
107
+
/**
108
+
* Row from the `blob` table - tracks uploaded blob metadata
109
+
* @typedef {Object} BlobRow
110
+
* @property {string} cid - Content ID of the blob (raw codec)
111
+
* @property {string} mimeType - MIME type (sniffed or from Content-Type header)
112
+
* @property {number} size - Size in bytes
113
+
* @property {string} createdAt - ISO timestamp of upload
114
+
*/
115
+
116
+
/**
117
+
* Decoded JWT payload for session tokens
118
+
* @typedef {Object} JwtPayload
119
+
* @property {string} [scope] - Token scope (e.g., "com.atproto.access")
120
+
* @property {string} sub - Subject DID (the authenticated user)
121
+
* @property {string} [aud] - Audience (for refresh tokens, should match sub)
122
+
* @property {number} [iat] - Issued-at timestamp (Unix seconds)
123
+
* @property {number} [exp] - Expiration timestamp (Unix seconds)
124
+
* @property {string} [jti] - Unique token identifier
125
+
*/
126
+
127
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
128
+
// ║ UTILITIES ║
129
+
// ║ Error responses, byte conversion, base encoding ║
130
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
131
+
132
+
/**
133
+
* @param {string} error - Error code
134
+
* @param {string} message - Error message
135
+
* @param {number} status - HTTP status code
136
+
* @returns {Response}
137
+
*/
138
function errorResponse(error, message, status) {
139
return Response.json({ error, message }, { status });
140
}
141
142
+
/**
143
+
* Convert bytes to hexadecimal string
144
+
* @param {Uint8Array} bytes - Bytes to convert
145
+
* @returns {string} Hex string
146
+
*/
147
+
export function bytesToHex(bytes) {
148
+
return Array.from(bytes)
149
+
.map((b) => b.toString(16).padStart(2, '0'))
150
+
.join('');
151
+
}
152
153
/**
154
+
* Convert hexadecimal string to bytes
155
+
* @param {string} hex - Hex string
156
+
* @returns {Uint8Array} Decoded bytes
157
*/
158
+
export function hexToBytes(hex) {
159
+
const bytes = new Uint8Array(hex.length / 2);
160
+
for (let i = 0; i < hex.length; i += 2) {
161
+
bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
162
}
163
+
return bytes;
164
+
}
165
166
+
/**
167
+
* @param {Uint8Array} bytes
168
+
* @returns {bigint}
169
+
*/
170
+
function bytesToBigInt(bytes) {
171
+
let result = 0n;
172
+
for (const byte of bytes) {
173
+
result = (result << 8n) | BigInt(byte);
174
}
175
+
return result;
176
+
}
177
178
+
/**
179
+
* @param {bigint} n
180
+
* @param {number} length
181
+
* @returns {Uint8Array}
182
+
*/
183
+
function bigIntToBytes(n, length) {
184
+
const bytes = new Uint8Array(length);
185
+
for (let i = length - 1; i >= 0; i--) {
186
+
bytes[i] = Number(n & 0xffn);
187
+
n >>= 8n;
188
}
189
+
return bytes;
190
+
}
191
192
+
/**
193
+
* Encode bytes as base32lower string
194
+
* @param {Uint8Array} bytes - Bytes to encode
195
+
* @returns {string} Base32lower-encoded string
196
+
*/
197
+
export function base32Encode(bytes) {
198
+
const alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
199
+
let result = '';
200
+
let bits = 0;
201
+
let value = 0;
202
203
+
for (const byte of bytes) {
204
+
value = (value << 8) | byte;
205
+
bits += 8;
206
+
while (bits >= 5) {
207
+
bits -= 5;
208
+
result += alphabet[(value >> bits) & 31];
209
}
210
}
211
212
+
if (bits > 0) {
213
+
result += alphabet[(value << (5 - bits)) & 31];
214
+
}
215
216
+
return result;
217
+
}
218
219
/**
220
+
* Decode base32lower string to bytes
221
+
* @param {string} str - Base32lower-encoded string
222
+
* @returns {Uint8Array} Decoded bytes
223
*/
224
+
export function base32Decode(str) {
225
+
const alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
226
+
let bits = 0;
227
+
let value = 0;
228
+
const output = [];
229
230
+
for (const char of str) {
231
+
const idx = alphabet.indexOf(char);
232
+
if (idx === -1) continue;
233
+
value = (value << 5) | idx;
234
+
bits += 5;
235
+
if (bits >= 8) {
236
+
bits -= 8;
237
+
output.push((value >> bits) & 0xff);
238
}
239
}
240
241
+
return new Uint8Array(output);
242
}
243
244
+
/**
245
+
* Encode bytes as base64url string (no padding)
246
+
* @param {Uint8Array} bytes - Bytes to encode
247
+
* @returns {string} Base64url-encoded string
248
+
*/
249
+
export function base64UrlEncode(bytes) {
250
+
let binary = '';
251
+
for (const byte of bytes) {
252
+
binary += String.fromCharCode(byte);
253
}
254
+
const base64 = btoa(binary);
255
+
return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
256
+
}
257
258
+
/**
259
+
* Decode base64url string to bytes
260
+
* @param {string} str - Base64url-encoded string
261
+
* @returns {Uint8Array} Decoded bytes
262
+
*/
263
+
export function base64UrlDecode(str) {
264
+
const base64 = str.replace(/-/g, '+').replace(/_/g, '/');
265
+
const pad = base64.length % 4;
266
+
const padded = pad ? base64 + '='.repeat(4 - pad) : base64;
267
+
const binary = atob(padded);
268
+
const bytes = new Uint8Array(binary.length);
269
+
for (let i = 0; i < binary.length; i++) {
270
+
bytes[i] = binary.charCodeAt(i);
271
+
}
272
+
return bytes;
273
+
}
274
275
+
/**
276
+
* Encode integer as unsigned varint
277
+
* @param {number} n - Non-negative integer
278
+
* @returns {Uint8Array} Varint-encoded bytes
279
+
*/
280
+
export function varint(n) {
281
+
const bytes = [];
282
+
while (n >= 0x80) {
283
+
bytes.push((n & 0x7f) | 0x80);
284
+
n >>>= 7;
285
+
}
286
+
bytes.push(n);
287
+
return new Uint8Array(bytes);
288
}
289
290
// === CID WRAPPER ===
291
// Explicit CID type for DAG-CBOR encoding (avoids fragile heuristic detection)
292
293
class CID {
294
+
/** @param {Uint8Array} bytes */
295
constructor(bytes) {
296
if (!(bytes instanceof Uint8Array)) {
297
throw new Error('CID must be constructed with Uint8Array');
···
300
}
301
}
302
303
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
304
+
// ║ CBOR ENCODING ║
305
+
// ║ RFC 8949 CBOR and DAG-CBOR for content-addressed data ║
306
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
307
308
/**
309
* Encode CBOR type header (major type + length)
···
337
* @returns {Uint8Array} CBOR-encoded bytes
338
*/
339
export function cborEncode(value) {
340
+
/** @type {number[]} */
341
const parts = [];
342
343
+
/** @param {*} val */
344
function encode(val) {
345
if (val === null) {
346
parts.push(CBOR_NULL);
···
371
}
372
}
373
374
+
/** @param {number} n */
375
function encodeInteger(n) {
376
if (n >= 0) {
377
encodeHead(parts, 0, n); // major type 0 = unsigned int
···
384
return new Uint8Array(parts);
385
}
386
387
+
/**
388
+
* DAG-CBOR encoder that handles CIDs with tag 42
389
+
* @param {*} value
390
+
* @returns {Uint8Array}
391
+
*/
392
function cborEncodeDagCbor(value) {
393
+
/** @type {number[]} */
394
const parts = [];
395
396
+
/** @param {*} val */
397
function encode(val) {
398
if (val === null) {
399
parts.push(CBOR_NULL);
···
455
export function cborDecode(bytes) {
456
let offset = 0;
457
458
+
/** @returns {*} */
459
function read() {
460
const initial = bytes[offset++];
461
const major = initial >> 5;
···
501
}
502
case 5: {
503
// map
504
+
/** @type {Record<string, *>} */
505
const obj = {};
506
for (let i = 0; i < length; i++) {
507
+
const key = /** @type {string} */ (read());
508
obj[key] = read();
509
}
510
return obj;
···
532
return read();
533
}
534
535
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
536
+
// ║ CONTENT IDENTIFIERS ║
537
+
// ║ CIDs (content hashes) and TIDs (timestamp IDs) ║
538
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
539
540
/**
541
* Create a CIDv1 with SHA-256 hash
···
544
* @returns {Promise<Uint8Array>} CID bytes (36 bytes: version + codec + multihash)
545
*/
546
async function createCidWithCodec(bytes, codec) {
547
+
const hash = await crypto.subtle.digest('SHA-256', /** @type {BufferSource} */(bytes));
548
const hashBytes = new Uint8Array(hash);
549
550
// CIDv1: version(1) + codec + multihash(sha256)
···
588
}
589
590
/**
591
+
* Convert base32lower CID string to raw bytes
592
+
* @param {string} cidStr - CID string with 'b' prefix
593
+
* @returns {Uint8Array} CID bytes
594
*/
595
+
export function cidToBytes(cidStr) {
596
+
// Decode base32lower CID string to bytes
597
+
if (!cidStr.startsWith('b')) throw new Error('expected base32lower CID');
598
+
return base32Decode(cidStr.slice(1));
599
}
600
601
/**
602
* Generate a timestamp-based ID (TID) for record keys
603
* Monotonic within a process, sortable by time
···
629
return tid;
630
}
631
632
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
633
+
// ║ CRYPTOGRAPHY ║
634
+
// ║ P-256 signing with low-S normalization, key management ║
635
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
636
+
637
+
/**
638
+
* @param {BufferSource} data
639
+
* @returns {Promise<Uint8Array>}
640
+
*/
641
+
async function sha256(data) {
642
+
const hash = await crypto.subtle.digest('SHA-256', data);
643
+
return new Uint8Array(hash);
644
+
}
645
646
/**
647
* Import a raw P-256 private key for signing
···
672
673
return crypto.subtle.importKey(
674
'pkcs8',
675
+
/** @type {BufferSource} */(pkcs8),
676
{ name: 'ECDSA', namedCurve: 'P-256' },
677
false,
678
['sign'],
679
);
680
}
681
682
/**
683
* Sign data with ECDSA P-256, returning low-S normalized signature
684
* @param {CryptoKey} privateKey - Web Crypto key from importPrivateKey
···
689
const signature = await crypto.subtle.sign(
690
{ name: 'ECDSA', hash: 'SHA-256' },
691
privateKey,
692
+
/** @type {BufferSource} */(data),
693
);
694
const sig = new Uint8Array(signature);
695
···
724
725
// Export private key as raw bytes
726
const privateJwk = await crypto.subtle.exportKey('jwk', keyPair.privateKey);
727
+
const privateBytes = base64UrlDecode(/** @type {string} */(privateJwk.d));
728
729
// Export public key as compressed point
730
const publicRaw = await crypto.subtle.exportKey('raw', keyPair.publicKey);
···
734
return { privateKey: privateBytes, publicKey: compressed };
735
}
736
737
+
/**
738
+
* @param {Uint8Array} uncompressed
739
+
* @returns {Uint8Array}
740
+
*/
741
function compressPublicKey(uncompressed) {
742
// uncompressed is 65 bytes: 0x04 + x(32) + y(32)
743
// compressed is 33 bytes: prefix(02 or 03) + x(32)
···
750
return compressed;
751
}
752
753
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
754
+
// ║ AUTHENTICATION ║
755
+
// ║ JWT creation/verification for sessions and service auth ║
756
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
757
758
/**
759
* Create HMAC-SHA256 signature for JWT
···
764
async function hmacSign(data, secret) {
765
const key = await crypto.subtle.importKey(
766
'raw',
767
+
/** @type {BufferSource} */(new TextEncoder().encode(secret)),
768
{ name: 'HMAC', hash: 'SHA-256' },
769
false,
770
['sign'],
···
772
const sig = await crypto.subtle.sign(
773
'HMAC',
774
key,
775
+
/** @type {BufferSource} */(new TextEncoder().encode(data)),
776
);
777
return base64UrlEncode(new Uint8Array(sig));
778
}
···
846
* @param {string} jwt - JWT string to verify
847
* @param {string} secret - JWT signing secret
848
* @param {string} expectedType - Expected token type (e.g., 'at+jwt', 'refresh+jwt')
849
+
* @returns {Promise<{header: {typ: string, alg: string}, payload: JwtPayload}>} Decoded header and payload
850
* @throws {Error} If token is invalid, expired, or wrong type
851
*/
852
async function verifyJwt(jwt, secret, expectedType) {
···
889
* Verify and decode an access JWT
890
* @param {string} jwt - JWT string to verify
891
* @param {string} secret - JWT signing secret
892
+
* @returns {Promise<JwtPayload>} Decoded payload
893
* @throws {Error} If token is invalid, expired, or wrong type
894
*/
895
export async function verifyAccessJwt(jwt, secret) {
···
901
* Verify and decode a refresh JWT
902
* @param {string} jwt - JWT string to verify
903
* @param {string} secret - JWT signing secret
904
+
* @returns {Promise<JwtPayload>} Decoded payload
905
* @throws {Error} If token is invalid, expired, or wrong type
906
*/
907
export async function verifyRefreshJwt(jwt, secret) {
···
934
crypto.getRandomValues(jtiBytes);
935
const jti = bytesToHex(jtiBytes);
936
937
+
/** @type {{ iss: string, aud: string, exp: number, iat: number, jti: string, lxm?: string }} */
938
const payload = {
939
iss,
940
aud,
···
958
return `${headerB64}.${payloadB64}.${sigB64}`;
959
}
960
961
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
962
+
// ║ MERKLE SEARCH TREE ║
963
+
// ║ MST for ATProto repository structure ║
964
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
965
966
// Cache for key depths (SHA-256 is expensive)
967
const keyDepthCache = new Map();
···
1000
return depth;
1001
}
1002
1003
+
/**
1004
+
* Compute common prefix length between two byte arrays
1005
+
* @param {Uint8Array} a
1006
+
* @param {Uint8Array} b
1007
+
* @returns {number}
1008
+
*/
1009
function commonPrefixLen(a, b) {
1010
const minLen = Math.min(a.length, b.length);
1011
for (let i = 0; i < minLen; i++) {
···
1015
}
1016
1017
class MST {
1018
+
/** @param {SqlStorage} sql */
1019
constructor(sql) {
1020
this.sql = sql;
1021
}
···
1043
entries.push({
1044
key,
1045
keyBytes: new TextEncoder().encode(key),
1046
+
cid: /** @type {string} */ (r.cid),
1047
depth,
1048
});
1049
}
···
1052
return this.buildTree(entries, maxDepth);
1053
}
1054
1055
+
/**
1056
+
* @param {Array<{key: string, keyBytes: Uint8Array, cid: string, depth: number}>} entries
1057
+
* @param {number} layer
1058
+
* @returns {Promise<string|null>}
1059
+
*/
1060
async buildTree(entries, layer) {
1061
if (entries.length === 0) return null;
1062
1063
// Separate entries for this layer vs lower layers (subtrees)
1064
// Keys with depth == layer stay at this node
1065
// Keys with depth < layer go into subtrees (going down toward layer 0)
1066
+
/** @type {Array<{type: 'subtree', cid: string|null} | {type: 'entry', entry: {key: string, keyBytes: Uint8Array, cid: string, depth: number}}>} */
1067
const thisLayer = [];
1068
+
/** @type {Array<{key: string, keyBytes: Uint8Array, cid: string, depth: number}>} */
1069
let leftSubtree = [];
1070
1071
for (const entry of entries) {
···
1091
}
1092
1093
// Build node with proper ATProto format
1094
+
/** @type {{ e: Array<{p: number, k: Uint8Array, v: CID, t: CID|null}>, l?: CID|null }} */
1095
const node = { e: [] };
1096
+
/** @type {string|null} */
1097
let leftCid = null;
1098
let prevKeyBytes = new Uint8Array(0);
1099
···
1105
leftCid = item.cid;
1106
} else {
1107
// Attach to previous entry's 't' field
1108
+
if (item.cid !== null) {
1109
+
node.e[node.e.length - 1].t = new CID(cidToBytes(item.cid));
1110
+
}
1111
}
1112
} else {
1113
// Entry - compute prefix compression
···
1124
};
1125
1126
node.e.push(e);
1127
+
prevKeyBytes = /** @type {Uint8Array<ArrayBuffer>} */ (keyBytes);
1128
}
1129
}
1130
···
1146
}
1147
}
1148
1149
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
1150
+
// ║ CAR FILES ║
1151
+
// ║ Content Addressable aRchive format for repo sync ║
1152
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
1153
1154
/**
1155
* Build a CAR (Content Addressable aRchive) file
···
1190
return car;
1191
}
1192
1193
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
1194
+
// ║ BLOB HANDLING ║
1195
+
// ║ MIME detection, blob reference scanning ║
1196
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
1197
+
1198
+
/**
1199
+
* Sniff MIME type from file magic bytes
1200
+
* @param {Uint8Array|ArrayBuffer} bytes - File bytes (only first 12 needed)
1201
+
* @returns {string|null} Detected MIME type or null if unknown
1202
+
*/
1203
+
export function sniffMimeType(bytes) {
1204
+
const arr = new Uint8Array(bytes.slice(0, 12));
1205
+
1206
+
// JPEG: FF D8 FF
1207
+
if (arr[0] === 0xff && arr[1] === 0xd8 && arr[2] === 0xff) {
1208
+
return 'image/jpeg';
1209
+
}
1210
+
1211
+
// PNG: 89 50 4E 47 0D 0A 1A 0A
1212
+
if (
1213
+
arr[0] === 0x89 &&
1214
+
arr[1] === 0x50 &&
1215
+
arr[2] === 0x4e &&
1216
+
arr[3] === 0x47 &&
1217
+
arr[4] === 0x0d &&
1218
+
arr[5] === 0x0a &&
1219
+
arr[6] === 0x1a &&
1220
+
arr[7] === 0x0a
1221
+
) {
1222
+
return 'image/png';
1223
+
}
1224
+
1225
+
// GIF: 47 49 46 38 (GIF8)
1226
+
if (
1227
+
arr[0] === 0x47 &&
1228
+
arr[1] === 0x49 &&
1229
+
arr[2] === 0x46 &&
1230
+
arr[3] === 0x38
1231
+
) {
1232
+
return 'image/gif';
1233
+
}
1234
+
1235
+
// WebP: RIFF....WEBP
1236
+
if (
1237
+
arr[0] === 0x52 &&
1238
+
arr[1] === 0x49 &&
1239
+
arr[2] === 0x46 &&
1240
+
arr[3] === 0x46 &&
1241
+
arr[8] === 0x57 &&
1242
+
arr[9] === 0x45 &&
1243
+
arr[10] === 0x42 &&
1244
+
arr[11] === 0x50
1245
+
) {
1246
+
return 'image/webp';
1247
+
}
1248
+
1249
+
// ISOBMFF container: ....ftyp at byte 4 (MP4, AVIF, HEIC, etc.)
1250
+
if (
1251
+
arr[4] === 0x66 &&
1252
+
arr[5] === 0x74 &&
1253
+
arr[6] === 0x79 &&
1254
+
arr[7] === 0x70
1255
+
) {
1256
+
// Check brand code at bytes 8-11
1257
+
const brand = String.fromCharCode(arr[8], arr[9], arr[10], arr[11]);
1258
+
if (brand === 'avif') {
1259
+
return 'image/avif';
1260
+
}
1261
+
if (brand === 'heic' || brand === 'heix' || brand === 'mif1') {
1262
+
return 'image/heic';
1263
+
}
1264
+
return 'video/mp4';
1265
+
}
1266
+
1267
+
return null;
1268
+
}
1269
+
1270
+
/**
1271
+
* Find all blob CID references in a record
1272
+
* @param {*} obj - Record value to scan
1273
+
* @param {string[]} refs - Accumulator array (internal)
1274
+
* @returns {string[]} Array of blob CID strings
1275
+
*/
1276
+
export function findBlobRefs(obj, refs = []) {
1277
+
if (!obj || typeof obj !== 'object') {
1278
+
return refs;
1279
+
}
1280
+
1281
+
// Check if this object is a blob ref
1282
+
if (obj.$type === 'blob' && obj.ref?.$link) {
1283
+
refs.push(obj.ref.$link);
1284
+
}
1285
+
1286
+
// Recurse into arrays and objects
1287
+
if (Array.isArray(obj)) {
1288
+
for (const item of obj) {
1289
+
findBlobRefs(item, refs);
1290
+
}
1291
+
} else {
1292
+
for (const value of Object.values(obj)) {
1293
+
findBlobRefs(value, refs);
1294
+
}
1295
+
}
1296
+
1297
+
return refs;
1298
+
}
1299
+
1300
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
1301
+
// ║ RELAY NOTIFICATION ║
1302
+
// ║ Notify relays to crawl after repo updates ║
1303
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
1304
+
1305
+
/**
1306
+
* Notify relays to come crawl us after writes (like official PDS)
1307
+
* @param {{ RELAY_HOST?: string }} env
1308
+
* @param {string} hostname
1309
+
*/
1310
+
async function notifyCrawlers(env, hostname) {
1311
+
const now = Date.now();
1312
+
if (now - lastCrawlNotify < CRAWL_NOTIFY_THRESHOLD) {
1313
+
return; // Throttle notifications
1314
+
}
1315
+
1316
+
const relayHost = env.RELAY_HOST;
1317
+
if (!relayHost) return;
1318
+
1319
+
lastCrawlNotify = now;
1320
+
1321
+
// Fire and forget - don't block writes on relay notification
1322
+
fetch(`${relayHost}/xrpc/com.atproto.sync.requestCrawl`, {
1323
+
method: 'POST',
1324
+
headers: { 'Content-Type': 'application/json' },
1325
+
body: JSON.stringify({ hostname }),
1326
+
}).catch(() => {
1327
+
// Silently ignore relay notification failures
1328
+
});
1329
+
}
1330
+
1331
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
1332
+
// ║ ROUTING ║
1333
+
// ║ XRPC endpoint definitions ║
1334
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
1335
+
1336
/**
1337
* Route handler function type
1338
* @callback RouteHandler
1339
* @param {PersonalDataServer} pds - PDS instance
1340
* @param {Request} request - HTTP request
1341
* @param {URL} url - Parsed URL
1342
+
* @returns {Response | Promise<Response>} HTTP response
1343
*/
1344
1345
/**
1346
+
* Route definition for the PDS router
1347
* @typedef {Object} Route
1348
* @property {string} [method] - Required HTTP method (default: any)
1349
* @property {RouteHandler} handler - Handler function
···
1459
},
1460
};
1461
1462
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
1463
+
// ║ PERSONAL DATA SERVER ║
1464
+
// ║ Durable Object class implementing ATProto PDS ║
1465
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
1466
+
1467
export class PersonalDataServer {
1468
+
/** @type {string | undefined} */
1469
+
_did;
1470
+
1471
+
/**
1472
+
* @param {DurableObjectState} state
1473
+
* @param {Env} env
1474
+
*/
1475
constructor(state, env) {
1476
this.state = state;
1477
this.sql = state.storage.sql;
···
1525
`);
1526
}
1527
1528
+
/**
1529
+
* @param {string} did
1530
+
* @param {string} privateKeyHex
1531
+
* @param {string|null} [handle]
1532
+
*/
1533
async initIdentity(did, privateKeyHex, handle = null) {
1534
await this.state.storage.put('did', did);
1535
await this.state.storage.put('privateKey', privateKeyHex);
···
1558
async getSigningKey() {
1559
const hex = await this.state.storage.get('privateKey');
1560
if (!hex) return null;
1561
+
return importPrivateKey(hexToBytes(/** @type {string} */(hex)));
1562
}
1563
1564
+
/**
1565
+
* Collect MST node blocks for a given root CID
1566
+
* @param {string} rootCidStr
1567
+
* @returns {Array<{cid: string, data: Uint8Array}>}
1568
+
*/
1569
collectMstBlocks(rootCidStr) {
1570
+
/** @type {Array<{cid: string, data: Uint8Array}>} */
1571
const blocks = [];
1572
const visited = new Set();
1573
1574
+
/** @param {string} cidStr */
1575
const collect = (cidStr) => {
1576
if (visited.has(cidStr)) return;
1577
visited.add(cidStr);
1578
1579
+
const rows = /** @type {BlockRow[]} */ (this.sql
1580
.exec(`SELECT data FROM blocks WHERE cid = ?`, cidStr)
1581
+
.toArray());
1582
if (rows.length === 0) return;
1583
1584
const data = new Uint8Array(rows[0].data);
···
1602
return blocks;
1603
}
1604
1605
+
/**
1606
+
* @param {string} collection
1607
+
* @param {Record<string, *>} record
1608
+
* @param {string|null} [rkey]
1609
+
* @returns {Promise<{uri: string, cid: string, commit: string}>}
1610
+
*/
1611
async createRecord(collection, record, rkey = null) {
1612
const did = await this.getDid();
1613
if (!did) throw new Error('PDS not initialized');
···
1675
const commit = {
1676
did,
1677
version: 3,
1678
+
data: new CID(cidToBytes(/** @type {string} */(dataRoot))), // CID wrapped for explicit encoding
1679
rev,
1680
+
prev: prevCommit?.cid ? new CID(cidToBytes(/** @type {string} */(prevCommit.cid))) : null,
1681
};
1682
1683
// Sign commit (using dag-cbor encoder for CIDs)
1684
const commitBytes = cborEncodeDagCbor(commit);
1685
const signingKey = await this.getSigningKey();
1686
+
if (!signingKey) throw new Error('No signing key');
1687
const sig = await sign(signingKey, commitBytes);
1688
1689
const signedCommit = { ...commit, sig };
···
1718
// Add commit block
1719
newBlocks.push({ cid: commitCidStr, data: signedBytes });
1720
// Add MST node blocks (get all blocks referenced by commit.data)
1721
+
const mstBlocks = this.collectMstBlocks(/** @type {string} */(dataRoot));
1722
newBlocks.push(...mstBlocks);
1723
1724
// Sequence event with blocks - store complete event data including rev and time
···
1740
);
1741
1742
// Broadcast to subscribers (both local and via default DO for relay)
1743
+
const evtRows = /** @type {SeqEventRow[]} */ (this.sql
1744
.exec(`SELECT * FROM seq_events ORDER BY seq DESC LIMIT 1`)
1745
+
.toArray());
1746
if (evtRows.length > 0) {
1747
this.broadcastEvent(evtRows[0]);
1748
// Also forward to default DO for relay subscribers
···
1760
body: JSON.stringify({ ...row, evt: evtArray }),
1761
}),
1762
)
1763
+
.catch(() => { }); // Ignore forward errors
1764
}
1765
}
1766
1767
return { uri, cid: recordCidStr, commit: commitCidStr };
1768
}
1769
1770
+
/**
1771
+
* @param {string} collection
1772
+
* @param {string} rkey
1773
+
*/
1774
async deleteRecord(collection, rkey) {
1775
const did = await this.getDid();
1776
if (!did) throw new Error('PDS not initialized');
···
1804
1805
if (stillReferenced.length === 0) {
1806
// Blob is orphaned, delete from R2 and database
1807
+
await this.env?.BLOBS?.delete(`${did}/${blobCid}`);
1808
this.sql.exec('DELETE FROM blob WHERE cid = ?', blobCid);
1809
}
1810
}
···
1824
const commit = {
1825
did,
1826
version: 3,
1827
+
data: dataRoot ? new CID(cidToBytes(/** @type {string} */(dataRoot))) : null,
1828
rev,
1829
+
prev: prevCommit?.cid ? new CID(cidToBytes(/** @type {string} */(prevCommit.cid))) : null,
1830
};
1831
1832
// Sign commit
1833
const commitBytes = cborEncodeDagCbor(commit);
1834
const signingKey = await this.getSigningKey();
1835
+
if (!signingKey) throw new Error('No signing key');
1836
const sig = await sign(signingKey, commitBytes);
1837
1838
const signedCommit = { ...commit, sig };
···
1863
const newBlocks = [];
1864
newBlocks.push({ cid: commitCidStr, data: signedBytes });
1865
if (dataRoot) {
1866
+
const mstBlocks = this.collectMstBlocks(/** @type {string} */(dataRoot));
1867
newBlocks.push(...mstBlocks);
1868
}
1869
···
1883
);
1884
1885
// Broadcast to subscribers
1886
+
const evtRows = /** @type {SeqEventRow[]} */ (this.sql
1887
.exec(`SELECT * FROM seq_events ORDER BY seq DESC LIMIT 1`)
1888
+
.toArray());
1889
if (evtRows.length > 0) {
1890
this.broadcastEvent(evtRows[0]);
1891
// Forward to default DO for relay subscribers
···
1901
body: JSON.stringify({ ...row, evt: evtArray }),
1902
}),
1903
)
1904
+
.catch(() => { }); // Ignore forward errors
1905
}
1906
}
1907
1908
return { ok: true };
1909
}
1910
1911
+
/**
1912
+
* @param {SeqEventRow} evt
1913
+
* @returns {Uint8Array}
1914
+
*/
1915
formatEvent(evt) {
1916
// AT Protocol frame format: header + body
1917
// Use DAG-CBOR encoding for body (CIDs need tag 42 + 0x00 prefix)
···
1919
1920
// Decode stored event to get ops, blocks, rev, and time
1921
const evtData = cborDecode(new Uint8Array(evt.evt));
1922
+
/** @type {Array<{action: string, path: string, cid: CID|null}>} */
1923
+
const ops = evtData.ops.map((/** @type {{action: string, path: string, cid?: string}} */ op) => ({
1924
...op,
1925
cid: op.cid ? new CID(cidToBytes(op.cid)) : null, // Wrap in CID class for tag 42 encoding
1926
}));
···
1948
return frame;
1949
}
1950
1951
+
/**
1952
+
* @param {WebSocket} ws
1953
+
* @param {string | ArrayBuffer} message
1954
+
*/
1955
async webSocketMessage(ws, message) {
1956
// Handle ping
1957
if (message === 'ping') ws.send('pong');
1958
}
1959
1960
+
/**
1961
+
* @param {WebSocket} _ws
1962
+
* @param {number} _code
1963
+
* @param {string} _reason
1964
+
*/
1965
async webSocketClose(_ws, _code, _reason) {
1966
// Durable Object will hibernate when no connections remain
1967
}
1968
1969
+
/**
1970
+
* @param {SeqEventRow} evt
1971
+
*/
1972
broadcastEvent(evt) {
1973
const frame = this.formatEvent(evt);
1974
for (const ws of this.state.getWebSockets()) {
···
1983
async handleAtprotoDid() {
1984
let did = await this.getDid();
1985
if (!did) {
1986
+
/** @type {string[]} */
1987
const registeredDids =
1988
(await this.state.storage.get('registeredDids')) || [];
1989
did = registeredDids[0];
···
1991
if (!did) {
1992
return new Response('User not found', { status: 404 });
1993
}
1994
+
return new Response(/** @type {string} */(did), { headers: { 'Content-Type': 'text/plain' } });
1995
}
1996
1997
+
/** @param {Request} request */
1998
async handleInit(request) {
1999
const body = await request.json();
2000
if (!body.did || !body.privateKey) {
···
2023
return Response.json({ ok: true, message: 'repo data cleared' });
2024
}
2025
2026
+
/** @param {Request} request */
2027
async handleForwardEvent(request) {
2028
const evt = await request.json();
2029
const numSockets = [...this.state.getWebSockets()].length;
···
2036
return Response.json({ ok: true, sockets: numSockets });
2037
}
2038
2039
+
/** @param {Request} request */
2040
async handleRegisterDid(request) {
2041
const body = await request.json();
2042
+
/** @type {string[]} */
2043
const registeredDids =
2044
(await this.state.storage.get('registeredDids')) || [];
2045
if (!registeredDids.includes(body.did)) {
···
2055
return Response.json({ dids: registeredDids });
2056
}
2057
2058
+
/** @param {Request} request */
2059
async handleRegisterHandle(request) {
2060
const body = await request.json();
2061
const { handle, did } = body;
2062
if (!handle || !did) {
2063
return errorResponse('InvalidRequest', 'missing handle or did', 400);
2064
}
2065
+
/** @type {Record<string, string>} */
2066
const handleMap = (await this.state.storage.get('handleMap')) || {};
2067
handleMap[handle] = did;
2068
await this.state.storage.put('handleMap', handleMap);
2069
return Response.json({ ok: true });
2070
}
2071
2072
+
/** @param {URL} url */
2073
async handleResolveHandle(url) {
2074
const handle = url.searchParams.get('handle');
2075
if (!handle) {
2076
return errorResponse('InvalidRequest', 'missing handle', 400);
2077
}
2078
+
/** @type {Record<string, string>} */
2079
const handleMap = (await this.state.storage.get('handleMap')) || {};
2080
const did = handleMap[handle];
2081
if (!did) {
···
2090
return Response.json({ head: head || null, rev: rev || null });
2091
}
2092
2093
+
/** @param {Request} request */
2094
handleDescribeServer(request) {
2095
const hostname = request.headers.get('x-hostname') || 'localhost';
2096
return Response.json({
···
2103
});
2104
}
2105
2106
+
/** @param {Request} request */
2107
async handleCreateSession(request) {
2108
const body = await request.json();
2109
const { identifier, password } = body;
···
2130
let did = identifier;
2131
if (!identifier.startsWith('did:')) {
2132
// Try to resolve handle
2133
+
/** @type {Record<string, string>} */
2134
const handleMap = (await this.state.storage.get('handleMap')) || {};
2135
did = handleMap[identifier];
2136
if (!did) {
···
2163
});
2164
}
2165
2166
+
/** @param {Request} request */
2167
async handleGetSession(request) {
2168
const authHeader = request.headers.get('Authorization');
2169
if (!authHeader || !authHeader.startsWith('Bearer ')) {
···
2195
active: true,
2196
});
2197
} catch (err) {
2198
+
const message = err instanceof Error ? err.message : String(err);
2199
+
return errorResponse('InvalidToken', message, 401);
2200
}
2201
}
2202
2203
+
/** @param {Request} request */
2204
async handleRefreshSession(request) {
2205
const authHeader = request.headers.get('Authorization');
2206
if (!authHeader || !authHeader.startsWith('Bearer ')) {
···
2238
active: true,
2239
});
2240
} catch (err) {
2241
+
const message = err instanceof Error ? err.message : String(err);
2242
+
if (message === 'Token expired') {
2243
return errorResponse('ExpiredToken', 'Refresh token has expired', 400);
2244
}
2245
+
return errorResponse('InvalidToken', message, 400);
2246
}
2247
}
2248
2249
+
/** @param {Request} _request */
2250
async handleGetPreferences(_request) {
2251
// Preferences are stored per-user in their DO
2252
const preferences = (await this.state.storage.get('preferences')) || [];
2253
return Response.json({ preferences });
2254
}
2255
2256
+
/** @param {Request} request */
2257
async handlePutPreferences(request) {
2258
const body = await request.json();
2259
const { preferences } = body;
···
2268
return Response.json({});
2269
}
2270
2271
+
/**
2272
+
* @param {string} did
2273
+
* @returns {Promise<string|null>}
2274
+
*/
2275
async getHandleForDid(did) {
2276
// Check if this DID has a handle registered
2277
+
/** @type {Record<string, string>} */
2278
const handleMap = (await this.state.storage.get('handleMap')) || {};
2279
for (const [handle, mappedDid] of Object.entries(handleMap)) {
2280
if (mappedDid === did) return handle;
···
2282
// Check instance's own handle
2283
const instanceDid = await this.getDid();
2284
if (instanceDid === did) {
2285
+
return /** @type {string|null} */ (await this.state.storage.get('handle'));
2286
}
2287
return null;
2288
}
2289
2290
+
/**
2291
+
* @param {string} did
2292
+
* @param {string|null} lxm
2293
+
*/
2294
async createServiceAuthForAppView(did, lxm) {
2295
const signingKey = await this.getSigningKey();
2296
+
if (!signingKey) throw new Error('No signing key available');
2297
return createServiceJwt({
2298
iss: did,
2299
aud: 'did:web:api.bsky.app',
···
2302
});
2303
}
2304
2305
+
/**
2306
+
* @param {Request} request
2307
+
* @param {string} userDid
2308
+
*/
2309
async handleAppViewProxy(request, userDid) {
2310
const url = new URL(request.url);
2311
// Extract lexicon method from path: /xrpc/app.bsky.actor.getPreferences -> app.bsky.actor.getPreferences
···
2327
'Content-Type',
2328
request.headers.get('Content-Type') || 'application/json',
2329
);
2330
+
const acceptHeader = request.headers.get('Accept');
2331
+
if (acceptHeader) {
2332
+
headers.set('Accept', acceptHeader);
2333
}
2334
+
const acceptLangHeader = request.headers.get('Accept-Language');
2335
+
if (acceptLangHeader) {
2336
+
headers.set('Accept-Language', acceptLangHeader);
2337
}
2338
2339
const proxyReq = new Request(appViewUrl.toString(), {
···
2356
headers: responseHeaders,
2357
});
2358
} catch (err) {
2359
+
const message = err instanceof Error ? err.message : String(err);
2360
return errorResponse(
2361
'UpstreamFailure',
2362
+
`Failed to reach AppView: ${message}`,
2363
502,
2364
);
2365
}
2366
}
2367
2368
async handleListRepos() {
2369
+
/** @type {string[]} */
2370
const registeredDids =
2371
(await this.state.storage.get('registeredDids')) || [];
2372
const did = await this.getDid();
2373
const repos = did
2374
? [{ did, head: null, rev: null }]
2375
+
: registeredDids.map((/** @type {string} */ d) => ({ did: d, head: null, rev: null }));
2376
return Response.json({ repos });
2377
}
2378
2379
+
/** @param {Request} request */
2380
async handleCreateRecord(request) {
2381
const body = await request.json();
2382
if (!body.collection || !body.record) {
···
2401
validationStatus: 'valid',
2402
});
2403
} catch (err) {
2404
+
const message = err instanceof Error ? err.message : String(err);
2405
+
return errorResponse('InternalError', message, 500);
2406
}
2407
}
2408
2409
+
/** @param {Request} request */
2410
async handleDeleteRecord(request) {
2411
const body = await request.json();
2412
if (!body.collection || !body.rkey) {
···
2419
}
2420
return Response.json({});
2421
} catch (err) {
2422
+
const message = err instanceof Error ? err.message : String(err);
2423
+
return errorResponse('InternalError', message, 500);
2424
}
2425
}
2426
2427
+
/** @param {Request} request */
2428
async handlePutRecord(request) {
2429
const body = await request.json();
2430
if (!body.collection || !body.rkey || !body.record) {
···
2450
validationStatus: 'valid',
2451
});
2452
} catch (err) {
2453
+
const message = err instanceof Error ? err.message : String(err);
2454
+
return errorResponse('InternalError', message, 500);
2455
}
2456
}
2457
2458
+
/** @param {Request} request */
2459
async handleApplyWrites(request) {
2460
const body = await request.json();
2461
if (!body.writes || !Array.isArray(body.writes)) {
···
2507
const rev = await this.state.storage.get('rev');
2508
return Response.json({ commit: { cid: head, rev }, results });
2509
} catch (err) {
2510
+
const message = err instanceof Error ? err.message : String(err);
2511
+
return errorResponse('InternalError', message, 500);
2512
}
2513
}
2514
2515
+
/** @param {URL} url */
2516
async handleGetRecord(url) {
2517
const collection = url.searchParams.get('collection');
2518
const rkey = url.searchParams.get('rkey');
···
2521
}
2522
const did = await this.getDid();
2523
const uri = `at://${did}/${collection}/${rkey}`;
2524
+
const rows = /** @type {RecordRow[]} */ (this.sql
2525
.exec(`SELECT cid, value FROM records WHERE uri = ?`, uri)
2526
+
.toArray());
2527
if (rows.length === 0) {
2528
return errorResponse('RecordNotFound', 'record not found', 404);
2529
}
···
2553
});
2554
}
2555
2556
+
/** @param {URL} url */
2557
async handleListRecords(url) {
2558
const collection = url.searchParams.get('collection');
2559
if (!collection) {
···
2570
const query = `SELECT uri, cid, value FROM records WHERE collection = ? ORDER BY rkey ${reverse ? 'DESC' : 'ASC'} LIMIT ?`;
2571
const params = [collection, limit + 1];
2572
2573
+
const rows = /** @type {RecordRow[]} */ (this.sql.exec(query, ...params).toArray());
2574
const hasMore = rows.length > limit;
2575
const records = rows.slice(0, limit).map((r) => ({
2576
uri: r.uri,
···
2585
}
2586
2587
handleGetLatestCommit() {
2588
+
const commits = /** @type {CommitRow[]} */ (this.sql
2589
.exec(`SELECT cid, rev FROM commits ORDER BY seq DESC LIMIT 1`)
2590
+
.toArray());
2591
if (commits.length === 0) {
2592
return errorResponse('RepoNotFound', 'repo not found', 404);
2593
}
···
2596
2597
async handleGetRepoStatus() {
2598
const did = await this.getDid();
2599
+
const commits = /** @type {CommitRow[]} */ (this.sql
2600
.exec(`SELECT cid, rev FROM commits ORDER BY seq DESC LIMIT 1`)
2601
+
.toArray());
2602
if (commits.length === 0 || !did) {
2603
return errorResponse('RepoNotFound', 'repo not found', 404);
2604
}
···
2611
}
2612
2613
handleGetRepo() {
2614
+
const commits = /** @type {CommitRow[]} */ (this.sql
2615
.exec(`SELECT cid FROM commits ORDER BY seq DESC LIMIT 1`)
2616
+
.toArray());
2617
if (commits.length === 0) {
2618
return errorResponse('RepoNotFound', 'repo not found', 404);
2619
}
···
2623
const neededCids = new Set();
2624
2625
// Helper to get block data
2626
+
/** @param {string} cid */
2627
const getBlock = (cid) => {
2628
+
const rows = /** @type {BlockRow[]} */ (this.sql
2629
.exec(`SELECT data FROM blocks WHERE cid = ?`, cid)
2630
+
.toArray());
2631
return rows.length > 0 ? new Uint8Array(rows[0].data) : null;
2632
};
2633
2634
// Collect all reachable blocks starting from commit
2635
+
/** @param {string} cid */
2636
const collectBlocks = (cid) => {
2637
if (neededCids.has(cid)) return;
2638
neededCids.add(cid);
···
2680
}
2681
2682
const car = buildCarFile(commitCid, blocksForCar);
2683
+
return new Response(/** @type {BodyInit} */(car), {
2684
headers: { 'content-type': 'application/vnd.ipld.car' },
2685
});
2686
}
2687
2688
+
/** @param {URL} url */
2689
async handleSyncGetRecord(url) {
2690
const collection = url.searchParams.get('collection');
2691
const rkey = url.searchParams.get('rkey');
···
2694
}
2695
const did = await this.getDid();
2696
const uri = `at://${did}/${collection}/${rkey}`;
2697
+
const rows = /** @type {RecordRow[]} */ (this.sql
2698
.exec(`SELECT cid FROM records WHERE uri = ?`, uri)
2699
+
.toArray());
2700
if (rows.length === 0) {
2701
return errorResponse('RecordNotFound', 'record not found', 404);
2702
}
2703
const recordCid = rows[0].cid;
2704
2705
// Get latest commit
2706
+
const commits = /** @type {CommitRow[]} */ (this.sql
2707
.exec(`SELECT cid FROM commits ORDER BY seq DESC LIMIT 1`)
2708
+
.toArray());
2709
if (commits.length === 0) {
2710
return errorResponse('RepoNotFound', 'no commits', 404);
2711
}
···
2713
2714
// Build proof chain: commit -> MST path -> record
2715
// Include commit block, all MST nodes on path to record, and record block
2716
+
/** @type {Array<{cid: string, data: Uint8Array}>} */
2717
const blocks = [];
2718
const included = new Set();
2719
2720
+
/** @param {string} cidStr */
2721
const addBlock = (cidStr) => {
2722
if (included.has(cidStr)) return;
2723
included.add(cidStr);
2724
+
const blockRows = /** @type {BlockRow[]} */ (this.sql
2725
.exec(`SELECT data FROM blocks WHERE cid = ?`, cidStr)
2726
+
.toArray());
2727
if (blockRows.length > 0) {
2728
blocks.push({ cid: cidStr, data: new Uint8Array(blockRows[0].data) });
2729
}
···
2733
addBlock(commitCid);
2734
2735
// Get commit to find data root
2736
+
const commitRows = /** @type {BlockRow[]} */ (this.sql
2737
.exec(`SELECT data FROM blocks WHERE cid = ?`, commitCid)
2738
+
.toArray());
2739
if (commitRows.length > 0) {
2740
const commit = cborDecode(new Uint8Array(commitRows[0].data));
2741
if (commit.data) {
···
2752
addBlock(recordCid);
2753
2754
const car = buildCarFile(commitCid, blocks);
2755
+
return new Response(/** @type {BodyInit} */(car), {
2756
headers: { 'content-type': 'application/vnd.ipld.car' },
2757
});
2758
}
2759
2760
+
/** @param {Request} request */
2761
async handleUploadBlob(request) {
2762
// Require auth
2763
const authHeader = request.headers.get('Authorization');
···
2782
try {
2783
await verifyAccessJwt(token, jwtSecret);
2784
} catch (err) {
2785
+
const message = err instanceof Error ? err.message : String(err);
2786
+
return errorResponse('InvalidToken', message, 401);
2787
}
2788
2789
const did = await this.getDid();
···
2820
2821
// Upload to R2 (idempotent - same CID always has same content)
2822
const r2Key = `${did}/${cidStr}`;
2823
+
await this.env?.BLOBS?.put(r2Key, bodyBytes, {
2824
httpMetadata: { contentType: mimeType },
2825
});
2826
···
2845
});
2846
}
2847
2848
+
/** @param {URL} url */
2849
async handleGetBlob(url) {
2850
const did = url.searchParams.get('did');
2851
const cid = url.searchParams.get('cid');
···
2878
2879
// Fetch from R2
2880
const r2Key = `${did}/${cid}`;
2881
+
const object = await this.env?.BLOBS?.get(r2Key);
2882
2883
if (!object) {
2884
return errorResponse('BlobNotFound', 'blob not found in storage', 404);
···
2887
// Return blob with security headers
2888
return new Response(object.body, {
2889
headers: {
2890
+
'Content-Type': /** @type {string} */ (mimeType),
2891
'Content-Length': String(size),
2892
'X-Content-Type-Options': 'nosniff',
2893
'Content-Security-Policy': "default-src 'none'; sandbox",
···
2896
});
2897
}
2898
2899
+
/** @param {URL} url */
2900
async handleListBlobs(url) {
2901
const did = url.searchParams.get('did');
2902
const cursor = url.searchParams.get('cursor');
···
2941
});
2942
}
2943
2944
+
/**
2945
+
* @param {Request} request
2946
+
* @param {URL} url
2947
+
*/
2948
handleSubscribeRepos(request, url) {
2949
const upgradeHeader = request.headers.get('Upgrade');
2950
if (upgradeHeader !== 'websocket') {
···
2954
this.state.acceptWebSocket(server);
2955
const cursor = url.searchParams.get('cursor');
2956
if (cursor) {
2957
+
const events = /** @type {SeqEventRow[]} */ (this.sql
2958
.exec(
2959
`SELECT * FROM seq_events WHERE seq > ? ORDER BY seq`,
2960
parseInt(cursor, 10),
2961
)
2962
+
.toArray());
2963
for (const evt of events) {
2964
server.send(this.formatEvent(evt));
2965
}
···
2967
return new Response(null, { status: 101, webSocket: client });
2968
}
2969
2970
+
/** @param {Request} request */
2971
async fetch(request) {
2972
const url = new URL(request.url);
2973
const route = pdsRoutes[url.pathname];
···
3015
.toArray();
3016
3017
for (const { cid } of orphans) {
3018
+
await this.env?.BLOBS?.delete(`${did}/${cid}`);
3019
this.sql.exec('DELETE FROM blob WHERE cid = ?', cid);
3020
}
3021
3022
}
3023
}
3024
3025
+
// ╔══════════════════════════════════════════════════════════════════════════════╗
3026
+
// ║ WORKERS ENTRY POINT ║
3027
+
// ║ Request handling, CORS, auth middleware ║
3028
+
// ╚══════════════════════════════════════════════════════════════════════════════╝
3029
+
3030
const corsHeaders = {
3031
'Access-Control-Allow-Origin': '*',
3032
'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
···
3034
'Content-Type, Authorization, atproto-accept-labelers, atproto-proxy, x-bsky-topics',
3035
};
3036
3037
+
/**
3038
+
* @param {Response} response
3039
+
* @returns {Response}
3040
+
*/
3041
function addCorsHeaders(response) {
3042
const newHeaders = new Headers(response.headers);
3043
for (const [key, value] of Object.entries(corsHeaders)) {
···
3051
}
3052
3053
export default {
3054
+
/**
3055
+
* @param {Request} request
3056
+
* @param {Env} env
3057
+
*/
3058
async fetch(request, env) {
3059
// Handle CORS preflight
3060
if (request.method === 'OPTIONS') {
···
3070
},
3071
};
3072
3073
+
/**
3074
+
* Extract subdomain from hostname (e.g., "alice" from "alice.foo.workers.dev")
3075
+
* @param {string} hostname
3076
+
* @returns {string|null}
3077
+
*/
3078
function getSubdomain(hostname) {
3079
const parts = hostname.split('.');
3080
// workers.dev domains: [subdomain?].[worker-name].[account].workers.dev
···
3090
/**
3091
* Verify auth and return DID from token
3092
* @param {Request} request - HTTP request with Authorization header
3093
+
* @param {Env} env - Environment with JWT_SECRET
3094
* @returns {Promise<{did: string} | {error: Response}>} DID or error response
3095
*/
3096
async function requireAuth(request, env) {
···
3125
const payload = await verifyAccessJwt(token, jwtSecret);
3126
return { did: payload.sub };
3127
} catch (err) {
3128
+
const message = err instanceof Error ? err.message : String(err);
3129
return {
3130
error: Response.json(
3131
{
3132
error: 'InvalidToken',
3133
+
message: message,
3134
},
3135
{ status: 401 },
3136
),
···
3138
}
3139
}
3140
3141
+
/**
3142
+
* @param {Request} request
3143
+
* @param {Env} env
3144
+
*/
3145
async function handleAuthenticatedBlobUpload(request, env) {
3146
const auth = await requireAuth(request, env);
3147
+
if ('error' in auth) return auth.error;
3148
3149
// Route to the user's DO based on their DID from the token
3150
const id = env.PDS.idFromName(auth.did);
···
3152
return pds.fetch(request);
3153
}
3154
3155
+
/**
3156
+
* @param {Request} request
3157
+
* @param {Env} env
3158
+
*/
3159
async function handleAuthenticatedRepoWrite(request, env) {
3160
const auth = await requireAuth(request, env);
3161
+
if ('error' in auth) return auth.error;
3162
3163
const body = await request.json();
3164
const repo = body.repo;
···
3189
return response;
3190
}
3191
3192
+
/**
3193
+
* @param {Request} request
3194
+
* @param {Env} env
3195
+
*/
3196
async function handleRequest(request, env) {
3197
const url = new URL(request.url);
3198
const subdomain = getSubdomain(url.hostname);
···
3255
if (url.pathname.startsWith('/xrpc/app.bsky.')) {
3256
// Authenticate the user first
3257
const auth = await requireAuth(request, env);
3258
+
if ('error' in auth) return auth.error;
3259
3260
// Route to the user's DO instance to create service auth and proxy
3261
const id = env.PDS.idFromName(auth.did);
+16
tsconfig.json
+16
tsconfig.json
···
···
1
+
{
2
+
"compilerOptions": {
3
+
"target": "ES2022",
4
+
"module": "ES2022",
5
+
"moduleResolution": "bundler",
6
+
"checkJs": true,
7
+
"allowJs": true,
8
+
"noEmit": true,
9
+
"strict": true,
10
+
"skipLibCheck": true,
11
+
"useUnknownInCatchVariables": false,
12
+
"types": ["@cloudflare/workers-types"]
13
+
},
14
+
"include": ["src/**/*.js"],
15
+
"exclude": ["node_modules"]
16
+
}