feat: Add dependency cooldown for npm packages (#200)

* feat: Add dependency cooldown for npm packages Strip recently-published package versions from npm registry metadata responses so npm's resolver naturally falls back to older versions. Overrides the Accept header to force full packument responses (which include the "time" field needed for publish-date checks). Reports cooldown blocks only when all versions are stripped (remaining == 0), matching npm's --min-release-age behavior for silent fallback. * fix: Report oldest version in cooldown block (shortest wait) When all versions are blocked by cooldown, report the oldest version since it exits the cooldown window first — giving the user the shortest wait time instead of the longest. * fix: Handle resp.Body.Close error return for errcheck linter * test: Add dependency cooldown assertions to template config tests * fix: config template for dependency cooldown * fix: Prevent npm from caching cooldown-stripped metadata responses * fix: Restore body on ReadAll failure and log Close errors in response modifier * fix: Close response body before replacing to prevent connection leak * fix: Correct daysLeft ceiling math and update ContentLength on error recovery * fix: Clear Status on status code change and update ContentLength in modifier error path * refactor: address review comments on dependency cooldown PR - Make NpmCooldownHandler and constructor package-private - Pass cooldown days as parameter instead of reading config internally - Convert standalone functions to methods on npmCooldownHandler - Set Accept-Encoding: identity to prevent gzip responses breaking JSON parsing - Return 503 with descriptive message when upstream body read fails * fix: log errors in stripCooldownVersions instead of swallowing them * fix: Config preserve fallback defaults * fix: Code review fixes * fix: correct cooldown tip to show wait time instead of incorrect trusted_packages advice * fix: prevent integer overflow in cooldown duration calculation with large days values * refactor: deduplicate CooldownBlock into internal/models, fix misleading variable names - Move CooldownBlock struct to internal/models to eliminate duplication between proxy/interceptors and internal/ui packages - Simplify proxy_flow.go by using direct assignment instead of field copy - Rename latestStripped/latestDate to oldestVer/oldestDate for clarity * fix: Dependency Cooldown Check Encapsulation (#207) * fix: Encapsulate cooldown check * feat: Add --skip-dependency-cooldown override * fix: Code review fixes --------- Co-authored-by: Abhisek Datta <abhisek.datta@gmail.com>
2026-08-03 07:24:09 +02:00 · 2026-04-08 21:04:17 +05:30
parent 64b95b3ad0
commit 987bda5d6a
18 changed files with 1159 additions and 23 deletions
@@ -0,0 +1,259 @@
+package interceptors
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/safedep/dry/log"
+	"github.com/safedep/pmg/proxy"
+)
+
+// npmMetadataTimeSkipKeys are non-version keys present in the NPM metadata "time" object.
+var npmMetadataTimeSkipKeys = map[string]bool{
+	"created":  true,
+	"modified": true,
+}
+
+// npmCooldownHandler handles dependency cooldown for npm packages.
+// It strips recently-published versions from metadata responses so npm's
+// resolver naturally falls back to the latest eligible version.
+type npmCooldownHandler struct {
+	statsCollector *AnalysisStatsCollector
+}
+
+func newNpmCooldownHandler(statsCollector *AnalysisStatsCollector) *npmCooldownHandler {
+	return &npmCooldownHandler{
+		statsCollector: statsCollector,
+	}
+}
+
+// HandleMetadataRequest overrides the Accept header to force the registry to return
+// a full packument (which includes publish dates in the "time" field), then registers
+// a response modifier that strips versions within the cooldown window.
+func (h *npmCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, packageName string, cooldownDays int) (*proxy.InterceptorResponse, error) {
+	log.Debugf("[%s] Cooldown: registering metadata modifier for %s", ctx.RequestID, packageName)
+
+	// Force full packument so the response always contains the "time" field.
+	// Abbreviated metadata (Accept: application/vnd.npm.install-v1+json) omits it.
+	ctx.Headers.Set("Accept", "application/json")
+
+	// Prevent the server from compressing the response so we can parse the JSON body.
+	// Go's http.Transport only auto-decompresses when it added the Accept-Encoding
+	// header itself; since the client's original header is forwarded by the proxy,
+	// we'd get raw gzip bytes that fail JSON parsing.
+	ctx.Headers.Set("Accept-Encoding", "identity")
+
+	modifier := func(statusCode int, headers http.Header, body []byte) (int, http.Header, []byte, error) {
+		dates, err := h.parseMetadataTime(body)
+		if err != nil {
+			log.Warnf("[%s] Cooldown: failed to parse metadata time for %s: %v", ctx.RequestID, packageName, err)
+			return statusCode, headers, body, nil
+		}
+
+		log.Debugf("[%s] Cooldown: parsed %d publish dates for %s", ctx.RequestID, len(dates), packageName)
+
+		strippedBody, stripped, remaining := h.stripCooldownVersions(body, dates, cooldownDays)
+		if stripped > 0 {
+			log.Infof("[%s] Cooldown: stripped %d version(s) from %s metadata (%d days, %d eligible remain)",
+				ctx.RequestID, stripped, packageName, cooldownDays, remaining)
+
+			if remaining == 0 && h.statsCollector != nil {
+				oldestVer, oldestDate := h.oldestVersion(dates)
+				if oldestVer != "" {
+					_, daysAgo, daysLeft := h.isWithinCooldown(oldestDate, cooldownDays)
+					h.statsCollector.RecordCooldownBlocked(packageName, oldestVer, oldestDate, daysAgo, daysLeft, cooldownDays)
+				}
+			}
+
+			// Prevent npm from caching the modified response. Without this,
+			// npm would serve the stripped metadata from cache even after the
+			// cooldown window passes or settings change.
+			headers.Set("Cache-Control", "no-store")
+
+			return statusCode, headers, strippedBody, nil
+		}
+
+		return statusCode, headers, body, nil
+	}
+
+	return &proxy.InterceptorResponse{
+		Action:           proxy.ActionModifyResponse,
+		ResponseModifier: modifier,
+	}, nil
+}
+
+// parseMetadataTime extracts version publish dates from an NPM package metadata body.
+func (h *npmCooldownHandler) parseMetadataTime(body []byte) (map[string]time.Time, error) {
+	var metadata struct {
+		Time map[string]string `json:"time"`
+	}
+
+	if err := json.Unmarshal(body, &metadata); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal npm metadata: %w", err)
+	}
+
+	if metadata.Time == nil {
+		return map[string]time.Time{}, nil
+	}
+
+	dates := make(map[string]time.Time, len(metadata.Time))
+	for version, dateStr := range metadata.Time {
+		if npmMetadataTimeSkipKeys[version] {
+			continue
+		}
+
+		t, err := time.Parse(time.RFC3339, dateStr)
+		if err != nil {
+			t, err = time.Parse("2006-01-02T15:04:05.000Z", dateStr)
+			if err != nil {
+				log.Debugf("Skipping unparseable publish date for version %s: %q", version, dateStr)
+				continue
+			}
+		}
+
+		dates[version] = t
+	}
+
+	return dates, nil
+}
+
+// stripCooldownVersions removes versions published within the cooldown window from the
+// NPM metadata response. It strips entries from "versions", "time", and updates "dist-tags".
+func (h *npmCooldownHandler) stripCooldownVersions(body []byte, dates map[string]time.Time, cooldownDays int) ([]byte, int, int) {
+	tooNew := make(map[string]bool)
+	for version, publishDate := range dates {
+		if withinCooldown, _, _ := h.isWithinCooldown(publishDate, cooldownDays); withinCooldown {
+			tooNew[version] = true
+		}
+	}
+
+	remaining := len(dates) - len(tooNew)
+
+	if len(tooNew) == 0 {
+		return body, 0, remaining
+	}
+
+	var metadata map[string]json.RawMessage
+	if err := json.Unmarshal(body, &metadata); err != nil {
+		log.Warnf("Cooldown: failed to unmarshal metadata body: %v", err)
+		return body, 0, remaining
+	}
+
+	if raw, ok := metadata["versions"]; ok {
+		var versions map[string]json.RawMessage
+		if err := json.Unmarshal(raw, &versions); err != nil {
+			log.Warnf("Cooldown: failed to unmarshal versions field: %v", err)
+		} else {
+			for v := range tooNew {
+				delete(versions, v)
+			}
+			if updated, err := json.Marshal(versions); err != nil {
+				log.Warnf("Cooldown: failed to marshal updated versions: %v", err)
+			} else {
+				metadata["versions"] = updated
+			}
+		}
+	}
+
+	if raw, ok := metadata["time"]; ok {
+		var timeMap map[string]string
+		if err := json.Unmarshal(raw, &timeMap); err != nil {
+			log.Warnf("Cooldown: failed to unmarshal time field: %v", err)
+		} else {
+			for v := range tooNew {
+				delete(timeMap, v)
+			}
+			if updated, err := json.Marshal(timeMap); err != nil {
+				log.Warnf("Cooldown: failed to marshal updated time: %v", err)
+			} else {
+				metadata["time"] = updated
+			}
+		}
+	}
+
+	if raw, ok := metadata["dist-tags"]; ok {
+		var distTags map[string]string
+		if err := json.Unmarshal(raw, &distTags); err != nil {
+			log.Warnf("Cooldown: failed to unmarshal dist-tags field: %v", err)
+		} else {
+			changed := false
+			for tag, version := range distTags {
+				if tooNew[version] {
+					latest := h.latestNonCooldownVersion(dates, tooNew)
+					if latest != "" {
+						distTags[tag] = latest
+					} else {
+						delete(distTags, tag)
+					}
+					changed = true
+				}
+			}
+			if changed {
+				if updated, err := json.Marshal(distTags); err != nil {
+					log.Warnf("Cooldown: failed to marshal updated dist-tags: %v", err)
+				} else {
+					metadata["dist-tags"] = updated
+				}
+			}
+		}
+	}
+
+	result, err := json.Marshal(metadata)
+	if err != nil {
+		log.Warnf("Cooldown: failed to marshal final metadata: %v", err)
+		return body, 0, remaining
+	}
+
+	return result, len(tooNew), remaining
+}
+
+// oldestVersion returns the version with the earliest publish date.
+// When all versions are blocked by cooldown, this is the version closest
+// to exiting the cooldown window (shortest wait for the user).
+func (h *npmCooldownHandler) oldestVersion(dates map[string]time.Time) (string, time.Time) {
+	var oldest string
+	var oldestTime time.Time
+
+	for version, publishDate := range dates {
+		if oldestTime.IsZero() || publishDate.Before(oldestTime) {
+			oldest = version
+			oldestTime = publishDate
+		}
+	}
+
+	return oldest, oldestTime
+}
+
+// isWithinCooldown reports whether a version published at publishDate is still
+// within the cooldown window of cooldownDays. It also returns the number of
+// whole days since publication.
+func (h *npmCooldownHandler) isWithinCooldown(publishDate time.Time, cooldownDays int) (withinCooldown bool, daysSincePublish int, daysRemaining int) {
+	daysSincePublish = int(time.Since(publishDate).Hours() / 24)
+	if daysSincePublish < 0 {
+		daysSincePublish = 0
+	}
+	daysRemaining = cooldownDays - daysSincePublish
+	if daysRemaining < 0 {
+		daysRemaining = 0
+	}
+	return daysSincePublish < cooldownDays, daysSincePublish, daysRemaining
+}
+
+func (h *npmCooldownHandler) latestNonCooldownVersion(dates map[string]time.Time, tooNew map[string]bool) string {
+	var latest string
+	var latestTime time.Time
+
+	for version, publishDate := range dates {
+		if tooNew[version] {
+			continue
+		}
+		if publishDate.After(latestTime) {
+			latest = version
+			latestTime = publishDate
+		}
+	}
+
+	return latest
+}
@@ -0,0 +1,600 @@
+package interceptors
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/safedep/pmg/config"
+	"github.com/safedep/pmg/proxy"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func setCooldownConfig(t *testing.T, cfg config.DependencyCooldownConfig) {
+	t.Helper()
+	orig := config.Get().Config.DependencyCooldown
+	t.Cleanup(func() { config.Get().Config.DependencyCooldown = orig })
+	config.Get().Config.DependencyCooldown = cfg
+}
+
+func mustParseURL(rawURL string) *url.URL {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		panic("mustParseURL: " + err.Error())
+	}
+	return u
+}
+
+func TestParseNpmMetadataTime(t *testing.T) {
+	handler := newNpmCooldownHandler(nil)
+
+	tests := []struct {
+		name          string
+		body          []byte
+		expectedCount int
+		expectError   bool
+	}{
+		{
+			name: "valid metadata with 3 versions",
+			body: []byte(`{
+				"time": {
+					"created": "2020-01-01T00:00:00.000Z",
+					"modified": "2024-01-01T00:00:00.000Z",
+					"1.0.0": "2020-06-01T00:00:00.000Z",
+					"1.0.1": "2021-06-01T00:00:00.000Z",
+					"1.0.2": "2022-06-01T00:00:00.000Z"
+				}
+			}`),
+			expectedCount: 3,
+		},
+		{
+			name:          "metadata without time field",
+			body:          []byte(`{"name":"foo","version":"1.0.0"}`),
+			expectedCount: 0,
+		},
+		{
+			name:          "only skip keys",
+			body:          []byte(`{"time":{"created":"2020-01-01T00:00:00.000Z","modified":"2024-01-01T00:00:00.000Z"}}`),
+			expectedCount: 0,
+		},
+		{
+			name:        "invalid JSON",
+			body:        []byte(`not-json`),
+			expectError: true,
+		},
+		{
+			name: "unparseable dates skipped",
+			body: []byte(`{
+				"time": {
+					"1.0.0": "not-a-date",
+					"1.0.1": "2022-06-01T00:00:00.000Z"
+				}
+			}`),
+			expectedCount: 1,
+		},
+		{
+			name: "RFC3339 without millis",
+			body: []byte(`{
+				"time": {
+					"1.0.0": "2022-06-01T00:00:00Z"
+				}
+			}`),
+			expectedCount: 1,
+		},
+		{
+			name: "millis precision",
+			body: []byte(`{
+				"time": {
+					"1.0.0": "2022-06-01T00:00:00.000Z"
+				}
+			}`),
+			expectedCount: 1,
+		},
+		{
+			name:        "empty body",
+			body:        []byte(``),
+			expectError: true,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			dates, err := handler.parseMetadataTime(tc.body)
+			if tc.expectError {
+				assert.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tc.expectedCount, len(dates))
+		})
+	}
+}
+
+func TestParseNpmMetadataTime_CorrectDates(t *testing.T) {
+	handler := newNpmCooldownHandler(nil)
+
+	body := []byte(`{
+		"time": {
+			"created": "2021-01-01T00:00:00.000Z",
+			"modified": "2024-01-01T00:00:00.000Z",
+			"4.17.20": "2021-02-17T12:00:00.000Z",
+			"4.17.21": "2021-05-19T12:00:00.000Z"
+		}
+	}`)
+
+	dates, err := handler.parseMetadataTime(body)
+	require.NoError(t, err)
+
+	assert.Equal(t, 2, len(dates))
+
+	d4_17_20, ok := dates["4.17.20"]
+	require.True(t, ok, "expected 4.17.20 in dates")
+	assert.Equal(t, 2021, d4_17_20.Year())
+	assert.Equal(t, time.February, d4_17_20.Month())
+	assert.Equal(t, 17, d4_17_20.Day())
+
+	d4_17_21, ok := dates["4.17.21"]
+	require.True(t, ok, "expected 4.17.21 in dates")
+	assert.Equal(t, 2021, d4_17_21.Year())
+	assert.Equal(t, time.May, d4_17_21.Month())
+	assert.Equal(t, 19, d4_17_21.Day())
+
+	_, hasCreated := dates["created"]
+	assert.False(t, hasCreated)
+	_, hasModified := dates["modified"]
+	assert.False(t, hasModified)
+}
+
+func buildTestPackument(versions map[string]time.Time, distTags map[string]string) []byte {
+	timeMap := map[string]string{
+		"created":  "2020-01-01T00:00:00.000Z",
+		"modified": "2024-01-01T00:00:00.000Z",
+	}
+	versionsMap := map[string]any{}
+	for v, t := range versions {
+		timeMap[v] = t.Format(time.RFC3339)
+		versionsMap[v] = map[string]any{"version": v}
+	}
+
+	packument := map[string]any{
+		"name":      "testpkg",
+		"time":      timeMap,
+		"versions":  versionsMap,
+		"dist-tags": distTags,
+	}
+	b, _ := json.Marshal(packument)
+	return b
+}
+
+func TestStripCooldownVersions_MixedVersions(t *testing.T) {
+	handler := newNpmCooldownHandler(nil)
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-30 * 24 * time.Hour), // old
+		"1.0.1": now.Add(-10 * 24 * time.Hour), // old
+		"1.0.2": now.Add(-1 * 24 * time.Hour),  // too new (within 5d cooldown)
+	}
+	distTags := map[string]string{"latest": "1.0.2"}
+	body := buildTestPackument(versions, distTags)
+
+	dates, err := handler.parseMetadataTime(body)
+	require.NoError(t, err)
+
+	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	assert.Equal(t, 1, stripped)
+	assert.Equal(t, 2, remaining)
+
+	var result map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(newBody, &result))
+
+	var resultVersions map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(result["versions"], &resultVersions))
+	assert.NotContains(t, resultVersions, "1.0.2")
+	assert.Contains(t, resultVersions, "1.0.0")
+	assert.Contains(t, resultVersions, "1.0.1")
+
+	var resultDistTags map[string]string
+	require.NoError(t, json.Unmarshal(result["dist-tags"], &resultDistTags))
+	// latest should be updated to an older eligible version
+	assert.NotEqual(t, "1.0.2", resultDistTags["latest"])
+
+	var resultTime map[string]string
+	require.NoError(t, json.Unmarshal(result["time"], &resultTime))
+	assert.Contains(t, resultTime, "created")
+	assert.Contains(t, resultTime, "modified")
+}
+
+func TestStripCooldownVersions_AllVersionsTooNew(t *testing.T) {
+	handler := newNpmCooldownHandler(nil)
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-1 * 24 * time.Hour), // too new
+		"1.0.1": now.Add(-2 * 24 * time.Hour), // too new
+	}
+	distTags := map[string]string{"latest": "1.0.1"}
+	body := buildTestPackument(versions, distTags)
+
+	dates, err := handler.parseMetadataTime(body)
+	require.NoError(t, err)
+
+	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	assert.Equal(t, 2, stripped)
+	assert.Equal(t, 0, remaining)
+
+	var result map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(newBody, &result))
+
+	var resultDistTags map[string]string
+	require.NoError(t, json.Unmarshal(result["dist-tags"], &resultDistTags))
+	// No eligible version exists, dist-tag should be removed
+	assert.Empty(t, resultDistTags)
+}
+
+func TestStripCooldownVersions_NoVersionsTooNew(t *testing.T) {
+	handler := newNpmCooldownHandler(nil)
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-10 * 24 * time.Hour), // old enough
+		"1.0.1": now.Add(-20 * 24 * time.Hour), // old enough
+	}
+	distTags := map[string]string{"latest": "1.0.0"}
+	body := buildTestPackument(versions, distTags)
+
+	dates, err := handler.parseMetadataTime(body)
+	require.NoError(t, err)
+
+	newBody, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	assert.Equal(t, 0, stripped)
+	assert.Equal(t, 2, remaining)
+	assert.Equal(t, body, newBody) // body unchanged
+}
+
+func TestStripCooldownVersions_SingleVersionInCooldown(t *testing.T) {
+	handler := newNpmCooldownHandler(nil)
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-1 * 24 * time.Hour), // too new
+	}
+	distTags := map[string]string{"latest": "1.0.0"}
+	body := buildTestPackument(versions, distTags)
+
+	dates, err := handler.parseMetadataTime(body)
+	require.NoError(t, err)
+
+	_, stripped, remaining := handler.stripCooldownVersions(body, dates, 5)
+	assert.Equal(t, 1, stripped)
+	assert.Equal(t, 0, remaining)
+}
+
+func TestStripCooldownVersions_MalformedJSON(t *testing.T) {
+	handler := newNpmCooldownHandler(nil)
+	body := []byte(`not-json`)
+	dates := map[string]time.Time{"1.0.0": time.Now().Add(-1 * time.Hour)}
+
+	newBody, stripped, _ := handler.stripCooldownVersions(body, dates, 5)
+	assert.Equal(t, 0, stripped)
+	assert.Equal(t, body, newBody)
+}
+
+func makeTestRequestContext(rawURL string) *proxy.RequestContext {
+	u := mustParseURL(rawURL)
+	return &proxy.RequestContext{
+		URL:       u,
+		Method:    "GET",
+		Headers:   http.Header{},
+		Hostname:  u.Host,
+		RequestID: "test-req-1",
+		StartTime: time.Now(),
+	}
+}
+
+func TestNpmCooldown_HandleMetadataRequest_OverridesHeaders(t *testing.T) {
+	collector := NewAnalysisStatsCollector()
+	handler := newNpmCooldownHandler(collector)
+
+	ctx := makeTestRequestContext("https://registry.npmjs.org/lodash")
+	ctx.Headers.Set("Accept", "application/vnd.npm.install-v1+json")
+	ctx.Headers.Set("Accept-Encoding", "gzip")
+
+	resp, err := handler.HandleMetadataRequest(ctx, "lodash", 5)
+	require.NoError(t, err)
+	assert.Equal(t, proxy.ActionModifyResponse, resp.Action)
+	assert.Equal(t, "application/json", ctx.Headers.Get("Accept"))
+	assert.Equal(t, "identity", ctx.Headers.Get("Accept-Encoding"))
+}
+
+func TestNpmCooldown_HandleMetadataRequest_StripsRecentVersions(t *testing.T) {
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-30 * 24 * time.Hour), // old
+		"1.0.1": now.Add(-1 * 24 * time.Hour),  // too new
+	}
+	distTags := map[string]string{"latest": "1.0.1"}
+	body := buildTestPackument(versions, distTags)
+
+	collector := NewAnalysisStatsCollector()
+	handler := newNpmCooldownHandler(collector)
+	ctx := makeTestRequestContext("https://registry.npmjs.org/testpkg")
+
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5)
+	require.NoError(t, err)
+	require.NotNil(t, resp.ResponseModifier)
+
+	newStatus, newHeaders, newBody, err := resp.ResponseModifier(200, http.Header{}, body)
+	require.NoError(t, err)
+	assert.Equal(t, 200, newStatus)
+	_ = newHeaders
+
+	var result map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(newBody, &result))
+
+	var resultVersions map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(result["versions"], &resultVersions))
+	assert.Contains(t, resultVersions, "1.0.0")
+	assert.NotContains(t, resultVersions, "1.0.1")
+
+	var resultDistTags map[string]string
+	require.NoError(t, json.Unmarshal(result["dist-tags"], &resultDistTags))
+	assert.Equal(t, "1.0.0", resultDistTags["latest"])
+}
+
+func TestNpmCooldown_HandleMetadataRequest_NoVersionsInCooldown(t *testing.T) {
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-30 * 24 * time.Hour), // old
+		"1.0.1": now.Add(-20 * 24 * time.Hour), // old
+	}
+	distTags := map[string]string{"latest": "1.0.1"}
+	body := buildTestPackument(versions, distTags)
+
+	collector := NewAnalysisStatsCollector()
+	handler := newNpmCooldownHandler(collector)
+	ctx := makeTestRequestContext("https://registry.npmjs.org/testpkg")
+
+	resp, err := handler.HandleMetadataRequest(ctx, "testpkg", 5)
+	require.NoError(t, err)
+	require.NotNil(t, resp.ResponseModifier)
+
+	_, _, newBody, err := resp.ResponseModifier(200, http.Header{}, body)
+	require.NoError(t, err)
+	assert.Equal(t, body, newBody)
+}
+
+func TestNpmCooldown_HandleMetadataRequest_AllVersionsInCooldown_RecordsStats(t *testing.T) {
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-1 * 24 * time.Hour), // too new
+	}
+	distTags := map[string]string{"latest": "1.0.0"}
+	body := buildTestPackument(versions, distTags)
+
+	collector := NewAnalysisStatsCollector()
+	handler := newNpmCooldownHandler(collector)
+	ctx := makeTestRequestContext("https://registry.npmjs.org/newpkg")
+
+	resp, err := handler.HandleMetadataRequest(ctx, "newpkg", 5)
+	require.NoError(t, err)
+	require.NotNil(t, resp.ResponseModifier)
+
+	_, _, _, err = resp.ResponseModifier(200, http.Header{}, body)
+	require.NoError(t, err)
+
+	blocks := collector.GetCooldownBlocks()
+	require.Len(t, blocks, 1)
+	assert.Equal(t, "newpkg", blocks[0].Name)
+	assert.Equal(t, "1.0.0", blocks[0].Version)
+	assert.Equal(t, 5, blocks[0].CooldownDays)
+
+	stats := collector.GetStats()
+	assert.Equal(t, 1, stats.CooldownBlockedCount)
+	assert.Equal(t, 1, stats.BlockedCount)
+}
+
+func TestNpmCooldown_HandleMetadataRequest_AllVersionsInCooldown_ReportsOldestVersion(t *testing.T) {
+	now := time.Now()
+	versions := map[string]time.Time{
+		"1.0.0": now.Add(-90 * 24 * time.Hour), // oldest — closest to exiting cooldown
+		"2.0.0": now.Add(-30 * 24 * time.Hour),
+		"2.1.0": now.Add(-1 * 24 * time.Hour), // newest — farthest from exiting cooldown
+	}
+	distTags := map[string]string{"latest": "2.1.0"}
+	body := buildTestPackument(versions, distTags)
+
+	collector := NewAnalysisStatsCollector()
+	handler := newNpmCooldownHandler(collector)
+	ctx := makeTestRequestContext("https://registry.npmjs.org/multipkg")
+
+	resp, err := handler.HandleMetadataRequest(ctx, "multipkg", 100)
+	require.NoError(t, err)
+
+	_, _, _, err = resp.ResponseModifier(200, http.Header{}, body)
+	require.NoError(t, err)
+
+	blocks := collector.GetCooldownBlocks()
+	require.Len(t, blocks, 1)
+	assert.Equal(t, "1.0.0", blocks[0].Version, "should report oldest version (closest to exiting cooldown)")
+}
+
+func TestNpmCooldown_HandleMetadataRequest_MalformedJSON_FailOpen(t *testing.T) {
+	body := []byte(`not-json`)
+	collector := NewAnalysisStatsCollector()
+	handler := newNpmCooldownHandler(collector)
+	ctx := makeTestRequestContext("https://registry.npmjs.org/badpkg")
+
+	resp, err := handler.HandleMetadataRequest(ctx, "badpkg", 5)
+	require.NoError(t, err)
+	require.NotNil(t, resp.ResponseModifier)
+
+	_, _, newBody, err := resp.ResponseModifier(200, http.Header{}, body)
+	require.NoError(t, err)
+	assert.Equal(t, body, newBody)
+}
+
+func TestNpmCooldown_InterceptorDelegation_CooldownEnabled(t *testing.T) {
+	setCooldownConfig(t, config.DependencyCooldownConfig{Enabled: true, Days: 5})
+
+	interceptor := NewNpmRegistryInterceptor(nil, NewInMemoryAnalysisCache(), NewAnalysisStatsCollector(), make(chan *ConfirmationRequest, 1))
+
+	ctx := makeTestRequestContext("https://registry.npmjs.org/lodash")
+	ctx.Hostname = "registry.npmjs.org"
+	ctx.Headers.Set("Accept", "application/vnd.npm.install-v1+json")
+
+	resp, err := interceptor.HandleRequest(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, proxy.ActionModifyResponse, resp.Action)
+	assert.Equal(t, "application/json", ctx.Headers.Get("Accept"))
+}
+
+func TestNpmCooldown_InterceptorDelegation_CooldownDisabled(t *testing.T) {
+	setCooldownConfig(t, config.DependencyCooldownConfig{Enabled: false, Days: 5})
+
+	interceptor := NewNpmRegistryInterceptor(nil, NewInMemoryAnalysisCache(), NewAnalysisStatsCollector(), make(chan *ConfirmationRequest, 1))
+
+	ctx := makeTestRequestContext("https://registry.npmjs.org/lodash")
+	ctx.Hostname = "registry.npmjs.org"
+	ctx.Headers.Set("Accept", "application/vnd.npm.install-v1+json")
+
+	resp, err := interceptor.HandleRequest(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, proxy.ActionAllow, resp.Action)
+	// Accept header should NOT be modified when cooldown is disabled
+	assert.Equal(t, "application/vnd.npm.install-v1+json", ctx.Headers.Get("Accept"))
+}
+
+func TestNpmCooldown_TarballRequestBypassesCooldown(t *testing.T) {
+	setCooldownConfig(t, config.DependencyCooldownConfig{Enabled: true, Days: 5})
+
+	// Use InsecureInstallation to skip the analyzer (which would fail without a real backend)
+	origInsecure := config.Get().InsecureInstallation
+	config.Get().InsecureInstallation = true
+	t.Cleanup(func() { config.Get().InsecureInstallation = origInsecure })
+
+	interceptor := NewNpmRegistryInterceptor(nil, NewInMemoryAnalysisCache(), NewAnalysisStatsCollector(), make(chan *ConfirmationRequest, 1))
+
+	// Tarball URL has a version component
+	ctx := makeTestRequestContext("https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz")
+	ctx.Hostname = "registry.npmjs.org"
+
+	resp, err := interceptor.HandleRequest(ctx)
+	require.NoError(t, err)
+	// Tarball should be allowed (bypasses cooldown, goes to analysis)
+	assert.Equal(t, proxy.ActionAllow, resp.Action)
+	// Accept header should not be set to application/json for tarball requests
+	assert.NotEqual(t, proxy.ActionModifyResponse, resp.Action)
+}
+
+func TestIsWithinCooldown(t *testing.T) {
+	h := newNpmCooldownHandler(nil)
+	now := time.Now()
+	day := 24 * time.Hour
+
+	tests := []struct {
+		name                 string
+		publishDate          time.Time
+		cooldownDays         int
+		wantWithinCooldown   bool
+		wantDaysSincePublish int
+		wantDaysRemaining    int
+	}{
+		{
+			name:                 "published today with 30 day cooldown",
+			publishDate:          now,
+			cooldownDays:         30,
+			wantWithinCooldown:   true,
+			wantDaysSincePublish: 0,
+			wantDaysRemaining:    30,
+		},
+		{
+			name:                 "published exactly at cooldown boundary",
+			publishDate:          now.Add(-30 * day),
+			cooldownDays:         30,
+			wantWithinCooldown:   false,
+			wantDaysSincePublish: 30,
+			wantDaysRemaining:    0,
+		},
+		{
+			name:                 "published one day before cooldown expires",
+			publishDate:          now.Add(-29 * day),
+			cooldownDays:         30,
+			wantWithinCooldown:   true,
+			wantDaysSincePublish: 29,
+			wantDaysRemaining:    1,
+		},
+		{
+			name:                 "published well beyond cooldown",
+			publishDate:          now.Add(-365 * day),
+			cooldownDays:         30,
+			wantWithinCooldown:   false,
+			wantDaysSincePublish: 365,
+			wantDaysRemaining:    0,
+		},
+		{
+			name:                 "zero cooldown days",
+			publishDate:          now,
+			cooldownDays:         0,
+			wantWithinCooldown:   false,
+			wantDaysSincePublish: 0,
+			wantDaysRemaining:    0,
+		},
+		{
+			name:                 "future publish date is clamped to zero days",
+			publishDate:          now.Add(5 * day),
+			cooldownDays:         30,
+			wantWithinCooldown:   true,
+			wantDaysSincePublish: 0,
+			wantDaysRemaining:    30,
+		},
+		{
+			name:                 "large cooldown days that previously caused overflow",
+			publishDate:          now.Add(-10 * day),
+			cooldownDays:         1000000,
+			wantWithinCooldown:   true,
+			wantDaysSincePublish: 10,
+			wantDaysRemaining:    999990,
+		},
+		{
+			name:                 "max int cooldown days does not overflow",
+			publishDate:          now.Add(-1 * day),
+			cooldownDays:         int(^uint(0) >> 1), // math.MaxInt
+			wantWithinCooldown:   true,
+			wantDaysSincePublish: 1,
+			wantDaysRemaining:    int(^uint(0)>>1) - 1,
+		},
+		{
+			name:                 "very old publish date well past cooldown",
+			publishDate:          now.Add(-3652 * day),
+			cooldownDays:         30,
+			wantWithinCooldown:   false,
+			wantDaysSincePublish: 3652,
+			wantDaysRemaining:    0,
+		},
+		{
+			name:                 "one day cooldown with publish yesterday",
+			publishDate:          now.Add(-1 * day),
+			cooldownDays:         1,
+			wantWithinCooldown:   false,
+			wantDaysSincePublish: 1,
+			wantDaysRemaining:    0,
+		},
+		{
+			name:                 "one day cooldown with publish today",
+			publishDate:          now,
+			cooldownDays:         1,
+			wantWithinCooldown:   true,
+			wantDaysSincePublish: 0,
+			wantDaysRemaining:    1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			withinCooldown, daysSincePublish, daysRemaining := h.isWithinCooldown(tt.publishDate, tt.cooldownDays)
+			assert.Equal(t, tt.wantWithinCooldown, withinCooldown, "withinCooldown")
+			assert.Equal(t, tt.wantDaysSincePublish, daysSincePublish, "daysSincePublish")
+			assert.Equal(t, tt.wantDaysRemaining, daysRemaining, "daysRemaining")
+		})
+	}
+}
@@ -4,6 +4,7 @@ import (
 	packagev1 "buf.build/gen/go/safedep/api/protocolbuffers/go/safedep/messages/package/v1"
 	"github.com/safedep/dry/log"
 	"github.com/safedep/pmg/analyzer"
+	pmgconfig "github.com/safedep/pmg/config"
 	"github.com/safedep/pmg/proxy"
 )

