Image CDN for atproto built on cloudflare
evan.jarrett.net
1# imgs.blue
2
3A **high-performance CDN for AT Protocol images** built on Cloudflare Workers. Fetch images from any AT Protocol user using their handle or DID, with automatic caching and base62 URL shortening.
4
5## Features
6
7- 🚀 **Fast global CDN** powered by Cloudflare's edge network
8- 🔗 **Multiple URL formats** - handles, DIDs, CIDs, or base62
9- 💾 **Intelligent caching** - images cached for 1 year, metadata for appropriate durations
10- 🔄 **Automatic redirects** - CIDs redirect to shorter base62 URLs (coming soon)
11- 🌐 **CORS enabled** - use images directly in web applications
12- 🔒 **No authentication required** - accesses only public blob data
13
14## Usage
15
16### Basic URL Format
17
18```
19https://imgs.blue/{handle-or-did}/{cid-or-base62}
20```
21
22### Using Handles
23
24Fetch images using a Bluesky handle:
25
26```
27https://imgs.blue/alice.bsky.social/3jui7kd54zh2y
28```
29
30### Using DIDs
31
32Direct access with Decentralized Identifiers:
33
34```
35https://imgs.blue/did:plc:z72i7hdynmk6r22z27h6tvur/3jui7kd54zh2y
36```
37
38### Base62 Format
39
40The **base62 format** provides shorter, cleaner URLs:
41- Original CID: ```bafkreihj3odjayaboovyvn7z6bugk5rldvqrzxnrxv3townofeql6jumeu```
42- Base62: ```3jui7kd54zh2y```
43
44## How It Works
45
461. **Handle Resolution** - Resolves handles to DIDs using DNS ```_atproto``` TXT records
472. **PDS Discovery** - Finds the user's Personal Data Server (PDS) from their DID document
483. **Blob Fetching** - Downloads the image blob from the PDS
494. **Caching** - Stores everything in Cloudflare's edge cache for fast subsequent requests
50
51## Setup & Deployment
52
53### Prerequisites
54
55- Cloudflare account
56- Wrangler CLI installed (```npm install -g wrangler```)
57- Node.js 16+
58
59### Installation
60
611. Clone the repository:
62```bash
63git clone https://tangled.sh/@evan.jarrett.net/imgs.blue
64cd imgs.blue
65```
66
672. Install dependencies:
68```bash
69npm install
70```
71
723. Configure your ```wrangler.jsonc```:
73```json
74"kv_namespaces": [
75 {
76 "binding": "USER_CACHE",
77 "id": "your-kv-namespace-id"
78 }
79],
80"routes": [
81 {
82 "pattern": "your-custom-domain",
83 "custom_domain": true
84 }
85]
86```
87
884. Deploy to Cloudflare:
89```bash
90wrangler deploy
91```
92
93## Caching Strategy
94
95- **Image content**: 1 year (```max-age=31536000, immutable```)
96- **Handle → DID resolution**: 1 year
97- **DID → PDS resolution**: 1 hour
98- **DNS lookups**: 5 minutes
99
100## Error Responses
101
102| Status | Description |
103|--------|-------------|
104| 400 | Invalid path or CID format |
105| 400 | PDS resolution or fetch failure |
106| 404 | Handle/DID not found or image doesn't exist |
107
108## Security & Privacy
109
110- Only accesses **publicly available** blob data
111- No authentication tokens required or stored
112- Respects AT Protocol's public content model
113- CORS headers allow usage from any domain
114
115
116---
117
118Built with 💙 for the AT Protocol ecosystem
119