eager-auth 2.0.0__py3-none-any.whl

eager_auth/__init__.py

@@ -0,0 +1,115 @@
+"""eager-auth — standard OIDC relying party for Eager FastAPI services.
+
+The public surface of the verification core. The authorization-code flow, the session
+cookie and the FastAPI glue build on top of this and do not change it.
+
+See CONTRACT.md at the repository root.
+"""
+
+from eager_auth.claims import claim_at, extract_org, extract_roles
+from eager_auth.config import (
+    ALLOWED_ALGORITHMS,
+    DEFAULT_ORG_CLAIM,
+    DEFAULT_ROLES_CLAIM,
+    DEFAULT_SESSION_TTL_SECONDS,
+    AuthConfig,
+)
+from eager_auth.context import AuthContext
+from eager_auth.discovery import Discovery, fetch_discovery
+from eager_auth.errors import (
+    AuthError,
+    BadSignatureError,
+    ConfigError,
+    DiscoveryError,
+    ExpiredTokenError,
+    InvalidSessionError,
+    InvalidTokenError,
+    MalformedTokenError,
+    NonceMismatchError,
+    RefreshRejectedError,
+    StateMismatchError,
+    TokenExchangeError,
+    UnknownKeyError,
+    UnsupportedAlgorithmError,
+    WrongAudienceError,
+    WrongIssuerError,
+)
+from eager_auth.flow import (
+    CompletedLogin,
+    PendingLogin,
+    code_challenge_for,
+    complete_login,
+    logout_url,
+    refresh_session,
+    start_login,
+)
+from eager_auth.keys import HttpJwksSource, JwksSource, KeyResolver
+from eager_auth.pending import PendingState, safe_next, seal_pending, unseal_pending
+from eager_auth.presets import KEYCLOAK_REALM_ROLES, ZITADEL, keycloak_client_roles
+from eager_auth.principal import Principal
+from eager_auth.session import (
+    CookieAttributes,
+    SessionPayload,
+    decode_session,
+    encode_session,
+    needs_refresh,
+    pending_cookie,
+    session_cookie,
+)
+from eager_auth.tokens import verify_id_token
+
+__all__ = [
+    "ALLOWED_ALGORITHMS",
+    "AuthConfig",
+    "AuthContext",
+    "AuthError",
+    "BadSignatureError",
+    "CompletedLogin",
+    "ConfigError",
+    "CookieAttributes",
+    "DEFAULT_ORG_CLAIM",
+    "DEFAULT_ROLES_CLAIM",
+    "DEFAULT_SESSION_TTL_SECONDS",
+    "Discovery",
+    "DiscoveryError",
+    "ExpiredTokenError",
+    "HttpJwksSource",
+    "InvalidSessionError",
+    "InvalidTokenError",
+    "JwksSource",
+    "KEYCLOAK_REALM_ROLES",
+    "KeyResolver",
+    "MalformedTokenError",
+    "NonceMismatchError",
+    "PendingLogin",
+    "PendingState",
+    "Principal",
+    "RefreshRejectedError",
+    "SessionPayload",
+    "StateMismatchError",
+    "TokenExchangeError",
+    "UnknownKeyError",
+    "UnsupportedAlgorithmError",
+    "WrongAudienceError",
+    "WrongIssuerError",
+    "ZITADEL",
+    "claim_at",
+    "code_challenge_for",
+    "complete_login",
+    "decode_session",
+    "encode_session",
+    "extract_org",
+    "extract_roles",
+    "fetch_discovery",
+    "keycloak_client_roles",
+    "logout_url",
+    "needs_refresh",
+    "pending_cookie",
+    "refresh_session",
+    "safe_next",
+    "seal_pending",
+    "session_cookie",
+    "start_login",
+    "unseal_pending",
+    "verify_id_token",
+]

eager_auth/claims.py

