pipefy-auth 0.3.0a1__py3-none-any.whl

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/_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/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/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",
+]

pipefy_auth/flow.py

@@ -0,0 +1,213 @@
+"""Orchestrate the Authorization Code + PKCE login against a Pipefy OIDC issuer."""
+
+from __future__ import annotations
+
+import secrets
+import webbrowser
+from dataclasses import dataclass
+from typing import Callable, cast
+from urllib.parse import urlencode
+
+import httpx
+from pydantic import ValidationError
+
+from pipefy_auth import _http
+from pipefy_auth.discovery import (
+    DiscoveryPolicy,
+    ProviderMetadata,
+    fetch_provider_metadata,
+)
+from pipefy_auth.loopback import CallbackResult, LoopbackCapture
+from pipefy_auth.pkce import challenge_from_verifier, generate_verifier
+from pipefy_auth.responses import (
+    OAuthErrorResponse,
+    TokenResponse,
+    _format_validation_error,
+)
+
+_DEFAULT_SCOPES = ("openid", "profile", "email", "offline_access")
+_TOKEN_EXCHANGE_TIMEOUT_S = 30.0
+
+
+class LoginError(RuntimeError):
+    """User-facing failure during the login flow (rendered verbatim by the CLI)."""
+
+
+@dataclass(frozen=True)
+class LoginResult:
+    """The OAuth token, plus the resolved issuer (post-discovery)."""
+
+    issuer: str
+    token: TokenResponse
+
+
+def build_authorization_url(
+    *,
+    metadata: ProviderMetadata,
+    client_id: str,
+    redirect_uri: str,
+    code_challenge: str,
+    state: str,
+    scopes: tuple[str, ...] = _DEFAULT_SCOPES,
+) -> str:
+    """Construct the URL the user's browser should open to begin login."""
+    params = {
+        "client_id": client_id,
+        "response_type": "code",
+        "redirect_uri": redirect_uri,
+        "scope": " ".join(scopes),
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    }
+    return f"{metadata.authorization_endpoint}?{urlencode(params)}"
+
+
+def exchange_code(
+    *,
+    metadata: ProviderMetadata,
+    client_id: str,
+    code: str,
+    redirect_uri: str,
+    code_verifier: str,
+    client: httpx.Client,
+) -> TokenResponse:
+    """Exchange an authorization code for tokens at the issuer's token endpoint."""
+    try:
+        response = client.post(
+            metadata.token_endpoint,
+            data={
+                "grant_type": "authorization_code",
+                "client_id": client_id,
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "code_verifier": code_verifier,
+            },
+        )
+    except httpx.HTTPError as exc:
+        raise LoginError(f"Token exchange request failed: {exc}") from exc
+
+    if response.status_code != 200:
+        # ``error_description`` is free-form per RFC 6749 §5.2 — its content
+        # reflects the IdP's framing, and surfacing it at all is part of trusting
+        # the IdP. A length cap wouldn't change that (an attacker can truncate
+        # to fit any cap, and a tight cap kills legitimate error context).
+        raise LoginError(
+            OAuthErrorResponse.from_response(response).render(
+                fallback=f"Token endpoint returned HTTP {response.status_code}",
+                prefix="Token exchange failed",
+            )
+        )
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise LoginError(f"Token endpoint returned non-JSON response: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise LoginError("Token endpoint returned a non-object JSON payload.")
+    try:
+        return TokenResponse.from_payload(payload)
+    except ValidationError as exc:
+        raise LoginError(_format_validation_error(exc)) from exc
+    except ValueError as exc:
+        raise LoginError(str(exc)) from exc
+
+
+def run_login(
+    *,
+    issuer_url: str,
+    client_id: str,
+    scopes: tuple[str, ...] = _DEFAULT_SCOPES,
+    callback_timeout_s: float = 180.0,
+    open_browser: Callable[[str], bool] = webbrowser.open,
+    on_url: Callable[[str], None] | None = None,
+    http_client: httpx.Client | None = None,
+    discovery_policy: DiscoveryPolicy = DiscoveryPolicy(),
+) -> LoginResult:
+    """Run the full PKCE loopback login. Returns tokens; does **not** persist them.
+
+    Args:
+        issuer_url: OIDC issuer URL (e.g. ``https://signin.pipefy.com/realms/pipefy``).
+        client_id: Public client id registered for the CLI.
+        scopes: Scopes to request. Must include ``offline_access`` for a refresh
+            token to be issued.
+        callback_timeout_s: Seconds to wait for the browser callback.
+        open_browser: Launch the browser at ``auth_url``. Returns ``True`` if a
+            browser was launched; ``False`` otherwise (``--no-browser`` mode or
+            the OS couldn't open one).
+        on_url: Called with ``auth_url`` only when ``open_browser`` returned
+            ``False`` — i.e., the user needs to open the URL by hand. Pass
+            ``None`` to skip the fallback (callers must then handle the
+            ``False`` return themselves).
+        http_client: Optional pre-configured ``httpx.Client`` (testing). When
+            omitted, one client is created and reused for discovery + token
+            exchange so the same TLS connection can serve both requests.
+        discovery_policy: Validation knobs forwarded to
+            :func:`fetch_provider_metadata` (notably ``allow_insecure_urls``
+            for local-development IdPs over http / private IPs).
+
+    Raises:
+        LoginError: For any user-visible failure (discovery, state mismatch,
+            token exchange).
+        TimeoutError: When no browser callback arrives in time.
+    """
+    with _http.http_client(http_client, timeout=_TOKEN_EXCHANGE_TIMEOUT_S) as http:
+        try:
+            metadata = fetch_provider_metadata(
+                issuer_url, policy=discovery_policy, client=http
+            )
+        except ValueError as exc:
+            raise LoginError(str(exc)) from exc
+
+        # Bind the loopback server *before* opening the browser so no other
+        # process can grab the ephemeral port in between. The `with` block
+        # guarantees the socket is released even if a step before
+        # `await_callback` raises.
+        with LoopbackCapture() as capture:
+            verifier = generate_verifier()
+            state = secrets.token_urlsafe(24)
+            auth_url = build_authorization_url(
+                metadata=metadata,
+                client_id=client_id,
+                redirect_uri=capture.redirect_uri,
+                code_challenge=challenge_from_verifier(verifier),
+                state=state,
+                scopes=scopes,
+            )
+            if not open_browser(auth_url) and on_url is not None:
+                on_url(auth_url)
+
+            callback = capture.await_callback(timeout=callback_timeout_s)
+            _ensure_callback_ok(callback, expected_state=state)
+            code = cast(str, callback.code)
+
+            token = exchange_code(
+                metadata=metadata,
+                client_id=client_id,
+                code=code,
+                redirect_uri=capture.redirect_uri,
+                code_verifier=verifier,
+                client=http,
+            )
+    return LoginResult(issuer=metadata.issuer, token=token)
+
+
+def _ensure_callback_ok(callback: CallbackResult, *, expected_state: str) -> None:
+    if callback.error:
+        detail = callback.error_description or ""
+        suffix = f": {detail}" if detail else ""
+        raise LoginError(f"Authorization server returned {callback.error}{suffix}")
+    if callback.state != expected_state:
+        raise LoginError(
+            "State mismatch on OAuth callback (possible CSRF). Aborting login."
+        )
+    if not callback.code:
+        raise LoginError("OAuth callback did not include an authorization code.")
+
+
+__all__ = [
+    "LoginError",
+    "LoginResult",
+    "build_authorization_url",
+    "exchange_code",
+    "run_login",
+]

pipefy_auth/identity.py

@@ -0,0 +1,27 @@
+"""OIDC client identity shared by every consumer of the stored user session."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Refresh tokens are bound to the client_id that obtained them, so this value
+# is fixed across consumers (CLI, MCP, …) and not user-configurable.
+DEFAULT_AUTH_CLIENT_ID = "pipefy-cli"
+
+
+@dataclass(frozen=True)
+class OidcClient:
+    """OIDC client identity: issuer URL + the public client id registered there.
+
+    Presence of an :class:`OidcClient` is what gates the stored-session method
+    of the credential precedence chain.
+    """
+
+    issuer_url: str
+    client_id: str
+
+
+__all__ = [
+    "DEFAULT_AUTH_CLIENT_ID",
+    "OidcClient",
+]