@@ -34,6 +35,7 @@ var npmRegistryDomains = registryConfigMap{
 // It embeds baseRegistryInterceptor to reuse ecosystem agnostic functionality
 type NpmRegistryInterceptor struct {
 	baseRegistryInterceptor
+	cooldownHandler *npmCooldownHandler
 }

 var _ proxy.Interceptor = (*NpmRegistryInterceptor)(nil)
@@ -54,6 +56,7 @@ func NewNpmRegistryInterceptor(
 			confirmationChan: confirmationChan,
 			circuitBreaker:   newAnalyzerCircuitBreaker("malysis-analyzer-npm"),
 		},
+		cooldownHandler: newNpmCooldownHandler(statsCollector),
 	}
 }

@@ -104,9 +107,13 @@ func (i *NpmRegistryInterceptor) HandleRequest(ctx *proxy.RequestContext) (*prox
 		return &proxy.InterceptorResponse{Action: proxy.ActionAllow}, nil
 	}

-	// Only analyze tarball downloads (these have a specific version)
-	// Metadata requests (without version) are allowed through
+	depCooldownConfig := pmgconfig.Get().Config.DependencyCooldown
+
 	if !pkgInfo.IsFileDownload() {
+		if depCooldownConfig.Enabled {
+			return i.cooldownHandler.HandleMetadataRequest(ctx, pkgInfo.GetName(), depCooldownConfig.Days)
+		}
+
 		log.Debugf("[%s] Skipping analysis for metadata request: %s", ctx.RequestID, pkgInfo.GetName())
 		return &proxy.InterceptorResponse{Action: proxy.ActionAllow}, nil
 	}
