Add npm virtual repositories (#152)

npm clients need one registry for internal and public packages, but npm virtuals have no merger, so a local npm repo and npmjs cannot be served together.

- merge packuments across members: union versions (member order wins), first-defined dist-tags minus ones naming missing versions
- serve full and abbreviated (`install-v1`) packuments, scoped names included, via the shared virtual merge cache
- point tarballs at `<virtual>/<member>/<path>` and 302 them to the owning member
- reject an invalid Host with 400; serve virtual and local packuments `no-store` with `Vary: Host, X-Forwarded-Proto, Accept`
- return 502 when a member errors; skip members without the package
- add `docs/npm/virtual.md` and a stock `node:22` e2e-docker case

Reviewed-on: #152
Co-authored-by: unkin-agent <unkin-agent@unkin.net>
Co-committed-by: unkin-agent <unkin-agent@unkin.net>

.gitignore

@@ -1,2 +1,6 @@
 bin/
-terraform/
+/terraform/
+
+# e2e-docker fixtures are real package files (.rpm, .tgz, .whl, .zip, ...) that
+# are intentionally tracked, overriding any global ignore of those extensions.
+!e2e-docker/fixtures/**

.woodpecker/docker.yaml

@@ -4,31 +4,45 @@ when:
 
 steps:
   - name: docker-api
-    image: woodpeckerci/plugin-docker-buildx
+    image: artifactapi.k8s.syd1.au.unkin.net/docker-internal/plugin-docker-buildx:latest
     settings:
-      registry: git.unkin.net
-      repo: git.unkin.net/unkin/artifactapi
+      registry: artifactapi.k8s.syd1.au.unkin.net
+      repo: artifactapi.k8s.syd1.au.unkin.net/docker-internal/artifactapi
       build_args:
         VERSION: ${CI_COMMIT_TAG}
-      username: droneci
-      password:
-        from_secret: DRONECI_PASSWORD
       tags:
         - ${CI_COMMIT_TAG}
         - latest
+    backend_options:
+      kubernetes:
+        serviceAccountName: default
+        resources:
+          requests:
+            memory: 1Gi
+            cpu: 1
+          limits:
+            memory: 4Gi
+            cpu: 2
 
   - name: docker-web
-    image: woodpeckerci/plugin-docker-buildx
+    image: artifactapi.k8s.syd1.au.unkin.net/docker-internal/plugin-docker-buildx:latest
     settings:
-      registry: git.unkin.net
-      repo: git.unkin.net/unkin/artifactapi-ui
+      registry: artifactapi.k8s.syd1.au.unkin.net
+      repo: artifactapi.k8s.syd1.au.unkin.net/docker-internal/artifactapi-ui
       dockerfile: ui/Dockerfile.ui
       context: ui
       build_args:
         BASE_PATH: /ui
-      username: droneci
-      password:
-        from_secret: DRONECI_PASSWORD
       tags:
         - ${CI_COMMIT_TAG}
         - latest
+    backend_options:
+      kubernetes:
+        serviceAccountName: default
+        resources:
+          requests:
+            memory: 1Gi
+            cpu: 1
+          limits:
+            memory: 4Gi
+            cpu: 2

.woodpecker/pre-commit.yaml

@@ -3,11 +3,28 @@ when:
 
 steps:
   - name: pre-commit
-    image: git.unkin.net/unkin/almalinux9-gobuilder:20260606
+    # gobuilder trusts the internal CA, which the S3 build cache endpoint needs.
+    # go-cache-plugin is baked into the image; S3 errors degrade to cache misses.
+    image: "artifactapi.k8s.syd1.au.unkin.net/docker-internal/gobuilder:0.1.2-alma9"
     commands:
       - uvx pre-commit run --all-files
+    environment:
+      # golib lives on Gitea; skip the public proxy/sum db.
+      GOPRIVATE: git.unkin.net
+      GOCACHEPROG: "go-cache-plugin --cache-dir=/tmp/gocache"
+      GOCACHE_S3_BUCKET: gocache
+      # Explicit region skips a GetBucketLocation probe RGW handles poorly.
+      GOCACHE_S3_REGION: us-east-1
+      GOCACHE_S3_ENDPOINT_URL: "https://s3.ceph.unkin.net"
+      GOCACHE_S3_PATH_STYLE: "true"
+      GOCACHE_KEY_PREFIX: ci-artifactapi
+      AWS_ACCESS_KEY_ID:
+        from_secret: GOCACHE_AWS_ACCESS_KEY_ID
+      AWS_SECRET_ACCESS_KEY:
+        from_secret: GOCACHE_AWS_SECRET_ACCESS_KEY
     backend_options:
       kubernetes:
+        serviceAccountName: default
         resources:
           requests:
             memory: 512Mi

.woodpecker/test.yaml

@@ -3,6 +3,32 @@ when:
 
 steps:
   - name: test
-    image: golang:1.25
+    # gobuilder trusts the internal CA, which the S3 build cache endpoint needs.
+    # go-cache-plugin is baked into the image; S3 errors degrade to cache misses.
+    image: "artifactapi.k8s.syd1.au.unkin.net/docker-internal/gobuilder:0.1.2-alma9"
     commands:
       - go test -race -count=1 ./pkg/... ./internal/...
+    environment:
+      # golib lives on Gitea; skip the public proxy/sum db.
+      GOPRIVATE: git.unkin.net
+      GOCACHEPROG: "go-cache-plugin --cache-dir=/tmp/gocache"
+      GOCACHE_S3_BUCKET: gocache
+      # Explicit region skips a GetBucketLocation probe RGW handles poorly.
+      GOCACHE_S3_REGION: us-east-1
+      GOCACHE_S3_ENDPOINT_URL: "https://s3.ceph.unkin.net"
+      GOCACHE_S3_PATH_STYLE: "true"
+      GOCACHE_KEY_PREFIX: ci-artifactapi
+      AWS_ACCESS_KEY_ID:
+        from_secret: GOCACHE_AWS_ACCESS_KEY_ID
+      AWS_SECRET_ACCESS_KEY:
+        from_secret: GOCACHE_AWS_SECRET_ACCESS_KEY
+    backend_options:
+      kubernetes:
+        serviceAccountName: default
+        resources:
+          requests:
+            memory: 1Gi
+            cpu: 1
+          limits:
+            memory: 4Gi
+            cpu: 2

Dockerfile

@@ -4,6 +4,10 @@ RUN apk add --no-cache git
 
 WORKDIR /build
 
+# golib is fetched straight from Gitea; the public proxy and sum db have no
+# view of git.unkin.net modules.
+ENV GOPRIVATE=git.unkin.net
+
 COPY go.mod go.sum ./
 RUN go mod download
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test lint fmt e2e docker docker-ui compose clean tidy check-go
+.PHONY: build test lint fmt e2e docker-e2e docker docker-ui compose clean tidy check-go
 
 BINARY := bin/artifactapi
 MODULE := git.unkin.net/unkin/artifactapi
@@ -6,6 +6,11 @@ VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "0.0
 GO_VERSION_REQUIRED := 1.23
 GO_VERSION_ACTUAL := $(shell go version | sed 's/go version go\([0-9]*\.[0-9]*\).*/\1/')
 
+# git.unkin.net modules (golib) are fetched straight from Gitea, never via the
+# public proxy or sum db, which have no view of them. Exported here rather than
+# written with `go env -w`, so a fresh checkout needs no machine-local setup.
+export GOPRIVATE := git.unkin.net
+
 check-go:
 	@if [ "$$(printf '%s\n%s' "$(GO_VERSION_REQUIRED)" "$(GO_VERSION_ACTUAL)" | sort -V | head -1)" != "$(GO_VERSION_REQUIRED)" ]; then \
 		echo "ERROR: Go >= $(GO_VERSION_REQUIRED) required, found $(GO_VERSION_ACTUAL)"; exit 1; \
@@ -28,6 +33,11 @@ fmt: check-go
 e2e: check-go
 	TESTCONTAINERS_RYUK_DISABLED=true go test -tags=e2e -race -count=1 -timeout=5m ./e2e/...
 
+# Build the container, bring up the full docker-compose stack + a mock upstream,
+# and run the black-box suite against the running product.
+docker-e2e: check-go
+	./scripts/docker-e2e.sh
+
 docker:
 	docker build -t artifactapi:$(VERSION) .
 

PLAN.md

@@ -672,7 +672,7 @@ func TestMain(m *testing.M) {
 
 ```hcl
 provider "artifactapi" {
-  endpoint = "https://artifactapi.k8s.syd1.au.unkin.net"
+  endpoint = "https://artifactapi.example.com"
 }
 
 resource "artifactapi_remote" "terraform_registry" {

README.md

@@ -1,6 +1,6 @@
 # ArtifactAPI
 
-Caching proxy for package repositories. Single Go binary, 10 package types, content-addressable storage, managed by Terraform.
+Caching proxy for package repositories. Single Go binary, 12 package types, content-addressable storage, managed by Terraform.
 
 ## Quick Start
 
@@ -20,74 +20,97 @@ API: `http://localhost:8000` | Frontend: `http://localhost:5173`
 
 ## Package Types
 
-| Type | Mutable (auto-detected) | Immutable (auto-detected) |
-|---|---|---|
-| `generic` | nothing | everything |
-| `docker` | tag manifests, `/tags/list` | blobs, digest manifests |
-| `helm` | `index.yaml` | `.tgz` charts |
-| `pypi` | `simple/*` index pages | `.whl`, `.tar.gz` |
-| `npm` | package metadata | `.tgz` tarballs |
-| `rpm` | `repomd.xml`, `repodata/*` | `.rpm` |
-| `alpine` | `APKINDEX.tar.gz` | `.apk` |
-| `puppet` | `v3/modules/*`, `v3/releases*` | `.tar.gz` |
-| `terraform` | `*/versions` | `*/download/*/*` |
-| `goproxy` | `@v/list`, `@latest` | `.info`, `.mod`, `.zip` |
-
 Providers classify paths automatically. Users only configure what to proxy and TTLs.
 
+Classification precedence, TTLs and eviction for every remote: [docs/common/caching.md](docs/common/caching.md).
+
+Each type's paths, Terraform examples and local/virtual behaviour are in `docs/<type>/`:
+
+- `alpine`: [remote](docs/alpine/remote.md), [remote-github](docs/alpine/remote-github.md)
+- `cargo`: [remote](docs/cargo/remote.md)
+- `deb`: [remote](docs/deb/remote.md), [remote-github](docs/deb/remote-github.md)
+- `docker`: [remote](docs/docker/remote.md), [local](docs/docker/local.md)
+- `generic`: [remote](docs/generic/remote.md)
+- `gems`: [remote](docs/gems/remote.md)
+- `goproxy`: [remote](docs/goproxy/remote.md)
+- `helm`: [remote](docs/helm/remote.md), [local](docs/helm/local.md), [virtual](docs/helm/virtual.md)
+- `npm`: [remote](docs/npm/remote.md), [local](docs/npm/local.md), [virtual](docs/npm/virtual.md)
+- `nuget`: [remote](docs/nuget/remote.md)
+- `puppet`: [remote](docs/puppet/remote.md), [local](docs/puppet/local.md)
+- `pypi`: [remote](docs/pypi/remote.md)
+- `rpm`: [remote](docs/rpm/remote.md), [remote-github](docs/rpm/remote-github.md)
+- `terraform`: [remote](docs/terraform/remote.md), [local](docs/terraform/local.md)
+
+### GitHub authentication
+
+Anonymous GitHub is capped at **60 requests/hour** and cannot read private
+repositories. Configure a **server-level GitHub credential** to raise the ceiling
+to roughly **5000 requests/hour** and to read private-repo release assets. The
+credential is a process-wide machine identity applied by default to *every*
+outbound GitHub request — the releases scan, the ranged asset-header fetches, and
+the generic-github byte proxy that streams private release assets.
+
+The credential is read from the environment (deliver it from a Vault or
+Kubernetes secret). It is **never** stored per-remote in the database, **never**
+returned by any API, and **never** logged. Configure **exactly one** mode.
+
+**Precedence.** A remote's own `username`/`password` credential still wins for
+that remote's requests; the server credential is the default for everything else.
+With no credential configured at all, requests stay anonymous (current behavior).
+Partial configuration (e.g. an App id with no private key) is a **startup error**
+— artifactapi fails closed rather than silently falling back to anonymous.
+
+Both modes share the syncer's single global rate limiter, so a token simply
+raises the effective GitHub ceiling; the default limiter settings stay safe.
+
+#### Mode 1 — Personal Access Token (minimum viable, recommended for free accounts)
+
+Set `GITHUB_TOKEN`. It is sent as `Authorization: Bearer <token>`.
+
+Recommended free-account setup — a **fine-grained PAT** scoped to just the target
+repositories:
+
+1. GitHub → *Settings → Developer settings → Personal access tokens →
+   Fine-grained tokens → Generate new token*.
+2. Limit *Repository access* to the specific repo(s) serving releases.
+3. Grant repository permissions **Contents: Read-only** and **Metadata:
+   Read-only** (Metadata is mandatory and auto-selected).
+
+A classic PAT with the `repo` scope also works but is broader than necessary.
+
+```bash
+GITHUB_TOKEN=github_pat_xxxxxxxx
+```
+
+#### Mode 2 — GitHub App installation token (proper machine identity)
+
+A GitHub App is not tied to a personal account and can be created and installed on
+free personal repos. artifactapi mints a short-lived RS256 **JWT** from the app
+private key, exchanges it at `POST /app/installations/{id}/access_tokens` for a
+~1-hour **installation access token**, caches that token, and refreshes it a few
+minutes before expiry (thread-safe, single-flighted).
+
+1. GitHub → *Settings → Developer settings → GitHub Apps → New GitHub App*.
+2. Under *Permissions → Repository permissions* grant **Contents: Read-only**
+   (Metadata: Read-only is implied).
+3. Generate a **private key** (downloads a PEM) and note the **App ID**.
+4. *Install* the App on the account and select the target repositories, then read
+   the **Installation ID** from the installation URL
+   (`.../settings/installations/<installation-id>`).
+
+```bash
+GITHUB_APP_ID=123456
+GITHUB_APP_INSTALLATION_ID=7654321
+GITHUB_APP_PRIVATE_KEY_PATH=/etc/artifactapi/github-app.pem
+# or inline PEM (e.g. mounted from a secret):
+# GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
+```
+
 ## Terraform
 
-Remotes and virtuals are managed by Terraform. Each package type has its own resource:
+Remotes and virtuals are managed by Terraform. Each package type has its own resource; see `docs/<type>/` for examples.
 
-```hcl
-resource "artifactapi_remote_generic" "github" {
-  name     = "github"
-  base_url = "https://github.com"
-
-  immutable_ttl = 0
-  mutable_ttl   = 7200
-
-  patterns = [
-    "ducaale/xh/.*/xh-.*-x86_64-unknown-linux-musl.tar.gz$",
-    "mikefarah/yq/.*/yq_linux_amd64$",
-  ]
-
-  mutable_patterns = [
-    ".*/archive/refs/heads/.*\\.tar\\.gz$",
-  ]
-}
-
-resource "artifactapi_remote_docker" "dockerhub" {
-  name     = "dockerhub"
-  base_url = "https://registry-1.docker.io"
-
-  immutable_ttl    = 0
-  mutable_ttl      = 300
-  ban_tags_enabled = true
-  ban_tags         = ["latest"]
-
-  patterns = [
-    "^library/postgres",
-    "^library/redis",
-  ]
-}
-
-resource "artifactapi_remote_helm" "jetstack" {
-  name     = "jetstack"
-  base_url = "https://charts.jetstack.io"
-
-  immutable_ttl = 0
-  mutable_ttl   = 3600
-}
-
-resource "artifactapi_virtual" "helm" {
-  name         = "helm"
-  package_type = "helm"
-  members      = [artifactapi_remote_helm.jetstack.name]
-}
-```
-
-Provider: [terraform-provider-artifactapi](../terraform-provider-artifactapi)
+Provider: [terraform-provider-artifactapi](https://git.unkin.net/unkin/terraform-provider-artifactapi)
 
 ## Access Control
 
@@ -107,6 +130,7 @@ No patterns + no blocklist = open proxy. Provider handles mutability classificat
 ```
 GET /api/v1/remote/{name}/{path}     Proxy/cache artifact
 GET /api/v1/virtual/{name}/{path}    Virtual repo (merged index)
+PUT /api/v1/local/{name}/{package}   npm publish (local npm repos)
 GET /v2/{name}/{path}                Docker Registry v2
 ```
 
@@ -132,6 +156,28 @@ S3/MinIO    ─── content-addressable blob storage (blobs/sha256/{hash})
 
 S3 client supports MinIO, Ceph RGW, and AWS S3 (via minio-go).
 
+### Schema migrations
+
+The SQL schema lives in `migrations/` as numbered `.sql` files, embedded into
+the binary and applied at startup before the server listens, so there is no
+mirrored copy of the schema in the deployment to drift out of sync.
+
+The runner is [`golib/pg`](https://git.unkin.net/unkin/golib)'s `pg.NewMigrated`
+— artifactapi owns the SQL, the shared library owns the mechanics.
+
+Each start takes `pg_advisory_lock` on a fixed key (FNV-1a/64 of the lock name
+`artifactapi-migrations`), creates `schema_migrations` (`version`, `applied_at`)
+if missing, and applies every embedded file whose filename is not yet recorded —
+in lexical (version) order, each file's SQL and its tracking row in one
+transaction — then unlocks. Replicas starting together queue on the lock and
+then find nothing to do.
+
+A file absent from `schema_migrations` is re-run even when the database already
+has the schema, which is how a database migrated by the old untracked inline DDL
+picks `0001_init.sql` up: the statements are `IF NOT EXISTS`-guarded, so the
+re-run is a no-op that only lands the tracking row. New migrations must stay
+additive and idempotent for the same reason; a test enforces it.
+
 ## Environment Variables
 
 | Variable | Default | Description |
@@ -142,6 +188,7 @@ S3 client supports MinIO, Ceph RGW, and AWS S3 (via minio-go).
 | `DBUSER` | `artifacts` | PostgreSQL user |
 | `DBPASS` | | PostgreSQL password |
 | `DBNAME` | `artifacts` | PostgreSQL database |
+| `DBSSL` | `disable` | PostgreSQL `sslmode` |
 | `REDIS_URL` | `redis://localhost:6379` | Redis URL |
 | `MINIO_ENDPOINT` | `localhost:9000` | S3 endpoint |
 | `MINIO_ACCESS_KEY` | | S3 access key |
@@ -149,6 +196,17 @@ S3 client supports MinIO, Ceph RGW, and AWS S3 (via minio-go).
 | `MINIO_BUCKET` | `artifacts` | S3 bucket |
 | `MINIO_SECURE` | `false` | Use HTTPS for S3 |
 | `MINIO_REGION` | | S3 region (AWS) |
+| `GITHUB_SYNC_RATE` | `1` | `github_rpm` syncer global GitHub request rate (req/s), shared across all remotes. `1`/s = 3600/hr, under an authenticated token's ~5000/hr; unauthenticated (~60/hr) relies on ETag/304 |
+| `GITHUB_SYNC_BURST` | `5` | Token-bucket burst for the shared limiter |
+| `GITHUB_SYNC_WORKERS` | `3` | Concurrent `github_rpm` scan workers |
+| `GITHUB_SYNC_POLL_INTERVAL` | `60` | Base scheduler tick in seconds; per-remote cadence is its `mutable_ttl`, enforced by the DB lease |
+| `GITHUB_TOKEN` | | Server-level GitHub PAT (fine-grained or classic), sent as `Authorization: Bearer`. Applies to every GitHub request; per-remote creds override it. See [GitHub authentication](#github-authentication) |
+| `GITHUB_APP_ID` | | GitHub App id (App auth mode; mutually exclusive with `GITHUB_TOKEN`) |
+| `GITHUB_APP_INSTALLATION_ID` | | GitHub App installation id |
+| `GITHUB_APP_PRIVATE_KEY` | | GitHub App private key, inline PEM |
+| `GITHUB_APP_PRIVATE_KEY_PATH` | | GitHub App private key, file path (alternative to inline PEM) |
+| `ARTIFACTAPI_OIDC_ISSUER` | | OIDC issuer URL (e.g. Vault `https://vault.service.consul:8200/v1/identity/oidc`). When set, `POST /api/v2/remotes`, `POST /api/v2/virtuals` and `PUT`/`DELETE` on `/api/v2/{remotes,virtuals}/{name}` require `Authorization: Bearer <jwt>` verified against the issuer's JWKS. Uploads, object/file deletes, probe, reads and `/v2` stay open. Unset = no auth |
+| `ARTIFACTAPI_OIDC_AUDIENCE` | | Comma-separated allowed `aud` values (e.g. the Vault OIDC role's client_id). Required when `ARTIFACTAPI_OIDC_ISSUER` is set |
 
 ## Development
 
@@ -160,6 +218,22 @@ make lint        # golangci-lint + go vet
 make fmt         # gofmt + goimports
 ```
 
+### `GOPRIVATE`
+
+artifactapi depends on `git.unkin.net/unkin/golib`, which is served by Gitea and
+is unknown to `proxy.golang.org` / `sum.golang.org`. Module resolution therefore
+needs:
+
+```
+export GOPRIVATE=git.unkin.net
+```
+
+The `Makefile` exports it for every target, and the `Dockerfile` and the
+woodpecker Go steps set it themselves, so `make build|test|lint` and CI work on
+a clean checkout. Only bare `go` commands run outside `make` need it in your
+shell — set it there (or in your shell profile) rather than with `go env -w`,
+which is machine state this repo cannot carry.
+
 ### TUI
 
 ```bash

docker-compose.e2e.yml

@@ -0,0 +1,34 @@
+# Overlay for the dockerised end-to-end suite (scripts/docker-e2e.sh).
+# Adds a static mock upstream that the artifactapi container proxies, so the
+# caching tests are hermetic and need no internet access.
+services:
+  mockupstream:
+    image: nginx:alpine
+    volumes:
+      - ./e2e-docker/fixtures:/usr/share/nginx/html:ro,z
+    # No host port needed: only the artifactapi container talks to it, and the
+    # tests compare served bytes against the on-disk fixtures.
+
+  # Two constant-body upstreams for the multi-base_url suite: each returns a
+  # distinct, upstream-identifying body for any path, so round-robin
+  # distribution across a two-mirror remote is directly observable.
+  mockupstreama:
+    image: nginx:alpine
+    volumes:
+      - ./e2e-docker/mirror-conf/a.conf:/etc/nginx/conf.d/default.conf:ro,z
+  mockupstreamb:
+    image: nginx:alpine
+    volumes:
+      - ./e2e-docker/mirror-conf/b.conf:/etc/nginx/conf.d/default.conf:ro,z
+
+  artifactapi:
+    # The host port is set via ARTIFACTAPI_PORT (see scripts/docker-e2e.sh),
+    # defaulting to 8000; the e2e run uses 8001 to avoid colliding with a
+    # locally-running instance.
+    depends_on:
+      mockupstream:
+        condition: service_started
+      mockupstreama:
+        condition: service_started
+      mockupstreamb:
+        condition: service_started

docker-compose.yml

@@ -2,7 +2,7 @@ services:
   artifactapi:
     build: .
     ports:
-      - "8000:8000"
+      - "${ARTIFACTAPI_PORT:-8000}:8000"
     environment:
       LISTEN_ADDR: ":8000"
       DBHOST: postgres

docs/alpine/remote-github.md

@@ -0,0 +1,7 @@
+# `github_alpine` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `github_alpine` | `APKINDEX.tar.gz` (synthesized) | `.apk` (redirected) |

docs/alpine/remote.md

@@ -0,0 +1,7 @@
+# `alpine` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `alpine` | `APKINDEX.tar.gz` | `.apk` |

docs/cargo/remote.md

@@ -0,0 +1,7 @@
+# `cargo` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `cargo` | sparse index files (`config.json` synthesized) | `crates/*/*.crate` |

docs/common/caching.md

@@ -0,0 +1,101 @@
+# Caching and classification (all remotes)
+
+Every proxied request on a remote is classified as **denied**, **immutable** or
+**mutable**. The class picks the storage path and the freshness TTL.
+
+## Fields
+
+| Field | Meaning |
+|---|---|
+| `patterns` | Allowlist of regexes. Empty allows every path; otherwise a non-matching path is denied (403). |
+| `blocklist` | Regexes; a match is denied (403). |
+| `immutable_patterns` | Regexes forcing a path immutable. |
+| `mutable_patterns` | Regexes forcing a path mutable. |
+| `immutable_ttl` | Seconds an immutable path stays fresh. `0` = forever. |
+| `mutable_ttl` | Seconds a mutable path stays fresh. `0` also means never expires. Omitted on create, it defaults to `3600`; omitted on update, the stored value is kept. |
+| `check_mutable` | When a mutable path's `mutable_ttl` expires, sends a conditional `HEAD` (`If-None-Match`) with the stored upstream ETag. A `304` re-arms the TTL and serves the stored copy; anything else refetches in full. The ETag is kept for `max(10 × mutable_ttl, 7 days)`, re-armed on each `304`, so idle paths age out. It is only stored when `check_mutable` is set and `mutable_ttl` is non-zero, and never for immutable paths. |
+| `stale_on_error` | On an upstream network error, serve the stored copy instead of failing. |
+| `quarantine_enabled` / `quarantine_days` | Stored on the remote but not enforced by the proxy yet. |
+| `mirrorlist` / `mirror_strategy` | rpm/deb/alpine only. Upstream pool is `[base_url] + mirrorlist`; `round_robin` (default) rotates the starting mirror, `least_conn` starts at the one with the fewest in-flight requests. Network errors and 5xx fail over to the next mirror; other statuses return as-is. |
+
+## Precedence
+
+The first rule that matches wins:
+
+1. `blocklist` matches: **denied**
+2. `patterns` is non-empty and nothing matches: **denied**
+3. `immutable_patterns` matches: **immutable**
+4. `mutable_patterns` matches: **mutable**
+5. the provider's built-in `Classify` says mutable: **mutable**
+6. anything else: **immutable**
+
+So `blocklist` beats the allowlist, and `immutable_patterns` beats
+`mutable_patterns`. Either user list overrides the built-in rules. `GET` and
+`HEAD` both apply this order.
+
+## Matching rules
+
+- Regexes are Go `regexp`, matched **unanchored** (`MatchString`). Add `^` or `$` yourself when you need them.
+- They match the path after `/api/v1/remote/<name>/`, without a leading slash, e.g. `9/BaseOS/x86_64/os/repodata/repomd.xml`.
+- The query string is not part of the path. It is dropped and not forwarded upstream.
+- `create` and `update` reject an invalid regex in `patterns`, `blocklist`, `mutable_patterns`, `immutable_patterns` or `ban_tags` with a 400. Only invalid regexes already stored before that check are skipped at match time.
+
+## Lifecycles
+
+| | Immutable | Mutable |
+|---|---|---|
+| Stored as | content-addressed blob (sha256), streamed | per-path index object, buffered and rewritten by the provider |
+| Fresh for | `immutable_ttl` (`0` = forever) | `mutable_ttl` |
+| After expiry | refetched from upstream | revalidated with `If-None-Match` when `check_mutable` is set and an ETag is stored, else refetched |
+| Upstream down | `stale_on_error` serves the stored copy and re-arms the TTL; an open circuit breaker always serves stale if a copy exists, else 503 | same |
+
+Concurrent misses on one path share a fetch lock. Waiters poll the store for
+up to 5s instead of all going upstream.
+
+## Eviction
+
+```sh
+curl -X DELETE https://artifactapi.example.com/api/v2/remotes/<name>/objects/<path>
+curl -X DELETE https://artifactapi.example.com/api/v2/remotes/<name>/objects/<dir>/*
+```
+
+- Evict drops the artifact row, the index object and the Redis TTL and ETag keys, so the next request goes upstream whatever the class or TTL.
+- Deleting a remote drops its Redis TTL and ETag keys, so a re-created remote of the same name starts cold.
+- A single-path evict takes the fetch lock first, so an in-flight fetch can't re-cache the path. It returns 503 if the lock stays busy.
+- A wildcard must end in `<dir>/*` and takes no lock.
+- Returns 204, or 404 for an unknown remote.
+
+## Examples
+
+Bodies for `POST https://artifactapi.example.com/api/v2/remotes`.
+
+GitHub release assets through a `generic` remote, allowlisted:
+
+```json
+{"name": "github", "package_type": "generic", "base_url": "https://github.com",
+ "immutable_ttl": 0, "mutable_ttl": 7200,
+ "patterns": ["^mikefarah/yq/releases/download/.*/yq_linux_amd64$"]}
+```
+
+rpm remote: `repodata/*` and `repomd.xml` are mutable by default, so only the TTLs are needed:
+
+```json
+{"name": "almalinux", "package_type": "rpm", "base_url": "https://repo.almalinux.org/almalinux",
+ "immutable_ttl": 0, "mutable_ttl": 3600, "check_mutable": true, "stale_on_error": true}
+```
+
+Force a moving path mutable, e.g. branch tarballs on `generic`:
+
+```json
+{"mutable_patterns": ["/archive/refs/heads/.*\\.tar\\.gz$"], "mutable_ttl": 600}
+```
+
+## Built-in classification per type
+
+Each type's page lists its auto-detected mutable and immutable paths:
+[alpine](../alpine/remote.md), [alpine github](../alpine/remote-github.md),
+[cargo](../cargo/remote.md), [deb](../deb/remote.md), [deb github](../deb/remote-github.md),
+[docker](../docker/remote.md), [generic](../generic/remote.md), [gems](../gems/remote.md), [goproxy](../goproxy/remote.md),
+[helm](../helm/remote.md), [npm](../npm/remote.md), [nuget](../nuget/remote.md),
+[puppet](../puppet/remote.md), [pypi](../pypi/remote.md), [rpm](../rpm/remote.md),
+[rpm github](../rpm/remote-github.md), [terraform](../terraform/remote.md).

docs/deb/remote-github.md

@@ -0,0 +1,7 @@
+# `github_deb` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `github_deb` | `Packages*`, `Release*` (synthesized) | `.deb` (redirected) |

docs/deb/remote.md

@@ -0,0 +1,7 @@
+# `deb` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `deb` | `Packages*`, `Sources*`, `Release`, `InRelease`, `Release.gpg`, `Contents-*` | `.deb` |

docs/docker/local.md

@@ -0,0 +1,17 @@
+# Local docker registry
+
+A local `docker` repo is a real container registry, not a mirror: it serves the
+Docker Registry HTTP API V2 for both push and pull, so any client (`docker`,
+`podman`, `skopeo`, `buildah`) can use it directly.
+
+```sh
+docker tag myapp:latest artifactapi.example.com/docker-internal/myapp:latest
+docker push        artifactapi.example.com/docker-internal/myapp:latest
+docker pull        artifactapi.example.com/docker-internal/myapp:latest
+```
+
+The first path segment after `/v2/` is the artifactapi repo name; the remainder
+is the image name. Blobs and manifests are stored through the shared
+content-addressable store (deduplicated by digest, reaped by GC once
+unreferenced); tags are mutable references and re-pushing a tag moves it. Blob
+uploads support both the monolithic and chunked (`POST`/`PATCH`/`PUT`) flows.

docs/docker/remote.md

@@ -0,0 +1,26 @@
+# `docker` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `docker` | tag manifests, `/tags/list` | blobs, digest manifests |
+
+## Terraform
+
+```hcl
+resource "artifactapi_remote_docker" "dockerhub" {
+  name     = "dockerhub"
+  base_url = "https://registry-1.docker.io"
+
+  immutable_ttl    = 0
+  mutable_ttl      = 300
+  ban_tags_enabled = true
+  ban_tags         = ["latest"]
+
+  patterns = [
+    "^library/postgres",
+    "^library/redis",
+  ]
+}
+```

docs/gems/remote.md

@@ -0,0 +1,7 @@
+# `gems` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `gems` | compact index (`versions`, `info/*`, `names`), `*specs.4.8.gz` | `gems/*.gem`, `quick/Marshal.4.8/*.gemspec.rz` |

docs/generic/remote.md

@@ -0,0 +1,28 @@
+# `generic` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `generic` | nothing | everything |
+
+## Terraform
+
+```hcl
+resource "artifactapi_remote_generic" "github" {
+  name     = "github"
+  base_url = "https://github.com"
+
+  immutable_ttl = 0
+  mutable_ttl   = 7200
+
+  patterns = [
+    "ducaale/xh/.*/xh-.*-x86_64-unknown-linux-musl.tar.gz$",
+    "mikefarah/yq/.*/yq_linux_amd64$",
+  ]
+
+  mutable_patterns = [
+    ".*/archive/refs/heads/.*\\.tar\\.gz$",
+  ]
+}
+```

docs/goproxy/remote.md

@@ -0,0 +1,7 @@
+# `goproxy` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `goproxy` | `@v/list`, `@latest` | `.info`, `.mod`, `.zip` |

docs/helm/local.md

@@ -0,0 +1,15 @@
+# Local helm repository
+
+A local `helm` repo is a real chart repository: `PUT` a packaged chart to
+`/api/v2/remotes/<repo>/files/<chart>-<version>.tgz` and `index.yaml` is
+generated from each chart's `Chart.yaml` (with sha256 digests) at
+`/api/v1/local/<repo>/index.yaml`; a file not named after its `Chart.yaml`
+name and version is stored but left out of the index. Add the local as a
+member of a helm virtual to serve it alongside remotes.
+
+```bash
+helm package ./mychart
+curl -fsSL --upload-file mychart-0.1.0.tgz \
+  https://artifactapi.example.com/api/v2/remotes/<repo>/files/mychart-0.1.0.tgz
+helm repo add <repo> https://artifactapi.example.com/api/v1/local/<repo>
+```

docs/helm/remote.md

@@ -0,0 +1,19 @@
+# `helm` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `helm` | `index.yaml` | `.tgz` charts |
+
+## Terraform
+
+```hcl
+resource "artifactapi_remote_helm" "jetstack" {
+  name     = "jetstack"
+  base_url = "https://charts.jetstack.io"
+
+  immutable_ttl = 0
+  mutable_ttl   = 3600
+}
+```

docs/helm/virtual.md

@@ -0,0 +1,9 @@
+# `helm` virtual
+
+```hcl
+resource "artifactapi_virtual" "helm" {
+  name         = "helm"
+  package_type = "helm"
+  members      = [artifactapi_remote_helm.jetstack.name]
+}
+```

docs/npm/local.md

@@ -0,0 +1,14 @@
+# Local npm registry
+
+A local `npm` repo is a real npm registry: `npm publish` (scoped and unscoped)
+and `npm install` work against `/api/v1/local/<repo>/`. npm requires an
+`_authToken` for the registry before it will publish; any value works.
+
+```ini
+# .npmrc
+registry=https://artifactapi.example.com/api/v1/local/<repo>/
+//artifactapi.example.com/api/v1/local/<repo>/:_authToken=unused
+```
+
+Versions are immutable: republishing an existing version is rejected. The
+dist-tags sent with a publish (`latest`, or `--tag`) move to that version.

docs/npm/remote.md

@@ -0,0 +1,7 @@
+# `npm` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `npm` | package metadata | `.tgz` tarballs |

docs/npm/virtual.md

@@ -0,0 +1,30 @@
+# `npm` virtual
+
+An npm virtual serves one registry over local and remote npm members:
+`npm install` and `npm view` work against `/api/v1/virtual/<name>/`.
+
+- Versions are the union across members; on a duplicate version the earlier
+  member wins.
+- Each dist-tag comes from the first member defining it, and is dropped if it
+  names a version missing from the merged set.
+- Tarball URLs point at the virtual (`<member>/<path>`), which 302s to the
+  owning member.
+- Full and abbreviated (`application/vnd.npm.install-v1+json`) packuments are
+  both served.
+- A member error fails the request with 502; a member without the package is
+  skipped. Merges are cached for 60s per package.
+
+```hcl
+resource "artifactapi_virtual" "npm" {
+  name         = "npm"
+  package_type = "npm"
+  members      = [artifactapi_local_npm.internal.name, artifactapi_remote_npm.npmjs.name]
+}
+```
+
+```ini
+# .npmrc
+registry=https://artifactapi.example.com/api/v1/virtual/npm/
+```
+
+Publish to the local member directly; the virtual is read-only.

docs/nuget/remote.md

@@ -0,0 +1,7 @@
+# `nuget` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `nuget` | `index.json` (service index), registration and flat container indexes | `.nupkg`, `.snupkg`, `.nuspec`, `readme`, `icon` |

docs/puppet/local.md

@@ -0,0 +1,14 @@
+# Local puppet forge
+
+A local `puppet` repo is a Forge: `PUT` a module tarball to
+`/api/v2/remotes/<repo>/files/<owner>-<module>-<version>.tar.gz` and the Forge
+v3 API (`/v3/modules`, `/v3/releases`, `/v3/files`) is served from each
+release's `metadata.json` at `/api/v1/local/<repo>`. Versions are immutable.
+
+```bash
+puppet module build ./hello
+curl -fsSL --upload-file pkg/unkin-hello-0.1.0.tar.gz \
+  https://artifactapi.example.com/api/v2/remotes/<repo>/files/unkin-hello-0.1.0.tar.gz
+puppet module install unkin-hello \
+  --module_repository https://artifactapi.example.com/api/v1/local/<repo>
+```

docs/puppet/remote.md

@@ -0,0 +1,7 @@
+# `puppet` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `puppet` | `v3/modules/*`, `v3/releases*` | `.tar.gz` |

docs/pypi/remote.md

@@ -0,0 +1,7 @@
+# `pypi` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `pypi` | `simple/*` index pages | `.whl`, `.tar.gz` |

docs/rpm/remote-github.md

@@ -0,0 +1,82 @@
+# `github_rpm` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `github_rpm` | `repodata/*` (synthesized) | `.rpm` (redirected) |
+
+## GitHub releases as a yum repo (metadata-only, no precache)
+
+A `github_rpm` remote turns a GitHub repo's **releases** into a real `dnf`/`yum`
+repository without ever caching the packages. It scans releases for `.rpm`
+assets, derives each package's metadata (NEVRA, requires/provides/conflicts/
+obsoletes, files, checksum) and **synthesizes `repodata/` on the fly**. Package
+metadata comes from a **ranged GET of just the RPM header** (the header sits at
+the front of the file, so the whole package is never downloaded); the sha256
+checksum comes from the GitHub asset `digest` when present, else a one-time
+lazy stream. Derived metadata is cached (keyed by asset) so repodata generation
+is served from primed DB rows, never a cold on-demand derive.
+
+Each package's `<location>` points back at the remote, which **302-redirects**
+the download to the `releases_remote` — an existing generic `github.com` remote
+that streams the actual bytes. `dnf` follows the redirect transparently.
+
+### Background syncer
+
+A single process-wide **background syncer** keeps every `github_rpm` remote's
+derived metadata current off the client request path:
+
+- **Prime on create.** Creating a `github_rpm` remote enqueues a background prime
+  scan, so its metadata is derived right away without blocking the create call.
+  The first `dnf` request is served from cache. If a request arrives before the
+  prime lands, it returns a retryable `503` (with `Retry-After`) rather than
+  serving an empty repo or blocking on a multi-minute derive.
+- **Periodic re-check, driven by `mutable_ttl`.** Each remote is re-checked for
+  new or changed releases no more often than its `mutable_ttl`. New/changed
+  assets are derived incrementally; assets already cached are never re-fetched,
+  and assets that disappear upstream are pruned.
+- **ETag / 304 conditional requests.** The releases-list `ETag` is stored per
+  remote and sent as `If-None-Match`; a `304 Not Modified` means nothing changed
+  and the syncer derives nothing. GitHub does not count `304` conditional
+  responses against the rate limit, so an unchanged repo is nearly free — this is
+  the main lever keeping GitHub traffic low.
+- **Global rate limit.** Every GitHub call (releases list + each ranged asset
+  header GET) passes through a single token-bucket limiter **shared across all
+  remotes**, so GitHub is never hammered. Configure a token (`password`) on the
+  remote for the higher authenticated rate limit (~5000/hr vs ~60/hr
+  unauthenticated).
+- **Multi-replica coordination.** State is shared through the database. Before a
+  periodic scan a replica must atomically claim a per-remote lease
+  (`github_rpm_sync_state`: `last_synced_at`, `etag`, `sync_lease_owner`,
+  `sync_lease_expires`); only the winner scans. This bounds total GitHub load to
+  ~once per `mutable_ttl` regardless of replica count, and the shared `etag`
+  lets any replica issue the conditional request.
+
+```hcl
+# Backend that serves the actual .rpm bytes from github.com.
+resource "artifactapi_remote_generic" "github" {
+  name     = "github"
+  base_url = "https://github.com"
+  patterns = [
+    "acme/tools/releases/download/.*\\.rpm$", # allowlist the repo's release assets
+  ]
+}
+
+resource "artifactapi_remote_github_rpm" "acme-tools" {
+  name            = "acme-tools"
+  base_url        = "https://api.github.com/repos/acme/tools" # the releases API root
+  releases_remote = "github"                                  # backend for downloads
+  mutable_ttl     = 3600                                      # release re-scan interval
+
+  # Optional: restrict which release assets become packages (regex on filename).
+  patterns = [".*\\.x86_64\\.rpm$", ".*\\.noarch\\.rpm$"]
+
+  # Optional: a token for private repos / higher API rate limits.
+  # password = "ghp_..."
+}
+```
+
+`dnf` config: `baseurl=https://artifactapi.example/api/v1/remote/acme-tools`.
+The repo is multi-arch (no `$basearch` needed) — `dnf` selects matching packages
+from the synthesized metadata.

docs/rpm/remote.md

@@ -0,0 +1,7 @@
+# `rpm` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `rpm` | `repomd.xml`, `repodata/*` | `.rpm` |

docs/terraform/local.md

@@ -0,0 +1,29 @@
+# Serving providers as a registry
+
+A local `terraform` repo is a real provider registry: upload
+`terraform-provider-{type}_{version}_{os}_{arch}.zip` files under
+`{namespace}/{type}/`, and Terraform installs them from a bare source address —
+no `.terraformrc` mirror config:
+
+```hcl
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "artifactapi.example.com/<repo>/<type>"
+      version = "0.1.2"
+    }
+  }
+}
+```
+
+The Terraform *namespace* segment is the artifactapi repo name; the provider is
+matched by *type*. The registry serves service discovery
+(`/.well-known/terraform.json`), the `providers.v1` version/download endpoints,
+and a GPG-signed `SHA256SUMS` per the provider registry protocol.
+
+Signing needs a GPG key. By default artifactapi generates one on first start and
+stores it in the database (`signing_keys` table), so every replica shares it and
+there's nothing to provision. To bring your own key instead, point
+`TF_SIGNING_KEY_PATH` at an armored private key (optionally
+`TF_SIGNING_KEY_PASSPHRASE`), which takes precedence over the generated one.
+`TF_PROVIDER_PROTOCOLS` (default `5.0,6.0`) sets the advertised plugin protocols.

docs/terraform/remote.md

@@ -0,0 +1,7 @@
+# `terraform` remote
+
+Shared classification, TTL and eviction rules: [caching](../common/caching.md).
+
+| Type | Mutable (auto-detected) | Immutable (auto-detected) |
+|---|---|---|
+| `terraform` | `*/versions` | `*/download/*/*` |

e2e-docker/README.md

@@ -0,0 +1,54 @@
+# Dockerised end-to-end suite
+
+Black-box tests that run against a fully **containerised** artifactapi stack
+(built image + Postgres + Redis + MinIO) plus a static mock upstream. Unlike the
+in-process `e2e/` suite (testcontainers, server run in-process), these only speak
+HTTP to the running product, so they exercise the shipped container image.
+
+## Run
+
+```bash
+make docker-e2e          # build image, compose up, run suite, compose down
+```
+
+`scripts/docker-e2e.sh` builds and starts `docker-compose.yml` +
+`docker-compose.e2e.yml`, waits for `/health`, then runs
+`go test -tags=dockere2e ./e2e-docker/...` and tears everything down.
+
+The stack publishes artifactapi on host port **8001** (to avoid colliding with a
+local instance on 8000). Override with `ARTIFACTAPI_URL` to point the tests at an
+already-running stack.
+
+## Coverage
+
+- **Repository lifecycle** — add / change / delete for remote, local and virtual repos.
+- **Caching** — one immutable artifact per remote package type (one
+  `caching_<type>_test.go` case each) proxied through the mock upstream: first fetch `X-Artifact-Source: remote`, second `cache`, bytes
+  verified against the origin fixture.
+- **Local uploads** — puppet (Forge v3 API via real `r10k` and `puppet module install`),
+  generic (upload/download), pypi (wheel + generated `simple/`
+  index), rpm (real package + **automatic repodata** generation), npm (stock
+  `node:22` client: `npm publish` unscoped + scoped, `npm install` + `require()`,
+  second version, republish rejected).
+- **Virtual repositories** — pypi simple-index merge and helm `index.yaml` merge
+  across two members; npm packument merge over two locals via a stock `node:22`
+  client (merged versions, install through the member redirect).
+- **Mirrorlist** — an rpm remote with a `mirrorlist` of extra upstream mirrors
+  (pool = `base_url` + `mirrorlist`): round-robin distribution across both mirrors
+  (constant-body `mockupstreama` / `mockupstreamb`), failover past a dead primary,
+  no-mirrorlist regression, and a real `dnf` (stock `rockylinux:9` container)
+  `makecache` + `install` through a two-mirror rpm remote whose `base_url` is dead
+  — a dead mirror must not break the client.
+- **Mirror strategy (`least_conn`)** — a `mirror_strategy: least_conn` rpm remote
+  over the two constant-body mirrors exercises the least-connections selection
+  path end-to-end (both mirrors serve, all requests succeed), plus a real `dnf`
+  install through a `least_conn` remote with a dead primary (failover unchanged).
+  The precise least-loaded pick is asserted deterministically in the proxy unit
+  test, since an in-flight-skew assertion over HTTP is timing-sensitive.
+
+## Fixtures
+
+`fixtures/` is served by the mock upstream at its web root. Paths mirror each
+provider's upstream URL layout (e.g. `v2/...` for docker, `v1/providers/...` for
+terraform). The RPM under `fixtures/rpmrepo/Packages/` is a real package so the
+rpm provider can parse its metadata for repodata generation.

e2e-docker/caching_alpine_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"alpine", "alpine/x86_64/testpkg-1.0-r0.apk", "alpine/x86_64/testpkg-1.0-r0.apk"})
+}

e2e-docker/caching_cargo_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"cargo", "crates/mycrate/mycrate-1.0.0.crate", "crates/mycrate/mycrate-1.0.0.crate"})
+}

