Adopt golib/pg for migrations and pool construction

artifactapi's schema was a ~180-line inline DDL blob re-executed on every
start, growing an ALTER TABLE ... IF NOT EXISTS line per change with nothing
recording what had run. golib/pg already owns that mechanic for the estate, so
move the SQL into a versioned, embedded set and let the library apply it.

- Depend on git.unkin.net/unkin/golib v0.1.0.
- Move the DDL verbatim to migrations/0001_init.sql, embedded via the new
  migrations package, and build the pool with pg.NewMigrated (LockName
  "artifactapi-migrations"). The runner adds a cluster-wide advisory lock the
  old blob never took, so replicas starting together queue instead of racing
  each other through the DDL.
- The live database has the schema but no schema_migrations, so its first start
  on this build re-runs 0001. Every statement is IF NOT EXISTS-guarded, so that
  run is a no-op landing only the tracking row; a container-backed test drops
  the row from a migrated database and asserts exactly that, and a static guard
  keeps future migrations additive and idempotent.
- Keep config.DatabaseDSN as the DSN source rather than pg.DSNFromEnv: the
  variable names match, but golib has no default user or database name, and
  artifactapi documents and ships DBUSER/DBNAME defaults of "artifacts". The
  deployed env var contract is unchanged.
- Guard the embedded set against migrations/ and pin the derived advisory key,
  so neither can drift unnoticed.
- Plumb GOPRIVATE=git.unkin.net for the first cross-repo Go dependency:
  exported by the Makefile, set in the Dockerfile and the woodpecker Go steps,
  documented in the README.

.gitignore

@@ -1,51 +1,6 @@
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
+bin/
+/terraform/
 
-# Virtual environment
-.venv/
-venv/
-ENV/
-env/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-
-# Environment variables
-.env
-remotes.yaml
-
-# Logs
-*.log
-
-# uv
-uv.lock
-
-# Docker volumes
-minio_data/
-
-# Local configuration overrides
-docker-compose.yml
-ca-bundle.pem
+# 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/**

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: https://github.com/dnephin/pre-commit-golang
+    rev: v0.5.1
+    hooks:
+      - id: go-fmt
+      - id: go-mod-tidy
+
+  - repo: local
+    hooks:
+      - id: go-vet
+        name: go vet
+        entry: go vet ./...
+        language: system
+        types: [go]
+        pass_filenames: false

.woodpecker/build.yaml

@@ -0,0 +1,9 @@
+when:
+  - event: pull_request
+
+steps:
+  - name: docker-build
+    image: woodpeckerci/plugin-docker-buildx
+    settings:
+      repo: git.unkin.net/unkin/artifactapi
+      dry_run: true

.woodpecker/docker.yaml

@@ -0,0 +1,34 @@
+when:
+  - event: tag
+    ref: refs/tags/v*
+
+steps:
+  - name: docker-api
+    image: woodpeckerci/plugin-docker-buildx
+    settings:
+      registry: git.unkin.net
+      repo: git.unkin.net/unkin/artifactapi
+      build_args:
+        VERSION: ${CI_COMMIT_TAG}
+      username: droneci
+      password:
+        from_secret: DRONECI_PASSWORD
+      tags:
+        - ${CI_COMMIT_TAG}
+        - latest
+
+  - name: docker-web
+    image: woodpeckerci/plugin-docker-buildx
+    settings:
+      registry: git.unkin.net
+      repo: git.unkin.net/unkin/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

.woodpecker/pre-commit.yaml

@@ -0,0 +1,20 @@
+when:
+  - event: pull_request
+
+steps:
+  - name: pre-commit
+    image: git.unkin.net/unkin/almalinux9-gobuilder:20260606
+    commands:
+      - uvx pre-commit run --all-files
+    environment:
+      # golib lives on Gitea; skip the public proxy/sum db.
+      GOPRIVATE: git.unkin.net
+    backend_options:
+      kubernetes:
+        resources:
+          requests:
+            memory: 512Mi
+            cpu: 1
+          limits:
+            memory: 2Gi
+            cpu: 2

.woodpecker/test.yaml

@@ -0,0 +1,11 @@
+when:
+  - event: pull_request
+
+steps:
+  - name: test
+    image: golang:1.25
+    commands:
+      - go test -race -count=1 ./pkg/... ./internal/...
+    environment:
+      # golib lives on Gitea; skip the public proxy/sum db.
+      GOPRIVATE: git.unkin.net

Dockerfile

@@ -1,51 +1,25 @@
-# Use Alpine Linux as base image
-FROM python:3.11-alpine
+FROM golang:1.25-alpine AS builder
 
-# Set working directory
-WORKDIR /app
+RUN apk add --no-cache git
 
-# Install system dependencies
-RUN apk add --no-cache \
-    gcc \
-    musl-dev \
-    libffi-dev \
-    postgresql-dev \
-    curl \
-    wget \
-    tar
+WORKDIR /build
 
-# Install uv
-ARG PACKAGE_VERSION=0.9.21
-RUN wget -O /app/uv-x86_64-unknown-linux-musl.tar.gz https://github.com/astral-sh/uv/releases/download/${PACKAGE_VERSION}/uv-x86_64-unknown-linux-musl.tar.gz && \
-    tar xf /app/uv-x86_64-unknown-linux-musl.tar.gz -C /app && \
-    mv /app/uv-x86_64-unknown-linux-musl/uv /usr/local/bin/uv && \
-    rm -rf /app/uv-x86_64-unknown-linux-musl* && \
-    chmod +x /usr/local/bin/uv && \
-    uv --version
+# 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
 
-# Create non-root user first
-RUN adduser -D -s /bin/sh appuser && \
-    chown -R appuser:appuser /app
+COPY go.mod go.sum ./
+RUN go mod download
 
-# Copy dependency files and change ownership
-COPY --chown=appuser:appuser pyproject.toml uv.lock README.md ./
+COPY . .
 
-# Switch to appuser and install Python dependencies
-USER appuser
 ARG VERSION=dev
-RUN HATCH_VCS_PRETEND_VERSION=${VERSION} uv sync --frozen
+RUN CGO_ENABLED=0 go build -ldflags="-s -w -X main.version=${VERSION}" -o artifactapi ./cmd/artifactapi
 
-# Copy application source
-COPY --chown=appuser:appuser src/ ./src/
-COPY --chown=appuser:appuser remotes.yaml ./
-COPY --chown=appuser:appuser ca-bundle.pem ./
+FROM gcr.io/distroless/static-debian12:nonroot
+
+COPY --from=builder /build/artifactapi /usr/local/bin/artifactapi
 
-# Expose port
 EXPOSE 8000
 
-# Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost:8000/health || exit 1
-
-# Run the application
-CMD ["uv", "run", "python", "-m", "src.artifactapi.main"]
+ENTRYPOINT ["artifactapi"]

Makefile

@@ -1,53 +1,59 @@
-.PHONY: build install dev clean test lint format docker-build docker-up docker-down docker-logs docker-rebuild docker-clean docker-restart
+.PHONY: build test lint fmt e2e docker-e2e docker docker-ui compose clean tidy check-go
 
-build:
-	docker build --no-cache -t artifactapi:latest .
+BINARY := bin/artifactapi
+MODULE := git.unkin.net/unkin/artifactapi
+VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "0.0.0-dev")
+GO_VERSION_REQUIRED := 1.23
+GO_VERSION_ACTUAL := $(shell go version | sed 's/go version go\([0-9]*\.[0-9]*\).*/\1/')
 
-install: build
+# 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
 
-docker-build: build
+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; \
+	fi
 
-dev: build
-	uv sync --dev
+build: check-go tidy
+	go build -ldflags="-s -w -X main.version=$(VERSION)" -o $(BINARY) ./cmd/artifactapi
+
+test: check-go
+	go test -race -count=1 ./pkg/... ./internal/...
+
+lint: check-go
+	golangci-lint run ./...
+	go vet ./...
+
+fmt: check-go
+	gofmt -w .
+	goimports -w .
+
+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) .
+
+docker-ui:
+	docker build -t artifactapi-ui:$(VERSION) -f ui/Dockerfile.ui ui/
+
+compose:
+	docker compose up -d
 
 clean:
-	rm -rf .venv
-	rm -rf build/
-	rm -rf dist/
-	rm -rf *.egg-info/
+	rm -rf bin/
 
-test:
-	uv run pytest
-
-lint:
-	uv run ruff check --fix .
-
-format:
-	uv run ruff format .
-
-run:
-	uv run python -m src.artifactapi.main
-
-docker-up:
-	docker-compose up --build --force-recreate -d
-
-docker-down:
-	docker-compose down
-
-docker-logs:
-	docker-compose logs -f
-
-docker-rebuild:
-	docker-compose build --no-cache
-
-docker-clean:
-	docker-compose down -v --remove-orphans
-	docker system prune -f
-
-docker-restart: docker-down docker-up
+tidy:
+	go mod tidy
 
 # Bump helpers — reads the latest semver tag and creates the next one.
