pmg/proxy/interceptors/npm_cooldown.go

package interceptors

import (
	"encoding/json"
	"fmt"
	"net/http"
	"time"

	packagev1 "buf.build/gen/go/safedep/api/protocolbuffers/go/safedep/messages/package/v1"
	"github.com/safedep/dry/log"
	pmgconfig "github.com/safedep/pmg/config"
	"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. Skip-list
// semantics are handled here so callers do not need to consult the config.
func (h *npmCooldownHandler) HandleMetadataRequest(ctx *proxy.RequestContext, packageName string, cooldownDays int, pinnedVersion string) (*proxy.InterceptorResponse, error) {
	skip := pmgconfig.CooldownSkip(packagev1.Ecosystem_ECOSYSTEM_NPM, packageName)
	if skip.SkipAll {
		// Whole package is on the cooldown skip list: pass metadata through
		// unmodified. The tarball download still hits analyzePackage, so malware
		// analysis is preserved.
		return &proxy.InterceptorResponse{Action: proxy.ActionAllow}, nil
	}

	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")

	// Strip conditional-GET headers so the registry cannot return 304 Not Modified.
	// A 304 has no body — the modifier would receive an empty body, fail to parse
	// it as JSON, and fail-open, letting the client use its cached (unfiltered)
	// response. Removing these forces a full 200 response on every request.
	ctx.Headers.Del("If-None-Match")
	ctx.Headers.Del("If-Modified-Since")

	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)

		exempt := cooldownExemptVersions(packagev1.Ecosystem_ECOSYSTEM_NPM, packageName, skip, dates, cooldownDays)
		auditCooldownSkips(ctx.RequestID, packagev1.Ecosystem_ECOSYSTEM_NPM, packageName, exempt)
		strippedBody, stripped, remaining := h.stripCooldownVersions(body, dates, cooldownDays, exempt.all)
		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)

			recordCooldownStats(h.statsCollector, packagev1.Ecosystem_ECOSYSTEM_NPM, packageName, pinnedVersion, dates, remaining, 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, exemptVersions map[string]bool) ([]byte, int, int) {
	tooNew := make(map[string]bool)
	for version, publishDate := range dates {
		// Version-pinned skip entries are never stripped, even inside the window.
		if exemptVersions[version] {
			continue
		}
		if withinCooldown, _, _ := cooldownIsWithinWindow(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
	}

	// survivingVersions holds the version keys still present in the "versions" object
	// after stripping. It is nil if the field is missing or unparseable, in which case
	// dist-tag repair falls back to the publish-date set. When non-nil it bounds the
	// repair candidates so a repaired dist-tag never points to a version absent from
	// the packument (e.g. an unpublished version whose "time" entry lingers).
	var survivingVersions map[string]bool

	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)
			}
			survivingVersions = make(map[string]bool, len(versions))
			for v := range versions {
				survivingVersions[v] = true
			}
			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

			// Repair the latest tag only when it points at a stripped version.
			// The eligible-version scan and semver parsing are deferred to this
			// branch so an unaffected latest tag costs nothing.
			if latest, ok := distTags["latest"]; ok && tooNew[latest] {
				eligible := make([]string, 0, len(dates))
				for v := range dates {
					if tooNew[v] {
						continue
					}
					if survivingVersions != nil && !survivingVersions[v] {
						continue // not in the packument's versions — would dangle
					}
					eligible = append(eligible, v)
				}

				if latestStable := cooldownHighestStableVersion(eligible, latest); latestStable != "" {
					// Repair latest to the highest stable eligible version so
					// `npm install <pkg>` resolves a real release — never a
					// more-recently-published prerelease or platform-specific
					// build (see #275).
					log.Infof("Cooldown: repaired dist-tag latest %s -> %s for stripped version", latest, latestStable)
					distTags["latest"] = latestStable
				} else {
					// No stable version survives — drop the tag so npm fails
					// cleanly instead of mis-resolving.
					log.Infof("Cooldown: removed dist-tag latest (was %s, no eligible stable version remains)", latest)
					delete(distTags, "latest")
				}
				changed = true
			}

			// Drop any non-latest tag (beta, next, platform tags) whose target was
			// stripped: an explicit `pkg@<tag>` request for a version in cooldown
			// should fail cleanly, not resolve to an unrelated version.
			for tag, version := range distTags {
				if tag != "latest" && tooNew[version] {
					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
}