feat(imageproxy): add image proxy service for AT Protocol blob transformations

Implement a comprehensive image proxy service that fetches, resizes, and caches
images from AT Protocol Personal Data Servers. This enables optimized image
delivery with preset-based transformations for avatars, banners, and content.

Changes:
- Add imageproxy core package with multi-tier architecture (service, cache, fetcher, processor)
- Implement disk-based LRU cache with configurable TTL and background cleanup
- Add HTTP handler at /img/{preset}/plain/{did}/{cid} with ETag support
- Define 6 presets: avatar, avatar_small, banner, content_preview, content_full, embed_thumbnail
- Add DID and CID validation with proper error handling
- Integrate with communities to serve optimized avatar/banner URLs
- Add HydrateImageURL helper with smart proxy/direct URL selection
- Add comprehensive E2E and unit tests
- Configure via environment variables (IMAGE_PROXY_*)
- Add disintegration/imaging dependency for image processing

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

.env.dev.example

···
 SKIP_DID_WEB_VERIFICATION=true
 AUTH_SKIP_VERIFY=true
 HS256_ISSUERS=http://localhost:3001
+
+# =============================================================================
+# Image Proxy Configuration
+# =============================================================================
+# On-the-fly image resizing with disk caching
+# Defaults to enabled - falls back to direct PDS URLs if proxy fails
+IMAGE_PROXY_ENABLED=true
+IMAGE_PROXY_BASE_URL=http://127.0.0.1:8081
+IMAGE_PROXY_CACHE_PATH=./cache/images
+IMAGE_PROXY_CACHE_MAX_GB=5
+# Optional: CDN URL for production (leave empty for local dev)
+# IMAGE_PROXY_CDN_URL=
+IMAGE_PROXY_FETCH_TIMEOUT_SECONDS=30
+IMAGE_PROXY_MAX_SOURCE_SIZE_MB=10

.env.prod.example

···
 SKIP_DID_WEB_VERIFICATION=false
 
 # =============================================================================
+# Image Proxy Configuration
+# =============================================================================
+# On-the-fly image resizing with disk caching
+# Enabled by default - gracefully falls back to direct PDS URLs on failure
+IMAGE_PROXY_ENABLED=true
+IMAGE_PROXY_BASE_URL=https://coves.social
+IMAGE_PROXY_CACHE_PATH=/var/cache/coves/images
+IMAGE_PROXY_CACHE_MAX_GB=10
+# Optional: CDN URL for edge caching (recommended for production)
+# IMAGE_PROXY_CDN_URL=https://cdn.coves.social
+IMAGE_PROXY_FETCH_TIMEOUT_SECONDS=30
+IMAGE_PROXY_MAX_SOURCE_SIZE_MB=10
+
+# =============================================================================
 # Optional: Versioning
 # =============================================================================
 VERSION=latest

.gitignore

···
 /local_dev_data/
 /test_db_data/
 
+# Image proxy cache
+/cache/
+
 # Logs
 *.log
 

cmd/server/main.go

···
 	"Coves/internal/atproto/jetstream"
 	"Coves/internal/atproto/oauth"
 
+	imageproxyhandlers "Coves/internal/api/handlers/imageproxy"
+	"Coves/internal/core/imageproxy"
+
 	indigoauth "github.com/bluesky-social/indigo/atproto/auth"
 	indigoidentity "github.com/bluesky-social/indigo/atproto/identity"
 	"Coves/internal/core/aggregators"
···
 	discoverService := discover.NewDiscoverService(discoverRepo)
 	log.Println("✅ Discover service initialized")
 
+	// Initialize image proxy (optional service for resizing/caching images)
+	imageProxyConfig := imageproxy.ConfigFromEnv()
+	var imageProxyCacheCleanupCancel context.CancelFunc = func() {} // No-op default
+	if imageProxyConfig.Enabled {
+		// Validate configuration at startup - fail fast if misconfigured
+		if err := imageProxyConfig.Validate(); err != nil {
+			log.Fatalf("Image proxy configuration error: %v", err)
+		}
+
+		imageProxyCache, err := imageproxy.NewDiskCache(
+			imageProxyConfig.CachePath,
+			imageProxyConfig.CacheMaxGB,
+			imageProxyConfig.CacheTTLDays,
+		)
+		if err != nil {
+			log.Fatalf("Failed to create image proxy cache: %v", err)
+		}
+
+		// Start background cache cleanup job
+		imageProxyCacheCleanupCancel = imageProxyCache.StartCleanupJob(imageProxyConfig.CleanupInterval)
+
+		imageProxyProcessor := imageproxy.NewProcessor()
+		imageProxyFetcher := imageproxy.NewPDSFetcher(imageProxyConfig.FetchTimeout, imageProxyConfig.MaxSourceSizeMB)
+		imageProxyService, err := imageproxy.NewService(
+			imageProxyCache,
+			imageProxyProcessor,
+			imageProxyFetcher,
+			imageProxyConfig,
+		)
+		if err != nil {
+			log.Fatalf("Failed to create image proxy service: %v", err)
+		}
+		imageProxyHandler := imageproxyhandlers.NewHandler(imageProxyService, identityResolver)
+		routes.RegisterImageProxyRoutes(r, imageProxyHandler)
+		log.Println("✅ Image proxy enabled at /img/{preset}/plain/{did}/{cid}")
+		slog.Info("[IMAGE-PROXY] service started",
+			"base_url", imageProxyConfig.BaseURL,
+			"cdn_url", imageProxyConfig.CDNURL,
+			"cache_path", imageProxyConfig.CachePath,
+			"cache_max_gb", imageProxyConfig.CacheMaxGB,
+			"cache_ttl_days", imageProxyConfig.CacheTTLDays,
+			"cleanup_interval", imageProxyConfig.CleanupInterval,
+			"fetch_timeout_seconds", int(imageProxyConfig.FetchTimeout.Seconds()),
+			"max_source_size_mb", imageProxyConfig.MaxSourceSizeMB,
+		)
+	}
+
+	// Initialize image proxy config for URL generation in communities package
+	// This is called once at startup and is thread-safe for concurrent access
+	communities.SetImageProxyConfig(blobs.ImageURLConfig{
+		ProxyEnabled: imageProxyConfig.Enabled,
+		ProxyBaseURL: imageProxyConfig.BaseURL,
+		CDNURL:       imageProxyConfig.CDNURL,
+	})
+	log.Printf("Image proxy URL generation config set (enabled: %v)", imageProxyConfig.Enabled)
+
 	// Start Jetstream consumer for posts
 	// This consumer indexes posts created in community repositories via the firehose
 	// Currently handles only CREATE operations - UPDATE/DELETE deferred until those features exist
···
 	// Stop background jobs
 	cleanupCancel()
 	tokenRefreshCancel()
+	imageProxyCacheCleanupCancel()
 
 	if err := server.Shutdown(ctx); err != nil {
 		log.Fatalf("Server shutdown error: %v", err)

go.mod

···
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cespare/xxhash/v2 v2.2.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/disintegration/imaging v1.6.2 // indirect
 	github.com/earthboundkid/versioninfo/v2 v2.24.1 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/go-logr/logr v1.4.1 // indirect
···
 	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.26.0 // indirect
 	golang.org/x/crypto v0.43.0 // indirect
+	golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8 // indirect
 	golang.org/x/sync v0.10.0 // indirect
 	golang.org/x/sys v0.37.0 // indirect
 	golang.org/x/xerrors v0.0.0-20231012003039-104605ab7028 // indirect

go.sum

···
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/disintegration/imaging v1.6.2 h1:w1LecBlG2Lnp8B3jk5zSuNqd7b4DXhcjwek1ei82L+c=
+github.com/disintegration/imaging v1.6.2/go.mod h1:44/5580QXChDfwIclfc/PCwrr44amcmDAg8hxG0Ewe4=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/earthboundkid/versioninfo/v2 v2.24.1 h1:SJTMHaoUx3GzjjnUO1QzP3ZXK6Ee/nbWyCm58eY3oUg=
···
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.43.0 h1:dduJYIi3A3KOfdGOHX8AVZ/jGiyPa3IbBozJ5kNuE04=
 golang.org/x/crypto v0.43.0/go.mod h1:BFbav4mRNlXJL4wNeejLpWxB7wMbc79PdRGhWKncxR0=
+golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8 h1:hVwzHzIUGRjiF7EcUjqNxk3NCfkPxbDKRdnNE1Rpg0U=
+golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
 golang.org/x/lint v0.0.0-20190930215403-16217165b5de/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
 golang.org/x/mod v0.0.0-20190513183733-4bf6d317e70e/go.mod h1:mXi4GBBbnImb6dmsKGUJ2LatrhH/nqhxcFungHvyanc=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=

internal/api/handlers/imageproxy/handler.go

···
+// Package imageproxy provides HTTP handlers for the image proxy service.
+// It handles requests for proxied and transformed images from AT Protocol PDSes.
+package imageproxy
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"Coves/internal/atproto/identity"
+	"Coves/internal/core/imageproxy"
+)
+
+// Service defines the interface for the image proxy service.
+// This interface is implemented by the imageproxy package's service layer.
+type Service interface {
+	// GetImage retrieves and processes an image from a PDS.
+	// preset: the image transformation preset (e.g., "avatar", "banner")
+	// did: the DID of the user who owns the blob
+	// cid: the content identifier of the blob
+	// pdsURL: the URL of the user's PDS
+	GetImage(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error)
+}
+
+// Handler handles HTTP requests for the image proxy.
+type Handler struct {
+	service          Service
+	identityResolver identity.Resolver
+}
+
+// NewHandler creates a new image proxy handler.
+func NewHandler(service Service, resolver identity.Resolver) *Handler {
+	return &Handler{
+		service:          service,
+		identityResolver: resolver,
+	}
+}
+
+// HandleImage handles GET /img/{preset}/plain/{did}/{cid}
+// It fetches the image from the user's PDS, transforms it according to the preset,
+// and returns the result with appropriate caching headers.
+func (h *Handler) HandleImage(w http.ResponseWriter, r *http.Request) {
+	// Parse URL parameters
+	preset := chi.URLParam(r, "preset")
+	did := chi.URLParam(r, "did")
+	cid := chi.URLParam(r, "cid")
+
+	// Validate required parameters
+	if preset == "" || did == "" || cid == "" {
+		writeErrorResponse(w, http.StatusBadRequest, "missing required parameters")
+		return
+	}
+
+	// Validate preset exists before proceeding
+	if _, err := imageproxy.GetPreset(preset); err != nil {
+		if errors.Is(err, imageproxy.ErrInvalidPreset) {
+			writeErrorResponse(w, http.StatusBadRequest, "invalid preset: "+preset)
+			return
+		}
+		writeErrorResponse(w, http.StatusBadRequest, "invalid preset")
+		return
+	}
+
+	// Validate DID format (must be did:plc: or did:web:)
+	if err := imageproxy.ValidateDID(did); err != nil {
+		writeErrorResponse(w, http.StatusBadRequest, "invalid DID format")
+		return
+	}
+
+	// Validate CID format (must be valid base32/base58 CID)
+	if err := imageproxy.ValidateCID(cid); err != nil {
+		writeErrorResponse(w, http.StatusBadRequest, "invalid CID format")
+		return
+	}
+
+	// Generate ETag for caching
+	etag := fmt.Sprintf(`"%s-%s"`, preset, cid)
+
+	// Check If-None-Match header for 304 response
+	if r.Header.Get("If-None-Match") == etag {
+		w.WriteHeader(http.StatusNotModified)
+		return
+	}
+
+	// Resolve DID to get PDS URL
+	didDoc, err := h.identityResolver.ResolveDID(r.Context(), did)
+	if err != nil {
+		slog.Warn("[IMAGE-PROXY] failed to resolve DID",
+			"did", did,
+			"error", err,
+		)
+		writeErrorResponse(w, http.StatusBadGateway, "failed to resolve DID")
+		return
+	}
+
+	// Extract PDS URL from DID document
+	pdsURL := getPDSEndpoint(didDoc)
+	if pdsURL == "" {
+		slog.Warn("[IMAGE-PROXY] no PDS endpoint found in DID document",
+			"did", did,
+		)
+		writeErrorResponse(w, http.StatusBadGateway, "no PDS endpoint found")
+		return
+	}
+
+	// Fetch and process the image
+	imageData, err := h.service.GetImage(r.Context(), preset, did, cid, pdsURL)
+	if err != nil {
+		handleServiceError(w, err)
+		return
+	}
+
+	// Set response headers
+	w.Header().Set("Content-Type", "image/jpeg")
+	w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+	w.Header().Set("ETag", etag)
+
+	// Write image data
+	w.WriteHeader(http.StatusOK)
+	if _, err := w.Write(imageData); err != nil {
+		slog.Warn("[IMAGE-PROXY] failed to write image response",
+			"preset", preset,
+			"did", did,
+			"cid", cid,
+			"error", err,
+		)
+	}
+}
+
+// getPDSEndpoint extracts the PDS service endpoint from a DID document.
+func getPDSEndpoint(doc *identity.DIDDocument) string {
+	if doc == nil {
+		return ""
+	}
+	for _, service := range doc.Service {
+		if service.Type == "AtprotoPersonalDataServer" {
+			return service.ServiceEndpoint
+		}
+	}
+	return ""
+}
+
+// handleServiceError converts service errors to appropriate HTTP responses.
+func handleServiceError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, imageproxy.ErrPDSNotFound):
+		writeErrorResponse(w, http.StatusNotFound, "blob not found")
+	case errors.Is(err, imageproxy.ErrPDSTimeout):
+		writeErrorResponse(w, http.StatusGatewayTimeout, "request timed out")
+	case errors.Is(err, imageproxy.ErrPDSFetchFailed):
+		writeErrorResponse(w, http.StatusBadGateway, "failed to fetch blob from PDS")
+	case errors.Is(err, imageproxy.ErrInvalidPreset):
+		writeErrorResponse(w, http.StatusBadRequest, "invalid preset")
+	case errors.Is(err, imageproxy.ErrInvalidDID):
+		writeErrorResponse(w, http.StatusBadRequest, "invalid DID format")
+	case errors.Is(err, imageproxy.ErrInvalidCID):
+		writeErrorResponse(w, http.StatusBadRequest, "invalid CID format")
+	case errors.Is(err, imageproxy.ErrUnsupportedFormat):
+		writeErrorResponse(w, http.StatusBadRequest, "unsupported image format")
+	case errors.Is(err, imageproxy.ErrImageTooLarge):
+		writeErrorResponse(w, http.StatusBadRequest, "image too large")
+	case errors.Is(err, imageproxy.ErrProcessingFailed):
+		writeErrorResponse(w, http.StatusInternalServerError, "image processing failed")
+	default:
+		slog.Error("[IMAGE-PROXY] unhandled service error",
+			"error", err,
+		)
+		writeErrorResponse(w, http.StatusInternalServerError, "internal server error")
+	}
+}
+
+// writeErrorResponse writes a plain text error response.
+// For the image proxy, we use simple text responses rather than JSON
+// since the expected response is binary image data.
+func writeErrorResponse(w http.ResponseWriter, status int, message string) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.WriteHeader(status)
+	if _, err := w.Write([]byte(message)); err != nil {
+		slog.Warn("[IMAGE-PROXY] failed to write error response",
+			"status", status,
+			"message", message,
+			"error", err,
+		)
+	}
+}

internal/api/handlers/imageproxy/handler_test.go

