iceberg-subzero 0.1.0__tar.gz

iceberg_subzero-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

iceberg_subzero-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: iceberg-subzero
+Version: 0.1.0
+Summary: Python client for the Subzero tokenization vault and LLM proxy
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: auth
+Requires-Dist: pyotp>=2.9.0; extra == 'auth'
+Provides-Extra: dev
+Requires-Dist: openai>=1.0.0; extra == 'dev'
+Requires-Dist: pyotp>=2.9.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Subzero Python SDK
+
+Thin Python client for the [Subzero](../api/) tokenization vault and LLM proxy.
+
+## Install
+
+```bash
+cd python-sdk
+pip install -e ".[dev,openai,auth]"
+```
+
+The optional `auth` extra adds `pyotp` for TOTP code generation during dashboard login.
+
+## Two auth planes
+
+| Plane | Credential | Use for |
+|-------|------------|---------|
+| **Server integration** | API key (`sz_live_...`) | `tokenize`, `search`, `reveal`, `proxy`, tenant admin after bootstrap |
+| **Dashboard / human** | JWT access token | `auth.*`, `members.*`, `admin.create_tenant`, `admin.get_tenant` |
+
+Pass an API key, an access token, or both when constructing the client:
+
+```python
+from subzero import SubzeroClient
+
+# Vault + proxy (server-side)
+vault = SubzeroClient(api_key="sz_live_...", base_url="http://127.0.0.1:8000")
+
+# Dashboard session (platform or tenant admin JWT)
+dashboard = SubzeroClient(access_token="eyJ...", base_url="http://127.0.0.1:8000")
+```
+
+## Quick start (vault)
+
+```python
+from subzero import SubzeroClient
+
+client = SubzeroClient(
+    api_key="sz_live_...",
+    base_url="http://127.0.0.1:8000",
+)
+client.ready()
+
+token = client.tokenize("SSN", "123-45-6789").token
+value = client.reveal(token).value
+```
+
+## Platform admin login (tenant provisioning)
+
+`POST /v1/tenants` requires a platform-admin JWT. Log in with MFA, then create tenants:
+
+```python
+from subzero import SubzeroClient
+
+client = SubzeroClient(base_url="http://127.0.0.1:8000")
+client.ready()
+
+client.auth.login_platform(
+    email="admin@iceberg.local",
+    password="...",
+    totp_code="123456",       # or totp_secret="BASE32..." with pip install 'subzero[auth]'
+)
+
+tenant = client.admin.create_tenant(name="Acme", slug="acme")
+admin_key = tenant.bootstrap_api_key
+
+# Switch to tenant admin API key for day-to-day vault/proxy setup
+admin = SubzeroClient(api_key=admin_key, base_url="http://127.0.0.1:8000")
+admin.admin.create_entity_type(tenant.id, name="SSN", deterministic=True)
+```
+
+Tenant member invites and management use `client.members` with a tenant-admin or platform-admin JWT.
+
+## API key scopes
+
+| Scope | Vault methods | Notes |
+|-------|---------------|-------|
+| `tokenize` | `tokenize`, `search` | No plaintext return |
+| `reveal` | `reveal` | Server-side plaintext reveal; requires matching policy rule |
+| `reveal_grant` | `create_reveal_grant` | Mint browser reveal grants only; requires matching policy rule |
+| `proxy` | `proxy.chat.completions` | In-flight tokenization |
+| `admin` | All of the above + `admin.*` + `delete_token` | Bypasses reveal policy |
+
+**Browser reveal:** the iframe calls `POST /v1/browser/reveal` with a server-minted grant. Your BFF uses a **`reveal_grant`** key to call `create_reveal_grant(token, client_public_key_jwk=..., allowed_origin=...)`. Keep **`reveal`** keys for server pipelines that need `client.reveal(token).value`.
+
+```python
+grant = client.create_reveal_grant(
+    token,
+    client_public_key_jwk=jwk_from_iframe,
+    allowed_origin="https://app.yourcompany.com",
+)
+```
+
+**Delete requires admin.** There is no delegatable delete-scoped API key at the HTTP layer. `delete_token()` needs an admin key even though policy rules support a `delete` action at the service layer.
+
+## Proxy vs reveal vs detokenize
+
+- **Vault reveal:** `client.reveal(token)` — `POST /v1/reveal`, reveal-scoped key + policy
+- **Proxy chat:** `client.proxy.chat.completions(...)` — tokenizes declared patterns in-flight
+- **Proxy detokenize:** pass `detokenize=True` or use OpenAI helper below — governed by reveal policy for the proxy key, not the reveal endpoint
+
+```python
+from subzero import create_openai_client
+
+client = create_openai_client(
+    api_key="sz_live_...",          # Subzero proxy key
+    base_url="http://127.0.0.1:8000/v1",
+    detokenize=True,                # X-Subzero-Detokenize: true via default_headers
+)
+client.chat.completions.create(model="gpt-4o", stream=False, messages=[...])
+```
+
+## Examples
+
+With the API running (`docker compose up` or `uvicorn`):
+
+```bash
+export SUBZERO_PLATFORM_EMAIL=admin@iceberg.local
+export SUBZERO_PLATFORM_PASSWORD=...
+export SUBZERO_TOTP_CODE=123456   # or SUBZERO_TOTP_SECRET / SUBZERO_ACCESS_TOKEN
+
+python examples/hero_demo.py
+python examples/vault_loop.py
+```
+
+Set `SUBZERO_BASE_URL` and `OPENAI_API_KEY` as needed.
+
+## Tests
+
+```bash
+pytest
+```
+
+## PyPI
+
+Local editable install only for now. `# TODO: twine upload` when ready to publish.

