pipefy-auth 0.3.0a1__tar.gz

pipefy_auth-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_auth-0.3.0a1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: pipefy-auth
+Version: 0.3.0a1
+Summary: Shared OAuth/keychain helpers for Pipefy CLI and MCP server.
+Requires-Python: >=3.11
+Requires-Dist: httpx-auth>=0.23.1
+Requires-Dist: httpx>=0.28
+Requires-Dist: keyring>=24
+Requires-Dist: keyrings-alt>=5
+Requires-Dist: pipefy-infra
+Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: pyjwt[crypto]>=2.8
+Description-Content-Type: text/markdown
+
+# pipefy-auth
+
+Shared OAuth + keychain helpers for Pipefy CLI and MCP server.
+
+## What lives here
+
+- **`storage`** — keychain-backed `StoredSession` (one entry per `(issuer, client_id)` tuple, under the OS keychain service name `pipefy`).
+- **`flow`** — OAuth 2.0 Authorization Code with PKCE login flow.
+- **`refresh`** — refresh-token grant + eager pre-use freshness check (`ensure_fresh_session`).
+- **`discovery`** — OIDC `.well-known/openid-configuration` fetch + validation.
+- **`revoke`** — IdP-side token invalidation (RFC 7009).
+- **`identity`** — `OidcClient` dataclass + the `DEFAULT_AUTH_CLIENT_ID` constant (the registered Keycloak public client_id).
+
+## Consumers
+
+`pipefy-cli` and `pipefy-mcp-server` both depend on this package and read the same keychain entry, so a single `pipefy auth login` serves both binaries.

pipefy_auth-0.3.0a1/README.md

@@ -0,0 +1,16 @@
+# pipefy-auth
+
+Shared OAuth + keychain helpers for Pipefy CLI and MCP server.
+
+## What lives here
+
+- **`storage`** — keychain-backed `StoredSession` (one entry per `(issuer, client_id)` tuple, under the OS keychain service name `pipefy`).
+- **`flow`** — OAuth 2.0 Authorization Code with PKCE login flow.
+- **`refresh`** — refresh-token grant + eager pre-use freshness check (`ensure_fresh_session`).
+- **`discovery`** — OIDC `.well-known/openid-configuration` fetch + validation.
+- **`revoke`** — IdP-side token invalidation (RFC 7009).
+- **`identity`** — `OidcClient` dataclass + the `DEFAULT_AUTH_CLIENT_ID` constant (the registered Keycloak public client_id).
+
+## Consumers
+
+`pipefy-cli` and `pipefy-mcp-server` both depend on this package and read the same keychain entry, so a single `pipefy auth login` serves both binaries.

pipefy_auth-0.3.0a1/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "pipefy-auth"
+dynamic = ["version"]
+description = "Shared OAuth/keychain helpers for Pipefy CLI and MCP server."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28",
+    "httpx-auth>=0.23.1",
+    "keyring>=24",
+    "keyrings.alt>=5",
+    "pipefy-infra",
+    # RS256 validation of inbound bearers (resource-server role); [crypto] pulls cryptography.
+    "pyjwt[crypto]>=2.8",
+    "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_auth"]
+
+[tool.hatch.version]
+path = "src/pipefy_auth/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+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_cli".msg = "pipefy_auth must not import the CLI package."
+"pipefy_mcp".msg = "pipefy_auth must not import the MCP package."
+"pipefy_sdk".msg = "pipefy_auth must not import the SDK package."

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

