Fall back to embedded build info for Version (#352)

go install does not apply goreleaser's -ldflags -X, so binaries
installed that way reported 'dev'. Read debug.BuildInfo.Main.Version
when the ldflag is unset.

.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

@@ -18,6 +18,7 @@ jobs:
     permissions:
       packages: write
       contents: read
+      id-token: write
     steps:
       - name: Check out the repo
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
@@ -25,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
@@ -45,7 +46,10 @@ jobs:
         with:
           images: ghcr.io/${{ github.repository }}
 
+      - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+
       - name: Build and push Docker image
+        id: build
         uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a
         with:
           context: .
@@ -53,3 +57,105 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          provenance: mode=max
+          sbom: true
+
+      - name: Sign image by digest
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          IMAGE: ghcr.io/${{ github.repository }}
+        run: |
+          set -euo pipefail
+          [[ "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]
+          cosign sign --yes "${IMAGE}@${DIGEST}"
+
+      - name: Verify BuildKit attestations and extract SPDX predicates
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          IMAGE: ghcr.io/${{ github.repository }}
+        run: |
+          set -euo pipefail
+          reference="${IMAGE}@${DIGEST}"
+          docker buildx imagetools inspect "$reference" --format '{{ json .Provenance }}' > provenance.json
+          docker buildx imagetools inspect "$reference" --format '{{ json .SBOM }}' > sbom.json
+
+          for platform in linux/amd64 linux/arm64; do
+            jq -e --arg p "$platform" '.[$p].SLSA | type == "object" and length > 0' \
+              provenance.json >/dev/null
+            jq -e --arg p "$platform" '.[$p].SPDX' sbom.json > "sbom-${platform//\//-}.spdx.json"
+          done
+
+      - name: Attest platform SBOMs by digest
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+          IMAGE: ghcr.io/${{ github.repository }}
+        run: |
+          set -euo pipefail
+          [[ "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]
+          reference="${IMAGE}@${DIGEST}"
+          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`:
@@ -376,6 +487,13 @@ Replace your existing sources.list entries, then:
 sudo apt update
 ```
 
+The upstream defaults to `http://deb.debian.org/debian`. To proxy a different APT repository (e.g. Ubuntu), set `upstream.debian` in the config file or `PROXY_UPSTREAM_DEBIAN` in the environment:
+
+```yaml
+upstream:
+  debian: "http://archive.ubuntu.com/ubuntu"
+```
+
 ### RPM / Yum / DNF
 
 Configure yum/dnf to use the proxy in `/etc/yum.repos.d/proxy.repo`:
@@ -395,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:
@@ -409,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
 ```
 
@@ -431,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
@@ -451,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
@@ -504,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)
@@ -546,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
 
@@ -607,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 |
@@ -624,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 |
 
@@ -632,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 |
 
@@ -837,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 |
@@ -847,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
 
@@ -860,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:
@@ -1017,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
@@ -104,6 +106,7 @@ import (
 	"log/slog"
 	"os"
 	"os/signal"
+	"runtime/debug"
 	"strings"
 	"syscall"
 
@@ -126,6 +129,15 @@ var (
 	Commit = "unknown"
 )
 
+func init() {
+	if Version != "dev" {
+		return
+	}
+	if bi, ok := debug.ReadBuildInfo(); ok && bi.Main.Version != "" && bi.Main.Version != "(devel)" {
+		Version = bi.Main.Version
+	}
+}
+
 func main() {
 	if len(os.Args) > 1 {
 		switch os.Args[1] {
@@ -184,6 +196,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 +214,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 +294,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 +308,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 +439,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,14 +114,109 @@ 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 URL prefixes matched against request URLs.
+  # Keys are absolute URL scopes. Scheme, host, effective port, and path
+  # segment boundaries must match; the longest matching scope wins.
   # Values can reference environment variables using ${VAR_NAME} syntax.
   #
   # Supported auth types:
   #   - 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":
@@ -126,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:
@@ -173,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,
@@ -240,6 +241,8 @@ Fetches artifacts from upstream registries.
 - Exponential backoff retry on 429 (rate limit) and 5xx errors
 - Returns streaming reader (doesn't load into memory)
 - Configurable user-agent
+- Shares an authentication-aware transport with metadata requests so URL-scoped credentials apply consistently
+- Discovers and caches scoped OCI Bearer tokens from registry challenges
 
 **Resolver:**
 - Determines download URL for a package/version
@@ -267,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.
@@ -277,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`
 
@@ -351,6 +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 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,22 +108,168 @@ 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. Auth is matched by URL prefix, and credentials can reference environment variables using `${VAR_NAME}` syntax.
+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.
+
+OCI registries that return a Bearer challenge from a `/v2/{repository}/…` endpoint are handled automatically. The proxy discovers the token realm from `WWW-Authenticate`, applies any configured credentials for the token URL, and reuses the scoped token until shortly before it expires.
 
 ### Bearer Token
 
@@ -170,9 +316,24 @@ 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 configs are matched by URL prefix. The longest matching prefix wins, so you can configure different credentials for different paths:
+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:
 
 ```yaml
 upstream:
@@ -242,10 +403,109 @@ 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 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
 ```
@@ -288,7 +548,7 @@ http_timeout: "30s"   # default
 
 Or via environment variable: `PROXY_HTTP_TIMEOUT=2m`.
 
-Set to `"0"` to disable the timeout entirely (requests then rely only on the server's write timeout).
+Set to `"0"` to disable the timeout entirely (requests then rely only on the server's write timeout). Independently of this setting, the shared transport gives up on an upstream that has not sent response headers within 60 seconds.
 
 ## Mirror API
 
@@ -302,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.
@@ -115,7 +137,9 @@ type Config struct {
 	// HTTPTimeout is the timeout for individual upstream HTTP requests made
 	// by protocol handlers (metadata fetches, pass-through file requests).
 	// Uses Go duration syntax (e.g. "30s", "2m"). Default: "30s".
-	// Set to "0" to disable the timeout entirely.
+	// Set to "0" to disable the timeout entirely. Independently of this
+	// setting, the shared transport gives up on an upstream that has not sent
+	// response headers within 60 seconds.
 	HTTPTimeout string `json:"http_timeout" yaml:"http_timeout"`
 
 	// MirrorAPI enables the /api/mirror endpoints for starting mirror jobs via HTTP.
@@ -171,6 +195,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 +336,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 +354,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 +440,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,37 +511,111 @@ 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 URL prefixes that are matched against request URLs.
+	// Keys are absolute URL scopes matched by scheme, host, effective port,
+	// and path-segment prefix.
 	// Example: "https://npm.pkg.github.com" matches all requests to that host.
 	Auth map[string]AuthConfig `json:"auth" yaml:"auth"`
 }
 
 // AuthForURL returns the auth config that matches the given URL.
-// Matches are based on URL prefix - the longest matching prefix wins.
+// The longest matching URL scope wins.
 func (u *UpstreamConfig) AuthForURL(url string) *AuthConfig {
 	if u.Auth == nil {
 		return nil
 	}
+	target, err := parseAuthURL(url)
+	if err != nil {
+		return nil
+	}
 
 	var bestMatch *AuthConfig
 	var bestLen int
 
 	for pattern, auth := range u.Auth {
-		if strings.HasPrefix(url, pattern) && len(pattern) > bestLen {
+		configured, err := parseAuthURL(pattern)
+		if err == nil && authURLMatches(configured, target) && len(pattern) > bestLen {
 			a := auth // copy to avoid loop variable capture
 			bestMatch = &a
 			bestLen = len(pattern)
@@ -336,9 +625,82 @@ func (u *UpstreamConfig) AuthForURL(url string) *AuthConfig {
 	return bestMatch
 }
 
+// Validate checks upstream authentication URL scopes.
+func (u *UpstreamConfig) Validate() error {
+	for pattern := range u.Auth {
+		if _, err := parseAuthURL(pattern); err != nil {
+			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
+}
+
+func parseAuthURL(value string) (*url.URL, error) {
+	parsed, err := url.Parse(value)
+	if err != nil || !parsed.IsAbs() || parsed.Hostname() == "" || parsed.Opaque != "" {
+		return nil, fmt.Errorf("invalid authentication URL")
+	}
+	return parsed, nil
+}
+
+func authURLMatches(configured, target *url.URL) bool {
+	if !strings.EqualFold(configured.Scheme, target.Scheme) ||
+		!strings.EqualFold(configured.Hostname(), target.Hostname()) ||
+		authURLPort(configured) != authURLPort(target) {
+		return false
+	}
+	if configured.RawQuery != "" && configured.RawQuery != target.RawQuery {
+		return false
+	}
+
+	configuredPath := strings.TrimSuffix(configured.EscapedPath(), "/")
+	if configuredPath == "" {
+		return true
+	}
+	targetPath := strings.TrimSuffix(target.EscapedPath(), "/")
+	return targetPath == configuredPath || strings.HasPrefix(targetPath, configuredPath+"/")
+}
+
+func authURLPort(value *url.URL) string {
+	if port := value.Port(); port != "" {
+		return port
+	}
+	if strings.EqualFold(value.Scheme, "https") {
+		return "443"
+	}
+	if strings.EqualFold(value.Scheme, "http") {
+		return "80"
+	}
+	return ""
+}
+
 // 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.
@@ -358,6 +720,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.
@@ -379,11 +746,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{
@@ -443,6 +830,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
@@ -453,6 +856,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")
@@ -469,10 +874,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")
@@ -577,15 +1014,23 @@ func (c *Config) Validate() error {
 		return err
 	}
 
+	return c.validateComponents()
+}
+
+func (c *Config) validateComponents() error {
+	if err := c.Upstream.Validate(); err != nil {
+		return err
+	}
+
 	if err := c.Health.Validate(); err != nil {
 		return err
 	}
 
-	if err := c.Gradle.BuildCache.Validate(); err != nil {
+	if err := c.Scanning.Validate(); err != nil {
 		return err
 	}
 
-	return nil
+	return c.Gradle.BuildCache.Validate()
 }
 
 // Validate checks the /health configuration. An unset interval is allowed
@@ -652,6 +1097,7 @@ const (
 	defaultGradleBuildCacheSweepInterval = 10 * time.Minute
 	defaultGradleMaxUploadSizeStr        = "100MB"
 	defaultGradleSweepIntervalStr        = "10m"
+	defaultScanningTimeoutStr            = "30s"
 )
 
 // ParseMaxSize returns the maximum cache size in bytes.
@@ -830,8 +1276,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

@@ -3,6 +3,7 @@ package config
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 )
@@ -13,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()
 
@@ -25,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) {
@@ -211,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)
@@ -239,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) {
@@ -247,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)
@@ -264,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) {
@@ -274,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")
@@ -300,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")
 	}
@@ -326,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")
@@ -559,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
@@ -795,3 +1112,147 @@ func TestDatabaseConfigString(t *testing.T) {
 		}
 	}
 }
+
+func TestUpstreamAuthForURLMatchesURLComponents(t *testing.T) {
+	registryAuth := AuthConfig{Type: "bearer", Token: "registry-token"}
+	privateAuth := AuthConfig{Type: "bearer", Token: "private-token"}
+	config := UpstreamConfig{Auth: map[string]AuthConfig{
+		"https://registry.example.com":         registryAuth,
+		"https://registry.example.com/private": privateAuth,
+	}}
+
+	tests := []struct {
+		name      string
+		url       string
+		wantToken string
+	}{
+		{name: "registry root", url: "https://registry.example.com/package", wantToken: "registry-token"},
+		{name: "host is case insensitive", url: "https://REGISTRY.EXAMPLE.COM/package", wantToken: "registry-token"},
+		{name: "longest path match", url: "https://registry.example.com/private/package", wantToken: "private-token"},
+		{name: "exact path match", url: "https://registry.example.com/private", wantToken: "private-token"},
+		{name: "path segment boundary", url: "https://registry.example.com/private-other/package", wantToken: "registry-token"},
+		{name: "lookalike host rejected", url: "https://registry.example.com.evil.test/package"},
+		{name: "different scheme rejected", url: "http://registry.example.com/package"},
+		{name: "different port rejected", url: "https://registry.example.com:8443/package"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			auth := config.AuthForURL(tt.url)
+			if tt.wantToken == "" {
+				if auth != nil {
+					t.Fatalf("AuthForURL() = %+v, want nil", auth)
+				}
+				return
+			}
+			if auth == nil {
+				t.Fatal("AuthForURL() = nil, want authentication")
+			}
+			if auth.Token != tt.wantToken {
+				t.Errorf("token = %q, want %q", auth.Token, tt.wantToken)
+			}
+		})
+	}
+}
+
+func TestValidateUpstreamAuthURLs(t *testing.T) {
+	t.Run("valid absolute URL", func(t *testing.T) {
+		cfg := Default()
+		cfg.Upstream.Auth = map[string]AuthConfig{
+			"https://registry.example.com/private": {Type: "bearer", Token: "token"},
+		}
+
+		if err := cfg.Validate(); err != nil {
+			t.Fatalf("Validate() error = %v", err)
+		}
+	})
+
+	t.Run("invalid URL", func(t *testing.T) {
+		cfg := Default()
+		cfg.Upstream.Auth = map[string]AuthConfig{
+			"registry.example.com": {Type: "bearer", Token: "token"},
+		}
+
+		err := cfg.Validate()
+		if err == nil {
+			t.Fatal("Validate() error = nil, want invalid upstream.auth URL error")
+		}
+		if !strings.Contains(err.Error(), "upstream.auth") || !strings.Contains(err.Error(), "registry.example.com") {
+			t.Errorf("Validate() error = %q, want field and URL", err)
+		}
+	})
+}
+
+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.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"time"
 
 	"github.com/jmoiron/sqlx"
 	_ "github.com/lib/pq"
@@ -14,6 +15,16 @@ const SchemaVersion = 1
 
 const dirPermissions = 0755
 
+// Postgres connection pool limits. database/sql keeps only two idle
+// connections by default, which opens a new Postgres session for almost every
+// request under load.
+const (
+	postgresMaxOpenConns    = 32
+	postgresMaxIdleConns    = 32
+	postgresConnMaxIdleTime = 5 * time.Minute
+	postgresConnMaxLifetime = 30 * time.Minute
+)
+
 type Dialect string
 
 const (
@@ -94,6 +105,11 @@ func OpenPostgres(url string) (*DB, error) {
 		return nil, fmt.Errorf("opening postgres database: %w", err)
 	}
 
+	sqlDB.SetMaxOpenConns(postgresMaxOpenConns)
+	sqlDB.SetMaxIdleConns(postgresMaxIdleConns)
+	sqlDB.SetConnMaxIdleTime(postgresConnMaxIdleTime)
+	sqlDB.SetConnMaxLifetime(postgresConnMaxLifetime)
+
 	if err := sqlDB.Ping(); err != nil {
 		_ = sqlDB.Close()
 		return nil, fmt.Errorf("connecting to postgres: %w", err)

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)
 		}
@@ -239,6 +244,92 @@ func TestArtifactCRUD(t *testing.T) {
 	})
 }
 
+func TestGetCachedArtifact(t *testing.T) {
+	runWithBothDatabases(t, func(t *testing.T, db *DB) {
+		const (
+			packagePURL = "pkg:npm/lodash"
+			versionPURL = "pkg:npm/lodash@4.17.21"
+			filename    = "lodash-4.17.21.tgz"
+		)
+		seedCachedArtifactTestData(t, db, packagePURL, versionPURL, filename)
+
+		cached, err := db.GetCachedArtifact(packagePURL, versionPURL, filename)
+		if err != nil {
+			t.Fatalf("GetCachedArtifact before cache failed: %v", err)
+		}
+		if cached != nil {
+			t.Fatalf("expected no cached artifact, got %+v", cached)
+		}
+
+		if err := db.MarkArtifactCached(versionPURL, filename, "/cache/npm/"+filename,
+			testContentHash, 12345, "application/gzip"); err != nil {
+			t.Fatalf("MarkArtifactCached failed: %v", err)
+		}
+
+		cached, err = db.GetCachedArtifact(packagePURL, versionPURL, filename)
+		if err != nil {
+			t.Fatalf("GetCachedArtifact failed: %v", err)
+		}
+		if cached == nil {
+			t.Fatal("expected cached artifact, got nil")
+		}
+		if cached.Ecosystem != "npm" {
+			t.Errorf("expected npm ecosystem, got %q", cached.Ecosystem)
+		}
+		if cached.StoragePath != "/cache/npm/"+filename {
+			t.Errorf("expected cached storage path, got %q", cached.StoragePath)
+		}
+		if cached.Artifact.PURL != versionPURL {
+			t.Errorf("expected cached PURL %q, got %q", versionPURL, cached.Artifact.PURL)
+		}
+		if cached.Artifact.Digest.String() != "sha256:"+testContentHash {
+			t.Errorf("expected cached digest, got %q", cached.Artifact.Digest)
+		}
+		if cached.Artifact.Size != 12345 {
+			t.Errorf("expected cached size 12345, got %d", cached.Artifact.Size)
+		}
+		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)
+		}
+
+		cached, err = db.GetCachedArtifact("pkg:npm/other", versionPURL, filename)
+		if err != nil {
+			t.Fatalf("GetCachedArtifact with wrong package failed: %v", err)
+		}
+		if cached != nil {
+			t.Fatalf("expected package mismatch to miss cache, got %+v", cached)
+		}
+	})
+}
+
+func seedCachedArtifactTestData(t *testing.T, db *DB, packagePURL, versionPURL, filename string) {
+	t.Helper()
+
+	if err := db.UpsertPackage(&Package{PURL: packagePURL, Ecosystem: "npm", Name: "lodash"}); err != nil {
+		t.Fatalf("UpsertPackage failed: %v", err)
+	}
+	if err := db.UpsertVersion(&Version{
+		PURL:        versionPURL,
+		PackagePURL: packagePURL,
+		Integrity:   sql.NullString{String: testIntegrity, Valid: true},
+	}); err != nil {
+		t.Fatalf("UpsertVersion failed: %v", err)
+	}
+	if err := db.UpsertArtifact(&Artifact{
+		VersionPURL: versionPURL,
+		Filename:    filename,
+		UpstreamURL: "https://registry.npmjs.org/lodash/-/" + filename,
+	}); err != nil {
+		t.Fatalf("UpsertArtifact failed: %v", err)
+	}
+}
+
 func TestCacheManagement(t *testing.T) {
 	runWithBothDatabases(t, func(t *testing.T, db *DB) {
 		pkg := &Package{
@@ -519,8 +610,10 @@ func createTestPostgresDB(t *testing.T) *DB {
 		t.Fatalf("OpenPostgres failed: %v", err)
 	}
 
-	// Drop and recreate tables for clean test state
-	tables := []string{"artifacts", "versions", "packages", "schema_info"}
+	// Drop and recreate every table CreateSchema creates for clean test state;
+	// leftover migration records make the next CreateSchema fail on the
+	// migrations primary key.
+	tables := []string{"artifacts", "versions", "packages", "vulnerabilities", "metadata_cache", "migrations", "schema_info"}
 	for _, table := range tables {
 		_, _ = db.Exec("DROP TABLE IF EXISTS " + table + " CASCADE")
 	}
@@ -1014,3 +1107,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,9 +29,14 @@ 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},
-		Size:        sql.NullInt64{Int64: 1024, Valid: true},
-		FetchedAt:   sql.NullTime{Time: time.Now(), Valid: true},
+		ContentDigest: sql.NullString{
+			String: "sha256:0123456789abcdef",
+			Valid:  true,
+		},
+		Size:      sql.NullInt64{Int64: 1024, Valid: true},
+		FetchedAt: sql.NullTime{Time: time.Now(), Valid: true},
 	}
 
 	err := db.UpsertMetadataCache(entry)
@@ -59,9 +64,15 @@ 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")
 	}
+	if !got.ContentDigest.Valid || got.ContentDigest.String != "sha256:0123456789abcdef" {
+		t.Errorf("content_digest = %v, want %q", got.ContentDigest, "sha256:0123456789abcdef")
+	}
 	if !got.Size.Valid || got.Size.Int64 != 1024 {
 		t.Errorf("size = %v, want 1024", got.Size)
 	}
@@ -151,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")
 	}
@@ -178,3 +192,173 @@ func TestMetadataCacheTableCreatedByMigration(t *testing.T) {
 		t.Error("metadata_cache table should exist after migration")
 	}
 }
+
+func TestMetadataCacheContentDigestMigrationPreservesExistingRows(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_digest"); err != nil {
+		t.Fatalf("dropping content_digest: %v", err)
+	}
+	if _, err := db.Exec("DELETE FROM migrations WHERE name = ?", "006_add_metadata_content_digest"); err != nil {
+		t.Fatalf("resetting digest 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-manifest", "cache-key", "_metadata/oci-manifest/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)
+	}
+	hasDigest, err := db.HasColumn("metadata_cache", "content_digest")
+	if err != nil {
+		t.Fatalf("HasColumn() error = %v", err)
+	}
+	if !hasDigest {
+		t.Fatal("metadata_cache.content_digest was not added")
+	}
+
+	entry, err := db.GetMetadataCache("oci-manifest", "cache-key")
+	if err != nil {
+		t.Fatalf("GetMetadataCache() error = %v", err)
+	}
+	if entry == nil || entry.StoragePath != "_metadata/oci-manifest/cache-key/metadata" {
+		t.Fatalf("existing metadata cache row was not preserved: %#v", entry)
+	}
+	if entry.ContentDigest.Valid {
+		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/postgres_pool_test.go

@@ -0,0 +1,57 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"os"
+	"testing"
+)
+
+// TestOpenPostgresKeepsConnectionsIdle checks the connection-count limits
+// OpenPostgres sets: the open cap admits a burst of postgresMaxIdleConns
+// connections, and releasing them again leaves all of them idle in the pool.
+// database/sql's default keeps only two, so the next burst would open a new
+// Postgres session for almost every request. The idle-time and lifetime
+// settings are not exercised here.
+func TestOpenPostgresKeepsConnectionsIdle(t *testing.T) {
+	url := os.Getenv("PROXY_DATABASE_URL")
+	if url == "" {
+		t.Skip("PROXY_DATABASE_URL not set, skipping postgres pool test")
+	}
+
+	db, err := OpenPostgres(url)
+	if err != nil {
+		t.Fatalf("OpenPostgres failed: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	const burst = postgresMaxIdleConns
+	// database/sql keeps two idle connections by default; a burst that small
+	// could not tell the tuned pool from the default one.
+	if burst <= 2 {
+		t.Fatalf("postgresMaxIdleConns = %d, want more than database/sql's default of 2", burst)
+	}
+	if got := db.Stats().MaxOpenConnections; got <= 0 || got < burst {
+		t.Fatalf("MaxOpenConnections = %d, want a cap of at least %d", got, burst)
+	}
+
+	conns := make([]*sql.Conn, 0, burst)
+	for range burst {
+		conn, err := db.Conn(context.Background())
+		if err != nil {
+			t.Fatalf("taking connection %d: %v", len(conns)+1, err)
+		}
+		t.Cleanup(func() { _ = conn.Close() }) // release the session if an assertion below fails
+		conns = append(conns, conn)
+	}
+	if got := db.Stats().InUse; got != burst {
+		t.Fatalf("InUse = %d while holding %d connections", got, burst)
+	}
+
+	for _, conn := range conns {
+		_ = conn.Close()
+	}
+	if got := db.Stats().Idle; got != burst {
+		t.Errorf("Idle = %d after releasing %d connections, want all of them kept", got, burst)
+	}
+}

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) {
@@ -191,6 +226,56 @@ func (db *DB) GetArtifact(versionPURL, filename string) (*Artifact, error) {
 	return &a, nil
 }
 
+// GetCachedArtifact returns the fields needed to serve a cached artifact.
+func (db *DB) GetCachedArtifact(packagePURL, versionPURL, filename string) (*CachedArtifact, error) {
+	var row cachedArtifactRow
+	query := db.Rebind(`
+		SELECT packages.ecosystem, artifacts.storage_path, artifacts.content_hash, artifacts.size,
+		       artifacts.content_type, versions.integrity
+		FROM artifacts
+		JOIN versions ON versions.purl = artifacts.version_purl
+		JOIN packages ON packages.purl = versions.package_purl
+		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(&row, query, packagePURL, versionPURL, filename)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	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) {
 	var a Artifact
 	query := db.Rebind(`
@@ -443,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) {
@@ -461,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
@@ -474,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
 }
 
@@ -893,8 +969,8 @@ 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,
-		       size, last_modified, fetched_at, created_at, updated_at
+		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 = ?
 	`)
 	err := db.Get(&entry, query, ecosystem, name)
@@ -913,13 +989,16 @@ func (db *DB) UpsertMetadataCache(entry *MetadataCacheEntry) error {
 
 	if db.dialect == DialectPostgres {
 		query = `
-			INSERT INTO metadata_cache (ecosystem, name, storage_path, etag, content_type,
-			                            size, last_modified, fetched_at, created_at, updated_at)
-			VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+			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, $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,
 				fetched_at = EXCLUDED.fetched_at,
@@ -927,13 +1006,16 @@ func (db *DB) UpsertMetadataCache(entry *MetadataCacheEntry) error {
 		`
 	} else {
 		query = `
-			INSERT INTO metadata_cache (ecosystem, name, storage_path, etag, content_type,
-			                            size, last_modified, fetched_at, created_at, updated_at)
-			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+			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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 			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,
 				fetched_at = excluded.fetched_at,
@@ -942,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.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,10 @@ 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,
 	fetched_at DATETIME,
@@ -201,7 +204,10 @@ 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,
 	fetched_at TIMESTAMP,
@@ -359,6 +365,9 @@ var migrations = []migration{
 	{"003_ensure_artifacts_table", migrateEnsureArtifactsTable},
 	{"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.
@@ -581,6 +590,56 @@ func migrateEnsureMetadataCacheTable(db *DB) error {
 	return db.EnsureMetadataCacheTable()
 }
 
+func migrateAddMetadataContentDigest(db *DB) error {
+	hasColumn, err := db.HasColumn("metadata_cache", "content_digest")
+	if err != nil {
+		return fmt.Errorf("checking metadata_cache content_digest column: %w", err)
+	}
+	if hasColumn {
+		return nil
+	}
+	if _, err := db.Exec("ALTER TABLE metadata_cache ADD COLUMN content_digest TEXT"); err != nil {
+		return fmt.Errorf("adding metadata_cache content_digest column: %w", err)
+	}
+	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")
@@ -599,8 +658,11 @@ 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,
 				fetched_at TIMESTAMP,
@@ -616,8 +678,11 @@ 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,
 				fetched_at 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.
@@ -76,19 +148,30 @@ func (a *Artifact) IsCached() bool {
 	return a.StoragePath.Valid && a.FetchedAt.Valid
 }
 
+// CachedArtifact contains the fields needed to serve a cached artifact.
+type CachedArtifact struct {
+	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"`
-	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,38 +4,94 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io"
 	"net/http"
 	"regexp"
 	"strings"
 )
 
 const (
-	dockerHubRegistry  = "https://registry-1.docker.io"
-	dockerHubAuth      = "https://auth.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
-	authURL     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,
-		authURL:     dockerHubAuth,
 		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.
@@ -88,33 +144,45 @@ 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
+	}
 
-	// Get auth token for upstream
-	token, err := h.getAuthToken(r.Context(), name, "pull")
+	h.proxy.Logger.Info("container blob request", "name", upstreamName, "digest", digest)
+
+	filename := digest
+	cached, err := h.proxy.GetCachedArtifact(r.Context(), "oci", cacheName, digest, filename)
 	if err != nil {
-		h.proxy.Logger.Error("failed to get auth token", "error", err)
-		h.containerError(w, http.StatusUnauthorized, "UNAUTHORIZED", "failed to authenticate")
+		h.proxy.Logger.Error("failed to check blob cache", "error", err)
+		h.containerError(w, http.StatusInternalServerError, "INTERNAL_ERROR", "failed to check blob cache")
+		return
+	}
+	if cached != nil {
+		w.Header().Set("Docker-Content-Digest", digest)
+		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, token)
+		h.proxyBlobHead(w, r, registryURL, upstreamName, digest)
 		return
 	}
 
-	// Try to get from cache, or fetch from upstream with auth
-	filename := digest
-	headers := http.Header{"Authorization": {"Bearer " + token}}
-	result, err := h.proxy.GetOrFetchArtifactFromURLWithHeaders(
+	// Try to get from cache, or fetch from the authentication-aware upstream client.
+	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),
-		headers,
+		fmt.Sprintf("%s/v2/%s/blobs/%s", registryURL, upstreamName, digest),
+		digest,
 	)
 
 	if err != nil {
@@ -122,18 +190,28 @@ 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)
 }
 
-// handleManifest proxies manifest requests to upstream.
-// Manifests change when tags are updated, so we proxy these directly.
+// handleManifest serves immutable manifests from cache and revalidates mutable tags.
 // Path format: {name}/manifests/{reference}
 func (h *ContainerHandler) handleManifest(w http.ResponseWriter, r *http.Request, path string) {
 	if r.Method != http.MethodGet && r.Method != http.MethodHead {
@@ -147,61 +225,17 @@ func (h *ContainerHandler) handleManifest(w http.ResponseWriter, r *http.Request
 		return
 	}
 
-	h.proxy.Logger.Info("container manifest request", "name", name, "reference", reference)
-
-	// Get auth token
-	token, err := h.getAuthToken(r.Context(), name, "pull")
-	if err != nil {
-		h.proxy.Logger.Error("failed to get auth token", "error", err)
-		h.containerError(w, http.StatusUnauthorized, "UNAUTHORIZED", "failed to authenticate")
+	registryURL, upstreamName, _, ok := h.registryForName(name)
+	if !ok {
+		h.containerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unknown upstream registry")
 		return
 	}
 
-	// Proxy to upstream
-	upstreamURL := fmt.Sprintf("%s/v2/%s/manifests/%s", h.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")
-		return
-	}
-
-	req.Header.Set("Authorization", "Bearer "+token)
-
-	// Forward Accept header for content negotiation
-	if accept := r.Header.Get("Accept"); accept != "" {
-		req.Header.Set("Accept", accept)
-	} else {
-		// Default accept headers for manifests
-		req.Header.Set("Accept", strings.Join([]string{
-			"application/vnd.oci.image.manifest.v1+json",
-			"application/vnd.oci.image.index.v1+json",
-			"application/vnd.docker.distribution.manifest.v2+json",
-			"application/vnd.docker.distribution.manifest.list.v2+json",
-			"application/vnd.docker.distribution.manifest.v1+prettyjws",
-		}, ", "))
-	}
-
-	resp, err := h.proxy.HTTPClient.Do(req)
-	if err != nil {
-		h.proxy.Logger.Error("failed to fetch manifest", "error", err)
-		h.containerError(w, http.StatusBadGateway, "INTERNAL_ERROR", "failed to fetch from upstream")
-		return
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	// Copy relevant headers
-	for _, header := range []string{"Content-Type", "Content-Length", "Docker-Content-Digest", "ETag"} {
-		if v := resp.Header.Get(header); v != "" {
-			w.Header().Set(header, v)
-		}
-	}
-
-	w.WriteHeader(resp.StatusCode)
-	_, _ = io.Copy(w, resp.Body)
+	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)
@@ -214,78 +248,18 @@ func (h *ContainerHandler) handleTagsList(w http.ResponseWriter, r *http.Request
 		return
 	}
 
-	// Get auth token
-	token, err := h.getAuthToken(r.Context(), name, "pull")
-	if err != nil {
-		h.containerError(w, http.StatusUnauthorized, "UNAUTHORIZED", "failed to authenticate")
+	registryURL, upstreamName, _, ok := h.registryForName(name)
+	if !ok {
+		h.containerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unknown upstream registry")
 		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")
-		return
-	}
-
-	req.Header.Set("Authorization", "Bearer "+token)
-
-	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)
-}
-
-// getAuthToken gets a bearer token for the specified repository.
-// Docker Hub requires auth even for public images.
-func (h *ContainerHandler) getAuthToken(_ interface{ Done() <-chan struct{} }, repository, action string) (string, error) {
-	// For Docker Hub: https://auth.docker.io/token?service=registry.docker.io&scope=repository:{repo}:pull
-	authURL := fmt.Sprintf("%s/token?service=registry.docker.io&scope=repository:%s:%s",
-		h.authURL, repository, action)
-
-	req, err := http.NewRequest(http.MethodGet, authURL, nil)
-	if err != nil {
-		return "", err
-	}
-
-	resp, err := h.proxy.HTTPClient.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("auth failed with status %d", resp.StatusCode)
-	}
-
-	var tokenResp struct {
-		Token       string `json:"token"`
-		AccessToken string `json:"access_token"`
-	}
-
-	if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
-		return "", err
-	}
-
-	if tokenResp.Token != "" {
-		return tokenResp.Token, nil
-	}
-	return tokenResp.AccessToken, nil
+	h.serveTagsList(w, r, registryURL, upstreamName)
 }
 
 // proxyBlobHead handles HEAD requests for blobs.
-func (h *ContainerHandler) proxyBlobHead(w http.ResponseWriter, r *http.Request, name, digest, token 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 {
@@ -293,8 +267,6 @@ func (h *ContainerHandler) proxyBlobHead(w http.ResponseWriter, r *http.Request,
 		return
 	}
 
-	req.Header.Set("Authorization", "Bearer "+token)
-
 	resp, err := h.proxy.HTTPClient.Do(req)
 	if err != nil {
 		h.containerError(w, http.StatusBadGateway, "INTERNAL_ERROR", "failed to fetch from upstream")
@@ -302,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

@@ -0,0 +1,434 @@
+package handler
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	containerManifestCacheEcosystem = "oci-manifest"
+	containerStaleWarning           = `110 - "Response is Stale"`
+
+	containerAcceptWildcardSpecificity = iota
+	containerAcceptTypeWildcardSpecificity
+	containerAcceptExactSpecificity
+)
+
+var manifestDigestReferencePattern = regexp.MustCompile(`^[a-z0-9]+:[a-f0-9]+$`)
+
+type cachedContainerManifest struct {
+	body          []byte
+	contentType   string
+	contentDigest string
+	etag          string
+	size          int64
+	lastModified  time.Time
+	fetchedAt     time.Time
+}
+
+func (h *ContainerHandler) serveManifest(w http.ResponseWriter, r *http.Request, registryURL, name, reference string) {
+	accept := containerManifestAccept(r)
+	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, cached, false)
+		return
+	}
+
+	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")
+		return
+	}
+	req.Header.Set("Accept", accept)
+	if cached != nil && cached.etag != "" {
+		req.Header.Set("If-None-Match", cached.etag)
+	}
+
+	resp, err := h.proxy.HTTPClient.Do(req)
+	if err != nil {
+		h.serveStaleManifestOrError(w, r, cached, err)
+		return
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode == http.StatusNotModified && cached != nil {
+		cached.fetchedAt = time.Now()
+		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, cached, true)
+			return
+		}
+		copyContainerManifestHeaders(w.Header(), resp.Header)
+		w.WriteHeader(resp.StatusCode)
+		_, _ = io.Copy(w, resp.Body)
+		return
+	}
+
+	if r.Method == http.MethodHead {
+		copyContainerManifestHeaders(w.Header(), resp.Header)
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+
+	body, err := h.proxy.ReadMetadata(resp.Body)
+	if err != nil {
+		h.serveStaleManifestOrError(w, r, cached, fmt.Errorf("reading manifest: %w", err))
+		return
+	}
+	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
+		}
+	}
+	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, cached, true)
+		return
+	}
+	h.proxy.Logger.Error("failed to fetch manifest", "error", err)
+	h.containerError(w, http.StatusBadGateway, "INTERNAL_ERROR", "failed to fetch from upstream")
+}
+
+func (h *ContainerHandler) containerManifestFresh(manifest *cachedContainerManifest) bool {
+	return h.proxy.MetadataTTL > 0 && !manifest.fetchedAt.IsZero() && time.Since(manifest.fetchedAt) < h.proxy.MetadataTTL
+}
+
+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
+	}
+	entry, err := h.proxy.DB.GetMetadataCache(containerManifestCacheEcosystem, 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
+	}
+
+	manifest := &cachedContainerManifest{body: body, size: int64(len(body))}
+	if entry.ContentType.Valid {
+		manifest.contentType = entry.ContentType.String
+	}
+	if entry.ContentDigest.Valid {
+		manifest.contentDigest = entry.ContentDigest.String
+	} else {
+		manifest.contentDigest = sha256Digest(body)
+	}
+	if entry.ETag.Valid {
+		manifest.etag = entry.ETag.String
+	}
+	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
+	}
+	return manifest, nil
+}
+
+func (h *ContainerHandler) storeContainerManifest(ctx context.Context, cacheKey string, manifest *cachedContainerManifest) error {
+	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 nil
+}
+
+func writeContainerManifest(w http.ResponseWriter, r *http.Request, manifest *cachedContainerManifest, stale bool) {
+	if manifest.contentType != "" {
+		w.Header().Set(headerContentType, manifest.contentType)
+	}
+	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(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 r.Method != http.MethodHead {
+		_, _ = w.Write(manifest.body)
+	}
+}
+
+func containerManifestAccept(r *http.Request) string {
+	if accept := r.Header.Get("Accept"); accept != "" {
+		return accept
+	}
+	return strings.Join([]string{
+		"application/vnd.oci.image.manifest.v1+json",
+		"application/vnd.oci.image.index.v1+json",
+		"application/vnd.docker.distribution.manifest.v2+json",
+		"application/vnd.docker.distribution.manifest.list.v2+json",
+		"application/vnd.docker.distribution.manifest.v1+prettyjws",
+	}, ", ")
+}
+
+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{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
+}
+
+func sha256Digest(body []byte) string {
+	digest := sha256.Sum256(body)
+	return "sha256:" + hex.EncodeToString(digest[:])
+}

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/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_bench_test.go

@@ -0,0 +1,300 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/proxy/internal/database"
+	"github.com/git-pkgs/proxy/internal/storage"
+	"github.com/git-pkgs/purl"
+	"github.com/git-pkgs/registries/fetch"
+)
+
+const benchmarkArtifactSize = 64 << 10
+
+const benchmarkMetadataSize = 1 << 20
+
+type benchmarkResponseWriter struct {
+	header http.Header
+}
+
+func (w *benchmarkResponseWriter) Header() http.Header {
+	return w.header
+}
+
+func (w *benchmarkResponseWriter) Write(p []byte) (int, error) {
+	return len(p), nil
+}
+
+func (w *benchmarkResponseWriter) WriteHeader(_ int) {}
+
+func benchmarkCachedProxy(b *testing.B) (*Proxy, *mockStorage) {
+	b.Helper()
+
+	proxy, db, store, _ := setupTestProxy(b)
+	content := strings.Repeat("x", benchmarkArtifactSize)
+	seedPackage(b, db, store, "npm", "lodash", "4.17.21", "lodash-4.17.21.tgz", content)
+
+	artifact, err := db.GetArtifact("pkg:npm/lodash@4.17.21", "lodash-4.17.21.tgz")
+	if err != nil {
+		b.Fatalf("get seeded artifact: %v", err)
+	}
+	sum := sha256.Sum256([]byte(content))
+	artifact.ContentHash.String = hex.EncodeToString(sum[:])
+	if err := db.UpsertArtifact(artifact); err != nil {
+		b.Fatalf("update seeded artifact hash: %v", err)
+	}
+
+	return proxy, store
+}
+
+func BenchmarkArtifactCacheHit(b *testing.B) {
+	ctx := context.Background()
+
+	b.Run("stream-64KiB", func(b *testing.B) {
+		proxy, _ := benchmarkCachedProxy(b)
+		w := &benchmarkResponseWriter{header: make(http.Header)}
+		b.SetBytes(benchmarkArtifactSize)
+		b.ReportAllocs()
+		b.ResetTimer()
+
+		for b.Loop() {
+			result, err := proxy.GetOrFetchArtifact(ctx, "npm", "lodash", "4.17.21", "lodash-4.17.21.tgz")
+			if err != nil {
+				b.Fatal(err)
+			}
+			ServeArtifact(w, result)
+		}
+	})
+
+	b.Run("direct-serve", func(b *testing.B) {
+		proxy, store := benchmarkCachedProxy(b)
+		proxy.DirectServe = true
+		store.signedURL = "https://storage.example/npm/lodash-4.17.21.tgz?signature=abc"
+		w := &benchmarkResponseWriter{header: make(http.Header)}
+		b.ReportAllocs()
+		b.ResetTimer()
+
+		for b.Loop() {
+			result, err := proxy.GetOrFetchArtifact(ctx, "npm", "lodash", "4.17.21", "lodash-4.17.21.tgz")
+			if err != nil {
+				b.Fatal(err)
+			}
+			ServeArtifact(w, result)
+		}
+	})
+}
+
+func BenchmarkArtifactCacheHitParallel(b *testing.B) {
+	proxy, _ := benchmarkCachedProxy(b)
+	ctx := context.Background()
+	b.SetBytes(benchmarkArtifactSize)
+	b.ReportAllocs()
+	b.ResetTimer()
+
+	b.RunParallel(func(pb *testing.PB) {
+		w := &benchmarkResponseWriter{header: make(http.Header)}
+		for pb.Next() {
+			result, err := proxy.GetOrFetchArtifact(ctx, "npm", "lodash", "4.17.21", "lodash-4.17.21.tgz")
+			if err != nil {
+				b.Error(err)
+				return
+			}
+			ServeArtifact(w, result)
+		}
+	})
+}
+
+func BenchmarkReadMetadata(b *testing.B) {
+	payload := bytes.Repeat([]byte("x"), benchmarkMetadataSize)
+	proxy := &Proxy{MetadataMaxSize: benchmarkMetadataSize}
+	b.SetBytes(benchmarkMetadataSize)
+	b.ReportAllocs()
+
+	var data []byte
+	for b.Loop() {
+		var err error
+		data, err = proxy.ReadMetadata(bytes.NewReader(payload))
+		if err != nil {
+			b.Fatal(err)
+		}
+	}
+	if len(data) != len(payload) {
+		b.Fatalf("metadata size = %d, want %d", len(data), len(payload))
+	}
+}
+
+func BenchmarkArtifactPURLConstruction(b *testing.B) {
+	for _, tc := range []struct {
+		name      string
+		ecosystem string
+		packageID string
+	}{
+		{"npm", "npm", "lodash"},
+		{"scoped-npm", "npm", "@scope/package"},
+		{"go", "golang", "github.com/git-pkgs/proxy"},
+	} {
+		b.Run(tc.name, func(b *testing.B) {
+			b.ReportAllocs()
+			var packagePURL, versionPURL string
+			for b.Loop() {
+				packagePURL = purl.MakePURLString(tc.ecosystem, tc.packageID, "")
+				versionPURL = purl.MakePURLString(tc.ecosystem, tc.packageID, "1.2.3")
+			}
+			if packagePURL == "" || versionPURL == "" {
+				b.Fatal("empty PURL")
+			}
+		})
+	}
+}
+
+type benchmarkNPMServer struct {
+	client      *http.Client
+	requestURL  string
+	db          *database.DB
+	versionPURL string
+	filename    string
+}
+
+func newBenchmarkNPMServer(b *testing.B) *benchmarkNPMServer {
+	b.Helper()
+
+	ctx := context.Background()
+	dir := b.TempDir()
+	db, err := database.Create(filepath.Join(dir, "benchmark.db"))
+	if err != nil {
+		b.Fatalf("create database: %v", err)
+	}
+	b.Cleanup(func() { _ = db.Close() })
+
+	store, err := storage.OpenBucket(ctx, "file://"+filepath.Join(dir, "cache"))
+	if err != nil {
+		b.Fatalf("open storage: %v", err)
+	}
+	b.Cleanup(func() { _ = store.Close() })
+
+	content := bytes.Repeat([]byte("x"), benchmarkArtifactSize)
+	storagePath := storage.ArtifactPath("npm", "", "lodash", "4.17.21", "lodash-4.17.21.tgz")
+	size, hash, err := store.Store(ctx, storagePath, bytes.NewReader(content))
+	if err != nil {
+		b.Fatalf("store artifact: %v", err)
+	}
+
+	pkg := &database.Package{PURL: "pkg:npm/lodash", Ecosystem: "npm", Name: "lodash"}
+	if err := db.UpsertPackage(pkg); err != nil {
+		b.Fatalf("seed package: %v", err)
+	}
+	version := &database.Version{PURL: "pkg:npm/lodash@4.17.21", PackagePURL: pkg.PURL}
+	if err := db.UpsertVersion(version); err != nil {
+		b.Fatalf("seed version: %v", err)
+	}
+	artifact := &database.Artifact{
+		VersionPURL: version.PURL,
+		Filename:    "lodash-4.17.21.tgz",
+		UpstreamURL: "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
+		StoragePath: sql.NullString{String: storagePath, Valid: true},
+		ContentHash: sql.NullString{String: hash, Valid: true},
+		Size:        sql.NullInt64{Int64: size, Valid: true},
+		ContentType: sql.NullString{String: "application/gzip", Valid: true},
+		FetchedAt:   sql.NullTime{Time: time.Now(), Valid: true},
+	}
+	if err := db.UpsertArtifact(artifact); err != nil {
+		b.Fatalf("seed artifact: %v", err)
+	}
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	proxy := NewProxy(db, store, &mockFetcher{}, fetch.NewResolver(), logger)
+	handler := NewNPMHandler(proxy, "http://proxy.example", "https://registry.npmjs.org")
+	server := httptest.NewServer(handler.Routes())
+	b.Cleanup(server.Close)
+	client := server.Client()
+	return &benchmarkNPMServer{
+		client:      client,
+		requestURL:  server.URL + "/lodash/-/lodash-4.17.21.tgz",
+		db:          db,
+		versionPURL: version.PURL,
+		filename:    artifact.Filename,
+	}
+}
+
+func (s *benchmarkNPMServer) request() error {
+	resp, err := s.client.Get(s.requestURL)
+	if err != nil {
+		return fmt.Errorf("GET cached artifact: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("GET cached artifact status = %d, want %d", resp.StatusCode, http.StatusOK)
+	}
+	n, err := io.Copy(io.Discard, resp.Body)
+	if err != nil {
+		return fmt.Errorf("read cached artifact: %w", err)
+	}
+	if n != benchmarkArtifactSize {
+		return fmt.Errorf("cached artifact size = %d, want %d", n, benchmarkArtifactSize)
+	}
+	return nil
+}
+
+func (s *benchmarkNPMServer) hitCount(b *testing.B) int64 {
+	b.Helper()
+	artifact, err := s.db.GetArtifact(s.versionPURL, s.filename)
+	if err != nil {
+		b.Fatalf("get artifact hit count: %v", err)
+	}
+	return artifact.HitCount
+}
+
+func benchmarkNPMArtifactCacheHitHTTP(b *testing.B, parallel bool) {
+	server := newBenchmarkNPMServer(b)
+	if err := server.request(); err != nil {
+		b.Fatal(err)
+	}
+	startHits := server.hitCount(b)
+
+	b.SetBytes(benchmarkArtifactSize)
+	b.ReportAllocs()
+	b.ResetTimer()
+	if parallel {
+		b.RunParallel(func(pb *testing.PB) {
+			for pb.Next() {
+				if err := server.request(); err != nil {
+					b.Error(err)
+					return
+				}
+			}
+		})
+	} else {
+		for b.Loop() {
+			if err := server.request(); err != nil {
+				b.Fatal(err)
+			}
+		}
+	}
+	b.StopTimer()
+
+	if hitCount := server.hitCount(b) - startHits; hitCount != int64(b.N) {
+		b.Fatalf("new artifact hits = %d, want %d", hitCount, b.N)
+	}
+	b.ReportMetric(float64(b.N)/b.Elapsed().Seconds(), "requests/s")
+}
+
+func BenchmarkNPMArtifactCacheHitHTTP(b *testing.B) {
+	benchmarkNPMArtifactCacheHitHTTP(b, false)
+}
+
+func BenchmarkNPMArtifactCacheHitHTTPParallel(b *testing.B) {
+	benchmarkNPMArtifactCacheHitHTTP(b, true)
+}

internal/handler/handler_test.go

@@ -3,25 +3,34 @@ package handler
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
 	"database/sql"
 	"errors"
-	"fmt"
 	"io"
 	"log/slog"
 	"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
@@ -128,7 +163,7 @@ func (f *mockFetcher) Head(_ context.Context, _ string) (int64, string, error) {
 }
 
 // setupTestProxy creates a Proxy with a real DB (SQLite in temp dir) and mock storage/fetcher.
-func setupTestProxy(t *testing.T) (*Proxy, *database.DB, *mockStorage, *mockFetcher) {
+func setupTestProxy(t testing.TB) (*Proxy, *database.DB, *mockStorage, *mockFetcher) {
 	t.Helper()
 
 	dir := t.TempDir()
@@ -147,12 +182,35 @@ func setupTestProxy(t *testing.T) (*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.T, db *database.DB, store *mockStorage, ecosystem, name, version, filename, content string) {
+func seedPackage(t testing.TB, db *database.DB, store *mockStorage, ecosystem, name, version, filename, content string) {
 	t.Helper()
 
 	pkg := &database.Package{
-		PURL:      fmt.Sprintf("pkg:%s/%s", ecosystem, name),
+		PURL:      purl.MakePURLString(ecosystem, name, ""),
 		Ecosystem: ecosystem,
 		Name:      name,
 	}
@@ -160,7 +218,7 @@ func seedPackage(t *testing.T, db *database.DB, store *mockStorage, ecosystem, n
 		t.Fatalf("failed to upsert package: %v", err)
 	}
 
-	versionPURL := fmt.Sprintf("pkg:%s/%s@%s", ecosystem, name, version)
+	versionPURL := purl.MakePURLString(ecosystem, name, version)
 	ver := &database.Version{
 		PURL:        versionPURL,
 		PackagePURL: pkg.PURL,
@@ -171,13 +229,14 @@ func seedPackage(t *testing.T, 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

@@ -1,7 +1,6 @@
 package handler
 
 import (
-	"context"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -20,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",
@@ -117,23 +120,12 @@ func TestComposerDownloadUpstreamNotFoundReturns404(t *testing.T) {
 }
 
 func TestContainerBlobUpstreamNotFoundReturns404(t *testing.T) {
-	authServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(`{"token": "test-token-123"}`))
-	}))
-	defer authServer.Close()
-
-	proxy, _, _, _ := setupTestProxy(t)
-	proxy.Fetcher = &mockFetcherWithHeaders{
-		fetchFn: func(_ context.Context, _ string, _ http.Header) (*fetch.Artifact, error) {
-			return nil, fetch.ErrNotFound
-		},
-	}
+	proxy, _, _, fetcher := setupTestProxy(t)
+	fetcher.fetchErr = fetch.ErrNotFound
 
 	h := &ContainerHandler{
 		proxy:       proxy,
 		registryURL: "https://registry-1.docker.io",
-		authURL:     authServer.URL,
 		proxyURL:    "http://localhost:8080",
 	}
 

internal/handler/npm.go

@@ -13,7 +13,7 @@ import (
 
 const (
 	npmUpstream      = "https://registry.npmjs.org"
-	npmAbbreviatedCT = "application/vnd.npm.install-v1+json"
+	npmAcceptDefault = "application/vnd.npm.install-v1+json;q=1.0, application/json;q=0.8"
 	scopedParts      = 2 // scope + name in scoped packages
 )
 
@@ -71,10 +71,15 @@ func (h *NPMHandler) handlePackageMetadata(w http.ResponseWriter, r *http.Reques
 
 	upstreamURL := fmt.Sprintf("%s/%s", h.upstreamURL, url.PathEscape(packageName))
 
-	// Use abbreviated metadata when cooldown is disabled — it's much smaller
-	// (e.g. drizzle-orm: 4MB vs 92MB) but lacks the time map needed for cooldown.
-	accept := npmAbbreviatedCT
-	if h.proxy.Cooldown != nil && h.proxy.Cooldown.Enabled() {
+	// Prefer the smaller abbreviated packument format but include application/json
+	// as a fallback so upstreams that reject the abbreviated type (e.g. JFrog
+	// 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.NPMFullMetadata || (h.proxy.Cooldown != nil && h.proxy.Cooldown.Enabled()) {
 		accept = contentTypeJSON
 	}
 
@@ -93,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)
 }
@@ -265,6 +270,13 @@ func (h *NPMHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 	h.proxy.Logger.Info("npm download request",
 		"package", packageName, "version", version, "filename", filename)
 
+	if h.versionInCooldown(r, packageName, version) {
+		h.proxy.Logger.Info("cooldown: withholding npm tarball",
+			"package", packageName, "version", version)
+		JSONError(w, http.StatusNotFound, "version not found")
+		return
+	}
+
 	downloadURL := fmt.Sprintf(
 		"%s/%s/-/%s",
 		h.upstreamURL,
@@ -275,18 +287,78 @@ 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
 	}
 
 	ServeArtifact(w, result)
 }
 
+// versionInCooldown reports whether a version is still inside the cooldown
+// window. Filtering the packument is not enough on its own: tarball URLs are
+// predictable and lockfiles record them directly, so `npm ci` reaches the
+// download path without ever requesting metadata.
+//
+// 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)
+	if err != nil {
+		h.proxy.Logger.Warn("cooldown: could not fetch npm metadata for download check",
+			"package", packageName, "version", version, "error", err)
+		return false
+	}
+
+	var metadata struct {
+		Time map[string]string `json:"time"`
+	}
+	if err := json.Unmarshal(body, &metadata); err != nil {
+		h.proxy.Logger.Warn("cooldown: could not parse npm metadata for download check",
+			"package", packageName, "version", version, "error", err)
+		return false
+	}
+
+	published, ok := metadata.Time[version]
+	if !ok {
+		return false
+	}
+
+	publishedAt, err := time.Parse(time.RFC3339, published)
+	if err != nil {
+		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)
+}
+
 func escapeNPMDownloadPackage(packageName string) string {
 	scope, name, scoped := strings.Cut(packageName, "/")
 	if scoped && strings.HasPrefix(scope, "@") && len(scope) > 1 && name != "" && !strings.Contains(name, "/") {

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"
 
@@ -396,7 +398,7 @@ func TestNPMHandlerUsesAbbreviatedMetadata(t *testing.T) {
 	}))
 	defer upstream.Close()
 
-	t.Run("no cooldown uses abbreviated metadata", func(t *testing.T) {
+	t.Run("no cooldown uses combined accept header", func(t *testing.T) {
 		h := &NPMHandler{
 			proxy:       testProxy(),
 			upstreamURL: upstream.URL,
@@ -407,12 +409,12 @@ func TestNPMHandlerUsesAbbreviatedMetadata(t *testing.T) {
 		w := httptest.NewRecorder()
 		h.handlePackageMetadata(w, req)
 
-		if gotAccept != npmAbbreviatedCT {
-			t.Errorf("Accept = %q, want abbreviated metadata header", gotAccept)
+		if gotAccept != npmAcceptDefault {
+			t.Errorf("Accept = %q, want %q", gotAccept, npmAcceptDefault)
 		}
 	})
 
-	t.Run("cooldown enabled uses full metadata", func(t *testing.T) {
+	t.Run("cooldown enabled uses full metadata only", func(t *testing.T) {
 		proxy := testProxy()
 		proxy.Cooldown = &cooldown.Config{Default: "3d"}
 
@@ -426,8 +428,27 @@ func TestNPMHandlerUsesAbbreviatedMetadata(t *testing.T) {
 		w := httptest.NewRecorder()
 		h.handlePackageMetadata(w, req)
 
-		if gotAccept == npmAbbreviatedCT {
-			t.Error("cooldown enabled should use full metadata, not abbreviated")
+		if gotAccept != contentTypeJSON {
+			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)
 		}
 	})
 }
@@ -454,3 +475,237 @@ func TestNPMHandlerMetadataNotFound(t *testing.T) {
 		t.Errorf("status = %d, want %d", w.Code, http.StatusNotFound)
 	}
 }
+
+func TestNPMDownloadCooldown(t *testing.T) {
+	now := time.Now()
+	packument := `{
+		"name": "leftpad",
+		"dist-tags": {"latest": "2.0.0"},
+		"time": {
+			"1.0.0": "` + now.Add(-30*24*time.Hour).Format(time.RFC3339) + `",
+			"2.0.0": "` + now.Add(-1*time.Hour).Format(time.RFC3339) + `"
+		},
+		"versions": {"1.0.0": {}, "2.0.0": {}}
+	}`
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", contentTypeJSON)
+		_, _ = io.WriteString(w, packument)
+	}))
+	defer upstream.Close()
+
+	tests := []struct {
+		name       string
+		version    string
+		wantStatus int
+	}{
+		{"published before the window serves the tarball", testVersion100, http.StatusOK},
+		{"published inside the window is withheld", "2.0.0", http.StatusNotFound},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			proxy, _, _, 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",
+			}
+
+			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)
+			}
+			if tt.wantStatus == http.StatusNotFound && fetcher.fetchCalled {
+				t.Error("fetched a version that is still inside the cooldown window")
+			}
+		})
+	}
+}
+
+func TestNPMDownloadCooldownDisabled(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		t.Error("metadata must not be fetched when cooldown is disabled")
+		w.WriteHeader(http.StatusInternalServerError)
+	}))
+	defer upstream.Close()
+
+	proxy, _, _, fetcher := setupTestProxy(t)
+	proxy.HTTPClient = upstream.Client()
+	fetcher.artifact = &fetch.Artifact{
+		Body:        io.NopCloser(strings.NewReader("tarball data")),
+		ContentType: "application/octet-stream",
+	}
+
+	h := NewNPMHandler(proxy, "http://proxy.test", upstream.URL)
+
+	if h.versionInCooldown(httptest.NewRequest(http.MethodGet, "/", nil), "leftpad", testVersion100) {
+		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

@@ -7,17 +7,18 @@ import (
 	"io"
 	"net/http"
 	"strings"
-	"time"
 )
 
 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 +27,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()
@@ -39,10 +50,12 @@ func (h *NuGetHandler) Routes() http.Handler {
 
 	// Package content (downloads)
 	mux.HandleFunc("GET /v3-flatcontainer/{id}/{version}/{filename}", h.handleDownload)
-	mux.HandleFunc("GET /v3-flatcontainer/{id}/index.json", h.proxyUpstream)
+	mux.HandleFunc("GET /v3-flatcontainer/{id}/index.json", h.handleVersionList)
 
 	// Registration (package metadata) - use prefix matching since {version}.json isn't allowed
-	mux.HandleFunc("GET /v3/registration5-gz-semver2/", h.handleRegistration)
+	for _, prefix := range nugetRegistrationPrefixes {
+		mux.HandleFunc("GET "+prefix, h.handleRegistration)
+	}
 
 	// Search
 	mux.HandleFunc("GET /query", h.proxyUpstream)
@@ -72,13 +85,17 @@ func (h *NuGetHandler) handleServiceIndex(w http.ResponseWriter, r *http.Request
 
 	rewritten, err := h.rewriteServiceIndex(body)
 	if err != nil {
+		if h.cooldownEnabled() {
+			h.nugetMetadataError(w, err)
+			return
+		}
 		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,189 +120,35 @@ 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", "RegistrationsBaseUrl/3.0.0-beta", "RegistrationsBaseUrl/3.0.0-rc":
+		return h.proxyURL + "/nuget/v3/registration5-semver1/"
+	case "RegistrationsBaseUrl/3.4.0":
+		return h.proxyURL + "/nuget/v3/registration5-gz-semver1/"
+	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.
-func (h *NuGetHandler) handleRegistration(w http.ResponseWriter, r *http.Request) {
-	if h.proxy.Cooldown == nil || !h.proxy.Cooldown.Enabled() {
-		h.proxyUpstream(w, r)
-		return
-	}
-
-	upstreamURL := h.buildUpstreamURL(r)
-
-	h.proxy.Logger.Debug("fetching registration for cooldown filtering", "url", upstreamURL)
-
-	req, err := http.NewRequestWithContext(r.Context(), http.MethodGet, upstreamURL, nil)
-	if err != nil {
-		http.Error(w, "failed to create request", http.StatusInternalServerError)
-		return
-	}
-	req.Header.Set(headerAcceptEncoding, "gzip")
-
-	resp, err := h.proxy.HTTPClient.Do(req)
-	if err != nil {
-		h.proxy.Logger.Error("upstream request failed", "error", err)
-		http.Error(w, "upstream request failed", http.StatusBadGateway)
-		return
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	if resp.StatusCode != http.StatusOK {
-		for k, vv := range resp.Header {
-			for _, v := range vv {
-				w.Header().Add(k, v)
-			}
-		}
-		w.WriteHeader(resp.StatusCode)
-		_, _ = io.Copy(w, resp.Body)
-		return
-	}
-
-	body, err := h.proxy.ReadMetadata(resp.Body)
-	if err != nil {
-		http.Error(w, "failed to read response", http.StatusInternalServerError)
-		return
-	}
-
-	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.Write(body)
-		return
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	_, _ = w.Write(filtered)
-}
-
-// applyCooldownFiltering filters versions from NuGet registration pages
-// that are too recently published.
-func (h *NuGetHandler) applyCooldownFiltering(body []byte) ([]byte, error) {
-	if h.proxy.Cooldown == nil || !h.proxy.Cooldown.Enabled() {
-		return body, nil
-	}
-
-	var registration map[string]any
-	if err := json.Unmarshal(body, &registration); err != nil {
-		return nil, err
-	}
-
-	pages, ok := registration["items"].([]any)
-	if !ok {
-		return body, nil
-	}
-
-	for _, page := range pages {
-		pageMap, ok := page.(map[string]any)
-		if !ok {
-			continue
-		}
-
-		items, ok := pageMap["items"].([]any)
-		if !ok {
-			continue
-		}
-
-		filtered := items[:0]
-		for _, item := range items {
-			itemMap, ok := item.(map[string]any)
-			if !ok {
-				continue
-			}
-
-			catalogEntry, ok := itemMap["catalogEntry"].(map[string]any)
-			if !ok {
-				filtered = append(filtered, item)
-				continue
-			}
-
-			version, _ := catalogEntry["version"].(string)
-			id, _ := catalogEntry["id"].(string)
-			publishedStr, _ := catalogEntry["published"].(string)
-
-			if publishedStr == "" {
-				filtered = append(filtered, item)
-				continue
-			}
-
-			publishedAt, err := time.Parse(time.RFC3339, publishedStr)
-			if err != nil {
-				// NuGet uses a slightly non-standard format, try parsing with fractional seconds
-				publishedAt, err = time.Parse("2006-01-02T15:04:05.999-07:00", publishedStr)
-				if err != nil {
-					filtered = append(filtered, item)
-					continue
-				}
-			}
-
-			packagePURL := canonicalPackagePURL("nuget", strings.ToLower(id))
-
-			if !h.proxy.Cooldown.IsAllowed("nuget", packagePURL, publishedAt) {
-				h.proxy.Logger.Info("cooldown: filtering nuget version",
-					"package", id, "version", version,
-					"published", publishedStr)
-				continue
-			}
-
-			filtered = append(filtered, item)
-		}
-
-		pageMap["items"] = filtered
-		pageMap["count"] = len(filtered)
-	}
-
-	return json.Marshal(registration)
 }
 
 // handleDownload serves a package file, fetching and caching from upstream if needed.
@@ -299,6 +162,18 @@ func (h *NuGetHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	if h.cooldownEnabled() {
+		allowed, err := h.nugetDownloadAllowed(r.Context(), id, version)
+		if err != nil {
+			h.nugetMetadataError(w, err)
+			return
+		}
+		if !allowed {
+			JSONError(w, http.StatusNotFound, "version not found")
+			return
+		}
+	}
+
 	// Only cache .nupkg files
 	if !strings.HasSuffix(filename, ".nupkg") {
 		h.proxyUpstream(w, r)
@@ -363,7 +238,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_cooldown.go

@@ -0,0 +1,374 @@
+package handler
+
+import (
+	"bytes"
+	"compress/gzip"
+	"context"
+	"crypto/sha256"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"slices"
+	"strings"
+	"time"
+)
+
+var nugetRegistrationPrefixes = []string{
+	"/v3/registration5-semver1/",
+	"/v3/registration5-gz-semver1/",
+	"/v3/registration5-gz-semver2/",
+}
+
+var nugetArtifactPrefixes = append([]string{"/v3-flatcontainer/"}, nugetRegistrationPrefixes...)
+
+const nugetRegistrationPath = "/v3/registration5-gz-semver2/"
+
+func (h *NuGetHandler) cooldownEnabled() bool {
+	return h.proxy.Cooldown != nil && h.proxy.Cooldown.Enabled()
+}
+
+func (h *NuGetHandler) nugetCooldownApplies(id string) bool {
+	return h.cooldownEnabled() && h.proxy.Cooldown.For("nuget", canonicalPackagePURL("nuget", strings.ToLower(id))) > 0
+}
+
+// Cache upstream documents, not filtered results, so policy changes and elapsed
+// time take effect even while metadata is fresh. Include the upstream in the key.
+func (h *NuGetHandler) nugetMetadata(ctx context.Context, path string) (map[string]any, error) {
+	target := h.upstreamURL + path
+	key := fmt.Sprintf("_cooldown/%x", sha256.Sum256([]byte(target)))
+	var document map[string]any
+	validate := func(body []byte) error {
+		var err error
+		document, err = h.decodeNuGetMetadata(body)
+		return err
+	}
+	_, _, _, err := h.proxy.fetchOrCacheMetadata(ctx, "nuget", key, target, "", validate)
+	if err != nil {
+		return nil, err
+	}
+	return document, nil
+}
+
+func (h *NuGetHandler) decodeNuGetMetadata(body []byte) (map[string]any, error) {
+	// Normally the HTTP transport decodes gzip. Also support compressed cached
+	// bytes and clients with transparent decompression disabled, with the same
+	// metadata limit applied to the decompressed document.
+	if bytes.HasPrefix(body, []byte{0x1f, 0x8b}) {
+		reader, err := gzip.NewReader(bytes.NewReader(body))
+		if err != nil {
+			return nil, err
+		}
+		defer func() { _ = reader.Close() }()
+		body, err = h.proxy.ReadMetadata(reader)
+		if err != nil {
+			return nil, err
+		}
+	}
+	var document map[string]any
+	if err := json.Unmarshal(body, &document); err != nil {
+		return nil, fmt.Errorf("parsing NuGet metadata: %w", err)
+	}
+	if document == nil {
+		return nil, fmt.Errorf("empty NuGet metadata")
+	}
+	return document, nil
+}
+
+// Prefer semver2, but a configured source may advertise only an older hive.
+// Retry only advertised aliases on 404; transport/validation errors must not
+// silently switch to a hive with less complete metadata. Keep requests on the
+// configured upstream, consistent with the service-index route rewriting.
+func (h *NuGetHandler) nugetRegistrationMetadata(ctx context.Context, suffix string) (map[string]any, string, error) {
+	path := nugetRegistrationPath + suffix
+	document, err := h.nugetMetadata(ctx, path)
+	if !errors.Is(err, ErrUpstreamNotFound) {
+		return document, path, err
+	}
+	index, indexErr := h.nugetMetadata(ctx, "/v3/index.json")
+	if indexErr != nil {
+		return nil, path, indexErr
+	}
+	resources, _ := index["resources"].([]any)
+	seen := map[string]bool{nugetRegistrationPath: true}
+	for _, resource := range resources {
+		entry, _ := resource.(map[string]any)
+		service, _ := entry["@type"].(string)
+		id, _ := entry["@id"].(string)
+		if id == "" || !strings.HasPrefix(service, "RegistrationsBaseUrl") {
+			continue
+		}
+		prefix := strings.TrimPrefix(h.rewriteNuGetURL(id, service), h.proxyURL+"/nuget")
+		if !slices.Contains(nugetRegistrationPrefixes, prefix) || seen[prefix] {
+			continue
+		}
+		seen[prefix] = true
+		path = prefix + suffix
+		document, err = h.nugetMetadata(ctx, path)
+		if !errors.Is(err, ErrUpstreamNotFound) {
+			return document, path, err
+		}
+	}
+	return nil, path, err
+}
+
+func (h *NuGetHandler) nugetMetadataError(w http.ResponseWriter, err error) {
+	if errors.Is(err, ErrUpstreamNotFound) {
+		JSONError(w, http.StatusNotFound, "package metadata not found")
+		return
+	}
+	h.proxy.Logger.Warn("failed to process NuGet metadata", "error", err)
+	JSONError(w, http.StatusBadGateway, "failed to process package metadata")
+}
+
+func (h *NuGetHandler) handleVersionList(w http.ResponseWriter, r *http.Request) {
+	if !h.cooldownEnabled() {
+		h.proxyUpstream(w, r)
+		return
+	}
+	id := strings.ToLower(r.PathValue("id"))
+	document, err := h.nugetMetadata(r.Context(), "/v3-flatcontainer/"+url.PathEscape(id)+"/index.json")
+	if err != nil {
+		h.nugetMetadataError(w, err)
+		return
+	}
+	blocked := make(map[string]bool)
+	// A globally enabled policy may still exempt this package or ecosystem.
+	// Keep metadata caching, but do not require publication data in that case.
+	if h.nugetCooldownApplies(id) {
+		registration, registrationPath, err := h.nugetRegistrationMetadata(r.Context(), url.PathEscape(id)+"/index.json")
+		if err == nil {
+			err = h.expandNuGetPages(r.Context(), registration, registrationPath)
+		}
+		if err != nil {
+			h.nugetMetadataError(w, err)
+			return
+		}
+		h.collectNuGetBlockedVersions(registration, id, blocked)
+	}
+	versions, ok := document["versions"].([]any)
+	if !ok {
+		h.nugetMetadataError(w, fmt.Errorf("missing NuGet versions"))
+		return
+	}
+	filtered := make([]any, 0, len(versions))
+	for _, value := range versions {
+		version, ok := value.(string)
+		if !ok {
+			h.nugetMetadataError(w, fmt.Errorf("invalid NuGet version"))
+			return
+		}
+		if !blocked[nugetVersionKey(version)] {
+			filtered = append(filtered, value)
+		}
+	}
+	document["versions"] = filtered
+	w.Header().Set(headerContentType, contentTypeJSON)
+	_ = json.NewEncoder(w).Encode(document)
+}
+
+func nugetVersionKey(version string) string {
+	version, _, _ = strings.Cut(version, "+")
+	return strings.ToLower(version)
+}
+
+func (h *NuGetHandler) nugetDownloadAllowed(ctx context.Context, id, version string) (bool, error) {
+	if !h.nugetCooldownApplies(id) {
+		return true, nil
+	}
+	suffix := url.PathEscape(strings.ToLower(id)) + "/" + url.PathEscape(nugetVersionKey(version)) + ".json"
+	leaf, _, err := h.nugetRegistrationMetadata(ctx, suffix)
+	if err != nil {
+		return false, err
+	}
+	return h.nugetLeafAllowed(leaf, id), nil
+}
+
+// A standalone leaf has published at its root; leaves embedded in pages carry
+// it in catalogEntry. Missing/invalid timestamps retain the existing permissive
+// behavior, but fetch and JSON errors must not bypass the policy.
+func (h *NuGetHandler) nugetLeafAllowed(leaf map[string]any, id string) bool {
+	if !h.cooldownEnabled() {
+		return true
+	}
+	entry := nugetCatalogEntry(leaf)
+	if id == "" {
+		id, _ = entry["id"].(string)
+	}
+	published, _ := entry["published"].(string)
+	when, err := time.Parse(time.RFC3339, published)
+	if err != nil {
+		return true
+	}
+	return h.proxy.Cooldown.IsAllowed("nuget", canonicalPackagePURL("nuget", strings.ToLower(id)), when)
+}
+
+func nugetCatalogEntry(leaf map[string]any) map[string]any {
+	if entry, ok := leaf["catalogEntry"].(map[string]any); ok {
+		return entry
+	}
+	return leaf
+}
+
+func (h *NuGetHandler) collectNuGetBlockedVersions(document map[string]any, id string, blocked map[string]bool) {
+	entry := nugetCatalogEntry(document)
+	if version, ok := entry["version"].(string); ok && !h.nugetLeafAllowed(document, id) {
+		blocked[nugetVersionKey(version)] = true
+	}
+	items, _ := document["items"].([]any)
+	for _, item := range items {
+		if child, ok := item.(map[string]any); ok {
+			h.collectNuGetBlockedVersions(child, id, blocked)
+		}
+	}
+}
+
+func (h *NuGetHandler) handleRegistration(w http.ResponseWriter, r *http.Request) {
+	if !h.cooldownEnabled() {
+		h.proxyUpstream(w, r)
+		return
+	}
+	id := nugetRegistrationID(r.URL.Path)
+	applyCooldown := h.nugetCooldownApplies(id)
+	document, err := h.nugetMetadata(r.Context(), r.URL.Path)
+	if err == nil && applyCooldown {
+		err = h.expandNuGetPages(r.Context(), document, r.URL.Path)
+	}
+	if err != nil {
+		h.nugetMetadataError(w, err)
+		return
+	}
+	_, hasItems := document["items"]
+	if applyCooldown && !h.filterNuGetRegistration(document, id) && !hasItems {
+		JSONError(w, http.StatusNotFound, "version not found")
+		return
+	}
+	h.rewriteNuGetRegistrationLinks(document)
+	w.Header().Set(headerContentType, contentTypeJSON)
+	_ = json.NewEncoder(w).Encode(document)
+}
+
+func nugetRegistrationID(path string) string {
+	for _, prefix := range nugetRegistrationPrefixes {
+		if rest, ok := strings.CutPrefix(path, prefix); ok {
+			id, _, _ := strings.Cut(rest, "/")
+			return id
+		}
+	}
+	return ""
+}
+
+// Only expand index pages, never recursively follow arbitrary upstream links.
+// Pin requests to this configured upstream and the current package's page path.
+func (h *NuGetHandler) expandNuGetPages(ctx context.Context, document map[string]any, path string) error {
+	if !strings.HasSuffix(path, "/index.json") {
+		return nil
+	}
+	items, ok := document["items"].([]any)
+	if !ok {
+		return fmt.Errorf("missing registration pages")
+	}
+	base, err := url.Parse(h.upstreamURL + path)
+	if err != nil {
+		return err
+	}
+	pagePrefix := strings.TrimSuffix(base.Path, "index.json") + "page/"
+	for _, item := range items {
+		page, ok := item.(map[string]any)
+		if !ok {
+			return fmt.Errorf("invalid registration page")
+		}
+		if _, ok := page["items"].([]any); ok {
+			continue
+		}
+		link, _ := page["@id"].(string)
+		target, err := base.Parse(link)
+		if err != nil || target.Scheme != base.Scheme || target.Host != base.Host ||
+			!strings.HasPrefix(target.Path, pagePrefix) || containsPathTraversal(target.Path) || target.RawQuery != "" || target.Fragment != "" {
+			return fmt.Errorf("invalid registration page URL: %q", link)
+		}
+		upstream, _ := url.Parse(h.upstreamURL)
+		pageDocument, err := h.nugetMetadata(ctx, strings.TrimPrefix(target.Path, upstream.Path))
+		if err != nil {
+			return err
+		}
+		leaves, ok := pageDocument["items"].([]any)
+		if !ok {
+			return fmt.Errorf("missing registration leaves")
+		}
+		page["items"] = leaves
+	}
+	return nil
+}
+
+func (h *NuGetHandler) filterNuGetRegistration(document map[string]any, id string) bool {
+	items, ok := document["items"].([]any)
+	if !ok {
+		return h.nugetLeafAllowed(document, id)
+	}
+	filtered := make([]any, 0, len(items))
+	for _, item := range items {
+		child, ok := item.(map[string]any)
+		if ok && h.filterNuGetRegistration(child, id) {
+			filtered = append(filtered, child)
+		}
+	}
+	document["items"] = filtered
+	document["count"] = len(filtered)
+	// Page bounds describe the retained leaves, not versions hidden by cooldown.
+	if _, isPage := document["lower"]; isPage && len(filtered) > 0 {
+		first, _ := filtered[0].(map[string]any)
+		last, _ := filtered[len(filtered)-1].(map[string]any)
+		document["lower"] = nugetCatalogEntry(first)["version"]
+		document["upper"] = nugetCatalogEntry(last)["version"]
+	}
+	return len(filtered) > 0
+}
+
+func (h *NuGetHandler) rewriteNuGetRegistrationLinks(value any) {
+	switch node := value.(type) {
+	case map[string]any:
+		for key, child := range node {
+			if link, ok := child.(string); ok {
+				switch key {
+				case "@id", "parent", "registration", "packageContent":
+					node[key] = h.nugetProxyLink(link)
+				}
+			} else {
+				h.rewriteNuGetRegistrationLinks(child)
+			}
+		}
+	case []any:
+		for _, child := range node {
+			h.rewriteNuGetRegistrationLinks(child)
+		}
+	}
+}
+
+func (h *NuGetHandler) nugetProxyLink(link string) string {
+	u, err := url.Parse(link)
+	if err != nil {
+		return link
+	}
+	upstream, err := url.Parse(h.upstreamURL)
+	if err != nil {
+		return link
+	}
+	path := u.Path
+	if u.Host == upstream.Host {
+		path = strings.TrimPrefix(path, upstream.Path)
+	}
+	for _, prefix := range nugetArtifactPrefixes {
+		if strings.HasPrefix(path, prefix) {
+			proxy, err := url.Parse(h.proxyURL + "/nuget" + path)
+			if err != nil {
+				return link
+			}
+			proxy.RawQuery = u.RawQuery
+			proxy.Fragment = u.Fragment
+			return proxy.String()
+		}
+	}
+	return link
+}

internal/handler/nuget_cooldown_test.go

@@ -0,0 +1,501 @@
+package handler
+
+import (
+	"bytes"
+	"compress/gzip"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/git-pkgs/cooldown"
+	"github.com/git-pkgs/registries/fetch"
+)
+
+func TestNuGetCooldownRoutes(t *testing.T) {
+	for _, disableCompression := range []bool{false, true} {
+		t.Run(map[bool]string{false: "transport gzip", true: "explicit gzip"}[disableCompression], func(t *testing.T) {
+			proxy, db, store, fetcher := setupTestProxy(t)
+			proxy.Cooldown = &cooldown.Config{Default: "14d"}
+			proxy.CacheMetadata = true
+			proxy.MetadataTTL = time.Hour
+			seedPackage(t, db, store, "nuget", "testpkg", "2.0.0", "testpkg.2.0.0.nupkg", "cached package")
+			seedPackage(t, db, store, "nuget", "testpkg", "1.0.0", "testpkg.1.0.0.nupkg", "old package")
+			metadataRequests := 0
+			upstream := newNuGetCooldownUpstream(t, &metadataRequests)
+			defer upstream.Close()
+			transport := http.DefaultTransport.(*http.Transport).Clone()
+			transport.DisableCompression = disableCompression
+			defer transport.CloseIdleConnections()
+			proxy.HTTPClient = &http.Client{Transport: transport}
+			h := NewNuGetHandlerWithUpstreams(proxy, "http://proxy.test", upstream.URL, upstream.URL)
+			routes := http.StripPrefix("/nuget", h.Routes())
+			get := func(path string, status int) *httptest.ResponseRecorder {
+				t.Helper()
+				return nugetGet(t, routes, path, status)
+			}
+			list := get("/nuget/v3-flatcontainer/testpkg/index.json", http.StatusOK)
+			if got := strings.TrimSpace(list.Body.String()); got != `{"versions":["1.0.0"]}` {
+				t.Fatalf("filtered list = %s", got)
+			}
+			index := get("/nuget"+nugetRegistrationPath+"testpkg/index.json", http.StatusOK)
+			if strings.Contains(index.Body.String(), `"version":"2.0.0"`) || strings.Contains(index.Body.String(), upstream.URL) {
+				t.Fatalf("registration leaks blocked leaf or upstream link: %s", index.Body.String())
+			}
+			if index.Header().Get("Content-Encoding") != "" || !json.Valid(index.Body.Bytes()) {
+				t.Fatal("registration must be decoded JSON")
+			}
+			var doc struct {
+				Items []struct {
+					ID           string `json:"@id"`
+					Count        int
+					Lower, Upper string
+					Items        []struct {
+						ID             string `json:"@id"`
+						PackageContent string
+					}
+				}
+			}
+			if err := json.Unmarshal(index.Body.Bytes(), &doc); err != nil {
+				t.Fatal(err)
+			}
+			if len(doc.Items) != 1 || doc.Items[0].Count != 1 || doc.Items[0].Upper != "1.0.0" {
+				t.Fatalf("incorrect page: %+v", doc)
+			}
+			get(doc.Items[0].ID, http.StatusOK)
+			get(doc.Items[0].Items[0].ID, http.StatusOK)
+			get(doc.Items[0].Items[0].PackageContent, http.StatusOK)
+			get("/nuget"+nugetRegistrationPath+"testpkg/2.0.0.json", http.StatusNotFound)
+			get("/nuget/v3-flatcontainer/TestPkg/2.0.0/testpkg.2.0.0.nupkg", http.StatusNotFound)
+			get("/nuget/v3-flatcontainer/testpkg/2.0.0/testpkg.nuspec", http.StatusNotFound)
+			if fetcher.fetchCalled {
+				t.Fatal("blocked or cached downloads must not fetch artifacts")
+			}
+
+			// Reevaluate fresh, unfiltered metadata under a changed package policy.
+			requestsBefore := metadataRequests
+			proxy.Cooldown = &cooldown.Config{Default: "14d", Packages: map[string]string{"pkg:nuget/testpkg": "1d"}}
+			list = get("/nuget/v3-flatcontainer/testpkg/index.json", http.StatusOK)
+			if !strings.Contains(list.Body.String(), "2.0.0") {
+				t.Fatal("fresh metadata retained the previous policy")
+			}
+			get("/nuget/v3-flatcontainer/testpkg/2.0.0/testpkg.2.0.0.nupkg", http.StatusOK)
+			if metadataRequests != requestsBefore {
+				t.Fatal("fresh metadata should be reused")
+			}
+		})
+	}
+}
+
+func nugetGet(t *testing.T, routes http.Handler, path string, status int) *httptest.ResponseRecorder {
+	t.Helper()
+	w := httptest.NewRecorder()
+	routes.ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+	if w.Code != status {
+		t.Fatalf("GET %s: status %d, want %d: %s", path, w.Code, status, w.Body.String())
+	}
+	return w
+}
+
+func TestNuGetMetadataWithoutEffectiveCooldown(t *testing.T) {
+	for _, tt := range []struct {
+		name   string
+		policy *cooldown.Config
+	}{
+		{"package exemption", &cooldown.Config{Default: "14d", Packages: map[string]string{"pkg:nuget/testpkg": "0"}}},
+		{"ecosystem exemption", &cooldown.Config{Default: "14d", Ecosystems: map[string]string{"nuget": "0"}}},
+		{"other ecosystem only", &cooldown.Config{Ecosystems: map[string]string{"npm": "14d"}}},
+		{"other package only", &cooldown.Config{Packages: map[string]string{"pkg:nuget/other": "14d"}}},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			const body = `{"versions":["1.0.0","2.0.0"]}`
+			const pagePath = nugetRegistrationPath + "testpkg/page/1.0.0/2.0.0.json"
+			upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				switch r.URL.Path {
+				case "/v3-flatcontainer/testpkg/index.json":
+					_, _ = io.WriteString(w, body)
+				case nugetRegistrationPath + "testpkg/index.json":
+					_, _ = io.WriteString(w, `{"count":1,"items":[{"@id":"`+pagePath+`","count":2,"lower":"1.0.0","upper":"2.0.0"}]}`)
+				default:
+					t.Errorf("unnecessary registration request: %s", r.URL.Path)
+					http.Error(w, "registration unavailable", http.StatusServiceUnavailable)
+				}
+			}))
+			defer upstream.Close()
+			p := nugetTestProxy()
+			p.Cooldown = tt.policy
+			h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL, upstream.URL)
+			w := nugetGet(t, h.Routes(), "/v3-flatcontainer/TestPkg/index.json", http.StatusOK)
+			if got := strings.TrimSpace(w.Body.String()); got != body {
+				t.Fatalf("version list = %s, want %s", got, body)
+			}
+			w = nugetGet(t, h.Routes(), nugetRegistrationPath+"testpkg/index.json", http.StatusOK)
+			if !strings.Contains(w.Body.String(), `"@id":"http://proxy.test/nuget`+pagePath+`"`) {
+				t.Fatalf("registration page link was not rewritten: %s", w.Body.String())
+			}
+		})
+	}
+}
+
+func TestNuGetCooldownColdDownload(t *testing.T) {
+	for _, tt := range []struct {
+		name, published string
+		policy          *cooldown.Config
+		want            int
+	}{
+		{"recent", time.Now().Add(-time.Hour).Format(time.RFC3339), &cooldown.Config{Default: "14d"}, http.StatusNotFound},
+		{"missing timestamp", "", &cooldown.Config{Default: "14d"}, http.StatusOK},
+		{"package exemption", time.Now().Add(-time.Hour).Format(time.RFC3339), &cooldown.Config{Default: "14d", Packages: map[string]string{"pkg:nuget/testpkg": "0"}}, http.StatusOK},
+		{"ecosystem override", time.Now().Add(-time.Hour).Format(time.RFC3339), &cooldown.Config{Ecosystems: map[string]string{"nuget": "14d"}}, http.StatusNotFound},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			p, _, _, fetcher := setupTestProxy(t)
+			p.Cooldown = tt.policy
+			fetcher.artifact = &fetch.Artifact{Body: io.NopCloser(strings.NewReader("package")), ContentType: "application/octet-stream"}
+			upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				_ = json.NewEncoder(w).Encode(map[string]string{"published": tt.published})
+			}))
+			defer upstream.Close()
+			h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL, upstream.URL)
+			nugetGet(t, h.Routes(), "/v3-flatcontainer/testpkg/2.0.0/testpkg.2.0.0.nupkg", tt.want)
+			if fetcher.fetchCalled != (tt.want == http.StatusOK) {
+				t.Errorf("artifact fetch called = %v", fetcher.fetchCalled)
+			}
+		})
+	}
+}
+
+func TestNuGetRegistrationServiceAliases(t *testing.T) {
+	h := NewNuGetHandler(nugetTestProxy(), "http://proxy.test")
+	for _, tt := range []struct{ service, path string }{
+		{"RegistrationsBaseUrl", "/v3/registration5-semver1/"},
+		{"RegistrationsBaseUrl/3.0.0-beta", "/v3/registration5-semver1/"},
+		{"RegistrationsBaseUrl/3.0.0-rc", "/v3/registration5-semver1/"},
+		{"RegistrationsBaseUrl/3.4.0", "/v3/registration5-gz-semver1/"},
+		{"RegistrationsBaseUrl/3.6.0", nugetRegistrationPath},
+		{"RegistrationsBaseUrl/Versioned", nugetRegistrationPath},
+	} {
+		t.Run(tt.service, func(t *testing.T) {
+			upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.URL.Path != tt.path+"testpkg/index.json" {
+					t.Errorf("wrong hive: %s", r.URL.Path)
+				}
+				_, _ = io.WriteString(w, `{"count":0,"items":[]}`)
+			}))
+			defer upstream.Close()
+			h.upstreamURL = upstream.URL
+			h.proxy.Cooldown = &cooldown.Config{Default: "14d"}
+			body := []byte(`{"resources":[{"@id":"` + upstream.URL + tt.path + `","@type":"` + tt.service + `"}]}`)
+			out, err := h.rewriteServiceIndex(body)
+			if err != nil {
+				t.Fatal(err)
+			}
+			var doc struct {
+				Resources []struct {
+					ID string `json:"@id"`
+				}
+			}
+			if err := json.Unmarshal(out, &doc); err != nil {
+				t.Fatal(err)
+			}
+			w := httptest.NewRecorder()
+			http.StripPrefix("/nuget", h.Routes()).ServeHTTP(w, httptest.NewRequest(http.MethodGet, doc.Resources[0].ID+"testpkg/index.json", nil))
+			if w.Code != http.StatusOK {
+				t.Fatalf("alias route status = %d: %s", w.Code, w.Body.String())
+			}
+		})
+	}
+}
+
+func TestNuGetCooldownMetadataErrors(t *testing.T) {
+	for _, tt := range []struct {
+		name, body string
+		status     int
+	}{
+		{"upstream failure", "unavailable", http.StatusServiceUnavailable},
+		{"invalid JSON", "broken JSON", http.StatusOK},
+		{"null", "null", http.StatusOK},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(tt.status)
+				_, _ = io.WriteString(w, tt.body)
+			}))
+			defer upstream.Close()
+			p := nugetTestProxy()
+			p.Cooldown = &cooldown.Config{Default: "14d"}
+			h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL, upstream.URL)
+			for _, path := range []string{"/v3-flatcontainer/testpkg/index.json", "/v3-flatcontainer/testpkg/2.0.0/testpkg.2.0.0.nupkg", nugetRegistrationPath + "testpkg/index.json"} {
+				w := httptest.NewRecorder()
+				h.Routes().ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+				if w.Code != http.StatusBadGateway {
+					t.Errorf("GET %s: %d, want 502", path, w.Code)
+				}
+			}
+		})
+	}
+}
+
+func TestNuGetCooldownRejectsUnsafePageLinks(t *testing.T) {
+	for _, link := range []string{"https://other.example/page.json", "/v3/registration5-gz-semver2/other/page/1/2.json", "page/../index.json", "index.json"} {
+		t.Run(link, func(t *testing.T) {
+			requests := 0
+			upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				requests++
+				_ = json.NewEncoder(w).Encode(map[string]any{"items": []any{map[string]any{"@id": link}}})
+			}))
+			defer upstream.Close()
+			p := nugetTestProxy()
+			p.Cooldown = &cooldown.Config{Default: "14d"}
+			h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL, upstream.URL)
+			nugetGet(t, h.Routes(), nugetRegistrationPath+"testpkg/index.json", http.StatusBadGateway)
+			if requests != 1 {
+				t.Fatalf("unsafe page link was followed (%d requests)", requests)
+			}
+		})
+	}
+}
+
+func TestNuGetCooldownDecompressedMetadataLimit(t *testing.T) {
+	var compressed bytes.Buffer
+	gz := gzip.NewWriter(&compressed)
+	_, _ = io.WriteString(gz, `{"padding":"`+strings.Repeat("x", 2048)+`"}`)
+	_ = gz.Close()
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Encoding", "gzip")
+		_, _ = w.Write(compressed.Bytes())
+	}))
+	defer upstream.Close()
+	p := nugetTestProxy()
+	p.Cooldown = &cooldown.Config{Default: "14d"}
+	p.MetadataMaxSize = 1024
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	transport.DisableCompression = true
+	defer transport.CloseIdleConnections()
+	p.HTTPClient = &http.Client{Transport: transport}
+	h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL, upstream.URL)
+	nugetGet(t, h.Routes(), nugetRegistrationPath+"testpkg/index.json", http.StatusBadGateway)
+}
+
+func newNuGetCooldownUpstream(t *testing.T, metadataRequests *int) *httptest.Server {
+	t.Helper()
+	var upstream *httptest.Server
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		(*metadataRequests)++
+		base := upstream.URL + nugetRegistrationPath + "testpkg/"
+		leaf := func(version string, age time.Duration) map[string]any {
+			return map[string]any{
+				"@id":            base + version + ".json",
+				"packageContent": upstream.URL + "/v3-flatcontainer/testpkg/" + version + "/testpkg." + version + ".nupkg",
+				"catalogEntry":   map[string]any{"id": "TestPkg", "version": version, "published": time.Now().Add(-age).Format(time.RFC3339)},
+			}
+		}
+		page := map[string]any{"@id": base + "page/1.0.0/2.0.0.json", "lower": "1.0.0", "upper": "2.0.0", "count": 2,
+			"parent": base + "index.json", "items": []any{leaf("1.0.0", 30*24*time.Hour), leaf("2.0.0", 2*24*time.Hour)}}
+		var body any
+		switch r.URL.Path {
+		case "/v3-flatcontainer/testpkg/index.json":
+			body = map[string]any{"versions": []string{"1.0.0", "2.0.0"}}
+		case nugetRegistrationPath + "testpkg/index.json":
+			// This index deliberately does not inline its leaves.
+			body = map[string]any{"count": 1, "items": []any{map[string]any{
+				"@id": page["@id"], "count": 2, "lower": "1.0.0", "upper": "2.0.0",
+			}}}
+		case nugetRegistrationPath + "testpkg/page/1.0.0/2.0.0.json":
+			body = page
+		case nugetRegistrationPath + "testpkg/1.0.0.json":
+			body = map[string]any{"published": time.Now().Add(-30 * 24 * time.Hour).Format(time.RFC3339)}
+		case nugetRegistrationPath + "testpkg/2.0.0.json":
+			body = map[string]any{"published": time.Now().Add(-2 * 24 * time.Hour).Format(time.RFC3339)}
+		default:
+			t.Errorf("unexpected metadata request: %s", r.URL.Path)
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Content-Encoding", "gzip")
+		gz := gzip.NewWriter(w)
+		_ = json.NewEncoder(gz).Encode(body)
+		_ = gz.Close()
+	}))
+
+	return upstream
+}
+
+func TestNuGetCooldownLegacyRegistration(t *testing.T) {
+	for _, service := range []string{"RegistrationsBaseUrl", "RegistrationsBaseUrl/3.0.0-beta", "RegistrationsBaseUrl/3.0.0-rc", "RegistrationsBaseUrl/3.4.0"} {
+		t.Run(service, func(t *testing.T) {
+			prefix := "/v3/registration5-semver1/"
+			if service == "RegistrationsBaseUrl/3.4.0" {
+				prefix = "/v3/registration5-gz-semver1/"
+			}
+			upstream := newNuGetLegacyUpstream(t, service, prefix)
+			defer upstream.Close()
+			p, db, store, fetcher := setupTestProxy(t)
+			p.Cooldown = &cooldown.Config{Default: "14d"}
+			seedPackage(t, db, store, "nuget", "testpkg", "1.0.0", "testpkg.1.0.0.nupkg", "cached old package")
+			seedPackage(t, db, store, "nuget", "testpkg", "2.0.0", "testpkg.2.0.0.nupkg", "cached recent package")
+			h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL+"/feed", upstream.URL)
+			list := nugetGet(t, h.Routes(), "/v3-flatcontainer/testpkg/index.json", http.StatusOK)
+			if strings.TrimSpace(list.Body.String()) != `{"versions":["1.0.0"]}` {
+				t.Fatalf("incorrect version list: %s", list.Body.String())
+			}
+			nugetGet(t, h.Routes(), "/v3-flatcontainer/testpkg/1.0.0/testpkg.1.0.0.nupkg", http.StatusOK)
+			nugetGet(t, h.Routes(), "/v3-flatcontainer/testpkg/2.0.0/testpkg.2.0.0.nupkg", http.StatusNotFound)
+			if fetcher.fetchCalled {
+				t.Fatal("cached or blocked package must not be fetched")
+			}
+		})
+	}
+}
+
+func newNuGetLegacyUpstream(t *testing.T, service, prefix string) *httptest.Server {
+	t.Helper()
+	var upstream *httptest.Server
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		path := strings.TrimPrefix(r.URL.Path, "/feed")
+		base := upstream.URL + "/feed" + prefix + "testpkg/"
+		published := func(age time.Duration) string { return time.Now().Add(-age).Format(time.RFC3339) }
+		var body any
+		switch path {
+		case "/v3/index.json":
+			body = map[string]any{"resources": []any{map[string]string{"@id": upstream.URL + "/feed" + prefix, "@type": service}}}
+		case "/v3-flatcontainer/testpkg/index.json":
+			body = map[string]any{"versions": []string{"1.0.0", "2.0.0"}}
+		case prefix + "testpkg/index.json":
+			body = map[string]any{"items": []any{map[string]any{"@id": base + "page/1.0.0/2.0.0.json"}}}
+		case prefix + "testpkg/page/1.0.0/2.0.0.json":
+			body = map[string]any{"items": []any{
+				map[string]any{"catalogEntry": map[string]string{"id": "testpkg", "version": "1.0.0", "published": published(30 * 24 * time.Hour)}},
+				map[string]any{"catalogEntry": map[string]string{"id": "testpkg", "version": "2.0.0", "published": published(time.Hour)}},
+			}}
+		case prefix + "testpkg/1.0.0.json":
+			body = map[string]string{"published": published(30 * 24 * time.Hour)}
+		case prefix + "testpkg/2.0.0.json":
+			body = map[string]string{"published": published(time.Hour)}
+		default:
+			if !strings.HasPrefix(path, nugetRegistrationPath) {
+				t.Errorf("unexpected request: %s", r.URL.Path)
+			}
+			http.NotFound(w, r)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(body)
+	}))
+	return upstream
+}
+
+func TestNuGetRegistrationDoesNotFallbackOnFailure(t *testing.T) {
+	for _, status := range []int{http.StatusServiceUnavailable, http.StatusUnauthorized, http.StatusOK} {
+		t.Run(http.StatusText(status), func(t *testing.T) {
+			upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.URL.Path != nugetRegistrationPath+"testpkg/index.json" {
+					t.Errorf("must not switch registration hive on failure: %s", r.URL.Path)
+				}
+				w.WriteHeader(status)
+				_, _ = io.WriteString(w, "invalid metadata")
+			}))
+			defer upstream.Close()
+			h := NewNuGetHandlerWithUpstreams(nugetTestProxy(), "http://proxy.test", upstream.URL, upstream.URL)
+			if _, _, err := h.nugetRegistrationMetadata(t.Context(), "testpkg/index.json"); err == nil {
+				t.Fatal("expected metadata error")
+			}
+		})
+	}
+}
+
+func TestNuGetMetadataPreservesValidCache(t *testing.T) {
+	for _, invalid := range []string{"broken JSON", "null", "[]", string([]byte{0x1f, 0x8b, 0x00})} {
+		t.Run(invalid, func(t *testing.T) {
+			const good = `{"published":"2020-01-01T00:00:00Z"}`
+			var response atomic.Value
+			response.Store(good)
+			var requests atomic.Int32
+			upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if requests.Add(1) > 1 && r.Header.Get("If-None-Match") != `"good"` {
+					t.Errorf("cached ETag was replaced: %s", r.Header.Get("If-None-Match"))
+				}
+				body := response.Load().(string)
+				etag := `"good"`
+				if body == invalid {
+					etag = `"bad"`
+				}
+				w.Header().Set("ETag", etag)
+				_, _ = io.WriteString(w, body)
+			}))
+			defer upstream.Close()
+			p, _, _, _ := setupTestProxy(t)
+			p.CacheMetadata = true
+			h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL, upstream.URL)
+			check := func(want string) {
+				t.Helper()
+				doc, err := h.nugetMetadata(t.Context(), nugetRegistrationPath+"testpkg/1.0.0.json")
+				if err != nil || doc["published"] != want {
+					t.Fatalf("metadata = %v, err = %v, want publication %s", doc, err, want)
+				}
+			}
+			check("2020-01-01T00:00:00Z")
+			response.Store(invalid)
+			check("2020-01-01T00:00:00Z") // Bad 200 must fall back without overwriting.
+			p.MetadataTTL = time.Hour
+			check("2020-01-01T00:00:00Z") // The on-disk cache must still be usable.
+			if requests.Load() != 2 {
+				t.Fatalf("requests = %d, want 2", requests.Load())
+			}
+			p.MetadataTTL = 0
+			response.Store(`{"published":"2021-01-01T00:00:00Z"}`)
+			check("2021-01-01T00:00:00Z") // A later valid response replaces the cache.
+		})
+	}
+}
+
+func TestNuGetMetadataInvalidResponseNotCached(t *testing.T) {
+	var requests atomic.Int32
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if requests.Add(1) == 1 {
+			_, _ = io.WriteString(w, "invalid JSON")
+			return
+		}
+		_, _ = io.WriteString(w, `{"published":"2020-01-01T00:00:00Z"}`)
+	}))
+	defer upstream.Close()
+	p, _, _, _ := setupTestProxy(t)
+	p.CacheMetadata = true
+	p.MetadataTTL = time.Hour
+	h := NewNuGetHandlerWithUpstreams(p, "http://proxy.test", upstream.URL, upstream.URL)
+	path := nugetRegistrationPath + "testpkg/1.0.0.json"
+	if _, err := h.nugetMetadata(t.Context(), path); err == nil {
+		t.Fatal("invalid response without a usable cache must fail")
+	}
+	if _, err := h.nugetMetadata(t.Context(), path); err != nil {
+		t.Fatalf("invalid response was cached: %v", err)
+	}
+	if requests.Load() != 2 {
+		t.Fatalf("requests = %d, want 2", requests.Load())
+	}
+}
+
+func TestNuGetRegistrationDoesNotGuessUnadvertisedAliases(t *testing.T) {
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case nugetRegistrationPath + "testpkg/index.json":
+			http.NotFound(w, r)
+		case "/v3/index.json":
+			_, _ = io.WriteString(w, `{"resources":[{"@type":"UnrelatedService","@id":"https://other.example/"}]}`)
+		default:
+			t.Errorf("unadvertised endpoint requested: %s", r.URL.Path)
+			http.NotFound(w, r)
+		}
+	}))
+	defer upstream.Close()
+	h := NewNuGetHandlerWithUpstreams(nugetTestProxy(), "http://proxy.test", upstream.URL, upstream.URL)
+	_, _, err := h.nugetRegistrationMetadata(t.Context(), "testpkg/index.json")
+	if !errors.Is(err, ErrUpstreamNotFound) {
+		t.Fatalf("error = %v, want metadata not found", err)
+	}
+}

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)
@@ -802,11 +812,6 @@ func TestNuGetCooldownFiltering(t *testing.T) {
 		},
 	}
 
