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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sunstone-data-platform
-Version: 1.0.0
+Version: 1.2.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: publicsuffixlist>=1.0.2.20261003
 Requires-Dist: pyiceberg[duckdb,gcsfs,s3fs]>=0.10.0
 Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: python-dotenv>=1.2.2
@@ -25,48 +26,44 @@ Description-Content-Type: text/markdown
 
 # Sunstone Data Platform
 
-A data lakehouse for importing, versioning, and querying external datasets with full provenance tracking. Built on Apache Iceberg, iceberg-catalog, RustFS, and DuckDB.
+A data lakehouse for importing, versioning, and querying external datasets with full provenance tracking. Built on Apache Iceberg, an Iceberg REST catalog, a versioned RDF graph in Postgres, RustFS, and DuckDB.
 
-Data scientists can import CSV/Excel files from local paths or URLs, query them via DuckDB with git-like version references, and track lineage through notebook sessions. All provenance is captured using W3C PROV-DM so metadata can later materialize as a knowledge graph.
+Data scientists import CSV/Excel files from local paths or URLs into Iceberg tables, query them with DuckDB using git-like version references, and publish dataset metadata and W3C PROV-DM provenance into the graph. The graph is the system of record for metadata, branches and tags.
 
 ## Architecture
 
 ```
-                        ┌──────────────┐
-                        │  sunstone    │
-                        │  CLI (Typer) │
-                        └──────┬───────┘
-                               │
-              ┌────────────────┼────────────────┐
-              │                │                │
-     ┌────────▼───────┐ ┌─────▼──────┐ ┌───────▼────────┐
-     │ Import Pipeline │ │   Query    │ │   Versioning   │
-     │ fetch → parse → │ │  (DuckDB)  │ │ branches/tags/ │
-     │ store → metadata│ │            │ │ history/diff   │
-     └────────┬────────┘ └─────┬──────┘ └───────┬────────┘
-              │                │                │
-              └────────────────┼────────────────┘
-                               │
-                    ┌──────────▼──────────┐
-                    │  iceberg-catalog    │
-                    │  (Iceberg REST API) │
-                    └──────────┬──────────┘
-                               │
-                    ┌──────────▼──────────┐
-                    │   RustFS (S3)       │
-                    │   Iceberg tables +  │
-                    │   original files    │
-                    └─────────────────────┘
+              ┌─────────────────────────────────┐
+              │ sunstone_data (Python)          │
+              │ sunstone data CLI, sunstone:    │
+              │ URLs, import pipeline, DuckDB   │
+              └───────┬─────────────────┬───────┘
+         Iceberg REST │                 │ GSP, refs, SPARQL
+                      ▼                 ▼
+          ┌─────────────────┐   ┌─────────────────┐
+          │ iceberg-catalog │──▶│ graph-server    │
+          │ :8181           │   │ :8080           │
+          └────────┬────────┘   └────────┬────────┘
+                   ▼                     ▼
+          ┌─────────────────┐   ┌─────────────────┐
+          │ RustFS (S3)     │   │ Postgres graph  │
+          │ Iceberg tables, │   │ (SoR), copied   │
+          │ original files  │   │ to Oxigraph     │
+          └─────────────────┘   └─────────────────┘
 ```
 
-**Stack**: Python 3.11+ | PyIceberg | DuckDB | iceberg-catalog | RustFS | PostgreSQL 16
+On every table commit, iceberg-catalog also writes the table's descriptor into
+the graph. See [docs/architecture.md](docs/architecture.md) for the
+full data flow.
+
+**Stack**: Python 3.11+ | PyIceberg | DuckDB | iceberg-catalog | graph-server | Oxigraph | RustFS | PostgreSQL 16
 
 ## Endpoints
 
 - `/catalog` — DCAT JSON-LD view of the lakehouse, served by graph-server views
   (see [the views design](docs/specs/2026-08-02-graph-server-views-design.md))
