sunstone-data-platform 1.0.0__py3-none-any.whl

sunstone_data/__init__.py

@@ -0,0 +1,36 @@
+"""Sunstone Data Platform - Data lakehouse with semantic metadata."""
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str):
+    """Lazy imports to avoid triggering heavy dependency chains at import time.
+
+    PyIceberg's GCS module calls google.auth.default() at import time,
+    which fails in environments without GCP credentials and prevents
+    the sunstone-py plugin from loading.
+    """
+    _lazy = {
+        "get_catalog": ("sunstone_data.catalog", "get_catalog"),
+        "create_namespace_if_not_exists": ("sunstone_data.catalog", "create_namespace_if_not_exists"),
+        "get_connection": ("sunstone_data.query", "get_connection"),
+        "list_tables": ("sunstone_data.query", "list_tables"),
+        "get_settings": ("sunstone_data.config", "get_settings"),
+    }
+    if name in _lazy:
+        module_path, attr = _lazy[name]
+        import importlib
+
+        mod = importlib.import_module(module_path)
+        return getattr(mod, attr)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "get_catalog",
+    "create_namespace_if_not_exists",
+    "get_connection",
+    "list_tables",
+    "get_settings",
+    "__version__",
+]

sunstone_data/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = None

sunstone_data/auth/__init__.py

@@ -0,0 +1,43 @@
+"""OAuth2 credentials for talking to graph-server.
+
+graph-server needs ``Authorization: Bearer <JWT>`` on every route except
+health, the UI and public views. Two ways to get one:
+
+- **Services** set ``client_id``/``client_secret`` and use the OAuth2
+  client-credentials grant (:mod:`sunstone_data.auth.client_creds`).
+- **Humans** log in once; the refresh token is cached per environment by
+  :mod:`sunstone_data.auth.store` and exchanged for access tokens on demand.
+
+:func:`resolve_access_token` picks between them, preferring an explicit
+environment credential, so CI is never silently authenticated as whoever
+last logged in on that machine.
+
+Access tokens live in memory only. The refresh token is the sole thing
+written to disk.
+"""
+
+from sunstone_data.auth.client_creds import (
+    ClientCredentialsToken,
+    discover_token_endpoint,
+    refresh_access_token,
+    resolve_access_token,
+)
+from sunstone_data.auth.store import (
+    Session,
+    clear_session,
+    read_session,
+    session_path,
+    write_session,
+)
+
+__all__ = [
+    "ClientCredentialsToken",
+    "Session",
+    "clear_session",
+    "discover_token_endpoint",
+    "read_session",
+    "refresh_access_token",
+    "resolve_access_token",
+    "session_path",
+    "write_session",
+]

sunstone_data/auth/client_creds.py

