feat: add SECRETS_DIR existence and writability warnings

Add check_secrets_dir() helper that validates the configured
SECRETS_DIR path and returns warning messages for non-existent
or writable directories. Called from the lifespan after logging
is configured, using the same dual-logger pattern (uvicorn +
loguru) as CORS and Redis warnings.

Skip passing _secrets_dir to pydantic-settings when the path
doesn't exist to prevent its raw warnings.warn() during early
startup.

Signed-off-by: Grant Ramsay <seapagan@gmail.com>

Author: seapagan

app/config/settings.py

@@ -5,7 +5,7 @@
 import os
 import sys
 from functools import lru_cache
-from pathlib import Path  # noqa: TC003
+from pathlib import Path
 from typing import TYPE_CHECKING, cast
 from urllib.parse import quote
 
@@ -300,11 +300,39 @@ def validate_db_user(cls: type[Settings], value: str) -> str:
         return value
 
 
+def check_secrets_dir() -> list[str]:
+    """Validate SECRETS_DIR and return warning messages.
+
+    Returns a list of warning strings (empty if no issues found).
+    Intended to be called from the application lifespan, after
+    logging is configured.
+    """
+    warnings: list[str] = []
+    secrets_dir = os.getenv("SECRETS_DIR", "").strip()
+    if not secrets_dir:
+        return warnings
+
+    secrets_path = Path(secrets_dir)
+    if not secrets_path.is_dir():
+        warnings.append(
+            f"SECRETS_DIR '{secrets_dir}' does not exist or is "
+            f"not a directory. File-based secrets will not be "
+            f"loaded."
+        )
+    elif os.access(secrets_path, os.W_OK):
+        warnings.append(
+            f"SECRETS_DIR '{secrets_dir}' is writable by the "
+            f"current process. For best security, this "
+            f"directory should be read-only."
+        )
+    return warnings
+
+
 @lru_cache
 def get_settings() -> Settings:
     """Return the current settings."""
-    secrets_dir = os.getenv("SECRETS_DIR")
+    secrets_dir = os.getenv("SECRETS_DIR", "").strip()
     settings_factory = cast("Callable[..., Settings]", Settings)
-    if secrets_dir and secrets_dir.strip():
+    if secrets_dir and Path(secrets_dir).is_dir():
         return settings_factory(_secrets_dir=secrets_dir)
     return settings_factory()

app/main.py

@@ -24,7 +24,7 @@
 from app.config.helpers import get_api_version, get_project_root
 from app.config.log_config import get_log_config
 from app.config.openapi import custom_openapi
-from app.config.settings import get_settings, unwrap_secret
+from app.config.settings import check_secrets_dir, get_settings, unwrap_secret
 from app.database.db import async_session
 from app.metrics.instrumentator import register_metrics
 from app.middleware.cache_logging import CacheLoggingMiddleware
@@ -73,6 +73,11 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[Any, None]:
     # Initialize loguru logging within the server process.
     get_log_config()
 
+    # Validate SECRETS_DIR configuration if set.
+    for warning_msg in check_secrets_dir():
+        logger.warning(warning_msg)
+        loguru_logger.warning(warning_msg)
+
     if "*" in cors_list:
         warning_msg = (
             "CORS_ORIGINS is set to '*', allowing any origin to access the "

tests/unit/test_validation.py

@@ -11,7 +11,12 @@
 from cryptography.fernet import Fernet
 from pydantic import SecretStr
 
-from app.config.settings import Settings, get_settings, unwrap_secret
+from app.config.settings import (
+    Settings,
+    check_secrets_dir,
+    get_settings,
+    unwrap_secret,
+)
 
 if TYPE_CHECKING:  # pragma: no cover
     from collections.abc import Callable
@@ -446,6 +451,7 @@ def test_get_settings_uses_secrets_dir_env_var(
         mock_settings = mocker.patch("app.config.settings.Settings")
         secrets_dir = "/var/run/app-secrets"
         monkeypatch.setenv("SECRETS_DIR", secrets_dir)
+        mocker.patch("app.config.settings.Path.is_dir", return_value=True)
         get_settings.cache_clear()
 
         settings = get_settings()
@@ -491,3 +497,31 @@ def test_weak_test_db_password_from_secrets_dir_rejected(
             ),
         ):
             build_settings(_env_file=None, _secrets_dir=tmp_path)
+
+    def test_secrets_dir_warns_when_not_found(self, monkeypatch) -> None:
+        """check_secrets_dir returns warning when path does not exist."""
+        monkeypatch.setenv("SECRETS_DIR", "/no/such/secrets/dir")
+
+        warnings = check_secrets_dir()
+
+        assert len(warnings) == 1
+        assert "does not exist" in warnings[0]
+
+    def test_secrets_dir_warns_when_writable(
+        self, monkeypatch, tmp_path: Path
+    ) -> None:
+        """check_secrets_dir returns warning when dir is writable."""
+        monkeypatch.setenv("SECRETS_DIR", str(tmp_path))
+
+        warnings = check_secrets_dir()
+
+        assert len(warnings) == 1
+        assert "writable" in warnings[0]
+
+    def test_secrets_dir_no_warnings_when_unset(self, monkeypatch) -> None:
+        """check_secrets_dir returns empty list when SECRETS_DIR unset."""
+        monkeypatch.delenv("SECRETS_DIR", raising=False)
+
+        warnings = check_secrets_dir()
+
+        assert warnings == []