drukbox-python-sdk 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

{drukbox_python_sdk-0.1.0.dist-info → drukbox_python_sdk-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: drukbox-python-sdk
-Version: 0.1.0
+Version: 0.3.0
 Summary: Async Python client for Drukbox.
 Project-URL: Homepage, https://github.com/clawhaven/drukbox-python-sdk
 Project-URL: Repository, https://github.com/clawhaven/drukbox-python-sdk
@@ -71,6 +71,9 @@ Public exports live in `drukbox_sdk`:
 - `SandboxAPI`
 - `SandboxHost`
 - `SandboxTemplate`
+- `Secret`
+- `Issuer`
+- `ServiceAccount`
 - `DoctorReport` and `DoctorCheck`
 - `HTTPProxy` and `HTTPProxyAttachment`
 - `SandboxAPIError` and typed subclasses for auth, not found, conflict,
@@ -84,21 +87,66 @@ Supported host operations:
 - `list_hosts`
 - `renew_host`
 - `delete_host`
+- `refresh_secret`
 - `doctor`
 - `aclose`
 
 `create_host` supports the service's optional `image`, `env`, `expires_at`,
-`permanent`, `provider`, `instance_type`, `disk_gb`, `template`, and
-`Idempotency-Key` inputs. `instance_type` (provider-native size, e.g.
+`permanent`, `provider`, `instance_type`, `disk_gb`, `template`, `secrets`,
+and `Idempotency-Key` inputs. `instance_type` (provider-native size, e.g.
 `t3.xlarge` / `cx33`) and `disk_gb` pin the VM shape; omit either for the
 provider default. Omit `expires_at` for the default lease, pass a datetime for
 an explicit expiry, or pass `permanent=True` for a never-reaped host.
 `template` accepts a template ID. An explicit `image` wins over it.
 
+`secrets` gives the box credentials it never sees. Each entry is a `Secret`,
+a value the caller holds, or an `Issuer`, a URL Drukbox fetches the value
+from. The box gets a placeholder per entry in the service's variable, and the
+Drukbox swaps it on the way out. A custom service names its `host` and
+`auth_variable`:
+
+```python
+from drukbox_sdk import Issuer, Secret
+
+host = await sandbox.create_host(
+    secrets={
+        "anthropic": Issuer(
+            "https://mint.example/box-1/anthropic",
+            headers={"Authorization": "Bearer ..."},
+            refresh="1h",
+        ),
+        "openai": Secret("sk-..."),
+        "acme": Secret("ak_...", host="api.acme.test", auth_variable="ACME_TOKEN"),
+    },
+)
+```
+
+The response carries no secret. A service name Drukbox does not know raises
+`SandboxValidationError`. A deployment without the secrets proxy raises
+`SandboxConflictError`.
+
 `renew_host` extends a host's lease via `POST /hosts/{id}/renew`. Omit
 `expires_at` to extend by the service's default TTL; renewal never makes a host
 permanent.
 
+`SandboxHost.service_account` names the service account that created or
+claimed the host, `admin` for an admin key, or `None` for an unclaimed warm
+host.
+
+`refresh_secret` makes the service forget the current value of one secret on
+a host and fetch a new one from its issuer. A static secret raises
+`SandboxConflictError`; an issuer or exchange that did not answer raises
+`SandboxUnavailableError`.
+
+Supported service account operations, admin key only:
+
+- `create_service_account`
+- `remove_service_account`
+
+`create_service_account` returns a `ServiceAccount` with the token the
+service hands out once. Store it. `remove_service_account` revokes it on the
+next request.
+
 Supported template operations:
 
 - `create_template`
@@ -125,7 +173,8 @@ proxy at a host's backing VM (the host must be `bootstrapping` or `active`).
 
 `doctor` fetches `GET /doctor` — read-only dependency health. The service
 runs one cheap, non-mutating probe per dependency (database, active VM
-provider, Tailscale when enabled) and always responds 200, so callers branch
+provider, secrets exchange, Tailscale when enabled) and always responds 200,
+so callers branch
 on `DoctorReport.ok` rather than the HTTP status. A failed `DoctorCheck`
 carries a stable `hint` slug for remediation.
 

drukbox_python_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+drukbox_sdk/__init__.py,sha256=bU2rOTzC3GMXSpiXvoMVwFOuKJUPZWSXhnteaRFxT_Y,1012
+drukbox_sdk/api.py,sha256=eoXXnK8mkrSK9Q4tRSuVbN-6mSjbBTTeEsH_jF3U_wY,24118
+drukbox_sdk/exceptions.py,sha256=Vzs4zVOywWsWfiZm6vgQ65ScI3Nn7zLGVj-8eT1YAR0,2224
+drukbox_python_sdk-0.3.0.dist-info/METADATA,sha256=KL-_BzJPSEVgimNohBs8BIxhwcU8dreFTdVSihBlUaI,6599
+drukbox_python_sdk-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+drukbox_python_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=zM66rWL3BWGJBa_mZPnM0WUomSSZ1xtWVtGQovQ71M8,1078
+drukbox_python_sdk-0.3.0.dist-info/RECORD,,

drukbox_sdk/__init__.py

@@ -9,9 +9,12 @@ from .api import (
     DoctorReport,
     HTTPProxy,
     HTTPProxyAttachment,
+    Issuer,
     SandboxAPI,
     SandboxHost,
     SandboxTemplate,
+    Secret,
+    ServiceAccount,
 )
 from .exceptions import (
     SandboxAPIError,
@@ -29,6 +32,7 @@ __all__ = [
     "DoctorReport",
     "HTTPProxy",
     "HTTPProxyAttachment",
+    "Issuer",
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",
@@ -40,4 +44,6 @@ __all__ = [
     "SandboxTemplate",
     "SandboxUnavailableError",
     "SandboxValidationError",
+    "Secret",
+    "ServiceAccount",
 ]

drukbox_sdk/api.py

@@ -39,7 +39,7 @@ For env-backed config use :meth:`SandboxAPI.from_env`.
 import asyncio
 import os
 import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any, Self
 
@@ -85,10 +85,15 @@ class SandboxHost:
     different SSH auth model (exe.dev's edge proxy, Tailscale ACLs
     via tailscaled-SSH) return None here. A later ``get_host`` call
     always returns None — the key is not persisted server-side.
+
+    ``service_account`` names the service account that created or claimed
+    the host, ``"admin"`` for an admin key, or None for an unclaimed warm
+    host.
     """
 
     id: str
     name: str
+    service_account: str | None
     status: str
     provider: str
     image: str
@@ -108,6 +113,50 @@ class SandboxHost:
     expires_at: str | None
 
 
+@dataclass(frozen=True, kw_only=True)
+class _Service:
+    """The custom service fields of a secret. None is unset. An empty
+    ``auth_prefix`` is set, and Drukbox reads it as no prefix."""
+
+    host: str | None = None
+    auth_variable: str | None = None
+    auth_header: str | None = None
+    auth_prefix: str | None = None
+
+    def get_service(self) -> dict[str, Any]:
+        fields = {
+            "host": self.host,
+            "auth_variable": self.auth_variable,
+            "auth_header": self.auth_header,
+            "auth_prefix": self.auth_prefix,
+        }
+        return {name: value for name, value in fields.items() if value is not None}
+
+
+@dataclass(frozen=True)
+class Secret(_Service):
+    """A credential the caller holds."""
+
+    value: str = field(repr=False)
+
+    def entry(self) -> dict[str, Any]:
+        return {**self.get_service(), "value": self.value}
+
+
+@dataclass(frozen=True)
+class Issuer(_Service):
+    """A credential Drukbox fetches from ``url`` with ``headers``, and again
+    every ``refresh`` when the answer carries no ``expires_at``."""
+
+    url: str
+    headers: dict[str, str] = field(repr=False)
+    refresh: str
+
+    def entry(self) -> dict[str, Any]:
+        issuer = {"url": self.url, "headers": dict(self.headers), "refresh": self.refresh}
+        return {**self.get_service(), "issuer": issuer}
+
+
 @dataclass(frozen=True)
 class SandboxTemplate:
     """Snapshot of a reusable sandbox template as returned by the service.
@@ -152,6 +201,15 @@ class DoctorReport:
     checks: list[DoctorCheck]
 
 
+@dataclass(frozen=True)
+class ServiceAccount:
+    """A name the service knows a caller by, and the token that caller
+    presents. The service returns the token once, at creation."""
+
+    name: str
+    token: str = field(repr=False)
+
+
 @dataclass(frozen=True)
 class HTTPProxy:
     """An account-bound HTTP proxy as returned by the service.
@@ -240,6 +298,7 @@ class SandboxAPI:
         instance_type: str | None = None,
         permanent: bool = False,
         provider: str | None = None,
+        secrets: dict[str, Secret | Issuer] | None = None,
         template: uuid.UUID | str | None = None,
     ) -> SandboxHost:
         """Provision a new host.
@@ -274,6 +333,9 @@ class SandboxAPI:
         Lease: omit ``expires_at`` for the service's default lease, pass a
         ``datetime`` for an explicit expiry, or pass ``permanent=True`` for
         a host the janitor never reaps.
+
+        ``secrets`` maps a service name to a :class:`Secret` or an
+        :class:`Issuer`. The response carries no secret.
         """
 
         if expires_at and permanent:
@@ -295,6 +357,8 @@ class SandboxAPI:
             payload["instance_type"] = instance_type
         if provider is not None:
             payload["provider"] = provider
+        if secrets:
+            payload["secrets"] = {name: entry.entry() for name, entry in secrets.items()}
         if template is not None:
             payload["template"] = str(template)
 
@@ -351,6 +415,18 @@ class SandboxAPI:
     async def delete_host(self, host_id: uuid.UUID | str) -> None:
         await self._request("DELETE", f"/hosts/{host_id}")
 
+    async def refresh_secret(self, host_id: uuid.UUID | str, service: str) -> None:
+        """Make the service forget the current value of ``service`` on the
+        host and fetch a new one from its issuer.
+
+        Raises :class:`SandboxNotFoundError` for an unknown host or secret,
+        :class:`SandboxConflictError` for a secret with a static value, and
+        :class:`SandboxUnavailableError` when the exchange or the issuer did
+        not answer.
+        """
+
+        await self._request("POST", f"/hosts/{host_id}/secrets/{service}/refresh")
+
     async def create_template(
         self,
         *,
@@ -416,6 +492,27 @@ class SandboxAPI:
             checks=[DoctorCheck(**check) for check in data["checks"]],
         )
 
+    async def create_service_account(self, name: str) -> ServiceAccount:
+        """Create a service account and return its token.
+
+        Only an admin key from the service's ``SERVICE_TOKENS`` may call
+        this. A name that already exists raises
+        :class:`SandboxConflictError`; an invalid name raises
+        :class:`SandboxValidationError`.
+        """
+
+        data = await self._request("POST", "/service-accounts", json={"name": name})
+        return ServiceAccount(**data)
+
+    async def remove_service_account(self, name: str) -> None:
+        """Revoke a service account's token and remove the account.
+
+        An unknown name raises :class:`SandboxNotFoundError`; the ``admin``
+        account raises :class:`SandboxConflictError`.
+        """
+
+        await self._request("DELETE", f"/service-accounts/{name}")
+
     async def create_http_proxy(
         self,
         *,

drukbox_sdk/exceptions.py

@@ -37,8 +37,8 @@ class SandboxNotFoundError(SandboxAPIError):
 class SandboxConflictError(SandboxAPIError):
     """409 — the operation conflicts with the current state.
 
-    e.g. provisioning a Linux user on a host that already has one with
-    the same name.
+    e.g. a template that is still building, or secrets on a deployment
+    without the secrets proxy configured.
     """
 
 
@@ -53,9 +53,10 @@ class SandboxProvisioningError(SandboxAPIError):
 class SandboxValidationError(SandboxAPIError):
     """422 — the service rejected the request payload as invalid.
 
-    e.g. an env key that isn't a valid environment-variable name, or a
-    proxy target URL carrying a path or credentials. The request is
-    malformed, so retrying it unchanged won't help — fix the input.
+    e.g. an env key that isn't a valid environment-variable name, a
+    proxy target URL carrying a path or credentials, or a secret for a
+    service name Drukbox does not know. The request is malformed, so
+    retrying it unchanged won't help — fix the input.
     """
 
 

drukbox_python_sdk-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-drukbox_sdk/__init__.py,sha256=8gZrxZhT8ivzDFZmTcnN5PbwL_kwRwHluJOQHfJJeaI,918
-drukbox_sdk/api.py,sha256=kO8qOaxLZ3How5b-yJNW51A7JjnVt7jP4BDf4kgnv3A,20655
-drukbox_sdk/exceptions.py,sha256=YecxsuwpHhwzgw-_h9KbXf1WqY6R0JIJrwPY3Eg4e6I,2146
-drukbox_python_sdk-0.1.0.dist-info/METADATA,sha256=mOJsJfO_rokCOmynC-C9DbdGqpqkYD0elzzRoCX6vzc,4943
-drukbox_python_sdk-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-drukbox_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=zM66rWL3BWGJBa_mZPnM0WUomSSZ1xtWVtGQovQ71M8,1078
-drukbox_python_sdk-0.1.0.dist-info/RECORD,,