Normalize cooldown package PURL overrides

config.example.yaml

@@ -168,7 +168,8 @@ cooldown:
   #   npm: "7d"
   #   cargo: "0"
 
-  # Per-package overrides (keyed by PURL)
+  # Per-package overrides (keyed by PURL). Keys are normalized, so npm scopes
+  # may use either @scope or the canonical %40scope form.
   # packages:
   #   "pkg:npm/lodash": "0"
   #   "pkg:npm/@babel/core": "14d"

docs/configuration.md

@@ -234,6 +234,8 @@ cooldown:
 
 Durations support days (`7d`), hours (`48h`), and minutes (`30m`). Set to `0` to disable.
 
+Package PURL keys are normalized to canonical form before matching, so `pkg:npm/@babel/core` and `pkg:npm/%40babel/core` are equivalent, as are `pkg:pypi/Django` and `pkg:pypi/django`. If both forms configure the same package, the canonical entry wins.
+
 Resolution order: package override, then ecosystem override, then global default. This lets you set a conservative default while exempting trusted packages.
 
 Currently supported for npm, PyPI, pub.dev, Composer, Cargo, NuGet, Conda, RubyGems, and Hex. These ecosystems include publish timestamps in their metadata.

internal/config/config.go

@@ -54,10 +54,12 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
 
+	"github.com/git-pkgs/purl"
 	"gopkg.in/yaml.v3"
 )
 
@@ -137,9 +139,38 @@ type CooldownConfig struct {
 	Ecosystems map[string]string `json:"ecosystems" yaml:"ecosystems"`
 
 	// Packages overrides the cooldown for specific packages (keyed by PURL).
+	// Valid PURL keys are normalized to canonical form before use.
 	Packages map[string]string `json:"packages" yaml:"packages"`
 }
 