-	body, err := json.Marshal(registration)
-	if err != nil {
-		t.Fatal(err)
-	}
-
 	proxy := testProxy()
 	proxy.Cooldown = &cooldown.Config{
 		Default: "3d",
@@ -817,17 +822,11 @@ func TestNuGetCooldownFiltering(t *testing.T) {
 		proxyURL: "http://localhost:8080",
 	}
 
-	filtered, err := h.applyCooldownFiltering(body)
-	if err != nil {
-		t.Fatal(err)
+	if !h.filterNuGetRegistration(registration, "") {
+		t.Fatal("expected registration items to be retained")
 	}
 
-	var result map[string]any
-	if err := json.Unmarshal(filtered, &result); err != nil {
-		t.Fatal(err)
-	}
-
-	pages := result["items"].([]any)
+	pages := registration["items"].([]any)
 	page := pages[0].(map[string]any)
 	items := page["items"].([]any)
 
@@ -841,7 +840,7 @@ func TestNuGetCooldownFiltering(t *testing.T) {
 	}
 
 	count := page["count"]
-	if count != float64(1) {
+	if count != 1 {
 		t.Errorf("expected page count to be 1, got %v", count)
 	}
 }
@@ -867,11 +866,6 @@ func TestNuGetCooldownFilteringWithPackageOverride(t *testing.T) {
 		},
 	}
 
-	body, err := json.Marshal(registration)
-	if err != nil {
-		t.Fatal(err)
-	}
-
 	proxy := testProxy()
 	proxy.Cooldown = &cooldown.Config{
 		Default:  "3d",
@@ -883,17 +877,11 @@ func TestNuGetCooldownFilteringWithPackageOverride(t *testing.T) {
 		proxyURL: "http://localhost:8080",
 	}
 
-	filtered, err := h.applyCooldownFiltering(body)
-	if err != nil {
-		t.Fatal(err)
+	if !h.filterNuGetRegistration(registration, "") {
+		t.Fatal("expected registration items to be retained")
 	}
 
-	var result map[string]any
-	if err := json.Unmarshal(filtered, &result); err != nil {
-		t.Fatal(err)
-	}
-
-	pages := result["items"].([]any)
+	pages := registration["items"].([]any)
 	page := pages[0].(map[string]any)
 	items := page["items"].([]any)
 
@@ -920,36 +908,20 @@ func TestNuGetCooldownNoCooldownConfig(t *testing.T) {
 		},
 	}
 
-	body, err := json.Marshal(registration)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	// No cooldown - applyCooldownFiltering still works, just doesn't filter
+	// No cooldown: all registration items are retained.
 	h := &NuGetHandler{
 		proxy:    testProxy(),
 		proxyURL: "http://localhost:8080",
 	}
 
-	filtered, err := h.applyCooldownFiltering(body)
-	if err != nil {
-		t.Fatal(err)
+	if !h.filterNuGetRegistration(registration, "") {
+		t.Fatal("expected registration items to be retained")
 	}
 
-	var result map[string]any
-	if err := json.Unmarshal(filtered, &result); err != nil {
-		t.Fatal(err)
-	}
-
-	pages := result["items"].([]any)
+	pages := registration["items"].([]any)
 	page := pages[0].(map[string]any)
 	items := page["items"].([]any)
 
-	// Without cooldown config on the handler, applyCooldownFiltering
-	// is called but proxy.Cooldown is nil, so IsAllowed is never called
-	// Actually, applyCooldownFiltering always runs the filter logic -
-	// but the caller (handleRegistration) short-circuits when cooldown is disabled.
-	// The function itself should still work fine with a nil Cooldown.
 	if len(items) != 1 {
 		t.Fatalf("expected 1 item, got %d", len(items))
 	}
@@ -978,11 +950,6 @@ func TestNuGetCooldownFilteringNuGetTimestamp(t *testing.T) {
 		},
 	}
 
-	body, err := json.Marshal(registration)
-	if err != nil {
-		t.Fatal(err)
-	}
-
 	proxy := testProxy()
 	proxy.Cooldown = &cooldown.Config{
 		Default: "3d",
@@ -993,17 +960,11 @@ func TestNuGetCooldownFilteringNuGetTimestamp(t *testing.T) {
 		proxyURL: "http://localhost:8080",
 	}
 
-	filtered, err := h.applyCooldownFiltering(body)
-	if err != nil {
-		t.Fatal(err)
+	if !h.filterNuGetRegistration(registration, "") {
+		t.Fatal("expected registration items to be retained")
 	}
 
-	var result map[string]any
-	if err := json.Unmarshal(filtered, &result); err != nil {
-		t.Fatal(err)
-	}
-
-	pages := result["items"].([]any)
+	pages := registration["items"].([]any)
 	page := pages[0].(map[string]any)
 	items := page["items"].([]any)
 

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)
 }
 
@@ -311,6 +465,21 @@ func (h *PyPIHandler) shouldFilterRelease(packagePURL string, files any) bool {
 	return !publishedAt.IsZero() && !h.proxy.Cooldown.IsAllowed("pypi", packagePURL, publishedAt)
 }
 
+// versionInCooldown reports whether a version is still inside the cooldown
+// window. Filtering the simple index is not enough on its own: file URLs are
+// recorded in lockfiles and requirements pins, so pip can reach the download
+// path without ever reading the index.
+//
+// A release whose upload time cannot be determined is allowed through, matching
+// how fetchFilteredVersions treats it.
+func (h *PyPIHandler) versionInCooldown(r *http.Request, name, version string) bool {
+	if h.proxy.Cooldown == nil || !h.proxy.Cooldown.Enabled() {
+		return false
+	}
+
+	return h.fetchFilteredVersions(r, name)[version]
+}
+
 // rewriteFileEntries rewrites URLs in a list of file entries.
 func (h *PyPIHandler) rewriteFileEntries(files any) {
 	filesArr, ok := files.([]any)
@@ -386,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)
 	}
 }
 