···
+package imageproxy
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"Coves/internal/atproto/identity"
+	"Coves/internal/core/imageproxy"
+)
+
+// Valid test constants that pass validation
+const (
+	// validTestDID is a valid did:plc identifier (24 lowercase base32 chars after did:plc:)
+	validTestDID = "did:plc:z72i7hdynmk6r22z27h6tvur"
+	// validTestCID is a valid CIDv1 base32 identifier
+	validTestCID = "bafyreihgdyzzpkkzq2izfnhcmm77ycuacvkuziwbnqxfxtqsz7tmxwhnshi"
+)
+
+// mockService implements imageproxy.Service for testing
+type mockService struct {
+	getImageFunc func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error)
+}
+
+func (m *mockService) GetImage(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+	if m.getImageFunc != nil {
+		return m.getImageFunc(ctx, preset, did, cid, pdsURL)
+	}
+	return nil, errors.New("not implemented")
+}
+
+// mockIdentityResolver implements identity.Resolver for testing
+type mockIdentityResolver struct {
+	resolveFunc    func(ctx context.Context, identifier string) (*identity.Identity, error)
+	resolveDIDFunc func(ctx context.Context, did string) (*identity.DIDDocument, error)
+}
+
+func (m *mockIdentityResolver) Resolve(ctx context.Context, identifier string) (*identity.Identity, error) {
+	if m.resolveFunc != nil {
+		return m.resolveFunc(ctx, identifier)
+	}
+	return nil, errors.New("not implemented")
+}
+
+func (m *mockIdentityResolver) ResolveHandle(ctx context.Context, handle string) (did, pdsURL string, err error) {
+	return "", "", errors.New("not implemented")
+}
+
+func (m *mockIdentityResolver) ResolveDID(ctx context.Context, did string) (*identity.DIDDocument, error) {
+	if m.resolveDIDFunc != nil {
+		return m.resolveDIDFunc(ctx, did)
+	}
+	return nil, errors.New("not implemented")
+}
+
+func (m *mockIdentityResolver) Purge(ctx context.Context, identifier string) error {
+	return nil
+}
+
+// createTestRequest creates an HTTP request with chi URL params
+func createTestRequest(method, path string, params map[string]string) *http.Request {
+	req := httptest.NewRequest(method, path, nil)
+	rctx := chi.NewRouteContext()
+	for k, v := range params {
+		rctx.URLParams.Add(k, v)
+	}
+	return req.WithContext(context.WithValue(req.Context(), chi.RouteCtxKey, rctx))
+}
+
+func TestHandler_HandleImage_Success(t *testing.T) {
+	expectedImage := []byte{0xFF, 0xD8, 0xFF, 0xE0} // JPEG magic bytes
+	testPDSURL := "https://pds.example.com"
+	testPreset := "avatar"
+
+	mockSvc := &mockService{
+		getImageFunc: func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+			if preset != testPreset {
+				t.Errorf("Expected preset %q, got %q", testPreset, preset)
+			}
+			if did != validTestDID {
+				t.Errorf("Expected DID %q, got %q", validTestDID, did)
+			}
+			if cid != validTestCID {
+				t.Errorf("Expected CID %q, got %q", validTestCID, cid)
+			}
+			if pdsURL != testPDSURL {
+				t.Errorf("Expected PDS URL %q, got %q", testPDSURL, pdsURL)
+			}
+			return expectedImage, nil
+		},
+	}
+
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			return &identity.DIDDocument{
+				DID: did,
+				Service: []identity.Service{
+					{
+						ID:              "#atproto_pds",
+						Type:            "AtprotoPersonalDataServer",
+						ServiceEndpoint: testPDSURL,
+					},
+				},
+			}, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": testPreset,
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("Expected status 200, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// Verify Content-Type
+	contentType := w.Header().Get("Content-Type")
+	if contentType != "image/jpeg" {
+		t.Errorf("Expected Content-Type image/jpeg, got %s", contentType)
+	}
+
+	// Verify Cache-Control
+	cacheControl := w.Header().Get("Cache-Control")
+	expectedCacheControl := "public, max-age=31536000, immutable"
+	if cacheControl != expectedCacheControl {
+		t.Errorf("Expected Cache-Control %q, got %q", expectedCacheControl, cacheControl)
+	}
+
+	// Verify ETag format
+	etag := w.Header().Get("ETag")
+	expectedETag := `"avatar-` + validTestCID + `"`
+	if etag != expectedETag {
+		t.Errorf("Expected ETag %q, got %q", expectedETag, etag)
+	}
+
+	// Verify body
+	if w.Body.Len() != len(expectedImage) {
+		t.Errorf("Expected body length %d, got %d", len(expectedImage), w.Body.Len())
+	}
+}
+
+func TestHandler_HandleImage_ETagMatch_Returns304(t *testing.T) {
+	testPreset := "avatar"
+
+	mockSvc := &mockService{
+		getImageFunc: func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+			t.Error("Service should not be called when ETag matches")
+			return nil, nil
+		},
+	}
+
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			t.Error("Resolver should not be called when ETag matches")
+			return nil, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": testPreset,
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+	// Set If-None-Match header with matching ETag
+	req.Header.Set("If-None-Match", `"avatar-`+validTestCID+`"`)
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusNotModified {
+		t.Errorf("Expected status 304, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// Verify no body in 304 response
+	if w.Body.Len() != 0 {
+		t.Errorf("Expected empty body for 304 response, got %d bytes", w.Body.Len())
+	}
+}
+
+func TestHandler_HandleImage_ETagMismatch_ReturnsImage(t *testing.T) {
+	expectedImage := []byte{0xFF, 0xD8, 0xFF, 0xE0}
+	testPreset := "avatar"
+	testPDSURL := "https://pds.example.com"
+
+	serviceCalled := false
+	mockSvc := &mockService{
+		getImageFunc: func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+			serviceCalled = true
+			return expectedImage, nil
+		},
+	}
+
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			return &identity.DIDDocument{
+				DID: did,
+				Service: []identity.Service{
+					{
+						ID:              "#atproto_pds",
+						Type:            "AtprotoPersonalDataServer",
+						ServiceEndpoint: testPDSURL,
+					},
+				},
+			}, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": testPreset,
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+	// Set If-None-Match header with different ETag
+	req.Header.Set("If-None-Match", `"other-preset-somecid"`)
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("Expected status 200, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	if !serviceCalled {
+		t.Error("Service should have been called when ETag doesn't match")
+	}
+}
+
+func TestHandler_HandleImage_InvalidPreset_Returns400(t *testing.T) {
+	mockSvc := &mockService{}
+	mockResolver := &mockIdentityResolver{}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/invalid_preset/plain/did:plc:test/somecid", map[string]string{
+		"preset": "invalid_preset",
+		"did":    "did:plc:test",
+		"cid":    "somecid",
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("Expected status 400, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// Verify error response contains error info
+	body := w.Body.String()
+	if body == "" {
+		t.Error("Expected error message in response body")
+	}
+}
+
+func TestHandler_HandleImage_DIDResolutionFailed_Returns502(t *testing.T) {
+	mockSvc := &mockService{}
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			return nil, errors.New("failed to resolve DID")
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": "avatar",
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusBadGateway {
+		t.Errorf("Expected status 502, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestHandler_HandleImage_BlobNotFound_Returns404(t *testing.T) {
+	testPDSURL := "https://pds.example.com"
+
+	mockSvc := &mockService{
+		getImageFunc: func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+			return nil, imageproxy.ErrPDSNotFound
+		},
+	}
+
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			return &identity.DIDDocument{
+				DID: did,
+				Service: []identity.Service{
+					{
+						ID:              "#atproto_pds",
+						Type:            "AtprotoPersonalDataServer",
+						ServiceEndpoint: testPDSURL,
+					},
+				},
+			}, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": "avatar",
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("Expected status 404, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestHandler_HandleImage_Timeout_Returns504(t *testing.T) {
+	testPDSURL := "https://pds.example.com"
+
+	mockSvc := &mockService{
+		getImageFunc: func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+			return nil, imageproxy.ErrPDSTimeout
+		},
+	}
+
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			return &identity.DIDDocument{
+				DID: did,
+				Service: []identity.Service{
+					{
+						ID:              "#atproto_pds",
+						Type:            "AtprotoPersonalDataServer",
+						ServiceEndpoint: testPDSURL,
+					},
+				},
+			}, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": "avatar",
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusGatewayTimeout {
+		t.Errorf("Expected status 504, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestHandler_HandleImage_InternalError_Returns500(t *testing.T) {
+	testPDSURL := "https://pds.example.com"
+
+	mockSvc := &mockService{
+		getImageFunc: func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+			return nil, errors.New("unexpected internal error")
+		},
+	}
+
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			return &identity.DIDDocument{
+				DID: did,
+				Service: []identity.Service{
+					{
+						ID:              "#atproto_pds",
+						Type:            "AtprotoPersonalDataServer",
+						ServiceEndpoint: testPDSURL,
+					},
+				},
+			}, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": "avatar",
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Errorf("Expected status 500, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestHandler_HandleImage_PDSFetchFailed_Returns502(t *testing.T) {
+	testPDSURL := "https://pds.example.com"
+
+	mockSvc := &mockService{
+		getImageFunc: func(ctx context.Context, preset, did, cid, pdsURL string) ([]byte, error) {
+			return nil, imageproxy.ErrPDSFetchFailed
+		},
+	}
+
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			return &identity.DIDDocument{
+				DID: did,
+				Service: []identity.Service{
+					{
+						ID:              "#atproto_pds",
+						Type:            "AtprotoPersonalDataServer",
+						ServiceEndpoint: testPDSURL,
+					},
+				},
+			}, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": "avatar",
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusBadGateway {
+		t.Errorf("Expected status 502, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestHandler_HandleImage_MissingParams(t *testing.T) {
+	mockSvc := &mockService{}
+	mockResolver := &mockIdentityResolver{}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	tests := []struct {
+		name   string
+		params map[string]string
+	}{
+		{
+			name:   "missing preset",
+			params: map[string]string{"did": "did:plc:test", "cid": "somecid"},
+		},
+		{
+			name:   "missing did",
+			params: map[string]string{"preset": "avatar", "cid": "somecid"},
+		},
+		{
+			name:   "missing cid",
+			params: map[string]string{"preset": "avatar", "did": "did:plc:test"},
+		},
+		{
+			name:   "empty preset",
+			params: map[string]string{"preset": "", "did": "did:plc:test", "cid": "somecid"},
+		},
+		{
+			name:   "empty did",
+			params: map[string]string{"preset": "avatar", "did": "", "cid": "somecid"},
+		},
+		{
+			name:   "empty cid",
+			params: map[string]string{"preset": "avatar", "did": "did:plc:test", "cid": ""},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			req := createTestRequest(http.MethodGet, "/img/test/plain/did:plc:test/cid", tc.params)
+
+			w := httptest.NewRecorder()
+			handler.HandleImage(w, req)
+
+			if w.Code != http.StatusBadRequest {
+				t.Errorf("Expected status 400, got %d. Body: %s", w.Code, w.Body.String())
+			}
+		})
+	}
+}
+
+func TestHandler_HandleImage_AllPresets(t *testing.T) {
+	expectedImage := []byte{0xFF, 0xD8, 0xFF, 0xE0}
+	testPDSURL := "https://pds.example.com"
+
+	// Test all valid presets
+	validPresets := []string{"avatar", "avatar_small", "banner", "content_preview", "content_full", "embed_thumbnail"}
+
+	for _, preset := range validPresets {
+		t.Run(preset, func(t *testing.T) {
+			mockSvc := &mockService{
+				getImageFunc: func(ctx context.Context, p, did, cid, pdsURL string) ([]byte, error) {
+					if p != preset {
+						t.Errorf("Expected preset %q, got %q", preset, p)
+					}
+					return expectedImage, nil
+				},
+			}
+
+			mockResolver := &mockIdentityResolver{
+				resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+					return &identity.DIDDocument{
+						DID: did,
+						Service: []identity.Service{
+							{
+								ID:              "#atproto_pds",
+								Type:            "AtprotoPersonalDataServer",
+								ServiceEndpoint: testPDSURL,
+							},
+						},
+					}, nil
+				},
+			}
+
+			handler := NewHandler(mockSvc, mockResolver)
+
+			req := createTestRequest(http.MethodGet, "/img/"+preset+"/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+				"preset": preset,
+				"did":    validTestDID,
+				"cid":    validTestCID,
+			})
+
+			w := httptest.NewRecorder()
+			handler.HandleImage(w, req)
+
+			if w.Code != http.StatusOK {
+				t.Errorf("Expected status 200 for preset %q, got %d. Body: %s", preset, w.Code, w.Body.String())
+			}
+
+			// Verify ETag matches preset
+			etag := w.Header().Get("ETag")
+			expectedETag := `"` + preset + `-` + validTestCID + `"`
+			if etag != expectedETag {
+				t.Errorf("Expected ETag %q, got %q", expectedETag, etag)
+			}
+		})
+	}
+}
+
+func TestHandler_HandleImage_NoPDSEndpoint_Returns502(t *testing.T) {
+	mockSvc := &mockService{}
+	mockResolver := &mockIdentityResolver{
+		resolveDIDFunc: func(ctx context.Context, did string) (*identity.DIDDocument, error) {
+			// Return document without PDS service
+			return &identity.DIDDocument{
+				DID:     did,
+				Service: []identity.Service{},
+			}, nil
+		},
+	}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+validTestCID, map[string]string{
+		"preset": "avatar",
+		"did":    validTestDID,
+		"cid":    validTestCID,
+	})
+
+	w := httptest.NewRecorder()
+	handler.HandleImage(w, req)
+
+	if w.Code != http.StatusBadGateway {
+		t.Errorf("Expected status 502, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}
+
+// TestHandler_HandleImage_InvalidDID tests that invalid DIDs are rejected
+// Note: We use Indigo's syntax.ParseDID for validation consistency with the codebase.
+// Some DIDs that look "wrong" (like did:plc:abc) are actually valid per Indigo's parser.
+func TestHandler_HandleImage_InvalidDID(t *testing.T) {
+	mockSvc := &mockService{}
+	mockResolver := &mockIdentityResolver{}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	// These DIDs are invalid per Indigo's syntax.ParseDID (or fail our security checks)
+	// Note: null bytes can't be tested at HTTP layer - Go's HTTP library rejects them first
+	invalidDIDs := []struct {
+		name string
+		did  string
+	}{
+		{"missing method", "did:abc123"},
+		{"path traversal", "did:plc:../../../etc/passwd"},
+		{"not a DID", "notadid"},
+		{"forward slash", "did:plc:abc/def"},
+		{"backslash", "did:plc:abc\\def"},
+		{"empty string", ""},
+	}
+
+	for _, tc := range invalidDIDs {
+		t.Run(tc.name, func(t *testing.T) {
+			req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+tc.did+"/"+validTestCID, map[string]string{
+				"preset": "avatar",
+				"did":    tc.did,
+				"cid":    validTestCID,
+			})
+
+			w := httptest.NewRecorder()
+			handler.HandleImage(w, req)
+
+			if w.Code != http.StatusBadRequest {
+				t.Errorf("Expected status 400 for invalid DID %q, got %d. Body: %s", tc.did, w.Code, w.Body.String())
+			}
+		})
+	}
+}
+
+// TestHandler_HandleImage_InvalidCID tests that invalid CIDs are rejected
+func TestHandler_HandleImage_InvalidCID(t *testing.T) {
+	mockSvc := &mockService{}
+	mockResolver := &mockIdentityResolver{}
+
+	handler := NewHandler(mockSvc, mockResolver)
+
+	invalidCIDs := []struct {
+		name string
+		cid  string
+	}{
+		{"too short", "bafyabc"},
+		{"path traversal", "../../../etc/passwd"},
+		{"contains slash", "bafy/path/to/file"},
+		{"random string", "this_is_not_a_cid"},
+	}
+
+	for _, tc := range invalidCIDs {
+		t.Run(tc.name, func(t *testing.T) {
+			req := createTestRequest(http.MethodGet, "/img/avatar/plain/"+validTestDID+"/"+tc.cid, map[string]string{
+				"preset": "avatar",
+				"did":    validTestDID,
+				"cid":    tc.cid,
+			})
+
+			w := httptest.NewRecorder()
+			handler.HandleImage(w, req)
+
+			if w.Code != http.StatusBadRequest {
+				t.Errorf("Expected status 400 for invalid CID %q, got %d. Body: %s", tc.cid, w.Code, w.Body.String())
+			}
+		})
+	}
+}

internal/api/routes/imageproxy.go

···
+package routes
+
+import (
+	"github.com/go-chi/chi/v5"
+
+	imageproxyhandlers "Coves/internal/api/handlers/imageproxy"
+)
+
+// RegisterImageProxyRoutes registers image proxy endpoints on the router.
+// The image proxy serves transformed images from AT Protocol PDSes.
+//
+// Route: GET /img/{preset}/plain/{did}/{cid}
+//
+// Parameters:
+//   - preset: Image transformation preset (e.g., "avatar", "banner", "content_preview")
+//   - did: DID of the user who owns the blob
+//   - cid: Content identifier of the blob
+//
+// The endpoint supports ETag-based caching with If-None-Match headers.
+func RegisterImageProxyRoutes(r chi.Router, handler *imageproxyhandlers.Handler) {
+	r.Get("/img/{preset}/plain/{did}/{cid}", handler.HandleImage)
+}

internal/core/blobs/types.go

···
 package blobs
 
 import (
+	"log/slog"
 	"net/url"
 	"strings"
 )
···
 	return strings.TrimSuffix(pdsURL, "/") + "/xrpc/com.atproto.sync.getBlob?did=" +
 		url.QueryEscape(did) + "&cid=" + url.QueryEscape(cid)
 }
+
+// HydrateImageProxyURL generates a URL for the image proxy with the specified preset.
+// Format: {proxyBaseURL}/img/{preset}/plain/{did}/{cid}
+// If proxyBaseURL is empty, generates a relative URL: /img/{preset}/plain/{did}/{cid}
+// Returns empty string if preset, did, or cid are empty.
+// DID and CID are URL-escaped for safety in path segments.
+func HydrateImageProxyURL(proxyBaseURL, preset, did, cid string) string {
+	if preset == "" || did == "" || cid == "" {
+		return ""
+	}
+	return strings.TrimSuffix(proxyBaseURL, "/") + "/img/" + preset + "/plain/" +
+		url.PathEscape(did) + "/" + url.PathEscape(cid)
+}
+
+// ImageURLConfig holds configuration for image URL generation.
+type ImageURLConfig struct {
+	ProxyEnabled bool   // Whether the image proxy is enabled
+	ProxyBaseURL string // Base URL for the image proxy (e.g., "https://coves.social")
+	CDNURL       string // Optional CDN override URL
+}
+
+// HydrateImageURL generates the appropriate image URL based on config.
+// If proxy is disabled, returns direct PDS URL via HydrateBlobURL.
+// If CDN URL is set and proxy is enabled, uses CDN instead of ProxyBaseURL.
+// Returns empty string if the generated URL would be invalid.
+func HydrateImageURL(config ImageURLConfig, pdsURL, did, cid, preset string) string {
+	if !config.ProxyEnabled {
+		return HydrateBlobURL(pdsURL, did, cid)
+	}
+
+	// Determine which base URL to use
+	baseURL := config.ProxyBaseURL
+	if config.CDNURL != "" {
+		baseURL = config.CDNURL
+	}
+
+	// Generate proxy URL
+	proxyURL := HydrateImageProxyURL(baseURL, preset, did, cid)
+
+	// If proxy URL generation failed (e.g., empty preset or base URL), fall back to direct URL
+	// Log this as it indicates a configuration problem when proxy is enabled
+	if proxyURL == "" {
+		slog.Warn("[IMAGE-PROXY] proxy URL generation failed, falling back to direct PDS URL",
+			"proxy_enabled", config.ProxyEnabled,
+			"proxy_base_url", config.ProxyBaseURL,
+			"cdn_url", config.CDNURL,
+			"preset", preset,
+			"did", did,
+			"cid", cid,
+		)
+		return HydrateBlobURL(pdsURL, did, cid)
+	}
+
+	return proxyURL
+}

internal/core/blobs/types_test.go

···
 package blobs
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestHydrateBlobURL(t *testing.T) {
 	tests := []struct {
···
 		})
 	}
 }
+
+func TestHydrateImageProxyURL(t *testing.T) {
+	tests := []struct {
+		name         string
+		proxyBaseURL string
+		preset       string
+		did          string
+		cid          string
+		expected     string
+	}{
+		{
+			name:         "generates correct format",
+			proxyBaseURL: "https://coves.social",
+			preset:       "avatar",
+			did:          "did:plc:abc123",
+			cid:          "bafyreiabc123",
+			expected:     "https://coves.social/img/avatar/plain/did:plc:abc123/bafyreiabc123",
+		},
+		{
+			name:         "trailing slash on proxy URL removed",
+			proxyBaseURL: "https://coves.social/",
+			preset:       "thumb",
+			did:          "did:plc:abc123",
+			cid:          "bafyreiabc123",
+			expected:     "https://coves.social/img/thumb/plain/did:plc:abc123/bafyreiabc123",
+		},
+		{
+			name:         "empty proxyBaseURL generates relative URL",
+			proxyBaseURL: "",
+			preset:       "avatar",
+			did:          "did:plc:abc123",
+			cid:          "bafyreiabc123",
+			expected:     "/img/avatar/plain/did:plc:abc123/bafyreiabc123",
+		},
+		{
+			name:         "empty preset returns empty",
+			proxyBaseURL: "https://coves.social",
+			preset:       "",
+			did:          "did:plc:abc123",
+			cid:          "bafyreiabc123",
+			expected:     "",
+		},
+		{
+			name:         "empty did returns empty",
+			proxyBaseURL: "https://coves.social",
+			preset:       "avatar",
+			did:          "",
+			cid:          "bafyreiabc123",
+			expected:     "",
+		},
+		{
+			name:         "empty cid returns empty",
+			proxyBaseURL: "https://coves.social",
+			preset:       "avatar",
+			did:          "did:plc:abc123",
+			cid:          "",
+			expected:     "",
+		},
+		{
+			name:         "all empty returns empty",
+			proxyBaseURL: "",
+			preset:       "",
+			did:          "",
+			cid:          "",
+			expected:     "",
+		},
+		{
+			name:         "DID with colons preserved in path",
+			proxyBaseURL: "https://coves.social",
+			preset:       "avatar",
+			did:          "did:web:example.com:user",
+			cid:          "bafyreiabc123",
+			// Colons are allowed in path segments per RFC 3986
+			expected: "https://coves.social/img/avatar/plain/did:web:example.com:user/bafyreiabc123",
+		},
+		{
+			name:         "forward slashes escaped in CID",
+			proxyBaseURL: "https://coves.social",
+			preset:       "avatar",
+			did:          "did:plc:abc123",
+			cid:          "bafyrei+special/chars",
+			// Forward slashes must be escaped; plus signs allowed per RFC 3986
+			expected: "https://coves.social/img/avatar/plain/did:plc:abc123/bafyrei+special%2Fchars",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := HydrateImageProxyURL(tt.proxyBaseURL, tt.preset, tt.did, tt.cid)
+			if result != tt.expected {
+				t.Errorf("HydrateImageProxyURL(%q, %q, %q, %q) = %q, want %q",
+					tt.proxyBaseURL, tt.preset, tt.did, tt.cid, result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestHydrateImageURL_ProxyDisabled(t *testing.T) {
+	config := ImageURLConfig{
+		ProxyEnabled: false,
+		ProxyBaseURL: "https://coves.social",
+	}
+	pdsURL := "https://pds.example.com"
+	did := "did:plc:abc123"
+	cid := "bafyreiabc123"
+	preset := "avatar"
+
+	result := HydrateImageURL(config, pdsURL, did, cid, preset)
+
+	// Should return direct PDS URL when proxy is disabled
+	expected := HydrateBlobURL(pdsURL, did, cid)
+	if result != expected {
+		t.Errorf("HydrateImageURL with proxy disabled = %q, want %q", result, expected)
+	}
+}
+
+func TestHydrateImageURL_ProxyEnabled(t *testing.T) {
+	config := ImageURLConfig{
+		ProxyEnabled: true,
+		ProxyBaseURL: "https://coves.social",
+	}
+	pdsURL := "https://pds.example.com"
+	did := "did:plc:abc123"
+	cid := "bafyreiabc123"
+	preset := "avatar"
+
+	result := HydrateImageURL(config, pdsURL, did, cid, preset)
+
+	// Should return proxy URL when proxy is enabled
+	expected := HydrateImageProxyURL(config.ProxyBaseURL, preset, did, cid)
+	if result != expected {
+		t.Errorf("HydrateImageURL with proxy enabled = %q, want %q", result, expected)
+	}
+}
+
+func TestHydrateImageURL_CDNOverride(t *testing.T) {
+	config := ImageURLConfig{
+		ProxyEnabled: true,
+		ProxyBaseURL: "https://coves.social",
+		CDNURL:       "https://cdn.coves.social",
+	}
+	pdsURL := "https://pds.example.com"
+	did := "did:plc:abc123"
+	cid := "bafyreiabc123"
+	preset := "avatar"
+
+	result := HydrateImageURL(config, pdsURL, did, cid, preset)
+
+	// Should use CDN URL instead of proxy base URL
+	expected := HydrateImageProxyURL(config.CDNURL, preset, did, cid)
+	if result != expected {
+		t.Errorf("HydrateImageURL with CDN URL = %q, want %q", result, expected)
+	}
+
+	// Verify CDN URL is actually in the result
+	if !strings.HasPrefix(result, "https://cdn.coves.social/") {
+		t.Errorf("Expected CDN URL prefix, got %q", result)
+	}
+}
+
+func TestHydrateImageURL_EmptyPresetUsesDirectURL(t *testing.T) {
+	config := ImageURLConfig{
+		ProxyEnabled: true,
+		ProxyBaseURL: "https://coves.social",
+	}
+	pdsURL := "https://pds.example.com"
+	did := "did:plc:abc123"
+	cid := "bafyreiabc123"
+	preset := "" // empty preset
+
+	result := HydrateImageURL(config, pdsURL, did, cid, preset)
+
+	// With empty preset, proxy URL will return empty, so fall back to direct URL
+	// This tests the behavior when preset is not specified
+	expected := HydrateBlobURL(pdsURL, did, cid)
+	if result != expected {
+		t.Errorf("HydrateImageURL with empty preset = %q, want %q", result, expected)
+	}
+}
+
+func TestImageURLConfig(t *testing.T) {
+	// Test that ImageURLConfig holds correct fields
+	config := ImageURLConfig{
+		ProxyEnabled: true,
+		ProxyBaseURL: "https://coves.social",
+		CDNURL:       "https://cdn.coves.social",
+	}
+
+	if !config.ProxyEnabled {
+		t.Error("ProxyEnabled should be true")
+	}
+	if config.ProxyBaseURL != "https://coves.social" {
+		t.Errorf("ProxyBaseURL = %q, want %q", config.ProxyBaseURL, "https://coves.social")
+	}
+	if config.CDNURL != "https://cdn.coves.social" {
+		t.Errorf("CDNURL = %q, want %q", config.CDNURL, "https://cdn.coves.social")
+	}
+}

internal/core/communities/community.go

···
 	"fmt"
 	"log"
 	"strings"
+	"sync"
 	"time"
 
 	"Coves/internal/core/blobs"
 )
+
+// imageProxyConfigOnce ensures thread-safe initialization of the image proxy config.
+var imageProxyConfigOnce sync.Once
+
+// imageProxyConfig holds the immutable configuration after initialization.
+// Access only through GetImageProxyConfig().
+var imageProxyConfig = blobs.ImageURLConfig{
+	ProxyEnabled: false, // Default to disabled until configured
+}
+
+// imageProxyConfigInitialized tracks whether SetImageProxyConfig has been called.
+var imageProxyConfigInitialized bool
+
+// SetImageProxyConfig initializes the image proxy configuration.
+// This should be called once during server startup. Subsequent calls are no-ops
+// and will log a warning. This design ensures thread-safety and prevents
+// accidental config changes during runtime.
+func SetImageProxyConfig(config blobs.ImageURLConfig) {
+	imageProxyConfigOnce.Do(func() {
+		imageProxyConfig = config
+		imageProxyConfigInitialized = true
+	})
+	// Log warning if called multiple times (indicates a programming error)
+	if imageProxyConfigInitialized && config != imageProxyConfig {
+		log.Printf("WARN: SetImageProxyConfig called multiple times with different config (ignored)")
+	}
+}
+
+// GetImageProxyConfig returns the current image proxy configuration.
+// Thread-safe for concurrent access.
+func GetImageProxyConfig() blobs.ImageURLConfig {
+	return imageProxyConfig
+}
+
+// ResetImageProxyConfigForTesting resets the config state for testing purposes.
+// This should ONLY be used in tests, never in production code.
+func ResetImageProxyConfigForTesting() {
+	imageProxyConfigOnce = sync.Once{}
+	imageProxyConfig = blobs.ImageURLConfig{ProxyEnabled: false}
+	imageProxyConfigInitialized = false
+}
 
 // Community represents a Coves community indexed from the firehose
 // Communities are federated, instance-scoped forums built on atProto
···
 }
 
 // ToCommunityView converts a Community to a CommunityView for API responses
+// Uses avatar_small preset (24px) for list views
 func (c *Community) ToCommunityView() *CommunityView {
 	view := &CommunityView{
 		DID:             c.DID,
···
 		Name:            c.Name,
 		DisplayName:     c.DisplayName,
 		DisplayHandle:   c.GetDisplayHandle(),
-		Avatar:          blobs.HydrateBlobURL(c.PDSURL, c.DID, c.AvatarCID),
+		Avatar:          blobs.HydrateImageURL(GetImageProxyConfig(), c.PDSURL, c.DID, c.AvatarCID, "avatar_small"),
 		Visibility:      c.Visibility,
 		SubscriberCount: c.SubscriberCount,
 		MemberCount:     c.MemberCount,
···
 }
 
 // ToCommunityViewDetailed converts a Community to a CommunityViewDetailed for API responses
+// Uses avatar preset (80px) for detail views and banner preset for banners
 func (c *Community) ToCommunityViewDetailed() *CommunityViewDetailed {
 	view := &CommunityViewDetailed{
 		DID:                    c.DID,
···
 		DisplayName:            c.DisplayName,
 		DisplayHandle:          c.GetDisplayHandle(),
 		Description:            c.Description,
-		Avatar:                 blobs.HydrateBlobURL(c.PDSURL, c.DID, c.AvatarCID),
-		Banner:                 blobs.HydrateBlobURL(c.PDSURL, c.DID, c.BannerCID),
+		Avatar:                 blobs.HydrateImageURL(GetImageProxyConfig(), c.PDSURL, c.DID, c.AvatarCID, "avatar"),
+		Banner:                 blobs.HydrateImageURL(GetImageProxyConfig(), c.PDSURL, c.DID, c.BannerCID, "banner"),
 		CreatedByDID:           c.CreatedByDID,
 		HostedByDID:            c.HostedByDID,
 		Visibility:             c.Visibility,

internal/core/imageproxy/cache.go

···
+package imageproxy
+
+import (
+	"context"
+	"errors"
+	"io/fs"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+var (
+	// ErrEmptyParameter is returned when a required parameter is empty
+	ErrEmptyParameter = errors.New("required parameter is empty")
+	// ErrInvalidCacheBasePath is returned when the cache base path is empty
+	ErrInvalidCacheBasePath = errors.New("cache base path cannot be empty")
+	// ErrInvalidCacheMaxSize is returned when maxSizeGB is not positive
+	ErrInvalidCacheMaxSize = errors.New("cache max size must be positive")
+)
+
+// Cache defines the interface for image proxy caching
+type Cache interface {
+	// Get retrieves cached image data for the given preset, DID, and CID.
+	// Returns the data, whether it was found, and any error.
+	Get(preset, did, cid string) ([]byte, bool, error)
+
+	// Set stores image data in the cache for the given preset, DID, and CID.
+	Set(preset, did, cid string, data []byte) error
+
+	// Delete removes cached image data for the given preset, DID, and CID.
+	Delete(preset, did, cid string) error
+
+	// Cleanup runs both LRU eviction and TTL cleanup.
+	// Returns the number of entries removed and any error.
+	Cleanup() (int, error)
+}
+
+// DiskCache implements Cache using the filesystem for storage.
+// Cache key format: {basePath}/{preset}/{did_safe}/{cid}
+// where did_safe has colons replaced with underscores for filesystem safety.
+type DiskCache struct {
+	basePath  string
+	maxSizeGB int
+	ttlDays   int
+}
+
+// NewDiskCache creates a new DiskCache with the specified base path, maximum size, and TTL.
+// Returns an error if basePath is empty or maxSizeGB is not positive.
+// ttlDays of 0 disables TTL-based cleanup (only LRU eviction applies).
+func NewDiskCache(basePath string, maxSizeGB int, ttlDays int) (*DiskCache, error) {
+	if basePath == "" {
+		return nil, ErrInvalidCacheBasePath
+	}
+	if maxSizeGB <= 0 {
+		return nil, ErrInvalidCacheMaxSize
+	}
+	if ttlDays < 0 {
+		return nil, errors.New("ttlDays cannot be negative")
+	}
+	return &DiskCache{
+		basePath:  basePath,
+		maxSizeGB: maxSizeGB,
+		ttlDays:   ttlDays,
+	}, nil
+}
+
+// makeDIDSafe converts a DID to a filesystem-safe directory name.
+// It sanitizes the input to prevent path traversal attacks by:
+// - Replacing colons with underscores
+// - Removing path separators (/ and \)
+// - Removing path traversal sequences (..)
+// - Removing null bytes
+func makeDIDSafe(did string) string {
+	// Replace colons with underscores
+	s := strings.ReplaceAll(did, ":", "_")
+
+	// Remove path separators to prevent directory escape
+	s = strings.ReplaceAll(s, "/", "")
+	s = strings.ReplaceAll(s, "\\", "")
+
+	// Remove path traversal sequences
+	s = strings.ReplaceAll(s, "..", "")
+
+	// Remove null bytes (could be used to terminate strings early)
+	s = strings.ReplaceAll(s, "\x00", "")
+
+	return s
+}
+
+// makeCIDSafe sanitizes a CID for use in filesystem paths.
+// It removes characters that could be used for path traversal attacks.
+func makeCIDSafe(cid string) string {
+	// Remove path separators to prevent directory escape
+	s := strings.ReplaceAll(cid, "/", "")
+	s = strings.ReplaceAll(s, "\\", "")
+
+	// Remove path traversal sequences
+	s = strings.ReplaceAll(s, "..", "")
+
+	// Remove null bytes
+	s = strings.ReplaceAll(s, "\x00", "")
+
+	return s
+}
+
+// makePresetSafe sanitizes a preset name for use in filesystem paths.
+func makePresetSafe(preset string) string {
+	// Remove path separators
+	s := strings.ReplaceAll(preset, "/", "")
+	s = strings.ReplaceAll(s, "\\", "")
+
+	// Remove path traversal sequences
+	s = strings.ReplaceAll(s, "..", "")
+
+	// Remove null bytes
+	s = strings.ReplaceAll(s, "\x00", "")
+
+	return s
+}
+
+// cachePath constructs the full filesystem path for a cached item.
+// All components are sanitized to prevent path traversal attacks.
+func (c *DiskCache) cachePath(preset, did, cid string) string {
+	presetSafe := makePresetSafe(preset)
+	didSafe := makeDIDSafe(did)
+	cidSafe := makeCIDSafe(cid)
+	return filepath.Join(c.basePath, presetSafe, didSafe, cidSafe)
+}
+
+// validateParams checks that all required parameters are non-empty.
+func validateParams(preset, did, cid string) error {
+	if preset == "" || did == "" || cid == "" {
+		return ErrEmptyParameter
+	}
+	return nil
+}
+
+// Get retrieves cached image data for the given preset, DID, and CID.
+// Returns the data, whether it was found, and any error.
+// If the item is not in cache, returns (nil, false, nil).
+// Updates the file's modification time on access for LRU tracking.
+func (c *DiskCache) Get(preset, did, cid string) ([]byte, bool, error) {
+	if err := validateParams(preset, did, cid); err != nil {
+		return nil, false, err
+	}
+
+	path := c.cachePath(preset, did, cid)
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, false, nil
+		}
+		return nil, false, err
+	}
+
+	// Update mtime for LRU tracking
+	// Log errors as warnings since failed mtime updates degrade LRU accuracy
+	now := time.Now()
+	if chtimesErr := os.Chtimes(path, now, now); chtimesErr != nil {
+		slog.Warn("[IMAGE-PROXY] failed to update mtime for LRU tracking",
+			"path", path,
+			"error", chtimesErr,
+		)
+	}
+
+	return data, true, nil
+}
+
+// Set stores image data in the cache for the given preset, DID, and CID.
+// Creates necessary directories if they don't exist.
+func (c *DiskCache) Set(preset, did, cid string, data []byte) error {
+	if err := validateParams(preset, did, cid); err != nil {
+		return err
+	}
+
+	path := c.cachePath(preset, did, cid)
+	dir := filepath.Dir(path)
+
+	// Create directory structure if it doesn't exist
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+
+	// Write the file atomically by writing to a temp file first
+	// then renaming (to avoid partial writes on crash)
+	tmpPath := path + ".tmp"
+	if err := os.WriteFile(tmpPath, data, 0644); err != nil {
+		return err
+	}
+
+	return os.Rename(tmpPath, path)
+}
+
+// Delete removes cached image data for the given preset, DID, and CID.
+// Returns nil if the item doesn't exist (idempotent delete).
+func (c *DiskCache) Delete(preset, did, cid string) error {
+	if err := validateParams(preset, did, cid); err != nil {
+		return err
+	}
+
+	path := c.cachePath(preset, did, cid)
+
+	err := os.Remove(path)
+	if err != nil && !os.IsNotExist(err) {
+		return err
+	}
+
+	return nil
+}
+
+// cacheEntry represents a cached file with its metadata.
+type cacheEntry struct {
+	path    string
+	size    int64
+	modTime time.Time
+}
+
+// scanCache walks the cache directory and returns all cache entries.
+func (c *DiskCache) scanCache() ([]cacheEntry, int64, error) {
+	var entries []cacheEntry
+	var totalSize int64
+
+	err := filepath.WalkDir(c.basePath, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+
+		info, err := d.Info()
+		if err != nil {
+			slog.Warn("[IMAGE-PROXY] failed to stat file during cache scan, cache size may be inaccurate",
+				"path", path,
+				"error", err,
+			)
+			return nil // Skip files we can't stat
+		}
+
+		entries = append(entries, cacheEntry{
+			path:    path,
+			size:    info.Size(),
+			modTime: info.ModTime(),
+		})
+		totalSize += info.Size()
+
+		return nil
+	})
+
+	if err != nil && !os.IsNotExist(err) {
+		return nil, 0, err
+	}
+
+	return entries, totalSize, nil
+}
+
+// GetCacheSize returns the current cache size in bytes.
+func (c *DiskCache) GetCacheSize() (int64, error) {
+	_, totalSize, err := c.scanCache()
+	return totalSize, err
+}
+
+// EvictLRU removes the least recently used entries until the cache is under the size limit.
+// Returns the number of entries removed.
+func (c *DiskCache) EvictLRU() (int, error) {
+	entries, totalSize, err := c.scanCache()
+	if err != nil {
+		return 0, err
+	}
+
+	maxSizeBytes := int64(c.maxSizeGB) * 1024 * 1024 * 1024
+	if totalSize <= maxSizeBytes {
+		return 0, nil // Under limit, nothing to do
+	}
+
+	// Sort by modification time (oldest first for LRU)
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].modTime.Before(entries[j].modTime)
+	})
+
+	removed := 0
+	for _, entry := range entries {
+		if totalSize <= maxSizeBytes {
+			break
+		}
+
+		if err := os.Remove(entry.path); err != nil {
+			if !os.IsNotExist(err) {
+				slog.Warn("[IMAGE-PROXY] failed to remove cache entry during LRU eviction",
+					"path", entry.path,
+					"error", err,
+				)
+			}
+			continue
+		}
+
+		totalSize -= entry.size
+		removed++
+
+		slog.Debug("[IMAGE-PROXY] evicted cache entry (LRU)",
+			"path", entry.path,
+			"size_bytes", entry.size,
+		)
+	}
+
+	if removed > 0 {
+		slog.Info("[IMAGE-PROXY] LRU eviction completed",
+			"entries_removed", removed,
+			"new_size_bytes", totalSize,
+			"max_size_bytes", maxSizeBytes,
+		)
+	}
+
+	return removed, nil
+}
+
+// CleanExpired removes cache entries older than the configured TTL.
+// Returns the number of entries removed.
+// If TTL is 0 (disabled), returns 0 without scanning.
+func (c *DiskCache) CleanExpired() (int, error) {
+	if c.ttlDays <= 0 {
+		return 0, nil // TTL disabled
+	}
+
+	entries, _, err := c.scanCache()
+	if err != nil {
+		return 0, err
+	}
+
+	cutoff := time.Now().AddDate(0, 0, -c.ttlDays)
+	removed := 0
+
+	for _, entry := range entries {
+		if entry.modTime.After(cutoff) {
+			continue // Not expired
+		}
+
+		if err := os.Remove(entry.path); err != nil {
+			if !os.IsNotExist(err) {
+				slog.Warn("[IMAGE-PROXY] failed to remove expired cache entry",
+					"path", entry.path,
+					"mod_time", entry.modTime,
+					"error", err,
+				)
+			}
+			continue
+		}
+
+		removed++
+
+		slog.Debug("[IMAGE-PROXY] removed expired cache entry",
+			"path", entry.path,
+			"mod_time", entry.modTime,
+			"ttl_days", c.ttlDays,
+		)
+	}
+
+	if removed > 0 {
+		slog.Info("[IMAGE-PROXY] TTL cleanup completed",
+			"entries_removed", removed,
+			"ttl_days", c.ttlDays,
+		)
+	}
+
+	return removed, nil
+}
+
+// Cleanup runs both TTL cleanup and LRU eviction.
+// TTL cleanup runs first (removes definitely stale entries),
+// then LRU eviction runs if still over size limit.
+// Returns the total number of entries removed.
+func (c *DiskCache) Cleanup() (int, error) {
+	totalRemoved := 0
+
+	// First, remove expired entries (definitely stale)
+	ttlRemoved, err := c.CleanExpired()
+	if err != nil {
+		return 0, err
+	}
+	totalRemoved += ttlRemoved
+
+	// Then, run LRU eviction if still over limit
+	lruRemoved, err := c.EvictLRU()
+	if err != nil {
+		return totalRemoved, err
+	}
+	totalRemoved += lruRemoved
+
+	return totalRemoved, nil
+}
+
+// cleanEmptyDirs removes empty directories under the cache base path.
+// This is useful after eviction/cleanup to remove orphaned preset/DID directories.
+func (c *DiskCache) cleanEmptyDirs() error {
+	// Walk in reverse depth order to clean leaf directories first
+	var dirs []string
+
+	var walkErrors []error
+	err := filepath.WalkDir(c.basePath, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			// Log WalkDir errors but continue scanning to clean as much as possible
+			slog.Warn("[IMAGE-PROXY] error during empty dir cleanup scan",
+				"path", path,
+				"error", err,
+			)
+			walkErrors = append(walkErrors, err)
+			return nil // Continue scanning despite errors
+		}
+		if d.IsDir() && path != c.basePath {
+			dirs = append(dirs, path)
+		}
+		return nil
+	})
+
+	if err != nil {
+		return err
+	}
+
+	if len(walkErrors) > 0 {
+		slog.Warn("[IMAGE-PROXY] encountered errors during empty dir cleanup scan",
+			"error_count", len(walkErrors),
+		)
+	}
+
+	// Sort by length descending (deepest paths first)
+	sort.Slice(dirs, func(i, j int) bool {
+		return len(dirs[i]) > len(dirs[j])
+	})
+
+	var removeErrors int
+	for _, dir := range dirs {
+		entries, err := os.ReadDir(dir)
+		if err != nil {
+			slog.Warn("[IMAGE-PROXY] failed to read directory during cleanup",
+				"path", dir,
+				"error", err,
+			)
+			continue
+		}
+		if len(entries) == 0 {
+			if removeErr := os.Remove(dir); removeErr != nil {
+				slog.Warn("[IMAGE-PROXY] failed to remove empty directory",
+					"path", dir,
+					"error", removeErr,
+				)
+				removeErrors++
+			}
+		}
+	}
+
+	if removeErrors > 0 {
+		slog.Warn("[IMAGE-PROXY] some empty directories could not be removed",
+			"failed_count", removeErrors,
+		)
+	}
+
+	return nil
+}
+
+// StartCleanupJob starts a background goroutine that periodically runs cache cleanup.
+// Returns a cancel function that should be called during graceful shutdown.
+// If interval is 0 or negative, no cleanup job is started and the cancel function is a no-op.
+func (c *DiskCache) StartCleanupJob(interval time.Duration) context.CancelFunc {
+	if interval <= 0 {
+		slog.Info("[IMAGE-PROXY] cache cleanup job disabled (interval=0)")
+		return func() {} // No-op cancel
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				slog.Error("[IMAGE-PROXY] CRITICAL: cache cleanup job panicked",
+					"panic", r,
+				)
+			}
+		}()
+
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+
+		slog.Info("[IMAGE-PROXY] cache cleanup job started",
+			"interval", interval,
+			"ttl_days", c.ttlDays,
+			"max_size_gb", c.maxSizeGB,
+		)
+
+		cycleCount := 0
+		for {
+			select {
+			case <-ctx.Done():
+				slog.Info("[IMAGE-PROXY] cache cleanup job stopped")
+				return
+			case <-ticker.C:
+				cycleCount++
+
+				removed, err := c.Cleanup()
+				if err != nil {
+					slog.Error("[IMAGE-PROXY] cache cleanup error",
+						"error", err,
+						"cycle", cycleCount,
+					)
+					continue
+				}
+
+				// Also clean up empty directories after removing files
+				if removed > 0 {
+					if err := c.cleanEmptyDirs(); err != nil {
+						slog.Warn("[IMAGE-PROXY] failed to clean empty directories",
+							"error", err,
+						)
+					}
+				}
+
+				// Log activity or heartbeat every 6 cycles (6 hours if interval is 1h)
+				if removed > 0 {
+					slog.Info("[IMAGE-PROXY] cache cleanup completed",
+						"entries_removed", removed,
+						"cycle", cycleCount,
+					)
+				} else if cycleCount%6 == 0 {
+					// Get cache size for heartbeat log
+					size, _ := c.GetCacheSize()
+					slog.Debug("[IMAGE-PROXY] cache cleanup heartbeat",
+						"cycle", cycleCount,
+						"cache_size_bytes", size,
+					)
+				}
+			}
+		}
+	}()
+
+	return cancel
+}