-# If no tag exists yet, starts from v0.0.0.
 _LATEST := $(shell git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$$' | head -1)
 _BASE   := $(if $(_LATEST),$(_LATEST),v0.0.0)
 _MAJ    := $(shell echo $(_BASE) | sed 's/^v//' | cut -d. -f1)
@@ -68,4 +74,3 @@ major:
 
 _tag:
 	git push origin $(TAG)
-	docker-compose build --no-cache --build-arg VERSION=$(TAG:v%=%)

PLAN.md

@@ -0,0 +1,880 @@
+# ArtifactAPI v3 — Go Rewrite Plan
+
+## Context
+
+ArtifactAPI is a production artifact proxy/cache serving ~42 remotes (Docker registries, Helm repos, RPM/Alpine repos, GitHub releases, PyPI, npm, Puppet Forge, Terraform registries, Go module proxies) across a Kubernetes cluster. The current Python (FastAPI) implementation works but has architectural debt: opaque hashed S3 paths, no UI for visibility, YAML config files that drift, no garbage collection, no access logging, and virtual repos limited to Helm only.
+
+The v3 rewrite targets: a single Go binary (API + TUI), a separate React frontend (own Dockerfile), a Terraform provider (separate repo), content-addressable storage, and a cleaner data model that makes the cache inspectable and manageable.
+
+**Repo**: Same repo (`git.unkin.net/unkin/artifactapi`), new branch.
+**Module**: `git.unkin.net/unkin/artifactapi`
+**Frontend**: React + Vite, separate Dockerfile, talks to API
+**Terraform provider**: Separate repo (`terraform-provider-artifactapi`)
+
+---
+
+## Architecture Overview
+
+```
+┌───────────────────────────────────┐    ┌──────────────────────┐
+│        Go Binary (API + TUI)      │    │   Frontend Container │
+│                                   │    │                      │
+│  ┌──────────┐  ┌───────────────┐  │    │  React + Vite SPA    │
+│  │ REST API │  │ Proxy Engine  │  │◄───│  nginx / node serve  │
+│  │ /api/v2  │  │ /api/v1/...   │  │    │  Dockerfile.ui       │
+│  │          │  │ /v2/... (OCI) │  │    └──────────────────────┘
+│  └────┬─────┘  └──────┬────────┘  │
+│       │               │           │    ┌──────────────────────┐
+│  ┌────┴───────────────┴────────┐  │    │ Terraform Provider   │
+│  │        Data Layer           │  │◄───│ (separate repo)      │
+│  │  PostgreSQL · Redis · S3    │  │    └──────────────────────┘
+│  └─────────────────────────────┘  │
+│                                   │    ┌──────────────────────┐
+│  ┌─────────────────────────────┐  │    │ TUI (subcommand)     │
+│  │  artifactapi tui            │──│───►│ artifactapi tui      │
+│  └─────────────────────────────┘  │    │ --endpoint <url>     │
+└───────────────────────────────────┘    └──────────────────────┘
+```
+
+Three independent deployment units:
+1. **Go binary** — API server + TUI subcommand (single `Dockerfile`)
+2. **React frontend** — SPA served by nginx (`Dockerfile.ui`), talks to `/api/v2`
+3. **Terraform provider** — separate repo, calls `/api/v2` CRUD
+
+---
+
+## Project Structure (Modular)
+
+```
+artifactapi/
+├── cmd/
+│   └── artifactapi/
+│       └── main.go                     # entrypoint: serve / tui subcommands
+│
+├── pkg/                                # PUBLIC — importable by terraform provider, CLI tools
+│   ├── models/                         # shared domain types
+│   │   ├── remote.go                   # Remote, RemoteConfig, PackageType enum
+│   │   ├── virtual.go                  # Virtual, VirtualConfig
+│   │   ├── artifact.go                 # Artifact, Blob, AccessLogEntry
+│   │   ├── local.go                    # LocalFile, LocalRepo
+│   │   └── stats.go                    # RemoteStats, OverviewStats
+│   └── client/                         # typed Go API client (used by TUI + Terraform provider)
+│       ├── client.go                   # Client struct, base HTTP
+│       ├── remotes.go                  # remote CRUD methods
+│       ├── virtuals.go                 # virtual CRUD methods
+│       ├── objects.go                  # object browse/evict methods
+│       └── stats.go                    # stats methods
+│
+├── internal/                           # PRIVATE — server internals
+│   ├── server/
+│   │   ├── server.go                   # HTTP server setup, router
+│   │   └── middleware.go               # logging, recovery, request-id, access logging
+│   │
+│   ├── api/
+│   │   ├── v1/                         # proxy endpoints (v1 compat)
+│   │   │   ├── proxy.go               # GET /api/v1/remote/{name}/{path}
+│   │   │   ├── docker.go              # /v2/{name}/{path}
+│   │   │   ├── virtual.go             # GET /api/v1/virtual/{name}/{path}
+│   │   │   └── local.go               # CRUD /api/v1/local/{name}/{path}
+│   │   └── v2/                         # management API
+│   │       ├── remotes.go             # CRUD + stats
+│   │       ├── virtuals.go            # CRUD
+│   │       ├── objects.go             # browse/evict cached objects
+│   │       ├── stats.go               # overview, top-remotes
+│   │       ├── events.go              # SSE stream
+│   │       └── health.go              # health, metrics
+│   │
+│   ├── provider/                       # package-type providers (registry protocol handlers)
+│   │   ├── provider.go                # Provider interface + registry
+│   │   ├── generic/
+│   │   │   ├── generic.go
+│   │   │   └── generic_test.go
+│   │   ├── docker/
+│   │   │   ├── docker.go              # OCI Distribution v2 via go-containerregistry
+│   │   │   ├── auth.go                # Bearer token fetch + cache
+│   │   │   └── docker_test.go
+│   │   ├── helm/
+│   │   │   ├── helm.go                # index rewriting via helm.sh/helm/v3/pkg/repo
+│   │   │   ├── merger.go              # virtual index merge
+│   │   │   └── helm_test.go
+│   │   ├── pypi/
+│   │   │   ├── pypi.go                # simple index HTML rewriting
+│   │   │   ├── merger.go              # virtual simple index merge
+│   │   │   └── pypi_test.go
+│   │   ├── npm/
+│   │   │   ├── npm.go                 # metadata JSON rewriting
+│   │   │   └── npm_test.go
+│   │   ├── rpm/
+│   │   │   ├── rpm.go                 # repodata patterns
+│   │   │   └── rpm_test.go
+│   │   ├── alpine/
+│   │   │   ├── alpine.go              # APKINDEX patterns
+│   │   │   └── alpine_test.go
+│   │   ├── puppet/
+│   │   │   ├── puppet.go              # file_uri JSON rewriting
+│   │   │   └── puppet_test.go
+│   │   ├── terraform/
+│   │   │   ├── terraform.go           # registry protocol, download URL rewriting
+│   │   │   └── terraform_test.go
+│   │   └── goproxy/
+│   │       ├── goproxy.go             # Go module proxy protocol (GOPROXY)
+│   │       └── goproxy_test.go
+│   │
+│   ├── proxy/
+│   │   ├── engine.go                  # core fetch-or-cache logic
+│   │   ├── engine_test.go
+│   │   ├── classifier.go              # immutable vs mutable classification
+│   │   ├── classifier_test.go
+│   │   ├── revalidator.go             # conditional HEAD requests (ETag/Last-Modified)
+│   │   └── circuit.go                 # per-remote circuit breaker
+│   │
+│   ├── storage/
+│   │   ├── s3.go                      # S3 client (minio-go — works with MinIO, Ceph, AWS)
+│   │   ├── s3_test.go
+│   │   ├── cas.go                     # content-addressable store logic
+│   │   └── cas_test.go
+│   │
+│   ├── cache/
+│   │   ├── redis.go                   # TTL management, fetch locks
+│   │   ├── redis_test.go
+│   │   └── lock.go                    # distributed lock abstraction
+│   │
+│   ├── database/
+│   │   ├── postgres.go                # connection pool, migration runner
+│   │   ├── queries/                   # SQL query files or sqlc-generated code
+│   │   │   ├── remotes.sql.go
+│   │   │   ├── virtuals.sql.go
+│   │   │   ├── artifacts.sql.go
+│   │   │   └── access_log.sql.go
+│   │   └── migrations/               # golang-migrate SQL files
+│   │       ├── 001_initial.up.sql
+│   │       └── 001_initial.down.sql
+│   │
+│   ├── metrics/
+│   │   └── prometheus.go             # counters, gauges, histograms
+│   │
+│   ├── gc/
+│   │   ├── gc.go                      # background garbage collection goroutine
+│   │   └── gc_test.go
+│   │
+│   ├── tui/
+│   │   ├── app.go                     # Bubble Tea main model
+│   │   ├── views/
+│   │   │   ├── dashboard.go
+│   │   │   ├── remotes.go
+│   │   │   ├── objects.go
+│   │   │   └── virtuals.go
+│   │   └── components/
+│   │       ├── table.go
+│   │       └── statusbar.go
+│   │
+│   └── config/
+│       └── env.go                     # environment variable parsing + validation
+│
+├── ui/                                 # React frontend — SEPARATE DOCKERFILE
+│   ├── src/
+│   │   ├── App.tsx
+│   │   ├── pages/
+│   │   │   ├── Dashboard.tsx
+│   │   │   ├── Remotes.tsx
+│   │   │   ├── RemoteDetail.tsx
+│   │   │   ├── Virtuals.tsx
+│   │   │   └── Objects.tsx
+│   │   ├── components/
+│   │   │   ├── RemoteTable.tsx
+│   │   │   ├── ObjectBrowser.tsx
+│   │   │   ├── StatsCard.tsx
+│   │   │   └── EventFeed.tsx
+│   │   └── api/
+│   │       └── client.ts              # typed API client
+│   ├── package.json
+│   ├── vite.config.ts
+│   ├── tsconfig.json
+│   ├── Dockerfile.ui                  # multi-stage: node build → nginx
+│   └── nginx.conf                     # proxy /api/* to backend, serve SPA
+│
+├── e2e/                                # end-to-end integration tests
+│   ├── e2e_test.go                    # TestMain spins up docker-compose stack
+│   ├── proxy_test.go                  # proxy through real remotes
+│   ├── docker_test.go                 # Docker v2 protocol e2e
+│   ├── management_test.go            # v2 API CRUD
+│   ├── virtual_test.go               # virtual repo merge e2e
+│   └── docker-compose.e2e.yml        # postgres + redis + minio for tests
+│
+├── go.mod
+├── go.sum
+├── Makefile
+├── Dockerfile                          # Go binary (API server + TUI)
+├── Dockerfile.ui                       # symlink or copy → ui/Dockerfile.ui
+└── docker-compose.yml
+```
+
+### Key Modularisation Decisions
+
+- **`pkg/models/`** — Shared domain types importable by the Terraform provider and any external tooling. No dependencies on internal packages
+- **`pkg/client/`** — Typed Go API client used by both the TUI and the Terraform provider. Depends only on `pkg/models/` and stdlib
+- **`internal/provider/`** — Each package type is its own subpackage with isolated tests. A provider registry maps `PackageType → Provider`
+- **`internal/database/queries/`** — Use [sqlc](https://sqlc.dev/) to generate type-safe query functions from SQL, or hand-written query files
+- **`e2e/`** — Separate test binary that spins up a real docker-compose stack
+
+---
+
+## Go Ecosystem Libraries
+
+Prefer existing, maintained Go modules over writing protocol handlers from scratch.
+
+### Package-Type Libraries
+
+| Package Type | Go Module | What It Gives Us |
+|---|---|---|
+| **Docker/OCI** | `github.com/google/go-containerregistry` | Full Registry v2/OCI client: manifest parsing, auth challenges, blob operations. `pkg/registry` can implement a v2 server. Reference: `github.com/regclient/regclient` |
+| **Helm** | `helm.sh/helm/v3/pkg/repo` | Parse/generate `index.yaml`, `IndexFile`/`ChartVersion` types, URL entries. Used directly for merge |
+| **Terraform** | `github.com/hashicorp/terraform-registry-address` | Provider/module address parsing, `ForRegistryProtocol()` URL generation. Protocol spec: provider registry protocol v1 |
+| **Go Modules** | `github.com/goproxy/goproxy` | Minimalist GOPROXY protocol handler, implements full spec as `http.Handler`. Handles `/@v/list`, `/@v/{v}.info`, `/@v/{v}.mod`, `/@v/{v}.zip`, `/@latest` |
+| **RPM** | `rs3.io/go/rpm/repomd` | Parse `repomd.xml`, `primary.xml` with proper XML namespace handling |
+| **Alpine** | `gitlab.alpinelinux.org/alpine/go` | Official Alpine library: parse APKINDEX, `.apk` files |
+| **PyPI** | stdlib `golang.org/x/net/html` | No dedicated Go PyPI library exists. Parse simple index HTML with `x/net/html`, extract `<a>` tags. Minimal — the rewriting is just href replacement |
+| **npm** | stdlib `encoding/json` | npm metadata is JSON — parse with stdlib, rewrite `dist.tarball` URLs. No special library needed |
+| **Puppet Forge** | stdlib `encoding/json` | Forge API is JSON — parse and rewrite `file_uri` fields. Community lib `github.com/johnmccabe/go-puppetforge` exists but is thin; stdlib suffices |
+
+### Infrastructure Libraries
+
+| Purpose | Go Module | Why This One |
+|---|---|---|
+| **HTTP router** | `github.com/go-chi/chi/v5` | Lightweight, stdlib `http.Handler` compatible, middleware chain |
+| **PostgreSQL** | `github.com/jackc/pgx/v5` | Pure Go, connection pooling, COPY support, prepared statements |
+| **SQL generation** | `github.com/sqlc-dev/sqlc` | Generate type-safe Go from SQL queries — no ORM, no reflection |
+| **Redis** | `github.com/redis/go-redis/v9` | Full Redis client, pipelining, pub/sub |
+| **S3 (MinIO/Ceph/AWS)** | `github.com/minio/minio-go/v7` | Native S3-compatible client. Works with MinIO, Ceph RGW, AWS S3, any S3-compatible backend out of the box. Lighter than aws-sdk-go-v2, purpose-built for S3 compat |
+| **DB migrations** | `github.com/golang-migrate/migrate/v4` | SQL file-based migrations, CLI + library |
+| **Prometheus** | `github.com/prometheus/client_golang` | Counters, gauges, histograms |
+| **TUI** | `github.com/charmbracelet/bubbletea` | Elm-architecture TUI framework |
+| **TUI styling** | `github.com/charmbracelet/lipgloss` | Terminal styling |
+| **TUI components** | `github.com/charmbracelet/bubbles` | Table, text input, spinner, etc. |
+| **Structured logging** | `log/slog` (stdlib) | Go 1.21+ structured logging, zero dependencies |
+| **Testing** | `github.com/stretchr/testify` | Assertions + require for unit tests |
+| **Test containers** | `github.com/testcontainers/testcontainers-go` | Spin up Postgres/Redis/MinIO in e2e tests |
+
+### S3 Client: Multi-Backend Support
+
+Using `minio-go/v7` as the S3 client because it natively supports:
+- **MinIO** — primary development/production target
+- **Ceph RGW** — S3-compatible via endpoint config
+- **AWS S3** — via region + credential config
+- **Any S3-compatible** — GCS (interop mode), Wasabi, DigitalOcean Spaces, etc.
+
+No abstraction layer needed — `minio-go` handles endpoint differences internally. Config:
+```go
+client, _ := minio.New(endpoint, &minio.Options{
+    Creds:  credentials.NewStaticV4(accessKey, secretKey, ""),
+    Secure: useTLS,
+    Region: region, // optional, for AWS
+})
+```
+
+---
+
+## Data Layer
+
+### PostgreSQL Schema
+
+```sql
+-- Remotes: managed exclusively by Terraform
+CREATE TABLE remotes (
+    name            TEXT PRIMARY KEY,
+    package_type    TEXT NOT NULL,  -- generic, docker, helm, pypi, npm, rpm, alpine, puppet, terraform, goproxy
+    base_url        TEXT NOT NULL,
+    description     TEXT DEFAULT '',
+    username        TEXT DEFAULT '',
+    password        TEXT DEFAULT '',
+    immutable_ttl   INTEGER DEFAULT 0,
+    mutable_ttl     INTEGER DEFAULT 3600,
+    check_mutable   BOOLEAN DEFAULT TRUE,
+    immutable_patterns  TEXT[] DEFAULT '{}',  -- user-defined immutable patterns
+    mutable_patterns    TEXT[] DEFAULT '{}',  -- user-defined mutable patterns (merged with provider built-ins)
+    allowlist        TEXT[] DEFAULT '{}',     -- if empty, allow all paths; if non-empty, only matching paths proxied
+    blocklist        TEXT[] DEFAULT '{}',     -- always denied, checked before allowlist
+    ban_tags_enabled    BOOLEAN DEFAULT FALSE,
+    ban_tags            TEXT[] DEFAULT '{}',
+    quarantine_enabled  BOOLEAN DEFAULT FALSE,
+    quarantine_days     INTEGER DEFAULT 3,
+    stale_on_error      BOOLEAN DEFAULT TRUE,
+    releases_remote     TEXT DEFAULT '',  -- terraform type: name of CDN remote for download URL rewriting
+    managed_by          TEXT DEFAULT '',  -- 'terraform' or empty
+    created_at      TIMESTAMPTZ DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Virtual repositories
+CREATE TABLE virtuals (
+    name            TEXT PRIMARY KEY,
+    package_type    TEXT NOT NULL,
+    description     TEXT DEFAULT '',
+    members         TEXT[] NOT NULL,
+    managed_by      TEXT DEFAULT '',
+    created_at      TIMESTAMPTZ DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Content-addressable blob storage tracking
+CREATE TABLE blobs (
+    content_hash    TEXT PRIMARY KEY,
+    s3_key          TEXT NOT NULL,
+    size_bytes      BIGINT NOT NULL,
+    content_type    TEXT DEFAULT 'application/octet-stream',
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Artifact metadata: maps (remote, path) → content blob
+CREATE TABLE artifacts (
+    id              BIGSERIAL PRIMARY KEY,
+    remote_name     TEXT NOT NULL REFERENCES remotes(name) ON DELETE CASCADE,
+    path            TEXT NOT NULL,
+    content_hash    TEXT NOT NULL REFERENCES blobs(content_hash),
+    upstream_etag   TEXT DEFAULT '',
+    upstream_last_modified TIMESTAMPTZ,
+    first_seen_at   TIMESTAMPTZ DEFAULT NOW(),
+    last_fetched_at TIMESTAMPTZ DEFAULT NOW(),
+    last_accessed_at TIMESTAMPTZ DEFAULT NOW(),
+    fetch_count     BIGINT DEFAULT 1,
+    access_count    BIGINT DEFAULT 1,
+    UNIQUE(remote_name, path)
+);
+
+CREATE INDEX idx_artifacts_remote ON artifacts(remote_name);
+CREATE INDEX idx_artifacts_last_accessed ON artifacts(last_accessed_at);
+
+-- Local file uploads
+CREATE TABLE local_files (
+    id              BIGSERIAL PRIMARY KEY,
+    repo_name       TEXT NOT NULL,
+    file_path       TEXT NOT NULL,
+    content_hash    TEXT NOT NULL REFERENCES blobs(content_hash),
+    created_at      TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(repo_name, file_path)
+);
+
+-- Access log (append-only, powers dashboards)
+CREATE TABLE access_log (
+    id              BIGSERIAL PRIMARY KEY,
+    remote_name     TEXT NOT NULL,
+    path            TEXT NOT NULL,
+    cache_hit       BOOLEAN NOT NULL,
+    size_bytes      BIGINT DEFAULT 0,
+    upstream_ms     INTEGER DEFAULT 0,
+    client_ip       TEXT DEFAULT '',
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_access_log_remote_time ON access_log(remote_name, created_at);
+```
+
+### Redis Usage (Ephemeral Only)
+
+| Key pattern | Type | TTL | Purpose |
+|---|---|---|---|
+| `ttl:{remote}:{path}` | STRING | remote's immutable/mutable TTL | Artifact freshness — existence = still fresh |
+| `lock:{remote}:{path}` | STRING (NX) | 30s | Fetch lock — prevents thundering herd |
+| `etag:{remote}:{path}` | STRING | same as TTL key | Cached ETag for conditional revalidation |
+| `circuit:{remote}` | STRING | configurable | Circuit breaker — consecutive failure count |
+
+Losing Redis = all TTLs expire = next request re-validates upstream. No data loss.
+
+### S3 Layout (Content-Addressable)
+
+```
+artifacts-bucket/
+├── blobs/sha256/{content_hash}     # immutable CAS blobs
+├── indexes/{remote}/{path}          # mutable index files (helm, pypi, rpm, etc.)
+├── indexes/{virtual}/{path}         # merged virtual indexes
+└── local/{repo}/{path}              # user uploads (CAS-backed via blobs table)
+```
+
+---
+
+## Terraform Remote Type (New in v2)
+
+The `terraform` package type proxies the Terraform Provider Registry Protocol:
+
+- **URL construction**: prepends `/v1/providers/` to request paths
+- **Built-in mutable pattern**: `[^/]+/[^/]+/versions$` (version listings change over time)
+- **Built-in immutable pattern**: `[^/]+/[^/]+/[^/]+/download/[^/]+/[^/]+$` (per-version download info is fixed)
+- **Response rewriting**: download info JSON — rewrites `download_url`, `shasums_url`, `shasums_signature_url` to route through a companion `releases_remote` (e.g., `hashicorp-releases` generic remote)
+- **Config**: requires `releases_remote` field pointing to the CDN remote that serves the actual binaries
+
+Uses `github.com/hashicorp/terraform-registry-address` for address parsing and protocol-compliant URL generation.
+
+---
+
+## Go Module Proxy Remote Type (New)
+
+The `goproxy` package type implements the GOPROXY protocol (Go module proxy):
+
+| Endpoint | Mutability | Description |
+|---|---|---|
+| `{module}/@v/list` | Mutable | Plain text list of known versions |
+| `{module}/@latest` | Mutable | JSON metadata for latest version |
+| `{module}/@v/{version}.info` | Immutable | JSON version metadata (`Version`, `Time`) |
+| `{module}/@v/{version}.mod` | Immutable | `go.mod` file for that version |
+| `{module}/@v/{version}.zip` | Immutable | Source archive for that version |
+
+- **No URL rewriting needed** — responses are self-contained (no embedded URLs)
+- **Config**: `base_url` points to upstream proxy (e.g., `https://proxy.golang.org`)
+- **Client usage**: set `GOPROXY=https://artifactapi.example.com/api/v1/remote/goproxy`
+- Uses `github.com/goproxy/goproxy` for protocol handling
+
+---
+
+## Allowlist / Blocklist / Automatic Mutable Patterns
+
+### Access Control (Per-Remote)
+
+| Field | Default | Behavior |
+|---|---|---|
+| `blocklist` | `[]` (empty) | If a path matches any blocklist pattern → **403 Forbidden**. Checked first |
+| `allowlist` | `[]` (empty) | If empty → **allow everything**. If non-empty → only matching paths are proxied; everything else → **403** |
+
+Evaluation order: blocklist → allowlist → proxy. No allowlist + no blocklist = open proxy (default).
+
+### Automatic Mutable Patterns (Per-Provider Built-ins)
+
+Each provider declares built-in mutable patterns that are **always merged** with user-defined `mutable_patterns`. Users never need to configure these — the provider knows which paths change over time.
+
+| Provider | Built-in Mutable Patterns | Rationale |
+|---|---|---|
+| **generic** | *(none)* | No convention for what's mutable |
+| **docker** | `/manifests/(?!sha256:)[^/]+$`, `/tags/list$` | Tag manifests change; digest manifests don't |
+| **helm** | `index\.yaml$` | Chart index changes when new charts are published |
+| **pypi** | `simple/` | Package index pages change with new releases |
+| **npm** | `^[^/]+$` (package metadata, not `.tgz`) | Package metadata changes; tarballs are immutable |
+| **rpm** | `repomd\.xml$`, `repodata/.*`, `Packages\.gz$` | Repo metadata rebuilt on every publish |
+| **alpine** | `APKINDEX\.tar\.gz$` | Package index rebuilt on every publish |
+| **puppet** | `^v3/modules/`, `^v3/releases` | Module metadata changes with new releases |
+| **terraform** | `[^/]+/[^/]+/versions$` | Provider version listings grow over time |
+| **goproxy** | `@v/list$`, `@latest$` | Version list and latest pointer change |
+
+These are returned by `Provider.BuiltinMutablePatterns()` and merged at classification time:
+```
+effective_mutable = provider.BuiltinMutablePatterns() ∪ remote.mutable_patterns
+```
+
+If a path matches `effective_mutable` → use `mutable_ttl`. If it matches `remote.immutable_patterns` → use `immutable_ttl`. Immutable patterns take precedence over mutable when both match.
+
+---
+
+## API Design
+
+### v1 Proxy Endpoints (Backwards Compatible)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/v1/remote/{name}/{path}` | Proxy/cache artifact |
+| `GET` | `/api/v1/virtual/{name}/{path}` | Virtual repo proxy |
+| `GET/HEAD` | `/v2/{name}/{path}` | Docker Registry v2 |
+| `GET` | `/v2/` | Docker v2 ping |
+| `GET/PUT/HEAD/DELETE` | `/api/v1/local/{name}/{path}` | Local repo CRUD |
+
+### v2 Management API (New)
+
+```
+GET    /api/v2/remotes                              → [{name, package_type, base_url, description, stats}]
+GET    /api/v2/remotes/{name}                       → {full config + stats + health}
+POST   /api/v2/remotes                              → create remote (Terraform provider)
+PUT    /api/v2/remotes/{name}                        → update remote (Terraform provider)
+DELETE /api/v2/remotes/{name}                        → delete remote — cascades artifacts, GC cleans S3
+
+GET    /api/v2/virtuals                             → [{name, package_type, members, stats}]
+GET    /api/v2/virtuals/{name}                      → {full config + member details}
+POST   /api/v2/virtuals                             → create virtual
+PUT    /api/v2/virtuals/{name}                       → update virtual
+DELETE /api/v2/virtuals/{name}                       → delete virtual
+
+GET    /api/v2/remotes/{name}/objects               → paginated objects
+         ?q=pattern&sort=size|accessed|age&page=1&per_page=50
+DELETE /api/v2/remotes/{name}/objects/{path}         → evict specific cached object
+DELETE /api/v2/remotes/{name}/cache                 → flush cache
+         ?type=all|indexes|blobs
+
+GET    /api/v2/stats                                → overview stats
+GET    /api/v2/stats/top-remotes                    → top remotes by size/requests/hit-rate
+
+GET    /api/v2/health                               → {status, postgres, redis, s3, uptime}
+GET    /metrics                                     → Prometheus format
+GET    /api/v2/events                               → SSE stream
+```
+
+---
+
+## Proxy Engine
+
+### Request Flow
+
+```
+Client Request
+    │
+    ▼
+Classify (immutable/mutable/denied)
+    │
+    ├── blocklist match → 403
+    ├── allowlist non-empty + no match → 403
+    │
+    ▼
+Check Redis TTL key
+    │
+    ├── exists (fresh) → serve from S3, log access
+    │
+    ├── missing (expired or uncached)
+    │   │
+    │   ▼
+    │   Acquire fetch lock (Redis SETNX, 30s TTL)
+    │   │
+    │   ├── lock acquired
+    │   │   ├── mutable + check_mutable + have ETag → HEAD upstream
+    │   │   │   ├── 304 → refresh TTL, serve from S3
+    │   │   │   └── changed → full fetch
+    │   │   └── full fetch from upstream
+    │   │       → provider.RewriteResponse() if needed
+    │   │       → CAS store (hash → check blobs → upload if new)
+    │   │       → upsert artifact in Postgres
+    │   │       → set Redis TTL + release lock
+    │   │       → on upstream error + stale_on_error → refresh TTL, serve stale
+    │   │
+    │   └── lock not acquired → poll S3 briefly, serve if another pod fetched it
+    │
+    ▼
+Stream response from S3, log access
+```
+
+### Circuit Breaker
+
+Per-remote, tracked in Redis. Closed → Open (after N failures) → Half-open (after cooldown). Exposed via `GET /api/v2/remotes/{name}` health field.
+
+### Content-Addressable Storage
+
+1. Stream upstream → temp file, compute SHA256 inline
+2. Check `blobs` table for hash
+3. Exists → skip S3 upload, upsert `artifacts` row only
+4. New → upload to `blobs/sha256/{hash}`, insert both rows
+
+### Garbage Collection
+
+Background goroutine (configurable interval, default 1h):
+1. Orphaned blobs: delete S3 objects whose `content_hash` has no referencing `artifacts` or `local_files` rows
+2. Cold artifacts: optional per-remote, delete artifacts not accessed in N days
+3. Remote deletion: `ON DELETE CASCADE` handles Postgres; GC sweeps orphaned blobs
+
+---
+
+## Package Providers
+
+### Provider Interface
+
+```go
+type Provider interface {
+    Type() models.PackageType
+    BuiltinMutablePatterns() []*regexp.Regexp
+    BuiltinImmutablePatterns() []*regexp.Regexp
+    ContentType(path string) string
+    UpstreamURL(remote models.Remote, path string) string
+    RewriteResponse(body []byte, remote models.Remote, proxyBaseURL string) ([]byte, error)
+    AuthHeaders(ctx context.Context, remote models.Remote) (http.Header, error)
+}
+
+type IndexMerger interface {
+    MergeIndexes(members []MemberIndex, proxyBaseURL string) ([]byte, error)
+}
+```
+
+### Provider Registry
+
+```go
+var registry = map[models.PackageType]Provider{
+    models.PackageGeneric:   &generic.Provider{},
+    models.PackageDocker:    &docker.Provider{},
+    models.PackageHelm:      &helm.Provider{},
+    models.PackagePyPI:      &pypi.Provider{},
+    models.PackageNPM:       &npm.Provider{},
+    models.PackageRPM:       &rpm.Provider{},
+    models.PackageAlpine:    &alpine.Provider{},
+    models.PackagePuppet:    &puppet.Provider{},
+    models.PackageTerraform: &terraform.Provider{},
+    models.PackageGoProxy:   &goproxy.Provider{},
+}
+
+func Get(t models.PackageType) (Provider, error) { ... }
+```
+
+Each provider lives in its own subpackage under `internal/provider/` with its own `_test.go`.
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+Every package gets `_test.go` files alongside the source. Run with `go test ./...`.
+
+| Package | What's Tested |
+|---|---|
+| `internal/provider/docker/` | Auth token parsing/caching, manifest classification, tag banning, URL construction, blob key generation |
+| `internal/provider/helm/` | `index.yaml` parsing (using `helm.sh/helm/v3/pkg/repo`), URL rewriting, index merging |
+| `internal/provider/pypi/` | Simple index HTML parsing, URL rewriting, index merging |
+| `internal/provider/npm/` | Metadata JSON rewriting (`dist.tarball` URLs) |
+| `internal/provider/terraform/` | Registry URL construction, download info JSON rewriting, `releases_remote` URL extraction |
+| `internal/provider/rpm/` | Mutable pattern matching (repodata) |
+| `internal/provider/alpine/` | Mutable pattern matching (APKINDEX) |
+| `internal/provider/puppet/` | `file_uri` JSON rewriting |
+| `internal/proxy/` | Classifier (immutable vs mutable vs denied), circuit breaker state transitions, revalidator logic |
+| `internal/storage/` | CAS key generation, dedup detection, S3 operation mocking |
+| `internal/cache/` | Redis TTL set/check, fetch lock acquire/release/contention |
+| `internal/gc/` | Orphan detection queries, cold artifact selection |
+| `pkg/models/` | Model validation, PackageType enum |
+| `pkg/client/` | API client request/response serialization |
+
+### End-to-End Tests
+
+Located in `e2e/`. Use `testcontainers-go` to spin up real Postgres, Redis, and MinIO containers. The test binary starts the actual `artifactapi` server against these backends.
+
+```go
+// e2e/e2e_test.go
+func TestMain(m *testing.M) {
+    // Start postgres, redis, minio via testcontainers-go
+    // Run migrations
+    // Start artifactapi server on random port
+    // Run tests
+    // Tear down
+}
+```
+
+| Test File | What's Tested |
+|---|---|
+| `e2e/proxy_test.go` | Proxy a real GitHub release through generic remote, verify S3 storage, verify Redis TTL, verify Postgres artifact row, verify cache hit on second request |
+| `e2e/docker_test.go` | Pull a real image manifest + blob through Docker v2 proxy, verify blob deduplication, tag banning |
+| `e2e/management_test.go` | Full CRUD lifecycle: create remote via v2 API, proxy through it, list objects, evict object, flush cache, delete remote |
+| `e2e/virtual_test.go` | Create two helm remotes + virtual, fetch merged index, verify priority ordering |
+| `e2e/terraform_test.go` | Proxy terraform provider version listing + download info, verify URL rewriting to releases_remote |
+| `e2e/goproxy_test.go` | Proxy Go module `@v/list`, `.info`, `.mod`, `.zip` through GOPROXY remote, verify mutable vs immutable classification |
+| `e2e/gc_test.go` | Create artifact, delete remote, trigger GC, verify S3 blob cleaned up |
+
+### Code Quality
+
+- `gofmt` / `goimports` — enforced in CI, run on save
+- `golangci-lint` — comprehensive linter suite (staticcheck, errcheck, govet, etc.)
+- `go vet ./...` — run in CI
+- Makefile targets: `make test`, `make lint`, `make e2e`, `make fmt`
+
+---
+
+## Terraform Provider (Separate Repo)
+
+**Repo**: `terraform-provider-artifactapi`
+**Uses**: `pkg/client/` and `pkg/models/` from the main module
+
+```hcl
+provider "artifactapi" {
+  endpoint = "https://artifactapi.k8s.syd1.au.unkin.net"
+}
+
+resource "artifactapi_remote" "terraform_registry" {
+  name            = "terraform-registry"
+  package_type    = "terraform"
+  base_url        = "https://registry.terraform.io"
+  description     = "Terraform provider registry"
+  releases_remote = artifactapi_remote.hashicorp_releases.name
+
+  immutable_patterns = [
+    "[^/]+/[^/]+/[^/]+/download/[^/]+/[^/]+$",
+  ]
+
+  cache {
+    immutable_ttl = 0
+    mutable_ttl   = 300
+  }
+}
+
+resource "artifactapi_remote" "hashicorp_releases" {
+  name         = "hashicorp-releases"
+  package_type = "generic"
+  base_url     = "https://releases.hashicorp.com"
+
+  immutable_patterns = [
+    ".*\\.zip$",
+    ".*SHA256SUMS(\\.sig)?$",
+  ]
+
+  cache {
+    immutable_ttl = 0
+    mutable_ttl   = 0
+  }
+}
+
+resource "artifactapi_virtual" "helm" {
+  name         = "helm"
+  package_type = "helm"
+  description  = "All helm repos merged"
+  members      = [
+    artifactapi_remote.jetstack.name,
+    artifactapi_remote.hashicorp_helm.name,
+  ]
+}
+```
+
+---
+
+## Web UI (React + Vite — Separate Container)
+
+### Deployment
+
+Separate `Dockerfile.ui`: multi-stage build (node → nginx). Served as its own container/pod. nginx proxies `/api/*` to the Go backend.
+
+### Pages
+
+| Route | Content |
+|---|---|
+| `/` | Dashboard: total objects, storage used, dedup savings, bandwidth saved, top remotes chart, live SSE event feed, health indicators |
+| `/remotes` | Remote table: name, type, description, object count, size, hit rate, health. Filter by type, sort any column |
+| `/remotes/:name` | Config (read-only, "Managed by Terraform" badge), stats, object browser with search/sort/evict, flush actions |
+| `/virtuals` | Virtual table: name, type, members, merged object count |
+| `/virtuals/:name` | Member list with individual stats |
+
+All config is read-only — managed by Terraform.
+
+---
+
+## TUI (Bubble Tea — Subcommand)
+
+`artifactapi tui --endpoint http://localhost:8000` or via `ARTIFACTAPI_ENDPOINT` env.
+
+Uses `pkg/client/` for all API calls (same client as Terraform provider).
+
+| View | Key bindings |
+|---|---|
+| Dashboard | summary stats, top remotes |
+| Remotes list | `j`/`k` navigate, `/` filter, `Enter` detail |
+| Remote detail | config + stats, `Enter` → object browser |
+| Object browser | `/` search, `d` evict, `f` flush |
+| Virtuals | `j`/`k`, `Enter` detail |
+
+---
+
+## Improvements Over v2
+
+| Area | v2 (Python) | v3 (Go) |
+|---|---|---|
+| S3 paths | Hashed, opaque | Content-addressed CAS |
+| Config | YAML files, mtime reload | Terraform via API |
+| Package types | 8 types | 10 types (+ terraform, goproxy) |
+| Virtual repos | Helm only | Helm + PyPI, extensible |
+| Deduplication | Docker blobs only | All types via CAS |
+| Revalidation | Opt-in flag | Default for all mutable |
+| Access logging | None | Per-artifact in Postgres |
+| GC | None | Background goroutine |
+| Upstream health | Per-request | Circuit breaker |
+| S3 backends | MinIO only | MinIO, Ceph, AWS (minio-go) |
+| UI | None | Web dashboard + TUI |
+| Binary | Python + venv | Static Go binary |
+| Frontend | N/A | Separate container (React) |
+| Testing | Mocked unit tests | Unit + e2e with real backends |
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core Engine + Models
+- Go module, Makefile (`make build test lint fmt e2e`), Dockerfile, docker-compose
+- `pkg/models/` — all domain types
+- PostgreSQL schema + migrations
+- S3 storage layer with CAS (`minio-go/v7`)
+- Redis cache layer (TTL, locks)
+- Proxy engine: fetch-or-cache, classifier, revalidator
+- Generic + Docker providers (most complexity: OCI auth, CAS, tag banning)
+- Health + metrics endpoints
+- Unit tests for all packages
+- **Milestone**: proxy Docker + generic, cache in S3, track in Postgres
+
+### Phase 2: All Providers
+- Helm (using `helm.sh/helm/v3/pkg/repo`)
+- PyPI (stdlib `x/net/html`)
+- npm (stdlib `encoding/json`)
+- RPM (using `rs3.io/go/rpm/repomd`)
+- Alpine (using `gitlab.alpinelinux.org/alpine/go`)
+- Puppet Forge (stdlib `encoding/json`)
+- Terraform (using `hashicorp/terraform-registry-address`)
+- Go Modules / GOPROXY (using `github.com/goproxy/goproxy`)
+- Unit tests per provider
+- **Milestone**: feature parity with v2 + goproxy
+
+### Phase 3: Management API + Virtual Repos + GC
+- `pkg/client/` — shared Go API client
+- v2 CRUD endpoints
+- Virtual repo engine: `IndexMerger` for Helm + PyPI
+- Circuit breaker
+- Access logging middleware
+- GC goroutine
+- **Milestone**: full API, virtuals, GC
+
+### Phase 4: End-to-End Tests
+- `e2e/` test suite with `testcontainers-go`
+- Proxy, Docker, management, virtual, terraform, GC tests
+- CI pipeline: `make e2e`
+- **Milestone**: comprehensive e2e coverage
+
+### Phase 5: Terraform Provider
+- Separate repo: `terraform-provider-artifactapi`
+- Imports `pkg/client/` and `pkg/models/`
+- `artifactapi_remote` + `artifactapi_virtual` resources + data sources
+- Import support
+- **Milestone**: manage all config via Terraform
+
+### Phase 6: Web UI
+- React + Vite in `ui/`
+- `Dockerfile.ui` (multi-stage → nginx)
+- Dashboard, remotes, objects, virtuals pages
+- SSE event feed
+- **Milestone**: full web UI in separate container
+
+### Phase 7: TUI
+- Bubble Tea in `internal/tui/`
+- Uses `pkg/client/`
+- Dashboard, remotes, objects, virtuals views
+- **Milestone**: TUI feature parity with web UI
+
+### Phase 8: Migration + Cutover
+- Migration tool: v2 YAML → Terraform HCL + `terraform import` commands
+- S3 rehash script: `{remote}/{hash16}/{file}` → `blobs/sha256/{content_hash}`
+- Parallel run, response comparison
+- Cutover
+
+---
+
+## Makefile Targets
+
+```makefile
+.PHONY: build test lint fmt e2e docker docker-ui
+
+build:                  ## Build Go binary
+	go build -o bin/artifactapi ./cmd/artifactapi
+
+test:                   ## Run unit tests
+	go test ./...
+
+lint:                   ## Run golangci-lint + go vet
+	golangci-lint run ./...
+	go vet ./...
+
+fmt:                    ## Format code (gofmt + goimports)
+	gofmt -w .
+	goimports -w .
+
+e2e:                    ## Run end-to-end tests (requires Docker)
+	go test -tags=e2e -count=1 -timeout=5m ./e2e/...
+
+docker:                 ## Build API server Docker image
+	docker build -t artifactapi .
+
+docker-ui:              ## Build frontend Docker image
+	docker build -t artifactapi-ui -f ui/Dockerfile.ui ui/
+
+compose:                ## Start full stack (API + UI + Postgres + Redis + MinIO)
+	docker compose up -d
+```

cmd/artifactapi/main.go

@@ -0,0 +1,57 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"git.unkin.net/unkin/artifactapi/internal/config"
+	"git.unkin.net/unkin/artifactapi/internal/server"
+	"git.unkin.net/unkin/artifactapi/internal/tui"
+)
+
+var version = "dev"
+
+func main() {
+	if len(os.Args) > 1 && os.Args[1] == "tui" {
+		endpoint := os.Getenv("ARTIFACTAPI_ENDPOINT")
+		if endpoint == "" {
+			endpoint = "http://localhost:8000"
+		}
+		for i, arg := range os.Args {
+			if arg == "--endpoint" && i+1 < len(os.Args) {
+				endpoint = os.Args[i+1]
+			}
+		}
+
+		app := tui.New(endpoint)
+		if err := app.Run(); err != nil {
+			fmt.Fprintf(os.Stderr, "tui error: %v\n", err)
+			os.Exit(1)
+		}
+		return
+	}
+
+	cfg, err := config.Load()
+	if err != nil {
+		slog.Error("failed to load config", "error", err)
+		os.Exit(1)
+	}
+
+	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer cancel()
+
+	srv, err := server.New(cfg, version)
+	if err != nil {
+		slog.Error("failed to create server", "error", err)
+		os.Exit(1)
+	}
+
+	if err := srv.Run(ctx); err != nil {
+		slog.Error("server exited with error", "error", err)
+		os.Exit(1)
+	}
+}

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

@@ -0,0 +1,91 @@
+services:
+  artifactapi:
+    build: .
+    ports:
+      - "${ARTIFACTAPI_PORT:-8000}:8000"
+    environment:
+      LISTEN_ADDR: ":8000"
+      DBHOST: postgres
+      DBPORT: "5432"
+      DBUSER: artifacts
+      DBPASS: artifacts123
+      DBNAME: artifacts
+      DBSSL: disable
+      REDIS_URL: redis://redis:6379
+      MINIO_ENDPOINT: minio:9000
+      MINIO_ACCESS_KEY: minioadmin
+      MINIO_SECRET_KEY: minioadmin
+      MINIO_BUCKET: artifacts
+      MINIO_SECURE: "false"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  ui:
+    build:
+      context: ui
+      dockerfile: Dockerfile.ui
+    ports:
+      - "8080:80"
+    depends_on:
+      - artifactapi
+
+  postgres:
+    image: postgres:17-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: artifacts
+      POSTGRES_PASSWORD: artifacts123
+      POSTGRES_DB: artifacts
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U artifacts -d artifacts"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    command: redis-server --save 20 1
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  minio:
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+  redis_data:
+  minio_data:

e2e-docker/README.md

@@ -0,0 +1,51 @@
+# 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 (generic, docker,
+  helm, pypi, npm, rpm, alpine, puppet, terraform, goproxy) proxied through the
+  mock upstream: first fetch `X-Artifact-Source: remote`, second `cache`, bytes
+  verified against the origin fixture.
+- **Local uploads** — generic (upload/download), pypi (wheel + generated `simple/`
+  index), rpm (real package + **automatic repodata** generation).
+- **Virtual repositories** — pypi simple-index merge and helm `index.yaml` merge
+  across two members.
+- **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_test.go

@@ -0,0 +1,76 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"bytes"
+	"fmt"
+	"net/http"
+	"testing"
+)
+
+// 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) {
+	cases := []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
+	}{
+		{"generic", "blobs/hello.bin", "blobs/hello.bin"},
+		{"npm", "mypkg/-/mypkg-1.0.0.tgz", "mypkg/-/mypkg-1.0.0.tgz"},
+		{"helm", "charts/mychart-1.0.0.tgz", "charts/mychart-1.0.0.tgz"},
+		{"pypi", "packages/foo-1.0-py3-none-any.whl", "packages/foo-1.0-py3-none-any.whl"},
+		{"rpm", "rpmrepo/Packages/e2e-testpkg-1.0-1.noarch.rpm", "rpmrepo/Packages/e2e-testpkg-1.0-1.noarch.rpm"},
+		{"alpine", "alpine/x86_64/testpkg-1.0-r0.apk", "alpine/x86_64/testpkg-1.0-r0.apk"},
+		{"puppet", "puppet-releases/author-mod-1.0.0.tar.gz", "puppet-releases/author-mod-1.0.0.tar.gz"},
+		{"goproxy", "goproxy/example.com/mod/@v/v1.0.0.zip", "goproxy/example.com/mod/@v/v1.0.0.zip"},
+		{"terraform", "hashicorp/aws/download/pkg.zip", "v1/providers/hashicorp/aws/download/pkg.zip"},
+		{"docker", "library/testimg/blobs/blobdata", "v2/library/testimg/blobs/blobdata"},
+	}
+
+	for _, tc := range cases {
+		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/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/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/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,54 @@
+//go:build dockere2e
+
+package e2edocker
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+)
+
+// 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)
+	}
+}

e2e/e2e_test.go