e2e-docker/caching_docker_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"docker", "library/testimg/blobs/blobdata", "v2/library/testimg/blobs/blobdata"})
+}

e2e-docker/caching_gems_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"gems", "gems/mygem-1.0.0.gem", "gems/mygem-1.0.0.gem"})
+}

e2e-docker/caching_generic_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"generic", "blobs/hello.bin", "blobs/hello.bin"})
+}

e2e-docker/caching_goproxy_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"goproxy", "goproxy/example.com/mod/@v/v1.0.0.zip", "goproxy/example.com/mod/@v/v1.0.0.zip"})
+}

e2e-docker/caching_helm_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"helm", "charts/mychart-1.0.0.tgz", "charts/mychart-1.0.0.tgz"})
+}

e2e-docker/caching_npm_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"npm", "mypkg/-/mypkg-1.0.0.tgz", "mypkg/-/mypkg-1.0.0.tgz"})
+}

e2e-docker/caching_nuget_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"nuget", "nuget/e2epkg/1.0.0/e2epkg.1.0.0.nupkg", "nuget/e2epkg/1.0.0/e2epkg.1.0.0.nupkg"})
+}

e2e-docker/caching_puppet_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"puppet", "puppet-releases/author-mod-1.0.0.tar.gz", "puppet-releases/author-mod-1.0.0.tar.gz"})
+}

e2e-docker/caching_pypi_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"pypi", "packages/foo-1.0-py3-none-any.whl", "packages/foo-1.0-py3-none-any.whl"})
+}

e2e-docker/caching_rpm_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"rpm", "rpmrepo/Packages/e2e-testpkg-1.0-1.noarch.rpm", "rpmrepo/Packages/e2e-testpkg-1.0-1.noarch.rpm"})
+}

e2e-docker/caching_terraform_test.go

@@ -0,0 +1,7 @@
+//go:build dockere2e
+
+package e2edocker
+
+func init() {
+	cachingCases = append(cachingCases, cachingCase{"terraform", "hashicorp/aws/download/pkg.zip", "v1/providers/hashicorp/aws/download/pkg.zip"})
+}

e2e-docker/caching_test.go

@@ -0,0 +1,68 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"testing"
+)
+
+type cachingCase struct {
+	pkgType string
+	// path is the request path under /api/v1/remote/<name>/. The provider
+	// derives the upstream URL from it (docker prepends /v2/, terraform
+	// prepends /v1/providers/), and the fixture lives at that resolved path.
+	path    string
+	fixture string
+}
+
+// cachingCases is filled by one caching_<type>_test.go file per package type.
+var cachingCases []cachingCase
+
+// TestCachingPerProvider proxies one immutable artifact for every remote
+// package type through the mock upstream and asserts: first fetch is served
+// from the remote, the second from cache, and the bytes match the origin.
+func TestCachingPerProvider(t *testing.T) {
+	for _, tc := range cachingCases {
+		t.Run(tc.pkgType, func(t *testing.T) {
+			name := "cache-" + tc.pkgType
+			createRepo(t, fmt.Sprintf(`{
+				"name": %q,
+				"package_type": %q,
+				"repo_type": "remote",
+				"base_url": %q,
+				"stale_on_error": true
+			}`, name, tc.pkgType, mockUpstream()))
+			defer deleteRepo(t, name)
+
+			want := fixtureBytes(t, tc.fixture)
+			url := api("/api/v1/remote/" + name + "/" + tc.path)
+
+			// First fetch: from remote.
+			resp, body := doRequest(t, http.MethodGet, url, nil, "")
+			if resp.StatusCode != http.StatusOK {
+				t.Fatalf("first fetch: status %d: %s", resp.StatusCode, body)
+			}
+			if src := resp.Header.Get("X-Artifact-Source"); src != "remote" {
+				t.Fatalf("first fetch source = %q, want remote", src)
+			}
+			if !bytes.Equal(body, want) {
+				t.Fatalf("first fetch body mismatch: got %d bytes, want %d", len(body), len(want))
+			}
+
+			// Second fetch: from cache, identical bytes.
+			resp, body = doRequest(t, http.MethodGet, url, nil, "")
+			if resp.StatusCode != http.StatusOK {
+				t.Fatalf("second fetch: status %d: %s", resp.StatusCode, body)
+			}
+			if src := resp.Header.Get("X-Artifact-Source"); src != "cache" {
+				t.Fatalf("second fetch source = %q, want cache", src)
+			}
+			if !bytes.Equal(body, want) {
+				t.Fatalf("cached body mismatch: got %d bytes, want %d", len(body), len(want))
+			}
+		})
+	}
+}