@@ -0,0 +1,239 @@
+"""OAuth2 token acquisition for graph-server clients.
+
+Two grants, one resolver:
+
+- ``client_credentials`` — a service authenticates as itself with the
+  ``client_id``/``client_secret`` its environment configures.
+- ``refresh_token`` — a human logged in earlier; the cached refresh token
+  (:mod:`sunstone_data.auth.store`) is exchanged for a fresh access token.
+
+:func:`resolve_access_token` prefers the service credential, so CI never runs
+silently as whoever last logged in on that machine (spec 180 §4).
+
+Endpoints are discovered, not configured: graph-server publishes the
+``issuer`` at ``/ui/config.json`` (:mod:`sunstone_data.discovery`) and
+standard OIDC discovery on the issuer supplies the token endpoint.
+
+Access tokens are held in memory only and never written to disk.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import httpx
+
+from sunstone_data.auth import store
+from sunstone_data.config import Settings
+
+#: Treat a token as expired this many seconds early, so one handed out here
+#: does not expire mid-request.
+EXPIRY_SKEW_SECONDS = 30.0
+
+OIDC_DISCOVERY_PATH = "/.well-known/openid-configuration"
+
+
+def _fetch_oidc_document(issuer: str, client: httpx.Client) -> tuple[dict, str]:
+    """Fetch an issuer's OIDC discovery document.
+
+    Returns the parsed document and the URL it came from, so callers can name
+    that URL in their own errors.
+
+    Raises:
+        RuntimeError: The document could not be fetched or parsed.
+    """
+    url = issuer.rstrip("/") + OIDC_DISCOVERY_PATH
+    try:
+        response = client.get(url, headers={"Accept": "application/json"})
+        response.raise_for_status()
+        payload = response.json()
+    except (httpx.HTTPError, ValueError) as e:
+        raise RuntimeError(f"OIDC discovery failed for {url}: {e}") from e
+    return (payload if isinstance(payload, dict) else {}), url
+
+
+def discover_token_endpoint(issuer: str, client: httpx.Client) -> str:
+    """Return the OAuth2 token endpoint for an OIDC issuer.
+
+    Args:
+        issuer: OIDC issuer URL, with or without a trailing slash.
+        client: HTTP client to use for the request.
+
+    Raises:
+        RuntimeError: The discovery document could not be fetched or has no
+            usable ``token_endpoint``.
+    """
+    payload, url = _fetch_oidc_document(issuer, client)
+    token_endpoint = payload.get("token_endpoint")
+    if not token_endpoint:
+        raise RuntimeError(f"OIDC discovery document at {url} has no token_endpoint")
+    return token_endpoint
+
+
+def discover_authorization_endpoint(issuer: str, client: httpx.Client) -> str:
+    """Return the OAuth2 authorization endpoint for an OIDC issuer.
+
+    This is where the PKCE flow sends the user's browser.
+
+    Args:
+        issuer: OIDC issuer URL, with or without a trailing slash.
+        client: HTTP client to use for the request.
+
+    Raises:
+        RuntimeError: The discovery document could not be fetched or has no
+            usable ``authorization_endpoint``.
+    """
+    payload, url = _fetch_oidc_document(issuer, client)
+    authorization_endpoint = payload.get("authorization_endpoint")
+    if not authorization_endpoint:
+        raise RuntimeError(f"OIDC discovery document at {url} has no authorization_endpoint")
+    return authorization_endpoint
+
+
+def _post_token(token_endpoint: str, form: dict[str, str], client: httpx.Client) -> tuple[str, float]:
+    """POST a token request and return ``(access_token, expires_at)``.
+
+    Raises:
+        RuntimeError: The request failed or the response carried no
+            ``access_token``.
+    """
+    try:
+        response = client.post(
+            token_endpoint,
+            data=form,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        response.raise_for_status()
+        payload = response.json()
+    except (httpx.HTTPError, ValueError) as e:
+        raise RuntimeError(f"Token request to {token_endpoint} failed: {e}") from e
+    access_token = payload.get("access_token") if isinstance(payload, dict) else None
+    if not access_token:
+        raise RuntimeError(f"Token response from {token_endpoint} has no access_token")
+    try:
+        expires_in = float(payload.get("expires_in") or 0)
+    except (TypeError, ValueError):
+        expires_in = 0.0
+    return access_token, time.time() + expires_in
+
+
+class ClientCredentialsToken:
+    """Client-credentials access tokens for one service identity.
+
+    Holds the current access token in memory and re-fetches it when it is
+    within :data:`EXPIRY_SKEW_SECONDS` of expiry. Nothing is written to disk.
+    """
+
+    def __init__(self, issuer: str, client_id: str, client_secret: str) -> None:
+        """Args: the OIDC issuer and the service's OAuth2 client credentials."""
+        self.issuer = issuer
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._access_token: str | None = None
+        self._expires_at: float = 0.0
+
+    def access_token(self, client: httpx.Client) -> str:
+        """Return a valid access token, fetching a new one only if needed.
+
+        Args:
+            client: HTTP client used for discovery and the token request.
+
+        Raises:
+            RuntimeError: Discovery or the token request failed.
+        """
+        if self._access_token is not None and time.time() < self._expires_at - EXPIRY_SKEW_SECONDS:
+            return self._access_token
+        token_endpoint = discover_token_endpoint(self.issuer, client)
+        self._access_token, self._expires_at = _post_token(
+            token_endpoint,
+            {
+                "grant_type": "client_credentials",
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+            },
+            client,
+        )
+        return self._access_token
+
+
+def refresh_access_token(issuer: str, client_id: str, refresh_token: str, client: httpx.Client) -> str:
+    """Exchange a cached human refresh token for a fresh access token.
+
+    The access token is returned, never persisted; only the refresh token
+    lives on disk.
+
+    Raises:
+        RuntimeError: Discovery or the token request failed.
+    """
+    token_endpoint = discover_token_endpoint(issuer, client)
+    access_token, _expires_at = _post_token(
+        token_endpoint,
+        {
+            "grant_type": "refresh_token",
+            "client_id": client_id,
+            "refresh_token": refresh_token,
+        },
+        client,
+    )
+    return access_token
+
+
+def discovered_issuer(env_name: str, graph_url: str) -> str:
+    """Return the OIDC issuer graph-server publishes for an environment.
+
+    Raises:
+        RuntimeError: No issuer could be discovered.
+    """
+    from sunstone_data.discovery import get_discovered
+
+    discovered = get_discovered(env_name, graph_url)
+    if discovered is None or not discovered.issuer:
+        raise RuntimeError(
+            f"No OIDC issuer discovered for environment {env_name!r}; cannot authenticate (graph_url={graph_url!r})"
+        )
+    return discovered.issuer
+
+
+def resolve_access_token(settings: Settings, env_name: str, client: httpx.Client) -> str | None:
+    """Return a bearer token for graph-server, or None if none is configured.
+
+    Precedence (spec 180 §4): an explicit environment credential beats a
+    cached human session, so a service or CI run is never silently
+    authenticated as whoever last logged in on that machine.
+
+    ``SUNSTONE_ACCESS_TOKEN`` sits above both. It is for callers that already
+    hold a token and have no reachable identity provider — CI, the compose
+    stack, a short-lived job handed a token by whatever started it. The token
+    is used as-is: it is never refreshed, so a caller supplying one owns its
+    lifetime. A blank value counts as unset.
+
+    Args:
+        settings: Resolved settings — ``client_id``/``client_secret`` select
+            the service flow, ``graph_url`` drives issuer discovery.
+        env_name: Environment whose session cache to consult.
+        client: HTTP client used for discovery and token requests.
+
+    Returns:
+        An access token, or ``None`` when neither a service credential nor a
+        cached login exists. What to do about that — error, prompt to log
+        in — is the caller's call.
+
+    Raises:
+        RuntimeError: A credential exists but no issuer could be discovered,
+            or the token request failed.
+    """
+    env_token = os.environ.get("SUNSTONE_ACCESS_TOKEN", "").strip()
+    if env_token:
+        return env_token
+
+    if settings.client_id and settings.client_secret:
+        issuer = discovered_issuer(env_name, settings.graph_url)
+        return ClientCredentialsToken(issuer, settings.client_id, settings.client_secret).access_token(client)
+
+    session = store.read_session(env_name)
+    if session is not None:
+        issuer = session.issuer or discovered_issuer(env_name, settings.graph_url)
+        return refresh_access_token(issuer, session.client_id, session.refresh_token, client)
+
+    return None

