konklav-control-plane 1.4.0__tar.gz

konklav_control_plane-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albin Skott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

konklav_control_plane-1.4.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: konklav-control-plane
+Version: 1.4.0
+Summary: Manage Konklav from Python: tenants, subjects, credentials, roles and the rest of the control plane
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/cstruct/konklav/releases
+Project-URL: Documentation, https://github.com/cstruct/konklav/tree/main/items/py-control-plane
+Project-URL: Issues, https://github.com/cstruct/konklav/issues
+Project-URL: Repository, https://github.com/cstruct/konklav
+Description-Content-Type: text/markdown
+
+# konklav-control-plane
+
+Manage [Konklav](https://github.com/cstruct/konklav) from Python.
+
+Konklav is a standalone identity and access service. This package is
+the Python client for its control plane, the API operators and automation
+use to manage tenants, subjects, credentials, roles, shares and the rest.
+
+```python
+from konklav_control_plane import ControlPlaneClient, SecretKey
+
+auth = SecretKey(subject_url="https://konklav:8080", key_id=key_id, secret=secret)
+async with ControlPlaneClient("https://konklav:8082", auth=auth) as client:
+    written = await client.tenants.create(tenant_id, {"facts": {}})
+```
+
+Every control-plane operation has a method, with request and response
+types generated from Konklav's API document. `client.batch()` applies
+several writes in one request, all or nothing, through the same methods.
+`konklav_control_plane.sync` has the same client for synchronous code.
+Failed requests are retried where that's safe, and errors raise
+`KonklavError` subclasses such as `NotFound` and `Forbidden`.
+
+To decide authorization in a relying system, use
+[`konklav-relying`](https://pypi.org/project/konklav-relying/) instead. The
+two packages don't depend on each other.
+
+## Versions
+
+The package has the same version as the Konklav server it was released
+with, and only that server version is supported. Pre-releases, such as
+`1.3.0rc1`, are installed only with `pip install --pre`.
+
+## Links
+
+- [Konklav](https://github.com/cstruct/konklav)
+- [This package's README](https://github.com/cstruct/konklav/tree/main/items/py-control-plane)
+- [Releases and changelog](https://github.com/cstruct/konklav/releases)
+- [Issues](https://github.com/cstruct/konklav/issues)
+
+MIT licensed.

konklav_control_plane-1.4.0/PYPI.md

@@ -0,0 +1,41 @@
+# konklav-control-plane
+
+Manage [Konklav](https://github.com/cstruct/konklav) from Python.
+
+Konklav is a standalone identity and access service. This package is
+the Python client for its control plane, the API operators and automation
+use to manage tenants, subjects, credentials, roles, shares and the rest.
+
+```python
+from konklav_control_plane import ControlPlaneClient, SecretKey
+
+auth = SecretKey(subject_url="https://konklav:8080", key_id=key_id, secret=secret)
+async with ControlPlaneClient("https://konklav:8082", auth=auth) as client:
+    written = await client.tenants.create(tenant_id, {"facts": {}})
+```
+
+Every control-plane operation has a method, with request and response
+types generated from Konklav's API document. `client.batch()` applies
+several writes in one request, all or nothing, through the same methods.
+`konklav_control_plane.sync` has the same client for synchronous code.
+Failed requests are retried where that's safe, and errors raise
+`KonklavError` subclasses such as `NotFound` and `Forbidden`.
+
+To decide authorization in a relying system, use
+[`konklav-relying`](https://pypi.org/project/konklav-relying/) instead. The
+two packages don't depend on each other.
+
+## Versions
+
+The package has the same version as the Konklav server it was released
+with, and only that server version is supported. Pre-releases, such as
+`1.3.0rc1`, are installed only with `pip install --pre`.
+
+## Links
+
+- [Konklav](https://github.com/cstruct/konklav)
+- [This package's README](https://github.com/cstruct/konklav/tree/main/items/py-control-plane)
+- [Releases and changelog](https://github.com/cstruct/konklav/releases)
+- [Issues](https://github.com/cstruct/konklav/issues)
+
+MIT licensed.

konklav_control_plane-1.4.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["uv_build>=0.8.24,<0.9"]
+build-backend = "uv_build"
+
+[project]
+name = "konklav-control-plane"
+# Set by `mise run release:bump`, with the rest of the release.
+version = "1.4.0"
+description = "Manage Konklav from Python: tenants, subjects, credentials, roles and the rest of the control plane"
+readme = "PYPI.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.28"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/cstruct/konklav"
+Documentation = "https://github.com/cstruct/konklav/tree/main/items/py-control-plane"
+Changelog = "https://github.com/cstruct/konklav/releases"
+Issues = "https://github.com/cstruct/konklav/issues"
+
+[dependency-groups]
+dev = [
+    "datamodel-code-generator==0.88.0",
+    "mypy==1.20.2",
+    "pytest>=8",
+    "unasync==0.6.0",
+]
+
+[tool.mypy]
+files = ["src", "tools", "tests/typing"]
+strict = true
+python_version = "3.12"
+
+[[tool.mypy.overrides]]
+module = "unasync"
+ignore_missing_imports = true

konklav_control_plane-1.4.0/src/konklav_control_plane/__init__.py

@@ -0,0 +1,46 @@
+"""A client for Konklav's control-plane surface.
+
+`ControlPlaneClient` is asynchronous; `konklav_control_plane.sync` has the
+same client for synchronous code. Request and response types are in
+`konklav_control_plane.types`, and errors in `konklav_control_plane.errors`.
+"""
+
+# r[impl item.py-control-plane.pure-python]
+# r[impl item.py-control-plane.independent]
+from importlib.metadata import version
+
+from ._async.auth import BearerToken, SecretKey
+from ._async.batch import Batch
+# r[impl item.py-control-plane.async-default]
+from ._async.client import ControlPlaneClient
+from ._common import Mode, Pending, Written
+from .errors import (
+    Conflict,
+    Forbidden,
+    InvalidRequest,
+    KonklavError,
+    NotFound,
+    RateLimited,
+    Unauthenticated,
+    Unavailable,
+)
+
+__version__ = version("konklav-control-plane")
+
+__all__ = [
+    "Batch",
+    "BearerToken",
+    "Conflict",
+    "ControlPlaneClient",
+    "Forbidden",
+    "InvalidRequest",
+    "KonklavError",
+    "Mode",
+    "NotFound",
+    "Pending",
+    "RateLimited",
+    "SecretKey",
+    "Unauthenticated",
+    "Unavailable",
+    "Written",
+]

konklav_control_plane-1.4.0/src/konklav_control_plane/_async/auth.py

@@ -0,0 +1,95 @@
+"""How the client authenticates to the control plane."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from .. import _backend
+from .._backend import AsyncLock, AsyncToken
+from .._common import base
+
+if TYPE_CHECKING:
+    from .client import ControlPlaneClient
+
+
+@runtime_checkable
+class Auth(Protocol):
+    async def token(self, client: ControlPlaneClient) -> str:
+        """The bearer token to send."""
+        ...
+
+    def invalidate(self) -> bool:
+        """Forgets a rejected token; `True` if the next one will differ."""
+        ...
+
+
+# r[impl item.py-control-plane.auth]
+class BearerToken:
+    """A fixed token: the bootstrap token, or an operator's access token."""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    async def token(self, client: ControlPlaneClient) -> str:
+        return self._token
+
+    def invalidate(self) -> bool:
+        return False
+
+
+class SecretKey:
+    """A service principal's secret key, logged in at the subject-facing
+    surface and logged in again once 80% of the token's lifetime has
+    passed."""
+
+    def __init__(self, *, subject_url: str, key_id: str, secret: str) -> None:
+        self._login_url = f"{base(subject_url)}/v1/login/secret-key"
+        self._key_id = key_id
+        self._secret = secret
+        self._cached: tuple[str, float] | None = None
+        self._lock = AsyncLock()
+
+    async def token(self, client: ControlPlaneClient) -> str:
+        async with self._lock:
+            if self._cached is not None and self._cached[1] > _backend.now():
+                return self._cached[0]
+            response = await client._send(
+                "POST",
+                self._login_url,
+                json={"key_id": self._key_id, "secret": self._secret},
+                authenticate=False,
+            )
+            body = response.json()
+            renew_at = _backend.now() + body["expires_in"] * 0.8
+            self._cached = (body["access_token"], renew_at)
+            return self._cached[0]
+
+    def invalidate(self) -> bool:
+        self._cached = None
+        return True
+
+
+class TokenFunction:
+    """A caller's function that returns the token to send."""
+
+    def __init__(self, function: Callable[[], AsyncToken]) -> None:
+        self._function = function
+
+    async def token(self, client: ControlPlaneClient) -> str:
+        token = self._function()
+        if inspect.isawaitable(token):
+            token = await token
+        if not isinstance(token, str):
+            raise TypeError(f"the token function returned {type(token).__name__}, not str")
+        return token
+
+    def invalidate(self) -> bool:
+        return False
+
+
+def resolve(auth: Auth | Callable[[], AsyncToken]) -> Auth:
+    if isinstance(auth, Auth):
+        return auth
+    return TokenFunction(auth)

konklav_control_plane-1.4.0/src/konklav_control_plane/_async/batch.py

@@ -0,0 +1,119 @@
+"""Batches: writes collected through the client's namespaces and applied in
+one request, all or nothing."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TYPE_CHECKING, Any
+
+from .._common import Call, Pending
+from . import resources
+from .resources import Batched
+
+if TYPE_CHECKING:
+    from .client import ControlPlaneClient
+
+
+# r[impl item.py-control-plane.batch]
+class Batch:
+    """Writes to apply in one request, all or nothing; make one with
+    `client.batch()`.
+
+    Its namespaces mirror the client's, writes only. Each call is recorded
+    and returns a `Pending`, whose `result` is what the same call on the
+    client returns, once the batch has been sent: on leaving `async with`
+    without an error, or by `send()`. Later operations name what earlier ones
+    create by the ids the caller chose for them. If an operation fails,
+    nothing is applied and its error is raised, with its position as
+    `operation`. `cursor` is then the change-feed cursor of the last event
+    the batch produced, if any.
+    """
+
+    tenants: resources.Tenants[Batched]
+    memberships: resources.Memberships[Batched]
+    subjects: resources.Subjects[Batched]
+    credentials: resources.Credentials[Batched]
+    sessions: resources.Sessions[Batched]
+    signing_keys: resources.SigningKeys[Batched]
+    catalog: resources.Catalog[Batched]
+    templates: resources.Templates[Batched]
+    roles: resources.Roles[Batched]
+    assignments: resources.Assignments[Batched]
+    shares: resources.Shares[Batched]
+    registered_scopes: resources.RegisteredScopes[Batched]
+    invites: resources.Invites[Batched]
+    oidc_clients: resources.OidcClients[Batched]
+    imports: resources.Imports[Batched]
+
+    def __init__(
+        self,
+        client: ControlPlaneClient,
+        *,
+        idempotency_key: str | None = None,
+        idempotency_seconds: int | None = None,
+    ) -> None:
+        self._client = client
+        self._key = idempotency_key
+        self._seconds = idempotency_seconds
+        self._calls: list[tuple[Call, Pending[Any]]] = []
+        self._sent = False
+        self.cursor: int | None = None
+        self.tenants = resources.Tenants(client, self)
+        self.memberships = resources.Memberships(client, self)
+        self.subjects = resources.Subjects(client, self)
+        self.credentials = resources.Credentials(client, self)
+        self.sessions = resources.Sessions(client, self)
+        self.signing_keys = resources.SigningKeys(client, self)
+        self.catalog = resources.Catalog(client, self)
+        self.templates = resources.Templates(client, self)
+        self.roles = resources.Roles(client, self)
+        self.assignments = resources.Assignments(client, self)
+        self.shares = resources.Shares(client, self)
+        self.registered_scopes = resources.RegisteredScopes(client, self)
+        self.invites = resources.Invites(client, self)
+        self.oidc_clients = resources.OidcClients(client, self)
+        self.imports = resources.Imports(client, self)
+
+    def _add(self, call: Call) -> Pending[Any]:
+        if self._sent:
+            raise RuntimeError("the batch was sent already")
+        pending: Pending[Any] = Pending()
+        self._calls.append((call, pending))
+        return pending
+
+    async def send(self) -> None:
+        """Sends the recorded writes. A batch is sent once; one with nothing
+        recorded sends nothing."""
+        if self._sent:
+            raise RuntimeError("the batch was sent already")
+        self._sent = True
+        if not self._calls:
+            return
+        body: dict[str, Any] = {"operations": [call.operation() for call, _ in self._calls]}
+        if self._key is not None:
+            body["idempotency_key"] = self._key
+        if self._seconds is not None:
+            body["idempotency_seconds"] = self._seconds
+        response = await self._client._send(
+            "POST",
+            f"{self._client._url}/batch",
+            json=body,
+            # r[impl item.py-control-plane.retries]
+            retry_as="PUT" if self._key is not None else None,
+        )
+        answer = response.json()
+        self.cursor = answer.get("cursor")
+        for (call, pending), result in zip(self._calls, answer["results"], strict=True):
+            pending._resolve(call.result(result["status"], result["body"]))
+
+    async def __aenter__(self) -> Batch:
+        return self
+
+    async def __aexit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if error is None:
+            await self.send()

konklav_control_plane-1.4.0/src/konklav_control_plane/_async/client.py

@@ -0,0 +1,220 @@
+"""The control-plane client."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from .. import _backend
+from .._backend import AsyncToken
+from .._common import Call, Written, base, delay, retryable, written
+from ..errors import KonklavError, from_response
+from . import resources
+from .auth import Auth, resolve
+from .batch import Batch
+from .resources import Direct
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_RETRIES = 3
+
+
+class ControlPlaneClient:
+    """A client for Konklav's control-plane surface.
+
+    `url` is the surface's base URL, without `/v1`; a path prefix it has,
+    such as a proxy's, is kept. `auth` is a `BearerToken`, a `SecretKey`
+    or a function returning the token to send. Pass `http` to send through
+    your own `httpx` client; otherwise the client makes one with `timeout`
+    and closes it when the client is closed. `retries` is how many times a failed request
+    is sent again, where it is safe to; `0` turns retries off.
+
+    The operations are grouped as the API document tags them, such as
+    `client.tenants.create(...)` and `client.roles.put(...)`. `batch()`
+    collects writes made through the same namespaces and applies them in
+    one request, all or nothing.
+    """
+
+    tenants: resources.Tenants[Direct]
+    memberships: resources.Memberships[Direct]
+    subjects: resources.Subjects[Direct]
+    credentials: resources.Credentials[Direct]
+    sessions: resources.Sessions[Direct]
+    signing_keys: resources.SigningKeys[Direct]
+    catalog: resources.Catalog[Direct]
+    templates: resources.Templates[Direct]
+    roles: resources.Roles[Direct]
+    assignments: resources.Assignments[Direct]
+    entitlements: resources.Entitlements[Direct]
+    explain: resources.Explain[Direct]
+    shares: resources.Shares[Direct]
+    registered_scopes: resources.RegisteredScopes[Direct]
+    invites: resources.Invites[Direct]
+    oidc_clients: resources.OidcClients[Direct]
+    imports: resources.Imports[Direct]
+    batches: resources.Batches[Direct]
+
+    # r[impl item.py-control-plane.injectable-http]
+    # r[impl item.py-control-plane.explicit-config]
+    def __init__(
+        self,
+        url: str,
+        *,
+        auth: Auth | Callable[[], AsyncToken],
+        http: httpx.AsyncClient | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+    ) -> None:
+        if retries < 0:
+            raise ValueError("retries can't be negative")
+        self._url = f"{base(url)}/v1"
+        self._auth = resolve(auth)
+        self._owns_http = http is None
+        # The environment holds no configuration for this client.
+        self._http = http if http is not None else httpx.AsyncClient(timeout=timeout, trust_env=False)
+        self._retries = retries
+        self.tenants = resources.Tenants(self)
+        self.memberships = resources.Memberships(self)
+        self.subjects = resources.Subjects(self)
+        self.credentials = resources.Credentials(self)
+        self.sessions = resources.Sessions(self)
+        self.signing_keys = resources.SigningKeys(self)
+        self.catalog = resources.Catalog(self)
+        self.templates = resources.Templates(self)
+        self.roles = resources.Roles(self)
+        self.assignments = resources.Assignments(self)
+        self.entitlements = resources.Entitlements(self)
+        self.explain = resources.Explain(self)
+        self.shares = resources.Shares(self)
+        self.registered_scopes = resources.RegisteredScopes(self)
+        self.invites = resources.Invites(self)
+        self.oidc_clients = resources.OidcClients(self)
+        self.imports = resources.Imports(self)
+        self.batches = resources.Batches(self)
+
+    def batch(self, *, idempotency_key: str | None = None, idempotency_seconds: int | None = None) -> Batch:
+        """A batch: `async with client.batch() as batch:` collects the writes
+        made through `batch`'s namespaces, which mirror the client's, and
+        sends them in one request on leaving the block without an error.
+
+        With an `idempotency_key`, sending the same batch again answers what
+        it first answered without applying it again, so it is retried like a
+        `PUT`. The server remembers the key for `idempotency_seconds`, or its
+        default (ten minutes) when `None`.
+        """
+        return Batch(self, idempotency_key=idempotency_key, idempotency_seconds=idempotency_seconds)
+
+    async def __aenter__(self) -> ControlPlaneClient:
+        return self
+
+    async def __aexit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Closes the `httpx` client, unless it was passed in."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Sends a request to `path` under `/v1` and returns its decoded
+        JSON body, or `None` when it has none."""
+        response = await self._send(method, f"{self._url}{path}", json=json, params=params)
+        return response.json() if response.content else None
+
+    async def _get(self, path: str, params: Mapping[str, Any] | None = None) -> Any:
+        """A `GET`, leaving out query parameters that are `None`."""
+        query = {name: value for name, value in (params or {}).items() if value is not None}
+        return await self.request("GET", path, params=query)
+
+    async def _post(self, path: str, body: Any = None) -> Any:
+        return await self.request("POST", path, json=body)
+
+    async def _write(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+        create: bool = False,
+    ) -> Written[Any]:
+        """Sends a write and splits the cursor off its result."""
+        response = await self._send(method, f"{self._url}{path}", json=json, params=params)
+        return written(response.status_code, response.json(), create=create)
+
+    async def _call(self, call: Call) -> Any:
+        """Sends `call` and returns what its method returns."""
+        response = await self._send(call.method, f"{self._url}{call.path}", json=call.json, params=call.query())
+        return call.result(response.status_code, response.json() if response.content else None)
+
+    # r[impl item.py-control-plane.paging]
+    async def _pages(
+        self, path: str, key: str, params: Mapping[str, Any] | None = None
+    ) -> AsyncIterator[Any]:
+        """Every item of a paged list, page after page."""
+        query = {name: value for name, value in (params or {}).items() if value is not None}
+        while True:
+            page = await self._get(path, query)
+            for item in page[key]:
+                yield item
+            if page.get("next") is None:
+                return
+            query["before"] = page["next"]
+
+    async def _send(
+        self,
+        method: str,
+        url: str,
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+        authenticate: bool = True,
+        retry_as: str | None = None,
+    ) -> httpx.Response:
+        """Sends a request, logging in again once and retrying as allowed,
+        as for `retry_as` when given instead of `method`."""
+        attempt = 0
+        relogged = False
+        while True:
+            headers = {}
+            if authenticate:
+                headers["authorization"] = f"Bearer {await self._auth.token(self)}"
+            cause: Exception | None = None
+            try:
+                response = await self._http.request(
+                    method, url, json=json, params=params, headers=headers
+                )
+            except httpx.TransportError as error:
+                failure = KonklavError(f"Konklav couldn't be reached: {error}")
+                cause = error
+            else:
+                if response.is_success:
+                    return response
+                failure = from_response(response)
+                # r[impl item.py-control-plane.auth-relogin]
+                if (
+                    authenticate
+                    and failure.code == "UNAUTHENTICATED"
+                    and not relogged
+                    and self._auth.invalidate()
+                ):
+                    relogged = True
+                    continue
+            if attempt >= self._retries or not retryable(retry_as or method, failure):
+                raise failure from cause
+            await _backend.async_sleep(delay(attempt, failure))
+            attempt += 1