Take the signature, the expiry and the URL scheme off the image request (closes #314)

The image request now holds only its source and its transform, exactly what
the variant key covers. The /v1/image/ handler checks the allowlist and
verifies the signature itself with Signer.Verify(req, sig, expires). Both
image handlers keep the URL's expiry as a local value for Cache-Control. The
image service holds no signer, allowlist or AllowHTTP, and ValidateRequest is
gone. The fetcher takes the source and builds its URL with Source.URL from its
own AllowHTTP, so no URL string is built and parsed again. chooseAutoFormat
returns the format it chooses instead of writing into the request. The signed
URL format and every route's answers are unchanged.

Model: opus-5-5

internal/handlers/auth.go

@@ -153,20 +153,20 @@ func (s *Handlers) HandleGenerateURL() http.HandlerFunc {
 			return
 		}
 
-		// The image URL must fetch the source URL as it was written
-		req.AllowHTTP = s.config.AllowHTTP
-		fetchURL := req.SourceURL()
+		// The image URL must fetch the source URL as it was written. The
+		// fetcher fetches over http only when allow_http is set.
+		fetchURL := req.Source.URL(s.config.AllowHTTP)
 
 		if !fetchedAsWritten(parsed, fetchURL) {
 			s.renderGeneratorWithForm(w, r, "Source URL cannot be fetched as "+
-				"written: pixa would fetch "+fetchURL,
+				"written: pixa would fetch "+fetchURL.String(),
 				r.Form, http.StatusBadRequest)
 
 			return
 		}
 
 		// Generate encrypted token
-		token, err := s.encGen.Generate(req)
+		token, err := s.encGen.Generate(req, expiresAt)
 		if err != nil {
 			s.log.Error("failed to generate encrypted URL", "error", err)
 			s.renderGeneratorWithForm(w, r, "Failed to generate URL", r.Form,
@@ -226,25 +226,23 @@ func parseSourceURL(sourceURL string) (*url.URL, error) {
 // in RawPath when it is not the decoded path percent-encoded again.
 // EscapedPath ignores RawPath when it also holds a character net/url encodes,
 // such as a space, so RawPath is compared itself.
-func fetchedAsWritten(source *url.URL, fetchURL string) bool {
+func fetchedAsWritten(source, fetchURL *url.URL) bool {
 	writtenPath := source.RawPath
 	if writtenPath == "" {
 		writtenPath = source.EscapedPath()
 	}
 
-	fetched, err := url.Parse(fetchURL)
-
-	return err == nil && source.User == nil && !source.ForceQuery &&
-		fetched.EscapedPath() == writtenPath &&
-		fetched.RawQuery == source.RawQuery
+	return source.User == nil && !source.ForceQuery &&
+		fetchURL.EscapedPath() == writtenPath &&
+		fetchURL.RawQuery == source.RawQuery
 }
 
 // buildGenerateRequest parses the numeric form fields and assembles the
-// image request the encrypted URL's token is made from. ttl=0 means never
-// expires (Expires stays the zero time). A non-numeric or out-of-range
-// width, height, quality or ttl, or an unrecognized fit mode, is a client
-// error naming the offending field. The format field is passed through
-// unchecked.
+// image request the encrypted URL's token is made from, and its expiry.
+// ttl=0 means never expires (the expiry is the zero time). A non-numeric or
+// out-of-range width, height, quality or ttl, or an unrecognized fit mode, is
+// a client error naming the offending field. The format field is passed
+// through unchecked.
 func buildGenerateRequest(
 	parsed *url.URL, form url.Values,
 ) (*imagerequest.Request, time.Time, int, error) {
@@ -294,7 +292,6 @@ func buildGenerateRequest(
 			Quality: quality,
 			FitMode: fitMode,
 		},
-		Expires: expiresAt,
 	}
 
 	return req, expiresAt, ttl, nil

internal/handlers/cache_hit_internal_test.go

@@ -19,11 +19,13 @@ import (
 	"github.com/go-chi/chi/v5"
 	"github.com/prometheus/client_golang/prometheus"
 
+	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/database"
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
 )
 
 // countingHost is the allowlisted host whose photoPath the server of
@@ -137,8 +139,6 @@ func newCountingDatabaseServer(
 			MaxInputBytes:           50 << 20,
 			MaxConcurrentProcessing: 2,
 		}),
-		SigningKey:      testSigningKey,
-		Allowlist:       []string{countingHost},
 		MaxResponseSize: 50 << 20,
 		Logger:          slog.New(slog.DiscardHandler),
 	})
@@ -159,15 +159,17 @@ func newCountingDatabaseServer(
 			Quality: 85,
 			FitMode: imagerequest.FitCover,
 		},
-	})
+	}, time.Time{})
 	if err != nil {
 		tb.Fatalf("encGen.Generate() error = %v", err)
 	}
 
 	h := &Handlers{
-		log:    slog.New(slog.DiscardHandler),
-		imgSvc: svc,
-		encGen: encGen,
+		log:       slog.New(slog.DiscardHandler),
+		imgSvc:    svc,
+		encGen:    encGen,
+		signer:    signature.New(testSigningKey),
+		allowlist: allowlist.New([]string{countingHost}),
 	}
 
 	r := chi.NewRouter()

internal/handlers/first_bytes_internal_test.go

@@ -13,11 +13,13 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/prometheus/client_golang/prometheus"
+	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
 )
 
 // mismatchedSourcePath is the path of the source that