internal/core/imageproxy/cache_test.go

···
+package imageproxy
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// mustNewDiskCache is a test helper that creates a DiskCache or fails the test
+// Uses 0 for TTL (disabled) by default for backward compatibility
+func mustNewDiskCache(t *testing.T, basePath string, maxSizeGB int) *DiskCache {
+	t.Helper()
+	cache, err := NewDiskCache(basePath, maxSizeGB, 0)
+	if err != nil {
+		t.Fatalf("NewDiskCache failed: %v", err)
+	}
+	return cache
+}
+
+func TestDiskCache_SetAndGet(t *testing.T) {
+	// Create a temporary directory for the cache
+	tmpDir := t.TempDir()
+
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	testData := []byte("test image data")
+	preset := "thumb"
+	did := "did:plc:abc123"
+	cid := "bafyreiabc123"
+
+	// Set the data
+	err := cache.Set(preset, did, cid, testData)
+	if err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	// Get the data back
+	data, found, err := cache.Get(preset, did, cid)
+	if err != nil {
+		t.Fatalf("Get failed: %v", err)
+	}
+	if !found {
+		t.Fatal("Expected data to be found in cache")
+	}
+	if string(data) != string(testData) {
+		t.Errorf("Get returned %q, want %q", string(data), string(testData))
+	}
+}
+
+func TestDiskCache_GetMissingKey(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	data, found, err := cache.Get("thumb", "did:plc:notexist", "bafynotexist")
+	if err != nil {
+		t.Fatalf("Get should not error for missing key: %v", err)
+	}
+	if found {
+		t.Error("Expected found to be false for missing key")
+	}
+	if data != nil {
+		t.Error("Expected data to be nil for missing key")
+	}
+}
+
+func TestDiskCache_Delete(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	testData := []byte("data to delete")
+	preset := "medium"
+	did := "did:plc:todelete"
+	cid := "bafyreitodelete"
+
+	// Set data
+	err := cache.Set(preset, did, cid, testData)
+	if err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	// Verify it exists
+	_, found, _ := cache.Get(preset, did, cid)
+	if !found {
+		t.Fatal("Expected data to exist before delete")
+	}
+
+	// Delete
+	err = cache.Delete(preset, did, cid)
+	if err != nil {
+		t.Fatalf("Delete failed: %v", err)
+	}
+
+	// Verify it's gone
+	_, found, _ = cache.Get(preset, did, cid)
+	if found {
+		t.Error("Expected data to be gone after delete")
+	}
+}
+
+func TestDiskCache_DeleteNonExistent(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	// Deleting a non-existent key should not error
+	err := cache.Delete("thumb", "did:plc:notexist", "bafynotexist")
+	if err != nil {
+		t.Errorf("Delete of non-existent key should not error: %v", err)
+	}
+}
+
+func TestDiskCache_PathConstruction(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	testData := []byte("path test data")
+	preset := "thumb"
+	did := "did:plc:abc123"
+	cid := "bafyreiabc123"
+
+	err := cache.Set(preset, did, cid, testData)
+	if err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	// Verify the path structure: {basePath}/{preset}/{did_safe}/{cid}
+	// did_safe should have colons replaced with underscores
+	expectedPath := filepath.Join(tmpDir, preset, "did_plc_abc123", cid)
+	if _, err := os.Stat(expectedPath); os.IsNotExist(err) {
+		t.Errorf("Expected cache file at %s to exist", expectedPath)
+	}
+}
+
+func TestDiskCache_HandlesSpecialCharactersInDID(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	tests := []struct {
+		name    string
+		did     string
+		wantDir string
+	}{
+		{
+			name:    "plc DID with colons",
+			did:     "did:plc:abc123",
+			wantDir: "did_plc_abc123",
+		},
+		{
+			name:    "web DID with multiple colons",
+			did:     "did:web:example.com:user",
+			wantDir: "did_web_example.com_user",
+		},
+		{
+			name:    "DID with many segments",
+			did:     "did:plc:a:b:c:d",
+			wantDir: "did_plc_a_b_c_d",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			testData := []byte("test data for " + tt.name)
+			preset := "thumb"
+			cid := "bafytest123"
+
+			err := cache.Set(preset, tt.did, cid, testData)
+			if err != nil {
+				t.Fatalf("Set failed: %v", err)
+			}
+
+			expectedPath := filepath.Join(tmpDir, preset, tt.wantDir, cid)
+			if _, err := os.Stat(expectedPath); os.IsNotExist(err) {
+				t.Errorf("Expected cache file at %s to exist for DID %s", expectedPath, tt.did)
+			}
+
+			// Also verify we can read it back
+			data, found, err := cache.Get(preset, tt.did, cid)
+			if err != nil {
+				t.Fatalf("Get failed: %v", err)
+			}
+			if !found {
+				t.Error("Expected to find cached data")
+			}
+			if string(data) != string(testData) {
+				t.Errorf("Get returned %q, want %q", string(data), string(testData))
+			}
+		})
+	}
+}
+
+func TestDiskCache_DifferentPresetsAreSeparate(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	did := "did:plc:same"
+	cid := "bafysame"
+	thumbData := []byte("thumbnail data")
+	fullData := []byte("full size data")
+
+	// Set different data for different presets
+	err := cache.Set("thumb", did, cid, thumbData)
+	if err != nil {
+		t.Fatalf("Set thumb failed: %v", err)
+	}
+
+	err = cache.Set("full", did, cid, fullData)
+	if err != nil {
+		t.Fatalf("Set full failed: %v", err)
+	}
+
+	// Verify they're separate
+	data, found, _ := cache.Get("thumb", did, cid)
+	if !found {
+		t.Fatal("Expected thumb data to be found")
+	}
+	if string(data) != string(thumbData) {
+		t.Errorf("thumb preset returned wrong data: got %q, want %q", string(data), string(thumbData))
+	}
+
+	data, found, _ = cache.Get("full", did, cid)
+	if !found {
+		t.Fatal("Expected full data to be found")
+	}
+	if string(data) != string(fullData) {
+		t.Errorf("full preset returned wrong data: got %q, want %q", string(data), string(fullData))
+	}
+}
+
+func TestDiskCache_EmptyParametersHandled(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	// Empty preset
+	err := cache.Set("", "did:plc:abc", "bafytest", []byte("data"))
+	if err == nil {
+		t.Error("Expected error when preset is empty")
+	}
+
+	// Empty DID
+	err = cache.Set("thumb", "", "bafytest", []byte("data"))
+	if err == nil {
+		t.Error("Expected error when DID is empty")
+	}
+
+	// Empty CID
+	err = cache.Set("thumb", "did:plc:abc", "", []byte("data"))
+	if err == nil {
+		t.Error("Expected error when CID is empty")
+	}
+}
+
+func TestNewDiskCache(t *testing.T) {
+	cache, err := NewDiskCache("/some/path", 5, 30)
+	if err != nil {
+		t.Fatalf("NewDiskCache failed: %v", err)
+	}
+
+	if cache == nil {
+		t.Fatal("NewDiskCache returned nil")
+	}
+	if cache.basePath != "/some/path" {
+		t.Errorf("basePath = %q, want %q", cache.basePath, "/some/path")
+	}
+	if cache.maxSizeGB != 5 {
+		t.Errorf("maxSizeGB = %d, want %d", cache.maxSizeGB, 5)
+	}
+	if cache.ttlDays != 30 {
+		t.Errorf("ttlDays = %d, want %d", cache.ttlDays, 30)
+	}
+}
+
+func TestNewDiskCache_Errors(t *testing.T) {
+	t.Run("empty base path", func(t *testing.T) {
+		_, err := NewDiskCache("", 5, 0)
+		if !errors.Is(err, ErrInvalidCacheBasePath) {
+			t.Errorf("expected ErrInvalidCacheBasePath, got: %v", err)
+		}
+	})
+
+	t.Run("zero max size", func(t *testing.T) {
+		_, err := NewDiskCache("/some/path", 0, 0)
+		if !errors.Is(err, ErrInvalidCacheMaxSize) {
+			t.Errorf("expected ErrInvalidCacheMaxSize, got: %v", err)
+		}
+	})
+
+	t.Run("negative max size", func(t *testing.T) {
+		_, err := NewDiskCache("/some/path", -1, 0)
+		if !errors.Is(err, ErrInvalidCacheMaxSize) {
+			t.Errorf("expected ErrInvalidCacheMaxSize, got: %v", err)
+		}
+	})
+
+	t.Run("negative TTL", func(t *testing.T) {
+		_, err := NewDiskCache("/some/path", 5, -1)
+		if err == nil {
+			t.Error("expected error for negative TTL")
+		}
+	})
+}
+
+func TestCache_InterfaceImplementation(t *testing.T) {
+	// Compile-time check that DiskCache implements Cache
+	var _ Cache = (*DiskCache)(nil)
+}
+
+func TestDiskCache_GetCacheSize(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	// Empty cache should be 0
+	size, err := cache.GetCacheSize()
+	if err != nil {
+		t.Fatalf("GetCacheSize failed: %v", err)
+	}
+	if size != 0 {
+		t.Errorf("Expected 0 for empty cache, got %d", size)
+	}
+
+	// Add some data
+	data := make([]byte, 1000) // 1KB
+	if err := cache.Set("avatar", "did:plc:test1", "cid1", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+	if err := cache.Set("avatar", "did:plc:test2", "cid2", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	size, err = cache.GetCacheSize()
+	if err != nil {
+		t.Fatalf("GetCacheSize failed: %v", err)
+	}
+	if size != 2000 {
+		t.Errorf("Expected 2000 bytes, got %d", size)
+	}
+}
+
+func TestDiskCache_EvictLRU(t *testing.T) {
+	tmpDir := t.TempDir()
+	// Use a very small max size (1 byte) so any data triggers eviction
+	cache, err := NewDiskCache(tmpDir, 1, 0) // 1GB but we'll add more than that won't fit
+	if err != nil {
+		t.Fatalf("NewDiskCache failed: %v", err)
+	}
+
+	// Add some files with different modification times
+	data := make([]byte, 100)
+
+	// Create old file
+	if err := cache.Set("avatar", "did:plc:old", "cid_old", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+	oldPath := cache.cachePath("avatar", "did:plc:old", "cid_old")
+	oldTime := time.Now().Add(-24 * time.Hour)
+	if err := os.Chtimes(oldPath, oldTime, oldTime); err != nil {
+		t.Fatalf("Chtimes failed: %v", err)
+	}
+
+	// Create new file
+	if err := cache.Set("avatar", "did:plc:new", "cid_new", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	// Cache is under 1GB so eviction shouldn't remove anything
+	removed, err := cache.EvictLRU()
+	if err != nil {
+		t.Fatalf("EvictLRU failed: %v", err)
+	}
+	if removed != 0 {
+		t.Errorf("Expected 0 entries removed (under limit), got %d", removed)
+	}
+
+	// Both files should still exist
+	if _, found, _ := cache.Get("avatar", "did:plc:old", "cid_old"); !found {
+		t.Error("Old entry should still exist")
+	}
+	if _, found, _ := cache.Get("avatar", "did:plc:new", "cid_new"); !found {
+		t.Error("New entry should still exist")
+	}
+}
+
+func TestDiskCache_CleanExpired(t *testing.T) {
+	tmpDir := t.TempDir()
+	// TTL of 1 day
+	cache, err := NewDiskCache(tmpDir, 1, 1)
+	if err != nil {
+		t.Fatalf("NewDiskCache failed: %v", err)
+	}
+
+	data := make([]byte, 100)
+
+	// Create fresh file
+	if err := cache.Set("avatar", "did:plc:fresh", "cid_fresh", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	// Create expired file (manually set old mtime)
+	if err := cache.Set("avatar", "did:plc:expired", "cid_expired", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+	expiredPath := cache.cachePath("avatar", "did:plc:expired", "cid_expired")
+	oldTime := time.Now().Add(-48 * time.Hour) // 2 days old, TTL is 1 day
+	if err := os.Chtimes(expiredPath, oldTime, oldTime); err != nil {
+		t.Fatalf("Chtimes failed: %v", err)
+	}
+
+	// Clean expired entries
+	removed, err := cache.CleanExpired()
+	if err != nil {
+		t.Fatalf("CleanExpired failed: %v", err)
+	}
+	if removed != 1 {
+		t.Errorf("Expected 1 expired entry removed, got %d", removed)
+	}
+
+	// Fresh file should still exist
+	if _, found, _ := cache.Get("avatar", "did:plc:fresh", "cid_fresh"); !found {
+		t.Error("Fresh entry should still exist")
+	}
+
+	// Expired file should be gone
+	if _, found, _ := cache.Get("avatar", "did:plc:expired", "cid_expired"); found {
+		t.Error("Expired entry should be removed")
+	}
+}
+
+func TestDiskCache_CleanExpired_TTLDisabled(t *testing.T) {
+	tmpDir := t.TempDir()
+	// TTL of 0 = disabled
+	cache, err := NewDiskCache(tmpDir, 1, 0)
+	if err != nil {
+		t.Fatalf("NewDiskCache failed: %v", err)
+	}
+
+	data := make([]byte, 100)
+
+	// Create a file with old mtime
+	if err := cache.Set("avatar", "did:plc:old", "cid_old", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+	path := cache.cachePath("avatar", "did:plc:old", "cid_old")
+	oldTime := time.Now().Add(-365 * 24 * time.Hour) // 1 year old
+	if err := os.Chtimes(path, oldTime, oldTime); err != nil {
+		t.Fatalf("Chtimes failed: %v", err)
+	}
+
+	// Clean expired should do nothing when TTL is disabled
+	removed, err := cache.CleanExpired()
+	if err != nil {
+		t.Fatalf("CleanExpired failed: %v", err)
+	}
+	if removed != 0 {
+		t.Errorf("Expected 0 removed with TTL disabled, got %d", removed)
+	}
+
+	// File should still exist
+	if _, found, _ := cache.Get("avatar", "did:plc:old", "cid_old"); !found {
+		t.Error("Entry should still exist when TTL is disabled")
+	}
+}
+
+func TestDiskCache_Cleanup(t *testing.T) {
+	tmpDir := t.TempDir()
+	// TTL of 1 day
+	cache, err := NewDiskCache(tmpDir, 1, 1)
+	if err != nil {
+		t.Fatalf("NewDiskCache failed: %v", err)
+	}
+
+	data := make([]byte, 100)
+
+	// Create fresh file
+	if err := cache.Set("avatar", "did:plc:fresh", "cid_fresh", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	// Create expired file
+	if err := cache.Set("avatar", "did:plc:expired", "cid_expired", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+	expiredPath := cache.cachePath("avatar", "did:plc:expired", "cid_expired")
+	oldTime := time.Now().Add(-48 * time.Hour)
+	if err := os.Chtimes(expiredPath, oldTime, oldTime); err != nil {
+		t.Fatalf("Chtimes failed: %v", err)
+	}
+
+	// Cleanup should remove expired entry
+	removed, err := cache.Cleanup()
+	if err != nil {
+		t.Fatalf("Cleanup failed: %v", err)
+	}
+	if removed != 1 {
+		t.Errorf("Expected 1 entry removed, got %d", removed)
+	}
+
+	// Fresh file should still exist
+	if _, found, _ := cache.Get("avatar", "did:plc:fresh", "cid_fresh"); !found {
+		t.Error("Fresh entry should still exist")
+	}
+}
+
+func TestDiskCache_GetUpdatesMtime(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	data := []byte("test data")
+	if err := cache.Set("avatar", "did:plc:test", "cid1", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+
+	path := cache.cachePath("avatar", "did:plc:test", "cid1")
+
+	// Set an old mtime
+	oldTime := time.Now().Add(-24 * time.Hour)
+	if err := os.Chtimes(path, oldTime, oldTime); err != nil {
+		t.Fatalf("Chtimes failed: %v", err)
+	}
+
+	// Get the file - this should update mtime
+	_, found, err := cache.Get("avatar", "did:plc:test", "cid1")
+	if err != nil {
+		t.Fatalf("Get failed: %v", err)
+	}
+	if !found {
+		t.Fatal("Expected to find entry")
+	}
+
+	// Check that mtime was updated
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("Stat failed: %v", err)
+	}
+
+	// Mtime should be recent (within last minute)
+	if time.Since(info.ModTime()) > time.Minute {
+		t.Errorf("Expected mtime to be updated to now, but it's %v old", time.Since(info.ModTime()))
+	}
+}
+
+func TestDiskCache_StartCleanupJob(t *testing.T) {
+	tmpDir := t.TempDir()
+	// Create cache with 1 day TTL
+	cache, err := NewDiskCache(tmpDir, 1, 1)
+	if err != nil {
+		t.Fatalf("NewDiskCache failed: %v", err)
+	}
+
+	data := make([]byte, 100)
+
+	// Create an expired file
+	if err := cache.Set("avatar", "did:plc:expired", "cid_expired", data); err != nil {
+		t.Fatalf("Set failed: %v", err)
+	}
+	expiredPath := cache.cachePath("avatar", "did:plc:expired", "cid_expired")
+	oldTime := time.Now().Add(-48 * time.Hour)
+	if err := os.Chtimes(expiredPath, oldTime, oldTime); err != nil {
+		t.Fatalf("Chtimes failed: %v", err)
+	}
+
+	// Start cleanup job with very short interval
+	cancel := cache.StartCleanupJob(50 * time.Millisecond)
+	defer cancel()
+
+	// Wait for at least one cleanup cycle
+	time.Sleep(100 * time.Millisecond)
+
+	// Expired file should be gone
+	if _, found, _ := cache.Get("avatar", "did:plc:expired", "cid_expired"); found {
+		t.Error("Expired entry should have been cleaned up by background job")
+	}
+}
+
+func TestDiskCache_StartCleanupJob_ZeroInterval(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	// Starting with 0 interval should return a no-op cancel
+	cancel := cache.StartCleanupJob(0)
+	defer cancel()
+
+	// Should not panic when called
+	cancel()
+	cancel() // Multiple calls should be safe
+}
+
+func TestDiskCache_StartCleanupJob_GracefulShutdown(t *testing.T) {
+	tmpDir := t.TempDir()
+	cache := mustNewDiskCache(t, tmpDir, 1)
+
+	// Start cleanup job
+	cancel := cache.StartCleanupJob(10 * time.Millisecond)
+
+	// Let it run briefly
+	time.Sleep(30 * time.Millisecond)
+
+	// Cancel should not hang or panic
+	done := make(chan struct{})
+	go func() {
+		cancel()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// Good, cancel returned
+	case <-time.After(1 * time.Second):
+		t.Error("Cancel took too long, may be stuck")
+	}
+}

internal/core/imageproxy/config.go

···
+package imageproxy
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"strconv"
+	"time"
+)
+
+// Config validation errors
+var (
+	// ErrInvalidCacheMaxGB is returned when CacheMaxGB is not positive
+	ErrInvalidCacheMaxGB = errors.New("CacheMaxGB must be positive")
+	// ErrInvalidFetchTimeout is returned when FetchTimeout is not positive
+	ErrInvalidFetchTimeout = errors.New("FetchTimeout must be positive")
+	// ErrInvalidMaxSourceSize is returned when MaxSourceSizeMB is not positive
+	ErrInvalidMaxSourceSize = errors.New("MaxSourceSizeMB must be positive")
+	// ErrMissingCachePath is returned when CachePath is empty while Enabled is true
+	ErrMissingCachePath = errors.New("CachePath is required when proxy is enabled")
+	// ErrInvalidCacheTTL is returned when CacheTTLDays is negative
+	ErrInvalidCacheTTL = errors.New("CacheTTLDays cannot be negative")
+)
+
+// Config holds the configuration for the image proxy service.
+type Config struct {
+	// Enabled determines whether the image proxy service is active.
+	Enabled bool
+
+	// BaseURL is the origin/domain for the image proxy service (e.g., "https://coves.social").
+	// Empty string generates relative URLs (e.g., "/img/avatar/plain/did/cid").
+	// The /img path prefix is added automatically by the URL generation function.
+	BaseURL string
+
+	// CachePath is the filesystem path where cached images are stored.
+	CachePath string
+
+	// CacheMaxGB is the maximum cache size in gigabytes.
+	CacheMaxGB int
+
+	// CacheTTLDays is the maximum age in days for cached entries.
+	// Entries older than this are eligible for cleanup regardless of cache size.
+	// Set to 0 to disable TTL-based cleanup (only LRU eviction applies).
+	CacheTTLDays int
+
+	// CleanupInterval is how often to run cache cleanup (TTL + LRU eviction).
+	// Set to 0 to disable background cleanup.
+	CleanupInterval time.Duration
+
+	// CDNURL is the optional CDN URL prefix for serving cached images.
+	CDNURL string
+
+	// FetchTimeout is the maximum time allowed for fetching images from PDS.
+	FetchTimeout time.Duration
+
+	// MaxSourceSizeMB is the maximum allowed size for source images in megabytes.
+	MaxSourceSizeMB int
+}
+
+// NewConfig creates a new Config with the provided values and validates it.
+// This is the recommended way to create a Config, as it ensures all invariants are satisfied.
+// Use DefaultConfig() or ConfigFromEnv() for convenient config creation with sensible defaults.
+func NewConfig(
+	enabled bool,
+	baseURL string,
+	cachePath string,
+	cacheMaxGB int,
+	cacheTTLDays int,
+	cleanupInterval time.Duration,
+	cdnURL string,
+	fetchTimeout time.Duration,
+	maxSourceSizeMB int,
+) (Config, error) {
+	cfg := Config{
+		Enabled:         enabled,
+		BaseURL:         baseURL,
+		CachePath:       cachePath,
+		CacheMaxGB:      cacheMaxGB,
+		CacheTTLDays:    cacheTTLDays,
+		CleanupInterval: cleanupInterval,
+		CDNURL:          cdnURL,
+		FetchTimeout:    fetchTimeout,
+		MaxSourceSizeMB: maxSourceSizeMB,
+	}
+
+	if err := cfg.Validate(); err != nil {
+		return Config{}, err
+	}
+
+	return cfg, nil
+}
+
+// Validate checks the configuration for invalid values.
+// Returns nil if the configuration is valid, or an error describing the problem.
+// When Enabled is false, only numeric constraints are validated (for safety).
+// When Enabled is true, all required fields must be set.
+func (c Config) Validate() error {
+	// Always validate numeric constraints regardless of enabled state
+	if c.CacheMaxGB <= 0 {
+		return fmt.Errorf("%w: got %d", ErrInvalidCacheMaxGB, c.CacheMaxGB)
+	}
+	if c.FetchTimeout <= 0 {
+		return fmt.Errorf("%w: got %v", ErrInvalidFetchTimeout, c.FetchTimeout)
+	}
+	if c.MaxSourceSizeMB <= 0 {
+		return fmt.Errorf("%w: got %d", ErrInvalidMaxSourceSize, c.MaxSourceSizeMB)
+	}
+	if c.CacheTTLDays < 0 {
+		return fmt.Errorf("%w: got %d", ErrInvalidCacheTTL, c.CacheTTLDays)
+	}
+
+	// When enabled, validate required fields
+	if c.Enabled {
+		if c.CachePath == "" {
+			return ErrMissingCachePath
+		}
+		// BaseURL can be empty for relative URLs
+	}
+
+	return nil
+}
+
+// DefaultConfig returns a Config with sensible default values.
+func DefaultConfig() Config {
+	return Config{
+		Enabled:         true,
+		BaseURL:         "",
+		CachePath:       "/var/cache/coves/images",
+		CacheMaxGB:      10,
+		CacheTTLDays:    30,
+		CleanupInterval: 1 * time.Hour,
+		CDNURL:          "",
+		FetchTimeout:    30 * time.Second,
+		MaxSourceSizeMB: 10,
+	}
+}
+
+// ConfigFromEnv creates a Config from environment variables.
+// Uses defaults for any missing environment variables.
+//
+// Environment variables:
+//   - IMAGE_PROXY_ENABLED: "true"/"1" to enable, "false"/"0" to disable (default: true)
+//   - IMAGE_PROXY_BASE_URL: origin URL for image proxy (default: "" for relative URLs)
+//   - IMAGE_PROXY_CACHE_PATH: filesystem cache path (default: "/var/cache/coves/images")
+//   - IMAGE_PROXY_CACHE_MAX_GB: max cache size in GB (default: 10)
+//   - IMAGE_PROXY_CACHE_TTL_DAYS: max age for cache entries in days, 0 to disable (default: 30)
+//   - IMAGE_PROXY_CLEANUP_INTERVAL_MINUTES: cleanup job interval in minutes, 0 to disable (default: 60)
+//   - IMAGE_PROXY_CDN_URL: optional CDN URL prefix (default: "")
+//   - IMAGE_PROXY_FETCH_TIMEOUT_SECONDS: PDS fetch timeout in seconds (default: 30)
+//   - IMAGE_PROXY_MAX_SOURCE_SIZE_MB: max source image size in MB (default: 10)
+func ConfigFromEnv() Config {
+	cfg := DefaultConfig()
+
+	if v := os.Getenv("IMAGE_PROXY_ENABLED"); v != "" {
+		cfg.Enabled = v == "true" || v == "1"
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_BASE_URL"); v != "" {
+		cfg.BaseURL = v
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_CACHE_PATH"); v != "" {
+		cfg.CachePath = v
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_CACHE_MAX_GB"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			cfg.CacheMaxGB = n
+		} else {
+			slog.Warn("[IMAGE-PROXY] invalid IMAGE_PROXY_CACHE_MAX_GB value, using default",
+				"value", v,
+				"default", cfg.CacheMaxGB,
+				"error", err,
+			)
+		}
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_CACHE_TTL_DAYS"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
+			cfg.CacheTTLDays = n
+		} else {
+			slog.Warn("[IMAGE-PROXY] invalid IMAGE_PROXY_CACHE_TTL_DAYS value, using default",
+				"value", v,
+				"default", cfg.CacheTTLDays,
+				"error", err,
+			)
+		}
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_CLEANUP_INTERVAL_MINUTES"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
+			cfg.CleanupInterval = time.Duration(n) * time.Minute
+		} else {
+			slog.Warn("[IMAGE-PROXY] invalid IMAGE_PROXY_CLEANUP_INTERVAL_MINUTES value, using default",
+				"value", v,
+				"default_minutes", int(cfg.CleanupInterval.Minutes()),
+				"error", err,
+			)
+		}
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_CDN_URL"); v != "" {
+		cfg.CDNURL = v
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_FETCH_TIMEOUT_SECONDS"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			cfg.FetchTimeout = time.Duration(n) * time.Second
+		} else {
+			slog.Warn("[IMAGE-PROXY] invalid IMAGE_PROXY_FETCH_TIMEOUT_SECONDS value, using default",
+				"value", v,
+				"default_seconds", int(cfg.FetchTimeout.Seconds()),
+				"error", err,
+			)
+		}
+	}
+
+	if v := os.Getenv("IMAGE_PROXY_MAX_SOURCE_SIZE_MB"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			cfg.MaxSourceSizeMB = n
+		} else {
+			slog.Warn("[IMAGE-PROXY] invalid IMAGE_PROXY_MAX_SOURCE_SIZE_MB value, using default",
+				"value", v,
+				"default", cfg.MaxSourceSizeMB,
+				"error", err,
+			)
+		}
+	}
+
+	return cfg
+}

internal/core/imageproxy/config_test.go

···
+package imageproxy
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestConfig_Validate(t *testing.T) {
+	tests := []struct {
+		name    string
+		config  Config
+		wantErr error
+	}{
+		{
+			name:    "valid default config",
+			config:  DefaultConfig(),
+			wantErr: nil,
+		},
+		{
+			name: "valid enabled config",
+			config: Config{
+				Enabled:         true,
+				BaseURL:         "/img",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: nil,
+		},
+		{
+			name: "invalid CacheMaxGB zero",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "/img",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      0,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: ErrInvalidCacheMaxGB,
+		},
+		{
+			name: "invalid CacheMaxGB negative",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "/img",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      -5,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: ErrInvalidCacheMaxGB,
+		},
+		{
+			name: "invalid FetchTimeout zero",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "/img",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				FetchTimeout:    0,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: ErrInvalidFetchTimeout,
+		},
+		{
+			name: "invalid FetchTimeout negative",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "/img",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				FetchTimeout:    -1 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: ErrInvalidFetchTimeout,
+		},
+		{
+			name: "invalid MaxSourceSizeMB zero",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "/img",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 0,
+			},
+			wantErr: ErrInvalidMaxSourceSize,
+		},
+		{
+			name: "invalid MaxSourceSizeMB negative",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "/img",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: -5,
+			},
+			wantErr: ErrInvalidMaxSourceSize,
+		},
+		{
+			name: "enabled but missing CachePath",
+			config: Config{
+				Enabled:         true,
+				BaseURL:         "/img",
+				CachePath:       "",
+				CacheMaxGB:      10,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: ErrMissingCachePath,
+		},
+		{
+			name: "enabled allows empty BaseURL for relative URLs",
+			config: Config{
+				Enabled:         true,
+				BaseURL:         "",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: nil,
+		},
+		{
+			name: "disabled allows empty CachePath",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "/img",
+				CachePath:       "",
+				CacheMaxGB:      10,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: nil,
+		},
+		{
+			name: "disabled allows empty BaseURL",
+			config: Config{
+				Enabled:         false,
+				BaseURL:         "",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: nil,
+		},
+		{
+			name: "valid TTL zero (disabled)",
+			config: Config{
+				Enabled:         true,
+				BaseURL:         "",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				CacheTTLDays:    0,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: nil,
+		},
+		{
+			name: "valid TTL positive",
+			config: Config{
+				Enabled:         true,
+				BaseURL:         "",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				CacheTTLDays:    30,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: nil,
+		},
+		{
+			name: "invalid TTL negative",
+			config: Config{
+				Enabled:         true,
+				BaseURL:         "",
+				CachePath:       "/var/cache/images",
+				CacheMaxGB:      10,
+				CacheTTLDays:    -1,
+				FetchTimeout:    30 * time.Second,
+				MaxSourceSizeMB: 10,
+			},
+			wantErr: ErrInvalidCacheTTL,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.config.Validate()
+			if tt.wantErr == nil {
+				if err != nil {
+					t.Errorf("expected no error, got: %v", err)
+				}
+			} else {
+				if !errors.Is(err, tt.wantErr) {
+					t.Errorf("expected %v, got: %v", tt.wantErr, err)
+				}
+			}
+		})
+	}
+}
+
+func TestDefaultConfig(t *testing.T) {
+	cfg := DefaultConfig()
+
+	// Verify default values
+	if !cfg.Enabled {
+		t.Error("expected Enabled to be true by default")
+	}
+	if cfg.BaseURL != "" {
+		t.Errorf("expected empty BaseURL for relative URLs, got %q", cfg.BaseURL)
+	}
+	if cfg.CachePath != "/var/cache/coves/images" {
+		t.Errorf("expected CachePath '/var/cache/coves/images', got %q", cfg.CachePath)
+	}
+	if cfg.CacheMaxGB != 10 {
+		t.Errorf("expected CacheMaxGB 10, got %d", cfg.CacheMaxGB)
+	}
+	if cfg.CacheTTLDays != 30 {
+		t.Errorf("expected CacheTTLDays 30, got %d", cfg.CacheTTLDays)
+	}
+	if cfg.CleanupInterval != 1*time.Hour {
+		t.Errorf("expected CleanupInterval 1h, got %v", cfg.CleanupInterval)
+	}
+	if cfg.CDNURL != "" {
+		t.Errorf("expected empty CDNURL, got %q", cfg.CDNURL)
+	}
+	if cfg.FetchTimeout != 30*time.Second {
+		t.Errorf("expected FetchTimeout 30s, got %v", cfg.FetchTimeout)
+	}
+	if cfg.MaxSourceSizeMB != 10 {
+		t.Errorf("expected MaxSourceSizeMB 10, got %d", cfg.MaxSourceSizeMB)
+	}
+
+	// Default config should be valid
+	if err := cfg.Validate(); err != nil {
+		t.Errorf("default config should be valid, got error: %v", err)
+	}
+}

internal/core/imageproxy/errors.go

···
+package imageproxy
+
+import "errors"
+
+var (
+	// ErrInvalidPreset is returned when a preset name is not found in the preset registry.
+	ErrInvalidPreset = errors.New("invalid image preset")
+
+	// ErrInvalidDID is returned when a DID string does not match expected atproto DID format.
+	ErrInvalidDID = errors.New("invalid DID format")
+
+	// ErrInvalidCID is returned when a CID string is not a valid content identifier.
+	ErrInvalidCID = errors.New("invalid CID format")
+
+	// ErrPDSFetchFailed is returned when fetching a blob from a PDS fails for any reason.
+	ErrPDSFetchFailed = errors.New("failed to fetch blob from PDS")
+
+	// ErrPDSNotFound is returned when the requested blob does not exist on the PDS.
+	ErrPDSNotFound = errors.New("blob not found on PDS")
+
+	// ErrPDSTimeout is returned when a PDS request exceeds the configured timeout.
+	ErrPDSTimeout = errors.New("PDS request timed out")
+
+	// ErrUnsupportedFormat is returned when the source image format cannot be processed.
+	ErrUnsupportedFormat = errors.New("unsupported image format")
+
+	// ErrImageTooLarge is returned when the source image exceeds the maximum allowed size.
+	ErrImageTooLarge = errors.New("source image exceeds size limit")
+
+	// ErrProcessingFailed is returned when image processing fails for any reason.
+	ErrProcessingFailed = errors.New("image processing failed")
+
+	// ErrNilDependency is returned when a required dependency is nil.
+	ErrNilDependency = errors.New("required dependency is nil")
+)

internal/core/imageproxy/fetcher.go

···
+package imageproxy
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// Fetcher defines the interface for fetching blobs from a PDS.
+type Fetcher interface {
+	// Fetch retrieves a blob from the specified PDS.
+	// Returns the blob bytes or an error if the fetch fails.
+	Fetch(ctx context.Context, pdsURL, did, cid string) ([]byte, error)
+}
+
+// PDSFetcher implements the Fetcher interface for fetching blobs from atproto PDS servers.
+type PDSFetcher struct {
+	client       *http.Client
+	timeout      time.Duration
+	maxSizeBytes int64
+}
+
+// DefaultMaxSourceSizeMB is the default maximum source image size if not configured.
+const DefaultMaxSourceSizeMB = 10
+
+// NewPDSFetcher creates a new PDSFetcher with the specified timeout.
+// maxSizeMB specifies the maximum allowed image size in megabytes (0 uses default of 10MB).
+func NewPDSFetcher(timeout time.Duration, maxSizeMB int) *PDSFetcher {
+	if maxSizeMB <= 0 {
+		maxSizeMB = DefaultMaxSourceSizeMB
+	}
+	return &PDSFetcher{
+		client: &http.Client{
+			Timeout: timeout,
+		},
+		timeout:      timeout,
+		maxSizeBytes: int64(maxSizeMB) * 1024 * 1024,
+	}
+}
+
+// Fetch retrieves a blob from the specified PDS using the com.atproto.sync.getBlob endpoint.
+// Returns:
+//   - ErrPDSNotFound if the blob does not exist (404 response)
+//   - ErrPDSTimeout if the request times out or context is cancelled
+//   - ErrPDSFetchFailed for any other error
+func (f *PDSFetcher) Fetch(ctx context.Context, pdsURL, did, cid string) ([]byte, error) {
+	// Construct the request URL
+	endpoint, err := url.Parse(pdsURL)
+	if err != nil {
+		return nil, fmt.Errorf("%w: invalid PDS URL: %v", ErrPDSFetchFailed, err)
+	}
+	endpoint.Path = "/xrpc/com.atproto.sync.getBlob"
+
+	query := url.Values{}
+	query.Set("did", did)
+	query.Set("cid", cid)
+	endpoint.RawQuery = query.Encode()
+
+	// Create the request with context
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint.String(), nil)
+	if err != nil {
+		return nil, fmt.Errorf("%w: failed to create request: %v", ErrPDSFetchFailed, err)
+	}
+
+	// Set User-Agent header for identification
+	req.Header.Set("User-Agent", "Coves-ImageProxy/1.0")
+
+	// Execute the request
+	resp, err := f.client.Do(req)
+	if err != nil {
+		// Check if the error is due to context cancellation or timeout
+		if ctx.Err() != nil {
+			return nil, fmt.Errorf("%w: %v", ErrPDSTimeout, ctx.Err())
+		}
+		// Check if it's a timeout error from the http client
+		if isTimeoutError(err) {
+			return nil, fmt.Errorf("%w: request timed out", ErrPDSTimeout)
+		}
+		return nil, fmt.Errorf("%w: %v", ErrPDSFetchFailed, err)
+	}
+	defer resp.Body.Close()
+
+	// Handle response status codes
+	switch resp.StatusCode {
+	case http.StatusOK:
+		// Check Content-Length header if available
+		if resp.ContentLength > 0 && resp.ContentLength > f.maxSizeBytes {
+			return nil, fmt.Errorf("%w: content length %d exceeds maximum %d bytes",
+				ErrImageTooLarge, resp.ContentLength, f.maxSizeBytes)
+		}
+
+		// Use a limited reader to prevent memory exhaustion even if Content-Length is missing or wrong.
+		// We read maxSizeBytes + 1 to detect if the response exceeds the limit.
+		limitedReader := io.LimitReader(resp.Body, f.maxSizeBytes+1)
+		data, err := io.ReadAll(limitedReader)
+		if err != nil {
+			return nil, fmt.Errorf("%w: failed to read response body: %v", ErrPDSFetchFailed, err)
+		}
+
+		// Check if we hit the limit (meaning there was more data)
+		if int64(len(data)) > f.maxSizeBytes {
+			return nil, fmt.Errorf("%w: response body exceeds maximum %d bytes",
+				ErrImageTooLarge, f.maxSizeBytes)
+		}
+
+		return data, nil
+
+	case http.StatusNotFound:
+		return nil, ErrPDSNotFound
+
+	case http.StatusBadRequest:
+		// AT Protocol PDS may return 400 with "Blob not found" for missing blobs
+		// We need to check the error message to distinguish from actual bad requests
+		body, readErr := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		if readErr == nil && isBlobNotFoundError(body) {
+			return nil, ErrPDSNotFound
+		}
+		return nil, fmt.Errorf("%w: bad request (status 400)", ErrPDSFetchFailed)
+
+	default:
+		return nil, fmt.Errorf("%w: unexpected status code %d", ErrPDSFetchFailed, resp.StatusCode)
+	}
+}
+
+// pdsErrorResponse represents the error response structure from AT Protocol PDS
+type pdsErrorResponse struct {
+	Error   string `json:"error"`
+	Message string `json:"message"`
+}
+
+// isBlobNotFoundError checks if the error response indicates a blob was not found.
+// AT Protocol PDS returns 400 with {"error":"InvalidRequest","message":"Blob not found"}
+// for missing blobs instead of a proper 404.
+func isBlobNotFoundError(body []byte) bool {
+	var errResp pdsErrorResponse
+	if err := json.Unmarshal(body, &errResp); err != nil {
+		return false
+	}
+	// Check for "Blob not found" message (case-insensitive)
+	return strings.Contains(strings.ToLower(errResp.Message), "blob not found")
+}
+
+// isTimeoutError checks if the error is a timeout-related error.
+func isTimeoutError(err error) bool {
+	if err == nil {
+		return false
+	}
+	// Check for timeout interface
+	if te, ok := err.(interface{ Timeout() bool }); ok {
+		return te.Timeout()
+	}
+	return false
+}

internal/core/imageproxy/fetcher_test.go

···
+package imageproxy
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+func TestPDSFetcher_Fetch_Success(t *testing.T) {
+	// Setup test server that returns blob data
+	expectedData := []byte("test image data")
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Verify the request path and query parameters
+		if r.URL.Path != "/xrpc/com.atproto.sync.getBlob" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		if r.URL.Query().Get("did") != "did:plc:test123" {
+			t.Errorf("unexpected did: %s", r.URL.Query().Get("did"))
+		}
+		if r.URL.Query().Get("cid") != "bafyreicid123" {
+			t.Errorf("unexpected cid: %s", r.URL.Query().Get("cid"))
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write(expectedData)
+	}))
+	defer server.Close()
+
+	fetcher := NewPDSFetcher(5 * time.Second, 10)
+	ctx := context.Background()
+
+	data, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if err != nil {
+		t.Fatalf("expected no error, got: %v", err)
+	}
+	if string(data) != string(expectedData) {
+		t.Errorf("expected data %q, got %q", expectedData, data)
+	}
+}
+
+func TestPDSFetcher_Fetch_NotFound(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer server.Close()
+
+	fetcher := NewPDSFetcher(5 * time.Second, 10)
+	ctx := context.Background()
+
+	_, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if !errors.Is(err, ErrPDSNotFound) {
+		t.Errorf("expected ErrPDSNotFound, got: %v", err)
+	}
+}
+
+func TestPDSFetcher_Fetch_Timeout(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Sleep longer than the timeout
+		time.Sleep(200 * time.Millisecond)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	// Use a very short timeout
+	fetcher := NewPDSFetcher(50 * time.Millisecond, 10)
+	ctx := context.Background()
+
+	_, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if !errors.Is(err, ErrPDSTimeout) {
+		t.Errorf("expected ErrPDSTimeout, got: %v", err)
+	}
+}
+
+func TestPDSFetcher_Fetch_NetworkError(t *testing.T) {
+	fetcher := NewPDSFetcher(5 * time.Second, 10)
+	ctx := context.Background()
+
+	// Use an invalid URL that will cause a network error
+	_, err := fetcher.Fetch(ctx, "http://localhost:99999", "did:plc:test123", "bafyreicid123")
+	if !errors.Is(err, ErrPDSFetchFailed) {
+		t.Errorf("expected ErrPDSFetchFailed, got: %v", err)
+	}
+}
+
+func TestPDSFetcher_Fetch_ContextCancellation(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Sleep to allow context cancellation
+		time.Sleep(100 * time.Millisecond)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	fetcher := NewPDSFetcher(5 * time.Second, 10)
+	ctx, cancel := context.WithCancel(context.Background())
+
+	// Cancel the context immediately
+	cancel()
+
+	_, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if err == nil {
+		t.Error("expected error due to context cancellation")
+	}
+	// Context cancellation should return ErrPDSTimeout
+	if !errors.Is(err, ErrPDSTimeout) {
+		t.Errorf("expected ErrPDSTimeout for context cancellation, got: %v", err)
+	}
+}
+
+func TestPDSFetcher_Fetch_ServerError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer server.Close()
+
+	fetcher := NewPDSFetcher(5 * time.Second, 10)
+	ctx := context.Background()
+
+	_, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if !errors.Is(err, ErrPDSFetchFailed) {
+		t.Errorf("expected ErrPDSFetchFailed, got: %v", err)
+	}
+}
+
+func TestPDSFetcher_Fetch_URLConstruction(t *testing.T) {
+	var capturedURL string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedURL = r.URL.String()
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("data"))
+	}))
+	defer server.Close()
+
+	fetcher := NewPDSFetcher(5 * time.Second, 10)
+	ctx := context.Background()
+
+	_, err := fetcher.Fetch(ctx, server.URL, "did:plc:abc123", "bafyreicid456")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	expectedPath := "/xrpc/com.atproto.sync.getBlob?cid=bafyreicid456&did=did%3Aplc%3Aabc123"
+	if capturedURL != expectedPath {
+		t.Errorf("expected URL %q, got %q", expectedPath, capturedURL)
+	}
+}
+
+func TestPDSFetcher_Fetch_ImageTooLarge_ContentLength(t *testing.T) {
+	// Server returns Content-Length header indicating size exceeds limit
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Set Content-Length larger than the max (1MB)
+		w.Header().Set("Content-Length", "2097152") // 2MB
+		w.WriteHeader(http.StatusOK)
+		// Don't actually write 2MB of data
+	}))
+	defer server.Close()
+
+	// Use 1MB max size
+	fetcher := NewPDSFetcher(5*time.Second, 1)
+	ctx := context.Background()
+
+	_, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if !errors.Is(err, ErrImageTooLarge) {
+		t.Errorf("expected ErrImageTooLarge, got: %v", err)
+	}
+}
+
+func TestPDSFetcher_Fetch_ImageTooLarge_StreamingBody(t *testing.T) {
+	// Server doesn't send Content-Length but streams more data than allowed
+	largeData := make([]byte, 2*1024*1024) // 2MB of zeros
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write(largeData)
+	}))
+	defer server.Close()
+
+	// Use 1MB max size
+	fetcher := NewPDSFetcher(5*time.Second, 1)
+	ctx := context.Background()
+
+	_, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if !errors.Is(err, ErrImageTooLarge) {
+		t.Errorf("expected ErrImageTooLarge, got: %v", err)
+	}
+}
+
+func TestPDSFetcher_Fetch_SizeWithinLimit(t *testing.T) {
+	// Server returns data within the limit
+	testData := make([]byte, 512*1024) // 512KB
+	for i := range testData {
+		testData[i] = byte(i % 256)
+	}
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write(testData)
+	}))
+	defer server.Close()
+
+	// Use 1MB max size
+	fetcher := NewPDSFetcher(5*time.Second, 1)
+	ctx := context.Background()
+
+	data, err := fetcher.Fetch(ctx, server.URL, "did:plc:test123", "bafyreicid123")
+	if err != nil {
+		t.Fatalf("expected no error, got: %v", err)
+	}
+	if len(data) != len(testData) {
+		t.Errorf("expected %d bytes, got %d", len(testData), len(data))
+	}
+}
+
+func TestPDSFetcher_Fetch_DefaultMaxSize(t *testing.T) {
+	// Test that 0 for maxSizeMB uses the default
+	fetcher := NewPDSFetcher(5*time.Second, 0)
+	expectedDefault := int64(DefaultMaxSourceSizeMB) * 1024 * 1024
+
+	if fetcher.maxSizeBytes != expectedDefault {
+		t.Errorf("expected default maxSizeBytes %d, got %d", expectedDefault, fetcher.maxSizeBytes)
+	}
+}
+
+func TestPDSFetcher_Fetch_NegativeMaxSize(t *testing.T) {
+	// Test that negative maxSizeMB uses the default
+	fetcher := NewPDSFetcher(5*time.Second, -5)
+	expectedDefault := int64(DefaultMaxSourceSizeMB) * 1024 * 1024
+
+	if fetcher.maxSizeBytes != expectedDefault {
+		t.Errorf("expected default maxSizeBytes %d, got %d", expectedDefault, fetcher.maxSizeBytes)
+	}
+}