iceberg_subzero-0.1.0/README.md

@@ -0,0 +1,136 @@
+# Subzero Python SDK
+
+Thin Python client for the [Subzero](../api/) tokenization vault and LLM proxy.
+
+## Install
+
+```bash
+cd python-sdk
+pip install -e ".[dev,openai,auth]"
+```
+
+The optional `auth` extra adds `pyotp` for TOTP code generation during dashboard login.
+
+## Two auth planes
+
+| Plane | Credential | Use for |
+|-------|------------|---------|
+| **Server integration** | API key (`sz_live_...`) | `tokenize`, `search`, `reveal`, `proxy`, tenant admin after bootstrap |
+| **Dashboard / human** | JWT access token | `auth.*`, `members.*`, `admin.create_tenant`, `admin.get_tenant` |
+
+Pass an API key, an access token, or both when constructing the client:
+
+```python
+from subzero import SubzeroClient
+
+# Vault + proxy (server-side)
+vault = SubzeroClient(api_key="sz_live_...", base_url="http://127.0.0.1:8000")
+
+# Dashboard session (platform or tenant admin JWT)
+dashboard = SubzeroClient(access_token="eyJ...", base_url="http://127.0.0.1:8000")
+```
+
+## Quick start (vault)
+
+```python
+from subzero import SubzeroClient
+
+client = SubzeroClient(
+    api_key="sz_live_...",
+    base_url="http://127.0.0.1:8000",
+)
+client.ready()
+
+token = client.tokenize("SSN", "123-45-6789").token
+value = client.reveal(token).value
+```
+
+## Platform admin login (tenant provisioning)
+
+`POST /v1/tenants` requires a platform-admin JWT. Log in with MFA, then create tenants:
+
+```python
+from subzero import SubzeroClient
+
+client = SubzeroClient(base_url="http://127.0.0.1:8000")
+client.ready()
+
+client.auth.login_platform(
+    email="admin@iceberg.local",
+    password="...",
+    totp_code="123456",       # or totp_secret="BASE32..." with pip install 'subzero[auth]'
+)
+
+tenant = client.admin.create_tenant(name="Acme", slug="acme")
+admin_key = tenant.bootstrap_api_key
+
+# Switch to tenant admin API key for day-to-day vault/proxy setup
+admin = SubzeroClient(api_key=admin_key, base_url="http://127.0.0.1:8000")
+admin.admin.create_entity_type(tenant.id, name="SSN", deterministic=True)
+```
+
+Tenant member invites and management use `client.members` with a tenant-admin or platform-admin JWT.
+
+## API key scopes
+
+| Scope | Vault methods | Notes |
+|-------|---------------|-------|
+| `tokenize` | `tokenize`, `search` | No plaintext return |
+| `reveal` | `reveal` | Server-side plaintext reveal; requires matching policy rule |
+| `reveal_grant` | `create_reveal_grant` | Mint browser reveal grants only; requires matching policy rule |
+| `proxy` | `proxy.chat.completions` | In-flight tokenization |
+| `admin` | All of the above + `admin.*` + `delete_token` | Bypasses reveal policy |
+
+**Browser reveal:** the iframe calls `POST /v1/browser/reveal` with a server-minted grant. Your BFF uses a **`reveal_grant`** key to call `create_reveal_grant(token, client_public_key_jwk=..., allowed_origin=...)`. Keep **`reveal`** keys for server pipelines that need `client.reveal(token).value`.
+
+```python
+grant = client.create_reveal_grant(
+    token,
+    client_public_key_jwk=jwk_from_iframe,
+    allowed_origin="https://app.yourcompany.com",
+)
+```
+
+**Delete requires admin.** There is no delegatable delete-scoped API key at the HTTP layer. `delete_token()` needs an admin key even though policy rules support a `delete` action at the service layer.
+
+## Proxy vs reveal vs detokenize
+
+- **Vault reveal:** `client.reveal(token)` — `POST /v1/reveal`, reveal-scoped key + policy
+- **Proxy chat:** `client.proxy.chat.completions(...)` — tokenizes declared patterns in-flight
+- **Proxy detokenize:** pass `detokenize=True` or use OpenAI helper below — governed by reveal policy for the proxy key, not the reveal endpoint
+
+```python
+from subzero import create_openai_client
+
+client = create_openai_client(
+    api_key="sz_live_...",          # Subzero proxy key
+    base_url="http://127.0.0.1:8000/v1",
+    detokenize=True,                # X-Subzero-Detokenize: true via default_headers
+)
+client.chat.completions.create(model="gpt-4o", stream=False, messages=[...])
+```
+
+## Examples
+
+With the API running (`docker compose up` or `uvicorn`):
+
+```bash
+export SUBZERO_PLATFORM_EMAIL=admin@iceberg.local
+export SUBZERO_PLATFORM_PASSWORD=...
+export SUBZERO_TOTP_CODE=123456   # or SUBZERO_TOTP_SECRET / SUBZERO_ACCESS_TOKEN
+
+python examples/hero_demo.py
+python examples/vault_loop.py
+```
+
+Set `SUBZERO_BASE_URL` and `OPENAI_API_KEY` as needed.
+
+## Tests
+
+```bash
+pytest
+```
+
+## PyPI
+
+Local editable install only for now. `# TODO: twine upload` when ready to publish.