e2e-docker/docker_local_test.go

@@ -0,0 +1,177 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func digestOf(b []byte) string {
+	sum := sha256.Sum256(b)
+	return "sha256:" + hex.EncodeToString(sum[:])
+}
+
+// pushBlobMonolithic uploads a blob with POST (open session) then PUT?digest
+// (whole body) — the monolithic-after-POST flow.
+func pushBlobMonolithic(t *testing.T, repo, image string, blob []byte) {
+	t.Helper()
+	dgst := digestOf(blob)
+
+	resp, body := doRequest(t, http.MethodPost, api("/v2/"+repo+"/"+image+"/blobs/uploads/"), nil, "")
+	if resp.StatusCode != http.StatusAccepted {
+		t.Fatalf("start upload: status %d: %s", resp.StatusCode, body)
+	}
+	loc := resp.Header.Get("Location")
+	if loc == "" {
+		t.Fatalf("start upload: no Location header")
+	}
+
+	resp, body = doRequest(t, http.MethodPut, baseURL()+loc+"?digest="+dgst, blob, "application/octet-stream")
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("finish upload: status %d: %s", resp.StatusCode, body)
+	}
+	if got := resp.Header.Get("Docker-Content-Digest"); got != dgst {
+		t.Fatalf("finish upload: digest mismatch: got %q want %q", got, dgst)
+	}
+}
+
+// pushBlobChunked uploads a blob with POST then PATCH (body) then PUT?digest
+// (empty) — the chunked flow a real docker daemon uses.
+func pushBlobChunked(t *testing.T, repo, image string, blob []byte) {
+	t.Helper()
+	dgst := digestOf(blob)
+
+	resp, body := doRequest(t, http.MethodPost, api("/v2/"+repo+"/"+image+"/blobs/uploads/"), nil, "")
+	if resp.StatusCode != http.StatusAccepted {
+		t.Fatalf("start upload: status %d: %s", resp.StatusCode, body)
+	}
+	loc := resp.Header.Get("Location")
+
+	resp, body = doRequest(t, http.MethodPatch, baseURL()+loc, blob, "application/octet-stream")
+	if resp.StatusCode != http.StatusAccepted {
+		t.Fatalf("patch upload: status %d: %s", resp.StatusCode, body)
+	}
+	if got := resp.Header.Get("Range"); got != fmt.Sprintf("0-%d", len(blob)-1) {
+		t.Fatalf("patch upload: unexpected Range %q", got)
+	}
+	loc = resp.Header.Get("Location")
+
+	resp, body = doRequest(t, http.MethodPut, baseURL()+loc+"?digest="+dgst, nil, "")
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("finish upload: status %d: %s", resp.StatusCode, body)
+	}
+}
+
+// TestLocalDockerPushPull exercises a full container push and pull against a
+// local docker repo using the Docker Registry HTTP API V2, the way a docker
+// client would: upload the config and layer blobs, push the manifest under a
+// tag, then pull the manifest and blobs back byte-identically.
+func TestLocalDockerPushPull(t *testing.T) {
+	createRepo(t, `{"name":"docker-internal","package_type":"docker","repo_type":"local"}`)
+	defer deleteRepo(t, "docker-internal")
+
+	const image = "team/app"
+	const tag = "v1.0.0"
+
+	// /v2/ version check.
+	resp, _ := doRequest(t, http.MethodGet, api("/v2/"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("/v2/ ping: status %d", resp.StatusCode)
+	}
+
+	config := []byte(`{"architecture":"amd64","os":"linux","config":{},"rootfs":{"type":"layers","diff_ids":["sha256:0000000000000000000000000000000000000000000000000000000000000000"]}}`)
+	layer := bytes.Repeat([]byte("artifactapi-layer-data-"), 4096) // ~90 KB opaque layer
+
+	configDigest := digestOf(config)
+	layerDigest := digestOf(layer)
+
+	// A brand-new blob should be absent (this is the client's mount check).
+	resp, _ = doRequest(t, http.MethodHead, api("/v2/"+"docker-internal/"+image+"/blobs/"+configDigest), nil, "")
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("pre-push blob HEAD: expected 404, got %d", resp.StatusCode)
+	}
+
+	pushBlobMonolithic(t, "docker-internal", image, config)
+	pushBlobChunked(t, "docker-internal", image, layer)
+
+	manifest := []byte(fmt.Sprintf(`{"schemaVersion":2,"mediaType":"application/vnd.docker.distribution.manifest.v2+json","config":{"mediaType":"application/vnd.docker.container.image.v1+json","size":%d,"digest":%q},"layers":[{"mediaType":"application/vnd.docker.image.rootfs.diff.tar.gzip","size":%d,"digest":%q}]}`,
+		len(config), configDigest, len(layer), layerDigest))
+	manifestDigest := digestOf(manifest)
+	manifestType := "application/vnd.docker.distribution.manifest.v2+json"
+
+	resp, body := doRequest(t, http.MethodPut, api("/v2/docker-internal/"+image+"/manifests/"+tag), manifest, manifestType)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("push manifest: status %d: %s", resp.StatusCode, body)
+	}
+	if got := resp.Header.Get("Docker-Content-Digest"); got != manifestDigest {
+		t.Fatalf("push manifest: digest %q want %q", got, manifestDigest)
+	}
+
+	// --- pull back ---
+
+	// Manifest by tag.
+	resp, body = doRequest(t, http.MethodGet, api("/v2/docker-internal/"+image+"/manifests/"+tag), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("pull manifest by tag: status %d: %s", resp.StatusCode, body)
+	}
+	if !bytes.Equal(body, manifest) {
+		t.Fatalf("pulled manifest bytes differ from pushed")
+	}
+	if ct := resp.Header.Get("Content-Type"); ct != manifestType {
+		t.Fatalf("pulled manifest content-type %q want %q", ct, manifestType)
+	}
+	if got := resp.Header.Get("Docker-Content-Digest"); got != manifestDigest {
+		t.Fatalf("pulled manifest digest %q want %q", got, manifestDigest)
+	}
+
+	// Manifest by digest.
+	resp, body = doRequest(t, http.MethodGet, api("/v2/docker-internal/"+image+"/manifests/"+manifestDigest), nil, "")
+	if resp.StatusCode != http.StatusOK || !bytes.Equal(body, manifest) {
+		t.Fatalf("pull manifest by digest: status %d, equal=%v", resp.StatusCode, bytes.Equal(body, manifest))
+	}
+
+	// Blobs by digest.
+	for _, tc := range []struct {
+		name   string
+		digest string
+		want   []byte
+	}{
+		{"config", configDigest, config},
+		{"layer", layerDigest, layer},
+	} {
+		resp, body = doRequest(t, http.MethodGet, api("/v2/docker-internal/"+image+"/blobs/"+tc.digest), nil, "")
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("pull %s blob: status %d", tc.name, resp.StatusCode)
+		}
+		if !bytes.Equal(body, tc.want) {
+			t.Fatalf("pulled %s blob bytes differ", tc.name)
+		}
+		if got := resp.Header.Get("Docker-Content-Digest"); got != tc.digest {
+			t.Fatalf("pulled %s blob digest %q want %q", tc.name, got, tc.digest)
+		}
+	}
+
+	// tags/list reflects the pushed tag.
+	resp, body = doRequest(t, http.MethodGet, api("/v2/docker-internal/"+image+"/tags/list"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("tags/list: status %d: %s", resp.StatusCode, body)
+	}
+	if !strings.Contains(string(body), `"`+tag+`"`) {
+		t.Fatalf("tags/list missing tag %q: %s", tag, body)
+	}
+	if !strings.Contains(string(body), `"docker-internal/`+image+`"`) {
+		t.Fatalf("tags/list wrong repository name: %s", body)
+	}
+
+	// A now-present blob HEAD should succeed (client would skip re-upload).
+	resp, _ = doRequest(t, http.MethodHead, api("/v2/docker-internal/"+image+"/blobs/"+layerDigest), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("post-push blob HEAD: expected 200, got %d", resp.StatusCode)
+	}
+}

e2e-docker/fixtures/blobs/hello.bin

@@ -0,0 +1 @@
+hello artifactapi generic blob

e2e-docker/fixtures/gems/mygem-1.0.0.gem

@@ -0,0 +1 @@
+mygem-1.0.0 e2e fixture

e2e-docker/fixtures/helm-a/index.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+entries:
+  alpha:
+    - name: alpha
+      version: 1.0.0
+      urls:
+        - charts/alpha-1.0.0.tgz
+generated: "2026-01-01T00:00:00Z"

e2e-docker/fixtures/helm-b/index.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+entries:
+  beta:
+    - name: beta
+      version: 2.0.0
+      urls:
+        - charts/beta-2.0.0.tgz
+generated: "2026-01-01T00:00:00Z"

e2e-docker/fixtures/rpm-mirror/repodata/repomd.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<repomd xmlns="http://linux.duke.edu/metadata/repo" xmlns:rpm="http://linux.duke.edu/metadata/rpm">
+  <revision>1786573032</revision>
+  <data type="primary">
+    <checksum type="sha256">d82f717e4da1afe96b8e7857de9e852f5785c0d75734e50d0f8afdcbc6261b08</checksum>
+    <open-checksum type="sha256">3345bb631380ae6c0620fe2a29cf7dff2ed4e28c5cb06c91e8a1628ba1979bcb</open-checksum>
+    <location href="repodata/d82f717e4da1afe96b8e7857de9e852f5785c0d75734e50d0f8afdcbc6261b08-primary.xml.gz"/>
+    <timestamp>1786573032</timestamp>
+    <size>631</size>
+    <open-size>1192</open-size>
+  </data>
+  <data type="filelists">
+    <checksum type="sha256">daa313cc5eeb7df556e1d4885d7701b10b9f012f436ef239fa46827f966222be</checksum>
+    <open-checksum type="sha256">648bd0ce00fda09abbc6e9c3ff3278518a76f258576ac24cd10c12e41e0e5bd7</open-checksum>
+    <location href="repodata/daa313cc5eeb7df556e1d4885d7701b10b9f012f436ef239fa46827f966222be-filelists.xml.gz"/>
+    <timestamp>1786573032</timestamp>
+    <size>256</size>
+    <open-size>338</open-size>
+  </data>
+  <data type="other">
+    <checksum type="sha256">8510c74a6f288828bbc92abee5d0d8ae9687d3c31a2579ea95e31a4c3a320d85</checksum>
+    <open-checksum type="sha256">c42cfd3843e9c53a60ad84bded44aa46c65faae7b3da99a099a9ca0b018872a9</open-checksum>
+    <location href="repodata/8510c74a6f288828bbc92abee5d0d8ae9687d3c31a2579ea95e31a4c3a320d85-other.xml.gz"/>
+    <timestamp>1786573032</timestamp>
+    <size>296</size>
+    <open-size>399</open-size>
+  </data>
+  <data type="primary_db">
+    <checksum type="sha256">f6bd7755da13d9726381048f467992869104a4c5521338ef740dc35eb85b9b71</checksum>
+    <open-checksum type="sha256">c45c85d12ccb0f8172b7bfae466362c08ac1867559574a9fb9cb2118c04daddb</open-checksum>
+    <location href="repodata/f6bd7755da13d9726381048f467992869104a4c5521338ef740dc35eb85b9b71-primary.sqlite.bz2"/>
+    <timestamp>1786573032</timestamp>
+    <size>1740</size>
+    <open-size>106496</open-size>
+    <database_version>10</database_version>
+  </data>
+  <data type="filelists_db">
+    <checksum type="sha256">be3c6e4c7a13ece48bd5d6a4d6d5e6a2395fe006ef9c5f217f5b87144f465e57</checksum>
+    <open-checksum type="sha256">1ccfa3dff532d782ce3225aae807506a4ce4534291386f1c47455dcc6b70cfd6</open-checksum>
+    <location href="repodata/be3c6e4c7a13ece48bd5d6a4d6d5e6a2395fe006ef9c5f217f5b87144f465e57-filelists.sqlite.bz2"/>
+    <timestamp>1786573032</timestamp>
+    <size>764</size>
+    <open-size>28672</open-size>
+    <database_version>10</database_version>
+  </data>
+  <data type="other_db">
+    <checksum type="sha256">ba593cd8ab5ec1e127888707c1fd882920996f1ce173fd7a589d647918fd7da4</checksum>
+    <open-checksum type="sha256">5d4d38380f0e359bfc0a50033d4faa84c75c5ae8fe2ef11c1c82d64748e9b8e2</open-checksum>
+    <location href="repodata/ba593cd8ab5ec1e127888707c1fd882920996f1ce173fd7a589d647918fd7da4-other.sqlite.bz2"/>
+    <timestamp>1786573032</timestamp>
+    <size>738</size>
+    <open-size>24576</open-size>
+    <database_version>10</database_version>
+  </data>
+</repomd>

e2e-docker/helm_local_test.go

@@ -0,0 +1,71 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestLocalHelmRealClient packages a chart with the real helm CLI, publishes it
+// to a helm local, then drives helm repo add/search/pull/template against the
+// local and against a helm virtual that has the local as a member.
+func TestLocalHelmRealClient(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := strings.TrimRight(os.Getenv("ARTIFACTAPI_INTERNAL"), "/")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	createRepo(t, `{"name":"local-helm","package_type":"helm","repo_type":"local"}`)
+	defer deleteRepo(t, "local-helm")
+	createVirtual(t, `{"name":"vhelm","package_type":"helm","members":["local-helm"]}`)
+	defer deleteVirtual(t, "vhelm")
+
+	helm := func(script string) string {
+		t.Helper()
+		out, err := exec.Command("docker", "run", "--rm", "--network", network, "--entrypoint", "sh",
+			"alpine/helm:3.16.4", "-c", "set -eu; "+script).Output()
+		if err != nil {
+			stderr := ""
+			if ee, ok := err.(*exec.ExitError); ok {
+				stderr = string(ee.Stderr)
+			}
+			t.Fatalf("helm script failed: %v\n%s%s", err, out, stderr)
+		}
+		return string(out)
+	}
+
+	chart := helm("cd /tmp && helm create e2echart >/dev/null && helm package e2echart >/dev/null && cat e2echart-0.1.0.tgz")
+	uploadFile(t, "local-helm", "e2echart-0.1.0.tgz", []byte(chart), "application/gzip")
+
+	// Chart metadata is recorded asynchronously after upload; poll the index.
+	var body []byte
+	for deadline := time.Now().Add(15 * time.Second); time.Now().Before(deadline); time.Sleep(500 * time.Millisecond) {
+		var resp *http.Response
+		resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-helm/index.yaml"), nil, "")
+		if resp.StatusCode == http.StatusOK && strings.Contains(string(body), "e2echart-0.1.0.tgz") {
+			break
+		}
+	}
+	if !strings.Contains(string(body), "e2echart-0.1.0.tgz") || !strings.Contains(string(body), "digest: ") {
+		t.Fatalf("index.yaml never listed the chart:\n%s", body)
+	}
+
+	for _, repoURL := range []string{internal + "/api/v1/local/local-helm", internal + "/api/v1/virtual/vhelm"} {
+		out := helm("helm repo add e2e " + repoURL + " >/dev/null && " +
+			"helm search repo e2e/e2echart && " +
+			"cd /tmp && helm pull e2e/e2echart --version 0.1.0 && " +
+			"helm template rel e2echart-0.1.0.tgz | grep -c 'kind: Deployment'")
+		if !strings.Contains(out, "e2e/e2echart") || !strings.Contains(out, "0.1.0") || !strings.HasSuffix(strings.TrimSpace(out), "1") {
+			t.Fatalf("helm via %s:\n%s", repoURL, out)
+		}
+	}
+}

e2e-docker/helpers_test.go

@@ -0,0 +1,108 @@
+//go:build dockere2e
+
+// Package e2edocker holds the black-box end-to-end suite that runs against a
+// fully dockerised artifactapi stack (see scripts/docker-e2e.sh). Unlike the
+// in-process e2e suite, these tests only speak HTTP to the running container.
+package e2edocker
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func baseURL() string {
+	if v := os.Getenv("ARTIFACTAPI_URL"); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return "http://localhost:8000"
+}
+
+// mockUpstream is the base URL the artifactapi *container* uses to reach the
+// static mock upstream. It is resolved on the compose network, not the host.
+func mockUpstream() string {
+	if v := os.Getenv("MOCK_UPSTREAM_INTERNAL"); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return "http://mockupstream"
+}
+
+func api(path string) string { return baseURL() + path }
+
+func fixtureBytes(t *testing.T, rel string) []byte {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join("fixtures", rel))
+	if err != nil {
+		t.Fatalf("read fixture %s: %v", rel, err)
+	}
+	return b
+}
+
+func doRequest(t *testing.T, method, url string, body []byte, contentType string) (*http.Response, []byte) {
+	t.Helper()
+	var r io.Reader
+	if body != nil {
+		r = bytes.NewReader(body)
+	}
+	req, err := http.NewRequest(method, url, r)
+	if err != nil {
+		t.Fatalf("%s %s: %v", method, url, err)
+	}
+	if contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("%s %s: %v", method, url, err)
+	}
+	defer resp.Body.Close()
+	respBody, _ := io.ReadAll(resp.Body)
+	return resp, respBody
+}
+
+func createRepo(t *testing.T, jsonBody string) {
+	t.Helper()
+	resp, body := doRequest(t, http.MethodPost, api("/api/v2/remotes"), []byte(jsonBody), "application/json")
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("create repo: status %d: %s", resp.StatusCode, body)
+	}
+}
+
+func deleteRepo(t *testing.T, name string) {
+	t.Helper()
+	doRequest(t, http.MethodDelete, api("/api/v2/remotes/"+name), nil, "")
+}
+
+func createVirtual(t *testing.T, jsonBody string) {
+	t.Helper()
+	resp, body := doRequest(t, http.MethodPost, api("/api/v2/virtuals"), []byte(jsonBody), "application/json")
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("create virtual: status %d: %s", resp.StatusCode, body)
+	}
+}
+
+func deleteVirtual(t *testing.T, name string) {
+	t.Helper()
+	doRequest(t, http.MethodDelete, api("/api/v2/virtuals/"+name), nil, "")
+}
+
+// getEventually retries a GET until it returns 200 or the deadline passes. Used
+// for asynchronously-generated artifacts (e.g. rpm repodata after upload).
+func getEventually(t *testing.T, url string, timeout time.Duration) (*http.Response, []byte) {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	var resp *http.Response
+	var body []byte
+	for {
+		resp, body = doRequest(t, http.MethodGet, url, nil, "")
+		if resp.StatusCode == http.StatusOK || time.Now().After(deadline) {
+			return resp, body
+		}
+		time.Sleep(250 * time.Millisecond)
+	}
+}

e2e-docker/leastconn_test.go

@@ -0,0 +1,105 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestLeastConnMultiBaseURL configures an rpm remote with mirror_strategy =
+// least_conn over a two-mirror pool and drives distinct cache-miss paths through
+// it, asserting every request succeeds and both mirrors serve traffic. This
+// exercises the least-connections selection path (leastConnOrder + the in-flight
+// gauge inc/dec around each upstream call) end-to-end through a real HTTP client.
+// A precise least-loaded assertion is timing-sensitive over HTTP and is covered
+// deterministically by the proxy unit test (TestLeastConnPicksLeastLoaded);
+// here, with requests issued serially, in-flight counts return to zero between
+// them so equal-load mirrors are spread by the round-robin tie-break.
+func TestLeastConnMultiBaseURL(t *testing.T) {
+	name := "e2e-leastconn"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": %q,
+		"mirrorlist": [%q],
+		"mirror_strategy": "least_conn",
+		"stale_on_error": false
+	}`, name, mockUpstreamA(), mockUpstreamB()))
+	defer deleteRepo(t, name)
+
+	seenA, seenB := false, false
+	const n = 12
+	for i := 0; i < n; i++ {
+		url := api(fmt.Sprintf("/api/v1/remote/%s/lc/%d", name, i))
+		resp, body := doRequest(t, http.MethodGet, url, nil, "")
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("request %d: status %d: %s", i, resp.StatusCode, body)
+		}
+		switch strings.TrimSpace(string(body)) {
+		case "UPSTREAM-A":
+			seenA = true
+		case "UPSTREAM-B":
+			seenB = true
+		default:
+			t.Fatalf("request %d: unexpected body %q", i, body)
+		}
+	}
+	if !seenA || !seenB {
+		t.Fatalf("least_conn remote did not reach both upstreams: A=%v B=%v", seenA, seenB)
+	}
+}
+
+// TestLeastConnDnfInstall drives a real dnf (stock rockylinux container) at a
+// two-mirror rpm remote configured with mirror_strategy = least_conn whose
+// primary base_url is dead: makecache + install must succeed via the live mirror.
+// This proves a real package-manager client installs correctly through a
+// least_conn remote and that failover semantics are unchanged under the new
+// strategy. Requires the compose network exported by scripts/docker-e2e.sh.
+func TestLeastConnDnfInstall(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := os.Getenv("ARTIFACTAPI_INTERNAL")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	name := "e2e-leastconn-dnf"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": "http://mockupstream-dead:80",
+		"mirrorlist": [%q],
+		"mirror_strategy": "least_conn",
+		"stale_on_error": false
+	}`, name, mockUpstream()))
+	defer deleteRepo(t, name)
+
+	repoURL := strings.TrimRight(internal, "/") + "/api/v1/remote/" + name + "/rpm-mirror"
+	repoConf := fmt.Sprintf("[dnflc]\nname=dnflc\nbaseurl=%s\nenabled=1\ngpgcheck=0\nsslverify=0\nmetadata_expire=0\n", repoURL)
+	script := "set -euo pipefail; " +
+		"printf '%s' \"$REPO\" > /etc/yum.repos.d/dnflc.repo; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnflc makecache; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnflc install e2e-testpkg; " +
+		"rpm -q e2e-testpkg"
+
+	cmd := exec.Command("docker", "run", "--rm",
+		"--network", network,
+		"-e", "REPO="+repoConf,
+		"rockylinux:9", "bash", "-c", script)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("real dnf install through a least_conn remote failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(string(out), "e2e-testpkg-1.0-1") {
+		t.Fatalf("dnf did not install the expected package via least_conn remote; output:\n%s", out)
+	}
+}

e2e-docker/local_test.go

