Merge pull request #86 from abinaze/feat/d1-dataset-provenance-schema

feat(D1): local config-file loading + desktop-mode admin-auth hardening

api/main.py

@@ -16,6 +16,12 @@ from api.models import HealthResponse, StatsResponse
 from processing.alias_graph import AliasGraph          # Phase 32
 from processing.entity_resolver_v2 import EntityResolverV2  # Phase 32
 from config.runtime_profile import PROFILE as _RUNTIME_PROFILE
+import config.settings  # noqa: F401 -- Phase D1: importing this loads any
+                         # local desktop config file into os.environ as a
+                         # side effect (mirrors load_dotenv() above). Must
+                         # happen at real application startup, not just
+                         # lazily inside admin.py, so every route -- not
+                         # only /admin/* -- sees locally-configured values.
 
 
 @asynccontextmanager

api/routes/admin.py

@@ -18,13 +18,70 @@ _pipeline_status = {
 _pipeline_lock = threading.Lock()
 
 
+def _generate_and_persist_admin_secret() -> str:
+    """Generate a random per-install admin secret and persist it locally.
+
+    Desktop groundwork (Phase D1). Persists via config.settings's local
+    config-file mechanism introduced in this same phase -- NOT yet the
+    real OS credential store (Windows Credential Manager) SECURITY.md's
+    Desktop Application Threat Model describes; that upgrade is Phase
+    D6's scope (API Key Manager, OS-keychain-backed storage). This is a
+    real, cryptographically random secret either way (secrets.token_urlsafe,
+    not a placeholder) -- just not yet in the most secure available
+    location for a desktop app specifically.
+    """
+    import secrets as _secrets_module
+    from config.settings import set_local_setting
+
+    new_secret = _secrets_module.token_urlsafe(32)
+    set_local_setting("ADMIN_SECRET", new_secret)
+    logger.info("[Admin] Generated new per-install ADMIN_SECRET (desktop mode)")
+    return new_secret
+
+
 def _require_admin(x_admin_secret: str = Header(default="")):
     """
     H-04 FIX: even in DEBUG_MODE, require a non-empty X-Admin-Secret header
     if ADMIN_SECRET is set. Previously DEBUG_MODE=true bypassed ALL auth,
     allowing anyone to POST /admin/pipeline (database wipe/reseed) on the
     production HuggingFace server if DEBUG_MODE was accidentally left on.
+
+    Phase D1 FIX: desktop builds (BHARATGRAPH_DESKTOP_MODE=true, a flag
+    the not-yet-built Tauri shell's backend-spawning code will set --
+    see PHASE_ROADMAP.md Phase D4) skip the DEBUG_MODE path entirely --
+    per SECURITY.md's Desktop Application Threat Model: "The web
+    deployment's DEBUG_MODE auth-bypass path... is not present in
+    desktop builds at all -- there is no bypass path to accidentally
+    leave enabled." Instead, a missing secret is generated and persisted
+    on the spot. Since BHARATGRAPH_DESKTOP_MODE is never set by any
+    current deployment (nothing sets it until Phase D4 exists), this
+    branch is unreachable today and the web deployment's behavior below
+    is completely unchanged.
     """
+    # Importing config.settings (even though nothing below references it
+    # by name) is not decorative -- it's what actually loads the local
+    # config file's persisted values into os.environ. api/main.py, the
+    # real application entry point, does the same import for the same
+    # reason (defense in depth: this function's correctness must not
+    # silently depend on something else having imported it first, since
+    # this file can be imported and tested in isolation, as it was
+    # during verification -- see the D1 commit message).
+    import config.settings  # noqa: F401
+
+    is_desktop_mode = os.getenv("BHARATGRAPH_DESKTOP_MODE", "").lower() in ("1", "true", "yes")
+
+    if is_desktop_mode:
+        secret = os.getenv("ADMIN_SECRET", "")
+        if not secret or not secret.strip():
+            secret = _generate_and_persist_admin_secret()
+        if x_admin_secret != secret:
+            raise HTTPException(
+                status_code=403,
+                detail="Forbidden: invalid or missing X-Admin-Secret header",
+            )
+        return
+
+    # Web deployment: existing behavior, completely unchanged.
     secret = os.getenv("ADMIN_SECRET", "")
     is_debug = os.getenv("DEBUG_MODE", "").lower() in ("1", "true", "yes")
 

config/settings.py

@@ -1,9 +1,100 @@
 import os
+import sys
+import json
 import warnings
+from pathlib import Path
 from dotenv import load_dotenv
 
 load_dotenv()
 
+# -- Local config-file support (Phase D1 -- desktop groundwork) --------
+# Added ALONGSIDE the .env loading above, not replacing it -- a web
+# deployment has no local config file, so this whole block is a no-op
+# for it. Desktop builds (once Phase D4+ exist) can persist settings
+# here -- e.g. a per-install ADMIN_SECRET generated by
+# api/routes/admin.py (see SECURITY.md's Desktop Application Threat
+# Model), or values a setup wizard collects in Phase D5 -- without a
+# .env file, which desktop users won't have or know how to edit.
+#
+# Mirrors exactly how load_dotenv() above already works: injects any
+# locally-configured value into os.environ, so every existing
+# os.getenv(...) call site throughout the codebase (api/dependencies.py,
+# every scraper, this file's own constants below) picks it up
+# transparently -- nothing outside this block needs to change.
+# Precedence: a real environment variable (including one already loaded
+# from .env) always wins; the local config file only fills in keys that
+# aren't already set.
+
+def get_app_data_dir() -> Path:
+    """OS-appropriate application-data directory for BharatGraph.
+
+    Desktop groundwork only -- not yet used for anything except the
+    local config file below. The full three-way app-files/user-data/
+    cache path split is a separate, larger piece of work (see
+    PHASE_ROADMAP.md, audit Finding P-1/F-3), not attempted here.
+    """
+    if sys.platform == "win32":
+        base = os.getenv("APPDATA", str(Path.home() / "AppData" / "Roaming"))
+    elif sys.platform == "darwin":
+        base = str(Path.home() / "Library" / "Application Support")
+    else:
+        base = os.getenv("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+    return Path(base) / "BharatGraph"
+
+
+def _local_config_path() -> Path:
+    return get_app_data_dir() / "config.json"
+
+
+def _load_local_config() -> dict:
+    """Load config.json from the app-data dir. Returns {} if absent/invalid.
+
+    A missing or malformed local config must never crash startup --
+    .env and hardcoded defaults remain the fallback either way.
+    """
+    path = _local_config_path()
+    if not path.exists():
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            warnings.warn(
+                f"Local config at {path} is not a JSON object -- ignoring.",
+                stacklevel=1,
+            )
+            return {}
+        return data
+    except (json.JSONDecodeError, OSError) as e:
+        warnings.warn(
+            f"Could not read local config at {path}: {e} -- ignoring.",
+            stacklevel=1,
+        )
+        return {}
+
+
+def set_local_setting(key: str, value: str) -> None:
+    """Persist one key/value to the local config file AND this process's
+    environment, so it's picked up by every existing os.getenv(...) call
+    site immediately, not just on next restart.
+
+    Used by api/routes/admin.py to persist an auto-generated per-install
+    ADMIN_SECRET (see SECURITY.md's Desktop Application Threat Model).
+    """
+    config = _load_local_config()
+    config[key] = value
+    path = _local_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2)
+    os.environ[key] = value
+
+
+_local_config = _load_local_config()
+for _k, _v in _local_config.items():
+    if _v and not os.getenv(_k):
+        os.environ[_k] = str(_v)
+
 # Project Info
 PROJECT_NAME = "BharatGraph"
 VERSION      = "0.36.0"   # NEW-A7 FIX: bumped from 0.31.0 after 3 bug sprints