iceberg-subzero 0.1.0__py3-none-any.whl

iceberg_subzero-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+subzero/__init__.py,sha256=MmL2CriJloDNmHj6m5qwi0W4OjUm4SWFV8zf6ki1SyU,1016
+subzero/_http.py,sha256=VByOmsY7Xxhbtfdz5C4ksBkylhsgG2Ie_IxLLNrXIuU,6429
+subzero/admin.py,sha256=WgZeiL72JAOCN3LBIYYHLSLYkQD2IW89TpUCJC8T74o,9529
+subzero/auth.py,sha256=kCTG_7SFaAXdldoFax_ajGCEB-Dk5FBJVEvBu_z2Hek,7944
+subzero/client.py,sha256=Tenrn14QamCZmP9GCNFHdUiHsNyVXOPLxZXuxj53L6w,3203
+subzero/exceptions.py,sha256=jCq4Ec8Pemty_347pCM6epcD54SZtygBIWq6C4HZE3k,812
+subzero/members.py,sha256=snUOMX_C3iBe8JCAA-s6e-fVnzB9aOkzlUiJ5w-MimM,2230
+subzero/openai.py,sha256=tfWvAjclLS-ZRLrur3S4QCK5XPcWsM2nASIBpFWib_k,786
+subzero/proxy.py,sha256=f3EULiF7jSWNOt1vkcPZLv9cWNLTIkcoeLpPCFAq9yo,1338
+subzero/types.py,sha256=xvVjGyH31p4LmY1Hiwc5HhXFY9NZi_BDManED0U0EZc,3402
+iceberg_subzero-0.1.0.dist-info/METADATA,sha256=Adkc7jVtkwf9SCBiONAtrnpHgkntkZFLS0q20xXdSVE,5001
+iceberg_subzero-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+iceberg_subzero-0.1.0.dist-info/RECORD,,

iceberg_subzero-0.1.0.dist-info/WHEEL

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

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",
+]

