feat: comprehensive audit + Tier 3 wiring (security/correctness/features)

Multi-agent audit + fix pass covering bugs, security, dead config wiring,
and missing features. All quality gates green: build/vet/test -race/govulncheck/
golangci-lint. Frontend tests 47/47.

SECURITY & CORRECTNESS

- Scanner pipeline fail-closed: cache.go scan timeout now 503 (was goto servePkg);
  scanner.go all-scanners-fail saves ScanStatusError; CheckVulnerabilities blocks
  on missing/error result instead of allowing.
- Scanner argv corrections: govulncheck source-mode + go.mod discovery;
  npm-audit generates lockfile via npm install --package-lock-only --ignore-scripts;
  pip-audit per-extension dispatch (wheel direct / sdist extract+pyproject).
- GHSA version-range filtering implemented (was always-include); url.QueryEscape
  on package name.
- pypi SSRF closed via host allowlist on original_url; url.QueryEscape on
  rewriteURL output.
- Path traversal: cache temp file uses os.CreateTemp; smb keyToPath sanitized;
  filesystem keyToPath returns error + filepath.Abs prefix-verify.
- Goroutine leaks plugged: cache.cleanupWorker stop channel; auth.ValidationCache
  Stop() with sync.Once; ws.unregister buffered with non-blocking send.
- WebSocket double-close panic fixed via sync.Once Client.closeSend().
- Race conditions: gormstore.registryCache sync.RWMutex (was concurrent map
  panic); auth.LastUsedAt no longer mutated under RLock; analytics strict
  lock-ordering invariant (statsMu before downloadsMu).
- Auth validator fails CLOSED on transport/unknown-status errors (was returning
  true,err 'allow cache fallback').
- Credential cache hash full SHA256 (was 8-byte truncate; eliminates 2^32
  collision risk).
- filesystem.fs.used incremented after successful rename (no quota inflation
  race).
- gormstore aggregation events deleted in same tx as insert (no double-counting).
- gormstore.SavePackage uses Updates(map) so zero-value security flags
  (RequiresAuth=false) can be cleared.
- partition_manager validates partition name regex before DROP TABLE.
- vcs/git: version regex validation rejects --option-injection; checkout uses
  --detach -- separator; removed TrimPrefix(repo,'v') that corrupted vault/
  vitess/vim-go.
- WebSocket CheckOrigin allowlist (was return true; CSWSH closed); same-origin
  default + ServerConfig.AllowedOrigins.
- fiber CVE GO-2026-4543 patched (v2.52.10 -> v2.52.12).

FUNCTIONAL FEATURES

- API key DB persistence: APIKeyModel + migration 202604280002, full CRUD,
  async LastUsedAt updates with WaitGroup-tracked goroutines drained on Close.
- Admin bootstrap via GOHOARDER_BOOTSTRAP_ADMIN_KEY env var; idempotent
  (skipped when non-revoked admin already exists).