@@ -2,17 +2,20 @@ package interceptors

 import (
 	"sync"
+	"time"

 	"github.com/safedep/pmg/analyzer"
+	"github.com/safedep/pmg/internal/models"
 )

 // AnalysisStats contains aggregated statistics from analysis results
 type AnalysisStats struct {
-	TotalAnalyzed      int
-	AllowedCount       int
-	ConfirmedCount     int
-	BlockedCount       int
-	UserCancelledCount int
+	TotalAnalyzed        int
+	AllowedCount         int
+	ConfirmedCount       int
+	BlockedCount         int
+	UserCancelledCount   int
+	CooldownBlockedCount int
 }

 // AnalysisStatsCollector tracks analysis statistics during proxy execution.
@@ -23,6 +26,7 @@ type AnalysisStatsCollector struct {
 	stats             AnalysisStats
 	blockedPackages   []*analyzer.PackageVersionAnalysisResult
 	confirmedPackages []*analyzer.PackageVersionAnalysisResult
+	cooldownBlocks    []models.CooldownBlock
 }

 // NewAnalysisStatsCollector creates a new stats collector
@@ -118,3 +122,31 @@ func (c *AnalysisStatsCollector) GetConfirmedPackages() []*analyzer.PackageVersi
 	copy(result, c.confirmedPackages)
 	return result
 }