subzero/_http.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+import httpx
+
+from subzero.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    NotFoundError,
+    PolicyDeniedError,
+    SubzeroAPIError,
+    SubzeroNotReadyError,
+)
+
+AuthMode = bool | Literal["api_key", "access_token", "none"]
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        access_token: str | None = None,
+        base_url: str,
+        timeout: float = 60.0,
+    ) -> None:
+        self._api_key = api_key
+        self._access_token = access_token
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(base_url=self._base_url, timeout=timeout)
+
+    @property
+    def access_token(self) -> str | None:
+        return self._access_token
+
+    def set_access_token(self, token: str | None) -> None:
+        self._access_token = token
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HTTPClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _headers(
+        self,
+        extra: dict[str, str] | None = None,
+        *,
+        auth: AuthMode = True,
+    ) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if auth is True:
+            if self._api_key is not None:
+                headers["Authorization"] = f"Bearer {self._api_key}"
+            elif self._access_token is not None:
+                headers["Authorization"] = f"Bearer {self._access_token}"
+        elif auth == "api_key":
+            if self._api_key is not None:
+                headers["Authorization"] = f"Bearer {self._api_key}"
+        elif auth == "access_token":
+            if self._access_token is not None:
+                headers["Authorization"] = f"Bearer {self._access_token}"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+
+        reason: str | None = None
+        detail = response.text
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                detail = str(body.get("detail", detail))
+                raw_reason = body.get("reason")
+                if isinstance(raw_reason, str):
+                    reason = raw_reason
+        except json.JSONDecodeError:
+            pass
+
+        status = response.status_code
+        if status == 401:
+            raise AuthenticationError(detail, status_code=status, reason=reason, response=response)
+        if status == 403:
+            if reason == "policy_denied":
+                raise PolicyDeniedError(detail, status_code=status, reason=reason, response=response)
+            if reason in {"insufficient_scope", "tenant_mismatch"}:
+                raise AuthorizationError(detail, status_code=status, reason=reason, response=response)
+            raise SubzeroAPIError(detail, status_code=status, reason=reason, response=response)
+        if status == 404:
+            raise NotFoundError(detail, status_code=status, reason=reason, response=response)
+        if status == 409:
+            raise ConflictError(detail, status_code=status, reason=reason, response=response)
+        raise SubzeroAPIError(detail, status_code=status, reason=reason, response=response)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        auth: AuthMode = True,
+    ) -> httpx.Response:
+        request_headers = self._headers(headers, auth=auth)
+        response = self._client.request(
+            method,
+            path,
+            json=json_body,
+            headers=request_headers,
+            params=params,
+        )
+        self._raise_for_status(response)
+        return response
+
+    def get_json(
+        self,
+        path: str,
+        *,
+        auth: AuthMode = True,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        response = self.request("GET", path, auth=auth, params=params)
+        if not response.content:
+            return None
+        return response.json()
+
+    def post_json(
+        self,
+        path: str,
+        body: dict[str, Any] | None = None,
+        *,
+        auth: AuthMode = True,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        response = self.request("POST", path, json_body=body, auth=auth, headers=headers)
+        if not response.content:
+            return None
+        return response.json()
+
+    def patch_json(
+        self,
+        path: str,
+        body: dict[str, Any],
+        *,
+        auth: AuthMode = True,
+    ) -> Any:
+        response = self.request("PATCH", path, json_body=body, auth=auth)
+        if not response.content:
+            return None
+        return response.json()
+
+    def delete(self, path: str, *, auth: AuthMode = True) -> None:
+        self.request("DELETE", path, auth=auth)
+
+    @staticmethod
+    def encode_token_path(token: str) -> str:
+        from urllib.parse import quote
+
+        return quote(token, safe="")
+
+    def health(self) -> dict[str, Any]:
+        return self.get_json("/v1/health", auth="none")
+
+    def ready(self, base_url: str) -> dict[str, Any]:
+        try:
+            response = self._client.get("/v1/ready")
+        except httpx.RequestError as exc:
+            raise SubzeroNotReadyError(
+                f"Subzero API not reachable at {base_url} — is `docker compose up` running? "
+                f"Migrations applied?",
+            ) from exc
+
+        if response.status_code != 200:
+            raise SubzeroNotReadyError(
+                f"Subzero API not ready at {base_url} — is `docker compose up` running? "
+                f"Migrations applied?",
+            )
+
+        body = response.json()
+        if not isinstance(body, dict) or body.get("status") != "ready":
+            raise SubzeroNotReadyError(
+                f"Subzero API not ready at {base_url} — is `docker compose up` running? "
+                f"Migrations applied?",
+            )
+        return body

subzero/admin.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from subzero._http import HTTPClient
+from subzero.types import (
+    ApiKeyResult,
+    ApiKeyScope,
+    AuditEventResult,
+    AuditLogPageResult,
+    EntityTypeResult,
+    LlmConfigResult,
+    PolicyAction,
+    PolicyRuleResult,
+    PublishableKeyResult,
+    TenantResult,
+    parse_datetime,
+)
+
+
+class AdminResource:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def create_tenant(self, *, name: str, slug: str) -> TenantResult:
+        body = self._http.post_json(
+            "/v1/tenants",
+            {"name": name, "slug": slug},
+            auth="access_token",
+        )
+        return TenantResult(
+            id=body["id"],
+            name=body["name"],
+            slug=body["slug"],
+            created_at=parse_datetime(body["created_at"]),
+            bootstrap_api_key=body.get("bootstrap_api_key"),
+        )
+
+    def get_tenant(self, tenant_id: str) -> TenantResult:
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}", auth="access_token")
+        return TenantResult(
+            id=body["id"],
+            name=body["name"],
+            slug=body["slug"],
+            created_at=parse_datetime(body["created_at"]),
+        )
+
+    def create_entity_type(
+        self,
+        tenant_id: str,
+        *,
+        name: str,
+        description: str | None = None,
+        deterministic: bool = False,
+        match_pattern: str | None = None,
+    ) -> EntityTypeResult:
+        payload: dict[str, Any] = {
+            "name": name,
+            "deterministic": deterministic,
+        }
+        if description is not None:
+            payload["description"] = description
+        if match_pattern is not None:
+            payload["match_pattern"] = match_pattern
+        body = self._http.post_json(f"/v1/tenants/{tenant_id}/entity-types", payload)
+        return _entity_type_from_body(body)
+
+    def list_entity_types(self, tenant_id: str) -> list[EntityTypeResult]:
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}/entity-types")
+        return [_entity_type_from_body(item) for item in body]
+
+    def create_policy(
+        self,
+        tenant_id: str,
+        *,
+        api_key_id: str,
+        entity_type: str,
+        action: PolicyAction,
+    ) -> PolicyRuleResult:
+        body = self._http.post_json(
+            f"/v1/tenants/{tenant_id}/policies",
+            {
+                "api_key_id": api_key_id,
+                "entity_type": entity_type,
+                "action": action,
+            },
+        )
+        return _policy_from_body(body)
+
+    def list_policies(self, tenant_id: str) -> list[PolicyRuleResult]:
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}/policies")
+        return [_policy_from_body(item) for item in body]
+
+    def delete_policy(self, tenant_id: str, rule_id: str) -> None:
+        self._http.delete(f"/v1/tenants/{tenant_id}/policies/{rule_id}")
+
+    def create_api_key(
+        self,
+        tenant_id: str,
+        *,
+        name: str,
+        scope: ApiKeyScope,
+    ) -> ApiKeyResult:
+        body = self._http.post_json(
+            f"/v1/tenants/{tenant_id}/api-keys",
+            {"name": name, "scope": scope},
+        )
+        return _api_key_from_body(body, include_secret=True)
+
+    def list_api_keys(self, tenant_id: str) -> list[ApiKeyResult]:
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}/api-keys")
+        return [_api_key_from_body(item) for item in body]
+
+    def revoke_api_key(self, tenant_id: str, key_id: str) -> ApiKeyResult:
+        response = self._http.request("DELETE", f"/v1/tenants/{tenant_id}/api-keys/{key_id}")
+        return _api_key_from_body(response.json())
+
+    def create_publishable_key(
+        self,
+        tenant_id: str,
+        *,
+        name: str,
+        allowed_origins: list[str],
+        rate_limit_rpm: int = 60,
+        integration_mode: Literal["secure", "lite"] = "secure",
+        risk_acknowledged: bool = False,
+    ) -> PublishableKeyResult:
+        payload: dict[str, Any] = {
+            "name": name,
+            "allowed_origins": allowed_origins,
+            "rate_limit_rpm": rate_limit_rpm,
+            "integration_mode": integration_mode,
+        }
+        if integration_mode == "lite":
+            payload["risk_acknowledged"] = risk_acknowledged
+        body = self._http.post_json(
+            f"/v1/tenants/{tenant_id}/publishable-keys",
+            payload,
+        )
+        return _publishable_key_from_body(body)
+
+    def list_publishable_keys(self, tenant_id: str) -> list[PublishableKeyResult]:
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}/publishable-keys")
+        return [_publishable_key_from_body(item) for item in body]
+
+    def revoke_publishable_key(self, tenant_id: str, key_id: str) -> PublishableKeyResult:
+        response = self._http.request(
+            "DELETE", f"/v1/tenants/{tenant_id}/publishable-keys/{key_id}"
+        )
+        return _publishable_key_from_body(response.json())
+
+    def create_llm_config(
+        self,
+        tenant_id: str,
+        *,
+        provider: str = "openai",
+        base_url: str,
+        api_key: str,
+    ) -> LlmConfigResult:
+        body = self._http.post_json(
+            f"/v1/tenants/{tenant_id}/llm-config",
+            {
+                "provider": provider,
+                "base_url": base_url,
+                "api_key": api_key,
+            },
+        )
+        return _llm_config_from_body(body)
+
+    def get_llm_config(self, tenant_id: str) -> LlmConfigResult | None:
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}/llm-config")
+        if body is None:
+            return None
+        return _llm_config_from_body(body)
+
+    def list_audit_events(
+        self,
+        tenant_id: str,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+        order: Literal["asc", "desc"] = "desc",
+        event_type: str | None = None,
+        actor: str | None = None,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+    ) -> AuditLogPageResult:
+        params: dict[str, Any] = {
+            "limit": limit,
+            "offset": offset,
+            "order": order,
+        }
+        if event_type is not None:
+            params["event_type"] = event_type
+        if actor is not None:
+            params["actor"] = actor
+        if date_from is not None:
+            params["date_from"] = date_from.isoformat()
+        if date_to is not None:
+            params["date_to"] = date_to.isoformat()
+
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}/audit", params=params)
+        return _audit_log_page_from_body(body)
+
+
+def _entity_type_from_body(body: dict[str, Any]) -> EntityTypeResult:
+    return EntityTypeResult(
+        id=body["id"],
+        name=body["name"],
+        description=body.get("description"),
+        deterministic=body["deterministic"],
+        match_pattern=body.get("match_pattern"),
+        created_at=parse_datetime(body["created_at"]),
+    )
+
+
+def _policy_from_body(body: dict[str, Any]) -> PolicyRuleResult:
+    return PolicyRuleResult(
+        id=body["id"],
+        principal=body["principal"],
+        entity_type=body["entity_type"],
+        action=body["action"],
+        created_at=parse_datetime(body["created_at"]),
+    )
+
+
+def _api_key_from_body(body: dict[str, Any], *, include_secret: bool = False) -> ApiKeyResult:
+    return ApiKeyResult(
+        id=body["id"],
+        name=body["name"],
+        prefix=body["prefix"],
+        scope=body["scope"],
+        revoked_at=parse_datetime(body["revoked_at"]) if body.get("revoked_at") else None,
+        created_at=parse_datetime(body["created_at"]),
+        secret=body.get("secret") if include_secret else None,
+    )
+
+
+def _publishable_key_from_body(body: dict[str, Any]) -> PublishableKeyResult:
+    return PublishableKeyResult(
+        id=body["id"],
+        name=body["name"],
+        key=body["key"],
+        allowed_origins=body["allowed_origins"],
+        rate_limit_rpm=body["rate_limit_rpm"],
+        integration_mode=body.get("integration_mode", "secure"),
+        revoked_at=parse_datetime(body["revoked_at"]) if body.get("revoked_at") else None,
+        created_at=parse_datetime(body["created_at"]),
+    )
+
+
+def _llm_config_from_body(body: dict[str, Any]) -> LlmConfigResult:
+    return LlmConfigResult(
+        id=body["id"],
+        provider=body["provider"],
+        base_url=body["base_url"],
+        is_active=body["is_active"],
+        created_at=parse_datetime(body["created_at"]),
+    )
+
+
+def _audit_event_from_body(body: dict[str, Any]) -> AuditEventResult:
+    return AuditEventResult(
+        id=body["id"],
+        tenant_id=body["tenant_id"],
+        event_type=body["event_type"],
+        actor=body["actor"],
+        resource=body.get("resource"),
+        outcome=body["outcome"],
+        metadata=body.get("metadata"),
+        created_at=parse_datetime(body["created_at"]),
+    )
+
+
+def _audit_log_page_from_body(body: dict[str, Any]) -> AuditLogPageResult:
+    return AuditLogPageResult(
+        items=[_audit_event_from_body(item) for item in body["items"]],
+        total=body["total"],
+        limit=body["limit"],
+        offset=body["offset"],
+    )

