pipefy-infra 0.3.0a1__tar.gz

pipefy_infra-0.3.0a1/.gitignore

@@ -0,0 +1,56 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Ruff stuff:
+.ruff_cache/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.mise.toml
+
+# Ralph Wiggum (local autonomous runs; state must not land in git)
+.ralph/
+RALPH_TASK.md
+
+# IDEs and editors
+.cursor/
+.claude/
+# Cursor MCP workspace config (machine-specific paths or local server entries).
+# Carve-out: repo-root .mcp.json is the Claude Code plugin's MCP server config
+# (auto-discovered at plugin root) and is intentionally tracked.
+.mcp.json
+!/.mcp.json
+
+# Tracked release tooling only (ignore ad-hoc local scripts and smoke artifacts)
+scripts/*
+!scripts/bump_version.py
+
+# macOS
+.DS_Store
+**/.DS_Store

pipefy_infra-0.3.0a1/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: pipefy-infra
+Version: 0.3.0a1
+Summary: Shared infra (TOML config loader, path discovery, SSRF defenses, string helpers) for Pipefy SDK and Auth.
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: pydantic<3,>=2.13.4
+Description-Content-Type: text/markdown
+
+# pipefy-infra
+
+Schema-agnostic infrastructure helpers shared by `pipefy` and `pipefy-auth`. Sits at the bottom of the workspace dependency graph; depends only on stdlib + `pydantic` / `pydantic-settings`.
+
+Adapter layer between Pipefy's application code (`pipefy`, `pipefy-auth`) and external concerns (filesystem, OS, network boundary). Each submodule owns one bounded context; the package root exposes only `__version__`.
+
+## `pipefy_infra.config`
+
+Pipefy on-disk configuration: where it lives and how it's read.
+
+- `config_dir() -> Path`. Resolves the OS-appropriate config directory (`$XDG_CONFIG_HOME/pipefy` on POSIX, `%APPDATA%\pipefy` on Windows, falling back to `~/.config/pipefy` when `XDG_CONFIG_HOME` is unset).
+- `config_file_path() -> Path`. Resolves the TOML file path, honouring the `PIPEFY_CONFIG_FILE` environment override.
+- `PipefyTomlConfigSource`. A `pydantic-settings` source that loads top-level TOML keys from `config_file_path()`. The source knows nothing about specific field names; each consuming `BaseSettings` subclass filters via its own field definitions plus `extra="ignore"`.
+
+```python
+from pipefy_infra.config import config_dir, config_file_path, PipefyTomlConfigSource
+```
+
+## `pipefy_infra.security`
+
+SSRF defenses on URLs destined for outbound HTTP. Layered gates: shape regex at field declaration, synchronous internal-IP check at settings construction, asynchronous DNS-rebinding check at request time.
+
+- `URL_SHAPE_PATTERN`. Regex for `Field(..., pattern=...)` on URL settings fields.
+- `validate_https_url(url, field_label, *, allow_insecure=False)`. Synchronous scheme + literal-IP gate. Enforces HTTPS and rejects literal IPs in private/loopback/link-local/multicast/reserved/unspecified ranges. With `allow_insecure=True` (driven by `PIPEFY_ALLOW_INSECURE_URLS`) both http and the literal-IP gate are skipped for dev mode; production callers must follow up with the async DNS gate.
+- `assert_hostname_is_not_internal(hostname, *, context)`. Rejects localhost and literal IPs in blocked ranges.
+- `assert_hostname_resolves_to_public_ips(hostname)`. Asynchronous DNS gate used right before issuing a request; defends against DNS-rebinding.
+- `validate_and_assert_public_url(url, *, field_label, allow_insecure=False) -> str`. Composite helper that runs the sync gate plus the DNS gate in one call and returns the validated hostname. Use from any new outbound-URL surface.
+- `assert_url_is_host_root(url, *, field_label)`. Rejects non-root paths (including `//`, `///`), query strings, and fragments. For base-URL fields that derive endpoints via f-string concatenation.
+- `assert_url_has_no_query_or_fragment(url, *, field_label)`. Path is allowed; rejects only query and fragment. For URLs that legitimately have a path (OIDC issuer URLs with a realm path) but where a stray query/fragment would corrupt downstream concatenation.
+
+This is the **SSRF audit namespace**: import the module and call through it so every call site is greppable for audits, matching the stdlib idiom (`hmac.compare_digest`, `secrets.token_urlsafe`).
+
+```python
+from pipefy_infra import security
+
+security.validate_https_url(url, "graphql_url", allow_insecure=False)
+await security.assert_hostname_resolves_to_public_ips(host)
+```
+
+## Field definitions
+
+This package owns **no schema**. Field definitions live with the settings models that use them (`pipefy_auth.AuthSettings`, `pipefy_sdk.PipefySettings`).

