af-credentials 0.1.0__py3-none-any.whl

af_credentials/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from af_credentials._version import version as __version__
+
+__all__ = ["__version__"]

af_credentials/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

af_credentials/_version.pyi

@@ -0,0 +1,2 @@
+version: str
+version_tuple: tuple[int, int, int] | tuple[int, int, int, str, str]

af_credentials/mcp.py

@@ -0,0 +1,56 @@
+"""Optional adapter from BrokerTokenVerifier to the mcp SDK's TokenVerifier protocol.
+
+Importing this module requires the ``mcp`` package (the ``[mcp]`` extra --
+see pyproject.toml and README.md); af_credentials.verifier itself never
+imports it, so a caller who only needs token verification (no MCP server)
+pays no cost for this optional dependency. The guard below turns a missing
+``mcp`` install into one clear error naming the extra to install, rather
+than a bare ``ModuleNotFoundError`` pointing at this file's internals.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from af_credentials.verifier import BrokerTokenVerifier
+
+try:
+    from mcp.server.auth.provider import AccessToken, TokenVerifier
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    msg = (  # pylint: disable=invalid-name
+        "af_credentials.mcp requires the 'mcp' package. Install it via the "
+        "'mcp' extra: pip install af-credentials[mcp]"
+    )
+    raise ImportError(msg) from exc
+
+
+class _BrokerTokenVerifierAdapter(TokenVerifier):
+    """Adapts a BrokerTokenVerifier to the mcp SDK's TokenVerifier protocol.
+
+    Never constructed directly by callers -- use ``mcp_token_verifier()``.
+    Carries no authorization claims: ``scopes`` is always empty, matching
+    the AF Broker Identity Token itself carrying none (see verifier.py's
+    module docstring) -- an MCP server wanting authorization must resolve
+    it itself from ``client_id`` (the token's ``sub``), not from this
+    adapter's output.
+    """
+
+    def __init__(self, verifier: BrokerTokenVerifier) -> None:
+        self._verifier = verifier
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        claims = await self._verifier.verify(token)
+        if claims is None:
+            return None
+        return AccessToken(
+            token=token,
+            client_id=claims.sub,
+            scopes=[],
+            expires_at=claims.exp,
+        )
+
+
+def mcp_token_verifier(verifier: BrokerTokenVerifier) -> TokenVerifier:
+    """Wrap *verifier* as an mcp SDK ``TokenVerifier`` for a FastMCP/mcp server's auth configuration."""
+    return _BrokerTokenVerifierAdapter(verifier)

af_credentials/proxy.py

@@ -0,0 +1,214 @@
+"""Client for redeeming a brokered x509/VOMS proxy.
+
+Codes against a redeem contract the broker does not implement yet (issue
+#112): ``POST {broker_url}/v1/credentials/x509/redeem``, bearer-authenticated
+with an AF Broker Identity Token (see verifier.py), empty JSON body. A 200
+response is::
+
+    {
+      "pem": "<PEM-encoded proxy certificate + key>",
+      "dn": "<VOMS proxy subject DN>",
+      "voms_attributes": ["<VOMS FQAN>", ...],
+      "expires_at": "<ISO-8601 timestamp>",
+      "remaining_seconds": <int>
+    }
+
+Mirrors the broker's own credential-brokering shape (x509/VOMS proxies
+minted via ephemeral k8s Jobs, docs/auth.md's "Critical auth constraint"
+section) without importing anything broker-side: this client only ever
+talks HTTP to ``{broker_url}``.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx2
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from typing_extensions import Self
+
+_REDEEM_PATH = "/v1/credentials/x509/redeem"
+
+
+class ProxyNotAvailableError(Exception):
+    """No usable proxy is available for this caller right now.
+
+    Raised when the broker answers 404 (e.g. the caller has no linked
+    ``.globus`` credential to mint a proxy from) or when it did mint one
+    but its remaining validity is below the caller's ``min_remaining``
+    floor -- in both cases the caller's fix is "try a different credential
+    or come back later," not "retry this exact call," which is what
+    distinguishes this from ``ProxyRedeemError``.
+    """
+
+    def __init__(self, detail: str) -> None:
+        super().__init__(detail)
+        self.detail = detail
+
+
+class ProxyRedeemError(Exception):
+    """The broker rejected or failed the redeem call for a reason other than "no proxy available" (a non-404, non-200 response)."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"proxy redeem failed with status {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+def _parse_iso8601(value: str) -> datetime:
+    """Parse an ISO-8601 timestamp, accepting a trailing Z on Python 3.10.
+
+    ``datetime.fromisoformat`` only learned the ``Z`` suffix in 3.11; the
+    broker emits ``+00:00`` offsets today, but a UTC designator from another
+    issuer must not break the oldest supported interpreter.
+    """
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    return datetime.fromisoformat(value)
+
+
+@dataclass
+class ProxyHandle:
+    """A materialized x509/VOMS proxy on disk.
+
+    A context manager: ``__exit__``/``close()`` deletes the underlying
+    file. Not cached by ``ProxyClient`` -- every ``proxy_file()`` call
+    returns its own handle over its own file (the broker itself caches the
+    proxy; this client does not cache handles across calls).
+    """
+
+    path: Path
+    dn: str
+    expires_at: datetime
+    _closed: bool = field(default=False, init=False, repr=False)
+
+    def close(self) -> None:
+        """Delete the underlying file. Safe to call more than once."""
+        if not self._closed:
+            self.path.unlink(missing_ok=True)
+            self._closed = True
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class ProxyClient:
+    """Redeems brokered x509/VOMS proxies from an AF MCP broker.
+
+    Materialized proxy files live under a private, 0700 directory created
+    lazily on first use (one per ``ProxyClient`` instance, reused across
+    calls); each file inside it is written 0600. *min_remaining* rejects a
+    freshly-redeemed proxy whose ``remaining_seconds`` is already below a
+    useful floor -- a caller who then retried "the credential I just got"
+    would just get the same near-expired proxy back (the broker caches it),
+    so this is reported as ``ProxyNotAvailableError`` rather than handed to
+    the caller as if it were usable.
+    """
+
+    def __init__(
+        self,
+        broker_url: str,
+        *,
+        timeout: float = 10.0,
+        min_remaining: float = 60.0,
+        http_client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        """Construct a client against *broker_url* (e.g. ``https://mcp.af.uchicago.edu``).
+
+        *http_client*, when given, is used for the redeem call instead of a
+        short-lived client created per call -- primarily a test seam
+        (inject an ``httpx2.AsyncClient`` backed by ``httpx2.MockTransport``)
+        but also usable by callers who want connection pooling. The client
+        never closes an injected ``http_client``.
+        """
+        self._broker_url = broker_url.rstrip("/")
+        self._timeout = timeout
+        self._min_remaining = min_remaining
+        self._http_client = http_client
+        self._dir: Path | None = None
+
+    async def proxy_file(self, bearer: str) -> ProxyHandle:
+        """Redeem a proxy and materialize it as a private 0600 file, returning a handle whose ``close()`` deletes it."""
+        data = await self._redeem(bearer)
+        directory = self._ensure_dir()
+        fd, raw_path = tempfile.mkstemp(dir=directory, prefix="proxy-", suffix=".pem")
+        path = Path(raw_path)
+        try:
+            with os.fdopen(fd, "w") as pem_file:
+                pem_file.write(data["pem"])
+            path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0600
+        except OSError:
+            path.unlink(missing_ok=True)
+            raise
+        return ProxyHandle(
+            path=path,
+            dn=data["dn"],
+            expires_at=_parse_iso8601(data["expires_at"]),
+        )
+
+    async def pem_bytes(self, bearer: str) -> bytes:
+        """Redeem a proxy and return its PEM material in-memory, without writing a file."""
+        data = await self._redeem(bearer)
+        pem: str = data["pem"]
+        return pem.encode()
+
+    def _ensure_dir(self) -> Path:
+        if self._dir is None:
+            self._dir = Path(tempfile.mkdtemp(prefix="af-credentials-proxy-"))
+            self._dir.chmod(
+                stat.S_IRWXU
+            )  # 0700 -- belt-and-suspenders over mkdtemp's default
+        return self._dir
+
+    async def _redeem(self, bearer: str) -> dict[str, Any]:
+        url = f"{self._broker_url}{_REDEEM_PATH}"
+        headers = {"Authorization": f"Bearer {bearer}"}
+        if self._http_client is not None:
+            response = await self._http_client.post(
+                url, headers=headers, json={}, timeout=self._timeout
+            )
+        else:
+            async with httpx2.AsyncClient(timeout=self._timeout) as client:
+                response = await client.post(url, headers=headers, json={})
+
+        if response.status_code == 404:
+            raise ProxyNotAvailableError(self._extract_detail(response))
+        if response.status_code != 200:
+            raise ProxyRedeemError(response.status_code, self._extract_detail(response))
+
+        data: dict[str, Any] = response.json()
+        remaining = data["remaining_seconds"]
+        if remaining < self._min_remaining:
+            raise ProxyNotAvailableError(
+                f"redeemed proxy has only {remaining}s remaining "
+                f"(minimum {self._min_remaining}s required)"
+            )
+        return data
+
+    @staticmethod
+    def _extract_detail(response: httpx2.Response) -> str:
+        try:
+            body = response.json()
+        except ValueError:
+            return response.text
+        if isinstance(body, dict) and "detail" in body:
+            detail: str = body["detail"]
+            return detail
+        return response.text

af_credentials/verifier.py

@@ -0,0 +1,161 @@
+"""Async verification of AF Broker Identity Tokens.
+
+The token format is documented in docs/auth.md ("AF Broker Identity Token",
+issue #162) and minted by ``af_mcp_broker.credentials.broker_issued``: an
+identity assertion only -- ``iss``/``sub``/``aud``/``exp``/``iat``/``jti``
+always present, ``uid``/``gid``/``unixname`` present only for targets whose
+broker config sets ``include_posix``. Deliberately absent: capabilities,
+groups, or any authorization claim -- this module surfaces nothing beyond
+what the token itself carries.
+
+This module has no dependency on af_mcp_broker or any web framework: it is
+the client half of the contract, meant to be embedded in any backend that
+trusts the broker as a token issuer (ami-mcp's broker mode, later
+rucio-mcp), verifying against the broker's own published JWKS
+(``GET /.well-known/jwks.json``) with a standard JWT library.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx2
+import jwt
+from jwt.algorithms import RSAAlgorithm
+
+
+@dataclass(frozen=True)
+class BrokerClaims:
+    """Decoded, verified claims from an AF Broker Identity Token.
+
+    Mirrors the claim set ``BrokerTokenIssuer.mint()`` signs: ``sub``,
+    ``jti``, and ``exp`` are always present on a verified token; ``uid``/
+    ``gid``/``unixname`` are ``None`` unless the issuing broker included
+    POSIX identity claims for this token's audience.
+    """
+
+    sub: str
+    jti: str
+    exp: int
+    uid: int | None = None
+    gid: int | None = None
+    unixname: str | None = None
+
+
+class BrokerTokenVerifier:
+    """Verifies AF Broker Identity Tokens (RS256) against a broker's published JWKS.
+
+    JWKS keys are cached in-process for *cache_ttl* seconds, keyed by
+    ``kid``. A token whose ``kid`` isn't in the current cache triggers
+    exactly one refetch (to pick up a key rotated in since the last fetch,
+    per docs/auth.md's rotation procedure) -- if the refetched JWKS still
+    doesn't carry that ``kid``, verification fails without fetching again.
+
+    ``verify()`` returns ``None`` for every way a token can be *invalid*
+    (bad signature, wrong issuer/audience, expired, malformed, unknown
+    key) so callers can treat "not authenticated" uniformly. It does NOT
+    catch transport-level failures (a network error, or the JWKS endpoint
+    itself returning a non-2xx status) -- those propagate as exceptions, so
+    a caller can distinguish "the broker is unreachable" from "this token
+    is bad" and respond accordingly (e.g. a 503 vs. a 401).
+    """
+
+    def __init__(
+        self,
+        jwks_url: str,
+        issuer: str,
+        audience: str,
+        *,
+        cache_ttl: float = 300.0,
+        http_client: httpx2.AsyncClient | None = None,
+    ) -> None:
+        """Construct a verifier for tokens issued by *issuer* naming *audience* as the audience.
+
+        *http_client*, when given, is used for every JWKS fetch instead of
+        a short-lived client created per fetch -- primarily a test seam
+        (inject an ``httpx2.AsyncClient`` backed by ``httpx2.MockTransport``)
+        but also usable by callers who want connection pooling across
+        verifiers. The verifier never closes an injected client; it owns
+        the lifecycle of one it creates itself, closing it after each
+        fetch.
+        """
+        self._jwks_url = jwks_url
+        self._issuer = issuer
+        self._audience = audience
+        self._cache_ttl = cache_ttl
+        self._http_client = http_client
+        self._keys_by_kid: dict[str, dict[str, Any]] = {}
+        self._fetched_at: float | None = None
+
+    async def verify(self, token: str) -> BrokerClaims | None:
+        """Verify *token* and return its claims, or ``None`` if it is not a currently-valid AF Broker Identity Token for this verifier's issuer/audience.
+
+        Raises whatever ``httpx2`` raises (connection errors, timeouts, a
+        non-2xx JWKS response) if a JWKS fetch is needed and fails -- see
+        the class docstring on why that is deliberately not folded into a
+        ``None`` return.
+        """
+        try:
+            header = jwt.get_unverified_header(token)
+        except jwt.InvalidTokenError:
+            return None
+        kid = header.get("kid")
+        if not isinstance(kid, str):
+            return None
+
+        key_data = await self._get_key(kid)
+        if key_data is None:
+            return None
+
+        try:
+            public_key = RSAAlgorithm.from_jwk(key_data)
+            claims = jwt.decode(
+                token,
+                public_key,  # type: ignore[arg-type]  # JWKS only ever carries public keys
+                algorithms=["RS256"],
+                issuer=self._issuer,
+                audience=self._audience,
+                options={"verify_exp": True},
+            )
+        except jwt.InvalidTokenError:
+            return None
+
+        return BrokerClaims(
+            sub=claims["sub"],
+            jti=claims["jti"],
+            exp=claims["exp"],
+            uid=claims.get("uid"),
+            gid=claims.get("gid"),
+            unixname=claims.get("unixname"),
+        )
+
+    async def _get_key(self, kid: str) -> dict[str, Any] | None:
+        """Return the JWK for *kid*, refreshing the cache if it is stale or missing *kid* -- with at most one refetch for a *kid* the refreshed JWKS still doesn't carry."""
+        now = time.monotonic()
+        cache_is_stale = (
+            self._fetched_at is None or (now - self._fetched_at) > self._cache_ttl
+        )
+        if cache_is_stale or kid not in self._keys_by_kid:
+            await self._refresh()
+        return self._keys_by_kid.get(kid)
+
+    async def _refresh(self) -> None:
+        """Refetch the JWKS unconditionally and replace the key cache with its contents."""
+        keys = await self._fetch_jwks()
+        self._keys_by_kid = {
+            key_data["kid"]: key_data for key_data in keys if "kid" in key_data
+        }
+        self._fetched_at = time.monotonic()
+
+    async def _fetch_jwks(self) -> list[dict[str, Any]]:
+        if self._http_client is not None:
+            response = await self._http_client.get(self._jwks_url)
+            response.raise_for_status()
+            return response.json()["keys"]  # type: ignore[no-any-return]
+
+        async with httpx2.AsyncClient(timeout=10.0) as client:
+            response = await client.get(self._jwks_url)
+            response.raise_for_status()
+            return response.json()["keys"]  # type: ignore[no-any-return]

af_credentials-0.1.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: af-credentials
+Version: 0.1.0
+Summary: Backend-side client for the AF MCP credential broker: identity-token verification and x509 proxy redemption
+Project-URL: Documentation, https://af-credentials.readthedocs.io/
+Project-URL: Homepage, https://github.com/maniaclab/af-credentials
+Project-URL: Bug Tracker, https://github.com/maniaclab/af-credentials/issues
+Project-URL: Discussions, https://github.com/maniaclab/af-credentials/discussions
+Project-URL: Changelog, https://github.com/maniaclab/af-credentials/releases
+Author-email: Giordon Stark <kratsg@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx2<3,>=2.5.0
+Requires-Dist: pyjwt[crypto]>=2.8
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# af-credentials v0.1.0
+
+[![Actions Status][actions-badge]][actions-link]
+[![Documentation Status][rtd-badge]][rtd-link]
+
+[![PyPI version][pypi-version]][pypi-link]
+[![PyPI platforms][pypi-platforms]][pypi-link]
+
+[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
+
+[![Coverage][coverage-badge]][coverage-link]
+
+<!-- --8<-- [start:intro] -->
+
+Backend-side client for the AF MCP platform's broker-issued credentials (issue
+#112). Import package: `af_credentials`. No dependency on `af_mcp_broker`,
+FastAPI, or Kubernetes — this is meant to be embedded in _other_ MCP backends
+that need to trust the broker (ami-mcp's broker mode today, later rucio-mcp), so
+it stays deliberately thin: `pyjwt[crypto]` and `httpx2` at runtime,
+`mcp>=2.0.0,<3` opt-in via the `[mcp]` extra.
+
+<!-- --8<-- [end:intro] -->
+
+<!-- --8<-- [start:installation] -->
+
+## Installation
+
+```bash
+pip install af-credentials
+```
+
+With the optional `mcp` SDK adapter (`af_credentials.mcp`):
+
+```bash
+pip install af-credentials[mcp]
+```
+
+Or with pixi:
+
+```bash
+pixi add af-credentials
+```
+
+<!-- --8<-- [end:installation] -->
+
+<!-- --8<-- [start:requirements] -->
+
+## Requirements
+
+- Python 3.10+
+- An AF MCP broker publishing a JWKS endpoint (for `BrokerTokenVerifier`)
+
+<!-- --8<-- [end:requirements] -->
+
+<!-- --8<-- [start:usage] -->
+
+## `BrokerTokenVerifier` (`af_credentials.verifier`)
+
+Verifies an **AF Broker Identity Token** — the RS256 identity assertion
+`af_mcp_broker.credentials.broker_issued.BrokerTokenIssuer` mints for AF-native
+backends (see the platform's `docs/auth.md`, "AF Broker Identity Token"). The
+claim set is exactly `iss`/`sub`/`aud`/`exp`/`iat`/`jti`, plus
+`uid`/`gid`/`unixname` only when the issuing broker's target config requested
+POSIX identity — never a capability or group claim.
+
+```python
+from af_credentials.verifier import BrokerTokenVerifier
+
+verifier = BrokerTokenVerifier(
+    jwks_url="https://mcp.af.uchicago.edu/.well-known/jwks.json",
+    issuer="https://mcp.af.uchicago.edu",
+    audience="ami-mcp",
+)
+
+claims = await verifier.verify(token)
+if claims is None:
+    ...  # not authenticated: bad signature, wrong iss/aud, expired, ...
+else:
+    claims.sub, claims.jti, claims.exp  # always present
+    claims.uid, claims.gid, claims.unixname  # None unless this token carries POSIX identity
+```
+
+JWKS keys are cached in-process for `cache_ttl` seconds (default 300), keyed by
+`kid`. A token whose `kid` isn't in the current cache triggers **exactly one**
+refetch, to pick up a key rotated in since the last fetch (see the platform's
+key-rotation procedure) — if the refetched JWKS still doesn't carry that `kid`,
+verification fails without fetching again.
+
+`verify()` returns `None` for every way a token can be _invalid_ (bad signature,
+wrong issuer/audience, expired, malformed, unknown key), so callers can treat
+"not authenticated" uniformly. It does **not** catch transport failures — a JWKS
+fetch that can't connect, times out, or gets a non-2xx response raises the
+underlying `httpx2` exception, so a caller can tell "the broker is unreachable"
+apart from "this token is bad" and respond accordingly (e.g. a 503 vs. a 401).
+
+### `mcp_token_verifier()` (`af_credentials.mcp`, requires the `[mcp]` extra)
+
+Adapts a `BrokerTokenVerifier` to the `mcp` SDK's `TokenVerifier` protocol, for
+wiring an AF Broker Identity Token straight into a FastMCP/mcp server's auth
+configuration:
+
+```python
+from af_credentials.mcp import mcp_token_verifier
+
+token_verifier = mcp_token_verifier(
+    verifier
+)  # implements mcp.server.auth.provider.TokenVerifier
+```
+
+`verify_token(token)` returns
+`AccessToken(token=token, client_id=claims.sub, scopes=[], expires_at=claims.exp)`
+or `None`. `scopes` is always empty — the token itself carries no authorization
+claims, so a server wanting authorization must resolve it from `client_id` (the
+token's `sub`) itself, not from this adapter's output.
+
+## `ProxyClient` (`af_credentials.proxy`)
+
+Redeems a brokered x509/VOMS proxy. **Codes against a contract the broker does
+not implement yet** (issue #112) — the redeem endpoint below is a specification
+for the broker-side work to land against, not a live API.
+
+```python
+from af_credentials.proxy import ProxyClient, ProxyNotAvailableError, ProxyRedeemError
+
+client = ProxyClient("https://mcp.af.uchicago.edu")
+
+try:
+    with await client.proxy_file(bearer_token) as handle:
+        # handle.path   -> Path to a private 0600 PEM file (proxy cert + key)
+        # handle.dn     -> VOMS proxy subject DN
+        # handle.expires_at -> datetime
+        run_subprocess(env={"X509_USER_PROXY": str(handle.path)})
+    # file is deleted here, on __exit__
+except ProxyNotAvailableError:
+    ...  # no proxy available for this caller right now (no linked .globus,
+    # or the broker's own cached proxy is too close to expiry)
+except ProxyRedeemError as exc:
+    ...  # the broker rejected/failed the call; exc.status_code, exc.detail
+```
+
+Use `pem_bytes(bearer_token)` instead of `proxy_file()` when the caller wants
+the PEM material in-memory rather than as a file.
+
+### The redeem contract
+
+```
+POST {broker_url}/v1/credentials/x509/redeem
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{}
+```
+
+A 200 response:
+
+```json
+{
+  "pem": "<PEM-encoded proxy certificate + key>",
+  "dn": "<VOMS proxy subject DN>",
+  "voms_attributes": ["<VOMS FQAN>", "..."],
+  "expires_at": "<ISO-8601 timestamp>",
+  "remaining_seconds": 3600
+}
+```
+
+- **404** → `ProxyNotAvailableError(detail)` — the response's `detail` field (or
+  raw body if not JSON) is the exception's `.detail`.
+- Any other non-200 → `ProxyRedeemError(status_code, detail)`.
+- A 200 response whose `remaining_seconds` is below the client's `min_remaining`
+  (default 60s) is _also_ treated as `ProxyNotAvailableError` — the broker
+  caches the proxy itself, so a caller who retried "the credential I just got"
+  would just get the same near-expired proxy back.
+
+`ProxyClient` never caches handles across calls — every `proxy_file()`/
+`pem_bytes()` call redeems fresh (the broker is expected to be the one doing the
+caching). Materialized files live under a private, 0700 directory created lazily
+on first use and reused for the lifetime of the `ProxyClient` instance; each
+file inside it is written 0600.
+
+<!-- --8<-- [end:usage] -->
+
+<!-- --8<-- [start:development] -->
+
+## Development
+
+```bash
+git clone https://github.com/maniaclab/af-credentials
+cd af-credentials
+pixi install
+pixi run pre-commit-install
+```
+
+```bash
+pixi run test          # run tests
+pixi run lint           # pre-commit + pylint
+pixi run build          # build sdist + wheel
+pixi run docs-serve     # build and serve docs locally
+```
+
+<!-- --8<-- [end:development] -->
+
+<!-- prettier-ignore-start -->
+[actions-badge]:            https://github.com/maniaclab/af-credentials/actions/workflows/ci.yml/badge.svg
+[actions-link]:             https://github.com/maniaclab/af-credentials/actions
+[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
+[github-discussions-link]:  https://github.com/maniaclab/af-credentials/discussions
+[pypi-link]:                https://pypi.org/project/af-credentials/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/af-credentials
+[pypi-version]:             https://img.shields.io/pypi/v/af-credentials
+[rtd-badge]:                https://readthedocs.org/projects/af-credentials/badge/?version=latest
+[rtd-link]:                 https://af-credentials.readthedocs.io/en/latest/?badge=latest
+[coverage-badge]:           https://codecov.io/github/maniaclab/af-credentials/branch/main/graph/badge.svg
+[coverage-link]:            https://codecov.io/github/maniaclab/af-credentials
+
+<!-- prettier-ignore-end -->

af_credentials-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+af_credentials/__init__.py,sha256=7tonT-iauV7s6Va9zOc2dBryOiJWYk6Xlh-85n_cFYY,122
+af_credentials/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+af_credentials/_version.pyi,sha256=o7uNL6MhuJoiqpEnriU7rBT6TmkJZA-i2qMoNz9YcgQ,82
+af_credentials/mcp.py,sha256=BzZVTcXXpKtwCE_Pv3ghsXWGYWXkcWUd30lSbIJL1e0,2233
+af_credentials/proxy.py,sha256=bT58uE0uOuZYklwV9xbLSrOiKMOeVWfMoHuVJZoysSo,7804
+af_credentials/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+af_credentials/verifier.py,sha256=uO6_LN3XjOT3CLKGMBwPClJV00ubYO9vlbDadRggBgc,6490
+af_credentials-0.1.0.dist-info/METADATA,sha256=NWp4JJ7y94qWMTl9pSy9GOxOUHiXhlTGFYdG336kOxw,9289
+af_credentials-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+af_credentials-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+af_credentials-0.1.0.dist-info/RECORD,,

af_credentials-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

af_credentials-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.