-- `/ui/` — the graph explorer, a 3D view of the data graph, served by
-  graph-server (see [docs/graph-explorer.md](docs/graph-explorer.md))
+- `/ui/` — the data explorer, a 3D view of the data graph, served by
+  graph-server (see [docs/data-explorer.md](docs/data-explorer.md))
 
 ## Local Development Setup
 
@@ -150,14 +147,16 @@ uv run scripts/smoke_test.py
 
 ### 5. Set up your environment
 
-The `sunstone` CLI comes from sunstone-py. data-platform registers as a plugin and adds the `data` subcommand group:
+The `sunstone` CLI comes from sunstone-py. data-platform registers as a plugin and adds the `data` subcommand group. You configure one value per environment, the base IRI (`base_iri`). graph-server is served at the base, the Iceberg catalog under `{base_iri}iceberg/`, and datasets and organizations are named under it. The client discovers sign-in settings from graph-server.
 
 ```bash
 # Add your local Docker stack as an environment
-sunstone env add local --catalog-url http://localhost:19120 --s3-endpoint http://localhost:9000
+sunstone env add local data-platform.base_iri=https://data.example.org/
 sunstone env use local
 ```
 
+`base_iri` must equal the iceberg-catalog service's `BASE_IRI`. In the local Docker stack, graph-server (port 8080) and the catalog (port 8181) listen on different ports, so also set the service overrides `GRAPH_URL=http://localhost:8080` and `CATALOG_URI=http://localhost:8181` (see `.env.example`). They never affect IRIs.
+
 ### 6. Try it out
 
 ```bash
@@ -167,17 +166,17 @@ sunstone data import path/to/data.csv
 # Import from a URL
 sunstone data import https://example.com/dataset.csv
 
-# List datasets
-sunstone data info
+# List namespaces and tables
+sunstone data ls
 
-# View dataset metadata
-sunstone data info namespace.table_name
+# View dataset metadata from the graph
+sunstone data show namespace.table_name
 
-# Query history
+# Snapshot history
 sunstone data history namespace.table_name
 
-# Compare versions
-sunstone data diff namespace.table_name @v1 @v2
+# Publish the current snapshot as a named version
+sunstone data publish namespace.table_name --version v1.0
 ```
 
 ## Running Tests
@@ -186,7 +185,7 @@ sunstone data diff namespace.table_name @v1 @v2
 # Unit tests (fast, no Docker required)
 uv run pytest tests/unit/
 
-# Integration tests (requires Docker stack running)
+# Integration tests (run inside Docker automatically; needs Docker)
 uv run pytest tests/integration/
 
 # All tests
@@ -200,25 +199,33 @@ uv run pytest tests/unit/test_query.py -v
 
 | Command | Description |
 |---------|-------------|
