refactor: modular local provider interfaces (#52)

## Summary
Move package-type-specific local repo logic out of centralized handlers into provider packages via optional Go interfaces.

**New interfaces in `provider` package:**
- \`LocalUploader\`: \`ValidateUpload(filePath) → (storagePath, contentType, error)\` + \`UploadResponse(...)\`
- \`LocalIndexer\`: \`ServeLocalIndex(w, r, files, repoName, path) → bool\` + \`GenerateLocalIndex(ctx, files, repoName, path) → ([]byte, error)\`
- \`FileStore\`: \`ListFilesByPrefix\` + \`ListPackages\` (implemented by database.DB)

**Providers implement these interfaces:**
- PyPI: upload validation (wheel/sdist naming), simple index serving + generation
- Terraform: upload validation (provider zip naming), mirror protocol serving

**Handlers simplified to generic dispatch:**
- \`local.go\`: type-asserts to \`LocalUploader\`, falls back to generic upload
- \`proxy.go\`: type-asserts to \`LocalIndexer\`, falls back to raw file serving
- \`engine.go\`: type-asserts to \`LocalIndexer\` for local virtual members

Adding a new local repo type (e.g. RPM) = implement the interfaces in its provider package. Zero handler changes.

## Test plan
- [x] Build + unit tests pass
- [x] E2E: PyPI local upload → simple index → uv pip install (smoke test after refactor)

Reviewed-on: #52
Co-authored-by: Ben Vincent <ben@unkin.net>
Co-committed-by: Ben Vincent <ben@unkin.net>

internal/api/v1/proxy.go

@@ -6,8 +6,6 @@ import (
 	"io"
 	"log/slog"
 	"net/http"
-	"regexp"
-	"strings"
 
 	"github.com/go-chi/chi/v5"
 
@@ -17,11 +15,8 @@ import (
 	"git.unkin.net/unkin/artifactapi/internal/proxy"
 	"git.unkin.net/unkin/artifactapi/internal/storage"
 	"git.unkin.net/unkin/artifactapi/internal/virtual"
-	"git.unkin.net/unkin/artifactapi/pkg/models"
 )
 
-var semverRe = regexp.MustCompile(`^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.]+)?$`)
-
 type ProxyHandler struct {
 	engine        *proxy.Engine
 	virtualEngine *virtual.Engine
@@ -115,8 +110,9 @@ func (h *ProxyHandler) handleLocal(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if remote.PackageType == models.PackageTerraform {
+	prov, _ := provider.Get(remote.PackageType)
-		if h.serveTerraformMirror(w, r, remote, path) {
+	if indexer, ok := prov.(provider.LocalIndexer); ok {
+		if indexer.ServeLocalIndex(w, r, h.db, remote.Name, path) {
 			return
 		}
 	}
@@ -124,31 +120,6 @@ func (h *ProxyHandler) handleLocal(w http.ResponseWriter, r *http.Request) {
 	h.serveLocalFile(w, r, localName, path)
 }
 
-func (h *ProxyHandler) serveTerraformMirror(w http.ResponseWriter, r *http.Request, remote *models.Remote, path string) bool {
-	parts := strings.Split(path, "/")
-	if len(parts) < 3 {
-		return false
-	}
-
-	namespace, typeName := parts[0], parts[1]
-	tail := parts[2]
-
-	if tail == "index.json" {
-		h.local.ServeTerraformIndex(w, r, remote.Name, namespace, typeName)
-		return true
-	}
-
-	if strings.HasSuffix(tail, ".json") {
-		version := strings.TrimSuffix(tail, ".json")
-		if semverRe.MatchString(version) {
-			h.local.ServeTerraformVersionDoc(w, r, remote.Name, namespace, typeName, version)
-			return true
-		}
-	}
-
-	return false
-}
-
 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 {

internal/api/v2/local.go

@@ -1,25 +1,19 @@
 package v2
 
 import (
-	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"net/http"
-	"regexp"
-	"strings"
 
 	"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"
 )
 
-var providerZipRe = regexp.MustCompile(
-	`^terraform-provider-([a-zA-Z0-9_-]+)_([0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.]+)?)_([a-z0-9]+)_([a-z0-9]+)\.zip$`,
-)
-
 type LocalHandler struct {
 	db    *database.DB
 	store *storage.S3
@@ -61,41 +55,22 @@ func (h *LocalHandler) upload(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if remote.PackageType == models.PackageTerraform {
+	prov, _ := provider.Get(remote.PackageType)
-		h.uploadTerraformProvider(w, r, remote, filePath)
+
+	if uploader, ok := prov.(provider.LocalUploader); ok {
+		h.uploadValidated(w, r, remote, filePath, uploader)
 		return
 	}
 
 	h.uploadGeneric(w, r, remote, filePath)
 }
 
-func (h *LocalHandler) uploadTerraformProvider(w http.ResponseWriter, r *http.Request, remote *models.Remote, filePath string) {
+func (h *LocalHandler) uploadValidated(w http.ResponseWriter, r *http.Request, remote *models.Remote, filePath string, uploader provider.LocalUploader) {
-	parts := strings.Split(filePath, "/")
+	storagePath, contentType, err := uploader.ValidateUpload(filePath)
-	if len(parts) != 3 {
+	if err != nil {
-		http.Error(w, "path must be {namespace}/{type}/{filename}.zip", http.StatusBadRequest)
+		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
 	}
-	namespace, typeName, filename := parts[0], parts[1], parts[2]
-
-	m := providerZipRe.FindStringSubmatch(filename)
-	if m == nil {
-		http.Error(w, fmt.Sprintf(
-			"filename %q does not match terraform-provider-{type}_{version}_{os}_{arch}.zip",
-			filename,
-		), http.StatusBadRequest)
-		return
-	}
-	fileType, version, os, arch := m[1], m[2], m[3], m[4]
-
-	if fileType != typeName {
-		http.Error(w, fmt.Sprintf(
-			"provider type in filename %q does not match path type %q",
-			fileType, typeName,
-		), http.StatusBadRequest)
-		return
-	}
-
-	storagePath := fmt.Sprintf("%s/%s/%s", namespace, typeName, filename)
 
 	existing, err := h.db.GetLocalFile(r.Context(), remote.Name, storagePath)
 	if err != nil {
@@ -103,20 +78,17 @@ func (h *LocalHandler) uploadTerraformProvider(w http.ResponseWriter, r *http.Re
 		return
 	}
 	if existing != nil {
-		http.Error(w, fmt.Sprintf(
+		http.Error(w, fmt.Sprintf("file %q already exists; overwrites are not allowed", storagePath), http.StatusConflict)
-			"provider %s/%s version %s for %s_%s already exists; overwrites are not allowed",
-			namespace, typeName, version, os, arch,
-		), http.StatusConflict)
 		return
 	}
 
-	result, err := h.cas.Store(r.Context(), r.Body, "application/zip")
+	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, "application/zip"); err != nil {
+	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
 	}
@@ -130,15 +102,7 @@ func (h *LocalHandler) uploadTerraformProvider(w http.ResponseWriter, r *http.Re
 		return
 	}
 
-	writeJSON(w, http.StatusCreated, map[string]any{
+	writeJSON(w, http.StatusCreated, uploader.UploadResponse(storagePath, result.ContentHash, result.SizeBytes))
-		"namespace":    namespace,
-		"type":         typeName,
-		"version":      version,
-		"os":           os,
-		"arch":         arch,
-		"content_hash": result.ContentHash,
-		"size_bytes":   result.SizeBytes,
-	})
 }
 
 func (h *LocalHandler) uploadGeneric(w http.ResponseWriter, r *http.Request, remote *models.Remote, filePath string) {
@@ -223,74 +187,6 @@ func (h *LocalHandler) remove(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
-type terraformIndex struct {
+func (h *LocalHandler) DB() *database.DB {
-	Versions map[string]json.RawMessage `json:"versions"`
+	return h.db
-}
-
-type terraformVersionDoc struct {
-	Archives map[string]terraformArchive `json:"archives"`
-}
-
-type terraformArchive struct {
-	URL    string   `json:"url"`
-	Hashes []string `json:"hashes,omitempty"`
-}
-
-func (h *LocalHandler) ServeTerraformIndex(w http.ResponseWriter, r *http.Request, repoName, namespace, typeName string) {
-	prefix := fmt.Sprintf("%s/%s/", namespace, typeName)
-	files, err := h.db.ListLocalFilesByPrefix(r.Context(), repoName, prefix)
-	if err != nil {
-		http.Error(w, err.Error(), http.StatusInternalServerError)
-		return
-	}
-
-	versions := map[string]json.RawMessage{}
-	for _, f := range files {
-		filename := strings.TrimPrefix(f.FilePath, prefix)
-		m := providerZipRe.FindStringSubmatch(filename)
-		if m == nil {
-			continue
-		}
-		versions[m[2]] = json.RawMessage(`{}`)
-	}
-
-	if len(versions) == 0 {
-		http.Error(w, "not found", http.StatusNotFound)
-		return
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(terraformIndex{Versions: versions})
-}
-
-func (h *LocalHandler) ServeTerraformVersionDoc(w http.ResponseWriter, r *http.Request, repoName, namespace, typeName, version string) {
-	prefix := fmt.Sprintf("%s/%s/terraform-provider-%s_%s_", namespace, typeName, typeName, version)
-	files, err := h.db.ListLocalFilesByPrefix(r.Context(), repoName, prefix)
-	if err != nil {
-		http.Error(w, err.Error(), http.StatusInternalServerError)
-		return
-	}
-
-	archives := map[string]terraformArchive{}
-	for _, f := range files {
-		filename := strings.TrimPrefix(f.FilePath, fmt.Sprintf("%s/%s/", namespace, typeName))
-		m := providerZipRe.FindStringSubmatch(filename)
-		if m == nil || m[2] != version {
-			continue
-		}
-		platform := m[3] + "_" + m[4]
-		archive := terraformArchive{URL: filename}
-		if f.ContentHash != "" {
-			archive.Hashes = []string{"zh:" + strings.TrimPrefix(f.ContentHash, "sha256:")}
-		}
-		archives[platform] = archive
-	}
-
-	if len(archives) == 0 {
-		http.Error(w, "not found", http.StatusNotFound)
-		return
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(terraformVersionDoc{Archives: archives})
 }

internal/database/local_files.go

@@ -8,6 +8,8 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgconn"
+
+	"git.unkin.net/unkin/artifactapi/internal/provider"
 )
 
 type LocalFile struct {
@@ -99,6 +101,45 @@ func (db *DB) ListLocalFilesByPrefix(ctx context.Context, repoName, prefix strin
 	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/provider/provider.go

@@ -24,6 +24,26 @@ type Provider interface {
 	AuthHeaders(ctx context.Context, remote models.Remote) (http.Header, error)
 }
 
+type FileEntry struct {
+	FilePath    string
+	ContentHash string
+}
+
+type FileStore interface {
+	ListFilesByPrefix(ctx context.Context, repoName, prefix string) ([]FileEntry, error)
+	ListPackages(ctx context.Context, repoName string) ([]string, error)
+}
+
+type LocalUploader interface {
+	ValidateUpload(filePath string) (storagePath, contentType string, err error)
+	UploadResponse(storagePath, contentHash string, sizeBytes int64) map[string]any
+}
+
+type LocalIndexer interface {
+	ServeLocalIndex(w http.ResponseWriter, r *http.Request, files FileStore, repoName, path string) bool
+	GenerateLocalIndex(ctx context.Context, files FileStore, repoName, path string) ([]byte, error)
+}
+
 type IndexMerger interface {
 	MergeIndexes(members []MemberIndex, proxyBaseURL string) ([]byte, error)
 }

internal/provider/pypi/pypi.go

@@ -2,7 +2,10 @@ package pypi
 
 import (
 	"context"
+	"fmt"
+	"io"
 	"net/http"
+	"regexp"
 	"strings"
 
 	"git.unkin.net/unkin/artifactapi/internal/auth"
@@ -14,6 +17,9 @@ func init() {
 	provider.Register(&Provider{})
 }
 
+var fileRe = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]*\.(whl|tar\.gz|zip)$`)
+var normalizeRe = regexp.MustCompile(`[-_.]+`)
+
 type Provider struct{}
 
 func (p *Provider) Type() models.PackageType { return models.PackagePyPI }
