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/storage/filesystem/filesystem.go

@@ -1,3 +1,5 @@
+// Package filesystem implements the local-disk Storage backend used for
+// development and single-node deployments.
 package filesystem
 
 import (
@@ -55,7 +57,11 @@ func (fs *FilesystemStorage) Get(ctx context.Context, key string) (io.ReadCloser
 	default:
 	}
 
-	path := fs.keyToPath(key)
+	path, err := fs.keyToPath(key)
+	if err != nil {
+		metrics.RecordStorageOperation("filesystem", "get", "error")
+		return nil, err
+	}
 
 	file, err := os.Open(path) // #nosec G304 -- Path is sanitized storage key
 	if err != nil {
@@ -80,13 +86,17 @@ func (fs *FilesystemStorage) Put(ctx context.Context, key string, data io.Reader
 	default:
 	}
 
-	path := fs.keyToPath(key)
+	path, err := fs.keyToPath(key)
+	if err != nil {
+		metrics.RecordStorageOperation("filesystem", "put", "error")
+		return err
+	}
 	dir := filepath.Dir(path)
 
 	// Create directory
-	if err := os.MkdirAll(dir, 0750); err != nil {
+	if mkErr := os.MkdirAll(dir, 0750); mkErr != nil {
 		metrics.RecordStorageOperation("filesystem", "put", "error")
-		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to create directory")
+		return errors.Wrap(mkErr, errors.ErrCodeStorageFailure, "failed to create directory")
 	}
 
 	// Create temp file for atomic write
@@ -105,7 +115,7 @@ func (fs *FilesystemStorage) Put(ctx context.Context, key string, data io.Reader
 
 	written, err := io.Copy(multiWriter, data)
 	if err != nil {
-		tempFile.Close()        // #nosec G104 -- Cleanup, error not critical
+		_ = tempFile.Close()    // #nosec G104 -- Cleanup, error not critical
 		_ = os.Remove(tempPath) // #nosec G104 -- Cleanup, error not critical
 		metrics.RecordStorageOperation("filesystem", "put", "error")
 		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to write data")
@@ -117,17 +127,6 @@ func (fs *FilesystemStorage) Put(ctx context.Context, key string, data io.Reader
 		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to close temp file")
 	}
 
-	// Check quota
-	fs.mu.Lock()
-	if fs.quota > 0 && fs.used+written > fs.quota {
-		fs.mu.Unlock()
-		_ = os.Remove(tempPath) // #nosec G104 -- Cleanup, error not critical
-		metrics.RecordStorageOperation("filesystem", "put", "quota_exceeded")
-		return errors.QuotaExceeded(fs.quota)
-	}
-	fs.used += written
-	fs.mu.Unlock()
-
 	// Verify checksums if provided
 	if opts != nil {
 		md5Sum := hex.EncodeToString(md5Hash.Sum(nil))
@@ -146,21 +145,25 @@ func (fs *FilesystemStorage) Put(ctx context.Context, key string, data io.Reader
 		}
 	}
 
-	// Atomic rename
-	if err := os.Rename(tempPath, path); err != nil {
-		_ = os.Remove(tempPath) // #nosec G104 -- Cleanup, error not critical
-		fs.mu.Lock()
-		fs.used -= written
-		currentUsed := fs.used
+	// Atomic rename and quota update under lock so that fs.used reflects
+	// only successfully renamed files. Quota check happens before increment
+	// to avoid transient inflation seen by concurrent Puts.
+	fs.mu.Lock()
+	if fs.quota > 0 && fs.used+written > fs.quota {
 		fs.mu.Unlock()
+		_ = os.Remove(tempPath) // #nosec G104 -- Cleanup, error not critical
+		metrics.RecordStorageOperation("filesystem", "put", "quota_exceeded")
+		return errors.QuotaExceeded(fs.quota)
+	}
+	if err := os.Rename(tempPath, path); err != nil {
+		fs.mu.Unlock()
+		_ = os.Remove(tempPath) // #nosec G104 -- Cleanup, error not critical
 		metrics.RecordStorageOperation("filesystem", "put", "error")
-		metrics.UpdateCacheSize("filesystem", currentUsed)
 		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to rename temp file")
 	}
-
-	fs.mu.RLock()
+	fs.used += written
 	currentUsed := fs.used
-	fs.mu.RUnlock()
+	fs.mu.Unlock()
 
 	metrics.RecordStorageOperation("filesystem", "put", "success")
 	metrics.UpdateCacheSize("filesystem", currentUsed)
@@ -175,7 +178,11 @@ func (fs *FilesystemStorage) Delete(ctx context.Context, key string) error {
 	default:
 	}
 
-	path := fs.keyToPath(key)
+	path, err := fs.keyToPath(key)
+	if err != nil {
+		metrics.RecordStorageOperation("filesystem", "delete", "error")
+		return err
+	}
 
 	// Get size before deletion
 	info, err := os.Stat(path)
@@ -213,8 +220,11 @@ func (fs *FilesystemStorage) Exists(ctx context.Context, key string) (bool, erro
 	default:
 	}
 
-	path := fs.keyToPath(key)
-	_, err := os.Stat(path)
+	path, err := fs.keyToPath(key)
+	if err != nil {
+		return false, err
+	}
+	_, err = os.Stat(path)
 	if err != nil {
 		if os.IsNotExist(err) {
 			return false, nil
@@ -232,10 +242,13 @@ func (fs *FilesystemStorage) List(ctx context.Context, prefix string, opts *stor
 	default:
 	}
 
-	searchPath := fs.keyToPath(prefix)
+	searchPath, err := fs.keyToPath(prefix)
+	if err != nil {
+		return nil, err
+	}
 	var objects []storage.StorageObject
 
-	err := filepath.Walk(searchPath, func(path string, info os.FileInfo, err error) error {
+	err = filepath.Walk(searchPath, func(path string, info os.FileInfo, err error) error {
 		if err != nil {
 			return nil // Skip errors
 		}
@@ -284,7 +297,10 @@ func (fs *FilesystemStorage) Stat(ctx context.Context, key string) (*storage.Sto
 	default:
 	}
 
-	path := fs.keyToPath(key)
+	path, err := fs.keyToPath(key)
+	if err != nil {
+		return nil, err
+	}
 	info, err := os.Stat(path)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -331,7 +347,7 @@ func (fs *FilesystemStorage) Health(ctx context.Context) error {
 	if err != nil {
 		return errors.Wrap(err, errors.ErrCodeStorageFailure, "cannot write to storage")
 	}
-	f.Close()               // #nosec G104 -- Cleanup, error not critical
+	_ = f.Close()           // #nosec G104 -- Cleanup, error not critical
 	_ = os.Remove(tempPath) // #nosec G104 -- Cleanup, error not critical
 
 	return nil
@@ -352,7 +368,10 @@ func (fs *FilesystemStorage) GetLocalPath(ctx context.Context, key string) (stri
 	default:
 	}
 
-	path := fs.keyToPath(key)
+	path, err := fs.keyToPath(key)
+	if err != nil {
+		return "", err
+	}
 
 	// Verify file exists
 	if _, err := os.Stat(path); err != nil {
@@ -365,27 +384,46 @@ func (fs *FilesystemStorage) GetLocalPath(ctx context.Context, key string) (stri
 	return path, nil
 }
 
-// keyToPath converts a storage key to filesystem path
-func (fs *FilesystemStorage) keyToPath(key string) string {
+// keyToPath converts a storage key to filesystem path.
+// It sanitizes the key to prevent path traversal and verifies that the
+// resulting absolute path stays within the configured base directory as a
+// defense-in-depth check on top of filepath.Clean/Join semantics.
+func (fs *FilesystemStorage) keyToPath(key string) (string, error) {
 	// Sanitize key to prevent path traversal
-	key = filepath.Clean(key)
+	cleaned := filepath.Clean(key)
 
 	// Remove any leading slashes or dots
-	key = strings.TrimPrefix(key, "/")
+	cleaned = strings.TrimPrefix(cleaned, "/")
 
 	// Keep removing ../ until there are no more
-	for strings.HasPrefix(key, "../") || strings.HasPrefix(key, "..\\") {
-		key = strings.TrimPrefix(key, "../")
-		key = strings.TrimPrefix(key, "..\\")
+	for strings.HasPrefix(cleaned, "../") || strings.HasPrefix(cleaned, "..\\") {
+		cleaned = strings.TrimPrefix(cleaned, "../")
+		cleaned = strings.TrimPrefix(cleaned, "..\\")
 	}
 
 	// Final clean and ensure it's within base path
-	key = filepath.Clean(key)
-	if key == ".." || strings.HasPrefix(key, "../") || strings.HasPrefix(key, "..\\") {
-		key = ""
+	cleaned = filepath.Clean(cleaned)
+	if cleaned == ".." || strings.HasPrefix(cleaned, "../") || strings.HasPrefix(cleaned, "..\\") {
+		cleaned = ""
 	}
 
-	return filepath.Join(fs.basePath, key)
+	target := filepath.Join(fs.basePath, cleaned)
+
+	// Defense-in-depth: verify the resolved absolute path is contained
+	// within the base directory.
+	targetAbs, err := filepath.Abs(target)
+	if err != nil {
+		return "", errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to resolve path")
+	}
+	baseAbs, err := filepath.Abs(fs.basePath)
+	if err != nil {
+		return "", errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to resolve base path")
+	}
+	if targetAbs != baseAbs && !strings.HasPrefix(targetAbs, baseAbs+string(os.PathSeparator)) {
+		return "", errors.New(errors.ErrCodeStorageFailure, fmt.Sprintf("path traversal rejected: %s", key))
+	}
+
+	return target, nil
 }
 
 // calculateUsage calculates current storage usage

pkg/storage/filesystem/filesystem_test.go

@@ -531,8 +531,8 @@ func (s *FilesystemStorageTestSuite) TestConcurrentReadsAndWrites() {
 				key := fmt.Sprintf("shared/file-%d.txt", j%10)
 				reader, err := s.fs.Get(ctx, key)
 				if err == nil {
-					io.ReadAll(reader)
-					reader.Close() // #nosec G104 -- Cleanup, error not critical
+					_, _ = io.ReadAll(reader)
+					_ = reader.Close() // #nosec G104 -- Cleanup, error not critical
 				}
 			}
 		}(i)
@@ -546,7 +546,7 @@ func (s *FilesystemStorageTestSuite) TestConcurrentReadsAndWrites() {
 			for j := 0; j < numOps; j++ {
 				key := fmt.Sprintf("shared/writer-%d-%d.txt", id, j)
 				data := fmt.Sprintf("writer-%d-%d", id, j)
-				s.fs.Put(ctx, key, strings.NewReader(data), nil)
+				_ = s.fs.Put(ctx, key, strings.NewReader(data), nil)
 			}
 		}(i)
 	}
@@ -608,15 +608,15 @@ func (s *FilesystemStorageTestSuite) TestAtomicWrite() {
 				case <-stopReading:
 					return
 				default:
-					reader, err := s.fs.Get(ctx, key)
-					if err != nil {
-						readErrors <- err
+					reader, getErr := s.fs.Get(ctx, key)
+					if getErr != nil {
+						readErrors <- getErr
 						continue
 					}
-					data, err := io.ReadAll(reader)
+					data, readErr := io.ReadAll(reader)
 					reader.Close() // #nosec G104 -- Cleanup, error not critical
-					if err != nil {
-						readErrors <- err
+					if readErr != nil {
+						readErrors <- readErr
 						continue
 					}
 					// Data should be either "initial" or "updated", never partial
@@ -663,7 +663,8 @@ func (s *FilesystemStorageTestSuite) TestPathSanitization() {
 			s.NoError(err) // Should succeed but sanitize path
 
 			// Verify file is inside base directory
-			sanitized := s.fs.keyToPath(path)
+			sanitized, sanitizeErr := s.fs.keyToPath(path)
+			s.NoError(sanitizeErr)
 			s.True(strings.HasPrefix(sanitized, s.tempDir),
 				"Sanitized path %s should be inside %s", sanitized, s.tempDir)
 		})
@@ -728,7 +729,7 @@ func BenchmarkFilesystemPut(b *testing.B) {
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
 		key := fmt.Sprintf("bench/file-%d.txt", i)
-		fs.Put(ctx, key, strings.NewReader(data), nil)
+		_ = fs.Put(ctx, key, strings.NewReader(data), nil)
 	}
 }
 
@@ -744,14 +745,14 @@ func BenchmarkFilesystemGet(b *testing.B) {
 	data := strings.Repeat("x", 1024)
 
 	// Setup: Create test file
-	fs.Put(ctx, "bench/test.txt", strings.NewReader(data), nil)
+	_ = fs.Put(ctx, "bench/test.txt", strings.NewReader(data), nil)
 
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
 		reader, _ := fs.Get(ctx, "bench/test.txt")
 		if reader != nil {
-			io.ReadAll(reader)
-			reader.Close() // #nosec G104 -- Cleanup, error not critical
+			_, _ = io.ReadAll(reader)
+			_ = reader.Close() // #nosec G104 -- Cleanup, error not critical
 		}
 	}
 }

pkg/storage/interface.go

@@ -1,3 +1,5 @@
+// Package storage defines the pluggable Storage backend interface used to
+// persist cached package payloads (filesystem, S3, NFS, etc.).
 package storage
 
 import (

pkg/storage/nfs/nfs.go

@@ -0,0 +1,280 @@
+// Package nfs implements an NFS-backed storage backend.
+//
+// NFS is, from Go's perspective, an ordinary mounted filesystem. The user is
+// expected to mount the export at cfg.Path before starting the application;
+// this package does NOT perform mount(8) calls. It wraps the filesystem
+// backend and adds NFS-specific safety:
+//
+//   - Best-effort mount-type detection (Linux: /proc/mounts). On non-Linux
+//     platforms detection is skipped silently. A non-NFS mount is logged at
+//     Warn level but is NOT a fatal error so tests/CI can run on local
+//     filesystems.
+//
+//   - Optional per-write fsync (SyncWrites, default true) to flush NFS client
+//     caches and improve durability across NFS-cached metadata. Stale handles
+//     and "silent" write losses are common NFS pitfalls.
+//
+//   - A richer Health probe that round-trips a marker file (write, fsync,
+//     read, delete) to surface stale handles or read-after-write
+//     inconsistencies the bare filesystem health check would miss.
+package nfs
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/lukaszraczylo/gohoarder/pkg/errors"
+	"github.com/lukaszraczylo/gohoarder/pkg/storage"
+	"github.com/lukaszraczylo/gohoarder/pkg/storage/filesystem"
+	"github.com/rs/zerolog"
+)
+
+// Config holds NFS storage configuration. The struct is intentionally
+// self-contained so callers can map their own config (e.g.
+// pkg/config.StorageConfig) without import cycles.
+type Config struct {
+	// Path is the local mount point of the NFS export. Required.
+	Path string
+	// MaxSize is the optional quota in bytes (0 = unlimited). Forwarded to
+	// the underlying filesystem backend.
+	MaxSize int64
+	// SyncWrites, when true (default), forces fsync after every successful
+	// Put so data is flushed through the NFS client cache to the server.
+	SyncWrites bool
+}
+
+// Storage implements storage.StorageBackend on top of an NFS-mounted path.
+type Storage struct {
+	fs         *filesystem.FilesystemStorage
+	logger     zerolog.Logger
+	path       string
+	syncWrites bool
+}
+
+// New constructs an NFS storage backend rooted at cfg.Path.
+//
+// cfg.Path must already exist and be a directory; the caller is responsible
+// for the actual NFS mount. Mount-type detection is best-effort.
+func New(cfg Config, logger zerolog.Logger) (*Storage, error) {
+	if cfg.Path == "" {
+		return nil, errors.New(errors.ErrCodeStorageFailure, "nfs: path is required")
+	}
+
+	info, err := os.Stat(cfg.Path)
+	if err != nil {
+		return nil, errors.Wrap(err, errors.ErrCodeStorageFailure, "nfs: path does not exist or is inaccessible")
+	}
+	if !info.IsDir() {
+		return nil, errors.New(errors.ErrCodeStorageFailure, fmt.Sprintf("nfs: path is not a directory: %s", cfg.Path))
+	}
+
+	// Best-effort mount-type detection. Non-fatal: warn only.
+	if mountType, ok := detectMountType(cfg.Path); ok {
+		if !isNFSMountType(mountType) {
+			logger.Warn().
+				Str("path", cfg.Path).
+				Str("mount_type", mountType).
+				Msg("nfs: configured path is not on an NFS mount; proceeding anyway")
+		} else {
+			logger.Info().
+				Str("path", cfg.Path).
+				Str("mount_type", mountType).
+				Msg("nfs: detected NFS mount")
+		}
+	} else {
+		// Detection unavailable (non-Linux or /proc/mounts unreadable).
+		logger.Debug().
+			Str("path", cfg.Path).
+			Str("os", runtime.GOOS).
+			Msg("nfs: mount-type detection skipped")
+	}
+
+	fs, err := filesystem.New(cfg.Path, cfg.MaxSize)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Storage{
+		fs:         fs,
+		logger:     logger,
+		path:       cfg.Path,
+		syncWrites: cfg.SyncWrites,
+	}, nil
+}
+
+// Get delegates to the underlying filesystem backend.
+func (s *Storage) Get(ctx context.Context, key string) (io.ReadCloser, error) {
+	return s.fs.Get(ctx, key)
+}
+
+// Put delegates to the filesystem backend and, when SyncWrites is enabled,
+// fsyncs the resulting file to flush the NFS client cache.
+func (s *Storage) Put(ctx context.Context, key string, data io.Reader, opts *storage.PutOptions) error {
+	if err := s.fs.Put(ctx, key, data, opts); err != nil {
+		return err
+	}
+	if !s.syncWrites {
+		return nil
+	}
+
+	// Resolve the on-disk path via the LocalPathProvider contract the
+	// filesystem backend implements. Failure to fsync is logged but not
+	// returned: the write itself succeeded; durability is best-effort.
+	path, err := s.fs.GetLocalPath(ctx, key)
+	if err != nil {
+		s.logger.Warn().Err(err).Str("key", key).Msg("nfs: post-put path lookup failed; skipping fsync")
+		return nil
+	}
+	f, err := os.OpenFile(path, os.O_RDWR, 0) // #nosec G304 -- path resolved by sanitizing backend
+	if err != nil {
+		s.logger.Warn().Err(err).Str("key", key).Msg("nfs: post-put open failed; skipping fsync")
+		return nil
+	}
+	if syncErr := f.Sync(); syncErr != nil {
+		s.logger.Warn().Err(syncErr).Str("key", key).Msg("nfs: post-put fsync failed")
+	}
+	_ = f.Close() // #nosec G104 -- close after sync, error not actionable
+	return nil
+}
+
+// Delete delegates to the underlying filesystem backend.
+func (s *Storage) Delete(ctx context.Context, key string) error {
+	return s.fs.Delete(ctx, key)
+}
+
+// Exists delegates to the underlying filesystem backend.
+func (s *Storage) Exists(ctx context.Context, key string) (bool, error) {
+	return s.fs.Exists(ctx, key)
+}
+
+// List delegates to the underlying filesystem backend.
+func (s *Storage) List(ctx context.Context, prefix string, opts *storage.ListOptions) ([]storage.StorageObject, error) {
+	return s.fs.List(ctx, prefix, opts)
+}
+
+// Stat delegates to the underlying filesystem backend.
+func (s *Storage) Stat(ctx context.Context, key string) (*storage.StorageInfo, error) {
+	return s.fs.Stat(ctx, key)
+}
+
+// GetQuota delegates to the underlying filesystem backend.
+func (s *Storage) GetQuota(ctx context.Context) (*storage.QuotaInfo, error) {
+	return s.fs.GetQuota(ctx)
+}
+
+// Health checks both the underlying filesystem and runs an NFS-specific
+// round-trip probe (write, fsync, read, delete) to surface stale handles or
+// cache-coherency issues that a bare stat would miss.
+func (s *Storage) Health(ctx context.Context) error {
+	if err := s.fs.Health(ctx); err != nil {
+		return err
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+
+	probePath := filepath.Join(s.path, ".nfs_health_probe")
+	payload := []byte("nfs-health-probe")
+
+	f, err := os.Create(probePath) // #nosec G304 -- path under configured base, fixed name
+	if err != nil {
+		return errors.Wrap(err, errors.ErrCodeStorageFailure, "nfs: cannot create health probe file")
+	}
+	if _, writeErr := f.Write(payload); writeErr != nil {
+		_ = f.Close()            // #nosec G104 -- cleanup
+		_ = os.Remove(probePath) // #nosec G104 -- cleanup
+		return errors.Wrap(writeErr, errors.ErrCodeStorageFailure, "nfs: cannot write health probe")
+	}
+	if syncErr := f.Sync(); syncErr != nil {
+		_ = f.Close()            // #nosec G104 -- cleanup
+		_ = os.Remove(probePath) // #nosec G104 -- cleanup
+		return errors.Wrap(syncErr, errors.ErrCodeStorageFailure, "nfs: fsync of health probe failed")
+	}
+	if closeErr := f.Close(); closeErr != nil {
+		_ = os.Remove(probePath) // #nosec G104 -- cleanup
+		return errors.Wrap(closeErr, errors.ErrCodeStorageFailure, "nfs: close of health probe failed")
+	}
+
+	got, err := os.ReadFile(probePath) // #nosec G304 -- fixed probe path
+	if err != nil {
+		_ = os.Remove(probePath) // #nosec G104 -- cleanup
+		return errors.Wrap(err, errors.ErrCodeStorageFailure, "nfs: read-back of health probe failed (possible stale handle)")
+	}
+	if string(got) != string(payload) {
+		_ = os.Remove(probePath) // #nosec G104 -- cleanup
+		return errors.New(errors.ErrCodeStorageFailure, "nfs: health probe payload mismatch (cache coherency issue?)")
+	}
+	if err := os.Remove(probePath); err != nil {
+		return errors.Wrap(err, errors.ErrCodeStorageFailure, "nfs: cannot remove health probe file")
+	}
+	return nil
+}
+
+// Close delegates to the underlying filesystem backend.
+func (s *Storage) Close() error {
+	return s.fs.Close()
+}
+
+// GetLocalPath exposes direct on-disk paths for scanning (NFS exports look
+// like local files to callers). Implements storage.LocalPathProvider.
+func (s *Storage) GetLocalPath(ctx context.Context, key string) (string, error) {
+	return s.fs.GetLocalPath(ctx, key)
+}
+
+// detectMountType returns the filesystem type backing path. Linux-only: on
+// other platforms the second return value is false. Implementation walks
+// /proc/mounts and selects the longest matching mount point, which is the
+// canonical way to find which mount owns a path.
+func detectMountType(path string) (string, bool) {
+	if runtime.GOOS != "linux" {
+		return "", false
+	}
+
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return "", false
+	}
+
+	data, err := os.ReadFile("/proc/mounts")
+	if err != nil {
+		return "", false
+	}
+
+	var (
+		bestMount string
+		bestType  string
+	)
+	for _, line := range strings.Split(string(data), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) < 3 {
+			continue
+		}
+		mountPoint := fields[1]
+		fsType := fields[2]
+		if abs == mountPoint || strings.HasPrefix(abs, strings.TrimRight(mountPoint, "/")+"/") {
+			if len(mountPoint) > len(bestMount) {
+				bestMount = mountPoint
+				bestType = fsType
+			}
+		}
+	}
+	if bestMount == "" {
+		return "", false
+	}
+	return bestType, true
+}
+
+// isNFSMountType returns true for NFS family mount types.
+func isNFSMountType(t string) bool {
+	switch t {
+	case "nfs", "nfs4":
+		return true
+	default:
+		return false
+	}
+}

pkg/storage/nfs/nfs_test.go

@@ -0,0 +1,239 @@
+package nfs
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/lukaszraczylo/gohoarder/pkg/storage"
+	"github.com/rs/zerolog"
+)
+
+// newTestStorage builds an NFS Storage rooted at t.TempDir(). It also returns
+// a buffer capturing the logger output so detection-related tests can assert
+// on log lines without requiring a real NFS mount.
+func newTestStorage(t *testing.T, syncWrites bool) (*Storage, *bytes.Buffer) {
+	t.Helper()
+	dir := t.TempDir()
+	logBuf := &bytes.Buffer{}
+	logger := zerolog.New(logBuf)
+	s, err := New(Config{
+		Path:       dir,
+		MaxSize:    1 << 20, // 1 MiB
+		SyncWrites: syncWrites,
+	}, logger)
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	return s, logBuf
+}
+
+func TestNew_RejectsMissingPath(t *testing.T) {
+	logger := zerolog.New(io.Discard)
+	if _, err := New(Config{Path: ""}, logger); err == nil {
+		t.Fatal("expected error for empty path")
+	}
+}
+
+func TestNew_RejectsNonDirectory(t *testing.T) {
+	dir := t.TempDir()
+	file := filepath.Join(dir, "not-a-dir")
+	if err := os.WriteFile(file, []byte("x"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	logger := zerolog.New(io.Discard)
+	if _, err := New(Config{Path: file}, logger); err == nil {
+		t.Fatal("expected error when path is a file")
+	}
+}
+
+func TestNew_RejectsNonexistentPath(t *testing.T) {
+	logger := zerolog.New(io.Discard)
+	if _, err := New(Config{Path: "/nonexistent/path/does/not/exist"}, logger); err == nil {
+		t.Fatal("expected error for missing path")
+	}
+}
+
+// TestNew_LogsWarnOnNonNFSMount: on Linux the temp dir lives on a non-NFS fs,
+// so detection should fire and log a warn. On other OSes detection is skipped
+// and we just assert New succeeds.
+func TestNew_LogsWarnOnNonNFSMount(t *testing.T) {
+	s, logBuf := newTestStorage(t, true)
+	if s == nil {
+		t.Fatal("expected storage")
+	}
+
+	if runtime.GOOS != "linux" {
+		t.Skipf("mount detection only runs on linux; got %s", runtime.GOOS)
+	}
+
+	out := logBuf.String()
+	// Either a warn ("not on an NFS mount") or, if /proc/mounts is unreadable
+	// inside the sandbox, a debug "detection skipped". Both are acceptable;
+	// what we never want is a hard error.
+	if !strings.Contains(out, "not on an NFS mount") &&
+		!strings.Contains(out, "detection skipped") &&
+		!strings.Contains(out, "detected NFS mount") {
+		t.Fatalf("expected mount-detection log line, got: %q", out)
+	}
+}
+
+func TestRoundTrip_PutGetStatDelete(t *testing.T) {
+	s, _ := newTestStorage(t, true)
+	ctx := context.Background()
+
+	const key = "pkgs/example/1.0.0/data.bin"
+	payload := []byte("hello-nfs-roundtrip")
+
+	if err := s.Put(ctx, key, bytes.NewReader(payload), nil); err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	exists, err := s.Exists(ctx, key)
+	if err != nil || !exists {
+		t.Fatalf("Exists: got (%v, %v), want (true, nil)", exists, err)
+	}
+
+	rc, err := s.Get(ctx, key)
+	if err != nil {
+		t.Fatalf("Get: %v", err)
+	}
+	got, err := io.ReadAll(rc)
+	_ = rc.Close()
+	if err != nil {
+		t.Fatalf("ReadAll: %v", err)
+	}
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("payload mismatch: got %q want %q", got, payload)
+	}
+
+	info, err := s.Stat(ctx, key)
+	if err != nil {
+		t.Fatalf("Stat: %v", err)
+	}
+	if info.Size != int64(len(payload)) {
+		t.Fatalf("Stat size: got %d want %d", info.Size, len(payload))
+	}
+
+	if delErr := s.Delete(ctx, key); delErr != nil {
+		t.Fatalf("Delete: %v", delErr)
+	}
+	exists, err = s.Exists(ctx, key)
+	if err != nil {
+		t.Fatalf("Exists after delete: %v", err)
+	}
+	if exists {
+		t.Fatal("expected key to be gone after delete")
+	}
+}
+
+func TestPut_NoSyncPath(t *testing.T) {
+	// Same flow as round-trip, but with SyncWrites=false to exercise the
+	// non-fsync branch.
+	s, _ := newTestStorage(t, false)
+	ctx := context.Background()
+	if err := s.Put(ctx, "no-sync.txt", strings.NewReader("data"), nil); err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+}
+
+func TestList(t *testing.T) {
+	s, _ := newTestStorage(t, true)
+	ctx := context.Background()
+	keys := []string{"a/one.txt", "a/two.txt", "b/three.txt"}
+	for _, k := range keys {
+		if err := s.Put(ctx, k, strings.NewReader(k), nil); err != nil {
+			t.Fatalf("Put %s: %v", k, err)
+		}
+	}
+
+	objs, err := s.List(ctx, "a", &storage.ListOptions{})
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if len(objs) != 2 {
+		t.Fatalf("List(a): got %d objs want 2 (%v)", len(objs), objsKeys(objs))
+	}
+}
+
+func TestGetQuota(t *testing.T) {
+	s, _ := newTestStorage(t, true)
+	ctx := context.Background()
+
+	q, err := s.GetQuota(ctx)
+	if err != nil {
+		t.Fatalf("GetQuota: %v", err)
+	}
+	if q.Limit != 1<<20 {
+		t.Fatalf("Limit: got %d want %d", q.Limit, 1<<20)
+	}
+}
+
+func TestHealth_OK(t *testing.T) {
+	s, _ := newTestStorage(t, true)
+	if err := s.Health(context.Background()); err != nil {
+		t.Fatalf("Health: %v", err)
+	}
+}
+
+func TestHealth_LeavesNoProbeFile(t *testing.T) {
+	s, _ := newTestStorage(t, true)
+	if err := s.Health(context.Background()); err != nil {
+		t.Fatalf("Health: %v", err)
+	}
+	probe := filepath.Join(s.path, ".nfs_health_probe")
+	if _, err := os.Stat(probe); !os.IsNotExist(err) {
+		t.Fatalf("expected probe file removed; stat err=%v", err)
+	}
+}
+
+func TestHealth_FailsWhenPathRemoved(t *testing.T) {
+	s, _ := newTestStorage(t, true)
+	// Remove the entire base dir under the backend's feet to simulate a
+	// missing/stale mount. Health must surface that as an error.
+	if err := os.RemoveAll(s.path); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	if err := s.Health(context.Background()); err == nil {
+		t.Fatal("expected Health to fail after path removed")
+	}
+}
+
+func TestGetLocalPath(t *testing.T) {
+	s, _ := newTestStorage(t, true)
+	ctx := context.Background()
+	const key = "local/path/test.txt"
+	if err := s.Put(ctx, key, strings.NewReader("data"), nil); err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+	p, err := s.GetLocalPath(ctx, key)
+	if err != nil {
+		t.Fatalf("GetLocalPath: %v", err)
+	}
+	if !strings.HasPrefix(p, s.path) {
+		t.Fatalf("expected path under base; got %s (base %s)", p, s.path)
+	}
+}
+
+func TestStorageBackend_InterfaceConformance(t *testing.T) {
+	// Compile-time check the wrapper satisfies the public interface.
+	var _ storage.StorageBackend = (*Storage)(nil)
+	var _ storage.LocalPathProvider = (*Storage)(nil)
+}
+
+// objsKeys is a small helper used in failure messages.
+func objsKeys(objs []storage.StorageObject) string {
+	keys := make([]string, 0, len(objs))
+	for _, o := range objs {
+		keys = append(keys, o.Key)
+	}
+	b, _ := json.Marshal(keys)
+	return string(b)
+}

pkg/storage/s3/s3.go

@@ -1,3 +1,5 @@
+// Package s3 implements the S3-compatible Storage backend (AWS S3,
+// MinIO, etc.).
 package s3
 
 import (
@@ -139,9 +141,9 @@ func (s *S3Storage) Put(ctx context.Context, key string, data io.Reader, opts *s
 
 	// Check quota if set
 	if s.maxSizeBytes > 0 {
-		currentUsage, err := s.calculateUsage(ctx)
-		if err != nil {
-			log.Warn().Err(err).Msg("Failed to calculate current usage, skipping quota check")
+		currentUsage, usageErr := s.calculateUsage(ctx)
+		if usageErr != nil {
+			log.Warn().Err(usageErr).Msg("Failed to calculate current usage, skipping quota check")
 		} else if currentUsage+size > s.maxSizeBytes {
 			return errors.QuotaExceeded(s.maxSizeBytes)
 		}

pkg/storage/s3/s3_test.go

@@ -17,9 +17,9 @@ func TestS3StorageTestSuite(t *testing.T) {
 func (s *S3StorageTestSuite) TestNewS3Storage() {
 	tests := []struct {
 		name        string
+		errorMsg    string
 		config      Config
 		expectError bool
-		errorMsg    string
 	}{
 		{
 			name: "valid config with credentials",
@@ -175,8 +175,8 @@ func (s *S3StorageTestSuite) TestStripPrefix() {
 
 func (s *S3StorageTestSuite) TestIsNotFoundError() {
 	tests := []struct {
-		name     string
 		err      error
+		name     string
 		expected bool
 	}{
 		{

pkg/storage/smb/smb.go

@@ -1,3 +1,4 @@
+// Package smb implements the SMB/CIFS-backed Storage backend.
 package smb
 
 import (
@@ -188,14 +189,17 @@ func (c *smbConnection) close() {
 
 // Get retrieves data from SMB share
 func (s *SMBStorage) Get(ctx context.Context, key string) (io.ReadCloser, error) {
+	path, err := s.keyToPath(key)
+	if err != nil {
+		return nil, err
+	}
+
 	conn, err := s.getConnection()
 	if err != nil {
 		return nil, errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to get SMB connection")
 	}
 	defer s.returnConnection(conn)
 
-	path := s.keyToPath(key)
-
 	log.Debug().Str("key", path).Msg("Getting file from SMB")
 
 	// Open file
@@ -222,20 +226,23 @@ func (s *SMBStorage) Get(ctx context.Context, key string) (io.ReadCloser, error)
 
 // Put stores data on SMB share
 func (s *SMBStorage) Put(ctx context.Context, key string, data io.Reader, opts *storage.PutOptions) error {
+	path, err := s.keyToPath(key)
+	if err != nil {
+		return err
+	}
+
 	conn, err := s.getConnection()
 	if err != nil {
 		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to get SMB connection")
 	}
 	defer s.returnConnection(conn)
 
-	path := s.keyToPath(key)
-
 	log.Debug().Str("key", path).Msg("Putting file to SMB")
 
 	// Ensure directory exists
 	dir := filepath.Dir(path)
-	if err := s.ensureDir(conn, dir); err != nil {
-		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to create SMB directory")
+	if dirErr := s.ensureDir(conn, dir); dirErr != nil {
+		return errors.Wrap(dirErr, errors.ErrCodeStorageFailure, "failed to create SMB directory")
 	}
 
 	// Read data into buffer to check quota
@@ -247,9 +254,9 @@ func (s *SMBStorage) Put(ctx context.Context, key string, data io.Reader, opts *
 
 	// Check quota if set
 	if s.maxSizeBytes > 0 {
-		currentUsage, err := s.calculateUsage(conn)
-		if err != nil {
-			log.Warn().Err(err).Msg("Failed to calculate current usage, skipping quota check")
+		currentUsage, usageErr := s.calculateUsage(conn)
+		if usageErr != nil {
+			log.Warn().Err(usageErr).Msg("Failed to calculate current usage, skipping quota check")
 		} else if currentUsage+size > s.maxSizeBytes {
 			return errors.QuotaExceeded(s.maxSizeBytes)
 		}
@@ -260,7 +267,11 @@ func (s *SMBStorage) Put(ctx context.Context, key string, data io.Reader, opts *
 	if err != nil {
 		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to create SMB file")
 	}
-	defer file.Close()
+	defer func() {
+		if closeErr := file.Close(); closeErr != nil {
+			log.Warn().Err(closeErr).Str("path", path).Msg("Failed to close SMB file after writing")
+		}
+	}()
 
 	// Write data
 	_, err = file.Write([]byte(buf.String()))
@@ -286,8 +297,8 @@ func (s *SMBStorage) ensureDir(conn *smbConnection, path string) error {
 	// Create parent directory first
 	parent := filepath.Dir(path)
 	if parent != path && parent != "." && parent != "/" {
-		if err := s.ensureDir(conn, parent); err != nil {
-			return err
+		if parentErr := s.ensureDir(conn, parent); parentErr != nil {
+			return parentErr
 		}
 	}
 
@@ -302,14 +313,17 @@ func (s *SMBStorage) ensureDir(conn *smbConnection, path string) error {
 
 // Delete removes data from SMB share
 func (s *SMBStorage) Delete(ctx context.Context, key string) error {
+	path, err := s.keyToPath(key)
+	if err != nil {
+		return err
+	}
+
 	conn, err := s.getConnection()
 	if err != nil {
 		return errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to get SMB connection")
 	}
 	defer s.returnConnection(conn)
 
-	path := s.keyToPath(key)
-
 	log.Debug().Str("key", path).Msg("Deleting file from SMB")
 
 	err = conn.share.Remove(path)
@@ -322,14 +336,17 @@ func (s *SMBStorage) Delete(ctx context.Context, key string) error {
 
 // Exists checks if data exists on SMB share
 func (s *SMBStorage) Exists(ctx context.Context, key string) (bool, error) {
+	path, err := s.keyToPath(key)
+	if err != nil {
+		return false, err
+	}
+
 	conn, err := s.getConnection()
 	if err != nil {
 		return false, errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to get SMB connection")
 	}
 	defer s.returnConnection(conn)
 
-	path := s.keyToPath(key)
-
 	_, err = conn.share.Stat(path)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -343,14 +360,17 @@ func (s *SMBStorage) Exists(ctx context.Context, key string) (bool, error) {
 
 // List returns a list of objects with the given prefix
 func (s *SMBStorage) List(ctx context.Context, prefix string, opts *storage.ListOptions) ([]storage.StorageObject, error) {
+	basePath, err := s.keyToPath(prefix)
+	if err != nil {
+		return nil, err
+	}
+
 	conn, err := s.getConnection()
 	if err != nil {
 		return nil, errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to get SMB connection")
 	}
 	defer s.returnConnection(conn)
 
-	basePath := s.keyToPath(prefix)
-
 	log.Debug().Str("prefix", basePath).Msg("Listing files in SMB")
 
 	var objects []storage.StorageObject
@@ -422,14 +442,17 @@ func (s *SMBStorage) walkPath(conn *smbConnection, root string, fn func(string,
 
 // Stat returns metadata about stored data
 func (s *SMBStorage) Stat(ctx context.Context, key string) (*storage.StorageInfo, error) {
+	path, err := s.keyToPath(key)
+	if err != nil {
+		return nil, err
+	}
+
 	conn, err := s.getConnection()
 	if err != nil {
 		return nil, errors.Wrap(err, errors.ErrCodeStorageFailure, "failed to get SMB connection")
 	}
 	defer s.returnConnection(conn)
 
-	path := s.keyToPath(key)
-
 	info, err := conn.share.Stat(path)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -494,17 +517,28 @@ func (s *SMBStorage) Close() error {
 	return nil
 }
 
-// keyToPath converts a storage key to SMB path
-func (s *SMBStorage) keyToPath(key string) string {
+// keyToPath converts a storage key to SMB path. It rejects keys that
+// contain traversal segments ("..") or empty segments to prevent escaping
+// the configured base path.
+func (s *SMBStorage) keyToPath(key string) (string, error) {
+	// Reject traversal attempts. Split by both forward and backslash so
+	// callers can use either separator on input.
+	normalized := strings.ReplaceAll(key, "\\", "/")
+	for _, seg := range strings.Split(normalized, "/") {
+		if seg == ".." || seg == "." {
+			return "", errors.New(errors.ErrCodeStorageFailure, fmt.Sprintf("invalid key segment %q in %q", seg, key))
+		}
+	}
+
 	// Normalize separators to backslash for SMB
-	key = strings.ReplaceAll(key, "/", "\\")
+	winKey := strings.ReplaceAll(key, "/", "\\")
 
 	if s.config.Path == "" {
-		return key
+		return winKey, nil
 	}
 
 	// Use backslash for SMB paths
-	return s.config.Path + "\\" + key
+	return s.config.Path + "\\" + winKey, nil
 }
 
 // pathToKey converts an SMB path to storage key

pkg/storage/smb/smb_test.go

@@ -141,7 +141,8 @@ func (s *SMBStorageTestSuite) TestKeyToPath() {
 				},
 			}
 
-			result := storage.keyToPath(tt.key)
+			result, err := storage.keyToPath(tt.key)
+			s.NoError(err)
 			s.Equal(tt.expectedWin, result)
 		})
 	}