clink-cli 0.2.1__py3-none-any.whl

utils/image_utils.py

@@ -0,0 +1,94 @@
+"""Utility helpers for validating image inputs."""
+
+import base64
+import binascii
+import os
+from collections.abc import Iterable
+
+from utils.file_types import IMAGES, get_image_mime_type
+
+DEFAULT_MAX_IMAGE_SIZE_MB = 20.0
+
+__all__ = ["DEFAULT_MAX_IMAGE_SIZE_MB", "validate_image"]
+
+
+def _valid_mime_types() -> Iterable[str]:
+    """Return the MIME types permitted by the IMAGES whitelist."""
+    return (get_image_mime_type(ext) for ext in IMAGES)
+
+
+def validate_image(image_path: str, max_size_mb: float = None) -> tuple[bytes, str]:
+    """Validate a user-supplied image path or data URL.
+
+    Args:
+        image_path: Either a filesystem path or a data URL.
+        max_size_mb: Optional size limit (defaults to ``DEFAULT_MAX_IMAGE_SIZE_MB``).
+
+    Returns:
+        A tuple ``(image_bytes, mime_type)`` ready for upstream providers.
+
+    Raises:
+        ValueError: When the image is missing, malformed, or exceeds limits.
+    """
+    if max_size_mb is None:
+        max_size_mb = DEFAULT_MAX_IMAGE_SIZE_MB
+
+    if image_path.startswith("data:"):
+        return _validate_data_url(image_path, max_size_mb)
+
+    return _validate_file_path(image_path, max_size_mb)
+
+
+def _validate_data_url(image_data_url: str, max_size_mb: float) -> tuple[bytes, str]:
+    """Validate a data URL and return image bytes plus MIME type."""
+    try:
+        header, data = image_data_url.split(",", 1)
+        mime_type = header.split(";")[0].split(":")[1]
+    except (ValueError, IndexError) as exc:
+        raise ValueError(f"Invalid data URL format: {exc}")
+
+    valid_mime_types = list(_valid_mime_types())
+    if mime_type not in valid_mime_types:
+        raise ValueError(
+            "Unsupported image type: {mime}. Supported types: {supported}".format(
+                mime=mime_type, supported=", ".join(valid_mime_types)
+            )
+        )
+
+    try:
+        image_bytes = base64.b64decode(data)
+    except binascii.Error as exc:
+        raise ValueError(f"Invalid base64 data: {exc}")
+
+    _validate_size(image_bytes, max_size_mb)
+    return image_bytes, mime_type
+
+
+def _validate_file_path(file_path: str, max_size_mb: float) -> tuple[bytes, str]:
+    """Validate an image loaded from the filesystem."""
+    try:
+        with open(file_path, "rb") as handle:
+            image_bytes = handle.read()
+    except FileNotFoundError:
+        raise ValueError(f"Image file not found: {file_path}")
+    except OSError as exc:
+        raise ValueError(f"Failed to read image file: {exc}")
+
+    ext = os.path.splitext(file_path)[1].lower()
+    if ext not in IMAGES:
+        raise ValueError(
+            "Unsupported image format: {ext}. Supported formats: {supported}".format(
+                ext=ext, supported=", ".join(sorted(IMAGES))
+            )
+        )
+
+    mime_type = get_image_mime_type(ext)
+    _validate_size(image_bytes, max_size_mb)
+    return image_bytes, mime_type
+
+
+def _validate_size(image_bytes: bytes, max_size_mb: float) -> None:
+    """Ensure the image does not exceed the configured size limit."""
+    size_mb = len(image_bytes) / (1024 * 1024)
+    if size_mb > max_size_mb:
+        raise ValueError(f"Image too large: {size_mb:.1f}MB (max: {max_size_mb}MB)")

utils/security_config.py

