jfastframework 0.1.0a1__py3-none-any.whl

jfastframework/__init__.py

@@ -0,0 +1,44 @@
+"""JFastFramework -- plugin-based FastAPI framework for microservices."""
+
+from jfastframework.app import create_app, get_context
+from jfastframework.context import AppContext
+from jfastframework.errors import (
+    ConflictError,
+    ForbiddenError,
+    JFastError,
+    NotFoundError,
+    ServiceUnavailableError,
+    UnauthorizedError,
+    ValidationError,
+)
+from jfastframework.plugins.base import (
+    HealthReport,
+    InfraService,
+    Plugin,
+    PluginMeta,
+    PluginSettings,
+)
+from jfastframework.settings import JFastConfig, JFastSettings
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "AppContext",
+    "ConflictError",
+    "ForbiddenError",
+    "HealthReport",
+    "InfraService",
+    "JFastConfig",
+    "JFastError",
+    "JFastSettings",
+    "NotFoundError",
+    "Plugin",
+    "PluginMeta",
+    "PluginSettings",
+    "ServiceUnavailableError",
+    "UnauthorizedError",
+    "ValidationError",
+    "__version__",
+    "create_app",
+    "get_context",
+]

jfastframework/app.py

@@ -0,0 +1,155 @@
+"""Application factory.
+
+A JFast service's ``main.py`` is this::
+
+    from jfastframework import create_app
+
+    app = create_app()
+
+Everything else -- middleware, observability, database, routers -- arrives
+through the plugin graph resolved from ``jfast.toml``.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator, Sequence
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+from starlette.middleware.cors import CORSMiddleware
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from jfastframework.context import AppContext
+from jfastframework.errors import install_error_handlers
+from jfastframework.health import build_system_router
+from jfastframework.middleware import BodySizeLimitMiddleware, RequestTimeoutMiddleware
+from jfastframework.plugins import registry
+from jfastframework.plugins.base import Plugin
+from jfastframework.settings import DEFAULT_CONFIG_FILE, JFastConfig, JFastSettings
+
+logger = logging.getLogger("jfast")
+
+
+def create_app(
+    *,
+    config: JFastConfig | None = None,
+    config_path: str | Path | None = DEFAULT_CONFIG_FILE,
+    overrides: dict[str, Any] | None = None,
+    plugins: Sequence[type[Plugin]] | None = None,
+    routers: Sequence[APIRouter] | None = None,
+) -> FastAPI:
+    """Build a configured FastAPI application.
+
+    Args:
+        config: Pre-built config. Skips loading ``jfast.toml``.
+        config_path: Path to ``jfast.toml``. ``None`` to use env vars only.
+        overrides: Kernel settings overrides, highest precedence.
+        plugins: Extra plugin classes to register without installing them as
+            distributions. Useful in tests and for private in-repo plugins.
+        routers: Application routers to mount after plugins have registered.
+    """
+    cfg = config or JFastConfig.load(config_path=config_path, overrides=overrides)
+    settings = cfg.settings
+
+    resolved = registry.build(cfg, extra_plugins=list(plugins or []))
+
+    app = FastAPI(
+        title=settings.app_name,
+        version=settings.version,
+        debug=settings.debug,
+        root_path=settings.root_path,
+        docs_url=settings.effective_docs_url,
+        openapi_url=settings.effective_openapi_url,
+        lifespan=_build_lifespan(resolved),
+    )
+
+    # Before plugins, so their middleware runs inside these. A body that is too
+    # large should be refused before observability logs it as a request served.
+    _install_edge_middleware(app, settings)
+
+    ctx = AppContext(app=app, config=cfg)
+    # Plugins and the lifespan reach the context through app.state; nothing
+    # else in the framework uses module-level globals.
+    app.state.jfast = ctx
+    app.state.plugins = resolved
+
+    install_error_handlers(app, debug=settings.debug)
+
+    for plugin in resolved:
+        logger.debug("registering plugin %s", plugin.meta.name)
+        plugin.register(ctx)
+
+    app.include_router(build_system_router(ctx, resolved))
+
+    for router in routers or []:
+        app.include_router(router)
+
+    logger.info(
+        "%s built with plugins: %s",
+        settings.app_name,
+        ", ".join(p.meta.name for p in resolved) or "<none>",
+    )
+    return app
+
+
+def _install_edge_middleware(app: FastAPI, settings: JFastSettings) -> None:
+    """Host validation, CORS, body limits and request timeouts.
+
+    Starlette applies middleware in reverse registration order, so the last one
+    added is the outermost. Registration here therefore reads inside-out:
+    timeout and body limit closest to the application, then CORS, then the host
+    check outermost -- a request for a host this service does not serve is
+    rejected before anything else looks at it, and an error response still
+    carries its CORS headers, which is the only way the browser will show it.
+    """
+    if settings.request_timeout is not None:
+        app.add_middleware(RequestTimeoutMiddleware, seconds=settings.request_timeout)
+
+    if settings.max_body_bytes is not None:
+        app.add_middleware(BodySizeLimitMiddleware, max_bytes=settings.max_body_bytes)
+
+    if settings.cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=settings.cors_origins,
+            allow_credentials=settings.cors_allow_credentials,
+            allow_methods=settings.cors_allow_methods,
+            allow_headers=settings.cors_allow_headers,
+        )
+
+    if settings.trusted_hosts:
+        app.add_middleware(TrustedHostMiddleware, allowed_hosts=settings.trusted_hosts)
+
+
+def _build_lifespan(plugins: list[Plugin]):  # type: ignore[no-untyped-def]
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        ctx: AppContext = app.state.jfast
+        started: list[Plugin] = []
+        try:
+            for plugin in plugins:
+                await plugin.startup(ctx)
+                started.append(plugin)
+                logger.debug("started plugin %s", plugin.meta.name)
+            yield
+        finally:
+            # Reverse order, and one plugin failing to shut down must not
+            # prevent the rest from releasing their resources.
+            for plugin in reversed(started):
+                try:
+                    await plugin.shutdown(ctx)
+                except Exception:
+                    logger.exception("plugin %s failed to shut down", plugin.meta.name)
+
+    return lifespan
+
+
+def get_context(app: FastAPI) -> AppContext:
+    """Retrieve the JFast context from a running app."""
+    ctx = getattr(app.state, "jfast", None)
+    if ctx is None:
+        raise RuntimeError("This app was not built by jfastframework.create_app")
+    return ctx  # type: ignore[no-any-return]

jfastframework/auth/__init__.py

@@ -0,0 +1,56 @@
+"""JWT authentication: verification, scopes, rotation, revocation.
+
+    from jfastframework.auth import Principal, require_scopes
+
+    @router.post("/invoices")
+    async def create(caller: Principal = Depends(require_scopes("invoices:write"))):
+        ...
+
+The plugin verifies tokens and can mint them. It does not know who your users
+are — there is no login endpoint, because checking a password against your user
+table is your application's job. Use ``auth.issuer`` from your own login route.
+"""
+
+from jfastframework.auth.jwks import JWKSClient, JWKSError
+from jfastframework.auth.principal import Principal, current_principal
+from jfastframework.auth.store import MemoryTokenStore, RedisTokenStore, TokenStore
+from jfastframework.auth.tokens import (
+    SUPPORTED_ALGORITHMS,
+    TokenClaims,
+    TokenError,
+    issue,
+    verify,
+)
+
+__all__ = [
+    "SUPPORTED_ALGORITHMS",
+    "JWKSClient",
+    "JWKSError",
+    "MemoryTokenStore",
+    "Principal",
+    "RedisTokenStore",
+    "TokenClaims",
+    "TokenError",
+    "TokenStore",
+    "current_principal",
+    "issue",
+    "optional_auth",
+    "require_auth",
+    "require_roles",
+    "require_scopes",
+    "verify",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Expose the FastAPI dependencies without importing the plugin eagerly.
+
+    ``jfastframework.auth`` must stay importable in a process that has no
+    FastAPI app — a worker, a script, a test of the token functions alone.
+    The dependencies live in the plugin because they read ``request.state``.
+    """
+    if name in ("require_auth", "require_scopes", "require_roles", "optional_auth"):
+        from jfastframework.plugins.builtin import auth as plugin
+
+        return getattr(plugin, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

jfastframework/auth/jwks.py

@@ -0,0 +1,117 @@
+"""JWKS client: fetch and cache an issuer's public keys.
+
+Asymmetric verification is what makes JWT workable across services. The
+identity provider holds the private key; every service fetches the public keys
+from its JWKS endpoint and verifies locally. No shared secret, no network hop
+per request, and key rotation is a publish rather than a redeploy.
+
+Two failure modes this guards against, both of which are easy to build in by
+accident:
+
+**Refresh amplification.** A token carrying an unknown ``kid`` should trigger a
+refresh -- that is how rotation is picked up. Refreshing on *every* unknown
+``kid`` turns a stream of forged tokens into a denial-of-service against your
+identity provider. Refreshes are therefore rate-limited, and a token whose
+``kid`` is still unknown afterwards is simply rejected.
+
+**Serving stale keys forever.** If the endpoint is unreachable, the cached keys
+keep working -- a JWKS outage must not take every service down with it -- but
+the staleness is reported through the health check rather than hidden.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class JWKSError(RuntimeError):
+    """The key set could not be fetched or does not contain the key."""
+
+
+@dataclass
+class JWKSClient:
+    url: str
+    # How long a fetched key set is considered fresh.
+    cache_seconds: int = 3600
+    # Floor between refreshes triggered by an unknown kid.
+    min_refresh_seconds: int = 60
+    timeout: float = 5.0
+
+    _keys: dict[str, Any] = field(default_factory=dict, repr=False)
+    _fetched_at: float = 0.0
+    _last_attempt: float = 0.0
+    _last_error: str | None = None
+
+    async def _fetch(self) -> None:
+        import httpx
+
+        self._last_attempt = time.monotonic()
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(self.url)
+            response.raise_for_status()
+            document = response.json()
+
+        keys = {}
+        for entry in document.get("keys", []):
+            kid = entry.get("kid")
+            if kid:
+                keys[kid] = entry
+
+        if not keys:
+            raise JWKSError(f"{self.url} returned no usable keys")
+
+        self._keys = keys
+        self._fetched_at = time.monotonic()
+        self._last_error = None
+
+    async def _refresh(self, *, force: bool = False) -> None:
+        try:
+            await self._fetch()
+        except Exception as exc:
+            self._last_error = str(exc)
+            if force or not self._keys:
+                # Nothing cached to fall back on: this request cannot be
+                # verified, and saying so beats guessing.
+                raise JWKSError(f"cannot fetch JWKS from {self.url}: {exc}") from exc
+
+    async def key_for(self, kid: str | None) -> Any:
+        """The signing key for this ``kid``, fetching the set if needed."""
+        now = time.monotonic()
+        expired = now - self._fetched_at > self.cache_seconds
+
+        if not self._keys or expired:
+            await self._refresh(force=not self._keys)
+
+        if kid is None:
+            if len(self._keys) == 1:
+                return next(iter(self._keys.values()))
+            raise JWKSError(
+                "the token has no 'kid' and the key set has several keys; "
+                "which one signed it is unknowable"
+            )
+
+        if kid not in self._keys and (now - self._last_attempt) > self.min_refresh_seconds:
+            # Unknown kid: the issuer may have rotated. Refresh at most once
+            # per window, so forged kids cannot be used to hammer the issuer.
+            await self._refresh()
+
+        try:
+            return self._keys[kid]
+        except KeyError:
+            raise JWKSError(f"no key with kid {kid!r} in {self.url}") from None
+
+    async def health(self) -> tuple[bool, str]:
+        if not self._keys:
+            return False, self._last_error or "no keys fetched yet"
+        age = int(time.monotonic() - self._fetched_at)
+        if self._last_error:
+            # Serving cached keys through an outage is correct; hiding that it
+            # is happening is not.
+            return False, f"serving keys cached {age}s ago; last refresh failed: {self._last_error}"
+        return True, f"{len(self._keys)} key(s), cached {age}s ago"
+
+    @property
+    def key_ids(self) -> tuple[str, ...]:
+        return tuple(sorted(self._keys))

jfastframework/auth/oidc.py

@@ -0,0 +1,268 @@
+"""Sign in with Google — and any other OIDC provider.
+
+The auth plugin already verifies JWTs against a JWKS endpoint, and a Google ID
+token is exactly that: a JWT signed by Google, with Google's keys published at
+a well-known URL. So "log in with Google" needs almost no new machinery, just
+the right issuer, audience and discovery document.
+
+The flow, and who does what:
+
+1. Your frontend sends the user to Google (:func:`authorization_url`).
+2. Google redirects back with a `code`.
+3. Your backend exchanges it for an **ID token** (:meth:`OIDCProvider.exchange`).
+4. This module verifies that ID token.
+5. **You** look the user up or create them, and mint *your own* token with
+   `auth.issuer`.
+
+Step 5 is yours on purpose. A Google ID token says "Google believes this is
+person@example.com". It does not say what they may do in your system, it
+expires on Google's schedule, and you cannot revoke it. Exchanging it for your
+own token is what puts scopes, your tenant and your revocation back under your
+control.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlencode
+
+from jfastframework.auth.jwks import JWKSClient
+from jfastframework.auth.principal import Principal
+from jfastframework.auth.tokens import TokenError, verify
+
+
+@dataclass(frozen=True)
+class ProviderPreset:
+    """Endpoints for a known provider, so nobody has to look them up."""
+
+    name: str
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    jwks_uri: str
+    default_scopes: tuple[str, ...] = ("openid", "email", "profile")
+    algorithms: tuple[str, ...] = ("RS256",)
+
+
+PRESETS: dict[str, ProviderPreset] = {
+    "google": ProviderPreset(
+        name="google",
+        issuer="https://accounts.google.com",
+        authorization_endpoint="https://accounts.google.com/o/oauth2/v2/auth",
+        token_endpoint="https://oauth2.googleapis.com/token",
+        jwks_uri="https://www.googleapis.com/oauth2/v3/certs",
+    ),
+    "microsoft": ProviderPreset(
+        name="microsoft",
+        issuer="https://login.microsoftonline.com/common/v2.0",
+        authorization_endpoint=("https://login.microsoftonline.com/common/oauth2/v2.0/authorize"),
+        token_endpoint="https://login.microsoftonline.com/common/oauth2/v2.0/token",
+        jwks_uri="https://login.microsoftonline.com/common/discovery/v2.0/keys",
+    ),
+    "github": ProviderPreset(
+        name="github",
+        # GitHub is OAuth2, not OIDC: no ID token, so the userinfo call is
+        # the only way to learn who signed in. Listed for completeness; it
+        # does not go through verify_id_token().
+        issuer="https://github.com",
+        authorization_endpoint="https://github.com/login/oauth/authorize",
+        token_endpoint="https://github.com/login/oauth/access_token",
+        jwks_uri="",
+        default_scopes=("read:user", "user:email"),
+    ),
+}
+
+
+@dataclass
+class OIDCIdentity:
+    """Who the provider says this is. Not yet a user in your system."""
+
+    subject: str
+    email: str | None = None
+    email_verified: bool = False
+    name: str | None = None
+    picture: str | None = None
+    provider: str = ""
+    claims: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def federated_id(self) -> str:
+        """Stable identifier to store on your user row.
+
+        Provider-qualified, because subject ids are only unique per provider,
+        and because a user who later signs in with a different provider must
+        not silently collide with someone else.
+        """
+        return f"{self.provider}:{self.subject}"
+
+
+class OIDCProvider:
+    """One configured provider."""
+
+    def __init__(
+        self,
+        preset: ProviderPreset,
+        *,
+        client_id: str,
+        client_secret: str = "",
+        redirect_uri: str = "",
+        scopes: tuple[str, ...] | None = None,
+    ) -> None:
+        self.preset = preset
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.redirect_uri = redirect_uri
+        self.scopes = scopes or preset.default_scopes
+        self._jwks = JWKSClient(url=preset.jwks_uri) if preset.jwks_uri else None
+
+    # -- step 1 --------------------------------------------------------
+
+    def authorization_url(
+        self, *, state: str | None = None, nonce: str | None = None
+    ) -> tuple[str, str, str]:
+        """Where to send the user. Returns ``(url, state, nonce)``.
+
+        Keep both values: `state` is checked on the callback (CSRF), and
+        `nonce` is checked inside the ID token (replay). Generating them and
+        then not verifying them is the same as not having them.
+        """
+        state = state or secrets.token_urlsafe(24)
+        nonce = nonce or secrets.token_urlsafe(24)
+        query = {
+            "client_id": self.client_id,
+            "redirect_uri": self.redirect_uri,
+            "response_type": "code",
+            "scope": " ".join(self.scopes),
+            "state": state,
+            "nonce": nonce,
+            # Ask for a refresh token and force the consent screen only when
+            # you actually need offline access; both annoy users otherwise.
+        }
+        return f"{self.preset.authorization_endpoint}?{urlencode(query)}", state, nonce
+
+    # -- step 3 --------------------------------------------------------
+
+    async def exchange(self, code: str) -> dict[str, Any]:
+        """Swap the authorization code for tokens. Server-side only.
+
+        The client secret must never reach a browser. If your frontend is a
+        SPA, this call belongs in your backend, which is where this runs.
+        """
+        import httpx
+
+        if not self.client_secret:
+            raise TokenError(f"{self.preset.name}: no client secret configured")
+
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.post(
+                self.preset.token_endpoint,
+                data={
+                    "code": code,
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                    "redirect_uri": self.redirect_uri,
+                    "grant_type": "authorization_code",
+                },
+                headers={"Accept": "application/json"},
+            )
+        if response.status_code >= 400:
+            # The provider's body often contains the client_id; log the code
+            # and a short reason, not the whole payload.
+            raise TokenError(f"{self.preset.name} token exchange failed ({response.status_code})")
+        payload: dict[str, Any] = response.json()
+        return payload
+
+    # -- step 4 --------------------------------------------------------
+
+    async def verify_id_token(self, id_token: str, *, nonce: str | None = None) -> OIDCIdentity:
+        """Verify an ID token and return who it identifies.
+
+        Audience is this client id, issuer is the provider. Both matter: an ID
+        token minted for a *different* application of the same provider is a
+        valid Google token, and accepting it lets anyone with their own Google
+        app sign in as anybody here.
+        """
+        import jwt
+
+        if self._jwks is None:
+            raise TokenError(f"{self.preset.name} does not issue ID tokens")
+
+        header = jwt.get_unverified_header(id_token)
+        jwk = await self._jwks.key_for(header.get("kid"))
+
+        principal: Principal = verify(
+            id_token,
+            key=jwt.PyJWK(jwk).key,
+            algorithms=list(self.preset.algorithms),
+            audience=self.client_id,
+            issuer=self.preset.issuer,
+        )
+
+        if nonce is not None and principal.claims.get("nonce") != nonce:
+            # Without this a captured ID token can be replayed into a fresh
+            # login attempt.
+            raise TokenError("ID token nonce does not match this login attempt")
+
+        claims = principal.claims
+        return OIDCIdentity(
+            subject=principal.subject,
+            email=claims.get("email"),
+            # An unverified email must not be used to match an existing
+            # account: it is an account-takeover primitive.
+            email_verified=bool(claims.get("email_verified", False)),
+            name=claims.get("name"),
+            picture=claims.get("picture"),
+            provider=self.preset.name,
+            claims=claims,
+        )
+
+    async def health(self) -> tuple[bool, str]:
+        if self._jwks is None:
+            return True, f"{self.preset.name} (OAuth2, no ID tokens)"
+        return await self._jwks.health()
+
+
+def provider(
+    name: str,
+    *,
+    client_id: str,
+    client_secret: str = "",
+    redirect_uri: str = "",
+    issuer: str = "",
+    jwks_uri: str = "",
+    authorization_endpoint: str = "",
+    token_endpoint: str = "",
+) -> OIDCProvider:
+    """A known provider by name, or a custom one from its endpoints."""
+    preset = PRESETS.get(name)
+    if preset is None:
+        missing = [
+            field_name
+            for field_name, value in (
+                ("issuer", issuer),
+                ("jwks_uri", jwks_uri),
+                ("authorization_endpoint", authorization_endpoint),
+                ("token_endpoint", token_endpoint),
+            )
+            if not value
+        ]
+        if missing:
+            raise TokenError(
+                f"Unknown provider {name!r}. Either use one of "
+                f"{', '.join(sorted(PRESETS))}, or supply: {', '.join(missing)}."
+            )
+        preset = ProviderPreset(
+            name=name,
+            issuer=issuer,
+            authorization_endpoint=authorization_endpoint,
+            token_endpoint=token_endpoint,
+            jwks_uri=jwks_uri,
+        )
+    return OIDCProvider(
+        preset,
+        client_id=client_id,
+        client_secret=client_secret,
+        redirect_uri=redirect_uri,
+    )