@@ -417,6 +579,13 @@ func (h *PyPIHandler) handleDownload(w http.ResponseWriter, r *http.Request) {
 	filename := parts[len(parts)-1]
 	name, version := h.parseFilename(filename)
 
+	if name != "" && h.versionInCooldown(r, name, version) {
+		h.proxy.Logger.Info("cooldown: withholding pypi file",
+			"name", name, "version", version, "filename", filename)
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
 	if name == "" {
 		// Can't determine name/version, use hash as identifier
 		name = fmt.Sprintf("_hash_%s", hashPath(path))
@@ -426,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 {
@@ -617,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 {
@@ -632,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()
 
@@ -236,3 +498,116 @@ func TestPyPIHandler_DownloadCacheMiss(t *testing.T) {
 		t.Error("expected fetcher to be called on cache miss")
 	}
 }
+
+func TestPyPIDownloadCooldown(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) + `"}]
+	}}`
+
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", contentTypeJSON)
+		_, _ = io.WriteString(w, releases)
+	}))
+	defer upstream.Close()
+
+	tests := []struct {
+		name       string
+		filename   string
+		wantStatus int
+	}{
+		{"published before the window serves the file", "newpkg-1.0.0.tar.gz", http.StatusOK},
+		{"published inside the window is withheld", "newpkg-2.0.0.tar.gz", http.StatusNotFound},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			proxy, _, _, fetcher := setupTestProxy(t)
+			proxy.HTTPClient = upstream.Client()
+			proxy.Cooldown = &cooldown.Config{Default: "7d"}
+			fetcher.artifact = &fetch.Artifact{
+				Body:        io.NopCloser(strings.NewReader("sdist data")),
+				ContentType: "application/octet-stream",
+			}
+
+			h := &PyPIHandler{
+				proxy:       proxy,
+				upstreamURL: upstream.URL,
+				proxyURL:    "http://localhost",
+			}
+			srv := httptest.NewServer(h.Routes())
+			defer srv.Close()
+
+			resp, err := http.Get(srv.URL + "/packages/packages/ab/cd/ef0123456789/" + tt.filename)
+			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 tt.wantStatus == http.StatusNotFound && fetcher.fetchCalled {
+				t.Error("fetched a version that is still inside the cooldown window")
+			}
+		})
+	}
+}
+
+// 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/stale_cache_test.go