pipefy_infra-0.3.0a1/README.md

@@ -0,0 +1,42 @@
+# pipefy-infra
+
+Schema-agnostic infrastructure helpers shared by `pipefy` and `pipefy-auth`. Sits at the bottom of the workspace dependency graph; depends only on stdlib + `pydantic` / `pydantic-settings`.
+
+Adapter layer between Pipefy's application code (`pipefy`, `pipefy-auth`) and external concerns (filesystem, OS, network boundary). Each submodule owns one bounded context; the package root exposes only `__version__`.
+
+## `pipefy_infra.config`
+
+Pipefy on-disk configuration: where it lives and how it's read.
+
+- `config_dir() -> Path`. Resolves the OS-appropriate config directory (`$XDG_CONFIG_HOME/pipefy` on POSIX, `%APPDATA%\pipefy` on Windows, falling back to `~/.config/pipefy` when `XDG_CONFIG_HOME` is unset).
+- `config_file_path() -> Path`. Resolves the TOML file path, honouring the `PIPEFY_CONFIG_FILE` environment override.
+- `PipefyTomlConfigSource`. A `pydantic-settings` source that loads top-level TOML keys from `config_file_path()`. The source knows nothing about specific field names; each consuming `BaseSettings` subclass filters via its own field definitions plus `extra="ignore"`.
+
+```python
+from pipefy_infra.config import config_dir, config_file_path, PipefyTomlConfigSource
+```
+
+## `pipefy_infra.security`
+
+SSRF defenses on URLs destined for outbound HTTP. Layered gates: shape regex at field declaration, synchronous internal-IP check at settings construction, asynchronous DNS-rebinding check at request time.
+
+- `URL_SHAPE_PATTERN`. Regex for `Field(..., pattern=...)` on URL settings fields.
+- `validate_https_url(url, field_label, *, allow_insecure=False)`. Synchronous scheme + literal-IP gate. Enforces HTTPS and rejects literal IPs in private/loopback/link-local/multicast/reserved/unspecified ranges. With `allow_insecure=True` (driven by `PIPEFY_ALLOW_INSECURE_URLS`) both http and the literal-IP gate are skipped for dev mode; production callers must follow up with the async DNS gate.
+- `assert_hostname_is_not_internal(hostname, *, context)`. Rejects localhost and literal IPs in blocked ranges.
+- `assert_hostname_resolves_to_public_ips(hostname)`. Asynchronous DNS gate used right before issuing a request; defends against DNS-rebinding.
+- `validate_and_assert_public_url(url, *, field_label, allow_insecure=False) -> str`. Composite helper that runs the sync gate plus the DNS gate in one call and returns the validated hostname. Use from any new outbound-URL surface.
+- `assert_url_is_host_root(url, *, field_label)`. Rejects non-root paths (including `//`, `///`), query strings, and fragments. For base-URL fields that derive endpoints via f-string concatenation.
+- `assert_url_has_no_query_or_fragment(url, *, field_label)`. Path is allowed; rejects only query and fragment. For URLs that legitimately have a path (OIDC issuer URLs with a realm path) but where a stray query/fragment would corrupt downstream concatenation.
+
+This is the **SSRF audit namespace**: import the module and call through it so every call site is greppable for audits, matching the stdlib idiom (`hmac.compare_digest`, `secrets.token_urlsafe`).
+
+```python
+from pipefy_infra import security
+
+security.validate_https_url(url, "graphql_url", allow_insecure=False)
+await security.assert_hostname_resolves_to_public_ips(host)
+```
+
+## Field definitions
+
+This package owns **no schema**. Field definitions live with the settings models that use them (`pipefy_auth.AuthSettings`, `pipefy_sdk.PipefySettings`).

