Move debug log defaults out of /tmp and reject symlinks (#23)

The default debug_log_path and resolver_debug_log_path were in /tmp,
which is world-writable on shared hosts. An attacker who pre-creates a
symlink at /tmp/historian-debug.log pointing at e.g. an authorized_keys
file could trick Historian (with debug mode on) into overwriting an
arbitrary file, because _prepare_private_file opened with O_CREAT and no
O_NOFOLLOW/O_EXCL.

Two defenses, per the issue:
- Move defaults under the XDG data dir (~/.local/share/historian/),
  which is not world-writable, matching how database_path already works.
- Add O_NOFOLLOW to _prepare_private_file so a symlinked target is
  rejected at open time rather than followed, even for custom paths.

Updates config.py, config.example.json, and docs/debugging.md. Adds tests
for the new defaults and symlink rejection.

Author: randileeharper

docs/debugging.md

@@ -5,8 +5,8 @@ Enable unified debugging in `config.json`:
 ```json
 {
   "debug_enabled": true,
-  "debug_log_path": "/tmp/historian-debug.log",
-  "resolver_debug_log_path": "/tmp/historian-resolver.log",
+  "debug_log_path": "~/.local/share/historian/debug.log",
+  "resolver_debug_log_path": "~/.local/share/historian/resolver.log",
   "log_level": "INFO"
 }
 ```
@@ -26,8 +26,8 @@ Useful checks:
 
 ```console
 uv run historian doctor --live
-tail -f /tmp/historian-debug.log
-less /tmp/historian-resolver.log
+tail -f ~/.local/share/historian/debug.log
+less ~/.local/share/historian/resolver.log
 ```
 
 `doctor` reports whether debug mode is enabled and whether both configured paths are writable.

historian/config.example.json

@@ -9,8 +9,8 @@
   "resolver_api_key": "",
   "resolver_include_reasoning": false,
   "debug_enabled": false,
-  "debug_log_path": "/tmp/historian-debug.log",
-  "resolver_debug_log_path": "/tmp/historian-resolver.log",
+  "debug_log_path": "~/.local/share/historian/debug.log",
+  "resolver_debug_log_path": "~/.local/share/historian/resolver.log",
   "cli_token_path": "~/.config/historian/cli-token",
   "request_timeout_seconds": 60.0,
   "resolver_max_retries": 3,

historian/config.py

@@ -98,8 +98,8 @@ class Settings:
     resolver_api_key: str = ""
     resolver_include_reasoning: bool = False
     debug_enabled: bool = False
-    debug_log_path: str = "/tmp/historian-debug.log"
-    resolver_debug_log_path: str = "/tmp/historian-resolver.log"
+    debug_log_path: str = str(_xdg_data_home() / "historian" / "debug.log")
+    resolver_debug_log_path: str = str(_xdg_data_home() / "historian" / "resolver.log")
     cli_token_path: str = str(_xdg_config_home() / "historian" / "cli-token")
     request_timeout_seconds: float = 60.0
     resolver_max_retries: int = 3

historian/debug.py

@@ -19,7 +19,7 @@
 
 def _prepare_private_file(path: Path, *, clear: bool) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
-    flags = os.O_WRONLY | os.O_CREAT | (os.O_TRUNC if clear else os.O_APPEND)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_NOFOLLOW | (os.O_TRUNC if clear else os.O_APPEND)
     descriptor = os.open(path, flags, 0o600)
     os.close(descriptor)
     os.chmod(path, 0o600)

tests/test_debug.py

@@ -4,10 +4,12 @@
 import logging
 import os
 
+import pytest
+
 from historian.app import build_app
 from historian.cli import main
 from historian.config import Settings
-from historian.debug import QueryTranscript, configure_logging
+from historian.debug import QueryTranscript, _prepare_private_file, configure_logging
 
 from conftest import event
 
@@ -157,3 +159,37 @@ def test_operational_log_uses_metadata_not_event_payload(tmp_path, vesper_manife
     assert "event-1" in content
     assert "music.playback.started" in content
     assert "do-not-store" not in content
+
+
+def test_default_debug_paths_are_not_in_tmp(monkeypatch) -> None:
+    """Default debug log paths must live under the XDG data dir, not /tmp."""
+    monkeypatch.setenv("XDG_DATA_HOME", "/tmp/xdg-data-fixture")
+    settings = Settings()
+    assert not settings.debug_log_path.startswith("/tmp/historian")
+    assert not settings.resolver_debug_log_path.startswith("/tmp/historian")
+    assert "/historian/debug.log" in settings.debug_log_path
+    assert "/historian/resolver.log" in settings.resolver_debug_log_path
+
+
+def test_prepare_private_file_refuses_symlink(tmp_path) -> None:
+    """_prepare_private_file must not follow a pre-existing symlink (O_NOFOLLOW).
+
+    A symlink at the target path is an attack vector for overwriting an
+    arbitrary file; opening it must fail rather than write through it.
+    """
+    real_file = tmp_path / "real-target.txt"
+    real_file.write_text("original\n", encoding="utf-8")
+    link = tmp_path / "debug.log"
+    os.symlink(real_file, link)
+    with pytest.raises(OSError):
+        _prepare_private_file(link, clear=True)
+    # The target the symlink pointed at must be untouched.
+    assert real_file.read_text(encoding="utf-8") == "original\n"
+
+
+def test_prepare_private_file_creates_new_file(tmp_path) -> None:
+    """A normal (non-symlink) path is created with owner-only permissions."""
+    target = tmp_path / "debug.log"
+    _prepare_private_file(target, clear=True)
+    assert target.is_file()
+    assert os.stat(target).st_mode & 0o777 == 0o600