Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

7.2 KB
Raw Blame
"""Security module for verified file write operations.

This module ensures that file writes only occur when explicitly allowed by configuration,
maintaining the encryption-at-rest security model.
"""

import json
import os
from pathlib import Path
from typing import Any

from loguru import logger

# Platforms without O_NOFOLLOW retain their normal symlink-following behavior.
_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)


def _open_nofollow(path: str, flags: int) -> int:
    """Add supported leaf-symlink refusal to Python's normal open flags."""
    return os.open(path, flags | _O_NOFOLLOW, 0o666)


def _open_nofollow_with_permissions(
    path: str, flags: int, permissions: int
) -> int:
    """Tighten an existing file before truncation, or create it privately."""
    truncate = bool(flags & os.O_TRUNC)
    fd = os.open(path, (flags & ~os.O_TRUNC) | _O_NOFOLLOW, permissions)
    try:
        os.fchmod(fd, permissions)
        if truncate:
            os.ftruncate(fd, 0)
    except BaseException:
        os.close(fd)
        raise
    return fd


# Keys that should never be written to disk in clear text
SENSITIVE_KEYS = frozenset(
    {
        "password",
        "api_key",
        "apikey",
        "api-key",
        "secret",
        "secret_key",
        "secretkey",
        "token",
        "access_token",
        "refresh_token",
        "private_key",
        "privatekey",
        "credentials",
        "auth",
        "authorization",
    }
)


def _sanitize_sensitive_data(data: Any) -> Any:
    """Remove sensitive keys from data before writing to disk.

    Args:
        data: Data to sanitize (dict, list, or primitive)

    Returns:
        Sanitized copy of the data with sensitive keys redacted
    """
    if isinstance(data, dict):
        result = {}
        for key, value in data.items():
            key_lower = key.lower() if isinstance(key, str) else key
            if key_lower in SENSITIVE_KEYS:
                result[key] = "[REDACTED]"
            else:
                result[key] = _sanitize_sensitive_data(value)
        return result
    if isinstance(data, list):
        return [_sanitize_sensitive_data(item) for item in data]
    return data


class FileWriteSecurityError(Exception):
    """Raised when a file write operation is not allowed by security settings."""

    pass


def write_file_verified(
    filepath: str | Path,
    content: str,
    setting_name: str,
    required_value: Any = True,
    context: str = "",
    mode: str = "w",
    encoding: str = "utf-8",
    settings_snapshot: dict = None,
    permissions: int | None = None,
) -> None:
    """Write content to a file only if security settings allow it.

    Args:
        filepath: Path to the file to write
        content: Content to write to the file
        setting_name: Configuration setting name to check (e.g., "api.allow_file_output")
        required_value: Required value for the setting (default: True)
        context: Description of what's being written (for error messages)
        mode: File open mode (default: "w")
        encoding: File encoding (default: "utf-8")
        settings_snapshot: Optional settings snapshot for programmatic mode
        permissions: POSIX file mode for private output. Existing files are
            tightened before their contents are replaced.

    Raises:
        FileWriteSecurityError: If the security setting doesn't match required value
        OSError: errno ELOOP, if the destination leaf is a symlink and the
            platform exposes O_NOFOLLOW

    Example:
        >>> write_file_verified(
        ...     "report.md",
        ...     markdown_content,
        ...     "api.allow_file_output",
        ...     context="API research report"
        ... )
    """
    from ..config.search_config import get_setting_from_snapshot

    try:
        actual_value = get_setting_from_snapshot(
            setting_name, settings_snapshot=settings_snapshot
        )
    except Exception:
        # Setting doesn't exist - default deny
        actual_value = None

    if actual_value != required_value:
        error_msg = (
            f"File write not allowed: {context or 'file operation'}. "
            f"Set '{setting_name}={required_value}' in config to enable this feature."
        )
        logger.warning(error_msg)
        raise FileWriteSecurityError(error_msg)

    # Where O_NOFOLLOW is available, refuse a symlink at the final path
    # component. Parent-directory symlinks and a leaf already dereferenced
    # by the caller's Path.resolve() are outside this check.
    # Let open() validate modes, own the descriptor and handle text/binary
    # translation. This remains an in-place write, not an atomic replacement.
    opener = _open_nofollow
    if permissions is not None:
        if os.name != "posix" or not 0 <= permissions <= 0o777:
            raise ValueError("Private POSIX file permissions are unavailable")

        def private_opener(path: str, flags: int) -> int:
            return _open_nofollow_with_permissions(path, flags, permissions)

        opener = private_opener

    if "b" in mode:
        with open(filepath, mode, opener=opener) as f:  # nosec B603
            f.write(content)
    else:
        with open(filepath, mode, encoding=encoding, opener=opener) as f:  # nosec B603
            f.write(content)

    logger.debug(
        f"Verified file write: {filepath} (setting: {setting_name}={required_value})"
    )


def write_json_verified(
    filepath: str | Path,
    data: dict | list,
    setting_name: str,
    required_value: Any = True,
    context: str = "",
    settings_snapshot: dict = None,
    permissions: int | None = None,
    **json_kwargs,
) -> None:
    """Write JSON data to a file only if security settings allow it.

    Args:
        filepath: Path to the file to write
        data: Dictionary or list to serialize as JSON
        setting_name: Configuration setting name to check
        required_value: Required value for the setting (default: True)
        context: Description of what's being written (for error messages)
        settings_snapshot: Optional settings snapshot for programmatic mode
        permissions: POSIX file mode for private output.
        **json_kwargs: Additional keyword arguments to pass to json.dumps()
                      (e.g., indent=2, ensure_ascii=False, sort_keys=True, default=custom_serializer)

    Raises:
        FileWriteSecurityError: If the security setting doesn't match required value

    Example:
        >>> write_json_verified(
        ...     "results.json",
        ...     {"accuracy": 0.95},
        ...     "benchmark.allow_file_output",
        ...     context="benchmark results",
        ...     indent=2,
        ...     sort_keys=True
        ... )
    """
    # Default to indent=2 if not specified for readability
    if "indent" not in json_kwargs:
        json_kwargs["indent"] = 2

    # Sanitize sensitive data before writing to disk
    sanitized_data = _sanitize_sensitive_data(data)
    content = json.dumps(sanitized_data, **json_kwargs)
    write_file_verified(
        filepath,
        content,
        setting_name,
        required_value,
        context,
        mode="w",
        encoding="utf-8",
        settings_snapshot=settings_snapshot,
        permissions=permissions,
    )