@@ -27,8 +29,9 @@ import (
 const mismatchedSourcePath = "/images/source.png"
 
 // newRoutesFetchingThrough returns both image routes, and the Handlers behind
-// them, whose image service fetches through fetcher and has allowlistedHost on
-// its allowlist. The handlers and the image service log to log.
+// them, whose image service fetches through fetcher, and which have
+// allowlistedHost on their allowlist. The handlers and the image service log
+// to log.
 func newRoutesFetchingThrough(
 	t *testing.T, fetcher httpfetcher.Fetcher, log *slog.Logger,
 ) (*Handlers, http.Handler) {
@@ -50,8 +53,6 @@ func newRoutesFetchingThrough(
 			MaxInputBytes:           50 << 20,
 			MaxConcurrentProcessing: 2,
 		}),
-		SigningKey:      testSigningKey,
-		Allowlist:       []string{allowlistedHost},
 		MaxResponseSize: 50 << 20,
 		Logger:          log,
 	})
@@ -64,7 +65,13 @@ func newRoutesFetchingThrough(
 		t.Fatalf("encurl.NewGenerator() error = %v", err)
 	}
 
-	h := &Handlers{log: log, imgSvc: svc, encGen: encGen}
+	h := &Handlers{
+		log:       log,
+		imgSvc:    svc,
+		encGen:    encGen,
+		signer:    signature.New(testSigningKey),
+		allowlist: allowlist.New([]string{allowlistedHost}),
+	}
 
 	r := chi.NewRouter()
 	r.Get("/v1/image/*", h.HandleImage())
@@ -93,7 +100,7 @@ func mismatchedSourceEncURL(t *testing.T, h *Handlers) string {
 			Size:   imagerequest.Size{Width: 50, Height: 50},
 			Format: imagerequest.FormatJPEG,
 		},
-	})
+	}, time.Time{})
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}

internal/handlers/format_auto.go

@@ -18,16 +18,17 @@ var (
 		"image/jxl, image/avif, image/webp or image/jpeg")
 )
 
-// chooseAutoFormat replaces the format auto in req with the format
-// formatForAccept chooses from r's Accept header, and adds Vary: Accept to the
+// chooseAutoFormat returns the format to serve for the requested format: for
+// the format auto, the format formatForAccept chooses from r's Accept header,
+// and any other format as it is. For auto it adds Vary: Accept to the
 // response, which then depends on that header. It answers 400 for an Accept
 // header that is not valid and 406 for one that allows none of the formats,
-// and reports whether req can be served. Any other format is left as it is.
+// and reports whether the image can be served.
 func (s *Handlers) chooseAutoFormat(
-	w http.ResponseWriter, r *http.Request, req *imagerequest.Request,
-) bool {
-	if req.Transform.Format != imagerequest.FormatAuto {
-		return true
+	w http.ResponseWriter, r *http.Request, requested imagerequest.Format,
+) (imagerequest.Format, bool) {
+	if requested != imagerequest.FormatAuto {
+		return requested, true
 	}
 
 	w.Header().Add("Vary", "Accept")
@@ -36,18 +37,16 @@ func (s *Handlers) chooseAutoFormat(
 	if errors.Is(err, errNotAcceptable) {
 		s.respondError(w, err.Error(), http.StatusNotAcceptable)
 
-		return false
+		return "", false
 	}
 
 	if err != nil {
 		s.respondError(w, err.Error(), http.StatusBadRequest)
 
-		return false
+		return "", false
 	}
 
-	req.Transform.Format = format
-
-	return true
+	return format, true
 }
 
 // formatForAccept returns the format an auto URL is served in for the Accept

internal/handlers/format_auto_internal_test.go

@@ -101,8 +101,7 @@ func autoPhotoURLs(t *testing.T, h *Handlers) (string, string) {
 			Size:   imagerequest.Size{Width: 50, Height: 50},
 			Format: imagerequest.FormatAuto,
 		},
-		Expires: time.Now().Add(time.Minute),
-	})
+	}, time.Now().Add(time.Minute))
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}

internal/handlers/handlers.go

@@ -16,6 +16,7 @@ import (
 	"sneak.berlin/go/pixa/internal/imgcache"
 	"sneak.berlin/go/pixa/internal/logger"
 	"sneak.berlin/go/pixa/internal/session"
+	"sneak.berlin/go/pixa/internal/signature"
 )
 
 // Params defines dependencies for Handlers.
@@ -41,6 +42,11 @@ type Handlers struct {
 	encGen      *encurl.Generator
 	csrfProtect func(http.Handler) http.Handler
 
+	// signer checks the signature of a /v1/image/ URL with signing_key.
+	signer *signature.Signer
+	// allowlist matches the hosts of allowlist_hosts, which a /v1/image/
+	// URL may name without a signature.
+	allowlist *allowlist.HostAllowList
 	// refererBlocklist matches the hosts of referer_blocklist; its IsAllowed
 	// reports whether a URL's host is on that list.
 	refererBlocklist *allowlist.HostAllowList
@@ -61,6 +67,8 @@ func New(_ fx.Lifecycle, params Params) (*Handlers, error) {
 		sessMgr:          params.SessionManager,
 		encGen:           params.EncryptedURLGenerator,
 		csrfProtect:      csrfProtect,
+		signer:           signature.New(params.Config.SigningKey),
+		allowlist:        allowlist.New(params.Config.AllowlistHosts),
 		refererBlocklist: allowlist.New(params.Config.RefererBlocklist),
 	}, nil
 }