internal/core/imageproxy/presets.go

···
+package imageproxy
+
+// FitMode defines how an image should be fitted to the target dimensions.
+type FitMode string
+
+const (
+	// FitCover scales the image to cover the target dimensions, cropping if necessary.
+	FitCover FitMode = "cover"
+	// FitContain scales the image to fit within the target dimensions, preserving aspect ratio.
+	FitContain FitMode = "contain"
+)
+
+// String returns the string representation of the FitMode.
+func (f FitMode) String() string {
+	return string(f)
+}
+
+// Preset defines the configuration for an image transformation preset.
+type Preset struct {
+	Name    string
+	Width   int
+	Height  int
+	Fit     FitMode
+	Quality int
+}
+
+// Validate checks that the preset has valid configuration values.
+// Returns nil if valid, or an error describing what is wrong.
+func (p Preset) Validate() error {
+	if p.Name == "" {
+		return ErrInvalidPreset
+	}
+	if p.Width <= 0 {
+		return ErrInvalidPreset
+	}
+	// Height can be 0 for FitContain (proportional scaling)
+	if p.Fit == FitCover && p.Height <= 0 {
+		return ErrInvalidPreset
+	}
+	// Quality must be in JPEG range (1-100)
+	if p.Quality < 1 || p.Quality > 100 {
+		return ErrInvalidPreset
+	}
+	// Validate FitMode is a known value
+	if p.Fit != FitCover && p.Fit != FitContain {
+		return ErrInvalidPreset
+	}
+	return nil
+}
+
+// presets is the registry of all available image presets.
+var presets = map[string]Preset{
+	"avatar": {
+		Name:    "avatar",
+		Width:   1000,
+		Height:  1000,
+		Fit:     FitCover,
+		Quality: 85,
+	},
+	"avatar_small": {
+		Name:    "avatar_small",
+		Width:   360,
+		Height:  360,
+		Fit:     FitCover,
+		Quality: 80,
+	},
+	"banner": {
+		Name:    "banner",
+		Width:   640,
+		Height:  300,
+		Fit:     FitCover,
+		Quality: 85,
+	},
+	"content_preview": {
+		Name:    "content_preview",
+		Width:   800,
+		Height:  0,
+		Fit:     FitContain,
+		Quality: 80,
+	},
+	"content_full": {
+		Name:    "content_full",
+		Width:   1600,
+		Height:  0,
+		Fit:     FitContain,
+		Quality: 90,
+	},
+	"embed_thumbnail": {
+		Name:    "embed_thumbnail",
+		Width:   720,
+		Height:  360,
+		Fit:     FitCover,
+		Quality: 80,
+	},
+}
+
+// GetPreset returns the preset configuration for the given name.
+// Returns ErrInvalidPreset if the preset name is not found.
+func GetPreset(name string) (Preset, error) {
+	if name == "" {
+		return Preset{}, ErrInvalidPreset
+	}
+	preset, exists := presets[name]
+	if !exists {
+		return Preset{}, ErrInvalidPreset
+	}
+	return preset, nil
+}
+
+// ListPresets returns all available presets.
+func ListPresets() []Preset {
+	result := make([]Preset, 0, len(presets))
+	for _, p := range presets {
+		result = append(result, p)
+	}
+	return result
+}