-| `sunstone data import <source>` | Import CSV/Excel from path or URL |
-| `sunstone data info [table]` | View metadata for one or all datasets |
-| `sunstone data history <table>` | Show snapshot history (git-log style) |
-| `sunstone data tag <table> <tag>` | Tag a snapshot version |
-| `sunstone data untag <table> <tag>` | Remove a tag |
-| `sunstone data branches` | List branches and tags |
-| `sunstone data diff <table> <from> [to]` | Compare two versions |
-| `sunstone data lineage <table>` | Show provenance and lineage |
-| `sunstone data original <table>` | Download the original imported source file |
-
-All commands support `--branch` for working on version branches and `--json` for machine-readable output. Run `sunstone data <command> --help` for full options.
+| `sunstone data 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 |
+| `sunstone data import <source>` | Import CSV/Excel from a path or URL |
+| `sunstone data publish <table>` | Publish dataset metadata to the graph; `--version` names the current snapshot |
+| `sunstone data history <table>` | Iceberg snapshot history |
+| `sunstone data lineage <table>` | Provenance from the published PROV facts |
+| `sunstone data sparql <query>` | Run a SPARQL query through graph-server |
+| `sunstone data branches`, `branch create\|delete` | List, create and delete graph branches |
+| `sunstone data tags`, `tag create\|delete` | List, create and delete graph tags |
+
+Every command takes `--json` for machine-readable output. `import`, `publish`, `show`, `history` and `tag create` take `--branch`. Run `sunstone data <command> --help` for full options.
 
 ## Key Concepts
 
-- **Table references** use git-like syntax: `namespace.table@branch`, `@v1.0`, `@2026-01-25`, `@snapshot_id`
-- **Deduplication**: Imports are checksum-based (SHA256). Re-importing the same file is a no-op.
+- **Table references** use the form `namespace.table@ref`. A ref is checked in this order:
+  1. a branch name
+  2. a snapshot id (13 or more digits)
+  3. a date or timestamp (UTC if it has no timezone), which selects the last snapshot at or before that time
+  4. a named version created with `sunstone data publish --version`
+
+  Snapshot ids, timestamps and named versions resolve against `main`. Graph tags (`sunstone data tag create`) are not valid refs.
+- **Deduplication**: Imports are checksum-based (SHA-256). Re-importing the same file is a no-op.
 - **Schema evolution**: Safe type promotions (e.g. int32 to int64) are allowed automatically. Unsafe changes require `--force-schema`.
-- **Provenance**: Every import captures source metadata, schema info, and W3C PROV-DM provenance as Iceberg table properties.
-- **Original files**: Source files are stored content-addressable in S3 alongside the Iceberg data.
+- **Provenance**: Every import records source metadata and schema info as Iceberg table properties, and asserts W3C PROV-DM provenance into the dataset's graph.
+- **Original files**: Source files are stored content-addressed in object storage next to the Iceberg data.
 
 ## sunstone: URLs
 
@@ -230,7 +237,7 @@ import sunstone
 df = sunstone.read("sunstone:namespace/table@v1.0")
 ```
 
-Supports the full ref syntax: `@branch`, `@tag`, `@2026-01-25`, `@snapshot_id`.
+The `@ref` part follows the same rules as table references above. Here `v1.0` is a named version.
 
 ## Project Structure
 
@@ -238,24 +245,26 @@ Supports the full ref syntax: `@branch`, `@tag`, `@2026-01-25`, `@snapshot_id`.
 src/sunstone_data/
 ├── plugin.py          # sunstone-py plugin (CLIProvider + URLHandler)
 ├── url.py             # sunstone: URL parser
+├── resolve.py         # Resolves a @ref to a branch or snapshot
 ├── config.py          # Settings from DataEnvironment or .env
+├── discovery.py       # Sign-in settings from graph-server /ui/config.json
+├── auth/              # Keycloak login and token handling
+├── graph/             # graph-server client and RDF serialization
+├── publish.py         # Publishes dataset metadata to the graph
 ├── catalog.py         # PyIceberg RestCatalog connection to the Iceberg REST catalog
 ├── query.py           # DuckDB QuerySession with time-travel support
-├── lineage.py         # Lineage in Iceberg table properties
-├── cli/               # Typer CLI commands + Rich formatters
+├── cli/               # Typer CLI commands
 ├── import_/           # Pipeline: fetch → parse → store → metadata
 ├── metadata/          # Frozen dataclasses, MetadataBuilder, W3C PROV-DM