internal/handlers/handlers_internal_test.go

@@ -19,10 +19,13 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/prometheus/client_golang/prometheus"
+	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/database"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
+	"sneak.berlin/go/pixa/internal/imagerequest"
 	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
 )
 
 // testFixtures contains test data.
@@ -62,8 +65,6 @@ func setupTestHandler(t *testing.T) *testFixtures {
 			MaxInputBytes:           50 << 20,
 			MaxConcurrentProcessing: 2,
 		}),
-		SigningKey:      "test-signing-key-must-be-32-chars",
-		Allowlist:       []string{goodHost},
 		MaxResponseSize: 50 << 20,
 	})
 	if err != nil {
@@ -71,8 +72,10 @@ func setupTestHandler(t *testing.T) *testFixtures {
 	}
 
 	h := &Handlers{
-		imgSvc: svc,
-		log:    slog.Default(),
+		imgSvc:    svc,
+		log:       slog.Default(),
+		signer:    signature.New("test-signing-key-must-be-32-chars"),
+		allowlist: allowlist.New([]string{goodHost}),
 	}
 
 	return &testFixtures{
@@ -127,10 +130,9 @@ func newMockFetcher(fs fs.FS) *mockFetcher {
 }
 
 func (f *mockFetcher) Fetch(
-	_ context.Context, url string,
+	_ context.Context, source imagerequest.Source,
 ) (*httpfetcher.FetchResult, error) {
-	// Remove https:// prefix
-	path := url[8:] // Remove "https://"
+	path := source.Host + source.Path
 
 	data, err := fs.ReadFile(f.fs, path)
 	if err != nil {

internal/handlers/image.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"net/url"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/go-chi/chi/v5/middleware"
@@ -27,13 +28,13 @@ func (s *Handlers) HandleImage() http.HandlerFunc {
 			return
 		}
 
-		req, ok := s.parseImageRequest(w, r)
+		req, sig, expires, ok := s.parseImageRequest(w, r)
 		if !ok {
 			return
 		}
 
 		// Validate signature if required
-		err := s.imgSvc.ValidateRequest(req)
+		err := s.validateSignature(req, sig, expires)
 		if err != nil {
 			s.log.Warn("signature validation failed",
 				"host", req.Source.Host,
@@ -46,10 +47,13 @@ func (s *Handlers) HandleImage() http.HandlerFunc {
 		}
 
 		// The signature covers the format auto, not the format chosen
-		if !s.chooseAutoFormat(w, r, req) {
+		format, ok := s.chooseAutoFormat(w, r, req.Transform.Format)
+		if !ok {
 			return
 		}
 
+		req.Transform.Format = format
+
 		// Get cache key for logging
 		cacheKey := imagerequest.CacheKey(req)
 
@@ -65,7 +69,7 @@ func (s *Handlers) HandleImage() http.HandlerFunc {
 
 		defer func() { _ = resp.Content.Close() }()
 
-		s.writeImageResponse(w, r, req, resp, cacheKey, startTime)
+		s.writeImageResponse(w, r, req, expires, resp, cacheKey, startTime)
 	}
 }
 
@@ -82,11 +86,11 @@ func (s *Handlers) HandleRobotsTxt() http.HandlerFunc {
 }
 
 // parseImageRequest parses the image URL's path and query parameters into
-// an image request. On invalid input it writes an error response and
-// returns false.
+// an image request, and returns it with the URL's signature and expiry. On
+// invalid input it writes an error response and returns false.
 func (s *Handlers) parseImageRequest(
 	w http.ResponseWriter, r *http.Request,
-) (*imagerequest.Request, bool) {
+) (*imagerequest.Request, string, time.Time, bool) {
 	// The path is parsed decoded once, as r.URL.Path holds it, and not from
 	// chi's wildcard: chi routes on the path as the client wrote it whenever
 	// that is not Go's own encoding of it, so its wildcard would still hold
@@ -100,7 +104,7 @@ func (s *Handlers) parseImageRequest(
 		)
 		s.respondError(w, "invalid image URL: "+err.Error(), http.StatusBadRequest)
 
-		return nil, false
+		return nil, "", time.Time{}, false
 	}
 
 	// Parse signature params from query string. r.URL.Query() would silently
@@ -113,7 +117,7 @@ func (s *Handlers) parseImageRequest(
 		s.respondError(w, fmt.Sprintf("invalid query string %q: %v",
 			r.URL.RawQuery, err), http.StatusBadRequest)
 
-		return nil, false
+		return nil, "", time.Time{}, false
 	}
 
 	for name, values := range query {
@@ -121,17 +125,15 @@ func (s *Handlers) parseImageRequest(
 			s.respondError(w, fmt.Sprintf("invalid %s: given more than once",
 				name), http.StatusBadRequest)
 
-			return nil, false
+			return nil, "", time.Time{}, false
 		}
 	}
 
-	req.Signature = query.Get("sig")
-
-	req.Expires, err = parseExpires(query)
+	expires, err := parseExpires(query)
 	if err != nil {
 		s.respondError(w, err.Error(), http.StatusBadRequest)
 
-		return nil, false
+		return nil, "", time.Time{}, false
 	}
 
 	// Parse optional quality and fit params. Only a q missing from the URL is
@@ -143,7 +145,7 @@ func (s *Handlers) parseImageRequest(
 		s.respondError(w, `invalid q: not a number, got ""`,
 			http.StatusBadRequest)
 
-		return nil, false
+		return nil, "", time.Time{}, false
 	}
 
 	req.Transform.Quality, err = parseFormInt(query, "q",
@@ -152,7 +154,7 @@ func (s *Handlers) parseImageRequest(
 		s.respondError(w, fmt.Sprintf("%v, got %q", err, qStr),
 			http.StatusBadRequest)
 
-		return nil, false
+		return nil, "", time.Time{}, false
 	}
 
 	// Only a fit missing from the URL is cover. A fit in the URL that is not a
@@ -162,7 +164,7 @@ func (s *Handlers) parseImageRequest(
 	if query.Has("fit") && req.Transform.FitMode == "" {
 		s.respondError(w, `invalid fit: not a fit mode, got ""`, http.StatusBadRequest)
 
-		return nil, false
+		return nil, "", time.Time{}, false
 	}
 
 	// Default fit mode if not set
@@ -179,10 +181,35 @@ func (s *Handlers) parseImageRequest(
 		s.respondError(w, "invalid image request: "+err.Error(),
 			http.StatusBadRequest)
 
-		return nil, false
+		return nil, "", time.Time{}, false
 	}
 
-	return req, true
+	return req, query.Get("sig"), expires, true
+}
+
+// validateSignature returns nil when the source host of req is on
+// allowlist_hosts and names no port. Otherwise it verifies sig, the URL's
+// signature of req, and expires, the URL's expiry.
+func (s *Handlers) validateSignature(
+	req *imagerequest.Request, sig string, expires time.Time,
+) error {
+	// An allowlist entry names no port, so a host followed by ":", with or
+	// without a port, needs a signature. Go's URL type reads the port as the
+	// fetcher does: in an IPv6 address written without brackets, such as
+	// 2001:db8::1:8443, it is what follows the last ":". This is checked here
+	// and not in allowlist.IsAllowed, which also matches referer_blocklist,
+	// where a Referer must be blocked whatever its port. Port and IsAllowed
+	// read only the host of a URL.
+	sourceURL := &url.URL{Host: req.Source.Host}
+	hostHasPort := sourceURL.Port() != "" ||
+		strings.HasSuffix(sourceURL.Host, ":")
+
+	if !hostHasPort && s.allowlist.IsAllowed(sourceURL) {
+		return nil
+	}
+
+	// Signature required for non-allowed hosts
+	return s.signer.Verify(req, sig, expires)
 }
 
 // parseExpires reads the exp query parameter, a Unix time in seconds. An exp
@@ -341,10 +368,11 @@ func notModified(w http.ResponseWriter, r *http.Request, etag string) bool {
 }
 
 // writeImageResponse writes headers and streams the image content,
-// handling conditional and HEAD requests.
+// handling conditional and HEAD requests. expires is the URL's expiry, which
+// ends the Cache-Control max-age.
 func (s *Handlers) writeImageResponse(
 	w http.ResponseWriter, r *http.Request,
-	req *imagerequest.Request, resp *imgcache.ImageResponse,
+	req *imagerequest.Request, expires time.Time, resp *imgcache.ImageResponse,
 	cacheKey imagerequest.VariantKey, startTime time.Time,
 ) {
 	// Set response headers
@@ -355,7 +383,7 @@ func (s *Handlers) writeImageResponse(
 	}
 
 	// Cache control headers
-	w.Header().Set("Cache-Control", cacheControl(req.Expires))
+	w.Header().Set("Cache-Control", cacheControl(expires))
 	w.Header().Set("X-Pixa-Cache", string(resp.CacheStatus))
 
 	if notModified(w, r, resp.ETag) {

internal/handlers/image_cache_control_internal_test.go

@@ -14,10 +14,12 @@ import (
 	"github.com/go-chi/chi/v5"
 	"github.com/prometheus/client_golang/prometheus"
 
+	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
 )
 
 // photoPath is the path of the JPEG that newSignedHostServer serves.
@@ -52,7 +54,6 @@ func newSignedHostServer(
 			MaxInputBytes:           50 << 20,
 			MaxConcurrentProcessing: 2,
 		}),
-		SigningKey:      testSigningKey,
 		MaxResponseSize: 50 << 20,
 		Logger:          log,
 	})
@@ -66,9 +67,11 @@ func newSignedHostServer(
 	}
 
 	h := &Handlers{
-		log:    log,
-		imgSvc: svc,
-		encGen: encGen,
+		log:       log,
+		imgSvc:    svc,
+		encGen:    encGen,
+		signer:    signature.New(testSigningKey),
+		allowlist: allowlist.New(nil),
 	}
 
 	r := chi.NewRouter()
@@ -202,8 +205,7 @@ func TestHandleImageEnc_MaxAge(t *testing.T) {
 					Size:   imagerequest.Size{Width: 50, Height: 50},
 					Format: imagerequest.FormatJPEG,
 				},
-				Expires: tt.expires,
-			})
+			}, tt.expires)
 			if err != nil {
 				t.Fatalf("Generate() error = %v", err)
 			}

internal/handlers/image_errors_internal_test.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/prometheus/client_golang/prometheus"
+	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
 	"sneak.berlin/go/pixa/internal/imagerequest"
@@ -26,7 +27,7 @@ import (
 const allowlistedHost = "allowed.example.com"
 
 // newImageRoute returns the image route of a Handlers whose service fetches
-// with fetcher and checks signatures with testSigningKey.
+// with fetcher, and which checks signatures with testSigningKey.
 func newImageRoute(t *testing.T, fetcher httpfetcher.Fetcher) http.Handler {
 	t.Helper()
 
@@ -46,15 +47,18 @@ func newImageRoute(t *testing.T, fetcher httpfetcher.Fetcher) http.Handler {
 			MaxInputBytes:           50 << 20,
 			MaxConcurrentProcessing: 2,
 		}),
-		SigningKey:      testSigningKey,
-		Allowlist:       []string{allowlistedHost},
 		MaxResponseSize: 50 << 20,
 	})
 	if err != nil {
 		t.Fatalf("failed to create service: %v", err)
 	}
 
-	h := &Handlers{imgSvc: svc, log: slog.New(slog.DiscardHandler)}
+	h := &Handlers{
+		imgSvc:    svc,
+		log:       slog.New(slog.DiscardHandler),
+		signer:    signature.New(testSigningKey),
+		allowlist: allowlist.New([]string{allowlistedHost}),
+	}
 
 	r := chi.NewRouter()
 	r.Get("/v1/image/*", h.HandleImage())
@@ -90,10 +94,10 @@ func photoURLWithSig(host, sig string, expires time.Time) string {
 	return fmt.Sprintf("%s?sig=%s&exp=%d", photoURL(host), sig, expires.Unix())
 }
 
-// photoSignature returns the signature of photoURL(host) at the default
-// quality and fit, made with key and expiring at expires.
-func photoSignature(key, host string, expires time.Time) string {
-	return signature.New(key).Sign(&imagerequest.Request{
+// photoRequest returns the image request of photoURL(host) at the default
+// quality and fit.
+func photoRequest(host string) *imagerequest.Request {
+	return &imagerequest.Request{
 		Source: imagerequest.Source{
 			Host: host,
 			Path: photoPath,
@@ -104,8 +108,13 @@ func photoSignature(key, host string, expires time.Time) string {
 			Quality: 85,
 			FitMode: imagerequest.FitCover,
 		},
-		Expires: expires,
-	})
+	}
+}
+
+// photoSignature returns the signature of photoURL(host) at the default
+// quality and fit, made with key and expiring at expires.
+func photoSignature(key, host string, expires time.Time) string {
+	return signature.New(key).Sign(photoRequest(host), expires)
 }
 
 // sendGet sends a GET for target to route and returns the response.
@@ -381,8 +390,7 @@ func TestHandleImage_HashInSourcePathOrQuery_Returns400(t *testing.T) {
 			Quality: 85,
 			FitMode: imagerequest.FitCover,
 		},
-		Expires: exp,
-	})
+	}, exp)
 
 	tests := []struct {
 		name   string

internal/handlers/image_signature_internal_test.go

@@ -38,40 +38,44 @@ func getImage(t *testing.T, fix *testFixtures, target string) int {
 }
 
 // generateSignedURL returns the /v1/image/ URL of req, signed with key and
-// expiring after ttl, and sets req's expiry. An unset quality or fit of req is
-// first set to 85 or cover, the values the route uses when a URL has no q or
-// fit. The URL carries q and fit next to sig and exp, so the route verifies it
-// for the quality and fit it was signed with.
+// expiring after ttl. It signs a copy of req, so req itself is not changed.
+// An unset quality or fit in the copy is set to 85 or cover, the values the
+// route uses when a URL has no q or fit. The URL carries q and fit next to sig
+// and exp, so the route verifies it for the quality and fit it was signed
+// with.
 func generateSignedURL(
 	key string, req *imagerequest.Request, ttl time.Duration,
 ) string {
-	if req.Transform.Quality == 0 {
-		req.Transform.Quality = 85
+	signed := *req
+
+	if signed.Transform.Quality == 0 {
+		signed.Transform.Quality = 85
 	}
 
-	if req.Transform.FitMode == "" {
-		req.Transform.FitMode = imagerequest.FitCover
+	if signed.Transform.FitMode == "" {
+		signed.Transform.FitMode = imagerequest.FitCover
 	}
 
-	req.Expires = time.Now().Add(ttl)
-	sig := signature.New(key).Sign(req)
+	expires := time.Now().Add(ttl)
+	sig := signature.New(key).Sign(&signed, expires)
 
 	// A source query follows the source path after a "?". The image route
 	// reads the path decoded once, so the whole path is written in Go's own
 	// percent-encoding of a URL path, which writes "?" as %3F and "%" as %25,
 	// and leaves "/", ";", ",", "=" and "&" as they are.
-	sourcePathAndQuery := req.Source.Path
-	if req.Source.Query != "" {
-		sourcePathAndQuery += "?" + req.Source.Query
+	sourcePathAndQuery := signed.Source.Path
+	if signed.Source.Query != "" {
+		sourcePathAndQuery += "?" + signed.Source.Query
 	}
 
 	unescapedPath := fmt.Sprintf("/v1/image/%s%s/%dx%d.%s",
-		req.Source.Host, sourcePathAndQuery,
-		req.Transform.Size.Width, req.Transform.Size.Height, req.Transform.Format)
+		signed.Source.Host, sourcePathAndQuery,
+		signed.Transform.Size.Width, signed.Transform.Size.Height,
+		signed.Transform.Format)
 
 	return fmt.Sprintf("%s?sig=%s&exp=%d&q=%d&fit=%s",
-		(&url.URL{Path: unescapedPath}).EscapedPath(), sig, req.Expires.Unix(),
-		req.Transform.Quality, req.Transform.FitMode)
+		(&url.URL{Path: unescapedPath}).EscapedPath(), sig, expires.Unix(),
+		signed.Transform.Quality, signed.Transform.FitMode)
 }
 
 // TestHandleImage_SignatureCoversQualityAndFit signs a URL for quality 85
@@ -93,8 +97,7 @@ func TestHandleImage_SignatureCoversQualityAndFit(t *testing.T) {
 			Quality: 85,
 			FitMode: imagerequest.FitCover,
 		},
-		Expires: expires,
-	})
+	}, expires)
 	signedURL := fmt.Sprintf("/v1/image/%s/images/photo.jpg/50x50.jpeg?sig=%s&exp=%d",
 		signedHost, sig, expires.Unix())
 