@@ -0,0 +1,163 @@
+"""
+Security configuration and path validation constants
+
+This module contains security-related constants and configurations
+for file access control.
+"""
+
+from pathlib import Path
+
+# Dangerous system paths - block these AND all their subdirectories
+# These are system directories where user code should never reside
+DANGEROUS_SYSTEM_PATHS = {
+    "/",
+    "/etc",
+    "/usr",
+    "/bin",
+    "/var",
+    "/root",
+    "C:\\Windows",
+    "C:\\Program Files",
+}
+
+# User home container paths - block ONLY the exact path, not subdirectories
+# Subdirectory access (e.g., /home/user/project) is controlled by is_home_directory_root()
+# This allows users to work in their home subdirectories while blocking overly broad access
+DANGEROUS_HOME_CONTAINERS = {
+    "/home",
+    "C:\\Users",
+}
+
+# Combined set for backward compatibility
+DANGEROUS_PATHS = DANGEROUS_SYSTEM_PATHS | DANGEROUS_HOME_CONTAINERS
+
+# Directories to exclude from recursive file search
+# These typically contain generated code, dependencies, or build artifacts
+EXCLUDED_DIRS = {
+    # Python
+    "__pycache__",
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    "*.egg-info",
+    ".eggs",
+    "wheels",
+    ".Python",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".tox",
+    "htmlcov",
+    ".coverage",
+    "coverage",
+    # Node.js / JavaScript
+    "node_modules",
+    ".next",
+    ".nuxt",
+    "bower_components",
+    ".sass-cache",
+    # Version Control
+    ".git",
+    ".svn",
+    ".hg",
+    # Build Output
+    "build",
+    "dist",
+    "target",
+    "out",
+    # IDEs
+    ".idea",
+    ".vscode",
+    ".sublime",
+    ".atom",
+    ".brackets",
+    # Temporary / Cache
+    ".cache",
+    ".temp",
+    ".tmp",
+    "*.swp",
+    "*.swo",
+    "*~",
+    # OS-specific
+    ".DS_Store",
+    "Thumbs.db",
+    # Java / JVM
+    ".gradle",
+    ".m2",
+    # Documentation build
+    "_build",
+    "site",
+    # Mobile development
+    ".expo",
+    ".flutter",
+    # Package managers
+    "vendor",
+}
+
+
+def is_dangerous_path(path: Path) -> bool:
+    """
+    Check if a path is in or under a dangerous directory.
+
+    This function handles two categories of dangerous paths differently:
+
+    1. System paths (DANGEROUS_SYSTEM_PATHS): Block the path AND all subdirectories.
+       Example: /etc is dangerous, so /etc/passwd is also blocked.
+
+    2. Home containers (DANGEROUS_HOME_CONTAINERS): Block ONLY the exact path.
+       Example: /home is blocked, but /home/user/project is allowed.
+       Subdirectory access control is delegated to is_home_directory_root().
+
+    Args:
+        path: Path to check
+
+    Returns:
+        True if the path is dangerous and should not be accessed
+
+    Security:
+        Fixes path traversal vulnerability (CWE-22) while preserving
+        user access to home subdirectories.
+    """
+    try:
+        resolved = path.resolve()
+
+        def _dangerous_variants(p: Path) -> set[Path]:
+            variants = {p}
+            # Only resolve paths that are absolute on the current platform.
+            # This avoids turning Windows-style strings into nonsense absolute paths on POSIX.
+            if p.is_absolute():
+                try:
+                    variants.add(p.resolve())
+                except Exception:
+                    pass
+            return variants
+
+        # Check 1: Root directory (filesystem root)
+        if resolved.parent == resolved:
+            return True
+
+        # Check 2: System paths - block exact match AND all subdirectories
+        for dangerous in DANGEROUS_SYSTEM_PATHS:
+            # Skip root "/" - already handled above
+            if dangerous == "/":
+                continue
+
+            for dangerous_path in _dangerous_variants(Path(dangerous)):
+                # is_relative_to() correctly handles both exact matches and subdirectories.
+                # Resolving the dangerous base path also handles platform symlinks
+                # (e.g., macOS /etc -> /private/etc, /var -> /private/var).
+                if resolved == dangerous_path or resolved.is_relative_to(dangerous_path):
+                    return True
+
+        # Check 3: Home containers - block ONLY exact match
+        # Subdirectories like /home/user/project should pass through here
+        # and be handled by is_home_directory_root() in resolve_and_validate_path()
+        for container in DANGEROUS_HOME_CONTAINERS:
+            for container_path in _dangerous_variants(Path(container)):
+                if resolved == container_path:
+                    return True
+
+        return False
+
+    except Exception:
+        return True  # If we can't resolve, consider it dangerous

utils/storage_backend.py

