Dependency policies

[ericmj]

Adds client-side enforcement of dependency policies. A policy is defined on hex.pm under an organization (or on any self-hosted repo) and fetched through the registry at resolution time. The client filters candidate versions the policy blocks before the solver sees them, so resolution simply never picks them.

Per repository, a policy can express:

• a cooldown (minimum age before a newly published version becomes eligible)
• an advisory rule (block versions with security advisories at or above a severity threshold, or with any advisory)
• a retirement rule (block versions retired for the configured reasons)
• package/version overrides (allow or deny exceptions; the most specific match wins, and an allow exempts the release from the restriction entirely)

Versions already in the lockfile are exempt from filtering, so re-resolution keeps a locked-but-now-blocked entry instead of failing. Policies have a visibility: public policies are fetchable anonymously, private ones require authentication to the owning organization.

Configuring the policy

A project has exactly one active policy, resolved with the usual Hex config precedence: env var, then mix.exs, then global config.

HEX_POLICY env var, a REPO/NAME pair. Overrides everything for the invocation, and an empty value disables the configured policy:

$ HEX_POLICY=hexpm:myorg/strict-prod mix deps.get
$ HEX_POLICY= mix deps.get

mix.exs :hex block, with org: for a hexpm organization or repo: for any configured repo:

defp project() do
  [hex: [policy: [org: "myorg", name: "strict-prod"]]]
end

mix hex.config, stored in the global Hex config:

$ mix hex.config policy hexpm:myorg/strict-prod

The bare hexpm repo is rejected in all forms: the global repository has no organization-scoped policies, so policies live under hexpm:<org> or a self-hosted repo.

New mix tasks

mix hex.policy show summarizes the active policy: its visibility, the per-repository restrictions (cooldown, advisory rule, retirement rule) and override counts, plus the effective cooldown, which is the strictest of the local cooldown config and the policy's own.

mix hex.policy why PACKAGE (or REPO/PACKAGE) walks every version of the package in the registry, classifies each against the active policy, and prints a per-version table:

Versions of "plug" (47):

Version  Status   Blocked by
1.16.0   ALLOWED
1.17.0   BLOCKED  retirement: security
1.18.0   BLOCKED  advisory ≥ high, cooldown 14d; eligible 2026-06-20

This is the uncapped companion to the resolution output below. mix hex.config policy reads and writes the setting like any other config key.

How policies surface in mix deps.get

After a successful resolution, a summary block reports the active policy, the cooldown it imposes (a locally configured cooldown keeps its own existing report), and every candidate version it hid, capped at the 5 newest per package:

Active policy: hexpm:myorg/strict-prod
Effective cooldown: 14d (hexpm:myorg/strict-prod)
Policy hid 7 candidate versions:
  phoenix 1.8.1 — cooldown 14d; eligible 2026-06-18
  plug 1.18.0 — advisory ≥ high
  ...and 5 more — run `mix hex.policy why plug`

When resolution fails and the policy hid versions of the packages involved, the solver's failure message is followed by a note attributing the hidden versions, in the same capped format, so a "no compatible versions" error explains itself:

Note: active policy hides 3 versions of "plug":
  plug 1.18.0 — advisory ≥ high
  ...

Because a policy is an enforcement feature, anything short of materializing it fails closed rather than resolving unenforced:

• a malformed config value aborts with Invalid policy configuration: ... and the expected formats
• a failed fetch prints Failed to fetch policy REPO/NAME from registry and aborts, unless a previously fetched copy is cached, in which case the cache is used and the message says so
• on a 404 or 401 the error explains the policy may not exist, may be misspelled, or may be private without sufficient permissions, and points at mix hex.user auth when no authenticated user is present

[maennchen]

Should this be a helper module in hex_core?

[ericmj]

Yes, we can move there it in the future.