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/scanner/scanner.go

@@ -1,11 +1,18 @@
+// Package scanner orchestrates pluggable vulnerability scanners and
+// records their results against cached packages.
 package scanner
 
 import (
 	"context"
+	stderrors "errors"
 	"fmt"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/lukaszraczylo/gohoarder/pkg/config"
+	hoardererrors "github.com/lukaszraczylo/gohoarder/pkg/errors"
+	"github.com/lukaszraczylo/gohoarder/pkg/events"
 	"github.com/lukaszraczylo/gohoarder/pkg/metadata"
 	"github.com/lukaszraczylo/gohoarder/pkg/scanner/ghsa"
 	"github.com/lukaszraczylo/gohoarder/pkg/scanner/govulncheck"
@@ -14,6 +21,8 @@ import (
 	"github.com/lukaszraczylo/gohoarder/pkg/scanner/osv"
 	"github.com/lukaszraczylo/gohoarder/pkg/scanner/pipaudit"
 	"github.com/lukaszraczylo/gohoarder/pkg/scanner/trivy"
+	"github.com/lukaszraczylo/gohoarder/pkg/uuid"
+	"github.com/lukaszraczylo/gohoarder/pkg/websocket"
 	"github.com/rs/zerolog/log"
 )
 
@@ -37,11 +46,34 @@ type DatabaseUpdater interface {
 // Manager manages multiple security scanners
 type Manager struct {
 	metadataStore metadata.MetadataStore
-	config        config.SecurityConfig
+	broadcaster   events.Broadcaster
 	scanners      []Scanner
+	config        config.SecurityConfig
+	bcMu          sync.RWMutex
 	enabled       bool
 }
 
+// SetBroadcaster wires an events.Broadcaster onto the scanner so scan
+// lifecycle events are published. Pass nil to disable broadcasting.
+// Safe for concurrent use.
+func (m *Manager) SetBroadcaster(b events.Broadcaster) {
+	m.bcMu.Lock()
+	m.broadcaster = b
+	m.bcMu.Unlock()
+}
+
+// emit publishes an event via the configured broadcaster, if any.
+// Non-blocking: the underlying transport handles overflow by dropping.
+func (m *Manager) emit(eventType string, payload map[string]interface{}) {
+	m.bcMu.RLock()
+	b := m.broadcaster
+	m.bcMu.RUnlock()
+	if b == nil {
+		return
+	}
+	b.BroadcastEvent(eventType, payload)
+}
+
 // New creates a new scanner manager with configured scanners
 func New(cfg config.SecurityConfig, metadataStore metadata.MetadataStore) (*Manager, error) {
 	manager := &Manager{
@@ -178,11 +210,42 @@ func (m *Manager) ScanPackage(ctx context.Context, registry, packageName, versio
 			Msg("Scan completed")
 	}
 
-	// If no scanners succeeded, return
+	// If no scanners succeeded, persist a synthetic error result so callers
+	// fail closed (no scan == blocked) rather than silently leaving
+	// SecurityScanned=false which would allow the package to be served.
 	if len(scanResults) == 0 {
 		log.Warn().
 			Str("package", packageName).
-			Msg("All scanners failed, no results to save")
+			Msg("All scanners failed, saving scan-error result for fail-closed enforcement")
+
+		errResult := &metadata.ScanResult{
+			ID:                 uuid.New().String(),
+			Registry:           registry,
+			PackageName:        packageName,
+			PackageVersion:     version,
+			Scanner:            "all",
+			ScannedAt:          time.Now(),
+			Status:             metadata.ScanStatusError,
+			VulnerabilityCount: 0,
+			Vulnerabilities:    []metadata.Vulnerability{},
+			Details: map[string]interface{}{
+				"error": "all configured scanners failed for this package",
+			},
+		}
+		if err := m.metadataStore.SaveScanResult(ctx, errResult); err != nil {
+			log.Error().
+				Err(err).
+				Str("package", packageName).
+				Msg("Failed to save scan-error result")
+			return err
+		}
+		m.emit(string(websocket.EventScanComplete), map[string]interface{}{
+			"registry":            registry,
+			"name":                packageName,
+			"version":             version,
+			"status":              string(errResult.Status),
+			"vulnerability_count": errResult.VulnerabilityCount,
+		})
 		return nil
 	}
 
@@ -206,6 +269,14 @@ func (m *Manager) ScanPackage(ctx context.Context, registry, packageName, versio
 		Strs("scanners", scannerNames).
 		Msg("Consolidated scan results saved")
 
+	m.emit(string(websocket.EventScanComplete), map[string]interface{}{
+		"registry":            registry,
+		"name":                packageName,
+		"version":             version,
+		"status":              string(mergedResult.Status),
+		"vulnerability_count": mergedResult.VulnerabilityCount,
+	})
+
 	return nil
 }
 
@@ -285,11 +356,21 @@ func (m *Manager) mergeResults(results []*metadata.ScanResult, scannerNames []st
 			}
 		}
 
-		// Update status to worst case
-		if result.Status == metadata.ScanStatusVulnerable {
+		// Update status to worst case.
+		// Order: vulnerable > error > pending > clean. Vulnerable wins because
+		// the cache layer must surface the actual vulns. Otherwise, if any
+		// scanner errored, propagate so CheckVulnerabilities can fail closed.
+		switch result.Status {
+		case metadata.ScanStatusVulnerable:
 			merged.Status = metadata.ScanStatusVulnerable
-		} else if result.Status == metadata.ScanStatusPending && merged.Status != metadata.ScanStatusVulnerable {
-			merged.Status = metadata.ScanStatusPending
+		case metadata.ScanStatusError:
+			if merged.Status != metadata.ScanStatusVulnerable {
+				merged.Status = metadata.ScanStatusError
+			}
+		case metadata.ScanStatusPending:
+			if merged.Status != metadata.ScanStatusVulnerable && merged.Status != metadata.ScanStatusError {
+				merged.Status = metadata.ScanStatusPending
+			}
 		}
 	}
 
@@ -359,11 +440,37 @@ func (m *Manager) CheckVulnerabilities(ctx context.Context, registry, packageNam
 		}
 	}
 
-	// Get latest scan result
+	// Get latest scan result.
+	// SECURITY: Fail closed when no scan exists or backend errors.
+	// Previously this returned (false, "", nil) which allowed unscanned
+	// packages through — a fail-open bypass. Cache layer is expected to
+	// wait for the initial scan via SecurityScanned flag; once that flag
+	// is set, GetScanResult MUST return a record. A missing record at this
+	// point indicates either a cleared/lost scan or a transient error;
+	// either way we block.
 	result, err := m.metadataStore.GetScanResult(ctx, registry, packageName, version)
 	if err != nil {
-		// No scan result found - allow download (will be scanned after)
-		return false, "", nil
+		var hErr *hoardererrors.Error
+		if stderrors.As(err, &hErr) && hErr.Code == hoardererrors.ErrCodeNotFound {
+			return true, "no scan available - fail closed", nil
+		}
+		// Real backend error (DB transient, etc.) — also block.
+		log.Warn().
+			Err(err).
+			Str("package", packageName).
+			Msg("Failed to retrieve scan result, failing closed")
+		return true, "scan lookup failed - fail closed", nil
+	}
+	if result == nil {
+		// File-backed metadata store returns (nil, nil) on not-found.
+		return true, "no scan available - fail closed", nil
+	}
+
+	// If the scan itself errored (all scanners failed for this package),
+	// block. A scan-error record means we don't actually know whether the
+	// package is safe.
+	if result.Status == metadata.ScanStatusError {
+		return true, "scan failed - fail closed", nil
 	}
 
 	// Build set of bypassed CVEs for fast lookup