onehouse-python-sdk 0.1.0__py3-none-any.whl

onehouse_python_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Onehouse Python SDK — modular data-plane and control-plane clients."""
+
+from . import exceptions
+from .base import SqlClient
+from .lakebase.client import LakebaseClient
+
+__all__ = ["SqlClient", "LakebaseClient", "exceptions"]
+__version__ = "0.1.0"

onehouse_python_sdk/base.py

@@ -0,0 +1,50 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class SqlClient(ABC):
+    """Abstract base for all Onehouse SQL clients.
+
+    Subclasses implement connect() and raw_connection. The convenience methods
+    (execute, fetchall, fetchone) delegate to a raw DB-API 2.0 cursor so that
+    simple one-liners work without boilerplate, while raw_connection provides
+    an escape hatch for advanced use cases (streaming, metadata, etc.).
+    """
+
+    @abstractmethod
+    def connect(self, **kwargs) -> "SqlClient":
+        """Establish the underlying connection and return self."""
+        ...
+
+    @property
+    @abstractmethod
+    def raw_connection(self) -> Any:
+        """The underlying DB-API 2.0 connection object."""
+        ...
+
+    def cursor(self):
+        return self.raw_connection.cursor()
+
+    def execute(self, sql: str, params: Optional[tuple] = None) -> int:
+        cur = self.cursor()
+        cur.execute(sql, params)
+        return cur.rowcount
+
+    def fetchall(self, sql: str, params: Optional[tuple] = None) -> list:
+        cur = self.cursor()
+        cur.execute(sql, params)
+        return cur.fetchall()
+
+    def fetchone(self, sql: str, params: Optional[tuple] = None) -> Optional[tuple]:
+        cur = self.cursor()
+        cur.execute(sql, params)
+        return cur.fetchone()
+
+    def close(self) -> None:
+        self.raw_connection.close()
+
+    def __enter__(self) -> "SqlClient":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

onehouse_python_sdk/exceptions.py

@@ -0,0 +1,10 @@
+class OnehouseSdkError(Exception):
+    pass
+
+
+class ConnectionError(OnehouseSdkError):
+    pass
+
+
+class QueryError(OnehouseSdkError):
+    pass

onehouse_python_sdk/lakebase/__init__.py

@@ -0,0 +1,6 @@
+"""LakeBase subpackage — psycopg2 backend with browser-based auth."""
+
+from .client import LakebaseClient
+from .connection import connect
+
+__all__ = ["LakebaseClient", "connect"]

onehouse_python_sdk/lakebase/auth/__init__.py

@@ -0,0 +1,24 @@
+from .browser_auth import (
+    AuthenticationError,
+    BrowserAuthHandler,
+    DEFAULT_CALLBACK_PATH,
+    DEFAULT_CALLBACK_PORT,
+)
+from .oidc_device_flow import OidcAuthenticationError, OidcDeviceFlowHandler
+from .azure_oauth import AzureOAuthError, AzureOAuthHandler
+from .saml import build_azure_entra_login_url, generate_saml_authn_request
+from .local_auth_server import LocalAuthServer
+
+__all__ = [
+    "AuthenticationError",
+    "AzureOAuthError",
+    "AzureOAuthHandler",
+    "BrowserAuthHandler",
+    "DEFAULT_CALLBACK_PATH",
+    "DEFAULT_CALLBACK_PORT",
+    "LocalAuthServer",
+    "OidcAuthenticationError",
+    "OidcDeviceFlowHandler",
+    "build_azure_entra_login_url",
+    "generate_saml_authn_request",
+]

onehouse_python_sdk/lakebase/auth/_ssl.py

@@ -0,0 +1,23 @@
+"""Shared SSL context that trusts the OS native cert store when available."""
+
+import ssl
+
+
+def default_ssl_context() -> ssl.SSLContext:
+    """Return an SSLContext for outbound HTTPS (token endpoints, IdP).
+
+    Prefers the OS native trust store via the optional ``truststore`` package
+    — required on corporate environments that MITM HTTPS with an internal CA
+    (Zscaler, Netskope, etc.) deployed to the Windows/macOS root store but
+    not to certifi's bundle.  Falls back to certifi, then Python defaults.
+    """
+    try:
+        import truststore
+        return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    except ImportError:
+        pass
+    try:
+        import certifi
+        return ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        return ssl.create_default_context()

onehouse_python_sdk/lakebase/auth/azure_oauth.py

@@ -0,0 +1,194 @@
+"""Azure AD OAuth2 Authorization Code flow (form_post response mode)."""
+
+import base64
+import gzip
+import json
+import logging
+import os
+import secrets
+import urllib.parse
+import urllib.request
+import webbrowser
+import zlib
+from typing import Optional
+
+from ._ssl import default_ssl_context
+from .local_auth_server import LocalAuthServer
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT_SECONDS = 120
+
+
+class AzureOAuthError(Exception):
+    pass
+
+
+class AzureOAuthHandler:
+    """Authenticates via Azure AD OAuth2 Authorization Code flow.
+
+    Azure POSTs the authorization code (form_post response mode), so a local
+    callback server is required.  The token exchange requests a SAML2 token
+    (``requested_token_type=urn:ietf:params:oauth:token-type:saml2``);
+    the result is GZIP-compressed and base64-encoded for the PostgreSQL password.
+    """
+
+    def __init__(
+        self,
+        tenant_id: str,
+        client_id: str,
+        client_secret: str,
+        scope: str = "openid",
+        iam_role_arn: Optional[str] = None,
+        callback_path: str = "/lakebase",
+    ) -> None:
+        self._tenant_id = tenant_id
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._scope = scope or "openid"
+        self._iam_role_arn = iam_role_arn
+        self._callback_path = callback_path
+
+    def authenticate(self, callback_port: int, auth_server: LocalAuthServer) -> dict:
+        """Opens browser, waits for callback, exchanges code for token.
+
+        Returns dict with keys ``user``, ``password``, and optionally ``options``.
+        """
+        state = secrets.token_urlsafe(32)
+        redirect_uri = f"http://localhost:{callback_port}{self._callback_path}"
+        auth_url = self._build_authorization_url(redirect_uri, state)
+
+        webbrowser.open(auth_url)
+        logger.info("=" * 80)
+        logger.info("AZURE AD OAUTH2 AUTHENTICATION REQUIRED")
+        logger.info("=" * 80)
+        logger.info("Please complete authentication in the opened browser window.")
+        logger.info("\nIf the browser didn't open automatically, visit:")
+        logger.info("    %s", auth_url)
+        logger.info("=" * 80)
+
+        event = auth_server.start()
+        if not event.wait(timeout=_DEFAULT_TIMEOUT_SECONDS):
+            raise AzureOAuthError(
+                f"Azure OAuth2 timed out after {_DEFAULT_TIMEOUT_SECONDS}s"
+            )
+
+        callback_data = auth_server.get_result()
+        returned_state = callback_data.get("state")
+        if returned_state != state:
+            raise AzureOAuthError("State parameter mismatch — possible CSRF attack")
+
+        # SAML response posted directly (some Azure Entra configurations)
+        saml_assertion = callback_data.get("SAMLResponse")
+        if saml_assertion:
+            password = base64.b64encode(
+                saml_assertion.encode("utf-8")
+            ).decode("ascii")
+        else:
+            code = callback_data.get("code")
+            if not code:
+                error = callback_data.get("error", "unknown_error")
+                desc = callback_data.get("error_description", "No description")
+                raise AzureOAuthError(f"OAuth2 error: {error} — {desc}")
+            password = self._exchange_code_for_token(code, redirect_uri)
+
+        result = {"user": "user", "password": password}
+        if self._iam_role_arn:
+            result["options"] = f"-c onehouse.lakebase_iam_role={self._iam_role_arn}"
+        return result
+
+    def _build_authorization_url(self, redirect_uri: str, state: str) -> str:
+        base = (
+            f"https://login.microsoftonline.com/{self._tenant_id}/oauth2/v2.0/authorize"
+        )
+        params = {
+            "client_id": self._client_id,
+            "response_type": "code",
+            "response_mode": "form_post",
+            "redirect_uri": redirect_uri,
+            "scope": self._scope,
+            "state": state,
+        }
+        return f"{base}?{urllib.parse.urlencode(params)}"
+
+    def _exchange_code_for_token(self, code: str, redirect_uri: str) -> str:
+        token_url = (
+            f"https://login.microsoftonline.com/{self._tenant_id}/oauth2/token"
+        )
+        params = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+            "redirect_uri": redirect_uri,
+            "resource": self._client_id,
+            "requested_token_type": "urn:ietf:params:oauth:token-type:saml2",
+        }
+        body = urllib.parse.urlencode(params).encode()
+        req = urllib.request.Request(
+            token_url,
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30, context=default_ssl_context()) as resp:
+                data = json.loads(resp.read().decode())
+        except urllib.error.HTTPError as exc:
+            raise AzureOAuthError(
+                f"Token exchange failed ({exc.code}): {exc.read().decode()}"
+            ) from exc
+
+        if "access_token" in data:
+            try:
+                # Azure may use URL-safe base64 (-/_ in place of +/) and strip padding.
+                tok = data["access_token"]
+                tok_padded = tok + "=" * (-len(tok) % 4)
+                saml_bytes = base64.urlsafe_b64decode(tok_padded)
+                try:
+                    # Some tenants return DEFLATE-compressed SAML; others plain XML bytes.
+                    saml_content = zlib.decompress(saml_bytes, -zlib.MAX_WBITS).decode("utf-8")
+                except zlib.error:
+                    saml_content = saml_bytes.decode("utf-8")
+                # Wrap in a proper SAML Response envelope with the
+                # required <samlp:Status> Success element.  STS
+                # AssumeRoleWithSAML requires a full Response, not a
+                # bare Assertion.
+                if "<samlp:Response" not in saml_content and "<Response" not in saml_content:
+                    saml_content = (
+                        '<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">'
+                        '<samlp:Status><samlp:StatusCode '
+                        'Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>'
+                        '</samlp:Status>'
+                        f'{saml_content}'
+                        '</samlp:Response>'
+                    )
+                # Wire encoding: base64(gzip(base64(xml))) — the XML is
+                # base64'd first, then gzipped, then base64'd again.
+                # Confirmed by decoding a password emitted by v7 JDBC.
+                inner_b64 = base64.b64encode(saml_content.encode("utf-8")).decode("ascii")
+                compressed = gzip.compress(inner_b64.encode("utf-8"))
+                return "gzip:" + base64.b64encode(compressed).decode("ascii")
+            except Exception:
+                logger.warning("Could not parse access_token as SAML; treating as opaque token")
+
+        if "id_token" in data:
+            if self._iam_role_arn:
+                self._log_id_token_claims(data["id_token"])
+            return data["id_token"]
+
+        raise AzureOAuthError("Token response missing id_token and access_token")
+
+    def _log_id_token_claims(self, id_token: str) -> None:
+        """Decode and log JWT claims for diagnostics (no signature validation)."""
+        try:
+            parts = id_token.split(".")
+            if len(parts) != 3:
+                return
+            # Add padding
+            payload_b64 = parts[1] + "=" * (-len(parts[1]) % 4)
+            payload = json.loads(base64.urlsafe_b64decode(payload_b64).decode("utf-8"))
+            logger.info("Azure ID token claims: iss=%s aud=%s sub=%s",
+                        payload.get("iss"), payload.get("aud"), payload.get("sub"))
+        except Exception:
+            pass

onehouse_python_sdk/lakebase/auth/browser_auth.py

@@ -0,0 +1,249 @@
+"""Orchestrates all browser-based auth modes and manages a 4-minute credential cache."""
+
+import logging
+import threading
+import time
+import webbrowser
+from typing import Optional
+
+from .azure_oauth import AzureOAuthHandler
+from .local_auth_server import LocalAuthServer
+from .oidc_device_flow import OidcDeviceFlowHandler
+from .saml import build_azure_entra_login_url
+
+logger = logging.getLogger(__name__)
+
+_CREDENTIAL_CACHE_TTL_SECONDS = 240  # 4 minutes
+_AUTH_TIMEOUT_SECONDS = 120
+
+# Property key constants (match Java driver)
+_BROWSER_AUTH = "browser_auth"
+_CALLBACK_PORT = "auth_callback_port"
+_CALLBACK_PATH = "auth_callback_path"
+_REDIRECT_URL = "auth_redirect_url"
+
+_OIDC_CLIENT_ID = "oidc_client_id"
+_OIDC_CLIENT_SECRET = "oidc_client_secret"
+_OIDC_ISSUER_URL = "oidc_issuer_url"
+_OIDC_IAM_ROLE = "oidc_iam_role"
+
+_AZURE_OAUTH_TENANT_ID = "azure_oauth_tenant_id"
+_AZURE_OAUTH_CLIENT_ID = "azure_oauth_client_id"
+_AZURE_OAUTH_CLIENT_SECRET = "azure_oauth_client_secret"
+_AZURE_OAUTH_SCOPE = "azure_oauth_scope"
+_AZURE_OAUTH_IAM_ROLE = "azure_oauth_iam_role"
+
+_AZURE_TENANT_ID = "azure_tenant_id"
+_AZURE_ENTITY_ID = "azure_entity_id"
+
+DEFAULT_CALLBACK_PORT = 8888
+DEFAULT_CALLBACK_PATH = "/lakebase"
+
+
+class AuthenticationError(Exception):
+    pass
+
+
+class _CachedCredentials:
+    def __init__(self, credentials: dict, ttl_seconds: float) -> None:
+        self.credentials = dict(credentials)
+        self._expires_at = time.monotonic() + ttl_seconds
+
+    def is_valid(self) -> bool:
+        return (
+            "user" in self.credentials
+            and "password" in self.credentials
+            and time.monotonic() < self._expires_at
+        )
+
+
+_cache: dict[str, _CachedCredentials] = {}
+_cache_lock = threading.Lock()
+
+
+def _cache_key(database_url: str, props: dict) -> str:
+    return "|".join([
+        database_url,
+        props.get(_REDIRECT_URL, ""),
+        props.get(_AZURE_TENANT_ID, ""),
+        props.get(_OIDC_CLIENT_ID, ""),
+        props.get(_AZURE_OAUTH_CLIENT_ID, ""),
+    ])
+
+
+def _get_callback_port(props: dict) -> int:
+    return int(props.get(_CALLBACK_PORT, DEFAULT_CALLBACK_PORT))
+
+
+def _get_callback_path(props: dict) -> str:
+    return props.get(_CALLBACK_PATH, DEFAULT_CALLBACK_PATH)
+
+
+class BrowserAuthHandler:
+    """Selects and executes the correct auth flow based on connection properties.
+
+    Priority order (matches Java driver):
+    1. OIDC Device Flow  (oidc_client_id + oidc_issuer_url + oidc_iam_role)
+    2. Azure OAuth2      (azure_oauth_tenant_id + azure_oauth_client_id + azure_oauth_client_secret)
+    3. Azure Entra SAML  (azure_tenant_id + azure_entity_id)
+    4. External Redirect (auth_redirect_url)
+    5. Built-in Form     (default)
+    """
+
+    def authenticate(self, database_url: str, props: dict) -> dict:
+        """Return credentials dict (``user``, ``password``, optionally ``options``)."""
+        key = _cache_key(database_url, props)
+        with _cache_lock:
+            cached = _cache.get(key)
+            if cached and cached.is_valid():
+                logger.debug("Returning cached credentials")
+                return dict(cached.credentials)
+
+        credentials = self._do_authenticate(database_url, props)
+
+        with _cache_lock:
+            _cache[key] = _CachedCredentials(credentials, _CREDENTIAL_CACHE_TTL_SECONDS)
+
+        return credentials
+
+    def _do_authenticate(self, database_url: str, props: dict) -> dict:
+        # 1. OIDC Device Flow
+        oidc_client_id = props.get(_OIDC_CLIENT_ID, "").strip()
+        oidc_issuer_url = props.get(_OIDC_ISSUER_URL, "").strip()
+        oidc_iam_role = props.get(_OIDC_IAM_ROLE, "").strip()
+        if oidc_client_id and oidc_issuer_url and oidc_iam_role:
+            return self._authenticate_oidc(props)
+
+        # 2. Azure OAuth2
+        azure_tenant_id = props.get(_AZURE_OAUTH_TENANT_ID, "").strip()
+        azure_client_id = props.get(_AZURE_OAUTH_CLIENT_ID, "").strip()
+        azure_client_secret = props.get(_AZURE_OAUTH_CLIENT_SECRET, "").strip()
+        if azure_tenant_id and azure_client_id and azure_client_secret:
+            return self._authenticate_azure_oauth(props)
+
+        # 3. Azure Entra SAML
+        if props.get(_AZURE_TENANT_ID, "").strip() and props.get(_AZURE_ENTITY_ID, "").strip():
+            return self._authenticate_azure_entra(database_url, props)
+
+        # 4. External redirect
+        if props.get(_REDIRECT_URL, "").strip():
+            return self._authenticate_redirect(database_url, props)
+
+        # 5. Built-in form
+        return self._authenticate_form(database_url, props)
+
+    # ------------------------------------------------------------------
+    # Auth mode implementations
+    # ------------------------------------------------------------------
+
+    def _authenticate_oidc(self, props: dict) -> dict:
+        handler = OidcDeviceFlowHandler(
+            client_id=props[_OIDC_CLIENT_ID],
+            issuer_url=props[_OIDC_ISSUER_URL],
+            iam_role_arn=props[_OIDC_IAM_ROLE],
+            client_secret=props.get(_OIDC_CLIENT_SECRET),
+        )
+        try:
+            return handler.authenticate()
+        except Exception as exc:
+            raise AuthenticationError(f"OIDC authentication failed: {exc}") from exc
+
+    def _authenticate_azure_oauth(self, props: dict) -> dict:
+        port = _get_callback_port(props)
+        path = _get_callback_path(props)
+        auth_server = LocalAuthServer(port=port, callback_path=path)
+        handler = AzureOAuthHandler(
+            tenant_id=props[_AZURE_OAUTH_TENANT_ID],
+            client_id=props[_AZURE_OAUTH_CLIENT_ID],
+            client_secret=props[_AZURE_OAUTH_CLIENT_SECRET],
+            scope=props.get(_AZURE_OAUTH_SCOPE, "openid"),
+            iam_role_arn=props.get(_AZURE_OAUTH_IAM_ROLE),
+            callback_path=path,
+        )
+        try:
+            credentials = handler.authenticate(port, auth_server)
+            return credentials
+        except Exception as exc:
+            raise AuthenticationError(f"Azure OAuth2 authentication failed: {exc}") from exc
+        finally:
+            auth_server.stop()
+
+    def _authenticate_azure_entra(self, database_url: str, props: dict) -> dict:
+        port = _get_callback_port(props)
+        path = _get_callback_path(props)
+        tenant_id = props[_AZURE_TENANT_ID]
+        entity_id = props[_AZURE_ENTITY_ID]
+        acs_url = f"http://localhost:{port}{path}"
+
+        auth_server = LocalAuthServer(port=port, callback_path=path)
+        event = auth_server.start()
+        login_url = build_azure_entra_login_url(tenant_id, acs_url, entity_id)
+
+        webbrowser.open(login_url)
+        logger.info("=" * 80)
+        logger.info("AZURE ENTRA ID SAML AUTHENTICATION REQUIRED")
+        logger.info("=" * 80)
+        logger.info("Please complete authentication in the opened browser window.")
+        logger.info("\nIf the browser didn't open automatically, visit:")
+        logger.info("    %s", login_url)
+        logger.info("=" * 80)
+
+        try:
+            if not event.wait(timeout=_AUTH_TIMEOUT_SECONDS):
+                raise AuthenticationError(
+                    f"Azure Entra SAML timed out after {_AUTH_TIMEOUT_SECONDS}s"
+                )
+            return auth_server.get_result()
+        finally:
+            auth_server.stop()
+
+    def _authenticate_redirect(self, database_url: str, props: dict) -> dict:
+        port = _get_callback_port(props)
+        path = _get_callback_path(props)
+        redirect_url = props[_REDIRECT_URL]
+        callback_url = f"http://localhost:{port}{path}"
+
+        # Replace {callback} placeholder or append redirect_uri param
+        if "{callback}" in redirect_url:
+            auth_url = redirect_url.replace("{callback}", callback_url)
+        else:
+            sep = "&" if "?" in redirect_url else "?"
+            auth_url = f"{redirect_url}{sep}redirect_uri={callback_url}"
+
+        auth_server = LocalAuthServer(port=port, callback_path=path)
+        event = auth_server.start()
+
+        webbrowser.open(auth_url)
+        logger.info("Opening browser for external redirect authentication: %s", auth_url)
+
+        try:
+            if not event.wait(timeout=_AUTH_TIMEOUT_SECONDS):
+                raise AuthenticationError(
+                    f"External redirect auth timed out after {_AUTH_TIMEOUT_SECONDS}s"
+                )
+            return auth_server.get_result()
+        finally:
+            auth_server.stop()
+
+    def _authenticate_form(self, database_url: str, props: dict) -> dict:
+        port = _get_callback_port(props)
+        path = _get_callback_path(props)
+        auth_server = LocalAuthServer(port=port, callback_path=path)
+        event = auth_server.start()
+
+        import urllib.parse as _up
+        auth_url = (
+            f"http://localhost:{port}/auth?"
+            + _up.urlencode({"database": database_url, "title": "LakeBase Authentication"})
+        )
+        webbrowser.open(auth_url)
+        logger.info("Opening built-in login form at: %s", auth_url)
+
+        try:
+            if not event.wait(timeout=_AUTH_TIMEOUT_SECONDS):
+                raise AuthenticationError(
+                    f"Built-in form auth timed out after {_AUTH_TIMEOUT_SECONDS}s"
+                )
+            return auth_server.get_result()
+        finally:
+            auth_server.stop()

onehouse_python_sdk/lakebase/auth/local_auth_server.py

@@ -0,0 +1,237 @@
+"""Local HTTP server that receives OAuth/SAML callbacks and browser form submissions."""
+
+import base64
+import gzip
+import logging
+import threading
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_AUTH_FORM_HTML = """\
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>{title}</title>
+  <style>
+    body {{ font-family: Arial, sans-serif; background: linear-gradient(135deg,#667eea,#764ba2);
+           display:flex; justify-content:center; align-items:center; min-height:100vh; margin:0; }}
+    .card {{ background:#fff; border-radius:12px; padding:40px; width:360px;
+             box-shadow:0 20px 40px rgba(0,0,0,.2); }}
+    h2 {{ color:#333; margin-bottom:24px; text-align:center; }}
+    label {{ display:block; margin-bottom:6px; color:#555; font-size:.9rem; }}
+    input {{ width:100%; padding:10px 12px; margin-bottom:18px; border:1px solid #ddd;
+             border-radius:6px; font-size:1rem; box-sizing:border-box; }}
+    button {{ width:100%; padding:12px; background:#667eea; color:#fff; border:none;
+              border-radius:6px; font-size:1rem; cursor:pointer; }}
+    button:hover {{ background:#5a6fd8; }}
+    .db {{ color:#888; font-size:.8rem; text-align:center; margin-bottom:16px; }}
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h2>{title}</h2>
+    <p class="db">{database}</p>
+    <form method="POST" action="/submit">
+      <label>Username</label>
+      <input type="text" name="username" required autofocus>
+      <label>Password</label>
+      <input type="password" name="password" required>
+      <button type="submit">Sign In</button>
+    </form>
+  </div>
+</body>
+</html>"""
+
+_SUCCESS_HTML = """\
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8"><title>Authentication Successful</title>
+  <style>
+    body {{ font-family:Arial,sans-serif; background:linear-gradient(135deg,#56ab2f,#a8e063);
+           display:flex; justify-content:center; align-items:center; min-height:100vh; margin:0; }}
+    .card {{ background:#fff; border-radius:12px; padding:40px; text-align:center;
+             box-shadow:0 20px 40px rgba(0,0,0,.2); }}
+    .check {{ font-size:4rem; color:#56ab2f; }}
+    h2 {{ color:#333; }}
+    p {{ color:#666; }}
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="check">&#10003;</div>
+    <h2>Authentication Successful</h2>
+    <p>You can close this window and return to your application.</p>
+  </div>
+</body>
+</html>"""
+
+_ERROR_HTML = """\
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Authentication Error</title></head>
+<body><h2>Authentication Error</h2><p>{message}</p></body>
+</html>"""
+
+
+def _gzip_password(decoded_xml: str) -> str:
+    """GZIP-compress the SAML XML and return ``gzip:<base64>``."""
+    compressed = gzip.compress(decoded_xml.encode("utf-8"))
+    return "gzip:" + base64.b64encode(compressed).decode("ascii")
+
+
+def _parse_query_string(query: Optional[str]) -> dict:
+    if not query:
+        return {}
+    return {k: v[0] for k, v in urllib.parse.parse_qs(query, keep_blank_values=True).items()}
+
+
+class LocalAuthServer:
+    """Ephemeral localhost HTTP server for auth callbacks.
+
+    Starts the server in a daemon thread and returns a ``threading.Event``
+    + result dict via ``start()``.  Call ``stop()`` when done.
+    """
+
+    def __init__(self, port: int = 8888, callback_path: str = "/lakebase") -> None:
+        self._port = port
+        self._callback_path = callback_path
+        self._result: dict = {}
+        self._event = threading.Event()
+        self._server: Optional[HTTPServer] = None
+
+    def start(self) -> threading.Event:
+        """Starts the server and returns an Event that is set when credentials arrive."""
+        handler_factory = self._make_handler()
+        try:
+            self._server = HTTPServer(("localhost", self._port), handler_factory)
+        except OSError as exc:
+            raise RuntimeError(
+                f"Could not start local auth server on port {self._port}: {exc}"
+            ) from exc
+
+        thread = threading.Thread(
+            target=self._server.serve_forever, kwargs={"poll_interval": 0.1}, daemon=True
+        )
+        thread.start()
+        logger.info("Local auth server started on port %d", self._port)
+        return self._event
+
+    def stop(self) -> None:
+        if self._server:
+            self._shutdown()
+
+    def _shutdown(self) -> None:
+        """Shut down the HTTP server in a background thread.
+
+        shutdown() blocks until serve_forever() exits its poll loop, so we
+        run it off the main thread to avoid stalling the caller.
+        """
+        server = self._server
+        self._server = None
+        threading.Thread(target=server.shutdown, daemon=True).start()
+        logger.info("Local auth server stopped")
+
+    def get_result(self) -> dict:
+        return self._result
+
+    def _make_handler(self):
+        server_ref = self
+
+        class _Handler(BaseHTTPRequestHandler):
+            def log_message(self, fmt, *args):  # silence default request logs
+                pass
+
+            def _send(self, status: int, body: str, content_type: str = "text/html") -> None:
+                encoded = body.encode("utf-8")
+                self.send_response(status)
+                self.send_header("Content-Type", f"{content_type}; charset=utf-8")
+                self.send_header("Content-Length", str(len(encoded)))
+                self.end_headers()
+                self.wfile.write(encoded)
+
+            def do_GET(self):
+                parsed = urllib.parse.urlparse(self.path)
+                if parsed.path == "/auth":
+                    params = _parse_query_string(parsed.query)
+                    database = params.get("database", "Unknown Database")
+                    title = params.get("title", "Database Authentication")
+                    html = _AUTH_FORM_HTML.format(title=title, database=database)
+                    self._send(200, html)
+                elif parsed.path == server_ref._callback_path:
+                    params = _parse_query_string(parsed.query)
+                    self._handle_callback(params)
+                else:
+                    self._send(404, "Not found")
+
+            def do_POST(self):
+                length = int(self.headers.get("Content-Length", 0))
+                body = self.rfile.read(length).decode("utf-8")
+                params = _parse_query_string(body)
+
+                if self.path == "/submit":
+                    username = params.get("username", "").strip()
+                    password = params.get("password", "").strip()
+                    if not username:
+                        self._send(400, _ERROR_HTML.format(message="Username is required"))
+                        return
+                    if not password:
+                        self._send(400, _ERROR_HTML.format(message="Password is required"))
+                        return
+                    server_ref._result = {"user": username, "password": password}
+                    self._send(200, _SUCCESS_HTML)
+                    server_ref._shutdown()
+                    server_ref._event.set()
+                elif self.path == server_ref._callback_path:
+                    self._handle_callback(params)
+                else:
+                    self._send(404, "Not found")
+
+            def _handle_callback(self, params: dict) -> None:
+                if "SAMLResponse" in params:
+                    logger.info("Processing SAML response")
+                    try:
+                        saml_b64 = params["SAMLResponse"]
+                        decoded_xml = base64.b64decode(saml_b64).decode("utf-8")
+                        encoded_password = _gzip_password(decoded_xml)
+                        server_ref._result = {"user": "user", "password": encoded_password}
+                        self._send(200, _SUCCESS_HTML)
+                    except Exception as exc:
+                        logger.error("Error processing SAML response: %s", exc)
+                        self._send(500, _ERROR_HTML.format(message=str(exc)))
+                    finally:
+                        server_ref._shutdown()
+                        server_ref._event.set()
+                elif "code" in params:
+                    logger.info("Processing OAuth2 authorization code")
+                    server_ref._result = dict(params)
+                    self._send(200, _SUCCESS_HTML)
+                    server_ref._shutdown()
+                    server_ref._event.set()
+                else:
+                    # Generic credential extraction
+                    username = next(
+                        (params[k] for k in ("username", "user", "login", "email") if k in params),
+                        "user",
+                    )
+                    password = next(
+                        (
+                            params[k]
+                            for k in ("password", "pass", "access_token", "token")
+                            if k in params
+                        ),
+                        None,
+                    )
+                    if password:
+                        server_ref._result = {"user": username, "password": password}
+                        self._send(200, _SUCCESS_HTML)
+                        server_ref._shutdown()
+                        server_ref._event.set()
+                    else:
+                        self._send(400, _ERROR_HTML.format(message="No credentials received"))
+
+        return _Handler

onehouse_python_sdk/lakebase/auth/oidc_device_flow.py

@@ -0,0 +1,167 @@
+"""OIDC Device Authorization Grant (RFC 8628) for Okta/Auth0."""
+
+import time
+import urllib.parse
+import urllib.request
+import json
+import webbrowser
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+from ._ssl import default_ssl_context
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT_SECONDS = 300
+_DEFAULT_POLL_INTERVAL_SECONDS = 5
+
+
+@dataclass
+class _DeviceCodeResponse:
+    device_code: str
+    verification_uri_complete: str
+    interval: int
+    expires_in: int
+    user_code: Optional[str] = None
+    verification_uri: Optional[str] = None
+
+
+class OidcAuthenticationError(Exception):
+    pass
+
+
+class OidcDeviceFlowHandler:
+    """Authenticates via OIDC Device Authorization Grant.
+
+    Opens a browser for the user to complete authentication, then polls the
+    token endpoint until the user approves or the request times out.
+    Sets the PostgreSQL ``options`` parameter to carry the IAM role ARN.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        issuer_url: str,
+        iam_role_arn: str,
+        client_secret: Optional[str] = None,
+    ) -> None:
+        if not iam_role_arn or not iam_role_arn.strip():
+            raise ValueError("iam_role_arn is required for OIDC authentication")
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._issuer_url = issuer_url.rstrip("/")
+        self._iam_role_arn = iam_role_arn
+
+    def authenticate(self) -> dict:
+        """Returns dict with keys ``user``, ``password``, ``options``."""
+        try:
+            device_code = self._request_device_code()
+            self._open_browser(device_code.verification_uri_complete)
+            logger.info("=" * 80)
+            logger.info("OIDC AUTHENTICATION REQUIRED")
+            logger.info("=" * 80)
+            logger.info("Please complete authentication in the opened browser window.")
+            logger.info("\nIf the browser didn't open automatically, visit:")
+            logger.info("    %s", device_code.verification_uri_complete)
+            logger.info("=" * 80)
+            id_token = self._poll_for_token(device_code.device_code, device_code.interval)
+            return {
+                "user": "user",
+                "password": id_token,
+                "options": f"-c onehouse.lakebase_iam_role={self._iam_role_arn}",
+            }
+        except OidcAuthenticationError:
+            raise
+        except Exception as exc:
+            raise OidcAuthenticationError(f"OIDC authentication failed: {exc}") from exc
+
+    def _request_device_code(self) -> _DeviceCodeResponse:
+        url = f"{self._issuer_url}/oauth2/v1/device/authorize"
+        params: dict = {
+            "client_id": self._client_id,
+            "scope": "openid profile offline_access groups",
+        }
+        if self._client_secret:
+            params["client_secret"] = self._client_secret
+
+        body = urllib.parse.urlencode(params).encode()
+        req = urllib.request.Request(
+            url,
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=30, context=default_ssl_context()) as resp:
+            data = json.loads(resp.read().decode())
+
+        return _DeviceCodeResponse(
+            device_code=data["device_code"],
+            verification_uri=data.get("verification_uri"),
+            verification_uri_complete=data.get(
+                "verification_uri_complete", data.get("verification_uri", "")
+            ),
+            user_code=data.get("user_code"),
+            expires_in=data.get("expires_in", _DEFAULT_TIMEOUT_SECONDS),
+            interval=data.get("interval", _DEFAULT_POLL_INTERVAL_SECONDS),
+        )
+
+    def _open_browser(self, url: str) -> None:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass  # Best-effort — user can navigate manually
+
+    def _poll_for_token(self, device_code: str, interval_seconds: int) -> str:
+        token_url = f"{self._issuer_url}/oauth2/v1/token"
+        elapsed = 0
+        interval = interval_seconds
+
+        while elapsed < _DEFAULT_TIMEOUT_SECONDS:
+            params: dict = {
+                "client_id": self._client_id,
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": device_code,
+            }
+            if self._client_secret:
+                params["client_secret"] = self._client_secret
+
+            body = urllib.parse.urlencode(params).encode()
+            req = urllib.request.Request(
+                token_url,
+                data=body,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=30, context=default_ssl_context()) as resp:
+                    data = json.loads(resp.read().decode())
+                if "id_token" in data:
+                    return data["id_token"]
+                if "access_token" in data:
+                    return data["access_token"]
+                raise OidcAuthenticationError(
+                    "Token response missing id_token and access_token"
+                )
+            except urllib.error.HTTPError as exc:
+                if exc.code == 400:
+                    error_body = json.loads(exc.read().decode())
+                    error = error_body.get("error", "unknown_error")
+                    if error == "authorization_pending":
+                        time.sleep(interval)
+                        elapsed += interval
+                        continue
+                    elif error == "slow_down":
+                        interval += 5
+                        time.sleep(interval)
+                        elapsed += interval
+                        continue
+                    else:
+                        raise OidcAuthenticationError(
+                            f"OIDC token error: {error}"
+                        ) from exc
+                raise
+
+        raise OidcAuthenticationError(
+            f"OIDC authentication timed out after {_DEFAULT_TIMEOUT_SECONDS}s"
+        )

onehouse_python_sdk/lakebase/auth/saml.py

@@ -0,0 +1,43 @@
+"""SAML AuthnRequest generation for Microsoft Entra ID (Azure AD SAML flow)."""
+
+import base64
+import uuid
+import zlib
+import urllib.parse
+from datetime import datetime, timezone
+
+
+def generate_saml_authn_request(acs_url: str, issuer: str, destination: str) -> str:
+    """Build, deflate-compress, base64-encode, and URL-encode a SAML AuthnRequest.
+
+    Uses raw DEFLATE (zlib wbits=-15) to match Java's ``Deflater(nowrap=True)``.
+    """
+    request_id = f"_{uuid.uuid4()}"
+    issue_instant = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    saml_request = (
+        f'<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" '
+        f'xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" '
+        f'ID="{request_id}" '
+        f'Version="2.0" '
+        f'IssueInstant="{issue_instant}" '
+        f'Destination="{destination}" '
+        f'AssertionConsumerServiceURL="{acs_url}" '
+        f'ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">'
+        f'<saml:Issuer>{issuer}</saml:Issuer>'
+        f'<samlp:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" '
+        f'AllowCreate="true"/>'
+        f'</samlp:AuthnRequest>'
+    )
+
+    # Raw DEFLATE (no zlib/gzip headers) — matches Java Deflater(nowrap=true)
+    compressed = zlib.compress(saml_request.encode("utf-8"))[2:-4]
+    b64_encoded = base64.b64encode(compressed).decode("ascii")
+    return urllib.parse.quote_plus(b64_encoded)
+
+
+def build_azure_entra_login_url(tenant_id: str, acs_url: str, entity_id: str) -> str:
+    """Return the full Azure Entra SAML login URL with an embedded AuthnRequest."""
+    destination = f"https://login.microsoftonline.com/{tenant_id}/saml2"
+    saml_request = generate_saml_authn_request(acs_url, entity_id, destination)
+    return f"{destination}?SAMLRequest={saml_request}"

onehouse_python_sdk/lakebase/client.py

@@ -0,0 +1,29 @@
+from onehouse_python_sdk.base import SqlClient
+from onehouse_python_sdk.exceptions import ConnectionError
+
+
+class LakebaseClient(SqlClient):
+    """psycopg2-backed client for LakeBase (PostgreSQL-compatible).
+
+    Requires the [lakebase] extra:  pip install onehouse-python-sdk[lakebase]
+
+    Supports all browser-based auth flows (OIDC, Azure OAuth2, SAML, form)
+    via the browser_auth=true connection parameter.
+    """
+
+    def __init__(self):
+        self._conn = None
+
+    def connect(self, dsn=None, **kwargs) -> "LakebaseClient":
+        try:
+            from onehouse_python_sdk.lakebase.connection import connect as _connect
+        except ImportError as exc:
+            raise ConnectionError(
+                "lakebase extra not installed. Run: pip install onehouse-python-sdk[lakebase]"
+            ) from exc
+        self._conn = _connect(dsn=dsn, **kwargs)
+        return self
+
+    @property
+    def raw_connection(self):
+        return self._conn

onehouse_python_sdk/lakebase/connection.py

@@ -0,0 +1,145 @@
+"""Main connection entry point — wraps psycopg2 with browser-auth support."""
+
+import logging
+import urllib.parse
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Property key for triggering browser auth
+_BROWSER_AUTH = "browser_auth"
+
+
+def connect(dsn: Optional[str] = None, **kwargs):
+    """Connect to a LakeBase (PostgreSQL) database, handling browser-based auth.
+
+    All arguments are forwarded to ``psycopg2.connect()``.  When the
+    connection string or kwargs include ``browser_auth=true``, credentials
+    are obtained via the appropriate browser-based auth flow before the
+    underlying connection is established.
+
+    Returns a psycopg2 connection object.
+
+    Example::
+
+        import lakebase
+        conn = lakebase.connect(
+            host="my-cluster.lakebase.io",
+            port=5432,
+            dbname="mydb",
+            browser_auth="true",
+            oidc_client_id="...",
+            oidc_issuer_url="https://...",
+            oidc_iam_role="arn:aws:iam::...",
+        )
+    """
+    try:
+        import psycopg2
+    except ImportError as exc:
+        raise ImportError(
+            "psycopg2 is required: pip install psycopg2-binary"
+        ) from exc
+
+    # Parse DSN if provided so we can inspect/modify properties
+    props: dict = {}
+    if dsn:
+        props.update(_parse_dsn(dsn))
+    props.update(kwargs)
+
+    # Check if browser_auth is requested
+    browser_auth_flag = str(props.get(_BROWSER_AUTH, "false")).lower()
+    if browser_auth_flag in ("true", "1", "yes"):
+        props = _apply_browser_auth(props)
+
+    # Rebuild call args for psycopg2
+    return _psycopg2_connect(props)
+
+
+def _apply_browser_auth(props: dict) -> dict:
+    """Authenticate via browser flow and inject credentials into props."""
+    from .auth.browser_auth import BrowserAuthHandler
+
+    database_url = _build_database_url(props)
+    handler = BrowserAuthHandler()
+    credentials = handler.authenticate(database_url, props)
+
+    result = dict(props)
+    result["user"] = credentials["user"]
+    result["password"] = credentials["password"]
+
+    # Set options from auth handler (e.g. IAM role) — merge with existing
+    if "options" in credentials:
+        existing = result.get("options", "")
+        result["options"] = (
+            f"{existing} {credentials['options']}".strip()
+            if existing
+            else credentials["options"]
+        )
+
+    # Strip browser-auth-specific keys that psycopg2 doesn't understand
+    for key in (
+        "browser_auth",
+        "auth_callback_port",
+        "auth_callback_path",
+        "auth_redirect_url",
+        "oidc_client_id",
+        "oidc_client_secret",
+        "oidc_issuer_url",
+        "oidc_iam_role",
+        "azure_oauth_tenant_id",
+        "azure_oauth_client_id",
+        "azure_oauth_client_secret",
+        "azure_oauth_scope",
+        "azure_oauth_iam_role",
+        "azure_tenant_id",
+        "azure_entity_id",
+    ):
+        result.pop(key, None)
+
+    return result
+
+
+def _build_database_url(props: dict) -> str:
+    host = props.get("host", "localhost")
+    port = props.get("port", 5432)
+    dbname = props.get("dbname") or props.get("database", "")
+    return f"postgresql://{host}:{port}/{dbname}"
+
+
+def _parse_dsn(dsn: str) -> dict:
+    """Parse a PostgreSQL DSN into a kwargs dict."""
+    # Handle postgresql:// / postgres:// URI form
+    if dsn.startswith(("postgresql://", "postgres://")):
+        parsed = urllib.parse.urlparse(dsn)
+        result: dict = {}
+        if parsed.hostname:
+            result["host"] = parsed.hostname
+        if parsed.port:
+            result["port"] = parsed.port
+        if parsed.username:
+            result["user"] = urllib.parse.unquote(parsed.username)
+        if parsed.password:
+            result["password"] = urllib.parse.unquote(parsed.password)
+        if parsed.path and parsed.path.lstrip("/"):
+            result["dbname"] = parsed.path.lstrip("/")
+        # Query string params (e.g. ?browser_auth=true&oidc_client_id=...)
+        if parsed.query:
+            for k, v in urllib.parse.parse_qs(parsed.query, keep_blank_values=True).items():
+                result[k] = v[0]
+        return result
+
+    # Handle key=value DSN form
+    result = {}
+    for token in dsn.split():
+        if "=" in token:
+            k, _, v = token.partition("=")
+            result[k.strip()] = v.strip().strip("'\"")
+    return result
+
+
+def _psycopg2_connect(props: dict):
+    """Call psycopg2.connect() with the resolved props dict."""
+    import psycopg2
+
+    # psycopg2 accepts keyword arguments directly
+    return psycopg2.connect(**props)

onehouse_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: onehouse-python-sdk
+Version: 0.1.0
+Summary: Onehouse Python SDK — modular data-plane clients for LakeBase and beyond
+Project-URL: Homepage, https://github.com/onehouseinc/onehouse-python-sdk
+Project-URL: Repository, https://github.com/onehouseinc/onehouse-python-sdk
+Project-URL: Issues, https://github.com/onehouseinc/onehouse-python-sdk/issues
+Author-email: Onehouse Team <eng@onehouse.ai>
+License: Proprietary
+Keywords: auth,azure,lakebase,oauth2,oidc,onehouse,postgresql,saml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: lakebase
+Requires-Dist: certifi>=2024.1; extra == 'lakebase'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'lakebase'
+Description-Content-Type: text/markdown
+
+# onehouse-python-sdk
+
+Python SDK for connecting to [Onehouse](https://www.onehouse.ai) data-plane services.
+
+The base package has **zero required dependencies**. Drivers ship as optional extras so you only install what you need.
+
+```bash
+pip install onehouse-python-sdk[lakebase]
+```
+
+## LakeBase
+
+LakeBase is Onehouse's PostgreSQL-compatible managed lakehouse engine. This SDK provides a `psycopg2`-backed client that handles the browser-based and federated authentication flows LakeBase clusters require, on top of standard username/password auth.
+
+### Installation
+
+```bash
+pip install onehouse-python-sdk[lakebase]
+```
+
+Requires Python 3.9+.
+
+### Quickstart
+
+```python
+from onehouse_python_sdk import LakebaseClient
+
+# Username / password
+with LakebaseClient().connect(
+    host="<cluster-host>",
+    port=5432,
+    dbname="mydb",
+    user="admin",
+    password="secret",
+) as client:
+    rows = client.fetchall("SELECT * FROM mytable WHERE id = %s", (42,))
+```
+
+### Authentication flows
+
+| Flow | Parameters |
+|------|------------|
+| Username / password | `user`, `password` |
+| OIDC Device Flow (Okta / Auth0) | `browser_auth=true`, `oidc_client_id`, `oidc_issuer_url`, `oidc_iam_role` |
+| Azure AD OAuth2 | `browser_auth=true`, `azure_oauth_tenant_id`, `azure_oauth_client_id`, `azure_oauth_client_secret` |
+| Azure Entra ID SAML | `browser_auth=true`, `azure_tenant_id`, `azure_entity_id` |
+| Built-in login form | `browser_auth=true` _(default when no IdP params are set)_ |
+| External redirect | `browser_auth=true`, `auth_redirect_url` |
+
+```python
+# OIDC Device Flow
+client = LakebaseClient().connect(
+    host="<cluster-host>",
+    port=5432,
+    dbname="mydb",
+    browser_auth="true",
+    oidc_client_id="0oaXXXXX",
+    oidc_issuer_url="https://myorg.okta.com",
+    oidc_iam_role="arn:aws:iam::123456789012:role/LakeBaseRole",
+)
+
+# Azure AD OAuth2
+client = LakebaseClient().connect(
+    host="<cluster-host>",
+    port=5432,
+    dbname="mydb",
+    browser_auth="true",
+    azure_oauth_tenant_id="your-tenant-id",
+    azure_oauth_client_id="your-client-id",
+    azure_oauth_client_secret="your-client-secret",
+)
+```
+
+DSN string form is also supported:
+
+```python
+client = LakebaseClient().connect(
+    "postgresql://<cluster-host>:5432/mydb"
+    "?browser_auth=true"
+    "&oidc_client_id=0oaXXXX"
+    "&oidc_issuer_url=https://myorg.okta.com"
+    "&oidc_iam_role=arn:aws:iam::123456789012:role/LakeBaseRole"
+)
+```
+
+### Client API
+
+All clients implement the `SqlClient` interface:
+
+| Method | Description |
+|--------|-------------|
+| `connect(dsn=None, **kwargs) → self` | Establish connection, returns self for chaining |
+| `execute(sql, params)` | Run a statement, return rowcount |
+| `fetchall(sql, params)` | Run a query, return `list[tuple]` |
+| `fetchone(sql, params)` | Run a query, return first row or `None` |
+| `cursor()` | Raw cursor for advanced use |
+| `raw_connection` | Underlying `psycopg2` connection |
+| `close()` | Close the connection |
+| `__enter__` / `__exit__` | Context manager — closes on exit |
+
+### Notes
+
+- **Credential caching** — auth tokens are cached for 4 minutes per connection parameters to avoid repeated browser prompts within the same process.
+- **Callback port** — the local auth callback server defaults to port `8888` at path `/lakebase`. Override with `auth_callback_port` and `auth_callback_path`.

onehouse_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+onehouse_python_sdk/__init__.py,sha256=dqWPAKgpPXybXnRqpmwvMLYABtvIh9bSadlMvPhX-dc,253
+onehouse_python_sdk/base.py,sha256=BvgJ80SFIIZDTUbZn_RccDvprDqBI2bxHo8MDHECSfI,1508
+onehouse_python_sdk/exceptions.py,sha256=5WgiJ5sTJ7hh7xdRZOhB5luGLzq0a1JnFYz6ebY34xI,143
+onehouse_python_sdk/lakebase/__init__.py,sha256=mTvTzW-UOwSJR8rqulAzVnsSWwr3q_6LkhUAxwJ2PBg,181
+onehouse_python_sdk/lakebase/client.py,sha256=AYFfhdB-CVqSWBJ6KKFbxLU-r-FKSpg8L-5niKfGi6Q,964
+onehouse_python_sdk/lakebase/connection.py,sha256=XSgtBb1ZZorgRH1FAIIKYFfRVuN3pp5ncAbmXOvGvdg,4604
+onehouse_python_sdk/lakebase/auth/__init__.py,sha256=TLx2JQubHombUAJ9anWWnGnaxzoqTJSYA129YJVtYM8,719
+onehouse_python_sdk/lakebase/auth/_ssl.py,sha256=iJUCuMsWizPWarkU3pkEFFj4hnVMOR1wX6rqBsEAdCo,824
+onehouse_python_sdk/lakebase/auth/azure_oauth.py,sha256=_aObA5jK6e9vx6SRJXpr5ygkiFwMcdwQOSL29zKuSpk,7943
+onehouse_python_sdk/lakebase/auth/browser_auth.py,sha256=4ZsPwM3RArx5-o5pRakumjBGJ1Wd20UIUDFjuh77vEk,9282
+onehouse_python_sdk/lakebase/auth/local_auth_server.py,sha256=Kx9PuKmSOC5d93gOk-xXz25nifhzydGYsvRhEbCTQok,9500
+onehouse_python_sdk/lakebase/auth/oidc_device_flow.py,sha256=NpUsHpIycIiuNQEMGlNkq796hCGTVOP1sNS7rJQHwF8,6197
+onehouse_python_sdk/lakebase/auth/saml.py,sha256=pRWtMkELDpALn_0rHZTFbPHArNkNW9CQbOyxHcrHqrA,1842
+onehouse_python_sdk-0.1.0.dist-info/METADATA,sha256=VbnNMH9sIWbh7Qc16XBcFkMz_-HPrT8592i0XuZOmCo,4719
+onehouse_python_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+onehouse_python_sdk-0.1.0.dist-info/RECORD,,

onehouse_python_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any