sunstone-data-platform 1.2.0__tar.gz → 1.3.0__tar.gz

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/.gitignore

@@ -20,3 +20,4 @@ security-prompts/
 /research-stack
 /target/
 CLAUDE.local.md
+/.sunstone

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sunstone-data-platform
-Version: 1.2.0
+Version: 1.3.0
 Summary: Sunstone Data Platform - Data lakehouse with semantic metadata
 Author-email: Sunstone Institute <stig@sunstone.institute>
 License-Expression: MIT
@@ -9,6 +9,7 @@ Requires-Dist: charset-normalizer>=3.4.0
 Requires-Dist: duckdb>=1.5.3
 Requires-Dist: fastexcel>=0.20.2
 Requires-Dist: httpx>=0.27.0
+Requires-Dist: keyring>=25
 Requires-Dist: publicsuffixlist>=1.0.2.20261003
 Requires-Dist: pyiceberg[duckdb,gcsfs,s3fs]>=0.10.0
 Requires-Dist: python-dateutil>=2.9.0.post0
@@ -199,7 +200,7 @@ uv run pytest tests/unit/test_query.py -v
 
 | Command | Description |
 |---------|-------------|
-| `sunstone data login`, `logout`, `whoami` | Sign in to graph-server (Keycloak) |
+| `sunstone auth login`, `logout`, `whoami` | Sign in to graph-server (Keycloak) |
 | `sunstone data ls [namespace]` | List namespaces and tables |
 | `sunstone data show <table>` | Dataset metadata from the graph (table, Turtle or JSON-LD) |
 | `sunstone data info [table]` | Iceberg table properties for one or all datasets |
@@ -297,11 +298,13 @@ graph-server publishes the OIDC issuer and public client id at
 
 ```bash
 sunstone env init          # cache discovery for configured environments
-sunstone data login        # browser sign-in (authorization code + PKCE)
+sunstone auth login        # browser sign-in (authorization code + PKCE)
 ```
 
 A browser window opens for Keycloak SSO; the refresh token renews silently
-until the SSO session expires.
+until the SSO session expires. The refresh token is stored in the OS keyring
+(macOS Keychain, Windows Credential Locker, Linux Secret Service). Without a
+usable keyring it falls back to a mode-0600 file under `~/.cache/sunstone/`.
 
 ### Services (CI, automation)
 

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/README.md

@@ -173,7 +173,7 @@ uv run pytest tests/unit/test_query.py -v
 
 | Command | Description |
 |---------|-------------|
-| `sunstone data login`, `logout`, `whoami` | Sign in to graph-server (Keycloak) |
+| `sunstone auth login`, `logout`, `whoami` | Sign in to graph-server (Keycloak) |
 | `sunstone data ls [namespace]` | List namespaces and tables |
 | `sunstone data show <table>` | Dataset metadata from the graph (table, Turtle or JSON-LD) |
 | `sunstone data info [table]` | Iceberg table properties for one or all datasets |
@@ -271,11 +271,13 @@ graph-server publishes the OIDC issuer and public client id at
 
 ```bash
 sunstone env init          # cache discovery for configured environments
-sunstone data login        # browser sign-in (authorization code + PKCE)
+sunstone auth login        # browser sign-in (authorization code + PKCE)
 ```
 
 A browser window opens for Keycloak SSO; the refresh token renews silently
-until the SSO session expires.
+until the SSO session expires. The refresh token is stored in the OS keyring
+(macOS Keychain, Windows Credential Locker, Linux Secret Service). Without a
+usable keyring it falls back to a mode-0600 file under `~/.cache/sunstone/`.
 
 ### Services (CI, automation)
 

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "python-slugify>=8.0.0",
     "python-dateutil>=2.9.0.post0",
     "publicsuffixlist>=1.0.2.20261003",
+    "keyring>=25",
 ]
 
 [project.entry-points."sunstone.plugins"]

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.0'
-__version_tuple__ = version_tuple = (1, 2, 0)
+__version__ = version = '1.3.0'
+__version_tuple__ = version_tuple = (1, 3, 0)
 
 __commit_id__ = commit_id = None

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/auth/__init__.py

@@ -12,8 +12,9 @@ health, the UI and public views. Two ways to get one:
 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.