@@ -0,0 +1,193 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+)
+
+func uploadFile(t *testing.T, repo, filePath string, body []byte, contentType string) {
+	t.Helper()
+	url := api("/api/v2/remotes/" + repo + "/files/" + filePath)
+	resp, respBody := doRequest(t, http.MethodPut, url, body, contentType)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("upload %s: status %d: %s", filePath, resp.StatusCode, respBody)
+	}
+}
+
+// TestLocalGenericUpload uploads a generic file and downloads it back.
+func TestLocalGenericUpload(t *testing.T) {
+	createRepo(t, `{"name":"local-generic","package_type":"generic","repo_type":"local"}`)
+	defer deleteRepo(t, "local-generic")
+
+	content := []byte("artifactapi local generic upload payload")
+	uploadFile(t, "local-generic", "data/hello.bin", content, "application/octet-stream")
+
+	resp, body := doRequest(t, http.MethodGet, api("/api/v1/local/local-generic/data/hello.bin"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("download: status %d: %s", resp.StatusCode, body)
+	}
+	if !bytes.Equal(body, content) {
+		t.Fatalf("downloaded content mismatch")
+	}
+}
+
+// TestLocalPyPIUpload uploads a wheel and validates the generated simple index.
+func TestLocalPyPIUpload(t *testing.T) {
+	createRepo(t, `{"name":"local-pypi","package_type":"pypi","repo_type":"local"}`)
+	defer deleteRepo(t, "local-pypi")
+
+	wheel := fixtureBytes(t, "packages/foo-1.0-py3-none-any.whl")
+	uploadFile(t, "local-pypi", "foo-1.0-py3-none-any.whl", wheel, "application/zip")
+
+	// Root index lists the package.
+	resp, body := doRequest(t, http.MethodGet, api("/api/v1/local/local-pypi/simple/"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("simple index: status %d: %s", resp.StatusCode, body)
+	}
+	if !strings.Contains(string(body), "foo") {
+		t.Fatalf("simple index missing package 'foo': %s", body)
+	}
+
+	// Per-package index lists the wheel file.
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-pypi/simple/foo/"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("package index: status %d: %s", resp.StatusCode, body)
+	}
+	if !strings.Contains(string(body), "foo-1.0-py3-none-any.whl") {
+		t.Fatalf("package index missing wheel: %s", body)
+	}
+
+	// The wheel downloads back byte-identical.
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-pypi/foo/foo-1.0-py3-none-any.whl"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("download wheel: status %d: %s", resp.StatusCode, body)
+	}
+	if !bytes.Equal(body, wheel) {
+		t.Fatalf("wheel content mismatch")
+	}
+}
+
+// TestLocalRPMRepodata uploads a real RPM and validates that repodata is
+// generated automatically (the special rpm-local feature).
+func TestLocalRPMRepodata(t *testing.T) {
+	createRepo(t, `{"name":"local-rpm","package_type":"rpm","repo_type":"local"}`)
+	defer deleteRepo(t, "local-rpm")
+
+	rpm := fixtureBytes(t, "rpmrepo/Packages/e2e-testpkg-1.0-1.noarch.rpm")
+	uploadFile(t, "local-rpm", "e2e-testpkg-1.0-1.noarch.rpm", rpm, "application/x-rpm")
+
+	// repodata is generated asynchronously after upload; poll for it.
+	resp, body := getEventually(t, api("/api/v1/local/local-rpm/repodata/repomd.xml"), 15*time.Second)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("repomd.xml: status %d: %s", resp.StatusCode, body)
+	}
+	s := string(body)
+	if !strings.Contains(s, "<repomd") || !strings.Contains(s, "primary") {
+		t.Fatalf("repomd.xml not a valid repodata document: %s", s)
+	}
+}
+
+// TestLocalDebRepo uploads a .deb and validates that the flat apt index
+// (Packages / Release) is generated automatically from the parsed control
+// stanza (the deb-local analog of rpm repodata generation).
+func TestLocalDebRepo(t *testing.T) {
+	createRepo(t, `{"name":"local-deb","package_type":"deb","repo_type":"local"}`)
+	defer deleteRepo(t, "local-deb")
+
+	deb := testsupport.MinimalDeb("e2e-testpkg", "1.0.0", "amd64")
+	uploadFile(t, "local-deb", "e2e-testpkg_1.0.0_amd64.deb", deb, "application/vnd.debian.binary-package")
+
+	// The index is generated asynchronously after upload; poll for it.
+	resp, body := getEventually(t, api("/api/v1/local/local-deb/Packages"), 15*time.Second)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("Packages: status %d: %s", resp.StatusCode, body)
+	}
+	pkgs := string(body)
+	for _, want := range []string{"Package: e2e-testpkg", "Version: 1.0.0", "Architecture: amd64", "Filename: pool/e2e-testpkg_1.0.0_amd64.deb", "SHA256:"} {
+		if !strings.Contains(pkgs, want) {
+			t.Fatalf("Packages missing %q:\n%s", want, pkgs)
+		}
+	}
+
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-deb/Release"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("Release: status %d: %s", resp.StatusCode, body)
+	}
+	rel := string(body)
+	for _, want := range []string{"Architectures: amd64", "SHA256:", "Packages"} {
+		if !strings.Contains(rel, want) {
+			t.Fatalf("Release missing %q:\n%s", want, rel)
+		}
+	}
+
+	// The .deb downloads back byte-identical from its pool path.
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-deb/pool/e2e-testpkg_1.0.0_amd64.deb"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("download deb: status %d: %s", resp.StatusCode, body)
+	}
+	if !bytes.Equal(body, deb) {
+		t.Fatalf("deb content mismatch")
+	}
+}
+
+// TestLocalAlpineIndex uploads an .apk to an alpine local repo and validates
+// that a per-arch APKINDEX.tar.gz is generated automatically from the parsed
+// .PKGINFO (the apk-local analog of rpm repodata / deb Packages generation).
+func TestLocalAlpineIndex(t *testing.T) {
+	createRepo(t, `{"name":"local-alpine","package_type":"alpine","repo_type":"local"}`)
+	defer deleteRepo(t, "local-alpine")
+
+	apk := testsupport.MinimalApk("e2e-testpkg", "1.0-r0", "x86_64")
+	uploadFile(t, "local-alpine", "x86_64/e2e-testpkg-1.0-r0.apk", apk, "application/vnd.android.package-archive")
+
+	// The index is generated asynchronously after upload; poll for it.
+	resp, body := getEventually(t, api("/api/v1/local/local-alpine/x86_64/APKINDEX.tar.gz"), 15*time.Second)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("APKINDEX: status %d: %s", resp.StatusCode, body)
+	}
+
+	zr, err := gzip.NewReader(bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("APKINDEX not gzip: %v", err)
+	}
+	tarBytes, _ := io.ReadAll(zr)
+	tr := tar.NewReader(bytes.NewReader(tarBytes))
+	var index string
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatalf("APKINDEX not tar: %v", err)
+		}
+		if hdr.Name == "APKINDEX" {
+			b, _ := io.ReadAll(tr)
+			index = string(b)
+		}
+	}
+	for _, want := range []string{"P:e2e-testpkg", "V:1.0-r0", "A:x86_64", "C:Q1", "S:", "I:"} {
+		if !strings.Contains(index, want) {
+			t.Fatalf("APKINDEX missing %q:\n%s", want, index)
+		}
+	}
+
+	// The .apk downloads back byte-identical from its arch path.
+	resp, body = doRequest(t, http.MethodGet, api("/api/v1/local/local-alpine/x86_64/e2e-testpkg-1.0-r0.apk"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("download apk: status %d: %s", resp.StatusCode, body)
+	}
+	if !bytes.Equal(body, apk) {
+		t.Fatalf("apk content mismatch")
+	}
+}

e2e-docker/mirror-conf/a.conf

@@ -0,0 +1,9 @@
+# Mock upstream A for the multi-base_url e2e: any path returns a constant,
+# upstream-identifying body so round-robin distribution is observable.
+server {
+    listen 80;
+    location / {
+        default_type text/plain;
+        return 200 "UPSTREAM-A";
+    }
+}

e2e-docker/mirror-conf/b.conf

@@ -0,0 +1,8 @@
+# Mock upstream B for the multi-base_url e2e (see a.conf).
+server {
+    listen 80;
+    location / {
+        default_type text/plain;
+        return 200 "UPSTREAM-B";
+    }
+}

e2e-docker/multibaseurl_test.go

