pal-found-cli 0.1.2__py3-none-any.whl

pal_found_cli/common/async_client_factory.py

@@ -0,0 +1,161 @@
+"""AsyncClientFactory — creates stateless AsyncFoundryClient (SRS §3.4).
+
+Creates an ``AsyncFoundryClient`` instance per invocation, configured with
+``UserTokenAuth`` and the resolved hostname. When attribution is enabled,
+the SDK attribution context variable is set for the current invocation.
+
+Stateless per invocation (DCC-3): no client is cached across calls —
+each ``create()`` returns a fresh client. This keeps tests isolated,
+avoids shared mutable state, and matches the CLI's per-command lifecycle.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Optional
+
+from pal_found_cli.common.config_loader import ConfigLoader, ConfigurationError
+from pal_found_cli.common.tracing_provider import B3Context, TracingProvider
+
+if TYPE_CHECKING:
+    from foundry_sdk import AsyncFoundryClient
+
+
+class AsyncClientFactory:
+    """Creates stateless ``AsyncFoundryClient`` instances.
+
+    Usage
+    -----
+    >>> factory = AsyncClientFactory()
+    >>> client = factory.create(cfg)
+    """
+
+    def __init__(self) -> None:
+        # Per-instance state only — no class-level caching. Each factory
+        # instance is independent; ``create()`` never mutates shared state.
+        self._last_client: AsyncFoundryClient | None = None
+
+    def create(
+        self,
+        cfg: ConfigLoader,
+        *,
+        include_attribution: bool | None = None,
+    ) -> "AsyncFoundryClient":
+        """Create an ``AsyncFoundryClient`` from credentials in ``cfg``.
+
+        Validates token and hostname are present before constructing the
+        client. A new client is returned on every call — nothing is cached
+        on the class.
+
+        Parameters
+        ----------
+        cfg : ConfigLoader
+            Configuration instance with loaded credentials.
+        include_attribution : bool or None, optional
+            ``False`` clears SDK attribution for this client. ``None`` keeps
+            existing behavior and follows loaded configuration.
+
+        Returns
+        -------
+        AsyncFoundryClient
+            Freshly constructed SDK async client instance.
+
+        Raises
+        ------
+        ConfigurationError
+            If credentials are missing or the SDK is not installed.
+        """
+        token = cfg.token
+        hostname = cfg.hostname
+
+        # Strip before presence check so whitespace-only tokens are rejected
+        # (review finding A1 applied at the factory boundary as defense in depth).
+        if not token or not token.strip() or not hostname or not hostname.strip():
+            raise ConfigurationError(
+                "Missing FOUNDRY_TOKEN and/or FOUNDRY_HOSTNAME. "
+                "Set credentials in .env or shell environment."
+            )
+
+        try:
+            from foundry_sdk import ATTRIBUTION_VAR, AsyncFoundryClient, UserTokenAuth
+        except ImportError as exc:
+            raise ConfigurationError(
+                "foundry-sdk not installed; run 'pip install foundry-platform-sdk'"
+            ) from exc
+
+        auth: UserTokenAuth = UserTokenAuth(token)
+
+        client_kwargs: dict[str, Any] = {
+            "auth": auth,
+            "hostname": hostname,
+            "preview": True,
+        }
+
+        # SDK reads attribution from a context variable when sending requests.
+        # Always set it here so disabled or empty config clears prior values.
+        if include_attribution is False:
+            ATTRIBUTION_VAR.set(None)
+        else:
+            rids: list[str] = []
+            if cfg.enable_attribution and cfg.attribution_rids:
+                rids = [r.strip() for r in cfg.attribution_rids.split(",")]
+                rids = [r for r in rids if r]
+            ATTRIBUTION_VAR.set(rids or None)
+
+        client: AsyncFoundryClient = AsyncFoundryClient(**client_kwargs)
+        self._last_client = client
+        return client
+
+    @contextmanager
+    def invocation_scope(
+        self,
+        cfg: ConfigLoader,
+        supplied: B3Context | None = None,
+        *,
+        include_attribution: bool | None = None,
+    ) -> Iterator[B3Context | None]:
+        """Keep one trace context active across client creation and SDK calls.
+
+        Callers enter this scope before :meth:`create` and leave it only after
+        retry handling and response processing finish.
+
+        When ``include_attribution`` is set, this scope restores the prior SDK
+        attribution context on every exit path.
+        """
+        attribution_var: Any = None
+        attribution_token: Any = None
+        if include_attribution is not None:
+            try:
+                from foundry_sdk import ATTRIBUTION_VAR
+            except ImportError as exc:
+                raise ConfigurationError(
+                    "foundry-sdk not installed; run 'pip install foundry-platform-sdk'"
+                ) from exc
+            attribution_var = ATTRIBUTION_VAR
+            if include_attribution:
+                rids = [
+                    rid.strip()
+                    for rid in (cfg.attribution_rids or "").split(",")
+                    if rid.strip()
+                ]
+                attribution_token = attribution_var.set(
+                    rids if cfg.enable_attribution and rids else None
+                )
+            else:
+                attribution_token = attribution_var.set(None)
+
+        try:
+            with TracingProvider(config=cfg).scope(supplied) as context:
+                yield context
+        finally:
+            if attribution_token is not None:
+                attribution_var.reset(attribution_token)
+
+    @property
+    def last_client(self) -> Optional["AsyncFoundryClient"]:
+        """Most recently created client, or ``None``.
+
+        Convenience accessor for inspection/diagnostics only. Callers must
+        not rely on this for caching — ``create()`` always builds a new
+        client.
+        """
+        return self._last_client

pal_found_cli/common/auth_provider.py

@@ -0,0 +1,82 @@
+"""AuthProvider — constructs UserTokenAuth from environment (SRS §3.1).
+
+Validates that FOUNDRY_TOKEN and FOUNDRY_HOSTNAME are present
+and constructs a UserTokenAuth instance for the SDK.
+"""
+
+from typing import TYPE_CHECKING
+
+from pal_found_cli.common.config_loader import ConfigurationError
+
+if TYPE_CHECKING:
+    from foundry_sdk import UserTokenAuth
+
+
+class AuthProvider:
+    """Constructs and validates UserTokenAuth credentials.
+
+    Usage
+    -----
+    >>> auth = AuthProvider()
+    >>> auth_obj = auth.get_auth(token, hostname)
+    """
+
+    @staticmethod
+    def validate(token: str | None, hostname: str | None) -> tuple[bool, str | None]:
+        """Validate that credentials are present and non-empty.
+
+        Whitespace-only values are rejected — a token consisting solely of
+        spaces is not a credential and must not pass validation (review
+        finding A1/A4, OWASP A07).
+
+        Parameters
+        ----------
+        token : str or None
+            FOUNDRY_TOKEN value.
+        hostname : str or None
+            FOUNDRY_HOSTNAME value.
+
+        Returns
+        -------
+        Tuple[bool, str or None]
+            (is_valid, error_message). If valid, error_message is None.
+            Error messages reference the env var name only — never the
+            credential value — so they are safe to log.
+        """
+        if token is None or token.strip() == "":
+            return False, "Missing FOUNDRY_TOKEN credential"
+        if hostname is None or hostname.strip() == "":
+            return False, "Missing FOUNDRY_HOSTNAME credential"
+        return True, None
+
+    @staticmethod
+    def get_auth(token: str) -> "UserTokenAuth":
+        """Construct UserTokenAuth from a token string.
+
+        The SDK's ``UserTokenAuth`` is constructed from the token only;
+        hostname is consumed by the client factory, not by the auth object,
+        so it is intentionally absent from this signature (review finding A2).
+
+        Parameters
+        ----------
+        token : str
+            FOUNDRY_TOKEN value. Caller is expected to have validated it
+            via :meth:`validate` first.
+
+        Returns
+        -------
+        UserTokenAuth
+            SDK auth instance.
+
+        Raises
+        ------
+        ConfigurationError
+            If the ``foundry-platform-sdk`` package is not installed.
+        """
+        try:
+            from foundry_sdk import UserTokenAuth
+        except ImportError as exc:
+            raise ConfigurationError(
+                "foundry-sdk not installed; run 'pip install foundry-platform-sdk'"
+            ) from exc
+        return UserTokenAuth(token)

pal_found_cli/common/binary_download_handler.py

@@ -0,0 +1,288 @@
+"""Bounded, atomic binary download persistence (DESIGN-005)."""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+import logging
+import mimetypes
+import os
+import re
+import tempfile
+import unicodedata
+import uuid
+from collections.abc import AsyncIterable
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from pal_found_cli.common.config_loader import ConfigLoader
+
+logger = logging.getLogger(__name__)
+
+_SAFE_FILENAME = re.compile(r"[^A-Za-z0-9._-]+")
+_DEFAULT_DOWNLOAD_ROOT = Path(".foundry-data/downloads")
+_DEFAULT_MAX_DOWNLOAD_BYTES = 1_572_864
+
+
+class DownloadError(Exception):
+    """Base error for binary download persistence."""
+
+    exit_code = 6
+
+
+class InvalidDownloadError(DownloadError, ValueError):
+    """Raised when download configuration or a filename is invalid."""
+
+    exit_code = 1
+
+
+@dataclass(frozen=True)
+class DownloadResult:
+    """Metadata for a downloaded file prefix."""
+
+    file_path: str
+    file_size: int
+    checksum_md5: str
+    checksum_sha256: str
+    mime_type: str | None
+    truncated: bool
+    source_size: int | None
+    source_size_at_least: int | None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable result envelope."""
+        return asdict(self)
+
+
+class BinaryDownloadHandler:
+    """Stream binary content into a contained UUID directory.
+
+    The handler reads at most ``max_download_bytes + 1`` bytes when source
+    length is unknown and publishes the stored prefix atomically.
+    """
+
+    def __init__(
+        self,
+        download_root: str | Path | None = None,
+        max_download_bytes: int | None = None,
+        *,
+        config: ConfigLoader | None = None,
+    ) -> None:
+        cfg = config or ConfigLoader()
+        self.download_root = Path(
+            download_root
+            if download_root is not None
+            else getattr(cfg, "download_path", _DEFAULT_DOWNLOAD_ROOT)
+        ).expanduser()
+        self.max_download_bytes = (
+            max_download_bytes
+            if max_download_bytes is not None
+            else getattr(cfg, "max_download_bytes", _DEFAULT_MAX_DOWNLOAD_BYTES)
+        )
+
+    async def save(
+        self,
+        chunks: AsyncIterable[bytes],
+        *,
+        original_filename: str | None,
+        namespace: str,
+        operation: str,
+        content_length: str | None = None,
+        content_encoding: str | None = None,
+        mime_type: str | None = None,
+    ) -> DownloadResult:
+        """Store a bounded stream and return checksums for persisted bytes."""
+        limit = self.max_download_bytes
+        if isinstance(limit, bool) or not isinstance(limit, int) or limit <= 0:
+            raise InvalidDownloadError("max_download_bytes must be a positive integer")
+
+        filename = self._safe_filename(
+            original_filename,
+            namespace=namespace,
+            operation=operation,
+            mime_type=mime_type,
+        )
+        root = self.download_root.resolve()
+        root.mkdir(mode=0o700, parents=True, exist_ok=True)
+        self._restrict_directory(root)
+
+        download_dir = root / str(uuid.uuid4())
+        download_dir.mkdir(mode=0o700)
+        # Path.mkdir applies the kernel umask to the supplied mode. Calling
+        # _restrict_directory invokes os.chmod directly, bypassing umask so
+        # the per-download UUID directory is owner-only (0o700) on POSIX,
+        # consistent with the protection applied to ``root`` above.
+        self._restrict_directory(download_dir)
+        final_path = (download_dir / filename).resolve()
+        if final_path.parent != download_dir.resolve() or not final_path.is_relative_to(
+            root
+        ):
+            self._remove_empty_directory(download_dir)
+            raise InvalidDownloadError("Download filename escapes configured path")
+
+        known_size = self._applicable_content_length(content_length, content_encoding)
+        truncated = known_size is not None and known_size > limit
+        source_size_at_least: int | None = None
+        bytes_seen = 0
+        bytes_written = 0
+        md5 = hashlib.md5(usedforsecurity=False)
+        sha256 = hashlib.sha256()
+        temp_path: Path | None = None
+        stream_closed = False
+
+        try:
+            fd, raw_temp_path = tempfile.mkstemp(
+                prefix=".download-", suffix=".tmp", dir=download_dir
+            )
+            temp_path = Path(raw_temp_path)
+            with os.fdopen(fd, "wb") as target:
+                async for chunk in chunks:
+                    if not isinstance(chunk, bytes):
+                        raise DownloadError("Download stream yielded a non-bytes chunk")
+                    if not chunk:
+                        continue
+
+                    observation_limit = (
+                        limit
+                        if known_size is not None and known_size > limit
+                        else limit + 1
+                    )
+                    remaining_probe = observation_limit - bytes_seen
+                    observed = chunk[:remaining_probe]
+                    bytes_seen += len(observed)
+                    writable = observed[: max(0, limit - bytes_written)]
+                    if writable:
+                        target.write(writable)
+                        md5.update(writable)
+                        sha256.update(writable)
+                        bytes_written += len(writable)
+
+                    if bytes_seen > limit or (
+                        known_size is not None
+                        and known_size > limit
+                        and bytes_written == limit
+                    ):
+                        truncated = True
+                        break
+
+                if (
+                    known_size is not None
+                    and known_size > limit
+                    and bytes_written < limit
+                ):
+                    raise DownloadError(
+                        "Download stream ended before the declared prefix was received"
+                    )
+
+                await self._close_stream(chunks)
+                stream_closed = True
+                target.flush()
+                os.fsync(target.fileno())
+
+            os.chmod(temp_path, 0o600)
+            os.replace(temp_path, final_path)
+            temp_path = None
+
+            if known_size is None:
+                if bytes_seen > limit:
+                    source_size = None
+                    source_size_at_least = limit + 1
+                else:
+                    source_size = bytes_seen
+            else:
+                source_size = known_size
+
+            if truncated:
+                warning: dict[str, Any] = {
+                    "op": f"{namespace}.{operation}",
+                    "file_size": bytes_written,
+                    "max_download_bytes": limit,
+                    "truncated": True,
+                    "source_size": source_size,
+                    "source_size_at_least": source_size_at_least,
+                }
+                logger.warning("Binary download truncated", extra=warning)
+
+            return DownloadResult(
+                file_path=str(final_path),
+                file_size=bytes_written,
+                checksum_md5=md5.hexdigest(),
+                checksum_sha256=sha256.hexdigest(),
+                mime_type=mime_type,
+                truncated=truncated,
+                source_size=source_size,
+                source_size_at_least=source_size_at_least,
+            )
+        except BaseException:
+            if temp_path is not None:
+                temp_path.unlink(missing_ok=True)
+            final_path.unlink(missing_ok=True)
+            self._remove_empty_directory(download_dir)
+            raise
+        finally:
+            if not stream_closed:
+                await self._close_stream(chunks)
+
+    @staticmethod
+    def _applicable_content_length(
+        content_length: str | None, content_encoding: str | None
+    ) -> int | None:
+        encoding = (content_encoding or "identity").strip().casefold()
+        if encoding not in {"", "identity"} or content_length is None:
+            return None
+        try:
+            value = int(content_length.strip())
+        except (AttributeError, ValueError):
+            return None
+        return value if value >= 0 else None
+
+    @classmethod
+    def _safe_filename(
+        cls,
+        original_filename: str | None,
+        *,
+        namespace: str,
+        operation: str,
+        mime_type: str | None,
+    ) -> str:
+        if original_filename is None or not original_filename.strip():
+            extension = mimetypes.guess_extension(mime_type or "") or ".bin"
+            timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+            original_filename = f"{namespace}_{operation}_{timestamp}{extension}"
+        if "\x00" in original_filename or any(
+            separator in original_filename for separator in ("/", "\\")
+        ):
+            raise InvalidDownloadError(
+                "Download filename contains a forbidden separator"
+            )
+        candidate = Path(original_filename)
+        if candidate.is_absolute() or original_filename in {".", ".."}:
+            raise InvalidDownloadError("Download filename must be a relative basename")
+        normalized = unicodedata.normalize("NFKC", original_filename).strip()
+        sanitized = _SAFE_FILENAME.sub("_", normalized).strip("._")
+        if not sanitized:
+            raise InvalidDownloadError("Download filename is empty after sanitization")
+        return sanitized[:255]
+
+    @staticmethod
+    def _restrict_directory(path: Path) -> None:
+        if os.name != "nt":
+            os.chmod(path, 0o700)
+
+    @staticmethod
+    def _remove_empty_directory(path: Path) -> None:
+        try:
+            path.rmdir()
+        except OSError:
+            pass
+
+    @staticmethod
+    async def _close_stream(chunks: AsyncIterable[bytes]) -> None:
+        close = getattr(chunks, "aclose", None)
+        if close is None:
+            return
+        result = close()
+        if inspect.isawaitable(result):
+            await result