@@ -277,8 +280,7 @@ func TestHandleImage_SourceQueryEncodedAnyWay(t *testing.T) {
 			Quality: 85,
 			FitMode: imagerequest.FitCover,
 		},
-		Expires: expires,
-	})
+	}, expires)
 
 	tests := []struct {
 		name         string
@@ -344,8 +346,7 @@ func TestHandleImage_SourceURLHoldingPercent25Verifies(t *testing.T) {
 					Quality: 85,
 					FitMode: imagerequest.FitCover,
 				},
-				Expires: expires,
-			})
+			}, expires)
 
 			target := fmt.Sprintf("/v1/image/%s%s/50x50.jpeg?sig=%s&exp=%d",
 				signedHost, tt.writtenPathAndQuery, sig, expires.Unix())

internal/handlers/imageenc.go

@@ -31,11 +31,18 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 		ctx := r.Context()
 		start := time.Now()
 
-		req, ok := s.parseImageEncRequest(w, r)
-		if !ok || !s.chooseAutoFormat(w, r, req) {
+		req, expires, ok := s.parseImageEncRequest(w, r)
+		if !ok {
 			return
 		}
 
+		format, ok := s.chooseAutoFormat(w, r, req.Transform.Format)
+		if !ok {
+			return
+		}
+
+		req.Transform.Format = format
+
 		// Log the request
 		s.log.Debug("encrypted image request",
 			"host", req.Source.Host,
@@ -64,7 +71,7 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 		}
 
 		// Cache headers: max-age ends at the URL's expiry
-		w.Header().Set("Cache-Control", cacheControl(req.Expires))
+		w.Header().Set("Cache-Control", cacheControl(expires))
 		w.Header().Set("X-Pixa-Cache", string(resp.CacheStatus))
 
 		if notModified(w, r, resp.ETag) {
@@ -102,34 +109,34 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 }
 
 // parseImageEncRequest decrypts the token of an encrypted image URL into an
-// image request and checks it. On a token that is missing, does not decrypt,
-// has expired or asks for something not valid, it writes an error response
-// and returns false.
+// image request and checks it, and returns it with the token's expiry. On a
+// token that is missing, does not decrypt, has expired or asks for something
+// not valid, it writes an error response and returns false.
 func (s *Handlers) parseImageEncRequest(
 	w http.ResponseWriter, r *http.Request,
-) (*imagerequest.Request, bool) {
+) (*imagerequest.Request, time.Time, bool) {
 	// Extract token from URL
 	token := chi.URLParam(r, "token")
 	if token == "" {
 		s.respondError(w, "missing token", http.StatusBadRequest)
 
-		return nil, false
+		return nil, time.Time{}, false
 	}
 
 	// Decrypt and validate the payload
-	req, err := s.encGen.Parse(token)
+	req, expires, err := s.encGen.Parse(token)
 	if err != nil {
 		if errors.Is(err, encurl.ErrExpired) {
 			s.log.Debug("encrypted URL expired", "error", err)
 			s.respondError(w, "URL has expired", http.StatusGone)
 
-			return nil, false
+			return nil, time.Time{}, false
 		}
 
 		s.log.Debug("failed to decrypt URL", "error", err)
 		s.respondError(w, "invalid encrypted URL", http.StatusBadRequest)
 
-		return nil, false
+		return nil, time.Time{}, false
 	}
 
 	// Apply the same dimension and fit-mode bounds as the plain image
@@ -142,10 +149,10 @@ func (s *Handlers) parseImageEncRequest(
 		s.respondError(w, "invalid encrypted URL: "+err.Error(),
 			http.StatusBadRequest)
 
-		return nil, false
+		return nil, time.Time{}, false
 	}
 
-	return req, true
+	return req, expires, true
 }
 
 // handleImageError converts image service errors to HTTP responses.

internal/handlers/imageenc_internal_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"testing"
+	"time"
 
 	"github.com/go-chi/chi/v5"
 
@@ -62,7 +63,7 @@ func TestHandleImageEnc_OverLimitDimension_Returns400(t *testing.T) {
 		Transform: imagerequest.Transform{
 			Size: imagerequest.Size{Width: 100000, Height: 100000},
 		},
-	})
+	}, time.Time{})
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}
@@ -91,7 +92,7 @@ func TestHandleImageEnc_InvalidFitMode_Returns400(t *testing.T) {
 			Size:    imagerequest.Size{Width: 800, Height: 600},
 			FitMode: imagerequest.Fit("bogus"),
 		},
