refactor: extract signature package from imgcache

Move HMAC-SHA256 request signing out of internal/imgcache/ into its own
internal/signature/ package, per the plan in issue #39. This is one of the
remaining "easily separable" extractions; only the signer is moved here so
the diff stays reviewable.

What moved (from internal/imgcache/signature.go):

- Signer type, its New constructor, Sign, Verify, GenerateSignedURL
- ParseParams (query-string signature/expiration parsing)
- Signature error sentinels

To keep the import edge one-way (imgcache depends on signature, never the
reverse), the package defines a standalone Request type carrying just the
fields the signature covers, instead of importing imgcache.ImageRequest.
imgcache projects its ImageRequest onto signature.Request via a small
unexported helper.

Renames (no stuttering):

- NewSigner -> signature.New
- ParseSignatureParams -> signature.ParseParams
- ErrSignatureRequired/Invalid/Expired -> signature.ErrRequired/Invalid/Expired

The "non-whitelisted host" error message is updated to "non-allowlisted"
for inclusive terminology, consistent with the allowlist rename.

Pure refactor. The bytes fed to the HMAC are unchanged, so signatures remain
compatible. All existing tests move with the package; docker build passes
(fmt-check, lint, test, build).

refs #39

internal/signature/signature.go

@@ -0,0 +1,173 @@
+// Package signature provides HMAC-SHA256 signing and verification of image
+// requests.
+package signature
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net/url"
+	"strconv"
+	"time"
+)
+
+// Signature errors.
+var (
+	ErrRequired          = errors.New("signature required for non-allowlisted host")
+	ErrInvalid           = errors.New("invalid signature")
+	ErrExpired           = errors.New("signature has expired")
+	ErrMissingExpiration = errors.New("signature expiration is required")
+)
+
+// Request carries the components an image request signature covers. It is a
+// standalone type so that this package does not depend on imgcache, keeping
+// the import edge one-way (imgcache depends on signature, never the reverse).
+type Request struct {
+	// SourceHost is the origin host (e.g. "cdn.example.com").
+	SourceHost string
+	// SourcePath is the path on the origin (e.g. "/photos/cat.jpg").
+	SourcePath string
+	// SourceQuery is the optional query string for the origin URL.
+	SourceQuery string
+	// Width is the requested output width in pixels.
+	Width int
+	// Height is the requested output height in pixels.
+	Height int
+	// Format is the requested output format (e.g. "webp").
+	Format string
+	// Signature is the HMAC signature to verify.
+	Signature string
+	// Expires is the signature expiration timestamp.
+	Expires time.Time
+}
+
+// Signer handles HMAC-SHA256 signature generation and verification.
+type Signer struct {
+	secretKey []byte
+}
+
+// New creates a new Signer with the given secret key.
+func New(secretKey string) *Signer {
+	return &Signer{
+		secretKey: []byte(secretKey),
+	}
+}
+
+// Sign generates an HMAC-SHA256 signature for the given request.
+// The signature covers: host + path + query + width + height + format + expiration.
+func (s *Signer) Sign(req *Request) string {
+	data := s.buildSignatureData(req)
+	mac := hmac.New(sha256.New, s.secretKey)
+	mac.Write([]byte(data))
+	sig := mac.Sum(nil)
+
+	return base64.URLEncoding.EncodeToString(sig)
+}
+
+// Verify checks if the signature on the request is valid and not expired.
+// Signatures are exact-match only: every component of the signed data
+// (host, path, query, dimensions, format, expiration) must match exactly.
+// No suffix matching, wildcard matching, or partial matching is supported.
+// A signature for "cdn.example.com" will NOT verify for "example.com" or
+// "other.cdn.example.com", and vice versa.
+func (s *Signer) Verify(req *Request) error {
+	// Check expiration first
+	if req.Expires.IsZero() {
+		return ErrMissingExpiration
+	}
+
+	if time.Now().After(req.Expires) {
+		return ErrExpired
+	}
+
+	// Compute expected signature
+	expected := s.Sign(req)
+
+	// Constant-time comparison to prevent timing attacks
+	if !hmac.Equal([]byte(req.Signature), []byte(expected)) {
+		return ErrInvalid
+	}
+
+	return nil
+}
+
+// buildSignatureData creates the string to be signed.
+// Format: "host:path:query:width:height:format:expiration"
+// All components are used verbatim (exact match). No normalization,
+// suffix matching, or wildcard expansion is performed.
+func (s *Signer) buildSignatureData(req *Request) string {
+	return fmt.Sprintf("%s:%s:%s:%d:%d:%s:%d",
+		req.SourceHost,
+		req.SourcePath,
+		req.SourceQuery,
+		req.Width,
+		req.Height,
+		req.Format,
+		req.Expires.Unix(),
+	)
+}
+
+// GenerateSignedURL creates a complete URL with signature and expiration.
+// Returns the path portion that should be appended to the base URL.
+func (s *Signer) GenerateSignedURL(req *Request, ttl time.Duration) (path string, sig string, exp int64) {
+	// Set expiration
+	req.Expires = time.Now().Add(ttl)
+	exp = req.Expires.Unix()
+
+	// Generate signature
+	sig = s.Sign(req)
+	req.Signature = sig
+
+	// Build the size component
+	var sizeStr string
+	if req.Width == 0 && req.Height == 0 {
+		sizeStr = "orig"
+	} else {
+		sizeStr = fmt.Sprintf("%dx%d", req.Width, req.Height)
+	}
+
+	// Build the path.
+	// When a source query is present, it is embedded as a path segment
+	// (e.g. /host/path?query/size.fmt) so that the URL parser can extract
+	// it from the last-slash split. The "?" inside a path segment is
+	// percent-encoded by clients but chi delivers it decoded, which is
+	// exactly what the URL parser expects.
+	if req.SourceQuery != "" {
+		path = fmt.Sprintf("/v1/image/%s%s%%3F%s/%s.%s",
+			req.SourceHost,
+			req.SourcePath,
+			url.PathEscape(req.SourceQuery),
+			sizeStr,
+			req.Format,
+		)
+	} else {
+		path = fmt.Sprintf("/v1/image/%s%s/%s.%s",
+			req.SourceHost,
+			req.SourcePath,
+			sizeStr,
+			req.Format,
+		)
+	}
+
+	return path, sig, exp
+}
+
+// ParseParams extracts signature and expiration from query parameters.
+func ParseParams(sig, expStr string) (parsed string, expires time.Time, err error) {
+	parsed = sig
+
+	if expStr == "" {
+		return parsed, time.Time{}, nil
+	}
+
+	expUnix, err := strconv.ParseInt(expStr, 10, 64)
+	if err != nil {
+		return "", time.Time{}, fmt.Errorf("invalid expiration: %w", err)
+	}
+
+	expires = time.Unix(expUnix, 0)
+
+	return parsed, expires, nil
+}