-├── versioning/        # Version branches/tags, refs, schema evolution, diff
+├── versioning/        # Schema evolution checks
 └── utils/             # Checksums, encoding detection, naming
 ```
 
 ## Documentation
 
-- [Getting Started](docs/getting-started.md) - Detailed setup instructions
-- [Architecture](docs/architecture.md) - System design and data flow
-- [CLI Reference](docs/cli-reference.md) - Complete command documentation
-- [Import Pipeline](docs/import-pipeline.md) - How imports work
-- [Development Guide](docs/development.md) - Contributing and testing
+- [docs/README.md](docs/README.md) - Index of all documentation
+- [docs/architecture.md](docs/architecture.md) - System overview and data flow
+- [docs/specs2/](docs/specs2/) - Current design, one file per subsystem. The Python client and CLI are in [05-python-client.md](docs/specs2/05-python-client.md).
 
 ## Resetting the Stack
 
@@ -278,11 +287,11 @@ determine which environment you can use. See
 `docs/specs/2026-07-05-graph-server-auth-design.md`.
 
 No hostnames or client ids ship in this package. Each environment's
-`graph_url` comes from config: Sunstone-managed machines get
+`base_iri` comes from config: Sunstone-managed machines get
 `/etc/sunstone/data_platform.toml` from the `fleet-config` repo, and other
-machines set `GRAPH_URL` or add an environment with `sunstone env add`.
+machines set `BASE_IRI` or add an environment with `sunstone env add`.
 graph-server publishes the OIDC issuer and public client id at
-`$GRAPH_URL/ui/config.json`; the CLI reads them from there.
+`{base_iri}ui/config.json`; the CLI reads them from there.
 
 ### Humans (CLI, local agents)
 

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

@@ -1,47 +1,43 @@
 # Sunstone Data Platform
 
-A data lakehouse for importing, versioning, and querying external datasets with full provenance tracking. Built on Apache Iceberg, iceberg-catalog, RustFS, and DuckDB.
+A data lakehouse for importing, versioning, and querying external datasets with full provenance tracking. Built on Apache Iceberg, an Iceberg REST catalog, a versioned RDF graph in Postgres, RustFS, and DuckDB.
 
-Data scientists can import CSV/Excel files from local paths or URLs, query them via DuckDB with git-like version references, and track lineage through notebook sessions. All provenance is captured using W3C PROV-DM so metadata can later materialize as a knowledge graph.
+Data scientists import CSV/Excel files from local paths or URLs into Iceberg tables, query them with DuckDB using git-like version references, and publish dataset metadata and W3C PROV-DM provenance into the graph. The graph is the system of record for metadata, branches and tags.
 
 ## Architecture
 
 ```
-                        ┌──────────────┐
-                        │  sunstone    │
-                        │  CLI (Typer) │
-                        └──────┬───────┘
-                               │
-              ┌────────────────┼────────────────┐
-              │                │                │
-     ┌────────▼───────┐ ┌─────▼──────┐ ┌───────▼────────┐
-     │ Import Pipeline │ │   Query    │ │   Versioning   │
-     │ fetch → parse → │ │  (DuckDB)  │ │ branches/tags/ │
-     │ store → metadata│ │            │ │ history/diff   │
-     └────────┬────────┘ └─────┬──────┘ └───────┬────────┘
-              │                │                │
-              └────────────────┼────────────────┘
-                               │
-                    ┌──────────▼──────────┐
-                    │  iceberg-catalog    │
-                    │  (Iceberg REST API) │
-                    └──────────┬──────────┘
-                               │
-                    ┌──────────▼──────────┐
-                    │   RustFS (S3)       │
-                    │   Iceberg tables +  │
-                    │   original files    │
-                    └─────────────────────┘
+              ┌─────────────────────────────────┐
+              │ sunstone_data (Python)          │
+              │ sunstone data CLI, sunstone:    │
+              │ URLs, import pipeline, DuckDB   │
+              └───────┬─────────────────┬───────┘
+         Iceberg REST │                 │ GSP, refs, SPARQL
+                      ▼                 ▼
+          ┌─────────────────┐   ┌─────────────────┐
+          │ iceberg-catalog │──▶│ graph-server    │
+          │ :8181           │   │ :8080           │
+          └────────┬────────┘   └────────┬────────┘
+                   ▼                     ▼
+          ┌─────────────────┐   ┌─────────────────┐
+          │ RustFS (S3)     │   │ Postgres graph  │
+          │ Iceberg tables, │   │ (SoR), copied   │
+          │ original files  │   │ to Oxigraph     │
+          └─────────────────┘   └─────────────────┘
 ```
 
-**Stack**: Python 3.11+ | PyIceberg | DuckDB | iceberg-catalog | RustFS | PostgreSQL 16
+On every table commit, iceberg-catalog also writes the table's descriptor into
+the graph. See [docs/architecture.md](docs/architecture.md) for the
+full data flow.
+
+**Stack**: Python 3.11+ | PyIceberg | DuckDB | iceberg-catalog | graph-server | Oxigraph | RustFS | PostgreSQL 16
 
 ## Endpoints
 
 - `/catalog` — DCAT JSON-LD view of the lakehouse, served by graph-server views
   (see [the views design](docs/specs/2026-08-02-graph-server-views-design.md))
-- `/ui/` — the graph explorer, a 3D view of the data graph, served by
-  graph-server (see [docs/graph-explorer.md](docs/graph-explorer.md))
+- `/ui/` — the data explorer, a 3D view of the data graph, served by
+  graph-server (see [docs/data-explorer.md](docs/data-explorer.md))
 
 ## Local Development Setup
 
@@ -125,14 +121,16 @@ uv run scripts/smoke_test.py
 
 ### 5. Set up your environment
 
-The `sunstone` CLI comes from sunstone-py. data-platform registers as a plugin and adds the `data` subcommand group:
+The `sunstone` CLI comes from sunstone-py. data-platform registers as a plugin and adds the `data` subcommand group. You configure one value per environment, the base IRI (`base_iri`). graph-server is served at the base, the Iceberg catalog under `{base_iri}iceberg/`, and datasets and organizations are named under it. The client discovers sign-in settings from graph-server.
 
 ```bash
 # Add your local Docker stack as an environment