@@ -0,0 +1,137 @@
+//go:build e2e
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/testcontainers/testcontainers-go"
+	tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
+	tcredis "github.com/testcontainers/testcontainers-go/modules/redis"
+	"github.com/testcontainers/testcontainers-go/wait"
+
+	"git.unkin.net/unkin/artifactapi/internal/config"
+	"git.unkin.net/unkin/artifactapi/internal/server"
+)
+
+var baseURL string
+
+func TestMain(m *testing.M) {
+	ctx := context.Background()
+
+	pgContainer, err := tcpostgres.Run(ctx,
+		"postgres:17-alpine",
+		tcpostgres.WithDatabase("artifacts"),
+		tcpostgres.WithUsername("artifacts"),
+		tcpostgres.WithPassword("artifacts123"),
+		testcontainers.WithWaitStrategy(
+			wait.ForListeningPort("5432/tcp").WithStartupTimeout(30*time.Second),
+		),
+	)
+	if err != nil {
+		log.Fatalf("postgres: %v", err)
+	}
+	defer pgContainer.Terminate(ctx)
+
+	redisContainer, err := tcredis.Run(ctx,
+		"redis:7-alpine",
+		testcontainers.WithWaitStrategy(
+			wait.ForListeningPort("6379/tcp").WithStartupTimeout(30*time.Second),
+		),
+	)
+	if err != nil {
+		log.Fatalf("redis: %v", err)
+	}
+	defer redisContainer.Terminate(ctx)
+
+	minioContainer, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+		ContainerRequest: testcontainers.ContainerRequest{
+			Image:        "minio/minio:latest",
+			ExposedPorts: []string{"9000/tcp"},
+			Cmd:          []string{"server", "/data"},
+			Env: map[string]string{
+				"MINIO_ROOT_USER":     "minioadmin",
+				"MINIO_ROOT_PASSWORD": "minioadmin",
+			},
+			WaitingFor: wait.ForHTTP("/minio/health/live").WithPort("9000/tcp").WithStartupTimeout(30 * time.Second),
+		},
+		Started: true,
+	})
+	if err != nil {
+		log.Fatalf("minio: %v", err)
+	}
+	defer minioContainer.Terminate(ctx)
+
+	pgHost, _ := pgContainer.Host(ctx)
+	pgPort, _ := pgContainer.MappedPort(ctx, "5432/tcp")
+	redisHost, _ := redisContainer.Host(ctx)
+	redisPort, _ := redisContainer.MappedPort(ctx, "6379/tcp")
+	minioHost, _ := minioContainer.Host(ctx)
+	minioPort, _ := minioContainer.MappedPort(ctx, "9000/tcp")
+
+	os.Setenv("DBHOST", pgHost)
+	os.Setenv("DBPORT", pgPort.Port())
+	os.Setenv("DBUSER", "artifacts")
+	os.Setenv("DBPASS", "artifacts123")
+	os.Setenv("DBNAME", "artifacts")
+	os.Setenv("DBSSL", "disable")
+	os.Setenv("REDIS_URL", fmt.Sprintf("redis://%s:%s", redisHost, redisPort.Port()))
+	os.Setenv("MINIO_ENDPOINT", fmt.Sprintf("%s:%s", minioHost, minioPort.Port()))
+	os.Setenv("MINIO_ACCESS_KEY", "minioadmin")
+	os.Setenv("MINIO_SECRET_KEY", "minioadmin")
+	os.Setenv("MINIO_BUCKET", "artifacts-test")
+	os.Setenv("MINIO_SECURE", "false")
+	os.Setenv("LISTEN_ADDR", ":0")
+
+	cfg, err := config.Load()
+	if err != nil {
+		log.Fatalf("config: %v", err)
+	}
+	cfg.ListenAddr = "127.0.0.1:0"
+
+	srv, err := server.New(cfg, "e2e-test")
+	if err != nil {
+		log.Fatalf("server: %v", err)
+	}
+
+	srvCtx, cancel := context.WithCancel(ctx)
+	defer cancel()
+
+	addr := startServer(srvCtx, srv)
+	baseURL = "http://" + addr
+
+	code := m.Run()
+	cancel()
+	os.Exit(code)
+}
+
+func startServer(ctx context.Context, srv *server.Server) string {
+	ln, err := findListener()
+	if err != nil {
+		log.Fatalf("listener: %v", err)
+	}
+	addr := ln.Addr().String()
+
+	go srv.RunOnListener(ctx, ln)
+
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		resp, err := http.Get("http://" + addr + "/health")
+		if err == nil && resp.StatusCode == 200 {
+			resp.Body.Close()
+			return addr
+		}
+		if resp != nil {
+			resp.Body.Close()
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	log.Fatalf("server did not start in time at %s", addr)
+	return ""
+}

e2e/helpers_test.go

@@ -0,0 +1,109 @@
+//go:build e2e
+
+package e2e
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func findListener() (net.Listener, error) {
+	return net.Listen("tcp", "127.0.0.1:0")
+}
+
+func apiURL(path string) string {
+	return baseURL + path
+}
+
+func createRemote(t *testing.T, body string) {
+	t.Helper()
+	resp, err := http.Post(apiURL("/api/v2/remotes"), "application/json", strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("create remote: %v", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusCreated {
+		b, _ := io.ReadAll(resp.Body)
+		t.Fatalf("create remote: status %d: %s", resp.StatusCode, b)
+	}
+}
+
+func deleteRemote(t *testing.T, name string) {
+	t.Helper()
+	req, _ := http.NewRequest(http.MethodDelete, apiURL("/api/v2/remotes/"+name), nil)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("delete remote: %v", err)
+	}
+	resp.Body.Close()
+}
+
+func getJSON(t *testing.T, url string) map[string]any {
+	t.Helper()
+	resp, err := http.Get(url)
+	if err != nil {
+		t.Fatalf("GET %s: %v", url, err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		b, _ := io.ReadAll(resp.Body)
+		t.Fatalf("GET %s: status %d: %s", url, resp.StatusCode, b)
+	}
+	var result map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	return result
+}
+
+func getBody(t *testing.T, url string) ([]byte, int) {
+	t.Helper()
+	resp, err := http.Get(url)
+	if err != nil {
+		t.Fatalf("GET %s: %v", url, err)
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return b, resp.StatusCode
+}
+
+func getString(t *testing.T, url string) string {
+	t.Helper()
+	b, status := getBody(t, url)
+	if status != http.StatusOK {
+		t.Fatalf("GET %s: status %d: %s", url, status, b)
+	}
+	return string(b)
+}
+
+func assertStatus(t *testing.T, url string, wantStatus int) {
+	t.Helper()
+	resp, err := http.Get(url)
+	if err != nil {
+		t.Fatalf("GET %s: %v", url, err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != wantStatus {
+		t.Errorf("GET %s: got %d, want %d", url, resp.StatusCode, wantStatus)
+	}
+}
+
+func deleteRequest(t *testing.T, url string) int {
+	t.Helper()
+	req, _ := http.NewRequest(http.MethodDelete, url, nil)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("DELETE %s: %v", url, err)
+	}
+	resp.Body.Close()
+	return resp.StatusCode
+}
+
+func mustFormat(format string, args ...any) string {
+	return fmt.Sprintf(format, args...)
+}

e2e/management_test.go

@@ -0,0 +1,183 @@
+//go:build e2e
+
+package e2e
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestHealth(t *testing.T) {
+	result := getJSON(t, apiURL("/health"))
+	if result["status"] != "ok" {
+		t.Errorf("expected ok, got %v", result["status"])
+	}
+}
+
+func TestRoot(t *testing.T) {
+	result := getJSON(t, apiURL("/"))
+	if result["name"] != "artifactapi" {
+		t.Errorf("expected artifactapi, got %v", result["name"])
+	}
+}
+
+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",
+		"package_type": "generic",
+		"base_url": "https://example.com",
+		"description": "test remote",
+		"mutable_ttl": 600,
+		"check_mutable": true,
+		"stale_on_error": true
+	}`)
+	defer deleteRemote(t, "test-generic")
+
+	remote := getJSON(t, apiURL("/api/v2/remotes/test-generic"))
+	if remote["name"] != "test-generic" {
+		t.Errorf("expected test-generic, got %v", remote["name"])
+	}
+	if remote["package_type"] != "generic" {
+		t.Errorf("expected generic, got %v", remote["package_type"])
+	}
+
+	req, _ := http.NewRequest(http.MethodPut, apiURL("/api/v2/remotes/test-generic"),
+		strings.NewReader(`{
+			"package_type": "generic",
+			"base_url": "https://updated.example.com",
+			"description": "updated",
+			"mutable_ttl": 300,
+			"check_mutable": true,
+			"stale_on_error": true
+		}`))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("update: status %d", resp.StatusCode)
+	}
+
+	updated := getJSON(t, apiURL("/api/v2/remotes/test-generic"))
+	if updated["base_url"] != "https://updated.example.com" {
+		t.Errorf("expected updated URL, got %v", updated["base_url"])
+	}
+
+	status := deleteRequest(t, apiURL("/api/v2/remotes/test-generic"))
+	if status != http.StatusNoContent {
+		t.Errorf("delete: got %d, want 204", status)
+	}
+
+	assertStatus(t, apiURL("/api/v2/remotes/test-generic"), http.StatusNotFound)
+}
+
+func TestRemoteList(t *testing.T) {
+	createRemote(t, `{"name":"list-a","package_type":"generic","base_url":"https://a.example.com","stale_on_error":true}`)
+	createRemote(t, `{"name":"list-b","package_type":"helm","base_url":"https://b.example.com","stale_on_error":true}`)
+	defer deleteRemote(t, "list-a")
+	defer deleteRemote(t, "list-b")
+
+	resp, err := http.Get(apiURL("/api/v2/remotes"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(resp.Body)
+
+	var remotes []map[string]any
+	json.Unmarshal(body, &remotes)
+
+	if len(remotes) < 2 {
+		t.Fatalf("expected at least 2 remotes, got %d", len(remotes))
+	}
+}
+
+func TestVirtualCRUD(t *testing.T) {
+	createRemote(t, `{"name":"virt-member-a","package_type":"helm","base_url":"https://a.example.com","stale_on_error":true}`)
+	createRemote(t, `{"name":"virt-member-b","package_type":"helm","base_url":"https://b.example.com","stale_on_error":true}`)
+	defer deleteRemote(t, "virt-member-a")
+	defer deleteRemote(t, "virt-member-b")
+
+	resp, err := http.Post(apiURL("/api/v2/virtuals"), "application/json",
+		strings.NewReader(`{
+			"name": "test-virtual",
+			"package_type": "helm",
+			"description": "test virtual",
+			"members": ["virt-member-a", "virt-member-b"]
+		}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("create virtual: status %d", resp.StatusCode)
+	}
+
+	virt := getJSON(t, apiURL("/api/v2/virtuals/test-virtual"))
+	if virt["name"] != "test-virtual" {
+		t.Errorf("expected test-virtual, got %v", virt["name"])
+	}
+
+	status := deleteRequest(t, apiURL("/api/v2/virtuals/test-virtual"))
+	if status != http.StatusNoContent {
+		t.Errorf("delete virtual: got %d, want 204", status)
+	}
+}
+
+func TestStatsEndpoint(t *testing.T) {
+	result := getJSON(t, apiURL("/api/v2/stats"))
+	if _, ok := result["total_remotes"]; !ok {
+		t.Error("expected total_remotes in stats")
+	}
+}
+
+func TestHealthV2(t *testing.T) {
+	result := getJSON(t, apiURL("/api/v2/health"))
+	if result["status"] != "ok" {
+		t.Errorf("expected ok, got %v", result["status"])
+	}
+	if result["postgres"] != "ok" {
+		t.Errorf("expected postgres ok, got %v", result["postgres"])
+	}
+}
+
+func TestInvalidPackageType(t *testing.T) {
+	resp, err := http.Post(apiURL("/api/v2/remotes"), "application/json",
+		strings.NewReader(`{"name":"bad","package_type":"bogus","base_url":"https://x.com"}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Errorf("expected 400 for invalid package type, got %d", resp.StatusCode)
+	}
+}

e2e/proxy_test.go

@@ -0,0 +1,71 @@
+//go:build e2e
+
+package e2e
+
+import (
+	"net/http"
+	"testing"
+)
+
+func TestProxyUnknownRemote(t *testing.T) {
+	assertStatus(t, apiURL("/api/v1/remote/nonexistent/some/path"), http.StatusNotFound)
+}
+
+func TestProxyBlocklist(t *testing.T) {
+	createRemote(t, `{
+		"name": "blocklist-test",
+		"package_type": "generic",
+		"base_url": "https://example.com",
+		"blocklist": ["\\.exe$"],
+		"stale_on_error": true
+	}`)
+	defer deleteRemote(t, "blocklist-test")
+
+	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",
+		"package_type": "generic",
+		"base_url": "https://example.com",
+		"patterns": ["^releases/"],
+		"stale_on_error": true
+	}`)
+	defer deleteRemote(t, "patterns-test")
+
+	assertStatus(t, apiURL("/api/v1/remote/patterns-test/uploads/file.tar.gz"), http.StatusForbidden)
+}

go.mod

@@ -0,0 +1,108 @@
+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/go-chi/chi/v5 v5.3.0
+	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.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/time v0.15.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/charmbracelet/colorprofile v0.4.3 // indirect
+	github.com/charmbracelet/x/ansi v0.11.7 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
+	github.com/charmbracelet/x/term v0.2.2 // indirect
+	github.com/clipperhouse/displaywidth v0.11.0 // indirect
+	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
+	github.com/containerd/errdefs v1.0.0 // indirect
+	github.com/containerd/errdefs/pkg v0.3.0 // indirect
+	github.com/containerd/log v0.1.0 // indirect
+	github.com/containerd/platforms v0.2.1 // indirect
+	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.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.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // 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.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/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-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
+	github.com/mattn/go-runewidth v0.0.23 // indirect
+	github.com/mdelapenya/tlscert v0.2.0 // indirect
+	github.com/minio/crc64nvme v1.1.1 // indirect
+	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.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.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
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/opencontainers/image-spec v1.1.1 // indirect
+	github.com/philhofer/fwd v1.2.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	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.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.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.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/net v0.56.0 // indirect
+	golang.org/x/sync v0.22.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

@@ -0,0 +1,255 @@
+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=
+github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
+github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cavaliergopher/rpm v1.3.0 h1:UHX46sasX8MesUXXQ+UbkFLUX4eUWTlEcX8jcnRBIgI=
+github.com/cavaliergopher/rpm v1.3.0/go.mod h1:vEumo1vvtrHM1Ov86f6+k8j7zNKOxQfHDCAIcR/36ZI=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
+github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
+github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
+github.com/charmbracelet/colorprofile v0.4.3/go.mod h1:/zT4BhpD5aGFpqQQqw7a+VtHCzu+zrQtt1zhMt9mR4Q=
+github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
+github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
+github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
+github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
+github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
+github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
+github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
+github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
+github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSEFgwIwO+UVM8=
+github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
+github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
+github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
+github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
+github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
+github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
+github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
+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/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=
+github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/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.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.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.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-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/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
+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=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+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.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=
+github.com/klauspost/crc32 v1.3.0 h1:sSmTt3gUt81RP655XGZPElI0PelVTZ6YwCRnPSupoFM=
+github.com/klauspost/crc32 v1.3.0/go.mod h1:D7kQaZhnkX/Y0tstFGf8VUzv2UofNGqCjnC3zdHB0Hw=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+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-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=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
+github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
+github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
+github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI=
+github.com/mdelapenya/tlscert v0.2.0/go.mod h1:O4njj3ELLnJjGdkN7M/vIVCpZ+Cf0L6muqOG4tLSl8o=
+github.com/minio/crc64nvme v1.1.1 h1:8dwx/Pz49suywbO+auHCBpCtlW1OfpcLN7wYgVR6wAI=
+github.com/minio/crc64nvme v1.1.1/go.mod h1:eVfm2fAzLlxMdUGc0EEBGSMmPwmXD5XiNRpnu9J3bvg=
+github.com/minio/md5-simd v1.1.2 h1:Gdi1DZK69+ZVMoNHRXJyNcxrMA4dSxoYHZSQbirFg34=
+github.com/minio/md5-simd v1.1.2/go.mod h1:MzdKDxYpY2BT9XQFocsiZf/NKVtR7nkE4RoEpN+20RM=
+github.com/minio/minio-go/v7 v7.2.0 h1:RCJM0R1XOsRs+A3x3UCaf3ZYbByDaLjFeAi+YCQEPhs=
+github.com/minio/minio-go/v7 v7.2.0/go.mod h1:EU9hENAStx/xXduNdrGO5e4X5vk19NtgB+RIPjZO8o0=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+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.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.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=
+github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
+github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ=
+github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
+github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
+github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
+github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
+github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
+github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
+github.com/philhofer/fwd v1.2.0 h1:e6DnBTl7vGY+Gz322/ASL4Gyp1FspeMvx1RNDoToZuM=
+github.com/philhofer/fwd v1.2.0/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
+github.com/redis/go-redis/v9 v9.20.0 h1:WnQYxLkgO2xiXTCJY0ldIiI8dNqCDlQAG+AtaH7a2a0=
+github.com/redis/go-redis/v9 v9.20.0/go.mod h1:v/M13XI1PVCDcm01VtPFOADfZtHf8YW3baQf57KlIkA=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/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.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=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
+github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+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.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.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=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
+github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
+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.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.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.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+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.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=
+gopkg.in/ini.v1 v1.67.2 h1:JtOSMb9OuaCZKr7h5D/h6iii14sK0hLbplTc6frx4Ss=
+gopkg.in/ini.v1 v1.67.2/go.mod h1:x/cyOwCgZqOkJoDIJ3c1KNHMo10+nLGAhh+kn3Zizss=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
+gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
+pgregory.net/rapid v1.2.0 h1:keKAYRcjm+e1F0oAuU5F5+YPAWcyxNNRK2wud503Gnk=
+pgregory.net/rapid v1.2.0/go.mod h1:PY5XlDGj0+V1FCq0o192FdRhpKHGTRIWBgqjDBTrq04=

internal/api/terraform/registry.go

@@ -0,0 +1,301 @@
+// 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"
+
+	"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 {
+	scheme := "http"
+	if r.TLS != nil {
+		scheme = "https"
+	}
+	if fwd := r.Header.Get("X-Forwarded-Proto"); fwd != "" {
+		scheme = fwd
+	}
+	return scheme + "://" + 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/proxy.go

@@ -0,0 +1,234 @@
+package v1
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	v2 "git.unkin.net/unkin/artifactapi/internal/api/v2"
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/proxy"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+	"git.unkin.net/unkin/artifactapi/internal/virtual"
+)
+
+type ProxyHandler struct {
+	engine        *proxy.Engine
+	virtualEngine *virtual.Engine
+	db            *database.DB
+	store         *storage.S3
+	local         *v2.LocalHandler
+	cas           *storage.CAS
+}
+
+func NewProxyHandler(engine *proxy.Engine, virtualEngine *virtual.Engine, db *database.DB, store *storage.S3, local *v2.LocalHandler) *ProxyHandler {
+	return &ProxyHandler{
+		engine:        engine,
+		virtualEngine: virtualEngine,
+		db:            db,
+		store:         store,
+		local:         local,
+		cas:           storage.NewCAS(store),
+	}
+}
+
+func (h *ProxyHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/remote/{remoteName}/*", h.handleProxy)
+	r.Get("/local/{localName}/*", h.handleLocal)
+	r.Get("/virtual/{virtualName}/*", h.handleVirtual)
+	return r
+}
+
+// DockerV2Routes mounts the Docker Registry HTTP API V2. Reads (GET/HEAD)
+// dispatch to a local registry implementation for local docker repos and fall
+// through to the upstream proxy otherwise; writes (POST/PATCH/PUT/DELETE) are
+// only valid for local docker repos and drive push.
+func (h *ProxyHandler) DockerV2Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.handleDockerPing)
+	r.Head("/", h.handleDockerPing)
+	r.Get("/{remoteName}/*", h.dockerGet)
+	r.Head("/{remoteName}/*", h.dockerHead)
+	r.Post("/{remoteName}/*", h.dockerPost)
+	r.Patch("/{remoteName}/*", h.dockerPatch)
+	r.Put("/{remoteName}/*", h.dockerPut)
+	r.Delete("/{remoteName}/*", h.dockerDelete)
+	return r
+}
+
+func (h *ProxyHandler) handleDockerPing(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Docker-Distribution-Api-Version", "registry/2.0")
+	w.WriteHeader(http.StatusOK)
+}
+
+func (h *ProxyHandler) handleProxy(w http.ResponseWriter, r *http.Request) {
+	remoteName := chi.URLParam(r, "remoteName")
+	path := chi.URLParam(r, "*")
+
+	remote, err := h.db.GetRemote(r.Context(), remoteName)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("remote %q not found", remoteName), http.StatusNotFound)
+		return
+	}
+
+	prov, err := provider.Get(remote.PackageType)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("no provider for %q", remote.PackageType), http.StatusInternalServerError)
+		return
+	}
+
+	// Metadata-only remotes (e.g. github_rpm) synthesize their own responses and
+	// redirect package downloads to a backend remote instead of proxying bytes.
+	if rs, ok := prov.(provider.RemoteServer); ok {
+		proxyBaseURL := fmt.Sprintf("%s://%s", scheme(r), r.Host)
+		if rs.ServeRemote(w, r, *remote, path, proxyBaseURL, h.db) {
+			return
+		}
+	}
+
+	result, err := h.engine.Fetch(r.Context(), *remote, path, prov, r.Header)
+	if err != nil {
+		var proxyErr *proxy.ProxyError
+		if errors.As(err, &proxyErr) {
+			http.Error(w, proxyErr.Message, proxyErr.Status)
+			return
+		}
+		slog.Error("proxy fetch failed", "remote", remoteName, "path", path, "error", err)
+		http.Error(w, "bad gateway", http.StatusBadGateway)
+		return
+	}
+	defer result.Reader.Close()
+
+	w.Header().Set("Content-Type", result.ContentType)
+	w.Header().Set("X-Artifact-Source", result.Source)
+	if result.Size > 0 {
+		w.Header().Set("X-Artifact-Size", fmt.Sprintf("%d", result.Size))
+	}
+	w.WriteHeader(http.StatusOK)
+	io.Copy(w, result.Reader)
+}
+
+func (h *ProxyHandler) handleProxyHead(w http.ResponseWriter, r *http.Request) {
+	remoteName := chi.URLParam(r, "remoteName")
+	path := chi.URLParam(r, "*")
+
+	remote, err := h.db.GetRemote(r.Context(), remoteName)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("remote %q not found", remoteName), http.StatusNotFound)
+		return
+	}
+
+	prov, err := provider.Get(remote.PackageType)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("no provider for %q", remote.PackageType), http.StatusInternalServerError)
+		return
+	}
+
+	result, err := h.engine.Head(r.Context(), *remote, path, prov)
+	if err != nil {
+		var proxyErr *proxy.ProxyError
+		if errors.As(err, &proxyErr) {
+			http.Error(w, proxyErr.Message, proxyErr.Status)
+			return
+		}
+		slog.Error("proxy head failed", "remote", remoteName, "path", path, "error", err)
+		http.Error(w, "bad gateway", http.StatusBadGateway)
+		return
+	}
+
+	w.Header().Set("Content-Type", result.ContentType)
+	w.Header().Set("X-Artifact-Source", result.Source)
+	if result.Size > 0 {
+		w.Header().Set("Content-Length", fmt.Sprintf("%d", result.Size))
+	}
+	w.WriteHeader(http.StatusOK)
+}
+
+func (h *ProxyHandler) handleVirtual(w http.ResponseWriter, r *http.Request) {
+	virtualName := chi.URLParam(r, "virtualName")
+	path := chi.URLParam(r, "*")
+
+	virt, err := h.db.GetVirtual(r.Context(), virtualName)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("virtual %q not found", virtualName), http.StatusNotFound)
+		return
+	}
+
+	proxyBaseURL := fmt.Sprintf("%s://%s", scheme(r), r.Host)
+
+	body, contentType, err := h.virtualEngine.Fetch(r.Context(), *virt, path, proxyBaseURL)
+	if err != nil {
+		slog.Error("virtual fetch failed", "virtual", virtualName, "path", path, "error", err)
+		http.Error(w, "bad gateway", http.StatusBadGateway)
+		return
+	}
+
+	w.Header().Set("Content-Type", contentType)
+	w.Header().Set("X-Artifact-Source", "virtual")
+	w.WriteHeader(http.StatusOK)
+	w.Write(body)
+}
+
+func (h *ProxyHandler) handleLocal(w http.ResponseWriter, r *http.Request) {
+	localName := chi.URLParam(r, "localName")
+	path := chi.URLParam(r, "*")
+
+	remote, err := h.db.GetRemote(r.Context(), localName)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("local %q not found", localName), http.StatusNotFound)
+		return
+	}
+
+	prov, _ := provider.Get(remote.PackageType)
+	if indexer, ok := prov.(provider.LocalIndexer); ok {
+		if indexer.ServeLocalIndex(w, r, h.db, remote.Name, path) {
+			return
+		}
+	}
+
+	h.serveLocalFile(w, r, localName, path)
+}
+
+func (h *ProxyHandler) serveLocalFile(w http.ResponseWriter, r *http.Request, repoName, path string) {
+	file, err := h.db.GetLocalFile(r.Context(), repoName, path)
+	if err != nil {
+		slog.Error("local file lookup failed", "repo", repoName, "path", path, "error", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	if file == nil {
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
+	s3Key := storage.BlobKey(file.ContentHash[len("sha256:"):])
+	reader, info, err := h.store.Download(r.Context(), s3Key)
+	if err != nil {
+		slog.Error("local file download failed", "repo", repoName, "path", path, "error", err)
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	defer reader.Close()
+
+	w.Header().Set("Content-Type", info.ContentType)
+	w.Header().Set("Content-Length", fmt.Sprintf("%d", info.Size))
+	w.Header().Set("X-Artifact-Source", "local")
+	w.WriteHeader(http.StatusOK)
+	io.Copy(w, reader)
+}
+
+func scheme(r *http.Request) string {
+	if r.TLS != nil {
+		return "https"
+	}
+	if fwd := r.Header.Get("X-Forwarded-Proto"); fwd != "" {
+		return fwd
+	}
+	return "http"
+}

internal/api/v1/scheme_test.go

@@ -0,0 +1,20 @@
+package v1
+
+import (
+	"crypto/tls"
+	"net/http"
+	"testing"
+)
+
+func TestScheme(t *testing.T) {
+	if got := scheme(&http.Request{TLS: &tls.ConnectionState{}}); got != "https" {
+		t.Errorf("TLS request scheme = %q, want https", got)
+	}
+	r := &http.Request{Header: http.Header{"X-Forwarded-Proto": {"https"}}}
+	if got := scheme(r); got != "https" {
+		t.Errorf("X-Forwarded-Proto scheme = %q, want https", got)
+	}
+	if got := scheme(&http.Request{Header: http.Header{}}); got != "http" {
+		t.Errorf("default scheme = %q, want http", got)
+	}
+}

internal/api/v2/errorpaths_test.go

@@ -0,0 +1,130 @@
+package v2
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+)
+
+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()
+	if code != 0 {
+		os.Exit(code)
+	}
+}
+
+// closedDB returns a DB whose pool has been closed, so every query fails —
+// used to drive the handlers' error branches.
+func closedDB(t *testing.T) *database.DB {
+	t.Helper()
+	if testDSN == "" {
+		t.Skip("Docker unavailable")
+	}
+	db, err := database.New(testDSN)
+	if err != nil {
+		t.Fatalf("new db: %v", err)
+	}
+	db.Close()
+	return db
+}
+
+func do(t *testing.T, h http.Handler, method, path, body string) int {
+	t.Helper()
+	var r io.Reader
+	if body != "" {
+		r = strings.NewReader(body)
+	}
+	req := httptest.NewRequest(method, path, r)
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, req)
+	return w.Code
+}
+
+func TestRemotesErrorPaths(t *testing.T) {
+	h := NewRemotesHandler(closedDB(t), nil, nil).Routes()
+	if c := do(t, h, "GET", "/", ""); c != 500 {
+		t.Errorf("list with dead db = %d, want 500", c)
+	}
+	if c := do(t, h, "POST", "/", `{"name":"x","package_type":"generic","repo_type":"remote","base_url":"https://x"}`); c != 500 {
+		t.Errorf("create with dead db = %d, want 500", c)
+	}
+	if c := do(t, h, "PUT", "/x", `{"package_type":"generic","base_url":"https://x"}`); c != 500 {
+		t.Errorf("update with dead db = %d, want 500", c)
+	}
+	if c := do(t, h, "GET", "/x", ""); c != 404 {
+		t.Errorf("get missing = %d, want 404", c)
+	}
+	if c := do(t, h, "DELETE", "/x", ""); c != 500 {
+		t.Errorf("delete with dead db = %d, want 500", c)
+	}
+	// Bad request bodies never reach the db.
+	if c := do(t, h, "POST", "/", `not json`); c != 400 {
+		t.Errorf("invalid json = %d, want 400", c)
+	}
+}
+
+func TestVirtualsErrorPaths(t *testing.T) {
+	h := NewVirtualsHandler(closedDB(t)).Routes()
+	if c := do(t, h, "GET", "/", ""); c != 500 {
+		t.Errorf("list = %d, want 500", c)
+	}
+	if c := do(t, h, "GET", "/x", ""); c != 404 {
+		t.Errorf("get missing = %d, want 404", c)
+	}
+	if c := do(t, h, "POST", "/", `{"name":"v","package_type":"helm","members":["a"]}`); c != 500 {
+		t.Errorf("create = %d, want 500", c)
+	}
+	if c := do(t, h, "PUT", "/v", `{"package_type":"helm","members":["a"]}`); c != 500 {
+		t.Errorf("update = %d, want 500", c)
+	}
+	if c := do(t, h, "DELETE", "/v", ""); c != 500 {
+		t.Errorf("delete = %d, want 500", c)
+	}
+}
+
+func TestStatsErrorPaths(t *testing.T) {
+	h := NewStatsHandler(closedDB(t)).Routes()
+	for _, p := range []string{"/", "/top-remotes", "/top-files-by-hits", "/top-files-by-bandwidth"} {
+		if c := do(t, h, "GET", p, ""); c != 500 {
+			t.Errorf("stats %s = %d, want 500", p, c)
+		}
+	}
+}
+
+func TestLocalErrorPaths(t *testing.T) {
+	h := NewLocalHandler(closedDB(t), nil).Routes()
+	// GetRemote fails on the closed db -> not found.
+	if c := do(t, h, "PUT", "/x/files/a.bin", "data"); c != 404 {
+		t.Errorf("upload unknown repo = %d, want 404", c)
+	}
+	// download / remove hit the db and 500.
+	if c := do(t, h, "GET", "/x/files/a.bin", ""); c != 500 {
+		t.Errorf("download = %d, want 500", c)
+	}
+	if c := do(t, h, "DELETE", "/x/files/a.bin", ""); c != 500 {
+		t.Errorf("remove = %d, want 500", c)
+	}
+}
+
+func TestLocalHandlerDBAccessor(t *testing.T) {
+	db := closedDB(t)
+	if NewLocalHandler(db, nil).DB() != db {
+		t.Error("DB() should return the handler's database")
+	}
+}

internal/api/v2/events.go

@@ -0,0 +1,49 @@
+package v2
+
+import (
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type EventsHandler struct{}
+
+func NewEventsHandler() *EventsHandler {
+	return &EventsHandler{}
+}
+
+func (h *EventsHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.stream)
+	return r
+}
+
+func (h *EventsHandler) stream(w http.ResponseWriter, r *http.Request) {
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "streaming not supported", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("X-Accel-Buffering", "no")
+	w.WriteHeader(http.StatusOK)
+	flusher.Flush()
+
+	ticker := time.NewTicker(30 * time.Second)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-r.Context().Done():
+			return
+		case <-ticker.C:
+			fmt.Fprintf(w, ": keepalive\n\n")
+			flusher.Flush()
+		}
+	}
+}

internal/api/v2/health.go

@@ -0,0 +1,43 @@
+package v2
+
+import (
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/cache"
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+)
+
+type HealthHandler struct {
+	db    *database.DB
+	cache *cache.Redis
+	store *storage.S3
+}
+
+func NewHealthHandler(db *database.DB, c *cache.Redis, s *storage.S3) *HealthHandler {
+	return &HealthHandler{db: db, cache: c, store: s}
+}
+
+func (h *HealthHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.health)
+	return r
+}
+
+func (h *HealthHandler) health(w http.ResponseWriter, r *http.Request) {
+	status := map[string]string{
+		"status":   "ok",
+		"postgres": "ok",
+		"redis":    "ok",
+		"s3":       "ok",
+	}
+
+	if err := h.db.Pool.Ping(r.Context()); err != nil {
+		status["postgres"] = "error"
+		status["status"] = "degraded"
+	}
+
+	writeJSON(w, http.StatusOK, status)
+}

internal/api/v2/local.go

@@ -0,0 +1,227 @@
+package v2
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+type LocalHandler struct {
+	db    *database.DB
+	store *storage.S3
+	cas   *storage.CAS
+}
+
+func NewLocalHandler(db *database.DB, store *storage.S3) *LocalHandler {
+	return &LocalHandler{
+		db:    db,
+		store: store,
+		cas:   storage.NewCAS(store),
+	}
+}
+
+func (h *LocalHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Put("/*", h.upload)
+	r.Get("/*", h.download)
+	r.Delete("/*", h.remove)
+	return r
+}
+
+func (h *LocalHandler) upload(w http.ResponseWriter, r *http.Request) {
+	repoName := chi.URLParam(r, "name")
+	filePath := chi.URLParam(r, "*")
+
+	if filePath == "" {
+		http.Error(w, "file path required", http.StatusBadRequest)
+		return
+	}
+
+	remote, err := h.db.GetRemote(r.Context(), repoName)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("remote %q not found", repoName), http.StatusNotFound)
+		return
+	}
+	if remote.RepoType != models.RepoTypeLocal {
+		http.Error(w, "upload only allowed for local repository types", http.StatusBadRequest)
+		return
+	}
+
+	prov, _ := provider.Get(remote.PackageType)
+
+	if uploader, ok := prov.(provider.LocalUploader); ok {
+		h.uploadValidated(w, r, remote, filePath, prov, uploader)
+		return
+	}
+
+	h.uploadGeneric(w, r, remote, filePath)
+}
+
+func (h *LocalHandler) uploadValidated(w http.ResponseWriter, r *http.Request, remote *models.Remote, filePath string, prov provider.Provider, uploader provider.LocalUploader) {
+	storagePath, contentType, err := uploader.ValidateUpload(filePath)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	existing, err := h.db.GetLocalFile(r.Context(), remote.Name, storagePath)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	if existing != nil {
+		http.Error(w, fmt.Sprintf("file %q already exists; overwrites are not allowed", storagePath), http.StatusConflict)
+		return
+	}
+
+	result, err := h.cas.Store(r.Context(), r.Body, contentType)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("store failed: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if err := h.db.UpsertBlob(r.Context(), result.ContentHash, result.S3Key, result.SizeBytes, contentType); err != nil {
+		http.Error(w, fmt.Sprintf("record blob: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if err := h.db.CreateLocalFile(r.Context(), remote.Name, storagePath, result.ContentHash); err != nil {
+		if errors.Is(err, database.ErrAlreadyExists) {
+			http.Error(w, fmt.Sprintf("file %q already exists; overwrites are not allowed", storagePath), http.StatusConflict)
+			return
+		}
+		http.Error(w, fmt.Sprintf("record file: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if hook, ok := prov.(provider.PostUploadHook); ok {
+		go hook.AfterUpload(context.Background(), remote.Name, storagePath, result.ContentHash, h, h.db)
+	}
+
+	writeJSON(w, http.StatusCreated, uploader.UploadResponse(storagePath, result.ContentHash, result.SizeBytes))
+}
+
+func (h *LocalHandler) uploadGeneric(w http.ResponseWriter, r *http.Request, remote *models.Remote, filePath string) {
+	existing, err := h.db.GetLocalFile(r.Context(), remote.Name, filePath)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	if existing != nil {
+		http.Error(w, fmt.Sprintf("file %q already exists; overwrites are not allowed", filePath), http.StatusConflict)
+		return
+	}
+
+	contentType := "application/octet-stream"
+	if ct := r.Header.Get("Content-Type"); ct != "" && ct != "application/octet-stream" {
+		contentType = ct
+	}
+
+	result, err := h.cas.Store(r.Context(), r.Body, contentType)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("store failed: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if err := h.db.UpsertBlob(r.Context(), result.ContentHash, result.S3Key, result.SizeBytes, contentType); err != nil {
+		http.Error(w, fmt.Sprintf("record blob: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if err := h.db.CreateLocalFile(r.Context(), remote.Name, filePath, result.ContentHash); err != nil {
+		if errors.Is(err, database.ErrAlreadyExists) {
+			http.Error(w, fmt.Sprintf("file %q already exists; overwrites are not allowed", filePath), http.StatusConflict)
+			return
+		}
+		http.Error(w, fmt.Sprintf("record file: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	writeJSON(w, http.StatusCreated, map[string]any{
+		"path":         filePath,
+		"content_hash": result.ContentHash,
+		"size_bytes":   result.SizeBytes,
+	})
+}
+
+func (h *LocalHandler) download(w http.ResponseWriter, r *http.Request) {
+	repoName := chi.URLParam(r, "name")
+	filePath := chi.URLParam(r, "*")
+
+	file, err := h.db.GetLocalFile(r.Context(), repoName, filePath)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	if file == nil {
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
+	s3Key := storage.BlobKey(file.ContentHash[len("sha256:"):])
+	reader, info, err := h.store.Download(r.Context(), s3Key)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("download failed: %v", err), http.StatusInternalServerError)
+		return
+	}
+	defer reader.Close()
+
+	w.Header().Set("Content-Type", info.ContentType)
+	w.Header().Set("Content-Length", fmt.Sprintf("%d", info.Size))
+	w.WriteHeader(http.StatusOK)
+	io.Copy(w, reader)
+}
+
+func (h *LocalHandler) remove(w http.ResponseWriter, r *http.Request) {
+	repoName := chi.URLParam(r, "name")
+	filePath := chi.URLParam(r, "*")
+
+	if err := deleteLocalFile(r.Context(), h.db, repoName, filePath); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// deleteLocalFile removes a local file and runs the provider's post-delete hook,
+// so provider-derived state (e.g. RPM metadata that feeds generated repodata)
+// stops referencing a package that no longer exists.
+func deleteLocalFile(ctx context.Context, db *database.DB, repoName, filePath string) error {
+	if err := db.DeleteLocalFile(ctx, repoName, filePath); err != nil {
+		return err
+	}
+
+	remote, err := db.GetRemote(ctx, repoName)
+	if err != nil {
+		return nil // file is gone; no repo left to resolve a cleanup hook from
+	}
+	prov, err := provider.Get(remote.PackageType)
+	if err != nil {
+		return nil
+	}
+	if hook, ok := prov.(provider.PostDeleteHook); ok {
+		return hook.AfterDelete(ctx, repoName, filePath, db)
+	}
+	return nil
+}
+
+func (h *LocalHandler) DB() *database.DB {
+	return h.db
+}
+
+func (h *LocalHandler) Download(ctx context.Context, key string) (io.ReadCloser, int64, error) {
+	reader, info, err := h.store.Download(ctx, key)
+	if err != nil {
+		return nil, 0, err
+	}
+	return reader, info.Size, nil
+}

internal/api/v2/local_evict_cleanup_test.go

@@ -0,0 +1,75 @@
+package v2
+
+import (
+	"context"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	_ "git.unkin.net/unkin/artifactapi/internal/provider/rpm" // register the rpm provider so its PostDeleteHook runs
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// TestLocalEvictCleansRPMMetadata verifies that evicting an RPM from a local
+// repo also removes the derived rpm_metadata row, so generated repodata stops
+// listing the deleted package.
+func TestLocalEvictCleansRPMMetadata(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 = "rpm-evict-cleanup"
+	if err := db.CreateRemote(ctx, &models.Remote{Name: repo, PackageType: models.PackageRPM, RepoType: models.RepoTypeLocal}); err != nil {
+		t.Fatal(err)
+	}
+
+	const hash = "sha256:bb22"
+	const path = "Packages/example-0.1.0-1.x86_64.rpm"
+	if err := db.UpsertBlob(ctx, hash, "blobs/bb/22", 2048, "application/x-rpm"); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.CreateLocalFile(ctx, repo, path, hash); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.InsertRPMMetadata(ctx, &provider.RPMMetadata{
+		RepoName: repo, FilePath: path, ContentHash: hash,
+		Name: "example", Version: "0.1.0", Release: "1", Arch: "x86_64",
+		Requires: []provider.RPMDep{}, Provides: []provider.RPMDep{},
+		Files: []provider.RPMFile{}, Changelogs: []provider.RPMChangelog{},
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	h := NewObjectsHandler(db)
+	router := chi.NewRouter()
+	router.Route("/locals/{name}/objects", func(r chi.Router) {
+		r.Delete("/*", h.LocalRoutes().ServeHTTP)
+	})
+
+	del := httptest.NewRequest("DELETE", "/locals/"+repo+"/objects/"+path, nil)
+	dw := httptest.NewRecorder()
+	router.ServeHTTP(dw, del)
+	if dw.Code != 204 {
+		t.Fatalf("evict = %d, want 204", dw.Code)
+	}
+
+	if f, _ := db.GetLocalFile(ctx, repo, path); f != nil {
+		t.Fatalf("local file still present after evict: %+v", f)
+	}
+	entries, err := db.ListRPMMetadataEntries(ctx, repo)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(entries) != 0 {
+		t.Fatalf("rpm_metadata still present after evict: %+v", entries)
+	}
+}

internal/api/v2/local_fault_test.go

@@ -0,0 +1,88 @@
+package v2
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"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/pkg/models"
+)
+
+// TestLocalUploadStoreFailure covers the upload handlers' store-error branches
+// by killing the object store after a successful upload.
+func TestLocalUploadStoreFailure(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()
+
+	conn, termMinio, err := testsupport.StartMinio(ctx)
+	if err != nil {
+		t.Skip("minio unavailable")
+	}
+	var store *storage.S3
+	for i := 0; i < 20; i++ {
+		if store, err = storage.NewS3(conn.Endpoint, conn.AccessKey, conn.SecretKey, "fault", false, ""); err == nil {
+			break
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+	if err != nil {
+		termMinio()
+		t.Fatal(err)
+	}
+
+	for _, pt := range []models.PackageType{models.PackageGeneric, models.PackagePyPI} {
+		if err := db.CreateRemote(ctx, &models.Remote{Name: "fault-" + string(pt), PackageType: pt, RepoType: models.RepoTypeLocal}); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	h := NewLocalHandler(db, store)
+	router := chi.NewRouter()
+	router.Route("/remotes/{name}/files", func(r chi.Router) {
+		r.Put("/*", h.Routes().ServeHTTP)
+	})
+	srv := httptest.NewServer(router)
+	defer srv.Close()
+
+	put := func(name, path, body string) int {
+		rq, _ := http.NewRequest("PUT", srv.URL+"/remotes/"+name+"/files/"+path, strings.NewReader(body))
+		resp, err := http.DefaultClient.Do(rq)
+		if err != nil {
+			t.Fatalf("put: %v", err)
+		}
+		resp.Body.Close()
+		return resp.StatusCode
+	}
+
+	// Sanity: uploads succeed while the store is up.
+	if c := put("fault-generic", "ok.bin", "data"); c != 201 {
+		t.Fatalf("generic upload while up = %d", c)
+	}
+	if c := put("fault-pypi", "foo-1.0-py3-none-any.whl", "wheel"); c != 201 {
+		t.Fatalf("pypi upload while up = %d", c)
+	}
+
+	// Kill the store; subsequent CAS.Store calls fail -> 500.
+	termMinio()
+	if c := put("fault-generic", "after.bin", "data"); c != 500 {
+		t.Errorf("generic upload after store down = %d, want 500", c)
+	}
+	if c := put("fault-pypi", "bar-1.0-py3-none-any.whl", "wheel"); c != 500 {
+		t.Errorf("pypi upload after store down = %d, want 500", c)
+	}
+}

internal/api/v2/local_objects_test.go

@@ -0,0 +1,78 @@
+package v2
+
+import (
+	"context"
+	"encoding/json"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// TestLocalObjectsListing verifies that files uploaded to a local repo (which
+// live in local_files, not artifacts) are listed by the local objects endpoint
+// and can be evicted through it.
+func TestLocalObjectsListing(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 = "rpm-local-objs"
+	if err := db.CreateRemote(ctx, &models.Remote{Name: repo, PackageType: models.PackageRPM, RepoType: models.RepoTypeLocal}); err != nil {
+		t.Fatal(err)
+	}
+
+	const hash = "sha256:aa11"
+	const path = "Packages/example-0.1.0-1.x86_64.rpm"
+	if err := db.UpsertBlob(ctx, hash, "blobs/aa/11", 1234, "application/x-rpm"); err != nil {
+		t.Fatal(err)
+	}
+	if err := db.CreateLocalFile(ctx, repo, path, hash); err != nil {
+		t.Fatal(err)
+	}
+
+	h := NewObjectsHandler(db)
+	router := chi.NewRouter()
+	router.Route("/locals/{name}/objects", func(r chi.Router) {
+		r.Get("/", h.LocalRoutes().ServeHTTP)
+		r.Delete("/*", h.LocalRoutes().ServeHTTP)
+	})
+
+	// The uploaded package must appear in the listing with its blob size.
+	req := httptest.NewRequest("GET", "/locals/"+repo+"/objects", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+	if w.Code != 200 {
+		t.Fatalf("list = %d, want 200", w.Code)
+	}
+	var got []models.Artifact
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("got %d objects, want 1", len(got))
+	}
+	if got[0].Path != path || got[0].SizeBytes != 1234 || got[0].ContentHash != hash {
+		t.Fatalf("unexpected object: %+v", got[0])
+	}
+
+	// Eviction removes it from local_files.
+	del := httptest.NewRequest("DELETE", "/locals/"+repo+"/objects/"+path, nil)
+	dw := httptest.NewRecorder()
+	router.ServeHTTP(dw, del)
+	if dw.Code != 204 {
+		t.Fatalf("evict = %d, want 204", dw.Code)
+	}
+	if f, _ := db.GetLocalFile(ctx, repo, path); f != nil {
+		t.Fatalf("file still present after evict: %+v", f)
+	}
+}

internal/api/v2/objects.go

@@ -0,0 +1,94 @@
+package v2
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+)
+
+type ObjectsHandler struct {
+	db *database.DB
+}
+
+func NewObjectsHandler(db *database.DB) *ObjectsHandler {
+	return &ObjectsHandler{db: db}
+}
+
+func (h *ObjectsHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.list)
+	r.Delete("/*", h.evict)
+	return r
+}
+
+// LocalRoutes lists and evicts objects for local repos, which live in the
+// local_files table rather than the artifacts table used by remotes.
+func (h *ObjectsHandler) LocalRoutes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.listLocal)
+	r.Delete("/*", h.evictLocal)
+	return r
+}
+
+// pageBounds parses the shared page/per_page query params into a SQL limit and offset.
+func pageBounds(r *http.Request) (limit, offset int) {
+	limit, _ = strconv.Atoi(r.URL.Query().Get("per_page"))
+	if limit <= 0 || limit > 5000 {
+		limit = 50
+	}
+	page, _ := strconv.Atoi(r.URL.Query().Get("page"))
+	if page <= 0 {
+		page = 1
+	}
+	return limit, (page - 1) * limit
+}
+
+func (h *ObjectsHandler) list(w http.ResponseWriter, r *http.Request) {
+	remoteName := chi.URLParam(r, "name")
+	limit, offset := pageBounds(r)
+
+	artifacts, err := h.db.ListArtifacts(r.Context(), remoteName, limit, offset)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, artifacts)
+}
+
+func (h *ObjectsHandler) listLocal(w http.ResponseWriter, r *http.Request) {
+	repoName := chi.URLParam(r, "name")
+	limit, offset := pageBounds(r)
+
+	artifacts, err := h.db.ListLocalArtifacts(r.Context(), repoName, limit, offset)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, artifacts)
+}
+
+func (h *ObjectsHandler) evictLocal(w http.ResponseWriter, r *http.Request) {
+	repoName := chi.URLParam(r, "name")
+	path := chi.URLParam(r, "*")
+
+	if err := deleteLocalFile(r.Context(), h.db, repoName, path); err != nil {
+		http.Error(w, fmt.Sprintf("evict failed: %v", err), http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (h *ObjectsHandler) evict(w http.ResponseWriter, r *http.Request) {
+	remoteName := chi.URLParam(r, "name")
+	path := chi.URLParam(r, "*")
+
+	if err := h.db.DeleteArtifact(r.Context(), remoteName, path); err != nil {
+		http.Error(w, fmt.Sprintf("evict failed: %v", err), http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

internal/api/v2/probe.go

@@ -0,0 +1,109 @@
+package v2
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/proxy"
+)
+
+type ProbeHandler struct {
+	engine *proxy.Engine
+	db     *database.DB
+}
+
+func NewProbeHandler(engine *proxy.Engine, db *database.DB) *ProbeHandler {
+	return &ProbeHandler{engine: engine, db: db}
+}
+
+func (h *ProbeHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Post("/", h.probe)
+	return r
+}
+
+type probeRequest struct {
+	Remote string `json:"remote"`
+	Path   string `json:"path"`
+}
+
+type probeResponse struct {
+	Status      int               `json:"status"`
+	Source      string            `json:"source,omitempty"`
+	ContentType string            `json:"content_type,omitempty"`
+	SizeBytes   int64             `json:"size_bytes"`
+	Headers     map[string]string `json:"headers,omitempty"`
+	DurationMS  int64             `json:"duration_ms"`
+	Error       string            `json:"error,omitempty"`
+}
+
+func (h *ProbeHandler) probe(w http.ResponseWriter, r *http.Request) {
+	var req probeRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "invalid json", http.StatusBadRequest)
+		return
+	}
+
+	if req.Remote == "" || req.Path == "" {
+		http.Error(w, "remote and path are required", http.StatusBadRequest)
+		return
+	}
+
+	remote, err := h.db.GetRemote(r.Context(), req.Remote)
+	if err != nil {
+		writeJSON(w, http.StatusOK, probeResponse{
+			Status: 404,
+			Error:  fmt.Sprintf("remote %q not found", req.Remote),
+		})
+		return
+	}
+
+	prov, err := provider.Get(remote.PackageType)
+	if err != nil {
+		writeJSON(w, http.StatusOK, probeResponse{
+			Status: 500,
+			Error:  fmt.Sprintf("no provider for %q", remote.PackageType),
+		})
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+	defer cancel()
+
+	start := time.Now()
+	result, err := h.engine.Fetch(ctx, *remote, req.Path, prov)
+	duration := time.Since(start).Milliseconds()
+
+	if err != nil {
+		writeJSON(w, http.StatusOK, probeResponse{
+			Status:     502,
+			DurationMS: duration,
+			Error:      err.Error(),
+		})
+		return
+	}
+
+	io.Copy(io.Discard, result.Reader)
+	result.Reader.Close()
+
+	writeJSON(w, http.StatusOK, probeResponse{
+		Status:      200,
+		Source:      result.Source,
+		ContentType: result.ContentType,
+		SizeBytes:   result.Size,
+		DurationMS:  duration,
+		Headers: map[string]string{
+			"X-Artifact-Source": result.Source,
+			"X-Artifact-Size":   fmt.Sprintf("%d", result.Size),
+			"Content-Type":      result.ContentType,
+		},
+	})
+}

internal/api/v2/remotes.go

@@ -0,0 +1,175 @@
+package v2
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// Primer enqueues a background metadata prime for a newly created remote so the
+// create call never blocks on a derive. *rpm.Syncer and *deb.Syncer satisfy it.
+type Primer interface {
+	EnqueuePrime(remote models.Remote)
+}
+
+// MetadataFlusher purges a remote's cached mutable metadata (repodata / Release
+// / APKINDEX freshness keys). *cache.Redis satisfies it.
+type MetadataFlusher interface {
+	FlushRemote(ctx context.Context, remote string) error
+}
+
+type RemotesHandler struct {
+	db      *database.DB
+	cache   MetadataFlusher
+	primers map[models.PackageType]Primer
+}
+
+// NewRemotesHandler wires the handler to the metadata cache and per-type
+// primers. cache may be nil (flush-on-backend-change is skipped); primers may
+// be nil (a package type with no registered primer simply skips priming).
+func NewRemotesHandler(db *database.DB, cache MetadataFlusher, primers map[models.PackageType]Primer) *RemotesHandler {
+	return &RemotesHandler{db: db, cache: cache, primers: primers}
+}
+
+func (h *RemotesHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.list)
+	r.Post("/", h.create)
+	r.Get("/{name}", h.get)
+	r.Put("/{name}", h.update)
+	r.Delete("/{name}", h.del)
+	return r
+}
+
+func (h *RemotesHandler) list(w http.ResponseWriter, r *http.Request) {
+	remotes, err := h.db.ListRemotes(r.Context())
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, remotes)
+}
+
+func (h *RemotesHandler) get(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	remote, err := h.db.GetRemote(r.Context(), name)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("remote %q not found", name), http.StatusNotFound)
+		return
+	}
+	writeJSON(w, http.StatusOK, remote)
+}
+
+func (h *RemotesHandler) create(w http.ResponseWriter, r *http.Request) {
+	var remote models.Remote
+	if err := json.NewDecoder(r.Body).Decode(&remote); err != nil {
+		http.Error(w, "invalid json", http.StatusBadRequest)
+		return
+	}
+	if !remote.PackageType.Valid() {
+		http.Error(w, fmt.Sprintf("invalid package type: %q", remote.PackageType), http.StatusBadRequest)
+		return
+	}
+	if remote.RepoType == "" {
+		remote.RepoType = models.RepoTypeRemote
+	}
+	if !remote.RepoType.Valid() {
+		http.Error(w, fmt.Sprintf("invalid repo type: %q", remote.RepoType), http.StatusBadRequest)
+		return
+	}
+	if remote.RepoType == models.RepoTypeRemote && remote.BaseURL == "" {
+		http.Error(w, "base_url is required for remote repositories", http.StatusBadRequest)
+		return
+	}
+	if err := remote.ValidateMirrorlist(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if err := remote.ValidateMirrorStrategy(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if err := remote.ValidatePatterns(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if err := h.db.CreateRemote(r.Context(), &remote); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	// Prime a metadata-only remote (github_rpm/github_deb) in the background so
+	// its first index request is served from cache instead of a cold derive.
+	if primer := h.primers[remote.PackageType]; primer != nil {
+		primer.EnqueuePrime(remote)
+	}
+	writeJSON(w, http.StatusCreated, remote)
+}
+
+func (h *RemotesHandler) update(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	var remote models.Remote
+	if err := json.NewDecoder(r.Body).Decode(&remote); err != nil {
+		http.Error(w, "invalid json", http.StatusBadRequest)
+		return
+	}
+	remote.Name = name
+	if err := remote.ValidateMirrorlist(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if err := remote.ValidateMirrorStrategy(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if err := remote.ValidatePatterns(); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	// Capture the current backend before the update so we can tell whether the
+	// remote's base_url (its upstream) changed. A read failure just means we
+	// skip the freshness flush; it must not block the update.
+	oldBaseURL, oldKnown := "", false
+	if existing, err := h.db.GetRemote(r.Context(), name); err == nil {
+		oldBaseURL, oldKnown = existing.BaseURL, true
+	}
+	if err := h.db.UpdateRemote(r.Context(), &remote); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	// Changing the backend invalidates any cached mutable metadata (repodata /
+	// Release / APKINDEX): purge it so the next request re-fetches from the new
+	// upstream instead of serving stale data until TTL expiry. A flush failure
+	// is logged but does not fail the request — the DB update already landed.
+	if oldKnown && oldBaseURL != remote.BaseURL && h.cache != nil {
+		if err := h.cache.FlushRemote(r.Context(), name); err != nil {
+			slog.Warn("flush cached metadata after base_url change failed",
+				"remote", name, "error", err)
+		} else {
+			slog.Info("flushed cached metadata after base_url change",
+				"remote", name, "old_base_url", oldBaseURL, "new_base_url", remote.BaseURL)
+		}
+	}
+	writeJSON(w, http.StatusOK, remote)
+}
+
+func (h *RemotesHandler) del(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	if err := h.db.DeleteRemote(r.Context(), name); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(v)
+}

internal/api/v2/remotes_flush_test.go

@@ -0,0 +1,96 @@
+package v2
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// fakeFlusher records FlushRemote calls so a test can assert whether — and how
+// often — a remote's cached metadata was purged.
+type fakeFlusher struct {
+	calls []string
+	err   error
+}
+
+func (f *fakeFlusher) FlushRemote(_ context.Context, remote string) error {
+	f.calls = append(f.calls, remote)
+	return f.err
+}
+
+func seedRemote(t *testing.T, db *database.DB, name, baseURL string) {
+	t.Helper()
+	err := db.CreateRemote(context.Background(), &models.Remote{
+		Name:        name,
+		PackageType: models.PackageRPM,
+		RepoType:    models.RepoTypeRemote,
+		BaseURL:     baseURL,
+	})
+	if err != nil {
+		t.Fatalf("seed remote: %v", err)
+	}
+}
+
+// A base_url change must flush the remote's cached metadata exactly once, while
+// an update that leaves base_url untouched must not flush at all.
+func TestUpdateFlushesCacheOnBaseURLChange(t *testing.T) {
+	if testDSN == "" {
+		t.Skip("Docker unavailable")
+	}
+	db, err := database.New(testDSN)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	const name = "rpm-flush-change"
+	seedRemote(t, db, name, "https://old.example.com/repo")
+
+	ff := &fakeFlusher{}
+	h := NewRemotesHandler(db, ff, nil).Routes()
+
+	if c := do(t, h, "PUT", "/"+name, `{"package_type":"rpm","repo_type":"remote","base_url":"https://new.example.com/repo"}`); c != 200 {
+		t.Fatalf("update (backend change) = %d, want 200", c)
+	}
+	if len(ff.calls) != 1 || ff.calls[0] != name {
+		t.Fatalf("flush calls = %v, want exactly one flush of %q", ff.calls, name)
+	}
+
+	// Re-updating with the same (now current) base_url must not flush again.
+	ff.calls = nil
+	if c := do(t, h, "PUT", "/"+name, `{"package_type":"rpm","repo_type":"remote","base_url":"https://new.example.com/repo"}`); c != 200 {
+		t.Fatalf("update (no backend change) = %d, want 200", c)
+	}
+	if len(ff.calls) != 0 {
+		t.Fatalf("flush calls = %v, want no flush when base_url is unchanged", ff.calls)
+	}
+}
+
+// A flush error must be swallowed: the DB update already succeeded, so the
+// request still returns 200.
+func TestUpdateFlushFailureStillSucceeds(t *testing.T) {
+	if testDSN == "" {
+		t.Skip("Docker unavailable")
+	}
+	db, err := database.New(testDSN)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	const name = "rpm-flush-error"
+	seedRemote(t, db, name, "https://old.example.com/repo")
+
+	ff := &fakeFlusher{err: errors.New("redis down")}
+	h := NewRemotesHandler(db, ff, nil).Routes()
+
+	if c := do(t, h, "PUT", "/"+name, `{"package_type":"rpm","repo_type":"remote","base_url":"https://new.example.com/repo"}`); c != 200 {
+		t.Fatalf("update with failing flush = %d, want 200", c)
+	}
+	if len(ff.calls) != 1 {
+		t.Fatalf("flush calls = %v, want exactly one attempted flush", ff.calls)
+	}
+}

internal/api/v2/stats.go

@@ -0,0 +1,62 @@
+package v2
+
+import (
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+)
+
+type StatsHandler struct {
+	db *database.DB
+}
+
+func NewStatsHandler(db *database.DB) *StatsHandler {
+	return &StatsHandler{db: db}
+}
+
+func (h *StatsHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.overview)
+	r.Get("/top-remotes", h.topRemotes)
+	r.Get("/top-files-by-hits", h.topFilesByHits)
+	r.Get("/top-files-by-bandwidth", h.topFilesByBandwidth)
+	return r
+}
+
+func (h *StatsHandler) overview(w http.ResponseWriter, r *http.Request) {
+	stats, err := h.db.GetOverviewStats(r.Context())
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, stats)
+}
+
+func (h *StatsHandler) topRemotes(w http.ResponseWriter, r *http.Request) {
+	remotes, err := h.db.GetTopRemotes(r.Context(), 10)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, remotes)
+}
+
+func (h *StatsHandler) topFilesByHits(w http.ResponseWriter, r *http.Request) {
+	files, err := h.db.GetTopFilesByHits(r.Context(), 10)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, files)
+}
+
+func (h *StatsHandler) topFilesByBandwidth(w http.ResponseWriter, r *http.Request) {
+	files, err := h.db.GetTopFilesByBandwidth(r.Context(), 10)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, files)
+}

internal/api/v2/virtuals.go

@@ -0,0 +1,86 @@
+package v2
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+type VirtualsHandler struct {
+	db *database.DB
+}
+
+func NewVirtualsHandler(db *database.DB) *VirtualsHandler {
+	return &VirtualsHandler{db: db}
+}
+
+func (h *VirtualsHandler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.list)
+	r.Post("/", h.create)
+	r.Get("/{name}", h.get)
+	r.Put("/{name}", h.update)
+	r.Delete("/{name}", h.del)
+	return r
+}
+
+func (h *VirtualsHandler) list(w http.ResponseWriter, r *http.Request) {
+	virtuals, err := h.db.ListVirtuals(r.Context())
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, virtuals)
+}
+
+func (h *VirtualsHandler) get(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	virt, err := h.db.GetVirtual(r.Context(), name)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("virtual %q not found", name), http.StatusNotFound)
+		return
+	}
+	writeJSON(w, http.StatusOK, virt)
+}
+
+func (h *VirtualsHandler) create(w http.ResponseWriter, r *http.Request) {
+	var virt models.Virtual
+	if err := json.NewDecoder(r.Body).Decode(&virt); err != nil {
+		http.Error(w, "invalid json", http.StatusBadRequest)
+		return
+	}
+	if err := h.db.CreateVirtual(r.Context(), &virt); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusCreated, virt)
+}
+
+func (h *VirtualsHandler) update(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	var virt models.Virtual
+	if err := json.NewDecoder(r.Body).Decode(&virt); err != nil {
+		http.Error(w, "invalid json", http.StatusBadRequest)
+		return
+	}
+	virt.Name = name
+	if err := h.db.UpdateVirtual(r.Context(), &virt); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	writeJSON(w, http.StatusOK, virt)
+}
+
+func (h *VirtualsHandler) del(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "name")
+	if err := h.db.DeleteVirtual(r.Context(), name); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

internal/auth/basic.go

@@ -0,0 +1,18 @@
+package auth
+
+import (
+	"encoding/base64"
+	"net/http"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func BasicHeaders(remote models.Remote) http.Header {
+	h := http.Header{}
+	if remote.Username != "" {
+		h.Set("Authorization", "Basic "+base64.StdEncoding.EncodeToString(
+			[]byte(remote.Username+":"+remote.Password),
+		))
+	}
+	return h
+}

internal/auth/basic_test.go

@@ -0,0 +1,23 @@
+package auth
+
+import (
+	"encoding/base64"
+	"testing"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func TestBasicHeaders(t *testing.T) {
+	h := BasicHeaders(models.Remote{Username: "alice", Password: "secret"})
+	got := h.Get("Authorization")
+	want := "Basic " + base64.StdEncoding.EncodeToString([]byte("alice:secret"))
+	if got != want {
+		t.Errorf("Authorization = %q, want %q", got, want)
+	}
+}
+
+func TestBasicHeadersNoUser(t *testing.T) {
+	if h := BasicHeaders(models.Remote{}); h.Get("Authorization") != "" {
+		t.Error("expected no Authorization header without a username")
+	}
+}

internal/cache/cache_test.go

@@ -0,0 +1,133 @@
+package cache
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+)
+
+var testRedis *Redis
+
+func TestMain(m *testing.M) {
+	ctx := context.Background()
+	url, terminate, err := testsupport.StartRedis(ctx)
+	if err != nil {
+		os.Exit(m.Run())
+	}
+	r, err := NewRedis(url)
+	if err != nil {
+		terminate()
+		panic(err)
+	}
+	testRedis = r
+	code := m.Run()
+	r.Close()
+	terminate()
+	if code != 0 {
+		os.Exit(code)
+	}
+}
+
+func requireRedis(t *testing.T) {
+	t.Helper()
+	if testRedis == nil {
+		t.Skip("Docker unavailable; skipping cache integration test")
+	}
+}
+
+func TestNewRedisInvalid(t *testing.T) {
+	if _, err := NewRedis("://bad-url"); err == nil {
+		t.Error("expected error for invalid redis URL")
+	}
+}
+
+func TestTTL(t *testing.T) {
+	requireRedis(t)
+	ctx := context.Background()
+	if fresh, _ := testRedis.CheckTTL(ctx, "r", "missing"); fresh {
+		t.Error("missing key should not be fresh")
+	}
+	if err := testRedis.SetTTL(ctx, "r", "p", time.Minute); err != nil {
+		t.Fatal(err)
+	}
+	if fresh, err := testRedis.CheckTTL(ctx, "r", "p"); err != nil || !fresh {
+		t.Errorf("expected fresh after SetTTL: %v %v", fresh, err)
+	}
+}
+
+func TestLock(t *testing.T) {
+	requireRedis(t)
+	ctx := context.Background()
+	ok, err := testRedis.AcquireLock(ctx, "r", "lockpath", time.Minute)
+	if err != nil || !ok {
+		t.Fatalf("first acquire should succeed: %v %v", ok, err)
+	}
+	if ok, _ := testRedis.AcquireLock(ctx, "r", "lockpath", time.Minute); ok {
+		t.Error("second acquire should fail while held")
+	}
+	if err := testRedis.ReleaseLock(ctx, "r", "lockpath"); err != nil {
+		t.Fatal(err)
+	}
+	if ok, _ := testRedis.AcquireLock(ctx, "r", "lockpath", time.Minute); !ok {
+		t.Error("acquire should succeed after release")
+	}
+}
+
+func TestETagAndToken(t *testing.T) {
+	requireRedis(t)
+	ctx := context.Background()
+	if v, _ := testRedis.GetETag(ctx, "r", "missing"); v != "" {
+		t.Error("missing etag should be empty")
+	}
+	testRedis.SetETag(ctx, "r", "p", `"abc"`, time.Minute)
+	if v, _ := testRedis.GetETag(ctx, "r", "p"); v != `"abc"` {
+		t.Errorf("etag = %q", v)
+	}
+
+	if v, _ := testRedis.GetToken(ctx, "missing"); v != "" {
+		t.Error("missing token should be empty")
+	}
+	testRedis.SetToken(ctx, "key", "tok", time.Minute)
+	if v, _ := testRedis.GetToken(ctx, "key"); v != "tok" {
+		t.Errorf("token = %q", v)
+	}
+}
+
+func TestCircuit(t *testing.T) {
+	requireRedis(t)
+	ctx := context.Background()
+	if n, _ := testRedis.GetCircuitFailures(ctx, "cr"); n != 0 {
+		t.Errorf("initial failures = %d", n)
+	}
+	n1, err := testRedis.IncrCircuitFailure(ctx, "cr", time.Minute)
+	if err != nil || n1 != 1 {
+		t.Fatalf("first incr = %d %v", n1, err)
+	}
+	n2, _ := testRedis.IncrCircuitFailure(ctx, "cr", time.Minute)
+	if n2 != 2 {
+		t.Errorf("second incr = %d", n2)
+	}
+	if n, _ := testRedis.GetCircuitFailures(ctx, "cr"); n != 2 {
+		t.Errorf("get failures = %d", n)
+	}
+	testRedis.ResetCircuit(ctx, "cr")
+	if n, _ := testRedis.GetCircuitFailures(ctx, "cr"); n != 0 {
+		t.Errorf("failures after reset = %d", n)
+	}
+}
+
+func TestFlushRemote(t *testing.T) {
+	requireRedis(t)
+	ctx := context.Background()
+	testRedis.SetTTL(ctx, "flushme", "a", time.Hour)
+	testRedis.SetETag(ctx, "flushme", "a", "x", time.Hour)
+	if err := testRedis.FlushRemote(ctx, "flushme"); err != nil {
+		t.Fatal(err)
+	}
+	if fresh, _ := testRedis.CheckTTL(ctx, "flushme", "a"); fresh {
+		t.Error("expected keys flushed")
+	}
+}

internal/cache/redis.go

@@ -0,0 +1,117 @@
+package cache
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+type Redis struct {
+	client *redis.Client
+}
+
+func NewRedis(url string) (*Redis, error) {
+	opts, err := redis.ParseURL(url)
+	if err != nil {
+		return nil, fmt.Errorf("parse redis url: %w", err)
+	}
+
+	client := redis.NewClient(opts)
+
+	if err := client.Ping(context.Background()).Err(); err != nil {
+		return nil, fmt.Errorf("ping redis: %w", err)
+	}
+
+	return &Redis{client: client}, nil
+}
+
+func (r *Redis) Close() error {
+	return r.client.Close()
+}
+
+func (r *Redis) SetTTL(ctx context.Context, remote, path string, ttl time.Duration) error {
+	key := fmt.Sprintf("ttl:%s:%s", remote, path)
+	return r.client.Set(ctx, key, "1", ttl).Err()
+}
+
+func (r *Redis) CheckTTL(ctx context.Context, remote, path string) (bool, error) {
+	key := fmt.Sprintf("ttl:%s:%s", remote, path)
+	exists, err := r.client.Exists(ctx, key).Result()
+	if err != nil {
+		return false, err
+	}
+	return exists > 0, nil
+}
+
+func (r *Redis) AcquireLock(ctx context.Context, remote, path string, ttl time.Duration) (bool, error) {
+	key := fmt.Sprintf("lock:%s:%s", remote, path)
+	ok, err := r.client.SetNX(ctx, key, "1", ttl).Result()
+	return ok, err
+}
+
+func (r *Redis) ReleaseLock(ctx context.Context, remote, path string) error {
+	key := fmt.Sprintf("lock:%s:%s", remote, path)
+	return r.client.Del(ctx, key).Err()
+}
+
+func (r *Redis) SetETag(ctx context.Context, remote, path, etag string, ttl time.Duration) error {
+	key := fmt.Sprintf("etag:%s:%s", remote, path)
+	return r.client.Set(ctx, key, etag, ttl).Err()
+}
+
+func (r *Redis) GetETag(ctx context.Context, remote, path string) (string, error) {
+	key := fmt.Sprintf("etag:%s:%s", remote, path)
+	val, err := r.client.Get(ctx, key).Result()
+	if err == redis.Nil {
+		return "", nil
+	}
+	return val, err
+}
+
+func (r *Redis) GetToken(ctx context.Context, key string) (string, error) {
+	val, err := r.client.Get(ctx, "token:"+key).Result()
+	if err == redis.Nil {
+		return "", nil
+	}
+	return val, err
+}
+
+func (r *Redis) SetToken(ctx context.Context, key, token string, ttl time.Duration) error {
+	return r.client.Set(ctx, "token:"+key, token, ttl).Err()
+}
+
+func (r *Redis) IncrCircuitFailure(ctx context.Context, remote string, cooldown time.Duration) (int64, error) {
+	key := fmt.Sprintf("circuit:%s", remote)
+	pipe := r.client.Pipeline()
+	incr := pipe.Incr(ctx, key)
+	pipe.Expire(ctx, key, cooldown)
+	_, err := pipe.Exec(ctx)
+	if err != nil {
+		return 0, err
+	}
+	return incr.Val(), nil
+}
+
+func (r *Redis) ResetCircuit(ctx context.Context, remote string) error {
+	key := fmt.Sprintf("circuit:%s", remote)
+	return r.client.Del(ctx, key).Err()
+}
+
+func (r *Redis) GetCircuitFailures(ctx context.Context, remote string) (int64, error) {
+	key := fmt.Sprintf("circuit:%s", remote)
+	val, err := r.client.Get(ctx, key).Int64()
+	if err == redis.Nil {
+		return 0, nil
+	}
+	return val, err
+}
+
+func (r *Redis) FlushRemote(ctx context.Context, remote string) error {
+	iter := r.client.Scan(ctx, 0, fmt.Sprintf("*:%s:*", remote), 100).Iterator()
+	for iter.Next(ctx) {
+		r.client.Del(ctx, iter.Val())
+	}
+	return iter.Err()
+}

internal/config/env.go

@@ -0,0 +1,136 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+)
+
+type Config struct {
+	ListenAddr string
+
+	DBHost string
+	DBPort int
+	DBUser string
+	DBPass string
+	DBName string
+	DBSSL  string
+
+	RedisURL string
+
+	S3Endpoint  string
+	S3AccessKey string
+	S3SecretKey string
+	S3Bucket    string
+	S3Secure    bool
+	S3Region    string
+
+	// Terraform provider registry signing. When TFSigningKeyPath points at a
+	// readable armored GPG private key, artifactapi serves local terraform
+	// repos as a real provider registry (service discovery + signed
+	// SHA256SUMS). Left empty, the registry endpoints stay disabled.
+	TFSigningKeyPath       string
+	TFSigningKeyPassphrase string
+	TFProviderProtocols    string
+
+	// github_rpm background syncer. The syncer keeps derived RPM metadata for
+	// every github_rpm remote fresh off the client request path, sharing a
+	// single global token-bucket limiter across all remotes so GitHub is never
+	// hammered. Defaults are conservative: 1 req/s (3600/hr) sits well under an
+	// authenticated token's 5000/hr. Unauthenticated remotes (60/hr) lean on
+	// ETag/304 — an unchanged repo costs nothing — so keep those repos small or
+	// configure a token.
+	GitHubSyncRatePerSec   float64
+	GitHubSyncBurst        int
+	GitHubSyncWorkers      int
+	GitHubSyncPollInterval int
+
+	// Server-level GitHub machine credential, applied by default to every
+	// outbound GitHub request (releases scan, ranged asset fetches, and the
+	// generic-github byte proxy for private assets). Delivered via env/secret
+	// only — never stored per-remote, never returned by an API, never logged.
+	// Configure exactly one mode: a Personal Access Token, or a GitHub App
+	// (id + installation id + private key). Partial App config fails at startup.
+	GitHubToken             string
+	GitHubAppID             string
+	GitHubAppInstallationID string
+	GitHubAppPrivateKey     string
+	GitHubAppPrivateKeyPath string
+}
+
+func (c *Config) DatabaseDSN() string {
+	return fmt.Sprintf(
+		"postgres://%s:%s@%s:%d/%s?sslmode=%s",
+		c.DBUser, c.DBPass, c.DBHost, c.DBPort, c.DBName, c.DBSSL,
+	)
+}
+
+func Load() (*Config, error) {
+	dbPort, err := strconv.Atoi(getenv("DBPORT", "5432"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid DBPORT: %w", err)
+	}
+
+	s3Secure, _ := strconv.ParseBool(getenv("MINIO_SECURE", "false"))
+
+	syncRate, err := strconv.ParseFloat(getenv("GITHUB_SYNC_RATE", "1"), 64)
+	if err != nil {
+		return nil, fmt.Errorf("invalid GITHUB_SYNC_RATE: %w", err)
+	}
+	syncBurst, err := strconv.Atoi(getenv("GITHUB_SYNC_BURST", "5"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid GITHUB_SYNC_BURST: %w", err)
+	}
+	syncWorkers, err := strconv.Atoi(getenv("GITHUB_SYNC_WORKERS", "3"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid GITHUB_SYNC_WORKERS: %w", err)
+	}
+	syncPoll, err := strconv.Atoi(getenv("GITHUB_SYNC_POLL_INTERVAL", "60"))
+	if err != nil {
+		return nil, fmt.Errorf("invalid GITHUB_SYNC_POLL_INTERVAL: %w", err)
+	}
+
+	cfg := &Config{
+		ListenAddr: getenv("LISTEN_ADDR", ":8000"),
+
+		DBHost: getenv("DBHOST", "localhost"),
+		DBPort: dbPort,
+		DBUser: getenv("DBUSER", "artifacts"),
+		DBPass: getenv("DBPASS", ""),
+		DBName: getenv("DBNAME", "artifacts"),
+		DBSSL:  getenv("DBSSL", "disable"),
+
+		RedisURL: getenv("REDIS_URL", "redis://localhost:6379"),
+
+		S3Endpoint:  getenv("MINIO_ENDPOINT", "localhost:9000"),
+		S3AccessKey: getenv("MINIO_ACCESS_KEY", ""),
+		S3SecretKey: getenv("MINIO_SECRET_KEY", ""),
+		S3Bucket:    getenv("MINIO_BUCKET", "artifacts"),
+		S3Secure:    s3Secure,
+		S3Region:    getenv("MINIO_REGION", ""),
+
+		TFSigningKeyPath:       getenv("TF_SIGNING_KEY_PATH", ""),
+		TFSigningKeyPassphrase: getenv("TF_SIGNING_KEY_PASSPHRASE", ""),
+		TFProviderProtocols:    getenv("TF_PROVIDER_PROTOCOLS", "5.0,6.0"),
+
+		GitHubSyncRatePerSec:   syncRate,
+		GitHubSyncBurst:        syncBurst,
+		GitHubSyncWorkers:      syncWorkers,
+		GitHubSyncPollInterval: syncPoll,
+
+		GitHubToken:             getenv("GITHUB_TOKEN", ""),
+		GitHubAppID:             getenv("GITHUB_APP_ID", ""),
+		GitHubAppInstallationID: getenv("GITHUB_APP_INSTALLATION_ID", ""),
+		GitHubAppPrivateKey:     getenv("GITHUB_APP_PRIVATE_KEY", ""),
+		GitHubAppPrivateKeyPath: getenv("GITHUB_APP_PRIVATE_KEY_PATH", ""),
+	}
+
+	return cfg, nil
+}
+
+func getenv(key, fallback string) string {
+	if v, ok := os.LookupEnv(key); ok {
+		return v
+	}
+	return fallback
+}

internal/config/env_test.go

@@ -0,0 +1,66 @@
+package config
+
+import (
+	"os"
+	"testing"
+)
+
+func TestLoadDefaults(t *testing.T) {
+	// Unset the vars Load reads so the fallback defaults are exercised.
+	for _, k := range []string{
+		"LISTEN_ADDR", "DBHOST", "DBPORT", "DBUSER", "DBPASS", "DBNAME", "DBSSL",
+		"REDIS_URL", "MINIO_ENDPOINT", "MINIO_ACCESS_KEY", "MINIO_SECRET_KEY",
+		"MINIO_BUCKET", "MINIO_SECURE", "MINIO_REGION",
+	} {
+		old, ok := os.LookupEnv(k)
+		os.Unsetenv(k)
+		if ok {
+			t.Cleanup(func() { os.Setenv(k, old) })
+		}
+	}
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if cfg.ListenAddr != ":8000" || cfg.DBPort != 5432 || cfg.DBUser != "artifacts" {
+		t.Errorf("unexpected defaults: %+v", cfg)
+	}
+	if cfg.RedisURL != "redis://localhost:6379" || cfg.S3Bucket != "artifacts" || cfg.S3Secure {
+		t.Errorf("unexpected defaults: %+v", cfg)
+	}
+}
+
+func TestLoadOverrides(t *testing.T) {
+	t.Setenv("LISTEN_ADDR", ":9999")
+	t.Setenv("DBHOST", "db.example.com")
+	t.Setenv("DBPORT", "6000")
+	t.Setenv("DBUSER", "u")
+	t.Setenv("DBPASS", "pw")
+	t.Setenv("DBNAME", "n")
+	t.Setenv("DBSSL", "require")
+	t.Setenv("MINIO_SECURE", "true")
+	t.Setenv("MINIO_REGION", "us-east-1")
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if cfg.ListenAddr != ":9999" || cfg.DBHost != "db.example.com" || cfg.DBPort != 6000 {
+		t.Errorf("overrides not applied: %+v", cfg)
+	}
+	if !cfg.S3Secure {
+		t.Error("MINIO_SECURE=true not parsed")
+	}
+	want := "postgres://u:pw@db.example.com:6000/n?sslmode=require"
+	if got := cfg.DatabaseDSN(); got != want {
+		t.Errorf("DSN = %q, want %q", got, want)
+	}
+}
+
+func TestLoadInvalidPort(t *testing.T) {
+	t.Setenv("DBPORT", "not-a-number")
+	if _, err := Load(); err == nil {
+		t.Error("expected error for invalid DBPORT")
+	}
+}

internal/database/alpine_github_sync.go

@@ -0,0 +1,71 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// ListGitHubAlpineRemotes returns every github_alpine remote so the syncer can
+// sweep them on each poll tick.
+func (db *DB) ListGitHubAlpineRemotes(ctx context.Context) ([]models.Remote, error) {
+	rows, err := db.Pool.Query(ctx, `SELECT `+remoteCols+` FROM remotes WHERE package_type = $1 ORDER BY name`, models.PackageGitHubAlpine)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var remotes []models.Remote
+	for rows.Next() {
+		var r models.Remote
+		if err := scanRemote(rows, &r); err != nil {
+			return nil, err
+		}
+		remotes = append(remotes, r)
+	}
+	return remotes, rows.Err()
+}
+
+// ClaimGitHubAlpineSyncLease atomically claims the per-remote sync lease. It
+// succeeds only when the remote is due (never synced, or synced longer than
+// freshness ago) and no live lease is held by another replica. A zero freshness
+// (prime scans) ignores the recency gate. The returned etag is the stored
+// releases-list ETag, shared across replicas.
+func (db *DB) ClaimGitHubAlpineSyncLease(ctx context.Context, remoteName, owner string, freshness, lease time.Duration) (bool, string, error) {
+	row := db.Pool.QueryRow(ctx, `
+		INSERT INTO github_alpine_sync_state AS s (remote_name, sync_lease_owner, sync_lease_expires)
+		VALUES ($1, $2, now() + make_interval(secs => $4))
+		ON CONFLICT (remote_name) DO UPDATE
+			SET sync_lease_owner   = $2,
+			    sync_lease_expires = now() + make_interval(secs => $4)
+			WHERE (s.last_synced_at IS NULL OR s.last_synced_at < now() - make_interval(secs => $3))
+			  AND (s.sync_lease_expires IS NULL OR s.sync_lease_expires < now())
+		RETURNING s.etag
+	`, remoteName, owner, freshness.Seconds(), lease.Seconds())
+
+	var etag string
+	if err := row.Scan(&etag); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return false, "", nil
+		}
+		return false, "", err
+	}
+	return true, etag, nil
+}
+
+// ReleaseGitHubAlpineSyncLease records the completed scan and frees the lease.
+// Only the owning replica may release; last_synced_at advances so the next poll
+// waits a full freshness window, and etag is persisted for the next conditional
+// request.
+func (db *DB) ReleaseGitHubAlpineSyncLease(ctx context.Context, remoteName, owner, etag string, syncedAt time.Time) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE github_alpine_sync_state
+		   SET last_synced_at = $3, etag = $4, sync_lease_owner = '', sync_lease_expires = NULL
+		 WHERE remote_name = $1 AND sync_lease_owner = $2
+	`, remoteName, owner, syncedAt, etag)
+	return err
+}

internal/database/alpine_metadata.go

@@ -0,0 +1,70 @@
+package database
+
+import (
+	"context"
+	"strings"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+func (db *DB) InsertAlpineMetadata(ctx context.Context, meta *provider.AlpineMetadata) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO alpine_metadata (
+			repo_name, file_path, content_hash, checksum,
+			name, version, arch, download_size, installed_size,
+			description, url, license, origin, maintainer,
+			build_time, commit_hash, provider_priority,
+			depends, provides, install_if
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20)
+		ON CONFLICT (repo_name, file_path) DO NOTHING
+	`,
+		meta.RepoName, meta.FilePath, meta.ContentHash, meta.Checksum,
+		meta.Name, meta.Version, meta.Arch, meta.DownloadSize, meta.InstalledSize,
+		meta.Description, meta.URL, meta.License, meta.Origin, meta.Maintainer,
+		meta.BuildTime, meta.Commit, meta.ProviderPriority,
+		strings.Join(meta.Depends, " "), strings.Join(meta.Provides, " "), strings.Join(meta.InstallIf, " "),
+	)
+	return err
+}
+
+func (db *DB) DeleteAlpineMetadata(ctx context.Context, repoName, filePath string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM alpine_metadata WHERE repo_name = $1 AND file_path = $2`, repoName, filePath)
+	return err
+}
+
+func (db *DB) ListAlpineMetadataEntries(ctx context.Context, repoName string) ([]provider.AlpineMetadata, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT repo_name, file_path, content_hash, checksum,
+			name, version, arch, download_size, installed_size,
+			description, url, license, origin, maintainer,
+			build_time, commit_hash, provider_priority,
+			depends, provides, install_if
+		FROM alpine_metadata
+		WHERE repo_name = $1
+		ORDER BY name, version, arch, file_path
+	`, repoName)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []provider.AlpineMetadata
+	for rows.Next() {
+		var m provider.AlpineMetadata
+		var depends, provides, installIf string
+		if err := rows.Scan(
+			&m.RepoName, &m.FilePath, &m.ContentHash, &m.Checksum,
+			&m.Name, &m.Version, &m.Arch, &m.DownloadSize, &m.InstalledSize,
+			&m.Description, &m.URL, &m.License, &m.Origin, &m.Maintainer,
+			&m.BuildTime, &m.Commit, &m.ProviderPriority,
+			&depends, &provides, &installIf,
+		); err != nil {
+			return nil, err
+		}
+		m.Depends = strings.Fields(depends)
+		m.Provides = strings.Fields(provides)
+		m.InstallIf = strings.Fields(installIf)
+		result = append(result, m)
+	}
+	return result, rows.Err()
+}

internal/database/artifacts.go

@@ -0,0 +1,188 @@
+package database
+
+import (
+	"context"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func (db *DB) UpsertBlob(ctx context.Context, contentHash, s3Key string, sizeBytes int64, contentType string) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO blobs (content_hash, s3_key, size_bytes, content_type)
+		VALUES ($1, $2, $3, $4)
+		ON CONFLICT (content_hash) DO NOTHING
+	`, contentHash, s3Key, sizeBytes, contentType)
+	return err
+}
+
+func (db *DB) UpsertArtifact(ctx context.Context, remoteName, path, contentHash, upstreamETag string) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO artifacts (remote_name, path, content_hash, upstream_etag)
+		VALUES ($1, $2, $3, $4)
+		ON CONFLICT (remote_name, path) DO UPDATE SET
+			content_hash = EXCLUDED.content_hash,
+			upstream_etag = EXCLUDED.upstream_etag,
+			last_fetched_at = NOW(),
+			fetch_count = artifacts.fetch_count + 1
+	`, remoteName, path, contentHash, upstreamETag)
+	return err
+}
+
+func (db *DB) GetArtifact(ctx context.Context, remoteName, path string) (*models.Artifact, error) {
+	row := db.Pool.QueryRow(ctx, `
+		SELECT a.id, a.remote_name, a.path, a.content_hash, a.upstream_etag,
+			a.upstream_last_modified, a.first_seen_at, a.last_fetched_at,
+			a.last_accessed_at, a.fetch_count, a.access_count,
+			b.size_bytes, b.content_type
+		FROM artifacts a
+		JOIN blobs b ON a.content_hash = b.content_hash
+		WHERE a.remote_name = $1 AND a.path = $2
+	`, remoteName, path)
+
+	var a models.Artifact
+	err := row.Scan(
+		&a.ID, &a.RemoteName, &a.Path, &a.ContentHash, &a.UpstreamETag,
+		&a.UpstreamLastModified, &a.FirstSeenAt, &a.LastFetchedAt,
+		&a.LastAccessedAt, &a.FetchCount, &a.AccessCount,
+		&a.SizeBytes, &a.ContentType,
+	)
+	if err != nil {
+		return nil, err
+	}
+	return &a, nil
+}
+
+func (db *DB) TouchArtifactAccess(ctx context.Context, remoteName, path string) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE artifacts SET
+			last_accessed_at = NOW(),
+			access_count = access_count + 1
+		WHERE remote_name = $1 AND path = $2
+	`, remoteName, path)
+	return err
+}
+
+func (db *DB) ListArtifacts(ctx context.Context, remoteName string, limit, offset int) ([]models.Artifact, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT a.id, a.remote_name, a.path, a.content_hash, a.upstream_etag,
+			a.upstream_last_modified, a.first_seen_at, a.last_fetched_at,
+			a.last_accessed_at, a.fetch_count, a.access_count,
+			b.size_bytes, b.content_type
+		FROM artifacts a
+		JOIN blobs b ON a.content_hash = b.content_hash
+		WHERE a.remote_name = $1
+		ORDER BY a.path
+		LIMIT $2 OFFSET $3
+	`, remoteName, limit, offset)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var artifacts []models.Artifact
+	for rows.Next() {
+		var a models.Artifact
+		if err := rows.Scan(
+			&a.ID, &a.RemoteName, &a.Path, &a.ContentHash, &a.UpstreamETag,
+			&a.UpstreamLastModified, &a.FirstSeenAt, &a.LastFetchedAt,
+			&a.LastAccessedAt, &a.FetchCount, &a.AccessCount,
+			&a.SizeBytes, &a.ContentType,
+		); err != nil {
+			return nil, err
+		}
+		artifacts = append(artifacts, a)
+	}
+	return artifacts, rows.Err()
+}
+
+func (db *DB) DeleteArtifact(ctx context.Context, remoteName, path string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM artifacts WHERE remote_name = $1 AND path = $2`, remoteName, path)
+	return err
+}
+
+func (db *DB) InsertAccessLog(ctx context.Context, remoteName, path string, cacheHit bool, sizeBytes int64, upstreamMS int, clientIP string) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO access_log (remote_name, path, cache_hit, size_bytes, upstream_ms, client_ip)
+		VALUES ($1, $2, $3, $4, $5, $6)
+	`, remoteName, path, cacheHit, sizeBytes, upstreamMS, clientIP)
+	return err
+}
+
+// AccessLogEntry is one buffered access-log record.
+type AccessLogEntry struct {
+	RemoteName string
+	Path       string
+	CacheHit   bool
+	SizeBytes  int64
+	UpstreamMS int
+	ClientIP   string
+}
+
+// InsertAccessLogBatch bulk-inserts access-log rows with a single COPY.
+func (db *DB) InsertAccessLogBatch(ctx context.Context, entries []AccessLogEntry) error {
+	if len(entries) == 0 {
+		return nil
+	}
+	rows := make([][]any, len(entries))
+	for i, e := range entries {
+		rows[i] = []any{e.RemoteName, e.Path, e.CacheHit, e.SizeBytes, e.UpstreamMS, e.ClientIP}
+	}
+	_, err := db.Pool.CopyFrom(ctx,
+		pgx.Identifier{"access_log"},
+		[]string{"remote_name", "path", "cache_hit", "size_bytes", "upstream_ms", "client_ip"},
+		pgx.CopyFromRows(rows),
+	)
+	return err
+}
+
+// FindOrphanedBlobs returns blobs no longer referenced by any artifact or
+// local file, restricted to those created before now()-minAge. The age cutoff
+// is a grace period that avoids a TOCTOU race with in-flight dedup uploads,
+// which insert the blob row before the referencing artifact/local_files row.
+func (db *DB) FindOrphanedBlobs(ctx context.Context, minAge time.Duration) ([]models.Blob, error) {
+	cutoff := time.Now().Add(-minAge)
+	rows, err := db.Pool.Query(ctx, `
+		SELECT b.content_hash, b.s3_key, b.size_bytes, b.content_type, b.created_at
+		FROM blobs b
+		WHERE b.created_at < $1
+		  AND b.content_hash NOT IN (
+			SELECT content_hash FROM artifacts
+			UNION
+			SELECT content_hash FROM local_files
+		)
+	`, cutoff)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var blobs []models.Blob
+	for rows.Next() {
+		var b models.Blob
+		if err := rows.Scan(&b.ContentHash, &b.S3Key, &b.SizeBytes, &b.ContentType, &b.CreatedAt); err != nil {
+			return nil, err
+		}
+		blobs = append(blobs, b)
+	}
+	return blobs, rows.Err()
+}
+
+func (db *DB) DeleteBlob(ctx context.Context, contentHash string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM blobs WHERE content_hash = $1`, contentHash)
+	return err
+}
+
+func (db *DB) DeleteColdArtifacts(ctx context.Context, remoteName string, olderThan time.Duration) (int64, error) {
+	cutoff := time.Now().Add(-olderThan)
+	tag, err := db.Pool.Exec(ctx, `
+		DELETE FROM artifacts
+		WHERE remote_name = $1 AND last_accessed_at < $2
+	`, remoteName, cutoff)
+	if err != nil {
+		return 0, err
+	}
+	return tag.RowsAffected(), nil
+}

internal/database/database_test.go

@@ -0,0 +1,381 @@
+package database
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+var (
+	testDB  *DB
+	testDSN string
+)
+
+func TestMain(m *testing.M) {
+	c := context.Background()
+	dsn, terminate, err := testsupport.StartPostgres(c)
+	if err != nil {
+		// Docker unavailable: run anyway so tests self-skip via requireDB.
+		os.Exit(m.Run())
+	}
+	testDSN = dsn
+	db, err := New(dsn)
+	if err != nil {
+		terminate()
+		panic(err)
+	}
+	testDB = db
+
+	code := m.Run()
+
+	db.Close()
+	terminate()
+	// Return normally on success so the coverage profile is flushed; os.Exit
+	// would truncate it.
+	if code != 0 {
+		os.Exit(code)
+	}
+}
+
+func requireDB(t *testing.T) {
+	t.Helper()
+	if testDB == nil {
+		t.Skip("Docker unavailable; skipping database integration test")
+	}
+}
+
+func ctx() context.Context { return context.Background() }
+
+func seedRemote(t *testing.T, name string) {
+	t.Helper()
+	if err := testDB.CreateRemote(ctx(), &models.Remote{
+		Name: name, PackageType: models.PackageGeneric, RepoType: models.RepoTypeRemote,
+		BaseURL: "https://example.com", MutableTTL: 3600,
+	}); err != nil {
+		t.Fatalf("seed remote: %v", err)
+	}
+}
+
+// seedBlob inserts a blob and returns its full content hash (sha256:<hash>),
+// matching the reference convention used by artifacts and local files.
+func seedBlob(t *testing.T, hash string) string {
+	t.Helper()
+	full := "sha256:" + hash
+	if err := testDB.UpsertBlob(ctx(), full, "blobs/sha256/"+hash, 10, "application/octet-stream"); err != nil {
+		t.Fatalf("seed blob: %v", err)
+	}
+	return full
+}
+
+func TestRemotesCRUD(t *testing.T) {
+	requireDB(t)
+	seedRemote(t, "r-crud")
+	got, err := testDB.GetRemote(ctx(), "r-crud")
+	if err != nil || got.BaseURL != "https://example.com" {
+		t.Fatalf("get: %v %v", got, err)
+	}
+	got.BaseURL = "https://updated.example.com"
+	if err := testDB.UpdateRemote(ctx(), got); err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	got, _ = testDB.GetRemote(ctx(), "r-crud")
+	if got.BaseURL != "https://updated.example.com" {
+		t.Errorf("update not applied: %v", got.BaseURL)
+	}
+	list, err := testDB.ListRemotes(ctx())
+	if err != nil || len(list) == 0 {
+		t.Fatalf("list: %v %v", len(list), err)
+	}
+	if err := testDB.DeleteRemote(ctx(), "r-crud"); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	if _, err := testDB.GetRemote(ctx(), "r-crud"); err == nil {
+		t.Error("expected error after delete")
+	}
+}
+
+func TestRemoteMirrorlistRoundTrip(t *testing.T) {
+	requireDB(t)
+	mirrors := []string{"https://b.example", "https://c.example"}
+	if err := testDB.CreateRemote(ctx(), &models.Remote{
+		Name: "r-mirror", PackageType: models.PackageRPM, RepoType: models.RepoTypeRemote,
+		BaseURL: "https://a.example", Mirrorlist: mirrors, MutableTTL: 3600,
+	}); err != nil {
+		t.Fatalf("create mirrorlist remote: %v", err)
+	}
+	defer testDB.DeleteRemote(ctx(), "r-mirror")
+
+	got, err := testDB.GetRemote(ctx(), "r-mirror")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got.BaseURL != "https://a.example" {
+		t.Fatalf("BaseURL = %q, want https://a.example", got.BaseURL)
+	}
+	if len(got.Mirrorlist) != 2 || got.Mirrorlist[0] != mirrors[0] || got.Mirrorlist[1] != mirrors[1] {
+		t.Fatalf("Mirrorlist round-trip = %v, want %v", got.Mirrorlist, mirrors)
+	}
+	// An unset strategy is stored as the round_robin default.
+	if got.MirrorStrategy != models.MirrorStrategyRoundRobin {
+		t.Fatalf("MirrorStrategy default = %q, want %q", got.MirrorStrategy, models.MirrorStrategyRoundRobin)
+	}
+
+	// Updating to least_conn round-trips.
+	got.MirrorStrategy = models.MirrorStrategyLeastConn
+	if err := testDB.UpdateRemote(ctx(), got); err != nil {
+		t.Fatalf("update to least_conn: %v", err)
+	}
+	got, _ = testDB.GetRemote(ctx(), "r-mirror")
+	if got.MirrorStrategy != models.MirrorStrategyLeastConn {
+		t.Fatalf("MirrorStrategy after update = %q, want least_conn", got.MirrorStrategy)
+	}
+
+	// Clearing the mirrorlist on update persists an empty list.
+	got.Mirrorlist = nil
+	if err := testDB.UpdateRemote(ctx(), got); err != nil {
+		t.Fatalf("update clearing mirrorlist: %v", err)
+	}
+	got, _ = testDB.GetRemote(ctx(), "r-mirror")
+	if len(got.Mirrorlist) != 0 {
+		t.Fatalf("mirrorlist after clear = %v, want empty", got.Mirrorlist)
+	}
+}
+
+func TestArtifactsAndBlobs(t *testing.T) {
+	requireDB(t)
+	seedRemote(t, "r-art")
+	seedBlob(t, "aaaa")
+	hash := "sha256:aaaa"
+	if err := testDB.UpsertBlob(ctx(), hash, "blobs/sha256/aaaa", 10, "text/plain"); err != nil {
+		t.Fatal(err)
+	}
+	if err := testDB.UpsertArtifact(ctx(), "r-art", "path/a.txt", hash, "etag1"); err != nil {
+		t.Fatal(err)
+	}
+	// Upsert again to exercise the ON CONFLICT update branch.
+	if err := testDB.UpsertArtifact(ctx(), "r-art", "path/a.txt", hash, "etag2"); err != nil {
+		t.Fatal(err)
+	}
+	art, err := testDB.GetArtifact(ctx(), "r-art", "path/a.txt")
+	if err != nil || art.ContentHash != hash {
+		t.Fatalf("get artifact: %v %v", art, err)
+	}
+	if err := testDB.TouchArtifactAccess(ctx(), "r-art", "path/a.txt"); err != nil {
+		t.Fatal(err)
+	}
+	arts, err := testDB.ListArtifacts(ctx(), "r-art", 10, 0)
+	if err != nil || len(arts) != 1 {
+		t.Fatalf("list artifacts: %v %v", len(arts), err)
+	}
+	if err := testDB.InsertAccessLog(ctx(), "r-art", "path/a.txt", true, 10, 5, "1.2.3.4"); err != nil {
+		t.Fatal(err)
+	}
+	if err := testDB.InsertAccessLogBatch(ctx(), []AccessLogEntry{
+		{RemoteName: "r-art", Path: "b", CacheHit: false, SizeBytes: 20, UpstreamMS: 3},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := testDB.InsertAccessLogBatch(ctx(), nil); err != nil {
+		t.Fatalf("empty batch should be a no-op: %v", err)
+	}
+	if err := testDB.DeleteArtifact(ctx(), "r-art", "path/a.txt"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestOrphanAndColdCleanup(t *testing.T) {
+	requireDB(t)
+	seedBlob(t, "orphanhash")
+	// A blob with no artifact/local_file reference is orphaned, but only past
+	// the grace period.
+	if got, _ := testDB.FindOrphanedBlobs(ctx(), time.Hour); containsHash(got, "sha256:orphanhash") {
+		t.Error("fresh orphan should be excluded by grace period")
+	}
+	orphans, err := testDB.FindOrphanedBlobs(ctx(), -time.Hour) // cutoff in the future => include fresh
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !containsHash(orphans, "sha256:orphanhash") {
+		t.Error("expected orphan to be found with zero grace")
+	}
+	if err := testDB.DeleteBlob(ctx(), "sha256:orphanhash"); err != nil {
+		t.Fatal(err)
+	}
+
+	seedRemote(t, "r-cold")
+	seedBlob(t, "coldhash")
+	testDB.UpsertArtifact(ctx(), "r-cold", "cold.txt", "sha256:coldhash", "")
+	n, err := testDB.DeleteColdArtifacts(ctx(), "r-cold", -time.Hour) // negative => everything is "cold"
+	if err != nil || n < 1 {
+		t.Fatalf("delete cold: n=%d err=%v", n, err)
+	}
+}
+
+func containsHash(blobs []models.Blob, hash string) bool {
+	for _, b := range blobs {
+		if b.ContentHash == hash {
+			return true
+		}
+	}
+	return false
+}
+
+func TestLocalFiles(t *testing.T) {
+	requireDB(t)
+	seedRemote(t, "r-local")
+	seedBlob(t, "localhash")
+	hash := "sha256:localhash"
+	if err := testDB.CreateLocalFile(ctx(), "r-local", "foo/foo-1.0.whl", hash); err != nil {
+		t.Fatal(err)
+	}
+	// Duplicate create must be rejected.
+	if err := testDB.CreateLocalFile(ctx(), "r-local", "foo/foo-1.0.whl", hash); err == nil {
+		t.Error("expected duplicate local file error")
+	}
+	f, err := testDB.GetLocalFile(ctx(), "r-local", "foo/foo-1.0.whl")
+	if err != nil || f == nil {
+		t.Fatalf("get local file: %v %v", f, err)
+	}
+	if files, err := testDB.ListLocalFiles(ctx(), "r-local", 10, 0); err != nil || len(files) != 1 {
+		t.Fatalf("list: %v %v", len(files), err)
+	}
+	if files, err := testDB.ListLocalFilesByPrefix(ctx(), "r-local", "foo/"); err != nil || len(files) != 1 {
+		t.Fatalf("list by prefix: %v %v", len(files), err)
+	}
+	if entries, err := testDB.ListFilesByPrefix(ctx(), "r-local", "foo/"); err != nil || len(entries) != 1 {
+		t.Fatalf("provider list by prefix: %v %v", len(entries), err)
+	}
+	if pkgs, err := testDB.ListLocalFilePackages(ctx(), "r-local"); err != nil || len(pkgs) == 0 {
+		t.Fatalf("list packages: %v %v", pkgs, err)
+	}
+	if pkgs, err := testDB.ListPackages(ctx(), "r-local"); err != nil || len(pkgs) == 0 {
+		t.Fatalf("provider list packages: %v %v", pkgs, err)
+	}
+	if err := testDB.DeleteLocalFile(ctx(), "r-local", "foo/foo-1.0.whl"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestVirtualsCRUD(t *testing.T) {
+	requireDB(t)
+	if err := testDB.CreateVirtual(ctx(), &models.Virtual{
+		Name: "v-crud", PackageType: models.PackageHelm, Members: []string{"a", "b"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	v, err := testDB.GetVirtual(ctx(), "v-crud")
+	if err != nil || len(v.Members) != 2 {
+		t.Fatalf("get virtual: %v %v", v, err)
+	}
+	v.Members = []string{"a"}
+	if err := testDB.UpdateVirtual(ctx(), v); err != nil {
+		t.Fatal(err)
+	}
+	if vs, err := testDB.ListVirtuals(ctx()); err != nil || len(vs) == 0 {
+		t.Fatalf("list virtuals: %v %v", len(vs), err)
+	}
+	if err := testDB.DeleteVirtual(ctx(), "v-crud"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestStats(t *testing.T) {
+	requireDB(t)
+	seedRemote(t, "r-stats")
+	seedBlob(t, "statshash")
+	testDB.UpsertArtifact(ctx(), "r-stats", "s.txt", "sha256:statshash", "")
+	testDB.InsertAccessLog(ctx(), "r-stats", "s.txt", true, 100, 2, "")
+
+	if _, err := testDB.GetOverviewStats(ctx()); err != nil {
+		t.Fatalf("overview: %v", err)
+	}
+	if _, err := testDB.GetTopRemotes(ctx(), 5); err != nil {
+		t.Fatalf("top remotes: %v", err)
+	}
+	if _, err := testDB.GetTopFilesByHits(ctx(), 5); err != nil {
+		t.Fatalf("top files by hits: %v", err)
+	}
+	if _, err := testDB.GetTopFilesByBandwidth(ctx(), 5); err != nil {
+		t.Fatalf("top files by bandwidth: %v", err)
+	}
+}
+
+func TestDatabaseErrorPaths(t *testing.T) {
+	requireDB(t)
+	bad, err := New(testDSN)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bad.Close() // every query now fails
+	ctx := context.Background()
+
+	if _, err := bad.ListRemotes(ctx); err == nil {
+		t.Error("ListRemotes should error on closed db")
+	}
+	if _, err := bad.ListVirtuals(ctx); err == nil {
+		t.Error("ListVirtuals should error")
+	}
+	if _, err := bad.ListArtifacts(ctx, "r", 10, 0); err == nil {
+		t.Error("ListArtifacts should error")
+	}
+	if _, err := bad.ListLocalFiles(ctx, "r", 10, 0); err == nil {
+		t.Error("ListLocalFiles should error")
+	}
+	if _, err := bad.ListLocalFilesByPrefix(ctx, "r", "p"); err == nil {
+		t.Error("ListLocalFilesByPrefix should error")
+	}
+	if _, err := bad.ListLocalFilePackages(ctx, "r"); err == nil {
+		t.Error("ListLocalFilePackages should error")
+	}
+	if _, err := bad.ListFilesByPrefix(ctx, "r", "p"); err == nil {
+		t.Error("ListFilesByPrefix should error")
+	}
+	if _, err := bad.ListPackages(ctx, "r"); err == nil {
+		t.Error("ListPackages should error")
+	}
+	if _, err := bad.FindOrphanedBlobs(ctx, 0); err == nil {
+		t.Error("FindOrphanedBlobs should error")
+	}
+	if _, err := bad.GetOverviewStats(ctx); err == nil {
+		t.Error("GetOverviewStats should error")
+	}
+	if _, err := bad.GetTopRemotes(ctx, 5); err == nil {
+		t.Error("GetTopRemotes should error")
+	}
+	if _, err := bad.GetTopFilesByHits(ctx, 5); err == nil {
+		t.Error("GetTopFilesByHits should error")
+	}
+	if _, err := bad.GetTopFilesByBandwidth(ctx, 5); err == nil {
+		t.Error("GetTopFilesByBandwidth should error")
+	}
+	if _, err := bad.ListRPMMetadataEntries(ctx, "r"); err == nil {
+		t.Error("ListRPMMetadataEntries should error")
+	}
+}
+
+func TestRPMMetadata(t *testing.T) {
+	requireDB(t)
+	seedRemote(t, "r-rpm")
+	meta := &provider.RPMMetadata{
+		RepoName: "r-rpm", FilePath: "Packages/x.rpm", ContentHash: "sha256:rpm",
+		Name: "x", Version: "1.0", Release: "1", Arch: "noarch",
+		Requires: []provider.RPMDep{{Name: "libc"}},
+		Provides: []provider.RPMDep{{Name: "x"}},
+		Files:    []provider.RPMFile{},
+	}
+	if err := testDB.InsertRPMMetadata(ctx(), meta); err != nil {
+		t.Fatal(err)
+	}
+	entries, err := testDB.ListRPMMetadataEntries(ctx(), "r-rpm")
+	if err != nil || len(entries) != 1 {
+		t.Fatalf("list rpm entries: %v %v", len(entries), err)
+	}
+	if rows, err := testDB.ListRPMMetadata(ctx(), "r-rpm"); err != nil || len(rows) != 1 {
+		t.Fatalf("list rpm rows: %v %v", len(rows), err)
+	}
+}

internal/database/deb_github_sync.go

@@ -0,0 +1,70 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// ListGitHubDebRemotes returns every github_deb remote so the syncer can sweep
+// them on each poll tick.
+func (db *DB) ListGitHubDebRemotes(ctx context.Context) ([]models.Remote, error) {
+	rows, err := db.Pool.Query(ctx, `SELECT `+remoteCols+` FROM remotes WHERE package_type = $1 ORDER BY name`, models.PackageGitHubDeb)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var remotes []models.Remote
+	for rows.Next() {
+		var r models.Remote
+		if err := scanRemote(rows, &r); err != nil {
+			return nil, err
+		}
+		remotes = append(remotes, r)
+	}
+	return remotes, rows.Err()
+}
+
+// ClaimGitHubDebSyncLease atomically claims the per-remote sync lease. It
+// succeeds only when the remote is due (never synced, or synced longer than
+// freshness ago) and no live lease is held by another replica. A zero freshness
+// (prime scans) ignores the recency gate. The returned etag is the stored
+// releases-list ETag, shared across replicas.
+func (db *DB) ClaimGitHubDebSyncLease(ctx context.Context, remoteName, owner string, freshness, lease time.Duration) (bool, string, error) {
+	row := db.Pool.QueryRow(ctx, `
+		INSERT INTO github_deb_sync_state AS s (remote_name, sync_lease_owner, sync_lease_expires)
+		VALUES ($1, $2, now() + make_interval(secs => $4))
+		ON CONFLICT (remote_name) DO UPDATE
+			SET sync_lease_owner   = $2,
+			    sync_lease_expires = now() + make_interval(secs => $4)
+			WHERE (s.last_synced_at IS NULL OR s.last_synced_at < now() - make_interval(secs => $3))
+			  AND (s.sync_lease_expires IS NULL OR s.sync_lease_expires < now())
+		RETURNING s.etag
+	`, remoteName, owner, freshness.Seconds(), lease.Seconds())
+
+	var etag string
+	if err := row.Scan(&etag); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return false, "", nil
+		}
+		return false, "", err
+	}
+	return true, etag, nil
+}
+
+// ReleaseGitHubDebSyncLease records the completed scan and frees the lease. Only
+// the owning replica may release; last_synced_at advances so the next poll waits
+// a full freshness window, and etag is persisted for the next conditional request.
+func (db *DB) ReleaseGitHubDebSyncLease(ctx context.Context, remoteName, owner, etag string, syncedAt time.Time) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE github_deb_sync_state
+		   SET last_synced_at = $3, etag = $4, sync_lease_owner = '', sync_lease_expires = NULL
+		 WHERE remote_name = $1 AND sync_lease_owner = $2
+	`, remoteName, owner, syncedAt, etag)
+	return err
+}

internal/database/deb_github_sync_test.go

@@ -0,0 +1,90 @@
+package database
+
+import (
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func seedGitHubDebRemote(t *testing.T, name string) {
+	t.Helper()
+	if err := testDB.CreateRemote(ctx(), &models.Remote{
+		Name: name, PackageType: models.PackageGitHubDeb, RepoType: models.RepoTypeRemote,
+		BaseURL: "https://api.github.com/repos/acme/tools", ReleasesRemote: "github", MutableTTL: 3600,
+	}); err != nil {
+		t.Fatalf("seed github_deb remote: %v", err)
+	}
+}
+
+// TestGitHubDebSyncLease exercises the real SQL: exactly one replica may hold the
+// lease, the recency window blocks a too-soon periodic re-claim, and a prime
+// (freshness 0) bypasses recency but still respects a live lease.
+func TestGitHubDebSyncLease(t *testing.T) {
+	requireDB(t)
+	name := "ghdeb-lease-" + time.Now().Format("150405.000000")
+	seedGitHubDebRemote(t, name)
+
+	const lease = 15 * time.Minute
+	freshness := time.Hour
+
+	claimed, etag, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-1", freshness, lease)
+	if err != nil || !claimed {
+		t.Fatalf("replica-1 first claim: claimed=%v err=%v", claimed, err)
+	}
+	if etag != "" {
+		t.Fatalf("initial etag should be empty, got %q", etag)
+	}
+
+	claimed2, _, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-2", freshness, lease)
+	if err != nil {
+		t.Fatalf("replica-2 claim err: %v", err)
+	}
+	if claimed2 {
+		t.Fatal("replica-2 claimed while replica-1 holds the lease")
+	}
+
+	if err := testDB.ReleaseGitHubDebSyncLease(ctx(), name, "replica-1", `"etag-1"`, time.Now()); err != nil {
+		t.Fatalf("release: %v", err)
+	}
+
+	claimed3, _, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-2", freshness, lease)
+	if err != nil {
+		t.Fatalf("replica-2 recency claim err: %v", err)
+	}
+	if claimed3 {
+		t.Fatal("periodic claim succeeded inside the freshness window")
+	}
+
+	claimed4, etag4, err := testDB.ClaimGitHubDebSyncLease(ctx(), name, "replica-2", 0, lease)
+	if err != nil || !claimed4 {
+		t.Fatalf("prime claim: claimed=%v err=%v", claimed4, err)
+	}
+	if etag4 != `"etag-1"` {
+		t.Fatalf("prime claim etag = %q, want persisted \"etag-1\"", etag4)
+	}
+}
+
+func TestListGitHubDebRemotes(t *testing.T) {
+	requireDB(t)
+	name := "ghdeb-list-" + time.Now().Format("150405.000000")
+	seedGitHubDebRemote(t, name)
+	seedRemote(t, "generic-"+time.Now().Format("150405.000000"))
+
+	remotes, err := testDB.ListGitHubDebRemotes(ctx())
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	found := false
+	for _, r := range remotes {
+		if r.PackageType != models.PackageGitHubDeb {
+			t.Fatalf("non-github_deb remote returned: %s (%s)", r.Name, r.PackageType)
+		}
+		if r.Name == name {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("seeded remote %q not returned", name)
+	}
+}

internal/database/deb_metadata.go

@@ -0,0 +1,57 @@
+package database
+
+import (
+	"context"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+func (db *DB) InsertDebMetadata(ctx context.Context, meta *provider.DebMetadata) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO deb_metadata (
+			repo_name, file_path, content_hash,
+			name, version, architecture, control,
+			size, md5, sha256
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
+		ON CONFLICT (repo_name, file_path) DO NOTHING
+	`,
+		meta.RepoName, meta.FilePath, meta.ContentHash,
+		meta.Name, meta.Version, meta.Architecture, meta.Control,
+		meta.Size, meta.MD5, meta.SHA256,
+	)
+	return err
+}
+
+func (db *DB) DeleteDebMetadata(ctx context.Context, repoName, filePath string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM deb_metadata WHERE repo_name = $1 AND file_path = $2`, repoName, filePath)
+	return err
+}
+
+func (db *DB) ListDebMetadataEntries(ctx context.Context, repoName string) ([]provider.DebMetadata, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT repo_name, file_path, content_hash,
+			name, version, architecture, control,
+			size, md5, sha256, created_at
+		FROM deb_metadata
+		WHERE repo_name = $1
+		ORDER BY name, version, architecture, file_path
+	`, repoName)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []provider.DebMetadata
+	for rows.Next() {
+		var m provider.DebMetadata
+		if err := rows.Scan(
+			&m.RepoName, &m.FilePath, &m.ContentHash,
+			&m.Name, &m.Version, &m.Architecture, &m.Control,
+			&m.Size, &m.MD5, &m.SHA256, &m.CreatedAt,
+		); err != nil {
+			return nil, err
+		}
+		result = append(result, m)
+	}
+	return result, rows.Err()
+}

internal/database/github_sync.go

@@ -0,0 +1,73 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+// ListGitHubRPMRemotes returns every github_rpm remote so the syncer can sweep
+// them on each poll tick.
+func (db *DB) ListGitHubRPMRemotes(ctx context.Context) ([]models.Remote, error) {
+	rows, err := db.Pool.Query(ctx, `SELECT `+remoteCols+` FROM remotes WHERE package_type = $1 ORDER BY name`, models.PackageGitHubRPM)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var remotes []models.Remote
+	for rows.Next() {
+		var r models.Remote
+		if err := scanRemote(rows, &r); err != nil {
+			return nil, err
+		}
+		remotes = append(remotes, r)
+	}
+	return remotes, rows.Err()
+}
+
+// ClaimGitHubSyncLease atomically claims the per-remote sync lease. It succeeds
+// (claimed=true) only when the remote is due — never synced, or synced longer
+// than freshness ago — and no live lease is held by another replica. This bounds
+// total GitHub load to roughly one scan per freshness window regardless of how
+// many replicas poll. The returned etag is the stored releases-list ETag, shared
+// across replicas so a conditional request can short-circuit an unchanged repo.
+// A zero freshness (used for prime scans) ignores the recency gate and claims
+// whenever no live lease is held.
+func (db *DB) ClaimGitHubSyncLease(ctx context.Context, remoteName, owner string, freshness, lease time.Duration) (bool, string, error) {
+	row := db.Pool.QueryRow(ctx, `
+		INSERT INTO github_rpm_sync_state AS s (remote_name, sync_lease_owner, sync_lease_expires)
+		VALUES ($1, $2, now() + make_interval(secs => $4))
+		ON CONFLICT (remote_name) DO UPDATE
+			SET sync_lease_owner   = $2,
+			    sync_lease_expires = now() + make_interval(secs => $4)
+			WHERE (s.last_synced_at IS NULL OR s.last_synced_at < now() - make_interval(secs => $3))
+			  AND (s.sync_lease_expires IS NULL OR s.sync_lease_expires < now())
+		RETURNING s.etag
+	`, remoteName, owner, freshness.Seconds(), lease.Seconds())
+
+	var etag string
+	if err := row.Scan(&etag); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return false, "", nil
+		}
+		return false, "", err
+	}
+	return true, etag, nil
+}
+
+// ReleaseGitHubSyncLease records the completed scan and frees the lease. Only the
+// owning replica may release; last_synced_at advances so the next poll waits a
+// full freshness window, and etag is persisted for the next conditional request.
+func (db *DB) ReleaseGitHubSyncLease(ctx context.Context, remoteName, owner, etag string, syncedAt time.Time) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE github_rpm_sync_state
+		   SET last_synced_at = $3, etag = $4, sync_lease_owner = '', sync_lease_expires = NULL
+		 WHERE remote_name = $1 AND sync_lease_owner = $2
+	`, remoteName, owner, syncedAt, etag)
+	return err
+}

internal/database/github_sync_test.go

@@ -0,0 +1,95 @@
+package database
+
+import (
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func seedGitHubRPMRemote(t *testing.T, name string) {
+	t.Helper()
+	if err := testDB.CreateRemote(ctx(), &models.Remote{
+		Name: name, PackageType: models.PackageGitHubRPM, RepoType: models.RepoTypeRemote,
+		BaseURL: "https://api.github.com/repos/acme/tools", ReleasesRemote: "github", MutableTTL: 3600,
+	}); err != nil {
+		t.Fatalf("seed github_rpm remote: %v", err)
+	}
+}
+
+// TestGitHubSyncLease exercises the real SQL: exactly one replica may hold the
+// lease, the recency window blocks a too-soon periodic re-claim, and a prime
+// (freshness 0) bypasses recency but still respects a live lease.
+func TestGitHubSyncLease(t *testing.T) {
+	requireDB(t)
+	name := "gh-lease-" + time.Now().Format("150405.000000")
+	seedGitHubRPMRemote(t, name)
+
+	const lease = 15 * time.Minute
+	freshness := time.Hour
+
+	// First claim on a never-synced remote wins; etag starts empty.
+	claimed, etag, err := testDB.ClaimGitHubSyncLease(ctx(), name, "replica-1", freshness, lease)
+	if err != nil || !claimed {
+		t.Fatalf("replica-1 first claim: claimed=%v err=%v", claimed, err)
+	}
+	if etag != "" {
+		t.Fatalf("initial etag should be empty, got %q", etag)
+	}
+
+	// A second replica cannot claim while the lease is held.
+	claimed2, _, err := testDB.ClaimGitHubSyncLease(ctx(), name, "replica-2", freshness, lease)
+	if err != nil {
+		t.Fatalf("replica-2 claim err: %v", err)
+	}
+	if claimed2 {
+		t.Fatal("replica-2 claimed while replica-1 holds the lease")
+	}
+
+	// Replica 1 finishes: record the sync and persist an etag.
+	if err := testDB.ReleaseGitHubSyncLease(ctx(), name, "replica-1", `"etag-1"`, time.Now()); err != nil {
+		t.Fatalf("release: %v", err)
+	}
+
+	// A periodic re-claim inside the freshness window is blocked by recency.
+	claimed3, _, err := testDB.ClaimGitHubSyncLease(ctx(), name, "replica-2", freshness, lease)
+	if err != nil {
+		t.Fatalf("replica-2 recency claim err: %v", err)
+	}
+	if claimed3 {
+		t.Fatal("periodic claim succeeded inside the freshness window")
+	}
+
+	// A prime (freshness 0) bypasses recency and reads the persisted etag.
+	claimed4, etag4, err := testDB.ClaimGitHubSyncLease(ctx(), name, "replica-2", 0, lease)
+	if err != nil || !claimed4 {
+		t.Fatalf("prime claim: claimed=%v err=%v", claimed4, err)
+	}
+	if etag4 != `"etag-1"` {
+		t.Fatalf("prime claim etag = %q, want persisted \"etag-1\"", etag4)
+	}
+}
+
+func TestListGitHubRPMRemotes(t *testing.T) {
+	requireDB(t)
+	name := "gh-list-" + time.Now().Format("150405.000000")
+	seedGitHubRPMRemote(t, name)
+	seedRemote(t, "generic-"+time.Now().Format("150405.000000"))
+
+	remotes, err := testDB.ListGitHubRPMRemotes(ctx())
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	found := false
+	for _, r := range remotes {
+		if r.PackageType != models.PackageGitHubRPM {
+			t.Fatalf("non-github_rpm remote returned: %s (%s)", r.Name, r.PackageType)
+		}
+		if r.Name == name {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("seeded remote %q not returned", name)
+	}
+}

internal/database/local_files.go

@@ -0,0 +1,195 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+type LocalFile struct {
+	ID          int64     `json:"id"`
+	RepoName    string    `json:"repo_name"`
+	FilePath    string    `json:"file_path"`
+	ContentHash string    `json:"content_hash"`
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+var ErrAlreadyExists = fmt.Errorf("file already exists")
+
+func (db *DB) CreateLocalFile(ctx context.Context, repoName, filePath, contentHash string) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO local_files (repo_name, file_path, content_hash)
+		VALUES ($1, $2, $3)
+	`, repoName, filePath, contentHash)
+	if err != nil {
+		var pgErr *pgconn.PgError
+		if errors.As(err, &pgErr) && pgErr.Code == "23505" {
+			return ErrAlreadyExists
+		}
+		return err
+	}
+	return nil
+}
+
+// UpsertLocalFile inserts a local file or repoints an existing path at a new
+// blob. Unlike CreateLocalFile it never errors on a duplicate path — it is for
+// mutable references such as Docker tags, where re-pushing a tag must move it to
+// the newly-pushed manifest rather than being rejected as an overwrite.
+func (db *DB) UpsertLocalFile(ctx context.Context, repoName, filePath, contentHash string) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO local_files (repo_name, file_path, content_hash)
+		VALUES ($1, $2, $3)
+		ON CONFLICT (repo_name, file_path)
+		DO UPDATE SET content_hash = EXCLUDED.content_hash, created_at = NOW()
+	`, repoName, filePath, contentHash)
+	return err
+}
+
+func (db *DB) GetLocalFile(ctx context.Context, repoName, filePath string) (*LocalFile, error) {
+	row := db.Pool.QueryRow(ctx, `
+		SELECT id, repo_name, file_path, content_hash, created_at
+		FROM local_files
+		WHERE repo_name = $1 AND file_path = $2
+	`, repoName, filePath)
+
+	var f LocalFile
+	if err := row.Scan(&f.ID, &f.RepoName, &f.FilePath, &f.ContentHash, &f.CreatedAt); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return &f, nil
+}
+
+func (db *DB) ListLocalFiles(ctx context.Context, repoName string, limit, offset int) ([]LocalFile, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT id, repo_name, file_path, content_hash, created_at
+		FROM local_files
+		WHERE repo_name = $1
+		ORDER BY file_path
+		LIMIT $2 OFFSET $3
+	`, repoName, limit, offset)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var files []LocalFile
+	for rows.Next() {
+		var f LocalFile
+		if err := rows.Scan(&f.ID, &f.RepoName, &f.FilePath, &f.ContentHash, &f.CreatedAt); err != nil {
+			return nil, err
+		}
+		files = append(files, f)
+	}
+	return files, rows.Err()
+}
+
+// ListLocalArtifacts returns a repo's local files shaped as models.Artifact so
+// the UI's cached-objects view can render them the same way as remote artifacts.
+// Local files carry no access/fetch counters, so those are left at zero and the
+// timestamps are all derived from created_at.
+func (db *DB) ListLocalArtifacts(ctx context.Context, repoName string, limit, offset int) ([]models.Artifact, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT lf.id, lf.repo_name, lf.file_path, lf.content_hash,
+			lf.created_at, b.size_bytes, b.content_type
+		FROM local_files lf
+		JOIN blobs b ON lf.content_hash = b.content_hash
+		WHERE lf.repo_name = $1
+		ORDER BY lf.file_path
+		LIMIT $2 OFFSET $3
+	`, repoName, limit, offset)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var artifacts []models.Artifact
+	for rows.Next() {
+		var a models.Artifact
+		var createdAt time.Time
+		if err := rows.Scan(&a.ID, &a.RemoteName, &a.Path, &a.ContentHash, &createdAt, &a.SizeBytes, &a.ContentType); err != nil {
+			return nil, err
+		}
+		a.FirstSeenAt = createdAt
+		a.LastFetchedAt = createdAt
+		a.LastAccessedAt = createdAt
+		artifacts = append(artifacts, a)
+	}
+	return artifacts, rows.Err()
+}
+
+func (db *DB) ListLocalFilesByPrefix(ctx context.Context, repoName, prefix string) ([]LocalFile, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT id, repo_name, file_path, content_hash, created_at
+		FROM local_files
+		WHERE repo_name = $1 AND file_path LIKE $2
+		ORDER BY file_path
+	`, repoName, prefix+"%")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var files []LocalFile
+	for rows.Next() {
+		var f LocalFile
+		if err := rows.Scan(&f.ID, &f.RepoName, &f.FilePath, &f.ContentHash, &f.CreatedAt); err != nil {
+			return nil, err
+		}
+		files = append(files, f)
+	}
+	return files, rows.Err()
+}
+
+func (db *DB) ListLocalFilePackages(ctx context.Context, repoName string) ([]string, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT DISTINCT split_part(file_path, '/', 1)
+		FROM local_files
+		WHERE repo_name = $1
+		ORDER BY 1
+	`, repoName)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var packages []string
+	for rows.Next() {
+		var pkg string
+		if err := rows.Scan(&pkg); err != nil {
+			return nil, err
+		}
+		packages = append(packages, pkg)
+	}
+	return packages, rows.Err()
+}
+
+func (db *DB) ListFilesByPrefix(ctx context.Context, repoName, prefix string) ([]provider.FileEntry, error) {
+	files, err := db.ListLocalFilesByPrefix(ctx, repoName, prefix)
+	if err != nil {
+		return nil, err
+	}
+	result := make([]provider.FileEntry, len(files))
+	for i, f := range files {
+		result[i] = provider.FileEntry{FilePath: f.FilePath, ContentHash: f.ContentHash}
+	}
+	return result, nil
+}
+
+func (db *DB) ListPackages(ctx context.Context, repoName string) ([]string, error) {
+	return db.ListLocalFilePackages(ctx, repoName)
+}
+
+func (db *DB) DeleteLocalFile(ctx context.Context, repoName, filePath string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM local_files WHERE repo_name = $1 AND file_path = $2`, repoName, filePath)
+	return err
+}

internal/database/migrations_test.go

@@ -0,0 +1,162 @@
+package database
+
+import (
+	"context"
+	"io/fs"
+	"maps"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+
+	"git.unkin.net/unkin/golib/pg"
+
+	"git.unkin.net/unkin/artifactapi/migrations"
+)
+
+// migrationsDir is the repo's migrations/ directory, relative to this package.
+const migrationsDir = "../../migrations"
+
+func readMigrationsFromDisk(t *testing.T) map[string]string {
+	t.Helper()
+	entries, err := os.ReadDir(migrationsDir)
+	if err != nil {
+		t.Fatalf("read %s: %v", migrationsDir, err)
+	}
+	files := map[string]string{}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".sql") {
+			continue
+		}
+		b, err := os.ReadFile(filepath.Join(migrationsDir, e.Name()))
+		if err != nil {
+			t.Fatalf("read %s: %v", e.Name(), err)
+		}
+		files[e.Name()] = string(b)
+	}
+	if len(files) == 0 {
+		t.Fatalf("no .sql files in %s", migrationsDir)
+	}
+	return files
+}
+
+// The embedded set is the shipped schema, so it must match the migrations/
+// directory exactly — a file added on disk but not embedded would never run.
+func TestEmbeddedMigrationsMatchDirectory(t *testing.T) {
+	onDisk := readMigrationsFromDisk(t)
+	entries, err := fs.ReadDir(migrations.FS, ".")
+	if err != nil {
+		t.Fatalf("read embedded migrations: %v", err)
+	}
+	embedded := map[string]string{}
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".sql") {
+			continue
+		}
+		b, err := migrations.FS.ReadFile(e.Name())
+		if err != nil {
+			t.Fatalf("read embedded %s: %v", e.Name(), err)
+		}
+		embedded[e.Name()] = string(b)
+	}
+	if len(embedded) != len(onDisk) {
+		t.Fatalf("embedded %d files, migrations/ has %d", len(embedded), len(onDisk))
+	}
+	for name, body := range embedded {
+		want, ok := onDisk[name]
+		if !ok {
+			t.Errorf("%s is embedded but not in migrations/", name)
+			continue
+		}
+		if body != want {
+			t.Errorf("%s: embedded body differs from migrations/%s", name, name)
+		}
+	}
+}
+
+var (
+	createTableRe = regexp.MustCompile(`(?i)\bCREATE\s+TABLE\b(\s+IF\s+NOT\s+EXISTS\b)?`)
+	createIndexRe = regexp.MustCompile(`(?i)\bCREATE\s+(UNIQUE\s+)?INDEX\b(\s+IF\s+NOT\s+EXISTS\b)?`)
+	addColumnRe   = regexp.MustCompile(`(?i)\bADD\s+COLUMN\b(\s+IF\s+NOT\s+EXISTS\b)?`)
+	destructiveRe = regexp.MustCompile(`(?i)\b(DROP\s+(TABLE|COLUMN|INDEX)|TRUNCATE|DELETE\s+FROM)\b`)
+)
+
+// A migration absent from schema_migrations is re-run even when the live
+// database already has the schema, which is exactly how the deployed database —
+// migrated for years by an untracked inline DDL blob — picks 0001 up. Every
+// statement must therefore be idempotent, or that first tracked run would fail
+// against production.
+func TestMigrationsAreIdempotent(t *testing.T) {
+	for name, body := range readMigrationsFromDisk(t) {
+		for _, m := range createTableRe.FindAllStringSubmatch(body, -1) {
+			if m[1] == "" {
+				t.Errorf("%s: %q is not IF NOT EXISTS-guarded", name, strings.Join(strings.Fields(m[0]), " "))
+			}
+		}
+		for _, m := range createIndexRe.FindAllStringSubmatch(body, -1) {
+			if m[2] == "" {
+				t.Errorf("%s: %q is not IF NOT EXISTS-guarded", name, strings.Join(strings.Fields(m[0]), " "))
+			}
+		}
+		for _, m := range addColumnRe.FindAllStringSubmatch(body, -1) {
+			if m[1] == "" {
+				t.Errorf("%s: %q is not IF NOT EXISTS-guarded", name, strings.Join(strings.Fields(m[0]), " "))
+			}
+		}
+		if loc := destructiveRe.FindString(body); loc != "" {
+			t.Errorf("%s: destructive statement %q; migrations are additive", name, loc)
+		}
+	}
+}
+
+// The deployed database was built by the untracked inline DDL this runner
+// replaces, so its very first tracked start runs 0001 against a schema that
+// already exists. Reproduce that by dropping the tracking row from an
+// already-migrated database and starting again: it must succeed and re-record
+// the version, changing nothing else.
+func TestMigratingAnAlreadyPopulatedSchemaIsANoOp(t *testing.T) {
+	requireDB(t)
+	c := context.Background()
+
+	if _, err := testDB.Pool.Exec(c, "DELETE FROM schema_migrations"); err != nil {
+		t.Fatalf("clear schema_migrations: %v", err)
+	}
+	db, err := New(testDSN)
+	if err != nil {
+		t.Fatalf("migrate over an existing schema: %v", err)
+	}
+	defer db.Close()
+
+	var versions []string
+	rows, err := db.Pool.Query(c, "SELECT version FROM schema_migrations ORDER BY version")
+	if err != nil {
+		t.Fatalf("read schema_migrations: %v", err)
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var v string
+		if err := rows.Scan(&v); err != nil {
+			t.Fatalf("scan version: %v", err)
+		}
+		versions = append(versions, v)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("read schema_migrations: %v", err)
+	}
+
+	want := slices.Sorted(maps.Keys(readMigrationsFromDisk(t)))
+	if !slices.Equal(versions, want) {
+		t.Fatalf("schema_migrations = %v, want %v", versions, want)
+	}
+}
+
+// The advisory lock key is derived from migrationLockName by golib. Pin it so a
+// rename cannot silently let two builds migrate the same cluster at once.
+func TestMigrationLockKeyIsPinned(t *testing.T) {
+	const wantKey int64 = -6981019939451326383
+	if got := pg.LockKey(migrationLockName); got != wantKey {
+		t.Fatalf("LockKey(%q) = %d, want %d", migrationLockName, got, wantKey)
+	}
+}

internal/database/postgres.go

@@ -0,0 +1,35 @@
+package database
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.unkin.net/unkin/golib/pg"
+
+	"git.unkin.net/unkin/artifactapi/migrations"
+)
+
+// migrationLockName names the cluster-wide advisory lock the migration run
+// contends for; golib derives the key as FNV-1a/64 of it. Replicas starting
+// together queue on it instead of racing each other through the DDL.
+const migrationLockName = "artifactapi-migrations"
+
+type DB struct {
+	Pool *pgxpool.Pool
+}
+
+func New(dsn string) (*DB, error) {
+	ctx := context.Background()
+	pool, err := pg.NewMigrated(ctx, dsn, migrations.FS, pg.MigrateOptions{
+		LockName: migrationLockName,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &DB{Pool: pool}, nil
+}
+
+func (db *DB) Close() {
+	db.Pool.Close()
+}

internal/database/remotes.go

@@ -0,0 +1,122 @@
+package database
+
+import (
+	"context"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+const remoteCols = `name, package_type, repo_type, base_url, mirrorlist, mirror_strategy, description, username, password,
+	immutable_ttl, mutable_ttl, check_mutable,
+	patterns, blocklist, mutable_patterns, immutable_patterns,
+	ban_tags_enabled, ban_tags,
+	quarantine_enabled, quarantine_days, stale_on_error,
+	releases_remote, managed_by,
+	upstream_dial_timeout, upstream_tls_timeout, upstream_response_header_timeout,
+	created_at, updated_at`
+
+// normalizeMirrorStrategy maps an empty strategy to the round_robin default so
+// the NOT NULL mirror_strategy column always stores a canonical value.
+func normalizeMirrorStrategy(s string) string {
+	if s == "" {
+		return models.MirrorStrategyRoundRobin
+	}
+	return s
+}
+
+func scanRemote(scanner interface{ Scan(...any) error }, r *models.Remote) error {
+	return scanner.Scan(
+		&r.Name, &r.PackageType, &r.RepoType, &r.BaseURL, &r.Mirrorlist, &r.MirrorStrategy, &r.Description, &r.Username, &r.Password,
+		&r.ImmutableTTL, &r.MutableTTL, &r.CheckMutable,
+		&r.Patterns, &r.Blocklist, &r.MutablePatterns, &r.ImmutablePatterns,
+		&r.BanTagsEnabled, &r.BanTags,
+		&r.QuarantineEnabled, &r.QuarantineDays, &r.StaleOnError,
+		&r.ReleasesRemote, &r.ManagedBy,
+		&r.UpstreamDialTimeout, &r.UpstreamTLSTimeout, &r.UpstreamResponseHeaderTimeout,
+		&r.CreatedAt, &r.UpdatedAt,
+	)
+}
+
+func (db *DB) GetRemote(ctx context.Context, name string) (*models.Remote, error) {
+	row := db.Pool.QueryRow(ctx, `SELECT `+remoteCols+` FROM remotes WHERE name = $1`, name)
+	var r models.Remote
+	if err := scanRemote(row, &r); err != nil {
+		return nil, err
+	}
+	return &r, nil
+}
+
+func (db *DB) ListRemotes(ctx context.Context) ([]models.Remote, error) {
+	rows, err := db.Pool.Query(ctx, `SELECT `+remoteCols+` FROM remotes ORDER BY name`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var remotes []models.Remote
+	for rows.Next() {
+		var r models.Remote
+		if err := scanRemote(rows, &r); err != nil {
+			return nil, err
+		}
+		remotes = append(remotes, r)
+	}
+	return remotes, rows.Err()
+}
+
+func (db *DB) CreateRemote(ctx context.Context, r *models.Remote) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO remotes (
+			name, package_type, repo_type, base_url, mirrorlist, description, username, password,
+			immutable_ttl, mutable_ttl, check_mutable,
+			patterns, blocklist, mutable_patterns, immutable_patterns,
+			ban_tags_enabled, ban_tags,
+			quarantine_enabled, quarantine_days, stale_on_error,
+			releases_remote, managed_by,
+			upstream_dial_timeout, upstream_tls_timeout, upstream_response_header_timeout,
+			mirror_strategy
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24,$25,$26)
+	`,
+		r.Name, r.PackageType, r.RepoType, r.BaseURL, r.Mirrorlist, r.Description, r.Username, r.Password,
+		r.ImmutableTTL, r.MutableTTL, r.CheckMutable,
+		r.Patterns, r.Blocklist, r.MutablePatterns, r.ImmutablePatterns,
+		r.BanTagsEnabled, r.BanTags,
+		r.QuarantineEnabled, r.QuarantineDays, r.StaleOnError,
+		r.ReleasesRemote, r.ManagedBy,
+		r.UpstreamDialTimeout, r.UpstreamTLSTimeout, r.UpstreamResponseHeaderTimeout,
+		normalizeMirrorStrategy(r.MirrorStrategy),
+	)
+	return err
+}
+
+func (db *DB) UpdateRemote(ctx context.Context, r *models.Remote) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE remotes SET
+			package_type=$2, repo_type=$3, base_url=$4, mirrorlist=$25, description=$5, username=$6, password=$7,
+			immutable_ttl=$8, mutable_ttl=$9, check_mutable=$10,
+			patterns=$11, blocklist=$12, mutable_patterns=$13, immutable_patterns=$14,
+			ban_tags_enabled=$15, ban_tags=$16,
+			quarantine_enabled=$17, quarantine_days=$18, stale_on_error=$19,
+			releases_remote=$20, managed_by=$21,
+			upstream_dial_timeout=$22, upstream_tls_timeout=$23, upstream_response_header_timeout=$24,
+			mirror_strategy=$26,
+			updated_at=NOW()
+		WHERE name=$1
+	`,
+		r.Name, r.PackageType, r.RepoType, r.BaseURL, r.Description, r.Username, r.Password,
+		r.ImmutableTTL, r.MutableTTL, r.CheckMutable,
+		r.Patterns, r.Blocklist, r.MutablePatterns, r.ImmutablePatterns,
+		r.BanTagsEnabled, r.BanTags,
+		r.QuarantineEnabled, r.QuarantineDays, r.StaleOnError,
+		r.ReleasesRemote, r.ManagedBy,
+		r.UpstreamDialTimeout, r.UpstreamTLSTimeout, r.UpstreamResponseHeaderTimeout,
+		r.Mirrorlist,
+		normalizeMirrorStrategy(r.MirrorStrategy),
+	)
+	return err
+}
+
+func (db *DB) DeleteRemote(ctx context.Context, name string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM remotes WHERE name = $1`, name)
+	return err
+}

internal/database/rpm_metadata.go

@@ -0,0 +1,145 @@
+package database
+
+import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
+)
+
+func (db *DB) InsertRPMMetadata(ctx context.Context, meta *provider.RPMMetadata) error {
+	requiresJSON, _ := json.Marshal(meta.Requires)
+	providesJSON, _ := json.Marshal(meta.Provides)
+	conflictsJSON, _ := json.Marshal(meta.Conflicts)
+	obsoletesJSON, _ := json.Marshal(meta.Obsoletes)
+	filesJSON, _ := json.Marshal(meta.Files)
+	changelogsJSON, _ := json.Marshal(meta.Changelogs)
+
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO rpm_metadata (
+			repo_name, file_path, content_hash,
+			name, epoch, version, release, arch,
+			summary, description, rpm_size, installed_size,
+			license, vendor, build_group, build_host, source_rpm, url, packager,
+			requires, provides, conflicts, obsoletes, files, changelogs
+		) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21,$22,$23,$24,$25)
+		ON CONFLICT (repo_name, file_path) DO NOTHING
+	`,
+		meta.RepoName, meta.FilePath, meta.ContentHash,
+		meta.Name, meta.Epoch, meta.Version, meta.Release, meta.Arch,
+		meta.Summary, meta.Description, meta.RPMSize, meta.InstalledSize,
+		meta.License, meta.Vendor, meta.Group, meta.BuildHost, meta.SourceRPM, meta.URL, meta.Packager,
+		requiresJSON, providesJSON, conflictsJSON, obsoletesJSON, filesJSON, changelogsJSON,
+	)
+	return err
+}
+
+func (db *DB) DeleteRPMMetadata(ctx context.Context, repoName, filePath string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM rpm_metadata WHERE repo_name = $1 AND file_path = $2`, repoName, filePath)
+	return err
+}
+
+type RPMMetadataRow struct {
+	RepoName      string
+	FilePath      string
+	ContentHash   string
+	Name          string
+	Epoch         int
+	Version       string
+	Release       string
+	Arch          string
+	Summary       string
+	Description   string
+	RPMSize       int64
+	InstalledSize int64
+	License       string
+	Vendor        string
+	Group         string
+	BuildHost     string
+	SourceRPM     string
+	URL           string
+	Packager      string
+	Requires      json.RawMessage
+	Provides      json.RawMessage
+	Conflicts     json.RawMessage
+	Obsoletes     json.RawMessage
+	Files         json.RawMessage
+	Changelogs    json.RawMessage
+	CreatedAt     time.Time
+}
+
+func (db *DB) ListRPMMetadataEntries(ctx context.Context, repoName string) ([]provider.RPMMetadata, error) {
+	rows, err := db.ListRPMMetadata(ctx, repoName)
+	if err != nil {
+		return nil, err
+	}
+	result := make([]provider.RPMMetadata, len(rows))
+	for i, r := range rows {
+		meta := provider.RPMMetadata{
+			RepoName:      r.RepoName,
+			FilePath:      r.FilePath,
+			ContentHash:   r.ContentHash,
+			Name:          r.Name,
+			Epoch:         r.Epoch,
+			Version:       r.Version,
+			Release:       r.Release,
+			Arch:          r.Arch,
+			Summary:       r.Summary,
+			Description:   r.Description,
+			RPMSize:       r.RPMSize,
+			InstalledSize: r.InstalledSize,
+			License:       r.License,
+			Vendor:        r.Vendor,
+			Group:         r.Group,
+			BuildHost:     r.BuildHost,
+			SourceRPM:     r.SourceRPM,
+			URL:           r.URL,
+			Packager:      r.Packager,
+			CreatedAt:     r.CreatedAt,
+		}
+		json.Unmarshal(r.Requires, &meta.Requires)
+		json.Unmarshal(r.Provides, &meta.Provides)
+		json.Unmarshal(r.Conflicts, &meta.Conflicts)
+		json.Unmarshal(r.Obsoletes, &meta.Obsoletes)
+		json.Unmarshal(r.Files, &meta.Files)
+		json.Unmarshal(r.Changelogs, &meta.Changelogs)
+		result[i] = meta
+	}
+	return result, nil
+}
+
+func (db *DB) ListRPMMetadata(ctx context.Context, repoName string) ([]RPMMetadataRow, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT repo_name, file_path, content_hash,
+			name, epoch, version, release, arch,
+			summary, description, rpm_size, installed_size,
+			license, vendor, build_group, build_host, source_rpm, url, packager,
+			requires, provides, conflicts, obsoletes, files, changelogs,
+			created_at
+		FROM rpm_metadata
+		WHERE repo_name = $1
+		ORDER BY name, epoch, version, release, arch, file_path
+	`, repoName)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []RPMMetadataRow
+	for rows.Next() {
+		var r RPMMetadataRow
+		if err := rows.Scan(
+			&r.RepoName, &r.FilePath, &r.ContentHash,
+			&r.Name, &r.Epoch, &r.Version, &r.Release, &r.Arch,
+			&r.Summary, &r.Description, &r.RPMSize, &r.InstalledSize,
+			&r.License, &r.Vendor, &r.Group, &r.BuildHost, &r.SourceRPM, &r.URL, &r.Packager,
+			&r.Requires, &r.Provides, &r.Conflicts, &r.Obsoletes, &r.Files, &r.Changelogs,
+			&r.CreatedAt,
+		); err != nil {
+			return nil, err
+		}
+		result = append(result, r)
+	}
+	return result, rows.Err()
+}

internal/database/signing_keys.go

@@ -0,0 +1,35 @@
+package database
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// GetSigningKey returns the stored armored private key and key id for a purpose.
+// found is false when no key has been generated yet.
+func (db *DB) GetSigningKey(ctx context.Context, purpose string) (armor, keyID string, found bool, err error) {
+	row := db.Pool.QueryRow(ctx, `
+		SELECT private_key_armor, key_id FROM signing_keys WHERE purpose = $1
+	`, purpose)
+	if err := row.Scan(&armor, &keyID); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return "", "", false, nil
+		}
+		return "", "", false, err
+	}
+	return armor, keyID, true, nil
+}
+
+// InsertSigningKeyIfAbsent stores a freshly generated key, doing nothing if
+// another replica already inserted one. Callers re-read with GetSigningKey to
+// pick up whichever key won the race.
+func (db *DB) InsertSigningKeyIfAbsent(ctx context.Context, purpose, armor, keyID string) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO signing_keys (purpose, private_key_armor, key_id)
+		VALUES ($1, $2, $3)
+		ON CONFLICT (purpose) DO NOTHING
+	`, purpose, armor, keyID)
+	return err
+}

internal/database/signing_keys_test.go

@@ -0,0 +1,31 @@
+package database
+
+import "testing"
+
+func TestSigningKeyRoundTripAndIdempotency(t *testing.T) {
+	requireDB(t)
+
+	const purpose = "terraform-provider-test"
+
+	// Absent to start.
+	if _, _, found, err := testDB.GetSigningKey(ctx(), purpose); err != nil || found {
+		t.Fatalf("expected no key, got found=%v err=%v", found, err)
+	}
+
+	if err := testDB.InsertSigningKeyIfAbsent(ctx(), purpose, "ARMOR-1", "KEYID1"); err != nil {
+		t.Fatal(err)
+	}
+
+	// A second insert must not overwrite (models the replica race).
+	if err := testDB.InsertSigningKeyIfAbsent(ctx(), purpose, "ARMOR-2", "KEYID2"); err != nil {
+		t.Fatal(err)
+	}
+
+	armor, keyID, found, err := testDB.GetSigningKey(ctx(), purpose)
+	if err != nil || !found {
+		t.Fatalf("expected key, found=%v err=%v", found, err)
+	}
+	if armor != "ARMOR-1" || keyID != "KEYID1" {
+		t.Errorf("key was overwritten: armor=%q key_id=%q", armor, keyID)
+	}
+}

internal/database/stats.go

@@ -0,0 +1,152 @@
+package database
+
+import (
+	"context"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func (db *DB) GetOverviewStats(ctx context.Context) (*models.OverviewStats, error) {
+	var stats models.OverviewStats
+
+	err := db.Pool.QueryRow(ctx, `SELECT COUNT(*) FROM remotes`).Scan(&stats.TotalRemotes)
+	if err != nil {
+		return nil, err
+	}
+
+	err = db.Pool.QueryRow(ctx, `SELECT COALESCE(COUNT(*), 0), COALESCE(SUM(b.size_bytes), 0)
+		FROM artifacts a JOIN blobs b ON a.content_hash = b.content_hash`).
+		Scan(&stats.TotalObjects, &stats.TotalBytes)
+	if err != nil {
+		return nil, err
+	}
+
+	err = db.Pool.QueryRow(ctx, `
+		SELECT COALESCE(
+			(SELECT COUNT(*) FROM artifacts) - (SELECT COUNT(DISTINCT content_hash) FROM artifacts),
+			0
+		)`).Scan(&stats.TotalBlobsDeduped)
+	if err != nil {
+		return nil, err
+	}
+
+	err = db.Pool.QueryRow(ctx, `
+		SELECT COALESCE(SUM(size_bytes), 0)
+		FROM access_log
+		WHERE cache_hit = TRUE AND created_at > NOW() - INTERVAL '30 days'
+	`).Scan(&stats.BandwidthSaved30d)
+	if err != nil {
+		return nil, err
+	}
+
+	return &stats, nil
+}
+
+type RemoteStatRow struct {
+	Name        string `json:"name"`
+	ObjectCount int64  `json:"object_count"`
+	TotalBytes  int64  `json:"total_bytes"`
+	Requests30d int64  `json:"requests_30d"`
+}
+
+func (db *DB) GetTopRemotes(ctx context.Context, limit int) ([]RemoteStatRow, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT r.name,
+			COALESCE(a.cnt, 0) AS object_count,
+			COALESCE(a.total_bytes, 0) AS total_bytes,
+			COALESCE(l.req_count, 0) AS requests_30d
+		FROM remotes r
+		LEFT JOIN (
+			SELECT remote_name, COUNT(*) AS cnt, SUM(b.size_bytes) AS total_bytes
+			FROM artifacts a JOIN blobs b ON a.content_hash = b.content_hash
+			GROUP BY remote_name
+		) a ON r.name = a.remote_name
+		LEFT JOIN (
+			SELECT remote_name, COUNT(*) AS req_count
+			FROM access_log
+			WHERE created_at > NOW() - INTERVAL '30 days'
+			GROUP BY remote_name
+		) l ON r.name = l.remote_name
+		ORDER BY COALESCE(a.total_bytes, 0) DESC
+		LIMIT $1
+	`, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []RemoteStatRow
+	for rows.Next() {
+		var r RemoteStatRow
+		if err := rows.Scan(&r.Name, &r.ObjectCount, &r.TotalBytes, &r.Requests30d); err != nil {
+			return nil, err
+		}
+		result = append(result, r)
+	}
+	return result, rows.Err()
+}
+
+type FileStatRow struct {
+	RemoteName  string `json:"remote_name"`
+	Path        string `json:"path"`
+	AccessCount int64  `json:"access_count"`
+	SizeBytes   int64  `json:"size_bytes"`
+}
+
+func (db *DB) GetTopFilesByHits(ctx context.Context, limit int) ([]FileStatRow, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT a.remote_name, a.path, a.access_count, b.size_bytes
+		FROM artifacts a
+		JOIN blobs b ON a.content_hash = b.content_hash
+		ORDER BY a.access_count DESC
+		LIMIT $1
+	`, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []FileStatRow
+	for rows.Next() {
+		var r FileStatRow
+		if err := rows.Scan(&r.RemoteName, &r.Path, &r.AccessCount, &r.SizeBytes); err != nil {
+			return nil, err
+		}
+		result = append(result, r)
+	}
+	return result, rows.Err()
+}
+
+type BandwidthStatRow struct {
+	RemoteName string `json:"remote_name"`
+	Path       string `json:"path"`
+	Bandwidth  int64  `json:"bandwidth"`
+	Requests   int64  `json:"requests"`
+}
+
+func (db *DB) GetTopFilesByBandwidth(ctx context.Context, limit int) ([]BandwidthStatRow, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT remote_name, path,
+			COALESCE(SUM(size_bytes), 0) AS bandwidth,
+			COUNT(*) AS requests
+		FROM access_log
+		WHERE created_at > NOW() - INTERVAL '30 days'
+		GROUP BY remote_name, path
+		ORDER BY bandwidth DESC
+		LIMIT $1
+	`, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var result []BandwidthStatRow
+	for rows.Next() {
+		var r BandwidthStatRow
+		if err := rows.Scan(&r.RemoteName, &r.Path, &r.Bandwidth, &r.Requests); err != nil {
+			return nil, err
+		}
+		result = append(result, r)
+	}
+	return result, rows.Err()
+}

internal/database/virtuals.go

@@ -0,0 +1,64 @@
+package database
+
+import (
+	"context"
+
+	"git.unkin.net/unkin/artifactapi/pkg/models"
+)
+
+func (db *DB) GetVirtual(ctx context.Context, name string) (*models.Virtual, error) {
+	row := db.Pool.QueryRow(ctx, `
+		SELECT name, package_type, description, members, managed_by, created_at, updated_at
+		FROM virtuals WHERE name = $1
+	`, name)
+
+	var v models.Virtual
+	err := row.Scan(&v.Name, &v.PackageType, &v.Description, &v.Members, &v.ManagedBy, &v.CreatedAt, &v.UpdatedAt)
+	if err != nil {
+		return nil, err
+	}
+	return &v, nil
+}
+
+func (db *DB) ListVirtuals(ctx context.Context) ([]models.Virtual, error) {
+	rows, err := db.Pool.Query(ctx, `
+		SELECT name, package_type, description, members, managed_by, created_at, updated_at
+		FROM virtuals ORDER BY name
+	`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var virtuals []models.Virtual
+	for rows.Next() {
+		var v models.Virtual
+		if err := rows.Scan(&v.Name, &v.PackageType, &v.Description, &v.Members, &v.ManagedBy, &v.CreatedAt, &v.UpdatedAt); err != nil {
+			return nil, err
+		}
+		virtuals = append(virtuals, v)
+	}
+	return virtuals, rows.Err()
+}
+
+func (db *DB) CreateVirtual(ctx context.Context, v *models.Virtual) error {
+	_, err := db.Pool.Exec(ctx, `
+		INSERT INTO virtuals (name, package_type, description, members, managed_by)
+		VALUES ($1, $2, $3, $4, $5)
+	`, v.Name, v.PackageType, v.Description, v.Members, v.ManagedBy)
+	return err
+}
+
+func (db *DB) UpdateVirtual(ctx context.Context, v *models.Virtual) error {
+	_, err := db.Pool.Exec(ctx, `
+		UPDATE virtuals SET
+			package_type=$2, description=$3, members=$4, managed_by=$5, updated_at=NOW()
+		WHERE name=$1
+	`, v.Name, v.PackageType, v.Description, v.Members, v.ManagedBy)
+	return err
+}
+
+func (db *DB) DeleteVirtual(ctx context.Context, name string) error {
+	_, err := db.Pool.Exec(ctx, `DELETE FROM virtuals WHERE name = $1`, name)
+	return err
+}

internal/gc/gc.go

@@ -0,0 +1,100 @@
+package gc
+
+import (
+	"context"
+	"log/slog"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+)
+
+// blobGracePeriod is how old an orphaned blob must be before GC will delete
+// it. This avoids racing in-flight dedup uploads that insert the blob row
+// before the referencing artifact/local_files row exists.
+const blobGracePeriod = 1 * time.Hour
+
+// uploadGracePeriod is how long a docker blob-upload staging object
+// (uploads/<uuid>) may sit idle before GC treats it as an abandoned push and
+// reaps it. Generous so a slow but live push is never cut off mid-flight.
+const uploadGracePeriod = 24 * time.Hour
+
+type Collector struct {
+	db       *database.DB
+	store    *storage.S3
+	interval time.Duration
+}
+
+func New(db *database.DB, store *storage.S3, interval time.Duration) *Collector {
+	return &Collector{db: db, store: store, interval: interval}
+}
+
+func (c *Collector) Run(ctx context.Context) {
+	slog.Info("gc started", "interval", c.interval)
+	ticker := time.NewTicker(c.interval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			slog.Info("gc stopped")
+			return
+		case <-ticker.C:
+			c.sweep(ctx)
+		}
+	}
+}
+
+func (c *Collector) sweep(ctx context.Context) {
+	start := time.Now()
+
+	c.sweepUploads(ctx)
+
+	orphaned, err := c.db.FindOrphanedBlobs(ctx, blobGracePeriod)
+	if err != nil {
+		slog.Error("gc: find orphaned blobs", "error", err)
+		return
+	}
+
+	deleted := 0
+	for _, blob := range orphaned {
+		if err := c.store.Delete(ctx, blob.S3Key); err != nil {
+			slog.Warn("gc: delete s3 object", "key", blob.S3Key, "error", err)
+			continue
+		}
+		if err := c.db.DeleteBlob(ctx, blob.ContentHash); err != nil {
+			slog.Warn("gc: delete blob row", "hash", blob.ContentHash, "error", err)
+			continue
+		}
+		deleted++
+	}
+
+	if deleted > 0 || len(orphaned) > 0 {
+		slog.Info("gc sweep complete",
+			"orphaned_found", len(orphaned),
+			"deleted", deleted,
+			"duration_ms", time.Since(start).Milliseconds(),
+		)
+	}
+}
+
+// sweepUploads reaps docker blob-upload staging objects abandoned longer than
+// uploadGracePeriod (cancelled or interrupted pushes that never finalised).
+func (c *Collector) sweepUploads(ctx context.Context) {
+	stale, err := c.store.ListStaleObjects(ctx, "uploads/", time.Now().Add(-uploadGracePeriod))
+	if err != nil {
+		slog.Error("gc: list stale uploads", "error", err)
+		return
+	}
+	reaped := 0
+	for _, key := range stale {
+		if err := c.store.Delete(ctx, key); err != nil {
+			slog.Warn("gc: delete stale upload", "key", key, "error", err)
+			continue
+		}
+		reaped++
+	}
+	if reaped > 0 {
+		slog.Info("gc: reaped stale docker uploads", "count", reaped)
+	}
+}

internal/gc/gc_integration_test.go

@@ -0,0 +1,114 @@
+package gc
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/database"
+	"git.unkin.net/unkin/artifactapi/internal/storage"
+	"git.unkin.net/unkin/artifactapi/internal/testsupport"
+)
+
+var (
+	testDB    *database.DB
+	testStore *storage.S3
+)
+
+func TestMain(m *testing.M) {
+	ctx := context.Background()
+	dsn, termPG, err := testsupport.StartPostgres(ctx)
+	if err != nil {
+		os.Exit(m.Run())
+	}
+	minio, termMinio, err := testsupport.StartMinio(ctx)
+	if err != nil {
+		termPG()
+		os.Exit(m.Run())
+	}
+	db, err := database.New(dsn)
+	if err != nil {
+		panic(err)
+	}
+	var s3 *storage.S3
+	for i := 0; i < 20; i++ {
+		if s3, err = storage.NewS3(minio.Endpoint, minio.AccessKey, minio.SecretKey, "gc-test", false, ""); err == nil {
+			break
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+	if err != nil {
+		panic(err)
+	}
+	testDB = db
+	testStore = s3
+
+	code := m.Run()
+	db.Close()
+	termMinio()
+	termPG()
+	if code != 0 {
+		os.Exit(code)
+	}
+}
+
+func TestSweepDeletesOldOrphan(t *testing.T) {
+	if testDB == nil {
+		t.Skip("Docker unavailable")
+	}
+	ctx := context.Background()
+	hash := "sha256:gcorphan"
+	key := storage.BlobKey("gcorphan")
+
+	if err := testStore.Upload(ctx, key, bytes.NewReader([]byte("orphan")), 6, "application/octet-stream"); err != nil {
+		t.Fatal(err)
+	}
+	if err := testDB.UpsertBlob(ctx, hash, key, 6, "application/octet-stream"); err != nil {
+		t.Fatal(err)
+	}
+	// Age the blob past the grace period.
+	if _, err := testDB.Pool.Exec(ctx, `UPDATE blobs SET created_at = now() - interval '2 hours' WHERE content_hash = $1`, hash); err != nil {
+		t.Fatal(err)
+	}
+
+	c := New(testDB, testStore, time.Hour)
+	c.sweep(ctx)
+
+	if exists, _ := testStore.Exists(ctx, key); exists {
+		t.Error("expected orphan object deleted from store")
+	}
+	orphans, _ := testDB.FindOrphanedBlobs(ctx, 0)
+	for _, b := range orphans {
+		if b.ContentHash == hash {
+			t.Error("expected orphan blob row deleted")
+		}
+	}
+}
+
+func TestSweepNoOrphans(t *testing.T) {
+	if testDB == nil {
+		t.Skip("Docker unavailable")
+	}
+	// A sweep with nothing to collect should be a clean no-op.
+	New(testDB, testStore, time.Hour).sweep(context.Background())
+}
+
+func TestRunStopsOnContextCancel(t *testing.T) {
+	if testDB == nil {
+		t.Skip("Docker unavailable")
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		New(testDB, testStore, time.Hour).Run(ctx)
+		close(done)
+	}()
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("Run did not return after context cancel")
+	}
+}

internal/gc/gc_test.go

@@ -0,0 +1,15 @@
+package gc_test
+
+import (
+	"testing"
+	"time"
+
+	"git.unkin.net/unkin/artifactapi/internal/gc"
+)
+
+func TestNew(t *testing.T) {
+	c := gc.New(nil, nil, 1*time.Hour)
+	if c == nil {
+		t.Fatal("expected non-nil collector")
+	}
+}

internal/githubauth/app.go

@@ -0,0 +1,199 @@
+package githubauth
+
+import (
+	"context"
+	"crypto"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/json"
+	"encoding/pem"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	defaultAPIBase = "https://api.github.com"
+
+	// jwtLifetime is how long the app JWT is valid. GitHub caps it at 10 minutes;
+	// 9 leaves headroom for clock skew.
+	jwtLifetime = 9 * time.Minute
+	// jwtBackdate backdates iat to tolerate the app server's clock running behind
+	// GitHub's, which otherwise rejects the JWT.
+	jwtBackdate = 60 * time.Second
+	// refreshSkew refreshes the installation token this long before it expires so
+	// a request never races an expiry.
+	refreshSkew = 5 * time.Minute
+)
+
+type httpDoer interface {
+	Do(*http.Request) (*http.Response, error)
+}
+
+// appCredential mints installation access tokens for a GitHub App. It signs a
+// short-lived RS256 JWT with the app private key, exchanges it for a ~1h
+// installation token, caches that token, and refreshes it shortly before expiry.
+// Refreshes are single-flighted by holding the mutex across the exchange, so
+// concurrent callers coalesce onto one HTTP request and reuse the cached token.
+type appCredential struct {
+	appID          string
+	installationID string
+	key            *rsa.PrivateKey
+	apiBase        string
+	client         httpDoer
+
+	mu     sync.Mutex
+	token  string
+	expiry time.Time
+}
+
+func newAppCredential(opts Options) (*appCredential, error) {
+	if opts.AppID == "" {
+		return nil, errors.New("github app: GITHUB_APP_ID is required")
+	}
+	if opts.InstallationID == "" {
+		return nil, errors.New("github app: GITHUB_APP_INSTALLATION_ID is required")
+	}
+	pemBytes, err := loadPrivateKeyPEM(opts)
+	if err != nil {
+		return nil, err
+	}
+	key, err := parseRSAPrivateKey(pemBytes)
+	if err != nil {
+		return nil, err
+	}
+
+	apiBase := opts.apiBaseURL
+	if apiBase == "" {
+		apiBase = defaultAPIBase
+	}
+	client := opts.httpClient
+	if client == nil {
+		client = &http.Client{Timeout: 30 * time.Second}
+	}
+
+	return &appCredential{
+		appID:          opts.AppID,
+		installationID: opts.InstallationID,
+		key:            key,
+		apiBase:        strings.TrimRight(apiBase, "/"),
+		client:         client,
+	}, nil
+}
+
+// Token returns a cached installation token, refreshing it under a single-flight
+// lock when it is missing or within refreshSkew of expiry.
+func (a *appCredential) Token(ctx context.Context) (string, error) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if a.token != "" && time.Now().Before(a.expiry.Add(-refreshSkew)) {
+		return a.token, nil
+	}
+	if err := a.refreshLocked(ctx); err != nil {
+		return "", err
+	}
+	return a.token, nil
+}
+
+func (a *appCredential) refreshLocked(ctx context.Context) error {
+	jwt, err := mintJWT(a.appID, a.key, time.Now())
+	if err != nil {
+		return fmt.Errorf("github app: mint jwt: %w", err)
+	}
+
+	u := fmt.Sprintf("%s/app/installations/%s/access_tokens", a.apiBase, a.installationID)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, u, nil)
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+jwt)
+	req.Header.Set("Accept", "application/vnd.github+json")
+	req.Header.Set("X-GitHub-Api-Version", "2022-11-28")
+
+	resp, err := a.client.Do(req)
+	if err != nil {
+		return fmt.Errorf("github app: token exchange: %w", err)
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
+		// Never echo the body verbatim — it can contain sensitive material.
+		return fmt.Errorf("github app: token exchange status %d", resp.StatusCode)
+	}
+
+	var out struct {
+		Token     string    `json:"token"`
+		ExpiresAt time.Time `json:"expires_at"`
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		return fmt.Errorf("github app: decode token response: %w", err)
+	}
+	if out.Token == "" {
+		return errors.New("github app: token exchange returned an empty token")
+	}
+	a.token = out.Token
+	a.expiry = out.ExpiresAt
+	if a.expiry.IsZero() {
+		// Defensive: assume the documented ~1h lifetime if GitHub omits it.
+		a.expiry = time.Now().Add(time.Hour)
+	}
+	return nil
+}
+
+// mintJWT builds and RS256-signs a GitHub App JWT (iss=app id, backdated iat,
+// ≤10m exp) using stdlib crypto — no third-party JWT dependency.
+func mintJWT(appID string, key *rsa.PrivateKey, now time.Time) (string, error) {
+	header := map[string]string{"alg": "RS256", "typ": "JWT"}
+	claims := map[string]any{
+		"iat": now.Add(-jwtBackdate).Unix(),
+		"exp": now.Add(jwtLifetime).Unix(),
+		"iss": appID,
+	}
+	hb, err := json.Marshal(header)
+	if err != nil {
+		return "", err
+	}
+	cb, err := json.Marshal(claims)
+	if err != nil {
+		return "", err
+	}
+	signingInput := b64url(hb) + "." + b64url(cb)
+	digest := sha256.Sum256([]byte(signingInput))
+	sig, err := rsa.SignPKCS1v15(rand.Reader, key, crypto.SHA256, digest[:])
+	if err != nil {
+		return "", err
+	}
+	return signingInput + "." + b64url(sig), nil
+}
+
+func b64url(b []byte) string {
+	return base64.RawURLEncoding.EncodeToString(b)
+}
+
+// parseRSAPrivateKey accepts PKCS#1 ("RSA PRIVATE KEY") and PKCS#8 ("PRIVATE
+// KEY") PEM, covering both GitHub App key export formats.
+func parseRSAPrivateKey(pemBytes []byte) (*rsa.PrivateKey, error) {
+	block, _ := pem.Decode(pemBytes)
+	if block == nil {
+		return nil, errors.New("github app: private key is not valid PEM")
+	}
+	if key, err := x509.ParsePKCS1PrivateKey(block.Bytes); err == nil {
+		return key, nil
+	}
+	keyAny, err := x509.ParsePKCS8PrivateKey(block.Bytes)
+	if err != nil {
+		return nil, errors.New("github app: private key is not a supported RSA PKCS#1/PKCS#8 key")
+	}
+	rsaKey, ok := keyAny.(*rsa.PrivateKey)
+	if !ok {
+		return nil, errors.New("github app: private key is not an RSA key")
+	}
+	return rsaKey, nil
+}

internal/githubauth/app_test.go

@@ -0,0 +1,207 @@
+package githubauth
+
+import (
+	"context"
+	"crypto"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/json"
+	"encoding/pem"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func testRSAKeyPEM(t *testing.T) string {
+	t.Helper()
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	der := x509.MarshalPKCS1PrivateKey(key)
+	return string(pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: der}))
+}
+
+// appFixture serves the installation-token exchange endpoint, records requests,
+// verifies the presented JWT against the app public key, and returns tokens with
+// a controllable expiry.
+type appFixture struct {
+	srv       *httptest.Server
+	pub       *rsa.PublicKey
+	mu        sync.Mutex
+	exchanges int
+	lastJWT   string
+	expiresAt func() time.Time
+	tokenSeq  int
+}
+
+func newAppFixture(t *testing.T, pemKey string) *appFixture {
+	t.Helper()
+	block, _ := pem.Decode([]byte(pemKey))
+	key, err := x509.ParsePKCS1PrivateKey(block.Bytes)
+	if err != nil {
+		t.Fatalf("parse test key: %v", err)
+	}
+	f := &appFixture{
+		pub:       &key.PublicKey,
+		expiresAt: func() time.Time { return time.Now().Add(time.Hour) },
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/app/installations/456/access_tokens", func(w http.ResponseWriter, r *http.Request) {
+		auth := r.Header.Get("Authorization")
+		jwt := strings.TrimPrefix(auth, "Bearer ")
+		f.mu.Lock()
+		f.exchanges++
+		f.lastJWT = jwt
+		f.tokenSeq++
+		seq := f.tokenSeq
+		exp := f.expiresAt()
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusCreated)
+		json.NewEncoder(w).Encode(map[string]any{
+			"token":      fmt.Sprintf("ghs_installation_%d", seq),
+			"expires_at": exp.UTC().Format(time.RFC3339),
+		})
+	})
+	f.srv = httptest.NewServer(mux)
+	t.Cleanup(f.srv.Close)
+	return f
+}
+
+func (f *appFixture) verifyJWT(t *testing.T) {
+	t.Helper()
+	f.mu.Lock()
+	jwt := f.lastJWT
+	f.mu.Unlock()
+	parts := strings.Split(jwt, ".")
+	if len(parts) != 3 {
+		t.Fatalf("jwt not three-part: %q", jwt)
+	}
+	signingInput := parts[0] + "." + parts[1]
+	sig, err := base64.RawURLEncoding.DecodeString(parts[2])
+	if err != nil {
+		t.Fatalf("decode sig: %v", err)
+	}
+	digest := sha256.Sum256([]byte(signingInput))
+	if err := rsa.VerifyPKCS1v15(f.pub, crypto.SHA256, digest[:], sig); err != nil {
+		t.Fatalf("jwt signature invalid: %v", err)
+	}
+	var claims struct {
+		Iss string `json:"iss"`
+		Iat int64  `json:"iat"`
+		Exp int64  `json:"exp"`
+	}
+	cb, _ := base64.RawURLEncoding.DecodeString(parts[1])
+	if err := json.Unmarshal(cb, &claims); err != nil {
+		t.Fatalf("decode claims: %v", err)
+	}
+	if claims.Iss != "123" {
+		t.Fatalf("iss = %q, want 123", claims.Iss)
+	}
+	if claims.Exp-claims.Iat > int64((10*time.Minute)/time.Second) {
+		t.Fatalf("jwt lifetime exceeds 10m: iat=%d exp=%d", claims.Iat, claims.Exp)
+	}
+	if claims.Iat > time.Now().Unix() {
+		t.Fatalf("iat not backdated: %d", claims.Iat)
+	}
+}
+
+func newAppCred(t *testing.T, f *appFixture, pemKey string) *appCredential {
+	t.Helper()
+	c, err := newAppCredential(Options{
+		AppID:          "123",
+		InstallationID: "456",
+		PrivateKeyPEM:  pemKey,
+		apiBaseURL:     f.srv.URL,
+		httpClient:     f.srv.Client(),
+	})
+	if err != nil {
+		t.Fatalf("newAppCredential: %v", err)
+	}
+	return c
+}
+
+func TestApp_MintsJWTAndExchangesForInstallationToken(t *testing.T) {
+	pemKey := testRSAKeyPEM(t)
+	f := newAppFixture(t, pemKey)
+	c := newAppCred(t, f, pemKey)
+
+	tok, err := c.Token(context.Background())
+	if err != nil {
+		t.Fatalf("token: %v", err)
+	}
+	if tok != "ghs_installation_1" {
+		t.Fatalf("token = %q, want ghs_installation_1", tok)
+	}
+	if f.exchanges != 1 {
+		t.Fatalf("exchanges = %d, want 1", f.exchanges)
+	}
+	f.verifyJWT(t)
+}
+
+func TestApp_CachesInstallationToken(t *testing.T) {
+	pemKey := testRSAKeyPEM(t)
+	f := newAppFixture(t, pemKey)
+	c := newAppCred(t, f, pemKey)
+
+	for i := 0; i < 5; i++ {
+		if _, err := c.Token(context.Background()); err != nil {
+			t.Fatalf("token: %v", err)
+		}
+	}
+	if f.exchanges != 1 {
+		t.Fatalf("exchanges = %d, want 1 (token should be cached)", f.exchanges)
+	}
+}
+
+func TestApp_RefreshesNearExpiry(t *testing.T) {
+	pemKey := testRSAKeyPEM(t)
+	f := newAppFixture(t, pemKey)
+	// Token expires within refreshSkew, so every call must re-exchange.
+	f.expiresAt = func() time.Time { return time.Now().Add(2 * time.Minute) }
+	c := newAppCred(t, f, pemKey)
+
+	t1, err := c.Token(context.Background())
+	if err != nil {
+		t.Fatalf("token 1: %v", err)
+	}
+	t2, err := c.Token(context.Background())
+	if err != nil {
+		t.Fatalf("token 2: %v", err)
+	}
+	if f.exchanges != 2 {
+		t.Fatalf("exchanges = %d, want 2 (near-expiry token must refresh)", f.exchanges)
+	}
+	if t1 == t2 {
+		t.Fatalf("expected a fresh token after refresh, both = %q", t1)
+	}
+}
+
+func TestApp_ConcurrentTokenSingleFlights(t *testing.T) {
+	pemKey := testRSAKeyPEM(t)
+	f := newAppFixture(t, pemKey)
+	c := newAppCred(t, f, pemKey)
+
+	var wg sync.WaitGroup
+	for i := 0; i < 20; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if _, err := c.Token(context.Background()); err != nil {
+				t.Errorf("token: %v", err)
+			}
+		}()
+	}
+	wg.Wait()
+	if f.exchanges != 1 {
+		t.Fatalf("exchanges = %d, want 1 (concurrent calls must coalesce)", f.exchanges)
+	}
+}

internal/githubauth/credential.go

@@ -0,0 +1,106 @@
+// Package githubauth provides the process-wide GitHub machine credential used to
+// authenticate every outbound GitHub request (releases scan, ranged asset header
+// fetches, and the generic-github byte proxy for private assets). The credential
+// is delivered via env/secret only — it is never stored per-remote in the DB,
+// never returned by any API, and never logged.
+package githubauth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"sync"
+)
+
+// Credential yields a bearer token for GitHub requests. Token may block to mint
+// or refresh (the GitHub App path); an empty string means "no auth", which only
+// happens when no credential is configured.
+type Credential interface {
+	Token(ctx context.Context) (string, error)
+}
+
+// Options is the raw, env-sourced auth configuration. Exactly one mode may be
+// configured: a static token, or a GitHub App (id + installation id + private
+// key). Partial App configuration is an error (fail closed); no fields at all is
+// fine and yields a nil credential (anonymous, current behavior).
+type Options struct {
+	// Token is a Personal Access Token (fine-grained or classic) sent verbatim
+	// as "Authorization: Bearer <token>".
+	Token string
+
+	// GitHub App fields. PrivateKeyPEM and PrivateKeyPath are alternatives; the
+	// inline PEM wins when both are set.
+	AppID          string
+	InstallationID string
+	PrivateKeyPEM  string
+	PrivateKeyPath string
+
+	// apiBaseURL overrides https://api.github.com for tests. Empty uses the real
+	// endpoint. httpClient likewise overrides the default client for tests.
+	apiBaseURL string
+	httpClient httpDoer
+}
+
+// New builds the process credential from options, validating that auth is either
+// fully configured or fully absent. It returns (nil, nil) when nothing is set.
+func New(opts Options) (Credential, error) {
+	hasToken := opts.Token != ""
+	hasAppField := opts.AppID != "" || opts.InstallationID != "" ||
+		opts.PrivateKeyPEM != "" || opts.PrivateKeyPath != ""
+
+	switch {
+	case !hasToken && !hasAppField:
+		return nil, nil // no auth configured — anonymous is fine
+	case hasToken && hasAppField:
+		return nil, errors.New("github auth: both a token and GitHub App fields are set; configure exactly one")
+	case hasToken:
+		return staticToken{token: opts.Token}, nil
+	default:
+		return newAppCredential(opts)
+	}
+}
+
+// staticToken is a fixed PAT credential.
+type staticToken struct{ token string }
+
+func (s staticToken) Token(context.Context) (string, error) { return s.token, nil }
+
+// server is the process-wide credential set once at startup. A nil value means
+// no server credential (anonymous). Access is guarded so a late SetServer in a
+// test is race-free.
+var (
+	serverMu sync.RWMutex
+	server   Credential
+)
+
+// SetServer installs the process credential. Call once during startup.
+func SetServer(c Credential) {
+	serverMu.Lock()
+	server = c
+	serverMu.Unlock()
+}
+
+// Server returns the process credential, or nil if none is configured.
+func Server() Credential {
+	serverMu.RLock()
+	defer serverMu.RUnlock()
+	return server
+}
+
+// loadPrivateKeyPEM resolves the App private key bytes from the inline PEM or a
+// file path, without ever returning the key material in an error message.
+func loadPrivateKeyPEM(opts Options) ([]byte, error) {
+	if strings.TrimSpace(opts.PrivateKeyPEM) != "" {
+		return []byte(opts.PrivateKeyPEM), nil
+	}
+	if opts.PrivateKeyPath != "" {
+		b, err := os.ReadFile(opts.PrivateKeyPath)
+		if err != nil {
+			return nil, fmt.Errorf("github app: read private key file: %w", err)
+		}
+		return b, nil
+	}
+	return nil, errors.New("github app: no private key configured")
+}

internal/githubauth/credential_test.go

@@ -0,0 +1,77 @@
+package githubauth
+
+import (
+	"context"
+	"testing"
+)
+
+func TestNew_NoConfigIsAnonymous(t *testing.T) {
+	c, err := New(Options{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if c != nil {
+		t.Fatalf("expected nil credential when nothing configured, got %T", c)
+	}
+}
+
+func TestNew_TokenMode(t *testing.T) {
+	c, err := New(Options{Token: "ghp_example"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	tok, err := c.Token(context.Background())
+	if err != nil {
+		t.Fatalf("token: %v", err)
+	}
+	if tok != "ghp_example" {
+		t.Fatalf("token = %q, want ghp_example", tok)
+	}
+}
+
+func TestNew_TokenAndAppConflict(t *testing.T) {
+	_, err := New(Options{Token: "ghp_example", AppID: "123"})
+	if err == nil {
+		t.Fatal("expected error when both token and app fields are set")
+	}
+}
+
+func TestNew_PartialAppFailsClosed(t *testing.T) {
+	cases := map[string]Options{
+		"app id without key":  {AppID: "123", InstallationID: "456"},
+		"key without app id":  {InstallationID: "456", PrivateKeyPEM: testRSAKeyPEM(t)},
+		"app id without inst": {AppID: "123", PrivateKeyPEM: testRSAKeyPEM(t)},
+	}
+	for name, opts := range cases {
+		t.Run(name, func(t *testing.T) {
+			if _, err := New(opts); err == nil {
+				t.Fatalf("expected fail-closed error for %q", name)
+			}
+		})
+	}
+}
+
+func TestNew_AppModeParsesKey(t *testing.T) {
+	c, err := New(Options{
+		AppID:          "123",
+		InstallationID: "456",
+		PrivateKeyPEM:  testRSAKeyPEM(t),
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, ok := c.(*appCredential); !ok {
+		t.Fatalf("expected *appCredential, got %T", c)
+	}
+}
+
+func TestNew_AppModeRejectsBadKey(t *testing.T) {
+	_, err := New(Options{
+		AppID:          "123",
+		InstallationID: "456",
+		PrivateKeyPEM:  "-----BEGIN RSA PRIVATE KEY-----\nnope\n-----END RSA PRIVATE KEY-----",
+	})
+	if err == nil {
+		t.Fatal("expected error for malformed private key")
+	}
+}