@@ -0,0 +1,110 @@
+"""Shared OAuth + keychain helpers for Pipefy CLI and MCP server.
+
+Owns the keychain-backed user session (``StoredSession``), the OIDC discovery /
+authorization-code-with-PKCE login flow, the refresh-token grant, and the OIDC
+client identity (``OidcClient``, ``DEFAULT_AUTH_CLIENT_ID``). Consumers
+(``pipefy_cli`` and ``pipefy_mcp``) build an authenticated client by passing the
+artifacts surfaced here to the SDK.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.3.0-alpha.1"
+
+from pipefy_auth.bearer import (
+    RefreshableBearerAuth,
+    StaticBearerAuth,
+)
+from pipefy_auth.discovery import (
+    DiscoveryPolicy,
+    ProviderMetadata,
+    fetch_provider_metadata,
+)
+from pipefy_auth.flow import LoginError, LoginResult, run_login
+from pipefy_auth.identity import DEFAULT_AUTH_CLIENT_ID, OidcClient
+from pipefy_auth.refresh import (
+    RefreshError,
+    ensure_fresh_session,
+    refresh_access_token,
+)
+from pipefy_auth.resolver import (
+    ResolvedAuth,
+    ServiceAccount,
+    ServiceAccountAuth,
+    StaticTokenAuth,
+    StoredSessionAuth,
+    build_httpx_auth,
+    detect_pipefy_auth_methods,
+    missing_auth_message,
+    resolve_pipefy_auth,
+)
+from pipefy_auth.responses import OAuthErrorResponse, TokenResponse
+from pipefy_auth.revoke import (
+    RevocationError,
+    RevocationUnsupportedError,
+    revoke_session,
+)
+from pipefy_auth.settings import AuthSettings, JwtValidationSettings
+from pipefy_auth.storage import (
+    SessionDeleteError,
+    StoredSession,
+    configure_keychain_backend,
+    delete_session,
+    keychain_backend_name,
+    keychain_key,
+    load_session,
+    store_session,
+)
+from pipefy_auth.verification import (
+    AudiencePolicy,
+    JwtValidator,
+    RequireAudience,
+    SkipAudience,
+    TokenValidationError,
+)
+
+__all__ = [
+    "AudiencePolicy",
+    "AuthSettings",
+    "JwtValidationSettings",
+    "RequireAudience",
+    "SkipAudience",
+    "DEFAULT_AUTH_CLIENT_ID",
+    "DiscoveryPolicy",
+    "JwtValidator",
+    "LoginError",
+    "LoginResult",
+    "OAuthErrorResponse",
+    "OidcClient",
+    "ProviderMetadata",
+    "RefreshError",
+    "RefreshableBearerAuth",
+    "RevocationError",
+    "RevocationUnsupportedError",
+    "ResolvedAuth",
+    "ServiceAccount",
+    "ServiceAccountAuth",
+    "SessionDeleteError",
+    "StaticBearerAuth",
+    "StaticTokenAuth",
+    "StoredSession",
+    "StoredSessionAuth",
+    "TokenResponse",
+    "TokenValidationError",
+    "__version__",
+    "build_httpx_auth",
+    "configure_keychain_backend",
+    "delete_session",
+    "detect_pipefy_auth_methods",
+    "ensure_fresh_session",
+    "fetch_provider_metadata",
+    "keychain_backend_name",
+    "keychain_key",
+    "load_session",
+    "missing_auth_message",
+    "refresh_access_token",
+    "resolve_pipefy_auth",
+    "revoke_session",
+    "run_login",
+    "store_session",
+]

pipefy_auth-0.3.0a1/src/pipefy_auth/_http.py

@@ -0,0 +1,33 @@
+"""Shared httpx.Client context-manager helper for the OAuth flow modules."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager, nullcontext
+from typing import Iterator
+
+import httpx
+from pipefy_infra.telemetry import auth_telemetry_headers
+
+
+@contextmanager
+def http_client(
+    provided: httpx.Client | None, *, timeout: float
+) -> Iterator[httpx.Client]:
+    """Yield ``provided`` (without closing it) or a fresh ``httpx.Client``.
+
+    The fresh client carries the auth telemetry headers so OAuth traffic to the
+    IdP is attributable to a pipefy-auth version rather than anonymous httpx.
+    """
+    if provided is not None:
+        with nullcontext(provided) as client:
+            yield client
+        return
+    from pipefy_auth import __version__
+
+    with httpx.Client(
+        timeout=timeout, headers=auth_telemetry_headers(version=__version__)
+    ) as client:
+        yield client
+
+
+__all__ = ["http_client"]

pipefy_auth-0.3.0a1/src/pipefy_auth/bearer.py