pipefy_infra-0.3.0a1/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "pipefy-infra"
+dynamic = ["version"]
+description = "Shared infra (TOML config loader, path discovery, SSRF defenses, string helpers) for Pipefy SDK and Auth."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.13.4,<3",
+    "pydantic-settings>=2.8.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "ruff>=0.11.4",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipefy_infra"]
+
+[tool.hatch.version]
+path = "src/pipefy_infra/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "module"
+markers = [
+    "unit: marks a test as a unit test",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+lint.extend-select = ["TID251"]
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"pipefy_auth".msg = "pipefy_infra is a leaf package; it must not import the Auth package."
+"pipefy_sdk".msg = "pipefy_infra is a leaf package; it must not import the SDK package."
+"pipefy_cli".msg = "pipefy_infra is a leaf package; it must not import the CLI package."
+"pipefy_mcp".msg = "pipefy_infra is a leaf package; it must not import the MCP package."

pipefy_infra-0.3.0a1/src/pipefy_infra/__init__.py

@@ -0,0 +1,18 @@
+"""Schema-agnostic infrastructure helpers shared by ``pipefy_sdk`` and ``pipefy_auth``.
+
+The package root exposes only ``__version__``. Consumers import from the
+submodule that names the concern: :mod:`pipefy_infra.config` (on-disk
+configuration: path discovery + TOML source), :mod:`pipefy_infra.security`
+(SSRF defenses, imported as ``from pipefy_infra import security`` so every
+call site is greppable for audits), and :mod:`pipefy_infra.coerce`
+(permissive type-coercion helpers for JSON/GraphQL response values). See
+each submodule docstring and ``README.md`` for the detailed surface. The
+package sits at the bottom of the workspace dependency graph: stdlib +
+``pydantic`` / ``pydantic-settings`` only.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.3.0-alpha.1"
+
+__all__ = ["__version__"]

pipefy_infra-0.3.0a1/src/pipefy_infra/coerce.py

@@ -0,0 +1,95 @@
+"""Permissive coercion helpers for values of uncertain shape.
+
+When a value crosses a boundary (deserialization, user input, third-party
+payload) it may arrive as a string, int, float, or wrong shape entirely.
+These helpers normalize the common cases without raising, and explicitly
+reject misshapen types (booleans, bytes) that Python's built-in conversions
+would silently accept:
+
+- :func:`optional_int` / :func:`optional_str` / :func:`optional_float` collapse
+  ``None`` and any unparseable or wrong-shape value to ``None``. Use when
+  absence and malformed-input are handled identically by the caller.
+- :func:`try_int` returns the input unchanged if it can't be parsed as int.
+  Use when a non-numeric input is itself a meaningful value to preserve.
+
+Booleans are rejected (or passed through, for ``try_int``) despite ``bool``
+being a subclass of ``int``: a bool in a numeric- or string-shaped slot is
+a shape signal, not the value ``1`` / ``0`` / ``"True"``. Bytes are likewise
+rejected because ``str(b"x") == "b'x'"`` (the repr) is almost never what a
+caller wants.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def optional_int(value: object) -> int | None:
+    """Return ``int(value)``, or ``None`` for None/bool/bytes/unparseable input.
+
+    Floats truncate (``42.7 -> 42``); non-finite floats and overflowing values
+    return ``None``. Numeric strings (including signed and PEP 515 underscored
+    forms) parse via Python's built-in ``int()``.
+    """
+    if value is None or isinstance(value, (bool, bytes, bytearray)):
+        return None
+    try:
+        return int(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def optional_str(value: object) -> str | None:
+    """Return ``str(value).strip()``, or ``None`` for None/bool/bytes/empty input.
+
+    Booleans return ``None`` (a bool in a string-shaped slot is a shape error,
+    not the literal ``'True'`` / ``'False'``). Bytes return ``None`` to avoid
+    producing the bytes-repr form. Numeric inputs are stringified
+    (``optional_str(42) == '42'``) for the case where a numeric id needs
+    comparing against a string token.
+    """
+    if value is None or isinstance(value, (bool, bytes, bytearray)):
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def optional_float(value: object) -> float | None:
+    """Return ``float(value)``, or ``None`` for None/bool/bytes/unparseable input.
+
+    Non-finite floats (``inf``, ``-inf``, ``nan``) return ``None`` so callers
+    can treat them like missing data rather than threading edge-case checks
+    through every comparison.
+    """
+    if value is None or isinstance(value, (bool, bytes, bytearray)):
+        return None
+    try:
+        result = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+    if not math.isfinite(result):
+        return None
+    return result
+
+
+def try_int(value: T) -> T | int:
+    """Return ``int(value)``, or ``value`` unchanged if conversion fails.
+
+    Distinct from :func:`optional_int` in that a non-numeric input is preserved
+    rather than collapsed to ``None``. Use when the caller wants to upgrade a
+    numeric form to an int but leave non-numeric values alone. Booleans and
+    bytes pass through unchanged (the misshapen-type rejection that
+    :func:`optional_int` uses ``None`` for).
+    """
+    if isinstance(value, (bool, bytes, bytearray)):
+        return value
+    try:
+        return int(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError, OverflowError):
+        return value
+
+
+__all__ = ["optional_float", "optional_int", "optional_str", "try_int"]

pipefy_infra-0.3.0a1/src/pipefy_infra/config.py

@@ -0,0 +1,107 @@
+"""Pipefy on-disk configuration: where it lives and how it's read.
+
+Bounded context: the operator-editable Pipefy config file. Owns path
+discovery (where the OS expects the config directory and the
+``config.toml`` file to live) and the ``pydantic-settings`` source that
+reads top-level TOML keys at settings construction.
+
+Path discovery is intentionally hand-rolled. Adopting ``platformdirs``
+would land config under ``~/Library/Application Support/pipefy`` on
+macOS, breaking parity with the CLI tools operators expect to share that
+location (``gh``, ``uv``, ``gcloud``).
+
+The TOML source is schema-agnostic: it returns the full top-level mapping
+filtered to the consuming ``BaseSettings`` subclass's field names
+(env-only aliases like ``PIPEFY_TOKEN`` are intentionally not honoured as
+TOML keys; operators get one canonical TOML schema).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic.fields import FieldInfo
+from pydantic_settings import PydanticBaseSettingsSource
+
+_CONFIG_FILE_ENV = "PIPEFY_CONFIG_FILE"
+
+
+def config_dir() -> Path:
+    """Resolve the shared Pipefy configuration directory.
+
+    On POSIX honours ``XDG_CONFIG_HOME`` (per the XDG Base Directory
+    Specification) and falls back to ``~/.config``. On Windows uses
+    ``%APPDATA%`` with a ``~/AppData/Roaming`` fallback. Returns the path
+    unconditionally; the directory may not yet exist.
+    """
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        base = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
+        return base / "pipefy"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "pipefy"
+
+
+def config_file_path() -> Path:
+    """Resolve the operator-editable ``config.toml`` path.
+
+    Honours the ``PIPEFY_CONFIG_FILE`` env override (useful for tests, ops
+    automation, and multi-environment workflows). Returns the path
+    unconditionally; the file may not yet exist; consumers must tolerate that.
+    """
+    override = os.environ.get(_CONFIG_FILE_ENV)
+    if override:
+        return Path(override)
+    return config_dir() / "config.toml"
+
+
+class PipefyTomlConfigSource(PydanticBaseSettingsSource):
+    """Load top-level TOML keys from :func:`config_file_path` as a settings source.
+
+    Missing file produces an empty mapping (no error). Malformed TOML
+    produces ``ValueError`` quoting the file path, chained from the
+    original ``tomllib.TOMLDecodeError`` so the parser context is preserved.
+    """
+
+    _cache: dict[str, Any] | None = None
+
+    def _data(self) -> dict[str, Any]:
+        # Pydantic-settings constructs a fresh source per ``BaseSettings.__init__``,
+        # so caching on the instance scopes to "one settings construction"; the
+        # lazy behaviour the tests exercise (env change between constructions)
+        # still works because each construction gets a new source instance.
+        if self._cache is not None:
+            return self._cache
+        path = config_file_path()
+        if not path.is_file():
+            self._cache = {}
+            return self._cache
+        try:
+            with path.open("rb") as handle:
+                raw = tomllib.load(handle)
+        except tomllib.TOMLDecodeError as exc:
+            msg = f"invalid TOML in {path}"
+            raise ValueError(msg) from exc
+        known = set(self.settings_cls.model_fields)
+        self._cache = {key: value for key, value in raw.items() if key in known}
+        return self._cache
+
+    def get_field_value(
+        self, field: FieldInfo, field_name: str
+    ) -> tuple[Any, str, bool]:
+        del field  # signature dictated by ``PydanticBaseSettingsSource``
+        data = self._data()
+        if field_name in data:
+            return data[field_name], field_name, False
+        return None, field_name, False
+
+    def __call__(self) -> dict[str, Any]:
+        return self._data()
+
+
+__all__ = ["PipefyTomlConfigSource", "config_dir", "config_file_path"]

pipefy_infra-0.3.0a1/src/pipefy_infra/filesystem.py

@@ -0,0 +1,111 @@
+"""Local filesystem I/O with normalized error handling.
+
+:class:`LocalFile` resolves a path on disk to its bytes, expanding ``~``,
+checking the path is a regular file, and (optionally) enforcing a size cap
+before reading. Every failure mode surfaces as :class:`LocalFileError` so
+callers handle a single exception type.
+
+Schema-agnostic: no Pipefy concepts here. Callers that need a domain-policy
+cap (e.g. the attachment 100 MiB ceiling) pass ``max_size_bytes``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__all__ = [
+    "LocalFile",
+    "LocalFileError",
+]
+
+
+class LocalFileError(Exception):
+    """Raised when a :class:`LocalFile` cannot be read.
+
+    Covers unknown ``~user`` in the path, missing path, non-regular file,
+    permission denied, generic OS read failure, and oversize files when a
+    cap is configured. The message is user-facing and safe to surface in
+    error envelopes or CLI errors.
+    """
+
+
+class LocalFile:
+    """A local file resolved to its bytes.
+
+    Construct with a path, optionally a size cap, then call :meth:`read` to
+    perform the I/O. All read-time failures land as :class:`LocalFileError`
+    so callers catch one exception type.
+
+    Path/bytes properties raise :class:`RuntimeError` if accessed before
+    :meth:`read` succeeds.
+
+    Args:
+        path: Local path. Supports ``~`` expansion against the user's home.
+        max_size_bytes: Optional ceiling enforced after ``stat()``. ``None``
+            (default) means no cap.
+    """
+
+    def __init__(self, path: Path, *, max_size_bytes: int | None = None):
+        self._path = path
+        self._max_size_bytes = max_size_bytes
+        self._expanded: Path | None = None
+        self._bytes: bytes | None = None
+
+    def read(self) -> None:
+        """Expand ``~``, validate, and read the file into memory.
+
+        Raises:
+            LocalFileError: For any failure mode (unknown ``~user``, missing
+                file, directory, permission denied, oversize when a cap is
+                configured).
+        """
+        try:
+            expanded = self._path.expanduser()
+        except RuntimeError as exc:
+            raise LocalFileError(f"Cannot expand ~ in {self._path}: {exc}") from exc
+
+        if not expanded.is_file():
+            raise LocalFileError(f"File not found or not a regular file: {expanded}")
+
+        if self._max_size_bytes is not None:
+            size = expanded.stat().st_size
+            if size > self._max_size_bytes:
+                cap_mib = self._max_size_bytes // (1024 * 1024)
+                raise LocalFileError(
+                    f"File too large: {expanded} is {size} bytes, exceeding "
+                    f"the {cap_mib} MiB cap."
+                )
+
+        try:
+            data = expanded.read_bytes()
+        except PermissionError as exc:
+            raise LocalFileError(
+                f"Permission denied reading {expanded}: {exc.strerror}"
+            ) from exc
+        except OSError as exc:
+            raise LocalFileError(f"Could not read {expanded}: {exc}") from exc
+
+        self._expanded = expanded
+        self._bytes = data
+
+    @property
+    def path(self) -> Path:
+        """The post-``expanduser()`` path. Available after :meth:`read`."""
+        if self._expanded is None:
+            raise RuntimeError("LocalFile.read() has not been called yet.")
+        return self._expanded
+
+    @property
+    def name(self) -> str:
+        """The expanded path's basename. May be empty for paths like ``/``."""
+        return self.path.name
+
+    @property
+    def bytes(self) -> bytes:
+        if self._bytes is None:
+            raise RuntimeError("LocalFile.read() has not been called yet.")
+        return self._bytes
+
+    @property
+    def size(self) -> int:
+        return len(self.bytes)