fathom-server 0.1.0__py3-none-any.whl

fathom_server/__init__.py

@@ -0,0 +1,8 @@
+"""Fathom Server — dashboard + REST API + background services for the vault layer."""
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("fathom-server")
+except Exception:
+    __version__ = "0.0.0-dev"

fathom_server/app.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Fathom Server — dashboard + REST API + background services for the vault layer."""
+
+import argparse
+
+from flask import Flask, send_from_directory
+
+from fathom_server.config import FRONTEND_DIR, HOST, PORT
+
+app = Flask(__name__, static_folder=FRONTEND_DIR, static_url_path="")
+
+from fathom_server.routes.activation import bp as activation_bp  # noqa: E402
+from fathom_server.routes.room import bp as room_bp  # noqa: E402
+from fathom_server.routes.settings import bp as settings_bp  # noqa: E402
+from fathom_server.routes.telegram import bp as telegram_bp  # noqa: E402
+from fathom_server.routes.terminal import sock as terminal_sock  # noqa: E402
+from fathom_server.routes.vault import bp as vault_bp  # noqa: E402
+
+terminal_sock.init_app(app)
+app.register_blueprint(activation_bp)
+app.register_blueprint(vault_bp)
+app.register_blueprint(settings_bp)
+app.register_blueprint(room_bp)
+app.register_blueprint(telegram_bp)
+
+# Bootstrap all workspaces on startup
+import threading as _threading  # noqa: E402
+
+from fathom_server.services.crystal_scheduler import crystal_scheduler  # noqa: E402
+from fathom_server.services.indexer import indexer  # noqa: E402
+from fathom_server.services.persistent_session import (  # noqa: E402
+    ensure_running as session_ensure_running,
+)
+from fathom_server.services.ping_scheduler import ping_scheduler  # noqa: E402
+from fathom_server.services.settings import (  # noqa: E402
+    load_global_settings,
+    load_workspace_settings,
+)
+from fathom_server.services.telegram_bridge import telegram_bridge  # noqa: E402
+
+_global_settings = load_global_settings()
+_workspaces = _global_settings["workspaces"]
+_default_ws = _global_settings["default_workspace"]
+
+# Ensure persistent sessions for local-execution workspaces only (non-blocking)
+for _ws_name, _ws_entry in _workspaces.items():
+    if _ws_entry.get("execution", "local") == "local" and _ws_entry.get("type") != "human":
+        _threading.Thread(target=session_ensure_running, args=(_ws_name,), daemon=True).start()
+
+# Collect all ping routines across workspaces (tagged with workspace)
+_all_routines = []
+for _ws_name in _workspaces:
+    _ws_settings = load_workspace_settings(_ws_name)
+    for _r in _ws_settings["ping"]["routines"]:
+        _r["workspace"] = _ws_name
+    _all_routines.extend(_ws_settings["ping"]["routines"])
+
+ping_scheduler.configure_all(_all_routines)
+
+# Configure indexer from default workspace settings (indexes all workspaces)
+_default_settings = load_workspace_settings(_default_ws)
+indexer.configure(
+    _default_settings["background_index"]["enabled"],
+    _default_settings["background_index"]["interval_minutes"],
+    _default_settings["background_index"]["excluded_dirs"],
+)
+
+# Configure crystal scheduler from default workspace
+crystal_scheduler.configure(
+    _default_settings["crystal_regen"]["enabled"],
+    _default_settings["crystal_regen"]["interval_days"],
+    workspace=_default_ws,
+)
+
+# Configure and start Telegram bridge if enabled
+_telegram_cfg = _global_settings.get("telegram", {})
+telegram_bridge.configure(
+    api_id=_telegram_cfg.get("api_id", 0),
+    api_hash=_telegram_cfg.get("api_hash", ""),
+    session_string=_telegram_cfg.get("session_string", ""),
+    primary_agent=_default_ws,
+    enabled=_telegram_cfg.get("enabled", False),
+)
+telegram_bridge.start()
+
+
+@app.route("/")
+def index():
+    return send_from_directory(FRONTEND_DIR, "index.html")
+
+
+@app.route("/<path:path>")
+def spa(path):  # noqa: ARG001
+    """Catch-all for SPA client-side routing."""
+    return send_from_directory(FRONTEND_DIR, "index.html")
+
+
+def _cmd_serve(args):
+    """Run the server."""
+    from fathom_server.auth import load_server_config
+
+    server_config = load_server_config()
+    api_key = server_config["api_key"]
+    auth_enabled = server_config.get("auth_enabled", False)
+    key_is_new = server_config.get("_key_newly_created", False)
+
+    from fathom_server import __version__
+
+    print(f"\n  Fathom Server v{__version__}")
+    print(f"  Bind: {args.host}:{args.port}")
+    print(f"  Auth: {'enabled' if auth_enabled else 'disabled (enable via dashboard)'}")
+    if key_is_new:
+        print(f"  API Key: {api_key}  \u2190 SAVE THIS (shown once)")
+    else:
+        print(f"  API Key: {api_key[:7]}...{api_key[-4:]}")
+    print(f"  Dashboard: http://localhost:{args.port}\n")
+
+    app.run(host=args.host, port=args.port, threaded=True)
+
+
+def _cmd_setup(args):
+    """First-time setup — create data dirs and generate API key."""
+    from fathom_server import __version__
+    from fathom_server.auth import load_server_config
+    from fathom_server.paths import DATA_DIR
+
+    if not args.yes:
+        print(f"\n  Fathom Server v{__version__}")
+        print(f"  Data directory: {DATA_DIR}")
+        print()
+        confirm = input("  Proceed with setup? [Y/n] ").strip().lower()
+        if confirm and confirm != "y":
+            print("  Aborted.")
+            return
+
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    server_config = load_server_config()
+    api_key = server_config["api_key"]
+    key_is_new = server_config.get("_key_newly_created", False)
+
+    print(f"\n  Fathom Server v{__version__} — setup complete")
+    print(f"  Data directory: {DATA_DIR}")
+    if key_is_new:
+        print(f"  API Key: {api_key}  \u2190 SAVE THIS (shown once)")
+    else:
+        print(f"  API Key: {api_key[:7]}...{api_key[-4:]} (already existed)")
+    print()
+    print("  Next steps:")
+    print("    fathom-server                    # run the server")
+    print("    fathom-server install             # register as a boot service")
+    print()
+
+
+def _cmd_install(args):
+    """Install fathom-server as a systemd user service."""
+    from fathom_server.service import install_service
+
+    install_service(
+        data_dir=args.data_dir,
+        host=args.host,
+        port=args.port,
+        working_dir=args.working_dir,
+        no_start=args.no_start,
+    )
+
+
+def _cmd_uninstall(_args):
+    """Remove the systemd user service."""
+    from fathom_server.service import uninstall_service
+
+    uninstall_service()
+
+
+def main():
+    """Entry point for `fathom-server` CLI command."""
+    parser = argparse.ArgumentParser(description="Fathom Server")
+    sub = parser.add_subparsers(dest="command")
+
+    # -- serve (default when no subcommand given) --
+    serve_p = sub.add_parser("serve", help="Run the server (default)")
+    serve_p.add_argument(
+        "--host", type=str, default=HOST, help=f"Address to bind to (default: {HOST})"
+    )
+    serve_p.add_argument(
+        "--port", type=int, default=PORT, help=f"Port to listen on (default: {PORT})"
+    )
+
+    # -- setup (non-interactive first-time setup, no service) --
+    setup_p = sub.add_parser("setup", help="First-time setup (create data dirs, generate API key)")
+    setup_p.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
+
+    # -- install --
+    install_p = sub.add_parser("install", help="Install as a systemd user service")
+    install_p.add_argument(
+        "--data-dir",
+        type=str,
+        default=None,
+        help="FATHOM_DATA_DIR override (default: ~/.local/share/fathom-server)",
+    )
+    install_p.add_argument("--host", type=str, default=HOST, help=f"Bind address (default: {HOST})")
+    install_p.add_argument("--port", type=int, default=PORT, help=f"Port (default: {PORT})")
+    install_p.add_argument(
+        "--working-dir",
+        type=str,
+        default=None,
+        help="WorkingDirectory for the service (default: home directory)",
+    )
+    install_p.add_argument(
+        "--no-start",
+        action="store_true",
+        help="Install and enable without starting immediately",
+    )
+
+    # -- uninstall --
+    sub.add_parser("uninstall", help="Remove the systemd user service")
+
+    # Also accept --host/--port at top level for backward compat (no subcommand = serve)
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+
+    cli_args = parser.parse_args()
+
+    if cli_args.command == "setup":
+        _cmd_setup(cli_args)
+    elif cli_args.command == "install":
+        _cmd_install(cli_args)
+    elif cli_args.command == "uninstall":
+        _cmd_uninstall(cli_args)
+    elif cli_args.command == "serve":
+        _cmd_serve(cli_args)
+    else:
+        # No subcommand — run serve with top-level flags
+        cli_args.host = cli_args.host or HOST
+        cli_args.port = cli_args.port or PORT
+        _cmd_serve(cli_args)
+
+
+if __name__ == "__main__":
+    main()

fathom_server/auth.py

@@ -0,0 +1,139 @@
+"""API key authentication for fathom-server.
+
+Generates a server API key on first run (stored in data/server.json).
+Provides a Flask middleware decorator to require Bearer token auth on API routes.
+Dashboard routes (serving static files) are exempt.
+"""
+
+import json
+import os
+import secrets
+from functools import wraps
+
+from flask import jsonify, request
+
+from fathom_server.paths import DATA_DIR, SERVER_CONFIG_PATH
+
+_DATA_DIR = str(DATA_DIR)
+_SERVER_CONFIG_PATH = str(SERVER_CONFIG_PATH)
+
+# Prefix makes keys visually identifiable and greppable
+_KEY_PREFIX = "fv_"
+_KEY_BYTES = 24  # 24 bytes = 32 base64 chars
+
+
+def _generate_api_key() -> str:
+    """Generate a new API key with the fv_ prefix."""
+    return _KEY_PREFIX + secrets.token_urlsafe(_KEY_BYTES)
+
+
+def load_server_config() -> dict:
+    """Load server config from data/server.json, creating with defaults if missing.
+
+    Returns the config dict with a transient ``_key_newly_created`` flag
+    (True when the API key was just generated — not persisted to disk).
+    """
+    os.makedirs(_DATA_DIR, exist_ok=True)
+
+    try:
+        with open(_SERVER_CONFIG_PATH) as f:
+            config = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        config = {}
+
+    changed = False
+    key_newly_created = False
+
+    if "api_key" not in config:
+        config["api_key"] = _generate_api_key()
+        changed = True
+        key_newly_created = True
+
+    if "auth_enabled" not in config:
+        config["auth_enabled"] = False  # Off by default for backward compat
+        changed = True
+
+    if changed:
+        save_server_config(config)
+
+    config["_key_newly_created"] = key_newly_created
+    return config
+
+
+def save_server_config(config: dict) -> None:
+    """Persist server config to data/server.json."""
+    os.makedirs(_DATA_DIR, exist_ok=True)
+    with open(_SERVER_CONFIG_PATH, "w") as f:
+        json.dump(config, f, indent=2)
+
+
+def get_api_key() -> str:
+    """Return the current server API key."""
+    return load_server_config()["api_key"]
+
+
+def regenerate_api_key() -> str:
+    """Generate a new API key, invalidating the old one."""
+    config = load_server_config()
+    config["api_key"] = _generate_api_key()
+    save_server_config(config)
+    return config["api_key"]
+
+
+def is_auth_enabled() -> bool:
+    """Check whether API key auth is currently enforced."""
+    return load_server_config().get("auth_enabled", False)
+
+
+def set_auth_enabled(enabled: bool) -> None:
+    """Enable or disable API key auth enforcement."""
+    config = load_server_config()
+    config["auth_enabled"] = enabled
+    save_server_config(config)
+
+
+def require_api_key(f):
+    """Flask route decorator — requires valid Bearer token when auth is enabled.
+
+    When auth is disabled (default), all requests pass through.
+    When auth is enabled, validates Authorization: Bearer <key> header.
+    """
+
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        if not is_auth_enabled():
+            return f(*args, **kwargs)
+
+        auth_header = request.headers.get("Authorization", "")
+        if not auth_header.startswith("Bearer "):
+            return jsonify({"error": "Missing or malformed Authorization header"}), 401
+
+        token = auth_header[7:]  # Strip "Bearer "
+        expected = get_api_key()
+
+        if not secrets.compare_digest(token, expected):
+            return jsonify({"error": "Invalid API key"}), 401
+
+        return f(*args, **kwargs)
+
+    return decorated
+
+
+def validate_token_param(query_string: str) -> bool:
+    """Validate a token query parameter for WebSocket/SSE connections.
+
+    These APIs don't support custom headers, so the token is passed as ?token=KEY.
+    Returns True if auth is disabled or token is valid.
+    """
+    if not is_auth_enabled():
+        return True
+
+    from urllib.parse import parse_qs
+
+    params = parse_qs(query_string)
+    tokens = params.get("token", [])
+    if not tokens:
+        return False
+
+    expected = get_api_key()
+    return secrets.compare_digest(tokens[0], expected)

fathom_server/config.py

@@ -0,0 +1,148 @@
+"""Shared constants and path configuration for Fathom Server."""
+
+import json
+import os
+
+_SETTINGS_FILE = os.path.expanduser("~/.config/fathom-vault/settings.json")
+_DEFAULT_VAULT_DIR = os.environ.get("FATHOM_VAULT_DIR", "")
+
+
+def _read_setting(*keys, default=None):
+    """Read a nested setting from the global settings file."""
+    try:
+        with open(_SETTINGS_FILE) as f:
+            data = json.load(f)
+        for k in keys:
+            data = data[k]
+        return data
+    except (FileNotFoundError, json.JSONDecodeError, KeyError, TypeError):
+        return default
+
+
+def get_workspace_path(workspace=None):
+    """Resolve project root directory for a workspace name.
+
+    Returns (path, None) on success, (None, error_dict) on failure.
+    If workspace is None, returns the default workspace path.
+    Empty or missing path returns (None, error_dict) — not a crash.
+    """
+    workspaces = _read_setting("workspaces", default={})
+    default_ws = _read_setting("default_workspace", default=None)
+
+    if not workspace:
+        if default_ws and workspaces.get(default_ws):
+            entry = workspaces[default_ws]
+            ws_path = entry["path"] if isinstance(entry, dict) else entry
+            if not ws_path:
+                return None, {"error": f'Workspace "{default_ws}" has no local path configured'}
+            return ws_path, None
+        # Legacy fallback — derive from terminal.vault_dir or default
+        vault_dir = _read_setting("terminal", "vault_dir", default=_DEFAULT_VAULT_DIR)
+        return os.path.dirname(vault_dir), None
+
+    ws_entry = workspaces.get(workspace)
+    if not ws_entry:
+        available = list(workspaces.keys()) if workspaces else []
+        return None, {
+            "error": f'Unknown workspace: "{workspace}"',
+            "available_workspaces": available,
+        }
+    # Entry can be a string (legacy) or dict (current)
+    ws_path = ws_entry["path"] if isinstance(ws_entry, dict) else ws_entry
+    if not ws_path:
+        return None, {"error": f'Workspace "{workspace}" has no local path configured'}
+    return ws_path, None
+
+
+def get_vault_path(workspace=None):
+    """Resolve vault directory for a workspace name.
+
+    Vault path = workspace project root + vault subdir (from settings, default "vault").
+    Returns (path, None) on success, (None, error_dict) on failure.
+    """
+    ws_path, err = get_workspace_path(workspace)
+    if err:
+        return None, err
+
+    # Read vault subdir from workspace entry
+    workspaces = _read_setting("workspaces", default={})
+    default_ws = _read_setting("default_workspace", default=None)
+    ws_name = workspace or default_ws
+    ws_entry = workspaces.get(ws_name, {})
+    vault_subdir = ws_entry.get("vault", "vault") if isinstance(ws_entry, dict) else "vault"
+
+    vault_dir = os.path.join(ws_path, vault_subdir) if vault_subdir != "." else ws_path
+    return vault_dir, None
+
+
+def get_workspace_settings_path(workspace=None):
+    """Resolve per-workspace settings file path.
+
+    Returns (<project_root>/.fathom/settings.json, None) on success.
+    """
+    ws_path, err = get_workspace_path(workspace)
+    if err:
+        return None, err
+    return os.path.join(ws_path, ".fathom", "settings.json"), None
+
+
+def get_workspaces():
+    """Return dict of all configured workspaces {name: project_root_path}."""
+    return _read_setting("workspaces", default={})
+
+
+def get_default_workspace():
+    """Return the default workspace name."""
+    return _read_setting("default_workspace", default=None)
+
+
+# Legacy constant — pre-migration reads terminal.vault_dir, post-migration falls back to default.
+# Used by services/indexer.py (until Phase 3 makes it workspace-aware).
+VAULT_DIR = _read_setting("terminal", "vault_dir", default=_DEFAULT_VAULT_DIR)
+FRONTEND_DIR = os.path.join(os.path.dirname(__file__), "static")
+IMAGE_EXTENSIONS = (".png", ".jpg", ".jpeg", ".gif", ".webp")
+HOST = os.environ.get("FATHOM_HOST", "0.0.0.0")
+PORT = int(os.environ.get("FATHOM_PORT", 4243))
+
+# Server-side vault storage — hosted vault files live here, keyed by workspace.
+from fathom_server.paths import VAULT_STORAGE_DIR as _VAULT_STORAGE_PATH  # noqa: E402
+
+VAULT_STORAGE_DIR = str(_VAULT_STORAGE_PATH)
+
+
+def get_vault_storage_path(workspace: str) -> str:
+    """Return the server-side vault storage directory for a workspace."""
+    return os.path.join(VAULT_STORAGE_DIR, workspace)
+
+
+def get_vault_dir_for_dashboard(workspace=None):
+    """Resolve vault directory for dashboard endpoints, respecting vault mode.
+
+    Vault mode is stored as 'type' on the workspace entry:
+      - "local"  → local filesystem vault (get_vault_path)
+      - "synced" / "hosted" → server storage (data/vaults/{workspace}/)
+      - "none"   → vault not configured
+
+    Returns (path, None) on success, (None, error_dict) on failure.
+    """
+    workspaces = _read_setting("workspaces", default={})
+    default_ws = _read_setting("default_workspace", default=None)
+    ws_name = workspace or default_ws
+
+    # Unknown workspace — fall through to get_vault_path for standard error handling
+    ws_entry = workspaces.get(ws_name)
+    if not ws_entry:
+        return get_vault_path(workspace)
+
+    vault_mode = ws_entry.get("type", "local") if isinstance(ws_entry, dict) else "local"
+
+    if vault_mode == "none":
+        return None, {"error": "Vault not configured", "vault_mode": "none"}
+
+    if vault_mode in ("synced", "hosted"):
+        storage_path = get_vault_storage_path(ws_name)
+        os.makedirs(storage_path, exist_ok=True)
+        return storage_path, None
+
+    # Default: local filesystem
+    return get_vault_path(workspace)

fathom_server/paths.py

@@ -0,0 +1,30 @@
+"""Centralized runtime data directory resolution.
+
+After pip install, source files live in read-only site-packages. All mutable data
+(SQLite databases, server config, telegram assets, hosted vaults) must go to a
+runtime data directory instead.
+
+Resolution order:
+  1. FATHOM_DATA_DIR env var (explicit override)
+  2. XDG_DATA_HOME/fathom-server (default: ~/.local/share/fathom-server)
+"""
+
+import os
+from pathlib import Path
+
+_ENV_OVERRIDE = os.environ.get("FATHOM_DATA_DIR")
+
+if _ENV_OVERRIDE:
+    DATA_DIR = Path(_ENV_OVERRIDE)
+else:
+    xdg_data = os.environ.get("XDG_DATA_HOME", os.path.expanduser("~/.local/share"))
+    DATA_DIR = Path(xdg_data) / "fathom-server"
+
+# Ensure it exists on import
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+# Convenience paths used across the codebase
+DB_PATH = DATA_DIR / "access.db"
+SERVER_CONFIG_PATH = DATA_DIR / "server.json"
+VAULT_STORAGE_DIR = DATA_DIR / "vaults"
+TELEGRAM_ASSETS_DIR = DATA_DIR / "telegram-assets"