Stop writing fileblob's .attrs sidecar (#328)

* Stop writing fileblob's .attrs sidecar

fileblob stores blob metadata in an ".attrs" file per object and rewrites
it with os.Create, truncating in place outside the atomic rename that
protects the blob. A read overlapping a write decodes a partial file and
fails with "opening reader: EOF", served as a 502. One writer against
four readers on a single key failed 408 of 2000 reads. cacheMetadataBlob
is most exposed to it, rewriting a key on every refresh while readers
are served from it.

Nothing in the proxy reads what the sidecar holds. gocloud.dev/blob is
imported only by internal/storage, Store sets no ContentType, and
Attributes is used only for Size, which comes from os.Stat. A missing
sidecar already defaults cleanly, so "metadata=skip" removes the hazard
rather than locking around it, and saves a write per store.

* Clear .attrs sidecars left by earlier versions

metadata=skip stops fileblob rewriting sidecars but does not delete ones
already on disk, so a sidecar left partial by an interrupted write now
fails every read of its key for good. Before, a later store repaired it
by rewriting.

Store therefore removes the sidecar for the key it writes. Removal is
atomic where the rewrite was not, so a concurrent reader gets the whole
old file or nothing. Delete already removes sidecars, so the two paths
drain a cache between them.

Deriving that path is necessary because fileblob's key escaping is
unexported. It is the identity for a plain key and parts from one only
for keys that are not valid local paths, which is what filepath.Localize
rejects. That also keeps the removal inside the cache directory: without
it a key holding ".." resolves outside.

The clearing test runs one key per storage path the proxy builds, seeded
through a bucket that still writes sidecars so the path under test is
fileblob's own.

* Explain why failed sidecar cleanup does not fail the store

Move the removal into clearLegacySidecar and say why its error is
dropped rather than returned. A failed removal leaves exactly the state
this change inherited, while failing the write would turn a cleanup miss
into a failed request.

Windows makes that concrete: Go opens files with FILE_SHARE_READ and
FILE_SHARE_WRITE but not FILE_SHARE_DELETE, so a reader holding the
sidecar open blocks deletion, and that reader is the workload this
change exists to protect. Propagating would fail stores during exactly
the overlap being fixed. The next store of the key retries.

A test pins it, using a non-empty directory at the sidecar path to make
os.Remove fail with something other than not-exist on any platform.

* Fail the concurrency test if its writer stops

The writer returned silently when Store failed, so the test could pass
with no concurrent writes at all. Its error is now reported, and the
test also checks that at least one write completed.

Reporting it showed the writer had been dying on Windows at its first
collision: Go opens files without FILE_SHARE_DELETE, so a reader holding
the file open makes the writer's rename fail with access denied. The
test now skips there, since it cannot contend a writer with readers on
that platform.

* Clear legacy sidecars for keys fileblob escapes

legacySidecarPath declined any key filepath.Localize rejects, which on
Windows is every key with a colon: OCI digests and Debian epochs. Their
sidecars were never cleared there, and a truncated one kept failing
reads, since fileblob still reads a sidecar it finds under metadata=skip.

fileblob hex-escapes such characters on the way to disk. The path is now
derived the same way, so the sidecar is looked for where fileblob wrote
it. Localize still validates the escaped form, which keeps the removal
inside the cache directory.

* Drop stale comment about declining colon keys on Windows

623ff3e made legacySidecarPath escape keys the way fileblob does, so
colon-bearing keys are now cleared on Windows and the OCI and Debian
rows in TestStoreClearsLegacyAttrsSidecar prove it. The comment
described the behaviour before that commit.

---------

Co-authored-by: Andrew Nesbitt <andrewnez@gmail.com>

.github/workflows/ci.yml

@@ -13,7 +13,6 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        go-version: ['1.25']
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -24,7 +23,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: ${{ matrix.go-version }}
+          go-version-file: go.mod
 
       - name: Build
         run: go build -v ./...
@@ -42,7 +41,35 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.25'
+          go-version-file: go.mod
 
       - name: golangci-lint
         run: go tool golangci-lint run ./...
+
+  helm:
+    name: Helm chart
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: azure/setup-helm@9bc31f4ebc9c6b171d7bfbaa5d006ae7abdb4310 # v5.0.1
+        with:
+          version: v3.18.6
+
+      - name: Lint chart
+        run: helm lint deploy/charts/proxy
+
+      - name: Render chart variants
+        run: |
+          set -euo pipefail
+          helm template proxy deploy/charts/proxy >/dev/null
+          helm template proxy deploy/charts/proxy \
+            --set persistence.enabled=false \
+            --set config.existingConfigMap=proxy-config \
+            --set ingress.enabled=true \
+            --set 'ingress.hosts[0].host=proxy.example.com' \
+            --set 'ingress.hosts[0].paths[0].path=/' \
+            --set 'ingress.hosts[0].paths[0].pathType=Prefix' \
+            >/dev/null

.github/workflows/publish.yml

@@ -26,12 +26,12 @@ jobs:
           persist-credentials: false
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
+        uses: docker/setup-qemu-action@1f40c72289eff860ee54a304f1438e3cff362e0a # v4.3.0
         with:
           platforms: linux/amd64,linux/arm64
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Log in to the Container registry
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f
@@ -96,3 +96,66 @@ jobs:
           for predicate in sbom-linux-amd64.spdx.json sbom-linux-arm64.spdx.json; do
             cosign attest --yes --type spdxjson --predicate "$predicate" "$reference"
           done
+
+  publish_chart:
+    name: Push Helm chart to GHCR
+    if: github.ref_type == 'tag'
+    needs: push_to_registry
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+
+      - uses: azure/setup-helm@9bc31f4ebc9c6b171d7bfbaa5d006ae7abdb4310 # v5.0.1
+        with:
+          version: v3.18.6
+
+      - name: Validate and normalize release version
+        id: version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          semver='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?$'
+          [[ "$TAG" =~ $semver ]] || {
+            echo "Tag must be strict SemVer of the form vMAJOR.MINOR.PATCH[-PRERELEASE]: $TAG" >&2
+            exit 1
+          }
+          version="${TAG#v}"
+          [[ "$version" != "0.0.0" ]] || {
+            echo "0.0.0 is a development placeholder and must not be published" >&2
+            exit 1
+          }
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to GHCR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: printf '%s' "$GH_TOKEN" | helm registry login ghcr.io --username "$GITHUB_ACTOR" --password-stdin
+
+      - name: Lint and package chart
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          helm lint deploy/charts/proxy
+          mkdir -p build
+          helm package \
+            --destination build \
+            --version "$VERSION" \
+            --app-version "$VERSION" \
+            deploy/charts/proxy
+          metadata="$(helm show chart "build/proxy-${VERSION}.tgz")"
+          [[ "$(awk '$1 == "version:" {print $2}' <<<"$metadata")" == "$VERSION" ]]
+          [[ "$(awk '$1 == "appVersion:" {gsub(/\"/, "", $2); print $2}' <<<"$metadata")" == "$VERSION" ]]
+
+      - name: Push chart
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: helm push "build/proxy-${VERSION}.tgz" oci://ghcr.io/git-pkgs/charts

.github/workflows/swagger.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
-          go-version: '1.25'
+          go-version-file: go.mod
 
       - name: Install swag
         run: go install github.com/swaggo/swag/cmd/swag@latest

.github/workflows/zizmor.yml

@@ -26,4 +26,4 @@ jobs:
           persist-credentials: false
 
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@6fc4b006235f201fdab3722e17240ab420d580e5 # v0.6.1
+        uses: zizmorcore/zizmor-action@70fb788f84895a7701f5643d103d587e460b5c99 # v0.6.3

.gitignore

@@ -4,7 +4,7 @@
 *.dll
 *.so
 *.dylib
-proxy
+/proxy
 
 # Test binary, built with `go test -c`
 *.test
@@ -43,4 +43,4 @@ cache/*
 
 # Debug files
 __debug_bin
-debug
+debug

CONTRIBUTING.md

@@ -39,7 +39,7 @@ proxy/
 │   │   └── queries.go       # CRUD operations
 │   ├── storage/             # Artifact file storage
 │   │   ├── storage.go       # Storage interface
-│   │   └── filesystem.go    # Local filesystem impl
+│   │   └── blob.go          # gocloud.dev/blob backends (file, S3, Azure)
 │   ├── upstream/            # Upstream registry clients
 │   │   ├── fetcher.go       # HTTP artifact fetching
 │   │   └── resolver.go      # Download URL resolution
@@ -72,7 +72,7 @@ Key types:
 
 ### `internal/storage`
 
-Artifact file storage abstraction. Currently implements local filesystem storage. Designed to allow future backends (S3, GCS).
+Artifact file storage abstraction backed by `gocloud.dev/blob`. Supports local filesystem (`file://`), S3 (`s3://`), and Azure (`azblob://`) URLs.
 
 Interface:
 ```go

Dockerfile

@@ -1,4 +1,4 @@
-FROM --platform=$BUILDPLATFORM golang:1.26.5-alpine AS builder
+FROM --platform=$BUILDPLATFORM golang:1.26.7-alpine AS builder
 
 WORKDIR /src
 

README.md

@@ -20,6 +20,26 @@ A 3-day cooldown means that when `lodash` publishes version `4.18.0`, your build
 
 Resolution order: package override, then ecosystem override, then global default. This lets you set a conservative default and carve out exceptions for packages where you need faster updates. See [docs/configuration.md](docs/configuration.md) for the full config reference.
 
+## Artifact Scanning
+
+Cooldown only looks at a version's publish timestamp — it never inspects the actual bytes. Artifact scanning closes that gap: when enabled, every artifact is staged into storage and scanned by one or more external services (trivy, ClamAV, Wiz, or anything else that speaks a small HTTP/JSON contract) before it's committed to the cache and served to clients.
+
+```yaml
+scanning:
+  enabled: true
+  signing_key: ${PROXY_SCANNING_SIGNING_KEY}
+  scanners:
+    - name: clamav
+      url: http://clamav-adapter:8080/scan
+      mode: block             # a block verdict deletes the artifact and returns 403
+    - name: trivy
+      url: http://trivy-adapter:8081/scan
+      mode: monitor            # findings are logged, never gate caching
+      ecosystems: [npm, pypi]
+```
+
+The proxy never uploads artifact bytes to a scanner. Each scanner is notified with package metadata plus a short-lived signed URL; the scanner pulls the bytes itself from the proxy's own storage. Scanners run concurrently, and the first `block`-mode scanner to report a verdict of not-allowed wins immediately, canceling the rest. See [docs/configuration.md](docs/configuration.md) for the full config reference and the scanner HTTP contract.
+
 ## Supported Registries
 
 | Registry | Language/Platform | Cooldown | Completed |
@@ -39,15 +59,16 @@ Resolution order: package override, then ecosystem override, then global default
 | Conda | Python/R | Yes | ✓ |
 | CRAN | R | | ✓ |
 | Julia | Julia | | ✓ |
+| Swift | Swift | | ✓ |
 | Container | Docker/OCI | | ✓ |
+| Homebrew | macOS/Linux | | ✓ |
 | Debian | Debian/Ubuntu | | ✓ |
 | RPM | RHEL/Fedora | | ✓ |
-| Alpine | Alpine Linux | | ✗ |
+| Alpine | Alpine Linux | | ✓ |
 | Arch | Arch Linux | | ✗ |
 | Chef | Chef | | ✗ |
-| Generic | Any | | ✗ |
-| Helm | Kubernetes | | ✗ |
-| Swift | Swift | | ✗ |
+| Generic | Any | | ✓ |
+| Helm | Kubernetes | | ✓ |
 | Vagrant | Vagrant | | ✗ |
 
 Cooldown requires publish timestamps in metadata. Registries without a "Yes" in the cooldown column either don't expose timestamps or haven't been wired up yet.
@@ -62,6 +83,21 @@ brew install git-pkgs/git-pkgs/proxy
 
 Or download a binary from the [releases page](https://github.com/git-pkgs/proxy/releases).
 
+### Helm
+
+Install the chart from GHCR, setting the public URL that package-manager clients
+will use to reach the proxy:
+
+```bash
+helm install proxy oci://ghcr.io/git-pkgs/charts/proxy \
+  --set config.data.base_url=https://proxy.example.com
+```
+
+The default chart deploys one replica backed by a 10 GiB persistent volume,
+using SQLite and filesystem artifact storage under `/data`. See
+[`deploy/charts/proxy/values.yaml`](deploy/charts/proxy/values.yaml) for ingress,
+external database and object-storage configuration options.
+
 ## Quick Start
 
 ```bash
@@ -157,6 +193,29 @@ export GOPROXY=http://localhost:8080/go,direct
 
 Or in your shell profile for persistence.
 
+### Homebrew
+
+Point Homebrew's JSON API and artifact domain at the proxy:
+
+```bash
+export HOMEBREW_API_DOMAIN=http://localhost:8080/homebrew
+export HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080
+```
+
+The artifact domain proxies manifests and bottle blobs under `/v2/homebrew/core/`. GHCR routing is limited to that repository. Source archives, cask application downloads, custom tap artifacts, and legacy flat-file bottle mirrors use Homebrew's normal fallback URLs. Keep fallback enabled by leaving `HOMEBREW_ARTIFACT_DOMAIN_NO_FALLBACK` unset.
+
+Enable `cache_metadata` or set `PROXY_CACHE_METADATA=true` to retain Homebrew JSON API responses for offline fallback. Bottle blobs and their OCI manifests are cached without this setting.
+
+The upstreams default to `https://formulae.brew.sh/api` for the JSON API and `https://ghcr.io` for artifacts. To chain this proxy to another proxy, configure its Homebrew endpoints as the upstreams:
+
+```yaml
+upstream:
+  homebrew_api: "https://upstream-proxy.example.com/homebrew"
+  homebrew_artifact: "https://upstream-proxy.example.com"
+```
+
+The equivalent environment variables are `PROXY_UPSTREAM_HOMEBREW_API` and `PROXY_UPSTREAM_HOMEBREW_ARTIFACT`.
+
 ### Hex (Elixir)
 
 Configure in `~/.hex/hex.config`:
@@ -340,6 +399,25 @@ ENV["JULIA_PKG_SERVER"] = "http://localhost:8080/julia"
 using Pkg; Pkg.update()
 ```
 
+### Swift
+
+Configure the proxy as the default registry for the current Swift package:
+
+```bash
+swift package-registry set --allow-insecure-http http://localhost:8080/swift
+```
+
+Registry dependencies use their scoped package identifier in `Package.swift`:
+
+```swift
+dependencies: [
+    .package(id: "apple.swift-argument-parser", from: "1.2.0")
+]
+```
+
+The proxy supports dependency resolution and source downloads. Publishing with
+`swift package-registry publish` is not supported.
+
 ### Docker / Container Registry
 
 Configure Docker to use the proxy as a registry mirror in `/etc/docker/daemon.json`:
@@ -362,6 +440,39 @@ Or pull images directly:
 docker pull localhost:8080/library/nginx:latest
 ```
 
+### Helm
+
+Configure each HTTP chart repository with a name, then add the matching proxy
+URL to Helm:
+
+```yaml
+upstream:
+  helm:
+    bitnami: "https://charts.bitnami.com/bitnami"
+```
+
+```bash
+helm repo add bitnami http://localhost:8080/helm/bitnami
+helm repo update
+helm pull bitnami/nginx
+```
+
+The proxy caches `index.yaml` using the normal metadata-cache settings and
+caches chart archives after verifying their SHA-256 digest from the index.
+
+For charts stored in an OCI registry, configure a named OCI upstream and add
+the reserved `upstream/{name}` prefix to the chart reference:
+
+```yaml
+upstream:
+  oci:
+    ghcr: "https://ghcr.io"
+```
+
+```bash
+helm pull oci://localhost:8080/upstream/ghcr/owner/charts/mychart --version 1.0.0 --plain-http
+```
+
 ### Debian / APT
 
 Configure APT to use the proxy in `/etc/apt/sources.list.d/proxy.list`:
@@ -402,6 +513,72 @@ sudo dnf clean all
 sudo dnf update
 ```
 
+### Alpine / apk
+
+Point `/etc/apk/repositories` at the proxy. The default repository name
+`alpine` proxies the official mirror (`https://dl-cdn.alpinelinux.org/alpine`):
+
+```
+http://localhost:8080/apk/alpine/v3.22/main
+http://localhost:8080/apk/alpine/v3.22/community
+```
+
+Then:
+
+```bash
+apk update
+```
+
+Repository indexes (v2 `APKINDEX.tar.gz` and v3 `Packages.adb`), detached
+signatures, and packages are served byte-for-byte unchanged, so apk's normal
+signature verification keeps working. Indexes use the metadata cache
+(`metadata_ttl`, stale fallback); `.apk` packages are stored in the shared
+artifact cache and remain available when the upstream is unreachable.
+
+To proxy other mirrors or private repositories, configure named upstreams
+under `upstream.apk` (this replaces the built-in default; re-add `alpine` if
+you still want it):
+
+```yaml
+upstream:
+  apk:
+    alpine: "https://dl-cdn.alpinelinux.org/alpine"
+    private: "https://apk.example.com"
+```
+
+```
+http://localhost:8080/apk/private
+```
+
+apk appends the architecture and index filename to each repository line
+itself.
+
+### GitHub Releases / mise (aqua backend)
+
+Configure named generic upstreams:
+
+```yaml
+upstream:
+  generic:
+    github: "https://github.com"
+    github-api: "https://api.github.com"
+```
+
+Then rewrite GitHub URLs in mise's settings (`~/.config/mise/config.toml`, mise ≥ 2025.9.3):
+
+```toml
+[settings.url_replacements]
+"regex:^https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" = "http://localhost:8080/generic/github/$1/$2/releases/download/$3"
+"regex:^https://api\\.github\\.com/(.*)" = "http://localhost:8080/generic/github-api/$1"
+```
+
+Release assets are cached permanently after the first download and keep
+installing while GitHub is down. Tag lookups through `api.github.com` are
+cached for `metadata_ttl` and served stale during an outage or rate limit.
+Commit a `mise.lock` and install with `mise install --locked` so pinned
+installs need no API call at all. Add a bearer token for `https://api.github.com`
+under `upstream.auth` if the fleet exceeds GitHub's anonymous rate limit.
+
 ## Configuration
 
 The proxy can be configured via:
@@ -416,13 +593,14 @@ The proxy can be configured via:
 -config string           Path to configuration file
 -listen string           Address to listen on (default ":8080")
 -base-url string         Public URL of this proxy (default "http://localhost:8080")
--storage-url string      Storage URL (file:// or s3://)
+-storage-url string      Storage URL (file://, s3://, gs://, azblob://)
 -storage-path string     Path to artifact storage directory (deprecated, use -storage-url)
 -database-driver string  Database driver: sqlite or postgres (default "sqlite")
 -database-path string    Path to SQLite database file (default "./cache/proxy.db")
 -database-url string     PostgreSQL connection URL
 -log-level string        Log level: debug, info, warn, error (default "info")
 -log-format string       Log format: text, json (default "text")
+-access-log string       Path to the JSONL access log
 -version                 Print version and exit
 ```
 
@@ -438,6 +616,8 @@ PROXY_DATABASE_PATH=./cache/proxy.db
 PROXY_DATABASE_URL=postgres://user:pass@localhost/proxy?sslmode=disable
 PROXY_LOG_LEVEL=info
 PROXY_LOG_FORMAT=text
+PROXY_ACCESS_LOG_PATH=/var/log/proxy/access.jsonl
+PROXY_UPSTREAM_SWIFT=https://tuist.dev/api/registry/swift
 ```
 
 ### Configuration File
@@ -458,16 +638,22 @@ log:
   level: "info"
   format: "text"
 
+access_log:
+  path: "/var/log/proxy/access.jsonl"  # Optional JSONL activity log
+
 # Optional: override upstream URLs
 upstream:
   npm: "https://registry.npmjs.org"
   cargo: "https://index.crates.io"
+  swift: "https://tuist.dev/api/registry/swift"
 
 # Optional: version cooldown (see above)
 cooldown:
   default: "3d"
 ```
 
+See the [configuration reference](docs/configuration.md#upstream-registries) for every upstream key, environment variable, and default URL.
+
 Run with config file:
 
 ```bash
@@ -511,6 +697,57 @@ storage:
 
 Set credentials via standard AWS environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`).
 
+### Google Cloud Storage
+
+The proxy can store cached artifacts in a GCS bucket using the `gs://` URL scheme.
+
+```yaml
+storage:
+  url: "gs://my-bucket-name"
+```
+
+Authentication uses [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials), which means no credentials need to be embedded in the config or environment. Supported sources, in order:
+
+- **GKE Workload Identity** — bind the Kubernetes service account running the proxy to a Google service account that has `roles/storage.objectAdmin` on the bucket. The proxy will use the workload's token automatically.
+- **Attached service account** on GCE, Cloud Run, Cloud Functions, etc.
+- **`GOOGLE_APPLICATION_CREDENTIALS`** environment variable pointing at a service account JSON key file.
+- **`gcloud auth application-default login`** for local development.
+
+#### GKE Workload Identity setup
+
+```bash
+# 1. Create a Google service account
+gcloud iam service-accounts create git-pkgs-proxy \
+  --project=PROJECT_ID
+
+# 2. Grant it access to the bucket
+gsutil iam ch \
+  serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com:objectAdmin \
+  gs://my-bucket-name
+
+# 3. Bind the Kubernetes service account to it
+gcloud iam service-accounts add-iam-policy-binding \
+  git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
+  --role=roles/iam.workloadIdentityUser \
+  --member="serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
+
+# 4. Annotate the Kubernetes service account
+kubectl annotate serviceaccount KSA_NAME \
+  --namespace=NAMESPACE \
+  iam.gke.io/gcp-service-account=git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com
+```
+
+#### Direct serve (signed URLs) with Workload Identity
+
+When `direct_serve: true` is enabled, the proxy issues HTTP 302 redirects to presigned GCS URLs. Workload Identity provides no private key, so the GCS backend calls the [IAM Credentials `signBlob` API](https://docs.cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob). Grant the service account the token-creator role on itself:
+
+```bash
+gcloud iam service-accounts add-iam-policy-binding \
+  git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
+  --role=roles/iam.serviceAccountTokenCreator \
+  --member="serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com"
+```
+
 ## CLI Commands
 
 ### serve (default)
@@ -553,6 +790,11 @@ curl -X POST http://localhost:8080/api/mirror \
   -H "Content-Type: application/json" \
   -d '{"purls": ["pkg:npm/lodash@4.17.21"]}'
 
+# Start a mirror job from an inline CycloneDX or SPDX JSON SBOM
+curl -X POST http://localhost:8080/api/mirror \
+  -H "Content-Type: application/json" \
+  -d '{"sbom":{"bomFormat":"CycloneDX","components":[{"purl":"pkg:npm/lodash@4.17.21"}]}}'
+
 # Check job status
 curl http://localhost:8080/api/mirror/mirror-1
 
@@ -614,7 +856,7 @@ Recently cached:
 | Endpoint | Description |
 |----------|-------------|
 | `GET /` | Dashboard (web UI) |
-| `GET /health` | Health check (JSON; HTTP 200 healthy, 503 unhealthy) |
+| `GET /health` | Health check and upstream circuit breaker state (JSON; HTTP 200 healthy, 503 unhealthy) |
 | `GET /stats` | Cache statistics (JSON) |
 | `GET /metrics` | Prometheus metrics |
 | `GET /npm/*` | npm registry protocol |
@@ -631,7 +873,13 @@ Recently cached:
 | `GET /conda/*` | Conda/Anaconda protocol |
 | `GET /cran/*` | CRAN (R) protocol |
 | `GET /julia/*` | Julia Pkg server protocol |
+| `GET /swift/*` | Swift Package Registry v1 protocol |
+| `GET /helm/{repository}/*` | HTTP Helm chart repository protocol |
+| `GET /homebrew/*` | Homebrew JSON API |
 | `GET /v2/*` | OCI/Docker registry protocol |
+| `GET /v2/homebrew/core/*` | Homebrew core bottle manifests and blobs from GHCR |
+| `GET /apk/{repository}/*` | Alpine APK repository protocol |
+| `GET /generic/{name}/*` | Generic HTTP download proxy (GitHub release assets, mise/aqua) |
 | `GET /debian/*` | Debian/APT repository protocol |
 | `GET /rpm/*` | RPM/Yum repository protocol |
 
@@ -639,7 +887,7 @@ Recently cached:
 
 | Endpoint | Description |
 |----------|-------------|
-| `POST /api/mirror` | Start a mirror job (JSON body with `purls`) |
+| `POST /api/mirror` | Start a mirror job (JSON body with `purls` or an inline `sbom`) |
 | `GET /api/mirror/{id}` | Get job status and progress |
 | `DELETE /api/mirror/{id}` | Cancel a running job |
 
@@ -844,6 +1092,8 @@ The proxy exposes Prometheus metrics at `GET /metrics`. All metric names are pre
 
 | Metric | Type | Labels | Description |
 |--------|------|--------|-------------|
+| `proxy_requests_total` | counter | `ecosystem`, `status` | Proxy responses by package ecosystem and HTTP status |
+| `proxy_request_duration_seconds` | histogram | `ecosystem`, `status` | Proxy request duration |
 | `proxy_cache_hits_total` | counter | `ecosystem` | Cache hits |
 | `proxy_cache_misses_total` | counter | `ecosystem` | Cache misses |
 | `proxy_cache_size_bytes` | gauge | | Total size of cached artifacts |
@@ -854,8 +1104,16 @@ The proxy exposes Prometheus metrics at `GET /metrics`. All metric names are pre
 | `proxy_storage_errors_total` | counter | `operation` | Storage read/write failures |
 | `proxy_active_requests` | gauge | | In-flight requests |
 | `proxy_health_probe_failures_total` | counter | `step` | Storage health probe failures by failing step (`write`, `size`, `read`, `verify`, `delete`). |
+| `proxy_circuit_breaker_state` | gauge | `registry` | Artifact-fetch circuit breaker state per upstream registry (0 closed, 2 open). Published once that registry's breaker has tripped. |
+| `proxy_circuit_breaker_trips_total` | counter | `registry` | Circuit breaker trips per upstream registry. |
 
-Cache size and artifact count are refreshed every 60 seconds. The remaining metrics update on each request.
+Cache size and artifact count are refreshed every 60 seconds. Circuit breaker state is read from the fetcher on each scrape of `/metrics` and each `/health` request, so `proxy_circuit_breaker_trips_total` counts the trips visible between those reads — a breaker that opens and recovers entirely between two scrapes is not counted. The remaining metrics update on each request.
+
+The breaker metrics carry one series per upstream host, but only for hosts whose breaker has tripped at least once since startup. A breaker is created per host the proxy fetches artifacts from, and for some ecosystems that host comes from upstream metadata rather than from configuration (composer takes it from a package's `dist.url`, helm from the chart URLs in `index.yaml`), so publishing every host would let upstream content grow the series count for the lifetime of the process. Once a host has tripped it keeps reporting, so a recovery still shows up as a transition to 0 rather than as a series that vanishes. `/health` is not a persistent time series and lists every breaker, tripped or not.
+
+The `registry` label is the host of the URL the artifact was fetched from. Because that URL can come from upstream metadata, it is not always one a host can be read off — a signed `dist.url` that fails to parse, for instance — and such a breaker is labelled `hostless-url-<digest>` instead, where the digest is keyed by a value drawn fresh at startup. Neither `/metrics` nor `/health` requires authentication, so a fetch URL is never published as a label or a key; the digest identifies the breaker for as long as the process runs without revealing the URL behind it or letting a chosen URL be matched against it.
+
+Alert on `proxy_circuit_breaker_state == 2` sustained for more than a few minutes: while a breaker is open, artifact downloads for that upstream fail with HTTP 502 on every cache miss, and only a single probe request per backoff interval reaches the upstream. Cached artifacts keep serving, and so does metadata for the same ecosystem (metadata does not go through the circuit breaker), so installs fail in a way that looks like a partial upstream outage.
 
 ### Health Check
 
@@ -867,12 +1125,20 @@ Cache size and artifact count are refreshed every 60 seconds. The remaining metr
   "checks": {
     "database": {"status": "ok"},
     "storage":  {"status": "ok"}
+  },
+  "circuit_breakers": {
+    "registry.npmjs.org": "closed",
+    "static.crates.io":   "open"
   }
 }
 ```
 
 Failing checks include an `"error"` field. Storage failures also include a `"step"` field identifying which probe step failed (`write`, `size`, `read`, `verify`, `delete`). When the database check fails, the storage entry reports `{"status": "skipped"}` so the response always carries the same key set.
 
+`circuit_breakers` reports the state of each upstream's artifact-fetch circuit breaker (`"open"` or `"closed"`), keyed by upstream host — or by the `hostless-url-<digest>` placeholder described under [Monitoring](#monitoring) where the fetch URL has no host to read. The key is omitted until the proxy has fetched an artifact from at least one upstream, and a host appears only once a breaker has been created for it. Breakers trip after repeated upstream failures and retry the upstream after an exponential backoff. While one is open, artifact downloads for that host return HTTP 502 on a cache miss without contacting the upstream; already-cached artifacts are still served from storage, since the cache is checked before the fetcher. A breaker is reported as `"open"` throughout its backoff, including the half-open window in which it admits one probe request to test recovery. Breaker state is per process and in memory, so a restart clears it, but a restart is not needed for recovery: the backoff keeps retrying for as long as the breaker is open, so it closes on its own once the upstream serves again.
+
+An open breaker does **not** set `status` to `"error"` or change the HTTP status code: it reports a specific upstream refusing to serve, not this proxy being unfit to receive traffic, and failing the readiness probe over one unhealthy upstream would pull the pod out of rotation for every other ecosystem too. Use `proxy_circuit_breaker_state` for alerting on it.
+
 Storage probe results are cached for `health.storage_probe_interval` (default 30s) to bound the cost of probing remote backends. A probe holds an internal mutex for up to 10 seconds (the hardcoded per-probe timeout), so `/health` is intended as a Kubernetes **readiness** probe rather than a liveness probe — a slow S3 round-trip should pull the pod from rotation, not restart it.
 
 Scrape config for Prometheus:
@@ -1024,7 +1290,7 @@ The proxy will recreate the database on next start.
 
 Requirements:
 
-- Go 1.25 or later
+- Go (the project version is declared in `go.mod`)
 
 ```bash
 git clone https://github.com/git-pkgs/proxy.git

cmd/proxy/main.go

@@ -40,6 +40,8 @@
 //	      Log level: debug, info, warn, error (default "info")
 //	-log-format string
 //	      Log format: text, json (default "text")
+//	-access-log string
+//	      Path to the JSONL access log (disabled by default)
 //
 // Stats Flags:
 //
@@ -72,8 +74,8 @@
 //	PROXY_DATABASE_URL     - PostgreSQL connection URL
 //	PROXY_LOG_LEVEL        - Log level
 //	PROXY_LOG_FORMAT       - Log format
-//	PROXY_UPSTREAM_MAVEN   - Maven repository upstream URL
-//	PROXY_UPSTREAM_GRADLE_PLUGIN_PORTAL - Gradle Plugin Portal upstream URL
+//	PROXY_ACCESS_LOG_PATH  - JSONL access log path
+//	PROXY_UPSTREAM_*       - Upstream URLs and network access controls
 //	PROXY_GRADLE_BUILD_CACHE_READ_ONLY       - Disable Gradle PUT uploads
 //	PROXY_GRADLE_BUILD_CACHE_MAX_UPLOAD_SIZE - Max Gradle PUT request body size
 //	PROXY_GRADLE_BUILD_CACHE_MAX_AGE         - Gradle cache max age eviction
@@ -184,6 +186,7 @@ func runServe() {
 	databaseURL := fs.String("database-url", "", "PostgreSQL connection URL")
 	logLevel := fs.String("log-level", "", "Log level: debug, info, warn, error")
 	logFormat := fs.String("log-format", "", "Log format: text, json")
+	accessLogPath := fs.String("access-log", "", "Path to the JSONL access log")
 	version := fs.Bool("version", false, "Print version and exit")
 
 	fs.Usage = func() {
@@ -201,8 +204,33 @@ func runServe() {
 		fmt.Fprintf(os.Stderr, "  PROXY_DATABASE_URL     PostgreSQL connection URL\n")
 		fmt.Fprintf(os.Stderr, "  PROXY_LOG_LEVEL        Log level\n")
 		fmt.Fprintf(os.Stderr, "  PROXY_LOG_FORMAT       Log format\n")
-		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_MAVEN   Maven repository upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_ACCESS_LOG_PATH  JSONL access log path\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_ALLOW_PRIVATE_HOSTS  Comma-separated private upstream hosts\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_ALLOW_LOOPBACK       Permit loopback upstreams and redirects\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_NPM                  npm registry upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_CARGO                Cargo index upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_CARGO_DOWNLOAD       Cargo download upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_GEM                  RubyGems upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_GO                   Go module proxy upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_HEX                  Hex repository upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_HEX_API              Hex API upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_PUB                  pub registry upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_PYPI                 PyPI index and API upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_PYPI_DOWNLOAD        PyPI download upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_MAVEN                Maven repository upstream URL\n")
 		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_GRADLE_PLUGIN_PORTAL Gradle Plugin Portal upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_NUGET                NuGet API upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_NUGET_SEARCH         NuGet search upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_COMPOSER             Packagist API upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_COMPOSER_REPOSITORY  Packagist repository upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_CONAN                Conan registry upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_CONDA                Conda channel upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_CRAN                 CRAN mirror upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_JULIA                Julia package server upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_SWIFT                Swift Package Registry upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_OCI_DEFAULT          Default OCI registry upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_DEBIAN               Debian repository upstream URL\n")
+		fmt.Fprintf(os.Stderr, "  PROXY_UPSTREAM_RPM                  RPM repository upstream URL\n")
 		fmt.Fprintf(os.Stderr, "  PROXY_GRADLE_BUILD_CACHE_READ_ONLY       Disable Gradle PUT uploads\n")
 		fmt.Fprintf(os.Stderr, "  PROXY_GRADLE_BUILD_CACHE_MAX_UPLOAD_SIZE Max Gradle PUT request body size\n")
 		fmt.Fprintf(os.Stderr, "  PROXY_GRADLE_BUILD_CACHE_MAX_AGE         Gradle cache max age eviction\n")
@@ -256,6 +284,9 @@ func runServe() {
 	if *logFormat != "" {
 		cfg.Log.Format = *logFormat
 	}
+	if *accessLogPath != "" {
+		cfg.AccessLog.Path = *accessLogPath
+	}
 
 	// Validate configuration
 	if err := cfg.Validate(); err != nil {
@@ -267,7 +298,10 @@ func runServe() {
 	logger := setupLogger(cfg.Log.Level, cfg.Log.Format)
 
 	// Create and start server
-	srv, err := server.New(cfg, logger)
+	srv, err := server.New(cfg, logger, server.BuildInfo{
+		Version: Version,
+		Commit:  Commit,
+	})
 	if err != nil {
 		logger.Error("failed to create server", "error", err)
 		os.Exit(1)
@@ -395,7 +429,12 @@ func runMirror() {
 	var source mirror.Source
 	switch {
 	case *sbomPath != "":
-		source = &mirror.SBOMSource{Path: *sbomPath}
+		data, err := os.ReadFile(*sbomPath)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error reading SBOM %s: %v\n", *sbomPath, err)
+			os.Exit(1)
+		}
+		source = &mirror.SBOMSource{Data: data, Name: *sbomPath}
 	case len(purls) > 0:
 		source = &mirror.PURLSource{PURLs: purls}
 	default:

cmd/proxy/main_test.go

@@ -0,0 +1,58 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+func TestServeHelpListsUpstreamEnvironmentVariables(t *testing.T) {
+	cmd := exec.Command(os.Args[0], "-test.run=^TestServeHelpProcess$")
+	cmd.Env = append(os.Environ(), "PROXY_TEST_SERVE_HELP=1")
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("serve help failed: %v\n%s", err, output)
+	}
+
+	variables := []string{
+		"PROXY_UPSTREAM_ALLOW_PRIVATE_HOSTS",
+		"PROXY_UPSTREAM_ALLOW_LOOPBACK",
+		"PROXY_UPSTREAM_NPM",
+		"PROXY_UPSTREAM_CARGO",
+		"PROXY_UPSTREAM_CARGO_DOWNLOAD",
+		"PROXY_UPSTREAM_GEM",
+		"PROXY_UPSTREAM_GO",
+		"PROXY_UPSTREAM_HEX",
+		"PROXY_UPSTREAM_HEX_API",
+		"PROXY_UPSTREAM_PUB",
+		"PROXY_UPSTREAM_PYPI",
+		"PROXY_UPSTREAM_PYPI_DOWNLOAD",
+		"PROXY_UPSTREAM_MAVEN",
+		"PROXY_UPSTREAM_GRADLE_PLUGIN_PORTAL",
+		"PROXY_UPSTREAM_NUGET",
+		"PROXY_UPSTREAM_NUGET_SEARCH",
+		"PROXY_UPSTREAM_COMPOSER",
+		"PROXY_UPSTREAM_COMPOSER_REPOSITORY",
+		"PROXY_UPSTREAM_CONAN",
+		"PROXY_UPSTREAM_CONDA",
+		"PROXY_UPSTREAM_CRAN",
+		"PROXY_UPSTREAM_JULIA",
+		"PROXY_UPSTREAM_OCI_DEFAULT",
+		"PROXY_UPSTREAM_DEBIAN",
+		"PROXY_UPSTREAM_RPM",
+	}
+	for _, variable := range variables {
+		if !strings.Contains(string(output), variable) {
+			t.Errorf("serve help omitted %s", variable)
+		}
+	}
+}
+
+func TestServeHelpProcess(*testing.T) {
+	if os.Getenv("PROXY_TEST_SERVE_HELP") != "1" {
+		return
+	}
+	os.Args = []string{"proxy", "serve", "-help"}
+	main()
+}

config.example.yaml

@@ -27,9 +27,20 @@ storage:
   #   - file:///path/to/dir - Local filesystem (default)
   #   - s3://bucket-name - Amazon S3
   #   - s3://bucket?endpoint=http://localhost:9000 - S3-compatible (MinIO)
+  #   - gs://bucket-name - Google Cloud Storage
+  #   - azblob://container-name - Azure Blob Storage
   #
   # For S3, configure credentials via environment variables:
   #   AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
+  #
+  # For GCS, authentication uses Application Default Credentials. On GKE with
+  # Workload Identity, bind the Kubernetes service account to a Google service
+  # account that has roles/storage.objectAdmin on the bucket. No extra config
+  # is needed in this file. For local development, run:
+  #   gcloud auth application-default login
+  # If direct_serve is enabled, the service account also needs
+  # roles/iam.serviceAccountTokenCreator on itself so the IAM Credentials
+  # signBlob API can sign URLs without a private key.
   url: ""
 
   # Local filesystem path (used when url is empty)
@@ -42,7 +53,7 @@ storage:
   max_size: ""
 
   # Redirect cached artifact downloads to presigned storage URLs (HTTP 302)
-  # instead of streaming through the proxy. Only effective for S3 and Azure.
+  # instead of streaming through the proxy. Only effective for S3, GCS, and Azure.
   # Leave disabled if clients reach the proxy through an authenticating gateway,
   # since presigned URLs bypass it.
   direct_serve: false
@@ -78,16 +89,24 @@ log:
   # Log format: "text" or "json"
   format: "text"
 
-# Upstream registry URLs and authentication
+# JSONL access log. Leave path empty to disable it.
+access_log:
+  path: ""
+
+# Upstream URLs for built-in routes and authentication
 upstream:
+  # Hosts allowed to resolve to private, ULA, or CGNAT addresses
+  allow_private_hosts: []
+
+  # Permit upstream requests and redirects to loopback addresses
+  allow_loopback: false
+
   # npm registry URL
   npm: "https://registry.npmjs.org"
-
-  # Maven repository URL (used by /maven endpoint)
-  maven: "https://repo1.maven.org/maven2"
-
-  # Gradle Plugin Portal Maven URL (fallback for plugin marker artifacts)
-  gradle_plugin_portal: "https://plugins.gradle.org/m2"
+  # Always request full npm packuments so served metadata carries publish
+  # times ("time" map) even when cooldown is disabled. Needed by clients that
+  # gate on publish age, e.g. Yarn's npmMinimalAgeGate. Default: false.
+  # npm_full_metadata: true
 
   # Cargo sparse index URL
   cargo: "https://index.crates.io"
@@ -95,9 +114,99 @@ upstream:
   # Cargo crate download URL
   cargo_download: "https://static.crates.io/crates"
 
+  # RubyGems registry URL
+  gem: "https://rubygems.org"
+
+  # Go module proxy URL
+  go: "https://proxy.golang.org"
+
+  # Hex repository URL
+  hex: "https://repo.hex.pm"
+
+  # Hex API URL used for package timestamps
+  hex_api: "https://hex.pm"
+
+  # pub registry URL
+  pub: "https://pub.dev"
+
+  # PyPI index and API URL
+  pypi: "https://pypi.org"
+
+  # PyPI package download URL
+  pypi_download: "https://files.pythonhosted.org"
+
+  # Maven repository URL (used by /maven endpoint)
+  maven: "https://repo1.maven.org/maven2"
+
+  # Gradle Plugin Portal Maven URL (fallback for plugin marker artifacts)
+  gradle_plugin_portal: "https://plugins.gradle.org/m2"
+
+  # NuGet API URL
+  nuget: "https://api.nuget.org"
+
+  # NuGet search API URL
+  nuget_search: "https://azuresearch-usnc.nuget.org"
+
+  # Packagist API URL
+  composer: "https://packagist.org"
+
+  # Packagist repository URL
+  composer_repository: "https://repo.packagist.org"
+
+  # Conan registry URL
+  conan: "https://center.conan.io"
+
+  # Conda channel base URL
+  conda: "https://conda.anaconda.org"
+
+  # CRAN mirror URL
+  cran: "https://cloud.r-project.org"
+
+  # Julia package server URL
+  julia: "https://pkg.julialang.org"
+
+  # Swift Package Registry URL (used by /swift endpoint)
+  swift: "https://tuist.dev/api/registry/swift"
+
+  # Default OCI registry URL for unprefixed /v2 requests
+  oci_default: "https://registry-1.docker.io"
+
   # Debian/APT repository URL (used by /debian endpoint)
   debian: "http://deb.debian.org/debian"
 
+  # RPM repository URL (used by /rpm endpoint)
+  rpm: "https://dl.fedoraproject.org/pub/fedora/linux"
+
+  # Homebrew JSON API URL (used by /homebrew endpoint)
+  homebrew_api: "https://formulae.brew.sh/api"
+
+  # Homebrew artifact registry URL (used for /v2/homebrew/core requests)
+  homebrew_artifact: "https://ghcr.io"
+
+  # Named HTTP Helm chart repositories (used by /helm/{name}/)
+  # helm:
+  #   bitnami: "https://charts.bitnami.com/bitnami"
+
+  # Named OCI registries. Use the upstream/{name}/ repository prefix, e.g.
+  # oci://proxy.example.com/upstream/ghcr/owner/chart.
+  # oci:
+  #   ghcr: "https://ghcr.io"
+
+  # Named Alpine APK repositories (used by /apk/{name}/).
+  # Defaults to {"alpine": "https://dl-cdn.alpinelinux.org/alpine"} when empty;
+  # configuring any entry replaces that default.
+  # apk:
+  #   alpine: "https://dl-cdn.alpinelinux.org/alpine"
+  #   private: "https://apk.example.com"
+
+  # Named generic HTTP upstreams (used by /generic/{name}/). The remaining
+  # request path and query are appended to the upstream URL. GitHub release
+  # assets ({owner}/{repo}/releases/download/{tag}/{asset}) are cached
+  # immutably; other paths use the metadata cache with stale-on-error.
+  # generic:
+  #   github: "https://github.com"
+  #   github-api: "https://api.github.com"
+
   # Authentication for upstream registries
   # Keys are absolute URL scopes. Scheme, host, effective port, and path
   # segment boundaries must match; the longest matching scope wins.
@@ -107,6 +216,7 @@ upstream:
   #   - bearer: Authorization header with Bearer token
   #   - basic: Authorization header with Basic auth (username:password)
   #   - header: Custom header name and value
+  #   - ecr: AWS ECR auto-refreshing token via the AWS SDK credential chain
   auth:
     # Example: npm with bearer token
     # "https://registry.npmjs.org":
@@ -130,6 +240,13 @@ upstream:
     #   header_name: "X-Auth-Token"
     #   header_value: "${MAVEN_TOKEN}"
 
+    # Example: private AWS ECR registry (12h tokens auto-refreshed via
+    # ecr:GetAuthorizationToken; credentials come from the AWS SDK default
+    # chain, so IRSA / instance profiles / AWS_* env vars all work; the region
+    # is inferred from the private ECR hostname)
+    # "https://123456789012.dkr.ecr.eu-west-1.amazonaws.com":
+    #   type: ecr
+
 # Gradle HttpBuildCache configuration
 gradle:
   build_cache:
@@ -177,3 +294,32 @@ cooldown:
   # packages:
   #   "pkg:npm/lodash": "0"
   #   "pkg:npm/@babel/core": "14d"
+
+# Pre-cache artifact scanning. When enabled, every artifact is staged into
+# storage and scanned by the configured scanners before it is committed to
+# the cache and served to clients. Scanners never receive artifact bytes
+# directly — each notify call includes a short-lived signed URL that the
+# scanner fetches itself, so the proxy stays agnostic to trivy/ClamAV/Wiz/
+# any custom service. Scanners run concurrently; the first "block" verdict
+# wins and cancels the rest.
+# scanning:
+#   enabled: true
+#   fail_open: false
+#   timeout: 30s
+#
+#   # Authenticates pull requests to the internal scan-fetch route.
+#   # Required whenever enabled is true. Supports ${VAR_NAME} expansion.
+#   signing_key: ${PROXY_SCANNING_SIGNING_KEY}
+#
+#   # Address scanners use to reach this proxy to pull staged artifacts.
+#   # Defaults to base_url.
+#   # fetch_base_url: http://proxy.internal:8080
+#
+#   scanners:
+#     - name: clamav
+#       url: http://clamav-adapter:8080/scan
+#       mode: block
+#     - name: trivy
+#       url: http://trivy-adapter:8081/scan
+#       mode: monitor
+#       ecosystems: [npm, pypi]

deploy/charts/proxy/.helmignore

@@ -0,0 +1,6 @@
+.DS_Store
+.git/
+.github/
+*.swp
+*.tmp
+*.tgz

deploy/charts/proxy/Chart.yaml

@@ -0,0 +1,11 @@
+apiVersion: v2
+name: proxy
+description: A caching proxy for package registries
+type: application
+version: 0.0.0
+appVersion: "0.0.0"
+home: https://github.com/git-pkgs/proxy
+sources:
+  - https://github.com/git-pkgs/proxy
+annotations:
+  artifacthub.io/license: MIT

deploy/charts/proxy/templates/NOTES.txt

@@ -0,0 +1,15 @@
+git-pkgs proxy has been installed.
+
+The default base URL is intended for local port forwarding. Before exposing the
+proxy, set config.data.base_url to the URL used by package-manager clients.
+
+To access the proxy locally:
+
+  kubectl -n {{ .Release.Namespace }} port-forward service/{{ include "proxy.fullname" . }} {{ .Values.service.port }}:{{ .Values.service.port }}
+
+Then visit http://localhost:{{ .Values.service.port }}/.
+
+{{- if not .Values.persistence.enabled }}
+WARNING: persistence is disabled. Cached artifacts and the default SQLite
+database will be lost when the pod is replaced.
+{{- end }}

deploy/charts/proxy/templates/_helpers.tpl

@@ -0,0 +1,46 @@
+{{/* Expand the chart name. */}}
+{{- define "proxy.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/* Create a release-specific, DNS-safe resource name. */}}
+{{- define "proxy.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := include "proxy.name" . }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{- define "proxy.labels" -}}
+helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{ include "proxy.selectorLabels" . }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{- define "proxy.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "proxy.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{- define "proxy.configMapName" -}}
+{{- default (include "proxy.fullname" .) .Values.config.existingConfigMap }}
+{{- end }}
+
+{{- define "proxy.claimName" -}}
+{{- default (include "proxy.fullname" .) .Values.persistence.existingClaim }}
+{{- end }}
+
+{{- define "proxy.image" -}}
+{{- if .Values.image.digest -}}
+{{- printf "%s@%s" .Values.image.repository .Values.image.digest -}}
+{{- else -}}
+{{- printf "%s:%s" .Values.image.repository (default .Chart.AppVersion .Values.image.tag) -}}
+{{- end -}}
+{{- end }}

deploy/charts/proxy/templates/configmap.yaml

@@ -0,0 +1,12 @@
+{{- if not .Values.config.existingConfigMap }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "proxy.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "proxy.labels" . | nindent 4 }}
+data:
+  {{ required "config.existingConfigMapKey is required" .Values.config.existingConfigMapKey }}: |
+    {{- toYaml .Values.config.data | nindent 4 }}
+{{- end }}

deploy/charts/proxy/templates/deployment.yaml

@@ -0,0 +1,102 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "proxy.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "proxy.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  strategy:
+    {{- toYaml .Values.deploymentStrategy | nindent 4 }}
+  selector:
+    matchLabels:
+      {{- include "proxy.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "proxy.selectorLabels" . | nindent 8 }}
+        {{- with .Values.podLabels }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+      annotations:
+        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
+        {{- with .Values.podAnnotations }}
+        {{- toYaml . | nindent 8 }}
+        {{- end }}
+    spec:
+      automountServiceAccountToken: false
+      terminationGracePeriodSeconds: {{ .Values.terminationGracePeriodSeconds }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: {{ .Chart.Name }}
+          image: {{ include "proxy.image" . | quote }}
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          securityContext:
+            {{- toYaml .Values.containerSecurityContext | nindent 12 }}
+          args:
+            - serve
+            - -config
+            - /etc/proxy/{{ .Values.config.existingConfigMapKey }}
+          {{- with .Values.extraEnv }}
+          env:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          {{- with .Values.extraEnvFrom }}
+          envFrom:
+            {{- toYaml . | nindent 12 }}
+          {{- end }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.service.containerPort }}
+              protocol: TCP
+          startupProbe:
+            {{- toYaml .Values.startupProbe | nindent 12 }}
+          readinessProbe:
+            {{- toYaml .Values.readinessProbe | nindent 12 }}
+          livenessProbe:
+            {{- toYaml .Values.livenessProbe | nindent 12 }}
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          volumeMounts:
+            - name: config
+              mountPath: /etc/proxy/{{ .Values.config.existingConfigMapKey }}
+              subPath: {{ .Values.config.existingConfigMapKey }}
+              readOnly: true
+            - name: data
+              mountPath: {{ .Values.persistence.mountPath }}
+      volumes:
+        - name: config
+          configMap:
+            name: {{ include "proxy.configMapName" . }}
+            items:
+              - key: {{ required "config.existingConfigMapKey is required" .Values.config.existingConfigMapKey }}
+                path: {{ .Values.config.existingConfigMapKey }}
+        - name: data
+          {{- if .Values.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ include "proxy.claimName" . }}
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.topologySpreadConstraints }}
+      topologySpreadConstraints:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

deploy/charts/proxy/templates/ingress.yaml

@@ -0,0 +1,39 @@
+{{- if .Values.ingress.enabled }}
+{{- if not .Values.ingress.hosts }}
+{{- fail "ingress.hosts must be set when ingress.enabled=true" }}
+{{- end }}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ include "proxy.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "proxy.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  {{- with .Values.ingress.className }}
+  ingressClassName: {{ . | quote }}
+  {{- end }}
+  {{- with .Values.ingress.tls }}
+  tls:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path | quote }}
+            pathType: {{ .pathType }}
+            backend:
+              service:
+                name: {{ include "proxy.fullname" $ }}
+                port:
+                  number: {{ $.Values.service.port }}
+          {{- end }}
+    {{- end }}
+{{- end }}

deploy/charts/proxy/templates/pvc.yaml

@@ -0,0 +1,22 @@
+{{- if and .Values.persistence.enabled (not .Values.persistence.existingClaim) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "proxy.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "proxy.labels" . | nindent 4 }}
+  {{- with .Values.persistence.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  accessModes:
+    {{- toYaml .Values.persistence.accessModes | nindent 4 }}
+  {{- with .Values.persistence.storageClass }}
+  storageClassName: {{ . | quote }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.persistence.size }}
+{{- end }}

deploy/charts/proxy/templates/service.yaml

@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "proxy.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "proxy.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.service.type }}
+  ports:
+    - name: http
+      port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP
+  selector:
+    {{- include "proxy.selectorLabels" . | nindent 4 }}

deploy/charts/proxy/values.yaml

@@ -0,0 +1,138 @@
+# More than one replica requires config.data.database on Postgres,
+# config.data.storage on object storage, deploymentStrategy: RollingUpdate,
+# and a PVC access mode other than ReadWriteOnce (or persistence disabled).
+replicaCount: 1
+
+nameOverride: ""
+fullnameOverride: ""
+
+image:
+  repository: ghcr.io/git-pkgs/proxy
+  # An empty tag uses the chart appVersion.
+  tag: ""
+  # When set, digest takes precedence over tag.
+  digest: ""
+  pullPolicy: IfNotPresent
+
+imagePullSecrets: []
+
+service:
+  type: ClusterIP
+  port: 8080
+  # Keep this aligned with config.data.listen (or the listen address in an
+  # existing ConfigMap).
+  containerPort: 8080
+
+# The generated configuration is ignored when existingConfigMap is set.
+config:
+  existingConfigMap: ""
+  existingConfigMapKey: config.yaml
+  data:
+    listen: ":8080"
+    # Set this to the URL package-manager clients use to reach the proxy.
+    base_url: "http://localhost:8080"
+    storage:
+      url: "file:///data/artifacts"
+    database:
+      driver: sqlite
+      path: "/data/proxy.db"
+    log:
+      level: info
+      format: json
+
+# Environment variables override values from the configuration file. This is
+# also the recommended way to supply secret values such as database passwords
+# and object-storage credentials.
+extraEnv: []
+#  - name: PROXY_DATABASE_URL
+#    valueFrom:
+#      secretKeyRef:
+#        name: proxy-database
+#        key: url
+
+extraEnvFrom: []
+#  - secretRef:
+#      name: proxy-object-storage
+
+persistence:
+  enabled: true
+  # Keep this aligned with config.data.storage.url and config.data.database.path
+  # (or the equivalent paths in an existing ConfigMap).
+  mountPath: /data
+  existingClaim: ""
+  annotations: {}
+  accessModes:
+    - ReadWriteOnce
+  size: 10Gi
+  storageClass: ""
+
+deploymentStrategy:
+  type: Recreate
+
+ingress:
+  enabled: false
+  className: ""
+  annotations: {}
+  hosts: []
+  #  - host: proxy.example.com
+  #    paths:
+  #      - path: /
+  #        pathType: Prefix
+  tls: []
+  #  - secretName: proxy-tls
+  #    hosts:
+  #      - proxy.example.com
+
+podAnnotations: {}
+podLabels: {}
+
+podSecurityContext:
+  runAsNonRoot: true
+  runAsUser: 1000
+  runAsGroup: 1000
+  fsGroup: 1000
+  seccompProfile:
+    type: RuntimeDefault
+
+containerSecurityContext:
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop:
+      - ALL
+
+resources: {}
+#  requests:
+#    cpu: 100m
+#    memory: 128Mi
+#  limits:
+#    memory: 512Mi
+
+startupProbe:
+  tcpSocket:
+    port: http
+  failureThreshold: 30
+  periodSeconds: 2
+
+# /health checks both the database and storage backends and can take up to ten
+# seconds. It is intentionally a readiness check rather than a liveness check.
+readinessProbe:
+  httpGet:
+    path: /health
+    port: http
+  timeoutSeconds: 11
+  periodSeconds: 15
+  failureThreshold: 2
+
+livenessProbe:
+  tcpSocket:
+    port: http
+  periodSeconds: 20
+  failureThreshold: 3
+
+terminationGracePeriodSeconds: 30
+
+nodeSelector: {}
+tolerations: []
+affinity: {}
+topologySpreadConstraints: []

docs/architecture.md

@@ -169,6 +169,7 @@ metadata_cache (
     storage_path  TEXT NOT NULL,
     etag          TEXT,
     content_type  TEXT,
+    content_encoding TEXT,           -- replayed on serve so signed bytes stay verbatim
     size          INTEGER,           -- BIGINT on Postgres
     fetched_at    DATETIME,
     created_at    DATETIME,
@@ -269,6 +270,10 @@ HTTP protocol handlers for each registry type.
 - `handleIndex()` - Proxy sparse index
 - `handleDownload()` - Serve cached crate
 
+**SwiftHandler:**
+- Proxies the Swift Package Registry v1 read endpoints
+- Rewrites release URLs and caches source archives
+
 ### `internal/server`
 
 HTTP server setup, web UI, and API handlers.
@@ -279,7 +284,7 @@ HTTP server setup, web UI, and API handlers.
 - Web UI under `/ui`: dashboard, package browser, source browser, version comparison
 - Templates are embedded in the binary via `//go:embed`
 - Enrichment API for package metadata, vulnerability scanning, and outdated detection
-- Health, stats, and Prometheus metrics endpoints. `/health` runs an active write → size-check → read → verify → delete probe against the storage backend and returns a structured JSON response (`HealthResponse`) with `"ok"` / `"error"` status per subsystem. Probe results are cached (default 30 s, configurable via `health.storage_probe_interval`) to avoid overwhelming remote backends.
+- Health, stats, and Prometheus metrics endpoints. `/health` runs an active write → size-check → read → verify → delete probe against the storage backend and returns a structured JSON response (`HealthResponse`) with `"ok"` / `"error"` status per subsystem. Probe results are cached (default 30 s, configurable via `health.storage_probe_interval`) to avoid overwhelming remote backends. The response also carries a `circuit_breakers` map reporting each upstream's artifact-fetch breaker as `"open"` or `"closed"`, keyed by the host fetched from (or an opaque placeholder where the fetch URL has no host to read); the same state is published as the `proxy_circuit_breaker_state` gauge on each `/metrics` scrape. An open breaker leaves the overall status `"ok"` — it describes an upstream, not this proxy.
 
 ### `internal/metrics`
 
@@ -353,7 +358,7 @@ Eviction can be implemented as:
 - Fresh data - new versions visible immediately
 - Metadata is small, upstream fetch is fast
 - Set `cache_metadata: true` or use the mirror command to enable metadata caching for offline use via the `metadata_cache` table
-- OCI manifests are the exception: they are cached automatically so previously fetched images remain pullable when the registry or token service is unavailable
+- OCI manifests and tag lists are exceptions: they are cached automatically so previously fetched images remain pullable and tag resolution works when the registry or token service is unavailable
 
 **Why stream artifacts?**
 - Memory efficient - don't load large files into RAM

docs/configuration.md

@@ -108,19 +108,163 @@ log:
 | `log.level` | `PROXY_LOG_LEVEL` | `-log-level` | `debug`, `info`, `warn`, `error` |
 | `log.format` | `PROXY_LOG_FORMAT` | `-log-format` | `text`, `json` |
 
+## Access Log
+
+The optional access log records client requests and each HTTP exchange with an upstream registry. It is always written as JSONL, with one JSON object per line. Records for the same client request share a `request_id`.
+
+```yaml
+access_log:
+  path: "/var/log/proxy/access.jsonl"
+```
+
+| Config | Environment | Flag | Description |
+|--------|-------------|------|-------------|
+| `access_log.path` | `PROXY_ACCESS_LOG_PATH` | `-access-log` | File to append JSONL records to; empty disables the log |
+
+The parent directory must exist and be writable when the proxy starts. A newly created log file is readable and writable only by the proxy process owner.
+
+A request that receives a rate limit response from an upstream can produce records like these:
+
+```json
+{"time":"2026-08-16T12:00:00Z","event":"upstream","request_id":"host/example-000001","method":"GET","url":"https://registry.example/packages/example","status_code":429,"duration_ms":42}
+{"time":"2026-08-16T12:00:00Z","event":"request","request_id":"host/example-000001","method":"GET","path":"/npm/example","status_code":502,"duration_ms":43,"remote_addr":"192.0.2.10:41234"}
+```
+
+Upstream retries and OCI authentication calls are separate `upstream` records, so the log preserves every status returned over the wire. Network failures have an `error` field and no `status_code`. URL credentials, query strings, and fragments are omitted from both upstream URLs and client paths.
+
 ## Upstream Registries
 
-Override default upstream registry URLs:
+Each upstream used by a built-in package route can be set in YAML or JSON under `upstream`, or with its matching environment variable. Existing installations keep the same public upstreams by default. Trailing slashes are ignored.
+
+| Config | Environment | Default |
+|--------|-------------|---------|
+| `upstream.allow_private_hosts` | `PROXY_UPSTREAM_ALLOW_PRIVATE_HOSTS` | `[]` |
+| `upstream.allow_loopback` | `PROXY_UPSTREAM_ALLOW_LOOPBACK` | `false` |
+| `upstream.npm` | `PROXY_UPSTREAM_NPM` | `https://registry.npmjs.org` |
+| `upstream.npm_full_metadata` | `PROXY_UPSTREAM_NPM_FULL_METADATA` | `false` |
+| `upstream.cargo` | `PROXY_UPSTREAM_CARGO` | `https://index.crates.io` |
+| `upstream.cargo_download` | `PROXY_UPSTREAM_CARGO_DOWNLOAD` | `https://static.crates.io/crates` |
+| `upstream.gem` | `PROXY_UPSTREAM_GEM` | `https://rubygems.org` |
+| `upstream.go` | `PROXY_UPSTREAM_GO` | `https://proxy.golang.org` |
+| `upstream.hex` | `PROXY_UPSTREAM_HEX` | `https://repo.hex.pm` |
+| `upstream.hex_api` | `PROXY_UPSTREAM_HEX_API` | `https://hex.pm` |
+| `upstream.pub` | `PROXY_UPSTREAM_PUB` | `https://pub.dev` |
+| `upstream.pypi` | `PROXY_UPSTREAM_PYPI` | `https://pypi.org` |
+| `upstream.pypi_download` | `PROXY_UPSTREAM_PYPI_DOWNLOAD` | `https://files.pythonhosted.org` |
+| `upstream.maven` | `PROXY_UPSTREAM_MAVEN` | `https://repo1.maven.org/maven2` |
+| `upstream.gradle_plugin_portal` | `PROXY_UPSTREAM_GRADLE_PLUGIN_PORTAL` | `https://plugins.gradle.org/m2` |
+| `upstream.nuget` | `PROXY_UPSTREAM_NUGET` | `https://api.nuget.org` |
+| `upstream.nuget_search` | `PROXY_UPSTREAM_NUGET_SEARCH` | `https://azuresearch-usnc.nuget.org` |
+| `upstream.composer` | `PROXY_UPSTREAM_COMPOSER` | `https://packagist.org` |
+| `upstream.composer_repository` | `PROXY_UPSTREAM_COMPOSER_REPOSITORY` | `https://repo.packagist.org` |
+| `upstream.conan` | `PROXY_UPSTREAM_CONAN` | `https://center.conan.io` |
+| `upstream.conda` | `PROXY_UPSTREAM_CONDA` | `https://conda.anaconda.org` |
+| `upstream.cran` | `PROXY_UPSTREAM_CRAN` | `https://cloud.r-project.org` |
+| `upstream.julia` | `PROXY_UPSTREAM_JULIA` | `https://pkg.julialang.org` |
+| `upstream.swift` | `PROXY_UPSTREAM_SWIFT` | `https://tuist.dev/api/registry/swift` |
+| `upstream.oci_default` | `PROXY_UPSTREAM_OCI_DEFAULT` | `https://registry-1.docker.io` |
+| `upstream.debian` | `PROXY_UPSTREAM_DEBIAN` | `http://deb.debian.org/debian` |
+| `upstream.rpm` | `PROXY_UPSTREAM_RPM` | `https://dl.fedoraproject.org/pub/fedora/linux` |
+| `upstream.homebrew_api` | `PROXY_UPSTREAM_HOMEBREW_API` | `https://formulae.brew.sh/api` |
+| `upstream.homebrew_artifact` | `PROXY_UPSTREAM_HOMEBREW_ARTIFACT` | `https://ghcr.io` |
+
+Private, ULA, CGNAT, and loopback addresses are rejected by default. Add each private upstream hostname or IP address to `upstream.allow_private_hosts`. The matching environment variable accepts a comma-separated list. Loopback upstreams also require `upstream.allow_loopback: true`. That setting permits upstream requests and redirects to reach any loopback address.
 
 ```yaml
 upstream:
-  npm: "https://registry.npmjs.org"
-  maven: "https://repo1.maven.org/maven2"
-  gradle_plugin_portal: "https://plugins.gradle.org/m2"
-  cargo: "https://index.crates.io"
-  cargo_download: "https://static.crates.io/crates"
+  allow_private_hosts:
+    - "upstream-proxy.internal"
+  pypi: "http://upstream-proxy.internal/pypi"
+  pypi_download: "http://upstream-proxy.internal/pypi"
 ```
 
+For protocols that use separate metadata and download services, configure both values. They may point to the same endpoint when chaining proxies:
+
+```yaml
+upstream:
+  pypi: "https://upstream-proxy.example.com/pypi"
+  pypi_download: "https://upstream-proxy.example.com/pypi"
+  nuget: "https://upstream-proxy.example.com/nuget"
+  nuget_search: "https://upstream-proxy.example.com/nuget"
+  composer: "https://upstream-proxy.example.com/composer"
+  composer_repository: "https://upstream-proxy.example.com/composer"
+```
+
+`upstream.hex_api` is used for cooldown timestamps and must expose Hex's `/api/packages/{name}` JSON endpoint.
+
+Helm HTTP repositories and additional OCI registries are configured as named maps:
+
+```yaml
+upstream:
+  # Named HTTP Helm chart repositories, served at /helm/{name}/.
+  helm:
+    bitnami: "https://charts.bitnami.com/bitnami"
+
+  # Named OCI registries. Select one with the repository prefix
+  # upstream/{name}/, e.g. oci://proxy.example.com/upstream/ghcr/owner/chart.
+  oci:
+    ghcr: "https://ghcr.io"
+```
+
+Helm HTTP repositories are read-only. The proxy fetches and rewrites each
+repository's `index.yaml` so chart archives are downloaded through the proxy.
+Chart archives are retained only when their SHA-256 digest matches the digest
+listed in the index. Relative and absolute chart URLs are both supported.
+
+Generic HTTP upstreams proxy plain downloads from fixed base URLs:
+
+```yaml
+upstream:
+  # Named HTTP upstreams, served at /generic/{name}/. The rest of the
+  # request path and the query string are appended to the upstream URL.
+  generic:
+    github: "https://github.com"
+    github-api: "https://api.github.com"
+  auth:
+    # Optional: raise the GitHub API rate limit. Scoped to this host only,
+    # so the token is never sent to the object store GitHub redirects to.
+    "https://api.github.com":
+      type: bearer
+      token: "${GITHUB_TOKEN}"
+```
+
+Only configured upstreams are reachable, so this is not an open HTTP proxy.
+Paths shaped like `{owner}/{repo}/releases/download/{tag}/{asset}` are
+version-pinned GitHub release assets: they are stored in the artifact cache
+and served from it without revalidation, including while the upstream is
+down. Every other path is served through the metadata cache (`cache_metadata`
+must be enabled for offline fallback): fresh within `metadata_ttl`, then
+revalidated with the upstream's `ETag`/`Last-Modified`, and served stale with
+a `Warning: 110` header when the upstream fails, refuses or rate-limits the
+request. Metadata responses are buffered up to `metadata_max_size`, so keep
+large mutable downloads (`releases/latest/download/...`) off this route.
+
+This is the cache behind [mise](https://mise.jdx.dev)'s aqua backend; see the
+mise section in the README for the client-side `url_replacements`.
+
+`upstream.oci_default` sets the registry used by unprefixed `/v2` requests,
+while `upstream.oci` selects named registries through the `upstream/{name}/`
+repository prefix. For example, `oci://proxy.example.com/upstream/ghcr/owner/chart`
+uses the `ghcr` registry with `owner/chart` as its repository.
+When the proxy uses plain HTTP (for example `localhost:8080`), pass
+`--plain-http` to Helm OCI commands.
+
+```yaml
+upstream:
+
+  # Named Alpine APK repositories, served at /apk/{name}/.
+  apk:
+    alpine: "https://dl-cdn.alpinelinux.org/alpine"
+```
+
+Alpine APK repositories are read-only. Requests to `/apk/{name}/…` mirror the
+upstream layout, e.g. `/apk/alpine/v3.22/main/x86_64/APKINDEX.tar.gz`. Indexes
+(v2 `APKINDEX.tar.gz`, v3 `Packages.adb`) and detached signatures are cached
+with the metadata TTL and served byte-for-byte unchanged so apk signature
+verification keeps working; `.apk` packages use the shared artifact cache.
+When `upstream.apk` is empty, a single repository named `alpine` pointing at
+the official mirror is available; configuring any entry replaces that default.
+
 ## Authentication
 
 Configure authentication for private upstream registries. The same authentication-aware client is used for metadata and artifact downloads, and credentials can reference environment variables using `${VAR_NAME}` syntax.
@@ -172,6 +316,21 @@ upstream:
       header_value: "${MAVEN_TOKEN}"
 ```
 
+### AWS ECR
+
+Private ECR registries issue authorization tokens that expire after 12 hours. The `ecr` auth type calls `ecr:GetAuthorizationToken` on demand, caches the result, and refreshes it shortly before expiry, so no static credential appears in the config file:
+
+```yaml
+upstream:
+  oci:
+    ecr: "https://123456789012.dkr.ecr.eu-west-1.amazonaws.com"
+  auth:
+    "https://123456789012.dkr.ecr.eu-west-1.amazonaws.com":
+      type: ecr
+```
+
+AWS credentials are resolved by the SDK's default chain, which covers EKS IAM Roles for Service Accounts (IRSA), EC2/ECS instance profiles, `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` environment variables, and `~/.aws/credentials`. The IAM identity needs the `ecr:GetAuthorizationToken` action plus the usual `ecr:BatchGetImage` / `ecr:GetDownloadUrlForLayer` permissions on the target repositories. The region is inferred from private ECR IPv4, dual-stack, and FIPS hostnames. For other endpoint formats, set `region` explicitly or configure a default region for the SDK.
+
 ### URL Matching
 
 Auth keys must be absolute URLs. Matching compares the scheme, host, effective port, and path-segment prefix, preventing credentials for `registry.example.com` from being sent to a lookalike host such as `registry.example.com.evil.test`. The longest matching scope wins, so you can configure different credentials for different paths:
@@ -244,11 +403,108 @@ Currently supported for npm, PyPI, pub.dev, Composer, Cargo, NuGet, Conda, RubyG
 
 Note: Hex cooldown requires disabling registry signature verification since the proxy re-encodes the protobuf payload without the original signature. Set `HEX_NO_VERIFY_REPO_ORIGIN=1` or configure your repo with `no_verify: true`.
 
+## Artifact Scanning
+
+Cooldown only ever looks at a version's *publish timestamp* — it never inspects the actual bytes of an artifact. Artifact scanning runs after a fetched artifact is staged into storage but before it becomes visible from cache, so an external scanner (trivy, ClamAV, Wiz, or any custom service) can block a bad verdict from ever reaching a client.
+
+```yaml
+scanning:
+  enabled: true
+  fail_open: false
+  timeout: 30s
+  signing_key: ${PROXY_SCANNING_SIGNING_KEY}
+  fetch_base_url: http://proxy.internal:8080
+  scanners:
+    - name: clamav
+      url: http://clamav-adapter:8080/scan
+      mode: block
+    - name: trivy
+      url: http://trivy-adapter:8081/scan
+      mode: monitor
+      ecosystems: [npm, pypi]
+```
+
+| Config | Environment | Description |
+|--------|-------------|-------------|
+| `scanning.enabled` | `PROXY_SCANNING_ENABLED` | Turn on the scan gate. When false (default), artifacts are cached exactly as if scanning didn't exist |
+| `scanning.fail_open` | `PROXY_SCANNING_FAIL_OPEN` | Treat scanner errors/timeouts as allow instead of block. Default is fail-closed |
+| `scanning.timeout` | `PROXY_SCANNING_TIMEOUT` | Per-scan-call timeout, Go duration syntax (default `30s`) |
+| `scanning.signing_key` | `PROXY_SCANNING_SIGNING_KEY` | Signs pull requests to the internal scan-fetch route. Required whenever `enabled` is true |
+| `scanning.fetch_base_url` | `PROXY_SCANNING_FETCH_BASE_URL` | Address scanners use to reach this proxy to pull staged artifacts. Defaults to `base_url` |
+| `scanning.scanners` | - | List of external scanning services (YAML only) |
+| `scanning.scanners[].name` | - | Identifies this scanner in logs and metrics |
+| `scanning.scanners[].url` | - | Endpoint the proxy POSTs scan notifications to |
+| `scanning.scanners[].mode` | - | `block` (default) or `monitor` |
+| `scanning.scanners[].ecosystems` | - | Restricts this scanner to specific ecosystems (e.g. `npm`, `pypi`). Empty means all ecosystems |
+| `scanning.scanners[].headers` | - | Extra HTTP headers sent with every scan request (e.g. for authenticating to the scanner service). Values support `${VAR_NAME}` expansion |
+
+### How caching defers to a scan verdict
+
+The proxy never uploads artifact bytes to a scanner. When an artifact is fetched from upstream, it's stored to the configured storage backend first, exactly as without scanning. If scanning is enabled for the artifact's ecosystem, the proxy then notifies each applicable scanner with package metadata and a short-lived, HMAC-signed URL pointing at the internal `/_internal/scan-fetch` route; each scanner GETs that URL itself to pull the exact bytes staged in storage and runs its own scan against them.
+
+Scanners configured for the same ecosystem all run concurrently, never sequentially. The moment any `block`-mode scanner reports a not-allowed verdict (or errors, unless `fail_open` is set), the proxy cancels the in-flight calls to the other scanners and deletes the staged artifact — it's never committed to the cache database, so it was never visible to a client. If nothing blocks, the proxy waits for every `block`-mode scanner to finish before caching the artifact and serving it. A `monitor`-mode scanner's findings are logged and never gate the wait or the caching decision, even when it reports not-allowed.
+
+A blocked download surfaces to the client as `403 Forbidden` with the scanner's reason, across every ecosystem handler.
+
+### Scanner HTTP contract
+
+Any external service that implements this contract can act as a scanner — a trivy wrapper, a clamav-rest bridge, a Wiz connector, or an in-house service. The proxy POSTs a notify request to `scanning.scanners[].url` and waits for a JSON verdict.
+
+**Request**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ecosystem` | string | e.g. `npm`, `pypi`, `cargo` |
+| `name` | string | Package name |
+| `version` | string | Package version |
+| `filename` | string | Artifact filename |
+| `purl` | string | Package URL (PURL) identifying this exact version |
+| `content_type` | string | Artifact content type |
+| `size` | integer | Artifact size in bytes |
+| `fetch_url` | string | Short-lived signed URL; GET this to retrieve the exact staged bytes |
+
+```json
+{
+  "ecosystem": "npm", "name": "left-pad", "version": "1.0.0",
+  "filename": "left-pad-1.0.0.tgz", "purl": "pkg:npm/left-pad@1.0.0",
+  "content_type": "application/octet-stream", "size": 1234,
+  "fetch_url": "https://proxy.internal/_internal/scan-fetch?path=...&exp=...&sig=..."
+}
+```
+
+**Response**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `allowed` | boolean | Whether the artifact may be cached and served |
+| `reason` | string | Human-readable reason, surfaced to the client when `allowed` is false |
+| `findings` | array | Optional list of `{"severity", "title", "description"}` objects |
+
+```json
+{
+  "allowed": false,
+  "reason": "malware detected",
+  "findings": [
+    {"severity": "critical", "title": "Trojan.GenericKD", "description": "..."}
+  ]
+}
+```
+
+The scanner must respond within `scanning.timeout` (default `30s`); a timeout is treated the same as a `block` verdict unless `fail_open` is set.
+
+### The `/_internal/scan-fetch` route
+
+`fetch_url` points at an internal route, `/_internal/scan-fetch`, that streams a staged object straight from the proxy's storage backend via a short-lived HMAC-signed token (`path`, `exp`, `sig` query parameters). This works identically across every storage backend — local filesystem, S3, GCS, Azure — since it never depends on a backend-specific presigned URL, only on the one storage operation every backend already implements.
+
+This route is not part of the public API. It's meant only for scanners to pull artifacts they've been notified about, and should be restricted to internal-network access at the ingress/network-policy layer — the HMAC scoping (one object, a short TTL) limits what a leaked token can do, but isn't a substitute for network restriction. Its query parameters are also documented in the generated [OpenAPI spec](../README.md#openapi-swagger).
+
+The route only exists when scanning is actually configured: it's not mounted at all unless at least one scanner is enabled and `scanning.signing_key` is set, and it also refuses every request with `404` if either condition somehow isn't met at request time. There is no way to reach it, even with a forged token, when scanning is disabled.
+
 ## Metadata Caching
 
 By default the proxy fetches metadata fresh from upstream on every request. Enable `cache_metadata` to store metadata responses in the database and storage backend for offline fallback. When upstream is unreachable, the proxy serves the last cached copy. ETag-based revalidation avoids re-downloading unchanged metadata.
 
-OCI manifests are always cached because cached image blobs cannot be pulled without their manifests. Digest-addressed manifests are immutable and served directly from cache. Tag-addressed manifests follow `metadata_ttl`, revalidate when stale, and fall back to the last cached response when the registry is unavailable.
+OCI manifests and tag lists are always cached because cached image blobs cannot be pulled without their manifests and offline clients may need tag resolution. Digest-addressed manifests are immutable and served directly from cache. Tag-addressed manifests and tag lists follow `metadata_ttl`, revalidate when stale, and fall back to the last cached response when the registry is unavailable.
 
 ```yaml
 cache_metadata: true
@@ -306,6 +562,14 @@ Or via environment variable: `PROXY_MIRROR_API=true`.
 
 When disabled, the endpoints are not registered and return 404.
 
+Start a mirror job with either PURLs or an inline CycloneDX or SPDX JSON document:
+
+```bash
+curl -X POST http://localhost:8080/api/mirror \
+  -H "Content-Type: application/json" \
+  -d '{"sbom":{"bomFormat":"CycloneDX","components":[{"purl":"pkg:npm/lodash@4.17.21"}]}}'
+```
+
 ## Mirror Command
 
 The `proxy mirror` command pre-populates the cache from various sources. It accepts the same storage and database flags as `serve`.

docs/swagger/docs.go

@@ -15,6 +15,61 @@ const docTemplate = `{
     "host": "{{.Host}}",
     "basePath": "{{.BasePath}}",
     "paths": {
+        "/_internal/scan-fetch": {
+            "get": {
+                "description": "Streams the exact bytes staged in storage for a pre-cache security scan.\nRequires a short-lived HMAC-signed token minted by the proxy itself and\ndelivered via the fetch_url field of the scan notify request (see the\nArtifact Scanning section of docs/configuration.md). Not part of the\npublic API; restrict access to the scanner network at the ingress layer.",
+                "produces": [
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "scanning"
+                ],
+                "summary": "Fetch a staged artifact for scanning",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Storage path of the staged artifact",
+                        "name": "path",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Token expiry, Unix seconds",
+                        "name": "exp",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "HMAC-SHA256 signature over the string path|exp",
+                        "name": "sig",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "403": {
+                        "description": "invalid, expired, or tampered token",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "404": {
+                        "description": "object not found in storage, or scanning is not configured",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
         "/api/bulk": {
             "post": {
                 "consumes": [
@@ -538,6 +593,13 @@ const docTemplate = `{
                         "$ref": "#/definitions/server.HealthCheck"
                     }
                 },
+                "circuit_breakers": {
+                    "description": "CircuitBreakers reports the state (\"open\" or \"closed\") of each upstream\nregistry's artifact-fetch circuit breaker, keyed by the host fetched from\nor, where the fetch URL has none to read, by an opaque placeholder\nstanding in for it. It is omitted when no breaker has been created yet.\nAn open breaker fails every artifact fetch it covers without contacting\nthe upstream, but says nothing about this proxy's own health, so it does\nnot change Status.",
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
                 "status": {
                     "type": "string"
                 }

docs/swagger/swagger.json

@@ -8,6 +8,61 @@
     },
     "basePath": "/",
     "paths": {
+        "/_internal/scan-fetch": {
+            "get": {
+                "description": "Streams the exact bytes staged in storage for a pre-cache security scan.\nRequires a short-lived HMAC-signed token minted by the proxy itself and\ndelivered via the fetch_url field of the scan notify request (see the\nArtifact Scanning section of docs/configuration.md). Not part of the\npublic API; restrict access to the scanner network at the ingress layer.",
+                "produces": [
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "scanning"
+                ],
+                "summary": "Fetch a staged artifact for scanning",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Storage path of the staged artifact",
+                        "name": "path",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Token expiry, Unix seconds",
+                        "name": "exp",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "HMAC-SHA256 signature over the string path|exp",
+                        "name": "sig",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "403": {
+                        "description": "invalid, expired, or tampered token",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    "404": {
+                        "description": "object not found in storage, or scanning is not configured",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
         "/api/bulk": {
             "post": {
                 "consumes": [
@@ -531,6 +586,13 @@
                         "$ref": "#/definitions/server.HealthCheck"
                     }
                 },
+                "circuit_breakers": {
+                    "description": "CircuitBreakers reports the state (\"open\" or \"closed\") of each upstream\nregistry's artifact-fetch circuit breaker, keyed by the host fetched from\nor, where the fetch URL has none to read, by an opaque placeholder\nstanding in for it. It is omitted when no breaker has been created yet.\nAn open breaker fails every artifact fetch it covers without contacting\nthe upstream, but says nothing about this proxy's own health, so it does\nnot change Status.",
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
                 "status": {
                     "type": "string"
                 }

go.mod

@@ -1,134 +1,143 @@
 module github.com/git-pkgs/proxy
 
-go 1.25.6
+go 1.26.7
 
 require (
 	github.com/BurntSushi/toml v1.6.0
-	github.com/CycloneDX/cyclonedx-go v0.11.0
-	github.com/git-pkgs/archives v0.5.0
-	github.com/git-pkgs/cooldown v0.1.1
-	github.com/git-pkgs/enrichment v0.6.4
-	github.com/git-pkgs/magic v0.2.0
-	github.com/git-pkgs/purl v0.1.15
-	github.com/git-pkgs/registries v0.6.4
-	github.com/git-pkgs/spdx v0.3.0
-	github.com/git-pkgs/vers v0.3.0
-	github.com/git-pkgs/vulns v0.2.1
-	github.com/go-chi/chi/v5 v5.3.1
+	github.com/CycloneDX/cyclonedx-go v0.12.0
+	github.com/aws/aws-sdk-go-v2/config v1.33.2
+	github.com/aws/aws-sdk-go-v2/service/ecr v1.64.0
+	github.com/git-pkgs/archives v0.7.0
+	github.com/git-pkgs/artifacts v0.2.1
+	github.com/git-pkgs/cooldown v0.2.0
+	github.com/git-pkgs/enrichment v0.7.1
+	github.com/git-pkgs/gcs v0.1.0
+	github.com/git-pkgs/integrity v0.1.1
+	github.com/git-pkgs/magic v0.3.1
+	github.com/git-pkgs/purl v0.1.20
+	github.com/git-pkgs/registries v0.9.1
+	github.com/git-pkgs/spdx v0.3.1
+	github.com/git-pkgs/vers v0.7.0
+	github.com/git-pkgs/vulns v0.2.3
+	github.com/go-chi/chi/v5 v5.3.2
 	github.com/jmoiron/sqlx v1.4.0
 	github.com/lib/pq v1.12.3
+	github.com/opencontainers/go-digest v1.0.0
 	github.com/prometheus/client_golang v1.24.1
-	github.com/prometheus/client_model v0.6.2
+	github.com/prometheus/client_model v0.6.3
 	github.com/spdx/tools-golang v0.5.7
 	github.com/swaggo/swag v1.16.6
 	gocloud.dev v0.46.0
-	golang.org/x/sync v0.22.0
-	google.golang.org/protobuf v1.36.11
+	golang.org/x/sync v0.23.0
+	google.golang.org/protobuf v1.36.12
 	gopkg.in/yaml.v3 v3.0.1
-	modernc.org/sqlite v1.56.0
+	modernc.org/sqlite v1.58.0
 )
 
 require (
-	4d63.com/gocheckcompilerdirectives v1.3.0 // indirect
+	4d63.com/gocheckcompilerdirectives v1.4.0 // indirect
 	4d63.com/gochecknoglobals v0.2.2 // indirect
-	cloud.google.com/go/auth v0.18.2 // indirect
+	charm.land/lipgloss/v2 v2.0.6 // indirect
+	cloud.google.com/go/auth v0.21.0 // indirect
 	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	codeberg.org/chavacava/garif v0.2.0 // indirect
 	codeberg.org/polyfloyd/go-errorlint v1.9.0 // indirect
 	dev.gaijin.team/go/exhaustruct/v4 v4.0.0 // indirect
-	dev.gaijin.team/go/golib v0.6.0 // indirect
+	dev.gaijin.team/go/exhaustruct/v5 v5.0.3 // indirect
+	dev.gaijin.team/go/golib v0.8.1 // indirect
 	github.com/4meepo/tagalign v1.4.3 // indirect
-	github.com/Abirdcfly/dupword v0.1.7 // indirect
+	github.com/Abirdcfly/dupword v0.1.8 // indirect
 	github.com/AdminBenni/iota-mixing v1.0.0 // indirect
-	github.com/AlwxSin/noinlineerr v1.0.5 // indirect
-	github.com/Antonboom/errname v1.1.1 // indirect
-	github.com/Antonboom/nilnil v1.1.1 // indirect
+	github.com/AlwxSin/noinlineerr v1.0.6 // indirect
+	github.com/Antonboom/errname v1.1.2 // indirect
+	github.com/Antonboom/nilnil v1.1.2 // indirect
 	github.com/Antonboom/testifylint v1.6.4 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/storage/azblob v1.6.4 // indirect
 	github.com/AzureAD/microsoft-authentication-library-for-go v1.7.0 // indirect
+	github.com/ClickHouse/clickhouse-go-linter v1.2.1 // indirect
 	github.com/Djarvur/go-err113 v0.1.1 // indirect
 	github.com/KyleBanks/depth v1.2.1 // indirect
-	github.com/Masterminds/semver/v3 v3.4.0 // indirect
-	github.com/MirrexOne/unqueryvet v1.5.3 // indirect
+	github.com/Masterminds/semver/v3 v3.5.0 // indirect
+	github.com/MirrexOne/unqueryvet v1.5.4 // indirect
 	github.com/OpenPeeDeeP/depguard/v2 v2.2.1 // indirect
 	github.com/PuerkitoBio/purell v1.1.1 // indirect
 	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
-	github.com/alecthomas/chroma/v2 v2.23.1 // indirect
+	github.com/alecthomas/chroma/v2 v2.27.0 // indirect
 	github.com/alecthomas/go-check-sumtype v0.3.1 // indirect
 	github.com/alexkohler/nakedret/v2 v2.0.6 // indirect
-	github.com/alexkohler/prealloc v1.0.2 // indirect
+	github.com/alexkohler/prealloc v1.1.0 // indirect
 	github.com/alfatraining/structtag v1.0.0 // indirect
 	github.com/alingse/asasalint v0.0.11 // indirect
 	github.com/alingse/nilnesserr v0.2.0 // indirect
 	github.com/anchore/go-struct-converter v0.1.0 // indirect
 	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
-	github.com/ashanbrown/forbidigo/v2 v2.3.0 // indirect
-	github.com/ashanbrown/makezero/v2 v2.1.0 // indirect
-	github.com/aws/aws-sdk-go-v2 v1.41.9 // indirect
+	github.com/ashanbrown/forbidigo/v2 v2.3.1 // indirect
+	github.com/ashanbrown/makezero/v2 v2.2.1 // indirect
+	github.com/aws/aws-sdk-go-v2 v1.46.0 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11 // indirect
-	github.com/aws/aws-sdk-go-v2/config v1.32.20 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.19 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.25 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.20.2 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.19.1 // indirect
 	github.com/aws/aws-sdk-go-v2/feature/s3/transfermanager v0.2.3 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.25 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.25 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.26 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.10 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.5.2 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.8.2 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.5.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.19 // indirect
 	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.25 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.14.1 // indirect
 	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.25 // indirect
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.1.1 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.19 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.2 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.42.3 // indirect
-	github.com/aws/smithy-go v1.26.0 // indirect
-	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.8.0 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.36.0 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.41.0 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.48.0 // indirect
+	github.com/aws/smithy-go v1.28.1 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/bkielbasa/cyclop v1.2.3 // indirect
 	github.com/blizzy78/varnamelen v0.8.0 // indirect
 	github.com/bombsimon/wsl/v4 v4.7.0 // indirect
-	github.com/bombsimon/wsl/v5 v5.6.0 // indirect
+	github.com/bombsimon/wsl/v5 v5.9.0 // indirect
 	github.com/breml/bidichk v0.3.3 // indirect
 	github.com/breml/errchkjson v0.4.1 // indirect
-	github.com/butuzov/ireturn v0.4.0 // indirect
-	github.com/butuzov/mirror v1.3.0 // indirect
+	github.com/butuzov/ireturn v0.4.1 // indirect
+	github.com/butuzov/mirror v1.3.3 // indirect
 	github.com/catenacyber/perfsprint v0.10.1 // indirect
 	github.com/ccojocar/zxcvbn-go v1.0.4 // indirect
 	github.com/cenk/backoff v2.2.1+incompatible // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/charithe/durationcheck v0.0.11 // indirect
-	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/lipgloss v1.1.0 // indirect
-	github.com/charmbracelet/x/ansi v0.10.1 // indirect
-	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
-	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/charmbracelet/colorprofile v0.4.3 // indirect
+	github.com/charmbracelet/ultraviolet v0.0.0-20260811164956-006e29f97886 // indirect
+	github.com/charmbracelet/x/ansi v0.11.8 // indirect
+	github.com/charmbracelet/x/term v0.2.2 // indirect
+	github.com/charmbracelet/x/termios v0.1.1 // indirect
+	github.com/charmbracelet/x/windows v0.2.2 // indirect
 	github.com/ckaznocha/intrange v0.3.1 // indirect
+	github.com/clipperhouse/displaywidth v0.11.0 // indirect
+	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
 	github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect
 	github.com/curioswitch/go-reassign v0.3.0 // indirect
 	github.com/daixiang0/gci v0.13.7 // indirect
 	github.com/dave/dst v0.27.3 // indirect
-	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/denis-tingaikin/go-header v0.5.0 // indirect
-	github.com/dlclark/regexp2 v1.11.5 // indirect
+	github.com/dlclark/regexp2/v2 v2.2.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/ecosyste-ms/ecosystems-go v0.4.0 // indirect
 	github.com/ettle/strcase v0.2.0 // indirect
 	github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a // indirect
-	github.com/fatih/color v1.18.0 // indirect
+	github.com/fatih/color v1.19.0 // indirect
 	github.com/fatih/structtag v1.2.0 // indirect
-	github.com/firefart/nonamedreturns v1.0.6 // indirect
+	github.com/firefart/nonamedreturns v1.0.8 // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
 	github.com/fzipp/gocyclo v0.6.0 // indirect
-	github.com/ghostiam/protogetter v0.3.20 // indirect
+	github.com/ghostiam/protogetter v0.3.21 // indirect
 	github.com/git-pkgs/packageurl-go v0.3.1 // indirect
-	github.com/git-pkgs/pom v0.1.5 // indirect
+	github.com/git-pkgs/pom v0.1.7 // indirect
 	github.com/github/go-spdx/v2 v2.7.0 // indirect
-	github.com/go-critic/go-critic v0.14.3 // indirect
+	github.com/go-critic/go-critic v0.14.4 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-openapi/jsonpointer v0.19.5 // indirect
@@ -149,83 +158,83 @@ require (
 	github.com/gofrs/flock v0.13.0 // indirect
 	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
 	github.com/golangci/asciicheck v0.5.0 // indirect
-	github.com/golangci/dupl v0.0.0-20250308024227-f665c8d69b32 // indirect
+	github.com/golangci/dupl v0.0.0-20260401084720-c99c5cf5c202 // indirect
 	github.com/golangci/go-printf-func-name v0.1.1 // indirect
-	github.com/golangci/gofmt v0.0.0-20250106114630-d62b90e6713d // indirect
-	github.com/golangci/golangci-lint/v2 v2.10.1 // indirect
+	github.com/golangci/gofmt v0.0.0-20260820135601-e84e05053792 // indirect
+	github.com/golangci/golangci-lint/v2 v2.13.1 // indirect
 	github.com/golangci/golines v0.15.0 // indirect
 	github.com/golangci/misspell v0.8.0 // indirect
 	github.com/golangci/plugin-module-register v0.1.2 // indirect
 	github.com/golangci/revgrep v0.8.0 // indirect
+	github.com/golangci/rowserrcheck v0.0.0-20260419091836-c5f79b8a11ba // indirect
 	github.com/golangci/swaggoswag v0.0.0-20250504205917-77f2aca3143e // indirect
 	github.com/golangci/unconvert v0.0.0-20250410112200-a129a6e6413e // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/google/wire v0.7.0 // indirect
-	github.com/googleapis/enterprise-certificate-proxy v0.3.14 // indirect
-	github.com/googleapis/gax-go/v2 v2.19.0 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.18 // indirect
+	github.com/googleapis/gax-go/v2 v2.23.0 // indirect
 	github.com/gordonklaus/ineffassign v0.2.0 // indirect
 	github.com/gostaticanalysis/analysisutil v0.7.1 // indirect
 	github.com/gostaticanalysis/comment v1.5.0 // indirect
 	github.com/gostaticanalysis/forcetypeassert v0.2.0 // indirect
 	github.com/gostaticanalysis/nilerr v0.1.2 // indirect
 	github.com/hashicorp/go-immutable-radix/v2 v2.1.0 // indirect
-	github.com/hashicorp/go-version v1.8.0 // indirect
+	github.com/hashicorp/go-version v1.9.0 // indirect
 	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/hexops/gotextdiff v1.0.3 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/jgautheron/goconst v1.8.2 // indirect
-	github.com/jingyugao/rowserrcheck v1.1.1 // indirect
+	github.com/jgautheron/goconst v1.11.0 // indirect
 	github.com/jjti/go-spancheck v0.6.5 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/julz/importas v0.2.0 // indirect
 	github.com/karamaru-alpha/copyloopvar v1.2.2 // indirect
-	github.com/kisielk/errcheck v1.9.0 // indirect
+	github.com/kisielk/errcheck v1.20.0 // indirect
 	github.com/kkHAIKE/contextcheck v1.1.6 // indirect
+	github.com/klauspost/compress v1.19.2 // indirect
 	github.com/kulti/thelper v0.7.1 // indirect
 	github.com/kunwardeep/paralleltest v1.0.15 // indirect
 	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/lasiar/canonicalheader v1.1.2 // indirect
 	github.com/ldez/exptostd v0.4.5 // indirect
-	github.com/ldez/gomoddirectives v0.8.0 // indirect
+	github.com/ldez/gomoddirectives v0.9.0 // indirect
 	github.com/ldez/grignotin v0.10.1 // indirect
 	github.com/ldez/structtags v0.6.1 // indirect
 	github.com/ldez/tagliatelle v0.7.2 // indirect
 	github.com/ldez/usetesting v0.5.0 // indirect
 	github.com/leonklingele/grouper v1.1.2 // indirect
-	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.4.1 // indirect
 	github.com/macabu/inamedparam v0.2.0 // indirect
 	github.com/magiconair/properties v1.8.6 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/manuelarte/embeddedstructfieldcheck v0.4.0 // indirect
-	github.com/manuelarte/funcorder v0.5.0 // indirect
+	github.com/manuelarte/funcorder v0.6.0 // indirect
 	github.com/maratori/testableexamples v1.0.1 // indirect
 	github.com/maratori/testpackage v1.1.2 // indirect
 	github.com/matoous/godox v1.1.0 // indirect
-	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-colorable v0.1.15 // indirect
 	github.com/mattn/go-isatty v0.0.24 // indirect
-	github.com/mattn/go-runewidth v0.0.16 // indirect
-	github.com/mgechev/revive v1.14.0 // indirect
+	github.com/mattn/go-runewidth v0.0.24 // indirect
+	github.com/mgechev/revive v1.15.0 // indirect
 	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/moricho/tparallel v0.3.2 // indirect
-	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/nakabonne/nestif v0.3.1 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
 	github.com/nishanths/exhaustive v0.12.0 // indirect
 	github.com/nishanths/predeclared v0.2.2 // indirect
-	github.com/nunnatsa/ginkgolinter v0.23.0 // indirect
-	github.com/oapi-codegen/nullable v1.1.0 // indirect
+	github.com/nunnatsa/ginkgolinter v0.24.0 // indirect
+	github.com/oapi-codegen/nullable v1.2.0 // indirect
 	github.com/oapi-codegen/runtime v1.6.0 // indirect
-	github.com/package-url/packageurl-go v0.1.6 // indirect
-	github.com/pandatix/go-cvss v0.6.2 // indirect
+	github.com/package-url/packageurl-go v0.1.7 // indirect
+	github.com/pandatix/go-cvss v0.6.4 // indirect
 	github.com/pelletier/go-toml v1.9.5 // indirect
-	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/pelletier/go-toml/v2 v2.4.3 // indirect
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
-	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/prometheus/common v0.70.1 // indirect
 	github.com/prometheus/procfs v0.21.1 // indirect
 	github.com/quasilyte/go-ruleguard v0.4.5 // indirect
@@ -233,24 +242,25 @@ require (
 	github.com/quasilyte/gogrep v0.5.0 // indirect
 	github.com/quasilyte/regex/syntax v0.0.0-20210819130434-b3f0c404a727 // indirect
 	github.com/quasilyte/stdinfo v0.0.0-20220114132959-f7386bf02567 // indirect
-	github.com/raeperd/recvcheck v0.2.0 // indirect
+	github.com/raeperd/recvcheck v0.3.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
-	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	github.com/rogpeppe/go-internal v1.16.0 // indirect
 	github.com/rs/dnscache v0.0.0-20230804202142-fc85eb664529 // indirect
 	github.com/rubyist/circuitbreaker v2.2.1+incompatible // indirect
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/ryancurrah/gomodguard v1.4.1 // indirect
-	github.com/ryanrolds/sqlclosecheck v0.5.1 // indirect
+	github.com/ryancurrah/gomodguard/v2 v2.1.3 // indirect
+	github.com/ryanrolds/sqlclosecheck v0.6.0 // indirect
 	github.com/sanposhiho/wastedassign/v2 v2.1.0 // indirect
-	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
 	github.com/sashamelentyev/interfacebloat v1.1.0 // indirect
 	github.com/sashamelentyev/usestdlibvars v1.29.0 // indirect
-	github.com/securego/gosec/v2 v2.23.0 // indirect
-	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/securego/gosec/v2 v2.28.0 // indirect
+	github.com/sirupsen/logrus v1.10.1 // indirect
 	github.com/sivchari/containedctx v1.0.3 // indirect
-	github.com/sonatard/noctx v0.4.0 // indirect
-	github.com/sourcegraph/go-diff v0.7.0 // indirect
+	github.com/sonatard/noctx v0.5.1 // indirect
+	github.com/sourcegraph/go-diff v0.8.0 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.5.0 // indirect
 	github.com/spf13/cobra v1.10.2 // indirect
@@ -259,11 +269,11 @@ require (
 	github.com/spf13/viper v1.12.0 // indirect
 	github.com/ssgreg/nlreturn/v2 v2.2.1 // indirect
 	github.com/stbenjam/no-sprintf-host-port v0.3.1 // indirect
-	github.com/stretchr/objx v0.5.2 // indirect
-	github.com/stretchr/testify v1.11.1 // indirect
+	github.com/stretchr/objx v0.5.3 // indirect
+	github.com/stretchr/testify v1.12.1 // indirect
 	github.com/subosito/gotenv v1.4.1 // indirect
-	github.com/tetafro/godot v1.5.4 // indirect
-	github.com/timakin/bodyclose v0.0.0-20241222091800-1db5c5ca4d67 // indirect
+	github.com/tetafro/godot v1.5.6 // indirect
+	github.com/timakin/bodyclose v0.0.0-20260129054331-73d1f95b84b4 // indirect
 	github.com/timonwong/loggercheck v0.11.0 // indirect
 	github.com/tomarrell/wrapcheck/v2 v2.12.0 // indirect
 	github.com/tommy-muehle/go-mnd/v2 v2.5.1 // indirect
@@ -271,8 +281,8 @@ require (
 	github.com/ultraware/funlen v0.2.0 // indirect
 	github.com/ultraware/whitespace v0.2.0 // indirect
 	github.com/urfave/cli/v2 v2.3.0 // indirect
-	github.com/uudashr/gocognit v1.2.0 // indirect
-	github.com/uudashr/iface v1.4.1 // indirect
+	github.com/uudashr/gocognit v1.2.1 // indirect
+	github.com/uudashr/iface v1.5.0 // indirect
 	github.com/xen0n/gosmopolitan v1.3.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yagipy/maintidx v1.0.0 // indirect
@@ -280,9 +290,9 @@ require (
 	github.com/ykadowak/zerologlint v0.1.5 // indirect
 	gitlab.com/bosi/decorder v0.4.2 // indirect
 	go-simpler.org/musttag v0.14.0 // indirect
-	go-simpler.org/sloglint v0.11.1 // indirect
+	go-simpler.org/sloglint v0.12.0 // indirect
 	go.augendre.info/arangolint v0.4.0 // indirect
-	go.augendre.info/fatcontext v0.9.0 // indirect
+	go.augendre.info/fatcontext v0.10.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/otel v1.44.0 // indirect
 	go.opentelemetry.io/otel/metric v1.44.0 // indirect
@@ -292,28 +302,28 @@ require (
 	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.27.1 // indirect
 	go.yaml.in/yaml/v2 v2.4.4 // indirect
-	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.54.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	golang.org/x/crypto v0.55.0 // indirect
 	golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa // indirect
-	golang.org/x/exp/typeparams v0.0.0-20260209203927-2842357ff358 // indirect
-	golang.org/x/mod v0.37.0 // indirect
-	golang.org/x/net v0.57.0 // indirect
+	golang.org/x/exp/typeparams v0.0.0-20260811152304-ee035b5b010f // indirect
+	golang.org/x/mod v0.40.0 // indirect
+	golang.org/x/net v0.58.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sys v0.47.0 // indirect
-	golang.org/x/text v0.40.0 // indirect
-	golang.org/x/tools v0.47.0 // indirect
+	golang.org/x/text v0.41.0 // indirect
+	golang.org/x/tools v0.49.0 // indirect
 	golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da // indirect
-	google.golang.org/api v0.272.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 // indirect
-	google.golang.org/grpc v1.82.1 // indirect
+	google.golang.org/api v0.288.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260706201446-f0a921348800 // indirect
+	google.golang.org/grpc v1.83.2 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
-	honnef.co/go/tools v0.7.0 // indirect
-	modernc.org/libc v1.74.4 // indirect
+	honnef.co/go/tools v0.8.0 // indirect
+	modernc.org/libc v1.75.6 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
-	modernc.org/memory v1.11.0 // indirect
-	mvdan.cc/gofumpt v0.9.2 // indirect
-	mvdan.cc/unparam v0.0.0-20251027182757-5beb8c8f8f15 // indirect
+	modernc.org/memory v1.12.1 // indirect
+	mvdan.cc/gofumpt v0.11.0 // indirect
+	mvdan.cc/unparam v0.0.0-20260818115549-3f964bcb5673 // indirect
 	sigs.k8s.io/yaml v1.6.0 // indirect
 )
 

go.sum

@@ -1,13 +1,15 @@
-4d63.com/gocheckcompilerdirectives v1.3.0 h1:Ew5y5CtcAAQeTVKUVFrE7EwHMrTO6BggtEj8BZSjZ3A=
-4d63.com/gocheckcompilerdirectives v1.3.0/go.mod h1:ofsJ4zx2QAuIP/NO/NAh1ig6R1Fb18/GI7RVMwz7kAY=
+4d63.com/gocheckcompilerdirectives v1.4.0 h1:ZLq62rbGWVmQhiZ8kuNVIT/M09xCSTdJz9K3xOdT/CY=
+4d63.com/gocheckcompilerdirectives v1.4.0/go.mod h1:9ZOAiMOjqC/nRwci2fcUXVHUNLG/cH6r6rhUh+jTFtQ=
 4d63.com/gochecknoglobals v0.2.2 h1:H1vdnwnMaZdQW/N+NrkT1SZMTBmcwHe9Vq8lJcYYTtU=
 4d63.com/gochecknoglobals v0.2.2/go.mod h1:lLxwTQjL5eIesRbvnzIP3jZtG140FnTdz+AlMa+ogt0=
-cel.dev/expr v0.25.1 h1:1KrZg61W6TWSxuNZ37Xy49ps13NUovb66QLprthtwi4=
-cel.dev/expr v0.25.1/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4=
+cel.dev/expr v0.25.2 h1:K6j46C81hXtZQfuX60cVWQFBJahKSE2gfRbNuvr5bFs=
+cel.dev/expr v0.25.2/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4=
+charm.land/lipgloss/v2 v2.0.6 h1:EaGKeuA8FvF+v2BT5VmZd2LoYLaMZJXA5n34th8nCIQ=
+charm.land/lipgloss/v2 v2.0.6/go.mod h1:ipDDJNSGa1hlwDtSfW1s2/xR8Vdhbut4PXh2zEKZd0Q=
 cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE=
 cloud.google.com/go v0.123.0/go.mod h1:xBoMV08QcqUGuPW65Qfm1o9Y4zKZBpGS+7bImXLTAZU=
-cloud.google.com/go/auth v0.18.2 h1:+Nbt5Ev0xEqxlNjd6c+yYUeosQ5TtEUaNcN/3FozlaM=
-cloud.google.com/go/auth v0.18.2/go.mod h1:xD+oY7gcahcu7G2SG2DsBerfFxgPAJz17zz2joOFF3M=
+cloud.google.com/go/auth v0.21.0 h1:g/QwYfYb2Ai6HH8oomAOyBaIHLbscZ4+T/F/f5JZHkE=
+cloud.google.com/go/auth v0.21.0/go.mod h1:M9o2Oz+YI2jAfxewJgb1vyI3vceHF+eohmxyzmrl+9s=
 cloud.google.com/go/auth/oauth2adapt v0.2.8 h1:keo8NaayQZ6wimpNSmW5OPc283g65QNIiLpZnkHRbnc=
 cloud.google.com/go/auth/oauth2adapt v0.2.8/go.mod h1:XQ9y31RkqZCcwJWNSx2Xvric3RrU88hAYYbjDWYDL+c=
 cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
@@ -24,23 +26,25 @@ codeberg.org/polyfloyd/go-errorlint v1.9.0 h1:VkdEEmA1VBpH6ecQoMR4LdphVI3fA4RrCh
 codeberg.org/polyfloyd/go-errorlint v1.9.0/go.mod h1:GPRRu2LzVijNn4YkrZYJfatQIdS+TrcK8rL5Xs24qw8=
 dev.gaijin.team/go/exhaustruct/v4 v4.0.0 h1:873r7aNneqoBB3IaFIzhvt2RFYTuHgmMjoKfwODoI1Y=
 dev.gaijin.team/go/exhaustruct/v4 v4.0.0/go.mod h1:aZ/k2o4Y05aMJtiux15x8iXaumE88YdiB0Ai4fXOzPI=
-dev.gaijin.team/go/golib v0.6.0 h1:v6nnznFTs4bppib/NyU1PQxobwDHwCXXl15P7DV5Zgo=
-dev.gaijin.team/go/golib v0.6.0/go.mod h1:uY1mShx8Z/aNHWDyAkZTkX+uCi5PdX7KsG1eDQa2AVE=
+dev.gaijin.team/go/exhaustruct/v5 v5.0.3 h1:yOeA7DNjlT8y4yfmN6nWWYYggA13N523YAj9/TXbuTM=
+dev.gaijin.team/go/exhaustruct/v5 v5.0.3/go.mod h1:KwtBsX8nHHH1YxhxkpiBq6bfsmw5WnazWpNvJPHgY9Y=
+dev.gaijin.team/go/golib v0.8.1 h1:JYju4x9BSo+QD/AYeHULVDcvEhiFg8wOi6pT0IaZF5E=
+dev.gaijin.team/go/golib v0.8.1/go.mod h1:c5fu7t1RSGMxSQgcUYO1sODbzsYnOCXJLmHeNG1Eb+0=
 filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
 filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 github.com/4meepo/tagalign v1.4.3 h1:Bnu7jGWwbfpAie2vyl63Zup5KuRv21olsPIha53BJr8=
 github.com/4meepo/tagalign v1.4.3/go.mod h1:00WwRjiuSbrRJnSVeGWPLp2epS5Q/l4UEy0apLLS37c=
-github.com/Abirdcfly/dupword v0.1.7 h1:2j8sInznrje4I0CMisSL6ipEBkeJUJAmK1/lfoNGWrQ=
-github.com/Abirdcfly/dupword v0.1.7/go.mod h1:K0DkBeOebJ4VyOICFdppB23Q0YMOgVafM0zYW0n9lF4=
+github.com/Abirdcfly/dupword v0.1.8 h1:SrhcUuGsROBuChFxHALRYzyyPODWn9zwghmzPvD9Cd8=
+github.com/Abirdcfly/dupword v0.1.8/go.mod h1:XZrhVnI7YGpsTiWZANSQaBJ4QpL/Tq5vIEdKJJAs9WI=
 github.com/AdminBenni/iota-mixing v1.0.0 h1:Os6lpjG2dp/AE5fYBPAA1zfa2qMdCAWwPMCgpwKq7wo=
 github.com/AdminBenni/iota-mixing v1.0.0/go.mod h1:i4+tpAaB+qMVIV9OK3m4/DAynOd5bQFaOu+2AhtBCNY=
-github.com/AlwxSin/noinlineerr v1.0.5 h1:RUjt63wk1AYWTXtVXbSqemlbVTb23JOSRiNsshj7TbY=
-github.com/AlwxSin/noinlineerr v1.0.5/go.mod h1:+QgkkoYrMH7RHvcdxdlI7vYYEdgeoFOVjU9sUhw/rQc=
-github.com/Antonboom/errname v1.1.1 h1:bllB7mlIbTVzO9jmSWVWLjxTEbGBVQ1Ff/ClQgtPw9Q=
-github.com/Antonboom/errname v1.1.1/go.mod h1:gjhe24xoxXp0ScLtHzjiXp0Exi1RFLKJb0bVBtWKCWQ=
-github.com/Antonboom/nilnil v1.1.1 h1:9Mdr6BYd8WHCDngQnNVV0b554xyisFioEKi30sksufQ=
-github.com/Antonboom/nilnil v1.1.1/go.mod h1:yCyAmSw3doopbOWhJlVci+HuyNRuHJKIv6V2oYQa8II=
+github.com/AlwxSin/noinlineerr v1.0.6 h1:KAvuxunTe9QxvqrFB7nZTdb/7Wzas4AvifslTnG0Ld8=
+github.com/AlwxSin/noinlineerr v1.0.6/go.mod h1:+QgkkoYrMH7RHvcdxdlI7vYYEdgeoFOVjU9sUhw/rQc=
+github.com/Antonboom/errname v1.1.2 h1:dxwONZJua3VB8Xh/VaCjqAcqF645sWWv7xj26zy7tdQ=
+github.com/Antonboom/errname v1.1.2/go.mod h1:YeZIpgLMxT+SNkruGgYkLhzq/9vs3fsolTZegKaKDZI=
+github.com/Antonboom/nilnil v1.1.2 h1:aNlFuJhaEseXe4fHO3xbjXlSeEiQVYa2lEkWD2s2hAY=
+github.com/Antonboom/nilnil v1.1.2/go.mod h1:0ynwvphOLmAuMwTNDyBnDZmSwZoDpcFXmUHmzoHH2WA=
 github.com/Antonboom/testifylint v1.6.4 h1:gs9fUEy+egzxkEbq9P4cpcMB6/G0DYdMeiFS87UiqmQ=
 github.com/Antonboom/testifylint v1.6.4/go.mod h1:YO33FROXX2OoUfwjz8g+gUxQXio5i9qpVy7nXGbxDD4=
 github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0 h1:fou+2+WFTib47nS+nz/ozhEBnvU96bKHy6LjRsY4E28=
@@ -62,22 +66,24 @@ github.com/AzureAD/microsoft-authentication-library-for-go v1.7.0/go.mod h1:HKpQ
 github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
 github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
 github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
-github.com/CycloneDX/cyclonedx-go v0.11.0 h1:GokP8FiRC+foiuwWhSSLpSD5H4hSWtGnR3wo7apkBFI=
-github.com/CycloneDX/cyclonedx-go v0.11.0/go.mod h1:vUvbCXQsEm48OI6oOlanxstwNByXjCZ2wuleUlwGEO8=
+github.com/ClickHouse/clickhouse-go-linter v1.2.1 h1:zGEKIyd5YL08ieWG/LOUmlau2DxbxPVOfAeo+4Jz3ck=
+github.com/ClickHouse/clickhouse-go-linter v1.2.1/go.mod h1:pLorS7ffPTfuUV9M0SJgfHA/h/WQPQUk2FWG9x74cQ4=
+github.com/CycloneDX/cyclonedx-go v0.12.0 h1:/7Jum36UA6V043tQZ/fE3jf+Nf9gn/qxUFfd7QReMy8=
+github.com/CycloneDX/cyclonedx-go v0.12.0/go.mod h1:V2577HhxDDCDLYfkm55WJrz16nHTfyQZwcWUBSG7Z28=
 github.com/Djarvur/go-err113 v0.1.1 h1:eHfopDqXRwAi+YmCUas75ZE0+hoBHJ2GQNLYRSxao4g=
 github.com/Djarvur/go-err113 v0.1.1/go.mod h1:IaWJdYFLg76t2ihfflPZnM1LIQszWOsFDh2hhhAVF6k=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.32.0 h1:rIkQfkCOVKc1OiRCNcSDD8ml5RJlZbH/Xsq7lbpynwc=
-github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.32.0/go.mod h1:RD2SsorTmYhF6HkTmDw7KmPYQk8OBYwTkuasChwv7R4=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.33.0 h1:l7+6kwRMJNwdCvYdDl7Eax+wzEYHSnNY7zrrfbhDdTA=
+github.com/GoogleCloudPlatform/opentelemetry-operations-go/detectors/gcp v1.33.0/go.mod h1:pJTkW8hEUIIi3Pf65lPZOnn4Y81yCllX6IWk2jNXdkM=
 github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.55.0 h1:UnDZ/zFfG1JhH/DqxIZYU/1CUAlTUScoXD/LcM2Ykk8=
 github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/metric v0.55.0/go.mod h1:IA1C1U7jO/ENqm/vhi7V9YYpBsp+IMyqNrEN94N7tVc=
 github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.55.0 h1:0s6TxfCu2KHkkZPnBfsQ2y5qia0jl3MMrmBhu3nCOYk=
 github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.55.0/go.mod h1:Mf6O40IAyB9zR/1J8nGDDPirZQQPbYJni8Yisy7NTMc=
 github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc=
 github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE=
-github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
-github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
-github.com/MirrexOne/unqueryvet v1.5.3 h1:LpT3rsH+IY3cQddWF9bg4C7jsbASdGnrOSofY8IPEiw=
-github.com/MirrexOne/unqueryvet v1.5.3/go.mod h1:fs9Zq6eh1LRIhsDIsxf9PONVUjYdFHdtkHIgZdJnyPU=
+github.com/Masterminds/semver/v3 v3.5.0 h1:kQceYJfbupGfZOKZQg0kou0DgAKhzDg2NZPAwZ/2OOE=
+github.com/Masterminds/semver/v3 v3.5.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
+github.com/MirrexOne/unqueryvet v1.5.4 h1:38QOxShO7JmMWT+eCdDMbcUgGCOeJphVkzzRgyLJgsQ=
+github.com/MirrexOne/unqueryvet v1.5.4/go.mod h1:fs9Zq6eh1LRIhsDIsxf9PONVUjYdFHdtkHIgZdJnyPU=
 github.com/OpenPeeDeeP/depguard/v2 v2.2.1 h1:vckeWVESWp6Qog7UZSARNqfu/cZqvki8zsuj3piCMx4=
 github.com/OpenPeeDeeP/depguard/v2 v2.2.1/go.mod h1:q4DKzC4UcVaAvcfd41CZh0PWpGgzrVxUYBlgKNGquUo=
 github.com/PuerkitoBio/purell v1.1.1 h1:WEQqlqaGbrPkxLJWfBwQmfEAE1Z7ONdDLqrN38tNFfI=
@@ -87,16 +93,16 @@ github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdko
 github.com/RaveNoX/go-jsoncommentstrip v1.0.0/go.mod h1:78ihd09MekBnJnxpICcwzCMzGrKSKYe4AqU6PDYYpjk=
 github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
 github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
-github.com/alecthomas/chroma/v2 v2.23.1 h1:nv2AVZdTyClGbVQkIzlDm/rnhk1E9bU9nXwmZ/Vk/iY=
-github.com/alecthomas/chroma/v2 v2.23.1/go.mod h1:NqVhfBR0lte5Ouh3DcthuUCTUpDC9cxBOfyMbMQPs3o=
+github.com/alecthomas/chroma/v2 v2.27.0 h1:FodwmyOBgJULFYmDqibcp9pvfDLWdtPRh9v/r5BXYZs=
+github.com/alecthomas/chroma/v2 v2.27.0/go.mod h1:NjJ3ciIgrqBNeIkWZ4e46nseoLDslxU1LmfCoL+wcY8=
 github.com/alecthomas/go-check-sumtype v0.3.1 h1:u9aUvbGINJxLVXiFvHUlPEaD7VDULsrxJb4Aq31NLkU=
 github.com/alecthomas/go-check-sumtype v0.3.1/go.mod h1:A8TSiN3UPRw3laIgWEUOHHLPa6/r9MtoigdlP5h3K/E=
 github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs=
 github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/alexkohler/nakedret/v2 v2.0.6 h1:ME3Qef1/KIKr3kWX3nti3hhgNxw6aqN5pZmQiFSsuzQ=
 github.com/alexkohler/nakedret/v2 v2.0.6/go.mod h1:l3RKju/IzOMQHmsEvXwkqMDzHHvurNQfAgE1eVmT40Q=
-github.com/alexkohler/prealloc v1.0.2 h1:MPo8cIkGkZytq7WNH9UHv3DIX1mPz1RatPXnZb0zHWQ=
-github.com/alexkohler/prealloc v1.0.2/go.mod h1:fT39Jge3bQrfA7nPMDngUfvUbQGQeJyGQnR+913SCig=
+github.com/alexkohler/prealloc v1.1.0 h1:cKGRBqlXw5iyQGLYhrXrDlcHxugXpTq4tQ5c91wkf8M=
+github.com/alexkohler/prealloc v1.1.0/go.mod h1:fT39Jge3bQrfA7nPMDngUfvUbQGQeJyGQnR+913SCig=
 github.com/alfatraining/structtag v1.0.0 h1:2qmcUqNcCoyVJ0up879K614L9PazjBSFruTB0GOFjCc=
 github.com/alfatraining/structtag v1.0.0/go.mod h1:p3Xi5SwzTi+Ryj64DqjLWz7XurHxbGsq6y3ubePJPus=
 github.com/alingse/asasalint v0.0.11 h1:SFwnQXJ49Kx/1GghOFz1XGqHYKp21Kq1nHad/0WQRnw=
@@ -107,50 +113,50 @@ github.com/anchore/go-struct-converter v0.1.0 h1:2rDRssAl6mgKBSLNiVCMADgZRhoqtw9
 github.com/anchore/go-struct-converter v0.1.0/go.mod h1:rYqSE9HbjzpHTI74vwPvae4ZVYZd1lue2ta6xHPdblA=
 github.com/apapsch/go-jsonmerge/v2 v2.0.0 h1:axGnT1gRIfimI7gJifB699GoE/oq+F2MU7Dml6nw9rQ=
 github.com/apapsch/go-jsonmerge/v2 v2.0.0/go.mod h1:lvDnEdqiQrp0O42VQGgmlKpxL1AP2+08jFMw88y4klk=
-github.com/ashanbrown/forbidigo/v2 v2.3.0 h1:OZZDOchCgsX5gvToVtEBoV2UWbFfI6RKQTir2UZzSxo=
-github.com/ashanbrown/forbidigo/v2 v2.3.0/go.mod h1:5p6VmsG5/1xx3E785W9fouMxIOkvY2rRV9nMdWadd6c=
-github.com/ashanbrown/makezero/v2 v2.1.0 h1:snuKYMbqosNokUKm+R6/+vOPs8yVAi46La7Ck6QYSaE=
-github.com/ashanbrown/makezero/v2 v2.1.0/go.mod h1:aEGT/9q3S8DHeE57C88z2a6xydvgx8J5hgXIGWgo0MY=
-github.com/aws/aws-sdk-go-v2 v1.41.9 h1:/rYeyO2+HrMztAmxAq9++XJtFMqSIpSsNA0yDGALYq4=
-github.com/aws/aws-sdk-go-v2 v1.41.9/go.mod h1:+HsoOEX80qAVUitj1A2DhCNTjmb3edVyuDypb6LNEeo=
+github.com/ashanbrown/forbidigo/v2 v2.3.1 h1:KAZijvQ7zeIBKbhikT4jCm0TLYXC4u78bTiLh/8JROI=
+github.com/ashanbrown/forbidigo/v2 v2.3.1/go.mod h1:2QDkLTzU6TV937eFROamXrW92M3paehdae4HCDCOZCM=
+github.com/ashanbrown/makezero/v2 v2.2.1 h1:A7uU8dgB1PA9aelTxHMfHIQ8Qev8AB3JLxJUBUsejqM=
+github.com/ashanbrown/makezero/v2 v2.2.1/go.mod h1:aEGT/9q3S8DHeE57C88z2a6xydvgx8J5hgXIGWgo0MY=
+github.com/aws/aws-sdk-go-v2 v1.46.0 h1:1kt7m/EKcEHt5mlyyxx9cSlMddRPIKbjb6DIQsu4HPk=
+github.com/aws/aws-sdk-go-v2 v1.46.0/go.mod h1:bttEH6JqnUL8LepvDVfdrds/fZ5bCIxzpe3abyUrhDU=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11 h1:h5+3VT69KUBK24grGuuA5saDJTj2IIjLb9au668Fo5I=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11/go.mod h1:dnakxebH6UwFvcvujL0LVggYQ8nEvBGjU4G/V79Nv94=
-github.com/aws/aws-sdk-go-v2/config v1.32.20 h1:8VMDnWc/kEzxsI/1ngGM9mG81a8IGmIHD8KLcYGwagc=
-github.com/aws/aws-sdk-go-v2/config v1.32.20/go.mod h1:PuwEpciweIXGULWeOeSTXtSbH4CW9mWdWrhdCKQI1sM=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.19 h1:yuFzSV1U0aRNYCQGVaTY2zW2M/L93pYHnXnrJUphYhU=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.19/go.mod h1:7y63L1kGzeoDlJaQ3Z578KrnmfBut96JjvJUzGwR+YE=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.25 h1:0w6dCiO8iez+YKwRhRBlL1CH/E3GTfdkuzrwj1by8vo=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.25/go.mod h1:9FDWUothyr5RCRAHc45XOiVCzUR8n/IhCYX+uVqw6vk=
+github.com/aws/aws-sdk-go-v2/config v1.33.2 h1:Pj4+nF2kc4Z+1BJysVPnX9d5dMN7IYFXR4UJaWK2IpA=
+github.com/aws/aws-sdk-go-v2/config v1.33.2/go.mod h1:Igw+HTwbR2tsTU/ydifAS9EHAFJ2s/FCgkwQWFnAdE4=
+github.com/aws/aws-sdk-go-v2/credentials v1.20.2 h1:VQjZODPNfdikCX2ZZrltw4zNLkcwjyUFDUl2vT9yTwg=
+github.com/aws/aws-sdk-go-v2/credentials v1.20.2/go.mod h1:OmeHCn28vZylsBvalLDf7t8fuJ2rHYQprJs+7WuxniI=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.19.1 h1:YIEBqcqRnpi4Pfv0YHImtgi6czGCwKHANC7SwmUAVD0=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.19.1/go.mod h1:imEf0oufgAo8KAkCHhrOdqGEC0YWx1PPBQH82shSxGw=
 github.com/aws/aws-sdk-go-v2/feature/s3/transfermanager v0.2.3 h1:w5OoDiMN6x53ROmiIImGzmVcxXv2q1GXY+aKV4WAJYM=
 github.com/aws/aws-sdk-go-v2/feature/s3/transfermanager v0.2.3/go.mod h1:dAhgYp776bX3LuWvnSCFwQEjNs6fuFg7YXIy5PXcP3Q=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.25 h1:Uii3frf9ztec/ABM2/FSH9/z7PLzxfpG8h4RpkUFflQ=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.25/go.mod h1:G6kntsA2GorAxDPbap6xgB2F+amSLUF8GJTi7PUoX44=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.25 h1:r1+/l6m+WaUJF9HISEsNOLHSNj5EXYQxK8VX6Cz9NlA=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.25/go.mod h1:cKf+D+NMDK1LndD7BowHbBZPgR9V0/5HubH0PFWvA+c=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.26 h1:A1PmWU2zfkIm9EyFlJncFXL4W4phML+h8KjltUsCvNQ=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.26/go.mod h1:dY4MRzXEizrD4hqtpKvWVGPX7QleSGGVY+EBolo1RmM=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.10 h1:d5/908OJ4bXg8lyjeMPvXetEKqoDoLi5Owy1zNue3yg=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.10/go.mod h1:a57l7Hwh+FWI+we50g5NPJHYUKeJKfXbc4w8SyXu8Ig=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.5.2 h1:q/PSLGuRWCChWg+dLnb9dWOnrCxJtnboXbBtFoqqRrI=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.5.2/go.mod h1:TD1jvU2LvXkJexct5vBqcd8QlNXh5EmRUeL/Z32p0n4=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.8.2 h1:6fl86IPqKEXoySqiOWdfgbEp9OVbn44zTfEICNEBDhY=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.8.2/go.mod h1:63HDfhFkdzBpI8WGXTSKUHPKS6mqldj4u3LJW7RZtSU=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.5.1 h1:yhw5KD1phVyP9vijxOUzDfEtJx+bt+L63k+VfuiYFAA=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.5.1/go.mod h1:ZW2e0d7DYlRxlS9hEiMXE47gTdX5KRN4byUiNbUpG+Q=
+github.com/aws/aws-sdk-go-v2/service/ecr v1.64.0 h1:iOYGE9bHGhMQYtbjEcgDJEobWIhKoUvE71m+Jm0vZgU=
+github.com/aws/aws-sdk-go-v2/service/ecr v1.64.0/go.mod h1:5ccNgipT/aF9MWzTrKkyGJaCozPt+D6LOD4RFIdP22k=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.19 h1:bAdDl/HkGCcGPoe25ToSHEw23VIxt6CT5fLcg111BKg=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.19/go.mod h1:KaUzbLxv4CeSxh6ZCl9B4m7CuFenS8kUEaDs+f/DQr4=
 github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18 h1:W/EyPFl9A5rXrtoilfwHYEvzHER+K4SpBPtMXi24Mos=
 github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.18/go.mod h1:UG50K+pvd/uy6xExbobg0rjqFBFZe6I3l75EPDZw4tg=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.25 h1:dD3dhHNglpd98gs72my22Ndqi1hqQGllFFg1F+twfxg=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.25/go.mod h1:0yAbjPfd64gG7mj85RW+fMEYdfBgCRZw8g/oWcL1pjc=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.14.1 h1:RmmWQPREQdk9U+PfqeHW3MqZaBaNK7TpV9W3RY+b+7g=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.14.1/go.mod h1:0A3W4F+68ZnNk5XcNL/e9HFMwnP8RlEicFfy6eOEDyw=
 github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.25 h1:2pQEbwf+/6EDbiit/GcBE2K4IUpMZymaA0kOz3xK978=
 github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.25/go.mod h1:KvT6NCcQ0EZ+ZkVRrlBMt04Po3ok23YELEp7WimhLhM=
 github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2 h1:ie4ElCmUKS26pzrZcIk/lmt4yWjAqLLcawstyQCh298=
 github.com/aws/aws-sdk-go-v2/service/s3 v1.102.2/go.mod h1:zjsomFeX5duj+4PlMB+o4JoWTIx+G0XMyzjYrUbQkN0=
-github.com/aws/aws-sdk-go-v2/service/signin v1.1.1 h1:1VwbP3qMNfxUDEXWki4rCE5iA+44VA1lokTz9HasGzw=
-github.com/aws/aws-sdk-go-v2/service/signin v1.1.1/go.mod h1:vUtyoSj0OPji3kjIVSc/GlKuWEiL33f/WFxl6dmpy/A=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.19 h1:N6pIsdFOW1Kd9S4KyFKXdGRBojPPxkP32+uHFWLv4Hc=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.19/go.mod h1:3gt5WJArFooNmyLONS+h/R4J+o86II8du38IgCwj9dE=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.2 h1:hc+lBYiiTr8Zk4MTzIsQ92MeDWCIDvWGmzKUWOaBcOg=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.36.2/go.mod h1:hU6fqB3OJA6/ePheD47LQnxvjYk6br6PtQxs+Q9ojvk=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.3 h1:ErklX/7uhSbkAAeyQD/Y1OoQ9hO3SJXQNEgksORW3Js=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.3/go.mod h1:ULe4HCzfKPiR6R3HEurE3b1upEkuk8AkMrOKtaOxKO8=
-github.com/aws/smithy-go v1.26.0 h1:9ouqbi+NyKP7fV3Te7UElCwdAb6Y8uk7LGwPE5tVe/s=
-github.com/aws/smithy-go v1.26.0/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
-github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
-github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/aws/aws-sdk-go-v2/service/signin v1.8.0 h1:bSvKIoLuRGFqGwASgeCQncCJDi9YKKBDEmCEZzOX1uU=
+github.com/aws/aws-sdk-go-v2/service/signin v1.8.0/go.mod h1:9IqUlsJDbUPcg6cgx3WEzXdjrbWzLDQrak0aaSqlTcI=
+github.com/aws/aws-sdk-go-v2/service/sso v1.36.0 h1:iivsh357VnfIc18IFWSuoyQEluf8frfWf4cL2Y0JUQw=
+github.com/aws/aws-sdk-go-v2/service/sso v1.36.0/go.mod h1:tWuiVBUtPBr8/rgRiYS8Uf85sHcAN+G7XS3D3CEoUh8=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.41.0 h1:wVxM3QzSKIK8tSN6OGgezp9OK91lCLH2zhmRInN9rFM=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.41.0/go.mod h1:naFe83jSMuYkH+QjQPX8n1MLhBkeCFM5Lsnh5m5wz3c=
+github.com/aws/aws-sdk-go-v2/service/sts v1.48.0 h1:RzZVCzYM19vhJCT5s6vO2wN8ie770Li/TmbAZ9B6N7E=
+github.com/aws/aws-sdk-go-v2/service/sts v1.48.0/go.mod h1:mKo/CzaCz8qytGW70NG4vIIGAx1HXTlb5lHNkC5k3lk=
+github.com/aws/smithy-go v1.28.1 h1:R/nXH00c8qcfCzQVELtRw+eLQWtzv+VAIEFJ1/xxXlQ=
+github.com/aws/smithy-go v1.28.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
 github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
 github.com/bkielbasa/cyclop v1.2.3 h1:faIVMIGDIANuGPWH031CZJTi2ymOQBULs9H21HSMa5w=
@@ -160,18 +166,18 @@ github.com/blizzy78/varnamelen v0.8.0/go.mod h1:V9TzQZ4fLJ1DSrjVDfl89H7aMnTvKkAp
 github.com/bmatcuk/doublestar v1.1.1/go.mod h1:UD6OnuiIn0yFxxA2le/rnRU1G4RaI4UvFv1sNto9p6w=
 github.com/bombsimon/wsl/v4 v4.7.0 h1:1Ilm9JBPRczjyUs6hvOPKvd7VL1Q++PL8M0SXBDf+jQ=
 github.com/bombsimon/wsl/v4 v4.7.0/go.mod h1:uV/+6BkffuzSAVYD+yGyld1AChO7/EuLrCF/8xTiapg=
-github.com/bombsimon/wsl/v5 v5.6.0 h1:4z+/sBqC5vUmSp1O0mS+czxwH9+LKXtCWtHH9rZGQL8=
-github.com/bombsimon/wsl/v5 v5.6.0/go.mod h1:Uqt2EfrMj2NV8UGoN1f1Y3m0NpUVCsUdrNCdet+8LvU=
+github.com/bombsimon/wsl/v5 v5.9.0 h1:WCrgZ7RQnZO5oEwbVTlYgBdU3wL294kR1BSWV8vTfsU=
+github.com/bombsimon/wsl/v5 v5.9.0/go.mod h1:kjo4HiAV5FDkHC8/uzJq9mBffEEd6WT/nvN7DoMovDM=
 github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M=
 github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0=
 github.com/breml/bidichk v0.3.3 h1:WSM67ztRusf1sMoqH6/c4OBCUlRVTKq+CbSeo0R17sE=
 github.com/breml/bidichk v0.3.3/go.mod h1:ISbsut8OnjB367j5NseXEGGgO/th206dVa427kR8YTE=
 github.com/breml/errchkjson v0.4.1 h1:keFSS8D7A2T0haP9kzZTi7o26r7kE3vymjZNeNDRDwg=
 github.com/breml/errchkjson v0.4.1/go.mod h1:a23OvR6Qvcl7DG/Z4o0el6BRAjKnaReoPQFciAl9U3s=
-github.com/butuzov/ireturn v0.4.0 h1:+s76bF/PfeKEdbG8b54aCocxXmi0wvYdOVsWxVO7n8E=
-github.com/butuzov/ireturn v0.4.0/go.mod h1:ghI0FrCmap8pDWZwfPisFD1vEc56VKH4NpQUxDHta70=
-github.com/butuzov/mirror v1.3.0 h1:HdWCXzmwlQHdVhwvsfBb2Au0r3HyINry3bDWLYXiKoc=
-github.com/butuzov/mirror v1.3.0/go.mod h1:AEij0Z8YMALaq4yQj9CPPVYOyJQyiexpQEQgihajRfI=
+github.com/butuzov/ireturn v0.4.1 h1:vWb3NO4t77iku/sjCQ/2pHTQeOmxEhjIriJqRLg1Y+I=
+github.com/butuzov/ireturn v0.4.1/go.mod h1:q+DXKzTDV5guNuXLnIab9fKXizTn2miZHLhxH7V/GB4=
+github.com/butuzov/mirror v1.3.3 h1:v0RsWBhfFc1RQqE/f3sHpSttKDtodFn0gFmtYyD4/hA=
+github.com/butuzov/mirror v1.3.3/go.mod h1:h9BzzwYnTiHO0GzgvaTqIg7VSsOUhdIv51cHFFBmX1w=
 github.com/catenacyber/perfsprint v0.10.1 h1:u7Riei30bk46XsG8nknMhKLXG9BcXz3+3tl/WpKm0PQ=
 github.com/catenacyber/perfsprint v0.10.1/go.mod h1:DJTGsi/Zufpuus6XPGJyKOTMELe347o6akPvWG9Zcsc=
 github.com/ccojocar/zxcvbn-go v1.0.4 h1:FWnCIRMXPj43ukfX000kvBZvV6raSxakYr1nzyNrUcc=
@@ -182,18 +188,24 @@ github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UF
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/charithe/durationcheck v0.0.11 h1:g1/EX1eIiKS57NTWsYtHDZ/APfeXKhye1DidBcABctk=
 github.com/charithe/durationcheck v0.0.11/go.mod h1:x5iZaixRNl8ctbM+3B2RrPG5t856TxRyVQEnbIEM2X4=
-github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4pZI35227imm7yK2bGPcfpFEmuY1gc2YSTShr4iJBfs=
-github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc/go.mod h1:X4/0JoqgTIPSFcRA/P6INZzIuyqdFY5rm8tb41s9okk=
-github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
-github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
-github.com/charmbracelet/x/ansi v0.10.1 h1:rL3Koar5XvX0pHGfovN03f5cxLbCF2YvLeyz7D2jVDQ=
-github.com/charmbracelet/x/ansi v0.10.1/go.mod h1:3RQDQ6lDnROptfpWuUVIUG64bD2g2BgntdxH0Ya5TeE=
-github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd h1:vy0GVL4jeHEwG5YOXDmi86oYw2yuYUGqz6a8sLwg0X8=
-github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
-github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
-github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
+github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
+github.com/charmbracelet/colorprofile v0.4.3/go.mod h1:/zT4BhpD5aGFpqQQqw7a+VtHCzu+zrQtt1zhMt9mR4Q=
+github.com/charmbracelet/ultraviolet v0.0.0-20260811164956-006e29f97886 h1:rdnVWKgJpTVXKuKuJyxDJ+NFJdUaUqGvyGy61OcvlbA=
+github.com/charmbracelet/ultraviolet v0.0.0-20260811164956-006e29f97886/go.mod h1:nAw0d9PhFp1qdzi2xhQU5YOu5sVpDIHWlaW2Uz/bCro=
+github.com/charmbracelet/x/ansi v0.11.8 h1:JMFwp0CgDC2+jcOB162HH5k7I3FVbgFSMMYg7dSPBQQ=
+github.com/charmbracelet/x/ansi v0.11.8/go.mod h1:ZNN+3mXny/516oTQPLMPIBeSINvNJJQ8uQXDgbeJxY0=
+github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
+github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
+github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8JawjaNZY=
+github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5WHJ2ivHeut/Pcwo=
+github.com/charmbracelet/x/windows v0.2.2 h1:IofanmuvaxnKHuV04sC0eBy/smG6kIKrWG2/jYn2GuM=
+github.com/charmbracelet/x/windows v0.2.2/go.mod h1:/8XtdKZzedat74NQFn0NGlGL4soHB0YQZrETF96h75k=
 github.com/ckaznocha/intrange v0.3.1 h1:j1onQyXvHUsPWujDH6WIjhyH26gkRt/txNlV7LspvJs=
 github.com/ckaznocha/intrange v0.3.1/go.mod h1:QVepyz1AkUoFQkpEqksSYpNpUo3c5W7nWh/s6SHIJJk=
+github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSEFgwIwO+UVM8=
+github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
+github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
+github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os8IaYg++6uMOdKK83QtkkvJik=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
@@ -209,12 +221,15 @@ github.com/dave/dst v0.27.3/go.mod h1:jHh6EOibnHgcUW3WjKHisiooEkYwqpHLBSX1iOBhEy
 github.com/dave/jennifer v1.7.1 h1:B4jJJDHelWcDhlRQxWeo0Npa/pYKBLrirAQoTN45txo=
 github.com/dave/jennifer v1.7.1/go.mod h1:nXbxhEmQfOZhWml3D1cDK5M1FLnMSozpbFN/m3RmGZc=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/denis-tingaikin/go-header v0.5.0 h1:SRdnP5ZKvcO9KKRP1KJrhFR3RrlGuD+42t4429eC9k8=
 github.com/denis-tingaikin/go-header v0.5.0/go.mod h1:mMenU5bWrok6Wl2UsZjy+1okegmwQ3UgWl4V1D8gjlY=
-github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ=
-github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dlclark/regexp2 v1.12.0 h1:0j4c5qQmnC6XOWNjP3PIXURXN2gWx76rd3KvgdPkCz8=
+github.com/dlclark/regexp2 v1.12.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dlclark/regexp2/v2 v2.2.1 h1:mf4KkFUj0gJuarK8P+LgiS+Lit7m9N1yAwEfPbee7R0=
+github.com/dlclark/regexp2/v2 v2.2.1/go.mod h1:avUrQvPaLz2DrFNHJF0taWAFFX2C1GMSSoeiqFjcBmU=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/ecosyste-ms/ecosystems-go v0.4.0 h1:5A+zF+XWT8sYYYjlc2/tI1SmiDGzbHLyT9CapVc5dGA=
@@ -228,50 +243,56 @@ github.com/ettle/strcase v0.2.0 h1:fGNiVF21fHXpX1niBgk0aROov1LagYsOwV/xqKDKR/Q=
 github.com/ettle/strcase v0.2.0/go.mod h1:DajmHElDSaX76ITe3/VHVyMin4LWSJN5Z909Wp+ED1A=
 github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a h1:yDWHCSQ40h88yih2JAcL6Ls/kVkSE8GFACTGVnMPruw=
 github.com/facebookgo/clock v0.0.0-20150410010913-600d898af40a/go.mod h1:7Ga40egUymuWXxAe151lTNnCv97MddSOVsjpPPkityA=
-github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
-github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
+github.com/fatih/color v1.19.0 h1:Zp3PiM21/9Ld6FzSKyL5c/BULoe/ONr9KlbYVOfG8+w=
+github.com/fatih/color v1.19.0/go.mod h1:zNk67I0ZUT1bEGsSGyCZYZNrHuTkJJB+r6Q9VuMi0LE=
 github.com/fatih/structtag v1.2.0 h1:/OdNE99OxoI/PqaW/SuSK9uxxT3f/tcSZgon/ssNSx4=
 github.com/fatih/structtag v1.2.0/go.mod h1:mBJUNpUnHmRKrKlQQlmCrh5PuhftFbNv8Ys4/aAZl94=
-github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
-github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
-github.com/firefart/nonamedreturns v1.0.6 h1:vmiBcKV/3EqKY3ZiPxCINmpS431OcE1S47AQUwhrg8E=
-github.com/firefart/nonamedreturns v1.0.6/go.mod h1:R8NisJnSIpvPWheCq0mNRXJok6D8h7fagJTF8EMEwCo=
+github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc=
+github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE=
+github.com/firefart/nonamedreturns v1.0.8 h1:iB32Dl17zJl1zlVEj/WlUWgx0HiRyQ85OUw1WHa4/II=
+github.com/firefart/nonamedreturns v1.0.8/go.mod h1:vxFNvm5AfP/8rgAKFzYmnqx0yp1HjrYsErZ9pHPTznA=
 github.com/frankban/quicktest v1.14.3 h1:FJKSZTDHjyhriyC81FLQ0LY93eSai0ZyR/ZIkd3ZUKE=
 github.com/frankban/quicktest v1.14.3/go.mod h1:mgiwOwqx65TmIk1wJ6Q7wvnVMocbUorkibMOrVTHZps=
 github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/fzipp/gocyclo v0.6.0 h1:lsblElZG7d3ALtGMx9fmxeTKZaLLpU8mET09yN4BBLo=
 github.com/fzipp/gocyclo v0.6.0/go.mod h1:rXPyn8fnlpa0R2csP/31uerbiVBugk5whMdlyaLkLoA=
-github.com/ghostiam/protogetter v0.3.20 h1:oW7OPFit2FxZOpmMRPP9FffU4uUpfeE/rEdE1f+MzD0=
-github.com/ghostiam/protogetter v0.3.20/go.mod h1:FjIu5Yfs6FT391m+Fjp3fbAYJ6rkL/J6ySpZBfnODuI=
-github.com/git-pkgs/archives v0.5.0 h1:QdowC1jTOSbEOKTYGqVt8ZjIr+yJzy7cmLNWcLPj9Y8=
-github.com/git-pkgs/archives v0.5.0/go.mod h1:tfio0OIuPKEBKHs/UCL5XBUvYmKpnvtnba2iDlfSd6g=
-github.com/git-pkgs/cooldown v0.1.1 h1:9OqqzCB8gANz/y44SmqGD0Jp8Qtu81D1sCbKl6Ehg7w=
-github.com/git-pkgs/cooldown v0.1.1/go.mod h1:v7APuK/UouTiu8mWQZbdDmj7DfxxkGUeuhjaRB5gv9E=
-github.com/git-pkgs/enrichment v0.6.4 h1:mGrfenttwmcUfPXRkWpB0wBJiiGj55ltniUh66Pq4bU=
-github.com/git-pkgs/enrichment v0.6.4/go.mod h1:zz1vPUak/w8Jhajll0KDRN2MjKaEYeCzQTxumWnVhqY=
-github.com/git-pkgs/magic v0.2.0 h1:c7HqVxnP8c88EaVMH0/KraDFVTcmiXckRiSvNZEnvMQ=
-github.com/git-pkgs/magic v0.2.0/go.mod h1:3ndidt+yvFaI1M0aEkkzkOlFnLPkeVQASIUojazcxCI=
+github.com/ghostiam/protogetter v0.3.21 h1:EeWTGvL/Eyosp653hiWb6Byx4b69iJC4/E+za7vQHoI=
+github.com/ghostiam/protogetter v0.3.21/go.mod h1:iAKSpyoHwYzay+OpjoWgwzRtPFthEfuUvmlomTThck0=
+github.com/git-pkgs/archives v0.7.0 h1:cRQEKK1N7LMabzXxExwmoAtRvxjuIAkzBxEZmYfH040=
+github.com/git-pkgs/archives v0.7.0/go.mod h1:LH7LSbREEaRlxtLwG2PC7evfhlWNgUB/DMBFr6+KsAA=
+github.com/git-pkgs/artifacts v0.2.1 h1:VwdxR4yTDaqBZ34h0slxQBVyr2Xfa+QGOKCKviMx2xk=
+github.com/git-pkgs/artifacts v0.2.1/go.mod h1:Otosgq52pXT5UNN7lh6s/lszpWKVDO8XrOjN1M70/IA=
+github.com/git-pkgs/cooldown v0.2.0 h1:0MWPHtkzZgvCR0wdiQeyvMea/dxgw9tParH1zzaFopc=
+github.com/git-pkgs/cooldown v0.2.0/go.mod h1:v7APuK/UouTiu8mWQZbdDmj7DfxxkGUeuhjaRB5gv9E=
+github.com/git-pkgs/enrichment v0.7.1 h1:8PRYE7gaB8y4M5wnRw/ymNDk0uOHtbQ8CEE7hF09Bv0=
+github.com/git-pkgs/enrichment v0.7.1/go.mod h1:QYLG8MtVWPqZojnq7KBKK/lllBWSjLnqvJCWvzGuNwU=
+github.com/git-pkgs/gcs v0.1.0 h1:E3awGtsO0xZyHT9FUfEwMHjMkRxw41Bh+c7lgTmPvBo=
+github.com/git-pkgs/gcs v0.1.0/go.mod h1:bdkCFD66ryaWnU8MBhokVA3WkJfyAEchm9qec5woBpE=
+github.com/git-pkgs/integrity v0.1.1 h1:nHQ7SktOiGM1dOb5BFnkdtttG/6FCgE6r5ru6QnsGts=
+github.com/git-pkgs/integrity v0.1.1/go.mod h1:hxu24lcd230377hCF28JQW7sGcCbuNLqo/0ULeb+F1Q=
+github.com/git-pkgs/magic v0.3.1 h1:UzjFRyEwJITA/JgznjmIM4VwuBszD2K4Q8XHgkgL+DM=
+github.com/git-pkgs/magic v0.3.1/go.mod h1:SXOqcsNmbmpZjJZHEEWnwxprbsFvpwWgTAZrgXp4Jm4=
 github.com/git-pkgs/packageurl-go v0.3.1 h1:WM3RBABQZLaRBxgKyYughc3cVBE8KyQxbSC6Jt5ak7M=
 github.com/git-pkgs/packageurl-go v0.3.1/go.mod h1:rcIxiG37BlQLB6FZfgdj9Fm7yjhRQd3l+5o7J0QPAk4=
-github.com/git-pkgs/pom v0.1.5 h1:TGT8Az2OMxGWsXnSagtUMGzZm7Oax8HrSCteA+mi0qY=
-github.com/git-pkgs/pom v0.1.5/go.mod h1:ufdMBe1lKzqOeP9IUb9NPZ458xKV8E8NvuyBMxOfwIk=
-github.com/git-pkgs/purl v0.1.15 h1:iQ3clh0Cw41rkM0rf24B7ShnN9Z+UtLMAFlNDUs+Qd4=
-github.com/git-pkgs/purl v0.1.15/go.mod h1:PqCLVBDeZrZgHysR803/AntMELgIr2LFZVNCcwLH2m0=
-github.com/git-pkgs/registries v0.6.4 h1:Kq/KlStjaQyE83UXT/tKuzCrIzc4keGeBjtroMqgoHA=
-github.com/git-pkgs/registries v0.6.4/go.mod h1:YkGHbxHIe2Ha/ROH6zNkS5PJUUoa9g0Ti/s2XhZnrak=
-github.com/git-pkgs/spdx v0.3.0 h1:AN0guJE7vN5gbOMi9We4j1ziS4cwgFVhTvjVDGfaC7Q=
-github.com/git-pkgs/spdx v0.3.0/go.mod h1:cqRoZcvl530s/W+oGNvwjt4ODN8T1W6D/20MUZEFdto=
-github.com/git-pkgs/vers v0.3.0 h1:xM4LLUCRmqzdDfe+/pVQUx4SRyFXRVth6tOsJ14wMKU=
-github.com/git-pkgs/vers v0.3.0/go.mod h1:biTbSQK1qdbrsxDEKnqe3Jzclxz8vW6uDcwKjfUGcOo=
-github.com/git-pkgs/vulns v0.2.1 h1:tWGhOfPVDZwkM2Y9vRkMpMR+gjtlu2jhERS5JeNBoKQ=
-github.com/git-pkgs/vulns v0.2.1/go.mod h1:/0gHKHQR5SWttZVEMqgOvCXssKFwAtbac/PfkhBax9o=
+github.com/git-pkgs/pom v0.1.7 h1:4yKdtw6eyShtjul6bcZdyz7yLQ+jdrYeYkKbskDGi4c=
+github.com/git-pkgs/pom v0.1.7/go.mod h1:ufdMBe1lKzqOeP9IUb9NPZ458xKV8E8NvuyBMxOfwIk=
+github.com/git-pkgs/purl v0.1.20 h1:a4qzvUy5mBZ2GGjOQNW2h/ocFqjTjOiTDMv2ONtivmM=
+github.com/git-pkgs/purl v0.1.20/go.mod h1:hthV5mp+Q67HpQ9+LnRLLmsReu5ooyQ5EaJsCGrA8yE=
+github.com/git-pkgs/registries v0.9.1 h1:z5GVFfLHWGoVEawppqXTaE2Y6RADkUbTPYctEs3BZ4M=
+github.com/git-pkgs/registries v0.9.1/go.mod h1:5rmFrC76K3zmOAJTTQPcYy0vV2i7MRByM1OQiQdGzl4=
+github.com/git-pkgs/spdx v0.3.1 h1:58JPY5X9pYpXvnzzZIgehItlBykeOOw52pNc4OBcS+c=
+github.com/git-pkgs/spdx v0.3.1/go.mod h1:cqRoZcvl530s/W+oGNvwjt4ODN8T1W6D/20MUZEFdto=
+github.com/git-pkgs/vers v0.7.0 h1:7PD2DKFB8jTDIfiyWXbqYW54iVuNkFCBgXHgxOTdr8A=
+github.com/git-pkgs/vers v0.7.0/go.mod h1:ofLiBpPNkQmC0LB1k0zmN1gCv7Hi3MiZx8WtmWZ4A9A=
+github.com/git-pkgs/vulns v0.2.3 h1:G8icINpR9WFgtwp+4mSdgO4THStiQvi6QuHl83J7iOs=
+github.com/git-pkgs/vulns v0.2.3/go.mod h1:+z7pZMjctLmUxMsq+tZbciD6xAAoejljDosC6n2YXps=
 github.com/github/go-spdx/v2 v2.7.0 h1:GzfXx4wFdlilARxmFRXW/mgUy3A4vSqZocCMFV6XFdQ=
 github.com/github/go-spdx/v2 v2.7.0/go.mod h1:Ftc45YYG1WzpzwEPKRVm9Jv8vDqOrN4gWoCkK+bHer0=
-github.com/go-chi/chi/v5 v5.3.1 h1:3j4HZLGZQ3JpMCrPJF/Jl3mYJfWLKBfNJ6quurUGCf8=
-github.com/go-chi/chi/v5 v5.3.1/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
-github.com/go-critic/go-critic v0.14.3 h1:5R1qH2iFeo4I/RJU8vTezdqs08Egi4u5p6vOESA0pog=
-github.com/go-critic/go-critic v0.14.3/go.mod h1:xwntfW6SYAd7h1OqDzmN6hBX/JxsEKl5up/Y2bsxgVQ=
+github.com/go-chi/chi/v5 v5.3.2 h1:5YQkICvTCSZ25hoRsyJazN0scjzKGiu4VAUc7H1o1nY=
+github.com/go-chi/chi/v5 v5.3.2/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
+github.com/go-critic/go-critic v0.14.4 h1:dSX4C3pWSeuMVxvQh6yG8U0ReSf3YOmKi4nwX5q7n/8=
+github.com/go-critic/go-critic v0.14.4/go.mod h1:xwntfW6SYAd7h1OqDzmN6hBX/JxsEKl5up/Y2bsxgVQ=
 github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
 github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -289,8 +310,8 @@ github.com/go-openapi/spec v0.20.4/go.mod h1:faYFR1CvsJZ0mNsmsphTMSoRrNV3TEDoAM7
 github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk=
 github.com/go-openapi/swag v0.19.15 h1:D2NRCBzS9/pEY3gP9Nl8aDqGUcPFrwG2p+CNFrLyrCM=
 github.com/go-openapi/swag v0.19.15/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ=
-github.com/go-quicktest/qt v1.101.0 h1:O1K29Txy5P2OK0dGo59b7b0LR6wKfIhttaAhHUyn7eI=
-github.com/go-quicktest/qt v1.101.0/go.mod h1:14Bz/f7NwaXPtdYEgzsx46kqSxVwTbzVZsDC26tQJow=
+github.com/go-quicktest/qt v1.102.0 h1:HSQxCeh5YZH3EL3W39ixjtyaEhcWSXQHtHnMBzSs474=
+github.com/go-quicktest/qt v1.102.0/go.mod h1:p4lGIVX+8Wa6ZPNDvqcxq36XpUDLh42FLetFU7odllI=
 github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
 github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
 github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
@@ -331,14 +352,14 @@ github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/golangci/asciicheck v0.5.0 h1:jczN/BorERZwK8oiFBOGvlGPknhvq0bjnysTj4nUfo0=
 github.com/golangci/asciicheck v0.5.0/go.mod h1:5RMNAInbNFw2krqN6ibBxN/zfRFa9S6tA1nPdM0l8qQ=
-github.com/golangci/dupl v0.0.0-20250308024227-f665c8d69b32 h1:WUvBfQL6EW/40l6OmeSBYQJNSif4O11+bmWEz+C7FYw=
-github.com/golangci/dupl v0.0.0-20250308024227-f665c8d69b32/go.mod h1:NUw9Zr2Sy7+HxzdjIULge71wI6yEg1lWQr7Evcu8K0E=
+github.com/golangci/dupl v0.0.0-20260401084720-c99c5cf5c202 h1:CbTB8KpqnViI6lIXxp03Oclc4VFHi3K4BWC1TacsZ+A=
+github.com/golangci/dupl v0.0.0-20260401084720-c99c5cf5c202/go.mod h1:NUw9Zr2Sy7+HxzdjIULge71wI6yEg1lWQr7Evcu8K0E=
 github.com/golangci/go-printf-func-name v0.1.1 h1:hIYTFJqAGp1iwoIfsNTpoq1xZAarogrvjO9AfiW3B4U=
 github.com/golangci/go-printf-func-name v0.1.1/go.mod h1:Es64MpWEZbh0UBtTAICOZiB+miW53w/K9Or/4QogJss=
-github.com/golangci/gofmt v0.0.0-20250106114630-d62b90e6713d h1:viFft9sS/dxoYY0aiOTsLKO2aZQAPT4nlQCsimGcSGE=
-github.com/golangci/gofmt v0.0.0-20250106114630-d62b90e6713d/go.mod h1:ivJ9QDg0XucIkmwhzCDsqcnxxlDStoTl89jDMIoNxKY=
-github.com/golangci/golangci-lint/v2 v2.10.1 h1:flhw5Px6ojbLyEFzXvJn5B2HEdkkRlkhE1SnmCbQBiE=
-github.com/golangci/golangci-lint/v2 v2.10.1/go.mod h1:dBsrOk6zj0vDhlTv+IiJGqkDokR24IVTS7W3EVfPTQY=
+github.com/golangci/gofmt v0.0.0-20260820135601-e84e05053792 h1:WL8YKrt3UbOBqSRU7GpP5BTtQTMWtVtj+mfPijgZeIg=
+github.com/golangci/gofmt v0.0.0-20260820135601-e84e05053792/go.mod h1:te5hX0dW4C5r6YbXs+6ysNr8Q5UTmdIqGbb+mlFiYmA=
+github.com/golangci/golangci-lint/v2 v2.13.1 h1:RuM4OcluM4xFQcGuRE6R7jA33pqxK/W1EsBxpugdZjg=
+github.com/golangci/golangci-lint/v2 v2.13.1/go.mod h1:HwX7mDzqHbcSxlhrTygjX1GJbAfQ3sJAqOx41qQlhDE=
 github.com/golangci/golines v0.15.0 h1:Qnph25g8Y1c5fdo1X7GaRDGgnMHgnxh4Gk4VfPTtRx0=
 github.com/golangci/golines v0.15.0/go.mod h1:AZjXd23tbHMpowhtnGlj9KCNsysj72aeZVVHnVcZx10=
 github.com/golangci/misspell v0.8.0 h1:qvxQhiE2/5z+BVRo1kwYA8yGz+lOlu5Jfvtx2b04Jbg=
@@ -347,6 +368,8 @@ github.com/golangci/plugin-module-register v0.1.2 h1:e5WM6PO6NIAEcij3B053CohVp3H
 github.com/golangci/plugin-module-register v0.1.2/go.mod h1:1+QGTsKBvAIvPvoY/os+G5eoqxWn70HYDm2uvUyGuVw=
 github.com/golangci/revgrep v0.8.0 h1:EZBctwbVd0aMeRnNUsFogoyayvKHyxlV3CdUA46FX2s=
 github.com/golangci/revgrep v0.8.0/go.mod h1:U4R/s9dlXZsg8uJmaR1GrloUr14D7qDl8gi2iPXJH8k=
+github.com/golangci/rowserrcheck v0.0.0-20260419091836-c5f79b8a11ba h1:lqtcnSMDuuJdu/LrKWi5RJzpSNLOJXYe/nzQutTI5kg=
+github.com/golangci/rowserrcheck v0.0.0-20260419091836-c5f79b8a11ba/go.mod h1:sCBNcpRmhJCtbFGz49+IM3ETTFf7QdJ30AeYCd43NKk=
 github.com/golangci/swaggoswag v0.0.0-20250504205917-77f2aca3143e h1:ai0EfmVYE2bRA5htgAG9r7s3tHsfjIhN98WshBTJ9jM=
 github.com/golangci/swaggoswag v0.0.0-20250504205917-77f2aca3143e/go.mod h1:Vrn4B5oR9qRwM+f54koyeH3yzphlecwERs0el27Fr/s=
 github.com/golangci/unconvert v0.0.0-20250410112200-a129a6e6413e h1:gD6P7NEo7Eqtt0ssnqSJNNndxe69DOQ24A5h7+i3KpM=
@@ -370,10 +393,10 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/wire v0.7.0 h1:JxUKI6+CVBgCO2WToKy/nQk0sS+amI9z9EjVmdaocj4=
 github.com/google/wire v0.7.0/go.mod h1:n6YbUQD9cPKTnHXEBN2DXlOp/mVADhVErcMFb0v3J18=
-github.com/googleapis/enterprise-certificate-proxy v0.3.14 h1:yh8ncqsbUY4shRD5dA6RlzjJaT4hi3kII+zYw8wmLb8=
-github.com/googleapis/enterprise-certificate-proxy v0.3.14/go.mod h1:vqVt9yG9480NtzREnTlmGSBmFrA+bzb0yl0TxoBQXOg=
-github.com/googleapis/gax-go/v2 v2.19.0 h1:fYQaUOiGwll0cGj7jmHT/0nPlcrZDFPrZRhTsoCr8hE=
-github.com/googleapis/gax-go/v2 v2.19.0/go.mod h1:w2ROXVdfGEVFXzmlciUU4EdjHgWvB5h2n6x/8XSTTJA=
+github.com/googleapis/enterprise-certificate-proxy v0.3.18 h1:hvVi34VucdrV1IIsiWuqYM8kutw/92MxNEFxCJZEh0k=
+github.com/googleapis/enterprise-certificate-proxy v0.3.18/go.mod h1:rSEsBUemEBZEexP2y6jPp16LUmUbjmSbcPMQizR0o4k=
+github.com/googleapis/gax-go/v2 v2.23.0 h1:Tchl7qkvE7Ip3y+ztvNufYFvkfqTe7NfLTYGIdJRLuE=
+github.com/googleapis/gax-go/v2 v2.23.0/go.mod h1:rBQKOVJCdb8IFEzg+FCwlt1LP/xMDGuqUXhUG+XMXEg=
 github.com/gordonklaus/ineffassign v0.2.0 h1:Uths4KnmwxNJNzq87fwQQDDnbNb7De00VOk9Nu0TySs=
 github.com/gordonklaus/ineffassign v0.2.0/go.mod h1:TIpymnagPSexySzs7F9FnO1XFTy8IT3a59vmZp5Y9Lw=
 github.com/gostaticanalysis/analysisutil v0.7.1 h1:ZMCjoue3DtDWQ5WyU16YbjbQEQ3VuzwxALrpYd+HeKk=
@@ -393,8 +416,8 @@ github.com/hashicorp/go-immutable-radix/v2 v2.1.0/go.mod h1:hgdqLXA4f6NIjRVisM1T
 github.com/hashicorp/go-uuid v1.0.3 h1:2gKiV6YVmrJ1i2CKKa9obLvRieoRGviZFL26PcT/Co8=
 github.com/hashicorp/go-uuid v1.0.3/go.mod h1:6SBZvOh/SIDV7/2o3Jml5SYk/TvGqwFJ/bN7x4byOro=
 github.com/hashicorp/go-version v1.2.1/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
-github.com/hashicorp/go-version v1.8.0 h1:KAkNb1HAiZd1ukkxDFGmokVZe1Xy9HG6NUp+bPle2i4=
-github.com/hashicorp/go-version v1.8.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
+github.com/hashicorp/go-version v1.9.0 h1:CeOIz6k+LoN3qX9Z0tyQrPtiB1DFYRPfCIBtaXPSCnA=
+github.com/hashicorp/go-version v1.9.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/hashicorp/hcl v1.0.0 h1:0Anlzjpi4vEasTeNFn2mLJgTSwt0+6sfsiTG8qcWGx4=
@@ -403,10 +426,8 @@ github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUq
 github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/jgautheron/goconst v1.8.2 h1:y0XF7X8CikZ93fSNT6WBTb/NElBu9IjaY7CCYQrCMX4=
-github.com/jgautheron/goconst v1.8.2/go.mod h1:A0oxgBCHy55NQn6sYpO7UdnA9p+h7cPtoOZUmvNIako=
-github.com/jingyugao/rowserrcheck v1.1.1 h1:zibz55j/MJtLsjP1OF4bSdgXxwL1b+Vn7Tjzq7gFzUs=
-github.com/jingyugao/rowserrcheck v1.1.1/go.mod h1:4yvlZSDb3IyDTUZJUmpZfm2Hwok+Dtp+nu2qOq+er9c=
+github.com/jgautheron/goconst v1.11.0 h1:KgN90z5qXt5f0Uzf3cWXev3hfMMFUyNeKdpkSBRvLDk=
+github.com/jgautheron/goconst v1.11.0/go.mod h1:0p+wv1lFOiUr0IlNNT1nrm6+8DB8u2sU6KHGzFRXHDc=
 github.com/jjti/go-spancheck v0.6.5 h1:lmi7pKxa37oKYIMScialXUK6hP3iY5F1gu+mLBPgYB8=
 github.com/jjti/go-spancheck v0.6.5/go.mod h1:aEogkeatBrbYsyW6y5TgDfihCulDYciL1B7rG2vSsrU=
 github.com/jmoiron/sqlx v1.4.0 h1:1PLqN7S1UYp5t4SrVVnt4nUVNemrDAtxlulVe+Qgm3o=
@@ -420,12 +441,12 @@ github.com/karamaru-alpha/copyloopvar v1.2.2 h1:yfNQvP9YaGQR7VaWLYcfZUlRP2eo2vhE
 github.com/karamaru-alpha/copyloopvar v1.2.2/go.mod h1:oY4rGZqZ879JkJMtX3RRkcXRkmUvH0x35ykgaKgsgJY=
 github.com/keybase/go-keychain v0.0.1 h1:way+bWYa6lDppZoZcgMbYsvC7GxljxrskdNInRtuthU=
 github.com/keybase/go-keychain v0.0.1/go.mod h1:PdEILRW3i9D8JcdM+FmY6RwkHGnhHxXwkPPMeUgOK1k=
-github.com/kisielk/errcheck v1.9.0 h1:9xt1zI9EBfcYBvdU1nVrzMzzUPUtPKs9bVSIM3TAb3M=
-github.com/kisielk/errcheck v1.9.0/go.mod h1:kQxWMMVZgIkDq7U8xtG/n2juOjbLgZtedi0D+/VL/i8=
+github.com/kisielk/errcheck v1.20.0 h1:9rwHBNKzd4wkDWcROy3DvFGNqEPlkxBg305rvk7HabI=
+github.com/kisielk/errcheck v1.20.0/go.mod h1:O+f80MKNwX8Oor2jwgpeQ9An7uJm+hRSgT+h22knRJU=
 github.com/kkHAIKE/contextcheck v1.1.6 h1:7HIyRcnyzxL9Lz06NGhiKvenXq7Zw6Q0UQu/ttjfJCE=
 github.com/kkHAIKE/contextcheck v1.1.6/go.mod h1:3dDbMRNBFaq8HFXWC1JyvDSPm43CmE6IuHam8Wr0rkg=
-github.com/klauspost/compress v1.19.1 h1:VsB4HPswih7mmZ8WleSFQ75c/Ui1M4trX5oAsJnhSlk=
-github.com/klauspost/compress v1.19.1/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/compress v1.19.2 h1:hMRETovs/pu/dVWN7zIT1PGG8t509MwT6bO7XSi26R8=
+github.com/klauspost/compress v1.19.2/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
@@ -443,8 +464,8 @@ github.com/lasiar/canonicalheader v1.1.2 h1:vZ5uqwvDbyJCnMhmFYimgMZnJMjwljN5VGY0
 github.com/lasiar/canonicalheader v1.1.2/go.mod h1:qJCeLFS0G/QlLQ506T+Fk/fWMa2VmBUiEI2cuMK4djI=
 github.com/ldez/exptostd v0.4.5 h1:kv2ZGUVI6VwRfp/+bcQ6Nbx0ghFWcGIKInkG/oFn1aQ=
 github.com/ldez/exptostd v0.4.5/go.mod h1:QRjHRMXJrCTIm9WxVNH6VW7oN7KrGSht69bIRwvdFsM=
-github.com/ldez/gomoddirectives v0.8.0 h1:JqIuTtgvFC2RdH1s357vrE23WJF2cpDCPFgA/TWDGpk=
-github.com/ldez/gomoddirectives v0.8.0/go.mod h1:jutzamvZR4XYJLr0d5Honycp4Gy6GEg2mS9+2YX3F1Q=
+github.com/ldez/gomoddirectives v0.9.0 h1:2YV/EX7nVlWL4jySusYTzBKHuE3D2fgcRsQuMa3yIoo=
+github.com/ldez/gomoddirectives v0.9.0/go.mod h1:DdZzfm9MdXCjn2/UGYXCFfo+tzrp2Ib4iD2Q0kIJkwE=
 github.com/ldez/grignotin v0.10.1 h1:keYi9rYsgbvqAZGI1liek5c+jv9UUjbvdj3Tbn5fn4o=
 github.com/ldez/grignotin v0.10.1/go.mod h1:UlDbXFCARrXbWGNGP3S5vsysNXAPhnSuBufpTEbwOas=
 github.com/ldez/structtags v0.6.1 h1:bUooFLbXx41tW8SvkfwfFkkjPYvFFs59AAMgVg6DUBk=
@@ -458,8 +479,8 @@ github.com/leonklingele/grouper v1.1.2/go.mod h1:6D0M/HVkhs2yRKRFZUoGjeDy7EZTfFB
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/lib/pq v1.12.3 h1:tTWxr2YLKwIvK90ZXEw8GP7UFHtcbTtty8zsI+YjrfQ=
 github.com/lib/pq v1.12.3/go.mod h1:/p+8NSbOcwzAEI7wiMXFlgydTwcgTr3OSKMsD2BitpA=
-github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
-github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/lucasb-eyer/go-colorful v1.4.1 h1:1EO+WB73+EH8EVbzlrG3KLAfEypQWVHIBqlTf+2hNss=
+github.com/lucasb-eyer/go-colorful v1.4.1/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/macabu/inamedparam v0.2.0 h1:VyPYpOc10nkhI2qeNUdh3Zket4fcZjEWe35poddBCpE=
 github.com/macabu/inamedparam v0.2.0/go.mod h1:+Pee9/YfGe5LJ62pYXqB89lJ+0k5bsR8Wgz/C0Zlq3U=
 github.com/magiconair/properties v1.8.6 h1:5ibWZ6iY0NctNGWo87LalDlEZ6R41TqbbDamhfG/Qzo=
@@ -471,8 +492,8 @@ github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
 github.com/manuelarte/embeddedstructfieldcheck v0.4.0 h1:3mAIyaGRtjK6EO9E73JlXLtiy7ha80b2ZVGyacxgfww=
 github.com/manuelarte/embeddedstructfieldcheck v0.4.0/go.mod h1:z8dFSyXqp+fC6NLDSljRJeNQJJDWnY7RoWFzV3PC6UM=
-github.com/manuelarte/funcorder v0.5.0 h1:llMuHXXbg7tD0i/LNw8vGnkDTHFpTnWqKPI85Rknc+8=
-github.com/manuelarte/funcorder v0.5.0/go.mod h1:Yt3CiUQthSBMBxjShjdXMexmzpP8YGvGLjrxJNkO2hA=
+github.com/manuelarte/funcorder v0.6.0 h1:0hBngc4fa1IgNiI65A7sFGkMvoMCc878RjqB5V7rWP0=
+github.com/manuelarte/funcorder v0.6.0/go.mod h1:id3NDhXdQBmeqXH7eVC6Z89xS6JxvZ8kF9xUxpArU/g=
 github.com/maratori/testableexamples v1.0.1 h1:HfOQXs+XgfeRBJ+Wz0XfH+FHnoY9TVqL6Fcevpzy4q8=
 github.com/maratori/testableexamples v1.0.1/go.mod h1:XE2F/nQs7B9N08JgyRmdGjYVGqxWwClLPCGSQhXQSrQ=
 github.com/maratori/testpackage v1.1.2 h1:ffDSh+AgqluCLMXhM19f/cpvQAKygKAJXFl9aUjmbqs=
@@ -481,24 +502,24 @@ github.com/matoous/godox v1.1.0 h1:W5mqwbyWrwZv6OQ5Z1a/DHGMOvXYCBP3+Ht7KMoJhq4=
 github.com/matoous/godox v1.1.0/go.mod h1:jgE/3fUXiTurkdHOLT5WEkThTSuE7yxHv5iWPa80afs=
 github.com/matryer/is v1.4.0 h1:sosSmIWwkYITGrxZ25ULNDeKiMNzFSr4V/eqBQP0PeE=
 github.com/matryer/is v1.4.0/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
-github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
-github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy0/jY=
+github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
 github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
-github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc=
-github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/mattn/go-runewidth v0.0.24 h1:cpokDiIn0MGnhdHwuWnJBITySJ20QyNGnY2kR/ay2DU=
+github.com/mattn/go-runewidth v0.0.24/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
 github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
-github.com/mgechev/revive v1.14.0 h1:CC2Ulb3kV7JFYt+izwORoS3VT/+Plb8BvslI/l1yZsc=
-github.com/mgechev/revive v1.14.0/go.mod h1:MvnujelCZBZCaoDv5B3foPo6WWgULSSFxvfxp7GsPfo=
+github.com/mgechev/revive v1.15.0 h1:vJ0HzSBzfNyPbHKolgiFjHxLek9KUijhqh42yGoqZ8Q=
+github.com/mgechev/revive v1.15.0/go.mod h1:LlAKO3QQe9OJ0pVZzI2GPa8CbXGZ/9lNpCGvK4T/a8A=
 github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
 github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/moricho/tparallel v0.3.2 h1:odr8aZVFA3NZrNybggMkYO3rgPRcqjeQUlBBFVxKHTI=
 github.com/moricho/tparallel v0.3.2/go.mod h1:OQ+K3b4Ln3l2TZveGCywybl68glfLEwFGqvnjok8b+U=
-github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
-github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/nakabonne/nestif v0.3.1 h1:wm28nZjhQY5HyYPx+weN3Q65k6ilSBxDb8v5S81B81U=
@@ -510,16 +531,18 @@ github.com/nishanths/exhaustive v0.12.0 h1:vIY9sALmw6T/yxiASewa4TQcFsVYZQQRUQJhK
 github.com/nishanths/exhaustive v0.12.0/go.mod h1:mEZ95wPIZW+x8kC4TgC+9YCUgiST7ecevsVDTgc2obs=
 github.com/nishanths/predeclared v0.2.2 h1:V2EPdZPliZymNAn79T8RkNApBjMmVKh5XRpLm/w98Vk=
 github.com/nishanths/predeclared v0.2.2/go.mod h1:RROzoN6TnGQupbC+lqggsOlcgysk3LMK/HI84Mp280c=
-github.com/nunnatsa/ginkgolinter v0.23.0 h1:x3o4DGYOWbBMP/VdNQKgSj+25aJKx2Pe6lHr8gBcgf8=
-github.com/nunnatsa/ginkgolinter v0.23.0/go.mod h1:9qN1+0akwXEccwV1CAcCDfcoBlWXHB+ML9884pL4SZ4=
-github.com/oapi-codegen/nullable v1.1.0 h1:eAh8JVc5430VtYVnq00Hrbpag9PFRGWLjxR1/3KntMs=
-github.com/oapi-codegen/nullable v1.1.0/go.mod h1:KUZ3vUzkmEKY90ksAmit2+5juDIhIZhfDl+0PwOQlFY=
+github.com/nunnatsa/ginkgolinter v0.24.0 h1:Mp0EagluLFP98JatP6nqp/gGEoljNG97uf9AcxcBVy8=
+github.com/nunnatsa/ginkgolinter v0.24.0/go.mod h1:2ZMRuzX6+3XXyY6UZOwb6n+MCocVGbkIsDBC4vuWz5c=
+github.com/oapi-codegen/nullable v1.2.0 h1:VflFkDW980KhBPiFF7nWSyjg+r4Obqj8lXipV0UkP5w=
+github.com/oapi-codegen/nullable v1.2.0/go.mod h1:KUZ3vUzkmEKY90ksAmit2+5juDIhIZhfDl+0PwOQlFY=
 github.com/oapi-codegen/runtime v1.6.0 h1:7Xx+GlueD6nRuyKoCPzL434Jfi3BetbiJOrzCHp/VPU=
 github.com/oapi-codegen/runtime v1.6.0/go.mod h1:GwV7hC2hviaMzj+ITfHVRESK5J2W/GefVwIND/bMGvU=
-github.com/onsi/ginkgo/v2 v2.28.1 h1:S4hj+HbZp40fNKuLUQOYLDgZLwNUVn19N3Atb98NCyI=
-github.com/onsi/ginkgo/v2 v2.28.1/go.mod h1:CLtbVInNckU3/+gC8LzkGUb9oF+e8W8TdUsxPwvdOgE=
-github.com/onsi/gomega v1.39.1 h1:1IJLAad4zjPn2PsnhH70V4DKRFlrCzGBNrNaru+Vf28=
-github.com/onsi/gomega v1.39.1/go.mod h1:hL6yVALoTOxeWudERyfppUcZXjMwIMLnuSfruD2lcfg=
+github.com/onsi/ginkgo/v2 v2.32.0 h1:Hw7s2pVrQo/8Yz5N77qdnpHaoc+c6cC9WIV1Jce+J6E=
+github.com/onsi/ginkgo/v2 v2.32.0/go.mod h1:+aXOY+vzZ5mu2iI2HpTZUPmM//oQfsNFX6gU9kNcA44=
+github.com/onsi/gomega v1.42.1 h1:iN1rCUX+44NZ1Dc97MPoeFYbFR0vh8zxoxMFwKdyZ6I=
+github.com/onsi/gomega v1.42.1/go.mod h1:REff/hsDsodHoKlWsP2mAPhu1+5/6hVYNf9rIEBpeSg=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
 github.com/otiai10/copy v1.2.0/go.mod h1:rrF5dJ5F0t/EWSYODDu4j9/vEeYHMkc8jt0zJChqQWw=
 github.com/otiai10/copy v1.14.0 h1:dCI/t1iTdYGtkvCuBG2BgR6KZa83PTclw4U5n2wAllU=
 github.com/otiai10/copy v1.14.0/go.mod h1:ECfuL02W+/FkTWZWgQqXPWZgW9oeKCSQ5qVfSc4qc4w=
@@ -527,26 +550,27 @@ github.com/otiai10/curr v0.0.0-20150429015615-9b4961190c95/go.mod h1:9qAhocn7zKJ
 github.com/otiai10/curr v1.0.0/go.mod h1:LskTG5wDwr8Rs+nNQ+1LlxRjAtTZZjtJW4rMXl6j4vs=
 github.com/otiai10/mint v1.3.0/go.mod h1:F5AjcsTsWUqX+Na9fpHb52P8pcRX2CI6A3ctIT91xUo=
 github.com/otiai10/mint v1.3.1/go.mod h1:/yxELlJQ0ufhjUwhshSj+wFjZ78CnZ48/1wtmBH1OTc=
-github.com/package-url/packageurl-go v0.1.6 h1:YO3p6u1XmCUliivUg/qWphaY8vI6hxSnnPv7Bfg3m5M=
-github.com/package-url/packageurl-go v0.1.6/go.mod h1:nKAWB8E6uk1MHqiS/lQb9pYBGH2+mdJ2PJc2s50dQY0=
-github.com/pandatix/go-cvss v0.6.2 h1:TFiHlzUkT67s6UkelHmK6s1INKVUG7nlKYiWWDTITGI=
-github.com/pandatix/go-cvss v0.6.2/go.mod h1:jDXYlQBZrc8nvrMUVVvTG8PhmuShOnKrxP53nOFkt8Q=
+github.com/package-url/packageurl-go v0.1.7 h1:iFWg6tzAjLA6F/qX3M5nZaiMHJgc+p2zxVyr/fY+sZY=
+github.com/package-url/packageurl-go v0.1.7/go.mod h1:nKAWB8E6uk1MHqiS/lQb9pYBGH2+mdJ2PJc2s50dQY0=
+github.com/pandatix/go-cvss v0.6.4 h1:9w2RCO/Q4UTiJyEgpCHRiVc6CfrsFEnkoX+OtATqKio=
+github.com/pandatix/go-cvss v0.6.4/go.mod h1:/ukvQnYlrKl3o/DVp7/GO2UZyZheuo/maOK0U1nBEhQ=
 github.com/pelletier/go-toml v1.9.5 h1:4yBQzkHv+7BHq2PQUZF3Mx0IYxG7LsP222s7Agd3ve8=
 github.com/pelletier/go-toml v1.9.5/go.mod h1:u1nR/EPcESfeI/szUZKdtJ0xRNbUoANCkoOuaOx1Y+c=
-github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
-github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
+github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/peterbourgon/g2s v0.0.0-20170223122336-d4e7ad98afea h1:sKwxy1H95npauwu8vtF95vG/syrL0p8fSZo/XlDg5gk=
 github.com/peterbourgon/g2s v0.0.0-20170223122336-d4e7ad98afea/go.mod h1:1VcHEd3ro4QMoHfiNl/j7Jkln9+KQuorp0PItHMJYNg=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo=
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_golang v1.24.1 h1:JnJkREXzWxUdCuPFpIWZiPispT9xVV59uiuyR2bPlnU=
 github.com/prometheus/client_golang v1.24.1/go.mod h1:F+oSRECHg4sse5ucfYpYDeIv/hu68Zo0uoHKetWnzcE=
-github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
-github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/client_model v0.6.3 h1:O0jaTVAYNxTHYInEPFJt5I3+sN8zqBtVMPTB1qyxiEo=
+github.com/prometheus/client_model v0.6.3/go.mod h1:gpN5P9S7Rr6Yr92PiQ+Ixvhf6JZEkF1dnxsYL2aPBEM=
 github.com/prometheus/common v0.70.1 h1:1HvjP4D5oL3t8RsPlwxA9onvvStjtIHYE5XuuwOi/PY=
 github.com/prometheus/common v0.70.1/go.mod h1:VdFUQDMZK3VLkurFUVhia6uys/0suUp86TJz5qbJRhc=
 github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
@@ -561,15 +585,14 @@ github.com/quasilyte/regex/syntax v0.0.0-20210819130434-b3f0c404a727 h1:TCg2WBOl
 github.com/quasilyte/regex/syntax v0.0.0-20210819130434-b3f0c404a727/go.mod h1:rlzQ04UMyJXu/aOvhd8qT+hvDrFpiwqp8MRXDY9szc0=
 github.com/quasilyte/stdinfo v0.0.0-20220114132959-f7386bf02567 h1:M8mH9eK4OUR4lu7Gd+PU1fV2/qnDNfzT635KRSObncs=
 github.com/quasilyte/stdinfo v0.0.0-20220114132959-f7386bf02567/go.mod h1:DWNGW8A4Y+GyBgPuaQJuWiy0XYftx4Xm/y5Jqk9I6VQ=
-github.com/raeperd/recvcheck v0.2.0 h1:GnU+NsbiCqdC2XX5+vMZzP+jAJC5fht7rcVTAhX74UI=
-github.com/raeperd/recvcheck v0.2.0/go.mod h1:n04eYkwIR0JbgD73wT8wL4JjPC3wm0nFtzBnWNocnYU=
+github.com/raeperd/recvcheck v0.3.0 h1:PM+XYvyxIj3bo+kobJfFTdTuU3Lmfu96mKDbyHDbRt8=
+github.com/raeperd/recvcheck v0.3.0/go.mod h1:PZNwG+HztFYMH2ZPq0Hu3QgkV2yiA6VrtNz9c1fXWJo=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
-github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
-github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
-github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/rogpeppe/go-internal v1.16.0 h1:O9DK+vNMDVGLr2BeZqmpLeMjiMNkuXfcqntWbZV6S5g=
+github.com/rogpeppe/go-internal v1.16.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/rs/dnscache v0.0.0-20230804202142-fc85eb664529 h1:18kd+8ZUlt/ARXhljq+14TwAoKa61q6dX8jtwOf6DH8=
 github.com/rs/dnscache v0.0.0-20230804202142-fc85eb664529/go.mod h1:qe5TWALJ8/a1Lqznoc5BDHpYX/8HU60Hm2AwRmqzxqA=
 github.com/rubyist/circuitbreaker v2.2.1+incompatible h1:KUKd/pV8Geg77+8LNDwdow6rVCAYOp8+kHUyFvL6Mhk=
@@ -579,31 +602,31 @@ github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryancurrah/gomodguard v1.4.1 h1:eWC8eUMNZ/wM/PWuZBv7JxxqT5fiIKSIyTvjb7Elr+g=
 github.com/ryancurrah/gomodguard v1.4.1/go.mod h1:qnMJwV1hX9m+YJseXEBhd2s90+1Xn6x9dLz11ualI1I=
-github.com/ryanrolds/sqlclosecheck v0.5.1 h1:dibWW826u0P8jNLsLN+En7+RqWWTYrjCB9fJfSfdyCU=
-github.com/ryanrolds/sqlclosecheck v0.5.1/go.mod h1:2g3dUjoS6AL4huFdv6wn55WpLIDjY7ZgUR4J8HOO/XQ=
+github.com/ryancurrah/gomodguard/v2 v2.1.3 h1:E7sz3PJwE9Ba1reVxSpF6XLCPJZ74Kfw/LabTNM4GIA=
+github.com/ryancurrah/gomodguard/v2 v2.1.3/go.mod h1:CQicdLGatWMxLX53JzoBjYlsNZhHbmLv2AVa0s2aivU=
+github.com/ryanrolds/sqlclosecheck v0.6.0 h1:pEyL9okISdg1F1SEpJNlrEotkTGerv5BMk7U4AG0eVg=
+github.com/ryanrolds/sqlclosecheck v0.6.0/go.mod h1:xyX16hsDaCMXHrMJ3JMzGf5OpDfHTOTTQrT7HOFUmeU=
 github.com/sanposhiho/wastedassign/v2 v2.1.0 h1:crurBF7fJKIORrV85u9UUpePDYGWnwvv3+A96WvwXT0=
 github.com/sanposhiho/wastedassign/v2 v2.1.0/go.mod h1:+oSmSC+9bQ+VUAxA66nBb0Z7N8CK7mscKTDYC6aIek4=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/sashamelentyev/interfacebloat v1.1.0 h1:xdRdJp0irL086OyW1H/RTZTr1h/tMEOsumirXcOJqAw=
 github.com/sashamelentyev/interfacebloat v1.1.0/go.mod h1:+Y9yU5YdTkrNvoX0xHc84dxiN1iBi9+G8zZIhPVoNjQ=
 github.com/sashamelentyev/usestdlibvars v1.29.0 h1:8J0MoRrw4/NAXtjQqTHrbW9NN+3iMf7Knkq057v4XOQ=
 github.com/sashamelentyev/usestdlibvars v1.29.0/go.mod h1:8PpnjHMk5VdeWlVb4wCdrB8PNbLqZ3wBZTZWkrpZZL8=
-github.com/securego/gosec/v2 v2.23.0 h1:h4TtF64qFzvnkqvsHC/knT7YC5fqyOCItlVR8+ptEBo=
-github.com/securego/gosec/v2 v2.23.0/go.mod h1:qRHEgXLFuYUDkI2T7W7NJAmOkxVhkR0x9xyHOIcMNZ0=
+github.com/securego/gosec/v2 v2.28.0 h1:ZsSdiDb0AtTpLFVol5z91gbMei9ZiLEPG/pZjZujp7c=
+github.com/securego/gosec/v2 v2.28.0/go.mod h1:lb4/9AHe+lJy/kjWmWRWWsEipvbwGKuxf+tY1Pmjdnk=
 github.com/sergi/go-diff v1.2.0 h1:XU+rvMAioB0UC3q1MFrIQy4Vo5/4VsRDQQXHsEya6xQ=
 github.com/sergi/go-diff v1.2.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
-github.com/shurcooL/go v0.0.0-20180423040247-9e1955d9fb6e/go.mod h1:TDJrrUr11Vxrven61rcy3hJMUqaf/CLWYhHNPmT14Lk=
-github.com/shurcooL/go-goon v0.0.0-20170922171312-37c2f522c041/go.mod h1:N5mDOmsrJOB+vfqUK+7DmDyjhSLIIBnXo9lvZJj3MWQ=
 github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
-github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
-github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
+github.com/sirupsen/logrus v1.10.1 h1:xi4336Zh11WpU14fXR6I67V3yaTPQYwRx2WEtHbRg4Q=
+github.com/sirupsen/logrus v1.10.1/go.mod h1:vsQHnG7xzNsxk3NrwboUiWPnIC3dmbjcGPykD7+tiHk=
 github.com/sivchari/containedctx v1.0.3 h1:x+etemjbsh2fB5ewm5FeLNi5bUjK0V8n0RB+Wwfd0XE=
 github.com/sivchari/containedctx v1.0.3/go.mod h1:c1RDvCbnJLtH4lLcYD/GqwiBSSf4F5Qk0xld2rBqzJ4=
-github.com/sonatard/noctx v0.4.0 h1:7MC/5Gg4SQ4lhLYR6mvOP6mQVSxCrdyiExo7atBs27o=
-github.com/sonatard/noctx v0.4.0/go.mod h1:64XdbzFb18XL4LporKXp8poqZtPKbCrqQ402CV+kJas=
-github.com/sourcegraph/go-diff v0.7.0 h1:9uLlrd5T46OXs5qpp8L/MTltk0zikUGi0sNNyCpA8G0=
-github.com/sourcegraph/go-diff v0.7.0/go.mod h1:iBszgVvyxdc8SFZ7gm69go2KDdt3ag071iBaWPF6cjs=
+github.com/sonatard/noctx v0.5.1 h1:wklWg9c9ZYugOAk7qG4yP4PBrlQsmSLPTvW1K4PRQMs=
+github.com/sonatard/noctx v0.5.1/go.mod h1:64XdbzFb18XL4LporKXp8poqZtPKbCrqQ402CV+kJas=
+github.com/sourcegraph/go-diff v0.8.0 h1:ipIyu4cTsLbIrln4l0qtHA3r0a7gyK4ntKjtQytHhvY=
+github.com/sourcegraph/go-diff v0.8.0/go.mod h1:hWlcO7Al+UZStZAP8rBumHpCK5ZHQ5BXsMls8p4+F5E=
 github.com/spdx/tools-golang v0.5.7 h1:+sWcKGnhwp3vLdMqPcLdA6QK679vd86cK9hQWH3AwCg=
 github.com/spdx/tools-golang v0.5.7/go.mod h1:jg7w0LOpoNAw6OxKEzCoqPC2GCTj45LyTlVmXubDsYw=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
@@ -620,22 +643,22 @@ github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.12.0 h1:CZ7eSOd3kZoaYDLbXnmzgQI5RlciuXBMA+18HwHRfZQ=
 github.com/spf13/viper v1.12.0/go.mod h1:b6COn30jlNxbm/V2IqWiNWkJ+vZNiMNksliPCiuKtSI=
-github.com/spiffe/go-spiffe/v2 v2.6.0 h1:l+DolpxNWYgruGQVV0xsfeya3CsC7m8iBzDnMpsbLuo=
-github.com/spiffe/go-spiffe/v2 v2.6.0/go.mod h1:gm2SeUoMZEtpnzPNs2Csc0D/gX33k1xIx7lEzqblHEs=
+github.com/spiffe/go-spiffe/v2 v2.7.0 h1:uXe1MflJoHw58wAUvxVlcM7WpKtijWG7I1UidcGh6g4=
+github.com/spiffe/go-spiffe/v2 v2.7.0/go.mod h1:47Q0Q9/AqGha8QLHp+kxpH4Wca7X7EnOtlIJy3mxZ3U=
 github.com/spkg/bom v0.0.0-20160624110644-59b7046e48ad/go.mod h1:qLr4V1qq6nMqFKkMo8ZTx3f+BZEkzsRUY10Xsm2mwU0=
 github.com/ssgreg/nlreturn/v2 v2.2.1 h1:X4XDI7jstt3ySqGU86YGAURbxw3oTDPK9sPEi6YEwQ0=
 github.com/ssgreg/nlreturn/v2 v2.2.1/go.mod h1:E/iiPB78hV7Szg2YfRgyIrk1AD6JVMTRkkxBiELzh2I=
 github.com/stbenjam/no-sprintf-host-port v0.3.1 h1:AyX7+dxI4IdLBPtDbsGAyqiTSLpCP9hWRrXQDU4Cm/g=
 github.com/stbenjam/no-sprintf-host-port v0.3.1/go.mod h1:ODbZesTCHMVKthBHskvUUexdcNHAQRXk9NpSsL8p/HQ=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
-github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
+github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
-github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
 github.com/subosito/gotenv v1.4.1 h1:jyEFiXpy21Wm81FBN71l9VoMMV8H8jG+qIK3GCpY6Qs=
 github.com/subosito/gotenv v1.4.1/go.mod h1:ayKnFf/c6rvx/2iiLrJUk1e6plDbT3edrFNGqEflhK0=
 github.com/swaggo/swag v1.16.6 h1:qBNcx53ZaX+M5dxVyTrgQ0PJ/ACK+NzhwcbieTt+9yI=
@@ -644,12 +667,12 @@ github.com/tenntenn/modver v1.0.1 h1:2klLppGhDgzJrScMpkj9Ujy3rXPUspSjAcev9tSEBgA
 github.com/tenntenn/modver v1.0.1/go.mod h1:bePIyQPb7UeioSRkw3Q0XeMhYZSMx9B8ePqg6SAMGH0=
 github.com/tenntenn/text/transform v0.0.0-20200319021203-7eef512accb3 h1:f+jULpRQGxTSkNYKJ51yaw6ChIqO+Je8UqsTKN/cDag=
 github.com/tenntenn/text/transform v0.0.0-20200319021203-7eef512accb3/go.mod h1:ON8b8w4BN/kE1EOhwT0o+d62W65a6aPw1nouo9LMgyY=
-github.com/terminalstatic/go-xsd-validate v0.1.6 h1:TenYeQ3eY631qNi1/cTmLH/s2slHPRKTTHT+XSHkepo=
-github.com/terminalstatic/go-xsd-validate v0.1.6/go.mod h1:18lsvYFofBflqCrvo1umpABZ99+GneNTw2kEEc8UPJw=
-github.com/tetafro/godot v1.5.4 h1:u1ww+gqpRLiIA16yF2PV1CV1n/X3zhyezbNXC3E14Sg=
-github.com/tetafro/godot v1.5.4/go.mod h1:eOkMrVQurDui411nBY2FA05EYH01r14LuWY/NrVDVcU=
-github.com/timakin/bodyclose v0.0.0-20241222091800-1db5c5ca4d67 h1:9LPGD+jzxMlnk5r6+hJnar67cgpDIz/iyD+rfl5r2Vk=
-github.com/timakin/bodyclose v0.0.0-20241222091800-1db5c5ca4d67/go.mod h1:mkjARE7Yr8qU23YcGMSALbIxTQ9r9QBVahQOBRfU460=
+github.com/terminalstatic/go-xsd-validate v0.1.8 h1:UVrTCy1j3DhwaYTTUF+QYO/Nan13S0tf+Jwi+p45Bf0=
+github.com/terminalstatic/go-xsd-validate v0.1.8/go.mod h1:1kb47fi2c6onlf+B7UrrQ9VYraOhcYwFm3iG+J6F4Zo=
+github.com/tetafro/godot v1.5.6 h1:IEkrFCwXaYHlOn4mGzGS3F3dkP6m9t0jpwqBFPIkKiA=
+github.com/tetafro/godot v1.5.6/go.mod h1:eOkMrVQurDui411nBY2FA05EYH01r14LuWY/NrVDVcU=
+github.com/timakin/bodyclose v0.0.0-20260129054331-73d1f95b84b4 h1:SiHe5XLTn9sFWJ5pBwJ5FN/4j34q9ZlOAD//kMoMYp0=
+github.com/timakin/bodyclose v0.0.0-20260129054331-73d1f95b84b4/go.mod h1:sDHLK7rb/59v/ZxZ7KtymgcoxuUMxjXq8gtu9VMOK8M=
 github.com/timonwong/loggercheck v0.11.0 h1:jdaMpYBl+Uq9mWPXv1r8jc5fC3gyXx4/WGwTnnNKn4M=
 github.com/timonwong/loggercheck v0.11.0/go.mod h1:HEAWU8djynujaAVX7QI65Myb8qgfcZ1uKbdpg3ZzKl8=
 github.com/tomarrell/wrapcheck/v2 v2.12.0 h1:H/qQ1aNWz/eeIhxKAFvkfIA+N7YDvq6TWVFL27Of9is=
@@ -664,10 +687,10 @@ github.com/ultraware/whitespace v0.2.0 h1:TYowo2m9Nfj1baEQBjuHzvMRbp19i+RCcRYrSW
 github.com/ultraware/whitespace v0.2.0/go.mod h1:XcP1RLD81eV4BW8UhQlpaR+SDc2givTvyI8a586WjW8=
 github.com/urfave/cli/v2 v2.3.0 h1:qph92Y649prgesehzOrQjdWyxFOp/QVM+6imKHad91M=
 github.com/urfave/cli/v2 v2.3.0/go.mod h1:LJmUH05zAU44vOAcrfzZQKsZbVcdbOG8rtL3/XcUArI=
-github.com/uudashr/gocognit v1.2.0 h1:3BU9aMr1xbhPlvJLSydKwdLN3tEUUrzPSSM8S4hDYRA=
-github.com/uudashr/gocognit v1.2.0/go.mod h1:k/DdKPI6XBZO1q7HgoV2juESI2/Ofj9AcHPZhBBdrTU=
-github.com/uudashr/iface v1.4.1 h1:J16Xl1wyNX9ofhpHmQ9h9gk5rnv2A6lX/2+APLTo0zU=
-github.com/uudashr/iface v1.4.1/go.mod h1:pbeBPlbuU2qkNDn0mmfrxP2X+wjPMIQAy+r1MBXSXtg=
+github.com/uudashr/gocognit v1.2.1 h1:CSJynt5txTnORn/DkhiB4mZjwPuifyASC8/6Q0I/QS4=
+github.com/uudashr/gocognit v1.2.1/go.mod h1:acaubQc6xYlXFEMb9nWX2dYBzJ/bIjEkc1zzvyIZg5Q=
+github.com/uudashr/iface v1.5.0 h1:PgdMt4uAettGG8K/Kbamc4B9FABgUgnS3TLbl6fnjEk=
+github.com/uudashr/iface v1.5.0/go.mod h1:pbeBPlbuU2qkNDn0mmfrxP2X+wjPMIQAy+r1MBXSXtg=
 github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=
 github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
 github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=
@@ -687,7 +710,6 @@ github.com/ykadowak/zerologlint v0.1.5/go.mod h1:KaUskqF3e/v59oPmdq1U1DnKcuHokl2
 github.com/yuin/goldmark v1.1.25/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.1.32/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
-github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
 github.com/yuin/goldmark v1.4.1/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 gitlab.com/bosi/decorder v0.4.2 h1:qbQaV3zgwnBZ4zPMhGLW4KZe7A7NwxEhJx39R3shffo=
@@ -696,20 +718,20 @@ go-simpler.org/assert v0.9.0 h1:PfpmcSvL7yAnWyChSjOz6Sp6m9j5lyK8Ok9pEL31YkQ=
 go-simpler.org/assert v0.9.0/go.mod h1:74Eqh5eI6vCK6Y5l3PI8ZYFXG4Sa+tkr70OIPJAUr28=
 go-simpler.org/musttag v0.14.0 h1:XGySZATqQYSEV3/YTy+iX+aofbZZllJaqwFWs+RTtSo=
 go-simpler.org/musttag v0.14.0/go.mod h1:uP8EymctQjJ4Z1kUnjX0u2l60WfUdQxCwSNKzE1JEOE=
-go-simpler.org/sloglint v0.11.1 h1:xRbPepLT/MHPTCA6TS/wNfZrDzkGvCCqUv4Bdwc3H7s=
-go-simpler.org/sloglint v0.11.1/go.mod h1:2PowwiCOK8mjiF+0KGifVOT8ZsCNiFzvfyJeJOIt8MQ=
+go-simpler.org/sloglint v0.12.0 h1:UzWDlLWNE5FLqsvyq3tWYHuQMbqrervOhT8qPl4Mmw4=
+go-simpler.org/sloglint v0.12.0/go.mod h1:jBjjC2bm8rYrs88oTRlFX497kWjJsyZWYoNaXkGRI6I=
 go.augendre.info/arangolint v0.4.0 h1:xSCZjRoS93nXazBSg5d0OGCi9APPLNMmmLrC995tR50=
 go.augendre.info/arangolint v0.4.0/go.mod h1:l+f/b4plABuFISuKnTGD4RioXiCCgghv2xqst/xOvAA=
-go.augendre.info/fatcontext v0.9.0 h1:Gt5jGD4Zcj8CDMVzjOJITlSb9cEch54hjRRlN3qDojE=
-go.augendre.info/fatcontext v0.9.0/go.mod h1:L94brOAT1OOUNue6ph/2HnwxoNlds9aXDF2FcUntbNw=
+go.augendre.info/fatcontext v0.10.0 h1:HhFopmivh8U1+AU7f0kuwUeg2eiIns7YsGQOMHwSJ90=
+go.augendre.info/fatcontext v0.10.0/go.mod h1:pqpGvA9GlrXy+aXkp8L2dKz12Zp4g2FhzcAtwToU+2w=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/detectors/gcp v1.43.0 h1:62yY3dT7/ShwOxzA0RsKRgshBmfElKI4d/Myu2OxDFU=
-go.opentelemetry.io/contrib/detectors/gcp v1.43.0/go.mod h1:RyaZMFY7yi1kAs45S6mbFGz8O8rqB0dTY14uzvG4LCs=
+go.opentelemetry.io/contrib/detectors/gcp v1.44.0 h1:NmLfL734pJhM0JKaYd2Y28+nY9dPRWYAAbxhRCrKXPw=
+go.opentelemetry.io/contrib/detectors/gcp v1.44.0/go.mod h1:tNAsgd8avTGke1+MndXlU5Cru4PQ9Ai/cCNWQv/ZJ/s=
 go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0 h1:yI1/OhfEPy7J9eoa6Sj051C7n5dvpj0QX8g4sRchg04=
 go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0/go.mod h1:NoUCKYWK+3ecatC4HjkRktREheMeEtrXoQxrqYFeHSc=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0/go.mod h1:z9+yiacE0IHRqM4qFfkbt/JYlmYXgss8GY/jXoNuPJI=
 go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
 go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
 go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
@@ -730,51 +752,43 @@ go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
 go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
 go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
-go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 gocloud.dev v0.46.0 h1:niIuZwSjMtBx8K+ITB2s5kZullB13PGOS2ZoQPZxQ4Q=
 gocloud.dev v0.46.0/go.mod h1:ACQe+2qO+hEO+pdcvvsM+RB63r8TyGD1W3ESCLFyzvM=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
-golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
-golang.org/x/crypto v0.14.0/go.mod h1:MVFd36DqK4CsrnJYDkBA3VC4m2GkXAM0PvzMCn4JQf4=
-golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
-golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
+golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M=
+golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis=
 golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa h1:Zt3DZoOFFYkKhDT3v7Lm9FDMEV06GpzjG2jrqW+QTE0=
 golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
 golang.org/x/exp/typeparams v0.0.0-20220428152302-39d4317da171/go.mod h1:AbB0pIl9nAr9wVwH+Z2ZpaocVmF5I4GyWCDIsVjR0bk=
 golang.org/x/exp/typeparams v0.0.0-20230203172020-98cc5a0785f9/go.mod h1:AbB0pIl9nAr9wVwH+Z2ZpaocVmF5I4GyWCDIsVjR0bk=
-golang.org/x/exp/typeparams v0.0.0-20260209203927-2842357ff358 h1:qWFG1Dj7TBjOjOvhEOkmyGPVoquqUKnIU0lEVLp8xyk=
-golang.org/x/exp/typeparams v0.0.0-20260209203927-2842357ff358/go.mod h1:4Mzdyp/6jzw9auFDJ3OMF5qksa7UvPnzKqTVGcb04ms=
+golang.org/x/exp/typeparams v0.0.0-20260811152304-ee035b5b010f h1:+lI8cDJ4uceLipg2f1ODay7fEuLkk0BIHXd6PB8icxo=
+golang.org/x/exp/typeparams v0.0.0-20260811152304-ee035b5b010f/go.mod h1:PqrXSW65cXDZH0k4IeUbhmg/bcAZDbzNz3byBpKCsXo=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.4.1/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
-golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.6.0-dev.0.20220106191415-9b9b3d81d5e3/go.mod h1:3p9vT2HGsQu2K1YbXdKPJLVgG5VJdoTa1poYQBtP1AY=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.13.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
-golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
-golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
+golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
+golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20200625001655-4c5254603344/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA=
 golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
-golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4/go.mod h1:p54w0d4576C0XHj96bSt6lcn1PtDYWL6XObtHCRCNQM=
 golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
 golang.org/x/net v0.0.0-20211015210444-4f30a5c0130f/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
-golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
-golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
-golang.org/x/net v0.16.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
-golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE=
-golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU=
+golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
+golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -784,20 +798,16 @@ golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJ
 golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
-golang.org/x/sync v0.4.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
-golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
-golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210420072515-93ed5bcd2bfe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210510120138-977fb7262007/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20211019181941-9d821ace8654/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20211105183446-c75c47738b0c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
@@ -805,27 +815,19 @@ golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
-golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
-golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
-golang.org/x/term v0.13.0/go.mod h1:LTmsnFJwVN6bCy1rVCoS+qHT1HhALEFxKncY3WNNh4U=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
-golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
-golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
-golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
-golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -834,14 +836,11 @@ golang.org/x/tools v0.0.0-20200329025819-fd4102a86c65/go.mod h1:Sl4aGygMT6LrqrWc
 golang.org/x/tools v0.0.0-20200724022722-7017fd6b1305/go.mod h1:njjCfa9FT2d7l9Bc6FUM5FLjQPp3cFF28FI3qnDFljA=
 golang.org/x/tools v0.1.1-0.20210205202024-ef80cdb6ec6d/go.mod h1:9bzcO0MWcOuT0tm1iBGzDVPshzfwoVvREIui8C+MHqU=
 golang.org/x/tools v0.1.1-0.20210302220138-2ac05c832e1a/go.mod h1:9bzcO0MWcOuT0tm1iBGzDVPshzfwoVvREIui8C+MHqU=
-golang.org/x/tools v0.1.1/go.mod h1:o0xws9oXOQQZyjljx8fwUC0k7L1pTE6eaCbjGeHmOkk=
 golang.org/x/tools v0.1.10/go.mod h1:Uh6Zz+xoGYZom868N8YTex3t7RhtHDBrE8Gzo9bV56E=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
-golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
-golang.org/x/tools v0.14.0/go.mod h1:uYBEerGOWcJyEORxN+Ek8+TT266gXkNlHdJBwexUsBg=
-golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
-golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
+golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
+golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
 golang.org/x/tools/go/expect v0.1.1-deprecated h1:jpBZDwmgPhXsKZC6WhL20P4b/wmnpsEAGHaNy0n/rJM=
 golang.org/x/tools/go/expect v0.1.1-deprecated/go.mod h1:eihoPOH+FgIqa3FpoTwguz/bVUSGBlGQU67vpBeOrBY=
 golang.org/x/tools/go/packages/packagestest v0.1.1-deprecated h1:1h2MnaIAIXISqTFKdENegdpAgUXz6NrPEsbIeWaBRvM=
@@ -854,18 +853,18 @@ golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da h1:noIWHXmPHxILtqtCOPIhS
 golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da/go.mod h1:NDW/Ps6MPRej6fsCIbMTohpP40sJ/P/vI1MoTEGwX90=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
-google.golang.org/api v0.272.0 h1:eLUQZGnAS3OHn31URRf9sAmRk3w2JjMx37d2k8AjJmA=
-google.golang.org/api v0.272.0/go.mod h1:wKjowi5LNJc5qarNvDCvNQBn3rVK8nSy6jg2SwRwzIA=
-google.golang.org/genproto v0.0.0-20260316180232-0b37fe3546d5 h1:JNfk58HZ8lfmXbYK2vx/UvsqIL59TzByCxPIX4TDmsE=
-google.golang.org/genproto v0.0.0-20260316180232-0b37fe3546d5/go.mod h1:x5julN69+ED4PcFk/XWayw35O0lf/nGa4aNgODCmNmw=
-google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478 h1:yQugLulqltosq0B/f8l4w9VryjV+N/5gcW0jQ3N8Qec=
-google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478/go.mod h1:C6ADNqOxbgdUUeRTU+LCHDPB9ttAMCTff6auwCVa4uc=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478 h1:RmoJA1ujG+/lRGNfUnOMfhCy5EipVMyvUE+KNbPbTlw=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260414002931-afd174a4e478/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.82.1 h1:NnAxzGRA0677vCa4BUkOAnO5+FfQqVl9iUXeD0IqcGE=
-google.golang.org/grpc v1.82.1/go.mod h1:yzTZ1TB1Z3SG+LIYaI+WiE8D5+PZ3ArnrSp8zF3+/ZA=
-google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
-google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+google.golang.org/api v0.288.0 h1:glhO/J88obKP5I269W3hB73dvBKrjU56ZfmNlNXpgTU=
+google.golang.org/api v0.288.0/go.mod h1:lM2kYRzYUCBY91P9h6VF1PYmvhxii3O5hji37qRvIcY=
+google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7 h1:XzmzkmB14QhVhgnawEVsOn6OFsnpyxNPRY9QV01dNB0=
+google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7/go.mod h1:L43LFes82YgSonw6iTXTxXUX1OlULt4AQtkik4ULL/I=
+google.golang.org/genproto/googleapis/api v0.0.0-20260630182238-925bb5da69e7 h1:jQ9p21COKWjP3VwuFrNRiiOTMh3mPpN45R7SLrH/HUU=
+google.golang.org/genproto/googleapis/api v0.0.0-20260630182238-925bb5da69e7/go.mod h1:KqHwBx2upmfa1XSi1WuRvC+2VGCLtooKkfmyvRbUmqA=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260706201446-f0a921348800 h1:qEHAMpSaUhtD0p3NbEEI83HwNGFxEwaSJ1G9PLnCBZE=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260706201446-f0a921348800/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.83.2 h1:EManeRomTObA0BU7I8vXgg/78uE5MJ9M8B39EX2WscU=
+google.golang.org/grpc v1.83.2/go.mod h1:YPI1hK3kDked6iHvgX3tR0y+nX/qpMFKhPgFsokw1S8=
+google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
+google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -881,39 +880,39 @@ gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C
 gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-honnef.co/go/tools v0.7.0 h1:w6WUp1VbkqPEgLz4rkBzH/CSU6HkoqNLp6GstyTx3lU=
-honnef.co/go/tools v0.7.0/go.mod h1:pm29oPxeP3P82ISxZDgIYeOaf9ta6Pi0EWvCFoLG2vc=
-modernc.org/cc/v4 v4.29.1 h1:MKgdCV3WykTSPqpVrnxdEDS0HEd2FHpKZDzxzU5LyeI=
-modernc.org/cc/v4 v4.29.1/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
-modernc.org/ccgo/v4 v4.34.6 h1:sBgfIwyN0TQ9C5hwIeuqyeAKyMWnbvj2fvpF4L11uzU=
-modernc.org/ccgo/v4 v4.34.6/go.mod h1:SZ8YcN9NG7XVsQYdm6jYBvi8PQP1qi+kqB6OhjqI3Fk=
+honnef.co/go/tools v0.8.0 h1:UacpzPr7D6i5BAjTkA7sNVcx4kIbhAZcQ4zYtKiXx68=
+honnef.co/go/tools v0.8.0/go.mod h1:XA+OnlRA9EDh/ukGvXMNSZNKGwFQJ+5dER0ioUkOxks=
+modernc.org/cc/v4 v4.29.2 h1:h6+9ciCnPKutf4I03CvheAvDLX7+IHlqR6Iy6J+cgd8=
+modernc.org/cc/v4 v4.29.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.35.0 h1:F+TUsmw09QxLzmi3aeYYGxjAXarmZaKgj3mKQHNaA8w=
+modernc.org/ccgo/v4 v4.35.0/go.mod h1:qrVGs9S3Sr2Ztcg9ve+kTAYMp5a3YvWjo+SoN06kJ5I=
 modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
 modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
 modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
 modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
-modernc.org/gc/v3 v3.1.4 h1:2g65LGVSmFQrXeITAw97x7hCRvZFcyE1uDP+7Vng7JI=
-modernc.org/gc/v3 v3.1.4/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc=
+modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
 modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
 modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
-modernc.org/libc v1.74.4 h1:fX1Omw4o2/1C2iRkkIsrQTasJQldLhRmuPreXLoWs9k=
-modernc.org/libc v1.74.4/go.mod h1:eeQAS9W3sZeKYMFubydxJpII9ybHWshk+7or7bLG9co=
+modernc.org/libc v1.75.6 h1:yKk8qo+Di4gkmvRboK8ocCqH22FiUCR6jRy2OwtCRus=
+modernc.org/libc v1.75.6/go.mod h1:bO5o2ztHxBb2rjz0PgdHN0sSMw57CgxGFLZ3Qd/QpVQ=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
-modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
-modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g=
+modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
 modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
 modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
 modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
 modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
-modernc.org/sqlite v1.56.0 h1:/D8e2RfFqoy/Zc6PuC76U28zFwmI/sYx1Kjm4yEn9e0=
-modernc.org/sqlite v1.56.0/go.mod h1:yCJ2cmAaIkHQ25oXWrF8H4O1lIfPYPR26yCEDj2P3pQ=
+modernc.org/sqlite v1.58.0 h1:38u40/bwkfM7f0Myhosl+SEMltSDxnGdQf8o6Kjmys0=
+modernc.org/sqlite v1.58.0/go.mod h1:rsD2CckafgObKC4DhBlGBf+RiHxkc3hINGt1Xw32tVY=
 modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
 modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
 modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
 modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
-mvdan.cc/gofumpt v0.9.2 h1:zsEMWL8SVKGHNztrx6uZrXdp7AX8r421Vvp23sz7ik4=
-mvdan.cc/gofumpt v0.9.2/go.mod h1:iB7Hn+ai8lPvofHd9ZFGVg2GOr8sBUw1QUWjNbmIL/s=
-mvdan.cc/unparam v0.0.0-20251027182757-5beb8c8f8f15 h1:ssMzja7PDPJV8FStj7hq9IKiuiKhgz9ErWw+m68e7DI=
-mvdan.cc/unparam v0.0.0-20251027182757-5beb8c8f8f15/go.mod h1:4M5MMXl2kW6fivUT6yRGpLLPNfuGtU2Z0cPvFquGDYU=
+mvdan.cc/gofumpt v0.11.0 h1:0H01XB95PnN2QgCSR9ELdZyTlJqNZ7181B0BTMh5VZc=
+mvdan.cc/gofumpt v0.11.0/go.mod h1:BeT5wCsOJt6J9zT2MZIOGszjUHzFkn1/l9g6xAzqsXo=
+mvdan.cc/unparam v0.0.0-20260818115549-3f964bcb5673 h1:dEE6li4OPIE54oojY2qaayFS1fSp17G14si0gXRxl0U=
+mvdan.cc/unparam v0.0.0-20260818115549-3f964bcb5673/go.mod h1:62roFV3D3nYOWIXv3PfGO4UYEKAotz2WgLywT87ONd8=
 sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
 sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=

internal/accesslog/accesslog.go

@@ -0,0 +1,109 @@
+// Package accesslog writes proxy activity as JSON Lines.
+package accesslog
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"os"
+	"sync"
+	"time"
+)
+
+const (
+	accessLogFileMode os.FileMode = 0o600
+
+	// EventRequest identifies the response sent by the proxy to a client.
+	EventRequest = "request"
+	// EventUpstream identifies one HTTP exchange with an upstream service.
+	EventUpstream = "upstream"
+)
+
+type requestIDKey struct{}
+
+// Entry is one proxy activity record.
+type Entry struct {
+	Time       time.Time `json:"time"`
+	Event      string    `json:"event"`
+	RequestID  string    `json:"request_id,omitempty"`
+	Method     string    `json:"method"`
+	Path       string    `json:"path,omitempty"`
+	URL        string    `json:"url,omitempty"`
+	StatusCode int       `json:"status_code,omitempty"`
+	DurationMS int64     `json:"duration_ms"`
+	RemoteAddr string    `json:"remote_addr,omitempty"`
+	Error      string    `json:"error,omitempty"`
+}
+
+// Logger appends complete JSON objects to a file, one per line.
+type Logger struct {
+	mu      sync.Mutex
+	file    *os.File
+	encoder *json.Encoder
+}
+
+// Open opens path for append, creating it with owner-only permissions when needed.
+func Open(path string) (*Logger, error) {
+	file, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, accessLogFileMode)
+	if err != nil {
+		return nil, fmt.Errorf("opening access log: %w", err)
+	}
+
+	return &Logger{
+		file:    file,
+		encoder: json.NewEncoder(file),
+	}, nil
+}
+
+// Write appends an entry to the log.
+func (l *Logger) Write(entry Entry) error {
+	if entry.Time.IsZero() {
+		entry.Time = time.Now().UTC()
+	}
+
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	if err := l.encoder.Encode(entry); err != nil {
+		return fmt.Errorf("writing access log: %w", err)
+	}
+	return nil
+}
+
+// Close closes the log file after any active writer finishes.
+func (l *Logger) Close() error {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	if err := l.file.Close(); err != nil {
+		return fmt.Errorf("closing access log: %w", err)
+	}
+	return nil
+}
+
+// WithRequestID stores a proxy request ID in ctx.
+func WithRequestID(ctx context.Context, requestID string) context.Context {
+	return context.WithValue(ctx, requestIDKey{}, requestID)
+}
+
+// RequestID returns the proxy request ID stored in ctx.
+func RequestID(ctx context.Context) string {
+	requestID, _ := ctx.Value(requestIDKey{}).(string)
+	return requestID
+}
+
+// URLWithoutSecrets returns a URL without user information, query values, or fragments.
+func URLWithoutSecrets(value *url.URL) string {
+	if value == nil {
+		return ""
+	}
+
+	clean := *value
+	clean.User = nil
+	clean.RawQuery = ""
+	clean.ForceQuery = false
+	clean.Fragment = ""
+	clean.RawFragment = ""
+	return clean.String()
+}

internal/accesslog/accesslog_test.go

@@ -0,0 +1,91 @@
+package accesslog
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"net/url"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+func TestLoggerWritesJSONLines(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "access.jsonl")
+	logger, err := Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	const entries = 20
+	var wg sync.WaitGroup
+	for range entries {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if err := logger.Write(Entry{
+				Event:      EventUpstream,
+				RequestID:  "request-id",
+				Method:     "GET",
+				URL:        "https://registry.example/packages/example",
+				StatusCode: 429,
+			}); err != nil {
+				t.Errorf("Write: %v", err)
+			}
+		}()
+	}
+	wg.Wait()
+
+	if err := logger.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	file, err := os.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = file.Close() }()
+
+	scanner := bufio.NewScanner(file)
+	count := 0
+	for scanner.Scan() {
+		var entry Entry
+		if err := json.Unmarshal(scanner.Bytes(), &entry); err != nil {
+			t.Fatalf("line %d is not JSON: %v", count+1, err)
+		}
+		if entry.Time.IsZero() {
+			t.Errorf("line %d has no time", count+1)
+		}
+		if entry.StatusCode != 429 {
+			t.Errorf("line %d status_code = %d, want 429", count+1, entry.StatusCode)
+		}
+		count++
+	}
+	if err := scanner.Err(); err != nil {
+		t.Fatal(err)
+	}
+	if count != entries {
+		t.Errorf("lines = %d, want %d", count, entries)
+	}
+}
+
+func TestRequestID(t *testing.T) {
+	ctx := WithRequestID(context.Background(), "abc-123")
+	if got := RequestID(ctx); got != "abc-123" {
+		t.Errorf("RequestID = %q, want %q", got, "abc-123")
+	}
+}
+
+func TestURLWithoutSecrets(t *testing.T) {
+	value, err := url.Parse("https://user:password@registry.example/package.tgz?token=secret#fragment")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got := URLWithoutSecrets(value)
+	want := "https://registry.example/package.tgz"
+	if got != want {
+		t.Errorf("URLWithoutSecrets = %q, want %q", got, want)
+	}
+}

internal/config/config.go

@@ -24,10 +24,22 @@
 //	storage:
 //	  url: "s3://bucket?endpoint=http://localhost:9000"
 //
+// Google Cloud Storage:
+//
+//	storage:
+//	  url: "gs://bucket-name"
+//
 // For S3, configure credentials via AWS environment variables:
 //
 //	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
 //
+// For GCS, authentication uses Application Default Credentials. This supports
+// GKE Workload Identity, attached service accounts on GCE and Cloud Run, and
+// local credentials created by `gcloud auth application-default login`.
+// When direct_serve is enabled without a private key, the GCS backend uses the
+// IAM Credentials signBlob API. The service account must hold
+// roles/iam.serviceAccountTokenCreator on itself.
+//
 // Database Configuration:
 //
 // The proxy supports two database backends:
@@ -63,6 +75,9 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
+// DefaultSwiftUpstream is the Swift Package Registry used when none is configured.
+const DefaultSwiftUpstream = "https://tuist.dev/api/registry/swift"
+
 // Config holds all configuration for the proxy server.
 type Config struct {
 	// Listen is the address to listen on (e.g., ":8080", "127.0.0.1:8080").
@@ -91,12 +106,19 @@ type Config struct {
 	// Log configures logging.
 	Log LogConfig `json:"log" yaml:"log"`
 
+	// AccessLog configures the JSONL activity log.
+	AccessLog AccessLogConfig `json:"access_log" yaml:"access_log"`
+
 	// Upstream configures upstream registry URLs (optional overrides).
 	Upstream UpstreamConfig `json:"upstream" yaml:"upstream"`
 
 	// Cooldown configures version age filtering to mitigate supply chain attacks.
 	Cooldown CooldownConfig `json:"cooldown" yaml:"cooldown"`
 
+	// Scanning configures pre-cache artifact scanning (trivy, ClamAV, Wiz,
+	// or a custom service) to mitigate supply chain attacks.
+	Scanning ScanningConfig `json:"scanning" yaml:"scanning"`
+
 	// CacheMetadata enables caching of upstream metadata responses for offline fallback.
 	// When enabled, metadata is stored in the database and storage backend.
 	// The mirror command always enables this regardless of this setting.
@@ -171,6 +193,140 @@ func (c *CooldownConfig) NormalizedPackages() map[string]string {
 	return normalized
 }
 
+// ScanningConfig configures pre-cache artifact scanning (e.g. trivy,
+// ClamAV, Wiz, or a custom service) to mitigate supply chain attacks.
+// Unlike Cooldown, which only looks at a version's publish timestamp,
+// scanning inspects the actual artifact bytes before they become
+// servable from cache.
+type ScanningConfig struct {
+	// Enabled turns on the scan gate. When false (default), artifacts are
+	// cached exactly as if scanning didn't exist.
+	Enabled bool `json:"enabled" yaml:"enabled"`
+
+	// FailOpen treats scanner errors and timeouts as an allow verdict
+	// instead of a block. Default is fail-closed, since the default
+	// posture for a security gate should block on infrastructure failure.
+	FailOpen bool `json:"fail_open" yaml:"fail_open"`
+
+	// Timeout bounds each scan call. Uses Go duration syntax (e.g. "30s").
+	// Default: "30s".
+	Timeout string `json:"timeout" yaml:"timeout"`
+
+	// SigningKey authenticates pull requests to the internal scan-fetch
+	// route used by every storage backend. Required whenever Enabled is
+	// true. Supports ${VAR_NAME} expansion like AuthConfig fields.
+	SigningKey string `json:"signing_key" yaml:"signing_key"`
+
+	// FetchBaseURL is the address scanners use to reach this proxy to pull
+	// staged artifacts. Defaults to BaseURL. Set this separately when
+	// scanners reach the proxy over an internal address different from the
+	// public-facing BaseURL (mirrors DirectServeBaseURL/UIBaseURL).
+	FetchBaseURL string `json:"fetch_base_url" yaml:"fetch_base_url"`
+
+	// Scanners is the list of external scanning services to call.
+	Scanners []ScannerConfig `json:"scanners" yaml:"scanners"`
+}
+
+// ScannerConfig configures a single external scanning service.
+type ScannerConfig struct {
+	// Name identifies this scanner in logs and metrics.
+	Name string `json:"name" yaml:"name"`
+
+	// URL is the endpoint the proxy POSTs scan notifications to.
+	URL string `json:"url" yaml:"url"`
+
+	// Mode is "block" (default) or "monitor". A "block" scanner's verdict
+	// can prevent caching; a "monitor" scanner's findings are logged but
+	// never gate caching.
+	Mode string `json:"mode" yaml:"mode"`
+
+	// Ecosystems restricts this scanner to specific ecosystems (e.g.
+	// "npm", "pypi"). Empty means all ecosystems.
+	Ecosystems []string `json:"ecosystems" yaml:"ecosystems"`
+
+	// Headers are additional HTTP headers sent with every scan request
+	// (e.g. for authenticating to the scanner service). Values support
+	// ${VAR_NAME} expansion like AuthConfig fields.
+	Headers map[string]string `json:"headers" yaml:"headers"`
+}
+
+// SigningKeyExpanded returns SigningKey with ${VAR_NAME} references expanded.
+func (s *ScanningConfig) SigningKeyExpanded() string {
+	return expandEnv(s.SigningKey)
+}
+
+// HeadersExpanded returns Headers with ${VAR_NAME} references expanded in
+// each value.
+func (s *ScannerConfig) HeadersExpanded() map[string]string {
+	if len(s.Headers) == 0 {
+		return nil
+	}
+	expanded := make(map[string]string, len(s.Headers))
+	for k, v := range s.Headers {
+		expanded[k] = expandEnv(v)
+	}
+	return expanded
+}
+
+// Validate checks the scanning configuration for errors, applying the
+// default timeout if unset.
+func (s *ScanningConfig) Validate() error {
+	if !s.Enabled {
+		return nil
+	}
+
+	if s.SigningKeyExpanded() == "" {
+		return fmt.Errorf("scanning.signing_key is required when scanning.enabled is true")
+	}
+
+	if len(s.Scanners) == 0 {
+		return fmt.Errorf("scanning.scanners must not be empty when scanning.enabled is true")
+	}
+
+	if s.FetchBaseURL != "" {
+		if err := validateAbsoluteURL("scanning.fetch_base_url", s.FetchBaseURL); err != nil {
+			return err
+		}
+	}
+
+	if s.Timeout == "" {
+		s.Timeout = defaultScanningTimeoutStr
+	}
+	if d, err := time.ParseDuration(s.Timeout); err != nil {
+		return fmt.Errorf("invalid scanning.timeout %q: %w", s.Timeout, err)
+	} else if d <= 0 {
+		return fmt.Errorf("invalid scanning.timeout %q: must be > 0", s.Timeout)
+	}
+
+	for i := range s.Scanners {
+		if err := s.Scanners[i].Validate(); err != nil {
+			return fmt.Errorf("scanning.scanners[%d]: %w", i, err)
+		}
+	}
+
+	return nil
+}
+
+// Validate checks a single scanner's configuration, applying the default
+// mode ("block") if unset.
+func (s *ScannerConfig) Validate() error {
+	if s.Name == "" {
+		return fmt.Errorf("name is required")
+	}
+	if err := validateAbsoluteURL("url", s.URL); err != nil {
+		return err
+	}
+	if s.Mode == "" {
+		s.Mode = "block"
+	}
+	switch s.Mode {
+	case "block", "monitor":
+	default:
+		return fmt.Errorf("invalid mode %q (must be block or monitor)", s.Mode)
+	}
+	return nil
+}
+
 // StorageConfig configures artifact storage.
 type StorageConfig struct {
 	// URL is the storage backend URL.
@@ -178,6 +334,8 @@ type StorageConfig struct {
 	//   - file:///path/to/dir - Local filesystem (default)
 	//   - s3://bucket-name - Amazon S3
 	//   - s3://bucket?endpoint=http://localhost:9000 - S3-compatible (MinIO)
+	//   - gs://bucket-name - Google Cloud Storage (Workload Identity supported)
+	//   - azblob://container-name - Azure Blob Storage
 	// If empty, defaults to file:// with the Path value.
 	URL string `json:"url" yaml:"url"`
 
@@ -194,7 +352,7 @@ type StorageConfig struct {
 
 	// DirectServe enables redirecting cached artifact downloads to presigned
 	// storage URLs (HTTP 302) instead of streaming bytes through the proxy.
-	// Only effective for backends that support URL signing (S3, Azure).
+	// Only effective for backends that support URL signing (S3, GCS, Azure).
 	DirectServe bool `json:"direct_serve" yaml:"direct_serve"`
 
 	// DirectServeTTL is how long presigned URLs remain valid.
@@ -280,13 +438,68 @@ type LogConfig struct {
 	Format string `json:"format" yaml:"format"`
 }
 
-// UpstreamConfig configures upstream registry URLs and authentication.
+// AccessLogConfig configures the JSONL activity log.
+type AccessLogConfig struct {
+	// Path is the file to append activity records to. Empty disables the access log.
+	Path string `json:"path" yaml:"path"`
+}
+
+// UpstreamConfig configures upstream URLs for built-in routes and authentication.
 // Leave empty to use defaults.
 type UpstreamConfig struct {
+	// AllowPrivateHosts permits listed upstream hosts to resolve to private addresses.
+	AllowPrivateHosts []string `json:"allow_private_hosts" yaml:"allow_private_hosts"`
+
+	// AllowLoopback permits upstream requests and redirects to loopback addresses.
+	AllowLoopback bool `json:"allow_loopback" yaml:"allow_loopback"`
+
 	// NPM is the upstream npm registry URL.
 	// Default: https://registry.npmjs.org
 	NPM string `json:"npm" yaml:"npm"`
 
+	// NPMFullMetadata always requests the full packument (application/json)
+	// from the npm upstream, so served metadata carries the "time" map even
+	// when cooldown is disabled. Clients that gate on publish age (for
+	// example Yarn's npmMinimalAgeGate) need this.
+	// Default: false (the abbreviated format is preferred).
+	NPMFullMetadata bool `json:"npm_full_metadata" yaml:"npm_full_metadata"`
+
+	// Cargo is the upstream cargo index URL.
+	// Default: https://index.crates.io
+	Cargo string `json:"cargo" yaml:"cargo"`
+
+	// CargoDownload is the upstream cargo download URL.
+	// Default: https://static.crates.io/crates
+	CargoDownload string `json:"cargo_download" yaml:"cargo_download"`
+
+	// Gem is the upstream RubyGems registry URL.
+	// Default: https://rubygems.org
+	Gem string `json:"gem" yaml:"gem"`
+
+	// Go is the upstream Go module proxy URL.
+	// Default: https://proxy.golang.org
+	Go string `json:"go" yaml:"go"`
+
+	// Hex is the upstream Hex repository URL.
+	// Default: https://repo.hex.pm
+	Hex string `json:"hex" yaml:"hex"`
+
+	// HexAPI is the upstream Hex API URL used for package timestamps.
+	// Default: https://hex.pm
+	HexAPI string `json:"hex_api" yaml:"hex_api"`
+
+	// Pub is the upstream pub registry URL.
+	// Default: https://pub.dev
+	Pub string `json:"pub" yaml:"pub"`
+
+	// PyPI is the upstream PyPI index and API URL.
+	// Default: https://pypi.org
+	PyPI string `json:"pypi" yaml:"pypi"`
+
+	// PyPIDownload is the upstream PyPI package download URL.
+	// Default: https://files.pythonhosted.org
+	PyPIDownload string `json:"pypi_download" yaml:"pypi_download"`
+
 	// Maven is the upstream Maven repository URL.
 	// Default: https://repo1.maven.org/maven2
 	Maven string `json:"maven" yaml:"maven"`
@@ -296,19 +509,87 @@ type UpstreamConfig struct {
 	// Default: https://plugins.gradle.org/m2
 	GradlePluginPortal string `json:"gradle_plugin_portal" yaml:"gradle_plugin_portal"`
 
-	// Cargo is the upstream cargo index URL.
-	// Default: https://index.crates.io
-	Cargo string `json:"cargo" yaml:"cargo"`
+	// NuGet is the upstream NuGet API URL.
+	// Default: https://api.nuget.org
+	NuGet string `json:"nuget" yaml:"nuget"`
 
-	// CargoDownload is the upstream cargo download URL.
-	// Default: https://static.crates.io/crates
-	CargoDownload string `json:"cargo_download" yaml:"cargo_download"`
+	// NuGetSearch is the upstream NuGet search API URL.
+	// Default: https://azuresearch-usnc.nuget.org
+	NuGetSearch string `json:"nuget_search" yaml:"nuget_search"`
+
+	// Composer is the upstream Packagist API URL.
+	// Default: https://packagist.org
+	Composer string `json:"composer" yaml:"composer"`
+
+	// ComposerRepository is the upstream Packagist repository URL.
+	// Default: https://repo.packagist.org
+	ComposerRepository string `json:"composer_repository" yaml:"composer_repository"`
+
+	// Conan is the upstream Conan registry URL.
+	// Default: https://center.conan.io
+	Conan string `json:"conan" yaml:"conan"`
+
+	// Conda is the upstream Conda channel base URL.
+	// Default: https://conda.anaconda.org
+	Conda string `json:"conda" yaml:"conda"`
+
+	// CRAN is the upstream CRAN mirror URL.
+	// Default: https://cloud.r-project.org
+	CRAN string `json:"cran" yaml:"cran"`
+
+	// Julia is the upstream Julia package server URL.
+	// Default: https://pkg.julialang.org
+	Julia string `json:"julia" yaml:"julia"`
+
+	// OCIDefault is the default upstream OCI registry URL.
+	// Default: https://registry-1.docker.io
+	OCIDefault string `json:"oci_default" yaml:"oci_default"`
+
+	// Swift is the upstream Swift Package Registry URL.
+	// Default: https://tuist.dev/api/registry/swift
+	Swift string `json:"swift" yaml:"swift"`
 
 	// Debian is the upstream APT repository base URL.
 	// Example: http://archive.ubuntu.com/ubuntu would get Ubuntu.
 	// Default: http://deb.debian.org/debian
 	Debian string `json:"debian" yaml:"debian"`
 
+	// RPM is the upstream RPM repository base URL.
+	// Default: https://dl.fedoraproject.org/pub/fedora/linux
+	RPM string `json:"rpm" yaml:"rpm"`
+
+	// HomebrewAPI is the upstream Homebrew JSON API URL.
+	// Default: https://formulae.brew.sh/api
+	HomebrewAPI string `json:"homebrew_api" yaml:"homebrew_api"`
+
+	// HomebrewArtifact is the upstream registry URL for Homebrew artifacts.
+	// Default: https://ghcr.io
+	HomebrewArtifact string `json:"homebrew_artifact" yaml:"homebrew_artifact"`
+
+	// Helm maps repository names to HTTP Helm chart repository URLs.
+	// Requests use /helm/{name}/index.yaml and chart URLs in the index are
+	// rewritten to the same named proxy endpoint.
+	Helm map[string]string `json:"helm" yaml:"helm"`
+
+	// APK maps repository names to Alpine APK repository base URLs, served
+	// at /apk/{name}/. The remaining request path mirrors the upstream
+	// layout, e.g. /apk/alpine/v3.22/main/x86_64/APKINDEX.tar.gz.
+	// Default when empty: {"alpine": "https://dl-cdn.alpinelinux.org/alpine"}.
+	APK map[string]string `json:"apk" yaml:"apk"`
+
+	// OCI maps names to OCI registry URLs. Requests to a named registry use
+	// the repository prefix upstream/{name}/, for example
+	// oci://proxy.example.com/upstream/ghcr/owner/chart.
+	OCI map[string]string `json:"oci" yaml:"oci"`
+
+	// Generic maps names to plain HTTP upstream base URLs, served at
+	// /generic/{name}/. The remaining request path and query string are
+	// appended to the upstream URL. GitHub release asset paths
+	// ({owner}/{repo}/releases/download/{tag}/{asset}) are cached in the
+	// artifact cache; everything else goes through the metadata cache.
+	// Example: {"github": "https://github.com", "github-api": "https://api.github.com"}.
+	Generic map[string]string `json:"generic" yaml:"generic"`
+
 	// Auth configures authentication for upstream registries.
 	// Keys are absolute URL scopes matched by scheme, host, effective port,
 	// and path-segment prefix.
@@ -349,6 +630,30 @@ func (u *UpstreamConfig) Validate() error {
 			return fmt.Errorf("invalid upstream.auth URL %q: %w", pattern, err)
 		}
 	}
+	if err := validateNamedUpstreams("upstream.helm", u.Helm); err != nil {
+		return err
+	}
+	if err := validateNamedUpstreams("upstream.apk", u.APK); err != nil {
+		return err
+	}
+	if err := validateNamedUpstreams("upstream.oci", u.OCI); err != nil {
+		return err
+	}
+	if err := validateNamedUpstreams("upstream.generic", u.Generic); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateNamedUpstreams(field string, upstreams map[string]string) error {
+	for name, upstreamURL := range upstreams {
+		if name == "" || name == "." || name == ".." || strings.ContainsAny(name, `/\\`) {
+			return fmt.Errorf("invalid %s name %q", field, name)
+		}
+		if err := validateAbsoluteURL(field+"."+name, upstreamURL); err != nil {
+			return err
+		}
+	}
 	return nil
 }
 
@@ -393,7 +698,7 @@ func authURLPort(value *url.URL) string {
 
 // AuthConfig configures authentication for an upstream registry.
 type AuthConfig struct {
-	// Type is the authentication type: "bearer", "basic", or "header".
+	// Type is the authentication type: "bearer", "basic", "header", or "ecr".
 	Type string `json:"type" yaml:"type"`
 
 	// Token is used for bearer authentication.
@@ -413,6 +718,11 @@ type AuthConfig struct {
 	// HeaderValue is the custom header value (for type "header").
 	// Can reference environment variables with ${VAR_NAME} syntax.
 	HeaderValue string `json:"header_value" yaml:"header_value"`
+
+	// Region is the AWS region for ECR authentication (for type "ecr").
+	// If empty, the region is inferred from private ECR registry URLs before
+	// falling back to the AWS SDK default region chain.
+	Region string `json:"region" yaml:"region"`
 }
 
 // Default returns a Config with sensible defaults.
@@ -434,11 +744,31 @@ func Default() *Config {
 		},
 		Upstream: UpstreamConfig{
 			NPM:                "https://registry.npmjs.org",
-			Maven:              "https://repo1.maven.org/maven2",
-			GradlePluginPortal: "https://plugins.gradle.org/m2",
 			Cargo:              "https://index.crates.io",
 			CargoDownload:      "https://static.crates.io/crates",
+			Gem:                "https://rubygems.org",
+			Go:                 "https://proxy.golang.org",
+			Hex:                "https://repo.hex.pm",
+			HexAPI:             "https://hex.pm",
+			Pub:                "https://pub.dev",
+			PyPI:               "https://pypi.org",
+			PyPIDownload:       "https://files.pythonhosted.org",
+			Maven:              "https://repo1.maven.org/maven2",
+			GradlePluginPortal: "https://plugins.gradle.org/m2",
+			NuGet:              "https://api.nuget.org",
+			NuGetSearch:        "https://azuresearch-usnc.nuget.org",
+			Composer:           "https://packagist.org",
+			ComposerRepository: "https://repo.packagist.org",
+			Conan:              "https://center.conan.io",
+			Conda:              "https://conda.anaconda.org",
+			CRAN:               "https://cloud.r-project.org",
+			Julia:              "https://pkg.julialang.org",
+			Swift:              DefaultSwiftUpstream,
+			OCIDefault:         "https://registry-1.docker.io",
 			Debian:             "http://deb.debian.org/debian",
+			RPM:                "https://dl.fedoraproject.org/pub/fedora/linux",
+			HomebrewAPI:        "https://formulae.brew.sh/api",
+			HomebrewArtifact:   "https://ghcr.io",
 		},
 		Gradle: GradleConfig{
 			BuildCache: GradleBuildCacheConfig{
@@ -498,6 +828,22 @@ func setEnvBool(dst *bool, key string) {
 	}
 }
 
+func setEnvStringSlice(dst *[]string, key string) {
+	value := os.Getenv(key)
+	if value == "" {
+		return
+	}
+	var items []string
+	for item := range strings.SplitSeq(value, ",") {
+		if item = strings.TrimSpace(item); item != "" {
+			items = append(items, item)
+		}
+	}
+	if len(items) > 0 {
+		*dst = items
+	}
+}
+
 // LoadFromEnv applies environment variable overrides to a Config.
 // Environment variables use the PROXY_ prefix:
 //   - PROXY_LISTEN
@@ -508,6 +854,8 @@ func setEnvBool(dst *bool, key string) {
 //   - PROXY_DATABASE_PATH
 //   - PROXY_LOG_LEVEL
 //   - PROXY_LOG_FORMAT
+//   - PROXY_ACCESS_LOG_PATH
+//   - PROXY_UPSTREAM_SWIFT
 //   - PROXY_HEALTH_STORAGE_PROBE_INTERVAL
 func (c *Config) LoadFromEnv() {
 	setEnvString(&c.Listen, "PROXY_LISTEN")
@@ -524,10 +872,42 @@ func (c *Config) LoadFromEnv() {
 	setEnvString(&c.Database.URL, "PROXY_DATABASE_URL")
 	setEnvString(&c.Log.Level, "PROXY_LOG_LEVEL")
 	setEnvString(&c.Log.Format, "PROXY_LOG_FORMAT")
+	setEnvString(&c.AccessLog.Path, "PROXY_ACCESS_LOG_PATH")
+	setEnvStringSlice(&c.Upstream.AllowPrivateHosts, "PROXY_UPSTREAM_ALLOW_PRIVATE_HOSTS")
+	setEnvBool(&c.Upstream.AllowLoopback, "PROXY_UPSTREAM_ALLOW_LOOPBACK")
+	setEnvString(&c.Upstream.NPM, "PROXY_UPSTREAM_NPM")
+	setEnvBool(&c.Upstream.NPMFullMetadata, "PROXY_UPSTREAM_NPM_FULL_METADATA")
+	setEnvString(&c.Upstream.Cargo, "PROXY_UPSTREAM_CARGO")
+	setEnvString(&c.Upstream.CargoDownload, "PROXY_UPSTREAM_CARGO_DOWNLOAD")
+	setEnvString(&c.Upstream.Gem, "PROXY_UPSTREAM_GEM")
+	setEnvString(&c.Upstream.Go, "PROXY_UPSTREAM_GO")
+	setEnvString(&c.Upstream.Hex, "PROXY_UPSTREAM_HEX")
+	setEnvString(&c.Upstream.HexAPI, "PROXY_UPSTREAM_HEX_API")
+	setEnvString(&c.Upstream.Pub, "PROXY_UPSTREAM_PUB")
+	setEnvString(&c.Upstream.PyPI, "PROXY_UPSTREAM_PYPI")
+	setEnvString(&c.Upstream.PyPIDownload, "PROXY_UPSTREAM_PYPI_DOWNLOAD")
 	setEnvString(&c.Upstream.Maven, "PROXY_UPSTREAM_MAVEN")
 	setEnvString(&c.Upstream.GradlePluginPortal, "PROXY_UPSTREAM_GRADLE_PLUGIN_PORTAL")
+	setEnvString(&c.Upstream.NuGet, "PROXY_UPSTREAM_NUGET")
+	setEnvString(&c.Upstream.NuGetSearch, "PROXY_UPSTREAM_NUGET_SEARCH")
+	setEnvString(&c.Upstream.Composer, "PROXY_UPSTREAM_COMPOSER")
+	setEnvString(&c.Upstream.ComposerRepository, "PROXY_UPSTREAM_COMPOSER_REPOSITORY")
+	setEnvString(&c.Upstream.Conan, "PROXY_UPSTREAM_CONAN")
+	setEnvString(&c.Upstream.Conda, "PROXY_UPSTREAM_CONDA")
+	setEnvString(&c.Upstream.CRAN, "PROXY_UPSTREAM_CRAN")
+	setEnvString(&c.Upstream.Julia, "PROXY_UPSTREAM_JULIA")
+	setEnvString(&c.Upstream.Swift, "PROXY_UPSTREAM_SWIFT")
+	setEnvString(&c.Upstream.OCIDefault, "PROXY_UPSTREAM_OCI_DEFAULT")
 	setEnvString(&c.Upstream.Debian, "PROXY_UPSTREAM_DEBIAN")
+	setEnvString(&c.Upstream.RPM, "PROXY_UPSTREAM_RPM")
+	setEnvString(&c.Upstream.HomebrewAPI, "PROXY_UPSTREAM_HOMEBREW_API")
+	setEnvString(&c.Upstream.HomebrewArtifact, "PROXY_UPSTREAM_HOMEBREW_ARTIFACT")
 	setEnvString(&c.Cooldown.Default, "PROXY_COOLDOWN_DEFAULT")
+	setEnvBool(&c.Scanning.Enabled, "PROXY_SCANNING_ENABLED")
+	setEnvBool(&c.Scanning.FailOpen, "PROXY_SCANNING_FAIL_OPEN")
+	setEnvString(&c.Scanning.Timeout, "PROXY_SCANNING_TIMEOUT")
+	setEnvString(&c.Scanning.SigningKey, "PROXY_SCANNING_SIGNING_KEY")
+	setEnvString(&c.Scanning.FetchBaseURL, "PROXY_SCANNING_FETCH_BASE_URL")
 	setEnvBool(&c.CacheMetadata, "PROXY_CACHE_METADATA")
 	setEnvBool(&c.MirrorAPI, "PROXY_MIRROR_API")
 	setEnvString(&c.MetadataTTL, "PROXY_METADATA_TTL")
@@ -644,6 +1024,10 @@ func (c *Config) validateComponents() error {
 		return err
 	}
 
+	if err := c.Scanning.Validate(); err != nil {
+		return err
+	}
+
 	return c.Gradle.BuildCache.Validate()
 }
 
@@ -711,6 +1095,7 @@ const (
 	defaultGradleBuildCacheSweepInterval = 10 * time.Minute
 	defaultGradleMaxUploadSizeStr        = "100MB"
 	defaultGradleSweepIntervalStr        = "10m"
+	defaultScanningTimeoutStr            = "30s"
 )
 
 // ParseMaxSize returns the maximum cache size in bytes.
@@ -889,8 +1274,7 @@ func ParseSize(s string) (int64, error) {
 	}
 
 	for _, s2 := range suffixes {
-		if strings.HasSuffix(s, s2.suffix) {
-			numStr := strings.TrimSuffix(s, s2.suffix)
+		if numStr, ok := strings.CutSuffix(s, s2.suffix); ok {
 			num, err := strconv.ParseFloat(numStr, 64)
 			if err != nil {
 				return 0, fmt.Errorf("invalid number %q", numStr)

internal/config/config_test.go

@@ -14,6 +14,109 @@ const (
 	testLevelDebug     = "debug"
 )
 
+func upstreamConfigValues(upstream UpstreamConfig) map[string]string {
+	return map[string]string{
+		"npm":                  upstream.NPM,
+		"cargo":                upstream.Cargo,
+		"cargo_download":       upstream.CargoDownload,
+		"gem":                  upstream.Gem,
+		"go":                   upstream.Go,
+		"hex":                  upstream.Hex,
+		"hex_api":              upstream.HexAPI,
+		"pub":                  upstream.Pub,
+		"pypi":                 upstream.PyPI,
+		"pypi_download":        upstream.PyPIDownload,
+		"maven":                upstream.Maven,
+		"gradle_plugin_portal": upstream.GradlePluginPortal,
+		"nuget":                upstream.NuGet,
+		"nuget_search":         upstream.NuGetSearch,
+		"composer":             upstream.Composer,
+		"composer_repository":  upstream.ComposerRepository,
+		"conan":                upstream.Conan,
+		"conda":                upstream.Conda,
+		"cran":                 upstream.CRAN,
+		"julia":                upstream.Julia,
+		"swift":                upstream.Swift,
+		"oci_default":          upstream.OCIDefault,
+		"debian":               upstream.Debian,
+		"rpm":                  upstream.RPM,
+		"homebrew_api":         upstream.HomebrewAPI,
+		"homebrew_artifact":    upstream.HomebrewArtifact,
+	}
+}
+
+func defaultUpstreamValues() map[string]string {
+	return map[string]string{
+		"npm":                  "https://registry.npmjs.org",
+		"cargo":                "https://index.crates.io",
+		"cargo_download":       "https://static.crates.io/crates",
+		"gem":                  "https://rubygems.org",
+		"go":                   "https://proxy.golang.org",
+		"hex":                  "https://repo.hex.pm",
+		"hex_api":              "https://hex.pm",
+		"pub":                  "https://pub.dev",
+		"pypi":                 "https://pypi.org",
+		"pypi_download":        "https://files.pythonhosted.org",
+		"maven":                "https://repo1.maven.org/maven2",
+		"gradle_plugin_portal": "https://plugins.gradle.org/m2",
+		"nuget":                "https://api.nuget.org",
+		"nuget_search":         "https://azuresearch-usnc.nuget.org",
+		"composer":             "https://packagist.org",
+		"composer_repository":  "https://repo.packagist.org",
+		"conan":                "https://center.conan.io",
+		"conda":                "https://conda.anaconda.org",
+		"cran":                 "https://cloud.r-project.org",
+		"julia":                "https://pkg.julialang.org",
+		"swift":                "https://tuist.dev/api/registry/swift",
+		"oci_default":          "https://registry-1.docker.io",
+		"debian":               "http://deb.debian.org/debian",
+		"rpm":                  "https://dl.fedoraproject.org/pub/fedora/linux",
+		"homebrew_api":         "https://formulae.brew.sh/api",
+		"homebrew_artifact":    "https://ghcr.io",
+	}
+}
+
+func upstreamEnvironmentVariables() map[string]string {
+	return map[string]string{
+		"npm":                  "PROXY_UPSTREAM_NPM",
+		"cargo":                "PROXY_UPSTREAM_CARGO",
+		"cargo_download":       "PROXY_UPSTREAM_CARGO_DOWNLOAD",
+		"gem":                  "PROXY_UPSTREAM_GEM",
+		"go":                   "PROXY_UPSTREAM_GO",
+		"hex":                  "PROXY_UPSTREAM_HEX",
+		"hex_api":              "PROXY_UPSTREAM_HEX_API",
+		"pub":                  "PROXY_UPSTREAM_PUB",
+		"pypi":                 "PROXY_UPSTREAM_PYPI",
+		"pypi_download":        "PROXY_UPSTREAM_PYPI_DOWNLOAD",
+		"maven":                "PROXY_UPSTREAM_MAVEN",
+		"gradle_plugin_portal": "PROXY_UPSTREAM_GRADLE_PLUGIN_PORTAL",
+		"nuget":                "PROXY_UPSTREAM_NUGET",
+		"nuget_search":         "PROXY_UPSTREAM_NUGET_SEARCH",
+		"composer":             "PROXY_UPSTREAM_COMPOSER",
+		"composer_repository":  "PROXY_UPSTREAM_COMPOSER_REPOSITORY",
+		"conan":                "PROXY_UPSTREAM_CONAN",
+		"conda":                "PROXY_UPSTREAM_CONDA",
+		"cran":                 "PROXY_UPSTREAM_CRAN",
+		"julia":                "PROXY_UPSTREAM_JULIA",
+		"swift":                "PROXY_UPSTREAM_SWIFT",
+		"oci_default":          "PROXY_UPSTREAM_OCI_DEFAULT",
+		"debian":               "PROXY_UPSTREAM_DEBIAN",
+		"rpm":                  "PROXY_UPSTREAM_RPM",
+		"homebrew_api":         "PROXY_UPSTREAM_HOMEBREW_API",
+		"homebrew_artifact":    "PROXY_UPSTREAM_HOMEBREW_ARTIFACT",
+	}
+}
+
+func assertUpstreamValues(t *testing.T, cfg *Config, want map[string]string) {
+	t.Helper()
+	got := upstreamConfigValues(cfg.Upstream)
+	for name, wantValue := range want {
+		if gotValue := got[name]; gotValue != wantValue {
+			t.Errorf("Upstream %s = %q, want %q", name, gotValue, wantValue)
+		}
+	}
+}
+
 func TestDefault(t *testing.T) {
 	cfg := Default()
 
@@ -26,21 +129,22 @@ func TestDefault(t *testing.T) {
 	if cfg.Database.Path == "" {
 		t.Error("Database.Path should not be empty")
 	}
+	if cfg.AccessLog.Path != "" {
+		t.Errorf("AccessLog.Path = %q, want disabled by default", cfg.AccessLog.Path)
+	}
 	if cfg.Gradle.BuildCache.MaxUploadSize != "100MB" {
 		t.Errorf("Gradle.BuildCache.MaxUploadSize = %q, want %q", cfg.Gradle.BuildCache.MaxUploadSize, "100MB")
 	}
 	if cfg.Gradle.BuildCache.MaxAge != "168h" {
 		t.Errorf("Gradle.BuildCache.MaxAge = %q, want %q", cfg.Gradle.BuildCache.MaxAge, "168h")
 	}
-	if cfg.Upstream.Maven != "https://repo1.maven.org/maven2" {
-		t.Errorf("Upstream.Maven = %q, want %q", cfg.Upstream.Maven, "https://repo1.maven.org/maven2")
+	if len(cfg.Upstream.AllowPrivateHosts) != 0 {
+		t.Errorf("Upstream.AllowPrivateHosts = %v, want empty", cfg.Upstream.AllowPrivateHosts)
 	}
-	if cfg.Upstream.GradlePluginPortal != "https://plugins.gradle.org/m2" {
-		t.Errorf("Upstream.GradlePluginPortal = %q, want %q", cfg.Upstream.GradlePluginPortal, "https://plugins.gradle.org/m2")
-	}
-	if cfg.Upstream.Debian != "http://deb.debian.org/debian" {
-		t.Errorf("Upstream.Debian = %q, want %q", cfg.Upstream.Debian, "http://deb.debian.org/debian")
+	if cfg.Upstream.AllowLoopback {
+		t.Error("Upstream.AllowLoopback = true, want false")
 	}
+	assertUpstreamValues(t, cfg, defaultUpstreamValues())
 }
 
 func TestValidate(t *testing.T) {
@@ -212,6 +316,11 @@ database:
 log:
   level: "debug"
   format: "json"
+access_log:
+  path: "/var/log/proxy/access.jsonl"
+upstream:
+  homebrew_api: "https://homebrew-api.example.com"
+  homebrew_artifact: "https://homebrew-artifact.example.com"
 `
 	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
 		t.Fatalf("writing config file: %v", err)
@@ -240,6 +349,72 @@ log:
 	if cfg.Log.Format != "json" {
 		t.Errorf("Log.Format = %q, want %q", cfg.Log.Format, "json")
 	}
+	if cfg.AccessLog.Path != "/var/log/proxy/access.jsonl" {
+		t.Errorf("AccessLog.Path = %q, want %q", cfg.AccessLog.Path, "/var/log/proxy/access.jsonl")
+	}
+	if cfg.Upstream.HomebrewAPI != "https://homebrew-api.example.com" {
+		t.Errorf("Upstream.HomebrewAPI = %q, want %q", cfg.Upstream.HomebrewAPI, "https://homebrew-api.example.com")
+	}
+	if cfg.Upstream.HomebrewArtifact != "https://homebrew-artifact.example.com" {
+		t.Errorf("Upstream.HomebrewArtifact = %q, want %q", cfg.Upstream.HomebrewArtifact, "https://homebrew-artifact.example.com")
+	}
+}
+
+func TestLoadYAMLUpstreams(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.yaml")
+	content := `
+upstream:
+  allow_private_hosts:
+    - "registry.internal"
+    - "10.0.0.12"
+  allow_loopback: true
+  npm: "https://upstream.example.com/npm"
+  cargo: "https://upstream.example.com/cargo"
+  cargo_download: "https://upstream.example.com/cargo_download"
+  gem: "https://upstream.example.com/gem"
+  go: "https://upstream.example.com/go"
+  hex: "https://upstream.example.com/hex"
+  hex_api: "https://upstream.example.com/hex_api"
+  pub: "https://upstream.example.com/pub"
+  pypi: "https://upstream.example.com/pypi"
+  pypi_download: "https://upstream.example.com/pypi_download"
+  maven: "https://upstream.example.com/maven"
+  gradle_plugin_portal: "https://upstream.example.com/gradle_plugin_portal"
+  nuget: "https://upstream.example.com/nuget"
+  nuget_search: "https://upstream.example.com/nuget_search"
+  composer: "https://upstream.example.com/composer"
+  composer_repository: "https://upstream.example.com/composer_repository"
+  conan: "https://upstream.example.com/conan"
+  conda: "https://upstream.example.com/conda"
+  cran: "https://upstream.example.com/cran"
+  julia: "https://upstream.example.com/julia"
+  swift: "https://upstream.example.com/swift"
+  oci_default: "https://upstream.example.com/oci_default"
+  debian: "https://upstream.example.com/debian"
+  rpm: "https://upstream.example.com/rpm"
+  homebrew_api: "https://upstream.example.com/homebrew_api"
+  homebrew_artifact: "https://upstream.example.com/homebrew_artifact"
+`
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		t.Fatalf("writing config file: %v", err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	want := make(map[string]string)
+	for name := range defaultUpstreamValues() {
+		want[name] = "https://upstream.example.com/" + name
+	}
+	assertUpstreamValues(t, cfg, want)
+	if got := strings.Join(cfg.Upstream.AllowPrivateHosts, ","); got != "registry.internal,10.0.0.12" {
+		t.Errorf("Upstream.AllowPrivateHosts = %q, want %q", got, "registry.internal,10.0.0.12")
+	}
+	if !cfg.Upstream.AllowLoopback {
+		t.Error("Upstream.AllowLoopback = false, want true")
+	}
 }
 
 func TestLoadJSON(t *testing.T) {
@@ -248,7 +423,11 @@ func TestLoadJSON(t *testing.T) {
 
 	content := `{
 		"listen": ":4000",
-		"base_url": "https://json.example.com"
+		"base_url": "https://json.example.com",
+		"upstream": {
+			"gem": "https://json.example.com/gem",
+			"rpm": "https://json.example.com/rpm"
+		}
 	}`
 	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
 		t.Fatalf("writing config file: %v", err)
@@ -265,6 +444,12 @@ func TestLoadJSON(t *testing.T) {
 	if cfg.BaseURL != "https://json.example.com" {
 		t.Errorf("BaseURL = %q, want %q", cfg.BaseURL, "https://json.example.com")
 	}
+	if cfg.Upstream.Gem != "https://json.example.com/gem" {
+		t.Errorf("Upstream.Gem = %q, want %q", cfg.Upstream.Gem, "https://json.example.com/gem")
+	}
+	if cfg.Upstream.RPM != "https://json.example.com/rpm" {
+		t.Errorf("Upstream.RPM = %q, want %q", cfg.Upstream.RPM, "https://json.example.com/rpm")
+	}
 }
 
 func TestLoadFromEnv(t *testing.T) {
@@ -275,9 +460,9 @@ func TestLoadFromEnv(t *testing.T) {
 	t.Setenv("PROXY_UI_URL", "https://ui.env.example.com/ui")
 	t.Setenv("PROXY_STORAGE_PATH", "/env/cache")
 	t.Setenv("PROXY_LOG_LEVEL", testLevelDebug)
-	t.Setenv("PROXY_UPSTREAM_MAVEN", "https://maven.example.com/repository/maven-public")
-	t.Setenv("PROXY_UPSTREAM_GRADLE_PLUGIN_PORTAL", "https://plugins.example.com/m2")
-	t.Setenv("PROXY_UPSTREAM_DEBIAN", "http://archive.ubuntu.com/ubuntu")
+	t.Setenv("PROXY_ACCESS_LOG_PATH", "/tmp/proxy-access.jsonl")
+	t.Setenv("PROXY_UPSTREAM_ALLOW_PRIVATE_HOSTS", "registry.internal, 10.0.0.12")
+	t.Setenv("PROXY_UPSTREAM_ALLOW_LOOPBACK", "true")
 	t.Setenv("PROXY_GRADLE_BUILD_CACHE_READ_ONLY", "true")
 	t.Setenv("PROXY_GRADLE_BUILD_CACHE_MAX_UPLOAD_SIZE", "32MB")
 	t.Setenv("PROXY_GRADLE_BUILD_CACHE_MAX_AGE", "12h")
@@ -301,15 +486,22 @@ func TestLoadFromEnv(t *testing.T) {
 	if cfg.Log.Level != testLevelDebug {
 		t.Errorf("Log.Level = %q, want %q", cfg.Log.Level, testLevelDebug)
 	}
-	if cfg.Upstream.Maven != "https://maven.example.com/repository/maven-public" {
-		t.Errorf("Upstream.Maven = %q, want %q", cfg.Upstream.Maven, "https://maven.example.com/repository/maven-public")
+	if cfg.AccessLog.Path != "/tmp/proxy-access.jsonl" {
+		t.Errorf("AccessLog.Path = %q, want %q", cfg.AccessLog.Path, "/tmp/proxy-access.jsonl")
 	}
-	if cfg.Upstream.GradlePluginPortal != "https://plugins.example.com/m2" {
-		t.Errorf("Upstream.GradlePluginPortal = %q, want %q", cfg.Upstream.GradlePluginPortal, "https://plugins.example.com/m2")
+	if got := strings.Join(cfg.Upstream.AllowPrivateHosts, ","); got != "registry.internal,10.0.0.12" {
+		t.Errorf("Upstream.AllowPrivateHosts = %q, want %q", got, "registry.internal,10.0.0.12")
 	}
-	if cfg.Upstream.Debian != "http://archive.ubuntu.com/ubuntu" {
-		t.Errorf("Upstream.Debian = %q, want %q", cfg.Upstream.Debian, "http://archive.ubuntu.com/ubuntu")
+	if !cfg.Upstream.AllowLoopback {
+		t.Error("Upstream.AllowLoopback = false, want true")
 	}
+
+	t.Setenv("PROXY_UPSTREAM_ALLOW_PRIVATE_HOSTS", " , ")
+	cfg.LoadFromEnv()
+	if got := strings.Join(cfg.Upstream.AllowPrivateHosts, ","); got != "registry.internal,10.0.0.12" {
+		t.Errorf("Upstream.AllowPrivateHosts after empty env = %q, want unchanged", got)
+	}
+
 	if !cfg.Gradle.BuildCache.ReadOnly {
 		t.Error("Gradle.BuildCache.ReadOnly = false, want true")
 	}
@@ -327,6 +519,19 @@ func TestLoadFromEnv(t *testing.T) {
 	}
 }
 
+func TestLoadFromEnvUpstreams(t *testing.T) {
+	cfg := Default()
+	want := make(map[string]string)
+	for name, envName := range upstreamEnvironmentVariables() {
+		value := "https://env.example.com/" + name
+		t.Setenv(envName, value)
+		want[name] = value
+	}
+
+	cfg.LoadFromEnv()
+	assertUpstreamValues(t, cfg, want)
+}
+
 func TestLoadCooldownConfig(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, "config.yaml")
@@ -560,6 +765,117 @@ func TestValidateHealthStorageProbeInterval(t *testing.T) {
 	}
 }
 
+func TestScanningConfigValidate(t *testing.T) {
+	tests := []struct {
+		name    string
+		cfg     ScanningConfig
+		wantErr bool
+	}{
+		{
+			name: "disabled skips validation entirely",
+			cfg:  ScanningConfig{Enabled: false, Timeout: "not-a-duration"},
+		},
+		{
+			name:    "enabled without signing key fails",
+			cfg:     ScanningConfig{Enabled: true},
+			wantErr: true,
+		},
+		{
+			name:    "enabled with signing key and no scanners fails",
+			cfg:     ScanningConfig{Enabled: true, SigningKey: "s3cret"},
+			wantErr: true,
+		},
+		{
+			name: "invalid fetch_base_url fails",
+			cfg: ScanningConfig{
+				Enabled:      true,
+				SigningKey:   "s3cret",
+				FetchBaseURL: "not-a-url",
+				Scanners:     []ScannerConfig{{Name: "clamav", URL: "http://scanner.invalid/scan"}},
+			},
+			wantErr: true,
+		},
+		{
+			name: "invalid timeout fails",
+			cfg: ScanningConfig{
+				Enabled:    true,
+				SigningKey: "s3cret",
+				Timeout:    "not-a-duration",
+				Scanners:   []ScannerConfig{{Name: "clamav", URL: "http://scanner.invalid/scan"}},
+			},
+			wantErr: true,
+		},
+		{
+			name: "zero timeout fails",
+			cfg: ScanningConfig{
+				Enabled:    true,
+				SigningKey: "s3cret",
+				Timeout:    "0",
+				Scanners:   []ScannerConfig{{Name: "clamav", URL: "http://scanner.invalid/scan"}},
+			},
+			wantErr: true,
+		},
+		{
+			name: "empty timeout defaults and is valid",
+			cfg: ScanningConfig{
+				Enabled:    true,
+				SigningKey: "s3cret",
+				Timeout:    "",
+				Scanners:   []ScannerConfig{{Name: "clamav", URL: "http://scanner.invalid/scan"}},
+			},
+		},
+		{
+			name: "scanner missing name fails",
+			cfg: ScanningConfig{
+				Enabled:    true,
+				SigningKey: "s3cret",
+				Scanners:   []ScannerConfig{{URL: "http://scanner.invalid/scan"}},
+			},
+			wantErr: true,
+		},
+		{
+			name: "scanner with invalid url fails",
+			cfg: ScanningConfig{
+				Enabled:    true,
+				SigningKey: "s3cret",
+				Scanners:   []ScannerConfig{{Name: "clamav", URL: "not-a-url"}},
+			},
+			wantErr: true,
+		},
+		{
+			name: "scanner with invalid mode fails",
+			cfg: ScanningConfig{
+				Enabled:    true,
+				SigningKey: "s3cret",
+				Scanners: []ScannerConfig{
+					{Name: "clamav", URL: "http://scanner.invalid/scan", Mode: "quarantine"},
+				},
+			},
+			wantErr: true,
+		},
+		{
+			name: "scanner with default mode is valid",
+			cfg: ScanningConfig{
+				Enabled:    true,
+				SigningKey: "s3cret",
+				Scanners:   []ScannerConfig{{Name: "clamav", URL: "http://scanner.invalid/scan"}},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := tt.cfg.Validate()
+			if tt.wantErr && err == nil {
+				t.Error("Validate() error = nil, want error")
+			}
+			if !tt.wantErr && err != nil {
+				t.Errorf("Validate() unexpected error: %v", err)
+			}
+		})
+	}
+}
+
 func TestParseHTTPTimeout(t *testing.T) {
 	tests := []struct {
 		name    string
@@ -866,3 +1182,77 @@ func TestValidateUpstreamAuthURLs(t *testing.T) {
 		}
 	})
 }
+
+func TestValidateNamedUpstreams(t *testing.T) {
+	tests := []struct {
+		name    string
+		modify  func(*Config)
+		wantErr bool
+	}{
+		{
+			name: "valid Helm, OCI, APK, and generic upstreams",
+			modify: func(cfg *Config) {
+				cfg.Upstream.Helm = map[string]string{"bitnami": "https://charts.bitnami.com/bitnami"}
+				cfg.Upstream.OCI = map[string]string{"ghcr": "https://ghcr.io"}
+				cfg.Upstream.APK = map[string]string{"alpine": "https://dl-cdn.alpinelinux.org/alpine"}
+				cfg.Upstream.Generic = map[string]string{
+					"github":     "https://github.com",
+					"github-api": "https://api.github.com",
+				}
+			},
+		},
+		{
+			name: "generic upstream name contains path separator",
+			modify: func(cfg *Config) {
+				cfg.Upstream.Generic = map[string]string{"github/releases": "https://github.com"}
+			},
+			wantErr: true,
+		},
+		{
+			name: "generic upstream URL is not absolute",
+			modify: func(cfg *Config) {
+				cfg.Upstream.Generic = map[string]string{"github": "github.com"}
+			},
+			wantErr: true,
+		},
+		{
+			name: "Helm upstream name contains path separator",
+			modify: func(cfg *Config) {
+				cfg.Upstream.Helm = map[string]string{"team/charts": "https://charts.example.com"}
+			},
+			wantErr: true,
+		},
+		{
+			name: "OCI upstream URL is not absolute",
+			modify: func(cfg *Config) {
+				cfg.Upstream.OCI = map[string]string{"private": "registry.example.com"}
+			},
+			wantErr: true,
+		},
+		{
+			name: "APK upstream name contains path separator",
+			modify: func(cfg *Config) {
+				cfg.Upstream.APK = map[string]string{"alpine/edge": "https://dl-cdn.alpinelinux.org/alpine"}
+			},
+			wantErr: true,
+		},
+		{
+			name: "APK upstream URL is not absolute",
+			modify: func(cfg *Config) {
+				cfg.Upstream.APK = map[string]string{"private": "apk.example.com"}
+			},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := Default()
+			tt.modify(cfg)
+			err := cfg.Validate()
+			if (err != nil) != tt.wantErr {
+				t.Errorf("Validate() error = %v, wantErr %t", err, tt.wantErr)
+			}
+		})
+	}
+}

internal/database/database_test.go

@@ -8,6 +8,11 @@ import (
 	"time"
 )
 
+const (
+	testContentHash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+	testIntegrity   = "sha512-z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg=="
+)
+
 func TestCreateAndOpen(t *testing.T) {
 	dir := t.TempDir()
 	dbPath := filepath.Join(dir, "test.db")
@@ -132,7 +137,7 @@ func TestVersionCRUD(t *testing.T) {
 		v := &Version{
 			PURL:        "pkg:npm/lodash@4.17.21",
 			PackagePURL: "pkg:npm/lodash",
-			Integrity:   sql.NullString{String: "sha512-abc123", Valid: true},
+			Integrity:   sql.NullString{String: testIntegrity, Valid: true},
 		}
 
 		err = db.UpsertVersion(v)
@@ -200,7 +205,7 @@ func TestArtifactCRUD(t *testing.T) {
 			t.Error("expected artifact to not be cached yet")
 		}
 
-		err = db.MarkArtifactCached(versionPURL, "lodash-4.17.21.tgz", "/cache/npm/lodash-4.17.21.tgz", "sha256-abc", 12345, "application/gzip")
+		err = db.MarkArtifactCached(versionPURL, "lodash-4.17.21.tgz", "/cache/npm/lodash-4.17.21.tgz", testContentHash, 12345, "application/gzip")
 		if err != nil {
 			t.Fatalf("MarkArtifactCached failed: %v", err)
 		}
@@ -257,7 +262,7 @@ func TestGetCachedArtifact(t *testing.T) {
 		}
 
 		if err := db.MarkArtifactCached(versionPURL, filename, "/cache/npm/"+filename,
-			"sha256-abc", 12345, "application/gzip"); err != nil {
+			testContentHash, 12345, "application/gzip"); err != nil {
 			t.Fatalf("MarkArtifactCached failed: %v", err)
 		}
 
@@ -274,16 +279,22 @@ func TestGetCachedArtifact(t *testing.T) {
 		if cached.StoragePath != "/cache/npm/"+filename {
 			t.Errorf("expected cached storage path, got %q", cached.StoragePath)
 		}
-		if cached.ContentHash.String != "sha256-abc" {
-			t.Errorf("expected cached content hash, got %q", cached.ContentHash.String)
+		if cached.Artifact.PURL != versionPURL {
+			t.Errorf("expected cached PURL %q, got %q", versionPURL, cached.Artifact.PURL)
 		}
-		if cached.Size.Int64 != 12345 {
-			t.Errorf("expected cached size 12345, got %d", cached.Size.Int64)
+		if cached.Artifact.Digest.String() != "sha256:"+testContentHash {
+			t.Errorf("expected cached digest, got %q", cached.Artifact.Digest)
 		}
-		if cached.ContentType.String != "application/gzip" {
-			t.Errorf("expected cached content type, got %q", cached.ContentType.String)
+		if cached.Artifact.Size != 12345 {
+			t.Errorf("expected cached size 12345, got %d", cached.Artifact.Size)
 		}
-		if cached.Integrity.String != "sha512-abc123" {
+		if cached.Artifact.Filename != filename {
+			t.Errorf("expected cached filename %q, got %q", filename, cached.Artifact.Filename)
+		}
+		if cached.Artifact.MediaType != "application/gzip" {
+			t.Errorf("expected cached content type, got %q", cached.Artifact.MediaType)
+		}
+		if cached.Integrity.String != testIntegrity {
 			t.Errorf("expected cached integrity, got %q", cached.Integrity.String)
 		}
 
@@ -306,7 +317,7 @@ func seedCachedArtifactTestData(t *testing.T, db *DB, packagePURL, versionPURL,
 	if err := db.UpsertVersion(&Version{
 		PURL:        versionPURL,
 		PackagePURL: packagePURL,
-		Integrity:   sql.NullString{String: "sha512-abc123", Valid: true},
+		Integrity:   sql.NullString{String: testIntegrity, Valid: true},
 	}); err != nil {
 		t.Fatalf("UpsertVersion failed: %v", err)
 	}
@@ -1094,3 +1105,56 @@ func BenchmarkMigrateSchemaFullyMigrated(b *testing.B) {
 		}
 	}
 }
+
+func TestVersionPublishedAtPreserved(t *testing.T) {
+	runWithBothDatabases(t, func(t *testing.T, db *DB) {
+		publishedAt := time.Date(2020, 1, 2, 3, 4, 5, 0, time.UTC)
+
+		if err := db.SetVersionPublishedAt("pkg:npm/leftpad@1.0.0", "pkg:npm/leftpad", publishedAt); err != nil {
+			t.Fatalf("SetVersionPublishedAt failed: %v", err)
+		}
+
+		got, err := db.GetVersionByPURL("pkg:npm/leftpad@1.0.0")
+		if err != nil || got == nil {
+			t.Fatalf("GetVersionByPURL failed: %v", err)
+		}
+		if !got.PublishedAt.Valid || !got.PublishedAt.Time.Equal(publishedAt) {
+			t.Fatalf("PublishedAt = %v, want %v", got.PublishedAt, publishedAt)
+		}
+
+		// An upsert that carries no publish time (the artifact cache path)
+		// must not erase the stored value.
+		if err := db.UpsertVersion(&Version{
+			PURL:        "pkg:npm/leftpad@1.0.0",
+			PackagePURL: "pkg:npm/leftpad",
+		}); err != nil {
+			t.Fatalf("UpsertVersion failed: %v", err)
+		}
+
+		got, err = db.GetVersionByPURL("pkg:npm/leftpad@1.0.0")
+		if err != nil || got == nil {
+			t.Fatalf("GetVersionByPURL after upsert failed: %v", err)
+		}
+		if !got.PublishedAt.Valid || !got.PublishedAt.Time.Equal(publishedAt) {
+			t.Fatalf("PublishedAt after null upsert = %v, want %v preserved", got.PublishedAt, publishedAt)
+		}
+
+		// An upsert that does carry a publish time still updates it.
+		later := publishedAt.Add(24 * time.Hour)
+		if err := db.UpsertVersion(&Version{
+			PURL:        "pkg:npm/leftpad@1.0.0",
+			PackagePURL: "pkg:npm/leftpad",
+			PublishedAt: sql.NullTime{Time: later, Valid: true},
+		}); err != nil {
+			t.Fatalf("UpsertVersion with publish time failed: %v", err)
+		}
+
+		got, err = db.GetVersionByPURL("pkg:npm/leftpad@1.0.0")
+		if err != nil || got == nil {
+			t.Fatalf("GetVersionByPURL after second upsert failed: %v", err)
+		}
+		if !got.PublishedAt.Valid || !got.PublishedAt.Time.Equal(later) {
+			t.Fatalf("PublishedAt after valued upsert = %v, want %v", got.PublishedAt, later)
+		}
+	})
+}

internal/database/metadata_cache_test.go

@@ -29,6 +29,7 @@ func TestUpsertAndGetMetadataCache(t *testing.T) {
 		Name:        "lodash",
 		StoragePath: "_metadata/npm/lodash/metadata",
 		ETag:        sql.NullString{String: `"abc123"`, Valid: true},
+		Link:        sql.NullString{String: `<https://registry.example.test/next>; rel="next"`, Valid: true},
 		ContentType: sql.NullString{String: "application/json", Valid: true},
 		ContentDigest: sql.NullString{
 			String: "sha256:0123456789abcdef",
@@ -63,6 +64,9 @@ func TestUpsertAndGetMetadataCache(t *testing.T) {
 	if !got.ETag.Valid || got.ETag.String != `"abc123"` {
 		t.Errorf("etag = %v, want %q", got.ETag, `"abc123"`)
 	}
+	if !got.Link.Valid || got.Link.String != `<https://registry.example.test/next>; rel="next"` {
+		t.Errorf("link = %v, want next link", got.Link)
+	}
 	if !got.ContentType.Valid || got.ContentType.String != "application/json" {
 		t.Errorf("content_type = %v, want %q", got.ContentType, "application/json")
 	}
@@ -158,6 +162,9 @@ func TestUpsertMetadataCacheNullableFields(t *testing.T) {
 	if got.ContentType.Valid {
 		t.Error("expected null content_type")
 	}
+	if got.Link.Valid {
+		t.Error("expected null link")
+	}
 	if got.Size.Valid {
 		t.Error("expected null size")
 	}
@@ -229,3 +236,129 @@ func TestMetadataCacheContentDigestMigrationPreservesExistingRows(t *testing.T)
 		t.Errorf("legacy content digest = %q, want NULL", entry.ContentDigest.String)
 	}
 }
+
+func TestMetadataCacheLinkMigrationPreservesExistingRows(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "test.db")
+	db, err := Create(dbPath)
+	if err != nil {
+		t.Fatalf("Create failed: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	if _, err := db.Exec("ALTER TABLE metadata_cache DROP COLUMN link"); err != nil {
+		t.Fatalf("dropping link: %v", err)
+	}
+	if _, err := db.Exec("DELETE FROM migrations WHERE name = ?", "007_add_metadata_link"); err != nil {
+		t.Fatalf("resetting link migration: %v", err)
+	}
+	if _, err := db.Exec(`
+		INSERT INTO metadata_cache (ecosystem, name, storage_path, content_type, size, fetched_at, created_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+	`, "oci-tags", "cache-key", "_metadata/oci-tags/cache-key/metadata", "application/json", 2, time.Now(), time.Now(), time.Now()); err != nil {
+		t.Fatalf("inserting legacy cache row: %v", err)
+	}
+
+	if err := db.MigrateSchema(); err != nil {
+		t.Fatalf("MigrateSchema() error = %v", err)
+	}
+	hasLink, err := db.HasColumn("metadata_cache", "link")
+	if err != nil {
+		t.Fatalf("HasColumn() error = %v", err)
+	}
+	if !hasLink {
+		t.Fatal("metadata_cache.link was not added")
+	}
+
+	entry, err := db.GetMetadataCache("oci-tags", "cache-key")
+	if err != nil {
+		t.Fatalf("GetMetadataCache() error = %v", err)
+	}
+	if entry == nil || entry.StoragePath != "_metadata/oci-tags/cache-key/metadata" {
+		t.Fatalf("existing metadata cache row was not preserved: %#v", entry)
+	}
+	if entry.Link.Valid {
+		t.Errorf("legacy link = %q, want NULL", entry.Link.String)
+	}
+}
+
+func TestMetadataCacheContentEncodingMigrationPreservesExistingRows(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "test.db")
+	db, err := Create(dbPath)
+	if err != nil {
+		t.Fatalf("Create failed: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	if _, err := db.Exec("ALTER TABLE metadata_cache DROP COLUMN content_encoding"); err != nil {
+		t.Fatalf("dropping content_encoding: %v", err)
+	}
+	if _, err := db.Exec("DELETE FROM migrations WHERE name = ?", "008_add_metadata_content_encoding"); err != nil {
+		t.Fatalf("resetting content_encoding migration: %v", err)
+	}
+	if _, err := db.Exec(`
+		INSERT INTO metadata_cache (ecosystem, name, storage_path, etag, content_type, size, fetched_at, created_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "apk", "cache-key", "_metadata/apk/cache-key/metadata", "\"legacy-etag\"", "application/octet-stream", 2, time.Now(), time.Now(), time.Now()); err != nil {
+		t.Fatalf("inserting legacy cache row: %v", err)
+	}
+
+	if err := db.MigrateSchema(); err != nil {
+		t.Fatalf("MigrateSchema() error = %v", err)
+	}
+	hasEncoding, err := db.HasColumn("metadata_cache", "content_encoding")
+	if err != nil {
+		t.Fatalf("HasColumn() error = %v", err)
+	}
+	if !hasEncoding {
+		t.Fatal("metadata_cache.content_encoding was not added")
+	}
+
+	entry, err := db.GetMetadataCache("apk", "cache-key")
+	if err != nil {
+		t.Fatalf("GetMetadataCache() error = %v", err)
+	}
+	if entry == nil || entry.StoragePath != "_metadata/apk/cache-key/metadata" {
+		t.Fatalf("existing metadata cache row was not preserved: %#v", entry)
+	}
+	if entry.ContentEncoding.Valid {
+		t.Errorf("legacy content encoding = %q, want NULL", entry.ContentEncoding.String)
+	}
+	// The migration must clear the pre-fix validators so the row is refetched
+	// once with identity instead of a 304 re-serving the decompressed copy.
+	if entry.ETag.Valid {
+		t.Errorf("legacy etag = %q, want cleared", entry.ETag.String)
+	}
+	if entry.FetchedAt.Valid {
+		t.Errorf("legacy fetched_at = %v, want cleared", entry.FetchedAt.Time)
+	}
+}
+
+func TestMetadataCacheRoundTripsContentEncoding(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "test.db")
+	db, err := Create(dbPath)
+	if err != nil {
+		t.Fatalf("Create failed: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	entry := &MetadataCacheEntry{
+		Ecosystem:       "apk",
+		Name:            "index-key",
+		StoragePath:     "_metadata/apk/index-key/metadata",
+		ContentType:     sql.NullString{String: "application/octet-stream", Valid: true},
+		ContentEncoding: sql.NullString{String: "gzip", Valid: true},
+		Size:            sql.NullInt64{Int64: 10, Valid: true},
+		FetchedAt:       sql.NullTime{Time: time.Now(), Valid: true},
+	}
+	if err := db.UpsertMetadataCache(entry); err != nil {
+		t.Fatalf("UpsertMetadataCache() error = %v", err)
+	}
+
+	got, err := db.GetMetadataCache("apk", "index-key")
+	if err != nil {
+		t.Fatalf("GetMetadataCache() error = %v", err)
+	}
+	if got == nil || !got.ContentEncoding.Valid || got.ContentEncoding.String != "gzip" {
+		t.Fatalf("content encoding round-trip failed: %#v", got)
+	}
+}

internal/database/queries.go

@@ -4,6 +4,9 @@ import (
 	"database/sql"
 	"fmt"
 	"time"
+
+	"github.com/git-pkgs/artifacts"
+	"github.com/opencontainers/go-digest"
 )
 
 // Package queries
@@ -141,7 +144,7 @@ func (db *DB) UpsertVersion(v *Version) error {
 			ON CONFLICT(purl) DO UPDATE SET
 				license = EXCLUDED.license,
 				integrity = EXCLUDED.integrity,
-				published_at = EXCLUDED.published_at,
+				published_at = COALESCE(EXCLUDED.published_at, versions.published_at),
 				yanked = EXCLUDED.yanked,
 				enriched_at = EXCLUDED.enriched_at,
 				updated_at = EXCLUDED.updated_at
@@ -154,7 +157,7 @@ func (db *DB) UpsertVersion(v *Version) error {
 			ON CONFLICT(purl) DO UPDATE SET
 				license = excluded.license,
 				integrity = excluded.integrity,
-				published_at = excluded.published_at,
+				published_at = COALESCE(excluded.published_at, published_at),
 				yanked = excluded.yanked,
 				enriched_at = excluded.enriched_at,
 				updated_at = excluded.updated_at
@@ -171,6 +174,38 @@ func (db *DB) UpsertVersion(v *Version) error {
 	return nil
 }
 
+// SetVersionPublishedAt records a version's publish time, creating the
+// versions row if the proxy has not seen the version yet. It only writes
+// published_at, so it never disturbs enrichment data on an existing row.
+func (db *DB) SetVersionPublishedAt(versionPURL, packagePURL string, publishedAt time.Time) error {
+	now := time.Now()
+	var query string
+
+	if db.dialect == DialectPostgres {
+		query = `
+			INSERT INTO versions (purl, package_purl, published_at, created_at, updated_at)
+			VALUES ($1, $2, $3, $4, $5)
+			ON CONFLICT(purl) DO UPDATE SET
+				published_at = EXCLUDED.published_at,
+				updated_at = EXCLUDED.updated_at
+		`
+	} else {
+		query = `
+			INSERT INTO versions (purl, package_purl, published_at, created_at, updated_at)
+			VALUES (?, ?, ?, ?, ?)
+			ON CONFLICT(purl) DO UPDATE SET
+				published_at = excluded.published_at,
+				updated_at = excluded.updated_at
+		`
+	}
+
+	_, err := db.Exec(query, versionPURL, packagePURL, publishedAt, now, now)
+	if err != nil {
+		return fmt.Errorf("setting version publish time: %w", err)
+	}
+	return nil
+}
+
 // Artifact queries
 
 func (db *DB) GetArtifact(versionPURL, filename string) (*Artifact, error) {
@@ -193,7 +228,7 @@ func (db *DB) GetArtifact(versionPURL, filename string) (*Artifact, error) {
 
 // GetCachedArtifact returns the fields needed to serve a cached artifact.
 func (db *DB) GetCachedArtifact(packagePURL, versionPURL, filename string) (*CachedArtifact, error) {
-	var artifact CachedArtifact
+	var row cachedArtifactRow
 	query := db.Rebind(`
 		SELECT packages.ecosystem, artifacts.storage_path, artifacts.content_hash, artifacts.size,
 		       artifacts.content_type, versions.integrity
@@ -203,14 +238,42 @@ func (db *DB) GetCachedArtifact(packagePURL, versionPURL, filename string) (*Cac
 		WHERE packages.purl = ? AND artifacts.version_purl = ? AND artifacts.filename = ?
 		  AND artifacts.storage_path IS NOT NULL AND artifacts.fetched_at IS NOT NULL
 	`)
-	err := db.Get(&artifact, query, packagePURL, versionPURL, filename)
+	err := db.Get(&row, query, packagePURL, versionPURL, filename)
 	if err == sql.ErrNoRows {
 		return nil, nil
 	}
 	if err != nil {
 		return nil, err
 	}
-	return &artifact, nil
+	return row.artifact(versionPURL, filename), nil
+}
+
+type cachedArtifactRow struct {
+	Ecosystem   string         `db:"ecosystem"`
+	StoragePath string         `db:"storage_path"`
+	ContentHash sql.NullString `db:"content_hash"`
+	Size        sql.NullInt64  `db:"size"`
+	ContentType sql.NullString `db:"content_type"`
+	Integrity   sql.NullString `db:"integrity"`
+}
+
+// artifact converts a cached artifact row to a CachedArtifact without
+// validation. A malformed hash or integrity value is handled by
+// checkCache, which clears the record and treats the request as a cache
+// miss so the client is served a fresh fetch instead of an error.
+func (row cachedArtifactRow) artifact(versionPURL, filename string) *CachedArtifact {
+	return &CachedArtifact{
+		Ecosystem:   row.Ecosystem,
+		StoragePath: row.StoragePath,
+		Integrity:   row.Integrity,
+		Artifact: artifacts.Artifact{
+			PURL:      versionPURL,
+			Digest:    digest.Digest("sha256:" + row.ContentHash.String),
+			Size:      row.Size.Int64,
+			Filename:  filename,
+			MediaType: row.ContentType.String,
+		},
+	}
 }
 
 func (db *DB) GetArtifactByPath(storagePath string) (*Artifact, error) {
@@ -465,11 +528,14 @@ func (db *DB) GetMostPopularPackages(limit int) ([]PopularPackage, error) {
 }
 
 type RecentPackage struct {
-	Ecosystem string    `db:"ecosystem"`
-	Name      string    `db:"name"`
-	Version   string    `db:"version"`
-	CachedAt  time.Time `db:"fetched_at"`
-	Size      int64     `db:"size"`
+	Ecosystem   string    `db:"ecosystem"`
+	Name        string    `db:"name"`
+	VersionPURL string    `db:"version_purl"`
+	CachedAt    time.Time `db:"fetched_at"`
+	Size        int64     `db:"size"`
+	// Version is derived from VersionPURL rather than selected, so that the
+	// PURL percent-encoding is decoded (e.g. "%2B" back to "+").
+	Version string `db:"-"`
 }
 
 func (db *DB) GetRecentlyCachedPackages(limit int) ([]RecentPackage, error) {
@@ -483,10 +549,10 @@ func (db *DB) GetRecentlyCachedPackages(limit int) ([]RecentPackage, error) {
 	}
 
 	var packages []RecentPackage
-	// We need to extract version from the purl since there's no separate version column
+	// There is no separate version column, so the full version PURL is selected
+	// and the version is decoded from it in Go.
 	query := db.Rebind(`
-		SELECT p.ecosystem, p.name,
-		       SUBSTR(v.purl, INSTR(v.purl, '@') + 1) as version,
+		SELECT p.ecosystem, p.name, v.purl as version_purl,
 		       a.fetched_at, COALESCE(a.size, 0) as size
 		FROM artifacts a
 		JOIN versions v ON v.purl = a.version_purl
@@ -496,25 +562,13 @@ func (db *DB) GetRecentlyCachedPackages(limit int) ([]RecentPackage, error) {
 		LIMIT ?
 	`)
 
-	// For postgres, use different string function
-	if db.dialect == DialectPostgres {
-		query = db.Rebind(`
-			SELECT p.ecosystem, p.name,
-			       SUBSTRING(v.purl FROM POSITION('@' IN v.purl) + 1) as version,
-			       a.fetched_at, COALESCE(a.size, 0) as size
-			FROM artifacts a
-			JOIN versions v ON v.purl = a.version_purl
-			JOIN packages p ON p.purl = v.package_purl
-			WHERE a.storage_path IS NOT NULL AND a.fetched_at IS NOT NULL
-			ORDER BY a.fetched_at DESC
-			LIMIT ?
-		`)
-	}
-
 	err = db.Select(&packages, query, limit)
 	if err != nil {
 		return nil, err
 	}
+	for i := range packages {
+		packages[i].Version = VersionFromPURL(packages[i].VersionPURL)
+	}
 	return packages, nil
 }
 
@@ -915,7 +969,7 @@ func (db *DB) CountCachedPackages(ecosystem string) (int64, error) {
 func (db *DB) GetMetadataCache(ecosystem, name string) (*MetadataCacheEntry, error) {
 	var entry MetadataCacheEntry
 	query := db.Rebind(`
-		SELECT id, ecosystem, name, storage_path, etag, content_type,
+		SELECT id, ecosystem, name, storage_path, etag, link, content_type, content_encoding,
 		       content_digest, size, last_modified, fetched_at, created_at, updated_at
 		FROM metadata_cache WHERE ecosystem = ? AND name = ?
 	`)
@@ -935,13 +989,15 @@ func (db *DB) UpsertMetadataCache(entry *MetadataCacheEntry) error {
 
 	if db.dialect == DialectPostgres {
 		query = `
-			INSERT INTO metadata_cache (ecosystem, name, storage_path, etag, content_type,
+			INSERT INTO metadata_cache (ecosystem, name, storage_path, etag, link, content_type, content_encoding,
 			                            content_digest, size, last_modified, fetched_at, created_at, updated_at)
-			VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+			VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
 			ON CONFLICT(ecosystem, name) DO UPDATE SET
 				storage_path = EXCLUDED.storage_path,
 				etag = EXCLUDED.etag,
+				link = EXCLUDED.link,
 				content_type = EXCLUDED.content_type,
+				content_encoding = EXCLUDED.content_encoding,
 				content_digest = EXCLUDED.content_digest,
 				size = EXCLUDED.size,
 				last_modified = EXCLUDED.last_modified,
@@ -950,13 +1006,15 @@ func (db *DB) UpsertMetadataCache(entry *MetadataCacheEntry) error {
 		`
 	} else {
 		query = `
-			INSERT INTO metadata_cache (ecosystem, name, storage_path, etag, content_type,
+			INSERT INTO metadata_cache (ecosystem, name, storage_path, etag, link, content_type, content_encoding,
 			                            content_digest, size, last_modified, fetched_at, created_at, updated_at)
-			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 			ON CONFLICT(ecosystem, name) DO UPDATE SET
 				storage_path = excluded.storage_path,
 				etag = excluded.etag,
+				link = excluded.link,
 				content_type = excluded.content_type,
+				content_encoding = excluded.content_encoding,
 				content_digest = excluded.content_digest,
 				size = excluded.size,
 				last_modified = excluded.last_modified,
@@ -966,8 +1024,8 @@ func (db *DB) UpsertMetadataCache(entry *MetadataCacheEntry) error {
 	}
 
 	_, err := db.Exec(query,
-		entry.Ecosystem, entry.Name, entry.StoragePath, entry.ETag,
-		entry.ContentType, entry.ContentDigest, entry.Size, entry.LastModified, entry.FetchedAt, now, now,
+		entry.Ecosystem, entry.Name, entry.StoragePath, entry.ETag, entry.Link,
+		entry.ContentType, entry.ContentEncoding, entry.ContentDigest, entry.Size, entry.LastModified, entry.FetchedAt, now, now,
 	)
 	if err != nil {
 		return fmt.Errorf("upserting metadata cache: %w", err)

internal/database/schema.go

@@ -101,7 +101,9 @@ CREATE TABLE IF NOT EXISTS metadata_cache (
 	name TEXT NOT NULL,
 	storage_path TEXT NOT NULL,
 	etag TEXT,
+	link TEXT,
 	content_type TEXT,
+	content_encoding TEXT,
 	content_digest TEXT,
 	size INTEGER,
 	last_modified DATETIME,
@@ -202,7 +204,9 @@ CREATE TABLE IF NOT EXISTS metadata_cache (
 	name TEXT NOT NULL,
 	storage_path TEXT NOT NULL,
 	etag TEXT,
+	link TEXT,
 	content_type TEXT,
+	content_encoding TEXT,
 	content_digest TEXT,
 	size BIGINT,
 	last_modified TIMESTAMP,
@@ -362,6 +366,8 @@ var migrations = []migration{
 	{"004_ensure_vulnerabilities_table", migrateEnsureVulnerabilitiesTable},
 	{"005_ensure_metadata_cache_table", migrateEnsureMetadataCacheTable},
 	{"006_add_metadata_content_digest", migrateAddMetadataContentDigest},
+	{"007_add_metadata_link", migrateAddMetadataLink},
+	{"008_add_metadata_content_encoding", migrateAddMetadataContentEncoding},
 }
 
 // isTableNotFound returns true if the error indicates a missing table.
@@ -598,6 +604,42 @@ func migrateAddMetadataContentDigest(db *DB) error {
 	return nil
 }
 
+func migrateAddMetadataLink(db *DB) error {
+	hasColumn, err := db.HasColumn("metadata_cache", "link")
+	if err != nil {
+		return fmt.Errorf("checking metadata_cache link column: %w", err)
+	}
+	if hasColumn {
+		return nil
+	}
+	if _, err := db.Exec("ALTER TABLE metadata_cache ADD COLUMN link TEXT"); err != nil {
+		return fmt.Errorf("adding metadata_cache link column: %w", err)
+	}
+	return nil
+}
+
+func migrateAddMetadataContentEncoding(db *DB) error {
+	hasColumn, err := db.HasColumn("metadata_cache", "content_encoding")
+	if err != nil {
+		return fmt.Errorf("checking metadata_cache content_encoding column: %w", err)
+	}
+	if hasColumn {
+		return nil
+	}
+	if _, err := db.Exec("ALTER TABLE metadata_cache ADD COLUMN content_encoding TEXT"); err != nil {
+		return fmt.Errorf("adding metadata_cache content_encoding column: %w", err)
+	}
+	// Rows cached before this column existed hold transport-decompressed bytes
+	// with no recorded encoding and the upstream ETag captured under Go's
+	// auto-added Accept-Encoding: gzip. Clearing the validators forces one fresh
+	// fetch per key so the encoding is recorded and verbatim bytes are restored,
+	// instead of an If-None-Match 304 re-serving the stale decompressed copy.
+	if _, err := db.Exec("UPDATE metadata_cache SET etag = NULL, fetched_at = NULL"); err != nil {
+		return fmt.Errorf("invalidating metadata_cache validators: %w", err)
+	}
+	return nil
+}
+
 // EnsureMetadataCacheTable creates the metadata_cache table if it doesn't exist.
 func (db *DB) EnsureMetadataCacheTable() error {
 	has, err := db.HasTable("metadata_cache")
@@ -616,8 +658,10 @@ func (db *DB) EnsureMetadataCacheTable() error {
 				ecosystem TEXT NOT NULL,
 				name TEXT NOT NULL,
 				storage_path TEXT NOT NULL,
-				etag TEXT,
-				content_type TEXT,
+			etag TEXT,
+			link TEXT,
+			content_type TEXT,
+			content_encoding TEXT,
 				content_digest TEXT,
 				size BIGINT,
 				last_modified TIMESTAMP,
@@ -634,8 +678,10 @@ func (db *DB) EnsureMetadataCacheTable() error {
 				ecosystem TEXT NOT NULL,
 				name TEXT NOT NULL,
 				storage_path TEXT NOT NULL,
-				etag TEXT,
-				content_type TEXT,
+			etag TEXT,
+			link TEXT,
+			content_type TEXT,
+			content_encoding TEXT,
 				content_digest TEXT,
 				size INTEGER,
 				last_modified DATETIME,

internal/database/types.go

@@ -2,8 +2,11 @@ package database
 
 import (
 	"database/sql"
+	"net/url"
 	"strings"
 	"time"
+
+	"github.com/git-pkgs/artifacts"
 )
 
 // Package represents a package in the database.
@@ -47,10 +50,79 @@ type Version struct {
 // Version extracts the version string from the PURL.
 // e.g., "pkg:npm/lodash@4.17.21" -> "4.17.21"
 func (v *Version) Version() string {
-	if idx := strings.LastIndex(v.PURL, "@"); idx >= 0 {
-		return v.PURL[idx+1:]
+	return VersionFromPURL(v.PURL)
+}
+
+// EscapedVersion returns the version escaped for use as a single URL path
+// segment.
+//
+// Version returns decoded text, which is what should be shown to a user but is
+// not safe to drop into a link: html/template preserves reserved characters and
+// existing escapes in a URL, so "release/1" would split into two path segments,
+// "v1?build" would start a query string, and a literal "%2B" would be read back
+// as "+". Escaping here and decoding in splitWildcardPath round-trips the value,
+// so the link resolves to the version that was stored.
+func (v *Version) EscapedVersion() string {
+	return url.PathEscape(v.Version())
+}
+
+// DisplayPURL returns the PURL with its path components percent-decoded, for
+// showing in the UI. The stored PURL keeps the canonical encoding (which is
+// what the API and all lookups use); this is only a readable rendering, so that
+// a version like "7.91+dfsg1-2ubuntu0.1" is not shown as "7.91%2Bdfsg1-2ubuntu0.1"
+// and an npm scope is shown as "@babel" rather than "%40babel". Qualifiers and
+// subpath keep their encoding, since decoding those would be ambiguous.
+func (v *Version) DisplayPURL() string {
+	base, suffix := v.PURL, ""
+	if i := strings.IndexAny(base, "?#"); i >= 0 {
+		base, suffix = base[:i], base[i:]
 	}
-	return ""
+
+	name, version := base, ""
+	if idx := strings.LastIndex(base, "@"); idx >= 0 {
+		name, version = base[:idx], "@"+decodePURLComponent(base[idx+1:])
+	}
+
+	parts := strings.Split(name, "/")
+	for i, part := range parts {
+		parts[i] = decodePURLComponent(part)
+	}
+	return strings.Join(parts, "/") + version + suffix
+}
+
+// VersionFromPURL extracts the decoded version string from a PURL.
+//
+// PURL percent-encodes characters that are not safe in a path component, so a
+// Debian version like "7.91+dfsg1-2ubuntu0.1" is stored as
+// "pkg:deb/nmap@7.91%2Bdfsg1-2ubuntu0.1". The raw substring after "@" is
+// therefore not the version: it must be percent-decoded before being displayed
+// or used to build a URL, otherwise "%2B" leaks into the UI and round-tripping
+// the value back into a PURL double-encodes it.
+//
+// e.g., "pkg:npm/lodash@4.17.21" -> "4.17.21"
+func VersionFromPURL(p string) string {
+	// Qualifiers ("?key=value") and subpath ("#path") follow the version.
+	if i := strings.IndexAny(p, "?#"); i >= 0 {
+		p = p[:i]
+	}
+	idx := strings.LastIndex(p, "@")
+	if idx < 0 {
+		return ""
+	}
+	return decodePURLComponent(p[idx+1:])
+}
+
+// decodePURLComponent percent-decodes a single PURL path component, returning
+// the input unchanged if it is not valid percent-encoding.
+func decodePURLComponent(s string) string {
+	if !strings.Contains(s, "%") {
+		return s
+	}
+	decoded, err := url.PathUnescape(s)
+	if err != nil {
+		return s
+	}
+	return decoded
 }
 
 // Artifact represents a cached artifact in the database.
@@ -78,28 +150,28 @@ func (a *Artifact) IsCached() bool {
 
 // CachedArtifact contains the fields needed to serve a cached artifact.
 type CachedArtifact struct {
-	Ecosystem   string         `db:"ecosystem"`
-	StoragePath string         `db:"storage_path"`
-	ContentHash sql.NullString `db:"content_hash"`
-	Size        sql.NullInt64  `db:"size"`
-	ContentType sql.NullString `db:"content_type"`
-	Integrity   sql.NullString `db:"integrity"`
+	Ecosystem   string
+	StoragePath string
+	Artifact    artifacts.Artifact
+	Integrity   sql.NullString
 }
 
 // MetadataCacheEntry represents a cached metadata blob for offline serving.
 type MetadataCacheEntry struct {
-	ID            int64          `db:"id" json:"id"`
-	Ecosystem     string         `db:"ecosystem" json:"ecosystem"`
-	Name          string         `db:"name" json:"name"`
-	StoragePath   string         `db:"storage_path" json:"storage_path"`
-	ETag          sql.NullString `db:"etag" json:"etag,omitempty"`
-	ContentType   sql.NullString `db:"content_type" json:"content_type,omitempty"`
-	ContentDigest sql.NullString `db:"content_digest" json:"content_digest,omitempty"`
-	Size          sql.NullInt64  `db:"size" json:"size,omitempty"`
-	LastModified  sql.NullTime   `db:"last_modified" json:"last_modified,omitempty"`
-	FetchedAt     sql.NullTime   `db:"fetched_at" json:"fetched_at,omitempty"`
-	CreatedAt     time.Time      `db:"created_at" json:"created_at"`
-	UpdatedAt     time.Time      `db:"updated_at" json:"updated_at"`
+	ID              int64          `db:"id" json:"id"`
+	Ecosystem       string         `db:"ecosystem" json:"ecosystem"`
+	Name            string         `db:"name" json:"name"`
+	StoragePath     string         `db:"storage_path" json:"storage_path"`
+	ETag            sql.NullString `db:"etag" json:"etag,omitempty"`
+	Link            sql.NullString `db:"link" json:"link,omitempty"`
+	ContentType     sql.NullString `db:"content_type" json:"content_type,omitempty"`
+	ContentEncoding sql.NullString `db:"content_encoding" json:"content_encoding,omitempty"`
+	ContentDigest   sql.NullString `db:"content_digest" json:"content_digest,omitempty"`
+	Size            sql.NullInt64  `db:"size" json:"size,omitempty"`
+	LastModified    sql.NullTime   `db:"last_modified" json:"last_modified,omitempty"`
+	FetchedAt       sql.NullTime   `db:"fetched_at" json:"fetched_at,omitempty"`
+	CreatedAt       time.Time      `db:"created_at" json:"created_at"`
+	UpdatedAt       time.Time      `db:"updated_at" json:"updated_at"`
 }
 
 // Vulnerability represents a cached vulnerability record.

internal/database/version_purl_test.go

@@ -0,0 +1,159 @@
+package database
+
+import (
+	"database/sql"
+	"net/url"
+	"testing"
+	"time"
+)
+
+func TestVersionFromPURL(t *testing.T) {
+	tests := []struct {
+		name string
+		purl string
+		want string
+	}{
+		{"simple", "pkg:npm/lodash@4.17.21", "4.17.21"},
+		{"namespaced", "pkg:composer/symfony/console@6.0.0", "6.0.0"},
+		// Debian/Ubuntu versions routinely contain "+", which PURL encodes.
+		{"encoded plus", "pkg:deb/nmap@7.91%2Bdfsg1%2Breally7.80%2Bdfsg1-2ubuntu0.1", "7.91+dfsg1+really7.80+dfsg1-2ubuntu0.1"},
+		{"encoded epoch", "pkg:deb/curl@1%3A7.81.0-1", "1:7.81.0-1"},
+		{"encoded plus with qualifier", "pkg:deb/nmap@7.91%2Bdfsg1?repository_url=http%3A%2F%2Fexample.com", "7.91+dfsg1"},
+		{"tilde is not encoded", "pkg:deb/foo@1.0~rc1", "1.0~rc1"},
+		{"no version", "pkg:npm/lodash", ""},
+		{"invalid escape passed through", "pkg:npm/lodash@1.0%zz", "1.0%zz"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := VersionFromPURL(tt.purl); got != tt.want {
+				t.Errorf("VersionFromPURL(%q) = %q, want %q", tt.purl, got, tt.want)
+			}
+			v := &Version{PURL: tt.purl}
+			if got := v.Version(); got != tt.want {
+				t.Errorf("Version.Version() for %q = %q, want %q", tt.purl, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestVersionEscapedVersion checks the value the templates put in a URL. It
+// must survive the round trip back through the router: escaping here and
+// decoding per path segment on the way in has to yield the original version.
+func TestVersionEscapedVersion(t *testing.T) {
+	tests := []struct {
+		name string
+		purl string
+		want string
+	}{
+		{"simple", "pkg:npm/lodash@4.17.21", "4.17.21"},
+		// "+" is legal in a path segment, so it stays literal and the UI keeps
+		// showing the version the way Debian writes it.
+		{"plus stays literal", "pkg:deb/nmap@7.91%2Bdfsg1-2ubuntu0.1", "7.91+dfsg1-2ubuntu0.1"},
+		// A slash would otherwise split the version into two path segments.
+		{"slash", "pkg:golang/example@release%2F1", "release%2F1"},
+		// A question mark would otherwise start the query string.
+		{"question mark", "pkg:npm/example@v1%3Fbuild", "v1%3Fbuild"},
+		// A version containing a literal "%2B" is stored double-encoded; the
+		// link must re-encode it or it decodes back to "+" instead.
+		{"literal percent escape", "pkg:npm/example@1.0%252B", "1.0%252B"},
+		{"space", "pkg:npm/example@1.0%20beta", "1.0%20beta"},
+		{"no version", "pkg:npm/lodash", ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			v := &Version{PURL: tt.purl}
+			got := v.EscapedVersion()
+			if got != tt.want {
+				t.Errorf("EscapedVersion() for %q = %q, want %q", tt.purl, got, tt.want)
+			}
+			// The router decodes each path segment, which must give back the
+			// version the page displays.
+			decoded, err := url.PathUnescape(got)
+			if err != nil {
+				t.Fatalf("PathUnescape(%q) failed: %v", got, err)
+			}
+			if decoded != v.Version() {
+				t.Errorf("round trip for %q = %q, want %q", tt.purl, decoded, v.Version())
+			}
+		})
+	}
+}
+
+func TestVersionDisplayPURL(t *testing.T) {
+	tests := []struct {
+		name string
+		purl string
+		want string
+	}{
+		{"simple", "pkg:npm/lodash@4.17.21", "pkg:npm/lodash@4.17.21"},
+		{
+			"encoded plus",
+			"pkg:deb/nmap@7.91%2Bdfsg1%2Breally7.80%2Bdfsg1-2ubuntu0.1",
+			"pkg:deb/nmap@7.91+dfsg1+really7.80+dfsg1-2ubuntu0.1",
+		},
+		{
+			"qualifier preserved",
+			"pkg:deb/nmap@7.91%2Bdfsg1?repository_url=http%3A%2F%2Fexample.com",
+			"pkg:deb/nmap@7.91+dfsg1?repository_url=http%3A%2F%2Fexample.com",
+		},
+		// The namespace is encoded too: MakePURLString("npm", "@babel/core", …)
+		// produces "pkg:npm/%40babel/core@…".
+		{"encoded npm scope", "pkg:npm/%40babel/core@7.0.0", "pkg:npm/@babel/core@7.0.0"},
+		{"encoded scope without version", "pkg:npm/%40babel/core", "pkg:npm/@babel/core"},
+		{"no version", "pkg:npm/lodash", "pkg:npm/lodash"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			v := &Version{PURL: tt.purl}
+			if got := v.DisplayPURL(); got != tt.want {
+				t.Errorf("DisplayPURL() for %q = %q, want %q", tt.purl, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestGetRecentlyCachedPackagesDecodesVersion guards the dashboard's "recently
+// cached" list, which derives the version from the version PURL.
+func TestGetRecentlyCachedPackagesDecodesVersion(t *testing.T) {
+	runWithBothDatabases(t, func(t *testing.T, db *DB) {
+		const versionPURL = "pkg:deb/nmap@7.91%2Bdfsg1%2Breally7.80%2Bdfsg1-2ubuntu0.1"
+
+		if err := db.UpsertPackage(&Package{
+			PURL: "pkg:deb/nmap", Ecosystem: "deb", Name: "nmap",
+		}); err != nil {
+			t.Fatalf("UpsertPackage failed: %v", err)
+		}
+		if err := db.UpsertVersion(&Version{
+			PURL: versionPURL, PackagePURL: "pkg:deb/nmap",
+		}); err != nil {
+			t.Fatalf("UpsertVersion failed: %v", err)
+		}
+		if err := db.UpsertArtifact(&Artifact{
+			VersionPURL: versionPURL,
+			Filename:    "nmap_7.91+dfsg1+really7.80+dfsg1-2ubuntu0.1_amd64.deb",
+			UpstreamURL: "http://archive.ubuntu.com/ubuntu/pool/universe/n/nmap/nmap.deb",
+			StoragePath: sql.NullString{String: "/cache/nmap.deb", Valid: true},
+			FetchedAt:   sql.NullTime{Time: time.Now(), Valid: true},
+		}); err != nil {
+			t.Fatalf("UpsertArtifact failed: %v", err)
+		}
+
+		recent, err := db.GetRecentlyCachedPackages(10)
+		if err != nil {
+			t.Fatalf("GetRecentlyCachedPackages failed: %v", err)
+		}
+		if len(recent) != 1 {
+			t.Fatalf("expected 1 recent package, got %d", len(recent))
+		}
+		const want = "7.91+dfsg1+really7.80+dfsg1-2ubuntu0.1"
+		if recent[0].Version != want {
+			t.Errorf("Version = %q, want %q", recent[0].Version, want)
+		}
+		if recent[0].VersionPURL != versionPURL {
+			t.Errorf("VersionPURL = %q, want %q", recent[0].VersionPURL, versionPURL)
+		}
+	})
+}

internal/enrichment/enrichment.go

@@ -9,6 +9,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/git-pkgs/proxy/internal/packageurl"
 	"github.com/git-pkgs/purl"
 	"github.com/git-pkgs/registries"
 	_ "github.com/git-pkgs/registries/all" // Import all registry implementations
@@ -67,7 +68,10 @@ type VulnInfo struct {
 
 // EnrichPackage fetches metadata for a package from registry APIs.
 func (s *Service) EnrichPackage(ctx context.Context, ecosystem, name string) (*PackageInfo, error) {
-	purlStr := purl.MakePURLString(ecosystem, name, "")
+	purlStr := packageurl.MakeString(ecosystem, name, "")
+	if purlStr == "" {
+		return nil, nil
+	}
 
 	pkg, err := registries.FetchPackageFromPURL(ctx, purlStr, s.regClient)
 	if err != nil {
@@ -102,7 +106,10 @@ func (s *Service) EnrichPackage(ctx context.Context, ecosystem, name string) (*P
 
 // EnrichVersion fetches metadata for a specific package version.
 func (s *Service) EnrichVersion(ctx context.Context, ecosystem, name, version string) (*VersionInfo, error) {
-	purlStr := purl.MakePURLString(ecosystem, name, version)
+	purlStr := packageurl.MakeString(ecosystem, name, version)
+	if purlStr == "" {
+		return nil, nil
+	}
 
 	ver, err := registries.FetchVersionFromPURL(ctx, purlStr, s.regClient)
 	if err != nil {
@@ -134,9 +141,14 @@ func (s *Service) EnrichVersion(ctx context.Context, ecosystem, name, version st
 
 // BulkEnrichPackages fetches metadata for multiple packages in parallel.
 func (s *Service) BulkEnrichPackages(ctx context.Context, packages []struct{ Ecosystem, Name string }) map[string]*PackageInfo {
-	purls := make([]string, len(packages))
-	for i, pkg := range packages {
-		purls[i] = purl.MakePURLString(pkg.Ecosystem, pkg.Name, "")
+	purls := make([]string, 0, len(packages))
+	for _, pkg := range packages {
+		if purlStr := packageurl.MakeString(pkg.Ecosystem, pkg.Name, ""); purlStr != "" {
+			purls = append(purls, purlStr)
+		}
+	}
+	if len(purls) == 0 {
+		return map[string]*PackageInfo{}
 	}
 
 	pkgData := registries.BulkFetchPackages(ctx, purls, s.regClient)
@@ -147,7 +159,10 @@ func (s *Service) BulkEnrichPackages(ctx context.Context, packages []struct{ Eco
 			continue
 		}
 
-		p, _ := purl.Parse(purlStr)
+		p, err := purl.Parse(purlStr)
+		if err != nil {
+			continue
+		}
 		info := &PackageInfo{
 			Ecosystem:     p.Type,
 			Name:          pkg.Name,
@@ -174,7 +189,10 @@ func (s *Service) BulkEnrichPackages(ctx context.Context, packages []struct{ Eco
 
 // CheckVulnerabilities queries for vulnerabilities affecting a package version.
 func (s *Service) CheckVulnerabilities(ctx context.Context, ecosystem, name, version string) ([]VulnInfo, error) {
-	p := purl.MakePURL(ecosystem, name, version)
+	p := packageurl.Make(ecosystem, name, version)
+	if p == nil {
+		return nil, nil
+	}
 
 	vulnList, err := s.vulnSource.Query(ctx, p)
 	if err != nil {
@@ -201,43 +219,6 @@ func (s *Service) CheckVulnerabilities(ctx context.Context, ecosystem, name, ver
 	return results, nil
 }
 
-// BulkCheckVulnerabilities queries vulnerabilities for multiple package versions.
-func (s *Service) BulkCheckVulnerabilities(ctx context.Context, packages []struct{ Ecosystem, Name, Version string }) (map[string][]VulnInfo, error) {
-	purls := make([]*purl.PURL, len(packages))
-	for i, pkg := range packages {
-		purls[i] = purl.MakePURL(pkg.Ecosystem, pkg.Name, pkg.Version)
-	}
-
-	vulnResults, err := s.vulnSource.QueryBatch(ctx, purls)
-	if err != nil {
-		return nil, err
-	}
-
-	result := make(map[string][]VulnInfo, len(packages))
-	for i, vulnList := range vulnResults {
-		pkg := packages[i]
-		key := purl.MakePURLString(pkg.Ecosystem, pkg.Name, pkg.Version)
-
-		var infos []VulnInfo
-		for _, v := range vulnList {
-			info := VulnInfo{
-				ID:           v.ID,
-				Summary:      v.Summary,
-				Severity:     v.SeverityLevel(),
-				CVSSScore:    v.CVSSScore(),
-				FixedVersion: v.FixedVersion(pkg.Ecosystem, pkg.Name),
-			}
-			for _, ref := range v.References {
-				info.References = append(info.References, ref.URL)
-			}
-			infos = append(infos, info)
-		}
-		result[key] = infos
-	}
-
-	return result, nil
-}
-
 // IsOutdated checks if a version is older than the latest version.
 func (s *Service) IsOutdated(currentVersion, latestVersion string) bool {
 	if latestVersion == "" || currentVersion == "" {
@@ -248,7 +229,10 @@ func (s *Service) IsOutdated(currentVersion, latestVersion string) bool {
 
 // GetLatestVersion fetches the latest version for a package.
 func (s *Service) GetLatestVersion(ctx context.Context, ecosystem, name string) (string, error) {
-	purlStr := purl.MakePURLString(ecosystem, name, "")
+	purlStr := packageurl.MakeString(ecosystem, name, "")
+	if purlStr == "" {
+		return "", nil
+	}
 
 	latest, err := registries.FetchLatestVersionFromPURL(ctx, purlStr, s.regClient)
 	if err != nil {
@@ -288,19 +272,6 @@ func (s *Service) CategorizeLicense(license string) LicenseCategory {
 	return LicenseUnknown
 }
 
-// NormalizeLicense normalizes a license string to SPDX format.
-func (s *Service) NormalizeLicense(license string) string {
-	if license == "" {
-		return ""
-	}
-
-	if normalized, err := spdx.NormalizeExpressionLax(license); err == nil {
-		return normalized
-	}
-
-	return license
-}
-
 // EnrichmentResult contains all enrichment data for a package version.
 type EnrichmentResult struct {
 	Package         *PackageInfo

internal/enrichment/enrichment_test.go

@@ -1,6 +1,7 @@
 package enrichment
 
 import (
+	"context"
 	"log/slog"
 	"os"
 	"testing"
@@ -23,6 +24,36 @@ func TestNew(t *testing.T) {
 	}
 }
 
+func TestSwiftRegistryIdentitySkipsPURLDependentLookups(t *testing.T) {
+	svc := New(slog.New(slog.NewTextHandler(os.Stdout, nil)))
+	ctx := context.Background()
+
+	packageInfo, err := svc.EnrichPackage(ctx, "swift", "apple/example")
+	if err != nil || packageInfo != nil {
+		t.Errorf("EnrichPackage() = %#v, %v; want nil, nil", packageInfo, err)
+	}
+
+	versionInfo, err := svc.EnrichVersion(ctx, "swift", "apple/example", "1.2.3")
+	if err != nil || versionInfo != nil {
+		t.Errorf("EnrichVersion() = %#v, %v; want nil, nil", versionInfo, err)
+	}
+
+	vulnerabilities, err := svc.CheckVulnerabilities(ctx, "swift", "apple/example", "1.2.3")
+	if err != nil || vulnerabilities != nil {
+		t.Errorf("CheckVulnerabilities() = %#v, %v; want nil, nil", vulnerabilities, err)
+	}
+
+	latest, err := svc.GetLatestVersion(ctx, "swift", "apple/example")
+	if err != nil || latest != "" {
+		t.Errorf("GetLatestVersion() = %q, %v; want empty string, nil", latest, err)
+	}
+
+	packages := []struct{ Ecosystem, Name string }{{Ecosystem: "swift", Name: "apple/example"}}
+	if got := svc.BulkEnrichPackages(ctx, packages); len(got) != 0 {
+		t.Errorf("BulkEnrichPackages() = %#v, want empty result", got)
+	}
+}
+
 func TestIsOutdated(t *testing.T) {
 	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
 	svc := New(logger)
@@ -74,25 +105,3 @@ func TestCategorizeLicense(t *testing.T) {
 		}
 	}
 }
-
-func TestNormalizeLicense(t *testing.T) {
-	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
-	svc := New(logger)
-
-	tests := []struct {
-		input    string
-		expected string
-	}{
-		{"MIT", "MIT"},
-		{"Apache 2", "Apache-2.0"},
-		{"Apache-2.0", "Apache-2.0"},
-		{"", ""},
-	}
-
-	for _, tc := range tests {
-		result := svc.NormalizeLicense(tc.input)
-		if result != tc.expected {
-			t.Errorf("NormalizeLicense(%q) = %q, want %q", tc.input, result, tc.expected)
-		}
-	}
-}

internal/handler/apk.go

@@ -0,0 +1,186 @@
+package handler
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"regexp"
+	"strings"
+)
+
+const (
+	apkEcosystem = "alpine"
+	// defaultAPKRepositoryName is the repository name used when no
+	// upstream.apk repositories are configured.
+	defaultAPKRepositoryName = "alpine"
+	// defaultAPKUpstream is the official Alpine Linux mirror.
+	defaultAPKUpstream = "https://dl-cdn.alpinelinux.org/alpine"
+	apkMatchCount      = 3 // full match + name + version
+)
+
+// APKHandler handles Alpine APK repository protocol requests. Each configured
+// upstream repository is mounted at /apk/{repository}/ and the remaining path
+// mirrors the upstream layout ({release}/{repo}/{arch}/{file}).
+//
+// Repository indexes (v2 APKINDEX.tar.gz, v3 Packages.adb) and detached
+// signatures are served byte-for-byte unchanged through the metadata cache so
+// apk signature verification keeps working. Package files are cached in the
+// shared artifact cache and stay available when the upstream is unreachable.
+type APKHandler struct {
+	proxy        *Proxy
+	proxyURL     string
+	repositories map[string]string
+}
+
+// NewAPKHandler creates an Alpine APK repository protocol handler.
+// When repositories is empty, a single repository named "alpine" pointing at
+// the official Alpine mirror is used.
+func NewAPKHandler(proxy *Proxy, proxyURL string, repositories map[string]string) *APKHandler {
+	h := &APKHandler{
+		proxy:        proxy,
+		proxyURL:     strings.TrimSuffix(proxyURL, "/"),
+		repositories: make(map[string]string, len(repositories)),
+	}
+	for name, repositoryURL := range repositories {
+		h.repositories[name] = strings.TrimSuffix(repositoryURL, "/")
+	}
+	if len(h.repositories) == 0 {
+		h.repositories[defaultAPKRepositoryName] = defaultAPKUpstream
+	}
+	return h
+}
+
+// Routes returns the HTTP handler for APK requests.
+// Mount this at /apk on your router.
+func (h *APKHandler) Routes() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet && r.Method != http.MethodHead {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+
+		path := strings.TrimPrefix(r.URL.Path, "/")
+
+		if containsPathTraversal(path) {
+			http.Error(w, "invalid path", http.StatusBadRequest)
+			return
+		}
+
+		repository, rest, ok := strings.Cut(path, "/")
+		upstreamURL, found := h.repositories[repository]
+		if !ok || rest == "" || !found {
+			http.NotFound(w, r)
+			return
+		}
+
+		switch {
+		case isAPKIndex(rest) || isAPKSignature(rest):
+			// Indexes and detached signatures are signed upstream metadata.
+			// Cache them with the metadata TTL and serve the stored bytes
+			// unchanged so apk verification continues to work.
+			h.handleMetadata(w, r, repository, upstreamURL, rest)
+		case strings.HasSuffix(rest, ".apk"):
+			// Package downloads - cache these in the artifact cache.
+			h.handlePackageDownload(w, r, repository, upstreamURL, rest)
+		default:
+			// Other files - proxy directly.
+			h.proxyFile(w, r, upstreamURL, rest)
+		}
+	})
+}
+
+// isAPKIndex reports whether the path names a repository index:
+// APKINDEX.tar.gz (apk v2) or Packages.adb (apk v3).
+func isAPKIndex(path string) bool {
+	base := path[strings.LastIndex(path, "/")+1:]
+	return base == "APKINDEX.tar.gz" || base == "Packages.adb"
+}
+
+// isAPKSignature reports whether the path names a detached signature file.
+func isAPKSignature(path string) bool {
+	return strings.HasSuffix(path, ".sig") || strings.HasSuffix(path, ".rsa.pub")
+}
+
+// handlePackageDownload fetches and caches .apk packages.
+// Path format: {release}/{repo}/{arch}/{name}-{version}-r{rel}.apk
+// Example: v3.22/main/x86_64/busybox-1.37.0-r12.apk
+//
+// APK filenames do not include the architecture, so the same filename can hold
+// different bytes per architecture (and per release). The full request path is
+// therefore part of the cache identity.
+func (h *APKHandler) handlePackageDownload(w http.ResponseWriter, r *http.Request, repository, upstreamURL, path string) {
+	name, version, arch := h.parseAPKPath(path)
+	if name == "" {
+		// Can't parse, just proxy directly
+		h.proxyFile(w, r, upstreamURL, path)
+		return
+	}
+
+	downloadURL := upstreamURL + "/" + path
+	cacheFilename := repository + "/" + path
+
+	h.proxy.Logger.Info("apk package download",
+		"repository", repository, "name", name, "version", version, "arch", arch)
+
+	result, err := h.proxy.GetOrFetchArtifactFromURL(
+		r.Context(), apkEcosystem, name, version, cacheFilename, downloadURL)
+	if err != nil {
+		h.proxy.serveArtifactError(w, err, "failed to fetch package")
+		return
+	}
+
+	if result.Artifact.MediaType == "" {
+		result.Artifact.MediaType = "application/octet-stream"
+	}
+	serveArtifact(w, r.Method, result)
+}
+
+// handleMetadata serves repository indexes and signatures through the
+// metadata cache. Stored bytes are re-served verbatim, which keeps embedded
+// and detached signatures valid.
+func (h *APKHandler) handleMetadata(w http.ResponseWriter, r *http.Request, repository, upstreamURL, path string) {
+	h.proxy.ProxyCached(w, r, upstreamURL+"/"+path, apkEcosystem,
+		h.metadataCacheKey(repository, upstreamURL, path), "*/*")
+}
+
+// metadataCacheKey derives the metadata cache key from the repository name,
+// its upstream URL, and the request path. Hashing the identity keeps distinct
+// repositories from sharing cache entries (repository names may contain '_'
+// and a separator-based key would be ambiguous) and drops cached entries when
+// a repository is repointed at a different upstream, mirroring
+// HelmHandler.indexCacheKey.
+func (h *APKHandler) metadataCacheKey(repository, upstreamURL, path string) string {
+	identity := repository + "\x00" + upstreamURL + "\x00" + path
+	digest := sha256.Sum256([]byte(identity))
+	return hex.EncodeToString(digest[:])
+}
+
+// proxyFile proxies any file directly without caching.
+func (h *APKHandler) proxyFile(w http.ResponseWriter, r *http.Request, upstreamURL, path string) {
+	h.proxy.ProxyFile(w, r, upstreamURL+"/"+path)
+}
+
+// apkPackagePattern matches .apk filenames to extract name and version.
+// Format: {name}-{version}-r{rel}.apk where version starts with a digit.
+// Examples:
+//   - busybox-1.37.0-r12.apk
+//   - alpine-baselayout-data-3.7.0-r0.apk
+var apkPackagePattern = regexp.MustCompile(`^(.+)-(\d[^-]*-r\d+)\.apk$`)
+
+// parseAPKPath extracts package info from a path containing an APK filename.
+// The architecture is taken from the parent directory since APK filenames do
+// not include it.
+func (h *APKHandler) parseAPKPath(path string) (name, version, arch string) {
+	segments := strings.Split(path, "/")
+	filename := segments[len(segments)-1]
+	if len(segments) > 1 {
+		arch = segments[len(segments)-2]
+	}
+
+	matches := apkPackagePattern.FindStringSubmatch(filename)
+	if len(matches) != apkMatchCount {
+		return "", "", ""
+	}
+
+	return matches[1], matches[2], arch
+}

internal/handler/apk_test.go

@@ -0,0 +1,362 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/registries/fetch"
+)
+
+func TestAPKHandler_parseAPKPath(t *testing.T) {
+	h := &APKHandler{}
+
+	assertPathParser(t, "parseAPKPath", h.parseAPKPath, []pathParseCase{
+		{"v3.22/main/x86_64/busybox-1.37.0-r12.apk", "busybox", "1.37.0-r12", "x86_64"},
+		{"v3.22/main/aarch64/alpine-baselayout-data-3.7.0-r0.apk", "alpine-baselayout-data", "3.7.0-r0", "aarch64"},
+		{"edge/community/x86_64/openjdk21-jre-21.0.2_p13-r1.apk", "openjdk21-jre", "21.0.2_p13-r1", "x86_64"},
+		{"busybox-1.37.0-r12.apk", "busybox", "1.37.0-r12", ""},
+		{"v3.22/main/x86_64/invalid.apk", "", "", ""},
+		{"v3.22/main/x86_64/not-an-apk-file", "", "", ""},
+	})
+}
+
+func TestAPKHandler_Routes(t *testing.T) {
+	h := NewAPKHandler(nil, "http://localhost:8080", nil)
+	assertRoutesBasics(t, h.Routes(), "/alpine/v3.22/main/x86_64/APKINDEX.tar.gz", "/alpine/v3.22/../../../etc/passwd")
+}
+
+func TestAPKHandler_DefaultsToOfficialMirror(t *testing.T) {
+	h := NewAPKHandler(nil, "http://localhost:8080", nil)
+	if got := h.repositories[defaultAPKRepositoryName]; got != defaultAPKUpstream {
+		t.Errorf("default repository = %q, want %q", got, defaultAPKUpstream)
+	}
+}
+
+func TestAPKHandler_UnknownRepositoryReturns404(t *testing.T) {
+	proxy, _, _, _ := setupTestProxy(t)
+	h := NewAPKHandler(proxy, "http://localhost:8080", map[string]string{"alpine": "https://example.test"})
+
+	for _, target := range []string{
+		"/unknown/v3.22/main/x86_64/APKINDEX.tar.gz",
+		"/alpine",
+		"/",
+	} {
+		w := serveAPKRequest(h, target)
+		if w.Code != http.StatusNotFound {
+			t.Errorf("%s: status = %d, want 404", target, w.Code)
+		}
+	}
+}
+
+// TestAPKHandler_MetadataCacheKeysDoNotCollideAcrossRepositories guards the
+// hashed metadata cache key: with a separator-based key, repositories named
+// "alpine" and "alpine_edge" would share cache entries for
+// /alpine/edge/main/x86_64/APKINDEX.tar.gz and
+// /alpine_edge/main/x86_64/APKINDEX.tar.gz, serving one repository's signed
+// index to clients of the other.
+func TestAPKHandler_MetadataCacheKeysDoNotCollideAcrossRepositories(t *testing.T) {
+	indexA := "signed index of repository A"
+	upstreamA := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/edge/main/x86_64/APKINDEX.tar.gz" {
+			http.NotFound(w, r)
+			return
+		}
+		_, _ = fmt.Fprint(w, indexA)
+	}))
+	defer upstreamA.Close()
+
+	indexB := "signed index of repository B"
+	upstreamB := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/main/x86_64/APKINDEX.tar.gz" {
+			http.NotFound(w, r)
+			return
+		}
+		_, _ = fmt.Fprint(w, indexB)
+	}))
+	defer upstreamB.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = http.DefaultClient
+
+	h := NewAPKHandler(proxy, "http://proxy.example", map[string]string{
+		"alpine":      upstreamA.URL,
+		"alpine_edge": upstreamB.URL,
+	})
+
+	first := serveAPKRequest(h, "/alpine/edge/main/x86_64/APKINDEX.tar.gz")
+	if first.Code != http.StatusOK || first.Body.String() != indexA {
+		t.Fatalf("repository A: status = %d, body = %q, want 200 %q", first.Code, first.Body.String(), indexA)
+	}
+
+	// Served within the metadata TTL: a colliding key would return indexA here.
+	second := serveAPKRequest(h, "/alpine_edge/main/x86_64/APKINDEX.tar.gz")
+	if second.Code != http.StatusOK {
+		t.Fatalf("repository B: status = %d, want 200: %s", second.Code, second.Body.String())
+	}
+	if second.Body.String() != indexB {
+		t.Errorf("repository B served %q, want %q (cache key collision)", second.Body.String(), indexB)
+	}
+}
+
+// TestAPKHandler_IndexesServedUnchanged covers v2 (APKINDEX.tar.gz) and v3
+// (Packages.adb) indexes plus detached signatures: bytes must be served
+// unchanged so apk signature verification keeps working, and within the
+// metadata TTL cached copies must be served without contacting the upstream
+// (the stale-after-TTL fallback itself is covered by the shared ProxyCached
+// tests).
+func TestAPKHandler_IndexesServedUnchanged(t *testing.T) {
+	files := map[string][]byte{
+		"/v3.22/main/x86_64/APKINDEX.tar.gz":  []byte("\x1f\x8b\x08v2-index-with-embedded-signature"),
+		"/v3.22/main/x86_64/Packages.adb":     []byte("ADB.v3-index-binary\x00payload"),
+		"/v3.22/main/x86_64/Packages.adb.sig": []byte("detached-signature-bytes"),
+	}
+
+	var available atomic.Bool
+	available.Store(true)
+	var upstreamRequests atomic.Int32
+	var authHeader string
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !available.Load() {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		authHeader = r.Header.Get("Authorization")
+		data, ok := files[r.URL.Path]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		upstreamRequests.Add(1)
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = w.Write(data)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+	proxy.AuthForURL = func(string) (string, string) {
+		return "Authorization", "Bearer apk-token"
+	}
+
+	h := NewAPKHandler(proxy, "http://proxy.example", map[string]string{"alpine": upstream.URL})
+
+	for path, want := range files {
+		w := serveAPKRequest(h, "/alpine"+path)
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s: status = %d, want 200: %s", path, w.Code, w.Body.String())
+		}
+		if got := w.Body.Bytes(); string(got) != string(want) {
+			t.Errorf("%s: body altered:\ngot  %q\nwant %q", path, got, want)
+		}
+	}
+	if authHeader != "Bearer apk-token" {
+		t.Errorf("Authorization = %q, want %q", authHeader, "Bearer apk-token")
+	}
+
+	// Upstream goes away: cached indexes must still be served, unchanged.
+	available.Store(false)
+	requestsBefore := upstreamRequests.Load()
+	for path, want := range files {
+		w := serveAPKRequest(h, "/alpine"+path)
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s offline: status = %d, want 200: %s", path, w.Code, w.Body.String())
+		}
+		if got := w.Body.Bytes(); string(got) != string(want) {
+			t.Errorf("%s offline: body altered:\ngot  %q\nwant %q", path, got, want)
+		}
+	}
+	if got := upstreamRequests.Load(); got != requestsBefore {
+		t.Errorf("upstream requests during offline reads = %d, want %d", got, requestsBefore)
+	}
+}
+
+// TestAPKHandler_PackageDownloadCachesPerArch covers package downloads, cache
+// hits, offline reads, and that identically named packages for different
+// architectures are cached separately.
+func TestAPKHandler_PackageDownloadCachesPerArch(t *testing.T) {
+	packages := map[string][]byte{
+		"/v3.22/main/x86_64/busybox-1.37.0-r12.apk":  []byte("x86_64 package bytes"),
+		"/v3.22/main/aarch64/busybox-1.37.0-r12.apk": []byte("aarch64 package bytes"),
+	}
+
+	var available atomic.Bool
+	available.Store(true)
+	var packageRequests atomic.Int32
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !available.Load() {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		data, ok := packages[r.URL.Path]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		packageRequests.Add(1)
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = w.Write(data)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(upstream.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewAPKHandler(proxy, "http://proxy.example", map[string]string{"alpine": upstream.URL})
+
+	for path, want := range packages {
+		w := serveAPKRequest(h, "/alpine"+path)
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s: status = %d, want 200: %s", path, w.Code, w.Body.String())
+		}
+		if got := w.Body.String(); got != string(want) {
+			t.Errorf("%s: body = %q, want %q", path, got, want)
+		}
+	}
+	if got := packageRequests.Load(); got != 2 {
+		t.Fatalf("upstream package requests = %d, want 2 (one per architecture)", got)
+	}
+
+	// Second round must be served from cache, even with the upstream down.
+	available.Store(false)
+	for path, want := range packages {
+		w := serveAPKRequest(h, "/alpine"+path)
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s cached: status = %d, want 200: %s", path, w.Code, w.Body.String())
+		}
+		if got := w.Body.String(); got != string(want) {
+			t.Errorf("%s cached: body = %q, want %q", path, got, want)
+		}
+	}
+	if got := packageRequests.Load(); got != 2 {
+		t.Errorf("upstream package requests after cache hits = %d, want 2", got)
+	}
+}
+
+func TestAPKHandler_PackageDownloadSendsUpstreamAuth(t *testing.T) {
+	var authHeader string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		authHeader = r.Header.Get("Authorization")
+		if authHeader != "Bearer apk-token" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		_, _ = fmt.Fprint(w, "private package")
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	client := upstream.Client()
+	client.Transport = &authRoundTripper{base: client.Transport, header: "Authorization", value: "Bearer apk-token"}
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(client), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewAPKHandler(proxy, "http://proxy.example", map[string]string{"private": upstream.URL})
+
+	w := serveAPKRequest(h, "/private/v3.22/main/x86_64/busybox-1.37.0-r12.apk")
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if w.Body.String() != "private package" {
+		t.Errorf("body = %q, want %q", w.Body.String(), "private package")
+	}
+	if authHeader != "Bearer apk-token" {
+		t.Errorf("Authorization = %q, want %q", authHeader, "Bearer apk-token")
+	}
+}
+
+func TestAPKHandler_UnparseablePackageProxiedDirectly(t *testing.T) {
+	var requested string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requested = r.URL.Path
+		_, _ = fmt.Fprint(w, "raw bytes")
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+
+	h := NewAPKHandler(proxy, "http://proxy.example", map[string]string{"alpine": upstream.URL})
+
+	w := serveAPKRequest(h, "/alpine/v3.22/main/x86_64/no-version.apk")
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if requested != "/v3.22/main/x86_64/no-version.apk" {
+		t.Errorf("upstream path = %q, want %q", requested, "/v3.22/main/x86_64/no-version.apk")
+	}
+	if w.Body.String() != "raw bytes" {
+		t.Errorf("body = %q, want %q", w.Body.String(), "raw bytes")
+	}
+}
+
+// authRoundTripper adds a static auth header, mimicking the server's
+// authentication-aware upstream transport.
+type authRoundTripper struct {
+	base   http.RoundTripper
+	header string
+	value  string
+}
+
+func (a *authRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
+	req = req.Clone(req.Context())
+	req.Header.Set(a.header, a.value)
+	base := a.base
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	return base.RoundTrip(req)
+}
+
+// TestAPKHandler_PackageHeadOmitsBody verifies that HEAD requests for cached
+// packages return headers (including Content-Length) without a body.
+func TestAPKHandler_PackageHeadOmitsBody(t *testing.T) {
+	pkg := []byte("package bytes")
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = w.Write(pkg)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(upstream.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewAPKHandler(proxy, "http://proxy.example", map[string]string{"alpine": upstream.URL})
+
+	target := "/alpine/v3.22/main/x86_64/busybox-1.37.0-r12.apk"
+	if w := serveAPKRequest(h, target); w.Code != http.StatusOK {
+		t.Fatalf("seeding GET: status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodHead, target, nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("HEAD: status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.Len(); got != 0 {
+		t.Errorf("HEAD body length = %d, want 0", got)
+	}
+	if got := w.Header().Get("Content-Length"); got != fmt.Sprint(len(pkg)) {
+		t.Errorf("HEAD Content-Length = %q, want %d", got, len(pkg))
+	}
+}
+
+func serveAPKRequest(h *APKHandler, target string) *httptest.ResponseRecorder {
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodGet, target, nil))
+	return w
+}

internal/handler/cargo.go

@@ -80,7 +80,7 @@ func (h *CargoHandler) handleConfig(w http.ResponseWriter, r *http.Request) {
 		DL: h.proxyURL + "/cargo/crates/{crate}/{version}/download",
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	_ = json.NewEncoder(w).Encode(config)
 }
 
@@ -112,7 +112,7 @@ func (h *CargoHandler) handleIndex(w http.ResponseWriter, r *http.Request) {
 		contentType = "text/plain; charset=utf-8"
 	}
 
-	w.Header().Set("Content-Type", contentType)
+	w.Header().Set(headerContentType, contentType)
 	w.WriteHeader(http.StatusOK)
 	h.applyCooldownFiltering(w, body)
 }

internal/handler/coalesce_semantics_test.go

@@ -0,0 +1,615 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/artifacts"
+	"github.com/git-pkgs/registries/fetch"
+)
+
+// runConcurrent runs fn in n goroutines released together and returns their errors.
+func runConcurrent(n int, fn func(i int) error) []error {
+	errs := make([]error, n)
+	start := make(chan struct{})
+	var wg sync.WaitGroup
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			<-start
+			errs[i] = fn(i)
+		}(i)
+	}
+	close(start)
+	wg.Wait()
+	return errs
+}
+
+// artifactBody builds a one-shot upstream artifact carrying the given bytes.
+func artifactBody(content string) *fetch.Artifact {
+	return &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader(content)),
+		ContentType: "application/gzip",
+	}
+}
+
+// drain consumes and closes a CacheResult reader, if there is one.
+func drain(res *CacheResult) {
+	if res != nil && res.Reader != nil {
+		_, _ = io.Copy(io.Discard, res.Reader)
+		_ = res.Reader.Close()
+	}
+}
+
+// TestCoalesceKey_DifferentUpstreamHashDoesNotShare is the safety property that
+// makes coalescing sound: callers expecting different bytes must never share a
+// fetch, so a re-published version cannot serve stale bytes to a caller that
+// asked for the new digest.
+func TestCoalesceKey_DifferentUpstreamHashDoesNotShare(t *testing.T) {
+	const content = "artifact bytes"
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: content, delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	// The digest must carry the "sha256:" prefix; without it the API treats the
+	// value as unverifiable and clears the hash, which would legitimately let
+	// the two callers share one fetch.
+	hashes := []string{
+		"sha256:" + sha256Hex(content),
+		"sha256:" + sha256Hex("something else entirely"),
+	}
+
+	_ = runConcurrent(2, func(i int) error {
+		res, err := proxy.GetOrFetchArtifactFromURLWithDigest(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz",
+			"https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz", hashes[i])
+		drain(res)
+		return err
+	})
+
+	if got := fetcher.calls.Load(); got != 2 {
+		t.Errorf("upstream fetches = %d, want 2: callers expecting different digests must not share a fetch", got)
+	}
+}
+
+// TestCoalesceKey_HashCasingSharesOneFetch is the other half of that property.
+// artifactHashMatches compares digests case-insensitively, so one digest in two
+// casings describes one artifact and must not split into two fetches.
+func TestCoalesceKey_HashCasingSharesOneFetch(t *testing.T) {
+	const content = "artifact bytes"
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: content, delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	hex := sha256Hex(content)
+	digests := []string{"sha256:" + hex, "sha256:" + strings.ToUpper(hex)}
+
+	for i, err := range runConcurrent(2, func(i int) error {
+		res, err := proxy.GetOrFetchArtifactFromURLWithDigest(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz",
+			"https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz", digests[i])
+		drain(res)
+		return err
+	}) {
+		if err != nil {
+			t.Fatalf("caller %d failed: %v", i, err)
+		}
+	}
+
+	if got := fetcher.calls.Load(); got != 1 {
+		t.Errorf("upstream fetches = %d, want 1: one digest in two casings is one artifact", got)
+	}
+}
+
+// TestCoalesceKey_DifferentDownloadURLDoesNotShare covers the other half of the
+// key: same package, different upstream URL, must not collapse into one fetch.
+func TestCoalesceKey_DifferentDownloadURLDoesNotShare(t *testing.T) {
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: "artifact bytes", delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	urls := []string{
+		"https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz",
+		"https://mirror.example.com/pkg/-/pkg-1.0.0.tgz",
+	}
+
+	_ = runConcurrent(2, func(i int) error {
+		res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", urls[i])
+		drain(res)
+		return err
+	})
+
+	if got := fetcher.calls.Load(); got != 2 {
+		t.Errorf("upstream fetches = %d, want 2: different upstream URLs must not share a fetch", got)
+	}
+}
+
+// TestCoalesceKey_DistinctArtifactsDoNotSerialize guards against an over-broad
+// key: four packages fetched at once must still produce four fetches.
+func TestCoalesceKey_DistinctArtifactsDoNotSerialize(t *testing.T) {
+	const n = 4
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: "artifact bytes", delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	names := []string{"alpha", "beta", "gamma", "delta"}
+	errs := runConcurrent(n, func(i int) error {
+		res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+			"npm", names[i], "1.0.0", names[i]+"-1.0.0.tgz",
+			"https://registry.npmjs.org/"+names[i]+"/-/"+names[i]+"-1.0.0.tgz")
+		drain(res)
+		return err
+	})
+	for i, err := range errs {
+		if err != nil {
+			t.Errorf("caller %d (%s): %v", i, names[i], err)
+		}
+	}
+	if got := fetcher.calls.Load(); got != n {
+		t.Errorf("upstream fetches = %d, want %d: distinct artifacts must not share a fetch", got, n)
+	}
+}
+
+// TestCoalesce_FailedFetchReachesEveryCallerAndIsRetriable verifies both claims
+// in coalesceFetch's doc comment: a failed fetch reaches every caller sharing
+// it, and the key is released so a later request retries.
+func TestCoalesce_FailedFetchReachesEveryCallerAndIsRetriable(t *testing.T) {
+	const callers = 8
+	proxy, _, _, fetcher := setupTestProxy(t)
+	boom := errors.New("upstream unavailable")
+	fetcher.fetchErr = boom
+
+	errs := runConcurrent(callers, func(int) error {
+		res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz",
+			"https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz")
+		drain(res)
+		return err
+	})
+	for i, err := range errs {
+		if err == nil {
+			t.Errorf("caller %d: got nil error, want the shared fetch's failure", i)
+		} else if !errors.Is(err, boom) {
+			t.Errorf("caller %d: got %v, want it to wrap %v", i, err, boom)
+		}
+	}
+
+	// The key must be released: a later request retries rather than inheriting
+	// the failure.
+	fetcher.fetchErr = nil
+	fetcher.artifact = artifactBody("recovered bytes")
+	res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+		"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz",
+		"https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("retry after failed coalesced fetch: %v", err)
+	}
+	body, _ := io.ReadAll(res.Reader)
+	_ = res.Reader.Close()
+	if string(body) != "recovered bytes" {
+		t.Errorf("retry body = %q, want %q", body, "recovered bytes")
+	}
+}
+
+// TestCoalesce_ResolverPath covers the other entry point: GetOrFetchArtifact
+// resolves the URL itself, so it is keyed without one.
+func TestCoalesce_ResolverPath(t *testing.T) {
+	const callers = 8
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: "resolved artifact bytes", delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	errs := runConcurrent(callers, func(int) error {
+		res, err := proxy.GetOrFetchArtifact(context.Background(),
+			"npm", "left-pad", "1.3.0", "left-pad-1.3.0.tgz")
+		drain(res)
+		return err
+	})
+	for i, err := range errs {
+		if err != nil {
+			t.Errorf("caller %d: %v", i, err)
+		}
+	}
+	if got := fetcher.calls.Load(); got != 1 {
+		t.Errorf("upstream fetches = %d, want 1", got)
+	}
+}
+
+// TestCoalesce_ResolverPathEmptyFilename exercises that path when the filename
+// is left to be resolved, which the key cannot know up front.
+func TestCoalesce_ResolverPathEmptyFilename(t *testing.T) {
+	const callers = 8
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: "resolved artifact bytes", delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	errs := runConcurrent(callers, func(int) error {
+		res, err := proxy.GetOrFetchArtifact(context.Background(), "npm", "left-pad", "1.3.0", "")
+		drain(res)
+		return err
+	})
+	for i, err := range errs {
+		if err != nil {
+			t.Errorf("caller %d: %v", i, err)
+		}
+	}
+	if got := fetcher.calls.Load(); got != 1 {
+		t.Errorf("upstream fetches = %d, want 1", got)
+	}
+}
+
+// TestCoalesce_SubsequentRequestIsACacheHit confirms the coalesced fetch was
+// committed and is visible later, not just streamed to the waiting callers.
+func TestCoalesce_SubsequentRequestIsACacheHit(t *testing.T) {
+	const callers = 8
+	const url = "https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz"
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: "artifact bytes", delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	_ = runConcurrent(callers, func(int) error {
+		res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", url)
+		drain(res)
+		return err
+	})
+
+	res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+		"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", url)
+	if err != nil {
+		t.Fatalf("follow-up request: %v", err)
+	}
+	defer func() { _ = res.Reader.Close() }()
+	if !res.Cached {
+		t.Error("follow-up request should be served from cache")
+	}
+	if got := fetcher.calls.Load(); got != 1 {
+		t.Errorf("upstream fetches = %d, want 1 after a follow-up cache hit", got)
+	}
+}
+
+// TestCoalesce_ReadersAreIndependent guards openStoredArtifact: callers sharing
+// a fetch each need their own reader, or one closing early breaks the rest.
+func TestCoalesce_ReadersAreIndependent(t *testing.T) {
+	const callers = 8
+	const content = "artifact bytes that every caller must receive intact"
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: content, delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	results := make([]*CacheResult, callers)
+	errs := runConcurrent(callers, func(i int) error {
+		res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz",
+			"https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz")
+		results[i] = res
+		return err
+	})
+	for i, err := range errs {
+		if err != nil {
+			t.Fatalf("caller %d: %v", i, err)
+		}
+	}
+
+	// Close the first caller's reader before anyone else has read a byte.
+	_ = results[0].Reader.Close()
+
+	for i := 1; i < callers; i++ {
+		body, err := io.ReadAll(results[i].Reader)
+		_ = results[i].Reader.Close()
+		if err != nil {
+			t.Errorf("caller %d read after another caller closed: %v", i, err)
+			continue
+		}
+		if string(body) != content {
+			t.Errorf("caller %d got %q, want %q", i, body, content)
+		}
+	}
+}
+
+// TestCoalesce_CanceledWaiterDoesNotWaitForTheSharedFetch checks that joining a
+// coalesced fetch does not cost a caller its own cancellation. Without the
+// leader/waiter split a waiter is pinned until the shared fetch resolves,
+// bounded only by the artifact client timeout, so clients that have already
+// gone away keep handler goroutines alive for minutes.
+func TestCoalesce_CanceledWaiterDoesNotWaitForTheSharedFetch(t *testing.T) {
+	const leaderFetch = 2 * time.Second
+	const url = "https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz"
+
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: "artifact bytes", delay: leaderFetch, entered: make(chan struct{})}
+	proxy.Fetcher = fetcher
+
+	leaderDone := make(chan error, 1)
+	go func() {
+		res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", url)
+		drain(res)
+		leaderDone <- err
+	}()
+
+	select {
+	case <-fetcher.entered: // the leader holds the key and is inside its fetch
+	case <-time.After(5 * time.Second):
+		t.Fatal("leader never started its fetch")
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	start := time.Now()
+	_, err := proxy.GetOrFetchArtifactFromURL(ctx, "npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", url)
+	blocked := time.Since(start)
+
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("waiter error = %v, want context.Canceled", err)
+	}
+	if blocked > leaderFetch/4 {
+		t.Errorf("canceled waiter blocked %v, want well under %v: it is pinned to the shared fetch",
+			blocked, leaderFetch/4)
+	}
+
+	// A waiter leaving must not disturb the fetch the others share.
+	if err := <-leaderDone; err != nil {
+		t.Fatalf("leader failed after a waiter canceled: %v", err)
+	}
+	res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+		"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", url)
+	if err != nil {
+		t.Fatalf("follow-up after leader completed: %v", err)
+	}
+	defer func() { _ = res.Reader.Close() }()
+	if !res.Cached {
+		t.Error("leader's fetch should have been committed to the cache")
+	}
+	if got := fetcher.calls.Load(); got != 1 {
+		t.Errorf("upstream fetches = %d, want 1", got)
+	}
+}
+
+// inFlightLen reports how many coalesced fetches are currently registered.
+func inFlightLen(p *Proxy) int {
+	p.fetchMu.Lock()
+	defer p.fetchMu.Unlock()
+	return len(p.inFlight)
+}
+
+// TestCoalesce_KeyIsReleasedAfterFetch guards the bug this hand-rolled map can
+// have that singleflight could not: a key left behind means later callers join
+// a finished entry, see its closed done channel, and are served that stale
+// result forever, while the map grows without bound.
+func TestCoalesce_KeyIsReleasedAfterFetch(t *testing.T) {
+	const url = "https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz"
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: "artifact bytes", delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	_ = runConcurrent(8, func(int) error {
+		res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+			"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", url)
+		drain(res)
+		return err
+	})
+	if n := inFlightLen(proxy); n != 0 {
+		t.Errorf("in-flight entries after a successful fetch = %d, want 0", n)
+	}
+
+	// A fresh miss for the same key must start a new fetch, not rejoin the old
+	// entry. Clearing the cache record forces the miss path again.
+	if err := proxy.ClearCachedArtifact(context.Background(), "npm", "pkg", "1.0.0", "pkg-1.0.0.tgz"); err != nil {
+		t.Fatalf("clear cached artifact: %v", err)
+	}
+	res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+		"npm", "pkg", "1.0.0", "pkg-1.0.0.tgz", url)
+	if err != nil {
+		t.Fatalf("second miss for the same key: %v", err)
+	}
+	drain(res)
+	if got := fetcher.calls.Load(); got != 2 {
+		t.Errorf("upstream fetches = %d, want 2: the second miss must not reuse the finished entry", got)
+	}
+	if n := inFlightLen(proxy); n != 0 {
+		t.Errorf("in-flight entries at end = %d, want 0", n)
+	}
+}
+
+// missingFromCache is a recheck that always reports a miss, so the shared fetch
+// runs.
+func missingFromCache() (artifacts.Artifact, string, bool) {
+	return artifacts.Artifact{}, "", false
+}
+
+// TestCoalesce_LeaderRechecksCacheBeforeFetching covers the window between a
+// caller's own cache lookup and it becoming the leader: a concurrent fetch can
+// commit the artifact in that gap, and the leader must serve that rather than
+// fetch it a second time.
+func TestCoalesce_LeaderRechecksCacheBeforeFetching(t *testing.T) {
+	const content = "artifact bytes"
+	proxy, _, store, _ := setupTestProxy(t)
+
+	const storagePath = "npm/pkg/1.0.0/pkg-1.0.0.tgz"
+	if _, _, err := store.Store(context.Background(), storagePath, strings.NewReader(content)); err != nil {
+		t.Fatalf("seeding storage: %v", err)
+	}
+	committed := artifacts.Artifact{
+		PURL:     "pkg:npm/pkg@1.0.0",
+		Filename: "pkg-1.0.0.tgz",
+		Size:     int64(len(content)),
+	}
+
+	res, err := proxy.coalesceFetch(context.Background(), "any-key",
+		func() (artifacts.Artifact, string, bool) { return committed, storagePath, true },
+		func(context.Context) (artifacts.Artifact, string, error) {
+			t.Error("fetched an artifact that was already in the cache")
+			return artifacts.Artifact{}, "", errors.New("commit must not run")
+		})
+	if err != nil {
+		t.Fatalf("coalesceFetch failed: %v", err)
+	}
+	defer drain(res)
+	got, err := io.ReadAll(res.Reader)
+	if err != nil {
+		t.Fatalf("reading result: %v", err)
+	}
+	if string(got) != content {
+		t.Errorf("got %q, want %q", got, content)
+	}
+	if n := inFlightLen(proxy); n != 0 {
+		t.Errorf("in-flight entries = %d, want 0", n)
+	}
+}
+
+// TestCachedArtifactRecord covers the recheck itself: it must report the row a
+// concurrent fetch committed, match its digest the way artifactHashMatches
+// does, and report a miss for anything else.
+func TestCachedArtifactRecord(t *testing.T) {
+	const (
+		content     = "artifact bytes"
+		pkgPURL     = "pkg:npm/pkg"
+		versionPURL = "pkg:npm/pkg@1.0.0"
+		filename    = "pkg-1.0.0.tgz"
+		storagePath = "npm/pkg/1.0.0/pkg-1.0.0.tgz"
+	)
+	proxy, _, _, _ := setupTestProxy(t)
+
+	hex := sha256Hex(content)
+	committed := testArtifact(content, versionPURL, filename, "application/gzip")
+	if err := proxy.updateCacheDB("npm", "pkg", pkgPURL,
+		"https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz", storagePath, committed); err != nil {
+		t.Fatalf("seeding cache record: %v", err)
+	}
+
+	for _, tc := range []struct {
+		name, filename, hash string
+		want                 bool
+	}{
+		{"no upstream hash", filename, "", true},
+		{"matching hash", filename, hex, true},
+		{"matching hash in upper case", filename, strings.ToUpper(hex), true},
+		{"different hash", filename, sha256Hex("something else entirely"), false},
+		{"unknown filename", "pkg-1.0.0.zip", hex, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got, path, ok := proxy.cachedArtifactRecord(pkgPURL, versionPURL, tc.filename, tc.hash)
+			if ok != tc.want {
+				t.Fatalf("ok = %v, want %v", ok, tc.want)
+			}
+			if !ok {
+				return
+			}
+			if path != storagePath {
+				t.Errorf("storage path = %q, want %q", path, storagePath)
+			}
+			if got.Digest.Encoded() != hex {
+				t.Errorf("digest = %q, want %q", got.Digest.Encoded(), hex)
+			}
+		})
+	}
+}
+
+// TestCoalesce_LeaderFetchesWhenRecheckedBytesAreGone covers the other branch
+// of the recheck: a record whose bytes no longer open is not served, and the
+// shared fetch runs instead, the same recovery the cache lookup makes.
+func TestCoalesce_LeaderFetchesWhenRecheckedBytesAreGone(t *testing.T) {
+	const content = "fetched bytes"
+	const storagePath = "npm/pkg/1.0.0/pkg-1.0.0.tgz"
+	proxy, _, store, _ := setupTestProxy(t)
+
+	stale := artifacts.Artifact{PURL: "pkg:npm/pkg@1.0.0", Filename: "pkg-1.0.0.tgz"}
+	if _, err := store.Open(context.Background(), storagePath); err == nil {
+		t.Fatal("stale bytes were present, so the test proves nothing")
+	}
+
+	// The leader runs commit on its own goroutine, so a plain counter is safe.
+	fetches := 0
+	res, err := proxy.coalesceFetch(context.Background(), "any-key",
+		func() (artifacts.Artifact, string, bool) { return stale, storagePath, true },
+		func(ctx context.Context) (artifacts.Artifact, string, error) {
+			fetches++
+			if _, _, err := store.Store(ctx, storagePath, strings.NewReader(content)); err != nil {
+				return artifacts.Artifact{}, "", err
+			}
+			return testArtifact(content, stale.PURL, stale.Filename, "application/gzip"), storagePath, nil
+		})
+	if err != nil {
+		t.Fatalf("coalesceFetch failed: %v", err)
+	}
+	defer drain(res)
+	if fetches != 1 {
+		t.Errorf("shared fetches = %d, want 1: a record without bytes must be refetched", fetches)
+	}
+	got, err := io.ReadAll(res.Reader)
+	if err != nil {
+		t.Fatalf("reading result: %v", err)
+	}
+	if string(got) != content {
+		t.Errorf("got %q, want %q", got, content)
+	}
+	if n := inFlightLen(proxy); n != 0 {
+		t.Errorf("in-flight entries = %d, want 0", n)
+	}
+}
+
+// TestCoalesce_PanicInSharedFetchDoesNotStrandWaiters checks the failure mode
+// that matters most: a caller parked on a shared fetch must never be left
+// blocked forever when that fetch dies.
+//
+// This drives coalesceFetch directly and holds the shared entry itself, because
+// whether a second caller has reached the wait is not observable from outside:
+// it runs a cache lookup against the database first, so releasing the leader on
+// a timer races that query. Losing the race made a second caller the leader
+// instead of a waiter, and its panic was unrecovered, killing the test binary
+// rather than failing the test.
+func TestCoalesce_PanicInSharedFetchDoesNotStrandWaiters(t *testing.T) {
+	proxy, _, _, _ := setupTestProxy(t)
+	const key = "pkg:npm/pkg@1.0.0\x00pkg-1.0.0.tgz"
+
+	inCommit := make(chan struct{})
+	release := make(chan struct{})
+	leaderPanicked := make(chan struct{})
+
+	go func() {
+		defer func() {
+			_ = recover() // the panic surfaces in the leader, as it would in a handler
+			close(leaderPanicked)
+		}()
+		_, _ = proxy.coalesceFetch(context.Background(), key, missingFromCache,
+			func(context.Context) (artifacts.Artifact, string, error) {
+				close(inCommit)
+				<-release
+				panic("upstream fetch exploded")
+			})
+	}()
+
+	<-inCommit // the leader holds the key and is inside the fetch
+
+	// Take the entry a waiter would park on, while the leader is still held.
+	proxy.fetchMu.Lock()
+	shared := proxy.inFlight[key]
+	proxy.fetchMu.Unlock()
+	if shared == nil {
+		t.Fatal("no in-flight entry registered for a running fetch")
+	}
+
+	close(release)
+
+	select {
+	case <-shared.done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("waiter stranded: a panicking shared fetch never released its waiters")
+	}
+	if !errors.Is(shared.err, errSharedFetchAbandoned) {
+		t.Errorf("waiter error = %v, want errSharedFetchAbandoned", shared.err)
+	}
+
+	<-leaderPanicked
+	if n := inFlightLen(proxy); n != 0 {
+		t.Errorf("in-flight entries after a panic = %d, want 0", n)
+	}
+}

internal/handler/coalesce_test.go

@@ -0,0 +1,185 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"log/slog"
+	"net/http"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/proxy/internal/database"
+	"github.com/git-pkgs/proxy/internal/storage"
+	"github.com/git-pkgs/registries/fetch"
+)
+
+// fetchHoldTime holds each stub fetch open long enough that concurrent callers
+// reliably overlap inside it. The exact value is not significant.
+const fetchHoldTime = 50 * time.Millisecond
+
+// countingFetcher counts upstream fetches and holds each one open.
+type countingFetcher struct {
+	calls   atomic.Int64
+	content string
+	delay   time.Duration
+
+	// entered, if set, is closed when the first fetch begins. A test can wait
+	// on it to know the leader holds the key, rather than guessing with a
+	// sleep.
+	entered   chan struct{}
+	enterOnce sync.Once
+}
+
+func (f *countingFetcher) Fetch(ctx context.Context, url string) (*fetch.Artifact, error) {
+	return f.FetchWithHeaders(ctx, url, nil)
+}
+
+func (f *countingFetcher) FetchWithHeaders(_ context.Context, _ string, _ http.Header) (*fetch.Artifact, error) {
+	f.calls.Add(1)
+	if f.entered != nil {
+		f.enterOnce.Do(func() { close(f.entered) })
+	}
+	time.Sleep(f.delay)
+	return &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader(f.content)),
+		ContentType: "application/gzip",
+	}, nil
+}
+
+func (f *countingFetcher) Head(context.Context, string) (int64, string, error) {
+	return 0, "", nil
+}
+
+// TestGetOrFetchArtifactFromURL_ConcurrentMissesCoalesce asserts that N
+// simultaneous misses for one artifact produce a single upstream fetch. That is
+// the CI shape: parallel jobs installing overlapping dependencies cold.
+func TestGetOrFetchArtifactFromURL_ConcurrentMissesCoalesce(t *testing.T) {
+	const goroutines = 8
+	const content = "left-pad tarball bytes"
+
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := &countingFetcher{content: content, delay: fetchHoldTime}
+	proxy.Fetcher = fetcher
+
+	start := make(chan struct{})
+	var wg sync.WaitGroup
+	errs := make([]error, goroutines)
+	bodies := make([]string, goroutines)
+
+	for i := 0; i < goroutines; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			<-start
+			res, err := proxy.GetOrFetchArtifactFromURL(context.Background(),
+				"npm", "left-pad", "1.3.0", "left-pad-1.3.0.tgz",
+				"https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz")
+			if err != nil {
+				errs[i] = err
+				return
+			}
+			defer func() { _ = res.Reader.Close() }()
+			b, err := io.ReadAll(res.Reader)
+			errs[i] = err
+			bodies[i] = string(b)
+		}(i)
+	}
+
+	close(start)
+	wg.Wait()
+
+	for i, err := range errs {
+		if err != nil {
+			t.Errorf("goroutine %d: unexpected error: %v", i, err)
+		}
+	}
+	// Every caller must get its own intact copy of the bytes.
+	for i, b := range bodies {
+		if b != content {
+			t.Errorf("goroutine %d: body = %q, want %q", i, b, content)
+		}
+	}
+	if got := fetcher.calls.Load(); got != 1 {
+		t.Errorf("upstream fetches = %d, want 1 (%d concurrent callers stampeded the upstream)", got, goroutines)
+	}
+}
+
+// TestGetOrFetchArtifactFromURL_ConcurrentMissesFileStorage runs the same
+// scenario against the real file:// backend, the default in production.
+//
+// Uncoalesced this fails outright, not merely wastefully. Every caller stores
+// to one key, and fileblob rewrites a ".attrs" sidecar per key with os.Create,
+// truncating in place outside the rename that protects the blob. Decoding that
+// sidecar mid-truncate gives "opening reader: EOF", served as a 502.
+//
+// Only the fetcher is stubbed, because the real one refuses loopback so an
+// httptest upstream is unreachable. The storage, where this fails, is real.
+func TestGetOrFetchArtifactFromURL_ConcurrentMissesFileStorage(t *testing.T) {
+	const goroutines = 16
+	content := bytes.Repeat([]byte("tarball-bytes-"), 512)
+
+	ctx := context.Background()
+	dir := t.TempDir()
+
+	db, err := database.Create(filepath.Join(dir, "test.db"))
+	if err != nil {
+		t.Fatalf("create database: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+
+	store, err := storage.OpenBucket(ctx, "file://"+filepath.Join(dir, "cache"))
+	if err != nil {
+		t.Fatalf("open storage: %v", err)
+	}
+	t.Cleanup(func() { _ = store.Close() })
+
+	fetcher := &countingFetcher{content: string(content), delay: fetchHoldTime}
+	proxy := NewProxy(db, store, fetcher, fetch.NewResolver(),
+		slog.New(slog.NewTextHandler(io.Discard, nil)))
+
+	start := make(chan struct{})
+	var wg sync.WaitGroup
+	errs := make([]error, goroutines)
+	bodies := make([][]byte, goroutines)
+
+	for i := 0; i < goroutines; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			<-start
+			res, err := proxy.GetOrFetchArtifactFromURL(ctx,
+				"npm", "left-pad", "1.3.0", "left-pad-1.3.0.tgz",
+				"https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz")
+			if err != nil {
+				errs[i] = err
+				return
+			}
+			defer func() { _ = res.Reader.Close() }()
+			body, readErr := io.ReadAll(res.Reader)
+			errs[i] = readErr
+			bodies[i] = body
+		}(i)
+	}
+
+	close(start)
+	wg.Wait()
+
+	for i, err := range errs {
+		if err != nil {
+			t.Errorf("caller %d failed: %v", i, err)
+		}
+	}
+	for i, body := range bodies {
+		if !bytes.Equal(body, content) {
+			t.Errorf("caller %d got %d bytes, want %d", i, len(body), len(content))
+		}
+	}
+	if got := fetcher.calls.Load(); got != 1 {
+		t.Errorf("upstream fetches = %d, want 1", got)
+	}
+}

internal/handler/composer.go

@@ -37,6 +37,15 @@ func NewComposerHandler(proxy *Proxy, proxyURL string) *ComposerHandler {
 	}
 }
 
+// NewComposerHandlerWithUpstreams creates a Composer handler with custom API
+// and repository upstreams.
+func NewComposerHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, repoURL string) *ComposerHandler {
+	h := NewComposerHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, composerUpstream)
+	h.repoURL = configuredUpstreamURL(repoURL, composerRepo)
+	return h
+}
+
 // Routes returns the HTTP handler for Composer requests.
 func (h *ComposerHandler) Routes() http.Handler {
 	mux := http.NewServeMux()
@@ -68,7 +77,7 @@ func (h *ComposerHandler) handleServiceIndex(w http.ResponseWriter, r *http.Requ
 		"providers-lazy-url": h.proxyURL + "/composer/p2/%package%.json",
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	_ = json.NewEncoder(w).Encode(index)
 }
 
@@ -104,12 +113,12 @@ func (h *ComposerHandler) handlePackageMetadata(w http.ResponseWriter, r *http.R
 	rewritten, err := h.rewriteMetadata(body)
 	if err != nil {
 		h.proxy.Logger.Warn("failed to rewrite metadata, proxying original", "error", err)
-		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set(headerContentType, "application/json")
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	_, _ = w.Write(rewritten)
 }
 

internal/handler/conan.go

@@ -27,6 +27,13 @@ func NewConanHandler(proxy *Proxy, proxyURL string) *ConanHandler {
 	}
 }
 
+// NewConanHandlerWithUpstream creates a Conan handler with a custom upstream.
+func NewConanHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *ConanHandler {
+	h := NewConanHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, conanUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for Conan requests.
 func (h *ConanHandler) Routes() http.Handler {
 	mux := http.NewServeMux()

internal/handler/conda.go

@@ -29,6 +29,13 @@ func NewCondaHandler(proxy *Proxy, proxyURL string) *CondaHandler {
 	}
 }
 
+// NewCondaHandlerWithUpstream creates a Conda handler with a custom upstream.
+func NewCondaHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *CondaHandler {
+	h := NewCondaHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, condaUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for Conda requests.
 func (h *CondaHandler) Routes() http.Handler {
 	mux := http.NewServeMux()
@@ -167,12 +174,12 @@ func (h *CondaHandler) handleRepodata(w http.ResponseWriter, r *http.Request) {
 	filtered, err := h.applyCooldownFiltering(body)
 	if err != nil {
 		h.proxy.Logger.Warn("failed to filter repodata, proxying original", "error", err)
-		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set(headerContentType, "application/json")
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	_, _ = w.Write(filtered)
 }
 

internal/handler/container.go

@@ -4,35 +4,94 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io"
 	"net/http"
 	"regexp"
 	"strings"
 )
 
 const (
-	dockerHubRegistry  = "https://registry-1.docker.io"
-	blobMatchCount     = 3 // full match + name + digest
-	manifestMatchCount = 3 // full match + name + reference
-	tagsListMatchCount = 2 // full match + name
+	dockerHubRegistry     = "https://registry-1.docker.io"
+	blobMatchCount        = 3 // full match + name + digest
+	manifestMatchCount    = 3 // full match + name + reference
+	tagsListMatchCount    = 2 // full match + name
+	registrySelectorParts = 3 // upstream + name + repository
 )
 
 // ContainerHandler handles OCI/Docker container registry protocol requests.
 // It implements the OCI Distribution Spec for pulling images.
 // Reference: https://github.com/opencontainers/distribution-spec/blob/main/spec.md
 type ContainerHandler struct {
-	proxy       *Proxy
-	registryURL string
-	proxyURL    string
+	proxy           *Proxy
+	registryURL     string
+	proxyURL        string
+	namedRegistries map[string]string
+	registries      []containerRegistry
+}
+
+type containerRegistry struct {
+	repositoryPrefix string
+	registryURL      string
 }
 
 // NewContainerHandler creates a new container registry protocol handler.
-func NewContainerHandler(proxy *Proxy, proxyURL string) *ContainerHandler {
-	return &ContainerHandler{
+// Named registries are selected with the repository prefix
+// upstream/{name}/, leaving unprefixed requests compatible with the Docker Hub
+// mirror behavior.
+func NewContainerHandler(proxy *Proxy, proxyURL string, namedRegistries ...map[string]string) *ContainerHandler {
+	h := &ContainerHandler{
 		proxy:       proxy,
 		registryURL: dockerHubRegistry,
 		proxyURL:    strings.TrimSuffix(proxyURL, "/"),
 	}
+	if len(namedRegistries) > 0 {
+		h.namedRegistries = make(map[string]string, len(namedRegistries[0]))
+		for name, registryURL := range namedRegistries[0] {
+			h.namedRegistries[name] = strings.TrimSuffix(registryURL, "/")
+		}
+	}
+	return h
+}
+
+// NewContainerHandlerWithRegistry creates a container handler with a custom
+// default registry and optional named registries.
+func NewContainerHandlerWithRegistry(
+	proxy *Proxy,
+	proxyURL, registryURL string,
+	namedRegistries ...map[string]string,
+) *ContainerHandler {
+	h := NewContainerHandler(proxy, proxyURL, namedRegistries...)
+	h.registryURL = configuredUpstreamURL(registryURL, dockerHubRegistry)
+	return h
+}
+
+// RegisterRegistry routes a repository and its descendants to a specific OCI
+// registry. The longest matching repository prefix wins.
+func (h *ContainerHandler) RegisterRegistry(repositoryPrefix, registryURL string) {
+	h.registries = append(h.registries, containerRegistry{
+		repositoryPrefix: strings.Trim(repositoryPrefix, "/"),
+		registryURL:      strings.TrimSuffix(registryURL, "/"),
+	})
+}
+
+// BlockRegistry prevents a repository and its descendants from falling back to
+// the default OCI registry. A more specific registered repository still wins.
+func (h *ContainerHandler) BlockRegistry(repositoryPrefix string) {
+	h.RegisterRegistry(repositoryPrefix, "")
+}
+
+func (h *ContainerHandler) registryURLFor(name string) string {
+	registryURL := h.registryURL
+	matchLength := 0
+	for _, registry := range h.registries {
+		if name != registry.repositoryPrefix && !strings.HasPrefix(name, registry.repositoryPrefix+"/") {
+			continue
+		}
+		if len(registry.repositoryPrefix) > matchLength {
+			registryURL = registry.registryURL
+			matchLength = len(registry.repositoryPrefix)
+		}
+	}
+	return registryURL
 }
 
 // Routes returns the HTTP handler for container registry requests.
@@ -85,10 +144,16 @@ func (h *ContainerHandler) handleBlobDownload(w http.ResponseWriter, r *http.Req
 		return
 	}
 
-	h.proxy.Logger.Info("container blob request", "name", name, "digest", digest)
+	registryURL, upstreamName, cacheName, ok := h.registryForName(name)
+	if !ok {
+		h.containerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unknown upstream registry")
+		return
+	}
+
+	h.proxy.Logger.Info("container blob request", "name", upstreamName, "digest", digest)
 
 	filename := digest
-	cached, err := h.proxy.GetCachedArtifact(r.Context(), "oci", name, digest, filename)
+	cached, err := h.proxy.GetCachedArtifact(r.Context(), "oci", cacheName, digest, filename)
 	if err != nil {
 		h.proxy.Logger.Error("failed to check blob cache", "error", err)
 		h.containerError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to check blob cache")
@@ -96,25 +161,28 @@ func (h *ContainerHandler) handleBlobDownload(w http.ResponseWriter, r *http.Req
 	}
 	if cached != nil {
 		w.Header().Set("Docker-Content-Digest", digest)
-		w.Header().Set("Content-Type", "application/octet-stream")
+		if cached.Artifact.MediaType == "" {
+			cached.Artifact.MediaType = "application/octet-stream"
+		}
 		serveArtifact(w, r.Method, cached)
 		return
 	}
 
 	// For HEAD requests, just proxy to upstream
 	if r.Method == http.MethodHead {
-		h.proxyBlobHead(w, r, name, digest)
+		h.proxyBlobHead(w, r, registryURL, upstreamName, digest)
 		return
 	}
 
 	// Try to get from cache, or fetch from the authentication-aware upstream client.
-	result, err := h.proxy.GetOrFetchArtifactFromURL(
+	result, err := h.proxy.GetOrFetchArtifactFromURLWithDigest(
 		r.Context(),
 		"oci",
-		name,
+		cacheName,
 		digest, // use digest as version
 		filename,
-		fmt.Sprintf("%s/v2/%s/blobs/%s", h.registryURL, name, digest),
+		fmt.Sprintf("%s/v2/%s/blobs/%s", registryURL, upstreamName, digest),
+		digest,
 	)
 
 	if err != nil {
@@ -122,13 +190,24 @@ func (h *ContainerHandler) handleBlobDownload(w http.ResponseWriter, r *http.Req
 			h.containerError(w, http.StatusNotFound, "BLOB_UNKNOWN", "blob unknown to registry")
 			return
 		}
+		if errors.Is(err, ErrArtifactBlocked) {
+			h.containerError(w, http.StatusForbidden, "DENIED", err.Error())
+			return
+		}
+		if errors.Is(err, ErrArtifactDigestMismatch) {
+			h.proxy.Logger.Error("upstream blob failed digest verification", "error", err)
+			h.containerError(w, http.StatusBadGateway, "DIGEST_INVALID", "blob digest verification failed")
+			return
+		}
 		h.proxy.Logger.Error("failed to fetch blob", "error", err)
 		h.containerError(w, http.StatusBadGateway, "INTERNAL_ERROR", "failed to fetch blob")
 		return
 	}
 
 	w.Header().Set("Docker-Content-Digest", digest)
-	w.Header().Set("Content-Type", "application/octet-stream")
+	if result.Artifact.MediaType == "" {
+		result.Artifact.MediaType = "application/octet-stream"
+	}
 	ServeArtifact(w, result)
 }
 
@@ -146,11 +225,17 @@ func (h *ContainerHandler) handleManifest(w http.ResponseWriter, r *http.Request
 		return
 	}
 
-	h.proxy.Logger.Info("container manifest request", "name", name, "reference", reference)
-	h.serveManifest(w, r, name, reference)
+	registryURL, upstreamName, _, ok := h.registryForName(name)
+	if !ok {
+		h.containerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unknown upstream registry")
+		return
+	}
+
+	h.proxy.Logger.Info("container manifest request", "name", upstreamName, "reference", reference)
+	h.serveManifest(w, r, registryURL, upstreamName, reference)
 }
 
-// handleTagsList proxies tag list requests to upstream.
+// handleTagsList caches tag list responses for offline OCI pulls.
 func (h *ContainerHandler) handleTagsList(w http.ResponseWriter, r *http.Request, path string) {
 	if r.Method != http.MethodGet {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
@@ -163,32 +248,18 @@ func (h *ContainerHandler) handleTagsList(w http.ResponseWriter, r *http.Request
 		return
 	}
 
-	upstreamURL := fmt.Sprintf("%s/v2/%s/tags/list", h.registryURL, name)
-	if r.URL.RawQuery != "" {
-		upstreamURL += "?" + r.URL.RawQuery
-	}
-
-	req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, upstreamURL, nil)
-	if err != nil {
-		h.containerError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to create request")
+	registryURL, upstreamName, _, ok := h.registryForName(name)
+	if !ok {
+		h.containerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unknown upstream registry")
 		return
 	}
 
-	resp, err := h.proxy.HTTPClient.Do(req)
-	if err != nil {
-		h.containerError(w, http.StatusBadGateway, "INTERNAL_ERROR", "failed to fetch from upstream")
-		return
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(resp.StatusCode)
-	_, _ = io.Copy(w, resp.Body)
+	h.serveTagsList(w, r, registryURL, upstreamName)
 }
 
 // proxyBlobHead handles HEAD requests for blobs.
-func (h *ContainerHandler) proxyBlobHead(w http.ResponseWriter, r *http.Request, name, digest string) {
-	upstreamURL := fmt.Sprintf("%s/v2/%s/blobs/%s", h.registryURL, name, digest)
+func (h *ContainerHandler) proxyBlobHead(w http.ResponseWriter, r *http.Request, registryURL, name, digest string) {
+	upstreamURL := fmt.Sprintf("%s/v2/%s/blobs/%s", registryURL, name, digest)
 
 	req, err := http.NewRequestWithContext(r.Context(), http.MethodHead, upstreamURL, nil)
 	if err != nil {
@@ -203,18 +274,44 @@ func (h *ContainerHandler) proxyBlobHead(w http.ResponseWriter, r *http.Request,
 	}
 	defer func() { _ = resp.Body.Close() }()
 
-	for _, header := range []string{"Content-Type", "Content-Length", "Docker-Content-Digest"} {
+	for _, header := range []string{headerContentType, headerContentLength, "Docker-Content-Digest", headerETag, headerLastModified} {
 		if v := resp.Header.Get(header); v != "" {
 			w.Header().Set(header, v)
 		}
 	}
+	if resp.StatusCode >= http.StatusOK && resp.StatusCode < http.StatusMultipleChoices && w.Header().Get("Docker-Content-Digest") == "" {
+		w.Header().Set("Docker-Content-Digest", digest)
+	}
 
 	w.WriteHeader(resp.StatusCode)
 }
 
+// registryForName resolves a client-visible OCI repository name to an upstream
+// registry and its repository name. Named upstreams use upstream/{name}/ as a
+// reserved prefix. Other names are matched against registered repository
+// prefixes, falling back to Docker Hub when no prefix matches.
+func (h *ContainerHandler) registryForName(name string) (registryURL, upstreamName, cacheName string, ok bool) {
+	parts := strings.SplitN(name, "/", registrySelectorParts)
+	if len(parts) >= 2 && parts[0] == "upstream" {
+		if len(parts) != registrySelectorParts || parts[2] == "" {
+			return "", "", "", false
+		}
+		registryURL, ok = h.namedRegistries[parts[1]]
+		if !ok || registryURL == "" {
+			return "", "", "", false
+		}
+		return registryURL, parts[2], name, true
+	}
+	registryURL = h.registryURLFor(name)
+	if registryURL == "" {
+		return "", "", "", false
+	}
+	return registryURL, name, name, true
+}
+
 // containerError writes an OCI-compliant error response.
 func (h *ContainerHandler) containerError(w http.ResponseWriter, status int, code, message string) {
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	w.WriteHeader(status)
 	_ = json.NewEncoder(w).Encode(map[string]any{
 		"errors": []map[string]string{

internal/handler/container_manifest.go

@@ -1,25 +1,27 @@
 package handler
 
 import (
-	"bytes"
 	"context"
 	"crypto/sha256"
-	"database/sql"
 	"encoding/hex"
 	"fmt"
 	"io"
+	"mime"
 	"net/http"
 	"regexp"
+	"sort"
 	"strconv"
 	"strings"
 	"time"
-
-	"github.com/git-pkgs/proxy/internal/database"
 )
 
 const (
 	containerManifestCacheEcosystem = "oci-manifest"
 	containerStaleWarning           = `110 - "Response is Stale"`
+
+	containerAcceptWildcardSpecificity = iota
+	containerAcceptTypeWildcardSpecificity
+	containerAcceptExactSpecificity
 )
 
 var manifestDigestReferencePattern = regexp.MustCompile(`^[a-z0-9]+:[a-f0-9]+$`)
@@ -30,25 +32,23 @@ type cachedContainerManifest struct {
 	contentDigest string
 	etag          string
 	size          int64
+	lastModified  time.Time
 	fetchedAt     time.Time
 }
 
-func (h *ContainerHandler) serveManifest(w http.ResponseWriter, r *http.Request, name, reference string) {
+func (h *ContainerHandler) serveManifest(w http.ResponseWriter, r *http.Request, registryURL, name, reference string) {
 	accept := containerManifestAccept(r)
-	cacheKey := h.containerManifestCacheKey(name, reference, accept)
-	cached, err := h.loadContainerManifest(r.Context(), cacheKey)
-	if err != nil {
-		h.proxy.Logger.Warn("failed to read cached container manifest", "error", err)
-		cached = nil
-	}
+	cacheAccept := normalizeContainerManifestAccept(accept)
+	cacheKey := h.containerManifestCacheKey(registryURL, name, reference, cacheAccept)
+	cached := h.loadContainerManifestForAccept(r.Context(), registryURL, name, reference, accept, cacheKey)
 
 	immutable := manifestDigestReferencePattern.MatchString(reference)
 	if cached != nil && (immutable || h.containerManifestFresh(cached)) {
-		writeContainerManifest(w, r.Method, cached, false)
+		writeContainerManifest(w, r, cached, false)
 		return
 	}
 
-	upstreamURL := fmt.Sprintf("%s/v2/%s/manifests/%s", h.registryURL, name, reference)
+	upstreamURL := fmt.Sprintf("%s/v2/%s/manifests/%s", registryURL, name, reference)
 	req, err := http.NewRequestWithContext(r.Context(), r.Method, upstreamURL, nil)
 	if err != nil {
 		h.containerError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to create request")
@@ -68,15 +68,13 @@ func (h *ContainerHandler) serveManifest(w http.ResponseWriter, r *http.Request,
 
 	if resp.StatusCode == http.StatusNotModified && cached != nil {
 		cached.fetchedAt = time.Now()
-		if err := h.storeContainerManifest(r.Context(), cacheKey, cached); err != nil {
-			h.proxy.Logger.Warn("failed to refresh cached container manifest", "error", err)
-		}
-		writeContainerManifest(w, r.Method, cached, false)
+		h.storeContainerManifestForAccept(r.Context(), registryURL, name, reference, accept, cacheAccept, cached)
+		writeContainerManifest(w, r, cached, false)
 		return
 	}
 	if resp.StatusCode != http.StatusOK {
 		if cached != nil && shouldServeStaleManifest(resp.StatusCode) {
-			writeContainerManifest(w, r.Method, cached, true)
+			writeContainerManifest(w, r, cached, true)
 			return
 		}
 		copyContainerManifestHeaders(w.Header(), resp.Header)
@@ -96,33 +94,40 @@ func (h *ContainerHandler) serveManifest(w http.ResponseWriter, r *http.Request,
 		h.serveStaleManifestOrError(w, r, cached, fmt.Errorf("reading manifest: %w", err))
 		return
 	}
-	manifest := &cachedContainerManifest{
-		body:          body,
-		contentType:   resp.Header.Get("Content-Type"),
-		contentDigest: resp.Header.Get("Docker-Content-Digest"),
-		etag:          resp.Header.Get("ETag"),
-		size:          int64(len(body)),
-		fetchedAt:     time.Now(),
-	}
-	if manifest.contentDigest == "" {
-		manifest.contentDigest = sha256Digest(body)
-	}
-	if err := h.storeContainerManifest(r.Context(), cacheKey, manifest); err != nil {
-		h.proxy.Logger.Warn("failed to cache container manifest", "error", err)
-	}
-	if manifest.contentDigest != reference && manifestDigestReferencePattern.MatchString(manifest.contentDigest) {
-		digestKey := h.containerManifestCacheKey(name, manifest.contentDigest, accept)
-		if err := h.storeContainerManifest(r.Context(), digestKey, manifest); err != nil {
-			h.proxy.Logger.Warn("failed to cache container manifest by digest", "error", err)
+	computedDigest := sha256Digest(body)
+	contentDigest := resp.Header.Get("Docker-Content-Digest")
+	for _, expected := range []string{reference, contentDigest} {
+		if strings.HasPrefix(expected, "sha256:") && expected != computedDigest {
+			h.proxy.Logger.Error("upstream manifest failed digest verification",
+				"name", name, "reference", reference, "expected", expected, "actual", computedDigest)
+			h.containerError(w, http.StatusBadGateway, "DIGEST_INVALID", "manifest digest verification failed")
+			return
 		}
 	}
-	writeContainerManifest(w, r.Method, manifest, false)
+	if contentDigest == "" {
+		contentDigest = computedDigest
+	}
+
+	manifest := &cachedContainerManifest{
+		body:          body,
+		contentType:   resp.Header.Get(headerContentType),
+		contentDigest: contentDigest,
+		etag:          resp.Header.Get(headerETag),
+		size:          int64(len(body)),
+		lastModified:  parseHTTPTime(resp.Header.Get(headerLastModified)),
+		fetchedAt:     time.Now(),
+	}
+	h.storeContainerManifestForAccept(r.Context(), registryURL, name, reference, accept, cacheAccept, manifest)
+	if manifest.contentDigest != reference && manifestDigestReferencePattern.MatchString(manifest.contentDigest) {
+		h.storeContainerManifestForAccept(r.Context(), registryURL, name, manifest.contentDigest, accept, cacheAccept, manifest)
+	}
+	writeContainerManifest(w, r, manifest, false)
 }
 
 func (h *ContainerHandler) serveStaleManifestOrError(w http.ResponseWriter, r *http.Request, cached *cachedContainerManifest, err error) {
 	if cached != nil {
 		h.proxy.Logger.Warn("upstream manifest fetch failed, serving stale cache", "error", err)
-		writeContainerManifest(w, r.Method, cached, true)
+		writeContainerManifest(w, r, cached, true)
 		return
 	}
 	h.proxy.Logger.Error("failed to fetch manifest", "error", err)
@@ -133,12 +138,58 @@ func (h *ContainerHandler) containerManifestFresh(manifest *cachedContainerManif
 	return h.proxy.MetadataTTL > 0 && !manifest.fetchedAt.IsZero() && time.Since(manifest.fetchedAt) < h.proxy.MetadataTTL
 }
 
-func (h *ContainerHandler) containerManifestCacheKey(name, reference, accept string) string {
-	identity := strings.Join([]string{h.registryURL, name, reference, accept}, "\x00")
+func (h *ContainerHandler) containerManifestCacheKey(registryURL, name, reference, accept string) string {
+	identity := strings.Join([]string{registryURL, name, reference, accept}, "\x00")
 	sum := sha256.Sum256([]byte(identity))
 	return hex.EncodeToString(sum[:])
 }
 
+func (h *ContainerHandler) loadContainerManifestForAccept(ctx context.Context, registryURL, name, reference, accept, cacheKey string) *cachedContainerManifest {
+	cached, err := h.loadContainerManifest(ctx, cacheKey)
+	if err != nil {
+		h.proxy.Logger.Warn("failed to read cached container manifest", "error", err)
+		return nil
+	}
+	if cached != nil {
+		if containerManifestCacheCompatible(accept, cached) {
+			return cached
+		}
+		return nil
+	}
+
+	legacyCacheKey := h.containerManifestCacheKey(registryURL, name, reference, accept)
+	if legacyCacheKey == cacheKey {
+		return nil
+	}
+	cached, err = h.loadContainerManifest(ctx, legacyCacheKey)
+	if err != nil {
+		h.proxy.Logger.Warn("failed to read legacy cached container manifest", "error", err)
+		return nil
+	}
+	if cached == nil || !containerManifestCacheCompatible(accept, cached) {
+		return nil
+	}
+	if err := h.storeContainerManifest(ctx, cacheKey, cached); err != nil {
+		h.proxy.Logger.Warn("failed to migrate cached container manifest", "error", err)
+	}
+	return cached
+}
+
+func (h *ContainerHandler) storeContainerManifestForAccept(ctx context.Context, registryURL, name, reference, accept, cacheAccept string, manifest *cachedContainerManifest) {
+	cacheKey := h.containerManifestCacheKey(registryURL, name, reference, cacheAccept)
+	if err := h.storeContainerManifest(ctx, cacheKey, manifest); err != nil {
+		h.proxy.Logger.Warn("failed to cache container manifest", "error", err)
+	}
+
+	legacyCacheKey := h.containerManifestCacheKey(registryURL, name, reference, accept)
+	if legacyCacheKey == cacheKey {
+		return
+	}
+	if err := h.storeContainerManifest(ctx, legacyCacheKey, manifest); err != nil {
+		h.proxy.Logger.Warn("failed to cache legacy container manifest", "error", err)
+	}
+}
+
 func (h *ContainerHandler) loadContainerManifest(ctx context.Context, cacheKey string) (*cachedContainerManifest, error) {
 	if h.proxy.DB == nil || h.proxy.Storage == nil {
 		return nil, nil
@@ -172,6 +223,9 @@ func (h *ContainerHandler) loadContainerManifest(ctx context.Context, cacheKey s
 	if entry.Size.Valid {
 		manifest.size = entry.Size.Int64
 	}
+	if entry.LastModified.Valid {
+		manifest.lastModified = entry.LastModified.Time
+	}
 	if entry.FetchedAt.Valid {
 		manifest.fetchedAt = entry.FetchedAt.Time
 	}
@@ -179,43 +233,44 @@ func (h *ContainerHandler) loadContainerManifest(ctx context.Context, cacheKey s
 }
 
 func (h *ContainerHandler) storeContainerManifest(ctx context.Context, cacheKey string, manifest *cachedContainerManifest) error {
-	if h.proxy.DB == nil || h.proxy.Storage == nil {
-		return nil
-	}
-	storagePath := metadataStoragePath(containerManifestCacheEcosystem, cacheKey)
-	size, _, err := h.proxy.Storage.Store(ctx, storagePath, bytes.NewReader(manifest.body))
+	size, err := h.storeContainerMetadata(ctx, containerManifestCacheEcosystem, cacheKey, manifest.body,
+		manifest.etag, "", manifest.contentType, manifest.contentDigest, manifest.lastModified, manifest.fetchedAt)
 	if err != nil {
 		return fmt.Errorf("storing manifest: %w", err)
 	}
 	manifest.size = size
-	return h.proxy.DB.UpsertMetadataCache(&database.MetadataCacheEntry{
-		Ecosystem:     containerManifestCacheEcosystem,
-		Name:          cacheKey,
-		StoragePath:   storagePath,
-		ETag:          sql.NullString{String: manifest.etag, Valid: manifest.etag != ""},
-		ContentType:   sql.NullString{String: manifest.contentType, Valid: manifest.contentType != ""},
-		ContentDigest: sql.NullString{String: manifest.contentDigest, Valid: manifest.contentDigest != ""},
-		Size:          sql.NullInt64{Int64: size, Valid: true},
-		FetchedAt:     sql.NullTime{Time: manifest.fetchedAt, Valid: !manifest.fetchedAt.IsZero()},
-	})
+	return nil
 }
 
-func writeContainerManifest(w http.ResponseWriter, method string, manifest *cachedContainerManifest, stale bool) {
+func writeContainerManifest(w http.ResponseWriter, r *http.Request, manifest *cachedContainerManifest, stale bool) {
 	if manifest.contentType != "" {
-		w.Header().Set("Content-Type", manifest.contentType)
+		w.Header().Set(headerContentType, manifest.contentType)
 	}
-	w.Header().Set("Content-Length", strconv.FormatInt(manifest.size, 10))
+	w.Header().Set(headerContentLength, strconv.FormatInt(manifest.size, 10))
 	if manifest.contentDigest != "" {
 		w.Header().Set("Docker-Content-Digest", manifest.contentDigest)
 	}
 	if manifest.etag != "" {
-		w.Header().Set("ETag", manifest.etag)
+		w.Header().Set(headerETag, manifest.etag)
+	}
+	if !manifest.lastModified.IsZero() {
+		w.Header().Set(headerLastModified, manifest.lastModified.UTC().Format(http.TimeFormat))
 	}
 	if stale {
 		w.Header().Set("Warning", containerStaleWarning)
 	}
+	if ifNoneMatchHits(r.Header.Get("If-None-Match"), manifest.etag) {
+		w.WriteHeader(http.StatusNotModified)
+		return
+	}
+	if !manifest.lastModified.IsZero() {
+		if modifiedSince, err := http.ParseTime(r.Header.Get("If-Modified-Since")); err == nil && !manifest.lastModified.After(modifiedSince) {
+			w.WriteHeader(http.StatusNotModified)
+			return
+		}
+	}
 	w.WriteHeader(http.StatusOK)
-	if method != http.MethodHead {
+	if r.Method != http.MethodHead {
 		_, _ = w.Write(manifest.body)
 	}
 }
@@ -233,14 +288,142 @@ func containerManifestAccept(r *http.Request) string {
 	}, ", ")
 }
 
+func normalizeContainerManifestAccept(accept string) string {
+	mediaTypes := make(map[string]struct{})
+	for _, value := range strings.Split(accept, ",") {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			continue
+		}
+		mediaType, params, err := mime.ParseMediaType(value)
+		if err != nil {
+			mediaTypes[strings.ToLower(value)] = struct{}{}
+			continue
+		}
+		paramKeys := make([]string, 0, len(params))
+		for key := range params {
+			paramKeys = append(paramKeys, key)
+		}
+		sort.Strings(paramKeys)
+		canonical := strings.ToLower(mediaType)
+		for _, key := range paramKeys {
+			value := params[key]
+			if strings.EqualFold(key, "q") {
+				if quality, err := strconv.ParseFloat(value, 64); err == nil {
+					if quality == 1 {
+						continue
+					}
+					value = strconv.FormatFloat(quality, 'g', -1, 64)
+				}
+			}
+			canonical += ";" + strings.ToLower(key) + "=" + value
+		}
+		mediaTypes[canonical] = struct{}{}
+	}
+	canonicalMediaTypes := make([]string, 0, len(mediaTypes))
+	for mediaType := range mediaTypes {
+		canonicalMediaTypes = append(canonicalMediaTypes, mediaType)
+	}
+	sort.Strings(canonicalMediaTypes)
+	return strings.Join(canonicalMediaTypes, ",")
+}
+
+func containerManifestAccepts(accept, contentType string) bool {
+	contentType, contentParams, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		return false
+	}
+	contentType = strings.ToLower(contentType)
+	contentMajor, contentMinor, found := strings.Cut(contentType, "/")
+	if !found {
+		return false
+	}
+
+	bestMediaTypeSpecificity := -1
+	bestParameterSpecificity := 0
+	bestQuality := 0.0
+	for _, value := range strings.Split(accept, ",") {
+		mediaType, params, err := mime.ParseMediaType(strings.TrimSpace(value))
+		if err != nil {
+			continue
+		}
+		mediaType = strings.ToLower(mediaType)
+		major, minor, found := strings.Cut(mediaType, "/")
+		if found && containerAcceptRangeMatches(major, minor, params, contentMajor, contentMinor, contentParams) {
+			mediaTypeSpecificity, parameterSpecificity := containerAcceptSpecificity(major, minor, params)
+			if mediaTypeSpecificity > bestMediaTypeSpecificity ||
+				(mediaTypeSpecificity == bestMediaTypeSpecificity && parameterSpecificity > bestParameterSpecificity) {
+				bestMediaTypeSpecificity = mediaTypeSpecificity
+				bestParameterSpecificity = parameterSpecificity
+				bestQuality = containerAcceptQuality(params)
+			}
+		}
+	}
+	return bestQuality > 0
+}
+
+func containerManifestCacheCompatible(accept string, manifest *cachedContainerManifest) bool {
+	return manifest.contentType == "" || containerManifestAccepts(accept, manifest.contentType)
+}
+
+func containerAcceptRangeMatches(major, minor string, params map[string]string, contentMajor, contentMinor string, contentParams map[string]string) bool {
+	if (major != "*" && major != contentMajor) || (minor != "*" && minor != contentMinor) {
+		return false
+	}
+	for key, value := range params {
+		if strings.EqualFold(key, "q") {
+			continue
+		}
+		if contentParams[key] != value {
+			return false
+		}
+	}
+	return true
+}
+
+func containerAcceptSpecificity(major, minor string, params map[string]string) (int, int) {
+	parameterSpecificity := 0
+	for key := range params {
+		if !strings.EqualFold(key, "q") {
+			parameterSpecificity++
+		}
+	}
+
+	switch {
+	case major == "*" && minor == "*":
+		return containerAcceptWildcardSpecificity, parameterSpecificity
+	case major == "*" || minor == "*":
+		return containerAcceptTypeWildcardSpecificity, parameterSpecificity
+	default:
+		return containerAcceptExactSpecificity, parameterSpecificity
+	}
+}
+
+func containerAcceptQuality(params map[string]string) float64 {
+	value, ok := params["q"]
+	if !ok {
+		return 1
+	}
+	quality, err := strconv.ParseFloat(value, 64)
+	if err != nil || quality < 0 || quality > 1 {
+		return 0
+	}
+	return quality
+}
+
 func copyContainerManifestHeaders(destination, source http.Header) {
-	for _, header := range []string{"Content-Type", "Content-Length", "Docker-Content-Digest", "ETag", "WWW-Authenticate"} {
+	for _, header := range []string{headerContentType, headerContentLength, "Docker-Content-Digest", headerETag, headerLastModified, "WWW-Authenticate"} {
 		if value := source.Get(header); value != "" {
 			destination.Set(header, value)
 		}
 	}
 }
 
+func parseHTTPTime(value string) time.Time {
+	parsed, _ := http.ParseTime(value)
+	return parsed
+}
+
 func shouldServeStaleManifest(status int) bool {
 	return status == http.StatusTooManyRequests || status >= http.StatusInternalServerError
 }

internal/handler/container_metadata.go

@@ -0,0 +1,39 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"fmt"
+	"time"
+
+	"github.com/git-pkgs/proxy/internal/database"
+)
+
+func (h *ContainerHandler) storeContainerMetadata(ctx context.Context, ecosystem, cacheKey string, body []byte, etag, link, contentType, contentDigest string, lastModified, fetchedAt time.Time) (int64, error) {
+	if h.proxy.DB == nil || h.proxy.Storage == nil {
+		return int64(len(body)), nil
+	}
+
+	storagePath := metadataStoragePath(ecosystem, cacheKey)
+	size, _, err := h.proxy.Storage.Store(ctx, storagePath, bytes.NewReader(body))
+	if err != nil {
+		return 0, fmt.Errorf("storing metadata: %w", err)
+	}
+	err = h.proxy.DB.UpsertMetadataCache(&database.MetadataCacheEntry{
+		Ecosystem:     ecosystem,
+		Name:          cacheKey,
+		StoragePath:   storagePath,
+		ETag:          sql.NullString{String: etag, Valid: etag != ""},
+		Link:          sql.NullString{String: link, Valid: link != ""},
+		ContentType:   sql.NullString{String: contentType, Valid: contentType != ""},
+		ContentDigest: sql.NullString{String: contentDigest, Valid: contentDigest != ""},
+		Size:          sql.NullInt64{Int64: size, Valid: true},
+		LastModified:  sql.NullTime{Time: lastModified, Valid: !lastModified.IsZero()},
+		FetchedAt:     sql.NullTime{Time: fetchedAt, Valid: !fetchedAt.IsZero()},
+	})
+	if err != nil {
+		return 0, err
+	}
+	return size, nil
+}

internal/handler/container_tags.go

@@ -0,0 +1,229 @@
+package handler
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const containerTagsCacheEcosystem = "oci-tags"
+
+var containerLinkTargetPattern = regexp.MustCompile(`<([^>]*)>`)
+
+type cachedContainerTags struct {
+	body        []byte
+	contentType string
+	etag        string
+	link        string
+	size        int64
+	fetchedAt   time.Time
+}
+
+func (h *ContainerHandler) serveTagsList(w http.ResponseWriter, r *http.Request, registryURL, name string) {
+	cacheKey := h.containerTagsCacheKey(registryURL, name, r.URL.Query())
+	cached, err := h.loadContainerTags(r.Context(), cacheKey)
+	if err != nil {
+		h.proxy.Logger.Warn("failed to read cached container tag list", "error", err)
+		cached = nil
+	}
+	if cached != nil && h.containerTagsFresh(cached) {
+		writeContainerTags(w, cached, false)
+		return
+	}
+
+	upstreamURL := fmt.Sprintf("%s/v2/%s/tags/list", registryURL, name)
+	if query := r.URL.Query().Encode(); query != "" {
+		upstreamURL += "?" + query
+	}
+	req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, upstreamURL, nil)
+	if err != nil {
+		h.containerError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to create request")
+		return
+	}
+	req.Header.Set("Accept", "application/json")
+	if cached != nil && cached.etag != "" {
+		req.Header.Set("If-None-Match", cached.etag)
+	}
+
+	resp, err := h.proxy.HTTPClient.Do(req)
+	if err != nil {
+		h.serveStaleTagsOrError(w, cached, err)
+		return
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode == http.StatusNotModified && cached != nil {
+		cached.fetchedAt = time.Now()
+		if err := h.storeContainerTags(r.Context(), cacheKey, cached); err != nil {
+			h.proxy.Logger.Warn("failed to refresh cached container tag list", "error", err)
+		}
+		writeContainerTags(w, cached, false)
+		return
+	}
+	if resp.StatusCode != http.StatusOK {
+		if cached != nil && shouldServeStaleManifest(resp.StatusCode) {
+			writeContainerTags(w, cached, true)
+			return
+		}
+		copyContainerTagsHeaders(w.Header(), resp.Header)
+		w.WriteHeader(resp.StatusCode)
+		_, _ = io.Copy(w, resp.Body)
+		return
+	}
+
+	body, err := h.proxy.ReadMetadata(resp.Body)
+	if err != nil {
+		h.serveStaleTagsOrError(w, cached, fmt.Errorf("reading tag list: %w", err))
+		return
+	}
+	tags := &cachedContainerTags{
+		body:        body,
+		contentType: resp.Header.Get(headerContentType),
+		etag:        resp.Header.Get(headerETag),
+		link:        h.rewriteContainerTagsLink(strings.Join(resp.Header.Values("Link"), ", "), registryURL, r.URL.Path),
+		size:        int64(len(body)),
+		fetchedAt:   time.Now(),
+	}
+	if tags.contentType == "" {
+		tags.contentType = contentTypeJSON
+	}
+	if err := h.storeContainerTags(r.Context(), cacheKey, tags); err != nil {
+		h.proxy.Logger.Warn("failed to cache container tag list", "error", err)
+	}
+	writeContainerTags(w, tags, false)
+}
+
+func (h *ContainerHandler) serveStaleTagsOrError(w http.ResponseWriter, cached *cachedContainerTags, err error) {
+	if cached != nil {
+		h.proxy.Logger.Warn("upstream tag list fetch failed, serving stale cache", "error", err)
+		writeContainerTags(w, cached, true)
+		return
+	}
+	h.proxy.Logger.Error("failed to fetch container tag list", "error", err)
+	h.containerError(w, http.StatusBadGateway, "INTERNAL_ERROR", "failed to fetch from upstream")
+}
+
+func (h *ContainerHandler) containerTagsCacheKey(registryURL, name string, query url.Values) string {
+	identity := registryURL + "\x00" + name + "\x00" + query.Encode()
+	sum := sha256.Sum256([]byte(identity))
+	return hex.EncodeToString(sum[:])
+}
+
+func (h *ContainerHandler) containerTagsFresh(tags *cachedContainerTags) bool {
+	return h.proxy.MetadataTTL > 0 && !tags.fetchedAt.IsZero() && time.Since(tags.fetchedAt) < h.proxy.MetadataTTL
+}
+
+func (h *ContainerHandler) loadContainerTags(ctx context.Context, cacheKey string) (*cachedContainerTags, error) {
+	if h.proxy.DB == nil || h.proxy.Storage == nil {
+		return nil, nil
+	}
+	entry, err := h.proxy.DB.GetMetadataCache(containerTagsCacheEcosystem, cacheKey)
+	if err != nil || entry == nil {
+		return nil, err
+	}
+	reader, err := h.proxy.Storage.Open(ctx, entry.StoragePath)
+	if err != nil {
+		return nil, nil
+	}
+	defer func() { _ = reader.Close() }()
+	body, err := h.proxy.ReadMetadata(reader)
+	if err != nil {
+		return nil, err
+	}
+
+	tags := &cachedContainerTags{body: body, contentType: contentTypeJSON, size: int64(len(body))}
+	if entry.ContentType.Valid {
+		tags.contentType = entry.ContentType.String
+	}
+	if entry.ETag.Valid {
+		tags.etag = entry.ETag.String
+	}
+	if entry.Link.Valid {
+		tags.link = entry.Link.String
+	}
+	if entry.Size.Valid {
+		tags.size = entry.Size.Int64
+	}
+	if entry.FetchedAt.Valid {
+		tags.fetchedAt = entry.FetchedAt.Time
+	}
+	return tags, nil
+}
+
+func (h *ContainerHandler) storeContainerTags(ctx context.Context, cacheKey string, tags *cachedContainerTags) error {
+	size, err := h.storeContainerMetadata(ctx, containerTagsCacheEcosystem, cacheKey, tags.body,
+		tags.etag, tags.link, tags.contentType, "", time.Time{}, tags.fetchedAt)
+	if err != nil {
+		return fmt.Errorf("storing tag list: %w", err)
+	}
+	tags.size = size
+	return nil
+}
+
+func writeContainerTags(w http.ResponseWriter, tags *cachedContainerTags, stale bool) {
+	w.Header().Set(headerContentType, tags.contentType)
+	w.Header().Set(headerContentLength, strconv.FormatInt(tags.size, 10))
+	if tags.etag != "" {
+		w.Header().Set(headerETag, tags.etag)
+	}
+	if tags.link != "" {
+		w.Header().Set("Link", tags.link)
+	}
+	if stale {
+		w.Header().Set("Warning", containerStaleWarning)
+	}
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write(tags.body)
+}
+
+func copyContainerTagsHeaders(destination, source http.Header) {
+	for _, header := range []string{headerContentType, headerContentLength, headerETag, "Link", "WWW-Authenticate"} {
+		if value := source.Get(header); value != "" {
+			destination.Set(header, value)
+		}
+	}
+}
+
+func (h *ContainerHandler) rewriteContainerTagsLink(link, registryURL, requestPath string) string {
+	if link == "" {
+		return ""
+	}
+	upstreamURL, err := url.Parse(registryURL)
+	if err != nil {
+		return link
+	}
+	proxyURL, err := url.Parse(h.proxyURL)
+	if err != nil {
+		return link
+	}
+
+	return containerLinkTargetPattern.ReplaceAllStringFunc(link, func(target string) string {
+		linkURL, err := url.Parse(target[1 : len(target)-1])
+		if err != nil {
+			return target
+		}
+		if linkURL.IsAbs() {
+			if linkURL.Scheme != upstreamURL.Scheme || linkURL.Host != upstreamURL.Host {
+				return target
+			}
+		} else if linkURL.Host != "" || (linkURL.Path != "" && !strings.HasPrefix(linkURL.Path, "/v2/")) {
+			return target
+		}
+		// Relative registry API links resolve against the current tag-list
+		// endpoint. Rebuild them below so named-registry selectors are kept.
+		linkURL.Scheme = proxyURL.Scheme
+		linkURL.Host = proxyURL.Host
+		linkURL.User = proxyURL.User
+		linkURL.Path = strings.TrimSuffix(proxyURL.Path, "/") + "/v2" + requestPath
+		linkURL.RawPath = ""
+		return "<" + linkURL.String() + ">"
+	})
+}

internal/handler/container_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strconv"
+	"strings"
 	"testing"
 	"time"
 
@@ -134,8 +135,241 @@ func TestContainerHandler_parseTagsListPath(t *testing.T) {
 	}
 }
 
+func TestContainerHandler_TagsListUsesStaleCacheOnUpstreamFailure(t *testing.T) {
+	tags := `{"name":"library/nginx","tags":["1.0","latest"]}`
+	upstreamAvailable := true
+	upstreamRequests := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamRequests++
+		if r.URL.Path != "/v2/library/nginx/tags/list" {
+			http.NotFound(w, r)
+			return
+		}
+		if !upstreamAvailable {
+			http.Error(w, "upstream unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("ETag", `"tags-etag"`)
+		_, _ = io.WriteString(w, tags)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.MetadataTTL = 0
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL, proxyURL: "http://localhost:8080"}
+
+	first := httptest.NewRecorder()
+	h.Routes().ServeHTTP(first, httptest.NewRequest(http.MethodGet, "/library/nginx/tags/list?n=2", nil))
+	if first.Code != http.StatusOK {
+		t.Fatalf("initial status = %d, want 200: %s", first.Code, first.Body.String())
+	}
+	if first.Body.String() != tags {
+		t.Errorf("initial body = %q, want %q", first.Body.String(), tags)
+	}
+
+	upstreamAvailable = false
+	second := httptest.NewRecorder()
+	h.Routes().ServeHTTP(second, httptest.NewRequest(http.MethodGet, "/library/nginx/tags/list?n=2", nil))
+	if second.Code != http.StatusOK {
+		t.Fatalf("stale status = %d, want 200: %s", second.Code, second.Body.String())
+	}
+	if second.Body.String() != tags {
+		t.Errorf("stale body = %q, want %q", second.Body.String(), tags)
+	}
+	if got := second.Header().Get("Warning"); got != `110 - "Response is Stale"` {
+		t.Errorf("Warning = %q, want stale warning", got)
+	}
+	if upstreamRequests != 2 {
+		t.Errorf("upstream requests = %d, want 2", upstreamRequests)
+	}
+}
+
+func TestContainerHandler_TagsListCachesPaginationLink(t *testing.T) {
+	tags := `{"name":"library/nginx","tags":["1.0"]}`
+	upstreamAvailable := true
+	upstreamRequests := 0
+	var upstream *httptest.Server
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamRequests++
+		if !upstreamAvailable {
+			http.Error(w, "upstream unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Link", `<`+upstream.URL+`/v2/library/nginx/tags/list?last=1.0&n=2>; rel="next"`)
+		_, _ = io.WriteString(w, tags)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.MetadataTTL = time.Hour
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL, proxyURL: "http://proxy.example.test"}
+	wantLink := `<http://proxy.example.test/v2/library/nginx/tags/list?last=1.0&n=2>; rel="next"`
+
+	warmRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/tags/list?n=2", nil)
+	warm := httptest.NewRecorder()
+	h.Routes().ServeHTTP(warm, warmRequest)
+	if warm.Code != http.StatusOK {
+		t.Fatalf("warm status = %d, want 200: %s", warm.Code, warm.Body.String())
+	}
+	if got := warm.Header().Get("Link"); got != wantLink {
+		t.Errorf("warm Link = %q, want %q", got, wantLink)
+	}
+
+	fresh := httptest.NewRecorder()
+	h.Routes().ServeHTTP(fresh, httptest.NewRequest(http.MethodGet, "/library/nginx/tags/list?n=2", nil))
+	if fresh.Code != http.StatusOK {
+		t.Fatalf("fresh status = %d, want 200: %s", fresh.Code, fresh.Body.String())
+	}
+	if got := fresh.Header().Get("Link"); got != wantLink {
+		t.Errorf("fresh Link = %q, want %q", got, wantLink)
+	}
+	if upstreamRequests != 1 {
+		t.Fatalf("upstream requests after fresh cache hit = %d, want 1", upstreamRequests)
+	}
+
+	proxy.MetadataTTL = 0
+	upstreamAvailable = false
+	stale := httptest.NewRecorder()
+	h.Routes().ServeHTTP(stale, httptest.NewRequest(http.MethodGet, "/library/nginx/tags/list?n=2", nil))
+	if stale.Code != http.StatusOK {
+		t.Fatalf("stale status = %d, want 200: %s", stale.Code, stale.Body.String())
+	}
+	if got := stale.Header().Get("Link"); got != wantLink {
+		t.Errorf("stale Link = %q, want %q", got, wantLink)
+	}
+	if got := stale.Header().Get("Warning"); got != `110 - "Response is Stale"` {
+		t.Errorf("stale Warning = %q, want stale warning", got)
+	}
+	if upstreamRequests != 2 {
+		t.Errorf("upstream requests after stale fallback = %d, want 2", upstreamRequests)
+	}
+}
+
+func TestContainerHandler_TagsListRewritesRelativePaginationLinkForNamedRegistry(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v2/owner/repo/tags/list" {
+			http.NotFound(w, r)
+			return
+		}
+		if r.URL.Query().Get("n") != "1" {
+			http.Error(w, "unexpected page size", http.StatusBadRequest)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Query().Get("last") == "" {
+			w.Header().Set("Link", `</v2/owner/repo/tags/list?last=1.0&n=1>; rel="next"`)
+			_, _ = io.WriteString(w, `{"name":"owner/repo","tags":["1.0"]}`)
+			return
+		}
+		if r.URL.Query().Get("last") != "1.0" {
+			http.Error(w, "unexpected pagination token", http.StatusBadRequest)
+			return
+		}
+		_, _ = io.WriteString(w, `{"name":"owner/repo","tags":["2.0"]}`)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	h := NewContainerHandler(proxy, "http://proxy.example.test", map[string]string{"test": upstream.URL})
+	routes := http.StripPrefix("/v2", h.Routes())
+
+	first := httptest.NewRecorder()
+	routes.ServeHTTP(first, httptest.NewRequest(http.MethodGet,
+		"/v2/upstream/test/owner/repo/tags/list?n=1", nil))
+	if first.Code != http.StatusOK {
+		t.Fatalf("first page status = %d, want 200: %s", first.Code, first.Body.String())
+	}
+	const wantLink = `<http://proxy.example.test/v2/upstream/test/owner/repo/tags/list?last=1.0&n=1>; rel="next"`
+	if got := first.Header().Get("Link"); got != wantLink {
+		t.Fatalf("first page Link = %q, want %q", got, wantLink)
+	}
+
+	nextURL := strings.TrimPrefix(strings.SplitN(first.Header().Get("Link"), ">", 2)[0], "<")
+	next := httptest.NewRecorder()
+	routes.ServeHTTP(next, httptest.NewRequest(http.MethodGet, nextURL, nil))
+	if next.Code != http.StatusOK {
+		t.Fatalf("next page status = %d, want 200: %s", next.Code, next.Body.String())
+	}
+	if got, want := next.Body.String(), `{"name":"owner/repo","tags":["2.0"]}`; got != want {
+		t.Errorf("next page body = %q, want %q", got, want)
+	}
+}
+
+func TestContainerHandler_NamedOCIRegistryServesHelmArtifacts(t *testing.T) {
+	const blob = "chart archive"
+	digest := "sha256:" + sha256Hex(blob)
+	manifest := `{"schemaVersion":2,"config":{"mediaType":"application/vnd.cncf.helm.config.v1+json"},"layers":[{"mediaType":"application/vnd.cncf.helm.chart.content.v1.tar+gzip","digest":"` + digest + `"}]}`
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v2/owner/demo/manifests/1.0.0":
+			w.Header().Set("Content-Type", "application/vnd.oci.image.manifest.v1+json")
+			w.Header().Set("Docker-Content-Digest", "sha256:"+sha256Hex(manifest))
+			_, _ = io.WriteString(w, manifest)
+		case "/v2/owner/demo/blobs/" + digest:
+			w.Header().Set("Content-Type", "application/vnd.cncf.helm.chart.content.v1.tar+gzip")
+			_, _ = io.WriteString(w, blob)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(upstream.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+	h := NewContainerHandler(proxy, "http://proxy.example", map[string]string{"ghcr": upstream.URL})
+
+	manifestResponse := httptest.NewRecorder()
+	h.Routes().ServeHTTP(manifestResponse,
+		httptest.NewRequest(http.MethodGet, "/upstream/ghcr/owner/demo/manifests/1.0.0", nil))
+	if manifestResponse.Code != http.StatusOK {
+		t.Fatalf("manifest status = %d, want 200: %s", manifestResponse.Code, manifestResponse.Body.String())
+	}
+	if got := manifestResponse.Header().Get("Content-Type"); got != "application/vnd.oci.image.manifest.v1+json" {
+		t.Errorf("manifest Content-Type = %q", got)
+	}
+
+	blobResponse := httptest.NewRecorder()
+	h.Routes().ServeHTTP(blobResponse,
+		httptest.NewRequest(http.MethodGet, "/upstream/ghcr/owner/demo/blobs/"+digest, nil))
+	if blobResponse.Code != http.StatusOK {
+		t.Fatalf("blob status = %d, want 200: %s", blobResponse.Code, blobResponse.Body.String())
+	}
+	if got := blobResponse.Header().Get("Content-Type"); got != "application/vnd.cncf.helm.chart.content.v1.tar+gzip" {
+		t.Errorf("blob Content-Type = %q", got)
+	}
+}
+
+func TestContainerHandler_registryURLForUsesLongestRepositoryPrefix(t *testing.T) {
+	h := &ContainerHandler{registryURL: "https://registry-1.docker.io"}
+	h.RegisterRegistry("homebrew", "https://example.test")
+	h.RegisterRegistry("homebrew/core", "https://ghcr.io/")
+
+	tests := map[string]string{
+		"homebrew/core":            "https://ghcr.io",
+		"homebrew/core/jq":         "https://ghcr.io",
+		"homebrew/portable-ruby":   "https://example.test",
+		"homebrew-core/jq":         "https://registry-1.docker.io",
+		"library/homebrew/core/jq": "https://registry-1.docker.io",
+	}
+	for name, want := range tests {
+		if got := h.registryURLFor(name); got != want {
+			t.Errorf("registryURLFor(%q) = %q, want %q", name, got, want)
+		}
+	}
+}
+
 func TestContainerHandler_BlobDownload_DiscoversBearerChallenge(t *testing.T) {
-	digest := "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abcd"
+	blob := "upstream blob"
+	digest := sha256Digest([]byte(blob))
 	registryRequests := 0
 	tokenRequests := 0
 	var upstream *httptest.Server
@@ -156,7 +390,7 @@ func TestContainerHandler_BlobDownload_DiscoversBearerChallenge(t *testing.T) {
 				return
 			}
 			w.Header().Set("Content-Type", "application/octet-stream")
-			_, _ = io.WriteString(w, "upstream blob")
+			_, _ = io.WriteString(w, blob)
 		default:
 			http.NotFound(w, r)
 		}
@@ -187,8 +421,8 @@ func TestContainerHandler_BlobDownload_DiscoversBearerChallenge(t *testing.T) {
 		if w.Code != http.StatusOK {
 			t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusOK, w.Body.String())
 		}
-		if got := w.Body.String(); got != "upstream blob" {
-			t.Errorf("body = %q, want %q", got, "upstream blob")
+		if got := w.Body.String(); got != blob {
+			t.Errorf("body = %q, want %q", got, blob)
 		}
 	}
 
@@ -200,10 +434,102 @@ func TestContainerHandler_BlobDownload_DiscoversBearerChallenge(t *testing.T) {
 	}
 }
 
+func TestContainerHandler_HomebrewBlobDoesNotForwardClientCredentialsToRegistryOrCDN(t *testing.T) {
+	blob := "homebrew bottle"
+	digest := sha256Digest([]byte(blob))
+	var registryAuthorization, cdnAuthorization string
+
+	cdn := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		cdnAuthorization = r.Header.Get("Authorization")
+		w.Header().Set("Content-Type", "application/vnd.homebrew.bottle")
+		_, _ = io.WriteString(w, blob)
+	}))
+	defer cdn.Close()
+
+	registry := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		registryAuthorization = r.Header.Get("Authorization")
+		http.Redirect(w, r, cdn.URL+"/bottle", http.StatusTemporaryRedirect)
+	}))
+	defer registry.Close()
+
+	defaultRequests := 0
+	defaultRegistry := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defaultRequests++
+		http.NotFound(w, r)
+	}))
+	defer defaultRegistry.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	client := registry.Client()
+	artifactFetcher := fetch.NewFetcher(
+		fetch.WithHTTPClient(client),
+		fetch.WithMaxRetries(0),
+	)
+	t.Cleanup(func() { _ = artifactFetcher.Close() })
+	proxy.Fetcher = artifactFetcher
+
+	h := &ContainerHandler{proxy: proxy, registryURL: defaultRegistry.URL}
+	h.RegisterRegistry("homebrew/core", registry.URL)
+	req := httptest.NewRequest(http.MethodGet, "/homebrew/core/jq/blobs/"+digest, nil)
+	req.Header.Set("Authorization", "Bearer client-secret")
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusOK, w.Body.String())
+	}
+	if got := w.Body.String(); got != blob {
+		t.Errorf("body = %q, want %q", got, blob)
+	}
+	if got := w.Header().Get("Content-Type"); got != "application/vnd.homebrew.bottle" {
+		t.Errorf("Content-Type = %q, want application/vnd.homebrew.bottle", got)
+	}
+	if registryAuthorization != "" {
+		t.Errorf("registry Authorization = %q, want empty", registryAuthorization)
+	}
+	if cdnAuthorization != "" {
+		t.Errorf("CDN Authorization = %q, want empty", cdnAuthorization)
+	}
+	if defaultRequests != 0 {
+		t.Errorf("default registry requests = %d, want 0", defaultRequests)
+	}
+}
+
+func TestContainerHandler_BlobDigestMismatchIsNotCached(t *testing.T) {
+	proxy, _, store, fetcher := setupTestProxy(t)
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("wrong bottle")),
+		ContentType: "application/octet-stream",
+	}
+	digest := sha256Digest([]byte("expected bottle"))
+	h := &ContainerHandler{proxy: proxy, registryURL: "https://registry.example.test"}
+
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/homebrew/core/jq/blobs/"+digest, nil))
+
+	if w.Code != http.StatusBadGateway {
+		t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusBadGateway, w.Body.String())
+	}
+	if !strings.Contains(w.Body.String(), "DIGEST_INVALID") {
+		t.Errorf("body = %q, want DIGEST_INVALID", w.Body.String())
+	}
+	cached, err := proxy.GetCachedArtifact(t.Context(), "oci", "homebrew/core/jq", digest, digest)
+	if err != nil {
+		t.Fatalf("checking cache: %v", err)
+	}
+	if cached != nil {
+		t.Error("digest-mismatched blob was recorded in the cache")
+	}
+	if len(store.files) != 0 {
+		t.Errorf("stored files = %d, want 0", len(store.files))
+	}
+}
+
 func TestContainerHandler_CachedImagePullSurvivesRegistryAndTokenOutages(t *testing.T) {
-	digest := "sha256:abc123def456abc123def456abc123def456abc123def456abc123def456abcd"
 	manifest := `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json"}`
 	blob := "cached image blob"
+	manifestDigest := sha256Digest([]byte(manifest))
+	blobDigest := sha256Digest([]byte(blob))
 	registryAvailable := true
 	tokenAvailable := true
 	registryRequests := 0
@@ -238,9 +564,9 @@ func TestContainerHandler_CachedImagePullSurvivesRegistryAndTokenOutages(t *test
 		switch r.URL.Path {
 		case "/v2/library/nginx/manifests/latest":
 			w.Header().Set("Content-Type", "application/vnd.oci.image.manifest.v1+json")
-			w.Header().Set("Docker-Content-Digest", digest)
+			w.Header().Set("Docker-Content-Digest", manifestDigest)
 			_, _ = io.WriteString(w, manifest)
-		case "/v2/library/nginx/blobs/" + digest:
+		case "/v2/library/nginx/blobs/" + blobDigest:
 			w.Header().Set("Content-Type", "application/octet-stream")
 			_, _ = io.WriteString(w, blob)
 		default:
@@ -270,7 +596,7 @@ func TestContainerHandler_CachedImagePullSurvivesRegistryAndTokenOutages(t *test
 		body string
 	}{
 		{path: "/library/nginx/manifests/latest", body: manifest},
-		{path: "/library/nginx/blobs/" + digest, body: blob},
+		{path: "/library/nginx/blobs/" + blobDigest, body: blob},
 	} {
 		response := httptest.NewRecorder()
 		warmHandler.ServeHTTP(response, httptest.NewRequest(http.MethodGet, request.path, nil))
@@ -303,13 +629,14 @@ func TestContainerHandler_CachedImagePullSurvivesRegistryAndTokenOutages(t *test
 	}).Routes()
 
 	for _, request := range []struct {
-		name string
-		path string
-		body string
+		name   string
+		path   string
+		body   string
+		digest string
 	}{
-		{name: "tag manifest", path: "/library/nginx/manifests/latest", body: manifest},
-		{name: "digest manifest", path: "/library/nginx/manifests/" + digest, body: manifest},
-		{name: "blob", path: "/library/nginx/blobs/" + digest, body: blob},
+		{name: "tag manifest", path: "/library/nginx/manifests/latest", body: manifest, digest: manifestDigest},
+		{name: "digest manifest", path: "/library/nginx/manifests/" + manifestDigest, body: manifest, digest: manifestDigest},
+		{name: "blob", path: "/library/nginx/blobs/" + blobDigest, body: blob, digest: blobDigest},
 	} {
 		t.Run(request.name, func(t *testing.T) {
 			response := httptest.NewRecorder()
@@ -320,8 +647,8 @@ func TestContainerHandler_CachedImagePullSurvivesRegistryAndTokenOutages(t *test
 			if got := response.Body.String(); got != request.body {
 				t.Errorf("body = %q, want %q", got, request.body)
 			}
-			if got := response.Header().Get("Docker-Content-Digest"); got != digest {
-				t.Errorf("Docker-Content-Digest = %q, want %q", got, digest)
+			if got := response.Header().Get("Docker-Content-Digest"); got != request.digest {
+				t.Errorf("Docker-Content-Digest = %q, want %q", got, request.digest)
 			}
 		})
 	}
@@ -436,8 +763,9 @@ func TestContainerHandler_BlobHead_DirectServeRedirects(t *testing.T) {
 	if got := w.Header().Get("Location"); got != store.signedURL {
 		t.Errorf("Location = %q, want %q", got, store.signedURL)
 	}
-	if got := w.Header().Get("ETag"); got != `"abc123"` {
-		t.Errorf("ETag = %q, want %q", got, `"abc123"`)
+	wantETag := `"` + sha256Hex("cached blob") + `"`
+	if got := w.Header().Get("ETag"); got != wantETag {
+		t.Errorf("ETag = %q, want %q", got, wantETag)
 	}
 	if w.Body.Len() != 0 {
 		t.Errorf("HEAD response body length = %d, want 0", w.Body.Len())
@@ -448,8 +776,9 @@ func TestContainerHandler_BlobHead_DirectServeRedirects(t *testing.T) {
 }
 
 func TestContainerHandler_ManifestByDigest_CacheHitSkipsUpstream(t *testing.T) {
-	digest := "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 	manifest := `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json"}`
+	digest := sha256Digest([]byte(manifest))
+	lastModified := time.Date(2026, time.August, 14, 9, 30, 0, 0, time.UTC)
 	upstreamAvailable := true
 	upstreamRequests := 0
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -465,6 +794,7 @@ func TestContainerHandler_ManifestByDigest_CacheHitSkipsUpstream(t *testing.T) {
 		w.Header().Set("Content-Type", "application/vnd.oci.image.manifest.v1+json")
 		w.Header().Set("Docker-Content-Digest", digest)
 		w.Header().Set("ETag", `"manifest-etag"`)
+		w.Header().Set("Last-Modified", lastModified.Format(http.TimeFormat))
 		if r.Method != http.MethodHead {
 			_, _ = io.WriteString(w, manifest)
 		}
@@ -496,6 +826,23 @@ func TestContainerHandler_ManifestByDigest_CacheHitSkipsUpstream(t *testing.T) {
 	if got := second.Header().Get("Docker-Content-Digest"); got != digest {
 		t.Errorf("cached Docker-Content-Digest = %q, want %q", got, digest)
 	}
+	if got := second.Header().Get("Last-Modified"); got != lastModified.Format(http.TimeFormat) {
+		t.Errorf("cached Last-Modified = %q, want %q", got, lastModified.Format(http.TimeFormat))
+	}
+
+	conditionalRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/"+digest, nil)
+	conditionalRequest.Header.Set("If-None-Match", `"manifest-etag"`)
+	conditional := httptest.NewRecorder()
+	h.Routes().ServeHTTP(conditional, conditionalRequest)
+	if conditional.Code != http.StatusNotModified {
+		t.Fatalf("conditional status = %d, want %d", conditional.Code, http.StatusNotModified)
+	}
+	if got := conditional.Header().Get("ETag"); got != `"manifest-etag"` {
+		t.Errorf("conditional ETag = %q, want %q", got, `"manifest-etag"`)
+	}
+	if conditional.Body.Len() != 0 {
+		t.Errorf("conditional body length = %d, want 0", conditional.Body.Len())
+	}
 
 	head := httptest.NewRecorder()
 	h.Routes().ServeHTTP(head, httptest.NewRequest(http.MethodHead, "/library/nginx/manifests/"+digest, nil))
@@ -514,9 +861,104 @@ func TestContainerHandler_ManifestByDigest_CacheHitSkipsUpstream(t *testing.T) {
 	}
 }
 
+func TestContainerHandler_ManifestDigestMismatchIsNotCached(t *testing.T) {
+	manifest := `{"schemaVersion":2}`
+	digest := sha256Digest([]byte("different manifest"))
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/vnd.oci.image.manifest.v1+json")
+		w.Header().Set("Docker-Content-Digest", digest)
+		_, _ = io.WriteString(w, manifest)
+	}))
+	defer upstream.Close()
+
+	proxy, db, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL}
+	req := httptest.NewRequest(http.MethodGet, "/homebrew/core/jq/manifests/"+digest, nil)
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadGateway {
+		t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusBadGateway, w.Body.String())
+	}
+	if !strings.Contains(w.Body.String(), "DIGEST_INVALID") {
+		t.Errorf("body = %q, want DIGEST_INVALID", w.Body.String())
+	}
+	cacheKey := h.containerManifestCacheKey(upstream.URL, "homebrew/core/jq", digest, containerManifestAccept(req))
+	entry, err := db.GetMetadataCache(containerManifestCacheEcosystem, cacheKey)
+	if err != nil {
+		t.Fatalf("checking manifest cache: %v", err)
+	}
+	if entry != nil {
+		t.Error("digest-mismatched manifest was recorded in the cache")
+	}
+}
+
+func TestContainerHandler_ManifestNonSHA256DigestReferenceIsProxied(t *testing.T) {
+	manifest := `{"schemaVersion":2}`
+	sha512Reference := "sha512:" + strings.Repeat("a", 128)
+	sha512Header := "sha512:" + strings.Repeat("b", 128)
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/vnd.oci.image.manifest.v1+json")
+		w.Header().Set("Docker-Content-Digest", sha512Header)
+		_, _ = io.WriteString(w, manifest)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL}
+
+	for _, reference := range []string{sha512Reference, "latest"} {
+		t.Run(reference, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/"+reference, nil))
+			if w.Code != http.StatusOK {
+				t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusOK, w.Body.String())
+			}
+			if got := w.Body.String(); got != manifest {
+				t.Errorf("body = %q, want %q", got, manifest)
+			}
+			if got := w.Header().Get("Docker-Content-Digest"); got != sha512Header {
+				t.Errorf("Docker-Content-Digest = %q, want %q", got, sha512Header)
+			}
+		})
+	}
+}
+
+func TestContainerHandler_ManifestTagWithInvalidDigestIsNotAliased(t *testing.T) {
+	manifest := `{"schemaVersion":2}`
+	invalidDigest := sha256Digest([]byte("different manifest"))
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/vnd.oci.image.manifest.v1+json")
+		w.Header().Set("Docker-Content-Digest", invalidDigest)
+		_, _ = io.WriteString(w, manifest)
+	}))
+	defer upstream.Close()
+
+	proxy, db, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL}
+	req := httptest.NewRequest(http.MethodGet, "/homebrew/core/jq/manifests/latest", nil)
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadGateway {
+		t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusBadGateway, w.Body.String())
+	}
+	cacheKey := h.containerManifestCacheKey(upstream.URL, "homebrew/core/jq", invalidDigest, containerManifestAccept(req))
+	entry, err := db.GetMetadataCache(containerManifestCacheEcosystem, cacheKey)
+	if err != nil {
+		t.Fatalf("checking manifest cache: %v", err)
+	}
+	if entry != nil {
+		t.Error("tag manifest was cached under an unverified digest")
+	}
+}
+
 func TestContainerHandler_ManifestByTag_UsesStaleCacheOnUpstreamFailure(t *testing.T) {
-	digest := "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
 	manifest := `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.index.v1+json"}`
+	digest := sha256Digest([]byte(manifest))
 	upstreamAvailable := true
 	upstreamRequests := 0
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
@@ -562,9 +1004,225 @@ func TestContainerHandler_ManifestByTag_UsesStaleCacheOnUpstreamFailure(t *testi
 	}
 }
 
-func TestContainerHandler_ManifestByTag_CachesDigestAlias(t *testing.T) {
-	digest := "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+func TestContainerHandler_ManifestVariantCacheNormalizesCompatibleAccept(t *testing.T) {
+	manifest := `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.index.v1+json"}`
+	digest := sha256Digest([]byte(manifest))
+	upstreamAvailable := true
+	upstreamRequests := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamRequests++
+		if !upstreamAvailable {
+			http.Error(w, "upstream unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "")
+		w.Header().Set("Docker-Content-Digest", digest)
+		_, _ = io.WriteString(w, manifest)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.MetadataTTL = 0
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL, proxyURL: "http://localhost:8080"}
+
+	firstRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	firstRequest.Header.Set("Accept", "application/vnd.oci.image.index.v1+json;q=1, application/vnd.oci.image.manifest.v1+json;q=1, application/vnd.oci.image.index.v1+json;q=1")
+	first := httptest.NewRecorder()
+	h.Routes().ServeHTTP(first, firstRequest)
+	if first.Code != http.StatusOK {
+		t.Fatalf("initial status = %d, want 200: %s", first.Code, first.Body.String())
+	}
+
+	upstreamAvailable = false
+	secondRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	secondRequest.Header.Set("Accept", " application/vnd.oci.image.manifest.v1+json , application/vnd.oci.image.index.v1+json ")
+	second := httptest.NewRecorder()
+	h.Routes().ServeHTTP(second, secondRequest)
+	if second.Code != http.StatusOK {
+		t.Fatalf("stale status = %d, want 200: %s", second.Code, second.Body.String())
+	}
+	if second.Body.String() != manifest {
+		t.Errorf("stale body = %q, want %q", second.Body.String(), manifest)
+	}
+	if got := second.Header().Get("Warning"); got != `110 - "Response is Stale"` {
+		t.Errorf("Warning = %q, want stale warning", got)
+	}
+	if upstreamRequests != 2 {
+		t.Errorf("upstream requests = %d, want 2", upstreamRequests)
+	}
+}
+
+func TestContainerHandler_ManifestMigratesLegacyAcceptCacheKey(t *testing.T) {
+	digest := "sha256:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
+	manifest := `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.index.v1+json"}`
+	upstreamRequests := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamRequests++
+		http.Error(w, "upstream should not be called", http.StatusServiceUnavailable)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.MetadataTTL = time.Hour
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL, proxyURL: "http://localhost:8080"}
+	accept := "application/vnd.oci.image.index.v1+json;q=1, application/vnd.oci.image.manifest.v1+json;q=1"
+	cacheAccept := normalizeContainerManifestAccept(accept)
+	legacyCacheKey := h.containerManifestCacheKey(upstream.URL, "library/nginx", "latest", accept)
+	cacheKey := h.containerManifestCacheKey(upstream.URL, "library/nginx", "latest", cacheAccept)
+	if legacyCacheKey == cacheKey {
+		t.Fatal("legacy and normalized cache keys are equal")
+	}
+
+	request := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	request.Header.Set("Accept", accept)
+	legacyManifest := &cachedContainerManifest{
+		body:          []byte(manifest),
+		contentType:   "application/vnd.oci.image.index.v1+json",
+		contentDigest: digest,
+		fetchedAt:     time.Now(),
+	}
+	if err := h.storeContainerManifest(request.Context(), legacyCacheKey, legacyManifest); err != nil {
+		t.Fatalf("store legacy manifest: %v", err)
+	}
+
+	response := httptest.NewRecorder()
+	h.Routes().ServeHTTP(response, request)
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", response.Code, response.Body.String())
+	}
+	if response.Body.String() != manifest {
+		t.Errorf("body = %q, want %q", response.Body.String(), manifest)
+	}
+	if upstreamRequests != 0 {
+		t.Errorf("upstream requests = %d, want 0", upstreamRequests)
+	}
+	migrated, err := h.loadContainerManifest(request.Context(), cacheKey)
+	if err != nil {
+		t.Fatalf("load migrated manifest: %v", err)
+	}
+	if migrated == nil {
+		t.Error("normalized cache entry was not created")
+	}
+}
+
+func TestContainerHandler_ManifestDualWritesLegacyAcceptCacheKeys(t *testing.T) {
 	manifest := `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json"}`
+	digest := sha256Digest([]byte(manifest))
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v2/library/nginx/manifests/latest" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/vnd.oci.image.manifest.v1+json")
+		w.Header().Set("Docker-Content-Digest", digest)
+		_, _ = io.WriteString(w, manifest)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL, proxyURL: "http://localhost:8080"}
+	accept := "application/vnd.oci.image.manifest.v1+json;q=1, application/vnd.oci.image.manifest.v1+json;q=1"
+	request := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	request.Header.Set("Accept", accept)
+	response := httptest.NewRecorder()
+	h.Routes().ServeHTTP(response, request)
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", response.Code, response.Body.String())
+	}
+
+	for _, reference := range []string{"latest", digest} {
+		legacyCacheKey := h.containerManifestCacheKey(upstream.URL, "library/nginx", reference, accept)
+		cached, err := h.loadContainerManifest(request.Context(), legacyCacheKey)
+		if err != nil {
+			t.Fatalf("load legacy %s manifest: %v", reference, err)
+		}
+		if cached == nil {
+			t.Errorf("legacy %s cache entry was not written", reference)
+		}
+	}
+}
+
+func TestContainerHandler_ManifestVariantCacheHonorsSpecificAcceptExclusions(t *testing.T) {
+	manifest := `{"schemaVersion":2}`
+	digest := sha256Digest([]byte(manifest))
+	upstreamAvailable := true
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if !upstreamAvailable {
+			http.Error(w, "upstream unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "application/vnd.oci.image.index.v1+json")
+		w.Header().Set("Docker-Content-Digest", digest)
+		_, _ = io.WriteString(w, manifest)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.MetadataTTL = 0
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL, proxyURL: "http://localhost:8080"}
+
+	warmRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	warmRequest.Header.Set("Accept", "application/vnd.oci.image.index.v1+json;q=0, */*;q=1")
+	warm := httptest.NewRecorder()
+	h.Routes().ServeHTTP(warm, warmRequest)
+	if warm.Code != http.StatusOK {
+		t.Fatalf("warm status = %d, want 200", warm.Code)
+	}
+
+	upstreamAvailable = false
+	offlineRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	offlineRequest.Header.Set("Accept", "application/vnd.oci.image.index.v1+json;q=0, */*;q=1")
+	offline := httptest.NewRecorder()
+	h.Routes().ServeHTTP(offline, offlineRequest)
+	if offline.Code != http.StatusServiceUnavailable {
+		t.Errorf("offline status = %d, want 503", offline.Code)
+	}
+}
+
+func TestContainerHandler_ManifestVariantCacheHonorsParameterizedAcceptExclusions(t *testing.T) {
+	contentType := "application/vnd.oci.image.index.v1+json; charset=utf-8"
+	upstreamAvailable := true
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if !upstreamAvailable {
+			http.Error(w, "upstream unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", contentType)
+		_, _ = io.WriteString(w, `{"schemaVersion":2}`)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.MetadataTTL = 0
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL, proxyURL: "http://localhost:8080"}
+	accept := "application/vnd.oci.image.index.v1+json;q=1, application/vnd.oci.image.index.v1+json;charset=utf-8;q=0"
+
+	warmRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	warmRequest.Header.Set("Accept", accept)
+	warm := httptest.NewRecorder()
+	h.Routes().ServeHTTP(warm, warmRequest)
+	if warm.Code != http.StatusOK {
+		t.Fatalf("warm status = %d, want 200", warm.Code)
+	}
+
+	upstreamAvailable = false
+	offlineRequest := httptest.NewRequest(http.MethodGet, "/library/nginx/manifests/latest", nil)
+	offlineRequest.Header.Set("Accept", accept)
+	offline := httptest.NewRecorder()
+	h.Routes().ServeHTTP(offline, offlineRequest)
+	if offline.Code != http.StatusServiceUnavailable {
+		t.Errorf("offline status = %d, want 503", offline.Code)
+	}
+}
+
+func TestContainerHandler_ManifestByTag_CachesDigestAlias(t *testing.T) {
+	manifest := `{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json"}`
+	digest := sha256Digest([]byte(manifest))
 	upstreamAvailable := true
 	upstreamRequests := 0
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -611,7 +1269,8 @@ func TestContainerHandler_ManifestByTag_CachesDigestAlias(t *testing.T) {
 }
 
 func TestContainerHandler_ManifestByTag_StaleHeadChecksUpstream(t *testing.T) {
-	oldDigest := "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+	manifest := `{"schemaVersion":2}`
+	oldDigest := sha256Digest([]byte(manifest))
 	newDigest := "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
 	currentDigest := oldDigest
 	upstreamRequests := 0
@@ -621,7 +1280,7 @@ func TestContainerHandler_ManifestByTag_StaleHeadChecksUpstream(t *testing.T) {
 		w.Header().Set("Docker-Content-Digest", currentDigest)
 		w.Header().Set("ETag", `"`+currentDigest+`"`)
 		if r.Method != http.MethodHead {
-			_, _ = io.WriteString(w, `{"schemaVersion":2}`)
+			_, _ = io.WriteString(w, manifest)
 		}
 	}))
 	defer upstream.Close()

internal/handler/cran.go

@@ -25,6 +25,13 @@ func NewCRANHandler(proxy *Proxy, proxyURL string) *CRANHandler {
 	}
 }
 
+// NewCRANHandlerWithUpstream creates a CRAN handler with a custom upstream.
+func NewCRANHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *CRANHandler {
+	h := NewCRANHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, cranUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for CRAN requests.
 func (h *CRANHandler) Routes() http.Handler {
 	mux := http.NewServeMux()

internal/handler/debian.go

@@ -88,7 +88,7 @@ func (h *DebianHandler) handlePackageDownload(w http.ResponseWriter, r *http.Req
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/vnd.debian.binary-package")
+	w.Header().Set(headerContentType, "application/vnd.debian.binary-package")
 	ServeArtifact(w, result)
 }
 

internal/handler/debian_test.go

@@ -12,6 +12,11 @@ func TestDebianHandler_parsePoolPath(t *testing.T) {
 		{"pool/main/libn/libncurses/libncurses6_6.2-1_amd64.deb", "libncurses6", "6.2-1", "amd64"},
 		{"pool/contrib/v/virtualbox/virtualbox_6.1.38-1_amd64.deb", "virtualbox", "6.1.38-1", "amd64"},
 		{"pool/main/g/git/git_2.39.2-1_arm64.deb", "git", "2.39.2-1", "arm64"},
+		{
+			"pool/universe/n/nmap/nmap_7.91+dfsg1+really7.80+dfsg1-2ubuntu0.1_amd64.deb",
+			"nmap", "7.91+dfsg1+really7.80+dfsg1-2ubuntu0.1", "amd64",
+		},
+		{"pool/main/o/openssl/openssl_3.0.2-0ubuntu1.15~build1_amd64.deb", "openssl", "3.0.2-0ubuntu1.15~build1", "amd64"},
 		{"invalid/path", "", "", ""},
 		{"pool/main/n/nginx/nginx.deb", "", "", ""},
 	})

internal/handler/download_test.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/git-pkgs/proxy/internal/database"
+	"github.com/git-pkgs/proxy/internal/metrics"
 	"github.com/git-pkgs/proxy/internal/storage"
 	"github.com/git-pkgs/purl"
 	"github.com/git-pkgs/registries/fetch"
@@ -43,13 +44,14 @@ func seedPackageWithPURL(t *testing.T, db *database.DB, store *mockStorage, ecos
 
 	storagePath := storage.ArtifactPath(ecosystem, "", name, version, filename)
 	store.files[storagePath] = []byte(content)
+	sharedArtifact := testArtifact(content, versionPURL, filename, "application/octet-stream")
 
 	art := &database.Artifact{
 		VersionPURL: versionPURL,
 		Filename:    filename,
 		UpstreamURL: "https://example.com/" + filename,
 		StoragePath: sql.NullString{String: storagePath, Valid: true},
-		ContentHash: sql.NullString{String: "abc123", Valid: true},
+		ContentHash: sql.NullString{String: sharedArtifact.Digest.Encoded(), Valid: true},
 		Size:        sql.NullInt64{Int64: int64(len(content)), Valid: true},
 		ContentType: sql.NullString{String: "application/octet-stream", Valid: true},
 		FetchedAt:   sql.NullTime{Time: time.Now(), Valid: true},
@@ -203,16 +205,19 @@ func TestGemHandler_UpstreamProxy(t *testing.T) {
 
 func TestGemHandler_CacheMiss(t *testing.T) {
 	proxy, _, _, fetcher := setupTestProxy(t)
+	fetchesBefore := histogramSampleCount(t, metrics.UpstreamFetchDuration.WithLabelValues("gem"))
 	fetcher.artifact = &fetch.Artifact{
 		Body:        io.NopCloser(strings.NewReader("fetched gem")),
 		ContentType: "application/octet-stream",
 	}
 
-	h := NewGemHandler(proxy, "http://localhost")
+	upstreamURL := "https://packages.example.com/gem"
+	h := NewGemHandlerWithUpstream(proxy, "http://localhost", upstreamURL)
 	srv := httptest.NewServer(h.Routes())
 	defer srv.Close()
 
-	resp, err := http.Get(srv.URL + "/gems/sinatra-3.0.0.gem")
+	path := "/gems/sinatra-3.0.0.gem"
+	resp, err := http.Get(srv.URL + path)
 	if err != nil {
 		t.Fatalf("request failed: %v", err)
 	}
@@ -221,6 +226,12 @@ func TestGemHandler_CacheMiss(t *testing.T) {
 	if !fetcher.fetchCalled {
 		t.Error("expected fetcher to be called on cache miss")
 	}
+	if want := upstreamURL + path; fetcher.fetchedURL != want {
+		t.Errorf("upstream URL = %q, want %q", fetcher.fetchedURL, want)
+	}
+	if diff := histogramSampleCount(t, metrics.UpstreamFetchDuration.WithLabelValues("gem")) - fetchesBefore; diff != 1 {
+		t.Errorf("upstream fetch observations delta = %d, want 1", diff)
+	}
 }
 
 func TestGoHandler_DownloadCacheHit(t *testing.T) {
@@ -342,11 +353,13 @@ func TestGoHandler_CacheMiss(t *testing.T) {
 		ContentType: "application/zip",
 	}
 
-	h := NewGoHandler(proxy, "http://localhost")
+	upstreamURL := "https://packages.example.com/go"
+	h := NewGoHandlerWithUpstream(proxy, "http://localhost", upstreamURL)
 	srv := httptest.NewServer(h.Routes())
 	defer srv.Close()
 
-	resp, err := http.Get(srv.URL + "/example.com/mod/@v/v1.0.0.zip")
+	path := "/example.com/mod/@v/v1.0.0.zip"
+	resp, err := http.Get(srv.URL + path)
 	if err != nil {
 		t.Fatalf("request failed: %v", err)
 	}
@@ -355,6 +368,9 @@ func TestGoHandler_CacheMiss(t *testing.T) {
 	if !fetcher.fetchCalled {
 		t.Error("expected fetcher to be called on cache miss")
 	}
+	if want := upstreamURL + path; fetcher.fetchedURL != want {
+		t.Errorf("upstream URL = %q, want %q", fetcher.fetchedURL, want)
+	}
 }
 
 func TestHexHandler_DownloadCacheHit(t *testing.T) {
@@ -423,11 +439,13 @@ func TestHexHandler_CacheMiss(t *testing.T) {
 		ContentType: "application/x-tar",
 	}
 
-	h := NewHexHandler(proxy, "http://localhost")
+	upstreamURL := "https://packages.example.com/hex"
+	h := NewHexHandlerWithUpstreams(proxy, "http://localhost", upstreamURL, "https://packages.example.com/hex-api")
 	srv := httptest.NewServer(h.Routes())
 	defer srv.Close()
 
-	resp, err := http.Get(srv.URL + "/tarballs/plug-1.15.0.tar")
+	path := "/tarballs/plug-1.15.0.tar"
+	resp, err := http.Get(srv.URL + path)
 	if err != nil {
 		t.Fatalf("request failed: %v", err)
 	}
@@ -436,6 +454,36 @@ func TestHexHandler_CacheMiss(t *testing.T) {
 	if !fetcher.fetchCalled {
 		t.Error("expected fetcher to be called on cache miss")
 	}
+	if want := upstreamURL + path; fetcher.fetchedURL != want {
+		t.Errorf("upstream URL = %q, want %q", fetcher.fetchedURL, want)
+	}
+}
+
+func TestPubHandler_CacheMiss(t *testing.T) {
+	proxy, _, _, fetcher := setupTestProxy(t)
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("fetched pub package")),
+		ContentType: "application/gzip",
+	}
+
+	upstreamURL := "https://packages.example.com/pub"
+	h := NewPubHandlerWithUpstream(proxy, "http://localhost", upstreamURL)
+	srv := httptest.NewServer(h.Routes())
+	defer srv.Close()
+
+	path := "/packages/flutter_bloc/versions/8.1.6.tar.gz"
+	resp, err := http.Get(srv.URL + path)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if !fetcher.fetchCalled {
+		t.Error("expected fetcher to be called on cache miss")
+	}
+	if want := upstreamURL + path; fetcher.fetchedURL != want {
+		t.Errorf("upstream URL = %q, want %q", fetcher.fetchedURL, want)
+	}
 }
 
 func TestCondaHandler_DownloadCacheHit(t *testing.T) {

internal/handler/filename_download.go

@@ -6,11 +6,12 @@ import (
 )
 
 type filenameDownload struct {
-	ecosystem string
-	suffix    string
-	parseErr  string
-	fetchErr  string
-	parse     func(string) (name, version string)
+	ecosystem   string
+	upstreamURL string
+	suffix      string
+	parseErr    string
+	fetchErr    string
+	parse       func(string) (name, version string)
 }
 
 func (p *Proxy) handleFilenameDownload(w http.ResponseWriter, r *http.Request, d filenameDownload) {
@@ -29,7 +30,10 @@ func (p *Proxy) handleFilenameDownload(w http.ResponseWriter, r *http.Request, d
 	p.Logger.Info(d.ecosystem+" download request",
 		"name", name, "version", version, "filename", filename)
 
-	result, err := p.GetOrFetchArtifact(r.Context(), d.ecosystem, name, version, filename)
+	downloadURL := d.upstreamURL + r.URL.Path
+	result, err := p.GetOrFetchArtifactFromURL(
+		r.Context(), d.ecosystem, name, version, filename, downloadURL,
+	)
 	if err != nil {
 		p.serveArtifactError(w, err, d.fetchErr)
 		return

internal/handler/gem.go

@@ -30,6 +30,13 @@ func NewGemHandler(proxy *Proxy, proxyURL string) *GemHandler {
 	}
 }
 
+// NewGemHandlerWithUpstream creates a RubyGems handler with a custom upstream.
+func NewGemHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *GemHandler {
+	h := NewGemHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, gemUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for RubyGems requests.
 func (h *GemHandler) Routes() http.Handler {
 	mux := http.NewServeMux()
@@ -59,11 +66,12 @@ func (h *GemHandler) Routes() http.Handler {
 // handleDownload serves a gem file, fetching and caching from upstream if needed.
 func (h *GemHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 	h.proxy.handleFilenameDownload(w, r, filenameDownload{
-		ecosystem: "gem",
-		suffix:    ".gem",
-		parseErr:  "could not parse gem filename",
-		fetchErr:  "failed to fetch gem",
-		parse:     h.parseGemFilename,
+		ecosystem:   "gem",
+		upstreamURL: h.upstreamURL,
+		suffix:      ".gem",
+		parseErr:    "could not parse gem filename",
+		fetchErr:    "failed to fetch gem",
+		parse:       h.parseGemFilename,
 	})
 }
 
@@ -174,7 +182,7 @@ func (h *GemHandler) fetchCompactIndex(r *http.Request, name string) (*http.Resp
 // writeFilteredIndex writes the compact index response with cooldown-filtered versions removed.
 func (h *GemHandler) writeFilteredIndex(w http.ResponseWriter, resp *http.Response, name string, filtered map[string]bool) {
 	for k, vv := range resp.Header {
-		if strings.EqualFold(k, "Content-Length") {
+		if strings.EqualFold(k, headerContentLength) {
 			continue // length will change after filtering
 		}
 		for _, v := range vv {

internal/handler/generic.go

@@ -0,0 +1,160 @@
+package handler
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"regexp"
+	"strings"
+)
+
+const (
+	genericEcosystem = "generic"
+	// genericAcceptAny is always sent for metadata so every client shares the
+	// same cached representation, regardless of its Accept header.
+	genericAcceptAny = "*/*"
+	// githubReleaseAssetMatchCount is the full match plus owner, repository,
+	// tag and asset filename.
+	githubReleaseAssetMatchCount = 5
+)
+
+// githubReleaseAssetPattern matches the path of a GitHub release asset
+// download, {owner}/{repo}/releases/download/{tag}/{asset}. A tag pins the
+// asset to one release, so these downloads are cached in the artifact cache
+// and served without revalidation once fetched.
+var githubReleaseAssetPattern = regexp.MustCompile(`^([^/]+)/([^/]+)/releases/download/([^/]+)/([^/]+)$`)
+
+// GenericHandler proxies plain HTTP downloads from configured upstream base
+// URLs. Each configured upstream is mounted at /generic/{name}/ and the
+// remaining request path (and query string) is appended to the upstream URL.
+//
+// Only configured upstreams are reachable, so the proxy is not an open HTTP
+// proxy. The handler is the caching layer behind tools that download from
+// fixed URL shapes, such as mise's aqua backend fetching GitHub release
+// assets, and is pointed at by URL-rewriting settings on the client.
+//
+// Release-asset paths ({owner}/{repo}/releases/download/{tag}/{asset}) are
+// version-pinned and cached in the shared artifact cache, so they keep being
+// served when the upstream is unreachable. Every other path is served through
+// the metadata cache: fresh within the metadata TTL, revalidated with the
+// upstream's validators after that, and served stale when the upstream fails
+// or refuses the request. That covers API responses such as
+// api.github.com/repos/{owner}/{repo}/releases/tags/{tag}.
+type GenericHandler struct {
+	proxy        *Proxy
+	repositories map[string]string
+}
+
+// NewGenericHandler creates a generic HTTP download proxy handler.
+func NewGenericHandler(proxy *Proxy, repositories map[string]string) *GenericHandler {
+	h := &GenericHandler{
+		proxy:        proxy,
+		repositories: make(map[string]string, len(repositories)),
+	}
+	for name, upstreamURL := range repositories {
+		h.repositories[name] = strings.TrimSuffix(upstreamURL, "/")
+	}
+	return h
+}
+
+// Routes returns the HTTP handler for generic download requests.
+// Mount this at /generic on your router.
+func (h *GenericHandler) Routes() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet && r.Method != http.MethodHead {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+
+		path := strings.TrimPrefix(r.URL.Path, "/")
+
+		if containsPathTraversal(path) {
+			http.Error(w, "invalid path", http.StatusBadRequest)
+			return
+		}
+
+		repository, rest, ok := strings.Cut(path, "/")
+		upstreamURL, found := h.repositories[repository]
+		if !ok || rest == "" || !found {
+			http.NotFound(w, r)
+			return
+		}
+
+		if asset, ok := parseGitHubReleaseAsset(rest); ok {
+			h.handleReleaseAsset(w, r, repository, upstreamURL, rest, asset)
+			return
+		}
+
+		h.handleMetadata(w, r, repository, upstreamURL, rest)
+	})
+}
+
+// githubReleaseAsset is the identity of a version-pinned release download.
+type githubReleaseAsset struct {
+	owner    string
+	repo     string
+	tag      string
+	filename string
+}
+
+// parseGitHubReleaseAsset extracts the release identity from a path shaped
+// like {owner}/{repo}/releases/download/{tag}/{asset}.
+func parseGitHubReleaseAsset(path string) (githubReleaseAsset, bool) {
+	matches := githubReleaseAssetPattern.FindStringSubmatch(path)
+	if len(matches) != githubReleaseAssetMatchCount {
+		return githubReleaseAsset{}, false
+	}
+	return githubReleaseAsset{
+		owner:    matches[1],
+		repo:     matches[2],
+		tag:      matches[3],
+		filename: matches[4],
+	}, true
+}
+
+// handleReleaseAsset fetches and caches a version-pinned release asset in the
+// artifact cache. The configured upstream name is part of the cache identity
+// so two upstreams serving the same path never share bytes.
+func (h *GenericHandler) handleReleaseAsset(w http.ResponseWriter, r *http.Request, repository, upstreamURL, path string, asset githubReleaseAsset) {
+	name := asset.owner + "/" + asset.repo
+	downloadURL := upstreamURL + "/" + path
+	cacheFilename := repository + "/" + asset.filename
+
+	h.proxy.Logger.Info("generic release asset download",
+		"repository", repository, "name", name, "version", asset.tag, "filename", asset.filename)
+
+	result, err := h.proxy.GetOrFetchArtifactFromURL(
+		r.Context(), genericEcosystem, name, asset.tag, cacheFilename, downloadURL)
+	if err != nil {
+		h.proxy.serveArtifactError(w, err, "failed to fetch release asset")
+		return
+	}
+
+	if result.Artifact.MediaType == "" {
+		result.Artifact.MediaType = "application/octet-stream"
+	}
+	serveArtifact(w, r.Method, result)
+}
+
+// handleMetadata serves any other path through the metadata cache. The query
+// string is forwarded and is part of the cache identity. A fixed Accept header
+// keeps all clients on one cached representation.
+func (h *GenericHandler) handleMetadata(w http.ResponseWriter, r *http.Request, repository, upstreamURL, path string) {
+	target := upstreamURL + "/" + path
+	if r.URL.RawQuery != "" {
+		target += "?" + r.URL.RawQuery
+	}
+
+	h.proxy.ProxyCached(w, r, target, genericEcosystem,
+		h.metadataCacheKey(repository, upstreamURL, path, r.URL.RawQuery), genericAcceptAny)
+}
+
+// metadataCacheKey derives the metadata cache key from the upstream name, its
+// URL, the request path and query. Hashing the identity keeps distinct
+// upstreams from sharing entries and drops cached entries when an upstream is
+// repointed, mirroring APKHandler.metadataCacheKey.
+func (h *GenericHandler) metadataCacheKey(repository, upstreamURL, path, query string) string {
+	identity := repository + "\x00" + upstreamURL + "\x00" + path + "\x00" + query
+	digest := sha256.Sum256([]byte(identity))
+	return hex.EncodeToString(digest[:])
+}

internal/handler/generic_test.go

@@ -0,0 +1,311 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	upstreamhttp "github.com/git-pkgs/proxy/internal/httpclient"
+	"github.com/git-pkgs/registries/fetch"
+)
+
+const testReleaseAssetPath = "/jqlang/jq/releases/download/jq-1.7.1/jq-linux-amd64"
+
+func TestParseGitHubReleaseAsset(t *testing.T) {
+	tests := []struct {
+		path string
+		want githubReleaseAsset
+		ok   bool
+	}{
+		{
+			"jqlang/jq/releases/download/jq-1.7.1/jq-linux-amd64",
+			githubReleaseAsset{owner: "jqlang", repo: "jq", tag: "jq-1.7.1", filename: "jq-linux-amd64"},
+			true,
+		},
+		{
+			"cli/cli/releases/download/v2.63.2/gh_2.63.2_linux_amd64.tar.gz",
+			githubReleaseAsset{owner: "cli", repo: "cli", tag: "v2.63.2", filename: "gh_2.63.2_linux_amd64.tar.gz"},
+			true,
+		},
+		// Mutable: resolves to whatever is latest today.
+		{"jqlang/jq/releases/latest/download/jq-linux-amd64", githubReleaseAsset{}, false},
+		// API lookups and tag listings are not assets.
+		{"repos/jqlang/jq/releases/tags/jq-1.7.1", githubReleaseAsset{}, false},
+		{"jqlang/jq/releases/tag/jq-1.7.1", githubReleaseAsset{}, false},
+		// Source archives are a different shape.
+		{"jqlang/jq/archive/refs/tags/jq-1.7.1.tar.gz", githubReleaseAsset{}, false},
+		// Extra or missing segments.
+		{"jqlang/jq/releases/download/jq-1.7.1", githubReleaseAsset{}, false},
+		{"jqlang/jq/releases/download/jq-1.7.1/dir/asset", githubReleaseAsset{}, false},
+		{"", githubReleaseAsset{}, false},
+	}
+
+	for _, tt := range tests {
+		got, ok := parseGitHubReleaseAsset(tt.path)
+		if ok != tt.ok || got != tt.want {
+			t.Errorf("parseGitHubReleaseAsset(%q) = (%+v, %v), want (%+v, %v)", tt.path, got, ok, tt.want, tt.ok)
+		}
+	}
+}
+
+func TestGenericHandler_RejectsUnknownUpstreamAndBadPaths(t *testing.T) {
+	h := NewGenericHandler(testProxy(), map[string]string{"github": "https://github.com"})
+
+	tests := []struct {
+		name   string
+		method string
+		target string
+		want   int
+	}{
+		{"unknown upstream", http.MethodGet, "/gitlab/owner/repo/releases/download/v1/asset", http.StatusNotFound},
+		{"missing path", http.MethodGet, "/github", http.StatusNotFound},
+		{"missing path with slash", http.MethodGet, "/github/", http.StatusNotFound},
+		{"traversal", http.MethodGet, "/github/../etc/passwd", http.StatusBadRequest},
+		{"encoded traversal", http.MethodGet, "/github/%2e%2e/etc/passwd", http.StatusBadRequest},
+		{"post", http.MethodPost, "/github/owner/repo/releases/download/v1/asset", http.StatusMethodNotAllowed},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			h.Routes().ServeHTTP(w, httptest.NewRequest(tt.method, tt.target, nil))
+			if w.Code != tt.want {
+				t.Errorf("status = %d, want %d", w.Code, tt.want)
+			}
+		})
+	}
+}
+
+func TestGenericHandler_ReleaseAssetIsCachedAndServedWhenUpstreamDown(t *testing.T) {
+	asset := []byte("jq binary bytes")
+	var available atomic.Bool
+	available.Store(true)
+	var upstreamRequests atomic.Int32
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !available.Load() {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		if r.URL.Path != testReleaseAssetPath {
+			http.NotFound(w, r)
+			return
+		}
+		upstreamRequests.Add(1)
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = w.Write(asset)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(upstream.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewGenericHandler(proxy, map[string]string{"github": upstream.URL})
+
+	w := serveGenericRequest(h, "/github"+testReleaseAssetPath)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.String(); got != string(asset) {
+		t.Errorf("body = %q, want %q", got, asset)
+	}
+	if got := upstreamRequests.Load(); got != 1 {
+		t.Fatalf("upstream requests = %d, want 1", got)
+	}
+
+	// Second request must be served from cache, even with the upstream down.
+	available.Store(false)
+	w = serveGenericRequest(h, "/github"+testReleaseAssetPath)
+	if w.Code != http.StatusOK {
+		t.Fatalf("cached: status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.String(); got != string(asset) {
+		t.Errorf("cached: body = %q, want %q", got, asset)
+	}
+	if got := upstreamRequests.Load(); got != 1 {
+		t.Errorf("upstream requests after cache hit = %d, want 1", got)
+	}
+
+	// HEAD is answered from the same cache entry without a body.
+	w = httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodHead, "/github"+testReleaseAssetPath, nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("HEAD: status = %d, want 200", w.Code)
+	}
+	if w.Body.Len() != 0 {
+		t.Errorf("HEAD: body length = %d, want 0", w.Body.Len())
+	}
+}
+
+func TestGenericHandler_ReleaseAssetNotFoundIsNotCached(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.NotFound(w, r)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(upstream.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewGenericHandler(proxy, map[string]string{"github": upstream.URL})
+	w := serveGenericRequest(h, "/github"+testReleaseAssetPath)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want 404: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestGenericHandler_MetadataForwardsQueryAndServesStaleOnThrottle(t *testing.T) {
+	const apiPath = "/repos/jqlang/jq/releases/tags/jq-1.7.1"
+	body := `{"tag_name":"jq-1.7.1"}`
+	var throttled atomic.Bool
+	var gotQuery string
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != apiPath {
+			http.NotFound(w, r)
+			return
+		}
+		gotQuery = r.URL.RawQuery
+		if throttled.Load() {
+			w.Header().Set("Retry-After", "60")
+			http.Error(w, `{"message":"API rate limit exceeded"}`, http.StatusTooManyRequests)
+			return
+		}
+		w.Header().Set("Content-Type", "application/vnd.github+json")
+		w.Header().Set("ETag", `"v1"`)
+		_, _ = w.Write([]byte(body))
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.CacheMetadata = true
+	// A tiny TTL so the second request is past freshness and has to consult
+	// the upstream, and the served copy is marked stale.
+	proxy.MetadataTTL = time.Millisecond
+
+	h := NewGenericHandler(proxy, map[string]string{"github-api": upstream.URL})
+
+	req := httptest.NewRequest(http.MethodGet, "/github-api"+apiPath+"?per_page=1", nil)
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.String(); got != body {
+		t.Errorf("body = %q, want %q", got, body)
+	}
+	if gotQuery != "per_page=1" {
+		t.Errorf("upstream query = %q, want %q", gotQuery, "per_page=1")
+	}
+	if ct := w.Header().Get("Content-Type"); ct != "application/vnd.github+json" {
+		t.Errorf("Content-Type = %q, want upstream's", ct)
+	}
+
+	// The upstream now throttles us: the cached body must be served stale
+	// rather than the 429 being passed through.
+	throttled.Store(true)
+	time.Sleep(5 * time.Millisecond)
+	w = httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("throttled: status = %d, want 200 stale: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.String(); got != body {
+		t.Errorf("throttled: body = %q, want cached %q", got, body)
+	}
+	if warning := w.Header().Get("Warning"); !strings.Contains(warning, "110") {
+		t.Errorf("throttled: Warning = %q, want a 110 stale warning", warning)
+	}
+}
+
+func TestGenericHandler_DistinctUpstreamsDoNotShareCache(t *testing.T) {
+	first := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte("from first"))
+	}))
+	defer first.Close()
+	second := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte("from second"))
+	}))
+	defer second.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(first.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewGenericHandler(proxy, map[string]string{"one": first.URL, "two": second.URL})
+
+	w := serveGenericRequest(h, "/one"+testReleaseAssetPath)
+	if got := w.Body.String(); got != "from first" {
+		t.Fatalf("one: body = %q, want %q", got, "from first")
+	}
+	w = serveGenericRequest(h, "/two"+testReleaseAssetPath)
+	if got := w.Body.String(); got != "from second" {
+		t.Fatalf("two: body = %q, want %q (must not reuse the first upstream's cache entry)", got, "from second")
+	}
+}
+
+func TestGenericHandler_UpstreamAuthIsScopedToTheConfiguredHost(t *testing.T) {
+	asset := []byte("private asset")
+	var storageAuth atomic.Value
+	storageAuth.Store("unset")
+
+	// The object store the release host redirects to must never see the
+	// token configured for the release host.
+	objectStore := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		storageAuth.Store(r.Header.Get("Authorization"))
+		_, _ = w.Write(asset)
+	}))
+	defer objectStore.Close()
+
+	var releaseAuth string
+	releaseHost := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		releaseAuth = r.Header.Get("Authorization")
+		if releaseAuth != "Bearer github-token" {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		http.Redirect(w, r, objectStore.URL+"/signed"+r.URL.Path, http.StatusFound)
+	}))
+	defer releaseHost.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	authClient := &http.Client{Transport: upstreamhttp.NewTransport(http.DefaultTransport,
+		upstreamhttp.AuthFunc(func(url string) (string, string) {
+			if strings.HasPrefix(url, releaseHost.URL) {
+				return "Authorization", "Bearer github-token"
+			}
+			return "", ""
+		}))}
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(authClient), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewGenericHandler(proxy, map[string]string{"github": releaseHost.URL})
+	w := serveGenericRequest(h, "/github"+testReleaseAssetPath)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.String(); got != string(asset) {
+		t.Errorf("body = %q, want %q", got, asset)
+	}
+	if releaseAuth != "Bearer github-token" {
+		t.Errorf("release host Authorization = %q, want the configured token", releaseAuth)
+	}
+	if got := storageAuth.Load(); got != "" {
+		t.Errorf("object store Authorization = %q, want none after the cross-host redirect", got)
+	}
+}
+
+func serveGenericRequest(h *GenericHandler, target string) *httptest.ResponseRecorder {
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodGet, target, nil))
+	return w
+}

internal/handler/go.go

@@ -30,6 +30,13 @@ func NewGoHandler(proxy *Proxy, proxyURL string) *GoHandler {
 	}
 }
 
+// NewGoHandlerWithUpstream creates a Go module handler with a custom upstream.
+func NewGoHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *GoHandler {
+	h := NewGoHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, goUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for Go proxy requests.
 func (h *GoHandler) Routes() http.Handler {
 	// Go module paths can contain slashes, so just use the handler directly
@@ -101,12 +108,19 @@ func (h *GoHandler) handleDownload(w http.ResponseWriter, r *http.Request, modul
 	h.proxy.Logger.Info("go module download request",
 		"module", decodedModule, "version", version)
 
-	result, err := h.proxy.GetOrFetchArtifact(r.Context(), "golang", decodedModule, version, filename)
+	downloadURL := h.upstreamURL + r.URL.Path
+	result, err := h.proxy.GetOrFetchArtifactFromURL(
+		r.Context(), "golang", decodedModule, version, filename, downloadURL,
+	)
 	if err != nil {
 		if errors.Is(err, fetch.ErrNotFound) {
 			http.Error(w, "not found", http.StatusNotFound)
 			return
 		}
+		if errors.Is(err, ErrArtifactBlocked) {
+			http.Error(w, err.Error(), http.StatusForbidden)
+			return
+		}
 		h.proxy.Logger.Error("failed to get artifact", "error", err)
 		http.Error(w, "failed to fetch module", http.StatusBadGateway)
 		return

internal/handler/gradle.go

@@ -93,7 +93,7 @@ func (h *GradleBuildCacheHandler) cacheStoragePath(key string) string {
 
 func (h *GradleBuildCacheHandler) handleGetOrHead(w http.ResponseWriter, r *http.Request, key string) {
 	storagePath := h.cacheStoragePath(key)
-	w.Header().Set("Content-Type", gradleBuildCacheContentType)
+	w.Header().Set(headerContentType, gradleBuildCacheContentType)
 
 	if r.Method == http.MethodHead {
 		existsStart := time.Now()
@@ -118,7 +118,7 @@ func (h *GradleBuildCacheHandler) handleGetOrHead(w http.ResponseWriter, r *http
 		if err != nil {
 			metrics.RecordStorageError("read")
 		} else if size >= 0 {
-			w.Header().Set("Content-Length", strconv.FormatInt(size, 10))
+			w.Header().Set(headerContentLength, strconv.FormatInt(size, 10))
 		}
 
 		w.WriteHeader(http.StatusOK)
@@ -171,8 +171,8 @@ func (h *GradleBuildCacheHandler) handlePut(w http.ResponseWriter, r *http.Reque
 		return
 	}
 
-	w.Header().Set("Content-Length", "0")
-	w.Header().Set("ETag", `"`+hash+`"`)
+	w.Header().Set(headerContentLength, "0")
+	w.Header().Set(headerETag, `"`+hash+`"`)
 
 	w.WriteHeader(http.StatusCreated)
 }

internal/handler/handler_test.go

@@ -3,6 +3,7 @@ package handler
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
 	"database/sql"
 	"errors"
 	"io"
@@ -10,18 +11,26 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 
+	"github.com/git-pkgs/artifacts"
 	"github.com/git-pkgs/proxy/internal/config"
 	"github.com/git-pkgs/proxy/internal/database"
+	"github.com/git-pkgs/proxy/internal/metrics"
 	"github.com/git-pkgs/proxy/internal/storage"
 	"github.com/git-pkgs/purl"
 	"github.com/git-pkgs/registries/fetch"
+	"github.com/opencontainers/go-digest"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/testutil"
+	dto "github.com/prometheus/client_model/go"
 )
 
 // mockStorage implements storage.Storage for testing.
 type mockStorage struct {
+	mu        sync.Mutex
 	files     map[string][]byte
 	storeErr  error
 	openErr   error
@@ -34,6 +43,8 @@ func newMockStorage() *mockStorage {
 }
 
 func (s *mockStorage) Store(_ context.Context, path string, r io.Reader) (int64, string, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
 	if s.storeErr != nil {
 		return 0, "", s.storeErr
 	}
@@ -42,10 +53,12 @@ func (s *mockStorage) Store(_ context.Context, path string, r io.Reader) (int64,
 		return 0, "", err
 	}
 	s.files[path] = data
-	return int64(len(data)), "fakehash123", nil
+	return int64(len(data)), sha256Hex(string(data)), nil
 }
 
 func (s *mockStorage) Open(_ context.Context, path string) (io.ReadCloser, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
 	if s.openErr != nil {
 		return nil, s.openErr
 	}
@@ -57,16 +70,28 @@ func (s *mockStorage) Open(_ context.Context, path string) (io.ReadCloser, error
 }
 
 func (s *mockStorage) Exists(_ context.Context, path string) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
 	_, ok := s.files[path]
 	return ok, nil
 }
 
-func (s *mockStorage) Delete(_ context.Context, path string) error {
+func (s *mockStorage) Delete(ctx context.Context, path string) error {
+	// Real backends (S3/GCS SDKs) fail fast on an already-cancelled
+	// context; mirror that here so tests can catch cleanup calls that
+	// forgot to detach from a cancelled client context.
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
 	delete(s.files, path)
 	return nil
 }
 
 func (s *mockStorage) Size(_ context.Context, path string) (int64, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
 	data, ok := s.files[path]
 	if !ok {
 		return 0, storage.ErrNotFound
@@ -75,6 +100,8 @@ func (s *mockStorage) Size(_ context.Context, path string) (int64, error) {
 }
 
 func (s *mockStorage) UsedSpace(_ context.Context) (int64, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
 	var total int64
 	for _, data := range s.files {
 		total += int64(len(data))
@@ -96,22 +123,30 @@ func (s *mockStorage) URL() string { return "mem://" }
 
 func (s *mockStorage) Close() error { return nil }
 
-// mockFetcher implements fetch.FetcherInterface for testing.
+// mockFetcher implements fetch.FetcherInterface for testing. Recording is
+// locked because coalescing tests call the handler from many goroutines; tests
+// read the recorded fields only after those calls have returned.
 type mockFetcher struct {
 	artifact      *fetch.Artifact
 	fetchErr      error
 	fetchErrByURL map[string]error
+
+	mu            sync.Mutex
 	fetchCalled   bool
 	fetchedURL    string
+	fetchedHeader http.Header
 }
 
 func (f *mockFetcher) Fetch(ctx context.Context, url string) (*fetch.Artifact, error) {
 	return f.FetchWithHeaders(ctx, url, nil)
 }
 
-func (f *mockFetcher) FetchWithHeaders(_ context.Context, url string, _ http.Header) (*fetch.Artifact, error) {
+func (f *mockFetcher) FetchWithHeaders(_ context.Context, url string, headers http.Header) (*fetch.Artifact, error) {
+	f.mu.Lock()
 	f.fetchCalled = true
 	f.fetchedURL = url
+	f.fetchedHeader = headers.Clone()
+	f.mu.Unlock()
 	if f.fetchErrByURL != nil {
 		if err, ok := f.fetchErrByURL[url]; ok {
 			return nil, err
@@ -147,6 +182,29 @@ func setupTestProxy(t testing.TB) (*Proxy, *database.DB, *mockStorage, *mockFetc
 	return proxy, db, store, fetcher
 }
 
+func histogramSampleCount(t testing.TB, observer prometheus.Observer) uint64 {
+	t.Helper()
+	metric, ok := observer.(prometheus.Metric)
+	if !ok {
+		t.Fatal("observer does not implement prometheus.Metric")
+	}
+	value := &dto.Metric{}
+	if err := metric.Write(value); err != nil {
+		t.Fatalf("writing Prometheus metric: %v", err)
+	}
+	return value.GetHistogram().GetSampleCount()
+}
+
+func testArtifact(content, packageURL, filename, mediaType string) artifacts.Artifact {
+	return artifacts.Artifact{
+		PURL:      packageURL,
+		Digest:    digest.Digest("sha256:" + sha256Hex(content)),
+		Size:      int64(len(content)),
+		Filename:  filename,
+		MediaType: mediaType,
+	}
+}
+
 // seedPackage creates a package, version, and cached artifact in the test DB and storage.
 func seedPackage(t testing.TB, db *database.DB, store *mockStorage, ecosystem, name, version, filename, content string) {
 	t.Helper()
@@ -171,13 +229,14 @@ func seedPackage(t testing.TB, db *database.DB, store *mockStorage, ecosystem, n
 
 	storagePath := storage.ArtifactPath(ecosystem, "", name, version, filename)
 	store.files[storagePath] = []byte(content)
+	sharedArtifact := testArtifact(content, versionPURL, filename, "application/octet-stream")
 
 	art := &database.Artifact{
 		VersionPURL: versionPURL,
 		Filename:    filename,
 		UpstreamURL: "https://example.com/" + filename,
 		StoragePath: sql.NullString{String: storagePath, Valid: true},
-		ContentHash: sql.NullString{String: "abc123", Valid: true},
+		ContentHash: sql.NullString{String: sharedArtifact.Digest.Encoded(), Valid: true},
 		Size:        sql.NullInt64{Int64: int64(len(content)), Valid: true},
 		ContentType: sql.NullString{String: "application/octet-stream", Valid: true},
 		FetchedAt:   sql.NullTime{Time: time.Now(), Valid: true},
@@ -263,16 +322,83 @@ func TestGetOrFetchArtifact_CacheHit(t *testing.T) {
 	if string(body) != "cached content" {
 		t.Errorf("got body %q, want %q", body, "cached content")
 	}
-	if result.ContentType != "application/octet-stream" {
-		t.Errorf("got content type %q, want %q", result.ContentType, "application/octet-stream")
+	if result.Artifact.MediaType != "application/octet-stream" {
+		t.Errorf("got content type %q, want %q", result.Artifact.MediaType, "application/octet-stream")
 	}
-	if result.Hash != "abc123" {
-		t.Errorf("got hash %q, want %q", result.Hash, "abc123")
+	if result.Artifact.Digest.Encoded() != sha256Hex("cached content") {
+		t.Errorf("got digest %q, want %q", result.Artifact.Digest.Encoded(), sha256Hex("cached content"))
+	}
+}
+
+func TestGetCachedArtifactRejectsMalformedIntegrityMetadata(t *testing.T) {
+	tests := []struct {
+		name               string
+		malformedHash      string
+		malformedIntegrity string
+	}{
+		{name: "content hash", malformedHash: "abc123"},
+		{name: "native integrity", malformedIntegrity: "sha512-abc123"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			assertMalformedCacheRejected(t, test.malformedHash, test.malformedIntegrity)
+		})
+	}
+}
+
+func assertMalformedCacheRejected(t *testing.T, malformedHash, malformedIntegrity string) {
+	t.Helper()
+	proxy, db, store, _ := setupTestProxy(t)
+	const (
+		packageName = "broken"
+		version     = "1.0.0"
+		filename    = "broken-1.0.0.tgz"
+	)
+	seedPackage(t, db, store, "npm", packageName, version, filename, "cached content")
+	versionPURL := purl.MakePURLString("npm", packageName, version)
+
+	if malformedHash != "" {
+		artifact, err := db.GetArtifact(versionPURL, filename)
+		if err != nil {
+			t.Fatal(err)
+		}
+		artifact.ContentHash = sql.NullString{String: malformedHash, Valid: true}
+		if err := db.UpsertArtifact(artifact); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if malformedIntegrity != "" {
+		versionRecord := &database.Version{
+			PURL:        versionPURL,
+			PackagePURL: purl.MakePURLString("npm", packageName, ""),
+			Integrity:   sql.NullString{String: malformedIntegrity, Valid: true},
+		}
+		if err := db.UpsertVersion(versionRecord); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	proxy.DirectServe = true
+	store.signedURL = "https://cache.example/broken"
+	result, err := proxy.GetCachedArtifact(context.Background(), "npm", packageName, version, filename)
+	if err != nil {
+		t.Fatalf("GetCachedArtifact: %v", err)
+	}
+	if result != nil {
+		t.Errorf("GetCachedArtifact = %+v, want nil", result)
+	}
+	artifact, err := db.GetArtifact(versionPURL, filename)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if artifact.StoragePath.Valid {
+		t.Error("unusable cache record retained its storage path")
 	}
 }
 
 func TestGetOrFetchArtifact_CacheMiss_NoPackage(t *testing.T) {
 	proxy, _, _, fetcher := setupTestProxy(t)
+	missesBefore := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("npm"))
 
 	// The resolver will fail because "nonexistent" isn't a real package,
 	// but we're testing that it tries to fetch (doesn't return from cache).
@@ -282,6 +408,10 @@ func TestGetOrFetchArtifact_CacheMiss_NoPackage(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for uncached package")
 	}
+	missesAfter := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("npm"))
+	if diff := missesAfter - missesBefore; diff != 1 {
+		t.Errorf("cache misses delta = %.0f, want 1", diff)
+	}
 }
 
 func TestGetOrFetchArtifactFromURL_CacheMiss_StorageMissing(t *testing.T) {
@@ -297,7 +427,7 @@ func TestGetOrFetchArtifactFromURL_CacheMiss_StorageMissing(t *testing.T) {
 		Filename:    "missing-1.0.0.tgz",
 		UpstreamURL: "https://example.com/missing.tgz",
 		StoragePath: sql.NullString{String: "nonexistent/path.tgz", Valid: true},
-		ContentHash: sql.NullString{String: "hash", Valid: true},
+		ContentHash: sql.NullString{String: sha256Hex("missing content"), Valid: true},
 		Size:        sql.NullInt64{Int64: 100, Valid: true},
 		ContentType: sql.NullString{String: "application/octet-stream", Valid: true},
 		FetchedAt:   sql.NullTime{Time: time.Now(), Valid: true},
@@ -330,6 +460,28 @@ func TestGetOrFetchArtifactFromURL_CacheMiss_StorageMissing(t *testing.T) {
 	}
 }
 
+func TestArtifactCacheRejectsUnsupportedPackageIdentity(t *testing.T) {
+	proxy, _, _, fetcher := setupTestProxy(t)
+
+	_, err := proxy.GetCachedArtifact(
+		context.Background(), "swift", "apple/example", "1.2.3", "example-1.2.3.zip",
+	)
+	if !errors.Is(err, errUnsupportedPackageIdentity) {
+		t.Fatalf("GetCachedArtifact() error = %v, want unsupported package identity", err)
+	}
+
+	_, err = proxy.GetOrFetchArtifactFromURL(
+		context.Background(), "swift", "apple/example", "1.2.3", "example-1.2.3.zip",
+		"https://registry.example/apple/example/1.2.3.zip",
+	)
+	if !errors.Is(err, errUnsupportedPackageIdentity) {
+		t.Fatalf("GetOrFetchArtifactFromURL() error = %v, want unsupported package identity", err)
+	}
+	if fetcher.fetchCalled {
+		t.Error("unsupported package identity reached the artifact fetcher")
+	}
+}
+
 func TestGetOrFetchArtifact_DirectServe_Redirect(t *testing.T) {
 	proxy, db, store, fetcher := setupTestProxy(t)
 	seedPackage(t, db, store, "npm", "lodash", "4.17.21", "lodash-4.17.21.tgz", "cached content")
@@ -499,8 +651,10 @@ func TestServeArtifact_Redirect(t *testing.T) {
 	w := httptest.NewRecorder()
 	ServeArtifact(w, &CacheResult{
 		RedirectURL: "https://bucket.s3.amazonaws.com/file?sig=abc",
-		Hash:        "abc123",
-		Cached:      true,
+		Artifact: artifacts.Artifact{
+			Digest: digest.Digest("sha256:" + strings.Repeat("a", sha256.Size*2)),
+		},
+		Cached: true,
 	})
 
 	if w.Code != http.StatusFound {
@@ -509,8 +663,8 @@ func TestServeArtifact_Redirect(t *testing.T) {
 	if loc := w.Header().Get("Location"); loc != "https://bucket.s3.amazonaws.com/file?sig=abc" {
 		t.Errorf("Location = %q", loc)
 	}
-	if etag := w.Header().Get("ETag"); etag != `"abc123"` {
-		t.Errorf("ETag = %q, want %q", etag, `"abc123"`)
+	if etag := w.Header().Get("ETag"); etag != `"`+strings.Repeat("a", sha256.Size*2)+`"` {
+		t.Errorf("ETag = %q", etag)
 	}
 	if cl := w.Header().Get("Content-Length"); cl != "" {
 		t.Errorf("Content-Length should not be set on redirect, got %q", cl)
@@ -520,10 +674,13 @@ func TestServeArtifact_Redirect(t *testing.T) {
 func TestServeArtifact_Stream(t *testing.T) {
 	w := httptest.NewRecorder()
 	ServeArtifact(w, &CacheResult{
-		Reader:      io.NopCloser(strings.NewReader("payload")),
-		Size:        7,
-		ContentType: "application/octet-stream",
-		Hash:        "abc123",
+		Reader: io.NopCloser(strings.NewReader("payload")),
+		Artifact: testArtifact(
+			"payload",
+			"pkg:npm/example@1.0.0",
+			"example.tgz",
+			"application/octet-stream",
+		),
 	})
 
 	if w.Code != http.StatusOK {
@@ -540,6 +697,7 @@ func TestServeArtifact_Stream(t *testing.T) {
 func TestGetOrFetchArtifactFromURL_CacheHit(t *testing.T) {
 	proxy, db, store, fetcher := setupTestProxy(t)
 	seedPackage(t, db, store, "pypi", "requests", "2.28.0", "requests-2.28.0.tar.gz", "pypi content")
+	missesBefore := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("pypi"))
 
 	result, err := proxy.GetOrFetchArtifactFromURL(context.Background(), "pypi", "requests", "2.28.0", "requests-2.28.0.tar.gz", "https://pypi.org/files/requests-2.28.0.tar.gz")
 	if err != nil {
@@ -553,10 +711,18 @@ func TestGetOrFetchArtifactFromURL_CacheHit(t *testing.T) {
 	if fetcher.fetchCalled {
 		t.Error("fetcher should not be called on cache hit")
 	}
+	missesAfter := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("pypi"))
+	if diff := missesAfter - missesBefore; diff != 0 {
+		t.Errorf("cache misses delta = %.0f, want 0", diff)
+	}
 }
 
 func TestGetOrFetchArtifactFromURL_CacheMiss(t *testing.T) {
 	proxy, _, store, fetcher := setupTestProxy(t)
+	missesBefore := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("pypi"))
+	fetchesBefore := histogramSampleCount(t, metrics.UpstreamFetchDuration.WithLabelValues("pypi"))
+	writesBefore := histogramSampleCount(t, metrics.StorageOperationDuration.WithLabelValues("write"))
+	readsBefore := histogramSampleCount(t, metrics.StorageOperationDuration.WithLabelValues("read"))
 
 	fetcher.artifact = &fetch.Artifact{
 		Body:        io.NopCloser(strings.NewReader("fetched content")),
@@ -583,17 +749,43 @@ func TestGetOrFetchArtifactFromURL_CacheMiss(t *testing.T) {
 	if string(body) != "fetched content" {
 		t.Errorf("got body %q, want %q", body, "fetched content")
 	}
+	if err := result.Artifact.Validate(); err != nil {
+		t.Errorf("Artifact.Validate() error = %v", err)
+	}
+	if result.Artifact.PURL != "pkg:pypi/newpkg@1.0.0" {
+		t.Errorf("PURL = %q", result.Artifact.PURL)
+	}
+	if result.Artifact.Size != int64(len("fetched content")) {
+		t.Errorf("Size = %d", result.Artifact.Size)
+	}
+	if result.Artifact.MediaType != "application/gzip" {
+		t.Errorf("MediaType = %q", result.Artifact.MediaType)
+	}
 
 	// Verify it was stored
 	storagePath := storage.ArtifactPath("pypi", "", "newpkg", "1.0.0", "newpkg-1.0.0.tar.gz")
 	if _, ok := store.files[storagePath]; !ok {
 		t.Error("artifact was not stored in storage")
 	}
+	missesAfter := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("pypi"))
+	if diff := missesAfter - missesBefore; diff != 1 {
+		t.Errorf("cache misses delta = %.0f, want 1", diff)
+	}
+	if diff := histogramSampleCount(t, metrics.UpstreamFetchDuration.WithLabelValues("pypi")) - fetchesBefore; diff != 1 {
+		t.Errorf("upstream fetch observations delta = %d, want 1", diff)
+	}
+	if diff := histogramSampleCount(t, metrics.StorageOperationDuration.WithLabelValues("write")) - writesBefore; diff != 1 {
+		t.Errorf("storage write observations delta = %d, want 1", diff)
+	}
+	if diff := histogramSampleCount(t, metrics.StorageOperationDuration.WithLabelValues("read")) - readsBefore; diff != 1 {
+		t.Errorf("storage read observations delta = %d, want 1", diff)
+	}
 }
 
 func TestGetOrFetchArtifactFromURL_FetchError(t *testing.T) {
 	proxy, _, _, fetcher := setupTestProxy(t)
 	fetcher.fetchErr = errors.New("connection refused")
+	errorsBefore := testutil.ToFloat64(metrics.UpstreamErrors.WithLabelValues("pypi", "fetch_failed"))
 
 	_, err := proxy.GetOrFetchArtifactFromURL(context.Background(), "pypi", "fail", "1.0.0", "fail-1.0.0.tar.gz", "https://pypi.org/files/fail-1.0.0.tar.gz")
 	if err == nil {
@@ -602,11 +794,15 @@ func TestGetOrFetchArtifactFromURL_FetchError(t *testing.T) {
 	if !strings.Contains(err.Error(), "fetching from upstream") {
 		t.Errorf("expected upstream error, got: %v", err)
 	}
+	if diff := testutil.ToFloat64(metrics.UpstreamErrors.WithLabelValues("pypi", "fetch_failed")) - errorsBefore; diff != 1 {
+		t.Errorf("upstream errors delta = %.0f, want 1", diff)
+	}
 }
 
 func TestGetOrFetchArtifactFromURL_StoreError(t *testing.T) {
 	proxy, _, store, fetcher := setupTestProxy(t)
 	store.storeErr = errors.New("disk full")
+	errorsBefore := testutil.ToFloat64(metrics.StorageErrors.WithLabelValues("write"))
 	fetcher.artifact = &fetch.Artifact{
 		Body:        io.NopCloser(strings.NewReader("data")),
 		ContentType: "application/gzip",
@@ -619,15 +815,16 @@ func TestGetOrFetchArtifactFromURL_StoreError(t *testing.T) {
 	if !strings.Contains(err.Error(), "storing artifact") {
 		t.Errorf("expected storage error, got: %v", err)
 	}
+	if diff := testutil.ToFloat64(metrics.StorageErrors.WithLabelValues("write")) - errorsBefore; diff != 1 {
+		t.Errorf("storage errors delta = %.0f, want 1", diff)
+	}
 }
 
 func TestServeArtifact(t *testing.T) {
 	result := &CacheResult{
-		Reader:      io.NopCloser(strings.NewReader("file contents")),
-		Size:        13,
-		ContentType: "application/gzip",
-		Hash:        "sha256abc",
-		Cached:      true,
+		Reader:   io.NopCloser(strings.NewReader("file contents")),
+		Artifact: testArtifact("file contents", "pkg:npm/example@1.0.0", "example.tgz", "application/gzip"),
+		Cached:   true,
 	}
 
 	w := httptest.NewRecorder()
@@ -642,8 +839,9 @@ func TestServeArtifact(t *testing.T) {
 	if w.Header().Get("Content-Length") != "13" {
 		t.Errorf("Content-Length = %q, want %q", w.Header().Get("Content-Length"), "13")
 	}
-	if w.Header().Get("ETag") != `"sha256abc"` {
-		t.Errorf("ETag = %q, want %q", w.Header().Get("ETag"), `"sha256abc"`)
+	wantETag := `"` + result.Artifact.Digest.Encoded() + `"`
+	if w.Header().Get("ETag") != wantETag {
+		t.Errorf("ETag = %q, want %q", w.Header().Get("ETag"), wantETag)
 	}
 	if w.Body.String() != "file contents" {
 		t.Errorf("body = %q, want %q", w.Body.String(), "file contents")
@@ -878,6 +1076,8 @@ func TestProxyCached_NoValidators_OmitsHeaders(t *testing.T) {
 }
 
 func TestFetchOrCacheMetadata_TTL_ServesFreshFromCache(t *testing.T) {
+	hitsBefore := testutil.ToFloat64(metrics.CacheHits.WithLabelValues("test"))
+	missesBefore := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("test"))
 	upstreamHits := 0
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		upstreamHits++
@@ -904,6 +1104,12 @@ func TestFetchOrCacheMetadata_TTL_ServesFreshFromCache(t *testing.T) {
 	if upstreamHits != 1 {
 		t.Fatalf("expected 1 upstream hit, got %d", upstreamHits)
 	}
+	if diff := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("test")) - missesBefore; diff != 1 {
+		t.Errorf("cache misses delta after first request = %.0f, want 1", diff)
+	}
+	if diff := testutil.ToFloat64(metrics.CacheHits.WithLabelValues("test")) - hitsBefore; diff != 0 {
+		t.Errorf("cache hits delta after first request = %.0f, want 0", diff)
+	}
 
 	// Second request within TTL should serve from cache without hitting upstream
 	body, _, err = proxy.FetchOrCacheMetadata(ctx, "test", "ttl-pkg", upstream.URL+"/pkg")
@@ -916,9 +1122,16 @@ func TestFetchOrCacheMetadata_TTL_ServesFreshFromCache(t *testing.T) {
 	if upstreamHits != 1 {
 		t.Errorf("expected upstream to still be hit only once, got %d", upstreamHits)
 	}
+	if diff := testutil.ToFloat64(metrics.CacheHits.WithLabelValues("test")) - hitsBefore; diff != 1 {
+		t.Errorf("cache hits delta after second request = %.0f, want 1", diff)
+	}
+	if diff := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("test")) - missesBefore; diff != 1 {
+		t.Errorf("cache misses delta after second request = %.0f, want 1", diff)
+	}
 }
 
 func TestFetchOrCacheMetadata_TTL_Zero_AlwaysRevalidates(t *testing.T) {
+	missesBefore := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("test"))
 	upstreamHits := 0
 	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		upstreamHits++
@@ -947,6 +1160,40 @@ func TestFetchOrCacheMetadata_TTL_Zero_AlwaysRevalidates(t *testing.T) {
 	if upstreamHits != 2 {
 		t.Errorf("expected 2 upstream hits with TTL=0, got %d", upstreamHits)
 	}
+	missesAfter := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues("test"))
+	if diff := missesAfter - missesBefore; diff != 2 {
+		t.Errorf("cache misses delta = %.0f, want 2", diff)
+	}
+}
+
+func TestFetchOrCacheMetadata_CacheDisabledDoesNotRecordMetrics(t *testing.T) {
+	const ecosystem = "metadata-disabled"
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"v":1}`))
+	}))
+	t.Cleanup(upstream.Close)
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+
+	hitsBefore := testutil.ToFloat64(metrics.CacheHits.WithLabelValues(ecosystem))
+	missesBefore := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues(ecosystem))
+
+	_, _, err := proxy.FetchOrCacheMetadata(context.Background(), ecosystem, "pkg", upstream.URL+"/pkg")
+	if err != nil {
+		t.Fatalf("fetch metadata: %v", err)
+	}
+
+	hitsAfter := testutil.ToFloat64(metrics.CacheHits.WithLabelValues(ecosystem))
+	missesAfter := testutil.ToFloat64(metrics.CacheMisses.WithLabelValues(ecosystem))
+	if diff := hitsAfter - hitsBefore; diff != 0 {
+		t.Errorf("cache hits delta = %.0f, want 0", diff)
+	}
+	if diff := missesAfter - missesBefore; diff != 0 {
+		t.Errorf("cache misses delta = %.0f, want 0", diff)
+	}
 }
 
 func TestProxyCached_StaleWarningHeader(t *testing.T) {

internal/handler/helm.go

@@ -0,0 +1,364 @@
+package handler
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"path"
+	"strings"
+	"time"
+
+	"gopkg.in/yaml.v3"
+)
+
+const (
+	helmMetadataEcosystem = "helm"
+	helmIndexFilename     = "index.yaml"
+	sha256HexLength       = 64
+)
+
+// HelmHandler serves read-only HTTP Helm chart repositories. Each configured
+// repository is mounted at /helm/{repository}/.
+type HelmHandler struct {
+	proxy        *Proxy
+	proxyURL     string
+	repositories map[string]string
+}
+
+// NewHelmHandler creates a Helm chart repository protocol handler.
+func NewHelmHandler(proxy *Proxy, proxyURL string, repositories map[string]string) *HelmHandler {
+	h := &HelmHandler{
+		proxyURL:     strings.TrimSuffix(proxyURL, "/"),
+		repositories: make(map[string]string, len(repositories)),
+		proxy:        proxy,
+	}
+	for name, repositoryURL := range repositories {
+		h.repositories[name] = strings.TrimSuffix(repositoryURL, "/")
+	}
+	return h
+}
+
+// Routes returns the HTTP handler for Helm chart repository requests.
+func (h *HelmHandler) Routes() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /{repository}/index.yaml", h.handleIndex)
+	mux.HandleFunc("GET /{repository}/charts/{digest}/{filename}", h.handleChart)
+	return mux
+}
+
+func (h *HelmHandler) handleIndex(w http.ResponseWriter, r *http.Request) {
+	repository, upstreamURL, ok := h.repositoryForRequest(r)
+	if !ok {
+		http.NotFound(w, r)
+		return
+	}
+
+	body, contentType, err := h.fetchIndex(r, repository, upstreamURL)
+	if err != nil {
+		h.serveIndexError(w, err)
+		return
+	}
+
+	rewritten, err := h.rewriteIndex(repository, upstreamURL, body)
+	if err != nil {
+		h.proxy.Logger.Warn("failed to rewrite Helm index", "repository", repository, "error", err)
+		http.Error(w, "invalid Helm repository index", http.StatusBadGateway)
+		return
+	}
+
+	h.proxy.writeMetadataCachedResponse(w, r, helmMetadataEcosystem, h.indexCacheKey(repository, upstreamURL), rewritten, contentType)
+}
+
+func (h *HelmHandler) handleChart(w http.ResponseWriter, r *http.Request) {
+	repository, upstreamURL, ok := h.repositoryForRequest(r)
+	if !ok {
+		http.NotFound(w, r)
+		return
+	}
+
+	digest, ok := normalizeHelmDigest(r.PathValue("digest"))
+	filename := r.PathValue("filename")
+	if !ok || filename == "" || strings.Contains(filename, "/") || containsPathTraversal(filename) {
+		http.Error(w, "invalid chart request", http.StatusBadRequest)
+		return
+	}
+
+	cached, err := h.proxy.GetCachedArtifact(r.Context(), helmMetadataEcosystem, repository, digest, filename)
+	if err != nil {
+		h.proxy.Logger.Error("failed to check Helm chart cache", "error", err)
+		http.Error(w, "failed to check chart cache", http.StatusInternalServerError)
+		return
+	}
+	if cached != nil {
+		h.serveChart(w, r, repository, digest, filename, cached)
+		return
+	}
+
+	body, _, err := h.fetchIndex(r, repository, upstreamURL)
+	if err != nil {
+		h.serveIndexError(w, err)
+		return
+	}
+
+	downloadURL, err := h.findChartDownload(upstreamURL, body, digest, filename)
+	if err != nil {
+		if errors.Is(err, errHelmChartNotFound) {
+			http.NotFound(w, r)
+			return
+		}
+		h.proxy.Logger.Warn("failed to read Helm index", "repository", repository, "error", err)
+		http.Error(w, "invalid Helm repository index", http.StatusBadGateway)
+		return
+	}
+
+	result, err := h.proxy.GetOrFetchArtifactFromURL(
+		r.Context(), helmMetadataEcosystem, repository, digest, filename, downloadURL)
+	if err != nil {
+		h.proxy.serveArtifactError(w, err, "failed to fetch chart")
+		return
+	}
+	h.serveChart(w, r, repository, digest, filename, result)
+}
+
+func (h *HelmHandler) serveChart(w http.ResponseWriter, r *http.Request, repository, digest, filename string, result *CacheResult) {
+	if !strings.EqualFold(result.Artifact.Digest.Encoded(), digest) {
+		if result.Reader != nil {
+			_ = result.Reader.Close()
+		}
+		if clearErr := h.proxy.ClearCachedArtifact(r.Context(), helmMetadataEcosystem, repository, digest, filename); clearErr != nil {
+			h.proxy.Logger.Warn("failed to clear Helm chart with invalid digest", "error", clearErr)
+		}
+		http.Error(w, "chart digest verification failed", http.StatusBadGateway)
+		return
+	}
+
+	if result.Artifact.MediaType == "" {
+		w.Header().Set(headerContentType, "application/gzip")
+	}
+	ServeArtifact(w, result)
+}
+
+func (h *HelmHandler) repositoryForRequest(r *http.Request) (name, upstreamURL string, ok bool) {
+	name = r.PathValue("repository")
+	upstreamURL, ok = h.repositories[name]
+	return name, upstreamURL, ok
+}
+
+func (h *HelmHandler) fetchIndex(r *http.Request, repository, upstreamURL string) ([]byte, string, error) {
+	return h.proxy.FetchOrCacheMetadata(
+		r.Context(),
+		helmMetadataEcosystem,
+		h.indexCacheKey(repository, upstreamURL),
+		upstreamURL+"/"+helmIndexFilename,
+		"application/x-yaml, text/yaml;q=0.9, */*;q=0.1",
+	)
+}
+
+func (h *HelmHandler) indexCacheKey(repository, upstreamURL string) string {
+	identity := repository + "\x00" + upstreamURL
+	digest := sha256.Sum256([]byte(identity))
+	return hex.EncodeToString(digest[:])
+}
+
+func (h *HelmHandler) serveIndexError(w http.ResponseWriter, err error) {
+	if errors.Is(err, ErrUpstreamNotFound) {
+		http.Error(w, "Helm repository not found", http.StatusNotFound)
+		return
+	}
+	h.proxy.Logger.Error("failed to fetch Helm index", "error", err)
+	http.Error(w, "failed to fetch Helm repository index", http.StatusBadGateway)
+}
+
+func (h *HelmHandler) rewriteIndex(repository, upstreamURL string, body []byte) ([]byte, error) {
+	document, entries, err := parseHelmIndex(body)
+	if err != nil {
+		return nil, err
+	}
+
+	for i := 0; i < len(entries.Content); i += 2 {
+		chartName := entries.Content[i].Value
+		releases := entries.Content[i+1]
+		if releases.Kind != yaml.SequenceNode {
+			return nil, fmt.Errorf("chart %q releases must be a sequence", chartName)
+		}
+
+		filtered := make([]*yaml.Node, 0, len(releases.Content))
+		for _, release := range releases.Content {
+			chart, err := h.parseChartRelease(chartName, upstreamURL, release)
+			if err != nil {
+				return nil, err
+			}
+			if h.chartOnCooldown(chartName, chart.created) {
+				continue
+			}
+			for _, download := range chart.downloads {
+				download.node.Value = h.chartProxyURL(repository, chart.digest, download.filename)
+			}
+			filtered = append(filtered, release)
+		}
+		releases.Content = filtered
+	}
+
+	return yaml.Marshal(document)
+}
+
+func (h *HelmHandler) findChartDownload(upstreamURL string, body []byte, digest, filename string) (string, error) {
+	_, entries, err := parseHelmIndex(body)
+	if err != nil {
+		return "", err
+	}
+
+	for i := 0; i < len(entries.Content); i += 2 {
+		chartName := entries.Content[i].Value
+		releases := entries.Content[i+1]
+		if releases.Kind != yaml.SequenceNode {
+			return "", fmt.Errorf("chart %q releases must be a sequence", chartName)
+		}
+		for _, release := range releases.Content {
+			chart, err := h.parseChartRelease(chartName, upstreamURL, release)
+			if err != nil {
+				return "", err
+			}
+			if chart.digest != digest || h.chartOnCooldown(chartName, chart.created) {
+				continue
+			}
+			for _, download := range chart.downloads {
+				if download.filename == filename {
+					return download.url, nil
+				}
+			}
+		}
+	}
+
+	return "", errHelmChartNotFound
+}
+
+func (h *HelmHandler) chartOnCooldown(chartName string, created time.Time) bool {
+	return !created.IsZero() && h.proxy.Cooldown != nil && h.proxy.Cooldown.Enabled() &&
+		!h.proxy.Cooldown.IsAllowed(helmMetadataEcosystem, canonicalPackagePURL(helmMetadataEcosystem, chartName), created)
+}
+
+type helmChartDownload struct {
+	node     *yaml.Node
+	url      string
+	filename string
+}
+
+type helmChartRelease struct {
+	created   time.Time
+	digest    string
+	downloads []helmChartDownload
+}
+
+var errHelmChartNotFound = errors.New("chart not found in Helm index")
+
+func (h *HelmHandler) parseChartRelease(chartName, upstreamURL string, release *yaml.Node) (helmChartRelease, error) {
+	digestNode := helmMappingValue(release, "digest")
+	urlsNode := helmMappingValue(release, "urls")
+	if digestNode == nil || urlsNode == nil || urlsNode.Kind != yaml.SequenceNode || len(urlsNode.Content) == 0 {
+		return helmChartRelease{}, fmt.Errorf("chart %q has no digest or URLs", chartName)
+	}
+	digest, ok := normalizeHelmDigest(digestNode.Value)
+	if !ok {
+		return helmChartRelease{}, fmt.Errorf("chart %q has invalid digest", chartName)
+	}
+
+	baseURL, err := url.Parse(upstreamURL + "/" + helmIndexFilename)
+	if err != nil {
+		return helmChartRelease{}, fmt.Errorf("parsing Helm repository URL: %w", err)
+	}
+
+	chart := helmChartRelease{digest: digest}
+	if createdNode := helmMappingValue(release, "created"); createdNode != nil && createdNode.Value != "" {
+		chart.created, err = time.Parse(time.RFC3339Nano, createdNode.Value)
+		if err != nil {
+			return helmChartRelease{}, fmt.Errorf("chart %q has invalid creation time: %w", chartName, err)
+		}
+	}
+
+	for _, urlNode := range urlsNode.Content {
+		if urlNode.Kind != yaml.ScalarNode {
+			return helmChartRelease{}, fmt.Errorf("chart %q has invalid URL", chartName)
+		}
+		reference, err := url.Parse(urlNode.Value)
+		if err != nil {
+			return helmChartRelease{}, fmt.Errorf("parsing chart %q URL: %w", chartName, err)
+		}
+		downloadURL := baseURL.ResolveReference(reference)
+		if (downloadURL.Scheme != "http" && downloadURL.Scheme != "https") || downloadURL.Host == "" {
+			return helmChartRelease{}, fmt.Errorf("chart %q URL must be HTTP(S)", chartName)
+		}
+		filename := path.Base(downloadURL.Path)
+		if filename == "." || filename == "/" || filename == "" || !strings.HasSuffix(filename, ".tgz") {
+			return helmChartRelease{}, fmt.Errorf("chart %q URL must point to a .tgz file", chartName)
+		}
+		chart.downloads = append(chart.downloads, helmChartDownload{
+			node:     urlNode,
+			url:      downloadURL.String(),
+			filename: filename,
+		})
+	}
+	return chart, nil
+}
+
+func (h *HelmHandler) chartProxyURL(repository, digest, filename string) string {
+	return fmt.Sprintf("%s/helm/%s/charts/%s/%s", h.proxyURL,
+		url.PathEscape(repository), digest, url.PathEscape(filename))
+}
+
+func parseHelmIndex(body []byte) (*yaml.Node, *yaml.Node, error) {
+	var document yaml.Node
+	if err := yaml.Unmarshal(body, &document); err != nil {
+		return nil, nil, fmt.Errorf("parsing Helm index: %w", err)
+	}
+	entries, err := helmIndexEntries(&document)
+	if err != nil {
+		return nil, nil, err
+	}
+	return &document, entries, nil
+}
+
+func helmIndexEntries(document *yaml.Node) (*yaml.Node, error) {
+	if document == nil {
+		return nil, errors.New("helm index is empty")
+	}
+	if len(document.Content) != 1 || document.Content[0].Kind != yaml.MappingNode {
+		return nil, errors.New("helm index must be a mapping")
+	}
+	entries := helmMappingValue(document.Content[0], "entries")
+	if entries == nil || entries.Kind != yaml.MappingNode {
+		return nil, errors.New("helm index has no entries mapping")
+	}
+	if len(entries.Content)%2 != 0 {
+		return nil, errors.New("helm index entries mapping has an incomplete key-value pair")
+	}
+	return entries, nil
+}
+
+func helmMappingValue(mapping *yaml.Node, key string) *yaml.Node {
+	if mapping == nil || mapping.Kind != yaml.MappingNode {
+		return nil
+	}
+	for i := 0; i+1 < len(mapping.Content); i += 2 {
+		if mapping.Content[i].Value == key {
+			return mapping.Content[i+1]
+		}
+	}
+	return nil
+}
+
+func normalizeHelmDigest(value string) (string, bool) {
+	digest := strings.TrimPrefix(strings.ToLower(value), "sha256:")
+	if len(digest) != sha256HexLength {
+		return "", false
+	}
+	for _, char := range digest {
+		if (char < '0' || char > '9') && (char < 'a' || char > 'f') {
+			return "", false
+		}
+	}
+	return digest, true
+}

internal/handler/helm_test.go

@@ -0,0 +1,337 @@
+package handler
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/cooldown"
+	upstreamhttp "github.com/git-pkgs/proxy/internal/httpclient"
+	"github.com/git-pkgs/proxy/internal/storage"
+	"github.com/git-pkgs/registries/fetch"
+	"gopkg.in/yaml.v3"
+)
+
+func TestHelmHandler_RewritesIndexAndCachesChart(t *testing.T) {
+	chart := []byte("a Helm chart")
+	digest := helmSHA256Hex(chart)
+	var available atomic.Bool
+	available.Store(true)
+	var indexRequests atomic.Int32
+	var chartRequests atomic.Int32
+
+	var upstream *httptest.Server
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !available.Load() {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		switch r.URL.Path {
+		case "/charts/index.yaml":
+			indexRequests.Add(1)
+			w.Header().Set("Content-Type", "application/x-yaml")
+			_, _ = fmt.Fprintf(w, `apiVersion: v1
+entries:
+  demo:
+    - annotations:
+        example.com/retained: "true"
+      created: 2020-01-02T03:04:05Z
+      digest: %s
+      name: demo
+      urls:
+        - demo-1.0.0.tgz
+        - %s/charts/mirror/demo-1.0.0.tgz
+      version: 1.0.0
+generated: 2020-01-02T03:04:05Z
+`, digest, upstream.URL)
+		case "/charts/demo-1.0.0.tgz", "/charts/mirror/demo-1.0.0.tgz":
+			chartRequests.Add(1)
+			w.Header().Set("Content-Type", "application/gzip")
+			_, _ = w.Write(chart)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(upstream.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+
+	h := NewHelmHandler(proxy, "http://proxy.example", map[string]string{"stable": upstream.URL + "/charts"})
+
+	indexResponse := serveHelmRequest(h, "/stable/index.yaml")
+	if indexResponse.Code != http.StatusOK {
+		t.Fatalf("index status = %d, want 200: %s", indexResponse.Code, indexResponse.Body.String())
+	}
+	if got := indexResponse.Header().Get("Content-Type"); got != "application/x-yaml" {
+		t.Errorf("index Content-Type = %q, want application/x-yaml", got)
+	}
+	if strings.Contains(indexResponse.Body.String(), upstream.URL) {
+		t.Errorf("rewritten index contains upstream URL: %s", indexResponse.Body.String())
+	}
+	if !strings.Contains(indexResponse.Body.String(), "example.com/retained") {
+		t.Errorf("rewritten index lost an unrelated field: %s", indexResponse.Body.String())
+	}
+
+	var index map[string]any
+	if err := yaml.Unmarshal(indexResponse.Body.Bytes(), &index); err != nil {
+		t.Fatalf("parse rewritten index: %v", err)
+	}
+	entries := index["entries"].(map[string]any)
+	release := entries["demo"].([]any)[0].(map[string]any)
+	urls := release["urls"].([]any)
+	wantURL := "http://proxy.example/helm/stable/charts/" + digest + "/demo-1.0.0.tgz"
+	for _, rawURL := range urls {
+		if rawURL != wantURL {
+			t.Errorf("rewritten URL = %q, want %q", rawURL, wantURL)
+		}
+	}
+
+	firstChart := serveHelmRequest(h, "/stable/charts/"+digest+"/demo-1.0.0.tgz")
+	if firstChart.Code != http.StatusOK {
+		t.Fatalf("chart status = %d, want 200: %s", firstChart.Code, firstChart.Body.String())
+	}
+	if got := firstChart.Body.String(); got != string(chart) {
+		t.Errorf("chart body = %q, want %q", got, chart)
+	}
+	if got := firstChart.Header().Get("Content-Type"); got != "application/gzip" {
+		t.Errorf("chart Content-Type = %q, want application/gzip", got)
+	}
+
+	// Artifact cache availability must not depend on metadata caching or a
+	// reachable index upstream.
+	proxy.CacheMetadata = false
+	available.Store(false)
+	cachedChart := serveHelmRequest(h, "/stable/charts/"+digest+"/demo-1.0.0.tgz")
+	if cachedChart.Code != http.StatusOK {
+		t.Fatalf("cached chart status = %d, want 200: %s", cachedChart.Code, cachedChart.Body.String())
+	}
+	if got := cachedChart.Body.String(); got != string(chart) {
+		t.Errorf("cached chart body = %q, want %q", got, chart)
+	}
+	if got := indexRequests.Load(); got != 1 {
+		t.Errorf("index requests = %d, want 1", got)
+	}
+	if got := chartRequests.Load(); got != 1 {
+		t.Errorf("chart requests = %d, want 1", got)
+	}
+}
+
+func TestHelmHandler_RejectsChartDigestMismatch(t *testing.T) {
+	chart := []byte("tampered chart")
+	digest := helmSHA256Hex([]byte("expected chart"))
+	requests := 0
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/index.yaml":
+			_, _ = fmt.Fprintf(w, "apiVersion: v1\nentries:\n  demo:\n    - digest: %s\n      urls: [demo.tgz]\n", digest)
+		case "/demo.tgz":
+			requests++
+			_, _ = w.Write(chart)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer upstream.Close()
+
+	proxy, _, store, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(upstream.Client()), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+	h := NewHelmHandler(proxy, "http://proxy.example", map[string]string{"test": upstream.URL})
+
+	for range 2 {
+		response := serveHelmRequest(h, "/test/charts/"+digest+"/demo.tgz")
+		if response.Code != http.StatusBadGateway {
+			t.Errorf("status = %d, want 502: %s", response.Code, response.Body.String())
+		}
+	}
+	if requests != 2 {
+		t.Errorf("chart requests = %d, want 2 after invalid cache entry is cleared", requests)
+	}
+	storagePath := storage.ArtifactPath(helmMetadataEcosystem, "", "test", digest, "demo.tgz")
+	if exists, err := store.Exists(t.Context(), storagePath); err != nil {
+		t.Fatalf("checking rejected chart storage: %v", err)
+	} else if exists {
+		t.Errorf("rejected chart remains in storage at %q", storagePath)
+	}
+}
+
+func TestHelmHandler_IndexCacheChangesWithUpstreamURL(t *testing.T) {
+	firstDigest := strings.Repeat("a", sha256HexLength)
+	secondDigest := strings.Repeat("b", sha256HexLength)
+	firstRequests := 0
+	secondRequests := 0
+	first := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		firstRequests++
+		_, _ = fmt.Fprintf(w, "apiVersion: v1\nentries:\n  demo:\n    - digest: %s\n      urls: [demo.tgz]\n", firstDigest)
+	}))
+	defer first.Close()
+	second := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		secondRequests++
+		_, _ = fmt.Fprintf(w, "apiVersion: v1\nentries:\n  demo:\n    - digest: %s\n      urls: [demo.tgz]\n", secondDigest)
+	}))
+	defer second.Close()
+
+	proxy, db, store, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = first.Client()
+	firstHandler := NewHelmHandler(proxy, "http://proxy.example", map[string]string{"stable": first.URL})
+	if response := serveHelmRequest(firstHandler, "/stable/index.yaml"); response.Code != http.StatusOK {
+		t.Fatalf("first index status = %d, want 200: %s", response.Code, response.Body.String())
+	}
+
+	// Model a restarted server with the same database and storage but a changed
+	// repository URL. Its cache key must not reuse the previous index or ETag.
+	restartedProxy := NewProxy(db, store, &mockFetcher{}, fetch.NewResolver(), nil)
+	restartedProxy.CacheMetadata = true
+	restartedProxy.MetadataTTL = time.Hour
+	restartedProxy.HTTPClient = second.Client()
+	secondHandler := NewHelmHandler(restartedProxy, "http://proxy.example", map[string]string{"stable": second.URL})
+	response := serveHelmRequest(secondHandler, "/stable/index.yaml")
+	if response.Code != http.StatusOK {
+		t.Fatalf("second index status = %d, want 200: %s", response.Code, response.Body.String())
+	}
+	if !strings.Contains(response.Body.String(), secondDigest) {
+		t.Errorf("second index did not use the new upstream: %s", response.Body.String())
+	}
+	if firstRequests != 1 {
+		t.Errorf("first upstream requests = %d, want 1", firstRequests)
+	}
+	if secondRequests != 1 {
+		t.Errorf("second upstream requests = %d, want 1", secondRequests)
+	}
+}
+
+func TestHelmHandler_UsesConfiguredUpstreamAuthentication(t *testing.T) {
+	chart := []byte("private Helm chart")
+	digest := helmSHA256Hex(chart)
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer private-token" {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		switch r.URL.Path {
+		case "/index.yaml":
+			_, _ = fmt.Fprintf(w, "apiVersion: v1\nentries:\n  demo:\n    - digest: %s\n      urls: [demo.tgz]\n", digest)
+		case "/demo.tgz":
+			_, _ = w.Write(chart)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	authClient := &http.Client{Transport: upstreamhttp.NewTransport(http.DefaultTransport,
+		upstreamhttp.AuthFunc(func(string) (string, string) {
+			return "Authorization", "Bearer private-token"
+		}))}
+	proxy.HTTPClient = authClient
+	fetcher := fetch.NewFetcher(fetch.WithHTTPClient(authClient), fetch.WithMaxRetries(0))
+	proxy.Fetcher = fetcher
+	t.Cleanup(func() { _ = fetcher.Close() })
+	h := NewHelmHandler(proxy, "http://proxy.example", map[string]string{"private": upstream.URL})
+
+	response := serveHelmRequest(h, "/private/charts/"+digest+"/demo.tgz")
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", response.Code, response.Body.String())
+	}
+	if got := response.Body.String(); got != string(chart) {
+		t.Errorf("body = %q, want %q", got, chart)
+	}
+}
+
+func TestHelmHandler_FiltersNewChartsFromIndex(t *testing.T) {
+	oldDigest := strings.Repeat("a", 64)
+	newDigest := strings.Repeat("b", 64)
+	proxy := &Proxy{Cooldown: &cooldown.Config{Default: "3d"}}
+	h := NewHelmHandler(proxy, "http://proxy.example", map[string]string{"test": "https://charts.example"})
+
+	body := fmt.Sprintf(`apiVersion: v1
+entries:
+  demo:
+    - created: %s
+      digest: %s
+      urls: [demo-old.tgz]
+    - created: %s
+      digest: %s
+      urls: [demo-new.tgz]
+`, time.Now().Add(-10*24*time.Hour).Format(time.RFC3339), oldDigest,
+		time.Now().Add(-time.Hour).Format(time.RFC3339), newDigest)
+
+	rewritten, err := h.rewriteIndex("test", "https://charts.example", []byte(body))
+	if err != nil {
+		t.Fatalf("rewriteIndex() error = %v", err)
+	}
+	if strings.Contains(string(rewritten), newDigest) {
+		t.Errorf("rewritten index includes a chart still in cooldown: %s", rewritten)
+	}
+	if !strings.Contains(string(rewritten), oldDigest) {
+		t.Errorf("rewritten index omitted an old chart: %s", rewritten)
+	}
+}
+
+func TestNormalizeHelmDigest(t *testing.T) {
+	digest := strings.Repeat("a", 64)
+	for _, input := range []string{digest, "sha256:" + digest, "SHA256:" + strings.ToUpper(digest)} {
+		if got, ok := normalizeHelmDigest(input); !ok || got != digest {
+			t.Errorf("normalizeHelmDigest(%q) = %q, %t; want %q, true", input, got, ok, digest)
+		}
+	}
+	if _, ok := normalizeHelmDigest("bad"); ok {
+		t.Error("normalizeHelmDigest accepted an invalid digest")
+	}
+}
+
+func TestHelmIndexEntriesRejectsIncompleteMapping(t *testing.T) {
+	entries := &yaml.Node{
+		Kind: yaml.MappingNode,
+		Content: []*yaml.Node{
+			{Kind: yaml.ScalarNode, Value: "demo"},
+		},
+	}
+	document := &yaml.Node{
+		Kind: yaml.DocumentNode,
+		Content: []*yaml.Node{{
+			Kind: yaml.MappingNode,
+			Content: []*yaml.Node{
+				{Kind: yaml.ScalarNode, Value: "entries"},
+				entries,
+			},
+		}},
+	}
+
+	if _, err := helmIndexEntries(document); err == nil {
+		t.Fatal("helmIndexEntries() error = nil, want incomplete mapping error")
+	}
+}
+
+func serveHelmRequest(h *HelmHandler, target string) *httptest.ResponseRecorder {
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodGet, target, nil))
+	return w
+}
+
+func helmSHA256Hex(data []byte) string {
+	digest := sha256.Sum256(data)
+	return hex.EncodeToString(digest[:])
+}

internal/handler/hex.go

@@ -21,6 +21,7 @@ const (
 type HexHandler struct {
 	proxy       *Proxy
 	upstreamURL string
+	apiURL      string
 	proxyURL    string
 }
 
@@ -29,10 +30,20 @@ func NewHexHandler(proxy *Proxy, proxyURL string) *HexHandler {
 	return &HexHandler{
 		proxy:       proxy,
 		upstreamURL: hexUpstream,
+		apiURL:      hexAPIURL,
 		proxyURL:    strings.TrimSuffix(proxyURL, "/"),
 	}
 }
 
+// NewHexHandlerWithUpstreams creates a Hex handler with custom repository and
+// API upstreams.
+func NewHexHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, apiURL string) *HexHandler {
+	h := NewHexHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, hexUpstream)
+	h.apiURL = configuredUpstreamURL(apiURL, hexAPIURL)
+	return h
+}
+
 // Routes returns the HTTP handler for Hex requests.
 func (h *HexHandler) Routes() http.Handler {
 	mux := http.NewServeMux()
@@ -54,11 +65,12 @@ func (h *HexHandler) Routes() http.Handler {
 // handleDownload serves a package tarball, fetching and caching from upstream if needed.
 func (h *HexHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 	h.proxy.handleFilenameDownload(w, r, filenameDownload{
-		ecosystem: "hex",
-		suffix:    ".tar",
-		parseErr:  "could not parse tarball filename",
-		fetchErr:  "failed to fetch package",
-		parse:     h.parseTarballFilename,
+		ecosystem:   "hex",
+		upstreamURL: h.upstreamURL,
+		suffix:      ".tar",
+		parseErr:    "could not parse tarball filename",
+		fetchErr:    "failed to fetch package",
+		parse:       h.parseTarballFilename,
 	})
 }
 
@@ -123,7 +135,7 @@ func (h *HexHandler) handlePackages(w http.ResponseWriter, r *http.Request) {
 
 	if len(filteredVersions) == 0 {
 		// No versions to filter or couldn't get timestamps, pass through
-		w.Header().Set("Content-Type", protoResp.Header.Get("Content-Type"))
+		w.Header().Set(headerContentType, protoResp.Header.Get(headerContentType))
 		w.Header().Set("Content-Encoding", "gzip")
 		_, _ = w.Write(body)
 		return
@@ -132,13 +144,13 @@ func (h *HexHandler) handlePackages(w http.ResponseWriter, r *http.Request) {
 	filtered, err := h.filterSignedPackage(body, filteredVersions)
 	if err != nil {
 		h.proxy.Logger.Warn("failed to filter hex package, proxying original", "error", err)
-		w.Header().Set("Content-Type", protoResp.Header.Get("Content-Type"))
+		w.Header().Set(headerContentType, protoResp.Header.Get(headerContentType))
 		w.Header().Set("Content-Encoding", "gzip")
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/octet-stream")
+	w.Header().Set(headerContentType, "application/octet-stream")
 	w.Header().Set("Content-Encoding", "gzip")
 	_, _ = w.Write(filtered)
 }
@@ -197,7 +209,7 @@ type hexPackageAPI struct {
 // fetchFilteredVersions fetches the Hex API and returns a set of version
 // strings that should be filtered out by cooldown.
 func (h *HexHandler) fetchFilteredVersions(r *http.Request, name string) (map[string]bool, error) {
-	apiURL := fmt.Sprintf("%s/api/packages/%s", hexAPIURL, name)
+	apiURL := fmt.Sprintf("%s/api/packages/%s", h.apiURL, name)
 	req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, apiURL, nil)
 	if err != nil {
 		return nil, err

internal/handler/homebrew.go

@@ -0,0 +1,74 @@
+package handler
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"strings"
+)
+
+const (
+	homebrewArtifactNamespace  = "homebrew"
+	homebrewArtifactRepository = "homebrew/core"
+	homebrewMetadataEcosystem  = "homebrew"
+)
+
+// HomebrewHandler proxies Homebrew's JSON API without modifying signed files.
+type HomebrewHandler struct {
+	proxy       *Proxy
+	apiUpstream string
+}
+
+// NewHomebrewHandler creates a Homebrew JSON API handler.
+func NewHomebrewHandler(proxy *Proxy, apiUpstream string) *HomebrewHandler {
+	return &HomebrewHandler{
+		proxy:       proxy,
+		apiUpstream: strings.TrimSuffix(apiUpstream, "/"),
+	}
+}
+
+// RegisterHomebrewArtifacts routes homebrew/core OCI requests to its configured
+// registry and blocks other homebrew repositories from reaching the default
+// OCI registry.
+func RegisterHomebrewArtifacts(container *ContainerHandler, artifactUpstream string) {
+	container.BlockRegistry(homebrewArtifactNamespace)
+	container.RegisterRegistry(homebrewArtifactRepository, artifactUpstream)
+}
+
+// Routes returns the Homebrew JSON API handler. Mount this at /homebrew.
+func (h *HomebrewHandler) Routes() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet && r.Method != http.MethodHead {
+			w.Header().Set("Allow", "GET, HEAD")
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+
+		requestPath := strings.TrimPrefix(r.URL.EscapedPath(), "/")
+		if requestPath == "" || containsPathTraversal(requestPath) {
+			http.NotFound(w, r)
+			return
+		}
+
+		upstreamURL := h.apiUpstream + "/" + requestPath
+		if r.URL.RawQuery != "" {
+			upstreamURL += "?" + r.URL.RawQuery
+		}
+
+		// brew fetches every JSON API download with `curl --compressed` and
+		// decodes Content-Encoding itself, and formula.jws.json is ~33 MB plain
+		// versus ~5 MB gzip, so keep both hops compressed. The analytics
+		// endpoints are the one consumer brew fetches without --compressed;
+		// they stay identity.
+		acceptEncoding := "gzip"
+		if strings.HasPrefix(requestPath, "analytics/") {
+			acceptEncoding = "identity"
+		}
+		h.proxy.proxyCachedWithEncoding(w, r, upstreamURL, homebrewMetadataEcosystem, homebrewMetadataCacheKey(requestPath, r.URL.RawQuery), acceptEncoding, "*/*")
+	})
+}
+
+func homebrewMetadataCacheKey(requestPath, rawQuery string) string {
+	sum := sha256.Sum256([]byte(requestPath + "\x00" + rawQuery))
+	return hex.EncodeToString(sum[:])
+}

internal/handler/homebrew_test.go

@@ -0,0 +1,458 @@
+package handler
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/registries/fetch"
+)
+
+func TestHomebrewHandler_PreservesSignedResponseAndClientValidators(t *testing.T) {
+	body := " {\n  \"payload\": \"signed bytes\",\n  \"signatures\": []\n}\n"
+	etag := `"homebrew-api-etag"`
+	lastModified := time.Date(2026, time.August, 14, 9, 30, 0, 0, time.UTC)
+	requests := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests++
+		if r.Method != http.MethodGet {
+			t.Errorf("upstream method = %s, want GET", r.Method)
+		}
+		if r.URL.Path != "/api/internal/packages.arm64_tahoe.jws.json" {
+			t.Errorf("upstream path = %q", r.URL.Path)
+		}
+		if got := r.Header.Get("Authorization"); got != "" {
+			t.Errorf("upstream Authorization = %q, want empty", got)
+		}
+		if got := r.Header.Get("Cookie"); got != "" {
+			t.Errorf("upstream Cookie = %q, want empty", got)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("ETag", etag)
+		w.Header().Set("Last-Modified", lastModified.Format(http.TimeFormat))
+		_, _ = io.WriteString(w, body)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+	h := NewHomebrewHandler(proxy, upstream.URL+"/api").Routes()
+
+	req := httptest.NewRequest(http.MethodGet, "/internal/packages.arm64_tahoe.jws.json", nil)
+	req.Header.Set("Authorization", "Bearer client-secret")
+	req.Header.Set("Cookie", "session=client-secret")
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d; body: %s", w.Code, http.StatusOK, w.Body.String())
+	}
+	if got := w.Body.String(); got != body {
+		t.Errorf("body = %q, want byte-for-byte %q", got, body)
+	}
+	if got := w.Header().Get("Content-Type"); got != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", got)
+	}
+	wantContentLength := strconv.Itoa(len(body))
+	if got := w.Header().Get("Content-Length"); got != wantContentLength {
+		t.Errorf("Content-Length = %q, want %q", got, wantContentLength)
+	}
+	if got := w.Header().Get("ETag"); got != etag {
+		t.Errorf("ETag = %q, want %q", got, etag)
+	}
+	if got := w.Header().Get("Last-Modified"); got != lastModified.Format(http.TimeFormat) {
+		t.Errorf("Last-Modified = %q, want %q", got, lastModified.Format(http.TimeFormat))
+	}
+
+	conditionalRequest := httptest.NewRequest(http.MethodGet, "/internal/packages.arm64_tahoe.jws.json", nil)
+	conditionalRequest.Header.Set("If-None-Match", etag)
+	conditional := httptest.NewRecorder()
+	h.ServeHTTP(conditional, conditionalRequest)
+	if conditional.Code != http.StatusNotModified {
+		t.Fatalf("conditional status = %d, want %d", conditional.Code, http.StatusNotModified)
+	}
+	if got := conditional.Header().Get("ETag"); got != etag {
+		t.Errorf("conditional ETag = %q, want %q", got, etag)
+	}
+	if conditional.Body.Len() != 0 {
+		t.Errorf("conditional body length = %d, want 0", conditional.Body.Len())
+	}
+
+	modifiedSinceRequest := httptest.NewRequest(http.MethodGet, "/internal/packages.arm64_tahoe.jws.json", nil)
+	modifiedSinceRequest.Header.Set("If-Modified-Since", lastModified.Format(http.TimeFormat))
+	modifiedSince := httptest.NewRecorder()
+	h.ServeHTTP(modifiedSince, modifiedSinceRequest)
+	if modifiedSince.Code != http.StatusNotModified {
+		t.Fatalf("If-Modified-Since status = %d, want %d", modifiedSince.Code, http.StatusNotModified)
+	}
+	if got := modifiedSince.Header().Get("Last-Modified"); got != lastModified.Format(http.TimeFormat) {
+		t.Errorf("conditional Last-Modified = %q, want %q", got, lastModified.Format(http.TimeFormat))
+	}
+	if requests != 1 {
+		t.Errorf("upstream requests = %d, want 1", requests)
+	}
+}
+
+func TestHomebrewHandler_HeadUsesMetadataCacheAndSurvivesOutage(t *testing.T) {
+	body := `{"payload":"signed bytes","signatures":[]}`
+	available := true
+	requests := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests++
+		if got := r.Header.Get("Authorization"); got != "" {
+			t.Errorf("upstream Authorization = %q, want empty", got)
+		}
+		if !available {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("ETag", `"head-etag"`)
+		_, _ = io.WriteString(w, body)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+	h := NewHomebrewHandler(proxy, upstream.URL+"/api").Routes()
+
+	coldRequest := httptest.NewRequest(http.MethodHead, "/formula.jws.json", nil)
+	coldRequest.Header.Set("Authorization", "Bearer client-secret")
+	cold := httptest.NewRecorder()
+	h.ServeHTTP(cold, coldRequest)
+	if cold.Code != http.StatusOK {
+		t.Fatalf("cold status = %d, want %d", cold.Code, http.StatusOK)
+	}
+	if cold.Body.Len() != 0 {
+		t.Errorf("cold body length = %d, want 0", cold.Body.Len())
+	}
+	if got := cold.Header().Get("Content-Length"); got != strconv.Itoa(len(body)) {
+		t.Errorf("Content-Length = %q, want %d", got, len(body))
+	}
+	if got := cold.Header().Get("ETag"); got != `"head-etag"` {
+		t.Errorf("ETag = %q, want %q", got, `"head-etag"`)
+	}
+	if requests != 1 {
+		t.Fatalf("cold upstream requests = %d, want 1", requests)
+	}
+
+	warm := httptest.NewRecorder()
+	h.ServeHTTP(warm, httptest.NewRequest(http.MethodHead, "/formula.jws.json", nil))
+	if warm.Code != http.StatusOK {
+		t.Fatalf("warm status = %d, want %d", warm.Code, http.StatusOK)
+	}
+	if warm.Body.Len() != 0 {
+		t.Errorf("warm body length = %d, want 0", warm.Body.Len())
+	}
+	if requests != 1 {
+		t.Errorf("warm upstream requests = %d, want 1", requests)
+	}
+
+	proxy.MetadataTTL = time.Nanosecond
+	available = false
+	stale := httptest.NewRecorder()
+	h.ServeHTTP(stale, httptest.NewRequest(http.MethodHead, "/formula.jws.json", nil))
+	if stale.Code != http.StatusOK {
+		t.Fatalf("stale status = %d, want %d; body: %s", stale.Code, http.StatusOK, stale.Body.String())
+	}
+	if stale.Body.Len() != 0 {
+		t.Errorf("stale body length = %d, want 0", stale.Body.Len())
+	}
+	if got := stale.Header().Get("Warning"); got != containerStaleWarning {
+		t.Errorf("Warning = %q, want %q", got, containerStaleWarning)
+	}
+}
+
+func TestHomebrewHandler_HeadWithoutMetadataCachePreservesUpstreamMethod(t *testing.T) {
+	upstreamMethod := ""
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		upstreamMethod = r.Method
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Content-Length", "42")
+		w.Header().Set("ETag", `"head-etag"`)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = false
+	proxy.HTTPClient = upstream.Client()
+	h := NewHomebrewHandler(proxy, upstream.URL+"/api").Routes()
+
+	head := httptest.NewRecorder()
+	h.ServeHTTP(head, httptest.NewRequest(http.MethodHead, "/formula.jws.json", nil))
+	if head.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", head.Code, http.StatusOK)
+	}
+	if upstreamMethod != http.MethodHead {
+		t.Errorf("upstream method = %q, want HEAD", upstreamMethod)
+	}
+	if head.Body.Len() != 0 {
+		t.Errorf("body length = %d, want 0", head.Body.Len())
+	}
+	if got := head.Header().Get("Content-Length"); got != "42" {
+		t.Errorf("Content-Length = %q, want 42", got)
+	}
+}
+
+func TestHomebrewHandler_ServesStaleCachedResponseWhenUpstreamFails(t *testing.T) {
+	body := `{"payload":"signed bytes","signatures":[]}`
+	available := true
+	requests := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		requests++
+		if !available {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("ETag", `"stale-etag"`)
+		_, _ = io.WriteString(w, body)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = 5 * time.Millisecond
+	proxy.HTTPClient = upstream.Client()
+	h := NewHomebrewHandler(proxy, upstream.URL+"/api").Routes()
+
+	first := httptest.NewRecorder()
+	h.ServeHTTP(first, httptest.NewRequest(http.MethodGet, "/formula.jws.json", nil))
+	if first.Code != http.StatusOK {
+		t.Fatalf("warm status = %d, want %d", first.Code, http.StatusOK)
+	}
+
+	time.Sleep(10 * time.Millisecond)
+	available = false
+	stale := httptest.NewRecorder()
+	h.ServeHTTP(stale, httptest.NewRequest(http.MethodGet, "/formula.jws.json", nil))
+	if stale.Code != http.StatusOK {
+		t.Fatalf("stale status = %d, want %d; body: %s", stale.Code, http.StatusOK, stale.Body.String())
+	}
+	if got := stale.Body.String(); got != body {
+		t.Errorf("stale body = %q, want %q", got, body)
+	}
+	if got := stale.Header().Get("Warning"); got != containerStaleWarning {
+		t.Errorf("Warning = %q, want %q", got, containerStaleWarning)
+	}
+	if requests != 2 {
+		t.Errorf("upstream requests = %d, want 2", requests)
+	}
+}
+
+func TestHomebrewHandler_ProxiesSupportedAPIPaths(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = io.WriteString(w, r.URL.RequestURI())
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	h := NewHomebrewHandler(proxy, upstream.URL+"/api").Routes()
+
+	paths := []string{
+		"/formula.jws.json",
+		"/cask.jws.json",
+		"/formula/jq.json",
+		"/cask/firefox.json",
+		"/internal/packages.arm64_tahoe.jws.json?download=1",
+	}
+	for _, requestPath := range paths {
+		t.Run(requestPath, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, requestPath, nil))
+			if w.Code != http.StatusOK {
+				t.Fatalf("status = %d, want %d", w.Code, http.StatusOK)
+			}
+			if got, want := w.Body.String(), "/api"+requestPath; got != want {
+				t.Errorf("upstream request = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+func TestHomebrewHandler_RejectsUnsupportedRequests(t *testing.T) {
+	proxy, _, _, _ := setupTestProxy(t)
+	h := NewHomebrewHandler(proxy, "https://example.test/api").Routes()
+
+	method := httptest.NewRecorder()
+	h.ServeHTTP(method, httptest.NewRequest(http.MethodPost, "/formula.jws.json", nil))
+	if method.Code != http.StatusMethodNotAllowed {
+		t.Errorf("POST status = %d, want %d", method.Code, http.StatusMethodNotAllowed)
+	}
+	if got := method.Header().Get("Allow"); got != "GET, HEAD" {
+		t.Errorf("Allow = %q, want GET, HEAD", got)
+	}
+
+	root := httptest.NewRecorder()
+	h.ServeHTTP(root, httptest.NewRequest(http.MethodGet, "/", nil))
+	if root.Code != http.StatusNotFound {
+		t.Errorf("root status = %d, want %d", root.Code, http.StatusNotFound)
+	}
+
+	traversal := httptest.NewRecorder()
+	h.ServeHTTP(traversal, httptest.NewRequest(http.MethodGet, "/%2e%2e/secret", nil))
+	if traversal.Code != http.StatusNotFound {
+		t.Errorf("traversal status = %d, want %d", traversal.Code, http.StatusNotFound)
+	}
+}
+
+func TestRegisterHomebrewArtifacts(t *testing.T) {
+	h := &ContainerHandler{registryURL: dockerHubRegistry}
+	artifactUpstream := "https://homebrew-proxy.example.com"
+	RegisterHomebrewArtifacts(h, artifactUpstream+"/")
+
+	if got := h.registryURLFor("homebrew/core/jq"); got != artifactUpstream {
+		t.Errorf("homebrew/core registry = %q, want %q", got, artifactUpstream)
+	}
+	if got := h.registryURLFor("homebrew/cask/firefox"); got != "" {
+		t.Errorf("other Homebrew registry = %q, want blocked", got)
+	}
+	if got := h.registryURLFor("library/nginx"); got != dockerHubRegistry {
+		t.Errorf("unrelated registry = %q, want %q", got, dockerHubRegistry)
+	}
+}
+
+func TestRegisterHomebrewArtifactsRejectsOtherHomebrewRoutes(t *testing.T) {
+	upstreamRequests := 0
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		upstreamRequests++
+		_, _ = io.WriteString(w, "unexpected upstream response")
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, fetcher := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("unexpected upstream blob")),
+		ContentType: "application/octet-stream",
+	}
+	h := &ContainerHandler{proxy: proxy, registryURL: upstream.URL}
+	RegisterHomebrewArtifacts(h, "https://ghcr.io")
+
+	const digest = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+	paths := []string{
+		"/homebrew/cask/firefox/blobs/" + digest,
+		"/homebrew/cask/firefox/manifests/latest",
+		"/homebrew/cask/firefox/tags/list",
+	}
+	for _, path := range paths {
+		t.Run(path, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+			if w.Code != http.StatusNotFound {
+				t.Errorf("status = %d, want %d; body: %s", w.Code, http.StatusNotFound, w.Body.String())
+			}
+		})
+	}
+
+	if fetcher.fetchCalled {
+		t.Error("blocked Homebrew blob reached the artifact fetcher")
+	}
+	if upstreamRequests != 0 {
+		t.Errorf("blocked Homebrew routes made %d upstream requests, want 0", upstreamRequests)
+	}
+}
+
+// TestHomebrewHandler_RequestsGzipForAPIPaths covers #305's motivating case:
+// the JSON API files are fetched, cached and served gzip-compressed with
+// Content-Encoding: gzip (brew fetches them with --compressed), while the
+// analytics endpoints, which brew fetches without --compressed, stay identity.
+func TestHomebrewHandler_RequestsGzipForAPIPaths(t *testing.T) {
+	plain := []byte(`{"payload":"signed bytes","signatures":[]}`)
+	compressed := gzipPayload(t, plain)
+
+	var available atomic.Bool
+	available.Store(true)
+	var requests atomic.Int32
+	var sawAcceptEncoding atomic.Value // string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requests.Add(1)
+		sawAcceptEncoding.Store(r.Header.Get(headerAcceptEncoding))
+		if !available.Load() {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set(headerContentType, "application/json")
+		if strings.Contains(r.Header.Get(headerAcceptEncoding), "gzip") {
+			w.Header().Set(headerContentEncoding, "gzip")
+			_, _ = w.Write(compressed)
+			return
+		}
+		_, _ = w.Write(plain)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+	h := NewHomebrewHandler(proxy, upstream.URL+"/api").Routes()
+
+	get := func(path string) *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+		return w
+	}
+	lastAE := func() string {
+		s, _ := sawAcceptEncoding.Load().(string)
+		return s
+	}
+
+	first := get("/formula.jws.json")
+	if first.Code != http.StatusOK {
+		t.Fatalf("formula.jws.json: status = %d, want 200: %s", first.Code, first.Body.String())
+	}
+	if got := lastAE(); got != "gzip" {
+		t.Errorf("formula.jws.json: upstream Accept-Encoding = %q, want %q", got, "gzip")
+	}
+	if !bytes.Equal(first.Body.Bytes(), compressed) {
+		t.Errorf("formula.jws.json: body is not the compressed bytes (got %d, want %d)", first.Body.Len(), len(compressed))
+	}
+	if got := first.Header().Get(headerContentEncoding); got != "gzip" {
+		t.Errorf("formula.jws.json: Content-Encoding = %q, want %q", got, "gzip")
+	}
+	if got := first.Header().Get(headerContentLength); got != strconv.Itoa(len(compressed)) {
+		t.Errorf("formula.jws.json: Content-Length = %q, want %d", got, len(compressed))
+	}
+
+	// Replay from cache with the upstream down: same bytes and header, no refetch.
+	before := requests.Load()
+	available.Store(false)
+	cached := get("/formula.jws.json")
+	if cached.Code != http.StatusOK {
+		t.Fatalf("cached formula.jws.json: status = %d, want 200: %s", cached.Code, cached.Body.String())
+	}
+	if !bytes.Equal(cached.Body.Bytes(), compressed) || cached.Header().Get(headerContentEncoding) != "gzip" {
+		t.Errorf("cached formula.jws.json: body/header not replayed verbatim")
+	}
+	if requests.Load() != before {
+		t.Errorf("cached formula.jws.json hit upstream: requests %d -> %d", before, requests.Load())
+	}
+	available.Store(true)
+
+	// Analytics is fetched by brew without --compressed: stays identity, no header.
+	analytics := get("/analytics/install/30d.json")
+	if analytics.Code != http.StatusOK {
+		t.Fatalf("analytics: status = %d, want 200: %s", analytics.Code, analytics.Body.String())
+	}
+	if got := lastAE(); got != "identity" {
+		t.Errorf("analytics: upstream Accept-Encoding = %q, want %q", got, "identity")
+	}
+	if !bytes.Equal(analytics.Body.Bytes(), plain) {
+		t.Errorf("analytics: body = %q, want plain %q", analytics.Body.Bytes(), plain)
+	}
+	if got := analytics.Header().Get(headerContentEncoding); got != "" {
+		t.Errorf("analytics: Content-Encoding = %q, want empty", got)
+	}
+}

internal/handler/if_none_match_test.go

@@ -0,0 +1,31 @@
+package handler
+
+import "testing"
+
+func TestIfNoneMatchHits(t *testing.T) {
+	tests := []struct {
+		header string
+		etag   string
+		want   bool
+	}{
+		{`"abc"`, `"abc"`, true},
+		{`"abc"`, `"def"`, false},
+		{"", `"abc"`, false},
+		{`"abc"`, "", false},
+		{"*", `"abc"`, true},
+		{"*", "", false},
+		{`W/"abc"`, `"abc"`, true},
+		{`"abc"`, `W/"abc"`, true},
+		{`W/"abc"`, `W/"abc"`, true},
+		{`"abc", "def"`, `"def"`, true},
+		{`"abc","def"`, `"def"`, true},
+		{` "abc" ,  W/"def" `, `"def"`, true},
+		{`"abc", "def"`, `"ghi"`, false},
+	}
+
+	for _, tt := range tests {
+		if got := ifNoneMatchHits(tt.header, tt.etag); got != tt.want {
+			t.Errorf("ifNoneMatchHits(%q, %q) = %v, want %v", tt.header, tt.etag, got, tt.want)
+		}
+	}
+}

internal/handler/integrity.go

@@ -1,140 +1,100 @@
 package handler
 
 import (
-	"crypto/sha256"
-	"crypto/sha512"
-	"crypto/subtle"
-	"encoding/base64"
-	"encoding/hex"
 	"fmt"
-	"hash"
 	"io"
-	"strings"
+
+	"github.com/git-pkgs/integrity"
 )
 
-// parseSRI parses a Subresource Integrity string (e.g. "sha512-abc==") into
-// an algorithm name and raw digest bytes. Returns ok=false for empty,
-// malformed, or unsupported entries. Only the first hash in a multi-hash
-// SRI string is considered.
-func parseSRI(s string) (algo string, digest []byte, ok bool) {
-	s = strings.TrimSpace(s)
-	if s == "" {
-		return "", nil, false
+type integrityChecks struct {
+	contentHash integrity.SRI
+	native      integrity.SRI
+	algorithms  []integrity.Algorithm
+}
+
+func newIntegrityChecks(contentHash, native string) (integrityChecks, error) {
+	checks := integrityChecks{}
+
+	if contentHash != "" {
+		digest, err := integrity.ParseHex(integrity.SHA256, contentHash)
+		if err != nil {
+			return integrityChecks{}, fmt.Errorf("parse content_hash: %w", err)
+		}
+		checks.contentHash = integrity.SRI{digest}
+		checks.algorithms = append(checks.algorithms, integrity.SHA256)
 	}
-	if i := strings.IndexByte(s, ' '); i >= 0 {
-		s = s[:i]
+
+	if native != "" {
+		digests, err := integrity.ParseSRI(native)
+		if err != nil {
+			return integrityChecks{}, fmt.Errorf("parse integrity: %w", err)
+		}
+		checks.native = digests
+		for _, digest := range digests {
+			checks.algorithms = append(checks.algorithms, digest.Algorithm())
+		}
 	}
-	algo, b64, found := strings.Cut(s, "-")
-	if !found {
-		return "", nil, false
+
+	return checks, nil
+}
+
+func (c integrityChecks) wrap(source io.ReadCloser, onMismatch func(string)) (io.ReadCloser, error) {
+	if len(c.algorithms) == 0 {
+		return source, nil
 	}
-	d, err := base64.StdEncoding.DecodeString(b64)
+	reader, err := integrity.NewReader(source, c.algorithms...)
 	if err != nil {
-		return "", nil, false
-	}
-	switch algo {
-	case "sha256", "sha384", "sha512":
-		return algo, d, true
-	default:
-		return "", nil, false
+		return nil, fmt.Errorf("create integrity reader: %w", err)
 	}
+	return &verifyingReader{
+		source:     source,
+		reader:     reader,
+		checks:     c,
+		onMismatch: onMismatch,
+	}, nil
 }
 
-func newSRIHash(algo string) hash.Hash {
-	switch algo {
-	case "sha256":
-		return sha256.New()
-	case "sha384":
-		return sha512.New384()
-	case "sha512":
-		return sha512.New()
-	}
-	return nil
-}
-
-// verifyingReader wraps an io.ReadCloser and computes SHA256 (and optionally
-// a second SRI hash) as bytes are read. When the underlying reader reaches
-// EOF it compares the digests against the expected values and calls
-// onMismatch for each failure. Verification is skipped if the stream was
-// not fully consumed (e.g. client disconnect) to avoid false positives.
+// verifyingReader forwards Close to its source and reports completed digest
+// mismatches after its shared integrity reader observes EOF.
 type verifyingReader struct {
-	r          io.ReadCloser
-	sha256     hash.Hash
-	wantSHA256 string
-	sri        hash.Hash
-	sriAlgo    string
-	wantSRI    []byte
+	source     io.ReadCloser
+	reader     *integrity.Reader
+	checks     integrityChecks
 	onMismatch func(reason string)
-	eof        bool
 	verified   bool
 }
 
-func newVerifyingReader(r io.ReadCloser, contentHash, sri string, onMismatch func(string)) io.ReadCloser {
-	if contentHash == "" && sri == "" {
-		return r
-	}
-	v := &verifyingReader{
-		r:          r,
-		onMismatch: onMismatch,
-	}
-	if contentHash != "" {
-		v.sha256 = sha256.New()
-		v.wantSHA256 = contentHash
-	}
-	if algo, digest, ok := parseSRI(sri); ok {
-		v.sri = newSRIHash(algo)
-		v.sriAlgo = algo
-		v.wantSRI = digest
-	}
-	if v.sha256 == nil && v.sri == nil {
-		return r
-	}
-	return v
-}
-
-func (v *verifyingReader) Read(p []byte) (int, error) {
-	n, err := v.r.Read(p)
-	if n > 0 {
-		if v.sha256 != nil {
-			v.sha256.Write(p[:n])
-		}
-		if v.sri != nil {
-			v.sri.Write(p[:n])
-		}
-	}
+func (r *verifyingReader) Read(p []byte) (int, error) {
+	n, err := r.reader.Read(p)
 	if err == io.EOF {
-		v.eof = true
-		v.verify()
+		r.verify()
 	}
 	return n, err
 }
 
-func (v *verifyingReader) Close() error {
-	if v.eof {
-		v.verify()
-	}
-	return v.r.Close()
+func (r *verifyingReader) Close() error {
+	return r.source.Close()
 }
 
-func (v *verifyingReader) verify() {
-	if v.verified {
+func (r *verifyingReader) verify() {
+	if r.verified {
+		return
+	}
+	r.verified = true
+	result := r.reader.Result()
+	if !result.Complete {
 		return
 	}
-	v.verified = true
 
-	if v.sha256 != nil {
-		got := hex.EncodeToString(v.sha256.Sum(nil))
-		if subtle.ConstantTimeCompare([]byte(got), []byte(v.wantSHA256)) != 1 {
-			v.onMismatch(fmt.Sprintf("content_hash mismatch: stored=%s computed=%s", v.wantSHA256, got))
+	if len(r.checks.contentHash) > 0 {
+		if err := result.Verify(r.checks.contentHash); err != nil {
+			r.onMismatch("content_hash: " + err.Error())
 		}
 	}
-	if v.sri != nil {
-		got := v.sri.Sum(nil)
-		if subtle.ConstantTimeCompare(got, v.wantSRI) != 1 {
-			v.onMismatch(fmt.Sprintf("integrity mismatch: %s expected=%s computed=%s",
-				v.sriAlgo,
-				base64.StdEncoding.EncodeToString(v.wantSRI),
-				base64.StdEncoding.EncodeToString(got)))
+	if len(r.checks.native) > 0 {
+		if err := result.Verify(r.checks.native); err != nil {
+			r.onMismatch("integrity: " + err.Error())
 		}
 	}
 }

internal/handler/integrity_test.go

@@ -5,6 +5,7 @@ import (
 	"crypto/sha512"
 	"encoding/base64"
 	"encoding/hex"
+	"errors"
 	"io"
 	"strings"
 	"testing"
@@ -15,42 +16,68 @@ func sha256Hex(data string) string {
 	return hex.EncodeToString(sum[:])
 }
 
+func sha256SRI(data string) string {
+	sum := sha256.Sum256([]byte(data))
+	return "sha256-" + base64.StdEncoding.EncodeToString(sum[:])
+}
+
+func sha384SRI(data string) string {
+	sum := sha512.Sum384([]byte(data))
+	return "sha384-" + base64.StdEncoding.EncodeToString(sum[:])
+}
+
 func sha512SRI(data string) string {
 	sum := sha512.Sum512([]byte(data))
 	return "sha512-" + base64.StdEncoding.EncodeToString(sum[:])
 }
 
-func TestParseSRI(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		algo  string
-		ok    bool
-	}{
-		{"sha512", sha512SRI("hello"), "sha512", true},
-		{"sha256", "sha256-" + base64.StdEncoding.EncodeToString([]byte("0123456789012345678901234567890123456789")), "sha256", true},
-		{"empty", "", "", false},
-		{"no dash", "sha512abc", "", false},
-		{"bad base64", "sha512-not!base64", "", false},
-		{"unsupported algo", "md5-" + base64.StdEncoding.EncodeToString([]byte("x")), "", false},
-		{"multi hash takes first", sha512SRI("a") + " " + sha512SRI("b"), "sha512", true},
-		{"whitespace", "  " + sha512SRI("x") + "  ", "sha512", true},
+func wrapIntegrityReader(t *testing.T, source io.ReadCloser, contentHash, native string, onMismatch func(string)) io.ReadCloser {
+	t.Helper()
+	checks, err := newIntegrityChecks(contentHash, native)
+	if err != nil {
+		t.Fatalf("newIntegrityChecks: %v", err)
 	}
+	reader, err := checks.wrap(source, onMismatch)
+	if err != nil {
+		t.Fatalf("wrap: %v", err)
+	}
+	return reader
+}
 
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			algo, digest, ok := parseSRI(tt.input)
-			if ok != tt.ok {
-				t.Fatalf("ok = %v, want %v", ok, tt.ok)
-			}
-			if !tt.ok {
-				return
-			}
-			if algo != tt.algo {
-				t.Errorf("algo = %q, want %q", algo, tt.algo)
-			}
-			if len(digest) == 0 {
-				t.Error("digest is empty")
+func TestNewIntegrityChecksCollectsAlgorithms(t *testing.T) {
+	checks, err := newIntegrityChecks(
+		sha256Hex("hello"),
+		strings.Join([]string{sha256SRI("first"), sha512SRI("second"), sha384SRI("third"), sha512SRI("alternative")}, " "),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(checks.algorithms) != 5 {
+		t.Fatalf("algorithms = %v, want 5 entries", checks.algorithms)
+	}
+	if len(checks.native) != 4 {
+		t.Errorf("native digests = %d, want 4", len(checks.native))
+	}
+}
+
+func TestNewIntegrityChecksRejectsMalformedMetadata(t *testing.T) {
+	tests := []struct {
+		name        string
+		contentHash string
+		native      string
+	}{
+		{name: "short content hash", contentHash: "abc123"},
+		{name: "non-hex content hash", contentHash: strings.Repeat("z", sha256.Size*2)},
+		{name: "missing SRI separator", native: "sha512"},
+		{name: "malformed SRI base64", native: "sha512-not!base64"},
+		{name: "wrong SRI length", native: "sha512-" + base64.StdEncoding.EncodeToString([]byte("short"))},
+		{name: "unsupported SRI algorithm", native: "md5-1B2M2Y8AsgTpgAmY7PhCfg=="},
+		{name: "invalid SRI alternative", native: sha512SRI("valid") + " sha384-nope"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if _, err := newIntegrityChecks(test.contentHash, test.native); err == nil {
+				t.Fatal("newIntegrityChecks returned nil error")
 			}
 		})
 	}
@@ -67,69 +94,156 @@ func TestVerifyingReader(t *testing.T) {
 		sri       string
 		wantCalls int
 	}{
-		{"both match", goodSHA, goodSRI, 0},
-		{"sha256 only match", goodSHA, "", 0},
-		{"sri only match", "", goodSRI, 0},
-		{"sha256 mismatch", sha256Hex("other"), "", 1},
-		{"sri mismatch", "", sha512SRI("other"), 1},
-		{"both mismatch", sha256Hex("other"), sha512SRI("other"), 2},
-		{"no checks", "", "", 0},
-		{"unparseable sri ignored", goodSHA, "garbage", 0},
+		{name: "both match", hash: goodSHA, sri: goodSRI},
+		{name: "SHA-256 only match", hash: goodSHA},
+		{name: "SRI only match", sri: goodSRI},
+		{name: "SHA-256 mismatch", hash: sha256Hex("other"), wantCalls: 1},
+		{name: "SRI mismatch", sri: sha512SRI("other"), wantCalls: 1},
+		{name: "both mismatch", hash: sha256Hex("other"), sri: sha512SRI("other"), wantCalls: 2},
+		{name: "no checks"},
 	}
 
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
 			var calls []string
-			r := newVerifyingReader(io.NopCloser(strings.NewReader(data)), tt.hash, tt.sri,
+			reader := wrapIntegrityReader(t, io.NopCloser(strings.NewReader(data)), test.hash, test.sri,
 				func(reason string) { calls = append(calls, reason) })
 
-			got, err := io.ReadAll(r)
+			got, err := io.ReadAll(reader)
 			if err != nil {
 				t.Fatalf("ReadAll: %v", err)
 			}
 			if string(got) != data {
 				t.Errorf("data corrupted: got %q", got)
 			}
-			if err := r.Close(); err != nil {
+			if err := reader.Close(); err != nil {
 				t.Fatalf("Close: %v", err)
 			}
-
-			if len(calls) != tt.wantCalls {
-				t.Errorf("onMismatch called %d times, want %d: %v", len(calls), tt.wantCalls, calls)
+			if len(calls) != test.wantCalls {
+				t.Errorf("onMismatch called %d times, want %d: %v", len(calls), test.wantCalls, calls)
 			}
 		})
 	}
 }
 
-func TestVerifyingReaderPassthrough(t *testing.T) {
-	src := io.NopCloser(strings.NewReader("x"))
-	r := newVerifyingReader(src, "", "", func(string) { t.Fatal("should not be called") })
-	if r != src {
-		t.Error("expected passthrough when no hashes provided")
+func TestVerifyingReaderUsesStrongestNativeAlgorithm(t *testing.T) {
+	const data = "artifact"
+	tests := []struct {
+		name      string
+		native    string
+		wantCalls int
+	}{
+		{
+			name:      "weaker match does not override stronger mismatch",
+			native:    sha256SRI(data) + " " + sha512SRI("other"),
+			wantCalls: 1,
+		},
+		{
+			name:   "stronger match ignores weaker mismatch",
+			native: sha256SRI("other") + " " + sha512SRI(data),
+		},
+		{
+			name:   "same algorithm alternative matches",
+			native: sha512SRI("other") + " " + sha512SRI(data),
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var calls int
+			reader := wrapIntegrityReader(t, io.NopCloser(strings.NewReader(data)), "", test.native, func(string) { calls++ })
+			if _, err := io.Copy(io.Discard, reader); err != nil {
+				t.Fatal(err)
+			}
+			if calls != test.wantCalls {
+				t.Errorf("onMismatch called %d times, want %d", calls, test.wantCalls)
+			}
+		})
 	}
 }
 
-func TestVerifyingReaderPartialRead(t *testing.T) {
-	var calls int
-	r := newVerifyingReader(io.NopCloser(strings.NewReader("hello world")),
-		sha256Hex("hello world"), "", func(string) { calls++ })
+func TestVerifyingReaderMismatchMessages(t *testing.T) {
+	const data = "actual"
+	wantHash := sha256Hex("expected")
+	wantSRI := sha512SRI("expected")
+	var reasons []string
+	reader := wrapIntegrityReader(t, io.NopCloser(strings.NewReader(data)), wantHash, wantSRI,
+		func(reason string) { reasons = append(reasons, reason) })
+	if _, err := io.Copy(io.Discard, reader); err != nil {
+		t.Fatal(err)
+	}
+	if len(reasons) != 2 {
+		t.Fatalf("reasons = %v, want two", reasons)
+	}
+	wantContentReason := "content_hash: integrity mismatch: expected " + sha256SRI("expected") + ", calculated " + sha256SRI(data)
+	if reasons[0] != wantContentReason {
+		t.Errorf("content reason = %q, want %q", reasons[0], wantContentReason)
+	}
+	wantNativeReason := "integrity: integrity mismatch: expected " + wantSRI + ", calculated " + sha512SRI(data)
+	if reasons[1] != wantNativeReason {
+		t.Errorf("native reason = %q, want %q", reasons[1], wantNativeReason)
+	}
+}
 
-	buf := make([]byte, 5)
-	_, _ = r.Read(buf)
-	_ = r.Close()
+func TestVerifyingReaderPassthrough(t *testing.T) {
+	source := io.NopCloser(strings.NewReader("x"))
+	reader := wrapIntegrityReader(t, source, "", "", func(string) { t.Fatal("should not be called") })
+	if reader != source {
+		t.Error("expected passthrough when no hashes were provided")
+	}
+}
+
+type closeTrackingReader struct {
+	io.Reader
+	closed bool
+}
+
+func (r *closeTrackingReader) Close() error {
+	r.closed = true
+	return nil
+}
+
+func TestVerifyingReaderPartialRead(t *testing.T) {
+	source := &closeTrackingReader{Reader: strings.NewReader("hello world")}
+	var calls int
+	reader := wrapIntegrityReader(t, source, sha256Hex("other"), "", func(string) { calls++ })
+
+	buffer := make([]byte, 5)
+	_, _ = reader.Read(buffer)
+	_ = reader.Close()
 
 	if calls != 0 {
 		t.Errorf("onMismatch called %d times for partial read, want 0", calls)
 	}
+	if !source.closed {
+		t.Error("Close was not forwarded to the source")
+	}
+}
+
+func TestVerifyingReaderNonEOFError(t *testing.T) {
+	var calls int
+	reader := wrapIntegrityReader(t, io.NopCloser(errorFixtureReader{}), sha256Hex("data"), "", func(string) { calls++ })
+	if _, err := io.ReadAll(reader); !errors.Is(err, errIntegrityReadFixture) {
+		t.Fatalf("ReadAll error = %v", err)
+	}
+	if calls != 0 {
+		t.Errorf("onMismatch called %d times after non-EOF error", calls)
+	}
+}
+
+var errIntegrityReadFixture = errors.New("integrity read fixture")
+
+type errorFixtureReader struct{}
+
+func (errorFixtureReader) Read(p []byte) (int, error) {
+	return copy(p, "data"), errIntegrityReadFixture
 }
 
 func TestVerifyingReaderVerifyOnce(t *testing.T) {
 	var calls int
-	r := newVerifyingReader(io.NopCloser(strings.NewReader("x")), sha256Hex("y"), "",
-		func(string) { calls++ })
-	_, _ = io.ReadAll(r)
-	_ = r.Close()
-	_ = r.Close()
+	reader := wrapIntegrityReader(t, io.NopCloser(strings.NewReader("x")), sha256Hex("y"), "", func(string) { calls++ })
+	_, _ = io.ReadAll(reader)
+	_ = reader.Close()
+	_ = reader.Close()
 	if calls != 1 {
 		t.Errorf("onMismatch called %d times, want 1", calls)
 	}

internal/handler/julia.go

@@ -53,6 +53,13 @@ func NewJuliaHandler(proxy *Proxy, _ string) *JuliaHandler {
 	}
 }
 
+// NewJuliaHandlerWithUpstream creates a Julia handler with a custom upstream.
+func NewJuliaHandlerWithUpstream(proxy *Proxy, upstreamURL string) *JuliaHandler {
+	h := NewJuliaHandler(proxy, "")
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, juliaUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for Julia requests.
 func (h *JuliaHandler) Routes() http.Handler {
 	mux := http.NewServeMux()

internal/handler/metadata_encoding_test.go

@@ -0,0 +1,200 @@
+package handler
+
+import (
+	"bytes"
+	"compress/gzip"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// gzipPayload returns a gzip-compressed copy of data, simulating an origin
+// that stores pre-compressed index files.
+func gzipPayload(t *testing.T, data []byte) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := gzip.NewWriter(&buf)
+	if _, err := zw.Write(data); err != nil {
+		t.Fatalf("compressing payload: %v", err)
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatalf("closing gzip writer: %v", err)
+	}
+	return buf.Bytes()
+}
+
+// TestProxyCached_PreservesContentEncodedBytes covers issue #300: an upstream
+// that serves a signed index with Content-Encoding: gzip must have its bytes
+// cached and re-served verbatim, with the encoding header replayed, instead of
+// being transparently decompressed by the HTTP client.
+func TestProxyCached_PreservesContentEncodedBytes(t *testing.T) {
+	raw := gzipPayload(t, []byte("signed index payload"))
+
+	var available atomic.Bool
+	available.Store(true)
+	var sawAcceptEncoding atomic.Value
+	var upstreamRequests atomic.Int32
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !available.Load() {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		upstreamRequests.Add(1)
+		sawAcceptEncoding.Store(r.Header.Get(headerAcceptEncoding))
+		w.Header().Set(headerContentType, "application/octet-stream")
+		w.Header().Set(headerContentEncoding, "gzip")
+		_, _ = w.Write(raw)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+
+	serve := func() *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(http.MethodGet, "/index", nil)
+		proxy.ProxyCached(w, r, upstream.URL+"/index", "apk", "index-key", "*/*")
+		return w
+	}
+
+	first := serve()
+	if first.Code != http.StatusOK {
+		t.Fatalf("first response status = %d, want 200: %s", first.Code, first.Body.String())
+	}
+	if got, _ := sawAcceptEncoding.Load().(string); got != "identity" {
+		t.Errorf("upstream saw Accept-Encoding %q, want %q", got, "identity")
+	}
+	if !bytes.Equal(first.Body.Bytes(), raw) {
+		t.Errorf("first response altered the upstream bytes: got %d bytes, want %d", first.Body.Len(), len(raw))
+	}
+	if got := first.Header().Get(headerContentEncoding); got != "gzip" {
+		t.Errorf("first response Content-Encoding = %q, want %q", got, "gzip")
+	}
+
+	// Within the TTL and with the upstream down, the cached copy must be
+	// served with the same bytes and encoding.
+	available.Store(false)
+	second := serve()
+	if second.Code != http.StatusOK {
+		t.Fatalf("cached response status = %d, want 200: %s", second.Code, second.Body.String())
+	}
+	if !bytes.Equal(second.Body.Bytes(), raw) {
+		t.Errorf("cached response altered the stored bytes")
+	}
+	if got := second.Header().Get(headerContentEncoding); got != "gzip" {
+		t.Errorf("cached response Content-Encoding = %q, want %q", got, "gzip")
+	}
+	if got := upstreamRequests.Load(); got != 1 {
+		t.Errorf("upstream requests = %d, want 1", got)
+	}
+}
+
+// TestProxyCached_NoEncodingHeaderForIdentityResponses pins that ordinary
+// responses do not grow a spurious Content-Encoding header.
+func TestProxyCached_NoEncodingHeaderForIdentityResponses(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set(headerContentType, contentTypeJSON)
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/meta", nil)
+	proxy.ProxyCached(w, r, upstream.URL+"/meta", "npm", "meta-key", contentTypeJSON)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if got := w.Header().Get(headerContentEncoding); got != "" {
+		t.Errorf("Content-Encoding = %q, want empty", got)
+	}
+}
+
+// TestProxyMetadataStream_PreservesSignedBytesWithoutClientEncoding pins the
+// uncached streaming path (the default, since cache_metadata is off) for the
+// realistic client that sends no Accept-Encoding: the proxy must request
+// identity upstream so Go does not transparently decompress a signed index,
+// and the raw bytes plus the Content-Encoding header must reach the client.
+func TestProxyMetadataStream_PreservesSignedBytesWithoutClientEncoding(t *testing.T) {
+	raw := gzipPayload(t, []byte("streamed index payload"))
+	var sawAcceptEncoding string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		sawAcceptEncoding = r.Header.Get(headerAcceptEncoding)
+		w.Header().Set(headerContentType, "application/octet-stream")
+		w.Header().Set(headerContentEncoding, "gzip")
+		_, _ = w.Write(raw)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = false
+	proxy.HTTPClient = upstream.Client()
+
+	w := httptest.NewRecorder()
+	// No Accept-Encoding on the client request -- the apk/apt/dnf case.
+	r := httptest.NewRequest(http.MethodGet, "/index", nil)
+	proxy.ProxyCached(w, r, upstream.URL+"/index", "apk", "stream-key", "*/*")
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if sawAcceptEncoding != "identity" {
+		t.Errorf("upstream saw Accept-Encoding %q, want %q", sawAcceptEncoding, "identity")
+	}
+	if !bytes.Equal(w.Body.Bytes(), raw) {
+		t.Errorf("streamed response altered the upstream bytes: got %d bytes, want %d", w.Body.Len(), len(raw))
+	}
+	if got := w.Header().Get(headerContentEncoding); got != "gzip" {
+		t.Errorf("Content-Encoding = %q, want %q", got, "gzip")
+	}
+}
+
+// TestFetchOrCacheMetadata_DirectCallersKeepTransparentCompression pins that
+// the parsing/rewriting ecosystems (npm, pypi, cargo, helm, ...) that call
+// FetchOrCacheMetadata directly are NOT forced to identity: they keep Go's
+// transparent transfer compression and receive decoded bytes, so a gzip-only
+// upstream does not regress them (no wire-size blowup, no parse failures).
+func TestFetchOrCacheMetadata_DirectCallersKeepTransparentCompression(t *testing.T) {
+	plaintext := []byte(`{"name":"demo","versions":{"1.0.0":{}}}`)
+	var sawAcceptEncoding string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		sawAcceptEncoding = r.Header.Get(headerAcceptEncoding)
+		// Serve gzip only when the client accepts it, like a real CDN.
+		if strings.Contains(r.Header.Get(headerAcceptEncoding), "gzip") {
+			w.Header().Set(headerContentType, contentTypeJSON)
+			w.Header().Set(headerContentEncoding, "gzip")
+			_, _ = w.Write(gzipPayload(t, plaintext))
+			return
+		}
+		w.Header().Set(headerContentType, contentTypeJSON)
+		_, _ = w.Write(plaintext)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+
+	body, _, err := proxy.FetchOrCacheMetadata(t.Context(), "npm", "demo", upstream.URL+"/demo", contentTypeJSON)
+	if err != nil {
+		t.Fatalf("FetchOrCacheMetadata() error = %v", err)
+	}
+	// The default transport adds Accept-Encoding: gzip and transparently
+	// decompresses, so the caller sees decoded JSON regardless of the wire form.
+	if sawAcceptEncoding == "identity" {
+		t.Errorf("direct caller forced identity; want transparent compression")
+	}
+	if !bytes.Equal(body, plaintext) {
+		t.Errorf("direct caller got %q, want decoded %q", body, plaintext)
+	}
+}

internal/handler/notfound_ecosystems_test.go

@@ -19,10 +19,14 @@ func TestArtifactDownloadUpstreamNotFoundReturns404(t *testing.T) {
 			func(p *Proxy) http.Handler { return NewDebianHandler(p, "http://localhost", "").Routes() }},
 		{"rpm", "/releases/39/Everything/x86_64/os/Packages/n/nginx-1.24.0-1.fc39.x86_64.rpm",
 			func(p *Proxy) http.Handler { return NewRPMHandler(p, "http://localhost").Routes() }},
+		{"apk", "/alpine/v3.22/main/x86_64/busybox-1.37.0-r12.apk",
+			func(p *Proxy) http.Handler { return NewAPKHandler(p, "http://localhost", nil).Routes() }},
 		{"nuget", "/v3-flatcontainer/newtonsoft.json/13.0.3/newtonsoft.json.13.0.3.nupkg",
 			func(p *Proxy) http.Handler { return NewNuGetHandler(p, "http://localhost").Routes() }},
 		{"pypi", "/packages/packages/ab/cd/ef0123456789/requests-2.31.0-py3-none-any.whl",
-			func(p *Proxy) http.Handler { return NewPyPIHandler(p, "http://localhost").Routes() }},
+			func(p *Proxy) http.Handler {
+				return NewPyPIHandlerWithUpstreams(p, "http://localhost", "", "").Routes()
+			}},
 		{"cran", "/src/contrib/ggplot2_3.4.4.tar.gz",
 			func(p *Proxy) http.Handler { return NewCRANHandler(p, "http://localhost").Routes() }},
 		{"conda", "/conda-forge/linux-64/numpy-1.26.0-py311_0.tar.bz2",

internal/handler/npm.go

@@ -76,8 +76,10 @@ func (h *NPMHandler) handlePackageMetadata(w http.ResponseWriter, r *http.Reques
 	// Artifactory, which returns 406) can still respond with full metadata.
 	// When cooldown is enabled we must use full metadata exclusively because the
 	// abbreviated format omits the "time" map required for version age filtering.
+	// Operators can also force full metadata so clients that gate on publish
+	// age (for example Yarn's npmMinimalAgeGate) keep working through the proxy.
 	accept := npmAcceptDefault
-	if h.proxy.Cooldown != nil && h.proxy.Cooldown.Enabled() {
+	if h.proxy.NPMFullMetadata || (h.proxy.Cooldown != nil && h.proxy.Cooldown.Enabled()) {
 		accept = contentTypeJSON
 	}
 
@@ -96,13 +98,13 @@ func (h *NPMHandler) handlePackageMetadata(w http.ResponseWriter, r *http.Reques
 	if err != nil {
 		// If rewriting fails, just proxy the original
 		h.proxy.Logger.Warn("failed to rewrite metadata, proxying original", "error", err)
-		w.Header().Set("Content-Type", contentTypeJSON)
+		w.Header().Set(headerContentType, contentTypeJSON)
 		w.WriteHeader(http.StatusOK)
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", contentTypeJSON)
+	w.Header().Set(headerContentType, contentTypeJSON)
 	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write(rewritten)
 }
@@ -285,12 +287,15 @@ func (h *NPMHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 		r.Context(), "npm", packageName, version, filename, downloadURL,
 	)
 	if err != nil {
-		if errors.Is(err, ErrUpstreamNotFound) {
+		switch {
+		case errors.Is(err, ErrUpstreamNotFound):
 			JSONError(w, http.StatusNotFound, "package not found")
-			return
+		case errors.Is(err, ErrArtifactBlocked):
+			JSONError(w, http.StatusForbidden, err.Error())
+		default:
+			h.proxy.Logger.Error("failed to get artifact", "error", err)
+			JSONError(w, http.StatusBadGateway, "failed to fetch package")
 		}
-		h.proxy.Logger.Error("failed to get artifact", "error", err)
-		JSONError(w, http.StatusBadGateway, "failed to fetch package")
 		return
 	}
 
@@ -302,14 +307,22 @@ func (h *NPMHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 // predictable and lockfiles record them directly, so `npm ci` reaches the
 // download path without ever requesting metadata.
 //
-// The packument is served from the metadata cache, so this normally costs no
-// extra upstream request. A version with no usable publish time is allowed
-// through, matching how applyCooldownFiltering treats it.
+// A version's publish time is immutable, so the check reads the stored
+// versions row first and only falls back to the packument for a version the
+// proxy has never seen, persisting the parsed time so the packument is
+// fetched and parsed at most once per version. A version with no usable
+// publish time is allowed through, matching how applyCooldownFiltering
+// treats it.
 func (h *NPMHandler) versionInCooldown(r *http.Request, packageName, version string) bool {
 	if h.proxy.Cooldown == nil || !h.proxy.Cooldown.Enabled() {
 		return false
 	}
 
+	versionPURL := canonicalVersionPURL("npm", packageName, version)
+	if ver, err := h.proxy.DB.GetVersionByPURL(versionPURL); err == nil && ver != nil && ver.PublishedAt.Valid {
+		return !h.proxy.Cooldown.IsAllowed("npm", canonicalPackagePURL("npm", packageName), ver.PublishedAt.Time)
+	}
+
 	upstreamURL := fmt.Sprintf("%s/%s", h.upstreamURL, url.PathEscape(packageName))
 
 	body, _, err := h.proxy.FetchOrCacheMetadata(r.Context(), "npm", packageName, upstreamURL, contentTypeJSON)
@@ -338,6 +351,11 @@ func (h *NPMHandler) versionInCooldown(r *http.Request, packageName, version str
 		return false
 	}
 
+	if err := h.proxy.DB.SetVersionPublishedAt(versionPURL, canonicalPackagePURL("npm", packageName), publishedAt); err != nil {
+		h.proxy.Logger.Warn("cooldown: could not store npm publish time",
+			"package", packageName, "version", version, "error", err)
+	}
+
 	return !h.proxy.Cooldown.IsAllowed("npm", canonicalPackagePURL("npm", packageName), publishedAt)
 }
 

internal/handler/npm_test.go

@@ -2,11 +2,13 @@ package handler
 
 import (
 	"encoding/json"
+	"errors"
 	"io"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -430,6 +432,25 @@ func TestNPMHandlerUsesAbbreviatedMetadata(t *testing.T) {
 			t.Errorf("Accept = %q, want %q (cooldown requires full metadata)", gotAccept, contentTypeJSON)
 		}
 	})
+
+	t.Run("full metadata option uses full metadata without cooldown", func(t *testing.T) {
+		proxy := testProxy()
+		proxy.NPMFullMetadata = true
+
+		h := &NPMHandler{
+			proxy:       proxy,
+			upstreamURL: upstream.URL,
+			proxyURL:    "http://proxy.local",
+		}
+
+		req := httptest.NewRequest(http.MethodGet, "/testpkg", nil)
+		w := httptest.NewRecorder()
+		h.handlePackageMetadata(w, req)
+
+		if gotAccept != contentTypeJSON {
+			t.Errorf("Accept = %q, want %q (npm_full_metadata requires full metadata)", gotAccept, contentTypeJSON)
+		}
+	})
 }
 
 func TestNPMHandlerMetadataNotFound(t *testing.T) {
@@ -532,3 +553,159 @@ func TestNPMDownloadCooldownDisabled(t *testing.T) {
 		t.Error("versionInCooldown = true, want false when cooldown is not configured")
 	}
 }
+
+func TestNPMDownloadCooldownUsesStoredPublishTime(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		t.Error("metadata must not be fetched when the publish time is already stored")
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer upstream.Close()
+
+	tests := []struct {
+		name        string
+		version     string
+		publishedAt time.Time
+		wantStatus  int
+	}{
+		{"stored time before the window serves the tarball", testVersion100, time.Now().Add(-30 * 24 * time.Hour), http.StatusOK},
+		{"stored time inside the window is withheld", "2.0.0", time.Now().Add(-1 * time.Hour), http.StatusNotFound},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			proxy, db, _, fetcher := setupTestProxy(t)
+			proxy.HTTPClient = upstream.Client()
+			proxy.Cooldown = &cooldown.Config{Default: "7d"}
+			fetcher.artifact = &fetch.Artifact{
+				Body:        io.NopCloser(strings.NewReader("tarball data")),
+				ContentType: "application/octet-stream",
+			}
+
+			if err := db.SetVersionPublishedAt("pkg:npm/leftpad@"+tt.version, "pkg:npm/leftpad", tt.publishedAt); err != nil {
+				t.Fatalf("seeding publish time failed: %v", err)
+			}
+
+			h := NewNPMHandler(proxy, "http://proxy.test", upstream.URL)
+			srv := httptest.NewServer(h.Routes())
+			defer srv.Close()
+
+			resp, err := http.Get(srv.URL + "/leftpad/-/leftpad-" + tt.version + ".tgz")
+			if err != nil {
+				t.Fatalf("request failed: %v", err)
+			}
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != tt.wantStatus {
+				t.Errorf("status = %d, want %d", resp.StatusCode, tt.wantStatus)
+			}
+		})
+	}
+}
+
+func TestNPMDownloadCooldownFetchesMetadataOnce(t *testing.T) {
+	now := time.Now()
+	packument := `{
+		"name": "leftpad",
+		"dist-tags": {"latest": "1.0.0"},
+		"time": {
+			"1.0.0": "` + now.Add(-30*24*time.Hour).Format(time.RFC3339) + `"
+		},
+		"versions": {"1.0.0": {}}
+	}`
+
+	var metadataRequests atomic.Int64
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		metadataRequests.Add(1)
+		w.Header().Set("Content-Type", contentTypeJSON)
+		_, _ = io.WriteString(w, packument)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, fetcher := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.Cooldown = &cooldown.Config{Default: "7d"}
+
+	h := NewNPMHandler(proxy, "http://proxy.test", upstream.URL)
+	srv := httptest.NewServer(h.Routes())
+	defer srv.Close()
+
+	// The first download parses the packument once and persists the publish
+	// time; caching the artifact afterwards upserts the versions row without a
+	// publish time, which must not erase the stored value. The second download
+	// must answer from the stored time alone.
+	for i := 0; i < 2; i++ {
+		fetcher.artifact = &fetch.Artifact{
+			Body:        io.NopCloser(strings.NewReader("tarball data")),
+			ContentType: "application/octet-stream",
+		}
+		resp, err := http.Get(srv.URL + "/leftpad/-/leftpad-" + testVersion100 + ".tgz")
+		if err != nil {
+			t.Fatalf("request %d failed: %v", i+1, err)
+		}
+		_ = resp.Body.Close()
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("request %d status = %d, want %d", i+1, resp.StatusCode, http.StatusOK)
+		}
+	}
+
+	if got := metadataRequests.Load(); got != 1 {
+		t.Errorf("metadata requests = %d, want 1", got)
+	}
+}
+
+// TestNPMDownloadErrorResponsesAreJSON guards against a regression where
+// routing handleDownload's error path through the shared serveArtifactError
+// helper silently switched npm's 404/502 tarball error bodies from JSON to
+// plain text; npm clients expect a JSON {"error": "..."} body on every
+// download failure, including the newer scan-blocked (403) case.
+func TestNPMDownloadErrorResponsesAreJSON(t *testing.T) {
+	tests := []struct {
+		name       string
+		fetchErr   error
+		blocked    bool
+		wantStatus int
+	}{
+		{"upstream not found", fetch.ErrNotFound, false, http.StatusNotFound},
+		{"upstream failure", errors.New("connection refused"), false, http.StatusBadGateway},
+		{"blocked by scan", nil, true, http.StatusForbidden},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			proxy, _, _, fetcher := setupTestProxy(t)
+			proxy.ScanSigningKey = []byte("test-signing-key")
+			if tt.blocked {
+				proxy.Scanners = newTestScanGroup(t, newTestScanServer(t, false, "malware detected").URL, false)
+			}
+			fetcher.fetchErr = tt.fetchErr
+			fetcher.artifact = &fetch.Artifact{
+				Body:        io.NopCloser(strings.NewReader("tarball data")),
+				ContentType: "application/octet-stream",
+			}
+
+			h := NewNPMHandler(proxy, "http://proxy.test", "http://upstream.invalid")
+			srv := httptest.NewServer(h.Routes())
+			defer srv.Close()
+
+			resp, err := http.Get(srv.URL + "/leftpad/-/leftpad-1.0.0.tgz")
+			if err != nil {
+				t.Fatalf("request failed: %v", err)
+			}
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != tt.wantStatus {
+				t.Errorf("status = %d, want %d", resp.StatusCode, tt.wantStatus)
+			}
+			if ct := resp.Header.Get("Content-Type"); ct != contentTypeJSON {
+				t.Errorf("Content-Type = %q, want %q", ct, contentTypeJSON)
+			}
+			var body map[string]any
+			if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+				t.Fatalf("response body is not valid JSON: %v", err)
+			}
+			if _, ok := body["error"]; !ok {
+				t.Errorf("response body %v missing \"error\" key", body)
+			}
+		})
+	}
+}

internal/handler/nuget.go

@@ -11,13 +11,15 @@ import (
 )
 
 const (
-	nugetUpstream = "https://api.nuget.org"
+	nugetUpstream       = "https://api.nuget.org"
+	nugetSearchUpstream = "https://azuresearch-usnc.nuget.org"
 )
 
 // NuGetHandler handles NuGet V3 API protocol requests.
 type NuGetHandler struct {
 	proxy       *Proxy
 	upstreamURL string
+	searchURL   string
 	proxyURL    string
 }
 
@@ -26,10 +28,20 @@ func NewNuGetHandler(proxy *Proxy, proxyURL string) *NuGetHandler {
 	return &NuGetHandler{
 		proxy:       proxy,
 		upstreamURL: nugetUpstream,
+		searchURL:   nugetSearchUpstream,
 		proxyURL:    strings.TrimSuffix(proxyURL, "/"),
 	}
 }
 
+// NewNuGetHandlerWithUpstreams creates a NuGet handler with custom API and
+// search upstreams.
+func NewNuGetHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, searchURL string) *NuGetHandler {
+	h := NewNuGetHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, nugetUpstream)
+	h.searchURL = configuredUpstreamURL(searchURL, nugetSearchUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for NuGet requests.
 func (h *NuGetHandler) Routes() http.Handler {
 	mux := http.NewServeMux()
@@ -73,12 +85,12 @@ func (h *NuGetHandler) handleServiceIndex(w http.ResponseWriter, r *http.Request
 	rewritten, err := h.rewriteServiceIndex(body)
 	if err != nil {
 		h.proxy.Logger.Warn("failed to rewrite service index, proxying original", "error", err)
-		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set(headerContentType, "application/json")
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	_, _ = w.Write(rewritten)
 }
 
@@ -103,55 +115,31 @@ func (h *NuGetHandler) rewriteServiceIndex(body []byte) ([]byte, error) {
 		id, _ := rmap["@id"].(string)
 		rtype, _ := rmap["@type"].(string)
 
-		// Rewrite URLs for services we proxy
-		if id != "" && h.shouldRewriteService(rtype) {
-			newURL := h.rewriteNuGetURL(id)
-			rmap["@id"] = newURL
+		// Rewrite URLs for services we proxy. The service type determines the
+		// local route because an upstream index may advertise a different host.
+		if id != "" {
+			rmap["@id"] = h.rewriteNuGetURL(id, rtype)
 		}
 	}
 
 	return json.Marshal(index)
 }
 
-// shouldRewriteService returns true if the service type should be rewritten.
-func (h *NuGetHandler) shouldRewriteService(serviceType string) bool {
-	// Rewrite package content and registration services
-	rewriteTypes := []string{
-		"PackageBaseAddress/3.0.0",
-		"RegistrationsBaseUrl/3.6.0",
-		"RegistrationsBaseUrl/Versioned",
-		"SearchQueryService",
-		"SearchQueryService/3.0.0-rc",
-		"SearchQueryService/3.5.0",
-		"SearchAutocompleteService",
-		"SearchAutocompleteService/3.5.0",
+// rewriteNuGetURL rewrites a NuGet service URL based on its advertised type.
+// Service types the proxy does not handle are returned unchanged.
+func (h *NuGetHandler) rewriteNuGetURL(origURL, serviceType string) string {
+	switch serviceType {
+	case "PackageBaseAddress/3.0.0":
+		return h.proxyURL + "/nuget/v3-flatcontainer/"
+	case "RegistrationsBaseUrl/3.6.0", "RegistrationsBaseUrl/Versioned":
+		return h.proxyURL + "/nuget/v3/registration5-gz-semver2/"
+	case "SearchQueryService", "SearchQueryService/3.0.0-rc", "SearchQueryService/3.5.0":
+		return h.proxyURL + "/nuget/query"
+	case "SearchAutocompleteService", "SearchAutocompleteService/3.5.0":
+		return h.proxyURL + "/nuget/autocomplete"
+	default:
+		return origURL
 	}
-
-	for _, t := range rewriteTypes {
-		if serviceType == t {
-			return true
-		}
-	}
-	return false
-}
-
-// rewriteNuGetURL rewrites a NuGet API URL to point at this proxy.
-func (h *NuGetHandler) rewriteNuGetURL(origURL string) string {
-	// Map known NuGet API endpoints to our proxy paths
-	replacements := map[string]string{
-		"https://api.nuget.org/v3-flatcontainer/":            h.proxyURL + "/nuget/v3-flatcontainer/",
-		"https://api.nuget.org/v3/registration5-gz-semver2/": h.proxyURL + "/nuget/v3/registration5-gz-semver2/",
-		"https://azuresearch-usnc.nuget.org/query":           h.proxyURL + "/nuget/query",
-		"https://azuresearch-usnc.nuget.org/autocomplete":    h.proxyURL + "/nuget/autocomplete",
-	}
-
-	for old, new := range replacements {
-		if strings.HasPrefix(origURL, old) {
-			return strings.Replace(origURL, old, new, 1)
-		}
-	}
-
-	return origURL
 }
 
 // handleRegistration proxies NuGet registration pages, applying cooldown filtering.
@@ -200,12 +188,12 @@ func (h *NuGetHandler) handleRegistration(w http.ResponseWriter, r *http.Request
 	filtered, err := h.applyCooldownFiltering(body)
 	if err != nil {
 		h.proxy.Logger.Warn("failed to filter registration, proxying original", "error", err)
-		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set(headerContentType, "application/json")
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	_, _ = w.Write(filtered)
 }
 
@@ -363,7 +351,7 @@ func (h *NuGetHandler) buildUpstreamURL(r *http.Request) string {
 
 	// Handle query and autocomplete which go to azuresearch
 	if strings.HasPrefix(path, "/query") || strings.HasPrefix(path, "/autocomplete") {
-		return "https://azuresearch-usnc.nuget.org" + path + "?" + r.URL.RawQuery
+		return h.searchURL + path + "?" + r.URL.RawQuery
 	}
 
 	return h.upstreamURL + path

internal/handler/nuget_test.go

@@ -91,75 +91,82 @@ func TestNuGetRewriteServiceIndex(t *testing.T) {
 	}
 }
 
-func TestNuGetShouldRewriteService(t *testing.T) {
-	h := &NuGetHandler{}
-
-	rewriteTypes := []string{
-		"PackageBaseAddress/3.0.0",
-		"RegistrationsBaseUrl/3.6.0",
-		"RegistrationsBaseUrl/Versioned",
-		"SearchQueryService",
-		"SearchQueryService/3.0.0-rc",
-		"SearchQueryService/3.5.0",
-		"SearchAutocompleteService",
-		"SearchAutocompleteService/3.5.0",
-	}
-
-	for _, stype := range rewriteTypes {
-		if !h.shouldRewriteService(stype) {
-			t.Errorf("shouldRewriteService(%q) = false, want true", stype)
-		}
-	}
-
-	noRewriteTypes := []string{
-		"SomeOtherService/1.0.0",
-		"PackagePublish/2.0.0",
-		"",
-		"SearchQueryService/99.0.0",
-	}
-
-	for _, stype := range noRewriteTypes {
-		if h.shouldRewriteService(stype) {
-			t.Errorf("shouldRewriteService(%q) = true, want false", stype)
-		}
-	}
-}
-
 func TestNuGetRewriteURL(t *testing.T) {
 	h := &NuGetHandler{
 		proxyURL: "http://localhost:8080",
 	}
 
 	tests := []struct {
-		input string
-		want  string
+		input       string
+		serviceType string
+		want        string
 	}{
 		{
 			"https://api.nuget.org/v3-flatcontainer/",
+			"PackageBaseAddress/3.0.0",
 			"http://localhost:8080/nuget/v3-flatcontainer/",
 		},
 		{
 			"https://api.nuget.org/v3/registration5-gz-semver2/",
+			"RegistrationsBaseUrl/3.6.0",
+			"http://localhost:8080/nuget/v3/registration5-gz-semver2/",
+		},
+		{
+			"https://api.nuget.org/v3/registration5-gz-semver2/",
+			"RegistrationsBaseUrl/Versioned",
 			"http://localhost:8080/nuget/v3/registration5-gz-semver2/",
 		},
 		{
 			"https://azuresearch-usnc.nuget.org/query",
+			"SearchQueryService",
+			"http://localhost:8080/nuget/query",
+		},
+		{
+			"https://azuresearch-usnc.nuget.org/query",
+			"SearchQueryService/3.0.0-rc",
+			"http://localhost:8080/nuget/query",
+		},
+		{
+			"https://azuresearch-usnc.nuget.org/query",
+			"SearchQueryService/3.5.0",
 			"http://localhost:8080/nuget/query",
 		},
 		{
 			"https://azuresearch-usnc.nuget.org/autocomplete",
+			"SearchAutocompleteService",
+			"http://localhost:8080/nuget/autocomplete",
+		},
+		{
+			"https://azuresearch-usnc.nuget.org/autocomplete",
+			"SearchAutocompleteService/3.5.0",
 			"http://localhost:8080/nuget/autocomplete",
 		},
 		{
 			"https://example.com/unknown",
+			"SomeOtherService/1.0.0",
 			"https://example.com/unknown",
 		},
+		{
+			"https://api.nuget.org/v2/package",
+			"PackagePublish/2.0.0",
+			"https://api.nuget.org/v2/package",
+		},
+		{
+			"https://azuresearch-usnc.nuget.org/query",
+			"SearchQueryService/99.0.0",
+			"https://azuresearch-usnc.nuget.org/query",
+		},
+		{
+			"https://example.com/resource",
+			"",
+			"https://example.com/resource",
+		},
 	}
 
 	for _, tt := range tests {
-		got := h.rewriteNuGetURL(tt.input)
+		got := h.rewriteNuGetURL(tt.input, tt.serviceType)
 		if got != tt.want {
-			t.Errorf("rewriteNuGetURL(%q) = %q, want %q", tt.input, got, tt.want)
+			t.Errorf("rewriteNuGetURL(%q, %q) = %q, want %q", tt.input, tt.serviceType, got, tt.want)
 		}
 	}
 }
@@ -458,6 +465,7 @@ func TestNuGetProxyUpstreamForwardsAcceptEncoding(t *testing.T) {
 func TestNuGetBuildUpstreamURL(t *testing.T) {
 	h := &NuGetHandler{
 		upstreamURL: "https://api.nuget.org",
+		searchURL:   "https://azuresearch-usnc.nuget.org",
 	}
 
 	tests := []struct {
@@ -736,6 +744,7 @@ func TestNuGetHandleDownloadMissingFilename(t *testing.T) {
 func TestNuGetBuildUpstreamURLQueryPath(t *testing.T) {
 	h := &NuGetHandler{
 		upstreamURL: "https://api.nuget.org",
+		searchURL:   "https://azuresearch-usnc.nuget.org",
 	}
 
 	// Query endpoint should go to azuresearch
@@ -750,6 +759,7 @@ func TestNuGetBuildUpstreamURLQueryPath(t *testing.T) {
 func TestNuGetBuildUpstreamURLAutocompletePath(t *testing.T) {
 	h := &NuGetHandler{
 		upstreamURL: "https://api.nuget.org",
+		searchURL:   "https://azuresearch-usnc.nuget.org",
 	}
 
 	req := httptest.NewRequest(http.MethodGet, "/autocomplete?q=new&take=10", nil)

internal/handler/proxy_cached_encoding_test.go

@@ -0,0 +1,260 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// gzipWhenAskedUpstream serves compressed bytes with Content-Encoding: gzip
+// when the request advertises gzip, plain bytes otherwise, like a CDN that
+// compresses on the fly. It records the last Accept-Encoding it saw and counts
+// every request before the availability gate so a cache-miss refetch during a
+// simulated outage is observable.
+type gzipWhenAskedUpstream struct {
+	*httptest.Server
+	available      atomic.Bool
+	requests       atomic.Int32
+	acceptEncoding atomic.Value // string
+}
+
+func newGzipWhenAskedUpstream(plain, compressed []byte) *gzipWhenAskedUpstream {
+	u := &gzipWhenAskedUpstream{}
+	u.available.Store(true)
+	u.Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		u.requests.Add(1)
+		u.acceptEncoding.Store(r.Header.Get(headerAcceptEncoding))
+		if !u.available.Load() {
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set(headerContentType, contentTypeJSON)
+		if strings.Contains(r.Header.Get(headerAcceptEncoding), "gzip") {
+			w.Header().Set(headerContentEncoding, "gzip")
+			_, _ = w.Write(compressed)
+			return
+		}
+		_, _ = w.Write(plain)
+	}))
+	return u
+}
+
+func (u *gzipWhenAskedUpstream) sawAcceptEncoding() string {
+	s, _ := u.acceptEncoding.Load().(string)
+	return s
+}
+
+// serveGzip issues one request through proxyCachedWithEncoding asking the
+// upstream for gzip.
+func serveGzip(proxy *Proxy, upstreamURL string) *httptest.ResponseRecorder {
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "/index.json", nil)
+	proxy.proxyCachedWithEncoding(w, r, upstreamURL, "gzip-test", "index", "gzip", "*/*")
+	return w
+}
+
+func assertGzipResponse(t *testing.T, label string, w *httptest.ResponseRecorder, compressed []byte) {
+	t.Helper()
+	if w.Code != http.StatusOK {
+		t.Fatalf("%s: status = %d, want 200: %s", label, w.Code, w.Body.String())
+	}
+	if !bytes.Equal(w.Body.Bytes(), compressed) {
+		t.Errorf("%s: body is not the compressed bytes (got %d, want %d)", label, w.Body.Len(), len(compressed))
+	}
+	if got := w.Header().Get(headerContentEncoding); got != "gzip" {
+		t.Errorf("%s: Content-Encoding = %q, want %q", label, got, "gzip")
+	}
+	if got := w.Header().Get(headerContentLength); got != strconv.Itoa(len(compressed)) {
+		t.Errorf("%s: Content-Length = %q, want %d", label, got, len(compressed))
+	}
+}
+
+// TestProxyCachedWithEncoding_GzipCachesAndReplays covers the cached path:
+// requesting gzip upstream stores the compressed bytes plus Content-Encoding
+// and replays both from cache without contacting the upstream again.
+func TestProxyCachedWithEncoding_GzipCachesAndReplays(t *testing.T) {
+	plain := []byte(`{"packages":{}}`)
+	compressed := gzipPayload(t, plain)
+	upstream := newGzipWhenAskedUpstream(plain, compressed)
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+
+	first := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "first", first, compressed)
+	if got := upstream.sawAcceptEncoding(); got != "gzip" {
+		t.Errorf("upstream Accept-Encoding = %q, want %q", got, "gzip")
+	}
+
+	before := upstream.requests.Load()
+	upstream.available.Store(false)
+	cached := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "cached", cached, compressed)
+	if upstream.requests.Load() != before {
+		t.Errorf("cached replay hit upstream: requests %d -> %d", before, upstream.requests.Load())
+	}
+}
+
+// TestProxyCachedWithEncoding_GzipStreamPath covers the cache_metadata=false
+// branch: the streaming path must request gzip and forward Content-Encoding.
+func TestProxyCachedWithEncoding_GzipStreamPath(t *testing.T) {
+	plain := []byte(`{"packages":{}}`)
+	compressed := gzipPayload(t, plain)
+	upstream := newGzipWhenAskedUpstream(plain, compressed)
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = false
+	proxy.HTTPClient = upstream.Client()
+
+	w := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "stream", w, compressed)
+	if got := upstream.sawAcceptEncoding(); got != "gzip" {
+		t.Errorf("stream path upstream Accept-Encoding = %q, want %q", got, "gzip")
+	}
+}
+
+// TestProxyCachedWithEncoding_GzipSurvivesCacheWriteFailure covers the failure
+// the gzip mode makes reachable: when the metadata cache write fails the
+// freshly fetched body is still served, so its Content-Encoding must come from
+// the fetch and not from the (unwritten) cache row -- otherwise gzip bytes go
+// out labelled application/json with no Content-Encoding.
+func TestProxyCachedWithEncoding_GzipSurvivesCacheWriteFailure(t *testing.T) {
+	plain := []byte(`{"packages":{}}`)
+	compressed := gzipPayload(t, plain)
+	upstream := newGzipWhenAskedUpstream(plain, compressed)
+	defer upstream.Close()
+
+	proxy, _, store, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.HTTPClient = upstream.Client()
+	store.storeErr = errors.New("disk full")
+
+	w := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "store-failure", w, compressed)
+}
+
+// TestProxyCachedWithEncoding_GzipStaleFallbackKeepsEncoding pins the
+// stale-fallback return: when the upstream fails after the entry has expired,
+// the stored gzip blob is served with its Content-Encoding taken from the
+// cache row.
+func TestProxyCachedWithEncoding_GzipStaleFallbackKeepsEncoding(t *testing.T) {
+	plain := []byte(`{"packages":{}}`)
+	compressed := gzipPayload(t, plain)
+	upstream := newGzipWhenAskedUpstream(plain, compressed)
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = 0 // every request revalidates; an upstream failure falls back to the stale row
+	proxy.HTTPClient = upstream.Client()
+
+	first := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "first", first, compressed)
+
+	upstream.available.Store(false)
+	stale := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "stale", stale, compressed)
+}
+
+// TestProxyCachedWithEncoding_UpsertFailureDiscardsBlob covers the row-write
+// failure: when the gzip blob is stored but the cache row cannot be updated,
+// the blob must be discarded so a later stale fallback cannot serve gzip
+// bytes with the previous row's encoding. The fresh response is still
+// correct because its encoding comes from the fetch.
+func TestProxyCachedWithEncoding_UpsertFailureDiscardsBlob(t *testing.T) {
+	plain := []byte(`{"packages":{}}`)
+	compressed := gzipPayload(t, plain)
+	upstream := newGzipWhenAskedUpstream(plain, compressed)
+	defer upstream.Close()
+
+	proxy, db, store, _ := setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = 0 // every request revalidates
+	proxy.HTTPClient = upstream.Client()
+
+	// Seed an identity row + plain blob, as every key has before the gzip rollout.
+	w := httptest.NewRecorder()
+	proxy.proxyCachedWithEncoding(w, httptest.NewRequest(http.MethodGet, "/index.json", nil),
+		upstream.URL+"/index.json", "gzip-test", "index", "identity", "*/*")
+	if w.Code != http.StatusOK {
+		t.Fatalf("seed status = %d, want 200", w.Code)
+	}
+
+	// Now DB writes fail while reads keep working.
+	db.SetMaxOpenConns(1)
+	if _, err := db.Exec("PRAGMA query_only=1"); err != nil {
+		t.Fatalf("PRAGMA query_only=1: %v", err)
+	}
+	fresh := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "fresh with failed row write", fresh, compressed)
+
+	storagePath := metadataStoragePath("gzip-test", "index")
+	if exists, _ := store.Exists(context.Background(), storagePath); exists {
+		t.Fatalf("blob %s still present after the row write failed", storagePath)
+	}
+
+	// Upstream down: the stale fallback must not serve the orphaned gzip
+	// blob under the old identity row.
+	if _, err := db.Exec("PRAGMA query_only=0"); err != nil {
+		t.Fatalf("PRAGMA query_only=0: %v", err)
+	}
+	upstream.available.Store(false)
+	stale := serveGzip(proxy, upstream.URL+"/index.json")
+	if stale.Code == http.StatusOK {
+		t.Fatalf("stale fallback served status 200 (Content-Encoding=%q, %d bytes) from an orphaned blob; want an error",
+			stale.Header().Get(headerContentEncoding), stale.Body.Len())
+	}
+}
+
+// TestProxyCachedWithEncoding_StaleFallbackRereadsRow covers the rollout race:
+// a request that read the identity row, lost the upstream race to a request
+// that stored the gzip blob, and then failed upstream must label the blob
+// with the row as it is now, not with the row it read at the start.
+func TestProxyCachedWithEncoding_StaleFallbackRereadsRow(t *testing.T) {
+	plain := []byte(`{"packages":{}}`)
+	compressed := gzipPayload(t, plain)
+
+	var proxy *Proxy
+	var requests atomic.Int32
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if requests.Add(1) == 1 {
+			w.Header().Set(headerContentType, contentTypeJSON)
+			_, _ = w.Write(plain) // seed request: identity
+			return
+		}
+		// Second request has already read the identity row. Simulate a
+		// concurrent request finishing first: store the gzip blob and row,
+		// then fail this request so it takes the stale fallback.
+		proxy.cacheMetadataBlob(r.Context(), "gzip-test", "index", metadataStoragePath("gzip-test", "index"),
+			&upstreamMetadata{body: compressed, contentType: contentTypeJSON, contentEncoding: "gzip"})
+		http.Error(w, "unavailable", http.StatusServiceUnavailable)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ = setupTestProxy(t)
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = 0
+	proxy.HTTPClient = upstream.Client()
+
+	w := httptest.NewRecorder()
+	proxy.proxyCachedWithEncoding(w, httptest.NewRequest(http.MethodGet, "/index.json", nil),
+		upstream.URL+"/index.json", "gzip-test", "index", "identity", "*/*")
+	if w.Code != http.StatusOK {
+		t.Fatalf("seed status = %d, want 200", w.Code)
+	}
+
+	raced := serveGzip(proxy, upstream.URL+"/index.json")
+	assertGzipResponse(t, "stale fallback after concurrent gzip store", raced, compressed)
+}

internal/handler/pub.go

@@ -30,6 +30,13 @@ func NewPubHandler(proxy *Proxy, proxyURL string) *PubHandler {
 	}
 }
 
+// NewPubHandlerWithUpstream creates a pub handler with a custom upstream.
+func NewPubHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *PubHandler {
+	h := NewPubHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, pubUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for pub requests.
 func (h *PubHandler) Routes() http.Handler {
 	mux := http.NewServeMux()
@@ -65,7 +72,10 @@ func (h *PubHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 	h.proxy.Logger.Info("pub download request",
 		"name", name, "version", version)
 
-	result, err := h.proxy.GetOrFetchArtifact(r.Context(), "pub", name, version, filename)
+	downloadURL := h.upstreamURL + r.URL.Path
+	result, err := h.proxy.GetOrFetchArtifactFromURL(
+		r.Context(), "pub", name, version, filename, downloadURL,
+	)
 	if err != nil {
 		h.proxy.serveArtifactError(w, err, "failed to fetch package")
 		return
@@ -100,13 +110,13 @@ func (h *PubHandler) handlePackageMetadata(w http.ResponseWriter, r *http.Reques
 	rewritten, err := h.rewriteMetadata(name, body)
 	if err != nil {
 		h.proxy.Logger.Warn("failed to rewrite metadata, proxying original", "error", err)
-		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set(headerContentType, "application/json")
 		w.WriteHeader(http.StatusOK)
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write(rewritten)
 }

internal/handler/pypi.go

@@ -7,19 +7,27 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"mime"
 	"net/http"
-	"net/url"
 	"regexp"
+	"strconv"
 	"strings"
 	"time"
 )
 
 const (
-	pypiUpstream     = "https://pypi.org"
-	minWheelParts    = 5 // name + version + python + abi + platform
-	minSubmatchParts = 2 // full match + first capture group
-	minPyPIPathParts = 3 // hash_prefix + hash + filename
-	minEggParts      = 3 // name + version + python tag
+	pypiUpstream         = "https://pypi.org"
+	pypiDownloadUpstream = "https://files.pythonhosted.org"
+	pypiSimpleJSON       = "application/vnd.pypi.simple.v1+json"
+	pypiSimpleHTML       = "application/vnd.pypi.simple.v1+html"
+	pypiSimpleLatestJSON = "application/vnd.pypi.simple.latest+json"
+	pypiSimpleLatestHTML = "application/vnd.pypi.simple.latest+html"
+	pypiLegacyHTML       = "text/html"
+	pypiExactSpecificity = 2
+	minWheelParts        = 5 // name + version + python + abi + platform
+	minSubmatchParts     = 2 // full match + first capture group
+	minPyPIPathParts     = 3 // hash_prefix + hash + filename
+	minEggParts          = 3 // name + version + python tag
 
 	// PyPIMetadataSuffix is the PEP 658 core-metadata sidecar suffix that pip
 	// appends to a distribution URL when the index advertises core metadata.
@@ -31,25 +39,36 @@ const (
 
 // PyPIHandler handles PyPI registry protocol requests.
 type PyPIHandler struct {
-	proxy       *Proxy
-	upstreamURL string
-	proxyURL    string
+	proxy          *Proxy
+	upstreamURL    string
+	downloadURL    string
+	downloadHrefRe *regexp.Regexp
+	proxyURL       string
 }
 
 // NewPyPIHandler creates a new PyPI protocol handler.
 func NewPyPIHandler(proxy *Proxy, proxyURL string) *PyPIHandler {
-	return &PyPIHandler{
+	return NewPyPIHandlerWithUpstreams(proxy, proxyURL, "", "")
+}
+
+// NewPyPIHandlerWithUpstreams creates a PyPI handler with custom API and
+// package download upstreams.
+func NewPyPIHandlerWithUpstreams(proxy *Proxy, proxyURL, upstreamURL, downloadURL string) *PyPIHandler {
+	h := &PyPIHandler{
 		proxy:       proxy,
-		upstreamURL: pypiUpstream,
+		upstreamURL: configuredUpstreamURL(upstreamURL, pypiUpstream),
+		downloadURL: configuredUpstreamURL(downloadURL, pypiDownloadUpstream),
 		proxyURL:    strings.TrimSuffix(proxyURL, "/"),
 	}
+	h.downloadHrefRe = regexp.MustCompile(`href="(` + regexp.QuoteMeta(h.downloadURL) + `/packages/[^"]+)"`)
+	return h
 }
 
 // Routes returns the HTTP handler for PyPI requests.
 func (h *PyPIHandler) Routes() http.Handler {
 	mux := http.NewServeMux()
 
-	// Simple API (used by pip)
+	// Simple API
 	mux.HandleFunc("GET /simple/", h.handleSimpleIndex)
 	mux.HandleFunc("GET /simple/{name}/", h.handleSimplePackage)
 
@@ -80,9 +99,10 @@ func (h *PyPIHandler) handleSimplePackage(w http.ResponseWriter, r *http.Request
 	h.proxy.Logger.Info("pypi simple request", "package", name)
 
 	upstreamURL := fmt.Sprintf("%s/simple/%s/", h.upstreamURL, name)
-	cacheKey := name + "/simple"
+	accept := selectPyPISimpleRepresentation(r.Header.Get("Accept"))
+	cacheKey := pypiSimpleCacheKey(name, accept)
 
-	body, _, err := h.proxy.FetchOrCacheMetadata(r.Context(), "pypi", cacheKey, upstreamURL, "text/html")
+	body, contentType, err := h.proxy.FetchOrCacheMetadata(r.Context(), "pypi", cacheKey, upstreamURL, accept)
 	if err != nil {
 		if errors.Is(err, ErrUpstreamNotFound) {
 			http.Error(w, "not found", http.StatusNotFound)
@@ -99,35 +119,143 @@ func (h *PyPIHandler) handleSimplePackage(w http.ResponseWriter, r *http.Request
 		filteredVersions = h.fetchFilteredVersions(r, name)
 	}
 
-	rewritten := h.rewriteSimpleHTML(body, filteredVersions)
+	var rewritten []byte
+	if isJSONMediaType(contentType) {
+		rewritten, err = h.rewriteSimpleJSON(body, filteredVersions)
+		if err != nil {
+			h.proxy.Logger.Warn("failed to rewrite pypi simple json, proxying original", "error", err)
+			rewritten = body
+		}
+	} else {
+		rewritten = h.rewriteSimpleHTML(body, filteredVersions)
+	}
 
-	w.Header().Set("Content-Type", "text/html")
+	w.Header().Set(headerContentType, contentType)
+	ensureVaryAccept(w.Header())
 	w.WriteHeader(http.StatusOK)
 	_, _ = w.Write(rewritten)
 }
 
+func selectPyPISimpleRepresentation(accept string) string {
+	if strings.TrimSpace(accept) == "" {
+		return pypiLegacyHTML
+	}
+
+	type score struct {
+		quality     float64
+		specificity int
+		matched     bool
+	}
+
+	scores := map[string]score{
+		pypiSimpleJSON: {},
+		pypiSimpleHTML: {},
+		pypiLegacyHTML: {},
+	}
+
+	update := func(representation string, quality float64, specificity int) {
+		current := scores[representation]
+		if !current.matched || specificity > current.specificity ||
+			(specificity == current.specificity && quality > current.quality) {
+			scores[representation] = score{quality: quality, specificity: specificity, matched: true}
+		}
+	}
+
+	for part := range strings.SplitSeq(accept, ",") {
+		mediaType, params, err := mime.ParseMediaType(strings.TrimSpace(part))
+		if err != nil {
+			continue
+		}
+
+		quality := 1.0
+		if value, ok := params["q"]; ok {
+			quality, err = strconv.ParseFloat(value, 64)
+			if err != nil || quality < 0 || quality > 1 {
+				continue
+			}
+		}
+
+		switch mediaType {
+		case pypiSimpleJSON, pypiSimpleLatestJSON:
+			update(pypiSimpleJSON, quality, pypiExactSpecificity)
+		case pypiSimpleHTML, pypiSimpleLatestHTML:
+			update(pypiSimpleHTML, quality, pypiExactSpecificity)
+		case pypiLegacyHTML:
+			update(pypiLegacyHTML, quality, pypiExactSpecificity)
+		case "application/*":
+			update(pypiSimpleJSON, quality, 1)
+			update(pypiSimpleHTML, quality, 1)
+		case "text/*":
+			update(pypiLegacyHTML, quality, 1)
+		case "*/*":
+			update(pypiSimpleJSON, quality, 0)
+			update(pypiSimpleHTML, quality, 0)
+			update(pypiLegacyHTML, quality, 0)
+		}
+	}
+
+	bestMediaType := ""
+	bestScore := score{}
+	for _, mediaType := range []string{pypiSimpleJSON, pypiSimpleHTML, pypiLegacyHTML} {
+		candidate := scores[mediaType]
+		if !candidate.matched || candidate.quality == 0 {
+			continue
+		}
+		if bestMediaType == "" || candidate.quality > bestScore.quality ||
+			(candidate.quality == bestScore.quality && candidate.specificity > bestScore.specificity) {
+			bestMediaType = mediaType
+			bestScore = candidate
+		}
+	}
+
+	if bestMediaType == "" || bestScore.specificity == 0 {
+		return pypiLegacyHTML
+	}
+	return bestMediaType
+}
+
+func pypiSimpleCacheKey(name, mediaType string) string {
+	switch mediaType {
+	case pypiSimpleJSON:
+		return name + "/simple/json"
+	case pypiSimpleHTML:
+		return name + "/simple/html"
+	default:
+		return name + "/simple"
+	}
+}
+
+func isJSONMediaType(contentType string) bool {
+	mediaType, _, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		return false
+	}
+	return mediaType == "application/json" || strings.HasSuffix(mediaType, "+json")
+}
+
+func ensureVaryAccept(header http.Header) {
+	for _, value := range header.Values("Vary") {
+		for field := range strings.SplitSeq(value, ",") {
+			if strings.EqualFold(strings.TrimSpace(field), "Accept") {
+				return
+			}
+		}
+	}
+	header.Add("Vary", "Accept")
+}
+
 // fetchFilteredVersions fetches JSON metadata and returns a set of version strings
 // that should be filtered out due to cooldown.
 func (h *PyPIHandler) fetchFilteredVersions(r *http.Request, name string) map[string]bool {
 	jsonURL := fmt.Sprintf("%s/pypi/%s/json", h.upstreamURL, name)
-	req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, jsonURL, nil)
-	if err != nil {
-		return nil
-	}
-	req.Header.Set("Accept", "application/json")
 
-	resp, err := h.proxy.HTTPClient.Do(req)
+	body, _, err := h.proxy.FetchOrCacheMetadata(r.Context(), "pypi", name+"/json", jsonURL)
 	if err != nil {
 		return nil
 	}
-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusOK {
-		return nil
-	}
 
 	var metadata map[string]any
-	if err := json.NewDecoder(resp.Body).Decode(&metadata); err != nil {
+	if err := json.Unmarshal(body, &metadata); err != nil {
 		return nil
 	}
 
@@ -179,28 +307,54 @@ func (h *PyPIHandler) rewriteSimpleHTML(body []byte, filteredVersions map[string
 		})
 	}
 
-	// Match href attributes pointing to packages
-	// PyPI URLs look like: https://files.pythonhosted.org/packages/...
-	re := regexp.MustCompile(`href="(https://files\.pythonhosted\.org/packages/[^"]+)"`)
-
-	return re.ReplaceAllFunc(body, func(match []byte) []byte {
-		submatch := re.FindSubmatch(match)
+	// Match href attributes pointing to packages on the configured download host.
+	return h.downloadHrefRe.ReplaceAllFunc(body, func(match []byte) []byte {
+		submatch := h.downloadHrefRe.FindSubmatch(match)
 		if len(submatch) < minSubmatchParts {
 			return match
 		}
 
 		origURL := string(submatch[1])
 
-		u, err := url.Parse(origURL)
-		if err != nil {
-			return match
-		}
-
-		newURL := fmt.Sprintf("%s/pypi/packages%s", h.proxyURL, u.Path)
+		newURL := h.proxyURL + "/pypi/packages" + strings.TrimPrefix(origURL, h.downloadURL)
 		return []byte(fmt.Sprintf(`href="%s"`, newURL))
 	})
 }
 
+func (h *PyPIHandler) rewriteSimpleJSON(body []byte, filteredVersions map[string]bool) ([]byte, error) {
+	var metadata map[string]any
+	if err := json.Unmarshal(body, &metadata); err != nil {
+		return nil, err
+	}
+
+	files, ok := metadata["files"].([]any)
+	if !ok {
+		return nil, errors.New("pypi simple json response has no files array")
+	}
+
+	rewrittenFiles := make([]any, 0, len(files))
+	for _, file := range files {
+		entry, ok := file.(map[string]any)
+		if !ok {
+			rewrittenFiles = append(rewrittenFiles, file)
+			continue
+		}
+
+		if filename, ok := entry["filename"].(string); ok {
+			_, version := h.parseFilename(filename)
+			if version != "" && filteredVersions[version] {
+				continue
+			}
+		}
+
+		h.rewriteURLEntry(entry)
+		rewrittenFiles = append(rewrittenFiles, entry)
+	}
+
+	metadata["files"] = rewrittenFiles
+	return json.Marshal(metadata)
+}
+
 // handleJSON serves the JSON API package metadata.
 func (h *PyPIHandler) handleJSON(w http.ResponseWriter, r *http.Request) {
 	name := r.PathValue("name")
@@ -247,12 +401,12 @@ func (h *PyPIHandler) proxyAndRewriteJSON(w http.ResponseWriter, r *http.Request
 	rewritten, err := h.rewriteJSONMetadata(body)
 	if err != nil {
 		h.proxy.Logger.Warn("failed to rewrite metadata, proxying original", "error", err)
-		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set(headerContentType, "application/json")
 		_, _ = w.Write(body)
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set(headerContentType, "application/json")
 	_, _ = w.Write(rewritten)
 }
 
@@ -401,15 +555,8 @@ func (h *PyPIHandler) rewriteURLEntry(entry map[string]any) {
 		return
 	}
 
-	u, err := url.Parse(urlStr)
-	if err != nil {
-		return
-	}
-
-	// Only rewrite pythonhosted.org URLs
-	if u.Host == "files.pythonhosted.org" {
-		newURL := fmt.Sprintf("%s/pypi/packages%s", h.proxyURL, u.Path)
-		entry["url"] = newURL
+	if strings.HasPrefix(urlStr, h.downloadURL+"/packages/") {
+		entry["url"] = h.proxyURL + "/pypi/packages" + strings.TrimPrefix(urlStr, h.downloadURL)
 	}
 }
 
@@ -448,10 +595,9 @@ func (h *PyPIHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 	h.proxy.Logger.Info("pypi download request",
 		"name", name, "version", version, "filename", filename)
 
-	// Construct upstream URL; the incoming path starts with
-	// '/packages' so there is no need to include it in the format
-	// string
-	upstreamURL := fmt.Sprintf("https://files.pythonhosted.org/%s", path)
+	// The path value starts with 'packages/' (no leading slash), so add
+	// the separator here.
+	upstreamURL := fmt.Sprintf("%s/%s", h.downloadURL, path)
 
 	result, err := h.proxy.GetOrFetchArtifactFromURL(r.Context(), "pypi", name, version, filename, upstreamURL)
 	if err != nil {
@@ -639,7 +785,7 @@ func (h *PyPIHandler) proxySimple(w http.ResponseWriter, r *http.Request, path s
 		http.Error(w, "failed to create request", http.StatusInternalServerError)
 		return
 	}
-	req.Header.Set("Accept", "text/html")
+	req.Header.Set("Accept", selectPyPISimpleRepresentation(r.Header.Get("Accept")))
 
 	resp, err := h.proxy.HTTPClient.Do(req)
 	if err != nil {
@@ -654,6 +800,7 @@ func (h *PyPIHandler) proxySimple(w http.ResponseWriter, r *http.Request, path s
 			w.Header().Add(k, v)
 		}
 	}
+	ensureVaryAccept(w.Header())
 
 	w.WriteHeader(resp.StatusCode)
 	_, _ = io.Copy(w, resp.Body)

internal/handler/pypi_test.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -14,6 +15,267 @@ import (
 	"github.com/git-pkgs/registries/fetch"
 )
 
+const uvPyPIAccept = "application/vnd.pypi.simple.v1+json, application/vnd.pypi.simple.v1+html;q=0.2, text/html;q=0.01"
+
+type pypiRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f pypiRoundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
+	return f(r)
+}
+
+func pypiHTTPResponse(r *http.Request, contentType, body string) *http.Response {
+	return &http.Response{
+		StatusCode:    http.StatusOK,
+		Status:        "200 OK",
+		Header:        http.Header{"Content-Type": []string{contentType}},
+		Body:          io.NopCloser(strings.NewReader(body)),
+		ContentLength: int64(len(body)),
+		Request:       r,
+	}
+}
+
+func setupPyPIHandler(t testing.TB, transport pypiRoundTripFunc) (*PyPIHandler, *Proxy) {
+	t.Helper()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = &http.Client{Transport: transport}
+	h := NewPyPIHandlerWithUpstreams(proxy, "http://proxy.test", "", "")
+	h.upstreamURL = "https://pypi.test"
+	return h, proxy
+}
+
+func TestSelectPyPISimpleRepresentation(t *testing.T) {
+	tests := []struct {
+		name   string
+		accept string
+		want   string
+	}{
+		{"missing header uses legacy html", "", "text/html"},
+		{"wildcard uses legacy html", "*/*", "text/html"},
+		{"uv prefers json", uvPyPIAccept, pypiSimpleJSON},
+		{"json only", pypiSimpleJSON, pypiSimpleJSON},
+		{"latest json", pypiSimpleLatestJSON, pypiSimpleJSON},
+		{"vendor html", pypiSimpleHTML, pypiSimpleHTML},
+		{"higher html quality", pypiSimpleJSON + ";q=0.2, text/html;q=0.8", "text/html"},
+		{"json excluded", pypiSimpleJSON + ";q=0, text/html", "text/html"},
+		{"application wildcard", "application/*", pypiSimpleJSON},
+		{"unsupported type uses legacy html", "application/xml", "text/html"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := selectPyPISimpleRepresentation(tt.accept); got != tt.want {
+				t.Errorf("selectPyPISimpleRepresentation(%q) = %q, want %q", tt.accept, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestPyPISimplePackageNegotiatesJSON(t *testing.T) {
+	const upstreamBody = `{
+		"meta":{"api-version":"1.4"},
+		"name":"ruff",
+		"files":[{
+			"filename":"ruff-0.16.0-py3-none-any.whl",
+			"url":"https://files.pythonhosted.org/packages/ab/cd/ruff-0.16.0-py3-none-any.whl",
+			"hashes":{"sha256":"abc123"},
+			"upload-time":"2026-08-01T12:00:00Z"
+		}]
+	}`
+
+	var upstreamAccept string
+	h, _ := setupPyPIHandler(t, func(r *http.Request) (*http.Response, error) {
+		upstreamAccept = r.Header.Get("Accept")
+		if r.URL.Path != "/simple/ruff/" {
+			t.Fatalf("upstream path = %q, want %q", r.URL.Path, "/simple/ruff/")
+		}
+		return pypiHTTPResponse(r, pypiSimpleJSON, upstreamBody), nil
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/simple/ruff/", nil)
+	req.Header.Set("Accept", uvPyPIAccept)
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if upstreamAccept != pypiSimpleJSON {
+		t.Errorf("upstream Accept = %q, want %q", upstreamAccept, pypiSimpleJSON)
+	}
+	if got := w.Header().Get("Content-Type"); got != pypiSimpleJSON {
+		t.Errorf("Content-Type = %q, want %q", got, pypiSimpleJSON)
+	}
+	if got := w.Header().Get("Vary"); !strings.Contains(got, "Accept") {
+		t.Errorf("Vary = %q, want Accept", got)
+	}
+
+	var result struct {
+		Meta  map[string]string `json:"meta"`
+		Files []struct {
+			URL        string `json:"url"`
+			UploadTime string `json:"upload-time"`
+		} `json:"files"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if result.Meta["api-version"] != "1.4" {
+		t.Errorf("api-version = %q, want 1.4", result.Meta["api-version"])
+	}
+	if len(result.Files) != 1 {
+		t.Fatalf("files = %d, want 1", len(result.Files))
+	}
+	if got, want := result.Files[0].URL, "http://proxy.test/pypi/packages/packages/ab/cd/ruff-0.16.0-py3-none-any.whl"; got != want {
+		t.Errorf("file URL = %q, want %q", got, want)
+	}
+	if got := result.Files[0].UploadTime; got != "2026-08-01T12:00:00Z" {
+		t.Errorf("upload-time = %q, want %q", got, "2026-08-01T12:00:00Z")
+	}
+}
+
+func TestPyPISimpleIndexNegotiatesJSON(t *testing.T) {
+	const upstreamBody = `{"meta":{"api-version":"1.4"},"projects":[{"name":"ruff"}]}`
+
+	var upstreamAccept string
+	h, _ := setupPyPIHandler(t, func(r *http.Request) (*http.Response, error) {
+		upstreamAccept = r.Header.Get("Accept")
+		return pypiHTTPResponse(r, pypiSimpleJSON, upstreamBody), nil
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/simple/", nil)
+	req.Header.Set("Accept", uvPyPIAccept)
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if upstreamAccept != pypiSimpleJSON {
+		t.Errorf("upstream Accept = %q, want %q", upstreamAccept, pypiSimpleJSON)
+	}
+	if got := w.Header().Get("Content-Type"); got != pypiSimpleJSON {
+		t.Errorf("Content-Type = %q, want %q", got, pypiSimpleJSON)
+	}
+	if got := w.Header().Get("Vary"); !strings.Contains(got, "Accept") {
+		t.Errorf("Vary = %q, want Accept", got)
+	}
+	if got := w.Body.String(); got != upstreamBody {
+		t.Errorf("body = %q, want %q", got, upstreamBody)
+	}
+}
+
+func TestPyPISimplePackageKeepsHTMLDefault(t *testing.T) {
+	const upstreamBody = `<a href="https://files.pythonhosted.org/packages/ab/cd/ruff-0.16.0.tar.gz">ruff-0.16.0.tar.gz</a>`
+
+	var upstreamAccept string
+	h, _ := setupPyPIHandler(t, func(r *http.Request) (*http.Response, error) {
+		upstreamAccept = r.Header.Get("Accept")
+		return pypiHTTPResponse(r, "text/html", upstreamBody), nil
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/simple/ruff/", nil)
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if upstreamAccept != "text/html" {
+		t.Errorf("upstream Accept = %q, want text/html", upstreamAccept)
+	}
+	if got := w.Header().Get("Content-Type"); got != "text/html" {
+		t.Errorf("Content-Type = %q, want text/html", got)
+	}
+	if !strings.Contains(w.Body.String(), `href="http://proxy.test/pypi/packages/packages/ab/cd/ruff-0.16.0.tar.gz"`) {
+		t.Errorf("download URL was not rewritten: %s", w.Body.String())
+	}
+}
+
+func TestPyPISimplePackageCachesRepresentationsSeparately(t *testing.T) {
+	hits := make(map[string]int)
+	h, proxy := setupPyPIHandler(t, func(r *http.Request) (*http.Response, error) {
+		accept := r.Header.Get("Accept")
+		hits[accept]++
+		if accept == pypiSimpleJSON {
+			body := `{"meta":{"api-version":"1.4"},"name":"ruff","files":[]}`
+			return pypiHTTPResponse(r, pypiSimpleJSON, body), nil
+		}
+		return pypiHTTPResponse(r, accept, `<a href="/ruff.tar.gz">ruff.tar.gz</a>`), nil
+	})
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+
+	for range 2 {
+		for _, accept := range []string{pypiLegacyHTML, pypiSimpleHTML, uvPyPIAccept} {
+			req := httptest.NewRequest(http.MethodGet, "/simple/ruff/", nil)
+			req.Header.Set("Accept", accept)
+			w := httptest.NewRecorder()
+			h.Routes().ServeHTTP(w, req)
+			if w.Code != http.StatusOK {
+				t.Fatalf("Accept %q: status = %d, want 200: %s", accept, w.Code, w.Body.String())
+			}
+		}
+	}
+
+	if got := hits[pypiLegacyHTML]; got != 1 {
+		t.Errorf("HTML upstream requests = %d, want 1", got)
+	}
+	if got := hits[pypiSimpleHTML]; got != 1 {
+		t.Errorf("vendor HTML upstream requests = %d, want 1", got)
+	}
+	if got := hits[pypiSimpleJSON]; got != 1 {
+		t.Errorf("JSON upstream requests = %d, want 1", got)
+	}
+}
+
+func TestPyPISimpleJSONCooldown(t *testing.T) {
+	now := time.Now()
+	old := now.Add(-30 * 24 * time.Hour).Format(time.RFC3339)
+	recent := now.Add(-time.Hour).Format(time.RFC3339)
+
+	h, proxy := setupPyPIHandler(t, func(r *http.Request) (*http.Response, error) {
+		switch r.URL.Path {
+		case "/simple/ruff/":
+			body := `{"meta":{"api-version":"1.4"},"name":"ruff","files":[` +
+				`{"filename":"ruff-1.0.0.tar.gz","url":"https://files.pythonhosted.org/packages/ab/ruff-1.0.0.tar.gz","upload-time":"` + old + `"},` +
+				`{"filename":"ruff-2.0.0.tar.gz","url":"https://files.pythonhosted.org/packages/cd/ruff-2.0.0.tar.gz","upload-time":"` + recent + `"}` +
+				`]}`
+			return pypiHTTPResponse(r, pypiSimpleJSON, body), nil
+		case "/pypi/ruff/json":
+			body := `{"releases":{` +
+				`"1.0.0":[{"upload_time_iso_8601":"` + old + `"}],` +
+				`"2.0.0":[{"upload_time_iso_8601":"` + recent + `"}]` +
+				`}}`
+			return pypiHTTPResponse(r, "application/json", body), nil
+		default:
+			t.Fatalf("unexpected upstream path: %s", r.URL.Path)
+			return nil, nil
+		}
+	})
+	proxy.Cooldown = &cooldown.Config{Default: "7d"}
+
+	req := httptest.NewRequest(http.MethodGet, "/simple/ruff/", nil)
+	req.Header.Set("Accept", uvPyPIAccept)
+	w := httptest.NewRecorder()
+	h.Routes().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	var result struct {
+		Files []struct {
+			Filename string `json:"filename"`
+		} `json:"files"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(result.Files) != 1 || result.Files[0].Filename != "ruff-1.0.0.tar.gz" {
+		t.Errorf("files = %#v, want only ruff-1.0.0.tar.gz", result.Files)
+	}
+}
+
 func TestPyPIParseFilename(t *testing.T) {
 	h := &PyPIHandler{proxy: &Proxy{Logger: slog.Default()}}
 
@@ -168,7 +430,7 @@ func TestPyPIHandler_DownloadUpstreamURL(t *testing.T) {
 		ContentType: "application/octet-stream",
 	}
 
-	h := NewPyPIHandler(proxy, "http://localhost")
+	h := NewPyPIHandlerWithUpstreams(proxy, "http://localhost", "", "")
 	srv := httptest.NewServer(h.Routes())
 	defer srv.Close()
 
@@ -196,7 +458,7 @@ func TestPyPIHandler_DownloadCacheHit(t *testing.T) {
 	seedPackage(t, db, store, "pypi", "requests", "2.31.0",
 		"requests-2.31.0-py3-none-any.whl", "wheel binary data")
 
-	h := NewPyPIHandler(proxy, "http://localhost")
+	h := NewPyPIHandlerWithUpstreams(proxy, "http://localhost", "", "")
 	srv := httptest.NewServer(h.Routes())
 	defer srv.Close()
 
@@ -222,7 +484,7 @@ func TestPyPIHandler_DownloadCacheMiss(t *testing.T) {
 		ContentType: "application/octet-stream",
 	}
 
-	h := NewPyPIHandler(proxy, "http://localhost")
+	h := NewPyPIHandlerWithUpstreams(proxy, "http://localhost", "", "")
 	srv := httptest.NewServer(h.Routes())
 	defer srv.Close()
 
@@ -292,3 +554,60 @@ func TestPyPIDownloadCooldown(t *testing.T) {
 		})
 	}
 }
+
+// TestPyPIDownloadCooldownMetadataCache ensures that repeated downloads that
+// trigger cooldown filtering reuse the cached PyPI JSON metadata instead of
+// fetching it from upstream once per download.
+func TestPyPIDownloadCooldownMetadataCache(t *testing.T) {
+	now := time.Now()
+	releases := `{"releases": {
+		"1.0.0": [{"upload_time_iso_8601": "` + now.Add(-30*24*time.Hour).Format(time.RFC3339) + `"}],
+		"2.0.0": [{"upload_time_iso_8601": "` + now.Add(-1*time.Hour).Format(time.RFC3339) + `"}]
+	}}`
+
+	var metadataRequests atomic.Int64
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/pypi/newpkg/json" {
+			metadataRequests.Add(1)
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, releases)
+			return
+		}
+		w.Header().Set("Content-Type", "application/octet-stream")
+		_, _ = io.WriteString(w, "package data")
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, fetcher := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	proxy.CacheMetadata = true
+	proxy.MetadataTTL = time.Hour
+	proxy.Cooldown = &cooldown.Config{Default: "7d"}
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("package data")),
+		ContentType: "application/octet-stream",
+	}
+
+	h := &PyPIHandler{
+		proxy:       proxy,
+		upstreamURL: upstream.URL,
+		proxyURL:    "http://localhost",
+	}
+	srv := httptest.NewServer(h.Routes())
+	defer srv.Close()
+
+	// Two downloads of the same package: one outside the cooldown window
+	// (served) and one inside (withheld). Both go through the download path
+	// that resolves filtered versions.
+	for _, filename := range []string{"newpkg-1.0.0.tar.gz", "newpkg-2.0.0.tar.gz"} {
+		resp, err := http.Get(srv.URL + "/packages/packages/ab/cd/ef0123456789/" + filename)
+		if err != nil {
+			t.Fatalf("request failed: %v", err)
+		}
+		_ = resp.Body.Close()
+	}
+
+	if got := metadataRequests.Load(); got != 1 {
+		t.Errorf("upstream metadata JSON requests = %d, want 1 (repeated downloads should reuse the cached metadata)", got)
+	}
+}

internal/handler/rpm.go

@@ -30,6 +30,13 @@ func NewRPMHandler(proxy *Proxy, proxyURL string) *RPMHandler {
 	}
 }
 
+// NewRPMHandlerWithUpstream creates an RPM handler with a custom upstream.
+func NewRPMHandlerWithUpstream(proxy *Proxy, proxyURL, upstreamURL string) *RPMHandler {
+	h := NewRPMHandler(proxy, proxyURL)
+	h.upstreamURL = configuredUpstreamURL(upstreamURL, defaultRPMUpstream)
+	return h
+}
+
 // Routes returns the HTTP handler for RPM requests.
 // Mount this at /rpm on your router.
 func (h *RPMHandler) Routes() http.Handler {
@@ -87,7 +94,7 @@ func (h *RPMHandler) handlePackageDownload(w http.ResponseWriter, r *http.Reques
 		return
 	}
 
-	w.Header().Set("Content-Type", "application/x-rpm")
+	w.Header().Set(headerContentType, "application/x-rpm")
 	ServeArtifact(w, result)
 }
 

internal/handler/scan_test.go

@@ -0,0 +1,310 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/proxy/internal/config"
+	"github.com/git-pkgs/proxy/internal/scanner"
+	"github.com/git-pkgs/purl"
+	"github.com/git-pkgs/registries/fetch"
+)
+
+// newTestScanServer returns an httptest.Server implementing the HTTPScanner
+// notify contract, always replying with the given verdict.
+func newTestScanServer(t testing.TB, allowed bool, reason string) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var body map[string]any
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Errorf("decode scan notify body: %v", err)
+		}
+		if body["fetch_url"] == "" || body["fetch_url"] == nil {
+			t.Error("scan notify body missing fetch_url")
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"allowed": allowed, "reason": reason})
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func newTestScanGroup(t testing.TB, scanURL string, failOpen bool) *scanner.Group {
+	t.Helper()
+	g, err := scanner.NewGroup(config.ScanningConfig{
+		Enabled:    true,
+		FailOpen:   failOpen,
+		Timeout:    "15s",
+		SigningKey: "test-signing-key",
+		Scanners: []config.ScannerConfig{
+			{Name: "test-scanner", URL: scanURL, Mode: "block"},
+		},
+	}, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		t.Fatalf("scanner.NewGroup() error: %v", err)
+	}
+	return g
+}
+
+func TestGetOrFetchArtifact_ScanAllowed(t *testing.T) {
+	proxy, db, store, fetcher := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	proxy.Scanners = newTestScanGroup(t, newTestScanServer(t, true, "").URL, false)
+
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("clean content")),
+		ContentType: "application/gzip",
+	}
+
+	result, err := proxy.GetOrFetchArtifact(context.Background(), "npm", "leftpad", "1.0.0", "leftpad-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	defer func() { _ = result.Reader.Close() }()
+
+	body, _ := io.ReadAll(result.Reader)
+	if string(body) != "clean content" {
+		t.Errorf("body = %q, want %q", body, "clean content")
+	}
+
+	cached, err := db.GetCachedArtifact(
+		purl.MakePURLString("npm", "leftpad", ""), purl.MakePURLString("npm", "leftpad", "1.0.0"), "leftpad-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("GetCachedArtifact() error: %v", err)
+	}
+	if cached == nil {
+		t.Error("expected allowed artifact to be committed to the cache database")
+	}
+	if len(store.files) == 0 {
+		t.Error("expected allowed artifact bytes to remain in storage")
+	}
+}
+
+func TestGetOrFetchArtifact_ScanBlocked(t *testing.T) {
+	proxy, db, store, fetcher := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	proxy.Scanners = newTestScanGroup(t, newTestScanServer(t, false, "malware detected").URL, false)
+
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("evil content")),
+		ContentType: "application/gzip",
+	}
+
+	_, err := proxy.GetOrFetchArtifact(context.Background(), "npm", "evilpkg", "1.0.0", "evilpkg-1.0.0.tgz")
+	if err == nil {
+		t.Fatal("expected error for blocked artifact")
+	}
+	if !errors.Is(err, ErrArtifactBlocked) {
+		t.Errorf("error = %v, want wrapped ErrArtifactBlocked", err)
+	}
+	if !strings.Contains(err.Error(), "malware detected") {
+		t.Errorf("error %q does not include scanner reason", err.Error())
+	}
+
+	cached, err := db.GetCachedArtifact(
+		purl.MakePURLString("npm", "evilpkg", ""), purl.MakePURLString("npm", "evilpkg", "1.0.0"), "evilpkg-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("GetCachedArtifact() error: %v", err)
+	}
+	if cached != nil {
+		t.Error("blocked artifact must never be committed to the cache database")
+	}
+	if len(store.files) != 0 {
+		t.Errorf("blocked artifact bytes must be deleted from storage, got %d files", len(store.files))
+	}
+}
+
+func TestGetOrFetchArtifact_BlockedDeleteSurvivesClientDisconnect(t *testing.T) {
+	proxy, db, store, fetcher := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+
+	const scanDelay = 150 * time.Millisecond
+	blockingSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(scanDelay)
+		_ = json.NewEncoder(w).Encode(map[string]any{"allowed": false, "reason": "malware detected"})
+	}))
+	t.Cleanup(blockingSrv.Close)
+	proxy.Scanners = newTestScanGroup(t, blockingSrv.URL, false)
+
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("evil content")),
+		ContentType: "application/gzip",
+	}
+
+	// The client disconnects long before the (genuinely malicious) verdict
+	// comes back; cleanup of the blocked bytes must not be skipped just
+	// because the client is gone.
+	ctx, cancel := context.WithCancel(context.Background())
+	time.AfterFunc(20*time.Millisecond, cancel)
+
+	_, err := proxy.GetOrFetchArtifact(ctx, "npm", "evilpkg", "1.0.0", "evilpkg-1.0.0.tgz")
+	if err == nil {
+		t.Fatal("expected error for blocked artifact")
+	}
+	if !errors.Is(err, ErrArtifactBlocked) {
+		t.Errorf("error = %v, want wrapped ErrArtifactBlocked", err)
+	}
+
+	cached, _ := db.GetCachedArtifact(
+		purl.MakePURLString("npm", "evilpkg", ""), purl.MakePURLString("npm", "evilpkg", "1.0.0"), "evilpkg-1.0.0.tgz")
+	if cached != nil {
+		t.Error("blocked artifact must never be committed to the cache database")
+	}
+	if len(store.files) != 0 {
+		t.Errorf("blocked artifact bytes must still be deleted even though the client disconnected mid-scan, got %d orphaned files", len(store.files))
+	}
+}
+
+func TestGetOrFetchArtifact_ScanErrorFailClosed(t *testing.T) {
+	proxy, db, store, fetcher := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+
+	brokenSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	t.Cleanup(brokenSrv.Close)
+	proxy.Scanners = newTestScanGroup(t, brokenSrv.URL, false)
+
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("content")),
+		ContentType: "application/gzip",
+	}
+
+	_, err := proxy.GetOrFetchArtifact(context.Background(), "npm", "flaky", "1.0.0", "flaky-1.0.0.tgz")
+	if err == nil {
+		t.Fatal("expected error when scanner infrastructure fails")
+	}
+	if !errors.Is(err, ErrArtifactBlocked) {
+		t.Errorf("error = %v, want wrapped ErrArtifactBlocked (fail-closed default)", err)
+	}
+	if strings.Contains(err.Error(), brokenSrv.URL) {
+		t.Errorf("error %q leaks the internal scanner URL to the client-facing message", err.Error())
+	}
+	if !strings.Contains(err.Error(), "scan could not be completed") {
+		t.Errorf("error %q does not use the generic infra-failure message", err.Error())
+	}
+
+	cached, _ := db.GetCachedArtifact(
+		purl.MakePURLString("npm", "flaky", ""), purl.MakePURLString("npm", "flaky", "1.0.0"), "flaky-1.0.0.tgz")
+	if cached != nil {
+		t.Error("artifact must not be committed when scanning fails fail-closed")
+	}
+	if len(store.files) != 0 {
+		t.Errorf("artifact bytes must be deleted on scan infra failure, got %d files", len(store.files))
+	}
+}
+
+func TestGetOrFetchArtifact_ScanErrorFailOpen(t *testing.T) {
+	proxy, db, store, fetcher := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+
+	brokenSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	t.Cleanup(brokenSrv.Close)
+	proxy.Scanners = newTestScanGroup(t, brokenSrv.URL, true)
+
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("content")),
+		ContentType: "application/gzip",
+	}
+
+	result, err := proxy.GetOrFetchArtifact(context.Background(), "npm", "flaky", "1.0.0", "flaky-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("unexpected error: %v (FailOpen must treat scanner infra failure as allowed)", err)
+	}
+	defer func() { _ = result.Reader.Close() }()
+
+	cached, err := db.GetCachedArtifact(
+		purl.MakePURLString("npm", "flaky", ""), purl.MakePURLString("npm", "flaky", "1.0.0"), "flaky-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("GetCachedArtifact() error: %v", err)
+	}
+	if cached == nil {
+		t.Error("expected artifact to be committed to the cache when scanning fails fail-open")
+	}
+	if len(store.files) == 0 {
+		t.Error("expected artifact bytes to remain in storage when scanning fails fail-open")
+	}
+}
+
+func TestGetOrFetchArtifact_ScanSurvivesClientDisconnect(t *testing.T) {
+	proxy, db, store, fetcher := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+
+	const scanDelay = 150 * time.Millisecond
+	slowSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(scanDelay)
+		_ = json.NewEncoder(w).Encode(map[string]any{"allowed": true})
+	}))
+	t.Cleanup(slowSrv.Close)
+	proxy.Scanners = newTestScanGroup(t, slowSrv.URL, false)
+
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("clean content")),
+		ContentType: "application/gzip",
+	}
+
+	// Simulate a client that disconnects shortly after issuing the request:
+	// its context is cancelled well before the scanner replies, but the
+	// scan itself must run to completion rather than being torn down with
+	// it.
+	ctx, cancel := context.WithCancel(context.Background())
+	time.AfterFunc(20*time.Millisecond, cancel)
+
+	start := time.Now()
+	result, err := proxy.GetOrFetchArtifact(ctx, "npm", "leftpad", "1.0.0", "leftpad-1.0.0.tgz")
+	elapsed := time.Since(start)
+	if err != nil {
+		t.Fatalf("unexpected error: %v (a cancelled client context must not be mistaken for a scanner failure)", err)
+	}
+	defer func() { _ = result.Reader.Close() }()
+
+	if elapsed < scanDelay {
+		t.Errorf("GetOrFetchArtifact returned after %v, want it to wait out the full scan (%v) despite client cancellation", elapsed, scanDelay)
+	}
+
+	cached, err := db.GetCachedArtifact(
+		purl.MakePURLString("npm", "leftpad", ""), purl.MakePURLString("npm", "leftpad", "1.0.0"), "leftpad-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("GetCachedArtifact() error: %v", err)
+	}
+	if cached == nil {
+		t.Error("expected artifact to be committed to the cache; a client disconnect must not cause a false block")
+	}
+	if len(store.files) == 0 {
+		t.Error("expected artifact bytes to remain in storage; a client disconnect must not delete a legitimately allowed artifact")
+	}
+}
+
+func TestGetOrFetchArtifact_ScanDisabledIsNoOp(t *testing.T) {
+	proxy, db, _, fetcher := setupTestProxy(t)
+	// proxy.Scanners left nil: scanning disabled.
+
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("content")),
+		ContentType: "application/gzip",
+	}
+
+	result, err := proxy.GetOrFetchArtifact(context.Background(), "npm", "plainpkg", "1.0.0", "plainpkg-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	defer func() { _ = result.Reader.Close() }()
+
+	cached, err := db.GetCachedArtifact(
+		purl.MakePURLString("npm", "plainpkg", ""), purl.MakePURLString("npm", "plainpkg", "1.0.0"), "plainpkg-1.0.0.tgz")
+	if err != nil {
+		t.Fatalf("GetCachedArtifact() error: %v", err)
+	}
+	if cached == nil {
+		t.Error("expected artifact to be cached when scanning is disabled")
+	}
+}

internal/handler/scanfetch.go

@@ -0,0 +1,89 @@
+package handler
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"time"
+)
+
+// scanFetchURL builds a short-lived, HMAC-signed URL for the internal
+// /_internal/scan-fetch route, so an external scanner can pull the exact
+// bytes staged at path without going through cooldown or the scan hook
+// itself. This is generated the same way for every storage backend: it
+// never depends on Storage.SignedURL, which not every backend implements.
+func (p *Proxy) scanFetchURL(path string, ttl time.Duration) string {
+	exp := time.Now().Add(ttl).Unix()
+	return fmt.Sprintf("%s/_internal/scan-fetch?path=%s&exp=%d&sig=%s",
+		p.ScanFetchBaseURL, url.QueryEscape(path), exp, hmacHex(p.ScanSigningKey, path, exp))
+}
+
+func hmacHex(key []byte, path string, exp int64) string {
+	mac := hmac.New(sha256.New, key)
+	_, _ = fmt.Fprintf(mac, "%s|%d", path, exp)
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+// ServeScanFetch streams a storage object to a caller presenting a valid
+// short-lived HMAC token, so external scanners can pull a staged artifact
+// without going through cooldown or the scan hook themselves. This handler
+// never calls GetOrFetchArtifact/fetchAndCache/storeArtifact — the
+// separation from the normal request path is structural, not a
+// conditional bypass flag.
+//
+// This route exists only for scanners configured under ScanningConfig; the
+// URL is minted by scanFetchURL and passed as fetch_url in the scan notify
+// request. It is not part of the public API and should be restricted to
+// internal-network access at the ingress/network-policy layer — the HMAC
+// scoping (one object, short TTL) limits what a leaked token can do, but
+// isn't a substitute for network restriction.
+//
+// @Summary Fetch a staged artifact for scanning
+// @Description Streams the exact bytes staged in storage for a pre-cache security scan.
+// @Description Requires a short-lived HMAC-signed token minted by the proxy itself and
+// @Description delivered via the fetch_url field of the scan notify request (see the
+// @Description Artifact Scanning section of docs/configuration.md). Not part of the
+// @Description public API; restrict access to the scanner network at the ingress layer.
+// @Tags scanning
+// @Produce application/octet-stream
+// @Param path query string true "Storage path of the staged artifact"
+// @Param exp query int true "Token expiry, Unix seconds"
+// @Param sig query string true "HMAC-SHA256 signature over the string path|exp"
+// @Success 200 {file} file
+// @Failure 403 {string} string "invalid, expired, or tampered token"
+// @Failure 404 {string} string "object not found in storage, or scanning is not configured"
+// @Router /_internal/scan-fetch [get]
+func (p *Proxy) ServeScanFetch(w http.ResponseWriter, r *http.Request) {
+	if p.Scanners == nil || !p.Scanners.Enabled() || len(p.ScanSigningKey) == 0 {
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
+	path := r.URL.Query().Get("path")
+	exp, err := strconv.ParseInt(r.URL.Query().Get("exp"), 10, 64)
+	if err != nil || containsPathTraversal(path) || time.Now().Unix() > exp {
+		http.Error(w, "invalid or expired token", http.StatusForbidden)
+		return
+	}
+
+	want := hmacHex(p.ScanSigningKey, path, exp)
+	if !hmac.Equal([]byte(r.URL.Query().Get("sig")), []byte(want)) {
+		http.Error(w, "invalid signature", http.StatusForbidden)
+		return
+	}
+
+	reader, err := p.Storage.Open(r.Context(), path)
+	if err != nil {
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+	defer func() { _ = reader.Close() }()
+
+	w.Header().Set("Content-Type", "application/octet-stream")
+	_, _ = io.Copy(w, reader)
+}

internal/handler/scanfetch_test.go

@@ -0,0 +1,153 @@
+package handler
+
+import (
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/proxy/internal/config"
+	"github.com/git-pkgs/proxy/internal/scanner"
+)
+
+// newEnabledScanGroup returns a scanner.Group that reports Enabled() true,
+// so tests can exercise ServeScanFetch's normal signature-checking path
+// rather than tripping its "scanning not configured" guard.
+func newEnabledScanGroup(t testing.TB) *scanner.Group {
+	t.Helper()
+	g, err := scanner.NewGroup(config.ScanningConfig{
+		Enabled:    true,
+		Timeout:    "15s",
+		SigningKey: "test-signing-key",
+		Scanners: []config.ScannerConfig{
+			{Name: "test-scanner", URL: "http://localhost/scan", Mode: "block"},
+		},
+	}, slog.Default())
+	if err != nil {
+		t.Fatalf("scanner.NewGroup() error: %v", err)
+	}
+	return g
+}
+
+func TestServeScanFetch_ValidToken(t *testing.T) {
+	proxy, _, store, _ := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	proxy.Scanners = newEnabledScanGroup(t)
+	store.files["npm/lodash/4.17.21/lodash-4.17.21.tgz"] = []byte("artifact bytes")
+
+	target := proxy.scanFetchURL("npm/lodash/4.17.21/lodash-4.17.21.tgz", time.Minute)
+
+	req := httptest.NewRequest(http.MethodGet, target, nil)
+	w := httptest.NewRecorder()
+	proxy.ServeScanFetch(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if w.Body.String() != "artifact bytes" {
+		t.Errorf("body = %q, want %q", w.Body.String(), "artifact bytes")
+	}
+}
+
+func TestServeScanFetch_Expired(t *testing.T) {
+	proxy, _, store, _ := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	proxy.Scanners = newEnabledScanGroup(t)
+	store.files["npm/lodash/4.17.21/lodash-4.17.21.tgz"] = []byte("artifact bytes")
+
+	target := proxy.scanFetchURL("npm/lodash/4.17.21/lodash-4.17.21.tgz", -time.Minute)
+
+	req := httptest.NewRequest(http.MethodGet, target, nil)
+	w := httptest.NewRecorder()
+	proxy.ServeScanFetch(w, req)
+
+	if w.Code != http.StatusForbidden {
+		t.Errorf("status = %d, want 403", w.Code)
+	}
+}
+
+func TestServeScanFetch_TamperedSignature(t *testing.T) {
+	proxy, _, store, _ := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	proxy.Scanners = newEnabledScanGroup(t)
+	store.files["npm/lodash/4.17.21/lodash-4.17.21.tgz"] = []byte("artifact bytes")
+
+	target := proxy.scanFetchURL("npm/lodash/4.17.21/lodash-4.17.21.tgz", time.Minute)
+	tampered := strings.Replace(target, "sig=", "sig=deadbeef", 1)
+
+	req := httptest.NewRequest(http.MethodGet, tampered, nil)
+	w := httptest.NewRecorder()
+	proxy.ServeScanFetch(w, req)
+
+	if w.Code != http.StatusForbidden {
+		t.Errorf("status = %d, want 403", w.Code)
+	}
+}
+
+func TestServeScanFetch_PathTraversal(t *testing.T) {
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	proxy.Scanners = newEnabledScanGroup(t)
+
+	target := proxy.scanFetchURL("../../etc/passwd", time.Minute)
+
+	req := httptest.NewRequest(http.MethodGet, target, nil)
+	w := httptest.NewRecorder()
+	proxy.ServeScanFetch(w, req)
+
+	if w.Code != http.StatusForbidden {
+		t.Errorf("status = %d, want 403", w.Code)
+	}
+}
+
+func TestServeScanFetch_ScanningDisabled(t *testing.T) {
+	proxy, _, store, _ := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	// proxy.Scanners left nil: scanning disabled.
+	store.files["npm/lodash/4.17.21/lodash-4.17.21.tgz"] = []byte("artifact bytes")
+
+	target := proxy.scanFetchURL("npm/lodash/4.17.21/lodash-4.17.21.tgz", time.Minute)
+
+	req := httptest.NewRequest(http.MethodGet, target, nil)
+	w := httptest.NewRecorder()
+	proxy.ServeScanFetch(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("status = %d, want 404 when scanning is disabled", w.Code)
+	}
+}
+
+func TestServeScanFetch_NoSigningKey(t *testing.T) {
+	proxy, _, store, _ := setupTestProxy(t)
+	// proxy.ScanSigningKey left empty.
+	proxy.Scanners = newEnabledScanGroup(t)
+	store.files["npm/lodash/4.17.21/lodash-4.17.21.tgz"] = []byte("artifact bytes")
+
+	target := proxy.scanFetchURL("npm/lodash/4.17.21/lodash-4.17.21.tgz", time.Minute)
+
+	req := httptest.NewRequest(http.MethodGet, target, nil)
+	w := httptest.NewRecorder()
+	proxy.ServeScanFetch(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("status = %d, want 404 when no signing key is configured", w.Code)
+	}
+}
+
+func TestServeScanFetch_MissingObject(t *testing.T) {
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.ScanSigningKey = []byte("test-signing-key")
+	proxy.Scanners = newEnabledScanGroup(t)
+
+	target := proxy.scanFetchURL("npm/missing/1.0.0/missing-1.0.0.tgz", time.Minute)
+
+	req := httptest.NewRequest(http.MethodGet, target, nil)
+	w := httptest.NewRecorder()
+	proxy.ServeScanFetch(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("status = %d, want 404", w.Code)
+	}
+}

internal/handler/swift.go

@@ -0,0 +1,645 @@
+package handler
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/git-pkgs/proxy/internal/config"
+	"github.com/git-pkgs/proxy/internal/packageurl"
+)
+
+const (
+	swiftAcceptJSON     = "application/vnd.swift.registry.v1+json"
+	swiftAcceptManifest = "application/vnd.swift.registry.v1+swift"
+	swiftAcceptArchive  = "application/vnd.swift.registry.v1+zip"
+	swiftContentVersion = "1"
+	swiftMaxScopeLength = 39
+	swiftMaxNameLength  = 100
+)
+
+// SwiftHandler handles the read-only Swift Package Registry v1 protocol.
+type SwiftHandler struct {
+	proxy       *Proxy
+	upstreamURL string
+	proxyURL    string
+}
+
+// NewSwiftHandler creates a Swift Package Registry protocol handler.
+func NewSwiftHandler(proxy *Proxy, proxyURL, upstreamURL string) *SwiftHandler {
+	if strings.TrimSpace(upstreamURL) == "" {
+		upstreamURL = config.DefaultSwiftUpstream
+	}
+
+	return &SwiftHandler{
+		proxy:       proxy,
+		upstreamURL: strings.TrimSuffix(upstreamURL, "/"),
+		proxyURL:    strings.TrimSuffix(proxyURL, "/"),
+	}
+}
+
+// Routes returns the HTTP handler for Swift registry requests.
+func (h *SwiftHandler) Routes() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /identifiers", h.handleIdentifiers)
+	mux.HandleFunc("GET /{scope}/{name}/{version}/Package.swift", h.handleManifest)
+	mux.HandleFunc("GET /{scope}/{name}/{version}", h.handleRelease)
+	mux.HandleFunc("PUT /{scope}/{name}/{version}", h.handlePublishingUnsupported)
+	mux.HandleFunc("GET /{scope}/{name}", h.handlePackageReleases)
+	return mux
+}
+
+func (h *SwiftHandler) handlePackageReleases(w http.ResponseWriter, r *http.Request) {
+	scope := r.PathValue("scope")
+	name := strings.TrimSuffix(r.PathValue("name"), ".json")
+	if !validSwiftScope(scope) || !validSwiftPackageName(name) {
+		writeSwiftProblem(w, http.StatusBadRequest, "invalid package identifier")
+		return
+	}
+	scope, name = canonicalSwiftPackage(scope, name)
+
+	upstreamURL := h.buildUpstreamURL(scope, name, "", "", r.URL.RawQuery)
+	body, contentType, responseHeaders, err := h.fetchMetadataWithHeaders(
+		r.Context(), upstreamURL, requestAccept(r, swiftAcceptJSON),
+	)
+	if err != nil {
+		h.writeMetadataError(w, err)
+		return
+	}
+
+	rewritten, err := h.rewriteReleaseURLs(scope, name, body)
+	if err != nil {
+		h.proxy.Logger.Warn("failed to rewrite Swift release URLs", "error", err)
+		rewritten = body
+	}
+	for _, link := range responseHeaders.Values("Link") {
+		w.Header().Add("Link", h.rewriteLinkHeader(link, upstreamURL))
+	}
+	writeSwiftMetadata(w, r, rewritten, contentType)
+}
+
+func (h *SwiftHandler) handleRelease(w http.ResponseWriter, r *http.Request) {
+	scope := r.PathValue("scope")
+	name := r.PathValue("name")
+	version := r.PathValue("version")
+	if strings.HasSuffix(version, ".zip") {
+		h.handleSourceArchive(w, r, scope, name, strings.TrimSuffix(version, ".zip"))
+		return
+	}
+
+	version = strings.TrimSuffix(version, ".json")
+	if !validSwiftPackageReference(scope, name, version) {
+		writeSwiftProblem(w, http.StatusBadRequest, "invalid package release")
+		return
+	}
+	scope, name = canonicalSwiftPackage(scope, name)
+
+	upstreamURL := h.buildUpstreamURL(scope, name, version, "", r.URL.RawQuery)
+	body, contentType, err := h.proxy.FetchOrCacheMetadata(
+		r.Context(), "swift", swiftReleaseCacheKey(scope, name, version), upstreamURL, requestAccept(r, swiftAcceptJSON),
+	)
+	if err != nil {
+		h.writeMetadataError(w, err)
+		return
+	}
+	writeSwiftMetadata(w, r, body, contentType)
+}
+
+func (h *SwiftHandler) handleManifest(w http.ResponseWriter, r *http.Request) {
+	scope := r.PathValue("scope")
+	name := r.PathValue("name")
+	version := r.PathValue("version")
+	if !validSwiftPackageReference(scope, name, version) {
+		writeSwiftProblem(w, http.StatusBadRequest, "invalid package release")
+		return
+	}
+	scope, name = canonicalSwiftPackage(scope, name)
+
+	upstreamURL := h.buildUpstreamURL(scope, name, version, "Package.swift", r.URL.RawQuery)
+	h.proxySwiftResource(w, r, upstreamURL, swiftAcceptManifest)
+}
+
+func (h *SwiftHandler) handleIdentifiers(w http.ResponseWriter, r *http.Request) {
+	if r.URL.Query().Get("url") == "" {
+		writeSwiftProblem(w, http.StatusBadRequest, "url query parameter is required")
+		return
+	}
+
+	upstreamURL := h.upstreamURL + "/identifiers?" + r.URL.RawQuery
+	cacheKey := swiftMetadataCacheKey("identifiers", r.URL.RawQuery)
+	body, contentType, err := h.proxy.FetchOrCacheMetadata(
+		r.Context(), "swift", cacheKey, upstreamURL, requestAccept(r, swiftAcceptJSON),
+	)
+	if err != nil {
+		h.writeMetadataError(w, err)
+		return
+	}
+	writeSwiftMetadata(w, r, body, contentType)
+}
+
+func (h *SwiftHandler) handlePublishingUnsupported(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Allow", "GET, HEAD")
+	writeSwiftProblem(w, http.StatusMethodNotAllowed, "publishing isn't supported")
+}
+
+func (h *SwiftHandler) handleSourceArchive(w http.ResponseWriter, r *http.Request, scope, name, version string) {
+	if !validSwiftPackageReference(scope, name, version) {
+		writeSwiftProblem(w, http.StatusBadRequest, "invalid package release")
+		return
+	}
+	scope, name = canonicalSwiftPackage(scope, name)
+
+	packageName := scope + "/" + name
+	filename := fmt.Sprintf("%s-%s.zip", name, version)
+	upstreamURL := h.buildUpstreamURL(scope, name, version+".zip", "", r.URL.RawQuery)
+	packagePURL, versionPURL := packageurl.MakeCacheStrings("swift", packageName, version)
+	if packagePURL == "" || versionPURL == "" {
+		h.writeArtifactError(w, fmt.Errorf("%w: swift %q", errUnsupportedPackageIdentity, packageName))
+		return
+	}
+	archiveInfo, infoErr := h.fetchArchiveInfo(r.Context(), scope, name, version)
+	if infoErr != nil {
+		h.writeArtifactError(w, fmt.Errorf("fetching release metadata: %w", infoErr))
+		return
+	}
+
+	if r.Method == http.MethodHead {
+		h.handleSourceArchiveHead(w, r, name, version, filename, packagePURL, versionPURL, upstreamURL, archiveInfo)
+		return
+	}
+
+	headers := make(http.Header)
+	headers.Set("Accept", requestAccept(r, swiftAcceptArchive))
+	result, err := h.proxy.getOrFetchArtifactFromURLWithCachePURLs(
+		r.Context(), "swift", packageName, version, filename, packagePURL, versionPURL,
+		upstreamURL, headers, archiveInfo.checksum,
+	)
+	if err != nil {
+		h.writeArtifactError(w, err)
+		return
+	}
+
+	result.Artifact.MediaType = "application/zip"
+	setSwiftArchiveHeaders(w.Header(), name, version, result.Artifact.Digest.Encoded(), archiveInfo)
+	serveArtifact(w, r.Method, result)
+}
+
+func (h *SwiftHandler) handleSourceArchiveHead(
+	w http.ResponseWriter,
+	r *http.Request,
+	name, version, filename, packagePURL, versionPURL, upstreamURL string,
+	archiveInfo swiftArchiveInfo,
+) {
+	result, err := h.proxy.getCachedArtifactWithUpstreamHash(
+		r.Context(), packagePURL, versionPURL, filename, archiveInfo.checksum,
+	)
+	if err != nil {
+		h.writeArtifactError(w, err)
+		return
+	}
+	if result != nil {
+		result.Artifact.MediaType = "application/zip"
+		setSwiftArchiveHeaders(w.Header(), name, version, result.Artifact.Digest.Encoded(), archiveInfo)
+		serveArtifact(w, r.Method, result)
+		return
+	}
+
+	size, err := h.probeSourceArchive(r.Context(), upstreamURL, requestAccept(r, swiftAcceptArchive))
+	if err != nil {
+		h.writeArtifactError(w, err)
+		return
+	}
+	setSwiftArchiveHeaders(w.Header(), name, version, "", archiveInfo)
+	w.Header().Set(headerContentType, "application/zip")
+	if size >= 0 {
+		w.Header().Set(headerContentLength, strconv.FormatInt(size, 10))
+	}
+	w.WriteHeader(http.StatusOK)
+}
+
+func (h *SwiftHandler) probeSourceArchive(ctx context.Context, upstreamURL, accept string) (int64, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, upstreamURL, nil)
+	if err != nil {
+		return 0, fmt.Errorf("creating upstream archive request: %w", err)
+	}
+	req.Header.Set("Accept", accept)
+	req.Header.Set("Range", "bytes=0-0")
+	h.proxy.applyUpstreamAuth(req)
+
+	resp, err := h.proxy.HTTPClient.Do(req)
+	if err != nil {
+		return 0, fmt.Errorf("requesting upstream archive: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode == http.StatusNotFound {
+		return 0, ErrUpstreamNotFound
+	}
+	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusPartialContent {
+		return 0, fmt.Errorf("upstream archive returned %d", resp.StatusCode)
+	}
+
+	if resp.StatusCode == http.StatusPartialContent {
+		_, total, found := strings.Cut(resp.Header.Get("Content-Range"), "/")
+		if !found || total == "*" {
+			return -1, nil
+		}
+		if parsed, parseErr := strconv.ParseInt(total, 10, 64); parseErr == nil {
+			return parsed, nil
+		}
+		return -1, nil
+	}
+
+	size := int64(-1)
+	if contentLength := resp.Header.Get(headerContentLength); contentLength != "" {
+		if parsed, parseErr := strconv.ParseInt(contentLength, 10, 64); parseErr == nil {
+			size = parsed
+		}
+	}
+	return size, nil
+}
+
+func (h *SwiftHandler) fetchMetadataWithHeaders(
+	ctx context.Context,
+	upstreamURL, accept string,
+) ([]byte, string, http.Header, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, upstreamURL, nil)
+	if err != nil {
+		return nil, "", nil, fmt.Errorf("creating upstream metadata request: %w", err)
+	}
+	req.Header.Set("Accept", accept)
+	h.proxy.applyUpstreamAuth(req)
+
+	resp, err := h.proxy.HTTPClient.Do(req)
+	if err != nil {
+		return nil, "", nil, fmt.Errorf("requesting upstream metadata: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode == http.StatusNotFound {
+		return nil, "", nil, ErrUpstreamNotFound
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, "", nil, fmt.Errorf("upstream metadata returned %d", resp.StatusCode)
+	}
+
+	body, err := h.proxy.ReadMetadata(resp.Body)
+	if err != nil {
+		return nil, "", nil, fmt.Errorf("reading upstream metadata: %w", err)
+	}
+	contentType := resp.Header.Get(headerContentType)
+	if contentType == "" {
+		contentType = contentTypeJSON
+	}
+	return body, contentType, resp.Header.Clone(), nil
+}
+
+type swiftReleaseMetadata struct {
+	Resources []struct {
+		Name     string `json:"name"`
+		Type     string `json:"type"`
+		Checksum string `json:"checksum"`
+		Signing  *struct {
+			Signature string `json:"signatureBase64Encoded"`
+			Format    string `json:"signatureFormat"`
+		} `json:"signing"`
+	} `json:"resources"`
+}
+
+type swiftArchiveInfo struct {
+	checksum        string
+	signature       string
+	signatureFormat string
+}
+
+func (h *SwiftHandler) fetchArchiveInfo(ctx context.Context, scope, name, version string) (swiftArchiveInfo, error) {
+	upstreamURL := h.buildUpstreamURL(scope, name, version, "", "")
+	body, _, err := h.proxy.FetchOrCacheMetadata(
+		ctx, "swift", swiftReleaseCacheKey(scope, name, version), upstreamURL, swiftAcceptJSON,
+	)
+	if err != nil {
+		return swiftArchiveInfo{}, err
+	}
+
+	var metadata swiftReleaseMetadata
+	if err := json.Unmarshal(body, &metadata); err != nil {
+		return swiftArchiveInfo{}, fmt.Errorf("parsing release metadata: %w", err)
+	}
+	for _, resource := range metadata.Resources {
+		if resource.Name != "source-archive" || resource.Type != "application/zip" {
+			continue
+		}
+		checksum, err := normalizeSwiftChecksum(resource.Checksum)
+		if err != nil {
+			return swiftArchiveInfo{}, err
+		}
+		info := swiftArchiveInfo{checksum: checksum}
+		if resource.Signing != nil {
+			if resource.Signing.Signature == "" || resource.Signing.Format == "" {
+				return swiftArchiveInfo{}, errors.New("source archive signing metadata is incomplete")
+			}
+			info.signature = resource.Signing.Signature
+			info.signatureFormat = resource.Signing.Format
+		}
+		return info, nil
+	}
+
+	return swiftArchiveInfo{}, errors.New("source archive is missing from release metadata")
+}
+
+func normalizeSwiftChecksum(checksum string) (string, error) {
+	digest, err := hex.DecodeString(checksum)
+	if err != nil || len(digest) != sha256.Size {
+		return "", errors.New("source archive checksum is not a SHA-256 digest")
+	}
+	return hex.EncodeToString(digest), nil
+}
+
+func setSwiftArchiveHeaders(header http.Header, name, version, contentHash string, info swiftArchiveInfo) {
+	header.Set("Cache-Control", "public, immutable")
+	header.Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s-%s.zip"`, name, version))
+	header.Set("Content-Version", swiftContentVersion)
+
+	checksum := info.checksum
+	if checksum == "" {
+		checksum = contentHash
+	}
+	if digest := swiftDigestHeader(checksum); digest != "" {
+		header.Set("Digest", digest)
+	}
+	if info.signature != "" && info.signatureFormat != "" {
+		header.Set("X-Swift-Package-Signature", info.signature)
+		header.Set("X-Swift-Package-Signature-Format", info.signatureFormat)
+	}
+}
+
+func swiftDigestHeader(checksum string) string {
+	digest, err := hex.DecodeString(checksum)
+	if err != nil || len(digest) != sha256.Size {
+		return ""
+	}
+	return "sha-256=" + base64.StdEncoding.EncodeToString(digest)
+}
+
+func (h *SwiftHandler) proxySwiftResource(w http.ResponseWriter, r *http.Request, upstreamURL, defaultAccept string) {
+	req, err := http.NewRequestWithContext(r.Context(), r.Method, upstreamURL, nil)
+	if err != nil {
+		writeSwiftProblem(w, http.StatusInternalServerError, "failed to create upstream request")
+		return
+	}
+	req.Header.Set("Accept", requestAccept(r, defaultAccept))
+	for _, name := range []string{"If-Modified-Since", "If-None-Match"} {
+		if value := r.Header.Get(name); value != "" {
+			req.Header.Set(name, value)
+		}
+	}
+	h.proxy.applyUpstreamAuth(req)
+
+	resp, err := h.proxy.HTTPClient.Do(req)
+	if err != nil {
+		writeSwiftProblem(w, http.StatusBadGateway, "upstream request failed")
+		return
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	copySwiftResponseHeaders(w.Header(), resp.Header)
+	if location := resp.Header.Get("Location"); location != "" {
+		w.Header().Set("Location", h.rewriteRegistryURL(location, upstreamURL))
+	}
+	for _, link := range resp.Header.Values("Link") {
+		w.Header().Add("Link", h.rewriteLinkHeader(link, upstreamURL))
+	}
+	if w.Header().Get("Content-Version") == "" {
+		w.Header().Set("Content-Version", swiftContentVersion)
+	}
+
+	w.WriteHeader(resp.StatusCode)
+	if r.Method != http.MethodHead {
+		_, _ = io.Copy(w, resp.Body)
+	}
+}
+
+func copySwiftResponseHeaders(dst, src http.Header) {
+	for _, name := range []string{
+		"Cache-Control", "Content-Disposition", "Content-Language", headerContentLength,
+		headerContentType, "Content-Version", "Digest", headerETag, headerLastModified,
+		"Retry-After", "Vary", "Warning", "X-Swift-Package-Signature",
+		"X-Swift-Package-Signature-Format",
+	} {
+		for _, value := range src.Values(name) {
+			dst.Add(name, value)
+		}
+	}
+}
+
+func (h *SwiftHandler) rewriteLinkHeader(value, upstreamRequestURL string) string {
+	var result strings.Builder
+	for len(value) > 0 {
+		start := strings.IndexByte(value, '<')
+		if start < 0 {
+			result.WriteString(value)
+			break
+		}
+		endOffset := strings.IndexByte(value[start+1:], '>')
+		if endOffset < 0 {
+			result.WriteString(value)
+			break
+		}
+		end := start + 1 + endOffset
+		result.WriteString(value[:start+1])
+		result.WriteString(h.rewriteRegistryURL(value[start+1:end], upstreamRequestURL))
+		result.WriteByte('>')
+		value = value[end+1:]
+	}
+	return result.String()
+}
+
+func (h *SwiftHandler) rewriteRegistryURL(rawURL, upstreamRequestURL string) string {
+	base, err := url.Parse(h.upstreamURL)
+	if err != nil {
+		return rawURL
+	}
+	requestURL, err := url.Parse(upstreamRequestURL)
+	if err != nil {
+		return rawURL
+	}
+	reference, err := url.Parse(rawURL)
+	if err != nil {
+		return rawURL
+	}
+	absolute := requestURL.ResolveReference(reference)
+	if !strings.EqualFold(absolute.Scheme, base.Scheme) || !strings.EqualFold(absolute.Host, base.Host) {
+		return rawURL
+	}
+
+	basePath := strings.TrimSuffix(base.EscapedPath(), "/")
+	absolutePath := absolute.EscapedPath()
+	if absolutePath != basePath && !strings.HasPrefix(absolutePath, basePath+"/") {
+		return rawURL
+	}
+	suffix := strings.TrimPrefix(absolutePath, basePath)
+	rewritten := h.proxyURL + "/swift" + suffix
+	if absolute.RawQuery != "" {
+		rewritten += "?" + absolute.RawQuery
+	}
+	if absolute.Fragment != "" {
+		rewritten += "#" + absolute.Fragment
+	}
+	return rewritten
+}
+
+func (h *SwiftHandler) rewriteReleaseURLs(scope, name string, body []byte) ([]byte, error) {
+	var metadata map[string]any
+	if err := json.Unmarshal(body, &metadata); err != nil {
+		return nil, err
+	}
+	releases, ok := metadata["releases"].(map[string]any)
+	if !ok {
+		return body, nil
+	}
+
+	for version, value := range releases {
+		release, ok := value.(map[string]any)
+		if !ok {
+			continue
+		}
+		if _, hasURL := release["url"]; !hasURL {
+			continue
+		}
+		release["url"] = fmt.Sprintf(
+			"%s/swift/%s/%s/%s",
+			h.proxyURL,
+			url.PathEscape(scope),
+			url.PathEscape(name),
+			url.PathEscape(version),
+		)
+	}
+	return json.Marshal(metadata)
+}
+
+func (h *SwiftHandler) buildUpstreamURL(scope, name, version, resource, rawQuery string) string {
+	parts := []string{h.upstreamURL, url.PathEscape(scope), url.PathEscape(name)}
+	if version != "" {
+		parts = append(parts, url.PathEscape(version))
+	}
+	if resource != "" {
+		parts = append(parts, resource)
+	}
+	result := strings.Join(parts, "/")
+	if rawQuery != "" {
+		result += "?" + rawQuery
+	}
+	return result
+}
+
+func swiftMetadataCacheKey(parts ...string) string {
+	joined := strings.Join(parts, "\x00")
+	digest := sha256.Sum256([]byte(joined))
+	return hex.EncodeToString(digest[:])
+}
+
+func swiftReleaseCacheKey(scope, name, version string) string {
+	return swiftMetadataCacheKey("release", scope, name, version)
+}
+
+func requestAccept(r *http.Request, fallback string) string {
+	if accept := r.Header.Get("Accept"); accept != "" {
+		return accept
+	}
+	return fallback
+}
+
+func writeSwiftMetadata(w http.ResponseWriter, r *http.Request, body []byte, contentType string) {
+	if contentType == "" {
+		contentType = "application/json"
+	}
+	digest := sha256.Sum256(body)
+	etag := fmt.Sprintf(`"%x"`, digest)
+	w.Header().Set(headerContentType, contentType)
+	w.Header().Set("Content-Version", swiftContentVersion)
+	w.Header().Set(headerETag, etag)
+	if ifNoneMatchHits(r.Header.Get("If-None-Match"), etag) {
+		w.WriteHeader(http.StatusNotModified)
+		return
+	}
+	w.Header().Set(headerContentLength, strconv.Itoa(len(body)))
+	w.WriteHeader(http.StatusOK)
+	if r.Method != http.MethodHead {
+		_, _ = w.Write(body)
+	}
+}
+
+func (h *SwiftHandler) writeMetadataError(w http.ResponseWriter, err error) {
+	if errors.Is(err, ErrUpstreamNotFound) {
+		writeSwiftProblem(w, http.StatusNotFound, "not found")
+		return
+	}
+	h.proxy.Logger.Error("Swift metadata request failed", "error", err)
+	writeSwiftProblem(w, http.StatusBadGateway, "upstream request failed")
+}
+
+func (h *SwiftHandler) writeArtifactError(w http.ResponseWriter, err error) {
+	if errors.Is(err, ErrUpstreamNotFound) {
+		writeSwiftProblem(w, http.StatusNotFound, "release not found")
+		return
+	}
+	h.proxy.Logger.Error("Swift archive request failed", "error", err)
+	writeSwiftProblem(w, http.StatusBadGateway, "failed to fetch package")
+}
+
+func writeSwiftProblem(w http.ResponseWriter, status int, detail string) {
+	w.Header().Set(headerContentType, "application/problem+json")
+	w.Header().Set("Content-Version", swiftContentVersion)
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(map[string]string{"detail": detail})
+}
+
+func validSwiftPackageReference(scope, name, version string) bool {
+	return validSwiftScope(scope) && validSwiftPackageName(name) && version != "" && version != "." && version != ".." && !strings.ContainsAny(version, "/\\")
+}
+
+func canonicalSwiftPackage(scope, name string) (string, string) {
+	return strings.ToLower(scope), strings.ToLower(name)
+}
+
+func validSwiftScope(scope string) bool {
+	return validSwiftIdentifier(scope, swiftMaxScopeLength, "-")
+}
+
+func validSwiftPackageName(name string) bool {
+	return validSwiftIdentifier(name, swiftMaxNameLength, "-_")
+}
+
+func validSwiftIdentifier(value string, maxLength int, separators string) bool {
+	if value == "" || len(value) > maxLength {
+		return false
+	}
+	previousSeparator := false
+	for i := 0; i < len(value); i++ {
+		character := value[i]
+		separator := strings.ContainsRune(separators, rune(character))
+		if separator {
+			if i == 0 || i == len(value)-1 || previousSeparator {
+				return false
+			}
+			previousSeparator = true
+			continue
+		}
+		if (character < 'a' || character > 'z') &&
+			(character < 'A' || character > 'Z') &&
+			(character < '0' || character > '9') {
+			return false
+		}
+		previousSeparator = false
+	}
+	return true
+}

internal/handler/swift_test.go

@@ -0,0 +1,534 @@
+package handler
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/git-pkgs/proxy/internal/packageurl"
+	"github.com/git-pkgs/registries/fetch"
+)
+
+func TestSwiftPackageReleasesRewritesRegistryURLs(t *testing.T) {
+	var gotAccept string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/registry/apple/swift-argument-parser" {
+			t.Errorf("upstream path = %q", r.URL.Path)
+		}
+		gotAccept = r.Header.Get("Accept")
+		w.Header().Set("Content-Type", "application/json; charset=utf-8")
+		w.Header().Set("Content-Version", "1")
+		w.Header().Add("Link", `</registry/apple/swift-argument-parser?page=2>; rel="next"`)
+		_, _ = io.WriteString(w, `{"releases":{"1.2.0":{"url":"/registry/apple/swift-argument-parser/1.2.0"},"1.1.0":{}}}`)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL+"/registry").Routes()
+	req := httptest.NewRequest(http.MethodGet, "/APPLE/SWIFT-ARGUMENT-PARSER", nil)
+	req.Header.Set("Accept", swiftAcceptJSON)
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if gotAccept != swiftAcceptJSON {
+		t.Errorf("upstream Accept = %q, want %q", gotAccept, swiftAcceptJSON)
+	}
+	if got := w.Header().Get("Content-Version"); got != "1" {
+		t.Errorf("Content-Version = %q, want 1", got)
+	}
+	if got := w.Header().Get("Link"); got != `<https://proxy.example/swift/apple/swift-argument-parser?page=2>; rel="next"` {
+		t.Errorf("Link = %q", got)
+	}
+
+	var body struct {
+		Releases map[string]struct {
+			URL string `json:"url"`
+		} `json:"releases"`
+	}
+	if err := json.NewDecoder(w.Body).Decode(&body); err != nil {
+		t.Fatalf("decoding response: %v", err)
+	}
+	if got := body.Releases["1.2.0"].URL; got != "https://proxy.example/swift/apple/swift-argument-parser/1.2.0" {
+		t.Errorf("release URL = %q", got)
+	}
+	if got := body.Releases["1.1.0"].URL; got != "" {
+		t.Errorf("release without upstream URL gained URL %q", got)
+	}
+}
+
+func TestSwiftReleaseMetadataSupportsJSONExtensionAndHead(t *testing.T) {
+	var requestMethods []string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestMethods = append(requestMethods, r.Method)
+		if r.URL.Path != "/registry/apple/example/1.2.3" {
+			t.Errorf("upstream path = %q", r.URL.Path)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"id":"apple.example","version":"1.2.3","resources":[]}`)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL+"/registry").Routes()
+
+	for _, method := range []string{http.MethodGet, http.MethodHead} {
+		req := httptest.NewRequest(method, "/APPLE/EXAMPLE/1.2.3.json", nil)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s status = %d, want 200", method, w.Code)
+		}
+		if method == http.MethodHead && w.Body.Len() != 0 {
+			t.Errorf("HEAD response body length = %d, want 0", w.Body.Len())
+		}
+	}
+	if len(requestMethods) != 2 || requestMethods[0] != http.MethodGet || requestMethods[1] != http.MethodGet {
+		t.Errorf("upstream methods = %v, want metadata GETs", requestMethods)
+	}
+}
+
+func TestSwiftManifestProxiesQueryAndRewritesLinks(t *testing.T) {
+	var upstream *httptest.Server
+	var gotAccept string
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			t.Errorf("upstream method = %s, want GET", r.Method)
+		}
+		if r.URL.Path != "/registry/apple/example/1.2.3/Package.swift" {
+			t.Errorf("upstream path = %q", r.URL.Path)
+		}
+		if got := r.URL.Query().Get("swift-version"); got != "5.9" {
+			t.Errorf("swift-version = %q, want 5.9", got)
+		}
+		gotAccept = r.Header.Get("Accept")
+		w.Header().Set("Content-Type", "text/x-swift")
+		w.Header().Add("Link", fmt.Sprintf(`<%s/registry/apple/example/1.2.3/Package.swift?swift-version=5.8>; rel="alternate"; filename="Package@swift-5.8.swift"`, upstream.URL))
+		w.Header().Add("Link", `<https://github.com/apple/example>; rel="canonical"`)
+		_, _ = io.WriteString(w, "// swift-tools-version: 5.9\n")
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL+"/registry").Routes()
+	req := httptest.NewRequest(http.MethodGet, "/APPLE/EXAMPLE/1.2.3/Package.swift?swift-version=5.9", nil)
+	req.Header.Set("Accept", swiftAcceptManifest)
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	if gotAccept != swiftAcceptManifest {
+		t.Errorf("upstream Accept = %q, want %q", gotAccept, swiftAcceptManifest)
+	}
+	links := strings.Join(w.Header().Values("Link"), ",")
+	if !strings.Contains(links, "https://proxy.example/swift/apple/example/1.2.3/Package.swift?swift-version=5.8") {
+		t.Errorf("internal manifest Link was not rewritten: %q", links)
+	}
+	if !strings.Contains(links, "https://github.com/apple/example") {
+		t.Errorf("external canonical Link was changed: %q", links)
+	}
+	if got := w.Header().Get("Content-Version"); got != "1" {
+		t.Errorf("Content-Version = %q, want 1", got)
+	}
+}
+
+func TestSwiftSourceArchiveCachesAndPreservesSecurityMetadata(t *testing.T) {
+	archive := []byte("swift source archive")
+	checksumBytes := sha256.Sum256(archive)
+	checksum := hex.EncodeToString(checksumBytes[:])
+	signature := base64.StdEncoding.EncodeToString([]byte("signature"))
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/registry/apple/example/1.2.3" {
+			t.Errorf("metadata path = %q", r.URL.Path)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprintf(w, `{"id":"apple.example","version":"1.2.3","resources":[{"name":"source-archive","type":"application/zip","checksum":%q,"signing":{"signatureBase64Encoded":%q,"signatureFormat":"cms-1.0.0"}}]}`, checksum, signature)
+	}))
+	defer upstream.Close()
+
+	proxy, db, _, fetcher := setupTestProxy(t)
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader(string(archive))),
+		Size:        int64(len(archive)),
+		ContentType: "application/zip",
+	}
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL+"/registry").Routes()
+
+	requestArchive := func(method string) *httptest.ResponseRecorder {
+		req := httptest.NewRequest(method, "/apple/example/1.2.3.zip", nil)
+		req.Header.Set("Accept", swiftAcceptArchive)
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, req)
+		return w
+	}
+
+	w := requestArchive(http.MethodGet)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if got := w.Body.Bytes(); string(got) != string(archive) {
+		t.Errorf("archive body = %q", got)
+	}
+	if !fetcher.fetchCalled {
+		t.Fatal("archive fetcher was not called")
+	}
+	if got := fetcher.fetchedURL; got != upstream.URL+"/registry/apple/example/1.2.3.zip" {
+		t.Errorf("fetched URL = %q", got)
+	}
+	if got := fetcher.fetchedHeader.Get("Accept"); got != swiftAcceptArchive {
+		t.Errorf("archive Accept = %q, want %q", got, swiftAcceptArchive)
+	}
+	if got := w.Header().Get("Digest"); got != "sha-256="+base64.StdEncoding.EncodeToString(checksumBytes[:]) {
+		t.Errorf("Digest = %q", got)
+	}
+	if got := w.Header().Get("X-Swift-Package-Signature"); got != signature {
+		t.Errorf("signature = %q", got)
+	}
+	if got := w.Header().Get("X-Swift-Package-Signature-Format"); got != "cms-1.0.0" {
+		t.Errorf("signature format = %q", got)
+	}
+	if got := w.Header().Get("Content-Disposition"); got != `attachment; filename="example-1.2.3.zip"` {
+		t.Errorf("Content-Disposition = %q", got)
+	}
+
+	packagePURL, versionPURL := packageurl.MakeCacheStrings("swift", "apple/example", "1.2.3")
+	if strings.HasPrefix(packagePURL, "pkg:swift/") {
+		t.Fatalf("registry identity produced source PURL %q", packagePURL)
+	}
+	versionRecord, err := db.GetVersionByPURL(versionPURL)
+	if err != nil {
+		t.Fatalf("cached Swift version %q not found: %v", versionPURL, err)
+	}
+	if versionRecord == nil {
+		t.Fatalf("cached Swift version %q not found", versionPURL)
+	}
+	if versionRecord.PackagePURL != packagePURL {
+		t.Errorf("cached package PURL = %q, want %q", versionRecord.PackagePURL, packagePURL)
+	}
+
+	fetcher.fetchCalled = false
+	w = requestArchive(http.MethodHead)
+	if w.Code != http.StatusOK {
+		t.Fatalf("HEAD status = %d, want 200", w.Code)
+	}
+	if w.Body.Len() != 0 {
+		t.Errorf("HEAD body length = %d, want 0", w.Body.Len())
+	}
+	if got := w.Header().Get("Content-Length"); got != fmt.Sprint(len(archive)) {
+		t.Errorf("HEAD Content-Length = %q", got)
+	}
+
+	w = requestArchive(http.MethodGet)
+	if w.Code != http.StatusOK || w.Body.String() != string(archive) {
+		t.Fatalf("cached response = %d %q", w.Code, w.Body.Bytes())
+	}
+	if fetcher.fetchCalled {
+		t.Error("cached archive contacted artifact upstream")
+	}
+}
+
+func TestSwiftSourceArchiveRejectsChecksumMismatch(t *testing.T) {
+	archive := []byte("unexpected archive")
+	expectedChecksum := sha256.Sum256([]byte("expected archive"))
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprintf(w, `{"id":"apple.example","version":"1.2.3","resources":[{"name":"source-archive","type":"application/zip","checksum":%q}]}`, hex.EncodeToString(expectedChecksum[:]))
+	}))
+	defer upstream.Close()
+
+	proxy, db, store, fetcher := setupTestProxy(t)
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader(string(archive))),
+		Size:        int64(len(archive)),
+		ContentType: "application/zip",
+	}
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL).Routes()
+
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/apple/example/1.2.3.zip", nil))
+
+	if w.Code != http.StatusBadGateway {
+		t.Fatalf("status = %d, want 502; body: %s", w.Code, w.Body.String())
+	}
+	if len(store.files) != 0 {
+		t.Errorf("mismatched archive remained in storage: %v", store.files)
+	}
+	packagePURL, versionPURL := packageurl.MakeCacheStrings("swift", "apple/example", "1.2.3")
+	cached, err := db.GetCachedArtifact(packagePURL, versionPURL, "example-1.2.3.zip")
+	if err != nil {
+		t.Fatalf("checking cache: %v", err)
+	}
+	if cached != nil {
+		t.Error("mismatched archive gained a cache record")
+	}
+}
+
+func TestSwiftSourceArchiveCanonicalizesPackageIdentity(t *testing.T) {
+	archive := []byte("swift source archive")
+	checksumBytes := sha256.Sum256(archive)
+	checksum := hex.EncodeToString(checksumBytes[:])
+	var metadataPaths []string
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		metadataPaths = append(metadataPaths, r.URL.Path)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprintf(w, `{"id":"apple.example","version":"1.2.3","resources":[{"name":"source-archive","type":"application/zip","checksum":%q}]}`, checksum)
+	}))
+	defer upstream.Close()
+
+	proxy, db, store, fetcher := setupTestProxy(t)
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL).Routes()
+	requestArchive := func(path string) {
+		fetcher.artifact = &fetch.Artifact{
+			Body:        io.NopCloser(strings.NewReader(string(archive))),
+			Size:        int64(len(archive)),
+			ContentType: "application/zip",
+		}
+		w := httptest.NewRecorder()
+		handler.ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+		if w.Code != http.StatusOK {
+			t.Fatalf("GET %s status = %d, want 200; body: %s", path, w.Code, w.Body.String())
+		}
+	}
+
+	requestArchive("/apple/example/1.2.3.zip")
+	requestArchive("/APPLE/EXAMPLE/1.2.3.zip")
+
+	if len(store.files) != 1 {
+		t.Errorf("cached files = %d, want 1", len(store.files))
+	}
+	for _, path := range metadataPaths {
+		if path != "/apple/example/1.2.3" {
+			t.Errorf("metadata path = %q, want canonical lowercase path", path)
+		}
+	}
+
+	canonicalPURL, _ := packageurl.MakeCacheStrings("swift", "apple/example", "1.2.3")
+	canonical, err := db.GetPackageByPURL(canonicalPURL)
+	if err != nil {
+		t.Fatalf("getting canonical package: %v", err)
+	}
+	if canonical == nil {
+		t.Fatalf("canonical package %q not found", canonicalPURL)
+	}
+
+	nonCanonicalPURL, _ := packageurl.MakeCacheStrings("swift", "APPLE/EXAMPLE", "1.2.3")
+	if nonCanonicalPURL != canonicalPURL {
+		t.Errorf("uppercase cache PURL = %q, want %q", nonCanonicalPURL, canonicalPURL)
+	}
+}
+
+func TestSwiftSourceArchiveHeadDiscardsCachedChecksumMismatch(t *testing.T) {
+	archive := []byte("cached archive")
+	upstreamChecksum := sha256.Sum256([]byte("upstream archive"))
+
+	var probed bool
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.HasSuffix(r.URL.Path, ".zip") {
+			probed = true
+			w.Header().Set("Content-Range", "bytes 0-0/456")
+			w.WriteHeader(http.StatusPartialContent)
+			_, _ = w.Write([]byte("x"))
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprintf(w, `{"id":"apple.example","version":"1.2.3","resources":[{"name":"source-archive","type":"application/zip","checksum":%q}]}`, hex.EncodeToString(upstreamChecksum[:]))
+	}))
+	defer upstream.Close()
+
+	proxy, db, store, fetcher := setupTestProxy(t)
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader(string(archive))),
+		Size:        int64(len(archive)),
+		ContentType: "application/zip",
+	}
+	packagePURL, versionPURL := packageurl.MakeCacheStrings("swift", "apple/example", "1.2.3")
+	cached, err := proxy.getOrFetchArtifactFromURLWithCachePURLs(
+		context.Background(), "swift", "apple/example", "1.2.3", "example-1.2.3.zip",
+		packagePURL, versionPURL, upstream.URL+"/apple/example/1.2.3.zip", nil, "",
+	)
+	if err != nil {
+		t.Fatalf("seeding cache: %v", err)
+	}
+	_ = cached.Reader.Close()
+
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL).Routes()
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, httptest.NewRequest(http.MethodHead, "/apple/example/1.2.3.zip", nil))
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if !probed {
+		t.Error("stale cache entry was not replaced by an upstream probe")
+	}
+	if got := w.Header().Get("Content-Length"); got != "456" {
+		t.Errorf("Content-Length = %q, want 456 from upstream probe", got)
+	}
+	if len(store.files) != 0 {
+		t.Errorf("mismatched cached archive remained in storage: %v", store.files)
+	}
+	if rec, _ := db.GetCachedArtifact(packagePURL, versionPURL, "example-1.2.3.zip"); rec != nil {
+		t.Error("mismatched cache record was not cleared")
+	}
+}
+
+func TestSwiftSourceArchiveRequiresReleaseMetadata(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "unavailable", http.StatusServiceUnavailable)
+	}))
+	defer upstream.Close()
+
+	proxy, _, store, fetcher := setupTestProxy(t)
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("signed archive")),
+		ContentType: "application/zip",
+	}
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL).Routes()
+
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/apple/example/1.2.3.zip", nil))
+
+	if w.Code != http.StatusBadGateway {
+		t.Fatalf("status = %d, want 502; body: %s", w.Code, w.Body.String())
+	}
+	if fetcher.fetchCalled {
+		t.Error("archive was fetched without release security metadata")
+	}
+	if len(store.files) != 0 {
+		t.Errorf("archive was cached without release security metadata: %v", store.files)
+	}
+}
+
+func TestSwiftSourceArchiveColdHeadUsesRangeGetAcrossRedirect(t *testing.T) {
+	checksum := strings.Repeat("a", sha256.Size*2)
+	var archiveAccept string
+	var archiveMethod string
+	var archiveRange string
+	download := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		archiveMethod = r.Method
+		archiveRange = r.Header.Get("Range")
+		w.Header().Set("Content-Range", "bytes 0-0/123")
+		w.WriteHeader(http.StatusPartialContent)
+		_, _ = w.Write([]byte("x"))
+	}))
+	defer download.Close()
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/apple/example/1.2.3":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = fmt.Fprintf(w, `{"id":"apple.example","version":"1.2.3","resources":[{"name":"source-archive","type":"application/zip","checksum":%q}]}`, checksum)
+		case "/apple/example/1.2.3.zip":
+			archiveAccept = r.Header.Get("Accept")
+			http.Redirect(w, r, download.URL, http.StatusSeeOther)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL).Routes()
+
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, httptest.NewRequest(http.MethodHead, "/apple/example/1.2.3.zip", nil))
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if archiveMethod != http.MethodGet {
+		t.Errorf("download method = %q, want GET", archiveMethod)
+	}
+	if archiveRange != "bytes=0-0" {
+		t.Errorf("download Range = %q, want bytes=0-0", archiveRange)
+	}
+	if archiveAccept != swiftAcceptArchive {
+		t.Errorf("upstream Accept = %q, want %q", archiveAccept, swiftAcceptArchive)
+	}
+	if got := w.Header().Get("Content-Length"); got != "123" {
+		t.Errorf("Content-Length = %q, want 123", got)
+	}
+}
+
+func TestSwiftIdentifiersAndPublishingUnsupported(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/registry/identifiers" {
+			t.Errorf("upstream path = %q", r.URL.Path)
+		}
+		if got := r.URL.Query().Get("url"); got != "https://github.com/apple/example" {
+			t.Errorf("lookup URL = %q", got)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"identifiers":["apple.example"]}`)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, _ := setupTestProxy(t)
+	handler := NewSwiftHandler(proxy, "https://proxy.example", upstream.URL+"/registry").Routes()
+
+	req := httptest.NewRequest(http.MethodGet, "/identifiers?url=https%3A%2F%2Fgithub.com%2Fapple%2Fexample", nil)
+	w := httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+	if w.Code != http.StatusOK || !strings.Contains(w.Body.String(), "apple.example") {
+		t.Fatalf("identifier response = %d %q", w.Code, w.Body.String())
+	}
+
+	req = httptest.NewRequest(http.MethodGet, "/identifiers", nil)
+	w = httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("missing URL status = %d, want 400", w.Code)
+	}
+
+	req = httptest.NewRequest(http.MethodPut, "/apple/example/1.2.3", strings.NewReader("ignored"))
+	w = httptest.NewRecorder()
+	handler.ServeHTTP(w, req)
+	if w.Code != http.StatusMethodNotAllowed {
+		t.Errorf("publish status = %d, want 405", w.Code)
+	}
+	if got := w.Header().Get("Allow"); got != "GET, HEAD" {
+		t.Errorf("Allow = %q", got)
+	}
+}
+
+func TestSwiftIdentifierValidation(t *testing.T) {
+	tests := []struct {
+		name  string
+		value string
+		valid func(string) bool
+		want  bool
+	}{
+		{"scope", "apple", validSwiftScope, true},
+		{"scope hyphen", "swift-server", validSwiftScope, true},
+		{"scope underscore", "swift_server", validSwiftScope, false},
+		{"scope repeated separator", "swift--server", validSwiftScope, false},
+		{"package", "swift-argument_parser", validSwiftPackageName, true},
+		{"package repeated separators", "swift-_argument", validSwiftPackageName, false},
+		{"package trailing separator", "example-", validSwiftPackageName, false},
+		{"package non-ASCII", "café", validSwiftPackageName, false},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := test.valid(test.value); got != test.want {
+				t.Errorf("validation of %q = %v, want %v", test.value, got, test.want)
+			}
+		})
+	}
+}

internal/handler/upstream_test.go

@@ -0,0 +1,130 @@
+package handler
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestHandlerUpstreamConfiguration(t *testing.T) {
+	const (
+		proxyURL = "https://proxy.example.com/"
+		baseURL  = "https://upstream.example.com"
+	)
+	hex := NewHexHandlerWithUpstreams(nil, proxyURL, baseURL+"/hex/", baseURL+"/hex-api/")
+	pypi := NewPyPIHandlerWithUpstreams(nil, proxyURL, baseURL+"/pypi/", baseURL+"/pypi-download/")
+	nuget := NewNuGetHandlerWithUpstreams(nil, proxyURL, baseURL+"/nuget/", baseURL+"/nuget-search/")
+	composer := NewComposerHandlerWithUpstreams(
+		nil, proxyURL, baseURL+"/composer/", baseURL+"/composer-repository/",
+	)
+
+	got := map[string]string{
+		"gem":                 NewGemHandlerWithUpstream(nil, proxyURL, baseURL+"/gem/").upstreamURL,
+		"go":                  NewGoHandlerWithUpstream(nil, proxyURL, baseURL+"/go/").upstreamURL,
+		"hex":                 hex.upstreamURL,
+		"hex_api":             hex.apiURL,
+		"pub":                 NewPubHandlerWithUpstream(nil, proxyURL, baseURL+"/pub/").upstreamURL,
+		"pypi":                pypi.upstreamURL,
+		"pypi_download":       pypi.downloadURL,
+		"nuget":               nuget.upstreamURL,
+		"nuget_search":        nuget.searchURL,
+		"composer":            composer.upstreamURL,
+		"composer_repository": composer.repoURL,
+		"conan":               NewConanHandlerWithUpstream(nil, proxyURL, baseURL+"/conan/").upstreamURL,
+		"conda":               NewCondaHandlerWithUpstream(nil, proxyURL, baseURL+"/conda/").upstreamURL,
+		"cran":                NewCRANHandlerWithUpstream(nil, proxyURL, baseURL+"/cran/").upstreamURL,
+		"julia":               NewJuliaHandlerWithUpstream(nil, baseURL+"/julia/").upstreamURL,
+		"oci_default":         NewContainerHandlerWithRegistry(nil, proxyURL, baseURL+"/oci/").registryURL,
+		"rpm":                 NewRPMHandlerWithUpstream(nil, proxyURL, baseURL+"/rpm/").upstreamURL,
+	}
+
+	want := map[string]string{
+		"gem":                 baseURL + "/gem",
+		"go":                  baseURL + "/go",
+		"hex":                 baseURL + "/hex",
+		"hex_api":             baseURL + "/hex-api",
+		"pub":                 baseURL + "/pub",
+		"pypi":                baseURL + "/pypi",
+		"pypi_download":       baseURL + "/pypi-download",
+		"nuget":               baseURL + "/nuget",
+		"nuget_search":        baseURL + "/nuget-search",
+		"composer":            baseURL + "/composer",
+		"composer_repository": baseURL + "/composer-repository",
+		"conan":               baseURL + "/conan",
+		"conda":               baseURL + "/conda",
+		"cran":                baseURL + "/cran",
+		"julia":               baseURL + "/julia",
+		"oci_default":         baseURL + "/oci",
+		"rpm":                 baseURL + "/rpm",
+	}
+
+	for name, wantURL := range want {
+		if gotURL := got[name]; gotURL != wantURL {
+			t.Errorf("%s upstream = %q, want %q", name, gotURL, wantURL)
+		}
+	}
+}
+
+func TestConfiguredUpstreamURL(t *testing.T) {
+	if got := configuredUpstreamURL("", "https://default.example.com/"); got != "https://default.example.com" {
+		t.Errorf("empty configured URL = %q, want default", got)
+	}
+	if got := configuredUpstreamURL("https://custom.example.com/", "https://default.example.com"); got != "https://custom.example.com" {
+		t.Errorf("configured URL = %q, want trimmed custom URL", got)
+	}
+	if got := configuredUpstreamURL("https://custom.example.com///", "https://default.example.com"); got != "https://custom.example.com" {
+		t.Errorf("configured URL with trailing slashes = %q, want trimmed custom URL", got)
+	}
+}
+
+func TestHexHandlerUsesConfiguredAPIUpstream(t *testing.T) {
+	var requestedPath string
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestedPath = r.URL.Path
+		_, _ = io.WriteString(w, `{"releases":[]}`)
+	}))
+	defer upstream.Close()
+
+	h := NewHexHandlerWithUpstreams(
+		&Proxy{HTTPClient: upstream.Client()},
+		"https://proxy.example.com",
+		upstream.URL+"/hex",
+		upstream.URL+"/hex-api",
+	)
+	_, err := h.fetchFilteredVersions(httptest.NewRequest(http.MethodGet, "/", nil), "demo")
+	if err != nil {
+		t.Fatalf("fetchFilteredVersions failed: %v", err)
+	}
+	if requestedPath != "/hex-api/api/packages/demo" {
+		t.Errorf("API path = %q, want %q", requestedPath, "/hex-api/api/packages/demo")
+	}
+}
+
+func TestPyPIHandlerRewritesConfiguredDownloadUpstream(t *testing.T) {
+	h := NewPyPIHandlerWithUpstreams(
+		nil,
+		"https://proxy.example.com",
+		"https://upstream.example.com/pypi",
+		"https://upstream.example.com/pypi",
+	)
+	body := []byte(`<a href="https://upstream.example.com/pypi/packages/packages/ab/demo.whl#sha256=abc">demo</a>`)
+	want := `<a href="https://proxy.example.com/pypi/packages/packages/packages/ab/demo.whl#sha256=abc">demo</a>`
+	if got := string(h.rewriteSimpleHTML(body, nil)); got != want {
+		t.Errorf("rewritten HTML = %q, want %q", got, want)
+	}
+}
+
+func TestNuGetHandlerUsesConfiguredSearchUpstream(t *testing.T) {
+	h := NewNuGetHandlerWithUpstreams(
+		nil,
+		"https://proxy.example.com",
+		"https://upstream.example.com/nuget",
+		"https://upstream.example.com/nuget-search",
+	)
+	req := httptest.NewRequest(http.MethodGet, "/query?q=demo", nil)
+	want := "https://upstream.example.com/nuget-search/query?q=demo"
+	if got := h.buildUpstreamURL(req); got != want {
+		t.Errorf("search URL = %q, want %q", got, want)
+	}
+}

internal/httpclient/access_log.go

@@ -0,0 +1,74 @@
+package httpclient
+
+import (
+	"log/slog"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/git-pkgs/proxy/internal/accesslog"
+)
+
+type accessLogTransport struct {
+	base      http.RoundTripper
+	accessLog *accesslog.Logger
+	logger    *slog.Logger
+}
+
+// NewAccessLogTransport records each upstream HTTP exchange around base.
+func NewAccessLogTransport(base http.RoundTripper, log *accesslog.Logger, logger *slog.Logger) http.RoundTripper {
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	if log == nil {
+		return base
+	}
+	return &accessLogTransport{
+		base:      base,
+		accessLog: log,
+		logger:    logger,
+	}
+}
+
+func (t *accessLogTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	start := time.Now()
+	resp, err := t.base.RoundTrip(req)
+
+	entry := accesslog.Entry{
+		Event:      accesslog.EventUpstream,
+		RequestID:  accesslog.RequestID(req.Context()),
+		Method:     req.Method,
+		URL:        accesslog.URLWithoutSecrets(req.URL),
+		DurationMS: time.Since(start).Milliseconds(),
+	}
+	if resp != nil {
+		entry.StatusCode = resp.StatusCode
+	}
+	if err != nil {
+		entry.Error = errorWithoutSecrets(err, req.URL)
+	}
+	if writeErr := t.accessLog.Write(entry); writeErr != nil {
+		t.logger.Error("failed to write access log", "error", writeErr)
+	}
+
+	return resp, err
+}
+
+func errorWithoutSecrets(err error, requestURL *url.URL) string {
+	message := err.Error()
+	if requestURL == nil {
+		return message
+	}
+
+	cleanURL := accesslog.URLWithoutSecrets(requestURL)
+	for _, value := range []string{requestURL.String(), requestURL.Redacted()} {
+		if value != "" {
+			message = strings.ReplaceAll(message, value, cleanURL)
+		}
+	}
+	return message
+}

internal/httpclient/access_log_test.go

@@ -0,0 +1,121 @@
+package httpclient
+
+import (
+	"bufio"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/git-pkgs/proxy/internal/accesslog"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+func TestAccessLogTransportRecordsUpstreamStatus(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "access.jsonl")
+	accessLogger, err := accesslog.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusTooManyRequests,
+			Body:       io.NopCloser(strings.NewReader("rate limited")),
+			Request:    req,
+		}, nil
+	})
+	client := &http.Client{Transport: NewAccessLogTransport(base, accessLogger, slog.Default())}
+	req, err := http.NewRequest(http.MethodGet, "https://user:password@registry.example/package.tgz?token=secret", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req = req.WithContext(accesslog.WithRequestID(req.Context(), "request-123"))
+
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = resp.Body.Close()
+	if err := accessLogger.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	entry := readAccessLogEntry(t, path)
+	if entry.Event != accesslog.EventUpstream {
+		t.Errorf("event = %q, want %q", entry.Event, accesslog.EventUpstream)
+	}
+	if entry.RequestID != "request-123" {
+		t.Errorf("request_id = %q, want %q", entry.RequestID, "request-123")
+	}
+	if entry.StatusCode != http.StatusTooManyRequests {
+		t.Errorf("status_code = %d, want %d", entry.StatusCode, http.StatusTooManyRequests)
+	}
+	if entry.URL != "https://registry.example/package.tgz" {
+		t.Errorf("url = %q, want URL without credentials or query", entry.URL)
+	}
+}
+
+func TestAccessLogTransportRecordsUpstreamError(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "access.jsonl")
+	accessLogger, err := accesslog.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	wantErr := errors.New("GET https://user:password@registry.example/package.tgz?token=secret: connection refused")
+	base := roundTripFunc(func(*http.Request) (*http.Response, error) {
+		return nil, wantErr
+	})
+	client := &http.Client{Transport: NewAccessLogTransport(base, accessLogger, slog.Default())}
+
+	_, err = client.Get("https://user:password@registry.example/package.tgz?token=secret")
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("GET error = %v, want %v", err, wantErr)
+	}
+	if err := accessLogger.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	entry := readAccessLogEntry(t, path)
+	if entry.StatusCode != 0 {
+		t.Errorf("status_code = %d, want 0", entry.StatusCode)
+	}
+	if strings.Contains(entry.Error, "password") || strings.Contains(entry.Error, "secret") {
+		t.Errorf("error contains URL credentials or query: %q", entry.Error)
+	}
+	if !strings.Contains(entry.Error, "connection refused") {
+		t.Errorf("error = %q, want connection failure", entry.Error)
+	}
+}
+
+func readAccessLogEntry(t *testing.T, path string) accesslog.Entry {
+	t.Helper()
+
+	file, err := os.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = file.Close() }()
+
+	scanner := bufio.NewScanner(file)
+	if !scanner.Scan() {
+		t.Fatalf("access log is empty: %v", scanner.Err())
+	}
+
+	var entry accesslog.Entry
+	if err := json.Unmarshal(scanner.Bytes(), &entry); err != nil {
+		t.Fatalf("decoding access log: %v", err)
+	}
+	return entry
+}

internal/httpclient/transport.go

@@ -4,8 +4,10 @@ package httpclient
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"net/url"
 	"strings"
@@ -18,6 +20,8 @@ const (
 	tokenExpirySkew       = 5 * time.Second
 	maxTokenResponseSize  = 1 << 20
 	shortTokenSkewDivisor = 10
+	tokenMaxRetries       = 3
+	tokenRetryBaseDelay   = 500 * time.Millisecond
 )
 
 // AuthFunc returns a configured authentication header for a URL.
@@ -27,6 +31,7 @@ type AuthFunc func(url string) (headerName, headerValue string)
 type Transport struct {
 	base       http.RoundTripper
 	authForURL AuthFunc
+	retryWait  func(context.Context, time.Duration) error
 
 	mu         sync.Mutex
 	tokens     map[string]cachedToken
@@ -59,6 +64,7 @@ func NewTransport(base http.RoundTripper, authForURL AuthFunc) *Transport {
 	return &Transport{
 		base:       base,
 		authForURL: authForURL,
+		retryWait:  waitForRetry,
 		tokens:     make(map[string]cachedToken),
 		challenges: make(map[string]bearerChallenge),
 	}
@@ -172,17 +178,38 @@ func (t *Transport) fetchToken(ctx context.Context, challenge bearerChallenge) (
 	}
 
 	client := &http.Client{Transport: configuredTransport{parent: t}}
-	resp, err := client.Do(req)
-	if err != nil {
-		return "", time.Time{}, fmt.Errorf("requesting token: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
+	for attempt := 0; attempt <= tokenMaxRetries; attempt++ {
+		resp, err := client.Do(req.Clone(ctx))
+		if err != nil {
+			requestErr := fmt.Errorf("requesting token: %w", err)
+			if !shouldRetryTokenRequest(ctx, err) || attempt == tokenMaxRetries {
+				return "", time.Time{}, requestErr
+			}
+			if err := t.waitForTokenRetry(ctx, attempt); err != nil {
+				return "", time.Time{}, err
+			}
+			continue
+		}
 
-	if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, maxTokenResponseSize))
-		return "", time.Time{}, fmt.Errorf("token service returned %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+		if resp.StatusCode >= http.StatusOK && resp.StatusCode < http.StatusMultipleChoices {
+			return decodeTokenResponse(resp)
+		}
+
+		responseErr := tokenResponseError(resp)
+		if !shouldRetryTokenStatus(resp.StatusCode) || attempt == tokenMaxRetries {
+			return "", time.Time{}, responseErr
+		}
+		if err := t.waitForTokenRetry(ctx, attempt); err != nil {
+			return "", time.Time{}, err
+		}
 	}
 
+	return "", time.Time{}, errors.New("token request retries exhausted")
+}
+
+func decodeTokenResponse(resp *http.Response) (string, time.Time, error) {
+	defer func() { _ = resp.Body.Close() }()
+
 	var payload tokenResponse
 	if err := json.NewDecoder(io.LimitReader(resp.Body, maxTokenResponseSize)).Decode(&payload); err != nil {
 		return "", time.Time{}, fmt.Errorf("decoding token response: %w", err)
@@ -209,6 +236,53 @@ func (t *Transport) fetchToken(ctx context.Context, challenge bearerChallenge) (
 	return token, expiresAt, nil
 }
 
+func tokenResponseError(resp *http.Response) error {
+	defer func() { _ = resp.Body.Close() }()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, maxTokenResponseSize))
+	return fmt.Errorf("token service returned %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+}
+
+func shouldRetryTokenRequest(ctx context.Context, err error) bool {
+	if ctx.Err() != nil || errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		return false
+	}
+
+	var networkErr net.Error
+	if !errors.As(err, &networkErr) {
+		return false
+	}
+
+	var dnsErr *net.DNSError
+	if errors.As(err, &dnsErr) {
+		return dnsErr.IsTemporary || dnsErr.IsTimeout
+	}
+	return networkErr.Timeout()
+}
+
+func shouldRetryTokenStatus(status int) bool {
+	return status == http.StatusTooManyRequests || status >= http.StatusInternalServerError
+}
+
+func (t *Transport) waitForTokenRetry(ctx context.Context, attempt int) error {
+	delay := tokenRetryBaseDelay << attempt
+	if t.retryWait != nil {
+		return t.retryWait(ctx, delay)
+	}
+	return waitForRetry(ctx, delay)
+}
+
+func waitForRetry(ctx context.Context, delay time.Duration) error {
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
 type configuredTransport struct {
 	parent *Transport
 }

internal/httpclient/transport_test.go

@@ -2,7 +2,9 @@ package httpclient
 
 import (
 	"context"
+	"errors"
 	"io"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -10,6 +12,12 @@ import (
 	"time"
 )
 
+type roundTripperFunc func(*http.Request) (*http.Response, error)
+
+func (fn roundTripperFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return fn(req)
+}
+
 func TestTransportFollowsBearerChallengeAndCachesToken(t *testing.T) {
 	var registryRequests int
 	var tokenRequests int
@@ -68,6 +76,161 @@ func TestTransportFollowsBearerChallengeAndCachesToken(t *testing.T) {
 	}
 }
 
+func TestTransportRetriesTemporaryTokenLookupFailures(t *testing.T) {
+	var registryRequests int
+	var tokenRequests int
+	var tokenLookupFailures int
+	var server *httptest.Server
+
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/token":
+			tokenRequests++
+			_, _ = io.WriteString(w, `{"token":"registry-token"}`)
+		case "/v2/library/test/blobs/sha256:test":
+			registryRequests++
+			if r.Header.Get("Authorization") != "Bearer registry-token" {
+				w.Header().Set("WWW-Authenticate", `Bearer realm="`+server.URL+`/token",service="registry.test",scope="repository:library/test:pull"`)
+				http.Error(w, "authentication required", http.StatusUnauthorized)
+				return
+			}
+			_, _ = io.WriteString(w, "blob")
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+
+	base := roundTripperFunc(func(req *http.Request) (*http.Response, error) {
+		if req.URL.Path == "/token" && tokenLookupFailures < 2 {
+			tokenLookupFailures++
+			return nil, &net.DNSError{Err: "server misbehaving", IsTemporary: true}
+		}
+		return http.DefaultTransport.RoundTrip(req)
+	})
+	transport := NewTransport(base, nil)
+	transport.retryWait = func(context.Context, time.Duration) error { return nil }
+	client := &http.Client{Transport: transport}
+
+	resp, err := client.Get(server.URL + "/v2/library/test/blobs/sha256:test")
+	if err != nil {
+		t.Fatalf("GET blob: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusOK)
+	}
+	if tokenLookupFailures != 2 {
+		t.Errorf("token lookup failures = %d, want 2", tokenLookupFailures)
+	}
+	if tokenRequests != 1 {
+		t.Errorf("token requests = %d, want 1", tokenRequests)
+	}
+	if registryRequests != 2 {
+		t.Errorf("registry requests = %d, want 2", registryRequests)
+	}
+}
+
+func TestTransportDoesNotRetryPermanentTokenLookupFailures(t *testing.T) {
+	var tokenRequests int
+	base := roundTripperFunc(func(*http.Request) (*http.Response, error) {
+		tokenRequests++
+		return nil, &net.DNSError{Err: "no such host"}
+	})
+	transport := NewTransport(base, nil)
+	transport.retryWait = func(context.Context, time.Duration) error { return nil }
+
+	_, _, err := transport.fetchToken(context.Background(), bearerChallenge{realm: "https://auth.example.test/token"})
+	if err == nil {
+		t.Fatal("fetchToken succeeded, want error")
+	}
+	if tokenRequests != 1 {
+		t.Errorf("token requests = %d, want 1", tokenRequests)
+	}
+}
+
+func TestTransportDoesNotRetryPermanentTokenFailures(t *testing.T) {
+	var tokenRequests int
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		tokenRequests++
+		http.Error(w, "invalid credentials", http.StatusUnauthorized)
+	}))
+	defer server.Close()
+
+	transport := NewTransport(http.DefaultTransport, nil)
+	_, _, err := transport.fetchToken(context.Background(), bearerChallenge{realm: server.URL + "/token"})
+	if err == nil {
+		t.Fatal("fetchToken succeeded, want error")
+	}
+	if tokenRequests != 1 {
+		t.Errorf("token requests = %d, want 1", tokenRequests)
+	}
+}
+
+func TestTransportRetriesTokenServiceFailures(t *testing.T) {
+	for _, status := range []int{http.StatusTooManyRequests, http.StatusServiceUnavailable} {
+		t.Run(http.StatusText(status), func(t *testing.T) {
+			var tokenRequests int
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				tokenRequests++
+				http.Error(w, "temporary token service failure", status)
+			}))
+			defer server.Close()
+
+			var delays []time.Duration
+			transport := NewTransport(http.DefaultTransport, nil)
+			transport.retryWait = func(_ context.Context, delay time.Duration) error {
+				delays = append(delays, delay)
+				return nil
+			}
+
+			_, _, err := transport.fetchToken(context.Background(), bearerChallenge{realm: server.URL + "/token"})
+			if err == nil {
+				t.Fatal("fetchToken succeeded, want error")
+			}
+			if tokenRequests != tokenMaxRetries+1 {
+				t.Errorf("token requests = %d, want %d", tokenRequests, tokenMaxRetries+1)
+			}
+			wantDelays := []time.Duration{500 * time.Millisecond, time.Second, 2 * time.Second}
+			if len(delays) != len(wantDelays) {
+				t.Fatalf("retry delays = %v, want %v", delays, wantDelays)
+			}
+			for index, want := range wantDelays {
+				if delays[index] != want {
+					t.Errorf("retry delay %d = %s, want %s", index, delays[index], want)
+				}
+			}
+		})
+	}
+}
+
+func TestTransportStopsTokenRetriesWhenWaitingIsCancelled(t *testing.T) {
+	var tokenRequests int
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		tokenRequests++
+		http.Error(w, "temporary token service failure", http.StatusServiceUnavailable)
+	}))
+	defer server.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	transport := NewTransport(http.DefaultTransport, nil)
+	transport.retryWait = func(ctx context.Context, _ time.Duration) error {
+		cancel()
+		<-ctx.Done()
+		return ctx.Err()
+	}
+
+	_, _, err := transport.fetchToken(ctx, bearerChallenge{realm: server.URL + "/token"})
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("fetchToken error = %v, want context canceled", err)
+	}
+	if tokenRequests != 1 {
+		t.Errorf("token requests = %d, want 1", tokenRequests)
+	}
+}
+
 func TestTransportAddsConfiguredAuthentication(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("X-Registry-Token"); got != "configured-token" {

internal/metrics/metrics.go

@@ -6,6 +6,7 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/git-pkgs/purl"
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
 )
@@ -136,6 +137,32 @@ var (
 		},
 		[]string{"step"},
 	)
+
+	// Scanning metrics
+	ScanDuration = prometheus.NewHistogramVec(
+		prometheus.HistogramOpts{
+			Name:    "proxy_scan_duration_seconds",
+			Help:    "Pre-cache artifact scan duration in seconds, by ecosystem and scanner",
+			Buckets: prometheus.DefBuckets,
+		},
+		[]string{"ecosystem", "scanner"},
+	)
+
+	ScanBlocked = prometheus.NewCounterVec(
+		prometheus.CounterOpts{
+			Name: "proxy_scan_blocked_total",
+			Help: "Total number of artifacts blocked by a pre-cache scan, by ecosystem and scanner",
+		},
+		[]string{"ecosystem", "scanner"},
+	)
+
+	ScanErrors = prometheus.NewCounterVec(
+		prometheus.CounterOpts{
+			Name: "proxy_scan_errors_total",
+			Help: "Total number of pre-cache scan errors, by ecosystem, scanner, and error type",
+		},
+		[]string{"ecosystem", "scanner", "error_type"},
+	)
 )
 
 func init() {
@@ -156,6 +183,9 @@ func init() {
 		ActiveRequests,
 		IntegrityFailures,
 		HealthProbeFailures,
+		ScanDuration,
+		ScanBlocked,
+		ScanErrors,
 	)
 }
 
@@ -173,12 +203,12 @@ func RecordRequest(ecosystem string, status int, duration time.Duration) {
 
 // RecordCacheHit increments cache hit counter.
 func RecordCacheHit(ecosystem string) {
-	CacheHits.WithLabelValues(ecosystem).Inc()
+	CacheHits.WithLabelValues(purl.NormalizeEcosystem(ecosystem)).Inc()
 }
 
 // RecordCacheMiss increments cache miss counter.
 func RecordCacheMiss(ecosystem string) {
-	CacheMisses.WithLabelValues(ecosystem).Inc()
+	CacheMisses.WithLabelValues(purl.NormalizeEcosystem(ecosystem)).Inc()
 }
 
 // RecordUpstreamFetch tracks upstream fetch duration.
@@ -212,6 +242,21 @@ func RecordStorageError(operation string) {
 	StorageErrors.WithLabelValues(operation).Inc()
 }
 
+// RecordScanResult tracks a completed pre-cache scan call.
+func RecordScanResult(ecosystem, scannerName string, allowed bool, duration time.Duration) {
+	ecosystem = purl.NormalizeEcosystem(ecosystem)
+	ScanDuration.WithLabelValues(ecosystem, scannerName).Observe(duration.Seconds())
+	if !allowed {
+		ScanBlocked.WithLabelValues(ecosystem, scannerName).Inc()
+	}
+}
+
+// RecordScanError increments the scan error counter.
+// errorType is one of: "error" (scanner call failed), "timeout", "cancelled".
+func RecordScanError(ecosystem, scannerName, errorType string) {
+	ScanErrors.WithLabelValues(purl.NormalizeEcosystem(ecosystem), scannerName, errorType).Inc()
+}
+
 // UpdateCacheStats updates cache size and artifact count gauges.
 func UpdateCacheStats(sizeBytes, artifactCount int64) {
 	CacheSize.Set(float64(sizeBytes))

internal/metrics/metrics_test.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/testutil"
 	dto "github.com/prometheus/client_model/go"
 )
 
@@ -191,22 +192,45 @@ func TestMetricsEndpointOutput(t *testing.T) {
 
 func TestMetricsLabeling(t *testing.T) {
 	// Test that different ecosystems are properly labeled
-	ecosystems := []string{"npm", "pypi", "cargo", "gem"}
+	ecosystems := []struct {
+		input string
+		label string
+	}{
+		{input: "npm", label: "npm"},
+		{input: "pypi", label: "pypi"},
+		{input: "cargo", label: "cargo"},
+		{input: "gem", label: "rubygems"},
+	}
 
 	for _, eco := range ecosystems {
-		RecordRequest(eco, 200, 10*time.Millisecond)
-		RecordCacheHit(eco)
+		RecordRequest(eco.input, 200, 10*time.Millisecond)
+		RecordCacheHit(eco.input)
 	}
 
 	// Verify each ecosystem has metrics
 	for _, eco := range ecosystems {
-		val := getMetricValue(t, CacheHits, eco)
+		val := getMetricValue(t, CacheHits, eco.label)
 		if val == 0 {
-			t.Errorf("no cache hits recorded for %s", eco)
+			t.Errorf("no cache hits recorded for %s", eco.label)
 		}
 	}
 }
 
+func TestCacheMetricLabelsAreNormalized(t *testing.T) {
+	rubyHitsBefore := testutil.ToFloat64(CacheHits.WithLabelValues("rubygems"))
+	composerMissesBefore := testutil.ToFloat64(CacheMisses.WithLabelValues("packagist"))
+
+	RecordCacheHit("gem")
+	RecordCacheMiss("composer")
+
+	if diff := testutil.ToFloat64(CacheHits.WithLabelValues("rubygems")) - rubyHitsBefore; diff != 1 {
+		t.Errorf("rubygems cache hits delta = %.0f, want 1", diff)
+	}
+	if diff := testutil.ToFloat64(CacheMisses.WithLabelValues("packagist")) - composerMissesBefore; diff != 1 {
+		t.Errorf("packagist cache misses delta = %.0f, want 1", diff)
+	}
+}
+
 func TestMetricNames(t *testing.T) {
 	// Verify metric names follow Prometheus naming conventions
 	expectedMetrics := []string{

internal/mirror/job.go

@@ -3,6 +3,7 @@ package mirror
 import (
 	"context"
 	"crypto/rand"
+	"encoding/json"
 	"fmt"
 	"sync"
 	"time"
@@ -35,8 +36,9 @@ type Job struct {
 
 // JobRequest is the JSON body for starting a mirror job via the API.
 type JobRequest struct {
-	PURLs    []string `json:"purls,omitempty"`
-	Registry string   `json:"registry,omitempty"`
+	PURLs    []string        `json:"purls,omitempty"`
+	SBOM     json.RawMessage `json:"sbom,omitempty"`
+	Registry string          `json:"registry,omitempty"`
 }
 
 // JobStore manages in-memory mirror jobs.
@@ -190,12 +192,16 @@ func (js *JobStore) runJob(ctx context.Context, cancel context.CancelFunc, job *
 
 func (js *JobStore) sourceFromRequest(req JobRequest) (Source, error) { //nolint:ireturn // interface return is the design
 	switch {
+	case len(req.PURLs) > 0 && len(req.SBOM) > 0:
+		return nil, fmt.Errorf("request must include only one of purls or sbom")
 	case len(req.PURLs) > 0:
 		return &PURLSource{PURLs: req.PURLs}, nil
+	case len(req.SBOM) > 0:
+		return &SBOMSource{Data: req.SBOM}, nil
 	case req.Registry != "":
 		return nil, fmt.Errorf("registry mirroring is not yet implemented; use purls instead")
 	default:
-		return nil, fmt.Errorf("request must include purls")
+		return nil, fmt.Errorf("request must include purls or sbom")
 	}
 }
 

internal/mirror/job_test.go

@@ -2,6 +2,7 @@ package mirror
 
 import (
 	"context"
+	"encoding/json"
 	"testing"
 	"time"
 )
@@ -100,6 +101,37 @@ func TestSourceFromRequestPURLs(t *testing.T) {
 	}
 }
 
+func TestSourceFromRequestSBOM(t *testing.T) {
+	m := setupTestMirror(t, 1)
+	js := NewJobStore(context.Background(), m)
+	sbom := json.RawMessage(`{"bomFormat":"CycloneDX","components":[]}`)
+
+	source, err := js.sourceFromRequest(JobRequest{SBOM: sbom})
+	if err != nil {
+		t.Fatalf("sourceFromRequest() error = %v", err)
+	}
+	sbomSource, ok := source.(*SBOMSource)
+	if !ok {
+		t.Fatalf("expected *SBOMSource, got %T", source)
+	}
+	if got := string(sbomSource.Data); got != string(sbom) {
+		t.Errorf("SBOM data = %q, want %q", got, sbom)
+	}
+}
+
+func TestSourceFromRequestRejectsPURLsAndSBOM(t *testing.T) {
+	m := setupTestMirror(t, 1)
+	js := NewJobStore(context.Background(), m)
+
+	_, err := js.sourceFromRequest(JobRequest{
+		PURLs: []string{"pkg:npm/lodash@4.17.21"},
+		SBOM:  json.RawMessage(`{"bomFormat":"CycloneDX","components":[]}`),
+	})
+	if err == nil {
+		t.Fatal("expected error when both purls and sbom are provided")
+	}
+}
+
 func TestSourceFromRequestRegistryRejected(t *testing.T) {
 	m := setupTestMirror(t, 1)
 	js := NewJobStore(context.Background(), m)

internal/mirror/mirror.go

@@ -212,7 +212,9 @@ func (m *Mirror) mirrorOne(ctx context.Context, pv PackageVersion, tracker *prog
 		return
 	}
 
-	_ = result.Reader.Close()
+	if result.Reader != nil {
+		_ = result.Reader.Close()
+	}
 
 	if result.Cached {
 		tracker.skipped.Add(1)
@@ -220,9 +222,9 @@ func (m *Mirror) mirrorOne(ctx context.Context, pv PackageVersion, tracker *prog
 			"ecosystem", pv.Ecosystem, "name", pv.Name, "version", pv.Version)
 	} else {
 		tracker.completed.Add(1)
-		tracker.bytes.Add(result.Size)
+		tracker.bytes.Add(result.Artifact.Size)
 		m.logger.Info("mirrored",
 			"ecosystem", pv.Ecosystem, "name", pv.Name, "version", pv.Version,
-			"size", result.Size)
+			"size", result.Artifact.Size)
 	}
 }

internal/mirror/mirror_test.go

@@ -2,8 +2,11 @@ package mirror
 
 import (
 	"context"
+	"crypto/sha256"
+	"database/sql"
 	"log/slog"
 	"os"
+	"strings"
 	"testing"
 	"time"
 
@@ -43,6 +46,14 @@ func setupTestMirror(t *testing.T, workers int) *Mirror {
 
 const testPackageLodash = "lodash"
 
+type signedURLStorage struct {
+	storage.Storage
+}
+
+func (signedURLStorage) SignedURL(context.Context, string, time.Duration) (string, error) {
+	return "https://storage.example/artifact", nil
+}
+
 func TestMirrorRunEmptySource(t *testing.T) {
 	m := setupTestMirror(t, 2)
 
@@ -111,6 +122,54 @@ func TestMirrorRunCanceled(t *testing.T) {
 	}
 }
 
+func TestMirrorOneDirectServeCacheHit(t *testing.T) {
+	m := setupTestMirror(t, 1)
+	m.proxy.DirectServe = true
+	m.proxy.Storage = signedURLStorage{Storage: m.storage}
+
+	packagePURL := "pkg:npm/example"
+	versionPURL := packagePURL + "@1.0.0"
+	if err := m.db.UpsertPackage(&database.Package{
+		PURL:      packagePURL,
+		Ecosystem: "npm",
+		Name:      "example",
+	}); err != nil {
+		t.Fatalf("UpsertPackage() error = %v", err)
+	}
+	if err := m.db.UpsertVersion(&database.Version{
+		PURL:        versionPURL,
+		PackagePURL: packagePURL,
+	}); err != nil {
+		t.Fatalf("UpsertVersion() error = %v", err)
+	}
+	if err := m.db.UpsertArtifact(&database.Artifact{
+		VersionPURL: versionPURL,
+		Filename:    "",
+		UpstreamURL: "https://registry.example/artifact",
+		StoragePath: sql.NullString{String: "npm/example/1.0.0/artifact", Valid: true},
+		ContentHash: sql.NullString{String: strings.Repeat("a", sha256.Size*2), Valid: true},
+		Size:        sql.NullInt64{Int64: 1, Valid: true},
+		FetchedAt:   sql.NullTime{Time: time.Now(), Valid: true},
+	}); err != nil {
+		t.Fatalf("UpsertArtifact() error = %v", err)
+	}
+
+	tracker := newProgressTracker()
+	m.mirrorOne(context.Background(), PackageVersion{
+		Ecosystem: "npm",
+		Name:      "example",
+		Version:   "1.0.0",
+	}, tracker)
+
+	progress := tracker.snapshot()
+	if progress.Skipped != 1 {
+		t.Errorf("skipped = %d, want 1", progress.Skipped)
+	}
+	if progress.Failed != 0 {
+		t.Errorf("failed = %d, want 0", progress.Failed)
+	}
+}
+
 func TestProgressTrackerSnapshot(t *testing.T) {
 	pt := newProgressTracker()
 	pt.total.Store(10)