internal/core/imageproxy/presets_test.go

···
+package imageproxy
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGetPreset(t *testing.T) {
+	tests := []struct {
+		name        string
+		presetName  string
+		wantWidth   int
+		wantHeight  int
+		wantFit     FitMode
+		wantQuality int
+		wantErr     error
+	}{
+		{
+			name:        "avatar preset returns correct dimensions",
+			presetName:  "avatar",
+			wantWidth:   1000,
+			wantHeight:  1000,
+			wantFit:     FitCover,
+			wantQuality: 85,
+			wantErr:     nil,
+		},
+		{
+			name:        "avatar_small preset returns correct dimensions",
+			presetName:  "avatar_small",
+			wantWidth:   360,
+			wantHeight:  360,
+			wantFit:     FitCover,
+			wantQuality: 80,
+			wantErr:     nil,
+		},
+		{
+			name:        "banner preset returns correct dimensions",
+			presetName:  "banner",
+			wantWidth:   640,
+			wantHeight:  300,
+			wantFit:     FitCover,
+			wantQuality: 85,
+			wantErr:     nil,
+		},
+		{
+			name:        "content_preview preset returns correct dimensions",
+			presetName:  "content_preview",
+			wantWidth:   800,
+			wantHeight:  0,
+			wantFit:     FitContain,
+			wantQuality: 80,
+			wantErr:     nil,
+		},
+		{
+			name:        "content_full preset returns correct dimensions",
+			presetName:  "content_full",
+			wantWidth:   1600,
+			wantHeight:  0,
+			wantFit:     FitContain,
+			wantQuality: 90,
+			wantErr:     nil,
+		},
+		{
+			name:        "embed_thumbnail preset returns correct dimensions",
+			presetName:  "embed_thumbnail",
+			wantWidth:   720,
+			wantHeight:  360,
+			wantFit:     FitCover,
+			wantQuality: 80,
+			wantErr:     nil,
+		},
+		{
+			name:       "invalid preset returns error",
+			presetName: "invalid",
+			wantErr:    ErrInvalidPreset,
+		},
+		{
+			name:       "empty preset name returns error",
+			presetName: "",
+			wantErr:    ErrInvalidPreset,
+		},
+		{
+			name:       "case sensitive - AVATAR should not match",
+			presetName: "AVATAR",
+			wantErr:    ErrInvalidPreset,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			preset, err := GetPreset(tt.presetName)
+
+			if tt.wantErr != nil {
+				require.Error(t, err)
+				assert.ErrorIs(t, err, tt.wantErr)
+				return
+			}
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.presetName, preset.Name)
+			assert.Equal(t, tt.wantWidth, preset.Width)
+			assert.Equal(t, tt.wantHeight, preset.Height)
+			assert.Equal(t, tt.wantFit, preset.Fit)
+			assert.Equal(t, tt.wantQuality, preset.Quality)
+		})
+	}
+}
+
+func TestAllPresetsHaveValidDimensions(t *testing.T) {
+	presetNames := []string{
+		"avatar",
+		"avatar_small",
+		"banner",
+		"content_preview",
+		"content_full",
+		"embed_thumbnail",
+	}
+
+	for _, name := range presetNames {
+		t.Run(name, func(t *testing.T) {
+			preset, err := GetPreset(name)
+			require.NoError(t, err)
+
+			// Width must always be positive
+			assert.Greater(t, preset.Width, 0, "preset %s must have positive width", name)
+
+			// Height can be 0 for contain fit (proportional scaling)
+			if preset.Fit == FitCover {
+				assert.Greater(t, preset.Height, 0, "cover fit preset %s must have positive height", name)
+			}
+
+			// Quality must be between 1 and 100
+			assert.GreaterOrEqual(t, preset.Quality, 1, "preset %s quality must be >= 1", name)
+			assert.LessOrEqual(t, preset.Quality, 100, "preset %s quality must be <= 100", name)
+
+			// Name must match
+			assert.Equal(t, name, preset.Name)
+		})
+	}
+}
+
+func TestFitModeString(t *testing.T) {
+	tests := []struct {
+		mode FitMode
+		want string
+	}{
+		{FitCover, "cover"},
+		{FitContain, "contain"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.want, func(t *testing.T) {
+			assert.Equal(t, tt.want, tt.mode.String())
+		})
+	}
+}
+
+func TestListPresets(t *testing.T) {
+	presets := ListPresets()
+
+	// Should have all 6 presets
+	assert.Len(t, presets, 6)
+
+	// Verify all expected presets are present
+	expectedNames := map[string]bool{
+		"avatar":          false,
+		"avatar_small":    false,
+		"banner":          false,
+		"content_preview": false,
+		"content_full":    false,
+		"embed_thumbnail": false,
+	}
+
+	for _, p := range presets {
+		if _, exists := expectedNames[p.Name]; exists {
+			expectedNames[p.Name] = true
+		}
+	}
+
+	for name, found := range expectedNames {
+		assert.True(t, found, "expected preset %s to be in list", name)
+	}
+}
+
+func TestPreset_Validate(t *testing.T) {
+	tests := []struct {
+		name    string
+		preset  Preset
+		wantErr bool
+	}{
+		{
+			name:    "valid avatar preset",
+			preset:  Preset{Name: "avatar", Width: 1000, Height: 1000, Fit: FitCover, Quality: 85},
+			wantErr: false,
+		},
+		{
+			name:    "valid contain preset with zero height",
+			preset:  Preset{Name: "content", Width: 800, Height: 0, Fit: FitContain, Quality: 80},
+			wantErr: false,
+		},
+		{
+			name:    "invalid empty name",
+			preset:  Preset{Name: "", Width: 160, Height: 160, Fit: FitCover, Quality: 85},
+			wantErr: true,
+		},
+		{
+			name:    "invalid zero width",
+			preset:  Preset{Name: "test", Width: 0, Height: 160, Fit: FitCover, Quality: 85},
+			wantErr: true,
+		},
+		{
+			name:    "invalid negative width",
+			preset:  Preset{Name: "test", Width: -100, Height: 160, Fit: FitCover, Quality: 85},
+			wantErr: true,
+		},
+		{
+			name:    "invalid cover fit with zero height",
+			preset:  Preset{Name: "test", Width: 160, Height: 0, Fit: FitCover, Quality: 85},
+			wantErr: true,
+		},
+		{
+			name:    "invalid quality zero",
+			preset:  Preset{Name: "test", Width: 160, Height: 160, Fit: FitCover, Quality: 0},
+			wantErr: true,
+		},
+		{
+			name:    "invalid quality over 100",
+			preset:  Preset{Name: "test", Width: 160, Height: 160, Fit: FitCover, Quality: 101},
+			wantErr: true,
+		},
+		{
+			name:    "valid quality at boundary 1",
+			preset:  Preset{Name: "test", Width: 160, Height: 160, Fit: FitCover, Quality: 1},
+			wantErr: false,
+		},
+		{
+			name:    "valid quality at boundary 100",
+			preset:  Preset{Name: "test", Width: 160, Height: 160, Fit: FitCover, Quality: 100},
+			wantErr: false,
+		},
+		{
+			name:    "invalid unknown fit mode",
+			preset:  Preset{Name: "test", Width: 160, Height: 160, Fit: FitMode("unknown"), Quality: 85},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.preset.Validate()
+			if tt.wantErr {
+				assert.Error(t, err)
+				assert.ErrorIs(t, err, ErrInvalidPreset)
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}
+
+func TestAllPresetsValidate(t *testing.T) {
+	// All built-in presets should pass validation
+	for _, preset := range ListPresets() {
+		t.Run(preset.Name, func(t *testing.T) {
+			err := preset.Validate()
+			assert.NoError(t, err, "built-in preset %s should be valid", preset.Name)
+		})
+	}
+}

internal/core/imageproxy/processor.go

···
+package imageproxy
+
+import (
+	"bytes"
+	"fmt"
+	"image"
+	"image/jpeg"
+	_ "image/png" // Register PNG decoder
+
+	"github.com/disintegration/imaging"
+	_ "golang.org/x/image/webp" // Register WebP decoder
+)
+
+// Processor defines the interface for image processing operations.
+type Processor interface {
+	// Process transforms image data according to the preset configuration.
+	// Returns the processed image as JPEG bytes, or an error if processing fails.
+	Process(data []byte, preset Preset) ([]byte, error)
+}
+
+// ImageProcessor implements the Processor interface using the imaging library.
+type ImageProcessor struct{}
+
+// NewProcessor creates a new ImageProcessor instance.
+func NewProcessor() Processor {
+	return &ImageProcessor{}
+}
+
+// Process transforms the input image data according to the preset configuration.
+// It handles both cover fit (crops to exact dimensions) and contain fit (preserves
+// aspect ratio within bounds). Output is always JPEG format.
+func (p *ImageProcessor) Process(data []byte, preset Preset) ([]byte, error) {
+	// Check for empty or nil data
+	if len(data) == 0 {
+		return nil, fmt.Errorf("%w: empty image data", ErrUnsupportedFormat)
+	}
+
+	// Decode the source image
+	img, format, err := image.Decode(bytes.NewReader(data))
+	if err != nil {
+		// Determine if this is a format issue or a corruption issue
+		if isUnsupportedFormatError(err) {
+			return nil, fmt.Errorf("%w: %v", ErrUnsupportedFormat, err)
+		}
+		return nil, fmt.Errorf("%w: failed to decode image: %v", ErrProcessingFailed, err)
+	}
+
+	// Validate that we decoded a supported format
+	if format != "jpeg" && format != "png" && format != "webp" {
+		return nil, fmt.Errorf("%w: format %s", ErrUnsupportedFormat, format)
+	}
+
+	// Process the image based on fit mode
+	var processed image.Image
+	switch preset.Fit {
+	case FitCover:
+		processed = processCover(img, preset.Width, preset.Height)
+	case FitContain:
+		processed = processContain(img, preset.Width, preset.Height)
+	default:
+		return nil, fmt.Errorf("%w: unknown fit mode", ErrProcessingFailed)
+	}
+
+	// Encode as JPEG
+	var buf bytes.Buffer
+	if err := jpeg.Encode(&buf, processed, &jpeg.Options{Quality: preset.Quality}); err != nil {
+		return nil, fmt.Errorf("%w: failed to encode JPEG: %v", ErrProcessingFailed, err)
+	}
+
+	return buf.Bytes(), nil
+}
+
+// processCover scales and crops the image to exactly fill the target dimensions.
+// The image is scaled to cover the entire target area, then cropped to exact size.
+func processCover(img image.Image, width, height int) image.Image {
+	// Use imaging.Fill which scales to cover and crops to exact dimensions
+	return imaging.Fill(img, width, height, imaging.Center, imaging.Lanczos)
+}
+
+// processContain scales the image to fit within the target width while preserving
+// aspect ratio. If the source image is smaller than the target, it is not upscaled.
+// Height of 0 means scale proportionally based on width only.
+func processContain(img image.Image, maxWidth, maxHeight int) image.Image {
+	bounds := img.Bounds()
+	srcWidth := bounds.Dx()
+	srcHeight := bounds.Dy()
+
+	// Don't upscale images smaller than target
+	if srcWidth <= maxWidth {
+		return img
+	}
+
+	// Calculate new dimensions preserving aspect ratio
+	newWidth := maxWidth
+	newHeight := int(float64(srcHeight) * (float64(maxWidth) / float64(srcWidth)))
+
+	// If maxHeight is specified and calculated height exceeds it,
+	// scale based on height instead
+	if maxHeight > 0 && newHeight > maxHeight {
+		newHeight = maxHeight
+		newWidth = int(float64(srcWidth) * (float64(maxHeight) / float64(srcHeight)))
+	}
+
+	return imaging.Resize(img, newWidth, newHeight, imaging.Lanczos)
+}
+
+// isUnsupportedFormatError checks if the error indicates an unsupported image format.
+func isUnsupportedFormatError(err error) bool {
+	if err == nil {
+		return false
+	}
+	errStr := err.Error()
+	return errStr == "image: unknown format" ||
+		errStr == "invalid JPEG format: missing SOI marker" ||
+		errStr == "invalid JPEG format: short segment" ||
+		bytes.Contains([]byte(errStr), []byte("unknown format"))
+}

internal/core/imageproxy/processor_test.go

···
+package imageproxy
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"image/png"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// createTestJPEG creates a test JPEG image with the specified dimensions.
+func createTestJPEG(t *testing.T, width, height int) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, width, height))
+	// Fill with a solid color
+	for y := 0; y < height; y++ {
+		for x := 0; x < width; x++ {
+			img.Set(x, y, color.RGBA{R: 255, G: 128, B: 64, A: 255})
+		}
+	}
+	var buf bytes.Buffer
+	err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: 90})
+	require.NoError(t, err)
+	return buf.Bytes()
+}
+
+// createTestPNG creates a test PNG image with the specified dimensions.
+func createTestPNG(t *testing.T, width, height int) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, width, height))
+	// Fill with a solid color
+	for y := 0; y < height; y++ {
+		for x := 0; x < width; x++ {
+			img.Set(x, y, color.RGBA{R: 64, G: 128, B: 255, A: 255})
+		}
+	}
+	var buf bytes.Buffer
+	err := png.Encode(&buf, img)
+	require.NoError(t, err)
+	return buf.Bytes()
+}
+
+func TestProcessor_Process_CoverFit(t *testing.T) {
+	proc := NewProcessor()
+
+	tests := []struct {
+		name         string
+		srcWidth     int
+		srcHeight    int
+		preset       Preset
+		wantWidth    int
+		wantHeight   int
+		description  string
+	}{
+		{
+			name:        "landscape image to square avatar",
+			srcWidth:    800,
+			srcHeight:   600,
+			preset:      Preset{Name: "avatar", Width: 1000, Height: 1000, Fit: FitCover, Quality: 85},
+			wantWidth:   1000,
+			wantHeight:  1000,
+			description: "landscape cropped to square",
+		},
+		{
+			name:        "portrait image to square avatar",
+			srcWidth:    600,
+			srcHeight:   800,
+			preset:      Preset{Name: "avatar", Width: 1000, Height: 1000, Fit: FitCover, Quality: 85},
+			wantWidth:   1000,
+			wantHeight:  1000,
+			description: "portrait cropped to square",
+		},
+		{
+			name:        "square image to smaller square",
+			srcWidth:    500,
+			srcHeight:   500,
+			preset:      Preset{Name: "avatar_small", Width: 360, Height: 360, Fit: FitCover, Quality: 80},
+			wantWidth:   360,
+			wantHeight:  360,
+			description: "square scaled down",
+		},
+		{
+			name:        "landscape to banner dimensions",
+			srcWidth:    1920,
+			srcHeight:   1080,
+			preset:      Preset{Name: "banner", Width: 640, Height: 300, Fit: FitCover, Quality: 85},
+			wantWidth:   640,
+			wantHeight:  300,
+			description: "banner crop",
+		},
+		{
+			name:        "embed thumbnail dimensions",
+			srcWidth:    1600,
+			srcHeight:   900,
+			preset:      Preset{Name: "embed_thumbnail", Width: 720, Height: 360, Fit: FitCover, Quality: 80},
+			wantWidth:   720,
+			wantHeight:  360,
+			description: "embed thumbnail crop",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			srcData := createTestJPEG(t, tt.srcWidth, tt.srcHeight)
+
+			result, err := proc.Process(srcData, tt.preset)
+			require.NoError(t, err)
+			require.NotNil(t, result)
+
+			// Decode the result to verify dimensions
+			img, _, err := image.Decode(bytes.NewReader(result))
+			require.NoError(t, err)
+
+			bounds := img.Bounds()
+			assert.Equal(t, tt.wantWidth, bounds.Dx(), "width mismatch for %s", tt.description)
+			assert.Equal(t, tt.wantHeight, bounds.Dy(), "height mismatch for %s", tt.description)
+		})
+	}
+}
+
+func TestProcessor_Process_ContainFit(t *testing.T) {
+	proc := NewProcessor()
+
+	tests := []struct {
+		name          string
+		srcWidth      int
+		srcHeight     int
+		preset        Preset
+		wantMaxWidth  int
+		wantMaxHeight int
+		description   string
+	}{
+		{
+			name:          "landscape image scaled to content_preview width",
+			srcWidth:      1600,
+			srcHeight:     900,
+			preset:        Preset{Name: "content_preview", Width: 800, Height: 0, Fit: FitContain, Quality: 80},
+			wantMaxWidth:  800,
+			wantMaxHeight: 450, // 800 * (900/1600) = 450 (aspect ratio preserved)
+			description:   "landscape scaled proportionally",
+		},
+		{
+			name:          "portrait image scaled to content_preview width",
+			srcWidth:      900,
+			srcHeight:     1600,
+			preset:        Preset{Name: "content_preview", Width: 800, Height: 0, Fit: FitContain, Quality: 80},
+			wantMaxWidth:  800,
+			wantMaxHeight: 1422, // 800 * (1600/900) ~= 1422
+			description:   "portrait scaled proportionally",
+		},
+		{
+			name:          "wide panorama to content_full",
+			srcWidth:      3200,
+			srcHeight:     800,
+			preset:        Preset{Name: "content_full", Width: 1600, Height: 0, Fit: FitContain, Quality: 90},
+			wantMaxWidth:  1600,
+			wantMaxHeight: 400, // 1600 * (800/3200) = 400
+			description:   "panorama scaled proportionally",
+		},
+		{
+			name:          "image smaller than target width stays same size",
+			srcWidth:      400,
+			srcHeight:     300,
+			preset:        Preset{Name: "content_preview", Width: 800, Height: 0, Fit: FitContain, Quality: 80},
+			wantMaxWidth:  400, // Don't upscale
+			wantMaxHeight: 300,
+			description:   "small image not upscaled",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			srcData := createTestJPEG(t, tt.srcWidth, tt.srcHeight)
+
+			result, err := proc.Process(srcData, tt.preset)
+			require.NoError(t, err)
+			require.NotNil(t, result)
+
+			// Decode the result to verify dimensions
+			img, _, err := image.Decode(bytes.NewReader(result))
+			require.NoError(t, err)
+
+			bounds := img.Bounds()
+			// For contain fit, verify width doesn't exceed max and aspect ratio is preserved
+			assert.LessOrEqual(t, bounds.Dx(), tt.wantMaxWidth, "width should not exceed max for %s", tt.description)
+			assert.Equal(t, tt.wantMaxWidth, bounds.Dx(), "width mismatch for %s", tt.description)
+			assert.Equal(t, tt.wantMaxHeight, bounds.Dy(), "height mismatch for %s", tt.description)
+		})
+	}
+}
+
+func TestProcessor_Process_InvalidImageData(t *testing.T) {
+	proc := NewProcessor()
+
+	tests := []struct {
+		name    string
+		data    []byte
+		wantErr error
+	}{
+		{
+			name:    "empty data",
+			data:    []byte{},
+			wantErr: ErrUnsupportedFormat,
+		},
+		{
+			name:    "nil data",
+			data:    nil,
+			wantErr: ErrUnsupportedFormat,
+		},
+		{
+			name:    "random garbage data",
+			data:    []byte("not an image at all"),
+			wantErr: ErrUnsupportedFormat,
+		},
+		{
+			name:    "truncated JPEG header",
+			data:    []byte{0xFF, 0xD8, 0xFF, 0xE0}, // Partial JPEG magic
+			wantErr: ErrProcessingFailed,
+		},
+	}
+
+	preset, _ := GetPreset("avatar")
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := proc.Process(tt.data, preset)
+			require.Error(t, err)
+			assert.ErrorIs(t, err, tt.wantErr)
+			assert.Nil(t, result)
+		})
+	}
+}
+
+func TestProcessor_Process_SupportsJPEG(t *testing.T) {
+	proc := NewProcessor()
+	srcData := createTestJPEG(t, 500, 500)
+	preset, _ := GetPreset("avatar")
+
+	result, err := proc.Process(srcData, preset)
+	require.NoError(t, err)
+	require.NotNil(t, result)
+
+	// Verify output is valid JPEG
+	img, format, err := image.Decode(bytes.NewReader(result))
+	require.NoError(t, err)
+	assert.Equal(t, "jpeg", format)
+	assert.Equal(t, 1000, img.Bounds().Dx())
+	assert.Equal(t, 1000, img.Bounds().Dy())
+}
+
+func TestProcessor_Process_SupportsPNG(t *testing.T) {
+	proc := NewProcessor()
+	srcData := createTestPNG(t, 500, 500)
+	preset, _ := GetPreset("avatar")
+
+	result, err := proc.Process(srcData, preset)
+	require.NoError(t, err)
+	require.NotNil(t, result)
+
+	// Verify output is valid JPEG (always output JPEG)
+	img, format, err := image.Decode(bytes.NewReader(result))
+	require.NoError(t, err)
+	assert.Equal(t, "jpeg", format)
+	assert.Equal(t, 1000, img.Bounds().Dx())
+	assert.Equal(t, 1000, img.Bounds().Dy())
+}
+
+func TestProcessor_Process_AlwaysOutputsJPEG(t *testing.T) {
+	proc := NewProcessor()
+	preset, _ := GetPreset("avatar")
+
+	// Test with PNG input
+	pngData := createTestPNG(t, 300, 300)
+	result, err := proc.Process(pngData, preset)
+	require.NoError(t, err)
+
+	// Verify output is JPEG even when input is PNG
+	_, format, err := image.Decode(bytes.NewReader(result))
+	require.NoError(t, err)
+	assert.Equal(t, "jpeg", format, "output should always be JPEG")
+}
+
+func TestProcessor_Interface(t *testing.T) {
+	// Compile-time check that ImageProcessor implements Processor
+	var _ Processor = (*ImageProcessor)(nil)
+}
+
+func TestNewProcessor(t *testing.T) {
+	proc := NewProcessor()
+	require.NotNil(t, proc)
+
+	// Verify it's an *ImageProcessor
+	_, ok := proc.(*ImageProcessor)
+	assert.True(t, ok, "NewProcessor should return *ImageProcessor")
+}