-	})
+	}, time.Time{})
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}

internal/handlers/imageenc_token_internal_test.go

@@ -70,15 +70,12 @@ func TestHandleImageEnc_RejectedToken(t *testing.T) {
 		},
 	}
 
-	valid, err := h.encGen.Generate(&photo)
+	valid, err := h.encGen.Generate(&photo, time.Time{})
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}
 
-	expiredPhoto := photo
-	expiredPhoto.Expires = time.Now().Add(-time.Minute)
-
-	expired, err := h.encGen.Generate(&expiredPhoto)
+	expired, err := h.encGen.Generate(&photo, time.Now().Add(-time.Minute))
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}
@@ -88,7 +85,7 @@ func TestHandleImageEnc_RejectedToken(t *testing.T) {
 		t.Fatalf("encurl.NewGenerator() error = %v", err)
 	}
 
-	otherKey, err := otherGen.Generate(&photo)
+	otherKey, err := otherGen.Generate(&photo, time.Time{})
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}

internal/handlers/jpegxl_default_internal_test.go

@@ -69,8 +69,7 @@ func TestImageWithoutFormat_SignedAsJXL(t *testing.T) {
 			Quality: encurl.DefaultQuality,
 			FitMode: imagerequest.FitCover,
 		},
-		Expires: expires,
-	})
+	}, expires)
 	query := fmt.Sprintf("?sig=%s&exp=%d", sig, expires.Unix())
 
 	for _, size := range []string{"50x50.jxl", "50x50"} {
@@ -94,7 +93,7 @@ func TestImageEncWithoutFormat_ServesJPEGXL(t *testing.T) {
 		Transform: imagerequest.Transform{
 			Size: imagerequest.Size{Width: 50, Height: 50},
 		},
-	})
+	}, time.Time{})
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}