@@ -0,0 +1,160 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+// These tests cover an upstream re-publishing a version: the cache holds one
+// artifact and upstream now declares another digest for it.
+
+const (
+	stalePkgPURL     = "pkg:npm/pkg"
+	staleVersionPURL = "pkg:npm/pkg@1.0.0"
+	staleFilename    = "pkg-1.0.0.tgz"
+	staleStoragePath = "npm/pkg/1.0.0/pkg-1.0.0.tgz"
+	staleURL         = "https://registry.npmjs.org/pkg/-/pkg-1.0.0.tgz"
+)
+
+// seedCachedArtifact commits content the way a fetch does.
+func seedCachedArtifact(t *testing.T, proxy *Proxy, store *mockStorage, content string) {
+	t.Helper()
+	ctx := context.Background()
+	if _, _, err := store.Store(ctx, staleStoragePath, strings.NewReader(content)); err != nil {
+		t.Fatalf("seeding storage: %v", err)
+	}
+	artifact := testArtifact(content, staleVersionPURL, staleFilename, "application/gzip")
+	if err := proxy.updateCacheDB("npm", "pkg", stalePkgPURL, staleURL, staleStoragePath, artifact); err != nil {
+		t.Fatalf("seeding cache record: %v", err)
+	}
+}
+
+// cachedDigest reports the digest the cache record holds, or "" without one.
+func cachedDigest(t *testing.T, proxy *Proxy) string {
+	t.Helper()
+	record, err := proxy.DB.GetCachedArtifact(stalePkgPURL, staleVersionPURL, staleFilename)
+	if err != nil {
+		t.Fatalf("reading cache record: %v", err)
+	}
+	if record == nil {
+		return ""
+	}
+	return record.Artifact.Digest.Encoded()
+}
+
+func bytesPresent(store *mockStorage) bool {
+	r, err := store.Open(context.Background(), staleStoragePath)
+	if err != nil {
+		return false
+	}
+	_ = r.Close()
+	return true
+}
+
+func TestStaleCacheCheckHasNoSideEffects(t *testing.T) {
+	proxy, _, store, _ := setupTestProxy(t)
+	seedCachedArtifact(t, proxy, store, "old bytes")
+
+	res, err := proxy.getCachedArtifactWithUpstreamHash(context.Background(),
+		stalePkgPURL, staleVersionPURL, staleFilename, sha256Hex("new bytes"))
+	if err != nil {
+		t.Fatalf("cache check failed: %v", err)
+	}
+	if res != nil {
+		drain(res)
+		t.Fatal("stale entry was served")
+	}
+	if got := cachedDigest(t, proxy); got != sha256Hex("old bytes") {
+		t.Errorf("record digest = %q, want the stale one kept: the check must not discard", got)
+	}
+	if !bytesPresent(store) {
+		t.Error("stale bytes were deleted by the check")
+	}
+}
+
+func TestStaleCacheIsDiscardedBeforeTheFetch(t *testing.T) {
+	proxy, _, store, fetcher := setupTestProxy(t)
+	seedCachedArtifact(t, proxy, store, "old bytes")
+	boom := errors.New("upstream unavailable")
+	fetcher.fetchErr = boom
+
+	_, err := proxy.GetOrFetchArtifactFromURLWithDigest(context.Background(),
+		"npm", "pkg", "1.0.0", staleFilename, staleURL, "sha256:"+sha256Hex("new bytes"))
+	if !errors.Is(err, boom) {
+		t.Fatalf("got %v, want the fetch failure", err)
+	}
+	if got := cachedDigest(t, proxy); got != "" {
+		t.Errorf("stale record survived a failed refresh, digest = %q", got)
+	}
+	if bytesPresent(store) {
+		t.Error("stale bytes survived a failed refresh")
+	}
+}
+
+func TestStaleCacheIsReplacedByTheFetch(t *testing.T) {
+	proxy, _, store, fetcher := setupTestProxy(t)
+	seedCachedArtifact(t, proxy, store, "old bytes")
+	fetcher.artifact = artifactBody("new bytes")
+	upstream := sha256Hex("new bytes")
+
+	res, err := proxy.GetOrFetchArtifactFromURLWithDigest(context.Background(),
+		"npm", "pkg", "1.0.0", staleFilename, staleURL, "sha256:"+upstream)
+	if err != nil {
+		t.Fatalf("refresh failed: %v", err)
+	}
+	got, err := io.ReadAll(res.Reader)
+	_ = res.Reader.Close()
+	if err != nil || string(got) != "new bytes" {
+		t.Fatalf("got %q (err %v), want the refreshed bytes", got, err)
+	}
+	if !fetcher.fetchCalled {
+		t.Error("stale entry was served without a fetch")
+	}
+	if d := cachedDigest(t, proxy); d != upstream {
+		t.Errorf("record digest = %q, want %q", d, upstream)
+	}
+
+	fetcher.fetchCalled = false
+	res, err = proxy.GetOrFetchArtifactFromURLWithDigest(context.Background(),
+		"npm", "pkg", "1.0.0", staleFilename, staleURL, "sha256:"+upstream)
+	if err != nil {
+		t.Fatalf("request after refresh failed: %v", err)
+	}
+	drain(res)
+	if fetcher.fetchCalled || !res.Cached {
+		t.Errorf("request after refresh: fetched=%v cached=%v, want served from cache", fetcher.fetchCalled, res.Cached)
+	}
+}
+
+// TestLateLeaderKeepsRefreshedEntry is the race, at the point it would happen:
+// a caller whose cache check saw a stale entry reaches the coalescing step
+// after another caller's fetch replaced it. It must serve the replacement.
+func TestLateLeaderKeepsRefreshedEntry(t *testing.T) {
+	proxy, _, store, fetcher := setupTestProxy(t)
+	seedCachedArtifact(t, proxy, store, "new bytes")
+	fetcher.fetchErr = errors.New("must not fetch")
+	upstream := sha256Hex("new bytes")
+
+	res, err := proxy.coalescedFetchFromURL(context.Background(),
+		"npm", "pkg", "1.0.0", staleFilename, stalePkgPURL, staleVersionPURL, staleURL, nil, upstream)
+	if err != nil {
+		t.Fatalf("late leader failed: %v", err)
+	}
+	got, err := io.ReadAll(res.Reader)
+	_ = res.Reader.Close()
+	if err != nil || string(got) != "new bytes" {
+		t.Fatalf("got %q (err %v), want the refreshed bytes", got, err)
+	}
+	if fetcher.fetchCalled {
+		t.Error("refreshed entry was fetched again")
+	}
+	if d := cachedDigest(t, proxy); d != upstream {
+		t.Errorf("refreshed record was discarded, digest = %q", d)
+	}
+	if !bytesPresent(store) {
+		t.Error("refreshed bytes were deleted")
+	}
+}

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,550 @@
+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 TestSwiftSourceArchiveHeadLeavesStaleCacheForTheFetch(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)
+	}
+	// HEAD leaves the stale entry alone; the next GET replaces it under the
+	// coalescing key.
+	if len(store.files) != 1 {
+		t.Errorf("HEAD must leave the stale archive in storage, got %v", store.files)
+	}
+	if rec, _ := db.GetCachedArtifact(packagePURL, versionPURL, "example-1.2.3.zip"); rec == nil {
+		t.Error("HEAD must leave the stale cache record in place")
+	}
+
+	fetcher.artifact = artifactBody("upstream archive")
+	w = httptest.NewRecorder()
+	handler.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/apple/example/1.2.3.zip", nil))
+	if w.Code != http.StatusOK {
+		t.Fatalf("GET status = %d, want 200; body: %s", w.Code, w.Body.String())
+	}
+	if w.Body.String() != "upstream archive" {
+		t.Errorf("GET body = %q, want the refreshed archive", w.Body.String())
+	}
+	rec, _ := db.GetCachedArtifact(packagePURL, versionPURL, "example-1.2.3.zip")
+	if rec == nil || rec.Artifact.Digest.Encoded() != hex.EncodeToString(upstreamChecksum[:]) {
+		t.Errorf("cache record after GET = %+v, want the upstream checksum", rec)
+	}
+}
+
+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