internal/core/imageproxy/service.go

···
+// Package imageproxy provides image proxy functionality for AT Protocol applications.
+// It handles fetching, caching, and transforming images from Personal Data Servers (PDS).
+//
+// The package implements a multi-tier architecture:
+//   - Service: Orchestrates caching, fetching, and processing
+//   - Cache: Disk-based LRU cache with TTL-based expiration
+//   - Fetcher: Retrieves blobs from AT Protocol PDSes
+//   - Processor: Transforms images according to preset configurations
+//
+// Presets define image transformation parameters (dimensions, fit mode, quality)
+// for common use cases like avatars, banners, and feed thumbnails.
+package imageproxy
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync/atomic"
+)
+
+// cacheWriteErrors tracks the number of async cache write failures.
+// This provides observability for cache write issues until proper metrics are implemented.
+var cacheWriteErrors atomic.Int64
+
+// CacheWriteErrorCount returns the total number of async cache write errors.
+// This is useful for monitoring and alerting on cache health.
+func CacheWriteErrorCount() int64 {
+	return cacheWriteErrors.Load()
+}
+
+// Service defines the interface for the image proxy service.
+type Service interface {
+	// GetImage retrieves an image for the given preset, DID, and CID.
+	// It checks the cache first, then fetches from the PDS if not cached,
+	// processes the image according to the preset, and stores in cache.
+	GetImage(ctx context.Context, preset, did, cid string, pdsURL string) ([]byte, error)
+}
+
+// ImageProxyService implements the Service interface and orchestrates
+// caching, fetching, and processing of images.
+type ImageProxyService struct {
+	cache     Cache
+	processor Processor
+	fetcher   Fetcher
+	config    Config
+}
+
+// NewService creates a new ImageProxyService with the provided dependencies.
+// Returns an error if any required dependency is nil.
+func NewService(cache Cache, processor Processor, fetcher Fetcher, config Config) (*ImageProxyService, error) {
+	if cache == nil {
+		return nil, fmt.Errorf("%w: cache", ErrNilDependency)
+	}
+	if processor == nil {
+		return nil, fmt.Errorf("%w: processor", ErrNilDependency)
+	}
+	if fetcher == nil {
+		return nil, fmt.Errorf("%w: fetcher", ErrNilDependency)
+	}
+
+	return &ImageProxyService{
+		cache:     cache,
+		processor: processor,
+		fetcher:   fetcher,
+		config:    config,
+	}, nil
+}
+
+// GetImage retrieves an image for the given preset, DID, and CID.
+// The service flow is:
+//  1. Validate preset exists
+//  2. Check cache for (preset, did, cid) - return if hit
+//  3. Fetch blob from PDS using pdsURL
+//  4. Process image with preset
+//  5. Store in cache (async, don't block response)
+//  6. Return processed image
+func (s *ImageProxyService) GetImage(ctx context.Context, presetName, did, cid string, pdsURL string) ([]byte, error) {
+	// Step 1: Validate preset exists
+	preset, err := GetPreset(presetName)
+	if err != nil {
+		return nil, err
+	}
+
+	// Step 2: Check cache for (preset, did, cid)
+	cachedData, found, err := s.cache.Get(presetName, did, cid)
+	if err != nil {
+		// Log cache read error but continue - cache miss is acceptable
+		slog.Warn("[IMAGE-PROXY] cache read error, falling back to fetch",
+			"preset", presetName,
+			"did", did,
+			"cid", cid,
+			"error", err,
+		)
+	}
+	if found {
+		slog.Debug("[IMAGE-PROXY] cache hit",
+			"preset", presetName,
+			"did", did,
+			"cid", cid,
+		)
+		return cachedData, nil
+	}
+
+	// Step 3: Fetch blob from PDS
+	rawData, err := s.fetcher.Fetch(ctx, pdsURL, did, cid)
+	if err != nil {
+		return nil, err
+	}
+
+	// Step 4: Process image with preset
+	processedData, err := s.processor.Process(rawData, preset)
+	if err != nil {
+		return nil, err
+	}
+
+	// Step 5: Store in cache (async, don't block response)
+	go func() {
+		// Use a background context since the original request context may be cancelled
+		if cacheErr := s.cache.Set(presetName, did, cid, processedData); cacheErr != nil {
+			// Increment error counter for monitoring
+			cacheWriteErrors.Add(1)
+			slog.Error("[IMAGE-PROXY] async cache write failed",
+				"preset", presetName,
+				"did", did,
+				"cid", cid,
+				"error", cacheErr,
+				"total_cache_write_errors", cacheWriteErrors.Load(),
+			)
+		} else {
+			slog.Debug("[IMAGE-PROXY] cached processed image",
+				"preset", presetName,
+				"did", did,
+				"cid", cid,
+				"size_bytes", len(processedData),
+			)
+		}
+	}()
+
+	// Step 6: Return processed image
+	return processedData, nil
+}

internal/core/imageproxy/service_test.go

