Enforce and document exact-match-only for signature verification (#40)

Closes #27 Signatures are per-URL only — this PR adds explicit tests and documentation enforcing that HMAC-SHA256 signatures verify against exact URLs only. No suffix matching, wildcard matching, or partial matching is supported. ## What this does NOT touch **The host whitelist code (`whitelist.go`) is not modified.** This PR is exclusively about signature verification, per sneak's instructions on [issue #27](#27), [PR #32](#32), and [PR #35](#35). ## Changes ### `internal/imgcache/signature.go` - Added documentation comments on `Verify()` and `buildSignatureData()` explicitly specifying that signatures are exact-match only — no suffix, wildcard, or partial matching ### `internal/imgcache/signature_test.go` - **`TestSigner_Verify_ExactMatchOnly`**: 14 tamper cases verifying that modifying any signed component (host, path, query, dimensions, format) causes verification to fail. Host-specific cases include: - Parent domain (`example.com`) does not match subdomain signature (`cdn.example.com`) - Sibling subdomain (`images.example.com`) does not match - Deeper subdomain (`images.cdn.example.com`) does not match - Evil suffix domain (`cdn.example.com.evil.com`) does not match - Prefixed host (`evilcdn.example.com`) does not match - **`TestSigner_Sign_ExactHostInData`**: Verifies that suffix-related hosts (`cdn.example.com`, `example.com`, `images.example.com`, etc.) all produce distinct signatures ### `internal/imgcache/service_test.go` - **`TestService_ValidateRequest_SignatureExactHostMatch`**: Integration test through `ValidateRequest` verifying that a valid signature for `cdn.example.com` is rejected when presented with a different host (parent domain, sibling subdomain, deeper subdomain, evil suffix, prefixed host) ### `README.md` - Updated Signature Specification section to explicitly document exact-match-only semantics Co-authored-by: user <user@Mac.lan guest wan> Reviewed-on: #40 Co-authored-by: clawbot <clawbot@noreply.example.org> Co-committed-by: clawbot <clawbot@noreply.example.org>
2026-03-20 23:56:45 +01:00
parent e85b5ff033
commit a50364bfca
4 changed files with 251 additions and 1 deletions
--- a/internal/imgcache/signature_test.go
+++ b/internal/imgcache/signature_test.go
@@ -152,6 +152,178 @@ func TestSigner_Verify(t *testing.T) {
 	}
 }

+// 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 := NewSigner("test-secret-key")
+
+	// Base request that we'll sign, then tamper with individual fields.
+	baseReq := func() *ImageRequest {
+		req := &ImageRequest{
+			SourceHost:  "cdn.example.com",
+			SourcePath:  "/photos/cat.jpg",
+			SourceQuery: "token=abc",
+			Size:        Size{Width: 800, Height: 600},
+			Format:      FormatWebP,
+			Expires:     time.Now().Add(1 * time.Hour),
+		}
+		req.Signature = signer.Sign(req)
+
+		return req
+	}
+
+	tests := []struct {
+		name   string
+		tamper func(req *ImageRequest)
+	}{
+		{
+			name: "parent domain does not match subdomain",
+			tamper: func(req *ImageRequest) {
+				// Signed for cdn.example.com, try example.com
+				req.SourceHost = "example.com"
+			},
+		},
+		{
+			name: "subdomain does not match parent domain",
+			tamper: func(req *ImageRequest) {
+				// 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 *ImageRequest) {
+				// 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 *ImageRequest) {
+				// 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 *ImageRequest) {
+				// Signed for cdn.example.com, try evilcdn.example.com
+				req.SourceHost = "evilcdn.example.com"
+			},
+		},
+		{
+			name: "different path does not match",
+			tamper: func(req *ImageRequest) {
+				req.SourcePath = "/photos/dog.jpg"
+			},
+		},
+		{
+			name: "path suffix does not match",
+			tamper: func(req *ImageRequest) {
+				req.SourcePath = "/photos/cat.jpg/extra"
+			},
+		},
+		{
+			name: "path prefix does not match",
+			tamper: func(req *ImageRequest) {
+				req.SourcePath = "/other/photos/cat.jpg"
+			},
+		},
+		{
+			name: "different query does not match",
+			tamper: func(req *ImageRequest) {
+				req.SourceQuery = "token=xyz"
+			},
+		},
+		{
+			name: "added query does not match empty query",
+			tamper: func(req *ImageRequest) {
+				req.SourceQuery = "extra=1"
+			},
+		},
+		{
+			name: "removed query does not match",
+			tamper: func(req *ImageRequest) {
+				req.SourceQuery = ""
+			},
+		},
+		{
+			name: "different width does not match",
+			tamper: func(req *ImageRequest) {
+				req.Size.Width = 801
+			},
+		},
+		{
+			name: "different height does not match",
+			tamper: func(req *ImageRequest) {
+				req.Size.Height = 601
+			},
+		},
+		{
+			name: "different format does not match",
+			tamper: func(req *ImageRequest) {
+				req.Format = FormatPNG
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := baseReq()
+			tt.tamper(req)
+
+			err := signer.Verify(req)
+			if err != ErrSignatureInvalid {
+				t.Errorf("Verify() = %v, want %v", err, ErrSignatureInvalid)
+			}
+		})
+	}
+
+	// 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 := NewSigner("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 := &ImageRequest{
+			SourceHost:  host,
+			SourcePath:  "/photos/cat.jpg",
+			SourceQuery: "",
+			Size:        Size{Width: 800, Height: 600},
+			Format:      FormatWebP,
+			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 := NewSigner("secret-key-1")
 	signer2 := NewSigner("secret-key-2")