+
+// RecordCooldownBlocked records a package blocked by the dependency cooldown policy.
+func (c *AnalysisStatsCollector) RecordCooldownBlocked(name, version string, publishDate time.Time, daysAgo, daysLeft, cooldownDays int) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.stats.TotalAnalyzed++
+	c.stats.BlockedCount++
+	c.stats.CooldownBlockedCount++
+	c.cooldownBlocks = append(c.cooldownBlocks, models.CooldownBlock{
+		Name:         name,
+		Version:      version,
+		PublishDate:  publishDate,
+		DaysAgo:      daysAgo,
+		DaysLeft:     daysLeft,
+		CooldownDays: cooldownDays,
+	})
+}
+
+// GetCooldownBlocks returns all packages blocked by the cooldown policy.
+func (c *AnalysisStatsCollector) GetCooldownBlocks() []models.CooldownBlock {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	result := make([]models.CooldownBlock, len(c.cooldownBlocks))
+	copy(result, c.cooldownBlocks)
+	return result
+}
@@ -1,9 +1,11 @@
 package proxy

 import (
+	"bytes"
 	"context"
 	"crypto/tls"
 	"fmt"
+	"io"
 	"net"
 	"net/http"
 	"net/url"
@@ -518,9 +520,33 @@ func (ps *proxyServer) registerHandlers() {
 			return resp
 		}

-		// TODO: Implement response body modification
-		// This requires buffering the response body, modifying it, and creating a new response
-		// For now, lets skip it
+		body, err := io.ReadAll(resp.Body)
+		if closeErr := resp.Body.Close(); closeErr != nil {
+			log.Warnf("[%s] Failed to close response body: %v", reqCtx.RequestID, closeErr)
+		}
+		if err != nil {
+			log.Errorf("[%s] Failed to read response body for modifier: %v", reqCtx.RequestID, err)
+			errMsg := []byte("PMG: failed to read response from upstream registry")
+			resp.StatusCode = http.StatusServiceUnavailable
+			resp.Status = ""
+			resp.Body = io.NopCloser(bytes.NewReader(errMsg))
+			resp.ContentLength = int64(len(errMsg))
+			return resp
+		}
+
+		newStatusCode, newHeaders, newBody, err := modifier(resp.StatusCode, resp.Header, body)
+		if err != nil {
+			log.Errorf("[%s] Response modifier error: %v", reqCtx.RequestID, err)
+			resp.Body = io.NopCloser(bytes.NewReader(body))
+			resp.ContentLength = int64(len(body))
+			return resp
+		}
+
+		resp.StatusCode = newStatusCode
+		resp.Status = ""
+		resp.Header = newHeaders
+		resp.Body = io.NopCloser(bytes.NewReader(newBody))
+		resp.ContentLength = int64(len(newBody))

 		return resp
 	})