@@ -0,0 +1,507 @@
+// Package httpclient provides authentication-aware HTTP transports for upstream requests.
+package httpclient
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	defaultTokenLifetime  = 60 * time.Second
+	tokenExpirySkew       = 5 * time.Second
+	maxTokenResponseSize  = 1 << 20
+	shortTokenSkewDivisor = 10
+	tokenMaxRetries       = 3
+	tokenRetryBaseDelay   = 500 * time.Millisecond
+)
+
+// AuthFunc returns a configured authentication header for a URL.
+type AuthFunc func(url string) (headerName, headerValue string)
+
+// Transport adds configured authentication and follows OCI Bearer challenges.
+type Transport struct {
+	base       http.RoundTripper
+	authForURL AuthFunc
+	retryWait  func(context.Context, time.Duration) error
+
+	mu         sync.Mutex
+	tokens     map[string]cachedToken
+	challenges map[string]bearerChallenge
+}
+
+type cachedToken struct {
+	value     string
+	expiresAt time.Time
+}
+
+type bearerChallenge struct {
+	realm   string
+	service string
+	scopes  []string
+}
+
+type tokenResponse struct {
+	Token       string `json:"token"`
+	AccessToken string `json:"access_token"`
+	ExpiresIn   int64  `json:"expires_in"`
+	IssuedAt    string `json:"issued_at"`
+}
+
+// NewTransport creates an authentication-aware transport around base.
+func NewTransport(base http.RoundTripper, authForURL AuthFunc) *Transport {
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	return &Transport{
+		base:       base,
+		authForURL: authForURL,
+		retryWait:  waitForRetry,
+		tokens:     make(map[string]cachedToken),
+		challenges: make(map[string]bearerChallenge),
+	}
+}
+
+// RoundTrip implements http.RoundTripper.
+func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error) {
+	hasExplicitAuthorization := req.Header.Get("Authorization") != ""
+	outbound := cloneRequest(req)
+	t.applyAuthentication(outbound, hasExplicitAuthorization)
+
+	resp, err := t.base.RoundTrip(outbound)
+	if err != nil || resp.StatusCode != http.StatusUnauthorized {
+		return resp, err
+	}
+	if hasExplicitAuthorization {
+		return resp, nil
+	}
+	if registryProtectionSpace(req.URL) == "" {
+		return resp, nil
+	}
+
+	challenge, ok := parseBearerChallenge(resp.Header.Values("WWW-Authenticate"))
+	if !ok || !canReplay(req) {
+		return resp, nil
+	}
+
+	drainAndClose(resp.Body)
+	token, err := t.token(req.Context(), challenge)
+	if err != nil {
+		return nil, fmt.Errorf("registry authentication: %w", err)
+	}
+	t.rememberChallenge(req.URL, challenge)
+
+	retry, err := cloneRequestForRetry(req)
+	if err != nil {
+		return nil, err
+	}
+	t.applyConfiguredAuthentication(retry)
+	retry.Header.Set("Authorization", "Bearer "+token)
+	return t.base.RoundTrip(retry)
+}
+
+func (t *Transport) applyAuthentication(req *http.Request, hasExplicitAuthorization bool) {
+	t.applyConfiguredAuthentication(req)
+	if hasExplicitAuthorization {
+		return
+	}
+	if token := t.cachedTokenForRequest(req.URL); token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+}
+
+func (t *Transport) applyConfiguredAuthentication(req *http.Request) {
+	if t.authForURL == nil {
+		return
+	}
+	name, value := t.authForURL(req.URL.String())
+	if name != "" && value != "" && req.Header.Get(name) == "" {
+		req.Header.Set(name, value)
+	}
+}
+
+func (t *Transport) token(ctx context.Context, challenge bearerChallenge) (string, error) {
+	key := challenge.key()
+	if token := t.cachedToken(key); token != "" {
+		return token, nil
+	}
+
+	token, expiresAt, err := t.fetchToken(ctx, challenge)
+	if err != nil {
+		return "", err
+	}
+
+	t.cacheToken(key, cachedToken{value: token, expiresAt: expiresAt})
+	return token, nil
+}
+
+func (t *Transport) cacheToken(key string, token cachedToken) {
+	now := time.Now()
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	for cachedKey, cached := range t.tokens {
+		if !now.Before(cached.expiresAt) {
+			delete(t.tokens, cachedKey)
+		}
+	}
+	t.tokens[key] = token
+}
+
+func (t *Transport) fetchToken(ctx context.Context, challenge bearerChallenge) (string, time.Time, error) {
+	tokenURL, err := url.Parse(challenge.realm)
+	if err != nil || !tokenURL.IsAbs() || (tokenURL.Scheme != "https" && tokenURL.Scheme != "http") {
+		return "", time.Time{}, fmt.Errorf("invalid token realm %q", challenge.realm)
+	}
+
+	query := tokenURL.Query()
+	if challenge.service != "" {
+		query.Set("service", challenge.service)
+	}
+	for _, scope := range challenge.scopes {
+		query.Add("scope", scope)
+	}
+	query.Set("client_id", "git-pkgs-proxy")
+	tokenURL.RawQuery = query.Encode()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, tokenURL.String(), nil)
+	if err != nil {
+		return "", time.Time{}, err
+	}
+
+	client := &http.Client{Transport: configuredTransport{parent: t}}
+	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 {
+			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)
+	}
+	token := payload.Token
+	if token == "" {
+		token = payload.AccessToken
+	}
+	if token == "" {
+		return "", time.Time{}, fmt.Errorf("token response did not contain a token")
+	}
+
+	issuedAt := time.Now()
+	if payload.IssuedAt != "" {
+		if parsed, parseErr := time.Parse(time.RFC3339, payload.IssuedAt); parseErr == nil {
+			issuedAt = parsed
+		}
+	}
+	lifetime := time.Duration(payload.ExpiresIn) * time.Second
+	if lifetime <= 0 {
+		lifetime = defaultTokenLifetime
+	}
+	expiresAt := issuedAt.Add(lifetime).Add(-expirySkew(lifetime))
+	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
+}
+
+func (t configuredTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	outbound := cloneRequest(req)
+	t.parent.applyConfiguredAuthentication(outbound)
+	return t.parent.base.RoundTrip(outbound)
+}
+
+func (t *Transport) cachedTokenForRequest(requestURL *url.URL) string {
+	space := registryProtectionSpace(requestURL)
+	if space == "" {
+		return ""
+	}
+
+	t.mu.Lock()
+	challenge, ok := t.challenges[space]
+	t.mu.Unlock()
+	if !ok {
+		return ""
+	}
+	return t.cachedToken(challenge.key())
+}
+
+func (t *Transport) cachedToken(key string) string {
+	now := time.Now()
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	token, ok := t.tokens[key]
+	if !ok {
+		return ""
+	}
+	if !now.Before(token.expiresAt) {
+		delete(t.tokens, key)
+		return ""
+	}
+	return token.value
+}
+
+func (t *Transport) rememberChallenge(requestURL *url.URL, challenge bearerChallenge) {
+	space := registryProtectionSpace(requestURL)
+	if space == "" {
+		return
+	}
+	t.mu.Lock()
+	t.challenges[space] = challenge
+	t.mu.Unlock()
+}
+
+func (c bearerChallenge) key() string {
+	return c.realm + "\x00" + c.service + "\x00" + strings.Join(c.scopes, "\x00")
+}
+
+func registryProtectionSpace(u *url.URL) string {
+	const registryPrefix = "/v2/"
+	if u == nil || !strings.HasPrefix(u.Path, registryPrefix) {
+		return ""
+	}
+	rest := strings.TrimPrefix(u.Path, registryPrefix)
+	end := len(rest)
+	for _, marker := range []string{"/blobs/", "/manifests/", "/tags/", "/referrers/"} {
+		if index := strings.Index(rest, marker); index >= 0 && index < end {
+			end = index
+		}
+	}
+	if end == len(rest) || end == 0 {
+		return ""
+	}
+	return u.Scheme + "://" + u.Host + registryPrefix + rest[:end]
+}
+
+func parseBearerChallenge(values []string) (bearerChallenge, bool) {
+	for _, value := range values {
+		params, ok := bearerParameters(value)
+		if !ok || params["realm"] == "" {
+			continue
+		}
+		challenge := bearerChallenge{
+			realm:   params["realm"],
+			service: params["service"],
+		}
+		if scope := params["scope"]; scope != "" {
+			challenge.scopes = append(challenge.scopes, scope)
+		}
+		return challenge, true
+	}
+	return bearerChallenge{}, false
+}
+
+func bearerParameters(value string) (map[string]string, bool) {
+	start := findAuthScheme(value, "Bearer")
+	if start < 0 {
+		return nil, false
+	}
+	rest := value[start+len("Bearer"):]
+	params := make(map[string]string)
+	for {
+		rest = strings.TrimLeft(rest, " \t,")
+		if rest == "" {
+			break
+		}
+
+		keyEnd := strings.IndexAny(rest, "= \t,")
+		if keyEnd <= 0 {
+			break
+		}
+		key := strings.ToLower(rest[:keyEnd])
+		rest = strings.TrimLeft(rest[keyEnd:], " \t")
+		if rest == "" || rest[0] != '=' {
+			break
+		}
+		rest = strings.TrimLeft(rest[1:], " \t")
+
+		parsed, remaining, ok := parseAuthValue(rest)
+		if !ok {
+			return nil, false
+		}
+		params[key] = parsed
+		rest = remaining
+	}
+	return params, true
+}
+
+func findAuthScheme(value, scheme string) int {
+	inQuote := false
+	escaped := false
+	for index := 0; index+len(scheme) <= len(value); index++ {
+		char := value[index]
+		if escaped {
+			escaped = false
+			continue
+		}
+		if char == '\\' && inQuote {
+			escaped = true
+			continue
+		}
+		if char == '"' {
+			inQuote = !inQuote
+			continue
+		}
+		if inQuote || !strings.EqualFold(value[index:index+len(scheme)], scheme) {
+			continue
+		}
+		beforeOK := index == 0 || value[index-1] == ',' || value[index-1] == ' ' || value[index-1] == '\t'
+		after := index + len(scheme)
+		afterOK := after < len(value) && (value[after] == ' ' || value[after] == '\t')
+		if beforeOK && afterOK {
+			return index
+		}
+	}
+	return -1
+}
+
+func parseAuthValue(value string) (parsed, remaining string, ok bool) {
+	if value == "" {
+		return "", "", false
+	}
+	if value[0] != '"' {
+		end := strings.IndexAny(value, " \t,")
+		if end < 0 {
+			return value, "", true
+		}
+		return value[:end], value[end:], end > 0
+	}
+
+	var builder strings.Builder
+	escaped := false
+	for index := 1; index < len(value); index++ {
+		char := value[index]
+		if escaped {
+			builder.WriteByte(char)
+			escaped = false
+			continue
+		}
+		if char == '\\' {
+			escaped = true
+			continue
+		}
+		if char == '"' {
+			return builder.String(), value[index+1:], true
+		}
+		builder.WriteByte(char)
+	}
+	return "", "", false
+}
+
+func cloneRequest(req *http.Request) *http.Request {
+	clone := req.Clone(req.Context())
+	clone.Header = req.Header.Clone()
+	return clone
+}
+
+func canReplay(req *http.Request) bool {
+	return req.Body == nil || req.GetBody != nil
+}
+
+func cloneRequestForRetry(req *http.Request) (*http.Request, error) {
+	clone := cloneRequest(req)
+	if req.Body == nil {
+		return clone, nil
+	}
+	body, err := req.GetBody()
+	if err != nil {
+		return nil, fmt.Errorf("replaying authenticated request: %w", err)
+	}
+	clone.Body = body
+	return clone, nil
+}
+
+func expirySkew(lifetime time.Duration) time.Duration {
+	if lifetime < tokenExpirySkew*2 {
+		return lifetime / shortTokenSkewDivisor
+	}
+	return tokenExpirySkew
+}
+
+func drainAndClose(body io.ReadCloser) {
+	_, _ = io.Copy(io.Discard, io.LimitReader(body, maxTokenResponseSize))
+	_ = body.Close()
+}