@@ -0,0 +1,78 @@
+"""Reading claims out of a token — see CONTRACT.md section 3.
+
+Brokers disagree about where authorization data lives, and the disagreement is structural,
+not cosmetic:
+
+* **Zitadel** puts a flat claim holding an object map keyed by role name.
+* **Keycloak** nests roles at `realm_access.roles` (realm roles) or
+  `resource_access.<client>.roles` (client roles), and its Organizations feature emits an
+  `organization` claim keyed by org alias.
+
+So claim paths are **dotted** and the extractors accept every shape we have actually seen.
+This is the one place the module bends to a provider — by configuration, never by branching
+on which broker is in use.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def claim_at(claims: dict[str, Any], path: str) -> Any:  # noqa: ANN401
+    """Read a claim by dotted path.
+
+    A flat name like `email` works as before. `realm_access.roles` walks into the nested
+    object. Any missing hop, or a hop that is not an object, yields None rather than an
+    error: a token that does not carry the claim is a legitimate token.
+
+    The full path is tried as a literal key first, because Zitadel's claim names contain
+    dots (`urn:zitadel:iam:org:project:roles` does not, but others do) and a literal match
+    must win over a walk.
+    """
+    if path in claims:
+        return claims[path]
+
+    current: Any = claims
+    for hop in path.split("."):
+        if not isinstance(current, dict) or hop not in current:
+            return None
+        current = current[hop]
+    return current
+
+
+def extract_roles(claim_value: Any) -> tuple[str, ...]:  # noqa: ANN401
+    """Normalise a roles claim into a sorted, de-duplicated tuple.
+
+    Accepted shapes: a list of strings (Keycloak), and an object map keyed by role name
+    (Zitadel). Anything else yields an empty tuple rather than an error — a user with no
+    roles is a legitimate state, and it is the service's job to decide what to do about it.
+    """
+    if isinstance(claim_value, dict):
+        names = [str(name) for name in claim_value]
+    elif isinstance(claim_value, (list, tuple, set)):
+        names = [str(name) for name in claim_value if isinstance(name, str)]
+    else:
+        return ()
+    return tuple(sorted({name for name in names if name}))
+
+
+def extract_org(claim_value: Any) -> str | None:  # noqa: ANN401
+    """Normalise an org claim into a single identifier.
+
+    Accepted shapes: a string (Zitadel's primary domain), a one-element list, and an object
+    map keyed by org alias (Keycloak Organizations). When a map or list carries more than
+    one entry the first sorted key wins, deterministically — a principal belonging to
+    several orgs is out of scope for this contract, and picking at random would be worse
+    than picking predictably.
+    """
+    if isinstance(claim_value, str):
+        return claim_value or None
+    if isinstance(claim_value, dict):
+        names = sorted(str(name) for name in claim_value if str(name))
+        return names[0] if names else None
+    if isinstance(claim_value, (list, tuple)):
+        names = sorted(str(name) for name in claim_value if isinstance(name, str) and name)
+        return names[0] if names else None
+    if isinstance(claim_value, int) and not isinstance(claim_value, bool):
+        return str(claim_value)
+    return None

eager_auth/config.py

@@ -0,0 +1,159 @@
+"""Configuration — see CONTRACT.md section 2.
+
+The broker's identity lives in exactly one place: `issuer`. Everything else about the
+provider is discovered from `{issuer}/.well-known/openid-configuration`, which is what
+makes swapping brokers a config change instead of a rewrite.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from urllib.parse import urlsplit
+
+from eager_auth.errors import ConfigError
+
+#: Asymmetric only. See CONTRACT.md section 4 step 1.
+ALLOWED_ALGORITHMS: frozenset[str] = frozenset(
+    {"RS256", "RS384", "RS512", "ES256", "ES384", "ES512"}
+)
+
+DEFAULT_ROLES_CLAIM = "urn:zitadel:iam:org:project:roles"
+DEFAULT_ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:primary_domain"
+DEFAULT_SESSION_TTL_SECONDS = 28_800  # 8h — one value for both adapters, on purpose.
+
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+def _is_loopback(url: str) -> bool:
+    """Whether this is a plain-http loopback URL, the one place http is acceptable.
+
+    The host is parsed and compared exactly. A prefix test would accept
+    `http://localhost.evil.test`, which is an attacker-controlled domain that merely starts
+    with the right letters — caught by a test rather than in review.
+    """
+    if not url.startswith("http://"):
+        return False
+    try:
+        host = urlsplit(url).hostname
+    except ValueError:
+        return False
+    return host in _LOOPBACK_HOSTS
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    """Everything a service must state to authenticate its users.
+
+    Args:
+        issuer: Broker base URL, https, no trailing slash.
+        client_id: This service's OIDC client id.
+        client_secret: This service's OIDC client secret.
+        audience: Expected `aud`. Defaults to `client_id`.
+        cookie_name: Session cookie name; shared across the estate.
+        session_ttl_seconds: Session lifetime.
+        route_prefix: Where the login/callback/logout/me routes are mounted.
+        roles_claim: Claim carrying roles. Configurable to keep the broker swappable.
+        org_claim: Claim carrying the org/tenant identifier.
+        redirect_uri: Where the broker sends the user back. Required for the login flow.
+        post_logout_redirect_uri: Absolute URL the broker returns to after a global logout.
+            Must be one the broker has registered. Taken from config rather than from the
+            request host, which behind a load balancer is not the public one.
+        secure_cookies: Force the cookie `Secure` flag. Leave None to derive it from
+            `redirect_uri` — off for http://localhost, on everywhere else.
+        session_key: 32 bytes, base64url, encrypting the session cookie. Required for the flow.
+        scopes: Requested scopes.
+        pending_cookie_name: Cookie holding the in-flight state/nonce/verifier.
+        pending_ttl_seconds: How long a login attempt may take.
+        jwks_max_age_seconds: How long a fetched key set stays usable.
+        clock_skew_seconds: Tolerance applied to `exp`, `nbf` and `iat`.
+
+    Raises:
+        ConfigError: If any value is unusable.
+
+    """
+
+    issuer: str
+    client_id: str
+    client_secret: str
+    audience: str | None = None
+    cookie_name: str = "access_token"
+    session_ttl_seconds: int = DEFAULT_SESSION_TTL_SECONDS
+    route_prefix: str = "/api/auth"
+    roles_claim: str = DEFAULT_ROLES_CLAIM
+    org_claim: str = DEFAULT_ORG_CLAIM
+    redirect_uri: str | None = None
+    post_logout_redirect_uri: str | None = None
+    session_key: str | None = None
+    # None means "derive from redirect_uri": http://localhost is development, where the
+    # browser will not store a Secure cookie, so hardcoding True made local login
+    # impossible while the validator below deliberately allowed a localhost redirect.
+    secure_cookies: bool | None = None
+    scopes: tuple[str, ...] = ("openid", "email", "profile")
+    pending_cookie_name: str = "auth_pending"
+    pending_ttl_seconds: int = 600
+    jwks_max_age_seconds: int = 3_600
+    clock_skew_seconds: int = 60
+    allowed_algorithms: frozenset[str] = field(default=ALLOWED_ALGORITHMS)
+
+    def __post_init__(self) -> None:
+        """Validate eagerly, so a misconfigured service fails at boot, not at first login."""
+        if not self.issuer:
+            raise ConfigError("issuer is required")
+        if not self.issuer.startswith("https://") and not _is_loopback(self.issuer):
+            # http is tolerated only on loopback, which is what a local broker and local development
+            # need. RFC 8252 makes the same carve-out for exactly this reason. Everything else must
+            # be https: an issuer reached over plain http can be substituted in transit, and every
+            # signature check downstream then verifies against the attacker's keys.
+            raise ConfigError(f"issuer must be https, got {self.issuer!r}")
+        if self.issuer.endswith("/"):
+            raise ConfigError(f"issuer must not end with a slash, got {self.issuer!r}")
+        if not self.client_id:
+            raise ConfigError("client_id is required")
+        if not self.client_secret:
+            raise ConfigError("client_secret is required")
+        if self.redirect_uri is not None and not self.redirect_uri.startswith("https://"):
+            if not _is_loopback(self.redirect_uri):
+                raise ConfigError(f"redirect_uri must be https, got {self.redirect_uri!r}")
+        if not self.scopes or "openid" not in self.scopes:
+            raise ConfigError("scopes must include 'openid'")
+        if self.pending_ttl_seconds <= 0:
+            raise ConfigError("pending_ttl_seconds must be positive")
+        if self.pending_cookie_name == self.cookie_name:
+            raise ConfigError("pending_cookie_name must differ from cookie_name")
+        if self.session_ttl_seconds <= 0:
+            raise ConfigError("session_ttl_seconds must be positive")
+        if self.jwks_max_age_seconds <= 0:
+            raise ConfigError("jwks_max_age_seconds must be positive")
+        if self.clock_skew_seconds < 0:
+            raise ConfigError("clock_skew_seconds must not be negative")
+        if not self.allowed_algorithms:
+            raise ConfigError("allowed_algorithms must not be empty")
+        symmetric = {a for a in self.allowed_algorithms if not a.startswith(("RS", "ES", "PS"))}
+        if symmetric:
+            raise ConfigError(f"symmetric algorithms are not allowed: {sorted(symmetric)}")
+
+    @property
+    def cookies_secure(self) -> bool:
+        """Whether cookies carry `Secure`.
+
+        Derived unless set explicitly: a Secure cookie is never stored over plain http, so a
+        localhost redirect_uri and a Secure cookie together mean login silently fails.
+        """
+        if self.secure_cookies is not None:
+            return self.secure_cookies
+        return not _is_loopback(self.redirect_uri or "")
+
+    @property
+    def expected_audience(self) -> str:
+        """The `aud` a token must carry — `audience` when set, otherwise `client_id`."""
+        return self.audience or self.client_id
+
+    @property
+    def scope_string(self) -> str:
+        """Scopes as the authorization request wants them."""
+        return " ".join(self.scopes)
+
+    @property
+    def discovery_url(self) -> str:
+        """Where the provider's metadata lives."""
+        return f"{self.issuer}/.well-known/openid-configuration"

eager_auth/context.py

@@ -0,0 +1,54 @@
+"""Everything a request handler needs, assembled once — see CONTRACT.md section 11.
+
+A service builds one of these at startup and hands it to the router. Discovery is fetched
+lazily and cached, so importing the module never performs I/O and a broker that is briefly
+unreachable at boot does not stop the service from starting.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from eager_auth.config import AuthConfig
+from eager_auth.discovery import Discovery, fetch_discovery
+from eager_auth.keys import HttpJwksSource, KeyResolver
+
+
+class AuthContext:
+    """Config, discovery and the key resolver, resolved on first use."""
+
+    def __init__(
+        self,
+        config: AuthConfig,
+        *,
+        client: httpx.Client | None = None,
+        keys: KeyResolver | None = None,
+        discovery: Discovery | None = None,
+    ) -> None:
+        """Assemble a context.
+
+        Args:
+            config: This service's auth configuration.
+            client: HTTP client for discovery and token calls. One is created if omitted.
+            keys: Key resolver. Built from the config if omitted.
+            discovery: Pre-fetched metadata, for tests or a pinned deployment.
+
+        """
+        self.config = config
+        self.client = client or httpx.Client(timeout=5.0)
+        self.keys = keys or KeyResolver(
+            HttpJwksSource(config, self.client), max_age_seconds=config.jwks_max_age_seconds
+        )
+        self._discovery = discovery
+
+    @property
+    def discovery(self) -> Discovery:
+        """The provider's metadata, fetched once and cached.
+
+        Raises:
+            DiscoveryError: The issuer is unreachable or its document is unusable.
+
+        """
+        if self._discovery is None:
+            self._discovery = fetch_discovery(self.config, self.client)
+        return self._discovery

eager_auth/discovery.py

@@ -0,0 +1,77 @@
+"""The provider's metadata — the single place the broker's shape is learned.
+
+Endpoints are never hand-built from the issuer. That is what keeps the module honest about
+being broker-agnostic: point `issuer` elsewhere and every URL follows.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+from eager_auth.config import AuthConfig
+from eager_auth.errors import DiscoveryError
+
+
+@dataclass(frozen=True)
+class Discovery:
+    """The parts of the discovery document this module uses."""
+
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    jwks_uri: str
+    end_session_endpoint: str | None = None
+
+    @classmethod
+    def from_dict(cls, document: dict, *, expected_issuer: str) -> Discovery:
+        """Validate a metadata document.
+
+        Raises:
+            DiscoveryError: If the issuer disagrees or a required endpoint is missing.
+
+        """
+        issuer = document.get("issuer")
+        if issuer != expected_issuer:
+            # Metadata naming a different issuer than the URL it came from is misconfigured or
+            # spoofed. Either way, refuse to trust its endpoints.
+            raise DiscoveryError(
+                f"discovery issuer {issuer!r} does not match configured {expected_issuer!r}"
+            )
+        missing = [
+            field
+            for field in ("authorization_endpoint", "token_endpoint", "jwks_uri")
+            if not document.get(field)
+        ]
+        if missing:
+            raise DiscoveryError(f"discovery document is missing {', '.join(missing)}")
+        return cls(
+            issuer=str(issuer),
+            authorization_endpoint=str(document["authorization_endpoint"]),
+            token_endpoint=str(document["token_endpoint"]),
+            jwks_uri=str(document["jwks_uri"]),
+            end_session_endpoint=(
+                str(document["end_session_endpoint"])
+                if document.get("end_session_endpoint")
+                else None
+            ),
+        )
+
+
+def fetch_discovery(config: AuthConfig, client: httpx.Client) -> Discovery:
+    """Read `{issuer}/.well-known/openid-configuration`.
+
+    Raises:
+        DiscoveryError: On any transport, parse or validation failure.
+
+    """
+    try:
+        response = client.get(config.discovery_url)
+        response.raise_for_status()
+        document = response.json()
+    except (httpx.HTTPError, ValueError) as exc:
+        raise DiscoveryError(f"cannot read {config.discovery_url}: {exc}") from exc
+    if not isinstance(document, dict):
+        raise DiscoveryError("discovery document is not an object")
+    return Discovery.from_dict(document, expected_issuer=config.issuer)

eager_auth/errors.py

@@ -0,0 +1,92 @@
+"""Typed error hierarchy — see CONTRACT.md section 4.
+
+Callers need to tell "your session expired" from "this token was never meant for us"
+from "the identity provider is down", so every failure mode gets its own class.
+"""
+
+from __future__ import annotations
+
+
+class AuthError(Exception):
+    """Base class for every failure this package raises."""
+
+
+class ConfigError(AuthError):
+    """Configuration is unusable. Raised at construction time, never per-request."""
+
+
+class DiscoveryError(AuthError):
+    """The issuer's discovery document or JWKS could not be fetched.
+
+    Deliberately NOT an InvalidTokenError: the token may be perfectly good and the
+    broker merely unreachable, so a caller may want to retry rather than bounce the
+    user to /login.
+    """
+
+
+class InvalidTokenError(AuthError):
+    """The token was rejected. Base class for every verification failure."""
+
+
+class MalformedTokenError(InvalidTokenError):
+    """Undecodable, structurally broken, missing `sub`, or not yet valid."""
+
+
+class UnsupportedAlgorithmError(InvalidTokenError):
+    """Header `alg` is symmetric or `none`.
+
+    Rejected before any key lookup: an attacker must not be able to downgrade us to a
+    symmetric secret we do not hold.
+    """
+
+
+class UnknownKeyError(InvalidTokenError):
+    """No key in the issuer's JWKS matches the token's `kid`, even after a refresh."""
+
+
+class BadSignatureError(InvalidTokenError):
+    """A known key was found and the signature did not verify against it."""
+
+
+class ExpiredTokenError(InvalidTokenError):
+    """`exp` is in the past, beyond the configured clock skew."""
+
+
+class WrongIssuerError(InvalidTokenError):
+    """`iss` does not equal the configured issuer."""
+
+
+class WrongAudienceError(InvalidTokenError):
+    """`aud` does not contain the configured audience."""
+
+
+class NonceMismatchError(InvalidTokenError):
+    """A nonce was expected and the token's claim is absent or different."""
+
+
+class InvalidSessionError(AuthError):
+    """The session cookie could not be opened: tampered, wrong key, or expired.
+
+    Not an InvalidTokenError — this is our own envelope failing, not a broker token.
+    """
+
+
+class StateMismatchError(AuthError):
+    """The callback's `state` does not match the pending login. Treated as CSRF."""
+
+
+class TokenExchangeError(AuthError):
+    """The token endpoint refused or malformed the exchange.
+
+    Like DiscoveryError, this means the broker misbehaved rather than the user, so callers
+    may retry instead of bouncing to /login.
+    """
+
+
+class RefreshRejectedError(AuthError):
+    """The broker refused to renew the session — the user must log in again.
+
+    Distinct from TokenExchangeError on purpose. `invalid_grant` means the refresh token is
+    spent, revoked or expired, so retrying is pointless and the only cure is a new login.
+    Any other failure is the broker misbehaving, where a retry is reasonable.
+    """