authgate-client 0.1.0__py3-none-any.whl

authgate/__init__.py

@@ -0,0 +1,24 @@
+"""authgate — verify AuthGate access tokens.
+
+from authgate import AuthGate
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+caller = auth.verify(token)
+caller.may("material", "update")
+"""
+
+from .errors import AuthGateError, ConfigurationError, InvalidTokenError, IssuerUnavailableError
+from .identity import Identity
+from .verifier import AuthGate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthGate",
+    "AuthGateError",
+    "ConfigurationError",
+    "Identity",
+    "InvalidTokenError",
+    "IssuerUnavailableError",
+    "__version__",
+]

authgate/errors.py

@@ -0,0 +1,24 @@
+"""The errors this package defines.
+
+The verifier is framework-free: it raises these, and `authgate.fastapi` maps them to status codes.
+"""
+
+
+class AuthGateError(Exception):
+    """Base for every error this package raises."""
+
+
+class ConfigurationError(AuthGateError):
+    """The verifier is set up wrong, or the issuer's discovery document contradicts the setup."""
+
+
+class InvalidTokenError(AuthGateError):
+    """The caller's token is not acceptable here. Maps to 401."""
+
+
+class IssuerUnavailableError(AuthGateError):
+    """The issuer's signing keys could not be fetched. Maps to 503.
+
+    Kept apart from InvalidTokenError on purpose. Reporting an outage as a 401 tells the client its
+    token is bad, and a well-behaved client responds by discarding it and signing the user out.
+    """

authgate/fastapi.py

@@ -0,0 +1,68 @@
+"""FastAPI integration — the only module in the package that imports a web framework.
+
+Reached through `AuthGate.identity` and `AuthGate.require`; there is nothing here to import directly.
+
+No `from __future__ import annotations` in this module: FastAPI reads the dependency signatures
+below at runtime, and `require`'s annotation refers to a closure variable that string annotations
+could not resolve.
+"""
+
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from .errors import InvalidTokenError, IssuerUnavailableError
+from .identity import Identity
+
+if TYPE_CHECKING:
+    from .verifier import AuthGate
+
+log = logging.getLogger("authgate")
+
+# auto_error=False so a missing token gets the same 401 and WWW-Authenticate header as a bad one,
+# rather than FastAPI's own response. The scheme still shows up in the OpenAPI document.
+_bearer = HTTPBearer(auto_error=False)
+
+
+def identity_dependency(auth: "AuthGate") -> Callable[..., Identity]:
+    # A plain `def`, not `async def`: FastAPI runs it in its threadpool, so the rare key fetch
+    # never blocks the event loop.
+    def identity(credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_bearer)]) -> Identity:
+        if credentials is None:
+            raise HTTPException(
+                status.HTTP_401_UNAUTHORIZED, "missing bearer token", headers={"WWW-Authenticate": "Bearer"}
+            )
+        try:
+            # Stripped because FastAPI versions disagree on whether they do it: RFC 6750 allows more
+            # than one space after "Bearer", and only newer releases trim it off.
+            return auth.verify(credentials.credentials.strip())
+        except InvalidTokenError as exc:
+            raise HTTPException(
+                status.HTTP_401_UNAUTHORIZED, str(exc), headers={"WWW-Authenticate": 'Bearer error="invalid_token"'}
+            ) from exc
+        except IssuerUnavailableError as exc:
+            # The detail — internal host names, network errors, the caller's kid — is for the log, not
+            # for an unauthenticated caller. Truncated, because part of it is caller-supplied.
+            log.warning("Answering 503, the token issuer is unavailable: %.500s", exc)
+            raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "the token issuer is unavailable") from exc
+
+    return identity
+
+
+def require_dependency(auth: "AuthGate", resource: str, action: str) -> Callable[..., Identity]:
+    identity = auth.identity
+
+    def require(caller: Annotated[Identity, Depends(identity)]) -> Identity:
+        if not caller.may(resource, action):
+            raise HTTPException(
+                status.HTTP_403_FORBIDDEN,
+                f"missing permission: {action} on {resource}",
+                # RFC 6750 §3.1, and what Spring's resource server answers the same denial with.
+                headers={"WWW-Authenticate": 'Bearer error="insufficient_scope"'},
+            )
+        return caller
+
+    return require

