imgs.blue #

A 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.

Features #

• 🚀 Fast global CDN powered by Cloudflare's edge network
• 🔗 Multiple URL formats - handles, DIDs, CIDs, or base62
• 💾 Intelligent caching - images cached for 1 year, metadata for appropriate durations
• 🔄 Automatic redirects - CIDs redirect to shorter base62 URLs (coming soon)
• 🌐 CORS enabled - use images directly in web applications
• 🔒 No authentication required - accesses only public blob data

Usage #

Basic URL Format #

https://imgs.blue/{handle-or-did}/{cid-or-base62}

Using Handles #

Fetch images using a Bluesky handle:

https://imgs.blue/alice.bsky.social/3jui7kd54zh2y

Using DIDs #

Direct access with Decentralized Identifiers:

https://imgs.blue/did:plc:z72i7hdynmk6r22z27h6tvur/3jui7kd54zh2y

Base62 Format #

The base62 format provides shorter, cleaner URLs:

• Original CID: bafkreihj3odjayaboovyvn7z6bugk5rldvqrzxnrxv3townofeql6jumeu
• Base62: 3jui7kd54zh2y

How It Works #

1. Handle Resolution - Resolves handles to DIDs using DNS _atproto TXT records
2. PDS Discovery - Finds the user's Personal Data Server (PDS) from their DID document
3. Blob Fetching - Downloads the image blob from the PDS
4. Caching - Stores everything in Cloudflare's edge cache for fast subsequent requests

Setup & Deployment #

Prerequisites #

• Cloudflare account
• Wrangler CLI installed (npm install -g wrangler)
• Node.js 16+

Installation #

1. Clone the repository:

git clone https://tangled.sh/@evan.jarrett.net/imgs.blue
cd imgs.blue

2. Install dependencies:

npm install

3. Configure your wrangler.jsonc:

"kv_namespaces": [
    {
        "binding": "USER_CACHE",
        "id": "your-kv-namespace-id"
    }
],
"routes": [
    {
    "pattern": "your-custom-domain",
    "custom_domain": true
    }
]

4. Deploy to Cloudflare:

wrangler deploy

Caching Strategy #

• Image content: 1 year (max-age=31536000, immutable)
• Handle → DID resolution: 1 year
• DID → PDS resolution: 1 hour
• DNS lookups: 5 minutes

Error Responses #

Status	Description
400	Invalid path or CID format
400	PDS resolution or fetch failure
404	Handle/DID not found or image doesn't exist

Security & Privacy #

• Only accesses publicly available blob data
• No authentication tokens required or stored
• Respects AT Protocol's public content model
• CORS headers allow usage from any domain

---

Built with 💙 for the AT Protocol ecosystem