iceberg_subzero-0.1.0/examples/_bootstrap.py

@@ -0,0 +1,42 @@
+"""Shared bootstrap helpers for SDK examples."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from subzero import SubzeroClient
+from subzero.exceptions import SubzeroAPIError
+
+
+def platform_bootstrap_client(base_url: str) -> SubzeroClient:
+    """Return a client authenticated as platform admin (JWT on client.access_token)."""
+    access_token = os.environ.get("SUBZERO_ACCESS_TOKEN")
+    if access_token:
+        client = SubzeroClient(access_token=access_token, base_url=base_url)
+        client.ready()
+        return client
+
+    email = os.environ.get("SUBZERO_PLATFORM_EMAIL")
+    password = os.environ.get("SUBZERO_PLATFORM_PASSWORD")
+    if not email or not password:
+        print(
+            "Set SUBZERO_PLATFORM_EMAIL and SUBZERO_PLATFORM_PASSWORD, "
+            "or SUBZERO_ACCESS_TOKEN for an existing session.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    client = SubzeroClient(base_url=base_url)
+    client.ready()
+    try:
+        client.auth.login_platform(
+            email=email,
+            password=password,
+            totp_code=os.environ.get("SUBZERO_TOTP_CODE"),
+            totp_secret=os.environ.get("SUBZERO_TOTP_SECRET"),
+        )
+    except SubzeroAPIError as exc:
+        print(f"Platform login failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+    return client

iceberg_subzero-0.1.0/examples/elements_demo.py

@@ -0,0 +1,67 @@
+"""Elements SDK setup: publishable key + tokenize + reveal grant mint."""
+
+import base64
+
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+from subzero import SubzeroClient
+
+from _bootstrap import admin_client, tenant_id
+
+
+def _rsa_public_jwk() -> dict:
+    public_key = rsa.generate_private_key(public_exponent=65537, key_size=2048).public_key()
+    numbers = public_key.public_numbers()
+
+    def int_to_b64url(val: int) -> str:
+        byte_length = (val.bit_length() + 7) // 8
+        return base64.urlsafe_b64encode(val.to_bytes(byte_length, "big")).rstrip(b"=").decode()
+
+    return {
+        "kty": "RSA",
+        "n": int_to_b64url(numbers.n),
+        "e": int_to_b64url(numbers.e),
+        "alg": "RSA-OAEP-256",
+        "ext": True,
+    }
+
+
+def main() -> None:
+    admin = admin_client()
+    admin.ready()
+    tid = tenant_id(admin)
+
+    pub = admin.admin.create_publishable_key(
+        tid,
+        name="demo-browser",
+        allowed_origins=["http://localhost:3000", "http://localhost"],
+    )
+    print(f"Publishable key: {pub.key}")
+
+    token = admin.tokenize("SSN", "123-45-6789").token
+    print(f"Token (server-side): {token}")
+
+    grant_key = admin.admin.create_api_key(tid, name="reveal-grant-demo", scope="reveal_grant")
+    policies = admin.admin.list_policies(tid)
+    if not any(p.principal == f"api_key:{grant_key.id}" for p in policies):
+        admin.admin.create_policy(
+            tid,
+            api_key_id=grant_key.id,
+            entity_type="SSN",
+            action="reveal",
+        )
+
+    grant_client = SubzeroClient(api_key=grant_key.secret, base_url=admin._base_url)
+    grant = grant_client.create_reveal_grant(
+        token,
+        client_public_key_jwk=_rsa_public_jwk(),
+        allowed_origin="http://localhost:3000",
+    )
+    print(f"Reveal grant (one-time): {grant.grant_id} expires {grant.expires_at}")
+
+    grant_client.close()
+    admin.close()
+
+
+if __name__ == "__main__":
+    main()

iceberg_subzero-0.1.0/examples/hero_demo.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Subzero LLM proxy hero demo using the Python SDK."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from subzero import SubzeroClient
+
+from _bootstrap import platform_bootstrap_client
+
+BASE_URL = os.environ.get("SUBZERO_BASE_URL", "http://127.0.0.1:8000")
+UPSTREAM_OPENAI_KEY = os.environ.get("OPENAI_API_KEY", "sk-demo-replace-me")
+SSN_PATTERN = r"\b\d{3}-\d{2}-\d{4}\b"
+
+
+def main() -> int:
+    bootstrap = platform_bootstrap_client(BASE_URL)
+
+    tenant = bootstrap.admin.create_tenant(name="Proxy Demo", slug="proxy-demo-sdk")
+    tenant_id = tenant.id
+    admin_key = tenant.bootstrap_api_key
+    if not admin_key:
+        print("Expected bootstrap_api_key from tenant signup", file=sys.stderr)
+        return 1
+
+    admin = SubzeroClient(api_key=admin_key, base_url=BASE_URL)
+    admin.admin.create_entity_type(
+        tenant_id,
+        name="SSN",
+        deterministic=True,
+        match_pattern=SSN_PATTERN,
+    )
+    admin.admin.create_llm_config(
+        tenant_id,
+        base_url="https://api.openai.com/v1",
+        api_key=UPSTREAM_OPENAI_KEY,
+    )
+    proxy_key_result = admin.admin.create_api_key(tenant_id, name="proxy", scope="proxy")
+    proxy_key = proxy_key_result.secret
+    if not proxy_key:
+        print("Expected proxy key secret", file=sys.stderr)
+        return 1
+
+    print("Subzero proxy key (use as OpenAI client api_key):")
+    print(f"  {proxy_key}")
+    print()
+    print("OpenAI Python client one-liner change:")
+    print(f'  base_url="{BASE_URL}/v1"')
+    print(f'  api_key="{proxy_key[:16]}..."')
+    print("  stream=False  # required for v1")
+    print()
+
+    proxy_client = SubzeroClient(api_key=proxy_key, base_url=BASE_URL)
+    try:
+        response = proxy_client.proxy.chat.completions(
+            model="gpt-4o",
+            messages=[
+                {
+                    "role": "user",
+                    "content": "Summarize account for SSN 123-45-6789 in one sentence.",
+                }
+            ],
+        )
+    except Exception as exc:
+        print(f"POST /v1/chat/completions failed: {exc}", file=sys.stderr)
+        if UPSTREAM_OPENAI_KEY == "sk-demo-replace-me":
+            print(
+                "Note: set OPENAI_API_KEY for a live upstream call; "
+                "tokenization still runs before forward.",
+                file=sys.stderr,
+            )
+            return 0
+        return 1
+
+    print("POST /v1/chat/completions -> 200")
+    print(json.dumps(response, indent=2)[:500])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

iceberg_subzero-0.1.0/examples/vault_loop.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Vault loop demo: tokenize → search → reveal → delete.
+
+Delete is the one vault step that requires an admin-scoped API key — there is no
+delegatable delete-scoped key at the HTTP layer (per Phase 1B).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from subzero import SubzeroClient
+from subzero.exceptions import AuthorizationError, NotFoundError
+
+from _bootstrap import platform_bootstrap_client
+
+BASE_URL = os.environ.get("SUBZERO_BASE_URL", "http://127.0.0.1:8000")
+SSN_VALUE = "123-45-6789"
+
+
+def main() -> int:
+    bootstrap = platform_bootstrap_client(BASE_URL)
+
+    tenant = bootstrap.admin.create_tenant(name="Vault Loop Demo", slug="vault-loop-sdk")
+    tenant_id = tenant.id
+    admin_key = tenant.bootstrap_api_key
+    if not admin_key:
+        print("Expected bootstrap_api_key", file=sys.stderr)
+        return 1
+
+    admin = SubzeroClient(api_key=admin_key, base_url=BASE_URL)
+    admin.admin.create_entity_type(tenant_id, name="SSN", deterministic=True)
+
+    tokenize_key = admin.admin.create_api_key(tenant_id, name="tokenize", scope="tokenize").secret
+    reveal_key_record = admin.admin.create_api_key(tenant_id, name="reveal", scope="reveal")
+    reveal_key = reveal_key_record.secret
+    if not tokenize_key or not reveal_key:
+        print("Expected scoped key secrets", file=sys.stderr)
+        return 1
+
+    admin.admin.create_policy(
+        tenant_id,
+        api_key_id=reveal_key_record.id,
+        entity_type="SSN",
+        action="reveal",
+    )
+
+    tokenize_client = SubzeroClient(api_key=tokenize_key, base_url=BASE_URL)
+    reveal_client = SubzeroClient(api_key=reveal_key, base_url=BASE_URL)
+    admin_client = SubzeroClient(api_key=admin_key, base_url=BASE_URL)
+
+    token = tokenize_client.tokenize("SSN", SSN_VALUE).token
+    print(f"tokenize -> {token}")
+
+    found = tokenize_client.search("SSN", SSN_VALUE).token
+    assert found == token
+    print("search -> hit")
+
+    try:
+        tokenize_client.reveal(token)
+    except AuthorizationError:
+        print("reveal with tokenize key -> denied (expected)")
+    else:
+        print("expected reveal denial with tokenize key", file=sys.stderr)
+        return 1
+
+    plaintext = reveal_client.reveal(token).value
+    assert plaintext == SSN_VALUE
+    print(f"reveal with reveal key -> {plaintext}")
+
+    admin_client.delete_token(token)
+    print("delete with admin key -> ok")
+
+    try:
+        tokenize_client.search("SSN", SSN_VALUE)
+    except NotFoundError:
+        print("search after delete -> 404 (expected)")
+    else:
+        print("expected search miss after delete", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

iceberg_subzero-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "iceberg-subzero"
+version = "0.1.0"
+description = "Python client for the Subzero tokenization vault and LLM proxy"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+auth = [
+    "pyotp>=2.9.0",
+]
+openai = [
+    "openai>=1.0.0",
+]
+dev = [
+    "pytest>=8.3.0",
+    "respx>=0.22.0",
+    "openai>=1.0.0",
+    "pyotp>=2.9.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/subzero"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

iceberg_subzero-0.1.0/src/subzero/__init__.py

@@ -0,0 +1,43 @@
+from subzero.auth import AuthResource
+from subzero.client import SubzeroClient
+from subzero.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    NotFoundError,
+    PolicyDeniedError,
+    SubzeroAPIError,
+    SubzeroNotReadyError,
+)
+from subzero.members import MembersResource
+from subzero.openai import create_openai_client
+from subzero.types import (
+    AcceptInviteResult,
+    LoginResult,
+    MeResult,
+    MemberResult,
+    MfaEnrollConfirmResult,
+    MfaEnrollStartResult,
+    TokenResult,
+)
+
+__all__ = [
+    "SubzeroClient",
+    "AuthResource",
+    "MembersResource",
+    "create_openai_client",
+    "LoginResult",
+    "TokenResult",
+    "MfaEnrollStartResult",
+    "MfaEnrollConfirmResult",
+    "AcceptInviteResult",
+    "MeResult",
+    "MemberResult",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConflictError",
+    "NotFoundError",
+    "PolicyDeniedError",
+    "SubzeroAPIError",
+    "SubzeroNotReadyError",
+]