authgate/identity.py

@@ -0,0 +1,55 @@
+"""The caller, as an AuthGate access token describes them."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import KW_ONLY, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Identity:
+    """A typed view over a verified token, so handlers are not digging through a claim dict.
+
+    Mirrors `Identity` in the Java starter, so a permission check reads the same in both languages.
+
+    `account_id` is AuthGate's account id (the `sub` claim), not the external provider's subject:
+    a service never needs to know which identity provider someone signed in through.
+
+    `claims` takes no part in equality or hashing: two tokens for the same caller differ in `jti`,
+    `iat` and `exp`, and still describe the same caller.
+    """
+
+    account_id: str
+    # Everything after the account id is keyword-only, so a field added later cannot silently shift
+    # a positional call in someone's code.
+    _: KW_ONLY
+    tenant_id: str | None = None
+    email: str | None = None
+    superuser: bool = False
+    permissions: Mapping[str, frozenset[str]] = field(default_factory=dict, hash=False)
+    claims: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_claims(cls, claims: Mapping[str, Any]) -> Identity:
+        """Build an identity from a payload that has already been verified. `sub` must be present."""
+        permissions: dict[str, frozenset[str]] = {}
+        perms = claims.get("perms")
+        if isinstance(perms, Mapping):
+            for resource, actions in perms.items():
+                # A malformed entry grants nothing rather than failing the whole request — the Java
+                # starter treats one the same way.
+                permissions[resource] = frozenset(map(str, actions)) if isinstance(actions, list) else frozenset()
+        return cls(
+            account_id=str(claims["sub"]),
+            tenant_id=claims.get("tenant"),
+            email=claims.get("email"),
+            # Only a literal JSON true. A string "true" is a malformed token, not a superuser.
+            superuser=claims.get("superuser") is True,
+            permissions=permissions,
+            claims=dict(claims),
+        )
+
+    def may(self, resource: str, action: str) -> bool:
+        """Whether this caller may take `action` on `resource`. Superusers pass everything."""
+        return self.superuser or action in self.permissions.get(resource, frozenset())

authgate/keys.py

@@ -0,0 +1,167 @@
+"""Fetches and caches an issuer's signing keys."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+
+import jwt
+
+from .errors import AuthGateError, ConfigurationError, IssuerUnavailableError
+
+log = logging.getLogger("authgate")
+
+_TIMEOUT_SECONDS = 5
+
+
+class KeyCache:
+    """The issuer's RS256 public keys, indexed by `kid`.
+
+    Discovery is read once; the JWKS is refreshed when it goes stale or when a token names a key we
+    have not seen, which is how a key rotation reaches a running verifier.
+
+    Every fetch *attempt*, successful or not, is spaced at least `min_interval` seconds from the
+    last. Without that, a stream of tokens with made-up `kid`s would turn each request into a
+    request to the issuer. The defaults — 300 s freshness, 30 s between attempts — are the ones
+    Nimbus uses, which is what the Java starter verifies with.
+    """
+
+    def __init__(
+        self,
+        issuer: str,
+        *,
+        ttl: float = 300,
+        min_interval: float = 30,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._issuer = issuer
+        self._ttl = ttl
+        self._min_interval = min_interval
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._keys: dict[str, Any] | None = None
+        self._fetched_at = 0.0
+        self._attempted_at: float | None = None
+        self._failure: AuthGateError | None = None
+        self._refresh_failed = False
+        self._jwks_uri: str | None = None
+        self.issuer: str | None = None
+        """The `iss` value tokens must carry, exactly as the discovery document states it."""
+
+    def get(self, kid: str) -> Any | None:
+        """The key for `kid`, or None if the issuer does not publish one.
+
+        Raises IssuerUnavailableError (or ConfigurationError) while no keys have ever been fetched,
+        and IssuerUnavailableError for an unknown `kid` while the last refresh failed — the token
+        may be perfectly valid, and a 401 would tell its holder otherwise. Once keys are cached, a
+        failed refresh keeps serving them.
+        """
+        keys = self._keys
+        cached = keys is not None and kid in keys
+        if cached and not self._stale():
+            return keys[kid]
+
+        # Without a usable key, wait for whoever is fetching. With one, never queue behind a slow
+        # issuer: the cached key is the best answer until the refresh lands.
+        if not self._lock.acquire(blocking=not cached):
+            return keys[kid]
+        try:
+            keys = self._keys
+            wanted = keys is None or kid not in keys or self._stale()
+            # The rate limit doubles as the re-check: a request that queued on the lock behind one
+            # that just fetched finds the attempt too recent and uses what it brought back.
+            if wanted and self._may_attempt():
+                self._refresh()
+            keys, failure, refresh_failed = self._keys, self._failure, self._refresh_failed
+        finally:
+            self._lock.release()
+
+        if keys is None:
+            raise type(failure)(*failure.args) if failure else IssuerUnavailableError("no keys fetched yet")
+        if kid not in keys and refresh_failed:
+            # Until a refresh succeeds, not every request that names an unknown kid can make its own
+            # attempt, so the answer holds for the whole interval, not just the one that tried.
+            raise IssuerUnavailableError(f"could not refresh signing keys from {self._issuer} to look for {kid!r}")
+        return keys.get(kid)
+
+    def _stale(self) -> bool:
+        return self._clock() - self._fetched_at >= self._ttl
+
+    def _may_attempt(self) -> bool:
+        return self._attempted_at is None or self._clock() - self._attempted_at >= self._min_interval
+
+    def _refresh(self) -> None:
+        """Fetch the JWKS. A failure with keys cached keeps them in use and marks the refresh failed."""
+        self._attempted_at = self._clock()
+        try:
+            if self._jwks_uri is None:
+                self._discover()
+            keys = _usable_keys(_fetch_json(self._jwks_uri))
+        except ConfigurationError as exc:
+            # Stored as a fresh instance so the cache does not keep the traceback's frames alive.
+            self._failure = ConfigurationError(*exc.args)
+            raise
+        except Exception as exc:  # whatever went wrong fetching or parsing, the issuer is unavailable to us
+            if self._keys is None:
+                self._failure = IssuerUnavailableError(f"could not fetch signing keys from {self._issuer}: {exc}")
+                raise IssuerUnavailableError(*self._failure.args) from exc
+            log.warning("Could not refresh signing keys from %s, keeping cached keys: %r", self._issuer, exc)
+            self._refresh_failed = True
+            return
+
+        self._keys = keys
+        self._fetched_at = self._attempted_at
+        self._failure = None
+        self._refresh_failed = False
+
+    def _discover(self) -> None:
+        url = f"{self._issuer}/.well-known/openid-configuration"
+        document = _fetch_json(url)
+        stated = document.get("issuer") if isinstance(document, dict) else None
+        # A redirect or a misconfigured proxy must not be able to point us at another issuer's keys.
+        if not isinstance(stated, str) or stated.rstrip("/") != self._issuer:
+            raise ConfigurationError(f"{url} names issuer {stated!r}, expected {self._issuer!r}")
+        jwks_uri = document.get("jwks_uri")
+        if not isinstance(jwks_uri, str):
+            raise ConfigurationError(f"{url} has no jwks_uri")
+        self._jwks_uri = jwks_uri
+        self.issuer = stated
+
+
+def _usable_keys(document: Any) -> dict[str, Any]:
+    """The RS256 signing keys in a JWKS, by `kid`.
+
+    Anything else is dropped here rather than failing later: an EC key under a `kid` a token names
+    would otherwise reach the RS256 verifier and fail as a 500 rather than a 401. If a `kid`
+    repeats, the first entry wins, so an unusable duplicate cannot displace a good key.
+    """
+    keys: dict[str, Any] = {}
+    for key in jwt.PyJWKSet.from_dict(document).keys:
+        if (
+            isinstance(key.key_id, str)
+            and key.key_type == "RSA"
+            and key.algorithm_name == "RS256"
+            and key.public_key_use in (None, "sig")
+        ):
+            keys.setdefault(key.key_id, key.key)
+    if not keys:
+        # Treated like any other failed fetch: an issuer publishing nothing usable is broken, and
+        # adopting an empty set would reject every token.
+        raise ValueError("the JWKS has no RS256 signing key")
+    return keys
+
+
+def _fetch_json(url: str) -> Any:
+    request = urllib.request.Request(url, headers={"Accept": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=_TIMEOUT_SECONDS) as response:
+            return json.load(response)
+    except urllib.error.HTTPError as exc:
+        exc.close()  # an error status arrives as an exception that still holds the open response
+        raise

authgate/verifier.py

@@ -0,0 +1,153 @@
+"""Verifies AuthGate access tokens."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import cached_property
+from urllib.parse import urlsplit
+
+import jwt
+
+from .errors import ConfigurationError, InvalidTokenError, IssuerUnavailableError
+from .identity import Identity
+from .keys import KeyCache
+
+# Pinned, never read from the token header — that is what closes `alg: none` and the HMAC
+# confusion attack, where an RSA public key is presented as an HMAC secret.
+_ALGORITHMS = ["RS256"]
+_REQUIRED_CLAIMS = ["exp", "iat", "iss", "aud", "sub", "jti"]
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+# Clock skew beyond a few minutes is a broken clock, not skew — and against tokens that live for
+# fifteen, a larger allowance would quietly extend every one of them.
+_MAX_LEEWAY_SECONDS = 300
+# PyJWT before 2.15 lets a deeply nested header escape json.loads as a RecursionError. Any caller can
+# send one, so it has to be a 401 rather than a 500 whatever PyJWT version is installed.
+_PARSE_ERRORS = (jwt.PyJWTError, RecursionError)
+
+
+class AuthGate:
+    """Verifies tokens issued by one AuthGate server for one audience.
+
+    Construction does no I/O. The issuer's discovery document and keys are fetched on first use and
+    cached, so verifying a token is normally a signature check and nothing else.
+    """
+
+    def __init__(self, issuer: str, audience: str, *, leeway: float = 60) -> None:
+        if not isinstance(issuer, str) or not issuer.strip():
+            raise ConfigurationError("issuer must be set")
+        if not isinstance(audience, str) or not audience.strip():
+            raise ConfigurationError(
+                "audience must be set, as one string — without it this service would accept any token the issuer "
+                "ever minted, including tokens meant for other services"
+            )
+        issuer = issuer.strip().rstrip("/")
+        audience = audience.strip()
+        try:
+            url = urlsplit(issuer)
+            _ = url.port  # raises ValueError for a port that is not a number in range
+        except ValueError as exc:
+            raise ConfigurationError(f"issuer is not a valid URL: {issuer!r}") from exc
+        # Keys fetched over plain HTTP can be swapped in transit. Localhost is exempt because the
+        # server's own development issuer is http://localhost:8080.
+        if url.scheme != "https" and not (url.scheme == "http" and url.hostname in _LOCAL_HOSTS):
+            raise ConfigurationError(f"issuer must be an https URL (plain http only for localhost), got {issuer!r}")
+        # An OIDC issuer is scheme://host[:port][/path]. Anything more would be spliced into the
+        # discovery URL, and fail as a permanent outage rather than here, at startup.
+        if (
+            not url.hostname
+            or "@" in url.netloc
+            or "?" in issuer
+            or "#" in issuer
+            or any(c.isspace() or not c.isprintable() for c in issuer)
+        ):
+            raise ConfigurationError(f"issuer must be scheme://host[:port][/path], got {issuer!r}")
+        # NaN or infinity would switch expiry checking off entirely; a string would fail every request.
+        if isinstance(leeway, bool) or not isinstance(leeway, (int, float)) or not 0 <= leeway <= _MAX_LEEWAY_SECONDS:
+            raise ConfigurationError(f"leeway must be between 0 and {_MAX_LEEWAY_SECONDS} seconds, got {leeway!r}")
+
+        self._issuer = issuer
+        self._audience = audience
+        self._leeway = leeway
+        self._keys = KeyCache(issuer)
+
+    @property
+    def issuer(self) -> str:
+        """The issuer as configured, trailing slash dropped.
+
+        Tokens must carry the discovery document's `issuer` exactly, which is normally this same
+        value. Read-only: the key cache is bound to it at construction.
+        """
+        return self._issuer
+
+    @property
+    def audience(self) -> str:
+        """The `aud` value tokens must name. Read-only, like the issuer."""
+        return self._audience
+
+    def verify(self, token: str) -> Identity:
+        """Verify `token` and return the caller it describes.
+
+        Raises InvalidTokenError for anything wrong with the token, and IssuerUnavailableError when
+        the issuer's keys cannot be fetched — including when the key a token names could not be
+        looked up because the issuer is unreachable. Raises ConfigurationError if, on first use, the
+        issuer's discovery document turns out to name a different issuer.
+        """
+        try:
+            header = jwt.get_unverified_header(token)
+        except _PARSE_ERRORS as exc:
+            raise InvalidTokenError(f"malformed token: {exc}") from exc
+        # Checked before any key lookup, so a token that can never verify costs the issuer nothing and
+        # is refused as invalid even while the issuer is down. jwt.decode enforces it again.
+        if header.get("alg") not in _ALGORITHMS:
+            raise InvalidTokenError(f"token alg {header.get('alg')!r} is not allowed, expected RS256")
+        kid = header.get("kid")
+        if not isinstance(kid, str):
+            raise InvalidTokenError("token has no kid header")
+
+        key = self._keys.get(kid)
+        if key is None:
+            raise InvalidTokenError(f"token is signed with an unknown key {kid!r}")
+        issuer = self._keys.issuer
+        if issuer is None:  # fail closed: PyJWT skips the iss check entirely when given no issuer
+            raise IssuerUnavailableError("the issuer's discovery document has not been read")
+
+        try:
+            claims = jwt.decode(
+                token,
+                key=key,
+                algorithms=_ALGORITHMS,
+                audience=self.audience,
+                issuer=issuer,
+                leeway=self._leeway,
+                options={"require": _REQUIRED_CLAIMS},
+            )
+        except jwt.InvalidAudienceError as exc:
+            raise InvalidTokenError(f"token is not intended for this service (expected aud {self.audience!r})") from exc
+        except _PARSE_ERRORS as exc:
+            raise InvalidTokenError(str(exc)) from exc
+        return Identity.from_claims(claims)
+
+    @cached_property
+    def identity(self) -> Callable[..., Identity]:
+        """FastAPI dependency resolving to the verified caller: `Depends(auth.identity)`.
+
+        Cached, so every route sees the same dependency object and FastAPI verifies once per
+        request even when `require()` is stacked on top of it.
+        """
+        return _integration().identity_dependency(self)
+
+    def require(self, resource: str, action: str) -> Callable[..., Identity]:
+        """FastAPI dependency that also demands a permission: `Depends(auth.require("material", "update"))`."""
+        return _integration().require_dependency(self, resource, action)
+
+
+def _integration():
+    try:
+        from . import fastapi
+    except ModuleNotFoundError as exc:
+        if exc.name != "fastapi":
+            raise
+        raise ModuleNotFoundError(
+            'the FastAPI integration needs the extra: pip install "authgate-client[fastapi]"', name="fastapi"
+        ) from exc
+    return fastapi

authgate_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: authgate-client
+Version: 0.1.0
+Summary: Verify AuthGate access tokens in Python, with an optional FastAPI integration.
+Project-URL: Homepage, https://github.com/boskodjokic/authgate-python
+Project-URL: Issues, https://github.com/boskodjokic/authgate-python/issues
+Project-URL: Changelog, https://github.com/boskodjokic/authgate-python/blob/main/CHANGELOG.md
+Project-URL: Server, https://github.com/boskodjokic/authgate
+Author: Bosko Djokic
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,authgate,fastapi,jwks,jwt,oidc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyjwt[crypto]>=2.13
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx2>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# authgate-client
+
+[![CI](https://github.com/boskodjokic/authgate-python/actions/workflows/ci.yml/badge.svg)](https://github.com/boskodjokic/authgate-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/authgate-client)](https://pypi.org/project/authgate-client/)
+[![Python](https://img.shields.io/pypi/pyversions/authgate-client)](https://pypi.org/project/authgate-client/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/boskodjokic/authgate-python/blob/main/LICENSE)
+
+Verify [AuthGate](https://github.com/boskodjokic/authgate) access tokens in Python. Framework-free,
+with one dependency — PyJWT and its `crypto` extra — and an optional FastAPI integration. Installed
+as `authgate-client`, imported as `authgate`.
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+
+from authgate import AuthGate, Identity
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+app = FastAPI()
+
+
+@app.get("/materials")
+def list_materials(caller: Annotated[Identity, Depends(auth.identity)]):
+    return materials.for_tenant(caller.tenant_id)
+
+
+@app.delete("/materials/{material_id}")
+def delete_material(material_id: str, caller: Annotated[Identity, Depends(auth.require("material", "delete"))]):
+    materials.delete(material_id, by=caller.account_id)
+```
+
+```bash
+pip install authgate-client              # the verifier
+pip install "authgate-client[fastapi]"   # plus the FastAPI dependencies
+```
+
+## You may not need this
+
+AuthGate publishes a standard `/.well-known/openid-configuration` and JWKS, so any JWT library that
+can fetch a JWKS already verifies its tokens. This package is a convenience, the Python counterpart
+of the server's Spring starter. What it adds is what a hand-written verifier usually gets wrong:
+
+- **The audience is required.** A verifier that skips `aud` accepts every token the issuer ever
+  minted, including tokens meant for a different service. There is no default for "any".
+- **A typed caller.** The `perms` claim arrives as `Identity.permissions`, and
+  `caller.may("material", "update")` applies the server's own rule, superuser included.
+- **Key refresh that cannot be turned against the issuer.** Tokens naming an unknown `kid` trigger
+  at most one JWKS fetch every 30 seconds, however many arrive.
+- **An outage is not a bad token.** If the issuer cannot be reached, the answer is 503, not 401 —
+  a 401 tells well-behaved clients to throw their token away and sign the user out.
+
+## Without FastAPI
+
+`verify` is plain synchronous code, so it works in Flask, Django, a worker or a script:
+
+```python
+from authgate import AuthGate, InvalidTokenError, IssuerUnavailableError
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+
+try:
+    caller = auth.verify(token)
+except InvalidTokenError:
+    ...  # 401
+except IssuerUnavailableError:
+    ...  # 503
+
+if not caller.may("material", "update"):
+    ...  # 403
+```
+
+It is also why the FastAPI dependencies are plain `def`s: FastAPI runs them in its threadpool, so
+the occasional key fetch never blocks the event loop. With the keys cached, verifying a token is
+normally a signature check and nothing else.
+
+## Testing an app that uses it
+
+Override `auth.identity` to stand in a caller. Every `require()` builds on it, so the permission
+checks still run against the identity you supply:
+
+```python
+app.dependency_overrides[auth.identity] = lambda: Identity("acct-1", permissions={"material": frozenset({"read"})})
+```
+
+The dependencies are for HTTP routes, since they read the `Authorization` header. Use them with
+`Depends`, not `Security(..., scopes=...)`: scopes make FastAPI treat each use as a separate
+dependency, and the token would be verified once per use instead of once per request.
+
+## What is checked
+
+| Check | Rule |
+|---|---|
+| Signature | RS256 only. The algorithm is pinned, never read from the token header, which closes `alg: none` and the RSA-key-as-HMAC-secret confusion. It is checked before any key lookup, so such a token is refused as invalid even while the issuer is down |
+| Key | the `kid` header must name an RS256 signing key the issuer publishes. If the issuer cannot be reached to look one up, the answer is 503, not 401 |
+| Issuer | `iss` must equal the discovery document's `issuer` exactly, and that document must name the issuer you configured |
+| Audience | `aud` must contain the audience you configured |
+| Lifetime | `exp` and `iat` required, `nbf` honoured if present, with 60 seconds of clock skew allowed (`leeway=`, up to 300). An `iat` further in the future than that is rejected — stricter than Spring, which checks only `exp` and `nbf` |
+| Required claims | `exp`, `iat`, `iss`, `aud`, `sub`, `jti` |
+| Transport | the issuer must be `https://host[:port][/path]`; plain `http://` is accepted only for `localhost`, `127.0.0.1` and `::1` |
+
+Keys are fetched on first use — constructing an `AuthGate` does no I/O — and cached for five
+minutes. A failed refresh keeps serving the cached keys rather than failing every request — until
+a refresh succeeds, however long that takes, so a key the issuer withdraws during an outage is
+trusted until the verifier can see that it is gone.
+
+## The caller
+
+| `Identity` field | Claim | |
+|---|---|---|
+| `account_id` | `sub` | AuthGate's account id, not the external provider's subject |
+| `tenant_id` | `tenant` | |
+| `email` | `email` | for display and audit |
+| `superuser` | `superuser` | `True` only for a literal JSON `true` |
+| `permissions` | `perms` | `{resource: frozenset(actions)}` |
+| `claims` | all of them | the verified payload; not part of equality, so two tokens for one caller compare equal |
+
+## Errors
+
+| Raised | Meaning | FastAPI response |
+|---|---|---|
+| — | no `Authorization: Bearer` header at all | 401, `WWW-Authenticate: Bearer` |
+| `InvalidTokenError` | the token is not acceptable here | 401, `WWW-Authenticate: Bearer error="invalid_token"` |
+| `IssuerUnavailableError` | the issuer's keys cannot be fetched | 503, with a fixed message; the detail is logged |
+| `ConfigurationError` | the verifier is set up wrong, or the issuer's discovery document contradicts it | raised at construction; 500 if discovered later |
+| — | a missing permission in `require()` | 403, `WWW-Authenticate: Bearer error="insufficient_scope"` |
+
+All three exceptions derive from `AuthGateError`.
+
+The public API is what `authgate` exports — `AuthGate`, `Identity` and the errors above. The
+submodules are implementation, and may change between releases.
+
+## Revocation
+
+AuthGate revokes an access token by adding its `jti` to a denylist on the server. A verifier
+working from the published keys cannot see that list, so a token that was already issued stays
+valid here until it expires. The server's short access-token lifetime — 15 minutes by default — is
+what bounds that window, and revocation is enforced where a new token would be issued. Every
+JWT-issuing provider behaves this way.
+
+## Development
+
+```bash
+pip install -e ".[dev]" "ruff==0.16.9"   # the ruff CI pins
+pytest
+ruff check . && ruff format --check .
+```
+
+The tests run against an in-process fake issuer: a real RSA key, a real JWKS served over real HTTP
+on `127.0.0.1`, and tokens carrying exactly the claims the server issues. That is what makes each
+attack — `alg: none`, HMAC confusion, a foreign key reusing a known `kid`, a tampered payload — a
+short test with no external network.
+
+## License
+
+MIT — see [LICENSE](https://github.com/boskodjokic/authgate-python/blob/main/LICENSE).

authgate_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+authgate/__init__.py,sha256=iZ-msjDlouABngQ1mr7qw_r0Ulu01_o_YuqxiQ9A3Nc,582
+authgate/errors.py,sha256=Evst77iYG9YGFQxYOkNr5rbxZws7yWTBUz0Dgve9tHM,795
+authgate/fastapi.py,sha256=NDnFWSiMkBl7Z2ZShUrt3NzGzQgGE8Eh3KKvbRF7S70,3109
+authgate/identity.py,sha256=a16PvbbEtCbtBcfvZeEdnKWklITHfvyQO18jkrtS3bc,2495
+authgate/keys.py,sha256=8lt-bNTRjJE1a0mmActlP_yELxg7eqhYAah5i7BIilk,7186
+authgate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authgate/verifier.py,sha256=2tx5CkLyRWCDlky5OeHxjt9WBZGf8uhE3_2U95xZOzc,7150
+authgate_client-0.1.0.dist-info/METADATA,sha256=O9lOyL81IpdyyM8tGzW_gZ2GyeoGZIqTKZa3itihTYk,8939
+authgate_client-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+authgate_client-0.1.0.dist-info/licenses/LICENSE,sha256=bIQgMfVLAHq7LdY5FIYUi1I5XlO77i01JnXhYq5esso,1069
+authgate_client-0.1.0.dist-info/RECORD,,

authgate_client-0.1.0.dist-info/WHEEL

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

authgate_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bosko Djokic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.