-sunstone env add local --catalog-url http://localhost:19120 --s3-endpoint http://localhost:9000
+sunstone env add local data-platform.base_iri=https://data.example.org/
 sunstone env use local
 ```
 
+`base_iri` must equal the iceberg-catalog service's `BASE_IRI`. In the local Docker stack, graph-server (port 8080) and the catalog (port 8181) listen on different ports, so also set the service overrides `GRAPH_URL=http://localhost:8080` and `CATALOG_URI=http://localhost:8181` (see `.env.example`). They never affect IRIs.
+
 ### 6. Try it out
 
 ```bash
@@ -142,17 +140,17 @@ sunstone data import path/to/data.csv
 # Import from a URL
 sunstone data import https://example.com/dataset.csv
 
-# List datasets
-sunstone data info
+# List namespaces and tables
+sunstone data ls
 
-# View dataset metadata
-sunstone data info namespace.table_name
+# View dataset metadata from the graph
+sunstone data show namespace.table_name
 
-# Query history
+# Snapshot history
 sunstone data history namespace.table_name
 
-# Compare versions
-sunstone data diff namespace.table_name @v1 @v2
+# Publish the current snapshot as a named version
+sunstone data publish namespace.table_name --version v1.0
 ```
 
 ## Running Tests
@@ -161,7 +159,7 @@ sunstone data diff namespace.table_name @v1 @v2
 # Unit tests (fast, no Docker required)
 uv run pytest tests/unit/
 
-# Integration tests (requires Docker stack running)
+# Integration tests (run inside Docker automatically; needs Docker)
 uv run pytest tests/integration/
 
 # All tests
@@ -175,25 +173,33 @@ uv run pytest tests/unit/test_query.py -v
 
 | Command | Description |
 |---------|-------------|