subzero/auth.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from subzero._http import HTTPClient
+from subzero.exceptions import SubzeroAPIError
+from subzero.types import (
+    AcceptInviteResult,
+    LoginResult,
+    MeResult,
+    MfaEnrollConfirmResult,
+    MfaEnrollStartResult,
+    TokenResult,
+    parse_datetime,
+)
+
+
+def _totp_code(secret: str) -> str:
+    try:
+        import pyotp
+    except ImportError as exc:
+        raise SubzeroAPIError(
+            "pyotp is required to generate TOTP codes — pip install 'subzero[auth]' "
+            "or pass totp_code explicitly.",
+        ) from exc
+    return pyotp.TOTP(secret).now()
+
+
+class AuthResource:
+    """Dashboard human auth — login, MFA, refresh (cookie-based), password reset."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def login(
+        self,
+        *,
+        email: str,
+        password: str,
+        tenant_slug: str | None = None,
+    ) -> LoginResult:
+        payload: dict[str, str] = {"email": email, "password": password}
+        if tenant_slug is not None:
+            payload["tenant_slug"] = tenant_slug
+        body = self._http.post_json("/v1/auth/login", payload, auth="none")
+        return LoginResult(
+            access_token=body.get("access_token"),
+            pre_auth_token=body.get("pre_auth_token"),
+            mfa_required=body.get("mfa_required", False),
+            mfa_enrollment_required=body.get("mfa_enrollment_required", False),
+        )
+
+    def mfa_verify(
+        self,
+        *,
+        pre_auth_token: str,
+        code: str | None = None,
+        recovery_code: str | None = None,
+    ) -> TokenResult:
+        payload: dict[str, str] = {"pre_auth_token": pre_auth_token}
+        if code is not None:
+            payload["code"] = code
+        if recovery_code is not None:
+            payload["recovery_code"] = recovery_code
+        response = self._http._client.post(
+            "/v1/auth/mfa/verify",
+            json=payload,
+            headers={"Content-Type": "application/json"},
+        )
+        self._http._raise_for_status(response)
+        body = response.json()
+        token = TokenResult(access_token=body["access_token"])
+        self._http.set_access_token(token.access_token)
+        return token
+
+    def mfa_enroll_start(self, *, pre_auth_token: str) -> MfaEnrollStartResult:
+        body = self._http.post_json(
+            "/v1/auth/mfa/enroll/start",
+            {"pre_auth_token": pre_auth_token},
+            auth="none",
+        )
+        return MfaEnrollStartResult(
+            otpauth_uri=body["otpauth_uri"],
+            secret=body.get("secret"),
+        )
+
+    def mfa_enroll_confirm(
+        self,
+        *,
+        pre_auth_token: str,
+        code: str,
+    ) -> MfaEnrollConfirmResult:
+        response = self._http._client.post(
+            "/v1/auth/mfa/enroll/confirm",
+            json={"pre_auth_token": pre_auth_token, "code": code},
+            headers={"Content-Type": "application/json"},
+        )
+        self._http._raise_for_status(response)
+        body = response.json()
+        result = MfaEnrollConfirmResult(
+            access_token=body["access_token"],
+            recovery_codes=body["recovery_codes"],
+        )
+        self._http.set_access_token(result.access_token)
+        return result
+
+    def refresh(self) -> TokenResult:
+        response = self._http._client.post("/v1/auth/refresh")
+        self._http._raise_for_status(response)
+        body = response.json()
+        token = TokenResult(access_token=body["access_token"])
+        self._http.set_access_token(token.access_token)
+        return token
+
+    def logout(self) -> None:
+        self._http.post_json("/v1/auth/logout", {}, auth="access_token")
+        self._http.set_access_token(None)
+
+    def me(self) -> MeResult:
+        body = self._http.get_json("/v1/auth/me", auth="access_token")
+        return MeResult(
+            principal_type=body["principal_type"],
+            id=body["id"],
+            email=body["email"],
+            role=body["role"],
+            tenant_id=body.get("tenant_id"),
+            mfa_verified=body["mfa_verified"],
+            mfa_enrolled=body["mfa_enrolled"],
+        )
+
+    def accept_invite(self, *, token: str, password: str) -> AcceptInviteResult:
+        body = self._http.post_json(
+            "/v1/auth/accept-invite",
+            {"token": token, "password": password},
+            auth="none",
+        )
+        return AcceptInviteResult(
+            pre_auth_token=body["pre_auth_token"],
+            mfa_enrollment_required=body.get("mfa_enrollment_required", True),
+        )
+
+    def request_password_reset(
+        self,
+        *,
+        email: str,
+        tenant_slug: str | None = None,
+    ) -> None:
+        payload: dict[str, str] = {"email": email}
+        if tenant_slug is not None:
+            payload["tenant_slug"] = tenant_slug
+        self._http.post_json("/v1/auth/password/reset/request", payload, auth="none")
+
+    def confirm_password_reset(self, *, token: str, new_password: str) -> None:
+        self._http.post_json(
+            "/v1/auth/password/reset/confirm",
+            {"token": token, "new_password": new_password},
+            auth="none",
+        )
+
+    def login_platform(
+        self,
+        *,
+        email: str,
+        password: str,
+        totp_code: str | None = None,
+        totp_secret: str | None = None,
+    ) -> str:
+        """Log in as platform admin with mandatory MFA; returns and stores access JWT."""
+        return self._complete_login(
+            email=email,
+            password=password,
+            tenant_slug=None,
+            totp_code=totp_code,
+            totp_secret=totp_secret,
+        )
+
+    def login_tenant(
+        self,
+        *,
+        email: str,
+        password: str,
+        tenant_slug: str,
+        totp_code: str | None = None,
+        totp_secret: str | None = None,
+    ) -> str:
+        """Log in as a tenant member/admin; returns and stores access JWT."""
+        return self._complete_login(
+            email=email,
+            password=password,
+            tenant_slug=tenant_slug,
+            totp_code=totp_code,
+            totp_secret=totp_secret,
+        )
+
+    def _complete_login(
+        self,
+        *,
+        email: str,
+        password: str,
+        tenant_slug: str | None,
+        totp_code: str | None,
+        totp_secret: str | None,
+    ) -> str:
+        login = self.login(email=email, password=password, tenant_slug=tenant_slug)
+        if login.access_token:
+            self._http.set_access_token(login.access_token)
+            return login.access_token
+
+        pre_auth = login.pre_auth_token
+        if not pre_auth:
+            raise SubzeroAPIError("Login did not return a pre_auth_token")
+
+        code = totp_code
+        if code is None and totp_secret is not None:
+            code = _totp_code(totp_secret)
+
+        if login.mfa_enrollment_required:
+            if code is None:
+                enroll = self.mfa_enroll_start(pre_auth_token=pre_auth)
+                raise SubzeroAPIError(
+                    "MFA enrollment required. Scan otpauth_uri and call mfa_enroll_confirm, "
+                    f"or pass totp_code/totp_secret. Dev secret: {enroll.secret!r}"
+                )
+            result = self.mfa_enroll_confirm(pre_auth_token=pre_auth, code=code)
+            return result.access_token
+
+        if login.mfa_required:
+            if code is None:
+                raise SubzeroAPIError(
+                    "MFA verification required — pass totp_code or totp_secret"
+                )
+            return self.mfa_verify(pre_auth_token=pre_auth, code=code).access_token
+
+        raise SubzeroAPIError("Unexpected login response — MFA expected")

subzero/client.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from subzero._http import HTTPClient
+from subzero.admin import AdminResource
+from subzero.auth import AuthResource
+from subzero.members import MembersResource
+from subzero.proxy import ProxyResource
+from subzero.types import RevealGrantResult, RevealResult, SearchResult, TokenizeResult, parse_datetime
+
+
+class SubzeroClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        access_token: str | None = None,
+        base_url: str = "http://127.0.0.1:8000",
+        timeout: float = 60.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._http = HTTPClient(
+            api_key=api_key,
+            access_token=access_token,
+            base_url=self._base_url,
+            timeout=timeout,
+        )
+        self.auth = AuthResource(self._http)
+        self.admin = AdminResource(self._http)
+        self.members = MembersResource(self._http)
+        self.proxy = ProxyResource(self._http)
+
+    @property
+    def access_token(self) -> str | None:
+        return self._http.access_token
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> SubzeroClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def health(self) -> dict:
+        return self._http.health()
+
+    def ready(self) -> dict:
+        return self._http.ready(self._base_url)
+
+    def tokenize(self, entity_type: str, value: str) -> TokenizeResult:
+        body = self._http.post_json(
+            "/v1/tokenize",
+            {"entity_type": entity_type, "value": value},
+            auth="api_key",
+        )
+        return TokenizeResult(token=body["token"], entity_type=body["entity_type"])
+
+    def search(self, entity_type: str, value: str) -> SearchResult:
+        body = self._http.post_json(
+            "/v1/search",
+            {"entity_type": entity_type, "value": value},
+            auth="api_key",
+        )
+        return SearchResult(token=body["token"])
+
+    def reveal(self, token: str) -> RevealResult:
+        body = self._http.post_json("/v1/reveal", {"token": token}, auth="api_key")
+        return RevealResult(
+            token=body["token"],
+            entity_type=body["entity_type"],
+            value=body["value"],
+        )
+
+    def create_reveal_grant(
+        self,
+        token: str,
+        *,
+        client_public_key_jwk: dict,
+        allowed_origin: str | None = None,
+    ) -> RevealGrantResult:
+        payload: dict[str, object] = {
+            "token": token,
+            "client_public_key_jwk": client_public_key_jwk,
+        }
+        if allowed_origin is not None:
+            payload["allowed_origin"] = allowed_origin
+        body = self._http.post_json("/v1/reveal/grants", payload, auth="api_key")
+        return RevealGrantResult(
+            grant_id=body["grant_id"],
+            expires_at=parse_datetime(body["expires_at"]),
+        )
+
+    def delete_token(self, token: str) -> None:
+        encoded = HTTPClient.encode_token_path(token)
+        self._http.delete(f"/v1/tokens/{encoded}", auth="api_key")

subzero/exceptions.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class SubzeroAPIError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        reason: str | None = None,
+        response: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.reason = reason
+        self.response = response
+
+
+class AuthenticationError(SubzeroAPIError):
+    pass
+
+
+class AuthorizationError(SubzeroAPIError):
+    pass
+
+
+class PolicyDeniedError(SubzeroAPIError):
+    pass
+
+
+class NotFoundError(SubzeroAPIError):
+    pass
+
+
+class ConflictError(SubzeroAPIError):
+    pass
+
+
+class SubzeroNotReadyError(SubzeroAPIError):
+    pass

subzero/members.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from subzero._http import HTTPClient
+from subzero.types import MemberResult, parse_datetime
+
+MemberRole = Literal["admin", "member"]
+
+
+class MembersResource:
+    """Tenant member invites and management (tenant admin or platform admin JWT)."""
+
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def invite(
+        self,
+        tenant_id: str,
+        *,
+        email: str,
+        role: MemberRole = "member",
+    ) -> MemberResult:
+        body = self._http.post_json(
+            f"/v1/tenants/{tenant_id}/members",
+            {"email": email, "role": role},
+            auth="access_token",
+        )
+        return _member_from_body(body)
+
+    def list(self, tenant_id: str) -> list[MemberResult]:
+        body = self._http.get_json(f"/v1/tenants/{tenant_id}/members", auth="access_token")
+        return [_member_from_body(item) for item in body]
+
+    def update(
+        self,
+        tenant_id: str,
+        member_id: str,
+        *,
+        role: MemberRole | None = None,
+        disabled: bool | None = None,
+    ) -> MemberResult:
+        payload: dict[str, Any] = {}
+        if role is not None:
+            payload["role"] = role
+        if disabled is not None:
+            payload["disabled"] = disabled
+        body = self._http.patch_json(
+            f"/v1/tenants/{tenant_id}/members/{member_id}",
+            payload,
+            auth="access_token",
+        )
+        return _member_from_body(body)
+
+
+def _member_from_body(body: dict[str, Any]) -> MemberResult:
+    return MemberResult(
+        id=body["id"],
+        email=body["email"],
+        role=body["role"],
+        status=body["status"],
+        mfa_enrolled_at=parse_datetime(body["mfa_enrolled_at"])
+        if body.get("mfa_enrolled_at")
+        else None,
+        invited_at=parse_datetime(body["invited_at"]) if body.get("invited_at") else None,
+        last_login_at=parse_datetime(body["last_login_at"])
+        if body.get("last_login_at")
+        else None,
+        created_at=parse_datetime(body["created_at"]),
+        invite_token=body.get("invite_token"),
+    )

subzero/openai.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def create_openai_client(
+    *,
+    api_key: str,
+    base_url: str,
+    detokenize: bool = False,
+    **kwargs: Any,
+):
+    try:
+        from openai import OpenAI
+    except ImportError as exc:
+        raise ImportError(
+            "Install the openai extra: pip install 'subzero[openai]'",
+        ) from exc
+
+    default_headers: dict[str, str] = {}
+    if detokenize:
+        default_headers["X-Subzero-Detokenize"] = "true"
+
+    client_kwargs = dict(kwargs)
+    if default_headers:
+        existing = client_kwargs.pop("default_headers", {})
+        client_kwargs["default_headers"] = {**existing, **default_headers}
+
+    return OpenAI(api_key=api_key, base_url=base_url, **client_kwargs)

subzero/proxy.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+from subzero._http import HTTPClient
+from subzero.exceptions import SubzeroAPIError
+
+
+class ProxyChatResource:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def completions(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: bool = False,
+        detokenize: bool = False,
+        **extra: Any,
+    ) -> dict[str, Any]:
+        if stream:
+            raise SubzeroAPIError(
+                "Streaming is not supported in subzero SDK v1 — pass stream=False",
+            )
+
+        headers: dict[str, str] = {}
+        if detokenize:
+            headers["X-Subzero-Detokenize"] = "true"
+
+        payload: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "stream": False,
+            **extra,
+        }
+        body = self._http.post_json(
+            "/v1/chat/completions",
+            payload,
+            headers=headers or None,
+        )
+        if not isinstance(body, dict):
+            raise SubzeroAPIError("Expected JSON object from chat/completions")
+        return body
+
+
+class ProxyResource:
+    def __init__(self, http: HTTPClient) -> None:
+        self.chat = ProxyChatResource(http)

subzero/types.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class TokenizeResult:
+    token: str
+    entity_type: str
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    token: str
+
+
+@dataclass(frozen=True)
+class RevealResult:
+    token: str
+    entity_type: str
+    value: str
+
+
+@dataclass(frozen=True)
+class TenantResult:
+    id: str
+    name: str
+    slug: str
+    created_at: datetime
+    bootstrap_api_key: str | None = None
+
+
+@dataclass(frozen=True)
+class EntityTypeResult:
+    id: str
+    name: str
+    description: str | None
+    deterministic: bool
+    match_pattern: str | None
+    created_at: datetime
+
+
+@dataclass(frozen=True)
+class PolicyRuleResult:
+    id: str
+    principal: str
+    entity_type: str
+    action: str
+    created_at: datetime
+
+
+@dataclass(frozen=True)
+class ApiKeyResult:
+    id: str
+    name: str
+    prefix: str
+    scope: str
+    revoked_at: datetime | None
+    created_at: datetime
+    secret: str | None = None
+
+
+@dataclass(frozen=True)
+class AuditEventResult:
+    id: str
+    tenant_id: str
+    event_type: str
+    actor: str
+    resource: str | None
+    outcome: str
+    metadata: dict[str, Any] | None
+    created_at: datetime
+
+
+@dataclass(frozen=True)
+class AuditLogPageResult:
+    items: list[AuditEventResult]
+    total: int
+    limit: int
+    offset: int
+
+
+@dataclass(frozen=True)
+class LlmConfigResult:
+    id: str
+    provider: str
+    base_url: str
+    is_active: bool
+    created_at: datetime
+
+
+@dataclass(frozen=True)
+class RevealGrantResult:
+    grant_id: str
+    expires_at: datetime
+
+
+@dataclass(frozen=True)
+class PublishableKeyResult:
+    id: str
+    name: str
+    key: str
+    allowed_origins: list[str]
+    rate_limit_rpm: int
+    integration_mode: str
+    revoked_at: datetime | None
+    created_at: datetime
+
+
+ApiKeyScope = Literal["tokenize", "reveal", "proxy", "admin"]
+PolicyAction = Literal["reveal", "delete"]
+MemberRole = Literal["admin", "member"]
+
+
+@dataclass(frozen=True)
+class LoginResult:
+    access_token: str | None
+    pre_auth_token: str | None
+    mfa_required: bool
+    mfa_enrollment_required: bool
+
+
+@dataclass(frozen=True)
+class TokenResult:
+    access_token: str
+
+
+@dataclass(frozen=True)
+class MfaEnrollStartResult:
+    otpauth_uri: str
+    secret: str | None
+
+
+@dataclass(frozen=True)
+class MfaEnrollConfirmResult:
+    access_token: str
+    recovery_codes: list[str]
+
+
+@dataclass(frozen=True)
+class AcceptInviteResult:
+    pre_auth_token: str
+    mfa_enrollment_required: bool
+
+
+@dataclass(frozen=True)
+class MeResult:
+    principal_type: Literal["platform_user", "member"]
+    id: str
+    email: str
+    role: str
+    tenant_id: str | None
+    mfa_verified: bool
+    mfa_enrolled: bool
+
+
+@dataclass(frozen=True)
+class MemberResult:
+    id: str
+    email: str
+    role: str
+    status: str
+    mfa_enrolled_at: datetime | None
+    invited_at: datetime | None
+    last_login_at: datetime | None
+    created_at: datetime
+    invite_token: str | None = None
+
+
+def parse_datetime(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def chat_completion_dict(**kwargs: Any) -> dict[str, Any]:
+    return dict(kwargs)