tangle-cli 0.0.1a1__py3-none-any.whl

tangle_cli/hydration_trust.py

@@ -0,0 +1,222 @@
+"""Trust controls for hydration features that can execute local Python code."""
+
+from __future__ import annotations
+
+import os
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+
+_TRUSTED_PYTHON_SOURCES: list[str] = []
+_ALLOW_ALL_HYDRATION = False
+_PACKAGE_CONFIG = Path(__file__).with_name("trusted_hydration.yaml")
+_USER_CONFIGS = (
+    Path.home() / ".config" / "tangle" / "trusted_hydration.yaml",
+    Path.home() / ".tangle" / "trusted_hydration.yaml",
+)
+_GLOB_CHARS = set("*?[")
+
+
+def register_trusted_python_source(source: str | os.PathLike[str]) -> None:
+    """Register a trusted Python-source root or glob pattern.
+
+    Sources are matched against canonical resolved paths.  A non-glob source
+    trusts the exact file if it resolves to a file (or ends in ``.py``), and a
+    directory subtree otherwise.  Glob sources are resolved up to their first
+    glob segment and matched against resolved candidate paths.
+    """
+
+    text = str(source).strip()
+    if text:
+        _TRUSTED_PYTHON_SOURCES.append(text)
+
+
+def set_allow_all_hydration(allow: bool = True) -> None:
+    """Set a process-wide escape hatch for trusted hydration execution."""
+
+    global _ALLOW_ALL_HYDRATION
+    _ALLOW_ALL_HYDRATION = bool(allow)
+
+
+def is_trusted_python_source(
+    path: str | os.PathLike[str],
+    *,
+    base_dirs: Iterable[str | os.PathLike[str] | None] | None = None,
+    trusted_sources: Iterable[str | os.PathLike[str]] | None = None,
+    allow_all: bool = False,
+) -> bool:
+    """Return whether *path* may be executed for ``local_from_python``.
+
+    The candidate path and every root/pattern prefix are canonicalized with
+    :meth:`Path.resolve` before matching so ``..`` traversal and symlink escapes
+    cannot extend trust outside the intended boundary.
+    """
+
+    if allow_all or _ALLOW_ALL_HYDRATION or _env_allow_all():
+        return True
+
+    candidate = _canonical(path)
+    if candidate is None:
+        return False
+
+    for base_dir in base_dirs or ():
+        if base_dir and _is_within(candidate, _canonical(base_dir)):
+            return True
+
+    for source in _all_configured_sources(trusted_sources):
+        if _matches_source(candidate, str(source)):
+            return True
+
+    return False
+
+
+def configured_trusted_python_sources(
+    extra_sources: Iterable[str | os.PathLike[str]] | None = None,
+) -> list[str]:
+    """Return trusted Python-source patterns from registry/config/env/extras."""
+
+    return [str(source) for source in _all_configured_sources(extra_sources)]
+
+
+def _all_configured_sources(
+    extra_sources: Iterable[str | os.PathLike[str]] | None = None,
+) -> list[str]:
+    sources: list[str] = []
+    sources.extend(_TRUSTED_PYTHON_SOURCES)
+    sources.extend(_load_configured_sources())
+    sources.extend(_env_trusted_sources())
+    if extra_sources:
+        sources.extend(str(source) for source in extra_sources if str(source).strip())
+    return sources
+
+
+def _env_allow_all() -> bool:
+    value = os.environ.get("TANGLE_TRUSTED_HYDRATION_ALLOW_ALL")
+    return bool(value and value.strip().lower() in {"1", "true", "yes", "on"})
+
+
+def _env_trusted_sources() -> list[str]:
+    value = os.environ.get("TANGLE_TRUSTED_PYTHON_SOURCES", "")
+    if not value.strip():
+        return []
+    parts: list[str] = []
+    for chunk in value.replace(",", os.pathsep).split(os.pathsep):
+        chunk = chunk.strip()
+        if chunk:
+            parts.append(chunk)
+    return parts
+
+
+def _load_configured_sources() -> list[str]:
+    sources: list[str] = []
+    for path in _config_paths():
+        sources.extend(_load_sources_from_file(path))
+    return sources
+
+
+def _config_paths() -> list[Path]:
+    paths = [_PACKAGE_CONFIG, *_USER_CONFIGS]
+    override = os.environ.get("TANGLE_TRUSTED_HYDRATION_CONFIG")
+    if override:
+        paths.append(Path(override).expanduser())
+    return paths
+
+
+def _load_sources_from_file(path: Path) -> list[str]:
+    if not path.exists():
+        return []
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+    trusted = data.get("trusted_hydration", data) if isinstance(data, dict) else data
+    if not isinstance(trusted, dict):
+        return []
+    raw = trusted.get("trusted_python_sources", [])
+    if isinstance(raw, str):
+        return [raw]
+    if isinstance(raw, list):
+        return [str(item) for item in raw if str(item).strip()]
+    return []
+
+
+def _canonical(path: str | os.PathLike[str] | None) -> Path | None:
+    if path is None:
+        return None
+    try:
+        return Path(path).expanduser().resolve()
+    except OSError:
+        return None
+
+
+def _is_within(candidate: Path, root: Path | None) -> bool:
+    if root is None:
+        return False
+    return candidate == root or root in candidate.parents
+
+
+def _matches_source(candidate: Path, source: str) -> bool:
+    source = os.path.expandvars(source.strip())
+    if not source:
+        return False
+    if any(char in source for char in _GLOB_CHARS):
+        return _matches_glob_source(candidate, source)
+    root = _canonical(source)
+    if root is None:
+        return False
+    source_path = Path(source)
+    if root.is_file() or source_path.suffix == ".py":
+        return candidate == root
+    return _is_within(candidate, root)
+
+
+def _matches_glob_source(candidate: Path, source: str) -> bool:
+    raw = Path(source).expanduser()
+    parts = raw.parts
+    first_glob = next(
+        (index for index, part in enumerate(parts) if any(char in part for char in _GLOB_CHARS)),
+        None,
+    )
+    if first_glob is None:
+        return _matches_source(candidate, source)
+    prefix_parts = parts[:first_glob]
+    suffix_parts = parts[first_glob:]
+    if prefix_parts:
+        prefix = Path(*prefix_parts).resolve()
+    else:
+        prefix = Path.cwd().resolve()
+    try:
+        relative_candidate = candidate.relative_to(prefix)
+    except ValueError:
+        return False
+    return _match_path_parts(relative_candidate.parts, suffix_parts)
+
+
+def _match_path_parts(candidate_parts: tuple[str, ...], pattern_parts: tuple[str, ...]) -> bool:
+    if not pattern_parts:
+        return not candidate_parts
+    pattern = pattern_parts[0]
+    remaining_patterns = pattern_parts[1:]
+    if pattern == "**":
+        return any(
+            _match_path_parts(candidate_parts[index:], remaining_patterns)
+            for index in range(len(candidate_parts) + 1)
+        )
+    if not candidate_parts:
+        return False
+    return fnmatchcase(candidate_parts[0], pattern) and _match_path_parts(candidate_parts[1:], remaining_patterns)
+
+
+def trusted_python_source_guidance(path: str | os.PathLike[str]) -> str:
+    """Human-readable refusal guidance for an untrusted Python source."""
+
+    return (
+        f"Refusing to execute untrusted local_from_python source {Path(path).expanduser()}. "
+        "Add an allowlisted trusted Python source with --trusted-source, "
+        "trusted_hydration.trusted_python_sources in config, "
+        "TANGLE_TRUSTED_PYTHON_SOURCES, or register_trusted_python_source(); "
+        "or use --trusted-hydration / set_allow_all_hydration() for trusted inputs. "
+        "You can also pre-hydrate trusted specs and submit them with --no-hydrate."
+    )

