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/proxy/npm/npm.go

@@ -1,3 +1,5 @@
+// Package npm implements the HTTP handler that proxies npm registry
+// requests through the GoHoarder cache.
 package npm
 
 import (
@@ -79,12 +81,12 @@ func (h *Handler) handleMetadata(ctx context.Context, w http.ResponseWriter, r *
 	packageName := extractPackageName(path)
 
 	entry, err := h.cache.Get(ctx, "npm", packageName, "metadata", func(ctx context.Context) (io.ReadCloser, string, error) {
-		body, statusCode, err := h.client.Get(ctx, url, nil)
-		if err != nil {
-			return nil, "", err
+		body, statusCode, fetchErr := h.client.Get(ctx, url, nil)
+		if fetchErr != nil {
+			return nil, "", fetchErr
 		}
 		if statusCode != http.StatusOK {
-			body.Close() // #nosec G104 -- Cleanup, error not critical
+			_ = body.Close()
 			return nil, "", fmt.Errorf("upstream returned status %d", statusCode)
 		}
 		return body, url, nil
@@ -95,20 +97,24 @@ func (h *Handler) handleMetadata(ctx context.Context, w http.ResponseWriter, r *
 		http.Error(w, "Failed to fetch package metadata", http.StatusBadGateway)
 		return
 	}
-	defer entry.Data.Close() // #nosec G104 -- Cleanup, error not critical
+	defer func() {
+		if cerr := entry.Data.Close(); cerr != nil {
+			log.Warn().Err(cerr).Msg("Failed to close NPM metadata body")
+		}
+	}()
 
 	// Read metadata into memory for URL rewriting
 	var buf bytes.Buffer
-	if _, err := io.Copy(&buf, entry.Data); err != nil {
-		log.Error().Err(err).Msg("Failed to read metadata")
+	if _, copyErr := io.Copy(&buf, entry.Data); copyErr != nil {
+		log.Error().Err(copyErr).Msg("Failed to read metadata")
 		http.Error(w, "Failed to read metadata", http.StatusInternalServerError)
 		return
 	}
 
 	// Parse JSON metadata
 	var metadata map[string]interface{}
-	if err := json.Unmarshal(buf.Bytes(), &metadata); err != nil {
-		log.Error().Err(err).Msg("Failed to parse metadata JSON")
+	if jsonErr := json.Unmarshal(buf.Bytes(), &metadata); jsonErr != nil {
+		log.Error().Err(jsonErr).Msg("Failed to parse metadata JSON")
 		http.Error(w, "Failed to parse metadata", http.StatusInternalServerError)
 		return
 	}
@@ -138,8 +144,10 @@ func (h *Handler) handleTarball(ctx context.Context, w http.ResponseWriter, r *h
 	credHash := h.credHasher.Hash(credentials)
 
 	// Construct proper upstream URL with /-/ format
-	// Format: https://registry.npmjs.org/package/-/package-version.tgz
-	tarballFilename := strings.ReplaceAll(packageName, "/", "-") + "-" + version + ".tgz"
+	// Format: https://registry.npmjs.org/<package>/-/<filename>
+	// For unscoped: filename is "<package>-<version>.tgz"
+	// For scoped @scope/pkg: filename is "<pkg>-<version>.tgz" (no scope, no leading @)
+	tarballFilename := tarballPrefix(packageName) + version + ".tgz"
 	url := fmt.Sprintf("%s/%s/-/%s", h.upstream, packageName, tarballFilename)
 
 	log.Debug().
@@ -159,12 +167,12 @@ func (h *Handler) handleTarball(ctx context.Context, w http.ResponseWriter, r *h
 			headers["Authorization"] = credentials
 		}
 
-		body, statusCode, err := h.client.Get(ctx, url, headers)
-		if err != nil {
-			return nil, "", err
+		body, statusCode, fetchErr := h.client.Get(ctx, url, headers)
+		if fetchErr != nil {
+			return nil, "", fetchErr
 		}
 		if statusCode != http.StatusOK {
-			body.Close() // #nosec G104 -- Cleanup, error not critical
+			_ = body.Close()
 			return nil, "", fmt.Errorf("upstream returned status %d", statusCode)
 		}
 		return body, url, nil
@@ -183,7 +191,11 @@ func (h *Handler) handleTarball(ctx context.Context, w http.ResponseWriter, r *h
 		http.Error(w, "Failed to fetch package tarball", http.StatusBadGateway)
 		return
 	}
-	defer entry.Data.Close() // #nosec G104 -- Cleanup, error not critical
+	defer func() {
+		if cerr := entry.Data.Close(); cerr != nil {
+			log.Warn().Err(cerr).Msg("Failed to close NPM tarball body")
+		}
+	}()
 
 	// CRITICAL SECURITY CHECK: If package requires auth, validate credentials
 	if entry.Package != nil && entry.Package.RequiresAuth {
@@ -251,7 +263,11 @@ func (h *Handler) handleSpecial(ctx context.Context, w http.ResponseWriter, r *h
 		http.Error(w, "Failed to fetch from upstream", http.StatusBadGateway)
 		return
 	}
-	defer body.Close() // #nosec G104 -- Cleanup, error not critical
+	defer func() {
+		if cerr := body.Close(); cerr != nil {
+			log.Warn().Err(cerr).Msg("Failed to close NPM special endpoint body")
+		}
+	}()
 
 	w.WriteHeader(statusCode)
 	_, _ = io.Copy(w, body) // #nosec G104 -- HTTP response write
@@ -290,6 +306,19 @@ func extractPackageName(path string) string {
 	return path
 }
 
+// tarballPrefix returns the filename prefix used by npm tarballs for a given
+// package. For scoped packages (@scope/pkg) only the bare name is used as a
+// prefix — the @scope segment is not part of the filename.
+func tarballPrefix(packageName string) string {
+	bare := packageName
+	if strings.HasPrefix(bare, "@") {
+		if idx := strings.Index(bare, "/"); idx >= 0 {
+			bare = bare[idx+1:]
+		}
+	}
+	return bare + "-"
+}
+
 // extractTarballInfo extracts package name and version from tarball path
 func extractTarballInfo(path string) (string, string) {
 	// Format: /@scope/package/-/package-version.tgz
@@ -304,9 +333,9 @@ func extractTarballInfo(path string) (string, string) {
 		tarballName = strings.TrimSuffix(tarballName, ".tgz")
 		tarballName = strings.TrimSuffix(tarballName, ".tar.gz")
 
-		// Remove package name prefix to get version
-		prefix := strings.ReplaceAll(packageName, "/", "-") + "-"
-		version := strings.TrimPrefix(tarballName, prefix)
+		// Remove package name prefix to get version. For scoped packages the
+		// tarball filename uses only the bare package name (no @scope/ prefix).
+		version := strings.TrimPrefix(tarballName, tarballPrefix(packageName))
 
 		return packageName, version
 	}
@@ -334,9 +363,8 @@ func extractTarballInfo(path string) (string, string) {
 	tarballName = strings.TrimSuffix(tarballName, ".tgz")
 	tarballName = strings.TrimSuffix(tarballName, ".tar.gz")
 
-	// Remove package name prefix to get version
-	prefix := strings.ReplaceAll(packageName, "/", "-") + "-"
-	version := strings.TrimPrefix(tarballName, prefix)
+	// Remove package name prefix to get version (scope-aware).
+	version := strings.TrimPrefix(tarballName, tarballPrefix(packageName))
 
 	return packageName, version
 }