@@ -60,3 +66,177 @@ func (p *Provider) RewriteResponse(body []byte, remote models.Remote, proxyBaseU
 func (p *Provider) AuthHeaders(_ context.Context, remote models.Remote) (http.Header, error) {
 	return auth.BasicHeaders(remote), nil
 }
+
+func normalize(name string) string {
+	return strings.ToLower(normalizeRe.ReplaceAllString(name, "-"))
+}
+
+func packageFromWheel(filename string) string {
+	parts := strings.SplitN(filename, "-", 3)
+	if len(parts) < 2 {
+		return ""
+	}
+	return normalize(parts[0])
+}
+
+func packageFromSdist(filename string) string {
+	name := filename
+	for _, suffix := range []string{".tar.gz", ".zip"} {
+		if strings.HasSuffix(name, suffix) {
+			name = strings.TrimSuffix(name, suffix)
+			break
+		}
+	}
+	idx := strings.LastIndex(name, "-")
+	if idx <= 0 {
+		return ""
+	}
+	return normalize(name[:idx])
+}
+
+func (p *Provider) ValidateUpload(filePath string) (storagePath, contentType string, err error) {
+	filename := filePath
+	if idx := strings.LastIndex(filePath, "/"); idx >= 0 {
+		filename = filePath[idx+1:]
+	}
+
+	if !fileRe.MatchString(filename) {
+		return "", "", fmt.Errorf("filename %q must be a .whl, .tar.gz, or .zip file", filename)
+	}
+
+	var pkgName string
+	if strings.HasSuffix(filename, ".whl") {
+		pkgName = packageFromWheel(filename)
+	} else {
+		pkgName = packageFromSdist(filename)
+	}
+	if pkgName == "" {
+		return "", "", fmt.Errorf("cannot parse package name from %q", filename)
+	}
+
+	ct := "application/zip"
+	if strings.HasSuffix(filename, ".tar.gz") {
+		ct = "application/gzip"
+	}
+
+	return pkgName + "/" + filename, ct, nil
+}
+
+func (p *Provider) UploadResponse(storagePath, contentHash string, sizeBytes int64) map[string]any {
+	parts := strings.SplitN(storagePath, "/", 2)
+	filename := storagePath
+	if len(parts) == 2 {
+		filename = parts[1]
+	}
+	return map[string]any{
+		"package":      parts[0],
+		"filename":     filename,
+		"content_hash": contentHash,
+		"size_bytes":   sizeBytes,
+	}
+}
+
+func (p *Provider) ServeLocalIndex(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName, path string) bool {
+	if path == "simple" || path == "simple/" {
+		p.servePackageList(w, r, files, repoName)
+		return true
+	}
+
+	if strings.HasPrefix(path, "simple/") {
+		pkg := strings.TrimPrefix(path, "simple/")
+		pkg = strings.TrimSuffix(pkg, "/")
+		if pkg != "" && !strings.Contains(pkg, "/") {
+			p.servePackageFiles(w, r, files, repoName, pkg)
+			return true
+		}
+	}
+
+	return false
+}
+
+func (p *Provider) GenerateLocalIndex(ctx context.Context, files provider.FileStore, repoName, path string) ([]byte, error) {
+	if !strings.HasPrefix(path, "simple/") {
+		return nil, fmt.Errorf("unsupported index path: %q", path)
+	}
+
+	pkg := strings.TrimPrefix(path, "simple/")
+	pkg = strings.TrimSuffix(pkg, "/")
+	if pkg == "" {
+		return p.generatePackageListHTML(ctx, files, repoName)
+	}
+	return p.generatePackageFilesHTML(ctx, files, repoName, pkg)
+}
+
+func (p *Provider) servePackageList(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName string) {
+	body, err := p.generatePackageListHTML(r.Context(), files, repoName)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "text/html")
+	w.WriteHeader(http.StatusOK)
+	w.Write(body)
+}
+
+func (p *Provider) servePackageFiles(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName, packageName string) {
+	normalized := normalize(packageName)
+	prefix := normalized + "/"
+	entries, err := files.ListFilesByPrefix(r.Context(), repoName, prefix)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+	if len(entries) == 0 {
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
+	var b strings.Builder
+	b.WriteString("<!DOCTYPE html>\n<html><body>\n")
+	for _, f := range entries {
+		filename := strings.TrimPrefix(f.FilePath, normalized+"/")
+		hash := strings.TrimPrefix(f.ContentHash, "sha256:")
+		fmt.Fprintf(&b, "<a href=\"../../%s/%s#sha256=%s\">%s</a>\n",
+			normalized, filename, hash, filename)
+	}
+	b.WriteString("</body></html>\n")
+
+	w.Header().Set("Content-Type", "text/html")
+	w.WriteHeader(http.StatusOK)
+	io.WriteString(w, b.String())
+}
+
+func (p *Provider) generatePackageListHTML(ctx context.Context, files provider.FileStore, repoName string) ([]byte, error) {
+	packages, err := files.ListPackages(ctx, repoName)
+	if err != nil {
+		return nil, err
+	}
+
+	var b strings.Builder
+	b.WriteString("<!DOCTYPE html>\n<html><body>\n")
+	for _, pkg := range packages {
+		fmt.Fprintf(&b, "<a href=\"%s/\">%s</a>\n", pkg, pkg)
+	}
+	b.WriteString("</body></html>\n")
+	return []byte(b.String()), nil
+}
+
+func (p *Provider) generatePackageFilesHTML(ctx context.Context, files provider.FileStore, repoName, packageName string) ([]byte, error) {
+	normalized := normalize(packageName)
+	prefix := normalized + "/"
+	entries, err := files.ListFilesByPrefix(ctx, repoName, prefix)
+	if err != nil {
+		return nil, err
+	}
+
+	var b strings.Builder
+	b.WriteString("<!DOCTYPE html>\n<html><body>\n")
+	for _, f := range entries {
+		filename := strings.TrimPrefix(f.FilePath, normalized+"/")
+		hash := strings.TrimPrefix(f.ContentHash, "sha256:")
+		fmt.Fprintf(&b, "<a href=\"%s/%s#sha256=%s\">%s</a>\n",
+			normalized, filename, hash, filename)
+	}
+	b.WriteString("</body></html>\n")
+	return []byte(b.String()), nil
+}

internal/provider/terraform/terraform.go

@@ -3,6 +3,7 @@ package terraform
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"net/url"
 	"regexp"
@@ -19,6 +20,12 @@ func init() {
 
 var versionsRe = regexp.MustCompile(`[^/]+/[^/]+/versions$`)
 
+var providerZipRe = regexp.MustCompile(
+	`^terraform-provider-([a-zA-Z0-9_-]+)_([0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.]+)?)_([a-z0-9]+)_([a-z0-9]+)\.zip$`,
+)
+
+var semverRe = regexp.MustCompile(`^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9.]+)?$`)
+
 type Provider struct{}
 
 func (p *Provider) Type() models.PackageType { return models.PackageTerraform }
@@ -86,3 +93,145 @@ func rewriteDownloadURL(originalURL, releasesRemote, proxyBaseURL string) string
 func (p *Provider) AuthHeaders(_ context.Context, remote models.Remote) (http.Header, error) {
 	return auth.BasicHeaders(remote), nil
 }
+
+func (p *Provider) ValidateUpload(filePath string) (storagePath, contentType string, err error) {
+	parts := strings.Split(filePath, "/")
+	if len(parts) != 3 {
+		return "", "", fmt.Errorf("path must be {namespace}/{type}/{filename}.zip")
+	}
+	namespace, typeName, filename := parts[0], parts[1], parts[2]
+
+	m := providerZipRe.FindStringSubmatch(filename)
+	if m == nil {
+		return "", "", fmt.Errorf("filename %q does not match terraform-provider-{type}_{version}_{os}_{arch}.zip", filename)
+	}
+
+	if m[1] != typeName {
+		return "", "", fmt.Errorf("provider type in filename %q does not match path type %q", m[1], typeName)
+	}
+
+	return fmt.Sprintf("%s/%s/%s", namespace, typeName, filename), "application/zip", nil
+}
+
+func (p *Provider) UploadResponse(storagePath, contentHash string, sizeBytes int64) map[string]any {
+	parts := strings.Split(storagePath, "/")
+	if len(parts) != 3 {
+		return map[string]any{"path": storagePath, "content_hash": contentHash, "size_bytes": sizeBytes}
+	}
+
+	m := providerZipRe.FindStringSubmatch(parts[2])
+	if m == nil {
+		return map[string]any{"path": storagePath, "content_hash": contentHash, "size_bytes": sizeBytes}
+	}
+
+	return map[string]any{
+		"namespace":    parts[0],
+		"type":         parts[1],
+		"version":      m[2],
+		"os":           m[3],
+		"arch":         m[4],
+		"content_hash": contentHash,
+		"size_bytes":   sizeBytes,
+	}
+}
+
+type terraformIndex struct {
+	Versions map[string]json.RawMessage `json:"versions"`
+}
+
+type terraformVersionDoc struct {
+	Archives map[string]terraformArchive `json:"archives"`
+}
+
+type terraformArchive struct {
+	URL    string   `json:"url"`
+	Hashes []string `json:"hashes,omitempty"`
+}
+
+func (p *Provider) ServeLocalIndex(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName, path string) bool {
+	parts := strings.Split(path, "/")
+	if len(parts) < 3 {
+		return false
+	}
+
+	namespace, typeName := parts[0], parts[1]
+	tail := parts[2]
+
+	if tail == "index.json" {
+		p.serveIndex(w, r, files, repoName, namespace, typeName)
+		return true
+	}
+
+	if strings.HasSuffix(tail, ".json") {
+		version := strings.TrimSuffix(tail, ".json")
+		if semverRe.MatchString(version) {
+			p.serveVersionDoc(w, r, files, repoName, namespace, typeName, version)
+			return true
+		}
+	}
+
+	return false
+}
+
+func (p *Provider) GenerateLocalIndex(ctx context.Context, files provider.FileStore, repoName, path string) ([]byte, error) {
+	return nil, fmt.Errorf("terraform local index generation for virtual repos not supported")
+}
+
+func (p *Provider) serveIndex(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName, namespace, typeName string) {
+	prefix := fmt.Sprintf("%s/%s/", namespace, typeName)
+	entries, err := files.ListFilesByPrefix(r.Context(), repoName, prefix)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	versions := map[string]json.RawMessage{}
+	for _, f := range entries {
+		filename := strings.TrimPrefix(f.FilePath, prefix)
+		m := providerZipRe.FindStringSubmatch(filename)
+		if m == nil {
+			continue
+		}
+		versions[m[2]] = json.RawMessage(`{}`)
+	}
+
+	if len(versions) == 0 {
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(terraformIndex{Versions: versions})
+}
+
+func (p *Provider) serveVersionDoc(w http.ResponseWriter, r *http.Request, files provider.FileStore, repoName, namespace, typeName, version string) {
+	prefix := fmt.Sprintf("%s/%s/terraform-provider-%s_%s_", namespace, typeName, typeName, version)
+	entries, err := files.ListFilesByPrefix(r.Context(), repoName, prefix)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	archives := map[string]terraformArchive{}
+	for _, f := range entries {
+		filename := strings.TrimPrefix(f.FilePath, fmt.Sprintf("%s/%s/", namespace, typeName))
+		m := providerZipRe.FindStringSubmatch(filename)
+		if m == nil || m[2] != version {
+			continue
+		}
+		platform := m[3] + "_" + m[4]
+		archive := terraformArchive{URL: filename}
+		if f.ContentHash != "" {
+			archive.Hashes = []string{"zh:" + strings.TrimPrefix(f.ContentHash, "sha256:")}
+		}
+		archives[platform] = archive
+	}
+
+	if len(archives) == 0 {
+		http.Error(w, "not found", http.StatusNotFound)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(terraformVersionDoc{Archives: archives})
+}

internal/server/server.go

@@ -34,14 +34,15 @@ import (
 )
 
 type Server struct {
-	cfg        *config.Config
+	cfg          *config.Config
-	router     chi.Router
+	router       chi.Router
-	db         *database.DB
+	db           *database.DB
-	cache      *cache.Redis
+	cache        *cache.Redis
-	store      *storage.S3
+	store        *storage.S3
-	engine     *proxy.Engine
+	engine       *proxy.Engine
-	virtEngine *virtual.Engine
+	virtEngine   *virtual.Engine
-	gc         *gc.Collector
+	localHandler *v2.LocalHandler
+	gc           *gc.Collector
 }
 
 func New(cfg *config.Config) (*Server, error) {
@@ -61,17 +62,19 @@ func New(cfg *config.Config) (*Server, error) {
 	}
 
 	engine := proxy.NewEngine(db, redis, s3)
+	localHandler := v2.NewLocalHandler(db, s3)
 	virtEngine := virtual.NewEngine(db, engine)
 	collector := gc.New(db, s3, 1*time.Hour)
 
 	s := &Server{
-		cfg:        cfg,
+		cfg:          cfg,
-		db:         db,
+		db:           db,
-		cache:      redis,
+		cache:        redis,
-		store:      s3,
+		store:        s3,
-		engine:     engine,
+		engine:       engine,
-		virtEngine: virtEngine,
+		virtEngine:   virtEngine,
-		gc:         collector,
+		localHandler: localHandler,
+		gc:           collector,
 	}
 
 	s.router = s.routes()
@@ -91,9 +94,7 @@ func (s *Server) routes() chi.Router {
 	r.Get("/health", s.handleHealth)
 	r.Get("/", s.handleRoot)
 
-	localHandler := v2.NewLocalHandler(s.db, s.store)
+	proxyHandler := v1.NewProxyHandler(s.engine, s.virtEngine, s.db, s.store, s.localHandler)
-
-	proxyHandler := v1.NewProxyHandler(s.engine, s.virtEngine, s.db, s.store, localHandler)
 	r.Mount("/api/v1", proxyHandler.Routes())
 
 	remotesHandler := v2.NewRemotesHandler(s.db)
@@ -118,9 +119,9 @@ func (s *Server) routes() chi.Router {
 		})
 
 		r.Route("/remotes/{name}/files", func(r chi.Router) {
-			r.Put("/*", localHandler.Routes().ServeHTTP)
+			r.Put("/*", s.localHandler.Routes().ServeHTTP)
-			r.Get("/*", localHandler.Routes().ServeHTTP)
+			r.Get("/*", s.localHandler.Routes().ServeHTTP)
-			r.Delete("/*", localHandler.Routes().ServeHTTP)
+			r.Delete("/*", s.localHandler.Routes().ServeHTTP)
 		})
 	})
 

internal/virtual/engine.go

@@ -73,6 +73,16 @@ func (e *Engine) fetchMemberIndexes(ctx context.Context, virt models.Virtual, pa
 				return
 			}
 
+			if remote.RepoType == models.RepoTypeLocal {
+				body, err := e.fetchLocalIndex(ctx, *remote, path)
+				if err != nil {
+					results[idx] = result{err: fmt.Errorf("local index %q: %w", name, err)}
+					return
+				}
+				results[idx] = result{index: MemberIndex{RemoteName: name, RepoType: remote.RepoType, Body: body}}
+				return
+			}
+
 			prov, err := provider.Get(remote.PackageType)
 			if err != nil {
 				results[idx] = result{err: fmt.Errorf("provider %q: %w", remote.PackageType, err)}
@@ -92,7 +102,7 @@ func (e *Engine) fetchMemberIndexes(ctx context.Context, virt models.Virtual, pa
 				return
 			}
 
-			results[idx] = result{index: MemberIndex{RemoteName: name, Body: body}}
+			results[idx] = result{index: MemberIndex{RemoteName: name, RepoType: remote.RepoType, Body: body}}
 		}(i, memberName)
 	}
 
@@ -109,3 +119,17 @@ func (e *Engine) fetchMemberIndexes(ctx context.Context, virt models.Virtual, pa
 
 	return members, nil
 }
+
+func (e *Engine) fetchLocalIndex(ctx context.Context, remote models.Remote, path string) ([]byte, error) {
+	prov, err := provider.Get(remote.PackageType)
+	if err != nil {
+		return nil, fmt.Errorf("no provider for %q: %w", remote.PackageType, err)
+	}
+
+	indexer, ok := prov.(provider.LocalIndexer)
+	if !ok {
+		return nil, fmt.Errorf("provider %q does not support local index generation", remote.PackageType)
+	}
+
+	return indexer.GenerateLocalIndex(ctx, e.db, remote.Name, path)
+}

internal/virtual/merger.go

@@ -8,6 +8,7 @@ import (
 
 type MemberIndex struct {
 	RemoteName string
+	RepoType   models.RepoType
 	Body       []byte
 }
 

internal/virtual/pypi_merger.go

@@ -36,8 +36,13 @@ func (m *PyPIMerger) MergeIndexes(members []MemberIndex, proxyBaseURL string) ([
 			}
 
 			if proxyBaseURL != "" && href != "" {
-				href = fmt.Sprintf("%s/api/v1/remote/%s/%s",
+				routePrefix := "remote"
+				if member.RepoType == "local" {
+					routePrefix = "local"
+				}
+				href = fmt.Sprintf("%s/api/v1/%s/%s/%s",
 					strings.TrimRight(proxyBaseURL, "/"),
+					routePrefix,
 					member.RemoteName,
 					strings.TrimLeft(href, "/"))
 			}