tangle_cli/logger.py

@@ -0,0 +1,166 @@
+"""Structured logging for tangle-cli.
+
+Provides an injectable logger abstraction so library code never calls print()
+directly.  CLI entry points use the default :class:`ConsoleLogger` (same
+behaviour as bare ``print``).  Wrappers that need to capture output (an MCP
+server, a test harness, etc.) inject a :class:`CaptureLogger` that
+accumulates messages in memory and returns them as a single string.
+
+CLI commands use :func:`run_with_logging` to handle the ``--log-type`` flag
+uniformly::
+
+    run_with_logging(log_type, lambda logger: my_core_func(..., logger=logger))
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from typing import Any, Callable, Protocol
+
+
+class Logger(Protocol):
+    """Minimal logging protocol for Tangle tooling."""
+
+    def info(self, msg: str) -> None: ...
+    def warn(self, msg: str) -> None: ...
+    def error(self, msg: str) -> None: ...
+
+
+class ConsoleLogger:
+    """Default logger — prints to stderr so structured output on stdout stays clean."""
+
+    def info(self, msg: str) -> None:
+        print(msg, file=sys.stderr, flush=True)
+
+    def warn(self, msg: str) -> None:
+        print(msg, file=sys.stderr, flush=True)
+
+    def error(self, msg: str) -> None:
+        print(msg, file=sys.stderr, flush=True)
+
+
+class CaptureLogger:
+    """Logger for MCP: accumulates messages in memory.
+
+    Use :meth:`get_logs` to retrieve the collected output as a single string.
+    """
+
+    def __init__(self) -> None:
+        self._messages: list[str] = []
+
+    def info(self, msg: str) -> None:
+        self._messages.append(msg)
+
+    def warn(self, msg: str) -> None:
+        self._messages.append(msg)
+
+    def error(self, msg: str) -> None:
+        self._messages.append(f"[error] {msg}")
+
+    def get_logs(self) -> str | None:
+        """Return accumulated logs as a single string, or None if empty."""
+        text = "\n".join(self._messages).strip()
+        return text if text else None
+
+
+class NullLogger:
+    """Logger that discards all messages. Used by MCP when include_logs is False."""
+
+    def info(self, msg: str) -> None:
+        pass
+
+    def warn(self, msg: str) -> None:
+        pass
+
+    def error(self, msg: str) -> None:
+        pass
+
+
+_default_logger = ConsoleLogger()
+_null_logger = NullLogger()
+
+
+def get_default_logger() -> ConsoleLogger:
+    """Return the module-level default :class:`ConsoleLogger`."""
+    return _default_logger
+
+
+# Valid log_type values for CLI commands. Keep this as ``str`` because Typer
+# does not support Literal annotations for option parameters.
+CliLogType = str
+
+
+class LogFinalizer(Protocol):
+    def __call__(self) -> None: ...
+
+
+def logger_for_log_type(log_type: CliLogType) -> tuple[Logger, LogFinalizer]:
+    """Return a logger/finalizer pair for TD-compatible CLI log types.
+
+    ``console`` logs to stderr, ``none`` discards logs, and ``file`` captures
+    logs to a temporary file whose path is printed to stderr by the finalizer.
+    Callers that need custom structured stdout handling can use this lower-level
+    helper instead of :func:`run_with_logging`.
+    """
+
+    if log_type == "console":
+        return _default_logger, lambda: None
+    if log_type == "none":
+        return _null_logger, lambda: None
+    if log_type == "file":
+        capture = CaptureLogger()
+
+        def finalize() -> None:
+            if logs := capture.get_logs():
+                with tempfile.NamedTemporaryFile(
+                    mode="w", suffix=".log", prefix="tangle_", delete=False,
+                ) as f:
+                    f.write(logs)
+                print(f"\nLogs written to: {f.name}", file=sys.stderr)
+
+        return capture, finalize
+    raise SystemExit("--log-type must be one of: console, none, file")
+
+
+def _print_result(result: Any) -> None:
+    """Print a function result as JSON (dicts) or plain text.
+
+    Uses plain :func:`print` so this module has no CLI-framework
+    dependency.  Concrete CLI wrappers built on top of ``tangle-cli``
+    can wrap this with ``typer.echo`` / ``click.echo`` if they need
+    terminal-aware encoding handling.
+    """
+    if result is None:
+        return
+    if isinstance(result, dict):
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(result)
+
+
+def run_with_logging(
+    log_type: CliLogType,
+    fn: Callable[[Logger], dict[str, Any] | Any],
+) -> None:
+    """Run *fn* with the appropriate logger for *log_type*, then handle output.
+
+    This is the universal CLI wrapper for the ``--log-type`` flag:
+
+    - **console** (default): logs stream to stdout/stderr via :class:`ConsoleLogger`.
+      If *fn* returns a non-None result, it is printed as JSON after the logs.
+    - **none**: logs are discarded. The function result is printed as JSON.
+    - **file**: logs are captured and written to a temp file whose path is
+      printed to stderr. The function result is printed as JSON.
+
+    *fn* receives a :class:`Logger` and should return a dict (or any value).
+    Return ``None`` to suppress result output (useful when the logs *are* the output).
+    """
+    logger, finalize = logger_for_log_type(log_type)
+
+    try:
+        result = fn(logger)
+        _print_result(result)
+    finally:
+        finalize()