internal/handlers/referer_blocklist_internal_test.go

@@ -15,7 +15,9 @@ import (
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
+	"sneak.berlin/go/pixa/internal/imagerequest"
 	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
 )
 
 // blockedReferer is a page on leech.example, which newRefererRoutes puts on
@@ -31,11 +33,11 @@ type countingFetcher struct {
 
 // Fetch counts the fetch and passes it on.
 func (f *countingFetcher) Fetch(
-	ctx context.Context, url string,
+	ctx context.Context, source imagerequest.Source,
 ) (*httpfetcher.FetchResult, error) {
 	f.fetches.Add(1)
 
-	return f.Fetcher.Fetch(ctx, url)
+	return f.Fetcher.Fetch(ctx, source)
 }
 
 // newRefererRoutes returns both image routes of a Handlers whose
@@ -65,8 +67,6 @@ func newRefererRoutes(t *testing.T) (http.Handler, *Handlers, *countingFetcher)
 			MaxInputBytes:           50 << 20,
 			MaxConcurrentProcessing: 2,
 		}),
-		SigningKey:      testSigningKey,
-		Allowlist:       []string{allowlistedHost},
 		MaxResponseSize: 50 << 20,
 	})
 	if err != nil {
@@ -79,9 +79,11 @@ func newRefererRoutes(t *testing.T) (http.Handler, *Handlers, *countingFetcher)
 	}
 
 	h := &Handlers{
-		log:    slog.New(slog.DiscardHandler),
-		imgSvc: svc,
-		encGen: encGen,
+		log:       slog.New(slog.DiscardHandler),
+		imgSvc:    svc,
+		encGen:    encGen,
+		signer:    signature.New(testSigningKey),
+		allowlist: allowlist.New([]string{allowlistedHost}),
 		refererBlocklist: allowlist.New(
 			[]string{"leech.example", ".hotlinker.example"}),
 	}