@@ -0,0 +1,91 @@
+"""``httpx.Auth`` adapters that attach ``Authorization: Bearer …`` headers."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator, Callable, Generator
+
+from httpx import Auth, Request, Response
+
+
+class StaticBearerAuth(Auth):
+    """Attach a fixed ``Authorization: Bearer …`` header."""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def auth_flow(self, request: Request) -> Generator[Request, Response, None]:
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        yield request
+
+
+class RefreshableBearerAuth(Auth):
+    """Per-request bearer + reactive refresh-on-401 retry.
+
+    Pairs per-request token rotation (the provider is re-called on every request,
+    so a keychain-backed refresh in :func:`ensure_fresh_session` is observed
+    without rebuilding the SDK client) with a 401 safety net: when an API call
+    returns 401, ``force_refresh`` is
+    invoked to obtain a new bearer and the request is retried exactly once. If
+    it returns ``None`` or the same token, the 401 propagates so callers surface
+    a "session expired, re-login" error instead of looping. ``force_refresh`` is
+    trusted to return ``str | None`` — translating an IdP failure (``RefreshError``)
+    into ``None`` is the wiring's job, not this class's.
+
+    The eager refresh path (``token_provider`` calling
+    :func:`pipefy_auth.refresh.ensure_fresh_session`) still handles the common
+    "token expired by our clock" case. This class fills the gap eager refresh
+    cannot see — IdP-side revocation, and the narrow race between the eager
+    check and the API call.
+
+    Concurrency model: under async fan-out, the internal lock **serializes**
+    both eager token reads (``token_provider``) and reactive refreshes
+    (``force_refresh``) — three concurrent 401s run three refreshes
+    back-to-back, not one shared refresh. Coalescing racing refreshes is
+    out of scope here; it's the responsibility of the refresh-token grant
+    path.
+    """
+
+    def __init__(
+        self,
+        *,
+        token_provider: Callable[[], str],
+        force_refresh: Callable[[], str | None],
+    ) -> None:
+        self._token_provider = token_provider
+        self._force_refresh = force_refresh
+        self._async_lock = asyncio.Lock()
+
+    def auth_flow(self, request: Request) -> Generator[Request, Response, None]:
+        token = self._token_provider()
+        request.headers["Authorization"] = f"Bearer {token}"
+        response = yield request
+        if response.status_code != 401:
+            return
+        new_token = self._force_refresh()
+        if new_token is None or new_token == token:
+            return
+        request.headers["Authorization"] = f"Bearer {new_token}"
+        yield request
+
+    async def async_auth_flow(
+        self, request: Request
+    ) -> AsyncGenerator[Request, Response]:
+        async with self._async_lock:
+            token = await asyncio.to_thread(self._token_provider)
+        request.headers["Authorization"] = f"Bearer {token}"
+        response = yield request
+        if response.status_code != 401:
+            return
+        async with self._async_lock:
+            new_token = await asyncio.to_thread(self._force_refresh)
+        if new_token is None or new_token == token:
+            return
+        request.headers["Authorization"] = f"Bearer {new_token}"
+        yield request
+
+
+__all__ = [
+    "RefreshableBearerAuth",
+    "StaticBearerAuth",
+]

pipefy_auth-0.3.0a1/src/pipefy_auth/discovery.py

@@ -0,0 +1,150 @@
+"""OIDC discovery: fetch ``.well-known/openid-configuration`` from an issuer URL."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+from pipefy_infra import security
+from pipefy_infra.coerce import optional_str
+
+from pipefy_auth import _http
+
+DISCOVERY_PATH = "/.well-known/openid-configuration"
+_DEFAULT_TIMEOUT = 10.0
+
+
+@dataclass(frozen=True)
+class ProviderMetadata:
+    """Subset of OIDC provider metadata the login flow needs.
+
+    ``end_session_endpoint`` is optional per OIDC Discovery 1.0: not every IdP
+    advertises it. ``auth logout`` soft-fails when it's absent (warns + clears
+    the local session only). ``jwks_uri`` is the signing-key set the
+    resource-server bearer verifier reads; it's likewise modeled optional so
+    callers that don't validate inbound tokens (the login flow) don't depend on
+    it.
+    """
+
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    end_session_endpoint: str | None = None
+    jwks_uri: str | None = None
+
+
+@dataclass(frozen=True)
+class DiscoveryPolicy:
+    """Knobs governing how ``fetch_provider_metadata`` validates its inputs.
+
+    Bundled so future flags (cached metadata, custom timeouts) can grow here
+    without re-threading kwargs through every caller.
+    """
+
+    allow_insecure_urls: bool = False
+
+
+def _normalize_issuer(issuer_url: str) -> str:
+    return issuer_url.rstrip("/")
+
+
+def discovery_url(issuer_url: str) -> str:
+    """Return the well-known discovery URL for ``issuer_url``."""
+    return f"{_normalize_issuer(issuer_url)}{DISCOVERY_PATH}"
+
+
+def fetch_provider_metadata(
+    issuer_url: str,
+    *,
+    policy: DiscoveryPolicy = DiscoveryPolicy(),
+    timeout: float = _DEFAULT_TIMEOUT,
+    client: httpx.Client | None = None,
+) -> ProviderMetadata:
+    """Fetch and parse the issuer's OIDC discovery document.
+
+    Validates that ``metadata.issuer`` matches ``issuer_url`` (per OIDC
+    Discovery 1.0 §4.3) and that the returned ``authorization_endpoint`` and
+    ``token_endpoint`` aren't pointing at internal hosts or non-HTTPS URLs —
+    a tampered or misconfigured discovery doc must not be allowed to redirect
+    the browser dance or token exchange to an attacker-controlled target.
+
+    Raises:
+        ValueError: When the discovery document is unreachable, malformed,
+            issuer-mismatched, or returns endpoint URLs that don't pass the
+            shared SSRF check. Message is user-facing.
+    """
+    url = discovery_url(issuer_url)
+    with _http.http_client(client, timeout=timeout) as http:
+        try:
+            response = http.get(url)
+        except httpx.HTTPError as exc:
+            raise ValueError(
+                f"Could not reach Pipefy auth server at {url}: {exc}"
+            ) from exc
+
+    if response.status_code != 200:
+        # Status-only; never echo the raw body. Discovery isn't OAuth so there's
+        # no RFC 6749 ``error`` field to surface, and a `[:N]` window of the
+        # body is the same echo-channel class scrubbed in ``OAuthErrorResponse``.
+        raise ValueError(f"OIDC discovery failed ({response.status_code}) at {url}")
+
+    try:
+        data = response.json()
+    except ValueError as exc:
+        raise ValueError(
+            f"OIDC discovery returned non-JSON body at {url}: {exc}"
+        ) from exc
+
+    required = ("issuer", "authorization_endpoint", "token_endpoint")
+    missing = [key for key in required if not data.get(key)]
+    if missing:
+        raise ValueError(
+            f"OIDC discovery at {url} is missing required fields: {', '.join(missing)}"
+        )
+
+    # OIDC Discovery 1.0 §4.3 — the ``issuer`` claim must match the URL the
+    # document was fetched from. Trailing slashes don't carry meaning here.
+    claimed_issuer = str(data["issuer"])
+    if _normalize_issuer(claimed_issuer) != _normalize_issuer(issuer_url):
+        raise ValueError(
+            f"OIDC discovery issuer mismatch: requested {issuer_url!r}, "
+            f"document claims {claimed_issuer!r}"
+        )
+
+    authorization_endpoint = str(data["authorization_endpoint"])
+    token_endpoint = str(data["token_endpoint"])
+    end_session_endpoint = optional_str(data.get("end_session_endpoint"))
+    jwks_uri = optional_str(data.get("jwks_uri"))
+
+    endpoints: list[tuple[str, str]] = [
+        ("authorization_endpoint", authorization_endpoint),
+        ("token_endpoint", token_endpoint),
+    ]
+    if end_session_endpoint is not None:
+        endpoints.append(("end_session_endpoint", end_session_endpoint))
+    if jwks_uri is not None:
+        endpoints.append(("jwks_uri", jwks_uri))
+    for field, value in endpoints:
+        try:
+            security.validate_https_url(
+                value, field, allow_insecure=policy.allow_insecure_urls
+            )
+        except ValueError as exc:
+            raise ValueError(f"OIDC discovery returned invalid {field}: {exc}") from exc
+
+    return ProviderMetadata(
+        issuer=claimed_issuer,
+        authorization_endpoint=authorization_endpoint,
+        token_endpoint=token_endpoint,
+        end_session_endpoint=end_session_endpoint,
+        jwks_uri=jwks_uri,
+    )
+
+
+__all__ = [
+    "DISCOVERY_PATH",
+    "DiscoveryPolicy",
+    "ProviderMetadata",
+    "discovery_url",
+    "fetch_provider_metadata",
+]