@@ -0,0 +1,177 @@
+"""Bounded, process-local conversation storage with atomic admission reservations."""
+
+import asyncio
+import logging
+import threading
+import time
+from collections.abc import Callable
+from contextlib import asynccontextmanager
+
+logger = logging.getLogger(__name__)
+
+MAX_ACTIVE_THREADS = 256
+MAX_STORAGE_BYTES = 64 * 1024 * 1024
+
+
+class StorageCapacityError(RuntimeError):
+    """The process cannot admit another record without evicting live state."""
+
+
+class InMemoryStorage:
+    """Keep expiring JSON records; never evict a live conversation for capacity."""
+
+    def __init__(
+        self,
+        max_threads: int = MAX_ACTIVE_THREADS,
+        max_bytes: int = MAX_STORAGE_BYTES,
+        clock: Callable[[], float] = time.time,
+    ):
+        self._store: dict[str, tuple[str, float]] = {}
+        self._lock = threading.RLock()
+        self._reservations: dict[str, int] = {}
+        self._async_locks: dict[str, tuple[asyncio.Lock, int]] = {}
+        self.max_threads = max_threads
+        self.max_bytes = max_bytes
+        self._clock = clock
+        self._stop = threading.Event()
+        self._cleanup_thread = threading.Thread(target=self._cleanup_worker, daemon=True)
+        self._cleanup_thread.start()
+
+    @staticmethod
+    def _size(value: str) -> int:
+        return len(value.encode("utf-8"))
+
+    def _cleanup_expired_locked(self) -> None:
+        now = self._clock()
+        for key, (_, expires_at) in list(self._store.items()):
+            # A reserved operation owns its record until its terminal update.
+            if expires_at <= now and key not in self._reservations:
+                del self._store[key]
+                self._discard_idle_lock(key)
+
+    def _discard_idle_lock(self, key: str) -> None:
+        entry = self._async_locks.get(key)
+        if entry is not None and entry[1] == 0 and key not in self._store:
+            del self._async_locks[key]
+
+    def _check_capacity(self, key: str, value: str, reservation: int = 0) -> None:
+        old_size = self._size(self._store[key][0]) if key in self._store else 0
+        total = sum(self._size(item[0]) for item in self._store.values()) - old_size + self._size(value)
+        total += sum(size for reserved_key, size in self._reservations.items() if reserved_key != key)
+        if key not in self._store and len(self._store) >= self.max_threads:
+            raise StorageCapacityError("Conversation capacity reached; wait for an existing conversation to expire.")
+        if total + reservation > self.max_bytes:
+            raise StorageCapacityError("Conversation storage is full; wait for existing conversations to expire.")
+
+    def set_with_ttl(self, key: str, ttl_seconds: int, value: str) -> None:
+        """Atomically admit a record, respecting every outstanding reservation."""
+        with self._lock:
+            self._cleanup_expired_locked()
+            if key in self._reservations:
+                raise RuntimeError("Conversation is owned by an active transaction")
+            self._check_capacity(key, value)
+            self._store[key] = (value, self._clock() + ttl_seconds)
+
+    def get(self, key: str) -> str | None:
+        with self._lock:
+            self._cleanup_expired_locked()
+            entry = self._store.get(key)
+            return entry[0] if entry is not None else None
+
+    def setex(self, key: str, ttl_seconds: int, value: str) -> None:
+        self.set_with_ttl(key, ttl_seconds, value)
+
+    def update(self, key: str, ttl_seconds: int, transform: Callable[[str], str]) -> bool:
+        """Apply a synchronous legacy helper update without losing concurrent turns."""
+        with self._lock:
+            current = self.get(key)
+            if current is None:
+                return False
+            self.setex(key, ttl_seconds, transform(current))
+            return True
+
+    def reserve(self, key: str, ttl_seconds: int, initial_value: str | None, extra_bytes: int) -> None:
+        """Reserve a live slot and worst-case terminal growth before external work."""
+        with self._lock:
+            self._cleanup_expired_locked()
+            existing = self._store.get(key)
+            value = existing[0] if existing is not None else initial_value
+            if value is None:
+                raise KeyError(key)
+            if key in self._reservations:
+                raise RuntimeError("Conversation already has a reservation")
+            self._check_capacity(key, value, extra_bytes)
+            if existing is None:
+                self._store[key] = (value, self._clock() + ttl_seconds)
+            self._reservations[key] = extra_bytes
+
+    def commit_reserved(self, key: str, ttl_seconds: int, value: str) -> None:
+        """Publish a complete terminal record and release its growth reservation."""
+        with self._lock:
+            if key not in self._reservations or key not in self._store:
+                raise RuntimeError("Conversation has no active reservation")
+            previous_size = self._size(self._store[key][0])
+            if self._size(value) > previous_size + self._reservations[key]:
+                raise StorageCapacityError("Terminal conversation state exceeds its admitted storage reservation.")
+            self._check_capacity(key, value)
+            self._store[key] = (value, self._clock() + ttl_seconds)
+            del self._reservations[key]
+
+    def release_reservation(self, key: str) -> None:
+        with self._lock:
+            self._reservations.pop(key, None)
+            self._cleanup_expired_locked()
+
+    @asynccontextmanager
+    async def serialize(self, key: str, deadline: float | None = None):
+        """Serialize one continuation through its terminal update; include lock wait in deadline."""
+        with self._lock:
+            lock, users = self._async_locks.get(key, (asyncio.Lock(), 0))
+            self._async_locks[key] = (lock, users + 1)
+        acquired = False
+        try:
+            if deadline is None:
+                await lock.acquire()
+            else:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise asyncio.TimeoutError
+                await asyncio.wait_for(lock.acquire(), remaining)
+            acquired = True
+            if deadline is not None and time.monotonic() >= deadline:
+                raise asyncio.TimeoutError
+            yield
+        finally:
+            if acquired:
+                lock.release()
+            with self._lock:
+                _, users = self._async_locks[key]
+                self._async_locks[key] = (lock, users - 1)
+                self._discard_idle_lock(key)
+
+    def _cleanup_worker(self) -> None:
+        while not self._stop.wait(300):
+            self._cleanup_expired()
+
+    def _cleanup_expired(self) -> None:
+        with self._lock:
+            self._cleanup_expired_locked()
+
+    def shutdown(self) -> None:
+        self._stop.set()
+        if self._cleanup_thread.is_alive():
+            self._cleanup_thread.join(timeout=1)
+
+
+_storage_instance = None
+_storage_lock = threading.Lock()
+
+
+def get_storage_backend() -> InMemoryStorage:
+    """Return the process-local storage instance."""
+    global _storage_instance
+    if _storage_instance is None:
+        with _storage_lock:
+            if _storage_instance is None:
+                _storage_instance = InMemoryStorage()
+    return _storage_instance