@@ -0,0 +1,163 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// mockUpstreamA/B are the constant-body upstreams (see docker-compose.e2e.yml)
+// that let the round-robin test observe which mirror served each request.
+func mockUpstreamA() string {
+	if v := os.Getenv("MOCK_UPSTREAM_A_INTERNAL"); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return "http://mockupstreama"
+}
+
+func mockUpstreamB() string {
+	if v := os.Getenv("MOCK_UPSTREAM_B_INTERNAL"); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return "http://mockupstreamb"
+}
+
+// TestMultiBaseURLRoundRobin configures an rpm remote with base_url = mirror A
+// and mirrorlist = [mirror B] and drives distinct paths through it, asserting
+// both mirrors serve traffic. Each path is a cache miss, so every request reaches
+// upstream and the round-robin cursor alternates mirrors.
+func TestMultiBaseURLRoundRobin(t *testing.T) {
+	name := "e2e-rr"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": %q,
+		"mirrorlist": [%q],
+		"stale_on_error": false
+	}`, name, mockUpstreamA(), mockUpstreamB()))
+	defer deleteRepo(t, name)
+
+	seenA, seenB := false, false
+	const n = 12
+	for i := 0; i < n; i++ {
+		url := api(fmt.Sprintf("/api/v1/remote/%s/rr/%d", name, i))
+		resp, body := doRequest(t, http.MethodGet, url, nil, "")
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("request %d: status %d: %s", i, resp.StatusCode, body)
+		}
+		switch strings.TrimSpace(string(body)) {
+		case "UPSTREAM-A":
+			seenA = true
+		case "UPSTREAM-B":
+			seenB = true
+		default:
+			t.Fatalf("request %d: unexpected body %q", i, body)
+		}
+	}
+	if !seenA || !seenB {
+		t.Fatalf("round-robin did not reach both upstreams: A=%v B=%v", seenA, seenB)
+	}
+}
+
+// TestMultiBaseURLFailover points a two-mirror remote at a dead primary and a
+// healthy secondary and asserts every request still succeeds via the secondary.
+func TestMultiBaseURLFailover(t *testing.T) {
+	name := "e2e-failover"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": "http://mockupstream-dead:80",
+		"mirrorlist": [%q],
+		"stale_on_error": false
+	}`, name, mockUpstreamB()))
+	defer deleteRepo(t, name)
+
+	for i := 0; i < 6; i++ {
+		url := api(fmt.Sprintf("/api/v1/remote/%s/fo/%d", name, i))
+		resp, body := doRequest(t, http.MethodGet, url, nil, "")
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("request %d: dead primary broke fetch: status %d: %s", i, resp.StatusCode, body)
+		}
+		if got := strings.TrimSpace(string(body)); got != "UPSTREAM-B" {
+			t.Fatalf("request %d: body %q, want UPSTREAM-B (served via failover)", i, got)
+		}
+	}
+}
+
+// TestSingleBaseURLRegression asserts a remote with no mirrorlist works exactly
+// as before the mirrorlist change.
+func TestSingleBaseURLRegression(t *testing.T) {
+	name := "e2e-single"
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": %q,
+		"stale_on_error": false
+	}`, name, mockUpstreamA()))
+	defer deleteRepo(t, name)
+
+	resp, body := doRequest(t, http.MethodGet, api("/api/v1/remote/"+name+"/solo/0"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("single-url fetch: status %d: %s", resp.StatusCode, body)
+	}
+	if got := strings.TrimSpace(string(body)); got != "UPSTREAM-A" {
+		t.Fatalf("single-url body %q, want UPSTREAM-A", got)
+	}
+}
+
+// TestMultiBaseURLDnfFailover drives a real dnf (stock rockylinux container) at
+// a two-mirror rpm remote whose primary is dead: makecache + install must
+// succeed via the live secondary mirror, proving a dead mirror does not break a
+// real package-manager client. Requires the compose network and internal API
+// URL exported by scripts/docker-e2e.sh; skipped when run standalone.
+func TestMultiBaseURLDnfFailover(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := os.Getenv("ARTIFACTAPI_INTERNAL")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	name := "e2e-dnf-failover"
+	// Primary base_url is dead; the live mirror serves the real yum repo under
+	// fixtures/rpm-mirror via the shared mock upstream.
+	createRepo(t, fmt.Sprintf(`{
+		"name": %q,
+		"package_type": "rpm",
+		"repo_type": "remote",
+		"base_url": "http://mockupstream-dead:80",
+		"mirrorlist": [%q],
+		"stale_on_error": false
+	}`, name, mockUpstream()))
+	defer deleteRepo(t, name)
+
+	repoURL := strings.TrimRight(internal, "/") + "/api/v1/remote/" + name + "/rpm-mirror"
+	repoConf := fmt.Sprintf("[dnffo]\nname=dnffo\nbaseurl=%s\nenabled=1\ngpgcheck=0\nsslverify=0\nmetadata_expire=0\n", repoURL)
+	script := "set -euo pipefail; " +
+		"printf '%s' \"$REPO\" > /etc/yum.repos.d/dnffo.repo; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnffo makecache; " +
+		"dnf -y --disablerepo='*' --enablerepo=dnffo install e2e-testpkg; " +
+		"rpm -q e2e-testpkg"
+
+	cmd := exec.Command("docker", "run", "--rm",
+		"--network", network,
+		"-e", "REPO="+repoConf,
+		"rockylinux:9", "bash", "-c", script)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("real dnf install through a dead primary mirror failed: %v\n%s", err, out)
+	}
+	if !strings.Contains(string(out), "e2e-testpkg-1.0-1") {
+		t.Fatalf("dnf did not install the expected package via failover; output:\n%s", out)
+	}
+}

e2e-docker/npm_local_test.go

@@ -0,0 +1,62 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestLocalNPMPublishInstall drives a stock npm client against a local npm
+// repo: publish unscoped and scoped packages, install and require() them in a
+// fresh project, publish a second version, and reject a republish.
+func TestLocalNPMPublishInstall(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := os.Getenv("ARTIFACTAPI_INTERNAL")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	name := fmt.Sprintf("e2e-npm-local-%d", time.Now().UnixNano())
+	createRepo(t, fmt.Sprintf(`{"name":%q,"package_type":"npm","repo_type":"local"}`, name))
+	defer deleteRepo(t, name)
+
+	reg := strings.TrimRight(internal, "/") + "/api/v1/local/" + name + "/"
+	script := `set -euo pipefail
+printf 'registry=%s\n%s:_authToken=unused\n' "$REG" "${REG#http:}" > ~/.npmrc
+mk() { d="/w/src/$1-$2"; mkdir -p "$d"; cd "$d"
+  printf '{"name":"%s","version":"%s","main":"index.js"}' "$1" "$2" > package.json
+  echo "module.exports = '$1@$2';" > index.js; }
+mk e2e-npm-plain 1.0.0 && npm publish
+mk @e2e/npm-scoped 1.0.0 && npm publish
+mk e2e-npm-plain 1.0.0
+if npm publish 2>/dev/null; then echo "republish accepted"; exit 1; fi
+mkdir -p /w/app && cd /w/app && npm init -y >/dev/null
+npm install --no-audit --cache /tmp/fresh-cache e2e-npm-plain @e2e/npm-scoped
+node -e "console.log('REQ', require('e2e-npm-plain'), require('@e2e/npm-scoped'))"
+mk e2e-npm-plain 1.1.0 && npm publish
+echo "VERSIONS $(npm view e2e-npm-plain versions --json | tr -d ' \n')"
+echo "LATEST $(npm view e2e-npm-plain dist-tags.latest)"`
+
+	out, err := exec.Command("docker", "run", "--rm", "--network", network,
+		"-e", "REG="+reg, "node:22", "bash", "-c", script).CombinedOutput()
+	if err != nil {
+		t.Fatalf("npm client run failed: %v\n%s", err, out)
+	}
+	for _, want := range []string{
+		"REQ e2e-npm-plain@1.0.0 @e2e/npm-scoped@1.0.0",
+		`VERSIONS ["1.0.0","1.1.0"]`,
+		"LATEST 1.1.0",
+	} {
+		if !strings.Contains(string(out), want) {
+			t.Fatalf("missing %q in npm output:\n%s", want, out)
+		}
+	}
+}

e2e-docker/npm_virtual_test.go

@@ -0,0 +1,68 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestVirtualNPMInstall publishes to two local npm repos and drives a stock
+// npm client through a virtual over both: merged versions and dist-tags, and
+// an install whose tarballs resolve via the virtual's member redirect.
+func TestVirtualNPMInstall(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := os.Getenv("ARTIFACTAPI_INTERNAL")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	id := time.Now().UnixNano()
+	a, b, virt := fmt.Sprintf("e2e-npm-a-%d", id), fmt.Sprintf("e2e-npm-b-%d", id), fmt.Sprintf("e2e-npm-v-%d", id)
+	for _, name := range []string{a, b} {
+		createRepo(t, fmt.Sprintf(`{"name":%q,"package_type":"npm","repo_type":"local"}`, name))
+		defer deleteRepo(t, name)
+	}
+	createVirtual(t, fmt.Sprintf(`{"name":%q,"package_type":"npm","members":[%q,%q]}`, virt, a, b))
+	defer deleteVirtual(t, virt)
+
+	base := strings.TrimRight(internal, "/")
+	script := `set -euo pipefail
+pub() { d="/w/src/$2-$3-$1"; mkdir -p "$d"; cd "$d"
+  printf '{"name":"%s","version":"%s","main":"index.js"}' "$2" "$3" > package.json
+  echo "module.exports = '$1:$2@$3';" > index.js
+  printf 'registry=%s\n%s:_authToken=unused\n' "$BASE/api/v1/local/$1/" "${BASE#http:}/api/v1/local/$1/" > .npmrc
+  npm publish; }
+pub "$A" @e2e/virt 1.0.0
+pub "$B" @e2e/virt 1.0.0
+pub "$B" @e2e/virt 1.1.0
+mkdir -p /w/app && cd /w/app && npm init -y >/dev/null
+echo "registry=$BASE/api/v1/virtual/$V/" > .npmrc
+echo "VERSIONS $(npm view @e2e/virt versions --json | tr -d ' \n')"
+npm install --no-audit --cache /tmp/fresh-cache @e2e/virt@1.0.0
+node -e "console.log('REQ', require('@e2e/virt'))"
+echo "RESOLVED $(node -p "require('./package-lock.json').packages['node_modules/@e2e/virt'].resolved")"`
+
+	out, err := exec.Command("docker", "run", "--rm", "--network", network,
+		"-e", "BASE="+base, "-e", "A="+a, "-e", "B="+b, "-e", "V="+virt,
+		"node:22", "bash", "-c", script).CombinedOutput()
+	if err != nil {
+		t.Fatalf("npm client run failed: %v\n%s", err, out)
+	}
+	for _, want := range []string{
+		`VERSIONS ["1.0.0","1.1.0"]`,
+		"REQ " + a + ":@e2e/virt@1.0.0",
+		"RESOLVED " + base + "/api/v1/virtual/" + virt + "/" + a + "/@e2e/virt/-/virt-1.0.0.tgz",
+	} {
+		if !strings.Contains(string(out), want) {
+			t.Fatalf("missing %q in npm output:\n%s", want, out)
+		}
+	}
+}

e2e-docker/puppet_local_test.go

@@ -0,0 +1,88 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+	"time"
+)
+
+const puppetHelloMetadata = `{"name":"unkin-hello","version":"0.1.0","author":"unkin","summary":"e2e","license":"Apache-2.0","source":"https://example.invalid","dependencies":[{"name":"puppetlabs/stdlib","version_requirement":">= 4.0.0 < 10.0.0"}]}`
+
+func puppetModuleTarball(t *testing.T) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := gzip.NewWriter(&buf)
+	tw := tar.NewWriter(zw)
+	for name, body := range map[string]string{
+		"unkin-hello-0.1.0/metadata.json":     puppetHelloMetadata,
+		"unkin-hello-0.1.0/manifests/init.pp": "class hello {}\n",
+	} {
+		if err := tw.WriteHeader(&tar.Header{Name: name, Mode: 0o644, Size: int64(len(body)), ModTime: time.Now()}); err != nil {
+			t.Fatal(err)
+		}
+		_, _ = tw.Write([]byte(body))
+	}
+	_ = tw.Close()
+	_ = zw.Close()
+	return buf.Bytes()
+}
+
+// TestLocalPuppetRealClient publishes a module to a puppet local and installs
+// it with the real r10k and puppet module tool. The stdlib dependency is not on
+// a local-only forge, so puppet runs with --ignore-dependencies.
+func TestLocalPuppetRealClient(t *testing.T) {
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := strings.TrimRight(os.Getenv("ARTIFACTAPI_INTERNAL"), "/")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; run via scripts/docker-e2e.sh")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+
+	createRepo(t, `{"name":"local-puppet","package_type":"puppet","repo_type":"local"}`)
+	defer deleteRepo(t, "local-puppet")
+
+	upload := api("/api/v2/remotes/local-puppet/files/unkin-hello-0.1.0.tar.gz")
+	defer doRequest(t, http.MethodDelete, api("/api/v2/remotes/local-puppet/files/v3/files/unkin-hello-0.1.0.tar.gz"), nil, "")
+	tarball := puppetModuleTarball(t)
+	if resp, body := doRequest(t, http.MethodPut, upload, tarball, "application/gzip"); resp.StatusCode != http.StatusCreated {
+		t.Fatalf("upload: %d %s", resp.StatusCode, body)
+	}
+	if resp, _ := doRequest(t, http.MethodPut, upload, tarball, "application/gzip"); resp.StatusCode != http.StatusConflict {
+		t.Fatalf("re-upload of an existing version: %d, want 409", resp.StatusCode)
+	}
+	if resp, body := getEventually(t, api("/api/v1/local/local-puppet/v3/releases/unkin-hello-0.1.0"), 15*time.Second); resp.StatusCode != http.StatusOK || !strings.Contains(string(body), `"file_md5"`) {
+		t.Fatalf("release never indexed: %d %s", resp.StatusCode, body)
+	}
+
+	forge := internal + "/api/v1/local/local-puppet"
+	run := func(image, script string) string {
+		t.Helper()
+		out, err := exec.Command("docker", "run", "--rm", "--network", network, "--entrypoint", "sh", image, "-c", "set -eu; "+script).CombinedOutput()
+		if err != nil {
+			t.Fatalf("%s failed: %v\n%s", image, err, out)
+		}
+		return string(out)
+	}
+
+	out := run("ghcr.io/voxpupuli/r10k:latest", "cd /tmp && printf 'forge:\\n  baseurl: "+forge+"\\n' > r10k.yaml && "+
+		"printf \"forge '"+forge+"'\\nmod 'unkin-hello', '0.1.0'\\n\" > Puppetfile && "+
+		"r10k puppetfile install -c r10k.yaml --verbose && cat modules/hello/metadata.json")
+	if !strings.Contains(out, `"unkin-hello"`) {
+		t.Fatalf("r10k did not install unkin-hello:\n%s", out)
+	}
+
+	out = run("ghcr.io/openvoxproject/openvoxagent:latest", "export PATH=/opt/puppetlabs/bin:$PATH; puppet module install unkin-hello --module_repository "+forge+" --ignore-dependencies --target-dir /tmp/mods && puppet module list --color=false --modulepath /tmp/mods")
+	if !strings.Contains(out, "unkin-hello (v0.1.0)") {
+		t.Fatalf("puppet module install did not install unkin-hello:\n%s", out)
+	}
+}

e2e-docker/repos_test.go

@@ -0,0 +1,134 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+)
+
+func TestHealth(t *testing.T) {
+	resp, body := doRequest(t, http.MethodGet, api("/health"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("health: status %d: %s", resp.StatusCode, body)
+	}
+}
+
+// TestRemoteLifecycle covers add/change/delete for a remote repository.
+func TestRemoteLifecycle(t *testing.T) {
+	createRepo(t, `{
+		"name": "crud-remote",
+		"package_type": "generic",
+		"repo_type": "remote",
+		"base_url": "https://example.com",
+		"mutable_ttl": 600,
+		"stale_on_error": true
+	}`)
+	defer deleteRepo(t, "crud-remote")
+
+	got := getRepo(t, "crud-remote")
+	if got["base_url"] != "https://example.com" || got["mutable_ttl"].(float64) != 600 {
+		t.Fatalf("unexpected created remote: %v", got)
+	}
+
+	// change
+	resp, body := doRequest(t, http.MethodPut, api("/api/v2/remotes/crud-remote"), []byte(`{
+		"package_type": "generic",
+		"base_url": "https://updated.example.com",
+		"mutable_ttl": 120,
+		"stale_on_error": true
+	}`), "application/json")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("update remote: status %d: %s", resp.StatusCode, body)
+	}
+	got = getRepo(t, "crud-remote")
+	if got["base_url"] != "https://updated.example.com" || got["mutable_ttl"].(float64) != 120 {
+		t.Fatalf("update not applied: %v", got)
+	}
+
+	// delete
+	resp, _ = doRequest(t, http.MethodDelete, api("/api/v2/remotes/crud-remote"), nil, "")
+	if resp.StatusCode != http.StatusNoContent {
+		t.Fatalf("delete remote: status %d", resp.StatusCode)
+	}
+	resp, _ = doRequest(t, http.MethodGet, api("/api/v2/remotes/crud-remote"), nil, "")
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404 after delete, got %d", resp.StatusCode)
+	}
+}
+
+// TestLocalLifecycle covers add/delete for a local repository.
+func TestLocalLifecycle(t *testing.T) {
+	createRepo(t, `{
+		"name": "crud-local",
+		"package_type": "generic",
+		"repo_type": "local"
+	}`)
+	defer deleteRepo(t, "crud-local")
+
+	got := getRepo(t, "crud-local")
+	if got["repo_type"] != "local" {
+		t.Fatalf("expected repo_type local, got %v", got["repo_type"])
+	}
+
+	resp, _ := doRequest(t, http.MethodDelete, api("/api/v2/remotes/crud-local"), nil, "")
+	if resp.StatusCode != http.StatusNoContent {
+		t.Fatalf("delete local: status %d", resp.StatusCode)
+	}
+}
+
+// TestVirtualLifecycle covers add/change/delete for a virtual repository.
+func TestVirtualLifecycle(t *testing.T) {
+	createRepo(t, `{"name":"vmem-a","package_type":"helm","repo_type":"remote","base_url":"https://a.example.com","stale_on_error":true}`)
+	createRepo(t, `{"name":"vmem-b","package_type":"helm","repo_type":"remote","base_url":"https://b.example.com","stale_on_error":true}`)
+	defer deleteRepo(t, "vmem-a")
+	defer deleteRepo(t, "vmem-b")
+
+	createVirtual(t, `{
+		"name": "crud-virtual",
+		"package_type": "helm",
+		"members": ["vmem-a"]
+	}`)
+	defer deleteVirtual(t, "crud-virtual")
+
+	// change members
+	resp, body := doRequest(t, http.MethodPut, api("/api/v2/virtuals/crud-virtual"), []byte(`{
+		"package_type": "helm",
+		"members": ["vmem-a", "vmem-b"]
+	}`), "application/json")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("update virtual: status %d: %s", resp.StatusCode, body)
+	}
+
+	resp, body = doRequest(t, http.MethodGet, api("/api/v2/virtuals/crud-virtual"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("get virtual: status %d: %s", resp.StatusCode, body)
+	}
+	var v map[string]any
+	if err := json.Unmarshal(body, &v); err != nil {
+		t.Fatalf("decode virtual: %v", err)
+	}
+	members, _ := v["members"].([]any)
+	if len(members) != 2 {
+		t.Fatalf("expected 2 members after update, got %v", v["members"])
+	}
+
+	resp, _ = doRequest(t, http.MethodDelete, api("/api/v2/virtuals/crud-virtual"), nil, "")
+	if resp.StatusCode != http.StatusNoContent {
+		t.Fatalf("delete virtual: status %d", resp.StatusCode)
+	}
+}
+
+func getRepo(t *testing.T, name string) map[string]any {
+	t.Helper()
+	resp, body := doRequest(t, http.MethodGet, api("/api/v2/remotes/"+name), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("get remote %s: status %d: %s", name, resp.StatusCode, body)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(body, &m); err != nil {
+		t.Fatalf("decode remote %s: %v", name, err)
+	}
+	return m
+}

e2e-docker/virtual_test.go

@@ -0,0 +1,138 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"bytes"
+	"compress/gzip"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"strings"
+	"testing"
+	"time"
+)
+
+// TestVirtualPyPIMerge uploads different packages to two pypi locals and
+// checks that a virtual over them serves a merged simple index.
+func TestVirtualPyPIMerge(t *testing.T) {
+	createRepo(t, `{"name":"pmerge-a","package_type":"pypi","repo_type":"local"}`)
+	createRepo(t, `{"name":"pmerge-b","package_type":"pypi","repo_type":"local"}`)
+	defer deleteRepo(t, "pmerge-a")
+	defer deleteRepo(t, "pmerge-b")
+
+	uploadFile(t, "pmerge-a", "foo-1.0-py3-none-any.whl", fixtureBytes(t, "packages/foo-1.0-py3-none-any.whl"), "application/zip")
+	uploadFile(t, "pmerge-b", "bar-2.0-py3-none-any.whl", []byte("bar wheel payload"), "application/zip")
+
+	createVirtual(t, `{"name":"pmerge-v","package_type":"pypi","members":["pmerge-a","pmerge-b"]}`)
+	defer deleteVirtual(t, "pmerge-v")
+
+	resp, body := doRequest(t, http.MethodGet, api("/api/v1/virtual/pmerge-v/simple/"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("virtual simple index: status %d: %s", resp.StatusCode, body)
+	}
+	s := string(body)
+	if !strings.Contains(s, "foo") || !strings.Contains(s, "bar") {
+		t.Fatalf("merged index missing a member package (want foo and bar): %s", s)
+	}
+}
+
+// TestVirtualHelmMerge points two helm remotes at mock index.yaml documents
+// with distinct charts and checks the virtual merges both into one index.
+func TestVirtualHelmMerge(t *testing.T) {
+	createRepo(t, `{"name":"hmerge-a","package_type":"helm","repo_type":"remote","base_url":"`+mockUpstream()+`/helm-a","stale_on_error":true}`)
+	createRepo(t, `{"name":"hmerge-b","package_type":"helm","repo_type":"remote","base_url":"`+mockUpstream()+`/helm-b","stale_on_error":true}`)
+	defer deleteRepo(t, "hmerge-a")
+	defer deleteRepo(t, "hmerge-b")
+
+	createVirtual(t, `{"name":"hmerge-v","package_type":"helm","members":["hmerge-a","hmerge-b"]}`)
+	defer deleteVirtual(t, "hmerge-v")
+
+	resp, body := doRequest(t, http.MethodGet, api("/api/v1/virtual/hmerge-v/index.yaml"), nil, "")
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("virtual index.yaml: status %d: %s", resp.StatusCode, body)
+	}
+	s := string(body)
+	if !strings.Contains(s, "alpha") || !strings.Contains(s, "beta") {
+		t.Fatalf("merged helm index missing a member chart (want alpha and beta): %s", s)
+	}
+}
+
+// TestVirtualRPMMerge merges a remote rpm repo and a local rpm repo carrying the
+// same package: the first member wins the duplicate, its package download
+// routes through the virtual, and a real dnf can consume the merged repo.
+func TestVirtualRPMMerge(t *testing.T) {
+	createRepo(t, `{"name":"vrpm-remote","package_type":"rpm","repo_type":"remote","base_url":"`+mockUpstream()+`/rpm-mirror","stale_on_error":true}`)
+	createRepo(t, `{"name":"vrpm-local","package_type":"rpm","repo_type":"local"}`)
+	defer deleteRepo(t, "vrpm-remote")
+	defer deleteRepo(t, "vrpm-local")
+
+	pkg := fixtureBytes(t, "rpmrepo/Packages/e2e-testpkg-1.0-1.noarch.rpm")
+	uploadFile(t, "vrpm-local", "e2e-testpkg-1.0-1.noarch.rpm", pkg, "application/x-rpm")
+
+	createVirtual(t, `{"name":"vrpm","package_type":"rpm","members":["vrpm-remote","vrpm-local"]}`)
+	defer deleteVirtual(t, "vrpm")
+
+	resp, body := getEventually(t, api("/api/v1/virtual/vrpm/repodata/repomd.xml"), 15*time.Second)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("virtual repomd.xml: status %d: %s", resp.StatusCode, body)
+	}
+	var md struct {
+		Data []struct {
+			Type     string `xml:"type,attr"`
+			Location struct {
+				Href string `xml:"href,attr"`
+			} `xml:"location"`
+		} `xml:"data"`
+	}
+	if err := xml.Unmarshal(body, &md); err != nil {
+		t.Fatalf("parse repomd.xml: %v\n%s", err, body)
+	}
+	var primary []byte
+	for _, d := range md.Data {
+		if d.Type == "primary" {
+			resp, gz := doRequest(t, http.MethodGet, api("/api/v1/virtual/vrpm/"+d.Location.Href), nil, "")
+			if resp.StatusCode != http.StatusOK {
+				t.Fatalf("primary: status %d", resp.StatusCode)
+			}
+			r, err := gzip.NewReader(bytes.NewReader(gz))
+			if err != nil {
+				t.Fatal(err)
+			}
+			primary, _ = io.ReadAll(r)
+		}
+	}
+	href := "vrpm-remote/Packages/e2e-testpkg-1.0-1.noarch.rpm"
+	if strings.Count(string(primary), "<name>e2e-testpkg</name>") != 1 || !strings.Contains(string(primary), `href="`+href+`"`) {
+		t.Fatalf("merged primary should hold one e2e-testpkg owned by the first member:\n%s", primary)
+	}
+
+	resp, got := doRequest(t, http.MethodGet, api("/api/v1/virtual/vrpm/"+href), nil, "")
+	if resp.StatusCode != http.StatusOK || !bytes.Equal(got, pkg) {
+		t.Fatalf("package via virtual: status %d, %d bytes (want %d)", resp.StatusCode, len(got), len(pkg))
+	}
+
+	network := os.Getenv("COMPOSE_NETWORK")
+	internal := os.Getenv("ARTIFACTAPI_INTERNAL")
+	if network == "" || internal == "" {
+		t.Skip("COMPOSE_NETWORK/ARTIFACTAPI_INTERNAL not set; skipping real dnf")
+	}
+	if _, err := exec.LookPath("docker"); err != nil {
+		t.Skip("docker not available on the test host")
+	}
+	repoConf := fmt.Sprintf("[vrpm]\nname=vrpm\nbaseurl=%s/api/v1/virtual/vrpm/\nenabled=1\ngpgcheck=0\nmetadata_expire=0\n", strings.TrimRight(internal, "/"))
+	script := "set -euo pipefail; " +
+		"printf '%s' \"$REPO\" > /etc/yum.repos.d/vrpm.repo; " +
+		"dnf -y --disablerepo='*' --enablerepo=vrpm makecache; " +
+		"dnf -y --disablerepo='*' --enablerepo=vrpm list --available; " +
+		"dnf -y --disablerepo='*' --enablerepo=vrpm install e2e-testpkg; " +
+		"rpm -q e2e-testpkg"
+	out, err := exec.Command("docker", "run", "--rm", "--network", network, "-e", "REPO="+repoConf,
+		"rockylinux:9", "bash", "-c", script).CombinedOutput()
+	if err != nil {
+		t.Fatalf("real dnf against rpm virtual failed: %v\n%s", err, out)
+	}
+}

e2e/e2e_test.go

@@ -95,7 +95,7 @@ func TestMain(m *testing.M) {
 	}
 	cfg.ListenAddr = "127.0.0.1:0"
 
-	srv, err := server.New(cfg)
+	srv, err := server.New(cfg, "e2e-test")
 	if err != nil {
 		log.Fatalf("server: %v", err)
 	}

e2e/head_test.go

@@ -0,0 +1,182 @@
+//go:build e2e
+
+package e2e
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+)
+
+// assertHeadMatchesGet checks HEAD returns GET's status, type and length with no body.
+func assertHeadMatchesGet(t *testing.T, url string) {
+	t.Helper()
+	get, err := http.Get(url)
+	if err != nil {
+		t.Fatalf("GET: %v", err)
+	}
+	body, _ := io.ReadAll(get.Body)
+	get.Body.Close()
+	if get.StatusCode != http.StatusOK {
+		t.Fatalf("GET %s: %d %s", url, get.StatusCode, body)
+	}
+
+	head, err := http.Head(url)
+	if err != nil {
+		t.Fatalf("HEAD: %v", err)
+	}
+	hb, _ := io.ReadAll(head.Body)
+	head.Body.Close()
+	if head.StatusCode != http.StatusOK {
+		t.Fatalf("HEAD %s: got %d, want 200", url, head.StatusCode)
+	}
+	if len(hb) != 0 {
+		t.Errorf("HEAD returned a %d-byte body", len(hb))
+	}
+	for _, h := range []string{"Content-Type", "Cache-Control", "Vary"} {
+		if head.Header.Get(h) != get.Header.Get(h) {
+			t.Errorf("HEAD %s %q, GET %q", h, head.Header.Get(h), get.Header.Get(h))
+		}
+	}
+	if head.ContentLength != int64(len(body)) {
+		t.Errorf("HEAD Content-Length %d, GET body %d bytes", head.ContentLength, len(body))
+	}
+}
+
+func TestProxyHeadNuGetRewritten(t *testing.T) {
+	var upstream *httptest.Server
+	upstream = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{"version": "3.0.0", "resources": []map[string]string{
+			{"@id": upstream.URL + "/v3-flatcontainer/", "@type": "PackageBaseAddress/3.0.0"},
+		}})
+	}))
+	defer upstream.Close()
+
+	createRemote(t, mustFormat(`{"name": "head-nuget", "package_type": "nuget", "base_url": %q}`, upstream.URL+"/v3/index.json"))
+	defer deleteRemote(t, "head-nuget")
+
+	url := apiURL("/api/v1/remote/head-nuget/index.json")
+	assertHeadMatchesGet(t, url)
+
+	req, _ := http.NewRequest(http.MethodHead, url, nil)
+	req.Host = "evil.example:"
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("HEAD with invalid Host: got %d, want 400", resp.StatusCode)
+	}
+}
+
+func TestProxyHeadGitHubRPMRepodata(t *testing.T) {
+	rpm := testsupport.MinimalRPM("demo", "1.2", "3", "x86_64")
+	var gh *httptest.Server
+	mux := http.NewServeMux()
+	mux.HandleFunc("/repos/acme/tools/releases", func(w http.ResponseWriter, r *http.Request) {
+		if p := r.URL.Query().Get("page"); p != "" && p != "1" {
+			w.Write([]byte("[]"))
+			return
+		}
+		json.NewEncoder(w).Encode([]map[string]any{{"tag_name": "v1.2-3", "assets": []map[string]any{{
+			"name":                 "demo-1.2-3.x86_64.rpm",
+			"size":                 len(rpm),
+			"browser_download_url": gh.URL + "/acme/tools/releases/download/v1.2-3/demo-1.2-3.x86_64.rpm",
+		}}}})
+	})
+	mux.HandleFunc("/acme/tools/releases/download/", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Length", strconv.Itoa(len(rpm)))
+		w.Write(rpm)
+	})
+	gh = httptest.NewServer(mux)
+	defer gh.Close()
+
+	createRemote(t, mustFormat(`{"name": "head-ghrpm", "package_type": "github_rpm", "base_url": %q, "releases_remote": "github"}`, gh.URL+"/repos/acme/tools"))
+	defer deleteRemote(t, "head-ghrpm")
+
+	url := apiURL("/api/v1/remote/head-ghrpm/repodata/repomd.xml")
+	deadline := time.Now().Add(30 * time.Second)
+	for {
+		if _, status := getBody(t, url); status == http.StatusOK || time.Now().After(deadline) {
+			break
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+	assertHeadMatchesGet(t, url)
+}
+
+func TestProxyHeadNpmUncachedPackument(t *testing.T) {
+	const abbreviated = "application/vnd.npm.install-v1+json"
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		doc := map[string]any{"name": "left-pad", "versions": map[string]any{"1.3.0": map[string]any{}}}
+		if r.Header.Get("Accept") != abbreviated {
+			doc["readme"] = strings.Repeat("full packument ", 200)
+		}
+		json.NewEncoder(w).Encode(doc)
+	}))
+	defer upstream.Close()
+
+	createRemote(t, mustFormat(`{"name": "head-npm", "package_type": "npm", "base_url": %q}`, upstream.URL))
+	defer deleteRemote(t, "head-npm")
+
+	url := apiURL("/api/v1/remote/head-npm/left-pad")
+	do := func(method string) (*http.Response, []byte) {
+		req, _ := http.NewRequest(method, url, nil)
+		req.Header.Set("Accept", abbreviated)
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			t.Fatalf("%s: %v", method, err)
+		}
+		defer resp.Body.Close()
+		b, _ := io.ReadAll(resp.Body)
+		return resp, b
+	}
+	head, _ := do(http.MethodHead)
+	get, body := do(http.MethodGet)
+	if head.StatusCode != http.StatusOK || get.StatusCode != http.StatusOK {
+		t.Fatalf("HEAD %d, GET %d", head.StatusCode, get.StatusCode)
+	}
+	if head.ContentLength != int64(len(body)) {
+		t.Errorf("uncached HEAD Content-Length %d, GET body %d bytes", head.ContentLength, len(body))
+	}
+}
+
+func TestProxyHeadNonRewritingUsesUpstreamHead(t *testing.T) {
+	methods := make(chan string, 4)
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		methods <- r.Method
+		w.Header().Set("Content-Type", "text/xml")
+		w.Write([]byte("<repomd/>"))
+	}))
+	defer upstream.Close()
+
+	createRemote(t, mustFormat(`{"name": "head-rpm", "package_type": "rpm", "base_url": %q}`, upstream.URL))
+	defer deleteRemote(t, "head-rpm")
+
+	resp, err := http.Head(apiURL("/api/v1/remote/head-rpm/repodata/repomd.xml"))
+	if err != nil {
+		t.Fatalf("HEAD: %v", err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusOK || resp.Header.Get("X-Artifact-Source") != "remote" {
+		t.Fatalf("HEAD %d source %q", resp.StatusCode, resp.Header.Get("X-Artifact-Source"))
+	}
+	close(methods)
+	var seen []string
+	for m := range methods {
+		seen = append(seen, m)
+	}
+	if len(seen) != 1 || seen[0] != http.MethodHead {
+		t.Errorf("upstream saw %v, want a single HEAD", seen)
+	}
+}

e2e/management_test.go

@@ -24,6 +24,30 @@ func TestRoot(t *testing.T) {
 	}
 }
 
+func TestRemoteUpstreamTimeouts(t *testing.T) {
+	createRemote(t, `{
+		"name": "timeout-test",
+		"package_type": "generic",
+		"base_url": "https://example.com",
+		"stale_on_error": true,
+		"upstream_dial_timeout": 3,
+		"upstream_tls_timeout": 4,
+		"upstream_response_header_timeout": 5
+	}`)
+	defer deleteRemote(t, "timeout-test")
+
+	remote := getJSON(t, apiURL("/api/v2/remotes/timeout-test"))
+	for field, want := range map[string]float64{
+		"upstream_dial_timeout":            3,
+		"upstream_tls_timeout":             4,
+		"upstream_response_header_timeout": 5,
+	} {
+		if got, _ := remote[field].(float64); got != want {
+			t.Errorf("%s: got %v, want %v", field, remote[field], want)
+		}
+	}
+}
+
 func TestRemoteCRUD(t *testing.T) {
 	createRemote(t, `{
 		"name": "test-generic",

e2e/proxy_test.go

@@ -24,6 +24,39 @@ func TestProxyBlocklist(t *testing.T) {
 	assertStatus(t, apiURL("/api/v1/remote/blocklist-test/malware.exe"), http.StatusForbidden)
 }
 
+func TestProxyHeadBlocklist(t *testing.T) {
+	createRemote(t, `{
+		"name": "head-block-test",
+		"package_type": "generic",
+		"base_url": "https://example.com",
+		"blocklist": ["\\.exe$"],
+		"stale_on_error": true
+	}`)
+	defer deleteRemote(t, "head-block-test")
+
+	req, _ := http.NewRequest(http.MethodHead, apiURL("/v2/head-block-test/malware.exe"), nil)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("HEAD: %v", err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("HEAD blocklisted path: got %d, want 403", resp.StatusCode)
+	}
+}
+
+func TestProxyHeadUnknownRemote(t *testing.T) {
+	req, _ := http.NewRequest(http.MethodHead, apiURL("/v2/nonexistent/some/path"), nil)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("HEAD: %v", err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("HEAD unknown remote: got %d, want 404", resp.StatusCode)
+	}
+}
+
 func TestProxyPatterns(t *testing.T) {
 	createRemote(t, `{
 		"name": "patterns-test",

e2e/scheme_test.go

@@ -0,0 +1,59 @@
+//go:build e2e
+
+package e2e
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func getForwardedHTTPS(t *testing.T, url string) *http.Response {
+	t.Helper()
+	req, _ := http.NewRequest(http.MethodGet, url, nil)
+	req.Header.Set("X-Forwarded-Proto", "https")
+	client := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
+	resp, err := client.Do(req)
+	if err != nil {
+		t.Fatalf("GET %s: %v", url, err)
+	}
+	return resp
+}
+
+func TestForwardedProtoCargoConfig(t *testing.T) {
+	createRemote(t, `{"name": "scheme-cargo", "package_type": "cargo", "base_url": "https://index.crates.io"}`)
+	defer deleteRemote(t, "scheme-cargo")
+
+	resp := getForwardedHTTPS(t, apiURL("/api/v1/remote/scheme-cargo/config.json"))
+	defer resp.Body.Close()
+	var cfg map[string]string
+	if err := json.NewDecoder(resp.Body).Decode(&cfg); err != nil {
+		t.Fatal(err)
+	}
+	if want := "https://" + strings.TrimPrefix(baseURL, "http://") + "/api/v1/remote/scheme-cargo/"; !strings.HasPrefix(cfg["dl"], want) {
+		t.Errorf("dl = %q, want prefix %q", cfg["dl"], want)
+	}
+}
+
+func TestForwardedProtoVirtualRedirect(t *testing.T) {
+	createRemote(t, `{"name": "scheme-rpm", "package_type": "rpm", "base_url": "https://rpm.example.com"}`)
+	defer deleteRemote(t, "scheme-rpm")
+	resp, err := http.Post(apiURL("/api/v2/virtuals"), "application/json",
+		strings.NewReader(`{"name": "scheme-virt", "package_type": "rpm", "members": ["scheme-rpm"]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("create virtual: status %d", resp.StatusCode)
+	}
+	defer deleteRequest(t, apiURL("/api/v2/virtuals/scheme-virt"))
+
+	resp = getForwardedHTTPS(t, apiURL("/api/v1/virtual/scheme-virt/scheme-rpm/Packages/a.rpm"))
+	resp.Body.Close()
+	loc := resp.Header.Get("Location")
+	if want := "https://" + strings.TrimPrefix(baseURL, "http://") + "/api/v1/remote/scheme-rpm/Packages/a.rpm"; resp.StatusCode != http.StatusFound || loc != want {
+		t.Errorf("redirect = %d %q, want 302 %q", resp.StatusCode, loc, want)
+	}
+}

go.mod

@@ -3,16 +3,25 @@ module git.unkin.net/unkin/artifactapi
 go 1.25.9
 
 require (
+	git.unkin.net/unkin/golib v0.1.0
 	github.com/cavaliergopher/rpm v1.3.0
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/coreos/go-oidc/v3 v3.21.0
 	github.com/go-chi/chi/v5 v5.3.0
+	github.com/go-jose/go-jose/v4 v4.1.4
+	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.10.0
+	github.com/klauspost/compress v1.19.2
 	github.com/minio/minio-go/v7 v7.2.0
 	github.com/redis/go-redis/v9 v9.20.0
-	github.com/testcontainers/testcontainers-go v0.42.0
-	github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0
+	github.com/testcontainers/testcontainers-go v0.44.0
+	github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0
 	github.com/testcontainers/testcontainers-go/modules/redis v0.42.0
+	github.com/ulikunitz/xz v0.5.16
+	golang.org/x/crypto v0.54.0
+	golang.org/x/sync v0.22.0
+	golang.org/x/time v0.15.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -36,24 +45,22 @@ require (
 	github.com/cpuguy83/dockercfg v0.3.2 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/distribution/reference v0.6.0 // indirect
-	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/go-connections v0.7.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/ebitengine/purego v0.10.0 // indirect
+	github.com/ebitengine/purego v0.10.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
-	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/felixge/httpsnoop v1.1.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
-	github.com/go-ole/go-ole v1.2.6 // indirect
-	github.com/google/uuid v1.6.0 // indirect
+	github.com/go-ole/go-ole v1.3.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
-	github.com/klauspost/compress v1.18.6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.11 // indirect
 	github.com/klauspost/crc32 v1.3.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
-	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
@@ -63,10 +70,10 @@ require (
 	github.com/minio/md5-simd v1.1.2 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
 	github.com/moby/go-archive v0.2.0 // indirect
-	github.com/moby/moby/api v1.54.1 // indirect
-	github.com/moby/moby/client v0.4.0 // indirect
+	github.com/moby/moby/api v1.55.0 // indirect
+	github.com/moby/moby/client v0.5.0 // indirect
 	github.com/moby/patternmatcher v0.6.1 // indirect
-	github.com/moby/sys/sequential v0.6.0 // indirect
+	github.com/moby/sys/sequential v0.7.0 // indirect
 	github.com/moby/sys/user v0.4.0 // indirect
 	github.com/moby/sys/userns v0.1.0 // indirect
 	github.com/moby/term v0.5.2 // indirect
@@ -80,26 +87,25 @@ require (
 	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/rs/xid v1.6.0 // indirect
-	github.com/shirou/gopsutil/v4 v4.26.3 // indirect
+	github.com/shirou/gopsutil/v4 v4.26.6 // indirect
 	github.com/sirupsen/logrus v1.9.4 // indirect
 	github.com/stretchr/testify v1.11.1 // indirect
 	github.com/tinylib/msgp v1.6.1 // indirect
-	github.com/tklauser/go-sysconf v0.3.16 // indirect
-	github.com/tklauser/numcpus v0.11.0 // indirect
+	github.com/tklauser/go-sysconf v0.4.0 // indirect
+	github.com/tklauser/numcpus v0.12.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0 // indirect
-	go.opentelemetry.io/otel v1.41.0 // indirect
-	go.opentelemetry.io/otel/metric v1.41.0 // indirect
-	go.opentelemetry.io/otel/trace v1.41.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
+	go.opentelemetry.io/otel v1.44.0 // indirect
+	go.opentelemetry.io/otel/metric v1.44.0 // indirect
+	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.51.0 // indirect
-	golang.org/x/net v0.53.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.44.0 // indirect
-	golang.org/x/text v0.37.0 // indirect
+	golang.org/x/net v0.56.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
 	gopkg.in/ini.v1 v1.67.2 // indirect
 )

go.sum

@@ -1,5 +1,7 @@
 dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
 dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
+git.unkin.net/unkin/golib v0.1.0 h1:OjKT5TO7PuXiYQ/1A+I4S2VZ/IsAxXY1reGWwasDMqE=
+git.unkin.net/unkin/golib v0.1.0/go.mod h1:1e3PpMLEfa03Re/6tlk+I2XPWzBQMSpw2MB+Aw2lkX4=
 github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk=
 github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8=
 github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg=
@@ -42,6 +44,8 @@ github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
 github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
 github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
 github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBqoWM=
+github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
 github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
 github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
@@ -51,28 +55,30 @@ 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/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
-github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
-github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
+github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c=
+github.com/docker/go-connections v0.7.0/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
 github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
 github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
 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/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
-github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
+github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY=
+github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
-github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
-github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc=
+github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE=
 github.com/go-chi/chi/v5 v5.3.0 h1:halUjDxhshgXHMrao5bB8eNBXo/rnzwr8m5m36glehM=
 github.com/go-chi/chi/v5 v5.3.0/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
+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=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
 github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
-github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
 github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
-github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
+github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -85,8 +91,8 @@ github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
 github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
-github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao=
-github.com/klauspost/compress v1.18.6/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/klauspost/cpuid/v2 v2.0.1/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.2.11 h1:0OwqZRYI2rFrjS4kvkDnqJkKHdHaRnCm68/DY4OxRzU=
 github.com/klauspost/cpuid/v2 v2.2.11/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
@@ -100,8 +106,8 @@ github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
 github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
-github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
+github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e h1:Q6MvJtQK/iRcRtzAscm/zF23XxJlbECiGPyRicsX+Ak=
+github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
 github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE=
 github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
@@ -122,14 +128,14 @@ github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3N
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
 github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8=
 github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU=
-github.com/moby/moby/api v1.54.1 h1:TqVzuJkOLsgLDDwNLmYqACUuTehOHRGKiPhvH8V3Nn4=
-github.com/moby/moby/api v1.54.1/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
-github.com/moby/moby/client v0.4.0 h1:S+2XegzHQrrvTCvF6s5HFzcrywWQmuVnhOXe2kiWjIw=
-github.com/moby/moby/client v0.4.0/go.mod h1:QWPbvWchQbxBNdaLSpoKpCdf5E+WxFAgNHogCWDoa7g=
+github.com/moby/moby/api v1.55.0 h1:2/sexvQyqIWS8pRSCFddBfpW2qE7vR7FCL+vN8pxwMc=
+github.com/moby/moby/api v1.55.0/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
+github.com/moby/moby/client v0.5.0 h1:5XhyPk2fuOWf6RlSFa3MkIIgDZkF25xToXW8Q/BH7cc=
+github.com/moby/moby/client v0.5.0/go.mod h1:rcVpF8ncl9vo5gaIBdol6CnbEtSj1uxMvEV/UrykF/s=
 github.com/moby/patternmatcher v0.6.1 h1:qlhtafmr6kgMIJjKJMDmMWq7WLkKIo23hsrpR3x084U=
 github.com/moby/patternmatcher v0.6.1/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
-github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
-github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
+github.com/moby/sys/sequential v0.7.0 h1:ASQNGNROJSuOO6LL6bPHbKvuZu6NU8P4ldPWk31zj/8=
+github.com/moby/sys/sequential v0.7.0/go.mod h1:NfSTAp6V3fw4tmkD62PEcOKeZKquXT8VKCkf7aVR79o=
 github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs=
 github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
 github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
@@ -160,8 +166,8 @@ github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0t
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
 github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
-github.com/shirou/gopsutil/v4 v4.26.3 h1:2ESdQt90yU3oXF/CdOlRCJxrP+Am1aBYubTMTfxJ1qc=
-github.com/shirou/gopsutil/v4 v4.26.3/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
+github.com/shirou/gopsutil/v4 v4.26.6 h1:Mzr/npDtQC/xpeEuQKHZt8Zo9CmPvhTj8nkR8w5TLDs=
+github.com/shirou/gopsutil/v4 v4.26.6/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -177,18 +183,20 @@ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 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/testcontainers/testcontainers-go v0.42.0 h1:He3IhTzTZOygSXLJPMX7n44XtK+qhjat1nI9cneBbUY=
-github.com/testcontainers/testcontainers-go v0.42.0/go.mod h1:vZjdY1YmUA1qEForxOIOazfsrdyORJAbhi0bp8plN30=
-github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0 h1:GCbb1ndrF7OTDiIvxXyItaDab4qkzTFJ48LKFdM7EIo=
-github.com/testcontainers/testcontainers-go/modules/postgres v0.42.0/go.mod h1:IRPBaI8jXdrNfD0e4Zm7Fbcgaz5shKxOQv4axiL09xs=
+github.com/testcontainers/testcontainers-go v0.44.0 h1:/Fwh6HY1mIikhnm9e7HwoxGycx0lzRAE0f5VQpjFxzI=
+github.com/testcontainers/testcontainers-go v0.44.0/go.mod h1:IcnwQrYTO86xHXu5bvMaBH7ATlbS3Qn1M1QWW3c66rE=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0 h1:8fdv/9y3JMxjQ+ULAcOG8RtgeNu5t9XF9LolSXDuTwM=
+github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0/go.mod h1:CFr2LncGYokw+OKjXcr8ARCKG1SaC2UEnGxFBovE86g=
 github.com/testcontainers/testcontainers-go/modules/redis v0.42.0 h1:id/6LH8ZeDrtAUVSuNvZUAJ1kVpb82y1pr9yweAWsRg=
 github.com/testcontainers/testcontainers-go/modules/redis v0.42.0/go.mod h1:uF0jI8FITagQpBNOgweGBmPf6rP4K0SeL1XFPbsZSSY=
 github.com/tinylib/msgp v1.6.1 h1:ESRv8eL3u+DNHUoSAAQRE50Hm162zqAnBoGv9PzScPY=
 github.com/tinylib/msgp v1.6.1/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
-github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=
-github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=
-github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=
-github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=
+github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRUgPQU=
+github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI=
+github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4=
+github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg=
+github.com/ulikunitz/xz v0.5.16 h1:ld6NyySjx5lowVKwJvMRLnW5nxKX/xnpSiFYZ/Lxur0=
+github.com/ulikunitz/xz v0.5.16/go.mod h1:H9Rt/W6/Qj27PGauhQc6nfCDy7vHpzsOThBSaYDoEhw=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
@@ -199,42 +207,46 @@ github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
 github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
 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/instrumentation/net/http/otelhttp v0.60.0 h1:sbiXRNDSWJOTobXh5HyQKjq6wUC5tNybqjIqDpAY4CU=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0/go.mod h1:69uWxva0WgAA/4bu2Yy70SLDBwZXuQ6PbBpbsa5iZrQ=
-go.opentelemetry.io/otel v1.41.0 h1:YlEwVsGAlCvczDILpUXpIpPSL/VPugt7zHThEMLce1c=
-go.opentelemetry.io/otel v1.41.0/go.mod h1:Yt4UwgEKeT05QbLwbyHXEwhnjxNO6D8L5PQP51/46dE=
-go.opentelemetry.io/otel/metric v1.41.0 h1:rFnDcs4gRzBcsO9tS8LCpgR0dxg4aaxWlJxCno7JlTQ=
-go.opentelemetry.io/otel/metric v1.41.0/go.mod h1:xPvCwd9pU0VN8tPZYzDZV/BMj9CM9vs00GuBjeKhJps=
-go.opentelemetry.io/otel/sdk v1.35.0 h1:iPctf8iprVySXSKJffSS79eOjl9pvxV9ZqOWT0QejKY=
-go.opentelemetry.io/otel/sdk v1.35.0/go.mod h1:+ga1bZliga3DxJ3CQGg3updiaAJoNECOgJREo9KHGQg=
-go.opentelemetry.io/otel/sdk/metric v1.35.0 h1:1RriWBmCKgkeHEhM7a2uMjMUfP7MsOF5JpUCaEqEI9o=
-go.opentelemetry.io/otel/sdk/metric v1.35.0/go.mod h1:is6XYCUMpcKi+ZsOvfluY5YstFnhW0BidkR+gL+qN+w=
-go.opentelemetry.io/otel/trace v1.41.0 h1:Vbk2co6bhj8L59ZJ6/xFTskY+tGAbOnCtQGVVa9TIN0=
-go.opentelemetry.io/otel/trace v1.41.0/go.mod h1:U1NU4ULCoxeDKc09yCWdWe+3QoyweJcISEVa1RBzOis=
+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=
+go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
 go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
 go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
-golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
-golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
-golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+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.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
-golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
-golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
-golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
-golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
-golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+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.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
+golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
+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/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

internal/api/terraform/registry.go

@@ -0,0 +1,295 @@
+// Package terraform serves local terraform repos as a real Terraform provider
+// registry: service discovery, version listing, and GPG-signed downloads, so
+// `terraform init` installs from a bare source address with no client config.
+package terraform
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"path"
+	"sort"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	v1 "git.unkin.net/unkin/artifactapi/internal/api/v1"
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	tfprov "git.unkin.net/unkin/artifactapi/internal/provider/terraform"
+	"git.unkin.net/unkin/artifactapi/internal/tfsign"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// ProvidersV1Path is the base the service-discovery document advertises (Terraform
+// appends "{namespace}/{type}/versions" etc). MountPath is the same prefix without
+// the trailing slash, for chi.Mount.
+const (
+	ProvidersV1Path = "/terraform/v1/providers/"
+	MountPath       = "/terraform/v1/providers"
+)
+
+type Handler struct {
+	db        *database.DB
+	signer    *tfsign.Signer
+	protocols []string
+}
+
+func NewHandler(db *database.DB, signer *tfsign.Signer, protocols string) *Handler {
+	var protos []string
+	for _, p := range strings.Split(protocols, ",") {
+		if p = strings.TrimSpace(p); p != "" {
+			protos = append(protos, p)
+		}
+	}
+	if len(protos) == 0 {
+		protos = []string{"5.0", "6.0"}
+	}
+	return &Handler{db: db, signer: signer, protocols: protos}
+}
+
+// Enabled reports whether a signing key is configured. Without one the registry
+// cannot produce the signed SHA256SUMS the protocol requires, so it stays off.
+func (h *Handler) Enabled() bool { return h.signer != nil }
+
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/{namespace}/{type}/versions", h.versions)
+	r.Get("/{namespace}/{type}/{version}/download/{os}/{arch}", h.download)
+	r.Get("/{namespace}/{type}/{version}/sha256sums", h.sha256sums)
+	r.Get("/{namespace}/{type}/{version}/sha256sums.sig", h.sha256sumsSig)
+	return r
+}
+
+// ServiceDiscovery answers /.well-known/terraform.json, pointing Terraform at the
+// providers.v1 protocol base.
+func (h *Handler) ServiceDiscovery(w http.ResponseWriter, r *http.Request) {
+	if !h.Enabled() {
+		http.NotFound(w, r)
+		return
+	}
+	writeJSON(w, map[string]string{"providers.v1": ProvidersV1Path})
+}
+
+// providerFile is one resolved platform artifact within a repo.
+type providerFile struct {
+	version  string
+	os       string
+	arch     string
+	filePath string // path within the repo, e.g. unkin/artifactapi/...zip
+	sha256   string // hex, no "sha256:" prefix
+}
+
+// resolve finds every provider zip of the given type in the repo (namespace).
+// The Terraform source namespace maps to the artifactapi repo name; the provider
+// is matched by type across whatever in-repo folder it was uploaded under.
+func (h *Handler) resolve(r *http.Request, namespace, typeName string) ([]providerFile, error) {
+	remote, err := h.db.GetRemote(r.Context(), namespace)
+	if err != nil || remote.PackageType != models.PackageTerraform {
+		return nil, nil
+	}
+
+	rows, err := h.db.ListLocalFiles(r.Context(), namespace, 10000, 0)
+	if err != nil {
+		return nil, err
+	}
+
+	var out []providerFile
+	for _, row := range rows {
+		parsed := tfprov.ParseProviderZip(path.Base(row.FilePath))
+		if !parsed.Ok || parsed.Type != typeName {
+			continue
+		}
+		out = append(out, providerFile{
+			version:  parsed.Version,
+			os:       parsed.OS,
+			arch:     parsed.Arch,
+			filePath: row.FilePath,
+			sha256:   strings.TrimPrefix(row.ContentHash, "sha256:"),
+		})
+	}
+	return out, nil
+}
+
+func (h *Handler) versions(w http.ResponseWriter, r *http.Request) {
+	if !h.Enabled() {
+		http.NotFound(w, r)
+		return
+	}
+	namespace := chi.URLParam(r, "namespace")
+	typeName := chi.URLParam(r, "type")
+
+	files, err := h.resolve(r, namespace, typeName)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	if len(files) == 0 {
+		http.NotFound(w, r)
+		return
+	}
+
+	// Group platforms by version, de-duplicated and stably ordered.
+	type platform struct {
+		OS   string `json:"os"`
+		Arch string `json:"arch"`
+	}
+	platforms := map[string]map[string]platform{}
+	for _, f := range files {
+		if platforms[f.version] == nil {
+			platforms[f.version] = map[string]platform{}
+		}
+		platforms[f.version][f.os+"_"+f.arch] = platform{OS: f.os, Arch: f.arch}
+	}
+
+	type versionEntry struct {
+		Version   string     `json:"version"`
+		Protocols []string   `json:"protocols"`
+		Platforms []platform `json:"platforms"`
+	}
+	out := struct {
+		Versions []versionEntry `json:"versions"`
+	}{}
+	for version, plats := range platforms {
+		entry := versionEntry{Version: version, Protocols: h.protocols}
+		for _, p := range plats {
+			entry.Platforms = append(entry.Platforms, p)
+		}
+		sort.Slice(entry.Platforms, func(i, j int) bool {
+			return entry.Platforms[i].OS+entry.Platforms[i].Arch < entry.Platforms[j].OS+entry.Platforms[j].Arch
+		})
+		out.Versions = append(out.Versions, entry)
+	}
+	sort.Slice(out.Versions, func(i, j int) bool { return out.Versions[i].Version < out.Versions[j].Version })
+
+	writeJSON(w, out)
+}
+
+func (h *Handler) download(w http.ResponseWriter, r *http.Request) {
+	if !h.Enabled() {
+		http.NotFound(w, r)
+		return
+	}
+	namespace := chi.URLParam(r, "namespace")
+	typeName := chi.URLParam(r, "type")
+	version := chi.URLParam(r, "version")
+	osName := chi.URLParam(r, "os")
+	arch := chi.URLParam(r, "arch")
+
+	files, err := h.resolve(r, namespace, typeName)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	var match *providerFile
+	for i := range files {
+		if files[i].version == version && files[i].os == osName && files[i].arch == arch {
+			match = &files[i]
+			break
+		}
+	}
+	if match == nil {
+		http.NotFound(w, r)
+		return
+	}
+
+	base := baseURL(r)
+	verBase := fmt.Sprintf("%s%s/%s/%s", base+ProvidersV1Path, namespace, typeName, version)
+
+	type gpgKey struct {
+		KeyID      string `json:"key_id"`
+		ASCIIArmor string `json:"ascii_armor"`
+	}
+	resp := struct {
+		Protocols           []string `json:"protocols"`
+		OS                  string   `json:"os"`
+		Arch                string   `json:"arch"`
+		Filename            string   `json:"filename"`
+		DownloadURL         string   `json:"download_url"`
+		SHASumsURL          string   `json:"shasums_url"`
+		SHASumsSignatureURL string   `json:"shasums_signature_url"`
+		SHASum              string   `json:"shasum"`
+		SigningKeys         struct {
+			GPGPublicKeys []gpgKey `json:"gpg_public_keys"`
+		} `json:"signing_keys"`
+	}{
+		Protocols:           h.protocols,
+		OS:                  match.os,
+		Arch:                match.arch,
+		Filename:            path.Base(match.filePath),
+		DownloadURL:         fmt.Sprintf("%s/api/v1/local/%s/%s", base, namespace, match.filePath),
+		SHASumsURL:          verBase + "/sha256sums",
+		SHASumsSignatureURL: verBase + "/sha256sums.sig",
+		SHASum:              match.sha256,
+	}
+	resp.SigningKeys.GPGPublicKeys = []gpgKey{{
+		KeyID:      h.signer.KeyID(),
+		ASCIIArmor: h.signer.PublicKeyArmor(),
+	}}
+
+	writeJSON(w, resp)
+}
+
+func (h *Handler) sha256sums(w http.ResponseWriter, r *http.Request) {
+	sums, ok := h.buildSums(w, r)
+	if !ok {
+		return
+	}
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.Write(sums)
+}
+
+func (h *Handler) sha256sumsSig(w http.ResponseWriter, r *http.Request) {
+	sums, ok := h.buildSums(w, r)
+	if !ok {
+		return
+	}
+	sig, err := h.signer.Sign(sums)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "application/octet-stream")
+	w.Write(sig)
+}
+
+// buildSums renders the SHA256SUMS body for one version: one "<hex>  <filename>"
+// line per platform zip, sorted by filename so the signed bytes are stable.
+func (h *Handler) buildSums(w http.ResponseWriter, r *http.Request) ([]byte, bool) {
+	if !h.Enabled() {
+		http.NotFound(w, r)
+		return nil, false
+	}
+	namespace := chi.URLParam(r, "namespace")
+	typeName := chi.URLParam(r, "type")
+	version := chi.URLParam(r, "version")
+
+	files, err := h.resolve(r, namespace, typeName)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return nil, false
+	}
+
+	var lines []string
+	for _, f := range files {
+		if f.version != version {
+			continue
+		}
+		lines = append(lines, fmt.Sprintf("%s  %s", f.sha256, path.Base(f.filePath)))
+	}
+	if len(lines) == 0 {
+		http.NotFound(w, r)
+		return nil, false
+	}
+	sort.Strings(lines)
+	return []byte(strings.Join(lines, "\n") + "\n"), true
+}
+
+func writeJSON(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(v)
+}
+
+func baseURL(r *http.Request) string {
+	return v1.Scheme(r) + "://" + r.Host
+}

internal/api/terraform/registry_test.go

@@ -0,0 +1,186 @@
+package terraform
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+	"golang.org/x/crypto/openpgp"
+	"golang.org/x/crypto/openpgp/armor"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/internal/tfsign"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+var testDSN string
+
+func TestMain(m *testing.M) {
+	ctx := context.Background()
+	dsn, terminate, err := testsupport.StartPostgres(ctx)
+	if err != nil {
+		os.Exit(m.Run())
+	}
+	testDSN = dsn
+	code := m.Run()
+	terminate()
+	os.Exit(code)
+}
+
+// testSigner writes a throwaway armored key and loads it.
+func testSigner(t *testing.T) *tfsign.Signer {
+	t.Helper()
+	e, err := openpgp.NewEntity("artifactapi test", "tf", "tf@example.com", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var buf bytes.Buffer
+	w, _ := armor.Encode(&buf, openpgp.PrivateKeyType, nil)
+	if err := e.SerializePrivate(w, nil); err != nil {
+		t.Fatal(err)
+	}
+	w.Close()
+	p := filepath.Join(t.TempDir(), "private-key.asc")
+	if err := os.WriteFile(p, buf.Bytes(), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	s, err := tfsign.Load(p, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+func TestProviderRegistryFlow(t *testing.T) {
+	if testDSN == "" {
+		t.Skip("Docker unavailable")
+	}
+	ctx := context.Background()
+	db, err := database.New(testDSN)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	const repo = "tf-reg" // Terraform namespace == repo name
+	const filePath = "unkin/artifactapi/terraform-provider-artifactapi_1.2.3_linux_amd64.zip"
+	const hash = "sha256:983cdb25cb7b976538e4334d26e52dee5f44749b9be1500c760cf5cf66be659b"
+	const wantSha = "983cdb25cb7b976538e4334d26e52dee5f44749b9be1500c760cf5cf66be659b"
+
+	if err := db.CreateRemote(ctx, &models.Remote{Name: repo, PackageType: models.PackageTerraform, RepoType: models.RepoTypeLocal}); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.UpsertBlob(ctx, hash, "blobs/98/3c", 6381007, "application/zip"); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.CreateLocalFile(ctx, repo, filePath, hash); err != nil {
+		t.Fatal(err)
+	}
+
+	signer := testSigner(t)
+	h := NewHandler(db, signer, "5.0,6.0")
+	router := chi.NewRouter()
+	router.Get("/.well-known/terraform.json", h.ServiceDiscovery)
+	router.Mount(MountPath, h.Routes())
+
+	get := func(p string) *httptest.ResponseRecorder {
+		req := httptest.NewRequest("GET", p, nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+		return w
+	}
+
+	// Service discovery.
+	w := get("/.well-known/terraform.json")
+	if w.Code != 200 {
+		t.Fatalf("discovery = %d", w.Code)
+	}
+	var disc map[string]string
+	json.Unmarshal(w.Body.Bytes(), &disc)
+	if disc["providers.v1"] != ProvidersV1Path {
+		t.Errorf("providers.v1 = %q", disc["providers.v1"])
+	}
+
+	// Versions.
+	w = get("/terraform/v1/providers/tf-reg/artifactapi/versions")
+	if w.Code != 200 {
+		t.Fatalf("versions = %d %s", w.Code, w.Body)
+	}
+	var vresp struct {
+		Versions []struct {
+			Version   string              `json:"version"`
+			Protocols []string            `json:"protocols"`
+			Platforms []map[string]string `json:"platforms"`
+		} `json:"versions"`
+	}
+	json.Unmarshal(w.Body.Bytes(), &vresp)
+	if len(vresp.Versions) != 1 || vresp.Versions[0].Version != "1.2.3" {
+		t.Fatalf("unexpected versions: %+v", vresp)
+	}
+	if len(vresp.Versions[0].Platforms) != 1 || vresp.Versions[0].Platforms[0]["os"] != "linux" {
+		t.Fatalf("unexpected platforms: %+v", vresp.Versions[0].Platforms)
+	}
+
+	// Download.
+	w = get("/terraform/v1/providers/tf-reg/artifactapi/1.2.3/download/linux/amd64")
+	if w.Code != 200 {
+		t.Fatalf("download = %d %s", w.Code, w.Body)
+	}
+	var dl struct {
+		Filename            string `json:"filename"`
+		DownloadURL         string `json:"download_url"`
+		SHASumsURL          string `json:"shasums_url"`
+		SHASumsSignatureURL string `json:"shasums_signature_url"`
+		SHASum              string `json:"shasum"`
+		SigningKeys         struct {
+			GPGPublicKeys []struct {
+				KeyID      string `json:"key_id"`
+				ASCIIArmor string `json:"ascii_armor"`
+			} `json:"gpg_public_keys"`
+		} `json:"signing_keys"`
+	}
+	json.Unmarshal(w.Body.Bytes(), &dl)
+	if dl.SHASum != wantSha {
+		t.Errorf("shasum = %q", dl.SHASum)
+	}
+	wantURL := "http://example.com/api/v1/local/tf-reg/" + filePath
+	if dl.DownloadURL != wantURL {
+		t.Errorf("download_url = %q, want %q", dl.DownloadURL, wantURL)
+	}
+	if len(dl.SigningKeys.GPGPublicKeys) != 1 || dl.SigningKeys.GPGPublicKeys[0].KeyID != signer.KeyID() {
+		t.Errorf("signing key mismatch: %+v", dl.SigningKeys)
+	}
+
+	// SHA256SUMS + signature verify against the advertised key.
+	sums := get("/terraform/v1/providers/tf-reg/artifactapi/1.2.3/sha256sums")
+	wantLine := wantSha + "  terraform-provider-artifactapi_1.2.3_linux_amd64.zip\n"
+	if sums.Body.String() != wantLine {
+		t.Errorf("sha256sums = %q, want %q", sums.Body.String(), wantLine)
+	}
+	sig := get("/terraform/v1/providers/tf-reg/artifactapi/1.2.3/sha256sums.sig")
+	keyring, err := openpgp.ReadArmoredKeyRing(bytes.NewReader([]byte(dl.SigningKeys.GPGPublicKeys[0].ASCIIArmor)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := openpgp.CheckDetachedSignature(keyring, bytes.NewReader(sums.Body.Bytes()), bytes.NewReader(sig.Body.Bytes())); err != nil {
+		t.Errorf("sha256sums.sig did not verify: %v", err)
+	}
+}
+
+func TestRegistryDisabledWithoutSigner(t *testing.T) {
+	h := NewHandler(nil, nil, "")
+	router := chi.NewRouter()
+	router.Get("/.well-known/terraform.json", h.ServiceDiscovery)
+	req := httptest.NewRequest("GET", "/.well-known/terraform.json", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != 404 {
+		t.Errorf("disabled discovery = %d, want 404", w.Code)
+	}
+}

internal/api/v1/docker.go

@@ -0,0 +1,486 @@
+package v1
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"os"
+	"sort"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/google/uuid"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// This file implements the write half of the Docker Registry HTTP API V2 for
+// *local* docker repositories, so a `docker push` / `docker pull` against
+// artifactapi treats a local docker repo as a genuine registry (matching the
+// project's "local repos are the real thing" principle) rather than a mirror.
+//
+// Storage reuses the existing content-addressable primitives:
+//   - blob and manifest bytes are stored via the CAS (deduplicated by sha256)
+//   - a local_files row per (repo, "<image>/blobs/<digest>") and
+//     (repo, "<image>/manifests/<ref>") keeps the blob referenced so the GC
+//     does not reap it, and lets pulls resolve a reference back to a blob.
+// Tags are mutable references (UpsertLocalFile); digests and blobs are
+// immutable (CreateLocalFile, tolerating an already-exists on re-push).
+
+const dockerAPIVersionHeader = "registry/2.0"
+
+// Chunked blob uploads are staged in object storage under uploads/<uuid> rather
+// than in process memory, so the POST / PATCH / PUT of a single push can each be
+// served by a different replica (the API runs with minReplicas>1 and no session
+// affinity). The upload UUID travels in the Location URL handed back to the
+// client, so any replica reconstructs the staging key with no shared in-process
+// state. Abandoned stages are dropped by the GC's uploads sweep.
+func uploadKey(id string) string { return "uploads/" + id }
+
+var errUploadUnknown = errors.New("unknown upload")
+
+// appendUpload appends a chunk to the staged upload object and returns the new
+// total size. The staged bytes live entirely in object storage (download,
+// append to a per-request temp file, re-upload), which keeps the session state
+// replica-independent. Docker sends the whole layer in one PATCH, so this is a
+// single append in the common case.
+func (h *ProxyHandler) appendUpload(ctx context.Context, id string, chunk io.Reader) (int64, error) {
+	key := uploadKey(id)
+	reader, info, err := h.store.Download(ctx, key)
+	if err != nil {
+		return 0, errUploadUnknown
+	}
+
+	tmp, err := os.CreateTemp("", "docker-upload-*")
+	if err != nil {
+		reader.Close()
+		return 0, err
+	}
+	defer os.Remove(tmp.Name())
+	defer tmp.Close()
+
+	if _, err := io.Copy(tmp, reader); err != nil {
+		reader.Close()
+		return 0, err
+	}
+	reader.Close()
+
+	n, err := io.Copy(tmp, chunk)
+	if err != nil {
+		return 0, err
+	}
+	size := info.Size + n
+	if _, err := tmp.Seek(0, io.SeekStart); err != nil {
+		return 0, err
+	}
+	if err := h.store.Upload(ctx, key, tmp, size, "application/octet-stream"); err != nil {
+		return 0, err
+	}
+	return size, nil
+}
+
+// dockerReq is a parsed /v2/<remote>/<image>/... request. kind is one of
+// "manifest", "blob", "upload", "tags".
+type dockerReq struct {
+	image string
+	kind  string
+	ref   string // tag, digest, or upload uuid depending on kind
+}
+
+// parseDockerPath splits the chi "*" remainder (everything after the repo name)
+// into the image name and the registry operation. The image name may itself
+// contain slashes, so operations are located by their well-known infixes.
+func parseDockerPath(rest string) (dockerReq, bool) {
+	rest = strings.TrimPrefix(rest, "/")
+	switch {
+	case strings.HasSuffix(rest, "/tags/list"):
+		return dockerReq{image: strings.TrimSuffix(rest, "/tags/list"), kind: "tags"}, true
+	case rest == "tags/list":
+		return dockerReq{}, false // no image
+	}
+	if i := strings.Index(rest, "/blobs/uploads"); i >= 0 {
+		image := rest[:i]
+		ref := strings.TrimPrefix(rest[i+len("/blobs/uploads"):], "/")
+		return dockerReq{image: image, kind: "upload", ref: ref}, image != ""
+	}
+	if i := strings.LastIndex(rest, "/manifests/"); i >= 0 {
+		return dockerReq{image: rest[:i], kind: "manifest", ref: rest[i+len("/manifests/"):]}, true
+	}
+	if i := strings.LastIndex(rest, "/blobs/"); i >= 0 {
+		return dockerReq{image: rest[:i], kind: "blob", ref: rest[i+len("/blobs/"):]}, true
+	}
+	return dockerReq{}, false
+}
+
+func isDigest(ref string) bool { return strings.HasPrefix(ref, "sha256:") }
+
+// localDockerRemote returns the repo if name is a local docker repository.
+func (h *ProxyHandler) localDockerRemote(r *http.Request, name string) (*models.Remote, bool) {
+	remote, err := h.db.GetRemote(r.Context(), name)
+	if err != nil {
+		return nil, false
+	}
+	return remote, remote.RepoType == models.RepoTypeLocal && remote.PackageType == models.PackageDocker
+}
+
+func dockerError(w http.ResponseWriter, status int, code, msg string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.WriteHeader(status)
+	fmt.Fprintf(w, `{"errors":[{"code":%q,"message":%q}]}`, code, msg)
+}
+
+// dockerGet dispatches a registry GET to the local handler for local docker
+// repos and falls through to the upstream proxy for everything else.
+func (h *ProxyHandler) dockerGet(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "remoteName")
+	if remote, ok := h.localDockerRemote(r, name); ok {
+		h.dockerLocalGet(w, r, remote, false)
+		return
+	}
+	h.handleProxy(w, r)
+}
+
+func (h *ProxyHandler) dockerHead(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "remoteName")
+	if remote, ok := h.localDockerRemote(r, name); ok {
+		h.dockerLocalGet(w, r, remote, true)
+		return
+	}
+	h.handleProxyHead(w, r)
+}
+
+func (h *ProxyHandler) dockerPost(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "remoteName")
+	remote, ok := h.localDockerRemote(r, name)
+	if !ok {
+		dockerError(w, http.StatusMethodNotAllowed, "UNSUPPORTED", "push is only supported for local docker repositories")
+		return
+	}
+	h.dockerStartUpload(w, r, remote)
+}
+
+func (h *ProxyHandler) dockerPatch(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "remoteName")
+	remote, ok := h.localDockerRemote(r, name)
+	if !ok {
+		dockerError(w, http.StatusMethodNotAllowed, "UNSUPPORTED", "push is only supported for local docker repositories")
+		return
+	}
+	h.dockerPatchUpload(w, r, remote)
+}
+
+func (h *ProxyHandler) dockerPut(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "remoteName")
+	remote, ok := h.localDockerRemote(r, name)
+	if !ok {
+		dockerError(w, http.StatusMethodNotAllowed, "UNSUPPORTED", "push is only supported for local docker repositories")
+		return
+	}
+	req, ok := parseDockerPath(chi.URLParam(r, "*"))
+	if !ok {
+		dockerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unrecognised registry path")
+		return
+	}
+	switch req.kind {
+	case "upload":
+		h.dockerFinishUpload(w, r, remote, req)
+	case "manifest":
+		h.dockerPutManifest(w, r, remote, req)
+	default:
+		dockerError(w, http.StatusMethodNotAllowed, "UNSUPPORTED", "PUT not supported for this path")
+	}
+}
+
+func (h *ProxyHandler) dockerDelete(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "remoteName")
+	remote, ok := h.localDockerRemote(r, name)
+	if !ok {
+		dockerError(w, http.StatusMethodNotAllowed, "UNSUPPORTED", "delete is only supported for local docker repositories")
+		return
+	}
+	req, ok := parseDockerPath(chi.URLParam(r, "*"))
+	if !ok {
+		dockerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unrecognised registry path")
+		return
+	}
+	// Cancel an in-progress upload: drop its staging object.
+	if req.kind == "upload" && req.ref != "" {
+		_ = h.store.Delete(r.Context(), uploadKey(req.ref))
+		w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+		w.WriteHeader(http.StatusNoContent)
+		return
+	}
+	if req.kind != "manifest" && req.kind != "blob" {
+		dockerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unrecognised registry path")
+		return
+	}
+	filePath := req.image + "/" + req.kind + "s/" + req.ref
+	if err := h.db.DeleteLocalFile(r.Context(), remote.Name, filePath); err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.WriteHeader(http.StatusAccepted)
+}
+
+// dockerLocalGet serves manifest / blob / tags-list reads for a local repo.
+func (h *ProxyHandler) dockerLocalGet(w http.ResponseWriter, r *http.Request, remote *models.Remote, head bool) {
+	req, ok := parseDockerPath(chi.URLParam(r, "*"))
+	if !ok {
+		dockerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unrecognised registry path")
+		return
+	}
+	switch req.kind {
+	case "tags":
+		h.dockerTagsList(w, r, remote, req.image)
+	case "manifest":
+		h.dockerServeRef(w, r, remote, req.image+"/manifests/"+req.ref, head, true)
+	case "blob":
+		h.dockerServeRef(w, r, remote, req.image+"/blobs/"+req.ref, head, false)
+	default:
+		dockerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unrecognised registry path")
+	}
+}
+
+// dockerServeRef streams the blob backing a local_files path. isManifest
+// controls only the default content type; the stored blob content type wins.
+func (h *ProxyHandler) dockerServeRef(w http.ResponseWriter, r *http.Request, remote *models.Remote, filePath string, head, isManifest bool) {
+	file, err := h.db.GetLocalFile(r.Context(), remote.Name, filePath)
+	if err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	if file == nil {
+		code := "BLOB_UNKNOWN"
+		if isManifest {
+			code = "MANIFEST_UNKNOWN"
+		}
+		dockerError(w, http.StatusNotFound, code, "not found")
+		return
+	}
+
+	s3Key := storage.BlobKey(file.ContentHash[len("sha256:"):])
+	reader, info, err := h.store.Download(r.Context(), s3Key)
+	if err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	defer reader.Close()
+
+	contentType := info.ContentType
+	if contentType == "" {
+		if isManifest {
+			contentType = "application/vnd.docker.distribution.manifest.v2+json"
+		} else {
+			contentType = "application/octet-stream"
+		}
+	}
+	w.Header().Set("Content-Type", contentType)
+	w.Header().Set("Content-Length", fmt.Sprintf("%d", info.Size))
+	w.Header().Set("Docker-Content-Digest", file.ContentHash)
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.Header().Set("X-Artifact-Source", "local")
+	if head {
+		w.WriteHeader(http.StatusOK)
+		return
+	}
+	w.WriteHeader(http.StatusOK)
+	io.Copy(w, reader)
+}
+
+func (h *ProxyHandler) dockerTagsList(w http.ResponseWriter, r *http.Request, remote *models.Remote, image string) {
+	prefix := image + "/manifests/"
+	files, err := h.db.ListLocalFilesByPrefix(r.Context(), remote.Name, prefix)
+	if err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	tags := []string{}
+	for _, f := range files {
+		ref := strings.TrimPrefix(f.FilePath, prefix)
+		if ref == "" || isDigest(ref) {
+			continue
+		}
+		tags = append(tags, ref)
+	}
+	sort.Strings(tags)
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.WriteHeader(http.StatusOK)
+	fmt.Fprintf(w, `{"name":%q,"tags":`, remote.Name+"/"+image)
+	writeJSONStringList(w, tags)
+	fmt.Fprint(w, "}")
+}
+
+func writeJSONStringList(w io.Writer, items []string) {
+	fmt.Fprint(w, "[")
+	for i, s := range items {
+		if i > 0 {
+			fmt.Fprint(w, ",")
+		}
+		fmt.Fprintf(w, "%q", s)
+	}
+	fmt.Fprint(w, "]")
+}
+
+// dockerStartUpload begins a blob upload. It honours a monolithic
+// POST?digest=... (blob in the POST body) and otherwise opens a chunked
+// session, returning its Location for the client's PATCH/PUT.
+func (h *ProxyHandler) dockerStartUpload(w http.ResponseWriter, r *http.Request, remote *models.Remote) {
+	req, ok := parseDockerPath(chi.URLParam(r, "*"))
+	if !ok || req.kind != "upload" {
+		dockerError(w, http.StatusNotFound, "NAME_UNKNOWN", "unrecognised registry path")
+		return
+	}
+
+	if digest := r.URL.Query().Get("digest"); digest != "" {
+		h.dockerCommitBlob(w, r, remote, req.image, digest, r.Body)
+		return
+	}
+
+	// Stage an empty object keyed by the upload UUID; PATCH/PUT append to it.
+	id := uuid.NewString()
+	if err := h.store.Upload(r.Context(), uploadKey(id), bytes.NewReader(nil), 0, "application/octet-stream"); err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	loc := fmt.Sprintf("/v2/%s/%s/blobs/uploads/%s", remote.Name, req.image, id)
+	w.Header().Set("Location", loc)
+	w.Header().Set("Docker-Upload-UUID", id)
+	w.Header().Set("Range", "0-0")
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.WriteHeader(http.StatusAccepted)
+}
+
+func (h *ProxyHandler) dockerPatchUpload(w http.ResponseWriter, r *http.Request, remote *models.Remote) {
+	req, ok := parseDockerPath(chi.URLParam(r, "*"))
+	if !ok || req.kind != "upload" || req.ref == "" {
+		dockerError(w, http.StatusNotFound, "BLOB_UPLOAD_UNKNOWN", "unknown upload")
+		return
+	}
+	size, err := h.appendUpload(r.Context(), req.ref, r.Body)
+	if err != nil {
+		if errors.Is(err, errUploadUnknown) {
+			dockerError(w, http.StatusNotFound, "BLOB_UPLOAD_UNKNOWN", "unknown upload")
+			return
+		}
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	loc := fmt.Sprintf("/v2/%s/%s/blobs/uploads/%s", remote.Name, req.image, req.ref)
+	w.Header().Set("Location", loc)
+	w.Header().Set("Docker-Upload-UUID", req.ref)
+	w.Header().Set("Range", fmt.Sprintf("0-%d", size-1))
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.WriteHeader(http.StatusAccepted)
+}
+
+// dockerFinishUpload completes a chunked upload: appends any final PUT body,
+// stores the assembled blob, and verifies its digest.
+func (h *ProxyHandler) dockerFinishUpload(w http.ResponseWriter, r *http.Request, remote *models.Remote, req dockerReq) {
+	digest := r.URL.Query().Get("digest")
+	if digest == "" {
+		dockerError(w, http.StatusBadRequest, "DIGEST_INVALID", "digest query parameter required")
+		return
+	}
+	if req.ref == "" {
+		// Monolithic PUT with no prior session: body is the whole blob.
+		h.dockerCommitBlob(w, r, remote, req.image, digest, r.Body)
+		return
+	}
+
+	key := uploadKey(req.ref)
+	reader, _, err := h.store.Download(r.Context(), key)
+	if err != nil {
+		dockerError(w, http.StatusNotFound, "BLOB_UPLOAD_UNKNOWN", "unknown upload")
+		return
+	}
+	defer reader.Close()
+	// Drop the staging object once we're done, regardless of outcome; a fresh
+	// context so cleanup still runs if the client disconnects.
+	defer h.store.Delete(context.Background(), key)
+
+	// Stream the staged bytes plus any trailing PUT body through the CAS in one
+	// pass — no extra round trip to re-assemble.
+	combined := io.MultiReader(reader, r.Body)
+	h.dockerCommitBlob(w, r, remote, req.image, digest, combined)
+}
+
+// dockerCommitBlob stores blob bytes through the CAS, verifies the client's
+// declared digest, and records the per-image local_files reference.
+func (h *ProxyHandler) dockerCommitBlob(w http.ResponseWriter, r *http.Request, remote *models.Remote, image, digest string, body io.Reader) {
+	result, err := h.cas.Store(r.Context(), body, "application/octet-stream")
+	if err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", fmt.Sprintf("store failed: %v", err))
+		return
+	}
+	if result.ContentHash != digest {
+		dockerError(w, http.StatusBadRequest, "DIGEST_INVALID", fmt.Sprintf("digest mismatch: got %s, declared %s", result.ContentHash, digest))
+		return
+	}
+	if err := h.db.UpsertBlob(r.Context(), result.ContentHash, result.S3Key, result.SizeBytes, "application/octet-stream"); err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	if err := h.db.CreateLocalFile(r.Context(), remote.Name, image+"/blobs/"+digest, result.ContentHash); err != nil && !errors.Is(err, database.ErrAlreadyExists) {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	w.Header().Set("Location", fmt.Sprintf("/v2/%s/%s/blobs/%s", remote.Name, image, digest))
+	w.Header().Set("Docker-Content-Digest", digest)
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.WriteHeader(http.StatusCreated)
+}
+
+// dockerPutManifest stores a manifest and points its reference (tag or digest)
+// at it. Tags are mutable so a re-push moves the tag; digests are immutable.
+func (h *ProxyHandler) dockerPutManifest(w http.ResponseWriter, r *http.Request, remote *models.Remote, req dockerReq) {
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	contentType := r.Header.Get("Content-Type")
+	if contentType == "" {
+		contentType = "application/vnd.docker.distribution.manifest.v2+json"
+	}
+	sum := sha256.Sum256(body)
+	digest := "sha256:" + hex.EncodeToString(sum[:])
+
+	result, err := h.cas.Store(r.Context(), strings.NewReader(string(body)), contentType)
+	if err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", fmt.Sprintf("store failed: %v", err))
+		return
+	}
+	if err := h.db.UpsertBlob(r.Context(), result.ContentHash, result.S3Key, result.SizeBytes, contentType); err != nil {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	// Always addressable by digest (immutable).
+	if err := h.db.CreateLocalFile(r.Context(), remote.Name, req.image+"/manifests/"+digest, result.ContentHash); err != nil && !errors.Is(err, database.ErrAlreadyExists) {
+		dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+		return
+	}
+	// If pushed under a tag, (re)point the tag at this manifest.
+	if !isDigest(req.ref) {
+		if err := h.db.UpsertLocalFile(r.Context(), remote.Name, req.image+"/manifests/"+req.ref, result.ContentHash); err != nil {
+			dockerError(w, http.StatusInternalServerError, "UNKNOWN", err.Error())
+			return
+		}
+	}
+
+	slog.Info("local docker manifest pushed", "repo", remote.Name, "image", req.image, "ref", req.ref, "digest", digest)
+	w.Header().Set("Location", fmt.Sprintf("/v2/%s/%s/manifests/%s", remote.Name, req.image, req.ref))
+	w.Header().Set("Docker-Content-Digest", digest)
+	w.Header().Set("Docker-Distribution-Api-Version", dockerAPIVersionHeader)
+	w.WriteHeader(http.StatusCreated)
+}

internal/api/v1/docker_test.go

@@ -0,0 +1,50 @@
+package v1
+
+import "testing"
+
+func TestParseDockerPath(t *testing.T) {
+	tests := []struct {
+		name      string
+		rest      string
+		wantOK    bool
+		wantImage string
+		wantKind  string
+		wantRef   string
+	}{
+		{"start upload trailing slash", "team/app/blobs/uploads/", true, "team/app", "upload", ""},
+		{"start upload no slash", "team/app/blobs/uploads", true, "team/app", "upload", ""},
+		{"patch upload with uuid", "team/app/blobs/uploads/abc-123", true, "team/app", "upload", "abc-123"},
+		{"single-segment image upload", "app/blobs/uploads/", true, "app", "upload", ""},
+		{"blob by digest", "team/app/blobs/sha256:deadbeef", true, "team/app", "blob", "sha256:deadbeef"},
+		{"manifest by tag", "team/app/manifests/v1.0.0", true, "team/app", "manifest", "v1.0.0"},
+		{"manifest by digest", "team/app/manifests/sha256:cafe", true, "team/app", "manifest", "sha256:cafe"},
+		{"tags list", "team/app/tags/list", true, "team/app", "tags", ""},
+		{"leading slash tolerated", "/team/app/manifests/latest", true, "team/app", "manifest", "latest"},
+		{"deep image name", "a/b/c/manifests/latest", true, "a/b/c", "manifest", "latest"},
+		{"unrecognised", "team/app/whatever", false, "", "", ""},
+		{"tags list without image", "tags/list", false, "", "", ""},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, ok := parseDockerPath(tc.rest)
+			if ok != tc.wantOK {
+				t.Fatalf("ok = %v, want %v", ok, tc.wantOK)
+			}
+			if !tc.wantOK {
+				return
+			}
+			if got.image != tc.wantImage || got.kind != tc.wantKind || got.ref != tc.wantRef {
+				t.Fatalf("got %+v, want image=%q kind=%q ref=%q", got, tc.wantImage, tc.wantKind, tc.wantRef)
+			}
+		})
+	}
+}
+
+func TestIsDigest(t *testing.T) {
+	if !isDigest("sha256:abc") {
+		t.Fatal("sha256: prefix should be a digest")
+	}
+	if isDigest("v1.0.0") {
+		t.Fatal("a tag is not a digest")
+	}
+}

internal/api/v1/npm.go

@@ -0,0 +1,334 @@
+package v1
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha1"
+	"crypto/sha512"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// Local npm repos speak the npm registry publish/read protocol. Per package:
+//   <pkg>/-/<base>-<version>.tgz   tarball (immutable)
+//   <pkg>/-/<base>-<version>.json  version manifest (immutable)
+//   <pkg>/-/dist-tags/<tag>        version string (mutable)
+
+var (
+	npmNameRe   = regexp.MustCompile(`^(@[a-z0-9][a-z0-9._~-]*/)?[a-z0-9][a-z0-9._~-]*$`)
+	npmRefRe    = regexp.MustCompile(`^[0-9A-Za-z][0-9A-Za-z.+_-]*$`)
+	npmSemverRe = regexp.MustCompile(`^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`)
+
+	npmMaxPublishBytes int64 = 256 << 20
+)
+
+func (h *ProxyHandler) localNPMRemote(r *http.Request, name string) (*models.Remote, bool) {
+	remote, err := h.db.GetRemote(r.Context(), name)
+	if err != nil {
+		return nil, false
+	}
+	return remote, remote.RepoType == models.RepoTypeLocal && remote.PackageType == models.PackageNPM
+}
+
+// npmPackageName returns the package a packument/publish path addresses, or ""
+// when the path is something else (e.g. a tarball under <pkg>/-/).
+func npmPackageName(raw string) string {
+	p, err := url.PathUnescape(raw)
+	if err != nil {
+		return ""
+	}
+	p = strings.TrimSuffix(p, "/")
+	if !npmNameRe.MatchString(p) {
+		return ""
+	}
+	return p
+}
+
+type npmRelease struct {
+	version  string
+	manifest []byte
+	tarball  []byte
+	tags     []string
+}
+
+func parseNPMPublish(body io.Reader, pkg string) (*npmRelease, error) {
+	var doc struct {
+		Name        string                     `json:"name"`
+		DistTags    map[string]string          `json:"dist-tags"`
+		Versions    map[string]json.RawMessage `json:"versions"`
+		Attachments map[string]struct {
+			Data string `json:"data"`
+		} `json:"_attachments"`
+	}
+	if err := json.NewDecoder(body).Decode(&doc); err != nil {
+		return nil, fmt.Errorf("invalid publish body: %w", err)
+	}
+	if doc.Name != pkg {
+		return nil, fmt.Errorf("body name %q does not match %q", doc.Name, pkg)
+	}
+	if len(doc.Versions) != 1 || len(doc.Attachments) != 1 {
+		return nil, errors.New("publish must carry exactly one version and one tarball")
+	}
+
+	rel := &npmRelease{}
+	for v, m := range doc.Versions {
+		rel.version, rel.manifest = v, m
+	}
+	if !npmSemverRe.MatchString(rel.version) {
+		return nil, fmt.Errorf("invalid version %q", rel.version)
+	}
+	var meta struct {
+		Name    string `json:"name"`
+		Version string `json:"version"`
+		Dist    struct {
+			Integrity string `json:"integrity"`
+			Shasum    string `json:"shasum"`
+		} `json:"dist"`
+	}
+	if err := json.Unmarshal(rel.manifest, &meta); err != nil {
+		return nil, fmt.Errorf("invalid version manifest: %w", err)
+	}
+	if meta.Name != pkg || meta.Version != rel.version {
+		return nil, errors.New("version manifest name/version mismatch")
+	}
+
+	for _, a := range doc.Attachments {
+		tgz, err := base64.StdEncoding.DecodeString(a.Data)
+		if err != nil {
+			return nil, fmt.Errorf("invalid tarball encoding: %w", err)
+		}
+		rel.tarball = tgz
+	}
+	if err := verifyNPMDist(rel.tarball, meta.Dist.Integrity, meta.Dist.Shasum); err != nil {
+		return nil, err
+	}
+
+	for tag, v := range doc.DistTags {
+		if !npmRefRe.MatchString(tag) || v != rel.version {
+			return nil, fmt.Errorf("dist-tag %q must point at the published version", tag)
+		}
+		rel.tags = append(rel.tags, tag)
+	}
+	return rel, nil
+}
+
+func verifyNPMDist(tgz []byte, integrity, shasum string) error {
+	if b64, ok := strings.CutPrefix(integrity, "sha512-"); ok {
+		sum := sha512.Sum512(tgz)
+		if base64.StdEncoding.EncodeToString(sum[:]) != b64 {
+			return errors.New("tarball does not match dist.integrity")
+		}
+		return nil
+	}
+	if shasum != "" {
+		sum := sha1.Sum(tgz)
+		if hex.EncodeToString(sum[:]) != shasum {
+			return errors.New("tarball does not match dist.shasum")
+		}
+		return nil
+	}
+	return errors.New("version manifest carries no sha512 integrity or shasum")
+}
+
+func npmError(w http.ResponseWriter, status int, msg string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(map[string]string{"error": msg})
+}
+
+func (h *ProxyHandler) handleLocalPut(w http.ResponseWriter, r *http.Request) {
+	remote, ok := h.localNPMRemote(r, chi.URLParam(r, "localName"))
+	if !ok {
+		npmError(w, http.StatusMethodNotAllowed, "publish is only supported on local npm repositories")
+		return
+	}
+	pkg := npmPackageName(chi.URLParam(r, "*"))
+	if pkg == "" {
+		npmError(w, http.StatusBadRequest, "invalid package name")
+		return
+	}
+	rel, err := parseNPMPublish(http.MaxBytesReader(w, r.Body, npmMaxPublishBytes), pkg)
+	if err != nil {
+		var tooLarge *http.MaxBytesError
+		if errors.As(err, &tooLarge) {
+			npmError(w, http.StatusRequestEntityTooLarge, fmt.Sprintf("publish body exceeds %d bytes", npmMaxPublishBytes))
+			return
+		}
+		npmError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	base := pkg[strings.LastIndex(pkg, "/")+1:]
+	stem := pkg + "/-/" + base + "-" + rel.version
+	// The manifest gates visibility and tags may only name visible versions, so
+	// the order is tarball, manifest, tags. A tarball left by a failed publish is
+	// accepted again only with identical bytes; an existing manifest always conflicts.
+	conflict := func() {
+		npmError(w, http.StatusConflict, fmt.Sprintf("%s@%s already exists; overwrites are not allowed", pkg, rel.version))
+	}
+	ok, err = h.npmStoreImmutable(r.Context(), remote.Name, stem+".tgz", rel.tarball, "application/octet-stream")
+	if err != nil {
+		npmError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	if !ok {
+		conflict()
+		return
+	}
+	if _, err := h.npmStore(r.Context(), remote.Name, stem+".json", rel.manifest, "application/json", false); err != nil {
+		if errors.Is(err, database.ErrAlreadyExists) {
+			conflict()
+			return
+		}
+		npmError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	for _, tag := range rel.tags {
+		if _, err := h.npmStore(r.Context(), remote.Name, pkg+"/-/dist-tags/"+tag, []byte(rel.version), "text/plain", true); err != nil {
+			npmError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+	}
+
+	slog.Info("local npm package published", "repo", remote.Name, "package", pkg, "version", rel.version)
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusCreated)
+	_ = json.NewEncoder(w).Encode(map[string]any{"ok": true, "id": pkg})
+}
+
+// npmStoreImmutable reports false when path already holds different bytes.
+func (h *ProxyHandler) npmStoreImmutable(ctx context.Context, repo, path string, data []byte, contentType string) (bool, error) {
+	hash, err := h.npmStore(ctx, repo, path, data, contentType, false)
+	if !errors.Is(err, database.ErrAlreadyExists) {
+		return err == nil, err
+	}
+	existing, err := h.db.GetLocalFile(ctx, repo, path)
+	if err != nil || existing == nil {
+		return false, fmt.Errorf("read existing %s: %v", path, err)
+	}
+	return existing.ContentHash == hash, nil
+}
+
+func (h *ProxyHandler) npmStore(ctx context.Context, repo, path string, data []byte, contentType string, mutable bool) (string, error) {
+	result, err := h.cas.Store(ctx, bytes.NewReader(data), contentType)
+	if err != nil {
+		return "", err
+	}
+	if err := h.db.UpsertBlob(ctx, result.ContentHash, result.S3Key, result.SizeBytes, contentType); err != nil {
+		return "", err
+	}
+	if mutable {
+		return result.ContentHash, h.db.UpsertLocalFile(ctx, repo, path, result.ContentHash)
+	}
+	return result.ContentHash, h.db.CreateLocalFile(ctx, repo, path, result.ContentHash)
+}
+
+func (h *ProxyHandler) readLocalBlob(ctx context.Context, contentHash string) ([]byte, error) {
+	reader, _, err := h.store.Download(ctx, storage.BlobKey(strings.TrimPrefix(contentHash, "sha256:")))
+	if err != nil {
+		return nil, err
+	}
+	defer reader.Close()
+	return io.ReadAll(reader)
+}
+
+func (h *ProxyHandler) serveNPMPackument(w http.ResponseWriter, r *http.Request, remote *models.Remote, pkg string) {
+	files, err := h.db.ListLocalFilesByPrefix(r.Context(), remote.Name, pkg+"/-/")
+	if err != nil {
+		npmError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	base, ok := requestBaseURL(w, r)
+	if !ok {
+		return
+	}
+	read := func(hash string) ([]byte, error) { return h.readLocalBlob(r.Context(), hash) }
+	tarballBase := base + "/api/v1/local/" + remote.Name + "/"
+	doc, err := buildNPMPackument(pkg, files, read, tarballBase)
+	if err != nil {
+		npmError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	if doc == nil {
+		npmError(w, http.StatusNotFound, "not found")
+		return
+	}
+	setNPMPerHostHeaders(w)
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("X-Artifact-Source", "local")
+	w.WriteHeader(http.StatusOK)
+	_ = json.NewEncoder(w).Encode(doc)
+}
+
+// setNPMPerHostHeaders keeps shared caches off packuments whose tarball URLs
+// are built from the request host and Accept (abbreviated vs full).
+func setNPMPerHostHeaders(w http.ResponseWriter) {
+	w.Header().Set("Cache-Control", "no-store")
+	w.Header().Set("Vary", "Host, X-Forwarded-Proto, Accept")
+}
+
+// buildNPMPackument returns nil when pkg has no published versions.
+func buildNPMPackument(pkg string, files []database.LocalFile, read func(hash string) ([]byte, error), tarballBase string) (map[string]any, error) {
+	prefix := pkg + "/-/"
+	versions := map[string]any{}
+	tags := map[string]string{}
+	for _, f := range files {
+		// LIKE treats '_' as a wildcard, so the prefix match can over-select.
+		rest, ok := strings.CutPrefix(f.FilePath, prefix)
+		if !ok {
+			continue
+		}
+		if tag, isTag := strings.CutPrefix(rest, "dist-tags/"); isTag {
+			v, err := read(f.ContentHash)
+			if err != nil {
+				return nil, err
+			}
+			tags[tag] = string(v)
+			continue
+		}
+		stem, isManifest := strings.CutSuffix(rest, ".json")
+		if !isManifest {
+			continue
+		}
+		raw, err := read(f.ContentHash)
+		if err != nil {
+			return nil, err
+		}
+		var m map[string]any
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("manifest %s: %w", f.FilePath, err)
+		}
+		dist, _ := m["dist"].(map[string]any)
+		if dist == nil {
+			dist = map[string]any{}
+			m["dist"] = dist
+		}
+		dist["tarball"] = tarballBase + prefix + stem + ".tgz"
+		v, _ := m["version"].(string)
+		versions[v] = m
+	}
+	if len(versions) == 0 {
+		return nil, nil
+	}
+	for tag, v := range tags {
+		if _, ok := versions[v]; !ok {
+			delete(tags, tag)
+		}
+	}
+	return map[string]any{"_id": pkg, "name": pkg, "dist-tags": tags, "versions": versions}, nil
+}

internal/api/v1/npm_handler_test.go

@@ -0,0 +1,333 @@
+package v1
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/internal/virtual"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+var (
+	testDSN   string
+	testMinio testsupport.MinioConn
+)
+
+func TestMain(m *testing.M) {
+	ctx := context.Background()
+	dsn, termPG, err := testsupport.StartPostgres(ctx)
+	if err != nil {
+		os.Exit(m.Run())
+	}
+	conn, termMinio, err := testsupport.StartMinio(ctx)
+	if err != nil {
+		termPG()
+		os.Exit(m.Run())
+	}
+	testDSN, testMinio = dsn, conn
+	code := m.Run()
+	termMinio()
+	termPG()
+	os.Exit(code)
+}
+
+func npmTestServer(t *testing.T) (*ProxyHandler, *httptest.Server) {
+	t.Helper()
+	if testDSN == "" {
+		t.Skip("Docker unavailable")
+	}
+	db, err := database.New(testDSN)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(db.Close)
+	var store *storage.S3
+	for i := 0; i < 20; i++ {
+		if store, err = storage.NewS3(testMinio.Endpoint, testMinio.AccessKey, testMinio.SecretKey, "npm", false, ""); err == nil {
+			break
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := NewProxyHandler(nil, nil, db, store, nil)
+	r := chi.NewRouter()
+	r.Mount("/api/v1", h.Routes())
+	srv := httptest.NewServer(r)
+	t.Cleanup(srv.Close)
+	return h, srv
+}
+
+func npmRepo(t *testing.T, h *ProxyHandler, pt models.PackageType) string {
+	t.Helper()
+	name := fmt.Sprintf("npm-%s-%d", pt, time.Now().UnixNano())
+	if err := h.db.CreateRemote(context.Background(), &models.Remote{Name: name, PackageType: pt, RepoType: models.RepoTypeLocal}); err != nil {
+		t.Fatal(err)
+	}
+	return name
+}
+
+func npmDo(t *testing.T, method, url, body string) (int, string) {
+	t.Helper()
+	req, _ := http.NewRequest(method, url, strings.NewReader(body))
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, string(b)
+}
+
+func packumentVersions(t *testing.T, url string) map[string]any {
+	t.Helper()
+	code, body := npmDo(t, http.MethodGet, url, "")
+	if code != http.StatusOK {
+		t.Fatalf("GET %s = %d: %s", url, code, body)
+	}
+	var doc struct {
+		Versions map[string]any `json:"versions"`
+	}
+	if err := json.Unmarshal([]byte(body), &doc); err != nil {
+		t.Fatal(err)
+	}
+	return doc.Versions
+}
+
+func packumentTags(t *testing.T, url string) map[string]string {
+	t.Helper()
+	_, body := npmDo(t, http.MethodGet, url, "")
+	var doc struct {
+		Tags map[string]string `json:"dist-tags"`
+	}
+	if err := json.Unmarshal([]byte(body), &doc); err != nil {
+		t.Fatal(err)
+	}
+	return doc.Tags
+}
+
+func concurrentPuts(t *testing.T, url string, bodies ...string) []int {
+	t.Helper()
+	var wg sync.WaitGroup
+	codes := make([]int, len(bodies))
+	for i, b := range bodies {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			codes[i], _ = npmDo(t, http.MethodPut, url, b)
+		}()
+	}
+	wg.Wait()
+	return codes
+}
+
+func TestNPMPublishHandler(t *testing.T) {
+	h, srv := npmTestServer(t)
+	repo := npmRepo(t, h, models.PackageNPM)
+	base := srv.URL + "/api/v1/local/" + repo + "/"
+
+	t.Run("scoped name via %2f", func(t *testing.T) {
+		body := publishBody(t, "@acme/widget", []byte("scoped tgz"), publishOpts{})
+		if code, b := npmDo(t, http.MethodPut, base+"@acme%2fwidget", body); code != http.StatusCreated {
+			t.Fatalf("publish = %d: %s", code, b)
+		}
+		v := packumentVersions(t, base+"@acme%2fwidget")
+		dist := v["1.0.0"].(map[string]any)["dist"].(map[string]any)
+		tarball := dist["tarball"].(string)
+		if !strings.HasPrefix(tarball, base+"@acme/widget/-/widget-1.0.0.tgz") {
+			t.Fatalf("tarball = %s", tarball)
+		}
+		if code, b := npmDo(t, http.MethodGet, tarball, ""); code != http.StatusOK || b != "scoped tgz" {
+			t.Fatalf("tarball fetch = %d %q", code, b)
+		}
+	})
+
+	t.Run("republish", func(t *testing.T) {
+		if code, b := npmDo(t, http.MethodPut, base+"repub", publishBody(t, "repub", []byte("v1"), publishOpts{})); code != http.StatusCreated {
+			t.Fatalf("first publish = %d: %s", code, b)
+		}
+		if code, _ := npmDo(t, http.MethodPut, base+"repub", publishBody(t, "repub", []byte("different"), publishOpts{})); code != http.StatusConflict {
+			t.Errorf("different bytes = %d, want 409", code)
+		}
+		if code, b := npmDo(t, http.MethodPut, base+"repub", publishBody(t, "repub", []byte("v2"), publishOpts{version: "1.1.0"})); code != http.StatusCreated {
+			t.Fatalf("publish 1.1.0 = %d: %s", code, b)
+		}
+		if code, _ := npmDo(t, http.MethodPut, base+"repub", publishBody(t, "repub", []byte("v1"), publishOpts{})); code != http.StatusConflict {
+			t.Errorf("identical republish = %d, want 409", code)
+		}
+		if tags := packumentTags(t, base+"repub"); tags["latest"] != "1.1.0" {
+			t.Errorf("latest = %q, want 1.1.0", tags["latest"])
+		}
+	})
+
+	t.Run("rejected republish leaves tags", func(t *testing.T) {
+		for _, v := range []string{"1.0.0", "1.1.0"} {
+			if code, b := npmDo(t, http.MethodPut, base+"rej", publishBody(t, "rej", []byte("tgz "+v), publishOpts{version: v})); code != http.StatusCreated {
+				t.Fatalf("publish %s = %d: %s", v, code, b)
+			}
+		}
+		if code, _ := npmDo(t, http.MethodPut, base+"rej", publishBody(t, "rej", []byte("tgz 1.0.0"), publishOpts{shasum: "x"})); code != http.StatusConflict {
+			t.Fatalf("re-PUT 1.0.0 = %d, want 409", code)
+		}
+		if tags := packumentTags(t, base+"rej"); tags["latest"] != "1.1.0" {
+			t.Errorf("latest = %q, want 1.1.0", tags["latest"])
+		}
+	})
+
+	t.Run("mid-publish window", func(t *testing.T) {
+		if code, b := npmDo(t, http.MethodPut, base+"mid", publishBody(t, "mid", []byte("v1"), publishOpts{})); code != http.StatusCreated {
+			t.Fatalf("publish = %d: %s", code, b)
+		}
+		ctx := context.Background()
+		if _, err := h.npmStore(ctx, repo, "mid/-/mid-1.0.1.tgz", []byte("v2"), "application/octet-stream", false); err != nil {
+			t.Fatal(err)
+		}
+		if tags := packumentTags(t, base+"mid"); tags["latest"] != "1.0.0" {
+			t.Errorf("tarball-only 1.0.1: latest = %q", tags["latest"])
+		}
+		if _, err := h.npmStore(ctx, repo, "mid/-/dist-tags/latest", []byte("1.0.1"), "text/plain", true); err != nil {
+			t.Fatal(err)
+		}
+		if tags := packumentTags(t, base+"mid"); tags["latest"] == "1.0.1" {
+			t.Error("latest points at invisible 1.0.1")
+		}
+	})
+
+	t.Run("concurrent identical", func(t *testing.T) {
+		body := publishBody(t, "same", []byte("same tgz"), publishOpts{})
+		codes := concurrentPuts(t, base+"same", body, body)
+		if codes[0]+codes[1] != http.StatusCreated+http.StatusConflict || codes[0] == codes[1] {
+			t.Fatalf("codes = %v, want one 201 and one 409", codes)
+		}
+		if tags := packumentTags(t, base+"same"); len(tags) != 1 || tags["latest"] != "1.0.0" {
+			t.Errorf("tags = %v", tags)
+		}
+	})
+
+	t.Run("concurrent different manifests", func(t *testing.T) {
+		tgz := []byte("race tgz")
+		codes := concurrentPuts(t, base+"race",
+			publishBody(t, "race", tgz, publishOpts{shasum: "a", tags: map[string]string{"a": "1.0.0"}}),
+			publishBody(t, "race", tgz, publishOpts{shasum: "b", tags: map[string]string{"b": "1.0.0"}}))
+		won := map[int]string{}
+		for i, c := range codes {
+			won[c] = []string{"a", "b"}[i]
+		}
+		if len(won) != 2 || won[http.StatusCreated] == "" || won[http.StatusConflict] == "" {
+			t.Fatalf("codes = %v, want one 201 and one 409", codes)
+		}
+		v := packumentVersions(t, base+"race")["1.0.0"].(map[string]any)
+		if got := v["dist"].(map[string]any)["shasum"]; got != won[http.StatusCreated] {
+			t.Errorf("manifest shasum = %v, winner %s", got, won[http.StatusCreated])
+		}
+		tags := packumentTags(t, base+"race")
+		if len(tags) != 1 || tags[won[http.StatusCreated]] != "1.0.0" {
+			t.Errorf("tags = %v, winner %s", tags, won[http.StatusCreated])
+		}
+	})
+
+	t.Run("retry after tarball-only write", func(t *testing.T) {
+		tgz := []byte("half published")
+		if _, err := h.npmStore(context.Background(), repo, "retry/-/retry-1.0.0.tgz", tgz, "application/octet-stream", false); err != nil {
+			t.Fatal(err)
+		}
+		if code, _ := npmDo(t, http.MethodGet, base+"retry", ""); code != http.StatusNotFound {
+			t.Fatalf("tarball-only version visible: %d", code)
+		}
+		if code, _ := npmDo(t, http.MethodPut, base+"retry", publishBody(t, "retry", []byte("other bytes"), publishOpts{})); code != http.StatusConflict {
+			t.Errorf("retry with different bytes = %d, want 409", code)
+		}
+		if code, b := npmDo(t, http.MethodPut, base+"retry", publishBody(t, "retry", tgz, publishOpts{})); code != http.StatusCreated {
+			t.Fatalf("retry with identical bytes = %d: %s", code, b)
+		}
+		if _, ok := packumentVersions(t, base+"retry")["1.0.0"]; !ok {
+			t.Error("retried version missing from packument")
+		}
+	})
+
+	t.Run("concurrent versions", func(t *testing.T) {
+		codes := concurrentPuts(t, base+"conc",
+			publishBody(t, "conc", []byte("tgz 1.0.0"), publishOpts{version: "1.0.0"}),
+			publishBody(t, "conc", []byte("tgz 2.0.0"), publishOpts{version: "2.0.0"}))
+		if codes[0] != http.StatusCreated || codes[1] != http.StatusCreated {
+			t.Fatalf("codes = %v", codes)
+		}
+		v := packumentVersions(t, base+"conc")
+		if _, ok := v["1.0.0"]; !ok {
+			t.Error("1.0.0 missing")
+		}
+		if _, ok := v["2.0.0"]; !ok {
+			t.Error("2.0.0 missing")
+		}
+	})
+
+	t.Run("body too large", func(t *testing.T) {
+		old := npmMaxPublishBytes
+		npmMaxPublishBytes = 64
+		defer func() { npmMaxPublishBytes = old }()
+		if code, _ := npmDo(t, http.MethodPut, base+"big", publishBody(t, "big", []byte("x"), publishOpts{})); code != http.StatusRequestEntityTooLarge {
+			t.Errorf("oversized body = %d, want 413", code)
+		}
+	})
+
+	t.Run("non-npm local", func(t *testing.T) {
+		generic := npmRepo(t, h, models.PackageGeneric)
+		if code, _ := npmDo(t, http.MethodPut, srv.URL+"/api/v1/local/"+generic+"/pkg", publishBody(t, "pkg", []byte("x"), publishOpts{})); code != http.StatusMethodNotAllowed {
+			t.Errorf("publish to generic local = %d, want 405", code)
+		}
+	})
+}
+
+func TestNPMPackumentPerHost(t *testing.T) {
+	h, srv := npmTestServer(t)
+	h.virtualEngine = virtual.NewEngine(h.db, nil)
+	h.virtualEngine.NPMLocal = h.LocalNPMPackument
+	repo := npmRepo(t, h, models.PackageNPM)
+	virt := "v" + repo
+	if err := h.db.CreateVirtual(context.Background(), &models.Virtual{Name: virt, PackageType: models.PackageNPM, Members: []string{repo}}); err != nil {
+		t.Fatal(err)
+	}
+	if code, b := npmDo(t, http.MethodPut, srv.URL+"/api/v1/local/"+repo+"/hostpkg", publishBody(t, "hostpkg", []byte("tgz"), publishOpts{})); code != http.StatusCreated {
+		t.Fatalf("publish = %d: %s", code, b)
+	}
+	routes := h.Routes()
+	get := func(path, host, proto string) *httptest.ResponseRecorder {
+		r := httptest.NewRequest(http.MethodGet, path, nil)
+		r.Host = host
+		if proto != "" {
+			r.Header.Set("X-Forwarded-Proto", proto)
+		}
+		w := httptest.NewRecorder()
+		routes.ServeHTTP(w, r)
+		return w
+	}
+	for _, path := range []string{"/local/" + repo + "/hostpkg", "/virtual/" + virt + "/hostpkg"} {
+		for _, host := range []string{"x@evil.com", "evil.example:"} {
+			if w := get(path, host, ""); w.Code != http.StatusBadRequest {
+				t.Errorf("%s Host %q = %d, want 400", path, host, w.Code)
+			}
+		}
+		w := get(path, "aa.example", "https")
+		if w.Code != http.StatusOK || !strings.Contains(w.Body.String(), `"tarball":"https://aa.example/api/v1/`) {
+			t.Fatalf("%s = %d: %s", path, w.Code, w.Body)
+		}
+		if cc, vary := w.Header().Get("Cache-Control"), w.Header().Get("Vary"); cc != "no-store" || vary != "Host, X-Forwarded-Proto, Accept" {
+			t.Errorf("%s Cache-Control %q Vary %q", path, cc, vary)
+		}
+	}
+}

internal/api/v1/npm_test.go

@@ -0,0 +1,166 @@
+package v1
+
+import (
+	"crypto/sha1"
+	"crypto/sha512"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+)
+
+func TestNPMPackageName(t *testing.T) {
+	tests := map[string]string{
+		"left-pad":                "left-pad",
+		"left-pad/":               "left-pad",
+		"@acme%2fwidget":          "@acme/widget",
+		"@acme%2Fwidget":          "@acme/widget",
+		"@acme/widget":            "@acme/widget",
+		"left-pad/-/left-pad.tgz": "",
+		"@acme/widget/-/w-1.tgz":  "",
+		"a/b":                     "",
+		"../etc":                  "",
+		"Upper":                   "",
+		"":                        "",
+	}
+	for in, want := range tests {
+		if got := npmPackageName(in); got != want {
+			t.Errorf("npmPackageName(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+type publishOpts struct {
+	bodyName, manifestName, version, integrity, shasum string
+	tags                                               map[string]string
+	extraVersion                                       bool
+}
+
+func publishBody(t *testing.T, pkg string, tgz []byte, o publishOpts) string {
+	t.Helper()
+	sha := sha512.Sum512(tgz)
+	sh1 := sha1.Sum(tgz)
+	if o.bodyName == "" {
+		o.bodyName = pkg
+	}
+	if o.manifestName == "" {
+		o.manifestName = pkg
+	}
+	if o.version == "" {
+		o.version = "1.0.0"
+	}
+	if o.integrity == "" {
+		o.integrity = "sha512-" + base64.StdEncoding.EncodeToString(sha[:])
+	}
+	if o.shasum == "" {
+		o.shasum = hex.EncodeToString(sh1[:])
+	}
+	if o.tags == nil {
+		o.tags = map[string]string{"latest": o.version}
+	}
+	versions := map[string]any{o.version: map[string]any{
+		"name": o.manifestName, "version": o.version, "main": "index.js",
+		"dist": map[string]any{"integrity": o.integrity, "shasum": o.shasum, "tarball": "http://elsewhere/x.tgz"},
+	}}
+	if o.extraVersion {
+		versions["2.0.0"] = map[string]any{"name": pkg, "version": "2.0.0"}
+	}
+	b, _ := json.Marshal(map[string]any{
+		"_id": pkg, "name": o.bodyName, "dist-tags": o.tags, "versions": versions,
+		"_attachments": map[string]any{pkg + "-" + o.version + ".tgz": map[string]any{
+			"content_type": "application/octet-stream", "data": base64.StdEncoding.EncodeToString(tgz), "length": len(tgz),
+		}},
+	})
+	return string(b)
+}
+
+func TestParseNPMPublish(t *testing.T) {
+	tgz := []byte("fake tarball bytes")
+
+	rel, err := parseNPMPublish(strings.NewReader(publishBody(t, "@acme/widget", tgz, publishOpts{tags: map[string]string{"latest": "1.0.0", "beta": "1.0.0"}})), "@acme/widget")
+	if err != nil {
+		t.Fatalf("valid scoped publish rejected: %v", err)
+	}
+	if rel.version != "1.0.0" || string(rel.tarball) != string(tgz) || len(rel.tags) != 2 {
+		t.Fatalf("unexpected release: %+v", rel)
+	}
+
+	if _, err := parseNPMPublish(strings.NewReader(publishBody(t, "left-pad", tgz, publishOpts{integrity: "none", shasum: hex.EncodeToString(make([]byte, 20))})), "left-pad"); err == nil {
+		t.Fatal("shasum fallback should reject a mismatched tarball")
+	}
+	if _, err := parseNPMPublish(strings.NewReader(publishBody(t, "left-pad", tgz, publishOpts{integrity: "none"})), "left-pad"); err != nil {
+		t.Fatalf("matching shasum fallback rejected: %v", err)
+	}
+
+	bad := map[string]publishOpts{
+		"body name mismatch":        {bodyName: "other"},
+		"manifest name mismatch":    {manifestName: "other"},
+		"integrity mismatch":        {integrity: "sha512-AAAA"},
+		"path-like version":         {version: "../1.0.0"},
+		"non-semver version":        {version: "1..2"},
+		"leading-zero version":      {version: "01.0.0"},
+		"tag at another version":    {tags: map[string]string{"latest": "9.9.9"}},
+		"path-like tag":             {tags: map[string]string{"../x": "1.0.0"}},
+		"multiple versions at once": {extraVersion: true},
+	}
+	for name, o := range bad {
+		if _, err := parseNPMPublish(strings.NewReader(publishBody(t, "left-pad", tgz, o)), "left-pad"); err == nil {
+			t.Errorf("%s: expected rejection", name)
+		}
+	}
+	if _, err := parseNPMPublish(strings.NewReader(`{"name":"left-pad","versions":{}}`), "left-pad"); err == nil {
+		t.Error("deprecate-style body without attachments should be rejected")
+	}
+}
+
+func TestBuildNPMPackument(t *testing.T) {
+	blobs := map[string]string{
+		"h1": `{"name":"my_pkg","version":"1.0.0","dist":{"shasum":"aa","tarball":"http://elsewhere/x.tgz"}}`,
+		"h2": `{"name":"my_pkg","version":"1.1.0"}`,
+		"h3": "1.1.0",
+		"h4": "2.0.0",
+		"hx": `{"name":"myXpkg","version":"6.6.6"}`,
+	}
+	read := func(h string) ([]byte, error) {
+		b, ok := blobs[h]
+		if !ok {
+			return nil, errors.New("missing blob")
+		}
+		return []byte(b), nil
+	}
+	files := []database.LocalFile{
+		{FilePath: "my_pkg/-/dist-tags/latest", ContentHash: "h3"},
+		{FilePath: "my_pkg/-/dist-tags/next", ContentHash: "h4"},
+		{FilePath: "my_pkg/-/my_pkg-1.0.0.json", ContentHash: "h1"},
+		{FilePath: "my_pkg/-/my_pkg-1.0.0.tgz", ContentHash: "nope"},
+		{FilePath: "my_pkg/-/my_pkg-1.1.0.json", ContentHash: "h2"},
+		{FilePath: "myXpkg/-/myXpkg-6.6.6.json", ContentHash: "hx"},
+	}
+
+	doc, err := buildNPMPackument("my_pkg", files, read, "http://reg/api/v1/local/npm/")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if tags := doc["dist-tags"].(map[string]string); tags["latest"] != "1.1.0" || len(tags) != 1 {
+		t.Errorf("dist-tags = %v", tags)
+	}
+	versions := doc["versions"].(map[string]any)
+	if len(versions) != 2 {
+		t.Fatalf("versions = %v (LIKE over-match must be dropped)", versions)
+	}
+	v1 := versions["1.0.0"].(map[string]any)["dist"].(map[string]any)
+	if v1["tarball"] != "http://reg/api/v1/local/npm/my_pkg/-/my_pkg-1.0.0.tgz" || v1["shasum"] != "aa" {
+		t.Errorf("1.0.0 dist = %v", v1)
+	}
+	if versions["1.1.0"].(map[string]any)["dist"].(map[string]any)["tarball"] != "http://reg/api/v1/local/npm/my_pkg/-/my_pkg-1.1.0.tgz" {
+		t.Error("1.1.0 missing rewritten tarball")
+	}
+
+	if doc, err := buildNPMPackument("absent", files, read, "x/"); err != nil || doc != nil {
+		t.Errorf("absent package: doc=%v err=%v", doc, err)
+	}
+}