internal/signature/signature_test.go

@@ -0,0 +1,530 @@
+package signature
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestSigner_Sign(t *testing.T) {
+	signer := New("test-secret-key")
+
+	req := &Request{
+		SourceHost:  "cdn.example.com",
+		SourcePath:  "/photos/cat.jpg",
+		SourceQuery: "",
+		Width:       800,
+		Height:      600,
+		Format:      "webp",
+		Expires:     time.Unix(1704067200, 0), // Fixed timestamp for reproducibility
+	}
+
+	sig1 := signer.Sign(req)
+	sig2 := signer.Sign(req)
+
+	// Same input should produce same signature
+	if sig1 != sig2 {
+		t.Errorf("Sign() produced different signatures for same input: %q vs %q", sig1, sig2)
+	}
+
+	// Signature should be non-empty
+	if sig1 == "" {
+		t.Error("Sign() produced empty signature")
+	}
+
+	// Different input should produce different signature
+	req2 := &Request{
+		SourceHost:  "cdn.example.com",
+		SourcePath:  "/photos/dog.jpg", // Different path
+		SourceQuery: "",
+		Width:       800,
+		Height:      600,
+		Format:      "webp",
+		Expires:     time.Unix(1704067200, 0),
+	}
+
+	sig3 := signer.Sign(req2)
+	if sig1 == sig3 {
+		t.Error("Sign() produced same signature for different input")
+	}
+}
+
+func TestSigner_Verify(t *testing.T) {
+	signer := New("test-secret-key")
+
+	tests := []struct {
+		name    string
+		setup   func() *Request
+		wantErr error
+	}{
+		{
+			name: "valid signature",
+			setup: func() *Request {
+				req := &Request{
+					SourceHost: "cdn.example.com",
+					SourcePath: "/photos/cat.jpg",
+					Width:      800,
+					Height:     600,
+					Format:     "webp",
+					Expires:    time.Now().Add(1 * time.Hour),
+				}
+				req.Signature = signer.Sign(req)
+
+				return req
+			},
+			wantErr: nil,
+		},
+		{
+			name: "expired signature",
+			setup: func() *Request {
+				req := &Request{
+					SourceHost: "cdn.example.com",
+					SourcePath: "/photos/cat.jpg",
+					Width:      800,
+					Height:     600,
+					Format:     "webp",
+					Expires:    time.Now().Add(-1 * time.Hour), // Expired
+				}
+				req.Signature = signer.Sign(req)
+
+				return req
+			},
+			wantErr: ErrExpired,
+		},
+		{
+			name: "invalid signature",
+			setup: func() *Request {
+				return &Request{
+					SourceHost: "cdn.example.com",
+					SourcePath: "/photos/cat.jpg",
+					Width:      800,
+					Height:     600,
+					Format:     "webp",
+					Expires:    time.Now().Add(1 * time.Hour),
+					Signature:  "invalid-signature",
+				}
+			},
+			wantErr: ErrInvalid,
+		},
+		{
+			name: "missing expiration",
+			setup: func() *Request {
+				return &Request{
+					SourceHost: "cdn.example.com",
+					SourcePath: "/photos/cat.jpg",
+					Width:      800,
+					Height:     600,
+					Format:     "webp",
+					Signature:  "some-signature",
+					// Expires is zero
+				}
+			},
+			wantErr: ErrMissingExpiration,
+		},
+		{
+			name: "tampered request",
+			setup: func() *Request {
+				req := &Request{
+					SourceHost: "cdn.example.com",
+					SourcePath: "/photos/cat.jpg",
+					Width:      800,
+					Height:     600,
+					Format:     "webp",
+					Expires:    time.Now().Add(1 * time.Hour),
+				}
+				req.Signature = signer.Sign(req)
+				// Tamper with the request
+				req.SourcePath = "/photos/secret.jpg"
+
+				return req
+			},
+			wantErr: ErrInvalid,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := tt.setup()
+			err := signer.Verify(req)
+
+			if tt.wantErr == nil {
+				if err != nil {
+					t.Errorf("Verify() unexpected error = %v", err)
+				}
+			} else {
+				if err != tt.wantErr {
+					t.Errorf("Verify() error = %v, wantErr %v", err, tt.wantErr)
+				}
+			}
+		})
+	}
+}
+
+// TestSigner_Verify_ExactMatchOnly verifies that signatures enforce exact
+// matching on every URL component. No suffix matching, wildcard matching,
+// or partial matching is supported.
+func TestSigner_Verify_ExactMatchOnly(t *testing.T) {
+	signer := New("test-secret-key")
+
+	// Base request that we'll sign, then tamper with individual fields.
+	baseReq := func() *Request {
+		req := &Request{
+			SourceHost:  "cdn.example.com",
+			SourcePath:  "/photos/cat.jpg",
+			SourceQuery: "token=abc",
+			Width:       800,
+			Height:      600,
+			Format:      "webp",
+			Expires:     time.Now().Add(1 * time.Hour),
+		}
+		req.Signature = signer.Sign(req)
+
+		return req
+	}
+
+	tests := []struct {
+		name   string
+		tamper func(req *Request)
+	}{
+		{
+			name: "parent domain does not match subdomain",
+			tamper: func(req *Request) {
+				// Signed for cdn.example.com, try example.com
+				req.SourceHost = "example.com"
+			},
+		},
+		{
+			name: "subdomain does not match parent domain",
+			tamper: func(req *Request) {
+				// Signed for cdn.example.com, try images.cdn.example.com
+				req.SourceHost = "images.cdn.example.com"
+			},
+		},
+		{
+			name: "sibling subdomain does not match",
+			tamper: func(req *Request) {
+				// Signed for cdn.example.com, try images.example.com
+				req.SourceHost = "images.example.com"
+			},
+		},
+		{
+			name: "host with suffix appended does not match",
+			tamper: func(req *Request) {
+				// Signed for cdn.example.com, try cdn.example.com.evil.com
+				req.SourceHost = "cdn.example.com.evil.com"
+			},
+		},
+		{
+			name: "host with prefix does not match",
+			tamper: func(req *Request) {
+				// Signed for cdn.example.com, try evilcdn.example.com
+				req.SourceHost = "evilcdn.example.com"
+			},
+		},
+		{
+			name: "different path does not match",
+			tamper: func(req *Request) {
+				req.SourcePath = "/photos/dog.jpg"
+			},
+		},
+		{
+			name: "path suffix does not match",
+			tamper: func(req *Request) {
+				req.SourcePath = "/photos/cat.jpg/extra"
+			},
+		},
+		{
+			name: "path prefix does not match",
+			tamper: func(req *Request) {
+				req.SourcePath = "/other/photos/cat.jpg"
+			},
+		},
+		{
+			name: "different query does not match",
+			tamper: func(req *Request) {
+				req.SourceQuery = "token=xyz"
+			},
+		},
+		{
+			name: "added query does not match empty query",
+			tamper: func(req *Request) {
+				req.SourceQuery = "extra=1"
+			},
+		},
+		{
+			name: "removed query does not match",
+			tamper: func(req *Request) {
+				req.SourceQuery = ""
+			},
+		},
+		{
+			name: "different width does not match",
+			tamper: func(req *Request) {
+				req.Width = 801
+			},
+		},
+		{
+			name: "different height does not match",
+			tamper: func(req *Request) {
+				req.Height = 601
+			},
+		},
+		{
+			name: "different format does not match",
+			tamper: func(req *Request) {
+				req.Format = "png"
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := baseReq()
+			tt.tamper(req)
+
+			err := signer.Verify(req)
+			if err != ErrInvalid {
+				t.Errorf("Verify() = %v, want %v", err, ErrInvalid)
+			}
+		})
+	}
+
+	// Verify the unmodified base request still passes
+	t.Run("unmodified request passes", func(t *testing.T) {
+		req := baseReq()
+		if err := signer.Verify(req); err != nil {
+			t.Errorf("Verify() unmodified request failed: %v", err)
+		}
+	})
+}
+
+// TestSigner_Sign_ExactHostInData verifies that Sign uses the exact host
+// string in the signature data, producing different signatures for
+// suffix-related hosts.
+func TestSigner_Sign_ExactHostInData(t *testing.T) {
+	signer := New("test-secret-key")
+
+	hosts := []string{
+		"cdn.example.com",
+		"example.com",
+		"images.example.com",
+		"images.cdn.example.com",
+		"cdn.example.com.evil.com",
+	}
+
+	sigs := make(map[string]string)
+
+	for _, host := range hosts {
+		req := &Request{
+			SourceHost:  host,
+			SourcePath:  "/photos/cat.jpg",
+			SourceQuery: "",
+			Width:       800,
+			Height:      600,
+			Format:      "webp",
+			Expires:     time.Unix(1704067200, 0),
+		}
+
+		sig := signer.Sign(req)
+		if existing, ok := sigs[sig]; ok {
+			t.Errorf("hosts %q and %q produced the same signature", existing, host)
+		}
+
+		sigs[sig] = host
+	}
+}
+
+func TestSigner_DifferentKeys(t *testing.T) {
+	signer1 := New("secret-key-1")
+	signer2 := New("secret-key-2")
+
+	req := &Request{
+		SourceHost: "cdn.example.com",
+		SourcePath: "/photos/cat.jpg",
+		Width:      800,
+		Height:     600,
+		Format:     "webp",
+		Expires:    time.Now().Add(1 * time.Hour),
+	}
+
+	// Sign with key 1
+	req.Signature = signer1.Sign(req)
+
+	// Verify with key 1 should succeed
+	if err := signer1.Verify(req); err != nil {
+		t.Errorf("Verify() with same key failed: %v", err)
+	}
+
+	// Verify with key 2 should fail
+	if err := signer2.Verify(req); err != ErrInvalid {
+		t.Errorf("Verify() with different key should fail, got: %v", err)
+	}
+}
+
+func TestGenerateSignedURL(t *testing.T) {
+	signer := New("test-secret-key")
+
+	req := &Request{
+		SourceHost:  "cdn.example.com",
+		SourcePath:  "/photos/cat.jpg",
+		SourceQuery: "",
+		Width:       800,
+		Height:      600,
+		Format:      "webp",
+	}
+
+	ttl := 1 * time.Hour
+	path, sig, exp := signer.GenerateSignedURL(req, ttl)
+
+	// Path should be correct format
+	expectedPath := "/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp"
+	if path != expectedPath {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", path, expectedPath)
+	}
+
+	// Signature should be non-empty
+	if sig == "" {
+		t.Error("GenerateSignedURL() produced empty signature")
+	}
+
+	// Expiration should be approximately now + TTL
+	expTime := time.Unix(exp, 0)
+	expectedExp := time.Now().Add(ttl)
+	if expTime.Sub(expectedExp) > time.Second {
+		t.Errorf("GenerateSignedURL() exp time off by too much")
+	}
+
+	// Request should have been updated with signature and expiration
+	if req.Signature != sig {
+		t.Errorf("GenerateSignedURL() didn't update request signature")
+	}
+}
+
+func TestGenerateSignedURL_OrigSize(t *testing.T) {
+	signer := New("test-secret-key")
+
+	req := &Request{
+		SourceHost: "cdn.example.com",
+		SourcePath: "/photos/cat.jpg",
+		Width:      0, // Original size
+		Height:     0,
+		Format:     "png",
+	}
+
+	path, _, _ := signer.GenerateSignedURL(req, time.Hour)
+
+	expectedPath := "/v1/image/cdn.example.com/photos/cat.jpg/orig.png"
+	if path != expectedPath {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", path, expectedPath)
+	}
+}
+
+func TestGenerateSignedURL_WithQueryString(t *testing.T) {
+	signer := New("test-secret-key-for-testing!")
+
+	req := &Request{
+		SourceHost:  "cdn.example.com",
+		SourcePath:  "/photos/cat.jpg",
+		SourceQuery: "token=abc&v=2",
+		Width:       800,
+		Height:      600,
+		Format:      "webp",
+	}
+
+	path, _, _ := signer.GenerateSignedURL(req, time.Hour)
+
+	// The path must NOT contain a bare "?" that would be interpreted as a query string delimiter.
+	// The size segment must appear as the last path component.
+	if strings.Contains(path, "?token=abc") {
+		t.Errorf("GenerateSignedURL() produced bare query string in path: %q", path)
+	}
+
+	// The size segment must be present in the path
+	if !strings.Contains(path, "/800x600.webp") {
+		t.Errorf("GenerateSignedURL() missing size segment in path: %q", path)
+	}
+
+	// Path should end with the size.format, not with query params
+	if !strings.HasSuffix(path, "/800x600.webp") {
+		t.Errorf("GenerateSignedURL() path should end with size.format: %q", path)
+	}
+}
+
+func TestGenerateSignedURL_WithoutQueryString(t *testing.T) {
+	signer := New("test-secret-key-for-testing!")
+
+	req := &Request{
+		SourceHost: "cdn.example.com",
+		SourcePath: "/photos/cat.jpg",
+		Width:      800,
+		Height:     600,
+		Format:     "webp",
+	}
+
+	path, _, _ := signer.GenerateSignedURL(req, time.Hour)
+
+	expected := "/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp"
+	if path != expected {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", path, expected)
+	}
+}
+
+func TestParseParams(t *testing.T) {
+	tests := []struct {
+		name      string
+		sig       string
+		expStr    string
+		wantSig   string
+		wantErr   bool
+		checkTime bool
+	}{
+		{
+			name:    "valid params",
+			sig:     "abc123",
+			expStr:  "1704067200",
+			wantSig: "abc123",
+			wantErr: false,
+		},
+		{
+			name:    "empty expiration",
+			sig:     "abc123",
+			expStr:  "",
+			wantSig: "abc123",
+			wantErr: false,
+		},
+		{
+			name:    "invalid expiration",
+			sig:     "abc123",
+			expStr:  "not-a-number",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			sig, exp, err := ParseParams(tt.sig, tt.expStr)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Error("ParseParams() expected error, got nil")
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Errorf("ParseParams() unexpected error = %v", err)
+
+				return
+			}
+
+			if sig != tt.wantSig {
+				t.Errorf("sig = %q, want %q", sig, tt.wantSig)
+			}
+
+			if tt.expStr != "" && exp.IsZero() {
+				t.Error("exp should not be zero when expStr is provided")
+			}
+		})
+	}
+}