···
+package imageproxy
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+)
+
+// MockCache implements Cache for testing
+type MockCache struct {
+	mu       sync.Mutex
+	data     map[string][]byte
+	getCalls int
+	setCalls int
+	setData  map[string][]byte // Track what was set
+}
+
+func NewMockCache() *MockCache {
+	return &MockCache{
+		data:    make(map[string][]byte),
+		setData: make(map[string][]byte),
+	}
+}
+
+func (m *MockCache) cacheKey(preset, did, cid string) string {
+	return preset + ":" + did + ":" + cid
+}
+
+func (m *MockCache) Get(preset, did, cid string) ([]byte, bool, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.getCalls++
+	key := m.cacheKey(preset, did, cid)
+	data, found := m.data[key]
+	return data, found, nil
+}
+
+func (m *MockCache) Set(preset, did, cid string, data []byte) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.setCalls++
+	key := m.cacheKey(preset, did, cid)
+	m.data[key] = data
+	m.setData[key] = data
+	return nil
+}
+
+func (m *MockCache) Delete(preset, did, cid string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	key := m.cacheKey(preset, did, cid)
+	delete(m.data, key)
+	return nil
+}
+
+func (m *MockCache) Cleanup() (int, error) {
+	// Mock implementation - no-op for tests
+	return 0, nil
+}
+
+func (m *MockCache) SetCacheData(preset, did, cid string, data []byte) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	key := m.cacheKey(preset, did, cid)
+	m.data[key] = data
+}
+
+func (m *MockCache) GetCalls() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.getCalls
+}
+
+func (m *MockCache) SetCalls() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.setCalls
+}
+
+func (m *MockCache) GetSetData(preset, did, cid string) ([]byte, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	key := m.cacheKey(preset, did, cid)
+	data, found := m.setData[key]
+	return data, found
+}
+
+// MockProcessor implements Processor for testing
+type MockProcessor struct {
+	returnData []byte
+	returnErr  error
+	calls      int
+	mu         sync.Mutex
+}
+
+func NewMockProcessor(returnData []byte, returnErr error) *MockProcessor {
+	return &MockProcessor{
+		returnData: returnData,
+		returnErr:  returnErr,
+	}
+}
+
+func (m *MockProcessor) Process(data []byte, preset Preset) ([]byte, error) {
+	m.mu.Lock()
+	m.calls++
+	m.mu.Unlock()
+	if m.returnErr != nil {
+		return nil, m.returnErr
+	}
+	return m.returnData, nil
+}
+
+func (m *MockProcessor) Calls() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.calls
+}
+
+// MockFetcher implements Fetcher for testing
+type MockFetcher struct {
+	returnData []byte
+	returnErr  error
+	calls      int
+	mu         sync.Mutex
+}
+
+func NewMockFetcher(returnData []byte, returnErr error) *MockFetcher {
+	return &MockFetcher{
+		returnData: returnData,
+		returnErr:  returnErr,
+	}
+}
+
+func (m *MockFetcher) Fetch(ctx context.Context, pdsURL, did, cid string) ([]byte, error) {
+	m.mu.Lock()
+	m.calls++
+	m.mu.Unlock()
+	if m.returnErr != nil {
+		return nil, m.returnErr
+	}
+	return m.returnData, nil
+}
+
+func (m *MockFetcher) Calls() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.calls
+}
+
+// mustNewService is a test helper that creates a service or fails the test
+func mustNewService(t *testing.T, cache Cache, processor Processor, fetcher Fetcher, config Config) *ImageProxyService {
+	t.Helper()
+	service, err := NewService(cache, processor, fetcher, config)
+	if err != nil {
+		t.Fatalf("NewService failed: %v", err)
+	}
+	return service
+}
+
+func TestImageProxyService_GetImage_CacheHit(t *testing.T) {
+	cache := NewMockCache()
+	processor := NewMockProcessor(nil, nil)
+	fetcher := NewMockFetcher(nil, nil)
+	config := DefaultConfig()
+
+	// Pre-populate the cache
+	cachedData := []byte("cached image data")
+	cache.SetCacheData("avatar", "did:plc:test123", "bafyreicid123", cachedData)
+
+	service := mustNewService(t, cache, processor, fetcher, config)
+	ctx := context.Background()
+
+	data, err := service.GetImage(ctx, "avatar", "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+	if err != nil {
+		t.Fatalf("expected no error, got: %v", err)
+	}
+	if string(data) != string(cachedData) {
+		t.Errorf("expected cached data %q, got %q", cachedData, data)
+	}
+
+	// Verify fetcher was not called
+	if fetcher.Calls() != 0 {
+		t.Errorf("expected fetcher to not be called on cache hit, got %d calls", fetcher.Calls())
+	}
+
+	// Verify processor was not called
+	if processor.Calls() != 0 {
+		t.Errorf("expected processor to not be called on cache hit, got %d calls", processor.Calls())
+	}
+}
+
+func TestImageProxyService_GetImage_CacheMiss(t *testing.T) {
+	cache := NewMockCache()
+	rawImageData := []byte("raw image from PDS")
+	processedData := []byte("processed image")
+	processor := NewMockProcessor(processedData, nil)
+	fetcher := NewMockFetcher(rawImageData, nil)
+	config := DefaultConfig()
+
+	service := mustNewService(t, cache, processor, fetcher, config)
+	ctx := context.Background()
+
+	data, err := service.GetImage(ctx, "avatar", "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+	if err != nil {
+		t.Fatalf("expected no error, got: %v", err)
+	}
+	if string(data) != string(processedData) {
+		t.Errorf("expected processed data %q, got %q", processedData, data)
+	}
+
+	// Verify fetcher was called
+	if fetcher.Calls() != 1 {
+		t.Errorf("expected fetcher to be called once, got %d calls", fetcher.Calls())
+	}
+
+	// Verify processor was called
+	if processor.Calls() != 1 {
+		t.Errorf("expected processor to be called once, got %d calls", processor.Calls())
+	}
+
+	// Wait a bit for async cache write
+	time.Sleep(50 * time.Millisecond)
+
+	// Verify cache was written
+	if cache.SetCalls() < 1 {
+		t.Errorf("expected cache to be written, got %d set calls", cache.SetCalls())
+	}
+
+	// Verify the correct data was cached
+	setData, found := cache.GetSetData("avatar", "did:plc:test123", "bafyreicid123")
+	if !found {
+		t.Error("expected data to be set in cache")
+	}
+	if string(setData) != string(processedData) {
+		t.Errorf("expected cached data %q, got %q", processedData, setData)
+	}
+}
+
+func TestImageProxyService_GetImage_InvalidPreset(t *testing.T) {
+	cache := NewMockCache()
+	processor := NewMockProcessor(nil, nil)
+	fetcher := NewMockFetcher(nil, nil)
+	config := DefaultConfig()
+
+	service := mustNewService(t, cache, processor, fetcher, config)
+	ctx := context.Background()
+
+	_, err := service.GetImage(ctx, "invalid_preset", "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+	if !errors.Is(err, ErrInvalidPreset) {
+		t.Errorf("expected ErrInvalidPreset, got: %v", err)
+	}
+}
+
+func TestImageProxyService_GetImage_PDSFetchError(t *testing.T) {
+	cache := NewMockCache()
+	processor := NewMockProcessor(nil, nil)
+	fetcher := NewMockFetcher(nil, ErrPDSNotFound)
+	config := DefaultConfig()
+
+	service := mustNewService(t, cache, processor, fetcher, config)
+	ctx := context.Background()
+
+	_, err := service.GetImage(ctx, "avatar", "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+	if !errors.Is(err, ErrPDSNotFound) {
+		t.Errorf("expected ErrPDSNotFound, got: %v", err)
+	}
+}
+
+func TestImageProxyService_GetImage_ProcessingError(t *testing.T) {
+	cache := NewMockCache()
+	processor := NewMockProcessor(nil, ErrProcessingFailed)
+	fetcher := NewMockFetcher([]byte("raw data"), nil)
+	config := DefaultConfig()
+
+	service := mustNewService(t, cache, processor, fetcher, config)
+	ctx := context.Background()
+
+	_, err := service.GetImage(ctx, "avatar", "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+	if !errors.Is(err, ErrProcessingFailed) {
+		t.Errorf("expected ErrProcessingFailed, got: %v", err)
+	}
+}
+
+func TestImageProxyService_GetImage_CacheWriteIsAsync(t *testing.T) {
+	cache := NewMockCache()
+	rawImageData := []byte("raw image from PDS")
+	processedData := []byte("processed image")
+	processor := NewMockProcessor(processedData, nil)
+	fetcher := NewMockFetcher(rawImageData, nil)
+	config := DefaultConfig()
+
+	service := mustNewService(t, cache, processor, fetcher, config)
+	ctx := context.Background()
+
+	// Call GetImage
+	startTime := time.Now()
+	data, err := service.GetImage(ctx, "avatar", "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+	elapsed := time.Since(startTime)
+
+	if err != nil {
+		t.Fatalf("expected no error, got: %v", err)
+	}
+	if string(data) != string(processedData) {
+		t.Errorf("expected processed data %q, got %q", processedData, data)
+	}
+
+	// The response should come back quickly, not blocked by cache write
+	// (This is a soft assertion - just ensures we're not blocking)
+	if elapsed > 100*time.Millisecond {
+		t.Logf("warning: GetImage took %v, expected faster response", elapsed)
+	}
+
+	// Wait for async cache write to complete
+	time.Sleep(100 * time.Millisecond)
+
+	// Now verify cache was written
+	if cache.SetCalls() < 1 {
+		t.Errorf("expected cache to be written asynchronously, got %d set calls", cache.SetCalls())
+	}
+}
+
+func TestImageProxyService_GetImage_EmptyPreset(t *testing.T) {
+	cache := NewMockCache()
+	processor := NewMockProcessor(nil, nil)
+	fetcher := NewMockFetcher(nil, nil)
+	config := DefaultConfig()
+
+	service := mustNewService(t, cache, processor, fetcher, config)
+	ctx := context.Background()
+
+	_, err := service.GetImage(ctx, "", "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+	if !errors.Is(err, ErrInvalidPreset) {
+		t.Errorf("expected ErrInvalidPreset for empty preset, got: %v", err)
+	}
+}
+
+func TestImageProxyService_GetImage_AllPresets(t *testing.T) {
+	// Test that all predefined presets work
+	presets := []string{"avatar", "avatar_small", "banner", "content_preview", "content_full", "embed_thumbnail"}
+
+	for _, presetName := range presets {
+		t.Run(presetName, func(t *testing.T) {
+			cache := NewMockCache()
+			processedData := []byte("processed image")
+			processor := NewMockProcessor(processedData, nil)
+			fetcher := NewMockFetcher([]byte("raw data"), nil)
+			config := DefaultConfig()
+
+			service := mustNewService(t, cache, processor, fetcher, config)
+			ctx := context.Background()
+
+			data, err := service.GetImage(ctx, presetName, "did:plc:test123", "bafyreicid123", "https://pds.example.com")
+			if err != nil {
+				t.Errorf("expected no error for preset %s, got: %v", presetName, err)
+			}
+			if string(data) != string(processedData) {
+				t.Errorf("expected processed data for preset %s", presetName)
+			}
+		})
+	}
+}
+
+func TestNewService_NilDependencies(t *testing.T) {
+	config := DefaultConfig()
+	cache := NewMockCache()
+	processor := NewMockProcessor(nil, nil)
+	fetcher := NewMockFetcher(nil, nil)
+
+	t.Run("nil cache", func(t *testing.T) {
+		_, err := NewService(nil, processor, fetcher, config)
+		if !errors.Is(err, ErrNilDependency) {
+			t.Errorf("expected ErrNilDependency, got: %v", err)
+		}
+	})
+
+	t.Run("nil processor", func(t *testing.T) {
+		_, err := NewService(cache, nil, fetcher, config)
+		if !errors.Is(err, ErrNilDependency) {
+			t.Errorf("expected ErrNilDependency, got: %v", err)
+		}
+	})
+
+	t.Run("nil fetcher", func(t *testing.T) {
+		_, err := NewService(cache, processor, nil, config)
+		if !errors.Is(err, ErrNilDependency) {
+			t.Errorf("expected ErrNilDependency, got: %v", err)
+		}
+	})
+
+	t.Run("all valid", func(t *testing.T) {
+		service, err := NewService(cache, processor, fetcher, config)
+		if err != nil {
+			t.Errorf("expected no error with valid dependencies, got: %v", err)
+		}
+		if service == nil {
+			t.Error("expected non-nil service")
+		}
+	})
+}

internal/core/imageproxy/validation.go

···
+package imageproxy
+
+import (
+	"strings"
+
+	"github.com/bluesky-social/indigo/atproto/syntax"
+)
+
+// ValidateDID validates that a DID string matches expected atproto DID formats.
+// It uses the Indigo library's syntax.ParseDID for consistent validation across the codebase.
+// Returns ErrInvalidDID if the DID is invalid.
+func ValidateDID(did string) error {
+	// Check for path traversal attempts before parsing
+	if strings.Contains(did, "..") || strings.Contains(did, "/") || strings.Contains(did, "\\") || strings.Contains(did, "\x00") {
+		return ErrInvalidDID
+	}
+
+	// Use Indigo's DID parser for consistent validation with the rest of the codebase
+	_, err := syntax.ParseDID(did)
+	if err != nil {
+		return ErrInvalidDID
+	}
+
+	return nil
+}
+
+// ValidateCID validates that a CID string is a valid content identifier.
+// It uses the Indigo library's syntax.ParseCID for consistent validation across the codebase.
+// Returns ErrInvalidCID if the CID is invalid.
+func ValidateCID(cid string) error {
+	// Check for path traversal attempts before parsing
+	if strings.Contains(cid, "..") || strings.Contains(cid, "/") || strings.Contains(cid, "\\") || strings.Contains(cid, "\x00") {
+		return ErrInvalidCID
+	}
+
+	// Use Indigo's CID parser for consistent validation with the rest of the codebase
+	_, err := syntax.ParseCID(cid)
+	if err != nil {
+		return ErrInvalidCID
+	}
+
+	return nil
+}
+
+// SanitizePathComponent ensures a string is safe to use as a filesystem path component.
+// It removes or replaces characters that could be used for path traversal attacks.
+// This is used as an additional safety layer beyond DID/CID validation.
+func SanitizePathComponent(s string) string {
+	// Replace any path separators
+	s = strings.ReplaceAll(s, "/", "_")
+	s = strings.ReplaceAll(s, "\\", "_")
+
+	// Remove any path traversal sequences
+	s = strings.ReplaceAll(s, "..", "")
+
+	// Replace colons for filesystem compatibility (Windows and general safety)
+	s = strings.ReplaceAll(s, ":", "_")
+
+	// Remove null bytes
+	s = strings.ReplaceAll(s, "\x00", "")
+
+	return s
+}
+
+// ValidatePreset validates that a preset name is safe and exists.
+// This combines format validation with registry lookup.
+func ValidatePreset(preset string) error {
+	// Check for empty preset
+	if preset == "" {
+		return ErrInvalidPreset
+	}
+
+	// Check for path separators (dangerous characters)
+	// Note: We use ContainsAny for individual chars and Contains for substrings
+	if strings.ContainsAny(preset, "/\\") {
+		return ErrInvalidPreset
+	}
+
+	// Check for path traversal sequences (must check ".." as a substring, not individual dots)
+	if strings.Contains(preset, "..") {
+		return ErrInvalidPreset
+	}
+
+	// Verify preset exists in registry
+	_, err := GetPreset(preset)
+	return err
+}

internal/core/imageproxy/validation_test.go

···
+package imageproxy
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestValidateDID(t *testing.T) {
+	tests := []struct {
+		name    string
+		did     string
+		wantErr error
+	}{
+		// Valid DIDs - uses Indigo's syntax.ParseDID for consistency with codebase
+		{
+			name:    "valid did:plc",
+			did:     "did:plc:z72i7hdynmk6r22z27h6tvur",
+			wantErr: nil,
+		},
+		{
+			name:    "valid did:web simple",
+			did:     "did:web:example.com",
+			wantErr: nil,
+		},
+		{
+			name:    "valid did:web with subdomain",
+			did:     "did:web:bsky.social",
+			wantErr: nil,
+		},
+		{
+			name:    "valid did:web with path",
+			did:     "did:web:example.com:user:alice",
+			wantErr: nil,
+		},
+		// did:key is valid per Indigo library (used in other atproto contexts)
+		{
+			name:    "valid did:key",
+			did:     "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+			wantErr: nil,
+		},
+		// Invalid DIDs
+		{
+			name:    "empty string",
+			did:     "",
+			wantErr: ErrInvalidDID,
+		},
+		{
+			name:    "missing did: prefix",
+			did:     "plc:z72i7hdynmk6r22z27h6tvur",
+			wantErr: ErrInvalidDID,
+		},
+		{
+			name:    "path traversal attempt in did",
+			did:     "did:plc:../../../etc/passwd",
+			wantErr: ErrInvalidDID,
+		},
+		{
+			name:    "null byte injection",
+			did:     "did:plc:abc\x00def",
+			wantErr: ErrInvalidDID,
+		},
+		{
+			name:    "forward slash injection",
+			did:     "did:plc:abc/def",
+			wantErr: ErrInvalidDID,
+		},
+		{
+			name:    "backslash injection",
+			did:     "did:plc:abc\\def",
+			wantErr: ErrInvalidDID,
+		},
+		{
+			name:    "just did prefix",
+			did:     "did:",
+			wantErr: ErrInvalidDID,
+		},
+		{
+			name:    "random gibberish",
+			did:     "not-a-did-at-all",
+			wantErr: ErrInvalidDID,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateDID(tt.did)
+			if !errors.Is(err, tt.wantErr) {
+				t.Errorf("ValidateDID(%q) = %v, want %v", tt.did, err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestValidateCID(t *testing.T) {
+	tests := []struct {
+		name    string
+		cid     string
+		wantErr error
+	}{
+		// Valid CIDs
+		{
+			name:    "valid CIDv1 base32 bafy",
+			cid:     "bafyreihgdyzzpkkzq2izfnhcmm77ycuacvkuziwbnqxfxtqsz7tmxwhnshi",
+			wantErr: nil,
+		},
+		{
+			name:    "valid CIDv1 base32 bafk",
+			cid:     "bafkreihgdyzzpkkzq2izfnhcmm77ycuacvkuziwbnqxfxtqsz7tmxwhnshi",
+			wantErr: nil,
+		},
+		{
+			name:    "valid CIDv0",
+			cid:     "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
+			wantErr: nil,
+		},
+		// Invalid CIDs
+		{
+			name:    "empty string",
+			cid:     "",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "too short",
+			cid:     "bafyabc",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "path traversal attempt",
+			cid:     "../../../etc/passwd",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "contains slash",
+			cid:     "bafyrei/abc/def",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "contains backslash",
+			cid:     "bafyrei\\abc",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "contains double dot",
+			cid:     "bafyrei..abc",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "invalid base32 chars",
+			cid:     "bafyreihgdyzzpkkzq2izfnhcmm77ycuacvkuziwbnqxfxtqsz7tmxwhnshi!@#",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "random string not matching any CID pattern",
+			cid:     "this_is_not_a_valid_cid_at_all_12345",
+			wantErr: ErrInvalidCID,
+		},
+		{
+			name:    "too long",
+			cid:     "bafyrei" + string(make([]byte, 200)),
+			wantErr: ErrInvalidCID,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ValidateCID(tt.cid)
+			if !errors.Is(err, tt.wantErr) {
+				t.Errorf("ValidateCID(%q) = %v, want %v", tt.cid, err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestSanitizePathComponent(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "clean string unchanged",
+			input: "abc123",
+			want:  "abc123",
+		},
+		{
+			name:  "forward slashes removed",
+			input: "path/to/file",
+			want:  "path_to_file",
+		},
+		{
+			name:  "backslashes removed",
+			input: "path\\to\\file",
+			want:  "path_to_file",
+		},
+		{
+			name:  "path traversal removed",
+			input: "../../../etc/passwd",
+			want:  "___etc_passwd",
+		},
+		{
+			name:  "colons replaced",
+			input: "did:plc:abc123",
+			want:  "did_plc_abc123",
+		},
+		{
+			name:  "null bytes removed",
+			input: "abc\x00def",
+			want:  "abcdef",
+		},
+		{
+			name:  "multiple dangerous chars",
+			input: "../path:to\\file\x00.txt",
+			want:  "_path_to_file.txt",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := SanitizePathComponent(tt.input)
+			if got != tt.want {
+				t.Errorf("SanitizePathComponent(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestMakeDIDSafe_PathTraversal(t *testing.T) {
+	tests := []struct {
+		name  string
+		did   string
+		check func(result string) bool
+	}{
+		{
+			name: "normal did:plc is safe",
+			did:  "did:plc:abc123",
+			check: func(r string) bool {
+				return r == "did_plc_abc123"
+			},
+		},
+		{
+			name: "path traversal sequences removed",
+			did:  "did:plc:../../../etc/passwd",
+			check: func(r string) bool {
+				// Should not contain .. or /
+				return !contains(r, "..") && !contains(r, "/") && !contains(r, "\\")
+			},
+		},
+		{
+			name: "forward slashes removed",
+			did:  "did:plc:abc/def",
+			check: func(r string) bool {
+				return !contains(r, "/")
+			},
+		},
+		{
+			name: "backslashes removed",
+			did:  "did:plc:abc\\def",
+			check: func(r string) bool {
+				return !contains(r, "\\")
+			},
+		},
+		{
+			name: "null bytes removed",
+			did:  "did:plc:abc\x00def",
+			check: func(r string) bool {
+				return !contains(r, "\x00")
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := makeDIDSafe(tt.did)
+			if !tt.check(result) {
+				t.Errorf("makeDIDSafe(%q) = %q, failed safety check", tt.did, result)
+			}
+		})
+	}
+}
+
+func TestMakeCIDSafe_PathTraversal(t *testing.T) {
+	tests := []struct {
+		name  string
+		cid   string
+		check func(result string) bool
+	}{
+		{
+			name: "normal CID unchanged",
+			cid:  "bafyreiabc123",
+			check: func(r string) bool {
+				return r == "bafyreiabc123"
+			},
+		},
+		{
+			name: "path traversal removed",
+			cid:  "../../../etc/passwd",
+			check: func(r string) bool {
+				return !contains(r, "..") && !contains(r, "/")
+			},
+		},
+		{
+			name: "forward slashes removed",
+			cid:  "abc/def/ghi",
+			check: func(r string) bool {
+				return !contains(r, "/")
+			},
+		},
+		{
+			name: "backslashes removed",
+			cid:  "abc\\def\\ghi",
+			check: func(r string) bool {
+				return !contains(r, "\\")
+			},
+		},
+		{
+			name: "null bytes removed",
+			cid:  "abc\x00def",
+			check: func(r string) bool {
+				return !contains(r, "\x00")
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := makeCIDSafe(tt.cid)
+			if !tt.check(result) {
+				t.Errorf("makeCIDSafe(%q) = %q, failed safety check", tt.cid, result)
+			}
+		})
+	}
+}
+
+// helper function for checking string containment
+func contains(s, substr string) bool {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return true
+		}
+	}
+	return false
+}

internal/core/users/service.go

···
 
 import (
 	"Coves/internal/atproto/identity"
+	"Coves/internal/core/blobs"
+	"Coves/internal/core/communities"
 	"bytes"
 	"context"
 	"encoding/json"
···
 		Bio:         user.Bio,
 	}
 
-	// Transform avatar CID to URL if both CID and PDS URL are present
-	if user.AvatarCID != "" && user.PDSURL != "" {
-		profile.Avatar = fmt.Sprintf("%s/xrpc/com.atproto.sync.getBlob?did=%s&cid=%s",
-			strings.TrimSuffix(user.PDSURL, "/"), user.DID, user.AvatarCID)
-	}
-
-	// Transform banner CID to URL if both CID and PDS URL are present
-	if user.BannerCID != "" && user.PDSURL != "" {
-		profile.Banner = fmt.Sprintf("%s/xrpc/com.atproto.sync.getBlob?did=%s&cid=%s",
-			strings.TrimSuffix(user.PDSURL, "/"), user.DID, user.BannerCID)
-	}
+	// Transform avatar/banner CIDs to URLs using image proxy config
+	// Uses 'avatar' preset (160x160) for profile detail view
+	config := communities.GetImageProxyConfig()
+	profile.Avatar = blobs.HydrateImageURL(config, user.PDSURL, user.DID, user.AvatarCID, "avatar")
+	profile.Banner = blobs.HydrateImageURL(config, user.PDSURL, user.DID, user.BannerCID, "banner")
 
 	return profile, nil
 }

internal/core/users/service_test.go

···
 	assert.Equal(t, "Avatar User", profile.DisplayName)
 	assert.Equal(t, "Test bio for avatar user", profile.Bio)
 
-	// Verify CID-to-URL transformation
-	expectedAvatarURL := "https://test.pds/xrpc/com.atproto.sync.getBlob?did=did:plc:avataruser&cid=bafkreiabc123avatar"
-	expectedBannerURL := "https://test.pds/xrpc/com.atproto.sync.getBlob?did=did:plc:avataruser&cid=bafkreixyz789banner"
+	// Verify CID-to-URL transformation (DID is URL-encoded in query params)
+	expectedAvatarURL := "https://test.pds/xrpc/com.atproto.sync.getBlob?did=did%3Aplc%3Aavataruser&cid=bafkreiabc123avatar"
+	expectedBannerURL := "https://test.pds/xrpc/com.atproto.sync.getBlob?did=did%3Aplc%3Aavataruser&cid=bafkreixyz789banner"
 	assert.Equal(t, expectedAvatarURL, profile.Avatar)
 	assert.Equal(t, expectedBannerURL, profile.Banner)
 
···
 	profile, err := service.GetProfile(ctx, testDID)
 	require.NoError(t, err)
 
-	// Avatar should be transformed to URL
-	expectedAvatarURL := "https://test.pds/xrpc/com.atproto.sync.getBlob?did=did:plc:avataronly&cid=bafkreiavataronly"
+	// Avatar should be transformed to URL (DID is URL-encoded in query params)
+	expectedAvatarURL := "https://test.pds/xrpc/com.atproto.sync.getBlob?did=did%3Aplc%3Aavataronly&cid=bafkreiavataronly"
 	assert.Equal(t, expectedAvatarURL, profile.Avatar)
 
 	// Banner should be empty

internal/db/postgres/feed_repo_base.go

···
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
+	"log/slog"
 	"strings"
 	"time"
 
 	"Coves/internal/core/blobs"
+	"Coves/internal/core/communities"
 	"Coves/internal/core/posts"
 )
 
···
 	if communityHandle.Valid {
 		communityRef.Handle = communityHandle.String
 	}
-	// Hydrate avatar CID to URL (instead of returning raw CID)
-	if avatarURL := blobs.HydrateBlobURL(communityPDSURL.String, communityRef.DID, communityAvatar.String); avatarURL != "" {
+	// Hydrate avatar CID to URL using image proxy config (avatar_small preset for feed lists)
+	if avatarURL := blobs.HydrateImageURL(communities.GetImageProxyConfig(), communityPDSURL.String, communityRef.DID, communityAvatar.String, "avatar_small"); avatarURL != "" {
 		communityRef.Avatar = &avatarURL
 	}
 	if communityPDSURL.Valid {
···
 	postView.Text = nullStringPtr(content)
 
 	// Parse facets JSON
+	// Log errors but continue - a single malformed post shouldn't break the entire feed
 	if facets.Valid {
 		var facetArray []interface{}
-		if err := json.Unmarshal([]byte(facets.String), &facetArray); err == nil {
+		if err := json.Unmarshal([]byte(facets.String), &facetArray); err != nil {
+			slog.Warn("[FEED] failed to parse facets JSON",
+				"post_uri", postView.URI,
+				"error", err,
+			)
+		} else {
 			postView.TextFacets = facetArray
 		}
 	}
 
 	// Parse embed JSON
+	// Log errors but continue - a single malformed post shouldn't break the entire feed
 	if embed.Valid {
 		var embedData interface{}
-		if err := json.Unmarshal([]byte(embed.String), &embedData); err == nil {
+		if err := json.Unmarshal([]byte(embed.String), &embedData); err != nil {
+			slog.Warn("[FEED] failed to parse embed JSON",
+				"post_uri", postView.URI,
+				"error", err,
+			)
+		} else {
 			postView.Embed = embedData
 		}
 	}
···
 	if content.Valid {
 		record["content"] = content.String
 	}
-	if facets.Valid {
-		var facetArray []interface{}
-		if err := json.Unmarshal([]byte(facets.String), &facetArray); err == nil {
-			record["facets"] = facetArray
-		}
+	// Reuse already-parsed facets and embed from PostView (parsed above with logging)
+	// This avoids double parsing and ensures consistent error handling
+	if postView.TextFacets != nil {
+		record["facets"] = postView.TextFacets
 	}
-	if embed.Valid {
-		var embedData interface{}
-		if err := json.Unmarshal([]byte(embed.String), &embedData); err == nil {
-			record["embed"] = embedData
-		}
+	if postView.Embed != nil {
+		record["embed"] = postView.Embed
 	}
 	if labelsJSON.Valid {
 		// Labels are stored as JSONB containing full com.atproto.label.defs#selfLabels structure
 		// Deserialize and include in record
 		var selfLabels posts.SelfLabels
-		if err := json.Unmarshal([]byte(labelsJSON.String), &selfLabels); err == nil {
+		if err := json.Unmarshal([]byte(labelsJSON.String), &selfLabels); err != nil {
+			slog.Warn("[FEED] failed to parse labels JSON",
+				"post_uri", postView.URI,
+				"error", err,
+			)
+		} else {
 			record["labels"] = selfLabels
 		}
 	}

internal/db/postgres/post_repo.go

···
 	"time"
 
 	"Coves/internal/core/blobs"
+	"Coves/internal/core/communities"
 	"Coves/internal/core/posts"
 )
 
···
 	if communityHandle.Valid {
 		communityRef.Handle = communityHandle.String
 	}
-	// Hydrate avatar CID to URL (instead of returning raw CID)
-	if avatarURL := blobs.HydrateBlobURL(communityPDSURL.String, communityRef.DID, communityAvatar.String); avatarURL != "" {
+	// Hydrate avatar CID to URL using image proxy config (avatar_small preset for post views)
+	if avatarURL := blobs.HydrateImageURL(communities.GetImageProxyConfig(), communityPDSURL.String, communityRef.DID, communityAvatar.String, "avatar_small"); avatarURL != "" {
 		communityRef.Avatar = &avatarURL
 	}
 	if communityPDSURL.Valid {

tests/integration/image_proxy_e2e_test.go

···
+package integration
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"image"
+	"image/color"
+	"image/png"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/disintegration/imaging"
+	"github.com/go-chi/chi/v5"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"Coves/internal/api/handlers/imageproxy"
+	"Coves/internal/api/routes"
+	"Coves/internal/atproto/identity"
+	"Coves/internal/core/blobs"
+	"Coves/internal/core/communities"
+	imageproxycore "Coves/internal/core/imageproxy"
+	"Coves/internal/db/postgres"
+)
+
+// TestImageProxy_E2E tests the complete image proxy flow including:
+// - Creating a community with an avatar
+// - Fetching the avatar via the image proxy
+// - Verifying response headers, status codes, and image dimensions
+// - Testing ETag-based caching (304 responses)
+// - Error handling for invalid presets and missing blobs
+func TestImageProxy_E2E(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping E2E integration test in short mode")
+	}
+
+	// Check if PDS is running
+	pdsURL := getTestPDSURL()
+	healthResp, err := http.Get(pdsURL + "/xrpc/_health")
+	if err != nil {
+		t.Skipf("PDS not running at %s: %v. Run 'make dev-up' to start.", pdsURL, err)
+	}
+	_ = healthResp.Body.Close()
+
+	// Setup test database
+	db := setupTestDB(t)
+	defer func() { _ = db.Close() }()
+
+	ctx := context.Background()
+
+	// Setup repositories and services
+	communityRepo := postgres.NewCommunityRepository(db)
+
+	// Setup identity resolver with local PLC
+	plcURL := os.Getenv("PLC_DIRECTORY_URL")
+	if plcURL == "" {
+		plcURL = "http://localhost:3002"
+	}
+	identityConfig := identity.DefaultConfig()
+	identityConfig.PLCURL = plcURL
+	identityResolver := identity.NewResolver(db, identityConfig)
+
+	// Create a real community WITH an avatar using the community service
+	// This ensures the blob is referenced by the community profile record
+	// (blobs must be referenced to be stored by PDS)
+	instanceDID := "did:web:coves.social"
+	provisioner := communities.NewPDSAccountProvisioner("coves.social", pdsURL)
+	blobService := blobs.NewBlobService(pdsURL)
+
+	communityService := communities.NewCommunityServiceWithPDSFactory(
+		communityRepo,
+		pdsURL,
+		instanceDID,
+		"coves.social",
+		provisioner,
+		nil, // No custom PDS factory
+		blobService,
+	)
+
+	// Create avatar image data
+	avatarData := createTestImageForProxy(t, 200, 200, color.RGBA{R: 100, G: 150, B: 200, A: 255})
+
+	uniqueID := time.Now().UnixNano() % 100000000 // Keep shorter for handle limit
+	communityName := fmt.Sprintf("ip%d", uniqueID)
+	creatorDID := fmt.Sprintf("did:plc:c%d", uniqueID)
+
+	t.Logf("Creating community with avatar: %s", communityName)
+	community, err := communityService.CreateCommunity(ctx, communities.CreateCommunityRequest{
+		Name:                   communityName,
+		DisplayName:            "Image Proxy Test Community",
+		Description:            "Testing image proxy with avatar",
+		Visibility:             "public",
+		CreatedByDID:           creatorDID,
+		HostedByDID:            instanceDID,
+		AllowExternalDiscovery: true,
+		AvatarBlob:             avatarData,
+		AvatarMimeType:         "image/png",
+	})
+	require.NoError(t, err, "Failed to create community with avatar")
+
+	// Get the avatar CID from the created community
+	avatarCID := community.AvatarCID
+	require.NotEmpty(t, avatarCID, "Avatar CID should not be empty")
+	t.Logf("Created community: DID=%s, AvatarCID=%s", community.DID, avatarCID)
+
+	// Verify blob exists on PDS before starting proxy tests
+	directBlobURL := fmt.Sprintf("%s/xrpc/com.atproto.sync.getBlob?did=%s&cid=%s", pdsURL, community.DID, avatarCID)
+	t.Logf("Verifying blob exists at: %s", directBlobURL)
+	verifyResp, verifyErr := http.Get(directBlobURL)
+	if verifyErr != nil {
+		t.Logf("Warning: Failed to verify blob: %v", verifyErr)
+	} else {
+		t.Logf("Direct blob fetch status: %d", verifyResp.StatusCode)
+		if verifyResp.StatusCode != http.StatusOK {
+			var errBuf bytes.Buffer
+			_, _ = errBuf.ReadFrom(verifyResp.Body)
+			t.Logf("Direct blob fetch error: %s", errBuf.String())
+		}
+		_ = verifyResp.Body.Close()
+	}
+
+	// Create the test server with image proxy routes
+	testServer := createImageProxyTestServer(t, pdsURL, identityResolver)
+	defer testServer.Close()
+
+	t.Run("fetch avatar via proxy returns valid JPEG", func(t *testing.T) {
+		// Build request URL
+		proxyURL := fmt.Sprintf("%s/img/avatar_small/plain/%s/%s", testServer.URL, community.DID, avatarCID)
+		t.Logf("Requesting: %s", proxyURL)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Log error details if not 200
+		if resp.StatusCode != http.StatusOK {
+			var errBuf bytes.Buffer
+			_, _ = errBuf.ReadFrom(resp.Body)
+			t.Logf("Error response (status %d): %s", resp.StatusCode, errBuf.String())
+		}
+
+		// Verify status code
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Should return 200 OK")
+
+		// Verify Content-Type header
+		contentType := resp.Header.Get("Content-Type")
+		assert.Equal(t, "image/jpeg", contentType, "Content-Type should be image/jpeg")
+
+		// Read the response body
+		var buf bytes.Buffer
+		_, err = buf.ReadFrom(resp.Body)
+		require.NoError(t, err, "Should read response body")
+
+		// Verify it's valid image data
+		img, err := imaging.Decode(&buf)
+		require.NoError(t, err, "Response should be valid image data")
+
+		// Verify dimensions match avatar_small preset (360x360)
+		bounds := img.Bounds()
+		assert.Equal(t, 360, bounds.Dx(), "Width should be 360 (avatar_small preset)")
+		assert.Equal(t, 360, bounds.Dy(), "Height should be 360 (avatar_small preset)")
+
+		t.Logf("Successfully fetched and verified avatar: %dx%d", bounds.Dx(), bounds.Dy())
+	})
+
+	t.Run("returns correct cache headers", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/avatar_small/plain/%s/%s", testServer.URL, community.DID, avatarCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Verify Cache-Control header
+		cacheControl := resp.Header.Get("Cache-Control")
+		expectedCacheControl := "public, max-age=31536000, immutable"
+		assert.Equal(t, expectedCacheControl, cacheControl, "Cache-Control header should be correct")
+
+		// Verify ETag header is present and matches expected format
+		etag := resp.Header.Get("ETag")
+		expectedETag := fmt.Sprintf(`"avatar_small-%s"`, avatarCID)
+		assert.Equal(t, expectedETag, etag, "ETag should match preset-cid format")
+
+		t.Logf("Cache headers verified: Cache-Control=%s, ETag=%s", cacheControl, etag)
+	})
+
+	t.Run("ETag returns 304 on match", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/avatar_small/plain/%s/%s", testServer.URL, community.DID, avatarCID)
+
+		// First, get the ETag
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Initial request should succeed")
+		etag := resp.Header.Get("ETag")
+		_ = resp.Body.Close()
+		require.NotEmpty(t, etag, "ETag should be present")
+
+		// Now make a conditional request with If-None-Match
+		req, err := http.NewRequest(http.MethodGet, proxyURL, nil)
+		require.NoError(t, err, "Should create request")
+		req.Header.Set("If-None-Match", etag)
+
+		resp, err = http.DefaultClient.Do(req)
+		require.NoError(t, err, "Conditional request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Verify 304 Not Modified
+		assert.Equal(t, http.StatusNotModified, resp.StatusCode, "Should return 304 Not Modified")
+
+		// Verify no body in 304 response
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		assert.Equal(t, 0, buf.Len(), "304 response should have empty body")
+
+		t.Log("ETag conditional request correctly returned 304 Not Modified")
+	})
+
+	t.Run("ETag mismatch returns full image", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/avatar_small/plain/%s/%s", testServer.URL, community.DID, avatarCID)
+
+		// Make request with non-matching ETag
+		req, err := http.NewRequest(http.MethodGet, proxyURL, nil)
+		require.NoError(t, err, "Should create request")
+		req.Header.Set("If-None-Match", `"wrong-etag-value"`)
+
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Should return 200 with full image
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Should return 200 OK when ETag doesn't match")
+
+		// Verify body is present
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		assert.Greater(t, buf.Len(), 0, "Response should have body")
+
+		t.Log("Non-matching ETag correctly returned full image")
+	})
+
+	t.Run("invalid preset returns 400", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/not_a_valid_preset/plain/%s/%s", testServer.URL, community.DID, avatarCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Verify 400 Bad Request
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode, "Should return 400 for invalid preset")
+
+		// Verify error message
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		body := buf.String()
+		assert.Contains(t, body, "invalid preset", "Error message should mention invalid preset")
+
+		t.Logf("Invalid preset correctly returned 400: %s", body)
+	})
+
+	t.Run("non-existent CID returns 404", func(t *testing.T) {
+		// Use a valid CIDv1 (raw codec, sha256) that doesn't exist on the PDS
+		// This is a properly formatted CID that will pass validation but won't exist
+		fakeCID := "bafkreiemeosfdll427qzow5tipvctigjebyvi6ketznqrau2ydhzyggt7i"
+		proxyURL := fmt.Sprintf("%s/img/avatar_small/plain/%s/%s", testServer.URL, community.DID, fakeCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Verify 404 Not Found (blob not found on PDS)
+		assert.Equal(t, http.StatusNotFound, resp.StatusCode, "Should return 404 for non-existent CID")
+
+		t.Log("Non-existent CID correctly returned 404")
+	})
+
+	t.Run("all valid presets work correctly", func(t *testing.T) {
+		// Test a subset of presets with fixed dimensions (cover fit)
+		presetTests := []struct {
+			preset       string
+			expectWidth  int
+			expectHeight int
+		}{
+			{"avatar", 1000, 1000},
+			{"avatar_small", 360, 360},
+			// banner has 640x300 but input is 200x200, so it will be scaled+cropped
+			{"banner", 640, 300},
+			// embed_thumbnail is 720x360, will also be scaled+cropped
+			{"embed_thumbnail", 720, 360},
+		}
+
+		for _, tc := range presetTests {
+			t.Run(tc.preset, func(t *testing.T) {
+				proxyURL := fmt.Sprintf("%s/img/%s/plain/%s/%s", testServer.URL, tc.preset, community.DID, avatarCID)
+
+				resp, err := http.Get(proxyURL)
+				require.NoError(t, err, "Request should succeed for preset %s", tc.preset)
+				defer func() { _ = resp.Body.Close() }()
+
+				assert.Equal(t, http.StatusOK, resp.StatusCode, "Should return 200 for valid preset %s", tc.preset)
+
+				// Verify ETag format
+				etag := resp.Header.Get("ETag")
+				expectedETag := fmt.Sprintf(`"%s-%s"`, tc.preset, avatarCID)
+				assert.Equal(t, expectedETag, etag, "ETag should match for preset %s", tc.preset)
+
+				// Verify image dimensions
+				var buf bytes.Buffer
+				_, _ = buf.ReadFrom(resp.Body)
+				img, err := imaging.Decode(&buf)
+				require.NoError(t, err, "Should decode image for preset %s", tc.preset)
+
+				bounds := img.Bounds()
+				assert.Equal(t, tc.expectWidth, bounds.Dx(), "Width should match for preset %s", tc.preset)
+				assert.Equal(t, tc.expectHeight, bounds.Dy(), "Height should match for preset %s", tc.preset)
+
+				t.Logf("Preset %s: verified %dx%d", tc.preset, bounds.Dx(), bounds.Dy())
+			})
+		}
+	})
+
+	t.Run("missing parameters return 400", func(t *testing.T) {
+		testCases := []struct {
+			name string
+			url  string
+		}{
+			{"missing CID", fmt.Sprintf("%s/img/avatar/plain/%s/", testServer.URL, community.DID)},
+			{"missing DID", fmt.Sprintf("%s/img/avatar/plain//%s", testServer.URL, avatarCID)},
+		}
+
+		for _, tc := range testCases {
+			t.Run(tc.name, func(t *testing.T) {
+				resp, err := http.Get(tc.url)
+				require.NoError(t, err, "Request should succeed")
+				defer func() { _ = resp.Body.Close() }()
+
+				// Should return 400 or 404 (depends on routing)
+				assert.True(t, resp.StatusCode == http.StatusBadRequest || resp.StatusCode == http.StatusNotFound,
+					"Should return 400 or 404 for %s, got %d", tc.name, resp.StatusCode)
+			})
+		}
+	})
+
+	t.Run("content_preview preset preserves aspect ratio", func(t *testing.T) {
+		// content_preview uses FitContain which preserves aspect ratio
+		// Input is 200x200, max width is 800, so output should be 200x200 (no upscaling)
+		proxyURL := fmt.Sprintf("%s/img/content_preview/plain/%s/%s", testServer.URL, community.DID, avatarCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Should return 200")
+
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		img, err := imaging.Decode(&buf)
+		require.NoError(t, err, "Should decode image")
+
+		bounds := img.Bounds()
+		// content_preview with FitContain doesn't upscale, so 200x200 stays 200x200
+		assert.Equal(t, 200, bounds.Dx(), "Width should be preserved (no upscaling)")
+		assert.Equal(t, 200, bounds.Dy(), "Height should be preserved (no upscaling)")
+
+		t.Logf("content_preview preserved aspect ratio: %dx%d", bounds.Dx(), bounds.Dy())
+	})
+}
+
+// TestImageProxy_CacheHit tests that cache hits are faster than cache misses
+func TestImageProxy_CacheHit(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping cache test in short mode")
+	}
+
+	// Check if PDS is running
+	pdsURL := getTestPDSURL()
+	healthResp, err := http.Get(pdsURL + "/xrpc/_health")
+	if err != nil {
+		t.Skipf("PDS not running at %s: %v. Run 'make dev-up' to start.", pdsURL, err)
+	}
+	_ = healthResp.Body.Close()
+
+	// Setup test database
+	db := setupTestDB(t)
+	defer func() { _ = db.Close() }()
+
+	ctx := context.Background()
+
+	// Setup repositories and services
+	communityRepo := postgres.NewCommunityRepository(db)
+
+	// Setup identity resolver
+	plcURL := os.Getenv("PLC_DIRECTORY_URL")
+	if plcURL == "" {
+		plcURL = "http://localhost:3002"
+	}
+	identityConfig := identity.DefaultConfig()
+	identityConfig.PLCURL = plcURL
+	identityResolver := identity.NewResolver(db, identityConfig)
+
+	// Create a real community with avatar using the community service
+	instanceDID := "did:web:coves.social"
+	provisioner := communities.NewPDSAccountProvisioner("coves.social", pdsURL)
+	blobService := blobs.NewBlobService(pdsURL)
+
+	communityService := communities.NewCommunityServiceWithPDSFactory(
+		communityRepo,
+		pdsURL,
+		instanceDID,
+		"coves.social",
+		provisioner,
+		nil,
+		blobService,
+	)
+
+	avatarData := createTestImageForProxy(t, 150, 150, color.RGBA{R: 50, G: 100, B: 150, A: 255})
+	uniqueID := time.Now().UnixNano() % 100000000 // Keep shorter for handle limit
+	communityName := fmt.Sprintf("ic%d", uniqueID)
+	creatorDID := fmt.Sprintf("did:plc:cc%d", uniqueID)
+
+	community, err := communityService.CreateCommunity(ctx, communities.CreateCommunityRequest{
+		Name:                   communityName,
+		DisplayName:            "Image Cache Test Community",
+		Description:            "Testing image proxy caching",
+		Visibility:             "public",
+		CreatedByDID:           creatorDID,
+		HostedByDID:            instanceDID,
+		AllowExternalDiscovery: true,
+		AvatarBlob:             avatarData,
+		AvatarMimeType:         "image/png",
+	})
+	require.NoError(t, err, "Failed to create community with avatar")
+
+	avatarCID := community.AvatarCID
+	require.NotEmpty(t, avatarCID, "Avatar CID should not be empty")
+	t.Logf("Created community: DID=%s, AvatarCID=%s", community.DID, avatarCID)
+
+	// Create temp directory for cache
+	cacheDir := t.TempDir()
+
+	// Create test server with caching enabled
+	testServer := createImageProxyTestServerWithCache(t, pdsURL, identityResolver, cacheDir)
+	defer testServer.Close()
+
+	proxyURL := fmt.Sprintf("%s/img/avatar/plain/%s/%s", testServer.URL, community.DID, avatarCID)
+
+	// First request (cache miss)
+	startFirst := time.Now()
+	resp, err := http.Get(proxyURL)
+	require.NoError(t, err, "First request should succeed")
+	_ = resp.Body.Close()
+	firstDuration := time.Since(startFirst)
+
+	// Second request (should hit cache)
+	startSecond := time.Now()
+	resp, err = http.Get(proxyURL)
+	require.NoError(t, err, "Second request should succeed")
+	_ = resp.Body.Close()
+	secondDuration := time.Since(startSecond)
+
+	t.Logf("First request (cache miss): %v", firstDuration)
+	t.Logf("Second request (should hit cache): %v", secondDuration)
+
+	// Note: Cache hit should generally be faster, but timing can be flaky in tests
+	// So we just verify both requests succeed
+	assert.Equal(t, http.StatusOK, resp.StatusCode, "Cached request should return 200")
+}
+
+// createTestImageForProxy creates a test PNG image with specified dimensions and color
+func createTestImageForProxy(t *testing.T, width, height int, fillColor color.Color) []byte {
+	t.Helper()
+
+	img := image.NewRGBA(image.Rect(0, 0, width, height))
+	for y := 0; y < height; y++ {
+		for x := 0; x < width; x++ {
+			img.Set(x, y, fillColor)
+		}
+	}
+
+	var buf bytes.Buffer
+	err := png.Encode(&buf, img)
+	require.NoError(t, err, "PNG encoding should succeed")
+
+	return buf.Bytes()
+}
+
+// createImageProxyTestServer creates an httptest server with image proxy routes configured
+func createImageProxyTestServer(t *testing.T, pdsURL string, identityResolver identity.Resolver) *httptest.Server {
+	t.Helper()
+
+	// Create temp directory for cache
+	cacheDir := t.TempDir()
+	return createImageProxyTestServerWithCache(t, pdsURL, identityResolver, cacheDir)
+}
+
+// createImageProxyTestServerWithCache creates an httptest server with image proxy routes and specified cache directory
+func createImageProxyTestServerWithCache(t *testing.T, pdsURL string, identityResolver identity.Resolver, cacheDir string) *httptest.Server {
+	t.Helper()
+
+	// Create imageproxy service components
+	cache, err := imageproxycore.NewDiskCache(cacheDir, 1, 0)
+	require.NoError(t, err, "Failed to create disk cache") // 1GB max
+	processor := imageproxycore.NewProcessor()
+	fetcher := imageproxycore.NewPDSFetcher(30 * time.Second, 10)
+	config := imageproxycore.Config{
+		Enabled:         true,
+		CachePath:       cacheDir,
+		CacheMaxGB:      1,
+		FetchTimeout:    30 * time.Second,
+		MaxSourceSizeMB: 10,
+	}
+
+	service, err := imageproxycore.NewService(cache, processor, fetcher, config)
+	require.NoError(t, err, "Failed to create imageproxy service")
+
+	// Create handler
+	handler := imageproxy.NewHandler(service, identityResolver)
+
+	// Create router and register routes
+	r := chi.NewRouter()
+	routes.RegisterImageProxyRoutes(r, handler)
+
+	return httptest.NewServer(r)
+}
+
+// TestImageProxy_MockPDS tests the image proxy with a mock PDS server
+// This allows testing image proxy behavior without a real PDS
+func TestImageProxy_MockPDS(t *testing.T) {
+	// Create test image
+	testImage := createTestImageForProxy(t, 100, 100, color.RGBA{R: 255, G: 128, B: 64, A: 255})
+	testCID := "bafybeimockimagetest123"
+	testDID := "did:plc:mocktest123"
+
+	// Create mock PDS server that returns the test image
+	mockPDS := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Verify it's a getBlob request
+		if !strings.HasPrefix(r.URL.Path, "/xrpc/com.atproto.sync.getBlob") {
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+
+		// Check query parameters
+		did := r.URL.Query().Get("did")
+		cid := r.URL.Query().Get("cid")
+
+		if did == testDID && cid == testCID {
+			w.Header().Set("Content-Type", "image/png")
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write(testImage)
+			return
+		}
+
+		// Return 404 for unknown blobs
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer mockPDS.Close()
+
+	// Create mock identity resolver that returns the mock PDS URL
+	mockResolver := &mockIdentityResolverForImageProxy{
+		pdsURL: mockPDS.URL,
+	}
+
+	// Create test server
+	cacheDir := t.TempDir()
+	cache, err := imageproxycore.NewDiskCache(cacheDir, 1, 0)
+	require.NoError(t, err, "Failed to create disk cache")
+	processor := imageproxycore.NewProcessor()
+	fetcher := imageproxycore.NewPDSFetcher(30 * time.Second, 10)
+	config := imageproxycore.Config{
+		Enabled:         true,
+		CachePath:       cacheDir,
+		CacheMaxGB:      1,
+		FetchTimeout:    30 * time.Second,
+		MaxSourceSizeMB: 10,
+	}
+
+	service, err := imageproxycore.NewService(cache, processor, fetcher, config)
+	require.NoError(t, err, "Failed to create imageproxy service")
+	handler := imageproxy.NewHandler(service, mockResolver)
+
+	r := chi.NewRouter()
+	routes.RegisterImageProxyRoutes(r, handler)
+	testServer := httptest.NewServer(r)
+	defer testServer.Close()
+
+	t.Run("mock PDS returns valid image", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/avatar/plain/%s/%s", testServer.URL, testDID, testCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Should return 200")
+		assert.Equal(t, "image/jpeg", resp.Header.Get("Content-Type"), "Content-Type should be JPEG")
+
+		// Verify processed dimensions (avatar is 1000x1000 per presets.go)
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		img, err := imaging.Decode(&buf)
+		require.NoError(t, err, "Should decode image")
+
+		bounds := img.Bounds()
+		assert.Equal(t, 1000, bounds.Dx(), "Width should be 1000 (avatar preset)")
+		assert.Equal(t, 1000, bounds.Dy(), "Height should be 1000 (avatar preset)")
+	})
+
+	t.Run("mock PDS 404 returns proxy 404", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/avatar/plain/%s/%s", testServer.URL, testDID, "nonexistentcid")
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusNotFound, resp.StatusCode, "Should return 404")
+	})
+}
+
+// mockIdentityResolverForImageProxy is a mock identity resolver for testing
+type mockIdentityResolverForImageProxy struct {
+	pdsURL string
+}
+
+func (m *mockIdentityResolverForImageProxy) Resolve(ctx context.Context, identifier string) (*identity.Identity, error) {
+	return nil, fmt.Errorf("not implemented")
+}
+
+func (m *mockIdentityResolverForImageProxy) ResolveHandle(ctx context.Context, handle string) (did, pdsURL string, err error) {
+	return "", "", fmt.Errorf("not implemented")
+}
+
+func (m *mockIdentityResolverForImageProxy) ResolveDID(ctx context.Context, did string) (*identity.DIDDocument, error) {
+	return &identity.DIDDocument{
+		DID: did,
+		Service: []identity.Service{
+			{
+				ID:              "#atproto_pds",
+				Type:            "AtprotoPersonalDataServer",
+				ServiceEndpoint: m.pdsURL,
+			},
+		},
+	}, nil
+}
+
+func (m *mockIdentityResolverForImageProxy) Purge(ctx context.Context, identifier string) error {
+	return nil
+}
+
+// TestImageProxy_ErrorHandling tests various error conditions
+func TestImageProxy_ErrorHandling(t *testing.T) {
+	// Create mock identity resolver
+	mockResolver := &mockIdentityResolverForImageProxy{
+		pdsURL: "http://localhost:9999", // Non-existent server
+	}
+
+	// Create test server
+	cacheDir := t.TempDir()
+	cache, err := imageproxycore.NewDiskCache(cacheDir, 1, 0)
+	require.NoError(t, err, "Failed to create disk cache")
+	processor := imageproxycore.NewProcessor()
+	fetcher := imageproxycore.NewPDSFetcher(1 * time.Second, 10) // Short timeout
+	config := imageproxycore.Config{
+		Enabled:         true,
+		CachePath:       cacheDir,
+		CacheMaxGB:      1,
+		FetchTimeout:    1 * time.Second,
+		MaxSourceSizeMB: 10,
+	}
+
+	service, err := imageproxycore.NewService(cache, processor, fetcher, config)
+	require.NoError(t, err, "Failed to create imageproxy service")
+	handler := imageproxy.NewHandler(service, mockResolver)
+
+	r := chi.NewRouter()
+	routes.RegisterImageProxyRoutes(r, handler)
+	testServer := httptest.NewServer(r)
+	defer testServer.Close()
+
+	t.Run("connection refused returns 502", func(t *testing.T) {
+		// Use a valid CID format - this will pass validation but fail at the PDS fetch stage
+		validCID := "bafyreihgdyzzpkkzq2izfnhcmm77ycuacvkuziwbnqxfxtqsz7tmxwhnshi"
+		proxyURL := fmt.Sprintf("%s/img/avatar/plain/did:plc:test/%s", testServer.URL, validCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Should return 502 Bad Gateway when PDS fetch fails
+		assert.Equal(t, http.StatusBadGateway, resp.StatusCode, "Should return 502 when PDS is unreachable")
+	})
+
+	t.Run("invalid DID resolution returns 502", func(t *testing.T) {
+		// Create resolver that returns error
+		errorResolver := &errorMockResolver{}
+
+		errorHandler := imageproxy.NewHandler(service, errorResolver)
+		errorRouter := chi.NewRouter()
+		routes.RegisterImageProxyRoutes(errorRouter, errorHandler)
+		errorServer := httptest.NewServer(errorRouter)
+		defer errorServer.Close()
+
+		// Use a valid CID format - this will pass validation but fail at DID resolution
+		validCID := "bafyreihgdyzzpkkzq2izfnhcmm77ycuacvkuziwbnqxfxtqsz7tmxwhnshi"
+		proxyURL := fmt.Sprintf("%s/img/avatar/plain/did:plc:test/%s", errorServer.URL, validCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusBadGateway, resp.StatusCode, "Should return 502 when DID resolution fails")
+	})
+}
+
+// errorMockResolver is a mock resolver that always returns an error
+type errorMockResolver struct{}
+
+func (m *errorMockResolver) Resolve(ctx context.Context, identifier string) (*identity.Identity, error) {
+	return nil, fmt.Errorf("resolution failed")
+}
+
+func (m *errorMockResolver) ResolveHandle(ctx context.Context, handle string) (did, pdsURL string, err error) {
+	return "", "", fmt.Errorf("resolution failed")
+}
+
+func (m *errorMockResolver) ResolveDID(ctx context.Context, did string) (*identity.DIDDocument, error) {
+	return nil, fmt.Errorf("resolution failed")
+}
+
+func (m *errorMockResolver) Purge(ctx context.Context, identifier string) error {
+	return nil
+}
+
+// TestImageProxy_UnsupportedFormat tests behavior with unsupported image formats
+func TestImageProxy_UnsupportedFormat(t *testing.T) {
+	// Create mock PDS that returns invalid image data
+	mockPDS := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/xrpc/com.atproto.sync.getBlob") {
+			cid := r.URL.Query().Get("cid")
+
+			if cid == "textdata" {
+				// Return text data instead of image
+				w.Header().Set("Content-Type", "text/plain")
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte("this is not an image"))
+				return
+			}
+
+			if cid == "corruptedimage" {
+				// Return corrupted image data
+				w.Header().Set("Content-Type", "image/png")
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte{0x89, 0x50, 0x4E, 0x47, 0x00, 0x00}) // Incomplete PNG header
+				return
+			}
+
+			if cid == "emptybody" {
+				// Return empty body
+				w.WriteHeader(http.StatusOK)
+				return
+			}
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer mockPDS.Close()
+
+	mockResolver := &mockIdentityResolverForImageProxy{
+		pdsURL: mockPDS.URL,
+	}
+
+	cacheDir := t.TempDir()
+	cache, err := imageproxycore.NewDiskCache(cacheDir, 1, 0)
+	require.NoError(t, err, "Failed to create disk cache")
+	processor := imageproxycore.NewProcessor()
+	fetcher := imageproxycore.NewPDSFetcher(30 * time.Second, 10)
+	config := imageproxycore.DefaultConfig()
+
+	service, err := imageproxycore.NewService(cache, processor, fetcher, config)
+	require.NoError(t, err, "Failed to create imageproxy service")
+	handler := imageproxy.NewHandler(service, mockResolver)
+
+	r := chi.NewRouter()
+	routes.RegisterImageProxyRoutes(r, handler)
+	testServer := httptest.NewServer(r)
+	defer testServer.Close()
+
+	testCases := []struct {
+		name           string
+		cid            string
+		expectedStatus int
+	}{
+		{"text data", "textdata", http.StatusBadRequest},
+		{"corrupted image", "corruptedimage", http.StatusInternalServerError},
+		{"empty body", "emptybody", http.StatusBadRequest},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			proxyURL := fmt.Sprintf("%s/img/avatar/plain/did:plc:test/%s", testServer.URL, tc.cid)
+
+			resp, err := http.Get(proxyURL)
+			require.NoError(t, err, "Request should succeed")
+			defer func() { _ = resp.Body.Close() }()
+
+			// Should return error status for invalid image data
+			assert.True(t, resp.StatusCode >= 400, "Should return error status for %s", tc.name)
+			t.Logf("%s returned status %d", tc.name, resp.StatusCode)
+		})
+	}
+}
+
+// TestImageProxy_LargeImage tests behavior with large images
+func TestImageProxy_LargeImage(t *testing.T) {
+	// Create a large test image (1000x1000)
+	largeImage := createTestImageForProxy(t, 1000, 1000, color.RGBA{R: 200, G: 100, B: 50, A: 255})
+	testCID := "bafylargeimagecid"
+	testDID := "did:plc:largetest"
+
+	mockPDS := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasPrefix(r.URL.Path, "/xrpc/com.atproto.sync.getBlob") {
+			did := r.URL.Query().Get("did")
+			cid := r.URL.Query().Get("cid")
+
+			if did == testDID && cid == testCID {
+				w.Header().Set("Content-Type", "image/png")
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write(largeImage)
+				return
+			}
+		}
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer mockPDS.Close()
+
+	mockResolver := &mockIdentityResolverForImageProxy{
+		pdsURL: mockPDS.URL,
+	}
+
+	cacheDir := t.TempDir()
+	cache, err := imageproxycore.NewDiskCache(cacheDir, 1, 0)
+	require.NoError(t, err, "Failed to create disk cache")
+	processor := imageproxycore.NewProcessor()
+	fetcher := imageproxycore.NewPDSFetcher(30 * time.Second, 10)
+	config := imageproxycore.DefaultConfig()
+
+	service, err := imageproxycore.NewService(cache, processor, fetcher, config)
+	require.NoError(t, err, "Failed to create imageproxy service")
+	handler := imageproxy.NewHandler(service, mockResolver)
+
+	r := chi.NewRouter()
+	routes.RegisterImageProxyRoutes(r, handler)
+	testServer := httptest.NewServer(r)
+	defer testServer.Close()
+
+	t.Run("large image resized correctly", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/avatar/plain/%s/%s", testServer.URL, testDID, testCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Should return 200")
+
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		img, err := imaging.Decode(&buf)
+		require.NoError(t, err, "Should decode image")
+
+		bounds := img.Bounds()
+		assert.Equal(t, 1000, bounds.Dx(), "Width should be 1000 (avatar preset)")
+		assert.Equal(t, 1000, bounds.Dy(), "Height should be 1000 (avatar preset)")
+
+		t.Logf("Large image correctly resized to %dx%d", bounds.Dx(), bounds.Dy())
+	})
+
+	t.Run("content_preview limits width for large image", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/content_preview/plain/%s/%s", testServer.URL, testDID, testCID)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Should return 200")
+
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		img, err := imaging.Decode(&buf)
+		require.NoError(t, err, "Should decode image")
+
+		bounds := img.Bounds()
+		// content_preview max width is 800, preserves aspect ratio
+		assert.Equal(t, 800, bounds.Dx(), "Width should be limited to 800")
+		assert.Equal(t, 800, bounds.Dy(), "Height should be 800 (1:1 aspect ratio)")
+
+		t.Logf("Large image correctly scaled to %dx%d for content_preview", bounds.Dx(), bounds.Dy())
+	})
+}
+
+// TestImageProxy_ResponseJSON verifies no JSON is returned (should be plain text or image)
+func TestImageProxy_ResponseJSON(t *testing.T) {
+	mockResolver := &mockIdentityResolverForImageProxy{
+		pdsURL: "http://localhost:9999",
+	}
+
+	cacheDir := t.TempDir()
+	cache, err := imageproxycore.NewDiskCache(cacheDir, 1, 0)
+	require.NoError(t, err, "Failed to create disk cache")
+	processor := imageproxycore.NewProcessor()
+	fetcher := imageproxycore.NewPDSFetcher(1 * time.Second, 10)
+	config := imageproxycore.DefaultConfig()
+
+	service, err := imageproxycore.NewService(cache, processor, fetcher, config)
+	require.NoError(t, err, "Failed to create imageproxy service")
+	handler := imageproxy.NewHandler(service, mockResolver)
+
+	r := chi.NewRouter()
+	routes.RegisterImageProxyRoutes(r, handler)
+	testServer := httptest.NewServer(r)
+	defer testServer.Close()
+
+	t.Run("error responses are plain text not JSON", func(t *testing.T) {
+		proxyURL := fmt.Sprintf("%s/img/invalid_preset/plain/did:plc:test/cid", testServer.URL)
+
+		resp, err := http.Get(proxyURL)
+		require.NoError(t, err, "Request should succeed")
+		defer func() { _ = resp.Body.Close() }()
+
+		contentType := resp.Header.Get("Content-Type")
+		assert.Contains(t, contentType, "text/plain", "Error responses should be text/plain")
+
+		// Verify body is not valid JSON
+		var buf bytes.Buffer
+		_, _ = buf.ReadFrom(resp.Body)
+		body := buf.Bytes()
+
+		var jsonCheck map[string]interface{}
+		jsonErr := json.Unmarshal(body, &jsonCheck)
+		assert.Error(t, jsonErr, "Error response should not be valid JSON")
+
+		t.Logf("Error response correctly returned as plain text: %s", string(body))
+	})
+}

tests/integration/user_profile_avatar_e2e_test.go

···
 	"net"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"os"
 	"strings"
 	"testing"
···
 		if finalProfile.Avatar != "" {
 			assert.Contains(t, finalProfile.Avatar, "/xrpc/com.atproto.sync.getBlob",
 				"Avatar URL should be a PDS blob URL")
-			assert.Contains(t, finalProfile.Avatar, userDID,
+			// URL-decode the avatar URL before checking for DID (DIDs are URL-encoded in query params)
+			decodedAvatarURL, _ := url.QueryUnescape(finalProfile.Avatar)
+			assert.Contains(t, decodedAvatarURL, userDID,
 				"Avatar URL should contain user DID")
 		}
 
···
 
 		if finalProfile.Banner != "" {
 			assert.Contains(t, finalProfile.Banner, "/xrpc/com.atproto.sync.getBlob")
-			assert.Contains(t, finalProfile.Banner, userDID)
+			// URL-decode the banner URL before checking for DID (DIDs are URL-encoded in query params)
+			decodedBannerURL, _ := url.QueryUnescape(finalProfile.Banner)
+			assert.Contains(t, decodedBannerURL, userDID)
 		}
 
 		t.Logf("\n TRUE E2E USER PROFILE BANNER UPDATE COMPLETE")