refactor: extract signature package from imgcache (#46)

Extracts HMAC-SHA256 request signing out of `internal/imgcache/` into its own `internal/signature/` package, per the plan in [issue #39](#39).

This is one of the remaining "easily separable" extractions (`imageprocessor`, `allowlist`, `magic`, and `httpfetcher` already landed). Only the signer is moved here so the diff stays reviewable.

## What moved

From `internal/imgcache/signature.go` and its tests into `internal/signature/`:

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

## One-way import edge

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 `signatureRequest` helper. This mirrors how the `magic` extraction defined its own `ImageFormat` type.

## Renames (no stuttering)

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

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

## Rework (post-review)

Three commits added after review feedback:

- `d69019b` — golden known-answer test pinning the exact HMAC signatures and signed URL paths for three fixed vectors (resized, resized+query, orig size), cross-validated against an independent HMAC implementation. Any change to the signed byte format now fails loudly.
- `43b9f1c` — whitelist→allowlist rename completed across `internal/imgcache` and `internal/handlers` (`ServiceConfig.Allowlist`, `Allowlist` interface, `IsAllowlisted`, test helpers and test names).
- `3dc1999` — one-pass config surface rename, no back-compat alias: YAML key `whitelist_hosts` → `allowlist_hosts`, `Config.WhitelistHosts` → `Config.AllowlistHosts`, `config.example.yml`, `scripts/manual-test.sh`, and `README.md` (which also documented a nonexistent `source_host_whitelist` key — now fixed to the real one).

## Behavior

Pure refactor apart from the config key rename above. The bytes fed to the HMAC are unchanged (`host:path:query:width:height:format:expiration`), so previously issued signatures remain valid — now enforced by the golden test. All existing tests move with the package. `script/cibuild` passes at head `3dc1999` (fmt-check, lint, test, build).

refs #39

Co-authored-by: sneak <sneak@sneak.berlin>
Co-authored-by: Jeffrey Paul <sneak@noreply.example.org>
Reviewed-on: #46
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

internal/signature/golden_test.go

@@ -0,0 +1,105 @@
+package signature
+
+import (
+	"testing"
+	"time"
+)
+
+// goldenExpiresUnix is the fixed expiration timestamp used by all golden
+// vectors: 2024-01-01T00:00:00Z.
+const goldenExpiresUnix int64 = 1704067200
+
+// goldenSigningKey is the fixed signing key used by all golden vectors.
+const goldenSigningKey = "golden-test-key"
+
+// TestSigner_GoldenVectors pins the exact HMAC-SHA256 signature output and
+// the exact generated signed URL path for fully-specified requests with a
+// hardcoded signing key. The expected values were computed once and are
+// hardcoded here as known answers.
+//
+// If any of these assertions fail, the signed byte format
+// ("host:path:query:width:height:format:expiration"), the base64url
+// encoding, or the signed URL layout has changed. Such a change breaks
+// every signature already issued to clients, so it must be made
+// deliberately: update these constants only as part of an intentional,
+// documented signature format migration.
+func TestSigner_GoldenVectors(t *testing.T) {
+	signer := New(goldenSigningKey)
+
+	vectors := []struct {
+		name string
+		req  Request
+		// wantSignature is the exact base64url (RFC 4648 URL-safe,
+		// padded) HMAC-SHA256 signature for the request with Expires
+		// set to goldenExpiresUnix.
+		wantSignature string
+		// wantSignedPath is the exact path returned by
+		// GenerateSignedURL for the request. The signature and
+		// expiration are returned separately by GenerateSignedURL and
+		// are not embedded in the path.
+		wantSignedPath string
+	}{
+		{
+			name: "resized without query",
+			req: Request{
+				SourceHost:  "cdn.example.com",
+				SourcePath:  "/photos/cat.jpg",
+				SourceQuery: "",
+				Width:       800,
+				Height:      600,
+				Format:      "webp",
+			},
+			// Signed data: "cdn.example.com:/photos/cat.jpg::800:600:webp:1704067200"
+			wantSignature:  "x5PfPp8QSDo0cJT96od-AEgrQyOVLfqifH5sst61_-w=",
+			wantSignedPath: "/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp",
+		},
+		{
+			name: "resized with query string",
+			req: Request{
+				SourceHost:  "cdn.example.com",
+				SourcePath:  "/photos/cat.jpg",
+				SourceQuery: "token=abc&v=2",
+				Width:       800,
+				Height:      600,
+				Format:      "webp",
+			},
+			// Signed data: "cdn.example.com:/photos/cat.jpg:token=abc&v=2:800:600:webp:1704067200"
+			wantSignature:  "394_Vf9TdQFkpQ3XKFDQSyxgqKq8N7mApf2S4QaHqyo=",
+			wantSignedPath: "/v1/image/cdn.example.com/photos/cat.jpg%3Ftoken=abc&v=2/800x600.webp",
+		},
+		{
+			name: "original size without query",
+			req: Request{
+				SourceHost:  "cdn.example.com",
+				SourcePath:  "/photos/cat.jpg",
+				SourceQuery: "",
+				Width:       0,
+				Height:      0,
+				Format:      "png",
+			},
+			// Signed data: "cdn.example.com:/photos/cat.jpg::0:0:png:1704067200"
+			wantSignature:  "7Be7oteeQwvnSPU4bchyQ4ZGYGsAGBKpeEtuQ02ox60=",
+			wantSignedPath: "/v1/image/cdn.example.com/photos/cat.jpg/orig.png",
+		},
+	}
+
+	for _, tt := range vectors {
+		t.Run(tt.name, func(t *testing.T) {
+			signReq := tt.req
+			signReq.Expires = time.Unix(goldenExpiresUnix, 0)
+
+			gotSignature := signer.Sign(&signReq)
+			if gotSignature != tt.wantSignature {
+				t.Errorf("Sign() = %q, want %q (signed byte format changed?)",
+					gotSignature, tt.wantSignature)
+			}
+
+			urlReq := tt.req
+			gotPath, _, _ := signer.GenerateSignedURL(&urlReq, time.Hour)
+			if gotPath != tt.wantSignedPath {
+				t.Errorf("GenerateSignedURL() path = %q, want %q (signed URL layout changed?)",
+					gotPath, tt.wantSignedPath)
+			}
+		})
+	}
+}