internal/httpclient/transport_test.go

@@ -0,0 +1,414 @@
+package httpclient
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"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
+	var server *httptest.Server
+
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/token":
+			tokenRequests++
+			if got := r.URL.Query().Get("service"); got != "registry.test" {
+				t.Errorf("service = %q, want %q", got, "registry.test")
+			}
+			if got := r.URL.Query().Get("scope"); got != "repository:library/test:pull" {
+				t.Errorf("scope = %q, want %q", got, "repository:library/test:pull")
+			}
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = io.WriteString(w, `{"token":"registry-token","expires_in":3600}`)
+		case "/v2/library/test/blobs/sha256:first", "/v2/library/test/blobs/sha256:second":
+			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()
+
+	client := &http.Client{Transport: NewTransport(http.DefaultTransport, nil)}
+	for _, digest := range []string{"sha256:first", "sha256:second"} {
+		resp, err := client.Get(server.URL + "/v2/library/test/blobs/" + digest)
+		if err != nil {
+			t.Fatalf("GET %s: %v", digest, err)
+		}
+		body, readErr := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+		if readErr != nil {
+			t.Fatalf("read %s response: %v", digest, readErr)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("GET %s status = %d, want %d", digest, resp.StatusCode, http.StatusOK)
+		}
+		if string(body) != "blob" {
+			t.Errorf("GET %s body = %q, want %q", digest, body, "blob")
+		}
+	}
+
+	if tokenRequests != 1 {
+		t.Errorf("token requests = %d, want 1", tokenRequests)
+	}
+	if registryRequests != 3 {
+		t.Errorf("registry requests = %d, want 3", registryRequests)
+	}
+}
+
+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" {
+			t.Errorf("X-Registry-Token = %q, want %q", got, "configured-token")
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	authForURL := func(url string) (string, string) {
+		if strings.HasPrefix(url, server.URL) {
+			return "X-Registry-Token", "configured-token"
+		}
+		return "", ""
+	}
+	client := &http.Client{Transport: NewTransport(http.DefaultTransport, authForURL)}
+
+	resp, err := client.Get(server.URL + "/metadata")
+	if err != nil {
+		t.Fatalf("GET metadata: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusNoContent {
+		t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusNoContent)
+	}
+}
+
+func TestTransportPreservesExplicitAuthentication(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("Authorization"); got != "Bearer explicit-token" {
+			t.Errorf("Authorization = %q, want %q", got, "Bearer explicit-token")
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer server.Close()
+
+	authForURL := func(string) (string, string) {
+		return "Authorization", "Bearer configured-token"
+	}
+	client := &http.Client{Transport: NewTransport(http.DefaultTransport, authForURL)}
+	req, err := http.NewRequest(http.MethodGet, server.URL+"/artifact", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer explicit-token")
+
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("GET artifact: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusNoContent {
+		t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusNoContent)
+	}
+}
+
+func TestTransportDoesNotReplaceExplicitAuthenticationAfterBearerChallenge(t *testing.T) {
+	var registryRequests int
+	var tokenRequests 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 got := r.Header.Get("Authorization"); got != "Bearer explicit-token" {
+				t.Errorf("Authorization = %q, want %q", got, "Bearer explicit-token")
+			}
+			w.Header().Set("WWW-Authenticate", `Bearer realm="`+server.URL+`/token"`)
+			http.Error(w, "authentication required", http.StatusUnauthorized)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer server.Close()
+
+	client := &http.Client{Transport: NewTransport(http.DefaultTransport, nil)}
+	req, err := http.NewRequest(http.MethodGet, server.URL+"/v2/library/test/blobs/sha256:test", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer explicit-token")
+
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("GET blob: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusUnauthorized)
+	}
+	if registryRequests != 1 {
+		t.Errorf("registry requests = %d, want 1", registryRequests)
+	}
+	if tokenRequests != 0 {
+		t.Errorf("token requests = %d, want 0", tokenRequests)
+	}
+}
+
+func TestTransportDoesNotForwardConfiguredAuthenticationOnTokenRedirect(t *testing.T) {
+	destination := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("X-Registry-Token"); got != "" {
+			t.Errorf("redirected X-Registry-Token = %q, want empty", got)
+		}
+		_, _ = io.WriteString(w, `{"token":"registry-token"}`)
+	}))
+	defer destination.Close()
+
+	source := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("X-Registry-Token"); got != "configured-token" {
+			t.Errorf("source X-Registry-Token = %q, want %q", got, "configured-token")
+		}
+		http.Redirect(w, r, destination.URL+"/token", http.StatusFound)
+	}))
+	defer source.Close()
+
+	authForURL := func(rawURL string) (string, string) {
+		if strings.HasPrefix(rawURL, source.URL) {
+			return "X-Registry-Token", "configured-token"
+		}
+		return "", ""
+	}
+	transport := NewTransport(http.DefaultTransport, authForURL)
+	token, _, err := transport.fetchToken(context.Background(), bearerChallenge{realm: source.URL + "/token"})
+	if err != nil {
+		t.Fatalf("fetchToken: %v", err)
+	}
+	if token != "registry-token" {
+		t.Errorf("token = %q, want %q", token, "registry-token")
+	}
+}
+
+func TestTransportPrunesExpiredTokens(t *testing.T) {
+	transport := NewTransport(http.DefaultTransport, nil)
+	transport.tokens["expired-unused"] = cachedToken{
+		value:     "expired-token",
+		expiresAt: time.Now().Add(-time.Minute),
+	}
+	transport.cacheToken("current", cachedToken{
+		value:     "current-token",
+		expiresAt: time.Now().Add(time.Minute),
+	})
+
+	if got := transport.cachedToken("current"); got != "current-token" {
+		t.Errorf("cachedToken(current) = %q, want %q", got, "current-token")
+	}
+	if _, ok := transport.tokens["expired-unused"]; ok {
+		t.Error("expired unused token was not pruned")
+	}
+}
+
+func TestTransportDoesNotFollowBearerChallengeOutsideOCIRegistry(t *testing.T) {
+	tokenRequests := 0
+	var server *httptest.Server
+	server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/token" {
+			tokenRequests++
+			_, _ = io.WriteString(w, `{"token":"unexpected"}`)
+			return
+		}
+		w.Header().Set("WWW-Authenticate", `Bearer realm="`+server.URL+`/token"`)
+		http.Error(w, "authentication required", http.StatusUnauthorized)
+	}))
+	defer server.Close()
+
+	client := &http.Client{Transport: NewTransport(http.DefaultTransport, nil)}
+	resp, err := client.Get(server.URL + "/api/packages")
+	if err != nil {
+		t.Fatalf("GET API: %v", err)
+	}
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Errorf("status = %d, want %d", resp.StatusCode, http.StatusUnauthorized)
+	}
+	if tokenRequests != 0 {
+		t.Errorf("token requests = %d, want 0", tokenRequests)
+	}
+}