Policy overview

A namespace policy turns the registry into a gate. Without a policy, every version a reader is entitled to is visible. With one, each version is either:

• Promoted: passes every rule; visible and resolvable by consumers.
• Held: fails at least one rule; stored and inspectable by owners, invisible to consumers.

Policy is evaluated deterministically on every read. Nothing needs to be re-run when conditions change: when a quarantine expires, an advisory is withdrawn, or an approval lands, the version promotes on the next read, instantly.

On publish namespaces, a few rules can additionally reject at publish instead of holding. Versions are immutable, so accepting a publish that can never pass burns its version number forever; when the failing fact is frozen into the tarball (vcs, license) or the remedy is a standing trust rather than a change to the version (new_publisher, vcs_downgrade, repository_change), rejecting keeps the number free: fix the problem and publish the same version again. Each of those rules has a reject toggle; see the rules reference. Mirrors never reject: there is no publish to refuse, so imported versions always hold at read time, and a mirror’s policy has no reject toggles.

Where to look

• The Held tab on the namespace lists everything currently held, why, and what would release each version. It opens on the versions still needing review, and an owner can accept a hold to take it out of that queue without releasing it; see Reviewing a hold.
• The crate page shows per-version status, hold reasons, remaining quarantine, and advisory badges.
• The Policy tab shows the namespace’s rules. Every reader of the namespace can see the policy; only owners can edit it.

How a hold clears

Each failing rule clears its own way:

1. By time: quarantine expires on its own.
2. By fixing the input: attach the missing SBOM, add attestations, or adjust the policy itself (for example, extend the license allowlist).
3. By manual promotion: owners can waive most rule failures for one specific version. When the number of distinct owner identities approving reaches the namespace’s threshold (2 by default), that rule failure is waived for that version. Partial approvals show their tally on the version until the threshold is met.
4. By standing trust: a new_publisher hold clears for all of a publisher’s versions once enough owners vouch for the publisher; a vcs_downgrade hold clears for all of a crate’s provenance-less versions once enough owners trust its new state; a repository_change hold clears for all versions declaring the new repository once enough owners trust that URL. These are standing trusts in the person or the crate’s new state, not one-version waivers. Any single owner can revoke one, and revocation re-holds whatever only that trust was releasing.

Advisory holds are the exception: they cannot be waived. No number of approvals promotes a version held by an advisory. Either the advisory is resolved upstream, or an owner allows that advisory’s id outright, from the Held tab or the policy’s ignored list, which stops it holding anything in the namespace. This keeps “we out-voted the CVE” from ever being a thing.

Designing a policy

Rules compose; a version must pass all of them. A reasonable starting point for a mirror: quarantine of a few days, advisory levels set to vulnerability and unsound, and publisher trust enabled. For a publish namespace: an SPDX license allowlist and require_clean_vcs. The full catalog of rules, defaults, and failure semantics is in the Policy rules reference.