-| `sunstone data import <source>` | Import CSV/Excel from path or URL |
-| `sunstone data info [table]` | View metadata for one or all datasets |
-| `sunstone data history <table>` | Show snapshot history (git-log style) |
-| `sunstone data tag <table> <tag>` | Tag a snapshot version |
-| `sunstone data untag <table> <tag>` | Remove a tag |
-| `sunstone data branches` | List branches and tags |
-| `sunstone data diff <table> <from> [to]` | Compare two versions |
-| `sunstone data lineage <table>` | Show provenance and lineage |
-| `sunstone data original <table>` | Download the original imported source file |
-
-All commands support `--branch` for working on version branches and `--json` for machine-readable output. Run `sunstone data <command> --help` for full options.
+| `sunstone data 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 |
+| `sunstone data import <source>` | Import CSV/Excel from a path or URL |
+| `sunstone data publish <table>` | Publish dataset metadata to the graph; `--version` names the current snapshot |
+| `sunstone data history <table>` | Iceberg snapshot history |
+| `sunstone data lineage <table>` | Provenance from the published PROV facts |
+| `sunstone data sparql <query>` | Run a SPARQL query through graph-server |
+| `sunstone data branches`, `branch create\|delete` | List, create and delete graph branches |
+| `sunstone data tags`, `tag create\|delete` | List, create and delete graph tags |
+
+Every command takes `--json` for machine-readable output. `import`, `publish`, `show`, `history` and `tag create` take `--branch`. Run `sunstone data <command> --help` for full options.
 
 ## Key Concepts
 
-- **Table references** use git-like syntax: `namespace.table@branch`, `@v1.0`, `@2026-01-25`, `@snapshot_id`
-- **Deduplication**: Imports are checksum-based (SHA256). Re-importing the same file is a no-op.
+- **Table references** use the form `namespace.table@ref`. A ref is checked in this order:
+  1. a branch name
+  2. a snapshot id (13 or more digits)
+  3. a date or timestamp (UTC if it has no timezone), which selects the last snapshot at or before that time
+  4. a named version created with `sunstone data publish --version`
+
+  Snapshot ids, timestamps and named versions resolve against `main`. Graph tags (`sunstone data tag create`) are not valid refs.
+- **Deduplication**: Imports are checksum-based (SHA-256). Re-importing the same file is a no-op.
 - **Schema evolution**: Safe type promotions (e.g. int32 to int64) are allowed automatically. Unsafe changes require `--force-schema`.
-- **Provenance**: Every import captures source metadata, schema info, and W3C PROV-DM provenance as Iceberg table properties.
-- **Original files**: Source files are stored content-addressable in S3 alongside the Iceberg data.
+- **Provenance**: Every import records source metadata and schema info as Iceberg table properties, and asserts W3C PROV-DM provenance into the dataset's graph.
+- **Original files**: Source files are stored content-addressed in object storage next to the Iceberg data.
 
 ## sunstone: URLs
 
@@ -205,7 +211,7 @@ import sunstone
 df = sunstone.read("sunstone:namespace/table@v1.0")
 ```
 
-Supports the full ref syntax: `@branch`, `@tag`, `@2026-01-25`, `@snapshot_id`.
+The `@ref` part follows the same rules as table references above. Here `v1.0` is a named version.
 
 ## Project Structure
 
@@ -213,24 +219,26 @@ Supports the full ref syntax: `@branch`, `@tag`, `@2026-01-25`, `@snapshot_id`.
 src/sunstone_data/
 ├── plugin.py          # sunstone-py plugin (CLIProvider + URLHandler)
 ├── url.py             # sunstone: URL parser
+├── resolve.py         # Resolves a @ref to a branch or snapshot
 ├── config.py          # Settings from DataEnvironment or .env
+├── discovery.py       # Sign-in settings from graph-server /ui/config.json
+├── auth/              # Keycloak login and token handling
+├── graph/             # graph-server client and RDF serialization
+├── publish.py         # Publishes dataset metadata to the graph
 ├── catalog.py         # PyIceberg RestCatalog connection to the Iceberg REST catalog
 ├── query.py           # DuckDB QuerySession with time-travel support
-├── lineage.py         # Lineage in Iceberg table properties
-├── cli/               # Typer CLI commands + Rich formatters
+├── cli/               # Typer CLI commands
 ├── import_/           # Pipeline: fetch → parse → store → metadata
 ├── metadata/          # Frozen dataclasses, MetadataBuilder, W3C PROV-DM