utils/token_utils.py

@@ -0,0 +1,54 @@
+"""
+Token counting utilities for managing API context limits
+
+This module provides functions for estimating token counts to ensure
+requests stay within the Gemini API's context window limits.
+
+Note: The estimation uses a simple character-to-token ratio which is
+approximate. For production systems requiring precise token counts,
+consider using the actual tokenizer for the specific model.
+"""
+
+# Default fallback for token limit (conservative estimate)
+DEFAULT_CONTEXT_WINDOW = 200_000  # Conservative fallback for unknown models
+
+
+def estimate_tokens(text: str) -> int:
+    """
+    Estimate token count using a character-based approximation.
+
+    This uses a rough heuristic where 1 token ≈ 4 characters, which is
+    a reasonable approximation for English text. The actual token count
+    may vary based on:
+    - Language (non-English text may have different ratios)
+    - Code vs prose (code often has more tokens per character)
+    - Special characters and formatting
+
+    Args:
+        text: The text to estimate tokens for
+
+    Returns:
+        int: Estimated number of tokens
+    """
+    return len(text) // 4
+
+
+def check_token_limit(text: str, context_window: int = DEFAULT_CONTEXT_WINDOW) -> tuple[bool, int]:
+    """
+    Check if text exceeds the specified token limit.
+
+    This function is used to validate that prepared prompts will fit
+    within the model's context window, preventing API errors and ensuring
+    reliable operation.
+
+    Args:
+        text: The text to check
+        context_window: The model's context window size (defaults to conservative fallback)
+
+    Returns:
+        Tuple[bool, int]: (is_within_limit, estimated_tokens)
+        - is_within_limit: True if the text fits within context_window
+        - estimated_tokens: The estimated token count
+    """
+    estimated = estimate_tokens(text)
+    return estimated <= context_window, estimated