feat(cooldown): respect trusted_packages in dependency cooldown (#342)

* feat(cooldown): respect trusted_packages in dependency cooldown

Trusted packages are now treated as a superset waiver that bypasses every
PMG control (malware analysis, cooldown, and any future controls). A
globally trusted package is automatically exempt from the cooldown window
and no longer needs a duplicate entry in dependency_cooldown.skip.

The skip list remains the narrower, cooldown-only waiver for packages
that must bypass the cooldown wait but still be malware-scanned.

* refactor(cooldown): tag skip reason and audit-log skipped packages

Address review feedback on #342:

- Restore cooldownSkip to a pure single-list function (SRP); the merge
  into trusted_packages now happens in a separate mergeCooldownSkip step,
  driven by the exported CooldownSkip wrapper.
- Extend CooldownSkipInfo with a CooldownSkipReason (TrustedPackage /
  CooldownSkipList) on both SkipAll and per-version entries, so callers
  can tell apart the broad waiver from the cooldown-only one. When both
  lists match the same package, trusted_packages wins.
- Add audit.LogCooldownSkipped and emit it from the npm and PyPI
  interceptors on the SkipAll path, alongside the existing info log,
  carrying the source list as the reason.

* refactor(cooldown): inline list merge, audit per-version exemptions

Address further review feedback:

- Drop the separate mergeCooldownSkip helper; cooldownSkip now writes
  into a shared *CooldownSkipInfo and is called twice from CooldownSkip
  (cooldown skip list first, trusted_packages on top so trusted entries
  override the reason on overlap).
- Audit log every exemption, not just SkipAll: a new auditCooldownSkip
  helper in proxy/interceptors/cooldown.go emits one event per match
  (package-wide or per-version), each tagged with its source list.
  LogCooldownSkipped gains a version argument for the per-version case.
- Cover the trusted_packages reason path in TestCooldownSkip.

* fix(cooldown): avoid double-auditing trusted package exemptions

auditCooldownSkip now only emits EventTypeCooldownSkipped for entries
that came from dependency_cooldown.skip. Trusted-package exemptions
already get an EventTypeInstallTrustedAllowed event at tarball-download
time (proxy/interceptors/base_registry.go), so emitting a cooldown event
for them too would double-count the same waiver.

* emit trusted and cooldown skip events to cloud

* fix tests

* refactor(cooldown): return value from collectCooldownSkip, short-circuit on trusted SkipAll

Address PR review feedback:
- Rename cooldownSkip to collectCooldownSkip and return CooldownSkipInfo
  instead of mutating an input pointer.
- Add mergeCooldownSkip to combine per-list results with trusted_packages
  taking precedence on overlap.
- CooldownSkip now consults trusted_packages first and returns immediately
  on a package-wide trusted exemption (DC skip list cannot add anything).
- Extend tests to cover disjoint pinned entries across both lists and the
  case where DC version-less subsumes a trusted pinned entry.

* fix(audit): address cooldown review feedback

* fix(cooldown): audit cooldown skips at download time with concrete version

Backend rejects PackageVersion messages without a version, and audit logs
should reflect the runtime fact (a specific version was skipped) rather
than the config rule. Move the audit emission from metadata-request
handling to download-request handling, where the concrete version is
known, and require version in LogCooldownSkipped.

* chore(audit): drop dead scope assignment in LogCooldownSkipped

* refactor(cooldown): move skip-list logic into cooldown handlers

Registry interceptors no longer compute CooldownSkip or branch on SkipAll;
they just call HandleMetadataRequest. The npm and pypi cooldown handlers
own the skip lookup, the package-wide exemption short-circuit, and (for
pypi) the canonical-name denormalization. Also align LogCooldownSkipped
with other LogXxx signatures by taking *packagev1.PackageVersion.

* fix: Simplify audit logging for dependency cooldown skip

* refactor: Simplify cooldown handling and maintain separation of concepts for trusted and DC skip packages

* fix: Code review fixes

* fix: Emit cooldown skipped audit event ONLY when an in-window version is skipped

---------

Co-authored-by: Abhisek Datta <abhisek.datta@gmail.com>

docs/dependency-cooldown.md

@@ -37,15 +37,19 @@ dependency_cooldown:
 ```
 
 The skip list is a **per-control exemption**: packages on it **skip only the
-cooldown window — they are still analyzed for malware.** It is independent of the
-top-level [`trusted_packages`](trusted-packages.md), which waives malware
-analysis. There is a single definition of a trusted package (the top-level list);
-this is just a cooldown skip list.
+cooldown window — they are still analyzed for malware.** Use it when you want a
+package to bypass cooldown but still go through every other security control.
 
-| List | Waives malware analysis | Waives cooldown |
-| --- | --- | --- |
-| `trusted_packages` (top level) | yes | no |
-| `dependency_cooldown.skip` | no | yes |
+If you want a package to bypass **every** control PMG enforces — malware
+analysis, dependency cooldown, and any future policies — add it to the
+top-level [`trusted_packages`](trusted-packages.md) list instead. A globally
+trusted package is automatically exempted from the cooldown window without
+needing a separate entry here.
+
+| List | Waives malware analysis | Waives cooldown | Waives future controls |
+| --- | --- | --- | --- |
+| `trusted_packages` (top level) | yes | yes | yes |
+| `dependency_cooldown.skip` | no | yes | no |
 
 Matching:
 

docs/trusted-packages.md

@@ -1,6 +1,15 @@
 # Trusted Packages
 
-`pmg` allows you to trust a package. Trusted packages are not scanned and always allowed to be installed.
+`pmg` allows you to trust a package. A trusted package bypasses **every**
+control PMG enforces: it is not scanned for malware, it is exempt from the
+[dependency cooldown](dependency-cooldown.md) window, and it will be exempted
+from any future controls PMG adds. Use this list for packages you fully vouch
+for — typically first-party packages or vendored internal dependencies.
+
+If you only want to waive a single control (for example, install a package
+immediately without waiting out the cooldown, but still have it analyzed for
+malware), use the per-control skip list for that control instead — e.g.
+[`dependency_cooldown.skip`](dependency-cooldown.md#exempting-specific-packages).
 
 ## Configuration