+Access tokens live in memory only. The refresh token is the sole credential
+kept between runs: in the OS keyring, or a mode-0600 file when no keyring is
+usable.
 """
 
 from sunstone_data.auth.client_creds import (

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/auth/pkce.py

@@ -13,7 +13,7 @@ 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
+This is the flow behind ``sunstone auth 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.
 """

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/auth/stepup.py

@@ -86,7 +86,7 @@ def step_up(
         raise StepUpRequired("writes to main need a passkey sign-in; a service credential cannot step up")
     session = store.read_session(env_name)
     if session is None:
-        raise StepUpRequired(f"writes to main need a passkey sign-in; run `sunstone data login` for {env_name!r}")
+        raise StepUpRequired(f"writes to main need a passkey sign-in; run `sunstone auth login` for {env_name!r}")
     issuer = session.issuer or discovered_issuer(env_name, settings.graph_url)
     authorization_endpoint = discover_authorization_endpoint(issuer, client)
     token_endpoint = discover_token_endpoint(issuer, client)

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/auth/store.py

@@ -1,30 +1,40 @@
 """Per-environment cache for a human login session.
 
-Holds the OAuth2 refresh token from ``sunstone data login`` so a user logs in
+Holds the OAuth2 refresh token from ``sunstone auth login`` so a user logs in
 once per environment. Access tokens are never stored here — they are minted on
 demand and kept in memory only.
 
-The file lives next to the discovery cache but one level down, so the two
-never collide::
+The refresh token goes in the OS keyring (macOS Keychain, Windows Credential
+Locker, Secret Service on Linux) under service ``sunstone-data-platform`` and
+the environment name. The rest of the session (issuer, client id, time) goes
+in a file next to the discovery cache, one level down so the two never
+collide::
 
     $XDG_CACHE_HOME/sunstone/data-platform/auth/{env_name}.json
 
-It is written atomically and chmod'ed ``0600``: a refresh token is a
-long-lived credential, so no other user on the machine may read it.
+When no keyring is usable (e.g. a headless Linux box), the refresh token is
+written into that file instead. The file is always written atomically and
+chmod'ed ``0600``, so no other user on the machine can read it.
 """
 
 from __future__ import annotations
 
 import json
+import logging
 import os
 import tempfile
 import time
 from dataclasses import asdict, dataclass, field, fields
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 #: Mode a session file must end up with — owner read/write only.
 SESSION_FILE_MODE = 0o600
 
+#: Keyring service name; the keyring username is the environment name.
+KEYRING_SERVICE = "sunstone-data-platform"
+
 
 @dataclass(frozen=True)
 class Session:
@@ -53,18 +63,56 @@ def session_path(env_name: str) -> Path:
     return _auth_dir() / f"{env_name}.json"
 
 
+def _keyring_set(env_name: str, token: str) -> bool:
+    """Store ``token`` in the OS keyring. Returns False if no keyring is usable."""
+    try:
+        import keyring
+
+        keyring.set_password(KEYRING_SERVICE, env_name, token)
+    except Exception:
+        logger.debug("OS keyring not usable", exc_info=True)
+        return False
+    return True
+
+
+def _keyring_get(env_name: str) -> str | None:
+    try:
+        import keyring
+
+        return keyring.get_password(KEYRING_SERVICE, env_name)
+    except Exception:
+        logger.debug("OS keyring not usable", exc_info=True)
+        return None
+
+
+def _keyring_delete(env_name: str) -> None:
+    try:
+        import keyring
+
+        keyring.delete_password(KEYRING_SERVICE, env_name)
+    except Exception:
+        # Missing entry or no usable keyring: nothing to delete either way.
+        logger.debug("No keyring entry deleted", exc_info=True)
+
+
 def write_session(env_name: str, session: Session) -> Path:
     """Persist a login session, atomically and mode 0600.
 
-    Returns the path written.
+    The refresh token goes in the OS keyring when one is usable, else in the
+    session file. Returns the path written.
     """
     path = session_path(env_name)
+    data = asdict(session)
+    if _keyring_set(env_name, session.refresh_token):
+        del data["refresh_token"]
+    else:
+        logger.warning("No usable OS keyring; storing the refresh token in %s (mode 0600)", path)
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, tmp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
     try:
         os.chmod(tmp_name, SESSION_FILE_MODE)
         with os.fdopen(fd, "w", encoding="utf-8") as f:
-            json.dump(asdict(session), f, indent=2)
+            json.dump(data, f, indent=2)
         os.replace(tmp_name, path)
     except Exception:
         Path(tmp_name).unlink(missing_ok=True)
@@ -76,7 +124,10 @@ def write_session(env_name: str, session: Session) -> Path:
 
 
 def read_session(env_name: str) -> Session | None:
-    """Load a cached login session. Returns None if missing or unreadable."""
+    """Load a cached login session. Returns None if missing or unreadable.
+
+    A refresh token in the file (keyring fallback) wins over the keyring.
+    """
     try:
         with open(session_path(env_name), encoding="utf-8") as f:
             data = json.load(f)
@@ -86,6 +137,11 @@ def read_session(env_name: str) -> Session | None:
         return None
     field_names = {f.name for f in fields(Session)}
     kwargs = {k: v for k, v in data.items() if k in field_names}
+    if not kwargs.get("refresh_token"):
+        token = _keyring_get(env_name)
+        if token is None:
+            return None
+        kwargs["refresh_token"] = token
     try:
         return Session(**kwargs)
     except TypeError:
@@ -95,3 +151,4 @@ def read_session(env_name: str) -> Session | None:
 def clear_session(env_name: str) -> None:
     """Remove the cached session for an environment, if any."""
     session_path(env_name).unlink(missing_ok=True)
+    _keyring_delete(env_name)

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/cli/_app.py

@@ -21,6 +21,9 @@ app = typer.Typer(
 data_app = typer.Typer(help="Data operations")
 app.add_typer(data_app, name="data")
 
+auth_app = typer.Typer(help="Sign in to the data platform")
+app.add_typer(auth_app, name="auth")
+
 console = Console()
 
-__all__ = ["app", "data_app", "console"]
+__all__ = ["app", "auth_app", "data_app", "console"]

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/cli/commands/data_auth.py

@@ -1,16 +1,16 @@
-"""``sunstone data login`` / ``logout`` / ``whoami`` — human sign-in sessions.
+"""``sunstone auth login`` / ``logout`` / ``whoami`` — human sign-in sessions.
 
 ``login`` runs the PKCE browser flow (:mod:`sunstone_data.auth.pkce`) and
-caches only the refresh token, per environment, mode 0600. Access tokens are
-minted on demand and never touch disk, so ``whoami`` reports what was cached,
-not live token claims.
+caches only the refresh token, per environment, in the OS keyring (see
+:mod:`sunstone_data.auth.store`). Access tokens are minted on demand and never
+stored, so ``whoami`` reports what was cached, not live token claims.
 """
 
 from __future__ import annotations
 
 import typer
 
-from sunstone_data.cli._app import console, data_app
+from sunstone_data.cli._app import auth_app, console
 
 _ENV_OPTION_HELP = "Environment to act on (defaults to the active sunstone environment)."
 
@@ -21,7 +21,7 @@ def _resolve_env(env: str | None) -> str:
     return env or current_environment_name()
 
 
-@data_app.command("login")
+@auth_app.command("login")
 def login_cmd(
     env: str | None = typer.Option(None, "--env", help=_ENV_OPTION_HELP),
 ) -> None:
@@ -78,7 +78,7 @@ def login_cmd(
     console.print(f"[green]Logged in to '{env_name}'.[/green]")
 
 
-@data_app.command("logout")
+@auth_app.command("logout")
 def logout_cmd(
     env: str | None = typer.Option(None, "--env", help=_ENV_OPTION_HELP),
 ) -> None:
@@ -94,7 +94,7 @@ def logout_cmd(
         console.print(f"Not logged in to '{env_name}'; nothing to do.")
 
 
-@data_app.command("whoami")
+@auth_app.command("whoami")
 def whoami_cmd(
     env: str | None = typer.Option(None, "--env", help=_ENV_OPTION_HELP),
 ) -> None:
@@ -109,7 +109,7 @@ def whoami_cmd(
     env_name = _resolve_env(env)
     session = store.read_session(env_name)
     if session is None:
-        console.print(f"Not logged in to '{env_name}'. Run `sunstone data login`.")
+        console.print(f"Not logged in to '{env_name}'. Run `sunstone auth login`.")
         return
 
     age_hours = max(0.0, time.time() - session.cached_at) / 3600

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/cli/main.py

@@ -14,16 +14,16 @@ Layout:
   ``@data_app.command(...)`` and lazy-imports its heavy dependencies
   inside the function body.
 
-This module re-exports ``app`` (the entry point) and ``data_app`` (used by
-:mod:`sunstone_data.plugin`).
+This module re-exports ``app`` (the entry point) and the ``data_app`` and
+``auth_app`` groups (used by :mod:`sunstone_data.plugin`).
 """
 
 from __future__ import annotations
 
 from sunstone_data.cli import commands  # noqa: F401  (import side-effect: registers commands)
-from sunstone_data.cli._app import app, console, data_app
+from sunstone_data.cli._app import app, auth_app, console, data_app
 
-__all__ = ["app", "console", "data_app"]
+__all__ = ["app", "auth_app", "console", "data_app"]
 
 
 if __name__ == "__main__":

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/config.py

@@ -109,8 +109,13 @@ def _try_resolve_environment() -> Any | None:
     """Resolve the active environment via sunstone-py.
 
     Returns an ``Environment`` (sunstone-py 1.12+) if available, else None.
-    Never raises — missing sunstone-py or resolution errors are logged at
-    debug level and return None so the caller falls back to ``.env`` files.
+    Missing sunstone-py and unexpected errors are logged at debug level and
+    return None so the caller falls back to ``.env`` files.
+
+    Raises:
+        ValueError: The active environment is misconfigured (undefined name,
+            invalid section). Falling back to defaults would silently target
+            the wrong service.
     """
     try:
         from sunstone.env import resolve_environment
@@ -119,6 +124,8 @@ def _try_resolve_environment() -> Any | None:
     except ImportError:
         logger.debug("sunstone-py not installed, skipping environment resolution")
         return None
+    except ValueError:
+        raise
     except Exception:
         logger.debug("Failed to resolve environment", exc_info=True)
         return None

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/env_section.py

@@ -47,6 +47,13 @@ class DataPlatformSection:
     :mod:`sunstone_data.discovery`.
     """
 
+    skolem_base_iri: str | None = None
+    """Base for skolem IRIs (``{base_iri}id/`` in deployed environments).
+
+    Accepted so fleet-distributed configs that set it still load. The client
+    does not use it.
+    """
+
     graph_url: str | None = None
     """Deprecated alias for ``base_iri``. Kept so existing config files still load."""
 

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/graph/client.py

@@ -31,7 +31,7 @@ N_TRIPLES = "application/n-triples"
 class AuthError(RuntimeError):
     """Not authenticated: no token, or the token was rejected twice."""
 
-    def __init__(self, message: str = "Not authenticated; run `sunstone data login`"):
+    def __init__(self, message: str = "Not authenticated; run `sunstone auth login`"):
         super().__init__(message)
 
 
@@ -314,7 +314,7 @@ class GraphClient:
         status = resp.status_code
         if status == 401:
             if parse_challenge(resp.headers.get("WWW-Authenticate")) is not None:
-                return StepUpRequired(f"{method} {path} needs a fresh passkey sign-in; run `sunstone data login`")
+                return StepUpRequired(f"{method} {path} needs a fresh passkey sign-in; run `sunstone auth login`")
             return AuthError()
         if status == 403:
             return PermissionError(_required_role(method, path), self._client_id)

{sunstone_data_platform-1.2.0 → sunstone_data_platform-1.3.0}/src/sunstone_data/plugin.py

@@ -10,24 +10,24 @@ from sunstone_data.env_section import DataPlatformSection, DataPlatformSectionPr
 class SunstoneDataPlugin:
     """Data platform plugin for sunstone-py.
 
-    Implements CLIProvider (mounts `data` subcommand group), URLHandler
+    Implements CLIProvider (mounts the `data` and `auth` subcommand groups), URLHandler
     (resolves sunstone: URLs to parquet data), and EnvSectionProvider
     (owns the ``data-platform`` subtable in env config files).
     """
 
     def cli_groups(self):
-        """Return the data CLI group for mounting on the sunstone app.
+        """Return the data and auth CLI groups for mounting on the sunstone app.
 
         Also attaches ``init`` and ``refresh`` to sunstone-py's ``env`` group.
         sunstone-py calls this only after ``sunstone.cli.env_app`` exists, so
         importing ``sunstone.cli`` here cannot re-enter plugin discovery.
         """
-        from sunstone_data.cli.main import data_app
+        from sunstone_data.cli.main import auth_app, data_app
         from sunstone_data.env_commands import _register
 
         _register()
 
-        return [("data", data_app)]
+        return [("data", data_app), ("auth", auth_app)]
 
     def can_handle(self, url: str) -> bool:
         """Return True for sunstone: URLs.