- Auth middleware factory in pkg/app: RequireAuth, RequireRole, RequirePermission,
  OptionalAuth. Mounted on proxy + read APIs when Auth.Enabled=true.
  DELETE /api/packages/* requires admin role. /health public for k8s probes.
- NFS storage backend: pkg/storage/nfs wraps filesystem with /proc/mounts
  detection (Linux), post-write fsync, read-after-write health probe.
- WebSocket real-time pipeline: pkg/events Broadcaster interface; cache + scanner
  managers emit EventPackageCached / EventPackageDownloaded / EventScanComplete;
  app.go runs 30s EventStatsUpdate ticker. Frontend has full WS client (reconnect
  with exponential backoff 1s->30s, 25s heartbeat, subscriber pattern), Pinia
  realtime store, Dashboard live indicator + activity feed + reactive stats
  override.
- TLS termination: fiber.ListenTLS when Server.TLS.Enabled.
- Pre-warming: Prewarming.Enabled flag wired (was hardcoded false); Interval,
  MaxConcurrent, TopPackages plumbed.
- NetworkConfig wired (timeouts, retry, rate-limit, circuit-breaker).
- AuthConfig.BcryptCost wired.
- Security.Scanners.Static.MaxPackageSize plumbed to cache.io.LimitReader.
- Handlers.{Go,NPM,PyPI}.Enabled gates route mounting.
- Graceful shutdown: authManager.Close drains async writes.

LINT/HYGIENE

- 80 golangci-lint issues resolved: errcheck (Close/Write/RemoveAll wrapped),
  gofmt, gosec G104/G306, govet shadow renames + fieldalignment reorders,
  staticcheck ST1000 pkg comments + QF1003 tagged switches + QF1008 embedded
  field selectors + QF1001 De Morgan's law.

BEHAVIOR CHANGES

- Scanner now fail-closed: deployments without scanner binaries
  (trivy/govulncheck/npm-audit/pip-audit/grype) BLOCK packages instead of
  serving unscanned. Add binaries or plan a future allow-on-scan-error flag.
- WS origin defaults to same-origin; cross-origin dashboards must set
  server.allowed_origins.
- Validator no longer fails open; private packages won't serve from cache when
  validation can't be performed.
- download_events retention dropped from 24h to ~5min (deleted in agg tx).
  Migration 202604280001 purges pre-upgrade events.
- DELETE /api/packages/* requires admin role when auth enabled.

NEW PACKAGES

- pkg/events  - Broadcaster interface
- pkg/storage/nfs  - NFS-aware filesystem wrapper

DEFERRED (out of scope this pass)

- Static scanner implementation (config defines AllowedLicenses/MaxPackageSize/
  BlockSuspicious but pkg/scanner/static/ does not exist).
- AuthConfig.AuditLog wiring (no audit log infra yet).
- CacheConfig.TTLOverrides passthrough (would touch cache.Config beyond
  integrator scope).

pkg/vcs/credentials.go

@@ -1,3 +1,5 @@
+// Package vcs provides Git/VCS helpers for resolving Go modules and
+// extracting repository credentials.
 package vcs
 
 import (

pkg/vcs/git.go

@@ -6,12 +6,33 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"time"
 
 	"github.com/rs/zerolog/log"
 )
 
+// versionPattern restricts version strings to characters that cannot be
+// confused with git command-line options. We additionally reject any leading
+// '-' to defend against argv option-injection (e.g. "--upload-pack=...").
+var versionPattern = regexp.MustCompile(`^v?[0-9A-Za-z.\-+]+$`)
+
+// validateVersion ensures a user-supplied version is safe to pass as an argv
+// argument to git. Empty input and option-like prefixes are rejected.
+func validateVersion(version string) error {
+	if version == "" {
+		return fmt.Errorf("version is required")
+	}
+	if strings.HasPrefix(version, "-") {
+		return fmt.Errorf("invalid version %q: must not start with '-'", version)
+	}
+	if !versionPattern.MatchString(version) {
+		return fmt.Errorf("invalid version %q: must match %s", version, versionPattern.String())
+	}
+	return nil
+}
+
 // GitFetcher handles git repository operations
 type GitFetcher struct {
 	credStore *CredentialStore
@@ -39,6 +60,12 @@ func NewGitFetcher(workDir string, credStore *CredentialStore) *GitFetcher {
 // FetchModule clones a git repository and checks out a specific version
 // Returns the path to the checked-out source directory
 func (g *GitFetcher) FetchModule(ctx context.Context, modulePath, version, credentials string) (string, error) {
+	// Validate version before it reaches any git argv to prevent
+	// option-injection (e.g. "--upload-pack=..." passed as a "version").
+	if err := validateVersion(version); err != nil {
+		return "", err
+	}
+
 	// Create context with timeout
 	ctx, cancel := context.WithTimeout(ctx, g.timeout)
 	defer cancel()
@@ -115,8 +142,10 @@ func (g *GitFetcher) modulePathToRepoURL(modulePath string) (string, error) {
 	owner := parts[1]
 	repo := parts[2]
 
-	// Remove version suffix if present (e.g., /v2, /v3)
-	repo = strings.TrimPrefix(repo, "v")
+	// NOTE: Go module major-version suffixes appear as separate path
+	// segments (e.g. "github.com/owner/repo/v2"), never as a "v" prefix on
+	// the repo name. Stripping a leading "v" from the repo segment would
+	// corrupt legitimate names like "vault", "vitess", "vim-go".
 
 	repoURL := fmt.Sprintf("https://%s/%s/%s.git", host, owner, repo)
 	return repoURL, nil
@@ -223,7 +252,12 @@ func (g *GitFetcher) extractHost(repoURL string) string {
 
 // shallowClone performs a shallow clone of a specific version
 func (g *GitFetcher) shallowClone(ctx context.Context, repoURL, version, cloneDir string, credentialHelper map[string]string) error {
-	cmd := exec.CommandContext(ctx, "git", "clone", "--depth", "1", "--branch", version, repoURL, cloneDir)
+	if err := validateVersion(version); err != nil {
+		return err
+	}
+	// "--" separates options from positional args; combined with version
+	// validation it prevents option-injection.
+	cmd := exec.CommandContext(ctx, "git", "clone", "--depth", "1", "--branch", version, "--", repoURL, cloneDir)
 	cmd.Env = append(os.Environ(), g.envMapToSlice(credentialHelper)...)
 
 	output, err := cmd.CombinedOutput()
@@ -236,7 +270,7 @@ func (g *GitFetcher) shallowClone(ctx context.Context, repoURL, version, cloneDi
 
 // fullClone performs a full clone of the repository
 func (g *GitFetcher) fullClone(ctx context.Context, repoURL, cloneDir string, credentialHelper map[string]string) error {
-	cmd := exec.CommandContext(ctx, "git", "clone", repoURL, cloneDir)
+	cmd := exec.CommandContext(ctx, "git", "clone", "--", repoURL, cloneDir)
 	cmd.Env = append(os.Environ(), g.envMapToSlice(credentialHelper)...)
 
 	output, err := cmd.CombinedOutput()
@@ -247,9 +281,15 @@ func (g *GitFetcher) fullClone(ctx context.Context, repoURL, cloneDir string, cr
 	return nil
 }
 
-// checkout checks out a specific version (tag, branch, or commit)
+// checkout checks out a specific version (tag, branch, or commit) in
+// detached-HEAD mode. Detached mode avoids ambiguity between local branch
+// refs and remote tags/commits and prevents creating unintended local
+// branches when the version happens to share a name with one.
 func (g *GitFetcher) checkout(ctx context.Context, repoDir, version string) error {
-	cmd := exec.CommandContext(ctx, "git", "checkout", version)
+	if err := validateVersion(version); err != nil {
+		return err
+	}
+	cmd := exec.CommandContext(ctx, "git", "checkout", "--detach", "--", version)
 	cmd.Dir = repoDir
 	cmd.Env = append(os.Environ(), "GIT_TERMINAL_PROMPT=0")
 

pkg/vcs/module.go

@@ -57,7 +57,7 @@ func (b *ModuleBuilder) BuildModuleZip(ctx context.Context, srcPath, modulePath,
 	prefix := fmt.Sprintf("%s@%s/", modulePath, version)
 	for _, relPath := range files {
 		if err := b.addFileToZip(zipWriter, srcPath, relPath, prefix); err != nil {
-			zipWriter.Close() // #nosec G104 -- Cleanup, error not critical
+			_ = zipWriter.Close() // #nosec G104 -- best-effort cleanup on error path
 			return nil, fmt.Errorf("failed to add file %s: %w", relPath, err)
 		}
 	}
@@ -152,7 +152,7 @@ func (b *ModuleBuilder) addFileToZip(zipWriter *zip.Writer, srcPath, relPath, pr
 	if err != nil {
 		return err
 	}
-	defer file.Close() // #nosec G104 -- Cleanup, error not critical
+	defer func() { _ = file.Close() }() // #nosec G104 -- read-only file, close error not actionable
 
 	if _, err := io.Copy(writer, file); err != nil {
 		return err