incorta-auth 0.1.0__py3-none-any.whl

incorta_auth/__init__.py

@@ -0,0 +1,77 @@
+"""Authenticate Incorta users in Python apps.
+
+Python port of ``@incorta/auth`` — OAuth 2.0 / OIDC against the authorization
+server built into Incorta, with sessions sealed in encrypted cookies that
+interop with the TS SDK.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _metadata_version
+
+from .asgi import IncortaAuthMiddleware, is_auth_configured
+from .auth import IncortaAuth
+from .config import (
+    AuthSession,
+    IncortaUser,
+    ResolvedConfig,
+    SessionData,
+    embedded_cookie_config,
+    resolve_config,
+)
+from .errors import IncortaAuthError
+from .flow import (
+    ACCESS_TOKEN_REFRESH_LEEWAY_MS,
+    CallbackResult,
+    LoadedSession,
+    LoginResult,
+    begin_login,
+    clear_session_cookie,
+    complete_callback,
+    get_session,
+    load_session,
+    validate_return_to,
+)
+from .register import (
+    ClientInfo,
+    RegisteredClient,
+    delete_client,
+    get_client,
+    register_client,
+    update_client_redirect_uris,
+)
+
+# The distribution's version is stamped into package metadata at publish time
+# (see release.python.config.cjs) — read it back rather than hardcoding.
+try:
+    __version__ = _metadata_version("incorta-auth")
+except PackageNotFoundError:  # bare checkout without an installed dist
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ACCESS_TOKEN_REFRESH_LEEWAY_MS",
+    "AuthSession",
+    "CallbackResult",
+    "ClientInfo",
+    "IncortaAuth",
+    "IncortaAuthError",
+    "IncortaAuthMiddleware",
+    "IncortaUser",
+    "LoadedSession",
+    "LoginResult",
+    "RegisteredClient",
+    "ResolvedConfig",
+    "SessionData",
+    "begin_login",
+    "clear_session_cookie",
+    "complete_callback",
+    "delete_client",
+    "embedded_cookie_config",
+    "get_client",
+    "get_session",
+    "is_auth_configured",
+    "load_session",
+    "register_client",
+    "resolve_config",
+    "update_client_redirect_uris",
+    "validate_return_to",
+]

incorta_auth/_time.py

@@ -0,0 +1,11 @@
+"""Clock indirection so tests can shift time without sleeping.
+
+Call sites use ``_time.now_ms()`` (module attribute lookup) rather than
+importing the function, so a monkeypatch here is seen everywhere.
+"""
+
+import time
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)

incorta_auth/asgi.py

@@ -0,0 +1,438 @@
+"""Pure-ASGI auth middleware — the Python equivalent of the fullstack
+template's ``src/server.ts`` + ``src/server/auth.ts`` gate combined with the
+TS SDK's ``/auth/*`` handler:
+
+- ``{base_path}/*`` is served by the SDK (login, callback, session, logout,
+  signed-out, and token when exposed);
+- every other request needs a session: browser navigations are redirected
+  into the Incorta login flow (relative ``Location`` on purpose — behind a
+  Host-rewriting proxy only the browser knows the public origin), data
+  requests get a 401, websockets are refused;
+- authenticated requests continue to the app with the session attached to
+  the ASGI ``state`` (``request.state.incorta_auth`` in Starlette/FastAPI);
+- when the INCORTA_* env is missing every request gets an honest 503
+  "authentication not configured" answer instead of a crash;
+- ``public_paths`` (exact matches) bypass the gate AND the 503 — liveness
+  probes keep working before provisioning completes.
+
+No Starlette/FastAPI dependency — this wraps any ASGI app. Network-touching
+work (token exchange, refresh, JWKS) runs in the default executor so the
+event loop never blocks on the sync core.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import json
+import logging
+import os
+from collections.abc import Awaitable, Callable, MutableMapping, Sequence
+from typing import Any
+from urllib.parse import parse_qsl, quote
+
+from . import flow
+from .auth import IncortaAuth
+from .config import ResolvedConfig
+from .errors import IncortaAuthError
+from .session import _user_to_payload
+
+Scope = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[MutableMapping[str, Any]]]
+Send = Callable[[MutableMapping[str, Any]], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+logger = logging.getLogger("incorta_auth")
+
+_REQUIRED = {
+    "incorta_url": "INCORTA_URL",
+    "tenant": "INCORTA_TENANT",
+    "client_id": "INCORTA_CLIENT_ID",
+    "client_secret": "INCORTA_CLIENT_SECRET",
+    "secret": "INCORTA_AUTH_SECRET",
+}
+
+
+def is_auth_configured(overrides: dict[str, Any] | None = None) -> bool:
+    """True when every required setting is present (argument or env) —
+    mirrors the fullstack template's ``isAuthConfigured``."""
+    provided = overrides or {}
+    return all(
+        str(provided.get(field) or os.environ.get(env_var) or "").strip() != ""
+        for field, env_var in _REQUIRED.items()
+    )
+
+
+class _Response:
+    def __init__(
+        self,
+        status: int,
+        body: bytes = b"",
+        content_type: str | None = None,
+        extra_headers: list[tuple[str, str]] | None = None,
+        cookies: list[str] | None = None,
+    ) -> None:
+        self.status = status
+        self.body = body
+        self.headers: list[tuple[str, str]] = []
+        if content_type:
+            self.headers.append(("content-type", content_type))
+        self.headers.extend(extra_headers or [])
+        # One header entry per cookie — Set-Cookie must never be folded.
+        self.headers.extend(("set-cookie", cookie) for cookie in cookies or [])
+
+
+def _json(status: int, body: Any, cookies: list[str] | None = None) -> _Response:
+    return _Response(
+        status,
+        json.dumps(body).encode(),
+        content_type="application/json; charset=utf-8",
+        extra_headers=[("cache-control", "no-store")],
+        cookies=cookies,
+    )
+
+
+def _redirect(location: str, cookies: list[str] | None = None) -> _Response:
+    return _Response(
+        302,
+        extra_headers=[("location", location), ("cache-control", "no-store")],
+        cookies=cookies,
+    )
+
+
+def _html(status: int, body: str) -> _Response:
+    return _Response(
+        status,
+        body.encode(),
+        content_type="text/html; charset=utf-8",
+        extra_headers=[("cache-control", "no-store")],
+    )
+
+
+_NOT_CONFIGURED_PAGE = """<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Authentication not configured</title>
+    <style>
+      body { margin: 0; display: grid; place-items: center; min-height: 100vh;
+             background: #fafafa; color: #18181b;
+             font-family: ui-sans-serif, system-ui, sans-serif; }
+      main { max-width: 28rem; padding: 2rem; text-align: center; }
+      h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+      p { color: #52525b; font-size: .9rem; line-height: 1.5; margin: 0; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Authentication is not configured yet</h1>
+      <p>
+        This app signs users in through Incorta, but its credentials have not
+        been provisioned. They are injected automatically — restarting the
+        app's dev server usually completes the setup.
+      </p>
+    </main>
+  </body>
+</html>"""
+
+
+def _signed_out_page(base_path: str) -> str:
+    sign_in_href = f"{base_path}/login?redirect_to=%2F"
+    return f"""<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Signed out</title>
+    <style>
+      body {{ margin: 0; display: grid; place-items: center; min-height: 100vh;
+             background: #fafafa; color: #18181b;
+             font-family: ui-sans-serif, system-ui, sans-serif; }}
+      main {{ max-width: 26rem; padding: 2rem; text-align: center; }}
+      h1 {{ font-size: 1.25rem; margin: 0 0 .5rem; }}
+      p {{ color: #52525b; font-size: .9rem; line-height: 1.5; margin: 0 0 1.25rem; }}
+      a {{ display: inline-block; padding: .55rem 1.1rem; border-radius: .5rem;
+          background: #18181b; color: #fafafa; font-size: .9rem;
+          text-decoration: none; }}
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>You&rsquo;ve signed out of this app</h1>
+      <p>
+        Your Incorta account may still be signed in elsewhere — signing back
+        in here is one click.
+      </p>
+      <a href="{sign_in_href}">Sign in with Incorta</a>
+    </main>
+  </body>
+</html>"""
+
+
+class _RequestFacts:
+    """The request details the flow functions need, lifted out of the scope."""
+
+    def __init__(self, scope: Scope) -> None:
+        self.method: str = scope.get("method", "GET").upper()
+        self.path: str = scope["path"]
+        self.query_string: str = (scope.get("query_string") or b"").decode("latin-1")
+        headers: dict[str, str] = {}
+        for raw_name, raw_value in scope.get("headers") or []:
+            name = raw_name.decode("latin-1").lower()
+            value = raw_value.decode("latin-1")
+            # Repeated headers are joined; "; " keeps multiple Cookie headers valid.
+            if name in headers:
+                separator = "; " if name == "cookie" else ", "
+                headers[name] = f"{headers[name]}{separator}{value}"
+            else:
+                headers[name] = value
+        self.headers = headers
+        self.scheme: str = scope.get("scheme", "http")
+        server = scope.get("server") or ("localhost", None)
+        port = f":{server[1]}" if server[1] is not None else ""
+        self._fallback_host = f"{server[0]}{port}"
+
+    @property
+    def cookie_header(self) -> str | None:
+        return self.headers.get("cookie")
+
+    @property
+    def query(self) -> dict[str, str]:
+        return dict(parse_qsl(self.query_string))
+
+    def origin(self, config: ResolvedConfig) -> str:
+        if config.app_url:
+            return config.app_url
+        forwarded_proto = self.headers.get("x-forwarded-proto")
+        proto = forwarded_proto.split(",")[0].strip() if forwarded_proto else self.scheme
+        forwarded_host = self.headers.get("x-forwarded-host")
+        host = (
+            forwarded_host.split(",")[0].strip()
+            if forwarded_host
+            else self.headers.get("host") or self._fallback_host
+        )
+        return f"{proto}://{host}"
+
+    def secure(self, config: ResolvedConfig) -> bool:
+        if config.secure_cookies != "auto":
+            return config.secure_cookies
+        return self.origin(config).startswith("https://")
+
+    def wants_html(self) -> bool:
+        return "text/html" in self.headers.get("accept", "")
+
+
+class IncortaAuthMiddleware:
+    """Wrap any ASGI app: ``IncortaAuthMiddleware(app)`` (config from
+    ``INCORTA_*`` env vars) or pass ``resolve_config`` keyword arguments,
+    e.g. ``IncortaAuthMiddleware(app, cookie_same_site="none")``. With
+    Starlette/FastAPI: ``app.add_middleware(IncortaAuthMiddleware, ...)``."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        auth: IncortaAuth | None = None,
+        public_paths: Sequence[str] = (),
+        **config_kwargs: Any,
+    ) -> None:
+        self._app = app
+        self._auth = auth
+        self._public_paths = tuple(public_paths)
+        self._config_kwargs = config_kwargs
+
+    def _get_auth(self) -> IncortaAuth:
+        # Lazy on purpose: reads env at first request, never at import time —
+        # the platform may inject INCORTA_* after the process image is built.
+        if self._auth is None:
+            self._auth = IncortaAuth(**self._config_kwargs)
+        return self._auth
+
+    def _is_configured(self) -> bool:
+        return self._auth is not None or is_auth_configured(self._config_kwargs)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "websocket":
+            await self._handle_websocket(scope, receive, send)
+            return
+        if scope["type"] != "http":
+            await self._app(scope, receive, send)
+            return
+
+        facts = _RequestFacts(scope)
+
+        if facts.path in self._public_paths:
+            # Reachable before provisioning and without a session (liveness);
+            # a session is still attached when one exists.
+            if self._is_configured():
+                self._attach_session(scope, self._get_auth(), facts)
+            await self._app(scope, receive, send)
+            return
+
+        if not self._is_configured():
+            await _send(send, self._not_configured(facts))
+            return
+
+        try:
+            auth = self._get_auth()
+            base_path = auth.config.base_path
+
+            if facts.path == base_path or facts.path.startswith(f"{base_path}/"):
+                loop = asyncio.get_running_loop()
+                response = await loop.run_in_executor(
+                    None, functools.partial(self._handle_auth_route, auth, facts)
+                )
+                await _send(send, response)
+                return
+
+            if self._attach_session(scope, auth, facts):
+                await self._app(scope, receive, send)
+                return
+
+            await _send(send, self._unauthenticated(auth, facts))
+        except Exception:
+            logger.exception("[incorta-auth] request handling failed")
+            await _send(send, _json(500, {"error": "internal_error"}))
+
+    def _attach_session(self, scope: Scope, auth: IncortaAuth, facts: _RequestFacts) -> bool:
+        session = auth.get_session(facts.cookie_header)
+        if session is None:
+            return False
+        scope.setdefault("state", {})["incorta_auth"] = session
+        return True
+
+    def _unauthenticated(self, auth: IncortaAuth, facts: _RequestFacts) -> _Response:
+        if facts.method == "GET" and facts.wants_html():
+            redirect_to = facts.path + (f"?{facts.query_string}" if facts.query_string else "")
+            # Relative Location on purpose: this server sits behind a
+            # Host-rewriting proxy, so the request's own origin is an internal
+            # loopback address — only the BROWSER knows the public origin, and
+            # it resolves a relative redirect against it.
+            location = f"{auth.config.base_path}/login?redirect_to={quote(redirect_to, safe='')}"
+            return _Response(302, extra_headers=[("location", location)])
+        return _Response(
+            401,
+            json.dumps({"error": "unauthenticated"}).encode(),
+            content_type="application/json",
+        )
+
+    def _not_configured(self, facts: _RequestFacts) -> _Response:
+        if not facts.wants_html():
+            return _Response(
+                503,
+                json.dumps({"error": "auth_not_configured"}).encode(),
+                content_type="application/json",
+            )
+        return _html(503, _NOT_CONFIGURED_PAGE)
+
+    async def _handle_websocket(self, scope: Scope, receive: Receive, send: Send) -> None:
+        # Websockets carry no redirect semantics — a missing session (or
+        # missing configuration) refuses the handshake outright.
+        if not self._is_configured():
+            await receive()
+            await send({"type": "websocket.close", "code": 1008})
+            return
+        facts = _RequestFacts(scope)
+        if self._attach_session(scope, self._get_auth(), facts):
+            await self._app(scope, receive, send)
+            return
+        await receive()
+        await send({"type": "websocket.close", "code": 1008})
+
+    # --- /auth/* routes (sync — runs in the executor) --------------------
+
+    def _handle_auth_route(self, auth: IncortaAuth, facts: _RequestFacts) -> _Response:
+        config = auth.config
+        route = facts.path[len(config.base_path) :] or "/"
+        method = facts.method
+        origin = facts.origin(config)
+        secure = facts.secure(config)
+
+        try:
+            if route == "/login" and method == "GET":
+                result = auth.begin_login(
+                    origin=origin,
+                    secure=secure,
+                    cookie_header=facts.cookie_header,
+                    redirect_to=facts.query.get("redirect_to"),
+                )
+                return _redirect(result.location, result.set_cookies)
+
+            if route == "/callback" and method == "GET":
+                callback = auth.complete_callback(
+                    origin=origin,
+                    secure=secure,
+                    cookie_header=facts.cookie_header,
+                    query=facts.query,
+                )
+                return _redirect(callback.location, callback.set_cookies)
+
+            if route == "/session" and method == "GET":
+                loaded = auth.load_session(cookie_header=facts.cookie_header, secure=secure)
+                if loaded.session is None:
+                    return _json(200, {"user": None}, loaded.set_cookies)
+                return _json(
+                    200,
+                    {
+                        "user": _user_to_payload(loaded.session.user),
+                        "session": {
+                            "expiresAt": loaded.session_expires_at,
+                            "accessTokenExpiresAt": loaded.session.access_token_expires_at,
+                        },
+                    },
+                    loaded.set_cookies,
+                )
+
+            if route == "/token" and method == "GET":
+                if not config.expose_access_token:
+                    return _json(404, {"error": "not_found"})
+                loaded = auth.load_session(cookie_header=facts.cookie_header, secure=secure)
+                if loaded.session is None:
+                    return _json(401, {"error": "unauthenticated"}, loaded.set_cookies)
+                return _json(
+                    200,
+                    {
+                        "accessToken": loaded.session.access_token,
+                        "expiresAt": loaded.session.access_token_expires_at,
+                    },
+                    loaded.set_cookies,
+                )
+
+            if route == "/logout" and method in ("GET", "POST"):
+                clear = auth.clear_session_cookie(secure=secure)
+                if method == "GET":
+                    # No explicit redirect_to → the signed-out page, NOT "/":
+                    # in an SSO-gated app, landing on a gated page silently
+                    # re-runs the login flow and signs the user straight back
+                    # in — sign-out must land somewhere UNGATED to stick.
+                    raw = facts.query.get("redirect_to")
+                    if not raw:
+                        return _redirect(f"{config.base_path}/signed-out", [clear])
+                    return _redirect(flow.validate_return_to(raw, origin), [clear])
+                return _json(200, {"ok": True}, [clear])
+
+            if route == "/signed-out" and method == "GET":
+                return _html(200, _signed_out_page(config.base_path))
+
+            return _json(404, {"error": "not_found"})
+        except IncortaAuthError as error:
+            logger.error("[incorta-auth] %s failed: %s", route, error)
+            return _json(500, {"error": error.code})
+        except Exception as error:
+            logger.error("[incorta-auth] %s failed: %s", route, error)
+            return _json(500, {"error": "internal_error"})
+
+
+async def _send(send: Send, response: _Response) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": response.status,
+            "headers": [
+                (name.encode("latin-1"), value.encode("latin-1"))
+                for name, value in response.headers
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": response.body})

incorta_auth/auth.py

@@ -0,0 +1,69 @@
+"""The main entry point — mirrors the TS SDK's ``createIncortaAuth``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .config import AuthSession, ResolvedConfig, resolve_config
+from .flow import (
+    CallbackResult,
+    LoadedSession,
+    LoginResult,
+    begin_login,
+    clear_session_cookie,
+    complete_callback,
+    get_session,
+    load_session,
+)
+
+
+class IncortaAuth:
+    """Bundles a resolved config with the framework-agnostic flow operations.
+
+    Framework adapters (ASGI middleware, the Streamlit gate) build on these;
+    they can also be called directly from any Python web stack.
+    """
+
+    def __init__(self, config: ResolvedConfig | None = None, **config_kwargs: Any) -> None:
+        self.config = config if config is not None else resolve_config(**config_kwargs)
+
+    def begin_login(
+        self,
+        *,
+        origin: str,
+        secure: bool,
+        cookie_header: str | None = None,
+        redirect_to: str | None = None,
+    ) -> LoginResult:
+        return begin_login(
+            self.config,
+            origin=origin,
+            secure=secure,
+            cookie_header=cookie_header,
+            redirect_to=redirect_to,
+        )
+
+    def complete_callback(
+        self,
+        *,
+        origin: str,
+        secure: bool,
+        cookie_header: str | None,
+        query: Mapping[str, str],
+    ) -> CallbackResult:
+        return complete_callback(
+            self.config, origin=origin, secure=secure, cookie_header=cookie_header, query=query
+        )
+
+    def load_session(self, *, cookie_header: str | None, secure: bool) -> LoadedSession:
+        return load_session(self.config, cookie_header=cookie_header, secure=secure)
+
+    def get_session(self, cookie_header: str | None) -> AuthSession | None:
+        return get_session(self.config, cookie_header)
+
+    def clear_session_cookie(self, *, secure: bool) -> str:
+        return clear_session_cookie(self.config, secure)
+
+    def close(self) -> None:
+        self.config.close()