coding-client 1.21.2__py3-none-any.whl

coding_client/utils/security_validation.py

@@ -0,0 +1,423 @@
+"""File security and validation utilities.
+
+This module provides utilities for file security validation, size checks,
+hash calculations, and permission validation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import stat
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from .constants import CHUNK_SIZE, MAX_FILE_SIZE
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityValidationError(Exception):
+    """Base exception for security validation operations."""
+
+    pass
+
+
+class FileSizeError(SecurityValidationError):
+    """Raised when file size exceeds limits."""
+
+    pass
+
+
+class FilePermissionError(SecurityValidationError):
+    """Raised when file permissions prevent operation."""
+
+    pass
+
+
+class FileNotFoundError(SecurityValidationError):
+    """Raised when file is not found."""
+
+    pass
+
+
+class InvalidPathError(SecurityValidationError):
+    """Raised when path is invalid or unsafe."""
+
+    pass
+
+
+def validate_file_access(
+    file_path: str | Path,
+    max_size: int | None = MAX_FILE_SIZE,
+    check_readable: bool = True,
+    check_writable: bool = False,
+) -> None:
+    """Validate file access and basic security checks."""
+    path = Path(file_path)
+
+    # Check if file exists
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    # Check if it's actually a file
+    if not path.is_file():
+        raise InvalidPathError(f"Not a file: {path}")
+
+    # Check file size
+    if max_size is not None:
+        file_size = path.stat().st_size
+        if file_size > max_size:
+            raise FileSizeError(f"File too large: {file_size} bytes (max: {max_size})")
+
+    # Check permissions
+    if check_readable and not os.access(path, os.R_OK):
+        raise FilePermissionError(f"File not readable: {path}")
+
+    if check_writable and not os.access(path, os.W_OK):
+        raise FilePermissionError(f"File not writable: {path}")
+
+
+def validate_directory_access(
+    dir_path: str | Path,
+    check_readable: bool = True,
+    check_writable: bool = False,
+    check_executable: bool = True,
+) -> None:
+    """Validate directory access and permissions."""
+    path = Path(dir_path)
+
+    # Check if directory exists
+    if not path.exists():
+        raise FileNotFoundError(f"Directory not found: {path}")
+
+    # Check if it's actually a directory
+    if not path.is_dir():
+        raise InvalidPathError(f"Not a directory: {path}")
+
+    # Check permissions
+    if check_readable and not os.access(path, os.R_OK):
+        raise FilePermissionError(f"Directory not readable: {path}")
+
+    if check_writable and not os.access(path, os.W_OK):
+        raise FilePermissionError(f"Directory not writable: {path}")
+
+    if check_executable and not os.access(path, os.X_OK):
+        raise FilePermissionError(f"Directory not executable: {path}")
+
+
+def get_file_size(file_path: str | Path) -> int:
+    """Get file size in bytes."""
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    try:
+        return path.stat().st_size
+    except Exception as e:
+        raise SecurityValidationError(f"Failed to get file size: {e}") from e
+
+
+def get_file_hash(
+    file_path: str | Path,
+    algorithm: str = "sha256",
+    chunk_size: int = CHUNK_SIZE,
+) -> str:
+    """Calculate file hash."""
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    try:
+        hash_obj = hashlib.new(algorithm)
+
+        with open(path, "rb") as f:
+            while chunk := f.read(chunk_size):
+                hash_obj.update(chunk)
+
+        return hash_obj.hexdigest()
+    except Exception as e:
+        raise SecurityValidationError(f"Failed to calculate hash: {e}") from e
+
+
+def verify_file_hash(
+    file_path: str | Path,
+    expected_hash: str,
+    algorithm: str = "sha256",
+) -> bool:
+    """Verify file hash matches expected value."""
+    try:
+        actual_hash = get_file_hash(file_path, algorithm)
+        return actual_hash.lower() == expected_hash.lower()
+    except Exception as e:
+        raise SecurityValidationError(f"Hash verification failed: {e}") from e
+
+
+def get_file_permissions(file_path: str | Path) -> dict[str, bool]:
+    """Get file permission details."""
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    try:
+        file_stat = path.stat()
+        mode = file_stat.st_mode
+
+        return {
+            "owner_read": bool(mode & stat.S_IRUSR),
+            "owner_write": bool(mode & stat.S_IWUSR),
+            "owner_execute": bool(mode & stat.S_IXUSR),
+            "group_read": bool(mode & stat.S_IRGRP),
+            "group_write": bool(mode & stat.S_IWGRP),
+            "group_execute": bool(mode & stat.S_IXGRP),
+            "other_read": bool(mode & stat.S_IROTH),
+            "other_write": bool(mode & stat.S_IWOTH),
+            "other_execute": bool(mode & stat.S_IXOTH),
+            "is_suid": bool(mode & stat.S_ISUID),
+            "is_sgid": bool(mode & stat.S_ISGID),
+            "is_sticky": bool(mode & stat.S_ISVTX),
+        }
+    except Exception as e:
+        raise SecurityValidationError(f"Failed to get permissions: {e}") from e
+
+
+def is_safe_filename(filename: str) -> bool:
+    """Check if filename is safe (no path traversal, etc.)."""
+    # Check for empty or None
+    if not filename:
+        return False
+
+    # Check for path separators
+    if os.sep in filename or os.altsep and os.altsep in filename:
+        return False
+
+    # Check for current/parent directory references
+    if filename in (".", ".."):
+        return False
+
+    # Check for null bytes
+    if "\x00" in filename:
+        return False
+
+    # Check for control characters
+    if any(ord(char) < 32 for char in filename):
+        return False
+
+    # Check for reserved names on Windows
+    reserved_names = {
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        "COM1",
+        "COM2",
+        "COM3",
+        "COM4",
+        "COM5",
+        "COM6",
+        "COM7",
+        "COM8",
+        "COM9",
+        "LPT1",
+        "LPT2",
+        "LPT3",
+        "LPT4",
+        "LPT5",
+        "LPT6",
+        "LPT7",
+        "LPT8",
+        "LPT9",
+    }
+
+    name_upper = filename.upper()
+    if name_upper in reserved_names or name_upper.split(".")[0] in reserved_names:
+        return False
+
+    return True
+
+
+def sanitize_filename(filename: str, replacement: str = "_") -> str:
+    """Sanitize filename by replacing unsafe characters."""
+    if not filename:
+        return "unnamed"
+
+    # Replace path separators
+    safe_name = filename.replace(os.sep, replacement)
+    if os.altsep:
+        safe_name = safe_name.replace(os.altsep, replacement)
+
+    # Replace control characters and null bytes
+    safe_chars = []
+    for char in safe_name:
+        if ord(char) < 32 or char == "\x00":
+            safe_chars.append(replacement)
+        else:
+            safe_chars.append(char)
+
+    safe_name = "".join(safe_chars)
+
+    # Handle reserved names
+    reserved_names = {
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        "COM1",
+        "COM2",
+        "COM3",
+        "COM4",
+        "COM5",
+        "COM6",
+        "COM7",
+        "COM8",
+        "COM9",
+        "LPT1",
+        "LPT2",
+        "LPT3",
+        "LPT4",
+        "LPT5",
+        "LPT6",
+        "LPT7",
+        "LPT8",
+        "LPT9",
+    }
+
+    name_upper = safe_name.upper()
+    if name_upper in reserved_names or name_upper.split(".")[0] in reserved_names:
+        safe_name = f"file_{safe_name}"
+
+    # Ensure not empty after sanitization
+    if not safe_name or safe_name == replacement:
+        safe_name = "unnamed"
+
+    return safe_name
+
+
+def get_file_info(file_path: str | Path) -> dict[str, Any]:
+    """Get comprehensive file information including security details."""
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    try:
+        file_stat = path.stat()
+
+        return {
+            "path": str(path.absolute()),
+            "name": path.name,
+            "size": file_stat.st_size,
+            "created": datetime.fromtimestamp(file_stat.st_ctime),
+            "modified": datetime.fromtimestamp(file_stat.st_mtime),
+            "accessed": datetime.fromtimestamp(file_stat.st_atime),
+            "is_file": path.is_file(),
+            "is_dir": path.is_dir(),
+            "is_symlink": path.is_symlink(),
+            "suffix": path.suffix,
+            "suffixes": path.suffixes,
+            "stem": path.stem,
+            "parent": str(path.parent),
+            "permissions": get_file_permissions(path),
+            "owner_uid": file_stat.st_uid,
+            "group_gid": file_stat.st_gid,
+            "mode_octal": oct(file_stat.st_mode),
+            "inode": file_stat.st_ino,
+            "device": file_stat.st_dev,
+            "nlinks": file_stat.st_nlink,
+        }
+    except Exception as e:
+        raise SecurityValidationError(f"Failed to get file info: {e}") from e
+
+
+def check_file_integrity(
+    file_path: str | Path,
+    expected_size: int | None = None,
+    expected_hash: str | None = None,
+    hash_algorithm: str = "sha256",
+) -> dict[str, bool | None]:
+    """Check file integrity against expected values."""
+    results = {
+        "exists": False,
+        "size_match": None,
+        "hash_match": None,
+        "overall_valid": False,
+    }
+
+    path = Path(file_path)
+
+    # Check if file exists
+    if not path.exists():
+        return results
+
+    results["exists"] = True
+
+    try:
+        # Check size if provided
+        if expected_size is not None:
+            actual_size = get_file_size(path)
+            results["size_match"] = actual_size == expected_size
+
+        # Check hash if provided
+        if expected_hash is not None:
+            results["hash_match"] = verify_file_hash(path, expected_hash, hash_algorithm)
+
+        # Overall validity
+        checks = [v for v in results.values() if v is not None and isinstance(v, bool)]
+        results["overall_valid"] = all(checks) if checks else True
+
+        return results
+    except Exception as e:
+        raise SecurityValidationError(f"Integrity check failed: {e}") from e
+
+
+def is_executable_file(file_path: str | Path) -> bool:
+    """Check if file is executable."""
+    path = Path(file_path)
+    return path.exists() and os.access(path, os.X_OK)
+
+
+def get_safe_temp_dir() -> Path:
+    """Get a safe temporary directory with appropriate permissions."""
+    import tempfile
+
+    try:
+        temp_dir = Path(tempfile.gettempdir())
+
+        # Verify temp directory is safe
+        if not temp_dir.exists():
+            raise SecurityValidationError("System temp directory doesn't exist")
+
+        if not os.access(temp_dir, os.R_OK | os.W_OK | os.X_OK):
+            raise SecurityValidationError("Insufficient permissions on temp directory")
+
+        return temp_dir
+    except Exception as e:
+        raise SecurityValidationError(f"Failed to get safe temp directory: {e}") from e
+
+
+# Export all public functions
+__all__ = [
+    # Exceptions
+    "SecurityValidationError",
+    "FileSizeError",
+    "FilePermissionError",
+    "FileNotFoundError",
+    "InvalidPathError",
+    # Validation
+    "validate_file_access",
+    "validate_directory_access",
+    # File info
+    "get_file_size",
+    "get_file_info",
+    "get_file_permissions",
+    # Hashing
+    "get_file_hash",
+    "verify_file_hash",
+    # Security checks
+    "is_safe_filename",
+    "sanitize_filename",
+    "check_file_integrity",
+    "is_executable_file",
+    "get_safe_temp_dir",
+]

coding_client-1.21.2.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: coding-client
+Version: 1.21.2
+Summary: Shared library for coding-* microservices: models, auth, DB helpers, HTTP client
+Author-email: Nonagentic <dev@nonagentic.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://nonagentic.ai
+Project-URL: Source, https://github.com/nonagenticai/coding-client
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: starlette>=1.0.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: psycopg[binary,pool]>=3.2.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: redis>=7.1.0
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: PyJWT[crypto]>=2.15.1
+Requires-Dist: cryptography>=46.0.6
+Requires-Dist: opentelemetry-api>=1.45.1
+Requires-Dist: opentelemetry-sdk>=1.24.0
+Requires-Dist: tenacity>=8.2.0
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: pydantic-ai<2.0.0,>=1.107.7
+Requires-Dist: openai<3,>=1.0.0
+Requires-Dist: pyasn1>=0.6.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: ruff==0.17.4; extra == "dev"
+Requires-Dist: ty==0.0.39; extra == "dev"
+Dynamic: license-file
+
+# coding-client
+
+[![CI](https://github.com/nonagenticai/coding-client/actions/workflows/ci.yml/badge.svg)](https://github.com/nonagenticai/coding-client/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/nonagenticai/coding-client)](https://github.com/nonagenticai/coding-client/releases)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+Shared Python library for the coding-* microservices ecosystem — models, auth, database, service clients, and utilities.
+
+| | |
+|---|---|
+| **Stack** | Python 3.14 · Pydantic 2.x · SQLAlchemy 2.x · psycopg 3.x · httpx · structlog |
+| **Package** | `coding-client` (Apache-2.0) |
+| **Used by** | coding-gateway, coding-analysis, coding-testing, coding-ai, coding-containers, coding-github, coding-security, coding-realtime |
+
+## What It Provides
+
+**Models** (`coding_client.models`) — 23 domain-specific Pydantic models covering code graphs, architecture, analysis, testing, containers, GitHub, security, AI agents, bug tracking, package management, PR validation, and more.
+
+**Auth** (`coding_client.auth`) — Istio header-based authentication middleware, RBAC helpers (`require_role`, `require_access_coding`), multi-tenant isolation (`TenantMiddleware`, `require_tenant`, `get_tenant_id`), and FastAPI dependencies (`get_current_user`).
+
+**Database** (`coding_client.db`) — PostgreSQL connection management via PgBouncer, SQLite code graph database, transaction management (`TransactionManager`, `TransactionContext`), tenant-aware queries (`TenantQueryBuilder`), migrations, and 9 custom exceptions.
+
+**Clients** (`coding_client.clients`) — service-to-service HTTP clients with retry and timeout, including the canonical `CodingWorkspacesClient` and the compatibility-only `CodingContainersClient`. All extend a common `ServiceClient` base.
+
+**Utilities** (`coding_client.utils`) — 16 modules: file operations, filesystem ops, path utils, archive utils, async timeout, encoding helper, HTTP client, retry helper, profiling, response builder, content processing, database utils, constants, enum helpers, security validation, AST debug.
+
+**Interfaces** (`coding_client.interfaces`) — 6 abstract contracts for dependency injection: `IGraphService`, `IDockerService`, `ISecurityService`, `IAnalysisCache`, `ICacheManager`, `IWebhookEventHandler`.
+
+**Types** (`coding_client.types`) — Shared type definitions, enums, constraint types, and workflow state machine definitions.
+
+**API** (`coding_client.api`) — FastAPI middleware (`RequestLoggingMiddleware`, `HealthCheckFilter`), exception handlers, and OpenAPI configuration helpers.
+
+## Installation
+
+Consumed as a **git dependency**, pinned to a commit:
+
+```toml
+[project]
+dependencies = ["coding-client"]
+
+[tool.uv.sources]
+coding-client = { git = "https://github.com/nonagenticai/coding-client", rev = "<commit sha>" }
+```
+
+```bash
+uv lock     # records the pinned commit in uv.lock
+uv sync
+```
+
+No package index is involved, so this resolves identically on a laptop, in CI, and inside a
+Docker build.
+
+## Quick Start
+
+```bash
+uv sync
+uv run pytest tests/ -v --cov=src
+uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/
+uv run ty check .
+```
+
+## Architecture
+
+```
+src/
+├── __init__.py
+├── api/
+│   ├── exception_handlers.py       # FastAPI exception handlers
+│   ├── openapi_config.py           # OpenAPI customization
+│   └── request_logging.py          # Request logging middleware
+├── auth/
+│   ├── dependencies.py             # FastAPI auth dependencies (get_current_user)
+│   ├── middleware.py                # Istio header auth middleware
+│   ├── models.py                   # User model
+│   ├── rbac.py                     # Role-based access control
+│   ├── rbac_coding.py              # Coding-specific RBAC helpers
+│   └── tenant.py                   # Multi-tenant isolation
+├── clients/
+│   ├── base.py                     # ServiceClient base with retry/timeout
+│   ├── coding_ai.py                # coding-ai client
+│   ├── coding_analysis.py          # coding-analysis client
+│   ├── coding_containers.py        # coding-containers client
+│   ├── coding_workspaces.py        # canonical repository-workspace client
+│   ├── coding_github.py            # coding-github client
+│   ├── coding_realtime.py          # coding-realtime client
+│   ├── coding_security.py          # coding-security client
+│   └── coding_testing.py           # coding-testing client
+├── config/
+│   └── yaml_config_loader.py       # YAML config loading
+├── db/
+│   ├── code_graph_database.py      # SQLite graph DB
+│   ├── database_path_manager.py    # DB file path management
+│   ├── db_types.py                 # Database type definitions
+│   ├── exceptions.py               # 9 custom DB exceptions
+│   ├── migrations.py               # Schema migration helpers
+│   ├── models/
+│   │   └── architecture.py         # ORM models
+│   ├── performance_optimizer.py    # Query performance tuning
+│   ├── postgres_connection.py      # PostgreSQL via PgBouncer
+│   ├── tenant_query_helper.py      # Tenant-aware query builder
+│   ├── transaction_manager.py      # Transaction management
+│   ├── transaction_mixin.py        # Transaction mixin
+│   └── transaction_patterns.py     # Transaction patterns
+├── exceptions/
+│   ├── api_exceptions.py           # API exception hierarchy
+│   └── pydantic_ai_exceptions.py   # PydanticAI-specific exceptions
+├── interfaces/                     # 6 abstract contracts
+├── models/                         # 23 Pydantic model files
+├── types/
+│   ├── constraint_types.py         # Validation constraints
+│   ├── core_types.py               # Enums and type hints
+│   └── state_machine.py            # Workflow state definitions
+└── utils/                          # 16 utility modules
+```
+
+## Tests
+
+```bash
+uv run pytest tests/ -v --cov=src --cov-report=term-missing    # 29 test files
+uv run ruff check src/ tests/                                   # Lint
+uv run ruff format --check src/ tests/                          # Format check
+uv run ty check .                                               # Type check
+```
+
+Test structure mirrors source: `test_api/`, `test_auth/`, `test_clients/`, `test_config/`, `test_db/`, `test_exceptions/`, `test_models/`, `test_types/`, `test_utils/`.
+
+The suite needs no database. ⛔ `coding_client.db_init` has **no default DSN** (it used to
+fall back to `localhost:5432/code_graph_helper`, a host Postgres deleted 2026-10-21):
+importing it without `DATABASE_URL` / `TEST_DATABASE_URL` raises `RuntimeError` naming the
+variable. A consumer that wants a test DB starts an ephemeral `postgres:18` container on a
+random port — never a host `:5432`.
+
+### Bypassing auth in a consumer's tests
+
+`SKIP_AUTH=true` was **removed in 1.16.0**. It made `require_tenant`,
+`optional_tenant` and `get_current_user_with_tenant` return the hardcoded tenant
+`"test-tenant"` before examining any credential — an ambient, global switch
+compiled into the production wheel, where one environment variable disabled
+authentication for a whole service.
+
+Use `coding_client.testing` instead. Same job for a test suite; per-app,
+explicit, and impossible to switch on from the environment:
+
+```python
+from coding_client.testing import override_tenant_auth
+
+@pytest.fixture
+def client(app):
+    undo = override_tenant_auth(app)          # or: with tenant_auth_override(app):
+    yield TestClient(app)
+    undo()                                     # restores the previous overrides exactly
+```
+
+It neutralises **every** identity dependency this SDK exposes, from one list.
+That matters: hand-rolled override lists drift, and one in this fleet already
+had — a consumer's conftest overrode three dependencies and not `require_tenant`,
+and only worked because it also set `SKIP_AUTH`.
+
+Pass `extra={dep: replacement}` for a service's own forked dependency object or a
+service-specific return shape.
+
+## CI
+
+`.github/workflows/ci.yml` calls the public `nonagenticai/ci-workflows` python-library pipeline:
+`ruff + ty + unit tests → uv build → bandit + pip-audit`, on GitHub-hosted runners with no
+repository secrets. The wheel is a build artifact only — nothing is published to a package index;
+consumers pin the git commit.
+
+## Dependencies
+
+| Category | Packages |
+|----------|----------|
+| **Web/API** | fastapi, httpx, PyJWT[crypto] |
+| **Data** | pydantic, pydantic-settings, sqlalchemy[asyncio] |
+| **Database** | psycopg[binary,pool] (PostgreSQL v3.x), aiosqlite |
+| **Async** | redis, tenacity, aiofiles |
+| **Observability** | structlog, opentelemetry-api, opentelemetry-sdk |
+| **Security** | cryptography |
+| **Utilities** | uuid-v7, cachetools, pyyaml |
+
+## Security
+
+Report vulnerabilities privately through the repository's Security tab — see
+[`SECURITY.md`](SECURITY.md). Do not open a public issue for a security problem.
+
+## Contributing
+
+Issues and pull requests are welcome. See
+[`CONTRIBUTING.md`](https://github.com/nonagenticai/.github/blob/main/CONTRIBUTING.md) for the
+organisation-wide rules; setup, test and lint commands are in this README. Commits carry DCO
+sign-off.
+
+## License
+
+Apache-2.0 — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).