grantor 0.1.0__tar.gz

grantor-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.tox/
+.env
+.DS_Store
+uv.lock.bak
+.venv*/
+node_modules/

grantor-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: grantor
+Version: 0.1.0
+Summary: The protocol core of the Grantor OAuth 2.1 / OpenID Connect client — framework-free.
+Project-URL: Homepage, https://grantor.id
+Project-URL: Documentation, https://docs.grantor.id
+Project-URL: Source, https://github.com/Grantor-id/grantor-python
+Project-URL: Issues, https://github.com/Grantor-id/grantor-python/issues
+Author: Allure Labs
+License-Expression: MIT
+Keywords: authentication,grantor,oauth2,oidc,openid-connect,pkce
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Security
+Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.9
+Description-Content-Type: text/markdown
+
+# `grantor`
+
+The protocol core of the Python client for [Grantor](https://grantor.id), an
+OAuth 2.1 / OpenID Connect provider. Discovery, PKCE, code exchange, JWKS
+verification, userinfo, RP-initiated logout and error normalization — sync
+and async, on `httpx`.
+
+**No framework, no Django.** If you are writing a Django application you
+want [`grantor-django`](https://pypi.org/project/grantor-django/) instead;
+it depends on this package. If you are writing an adapter for another
+framework, depend on this one alone: every pure step is public API, not a
+private helper, precisely so you can compose them.
+
+```sh
+pip install grantor
+```
+
+Documentation: [docs.grantor.id](https://docs.grantor.id).
+Source and security policy: [Grantor-id/grantor-python](https://github.com/Grantor-id/grantor-python).
+
+MIT. © Allure Labs.

grantor-0.1.0/README.md

@@ -0,0 +1,21 @@
+# `grantor`
+
+The protocol core of the Python client for [Grantor](https://grantor.id), an
+OAuth 2.1 / OpenID Connect provider. Discovery, PKCE, code exchange, JWKS
+verification, userinfo, RP-initiated logout and error normalization — sync
+and async, on `httpx`.
+
+**No framework, no Django.** If you are writing a Django application you
+want [`grantor-django`](https://pypi.org/project/grantor-django/) instead;
+it depends on this package. If you are writing an adapter for another
+framework, depend on this one alone: every pure step is public API, not a
+private helper, precisely so you can compose them.
+
+```sh
+pip install grantor
+```
+
+Documentation: [docs.grantor.id](https://docs.grantor.id).
+Source and security policy: [Grantor-id/grantor-python](https://github.com/Grantor-id/grantor-python).
+
+MIT. © Allure Labs.

grantor-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "grantor"
+version = "0.1.0"
+description = "The protocol core of the Grantor OAuth 2.1 / OpenID Connect client — framework-free."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Allure Labs" }]
+keywords = ["oauth2", "oidc", "openid-connect", "pkce", "authentication", "grantor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: System :: Systems Administration :: Authentication/Directory",
+    "Typing :: Typed",
+]
+dependencies = [
+    # httpx rather than requests, deliberately: the core has a sync and an
+    # async path so that a future `grantor-fastapi` composes these functions
+    # instead of blocking the event loop or reimplementing them.
+    "httpx>=0.27",
+    # PyJWT with cryptography for signature verification. JWKS is fetched
+    # through httpx rather than PyJWKClient's own urllib transport, so the
+    # async path and the sync path share one HTTP story.
+    "pyjwt[crypto]>=2.9",
+]
+
+[project.urls]
+Homepage = "https://grantor.id"
+Documentation = "https://docs.grantor.id"
+Source = "https://github.com/Grantor-id/grantor-python"
+Issues = "https://github.com/Grantor-id/grantor-python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/grantor"]

grantor-0.1.0/src/grantor/__init__.py

@@ -0,0 +1,172 @@
+"""The protocol core of the Grantor client — no framework, no Django.
+
+**Every pure step of the flow is public API here, not a private helper.**
+``build_authorization_url``, ``verify_id_token``, ``parse_error``,
+``exchange_code_request`` and the rest are importable and documented, and
+:class:`GrantorClient` is a thin shell over them. That is the condition that
+makes the split between this package and ``grantor-django`` worth having:
+an adapter for a framework this package has never heard of composes these
+instead of copying them. A core whose useful parts are all private is a core
+that gets copy-pasted.
+
+The rule the whole library is held to, and the reason it can exist beside a
+promise that there is no proprietary SDK:
+
+    The library may never require anything of the issuer that a stock OIDC
+    library could not do. If a feature needs a change on the issuer side to
+    work, that change must be an RFC, or the feature is wrong.
+
+One string is configured — the issuer. Every endpoint is read from its
+discovery document.
+
+    >>> from grantor import GrantorClient
+    >>> client = GrantorClient(
+    ...     "https://acme.api.grantor.id",
+    ...     client_id="...",
+    ...     client_secret="...",
+    ...     redirect_uri="https://app.example.com/auth/callback",
+    ... )
+    >>> request = client.start_authorization()   # doctest: +SKIP
+    >>> # send the browser to request.url; keep state, nonce and code_verifier
+"""
+
+from __future__ import annotations
+
+from ._discovery import (
+    DISCOVERY_TTL_SECONDS,
+    HTTP_TIMEOUT_SECONDS,
+    DiscoveryDocument,
+    async_discover,
+    clear_discovery_cache,
+    discover,
+    discovery_url,
+    parse_discovery_document,
+)
+from ._errors import (
+    DiscoveryError,
+    GrantorError,
+    ProtocolError,
+    TokenError,
+    normalize_error,
+    parse_error,
+    parse_redirect_error,
+)
+from ._pkce import (
+    CODE_CHALLENGE_METHOD,
+    PkcePair,
+    challenge_for,
+    generate_nonce,
+    generate_pkce,
+    generate_state,
+    generate_verifier,
+)
+from ._requests import (
+    ClientAuth,
+    TokenRequest,
+    append_query,
+    build_authorization_url,
+    build_end_session_url,
+    client_secret_basic,
+    client_secret_post,
+    exchange_code_request,
+    public_client,
+    refresh_token_request,
+    revocation_request,
+    userinfo_request,
+)
+from ._tokens import (
+    ACCESS_TOKEN_REQUIRED_CLAIMS,
+    ID_TOKEN_REQUIRED_CLAIMS,
+    LEEWAY_SECONDS,
+    JwksCache,
+    async_fetch_jwks,
+    async_verify_access_token,
+    async_verify_id_token,
+    check_nonce,
+    clear_jwks_cache,
+    decode_and_verify,
+    fetch_jwks,
+    verify_access_token,
+    verify_id_token,
+)
+from .client import (
+    DEFAULT_SCOPE,
+    AsyncGrantorClient,
+    AuthorizationRequest,
+    GrantorClient,
+    TokenResponse,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Clients — thin shells over everything below them.
+    "GrantorClient",
+    "AsyncGrantorClient",
+    "AuthorizationRequest",
+    "TokenResponse",
+    "DEFAULT_SCOPE",
+    # Discovery.
+    "DiscoveryDocument",
+    "discover",
+    "async_discover",
+    "discovery_url",
+    "parse_discovery_document",
+    "clear_discovery_cache",
+    "DISCOVERY_TTL_SECONDS",
+    "HTTP_TIMEOUT_SECONDS",
+    # PKCE and the round-trip secrets.
+    "PkcePair",
+    "generate_pkce",
+    "generate_verifier",
+    "challenge_for",
+    "generate_state",
+    "generate_nonce",
+    "CODE_CHALLENGE_METHOD",
+    # Request shaping — pure, and public for exactly that reason.
+    "build_authorization_url",
+    "exchange_code_request",
+    "refresh_token_request",
+    "userinfo_request",
+    "revocation_request",
+    "build_end_session_url",
+    "append_query",
+    "ClientAuth",
+    "TokenRequest",
+    "client_secret_basic",
+    "client_secret_post",
+    "public_client",
+    # Verification.
+    "verify_id_token",
+    "async_verify_id_token",
+    "verify_access_token",
+    "async_verify_access_token",
+    "decode_and_verify",
+    "check_nonce",
+    "JwksCache",
+    "fetch_jwks",
+    "async_fetch_jwks",
+    "clear_jwks_cache",
+    "LEEWAY_SECONDS",
+    "ID_TOKEN_REQUIRED_CLAIMS",
+    "ACCESS_TOKEN_REQUIRED_CLAIMS",
+    # Errors, and the two envelopes they arrive in.
+    "GrantorError",
+    "DiscoveryError",
+    "ProtocolError",
+    "TokenError",
+    "parse_error",
+    "normalize_error",
+    "parse_redirect_error",
+]
+
+
+def clear_caches() -> None:
+    """Drop the discovery and JWKS caches.
+
+    Both are process state with a TTL, which is right in production and
+    wrong in a test that has just changed what the issuer says.
+    """
+    clear_discovery_cache()
+    clear_jwks_cache()

grantor-0.1.0/src/grantor/_discovery.py

@@ -0,0 +1,276 @@
+"""The issuer's discovery document, and the one check that matters about it.
+
+One string is configured — the issuer. Every endpoint is read from here.
+That is not tidiness: transcribing endpoints into configuration is how a
+configuration goes stale while still looking correct, and the guide this
+library follows records a week in which its own endpoint table named a
+domain the product had already left.
+
+The I/O and the parsing are separate on purpose. ``parse_discovery_document``
+is pure, so the issuer-mismatch refusal — the security-relevant half — is
+tested without a socket anywhere near it.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ._errors import DiscoveryError
+
+__all__ = [
+    "DiscoveryDocument",
+    "discovery_url",
+    "parse_discovery_document",
+    "discover",
+    "async_discover",
+    "clear_discovery_cache",
+    "DISCOVERY_TTL_SECONDS",
+    "HTTP_TIMEOUT_SECONDS",
+]
+
+DISCOVERY_PATH = "/.well-known/openid-configuration"
+DISCOVERY_TTL_SECONDS = 3600.0
+HTTP_TIMEOUT_SECONDS = 15.0
+
+# Endpoints without which no flow can start. ``userinfo_endpoint`` and
+# ``end_session_endpoint`` are deliberately not here: an issuer may omit
+# them and the flows that need them fail on their own terms, with a message
+# naming what was missing, rather than making discovery itself unusable.
+_REQUIRED = ("authorization_endpoint", "token_endpoint", "jwks_uri")
+
+# The algorithms a signature may be verified with. Intersected with whatever
+# discovery advertises rather than trusted from it.
+#
+# All asymmetric. If a symmetric algorithm ever reached this list, a
+# verifier handed a public key would use it as an HMAC secret — the
+# algorithm-confusion attack, and the public key is published in the JWKS
+# for anyone to fetch. Neither implementation this package was extracted
+# from pinned this; both passed the advertised list straight through.
+_SAFE_ALGORITHMS = frozenset(
+    {
+        "RS256",
+        "RS384",
+        "RS512",
+        "PS256",
+        "PS384",
+        "PS512",
+        "ES256",
+        "ES384",
+        "ES512",
+        "EdDSA",
+    }
+)
+
+_DEFAULT_ALGORITHMS = ("RS256",)
+
+
+@dataclass(frozen=True)
+class DiscoveryDocument:
+    """A validated ``openid-configuration``.
+
+    The raw document stays reachable through :meth:`get` — this issuer emits
+    ``claims_supported``, ``scopes_supported`` and more that a caller may
+    legitimately want, and a dataclass that hid them would send people back
+    to fetching the URL themselves.
+    """
+
+    issuer: str
+    claims: Mapping[str, Any]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.claims.get(key, default)
+
+    def require(self, key: str) -> str:
+        """An endpoint, or a refusal naming the one that is absent."""
+        value = self.claims.get(key)
+        if not isinstance(value, str) or not value:
+            raise DiscoveryError(f"discovery document lacks {key}")
+        return value
+
+    @property
+    def authorization_endpoint(self) -> str:
+        return self.require("authorization_endpoint")
+
+    @property
+    def token_endpoint(self) -> str:
+        return self.require("token_endpoint")
+
+    @property
+    def jwks_uri(self) -> str:
+        return self.require("jwks_uri")
+
+    @property
+    def userinfo_endpoint(self) -> str | None:
+        value = self.claims.get("userinfo_endpoint")
+        return value if isinstance(value, str) and value else None
+
+    @property
+    def end_session_endpoint(self) -> str | None:
+        value = self.claims.get("end_session_endpoint")
+        return value if isinstance(value, str) and value else None
+
+    @property
+    def revocation_endpoint(self) -> str | None:
+        value = self.claims.get("revocation_endpoint")
+        return value if isinstance(value, str) and value else None
+
+    @property
+    def signing_algorithms(self) -> tuple[str, ...]:
+        """The algorithms a token from this issuer may be verified with.
+
+        The advertised list, intersected with the asymmetric allowlist. An
+        issuer that advertises nothing usable leaves ``RS256``, which is
+        what every conforming OIDC provider signs with; an issuer that
+        advertises only unsafe algorithms gets the same answer, and the
+        signature check then fails honestly rather than succeeding against
+        a key used for the wrong purpose.
+        """
+        advertised = self.claims.get("id_token_signing_alg_values_supported")
+        if not isinstance(advertised, (list, tuple)):
+            return _DEFAULT_ALGORITHMS
+        safe = tuple(a for a in advertised if isinstance(a, str) and a in _SAFE_ALGORITHMS)
+        return safe or _DEFAULT_ALGORITHMS
+
+
+def discovery_url(issuer: str) -> str:
+    """Where the document lives. Pure, and the only URL this library builds."""
+    return f"{issuer.rstrip('/')}{DISCOVERY_PATH}"
+
+
+def parse_discovery_document(payload: Any, *, issuer: str) -> DiscoveryDocument:
+    """Validate a discovery payload against the issuer it was fetched for.
+
+    **The ``issuer`` claim must equal the configured issuer.** A document
+    naming a different one means the wrong server answered, or something
+    answered for it. Either way it is a refusal, not a warning — every
+    endpoint below is about to be taken from this document, so a document
+    that lies about who it belongs to redirects a sign-in wherever it likes.
+    """
+    if not isinstance(payload, Mapping):
+        raise DiscoveryError("discovery document is not a JSON object")
+
+    expected = issuer.rstrip("/")
+    named = payload.get("issuer")
+    if not isinstance(named, str) or named.rstrip("/") != expected:
+        raise DiscoveryError("discovery document names a different issuer")
+
+    for key in _REQUIRED:
+        value = payload.get(key)
+        if not isinstance(value, str) or not value:
+            raise DiscoveryError(f"discovery document lacks {key}")
+
+    return DiscoveryDocument(issuer=expected, claims=dict(payload))
+
+
+class _Cache:
+    """Discovery documents by issuer, with a TTL.
+
+    Keyed by issuer rather than held as a single slot, because a process may
+    legitimately face two — a per-organization issuer for sign-in and the
+    platform one for something else — and a single slot would have them
+    evict each other on every call.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._entries: dict[str, tuple[DiscoveryDocument, float]] = {}
+
+    def get(self, issuer: str) -> DiscoveryDocument | None:
+        with self._lock:
+            entry = self._entries.get(issuer)
+        if entry is None:
+            return None
+        document, expires_at = entry
+        return document if time.monotonic() < expires_at else None
+
+    def put(self, issuer: str, document: DiscoveryDocument, ttl: float) -> None:
+        with self._lock:
+            self._entries[issuer] = (document, time.monotonic() + ttl)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+
+
+_cache = _Cache()
+
+
+def clear_discovery_cache() -> None:
+    """Drop every cached document. The test hook, and the operational one."""
+    _cache.clear()
+
+
+def _document_from_response(response: httpx.Response, *, issuer: str) -> DiscoveryDocument:
+    if response.status_code != 200:
+        raise DiscoveryError(f"discovery answered {response.status_code}")
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise DiscoveryError("discovery did not return JSON") from exc
+    return parse_discovery_document(payload, issuer=issuer)
+
+
+def discover(
+    issuer: str,
+    *,
+    client: httpx.Client | None = None,
+    ttl: float = DISCOVERY_TTL_SECONDS,
+    timeout: float = HTTP_TIMEOUT_SECONDS,
+    force: bool = False,
+) -> DiscoveryDocument:
+    """Fetch (or reuse) the issuer's discovery document."""
+    key = issuer.rstrip("/")
+    if not force:
+        cached = _cache.get(key)
+        if cached is not None:
+            return cached
+
+    url = discovery_url(key)
+    try:
+        if client is not None:
+            response = client.get(url, timeout=timeout)
+        else:
+            with httpx.Client(timeout=timeout, follow_redirects=True) as owned:
+                response = owned.get(url)
+    except httpx.HTTPError as exc:
+        raise DiscoveryError(f"discovery request failed: {type(exc).__name__}") from exc
+
+    document = _document_from_response(response, issuer=key)
+    _cache.put(key, document, ttl)
+    return document
+
+
+async def async_discover(
+    issuer: str,
+    *,
+    client: httpx.AsyncClient | None = None,
+    ttl: float = DISCOVERY_TTL_SECONDS,
+    timeout: float = HTTP_TIMEOUT_SECONDS,
+    force: bool = False,
+) -> DiscoveryDocument:
+    """:func:`discover`, without blocking the event loop."""
+    key = issuer.rstrip("/")
+    if not force:
+        cached = _cache.get(key)
+        if cached is not None:
+            return cached
+
+    url = discovery_url(key)
+    try:
+        if client is not None:
+            response = await client.get(url, timeout=timeout)
+        else:
+            async with httpx.AsyncClient(timeout=timeout, follow_redirects=True) as owned:
+                response = await owned.get(url)
+    except httpx.HTTPError as exc:
+        raise DiscoveryError(f"discovery request failed: {type(exc).__name__}") from exc
+
+    document = _document_from_response(response, issuer=key)
+    _cache.put(key, document, ttl)
+    return document