Add pre-mirror decision hooks before caching artifacts

[rams3sh]

Why

proxy mirror can pre-populate the cache from PURLs or SBOMs, but there is no decision point before artifacts are fetched and stored.

Mirroring makes artifacts available from the proxy cache. For security-sensitive environments, some checks need to happen before that point, not after. Examples include threat-intel checks, malware verdicts, vulnerability policy, license policy, internal allow/deny lists, and manual approval workflows. Once an artifact is mirrored, it becomes available from cache, so the check needs to happen before download/cache, not after.

While security is the primary use case for this feature request, the decision hook could support any workflow that requires an explicit decision before mirroring proceeds.

Current Workaround
Current workaround is to wrap proxy mirror outside the tool, but that does not cover the Mirror API cleanly and duplicates mirror resolution logic.

Possible Direction

Introduce a pre-mirror decision hook, similar in spirit to Git’s pre-commit / pre-push hooks.

The goal is to provide a blocking decision point before proxy mirror downloads and caches artifacts. This would allow operators to call an external security or policy service and wait for an explicit allow/deny decision before the mirror proceeds.

Add a configurable pre-mirror hook that runs after mirror input is resolved to package versions, but before artifact fetch/cache begins.

This feature request is intentionally limited to the concept and use case. The exact API shape, timeout behavior, need for polling, request/response schema, and implementation details can be discussed separately.

[andrew]

Agree on the concept of the feature, the hard bit is deciding how to implement the policies for the automated decision making, there are many different approaches in the wild but not an obvious winner: https://nesbitt.io/2026/03/19/the-fragmented-world-of-dependency-policy.html

[rams3sh]

Agree that policy implementation is the hard part, and that is exactly why I think this should be a decision hook rather than a built-in policy framework.

The proposal is not for proxy to define a dependency policy language or own the policy engine. proxy would only provide a blocking pre-mirror decision point with the resolved package/artifact context. Operators could then call whatever external policy, threat-intel, approval, or internal workflow service they use, and return an allow/deny decision.

That keeps proxy focused on mirroring while avoiding yet another dependency-policy format.

Roughly, the flow I had in mind is:

1. proxy resolves the mirror request to package/artifact context.
2. Before fetching or caching the artifact, proxy dispatches a configured pre-mirror webhook.
3. The webhook payload includes relevant context such as package name, version, ecosystem, source URL, checksums, requested artifact, etc.
4. The external service evaluates that context using its own logic.
5. The service returns a decision, for example:

  {
    "decision": "deny",
    "justification": "Package does not meet internal policy requirements."
  }

Think of it as similar to a Kubernetes admission controller. Operators can plug in the decision engine of their choice, register it as a validation webhook, and let it decide what is allowed before the action proceeds.

The exact schema, timeout behavior, retries, polling model, and failure mode can be discussed separately. The key point is that proxy provides the blocking decision point, while policy evaluation remains external and user-defined.