"""Vault path resolution shared by the REST routes and the AI tool layer.

This is the single implementation of the anti path-traversal check. Routes map
:class:`ServiceError` to ``HTTPException`` and tools map it to
:class:`backend.tools.context.ToolError`.
"""

from __future__ import annotations

import logging
from pathlib import Path

from backend.services.errors import ServiceError

logger = logging.getLogger("obsigate.services.paths")


def resolve_safe_path(vault_root: Path, relative_path: str | None) -> Path:
    """Resolve a vault-relative path, rejecting traversal outside the vault.

    Raises:
        ServiceError: ``path_error`` (500) when the path cannot be resolved,
            ``path_outside_vault`` (403) when it escapes the vault root.
    """
    full_path = vault_root / (relative_path or "")
    try:
        resolved = full_path.resolve(strict=False)
        root = vault_root.resolve(strict=False)
    except Exception as e:
        logger.error(f"Path resolution error - vault_root: {vault_root}, relative_path: {relative_path}, error: {e}")
        raise ServiceError(f"Path resolution error: {e!s}", code="path_error", status=500) from e

    try:
        resolved.relative_to(root)
    except ValueError:
        # Case-insensitive fallback for Windows / Docker path casing.
        if not str(resolved).lower().startswith(str(root).lower()):
            logger.warning(f"Path outside vault - vault: {root}, requested: {relative_path}, resolved: {resolved}")
            raise ServiceError(
                "Access denied: path outside vault",
                code="path_outside_vault",
                status=403,
                details={"path": relative_path},
            ) from None
    return resolved