-├── versioning/        # Version branches/tags, refs, schema evolution, diff
+├── versioning/        # Schema evolution checks
 └── utils/             # Checksums, encoding detection, naming
 ```
 
 ## Documentation
 
-- [Getting Started](docs/getting-started.md) - Detailed setup instructions
-- [Architecture](docs/architecture.md) - System design and data flow
-- [CLI Reference](docs/cli-reference.md) - Complete command documentation
-- [Import Pipeline](docs/import-pipeline.md) - How imports work
-- [Development Guide](docs/development.md) - Contributing and testing
+- [docs/README.md](docs/README.md) - Index of all documentation
+- [docs/architecture.md](docs/architecture.md) - System overview and data flow
+- [docs/specs2/](docs/specs2/) - Current design, one file per subsystem. The Python client and CLI are in [05-python-client.md](docs/specs2/05-python-client.md).
 
 ## Resetting the Stack
 
@@ -253,11 +261,11 @@ determine which environment you can use. See
 `docs/specs/2026-07-05-graph-server-auth-design.md`.
 
 No hostnames or client ids ship in this package. Each environment's
-`graph_url` comes from config: Sunstone-managed machines get
+`base_iri` comes from config: Sunstone-managed machines get
 `/etc/sunstone/data_platform.toml` from the `fleet-config` repo, and other
-machines set `GRAPH_URL` or add an environment with `sunstone env add`.
+machines set `BASE_IRI` or add an environment with `sunstone env add`.
 graph-server publishes the OIDC issuer and public client id at
-`$GRAPH_URL/ui/config.json`; the CLI reads them from there.
+`{base_iri}ui/config.json`; the CLI reads them from there.
 
 ### Humans (CLI, local agents)
 

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

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

{sunstone_data_platform-1.0.0 → sunstone_data_platform-1.2.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.0.0'
-__version_tuple__ = version_tuple = (1, 0, 0)
+__version__ = version = '1.2.0'
+__version_tuple__ = version_tuple = (1, 2, 0)
 
 __commit_id__ = commit_id = None

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

@@ -22,6 +22,7 @@ from sunstone_data.auth.client_creds import (
     refresh_access_token,
     resolve_access_token,
 )
+from sunstone_data.auth.stepup import StepUpChallenge, StepUpRequired, parse_challenge, step_up
 from sunstone_data.auth.store import (
     Session,
     clear_session,
@@ -33,11 +34,15 @@ from sunstone_data.auth.store import (
 __all__ = [
     "ClientCredentialsToken",
     "Session",
+    "StepUpChallenge",
+    "StepUpRequired",
     "clear_session",
     "discover_token_endpoint",
     "read_session",
+    "parse_challenge",
     "refresh_access_token",
     "resolve_access_token",
     "session_path",
+    "step_up",
     "write_session",
 ]

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

@@ -72,18 +72,27 @@ def build_authorization_url(
     redirect_uri: str,
     state: str,
     code_challenge: str,
+    acr_values: str | None = None,
+    max_age: int | None = None,
 ) -> 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",
-        }
-    )
+    """Build the URL the user's browser is sent to in order to sign in.
+
+    ``acr_values`` and ``max_age`` are the OIDC step-up parameters (RFC 9470).
+    They are sent only when given.
+    """
+    params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    }
+    if acr_values is not None:
+        params["acr_values"] = acr_values
+    if max_age is not None:
+        params["max_age"] = str(max_age)
+    query = urlencode(params)
     separator = "&" if urlparse(authorization_endpoint).query else "?"
     return f"{authorization_endpoint}{separator}{query}"
 
@@ -262,6 +271,8 @@ def login(
     client_id: str,
     client: httpx.Client,
     open_browser: Callable[[str], object] = webbrowser.open,
+    acr_values: str | None = None,
+    max_age: int | None = None,
 ) -> TokenResponse:
     """Run the full PKCE sign-in and return the resulting tokens.
 
@@ -276,6 +287,8 @@ def login(
         client: HTTP client for the token exchange.
         open_browser: How to show the user the authorization URL. Injected so
             tests need no browser.
+        acr_values: Authentication context the sign-in must satisfy (step-up).
+        max_age: Newest allowed age, in seconds, of the user's last sign-in.
 
     Raises:
         RuntimeError: Sign-in was refused, timed out, or the callback failed
@@ -292,6 +305,8 @@ def login(
             redirect_uri=redirect_uri,
             state=state,
             code_challenge=derive_code_challenge(verifier),
+            acr_values=acr_values,
+            max_age=max_age,
         )
         open_browser(url)
         code = verify_callback(await_callback(server, sink), state)