+// NormalizedPackages returns a copy of the package overrides with valid PURL
+// keys in canonical form. An explicitly canonical key wins over an equivalent
+// noncanonical key, and invalid keys are preserved unchanged.
+func (c *CooldownConfig) NormalizedPackages() map[string]string {
+	if c == nil || c.Packages == nil {
+		return nil
+	}
+
+	keys := make([]string, 0, len(c.Packages))
+	for key := range c.Packages {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	normalized := make(map[string]string, len(c.Packages))
+	for _, key := range keys {
+		canonical := key
+		if parsed, err := purl.Parse(key); err == nil {
+			canonical = parsed.String()
+		}
+		if _, exists := normalized[canonical]; exists && key != canonical {
+			continue
+		}
+		normalized[canonical] = c.Packages[key]
+	}
+	return normalized
+}
+
 // StorageConfig configures artifact storage.
 type StorageConfig struct {
 	// URL is the storage backend URL.

internal/config/config_test.go

@@ -363,6 +363,34 @@ cooldown:
 	if cfg.Cooldown.Packages["pkg:npm/@babel/core"] != "14d" {
 		t.Errorf("Cooldown.Packages[@babel/core] = %q, want %q", cfg.Cooldown.Packages["pkg:npm/@babel/core"], "14d")
 	}
+	if got := cfg.Cooldown.NormalizedPackages()["pkg:npm/%40babel/core"]; got != "14d" {
+		t.Errorf("normalized Cooldown.Packages[@babel/core] = %q, want %q", got, "14d")
+	}
+}
+
+func TestCooldownConfigNormalizedPackages(t *testing.T) {
+	rawScoped := "pkg:npm/@typescript/typescript-darwin-arm64"
+	canonicalScoped := "pkg:npm/%40typescript/typescript-darwin-arm64"
+	cfg := CooldownConfig{Packages: map[string]string{
+		rawScoped:       "2d",
+		canonicalScoped: "3d",
+		"not-a-purl":    "4d",
+	}}
+
+	got := cfg.NormalizedPackages()
+
+	if got[canonicalScoped] != "3d" {
+		t.Errorf("canonical scoped package duration = %q, want %q", got[canonicalScoped], "3d")
+	}
+	if _, exists := got[rawScoped]; exists {
+		t.Errorf("raw scoped package key %q was not canonicalized", rawScoped)
+	}
+	if got["not-a-purl"] != "4d" {
+		t.Errorf("invalid PURL duration = %q, want preserved value %q", got["not-a-purl"], "4d")
+	}
+	if cfg.Packages[rawScoped] != "2d" {
+		t.Error("NormalizedPackages mutated the source map")
+	}
 }
 
 func TestLoadCooldownFromEnv(t *testing.T) {

internal/handler/cargo.go

@@ -8,8 +8,6 @@ import (
 	"net/http"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -143,7 +141,7 @@ func (h *CargoHandler) applyCooldownFiltering(downstreamResponse http.ResponseWr
 			continue
 		}
 
-		cratePURL := purl.MakePURLString("cargo", crate.Name, "")
+		cratePURL := canonicalPackagePURL("cargo", crate.Name)
 
 		if !h.proxy.Cooldown.IsAllowed("cargo", cratePURL, publishedAt) {
 			h.proxy.Logger.Info("cooldown: filtering cargo version",

internal/handler/composer.go

@@ -10,8 +10,6 @@ import (
 	"path"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -216,7 +214,7 @@ func deepCopyValue(v any) any {
 // filterAndRewriteVersions applies cooldown filtering and rewrites dist URLs
 // for a single package's version list.
 func (h *ComposerHandler) filterAndRewriteVersions(packageName string, versionList []any) []any {
-	packagePURL := purl.MakePURLString("composer", packageName, "")
+	packagePURL := canonicalPackagePURL("composer", packageName)
 
 	filtered := versionList[:0]
 	for _, v := range versionList {

internal/handler/conda.go

@@ -6,8 +6,6 @@ import (
 	"net/http"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -218,7 +216,7 @@ func (h *CondaHandler) applyCooldownFiltering(body []byte) ([]byte, error) {
 				continue
 			}
 
-			packagePURL := purl.MakePURLString("conda", name, "")
+			packagePURL := canonicalPackagePURL("conda", name)
 
 			if !h.proxy.Cooldown.IsAllowed("conda", packagePURL, publishedAt) {
 				version, _ := entryMap["version"].(string)

internal/handler/gem.go

@@ -8,8 +8,6 @@ import (
 	"net/http"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -266,7 +264,7 @@ func (h *GemHandler) fetchFilteredVersions(r *http.Request, name string) (map[st
 		return nil, err
 	}
 
-	packagePURL := purl.MakePURLString("gem", name, "")
+	packagePURL := canonicalPackagePURL("gem", name)
 	filtered := make(map[string]bool)
 
 	for _, v := range versions {

internal/handler/handler.go

@@ -48,6 +48,14 @@ func hasDotDotSegment(path string) bool {
 
 const defaultHTTPTimeout = 30 * time.Second
 
+// canonicalPackagePURL returns a versionless PURL in canonical form so cooldown
+// lookups match keys produced by config.CooldownConfig.NormalizedPackages.
+func canonicalPackagePURL(ecosystem, name string) string {
+	p := purl.MakePURL(ecosystem, name, "")
+	_ = p.Normalize()
+	return p.String()
+}
+
 const contentTypeJSON = "application/json"
 
 const headerAcceptEncoding = "Accept-Encoding"

internal/handler/handler_test.go

@@ -14,6 +14,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/git-pkgs/proxy/internal/config"
 	"github.com/git-pkgs/proxy/internal/database"
 	"github.com/git-pkgs/proxy/internal/storage"
 	"github.com/git-pkgs/registries/fetch"
@@ -1010,3 +1011,33 @@ func TestProxyCached_FreshResponse_NoWarningHeader(t *testing.T) {
 		t.Errorf("Warning should be empty for fresh response, got %q", got)
 	}
 }
+
+// TestCanonicalPackagePURLMatchesConfig ensures the runtime cooldown lookup key
+// agrees with config.CooldownConfig.NormalizedPackages for the same package,
+// so a configured override is actually found regardless of how the user wrote it.
+func TestCanonicalPackagePURLMatchesConfig(t *testing.T) {
+	tests := []struct {
+		ecosystem   string
+		requestName string
+		configKey   string
+	}{
+		{"npm", "@babel/core", "pkg:npm/@babel/core"},
+		{"npm", "@babel/core", "pkg:npm/%40babel/core"},
+		{"npm", "@typescript/typescript-darwin-arm64", "pkg:npm/@typescript/typescript-darwin-arm64"},
+		{"pypi", "Django", "pkg:pypi/Django"},
+		{"pypi", "django", "pkg:pypi/Django"},
+		{"composer", "symfony/console", "pkg:composer/Symfony/Console"},
+		{"cargo", "serde", "pkg:cargo/serde"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.ecosystem+"/"+tt.requestName+"<="+tt.configKey, func(t *testing.T) {
+			cfg := config.CooldownConfig{Packages: map[string]string{tt.configKey: "1d"}}
+			normalized := cfg.NormalizedPackages()
+
+			lookup := canonicalPackagePURL(tt.ecosystem, tt.requestName)
+			if _, ok := normalized[lookup]; !ok {
+				t.Errorf("lookup key %q not found in normalized config %v", lookup, normalized)
+			}
+		})
+	}
+}

internal/handler/hex.go

@@ -10,7 +10,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/git-pkgs/purl"
 	"google.golang.org/protobuf/encoding/protowire"
 )
 
@@ -237,7 +236,7 @@ func (h *HexHandler) fetchFilteredVersions(r *http.Request, name string) (map[st
 		return nil, err
 	}
 
-	packagePURL := purl.MakePURLString("hex", name, "")
+	packagePURL := canonicalPackagePURL("hex", name)
 	filtered := make(map[string]bool)
 
 	for _, release := range pkg.Releases {

internal/handler/npm.go

@@ -9,8 +9,6 @@ import (
 	"sort"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -134,7 +132,7 @@ func (h *NPMHandler) applyCooldownFiltering(metadata map[string]any, versions ma
 		return
 	}
 
-	packagePURL := purl.MakePURLString("npm", packageName, "")
+	packagePURL := canonicalPackagePURL("npm", packageName)
 
 	for version := range versions {
 		publishedStr, ok := timeMap[version].(string)

internal/handler/nuget.go

@@ -8,8 +8,6 @@ import (
 	"net/http"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -271,7 +269,7 @@ func (h *NuGetHandler) applyCooldownFiltering(body []byte) ([]byte, error) {
 				}
 			}
 
-			packagePURL := purl.MakePURLString("nuget", strings.ToLower(id), "")
+			packagePURL := canonicalPackagePURL("nuget", strings.ToLower(id))
 
 			if !h.proxy.Cooldown.IsAllowed("nuget", packagePURL, publishedAt) {
 				h.proxy.Logger.Info("cooldown: filtering nuget version",

internal/handler/pub.go

@@ -7,8 +7,6 @@ import (
 	"net/http"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -127,7 +125,7 @@ func (h *PubHandler) rewriteMetadata(name string, body []byte) ([]byte, error) {
 		return body, nil
 	}
 
-	packagePURL := purl.MakePURLString("pub", name, "")
+	packagePURL := canonicalPackagePURL("pub", name)
 	filtered := h.filterAndRewriteVersions(name, packagePURL, versions)
 	metadata["versions"] = filtered
 

internal/handler/pypi.go

@@ -12,8 +12,6 @@ import (
 	"regexp"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/purl"
 )
 
 const (
@@ -131,7 +129,7 @@ func (h *PyPIHandler) fetchFilteredVersions(r *http.Request, name string) map[st
 		return nil
 	}
 
-	packagePURL := purl.MakePURLString("pypi", name, "")
+	packagePURL := canonicalPackagePURL("pypi", name)
 	filtered := make(map[string]bool)
 
 	for version, files := range releases {
@@ -262,7 +260,7 @@ func (h *PyPIHandler) rewriteJSONMetadata(body []byte) ([]byte, error) {
 	packageName, _ := extractPyPIName(metadata)
 	packagePURL := ""
 	if packageName != "" {
-		packagePURL = purl.MakePURLString("pypi", packageName, "")
+		packagePURL = canonicalPackagePURL("pypi", packageName)
 	}
 
 	h.filterAndRewriteReleases(metadata, packageName, packagePURL)

internal/server/server.go

@@ -163,7 +163,7 @@ func (s *Server) Start() error {
 	cd := &cooldown.Config{
 		Default:    s.cfg.Cooldown.Default,
 		Ecosystems: s.cfg.Cooldown.Ecosystems,
-		Packages:   s.cfg.Cooldown.Packages,
+		Packages:   s.cfg.Cooldown.NormalizedPackages(),
 	}
 	proxy := handler.NewProxy(s.db, s.storage, fetcher, resolver, s.logger)
 	proxy.HTTPClient.Timeout = s.cfg.ParseHTTPTimeout()