sunstone_data/auth/pkce.py

@@ -0,0 +1,307 @@
+"""Human sign-in: OAuth2 authorization code with PKCE on a loopback redirect.
+
+PKCE (Proof Key for Code Exchange, RFC 7636) lets a client with no secret —
+like a CLI — prove that the app redeeming an authorization code is the same
+app that asked for it. The client invents a random ``code_verifier``, sends
+only its SHA-256 hash (the ``code_challenge``) to the authorization endpoint,
+and reveals the verifier when it redeems the code.
+
+The browser hands the code back over a redirect to ``localhost`` on one of
+the ports registered on the Keycloak client (:data:`LOOPBACK_PORTS`), so
+nothing leaves the machine. Keycloak matches redirect URIs exactly and has no
+wildcard for ports, so the port cannot be ephemeral. The port is bound
+*before* the authorization URL is built, because the ``redirect_uri`` must
+name it.
+
+This is the flow behind ``sunstone data login`` (spec 180 §4). The public
+client it signs in as is the one graph-server publishes as ``clientId`` in
+``/ui/config.json``, the same one the graph explorer UI uses.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import time
+import webbrowser
+from collections.abc import Callable
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+#: Loopback ports registered as redirect URIs on the public Keycloak client
+#: (``http://localhost:<port>``, no path). Tried in order.
+LOOPBACK_PORTS = (8000, 18000)
+
+#: Give up if nobody completes the browser step within this many seconds.
+CALLBACK_TIMEOUT_SECONDS = 300.0
+
+_BROWSER_MESSAGE = "Signed in to Sunstone. You can close this window."
+
+
+def generate_code_verifier() -> str:
+    """Return a fresh PKCE ``code_verifier``.
+
+    ``token_urlsafe(64)`` yields 86 unreserved characters, inside RFC 7636's
+    43-128 range.
+    """
+    return secrets.token_urlsafe(64)
+
+
+def derive_code_challenge(verifier: str) -> str:
+    """Return the ``S256`` ``code_challenge`` for a verifier.
+
+    That is unpadded base64url of the SHA-256 of the verifier's ASCII bytes.
+    """
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+
+
+def generate_state() -> str:
+    """Return a random ``state`` value, which ties a callback to this request."""
+    return secrets.token_urlsafe(32)
+
+
+def build_authorization_url(
+    authorization_endpoint: str,
+    *,
+    client_id: str,
+    redirect_uri: str,
+    state: str,
+    code_challenge: str,
+) -> str:
+    """Build the URL the user's browser is sent to in order to sign in."""
+    query = urlencode(
+        {
+            "response_type": "code",
+            "client_id": client_id,
+            "redirect_uri": redirect_uri,
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+        }
+    )
+    separator = "&" if urlparse(authorization_endpoint).query else "?"
+    return f"{authorization_endpoint}{separator}{query}"
+
+
+@dataclass(frozen=True)
+class CallbackResult:
+    """What the browser handed back on the loopback redirect."""
+
+    code: str | None = None
+    """Authorization code, when sign-in succeeded."""
+
+    state: str | None = None
+    """The ``state`` echoed back; must match the one that was sent."""
+
+    error: str | None = None
+    """OAuth2 error code, when the provider refused."""
+
+
+def parse_callback_query(query_string: str) -> CallbackResult:
+    """Parse a redirect's query string into a :class:`CallbackResult`.
+
+    Kept separate from the HTTP server so it can be tested without a socket.
+    """
+    params = parse_qs(query_string)
+
+    def first(name: str) -> str | None:
+        values = params.get(name)
+        return values[0] if values else None
+
+    return CallbackResult(code=first("code"), state=first("state"), error=first("error"))
+
+
+def _handler_class(sink: dict[str, CallbackResult]) -> type[BaseHTTPRequestHandler]:
+    """Build a one-shot request handler that drops its result into ``sink``."""
+
+    class CallbackHandler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802  (stdlib naming)
+            sink["result"] = parse_callback_query(urlparse(self.path).query)
+            body = _BROWSER_MESSAGE.encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, format: str, *args: object) -> None:
+            """Silence the stdlib's stderr access log."""
+
+    return CallbackHandler
+
+
+def start_loopback_server(
+    ports: tuple[int, ...] = LOOPBACK_PORTS,
+) -> tuple[HTTPServer, dict[str, CallbackResult]]:
+    """Bind a loopback callback server on the first free registered port.
+
+    The server is bound but not yet serving, so the caller can read
+    ``server.server_address[1]`` to build the exact ``redirect_uri`` before
+    sending the user to the browser.
+
+    Returns:
+        The server and a dict that gains a ``"result"`` key holding a
+        :class:`CallbackResult` once one request has been handled.
+
+    Raises:
+        RuntimeError: Every port in ``ports`` is in use.
+    """
+    sink: dict[str, CallbackResult] = {}
+    handler = _handler_class(sink)
+    for port in ports:
+        try:
+            return HTTPServer(("127.0.0.1", port), handler), sink
+        except OSError:
+            continue
+    raise RuntimeError(f"No free loopback port for sign-in; tried {', '.join(map(str, ports))}")
+
+
+def await_callback(server: HTTPServer, sink: dict[str, CallbackResult]) -> CallbackResult:
+    """Serve exactly one request and return what it carried.
+
+    Raises:
+        RuntimeError: Nothing arrived within :data:`CALLBACK_TIMEOUT_SECONDS`.
+    """
+    server.timeout = CALLBACK_TIMEOUT_SECONDS
+    server.handle_request()
+    result = sink.get("result")
+    if result is None:
+        raise RuntimeError(f"No sign-in callback received within {CALLBACK_TIMEOUT_SECONDS:.0f}s")
+    return result
+
+
+def verify_callback(result: CallbackResult, expected_state: str) -> str:
+    """Check a callback and return its authorization code.
+
+    Raises:
+        RuntimeError: The ``state`` did not match the one sent (a possible
+            cross-site request forgery), the provider returned an error, or
+            no code came back.
+    """
+    if result.state != expected_state:
+        raise RuntimeError("Sign-in callback state did not match the request; discarding it")
+    if result.error:
+        raise RuntimeError(f"Sign-in failed: {result.error}")
+    if not result.code:
+        raise RuntimeError("Sign-in callback carried no authorization code")
+    return result.code
+
+
+@dataclass(frozen=True)
+class TokenResponse:
+    """Tokens minted by the authorization-code exchange."""
+
+    access_token: str
+    """Bearer token for graph-server. Held in memory only."""
+
+    refresh_token: str
+    """Long-lived token, the only part cached on disk."""
+
+    expires_at: float
+    """Unix time the access token expires."""
+
+
+def exchange_code(
+    token_endpoint: str,
+    *,
+    code: str,
+    code_verifier: str,
+    redirect_uri: str,
+    client_id: str,
+    client: httpx.Client,
+) -> TokenResponse:
+    """Redeem an authorization code for tokens.
+
+    No client secret is sent: the client is public, and the
+    ``code_verifier`` is what proves this is the app that asked for the code.
+
+    Raises:
+        RuntimeError: The request failed, or the response lacked an
+            ``access_token`` or ``refresh_token``.
+    """
+    try:
+        response = client.post(
+            token_endpoint,
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "client_id": client_id,
+                "code_verifier": code_verifier,
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        response.raise_for_status()
+        payload = response.json()
+    except (httpx.HTTPError, ValueError) as e:
+        raise RuntimeError(f"Token request to {token_endpoint} failed: {e}") from e
+    if not isinstance(payload, dict):
+        payload = {}
+    access_token = payload.get("access_token")
+    refresh_token = payload.get("refresh_token")
+    if not access_token:
+        raise RuntimeError(f"Token response from {token_endpoint} has no access_token")
+    if not refresh_token:
+        raise RuntimeError(f"Token response from {token_endpoint} has no refresh_token; cannot cache a session")
+    try:
+        expires_in = float(payload.get("expires_in") or 0)
+    except (TypeError, ValueError):
+        expires_in = 0.0
+    return TokenResponse(access_token, refresh_token, time.time() + expires_in)
+
+
+def login(
+    *,
+    authorization_endpoint: str,
+    token_endpoint: str,
+    client_id: str,
+    client: httpx.Client,
+    open_browser: Callable[[str], object] = webbrowser.open,
+) -> TokenResponse:
+    """Run the full PKCE sign-in and return the resulting tokens.
+
+    Binds a loopback port, sends the user's browser to the authorization
+    endpoint, waits for the one redirect back, checks the ``state``, and
+    redeems the code.
+
+    Args:
+        authorization_endpoint: Where to send the browser, from OIDC discovery.
+        token_endpoint: Where to redeem the code, from OIDC discovery.
+        client_id: The public OAuth2 client to sign in as.
+        client: HTTP client for the token exchange.
+        open_browser: How to show the user the authorization URL. Injected so
+            tests need no browser.
+
+    Raises:
+        RuntimeError: Sign-in was refused, timed out, or the callback failed
+            its ``state`` check.
+    """
+    verifier = generate_code_verifier()
+    state = generate_state()
+    server, sink = start_loopback_server()
+    try:
+        redirect_uri = f"http://localhost:{server.server_address[1]}"
+        url = build_authorization_url(
+            authorization_endpoint,
+            client_id=client_id,
+            redirect_uri=redirect_uri,
+            state=state,
+            code_challenge=derive_code_challenge(verifier),
+        )
+        open_browser(url)
+        code = verify_callback(await_callback(server, sink), state)
+    finally:
+        server.server_close()
+    return exchange_code(
+        token_endpoint,
+        code=code,
+        code_verifier=verifier,
+        redirect_uri=redirect_uri,
+        client_id=client_id,
+        client=client,
+    )