internal/handlers/request_id_internal_test.go

@@ -49,7 +49,7 @@ func encPhotoURL(t *testing.T, h *Handlers) string {
 			Size:   imagerequest.Size{Width: 50, Height: 50},
 			Format: imagerequest.FormatJPEG,
 		},
-	})
+	}, time.Time{})
 	if err != nil {
 		t.Fatalf("Generate() error = %v", err)
 	}

internal/handlers/validate_signature_internal_test.go

@@ -0,0 +1,211 @@
+package handlers
+
+import (
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/allowlist"
+	"sneak.berlin/go/pixa/internal/signature"
+)
+
+// Addresses the port tests below put on the allowlist.
+const (
+	allowlistedIPv4 = "203.0.113.5"
+	allowlistedIPv6 = "2001:db8::1"
+)
+
+// newSignatureChecker returns Handlers that check signatures with
+// testSigningKey and have allowlistHosts on their allowlist, as New builds
+// them from signing_key and allowlist_hosts.
+func newSignatureChecker(allowlistHosts ...string) *Handlers {
+	return &Handlers{
+		signer:    signature.New(testSigningKey),
+		allowlist: allowlist.New(allowlistHosts),
+	}
+}
+
+func TestValidateSignature_NonAllowlistedHost_NoSignature(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker(allowlistedHost)
+
+	// Should fail validation - not allowlisted and no signature
+	err := h.validateSignature(photoRequest(signedHost), "", time.Time{})
+	if err == nil {
+		t.Error("validateSignature() expected error for non-allowlisted " +
+			"host without signature")
+	}
+}
+
+func TestValidateSignature_NonAllowlistedHost_ValidSignature(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker(allowlistedHost)
+	req := photoRequest(signedHost)
+
+	// Generate a valid signature
+	expires := time.Now().Add(time.Hour)
+	sig := signature.New(testSigningKey).Sign(req, expires)
+
+	// Should pass validation
+	err := h.validateSignature(req, sig, expires)
+	if err != nil {
+		t.Errorf("validateSignature() error = %v", err)
+	}
+}
+
+func TestValidateSignature_NonAllowlistedHost_ExpiredSignature(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker(allowlistedHost)
+	req := photoRequest(signedHost)
+
+	// Generate an expired signature
+	expires := time.Now().Add(-time.Hour)
+	sig := signature.New(testSigningKey).Sign(req, expires)
+
+	// Should fail validation
+	err := h.validateSignature(req, sig, expires)
+	if err == nil {
+		t.Error("validateSignature() expected error for expired signature")
+	}
+}
+
+func TestValidateSignature_NonAllowlistedHost_InvalidSignature(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker(allowlistedHost)
+
+	// Should fail validation
+	err := h.validateSignature(photoRequest(signedHost), "invalid-signature",
+		time.Now().Add(time.Hour))
+	if err == nil {
+		t.Error("validateSignature() expected error for invalid signature")
+	}
+}
+
+// TestValidateSignature_NoAllowlist checks that with no host on the
+// allowlist, a request without a signature fails validation.
+func TestValidateSignature_NoAllowlist(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker()
+
+	err := h.validateSignature(photoRequest(signedHost), "", time.Time{})
+	if err == nil {
+		t.Error("validateSignature() expected error when no host is allowlisted")
+	}
+}
+
+// TestValidateSignature_SignatureExactHostMatch verifies that
+// validateSignature enforces exact host matching for signatures. A
+// signature for one host must not verify for a different host, even
+// if they share a domain suffix.
+func TestValidateSignature_SignatureExactHostMatch(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker()
+
+	// Sign a request for signedHost
+	signedReq := photoRequest(signedHost)
+	expires := time.Now().Add(time.Hour)
+	sig := signature.New(testSigningKey).Sign(signedReq, expires)
+
+	// The original request should pass validation
+	t.Run("exact host passes", func(t *testing.T) {
+		t.Parallel()
+
+		err := h.validateSignature(signedReq, sig, expires)
+		if err != nil {
+			t.Errorf("validateSignature() exact host failed: %v", err)
+		}
+	})
+
+	// Try to reuse the signature with different hosts
+	tests := []struct {
+		name string
+		host string
+	}{
+		{"parent domain", "example.com"},
+		{"sibling subdomain", "images.example.com"},
+		{"deeper subdomain", "a." + signedHost},
+		{"evil suffix domain", signedHost + ".evil.com"},
+		{"prefixed host", "evil" + signedHost},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name+" rejected", func(t *testing.T) {
+			t.Parallel()
+
+			err := h.validateSignature(photoRequest(tt.host), sig, expires)
+			if err == nil {
+				t.Errorf("validateSignature() should reject signature for "+
+					"host %q (signed for %q)", tt.host, signedHost)
+			}
+		})
+	}
+}
+
+// TestValidateSignature_HostWithPortNeedsSignature verifies that a host
+// followed by a port, or by a colon with no port, matches no allowlist entry,
+// so that a request for it without a signature is refused, while the same
+// host with no port is allowlisted.
+func TestValidateSignature_HostWithPortNeedsSignature(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker(allowlistedHost, allowlistedIPv4, allowlistedIPv6)
+
+	tests := []struct {
+		host        string
+		allowlisted bool
+	}{
+		{allowlistedHost, true},
+		{allowlistedHost + ":8443", false},
+		{allowlistedHost + ":443", false},
+		{allowlistedHost + ":", false},
+		{allowlistedIPv4, true},
+		{allowlistedIPv4 + ":8080", false},
+		{"[" + allowlistedIPv6 + "]", true},
+		{"[" + allowlistedIPv6 + "]:8443", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.host, func(t *testing.T) {
+			t.Parallel()
+
+			err := h.validateSignature(photoRequest(tt.host), "", time.Time{})
+			t.Logf("validateSignature() for host %q with no signature: %v",
+				tt.host, err)
+
+			if allowlisted := err == nil; allowlisted != tt.allowlisted {
+				t.Errorf("host %q served without a signature = %v, want %v",
+					tt.host, allowlisted, tt.allowlisted)
+			}
+		})
+	}
+}
+
+// TestValidateSignature_UnbracketedIPv6PortNeedsSignature verifies that an
+// allowlisted IPv6 address written without brackets and followed by a port,
+// or by a colon with no port, needs a signature. Go's URL type reads
+// 2001:db8::1:8443 as the host 2001:db8::1 with the port 8443.
+func TestValidateSignature_UnbracketedIPv6PortNeedsSignature(t *testing.T) {
+	t.Parallel()
+
+	h := newSignatureChecker(allowlistedIPv6)
+
+	for _, host := range []string{allowlistedIPv6 + ":8443", allowlistedIPv6 + ":"} {
+		t.Run(host, func(t *testing.T) {
+			t.Parallel()
+
+			err := h.validateSignature(photoRequest(host), "", time.Time{})
+			t.Logf("validateSignature() for host %q with no signature: %v",
+				host, err)
+
+			if err == nil {
+				t.Errorf("host %q served without a signature, want refused",
+					host)
+			}
+		})
+	}
+}