provablyfine-client 0.3.0__py3-none-any.whl

provablyfine_client/__init__.py

@@ -0,0 +1,28 @@
+from . import exceptions, schemas
+from .account_client import AccountClient
+from .aio import AsyncAccountClient, AsyncInvitationClient, AsyncPublicClient, AsyncSessionClient
+from .directory import Directory
+from .http_session import HttpSession
+from .http_signatures import Auth
+from .invitation_client import InvitationClient
+from .public_client import PublicClient
+from .session_client import SessionClient
+from .signer import HmacSigner, Signer
+
+__all__ = [
+    "AccountClient",
+    "AsyncAccountClient",
+    "AsyncInvitationClient",
+    "AsyncPublicClient",
+    "AsyncSessionClient",
+    "Auth",
+    "Directory",
+    "HmacSigner",
+    "HttpSession",
+    "InvitationClient",
+    "PublicClient",
+    "SessionClient",
+    "Signer",
+    "exceptions",
+    "schemas",
+]

provablyfine_client/_base64url.py

@@ -0,0 +1,9 @@
+import base64
+
+
+def decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=======")
+
+
+def encode(s: bytes) -> str:
+    return base64.urlsafe_b64encode(s).decode().rstrip("=")

provablyfine_client/account_client.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import typing
+
+from . import directory, exceptions, http_session, http_signatures, signer
+
+
+class AccountClient:
+    """API methods that require account + session authentication."""
+
+    def __init__(
+        self,
+        session: http_session.HttpSession,
+        _directory: directory.Directory,
+        account_signer: signer.Signer,
+        session_signer: signer.Signer,
+    ) -> None:
+        self._session = session
+        self._directory = _directory
+        self._account_signer = account_signer
+        self._session_signer = session_signer
+
+    def login_http_sig(self, session_public_key: dict[str, typing.Any]) -> None:
+        auth = http_signatures.Auth([self._account_signer, self._session_signer])
+        response = self._session.post(
+            self._directory.login,
+            auth=auth,
+            json={"session_public_key": session_public_key},
+        )
+        if response.status_code != 204:
+            raise exceptions.UI(f"Unable to login successfully: {response.text}")

provablyfine_client/aio.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import asyncio
+import typing
+
+from . import account_client, invitation_client, public_client, schemas, session_client, signer
+
+
+class AsyncPublicClient:
+    def __init__(self, inner: public_client.PublicClient) -> None:
+        self._inner = inner
+        self._lock = asyncio.Lock()
+
+    async def _run(self, fn: typing.Callable[[], typing.Any]) -> typing.Any:
+        async with self._lock:
+            return await asyncio.to_thread(fn)
+
+    async def get_user_trusted_keys_public(self) -> str:
+        return await self._run(self._inner.get_user_trusted_keys_public)
+
+    async def get_public_auth(self, auth_name: str) -> schemas.AuthPublic:
+        return await self._run(lambda: self._inner.get_public_auth(auth_name))
+
+    async def list_public_auths(self) -> list[schemas.AuthPublicSummary]:
+        return await self._run(self._inner.list_public_auths)
+
+    async def initialize(self, account_signer: signer.Signer, account_public_key: dict[str, typing.Any]) -> None:
+        return await self._run(lambda: self._inner.initialize(account_signer, account_public_key))
+
+
+class AsyncSessionClient:
+    def __init__(self, inner: session_client.SessionClient) -> None:
+        self._inner = inner
+        self._lock = asyncio.Lock()
+
+    async def _run(self, fn: typing.Callable[[], typing.Any]) -> typing.Any:
+        async with self._lock:
+            return await asyncio.to_thread(fn)
+
+    async def list_ssh_hosts(self) -> schemas.SshHostsResponse:
+        return await self._run(self._inner.list_ssh_hosts)
+
+    async def get_host_trusted_keys(self) -> str:
+        return await self._run(self._inner.get_host_trusted_keys)
+
+    async def get_user_certificate(
+        self,
+        hostname: str,
+        username: str,
+        action: str,
+        public_key: dict[str, typing.Any],
+        command: str | None = None,
+    ) -> schemas.SshUserCertificateResponse:
+        return await self._run(
+            lambda: self._inner.get_user_certificate(hostname, username, action, public_key, command)
+        )
+
+    async def sign_host_certificates(
+        self, public_keys: list[dict[str, typing.Any]]
+    ) -> schemas.SshHostCertificateResponse:
+        return await self._run(lambda: self._inner.sign_host_certificates(public_keys))
+
+    async def list_self_bastions(self) -> schemas.IdentitySelfBastionListResponse:
+        return await self._run(self._inner.list_self_bastions)
+
+    async def get_self_token(self, service: str) -> schemas.IdentitySelfTokenResponse:
+        return await self._run(lambda: self._inner.get_self_token(service))
+
+    async def list_tags(
+        self,
+        id: int | None = None,
+        name: str | None = None,
+        value: str | None = None,
+    ) -> schemas.TagsResponse:
+        return await self._run(lambda: self._inner.list_tags(id, name, value))
+
+    async def create_tag(self, name: str, value: str) -> schemas.Tag:
+        return await self._run(lambda: self._inner.create_tag(name, value))
+
+    async def delete_tag(self, id: int) -> None:
+        return await self._run(lambda: self._inner.delete_tag(id))
+
+    async def list_tenants(self, id: int | None = None) -> schemas.TenantsResponse:
+        return await self._run(lambda: self._inner.list_tenants(id))
+
+    async def get_tenant(self, id: int) -> schemas.Tenant:
+        return await self._run(lambda: self._inner.get_tenant(id))
+
+    async def create_tenant(self, name: str, display_name: str) -> schemas.Tenant:
+        return await self._run(lambda: self._inner.create_tenant(name, display_name))
+
+    async def update_tenant(
+        self,
+        id: int,
+        display_name: str | None = None,
+        is_enabled: bool | None = None,
+    ) -> None:
+        return await self._run(lambda: self._inner.update_tenant(id, display_name, is_enabled))
+
+    async def delete_tenant(self, id: int) -> None:
+        return await self._run(lambda: self._inner.delete_tenant(id))
+
+    async def list_auths(self) -> schemas.AuthListResponse:
+        return await self._run(self._inner.list_auths)
+
+    async def get_auth(self, id: int) -> schemas.Auth:
+        return await self._run(lambda: self._inner.get_auth(id))
+
+    async def create_auth_http_sig(self, name: str, description: str, tags: list[dict[str, str]]) -> schemas.Auth:
+        return await self._run(lambda: self._inner.create_auth_http_sig(name, description, tags))
+
+    async def create_auth_oidc(
+        self,
+        name: str,
+        description: str,
+        tags: list[dict[str, str]],
+        issuer: str,
+        client_id: str,
+        client_secret: str | None,
+    ) -> schemas.Auth:
+        return await self._run(
+            lambda: self._inner.create_auth_oidc(name, description, tags, issuer, client_id, client_secret)
+        )
+
+    async def create_auth_oauth2_github(
+        self,
+        name: str,
+        description: str,
+        tags: list[dict[str, str]],
+        client_id: str,
+        client_secret: str,
+    ) -> schemas.Auth:
+        return await self._run(
+            lambda: self._inner.create_auth_oauth2_github(name, description, tags, client_id, client_secret)
+        )
+
+    async def update_auth(
+        self,
+        id: int,
+        name: str | None = None,
+        description: str | None = None,
+        is_enabled: bool | None = None,
+        tags: list[schemas.TagNameValue] | None = None,
+    ) -> None:
+        return await self._run(lambda: self._inner.update_auth(id, name, description, is_enabled, tags))
+
+    async def delete_auth(self, id: int) -> None:
+        return await self._run(lambda: self._inner.delete_auth(id))
+
+    async def list_bastions(self, id: int | None = None) -> schemas.BastionListResponse:
+        return await self._run(lambda: self._inner.list_bastions(id))
+
+    async def get_bastion(self, id: int) -> schemas.Bastion:
+        return await self._run(lambda: self._inner.get_bastion(id))
+
+    async def create_bastion(
+        self,
+        url: str,
+        ssh_proxy_jump: str | None,
+        tag_id_list: list[int],
+        tag_name_value_list: list[dict[str, str]],
+    ) -> schemas.Bastion:
+        return await self._run(
+            lambda: self._inner.create_bastion(url, ssh_proxy_jump, tag_id_list, tag_name_value_list)
+        )
+
+    async def update_bastion(
+        self,
+        id: int,
+        url: str | None = None,
+        ssh_proxy_jump: str | None = None,
+        tag_id_list: list[int] | None = None,
+        tag_name_value_list: list[schemas.TagNameValue] | None = None,
+    ) -> None:
+        return await self._run(
+            lambda: self._inner.update_bastion(id, url, ssh_proxy_jump, tag_id_list, tag_name_value_list)
+        )
+
+    async def delete_bastion(self, id: int) -> None:
+        return await self._run(lambda: self._inner.delete_bastion(id))
+
+    async def list_roles(self, id: int | None = None, name: str | None = None) -> schemas.RolesResponse:
+        return await self._run(lambda: self._inner.list_roles(id, name))
+
+    async def get_role(self, id: int) -> schemas.Role:
+        return await self._run(lambda: self._inner.get_role(id))
+
+    async def create_role(self, name: str, description: str) -> schemas.Role:
+        return await self._run(lambda: self._inner.create_role(name, description))
+
+    async def update_role(
+        self,
+        id: int,
+        name: str | None = None,
+        description: str | None = None,
+        grant_list: list[schemas.Grant] | None = None,
+        member_list: list[schemas.RoleMemberRef] | None = None,
+    ) -> None:
+        return await self._run(lambda: self._inner.update_role(id, name, description, grant_list, member_list))
+
+    async def delete_role(self, id: int) -> None:
+        return await self._run(lambda: self._inner.delete_role(id))
+
+    async def list_boundaries(self, id: int | None = None, name: str | None = None) -> schemas.BoundariesResponse:
+        return await self._run(lambda: self._inner.list_boundaries(id, name))
+
+    async def get_boundary(self, id: int) -> schemas.Boundary:
+        return await self._run(lambda: self._inner.get_boundary(id))
+
+    async def create_boundary(self, name: str, description: str) -> schemas.Boundary:
+        return await self._run(lambda: self._inner.create_boundary(name, description))
+
+    async def update_boundary(
+        self,
+        id: int,
+        name: str | None = None,
+        description: str | None = None,
+        ceiling_list: list[schemas.Grant] | None = None,
+        denied_list: list[schemas.Grant] | None = None,
+    ) -> None:
+        return await self._run(lambda: self._inner.update_boundary(id, name, description, ceiling_list, denied_list))
+
+    async def delete_boundary(self, id: int) -> None:
+        return await self._run(lambda: self._inner.delete_boundary(id))
+
+    async def list_identities(
+        self,
+        id: int | None = None,
+        name: str | None = None,
+        tag_id: list[str] | None = None,
+        tag_name: list[str] | None = None,
+        boundary_id: list[str] | None = None,
+        boundary_name: list[str] | None = None,
+    ) -> schemas.IdentitiesResponse:
+        return await self._run(
+            lambda: self._inner.list_identities(id, name, tag_id, tag_name, boundary_id, boundary_name)
+        )
+
+    async def get_identity(self, id: int) -> schemas.Identity:
+        return await self._run(lambda: self._inner.get_identity(id))
+
+    async def create_identity(
+        self,
+        name: str | None,
+        boundary_id_list: list[int],
+        boundary_name_list: list[str],
+        tag_id_list: list[int],
+        tag_name_value_list: list[dict[str, str]],
+    ) -> schemas.Identity:
+        return await self._run(
+            lambda: self._inner.create_identity(
+                name, boundary_id_list, boundary_name_list, tag_id_list, tag_name_value_list
+            )
+        )
+
+    async def invite_identity(self, id: int, delivery: str) -> str | None:
+        return await self._run(lambda: self._inner.invite_identity(id, delivery))
+
+    async def delete_identity(self, id: int) -> None:
+        return await self._run(lambda: self._inner.delete_identity(id))
+
+    async def update_identity(
+        self,
+        id: int,
+        name: str | None = None,
+        tags: list[schemas.IdentityTagOp] | None = None,
+    ) -> None:
+        return await self._run(lambda: self._inner.update_identity(id, name, tags))
+
+    async def login_oidc(
+        self,
+        auth_name: str,
+        id_token: str,
+        session_public_key: dict[str, typing.Any],
+    ) -> None:
+        return await self._run(lambda: self._inner.login_oidc(auth_name, id_token, session_public_key))
+
+    async def login_oauth2_start(
+        self,
+        auth_name: str,
+        session_public_key: dict[str, typing.Any],
+        client_redirect_uri: str,
+    ) -> str:
+        return await self._run(
+            lambda: self._inner.login_oauth2_start(auth_name, session_public_key, client_redirect_uri)
+        )
+
+    async def list_audit_log(
+        self,
+        level: int | None = None,
+        object_type: str | None = None,
+        by_identity_id: str | None = None,
+        start_time: int | None = None,
+        end_time: int | None = None,
+    ) -> schemas.AuditLogListResponse:
+        return await self._run(
+            lambda: self._inner.list_audit_log(level, object_type, by_identity_id, start_time, end_time)
+        )
+
+
+class AsyncAccountClient:
+    def __init__(self, inner: account_client.AccountClient) -> None:
+        self._inner = inner
+        self._lock = asyncio.Lock()
+
+    async def _run(self, fn: typing.Callable[[], typing.Any]) -> typing.Any:
+        async with self._lock:
+            return await asyncio.to_thread(fn)
+
+    async def login_http_sig(self, session_public_key: dict[str, typing.Any]) -> None:
+        return await self._run(lambda: self._inner.login_http_sig(session_public_key))
+
+
+class AsyncInvitationClient:
+    def __init__(self, inner: invitation_client.InvitationClient) -> None:
+        self._inner = inner
+        self._lock = asyncio.Lock()
+
+    async def _run(self, fn: typing.Callable[[], typing.Any]) -> typing.Any:
+        async with self._lock:
+            return await asyncio.to_thread(fn)
+
+    async def connect(self, account_public_key: dict[str, typing.Any]) -> None:
+        return await self._run(lambda: self._inner.connect(account_public_key))

provablyfine_client/directory.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import requests
+
+from . import exceptions
+
+
+class Directory:
+    """Fetches and caches the server's endpoint URL map from a well-known URL."""
+
+    def __init__(self, url: str, timeout: float = 5.0) -> None:
+        self._url = url
+        self._timeout = timeout
+        self._data: dict[str, str] | None = None
+
+    def _load(self) -> dict[str, str]:
+        if self._data is None:
+            try:
+                response = requests.get(self._url, timeout=self._timeout)
+            except requests.exceptions.ConnectionError:
+                raise exceptions.UI("Unable to connect to server")
+            except requests.exceptions.ReadTimeout:
+                raise exceptions.UI("Request timed out")
+            if response.status_code != 200:
+                raise exceptions.UI("Unable to read directory from server")
+            self._data = response.json()
+        assert self._data is not None
+        return self._data
+
+    @property
+    def accept_invitation(self) -> str:
+        return self._load()["accept_invitation"]
+
+    @property
+    def audit_log(self) -> str:
+        return self._load()["audit_log"]
+
+    @property
+    def auth(self) -> str:
+        return self._load()["auth"]
+
+    @property
+    def bastion(self) -> str:
+        return self._load()["bastion"]
+
+    @property
+    def boundary(self) -> str:
+        return self._load()["boundary"]
+
+    @property
+    def identity(self) -> str:
+        return self._load()["identity"]
+
+    @property
+    def initialize(self) -> str:
+        return self._load()["initialize"]
+
+    @property
+    def login(self) -> str:
+        return self._load()["login"]
+
+    @property
+    def login_oauth2_start(self) -> str:
+        return self._load()["login_oauth2_start"]
+
+    @property
+    def login_oidc(self) -> str:
+        return self._load()["login_oidc"]
+
+    @property
+    def public_auth(self) -> str:
+        return self._load()["public_auth"]
+
+    @property
+    def role(self) -> str:
+        return self._load()["role"]
+
+    @property
+    def ssh(self) -> str:
+        return self._load()["ssh"]
+
+    @property
+    def tag(self) -> str:
+        return self._load()["tag"]
+
+    @property
+    def tenant(self) -> str:
+        return self._load()["tenant"]

provablyfine_client/exceptions.py

@@ -0,0 +1,11 @@
+class UI(Exception):
+    pass
+
+
+class Forbidden(UI):
+    pass
+
+
+class KeyExpired(Exception):
+    def __init__(self, key_type: str):
+        self.key_type = key_type

provablyfine_client/http_session.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import logging
+import typing
+
+import requests
+
+from . import exceptions, http_signatures
+
+logger = logging.getLogger(__name__)
+
+
+class HttpSession:
+    """Thin wrapper around requests.Session: logging, 400/422 error handling, per-request auth."""
+
+    def __init__(self, session: requests.Session, timeout: float = 5.0) -> None:
+        self._session = session
+        self._timeout = timeout
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        auth: http_signatures.Auth | None = None,
+        json: typing.Any = None,
+        data: typing.Any = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, typing.Any] | None = None,
+        timeout: float | None = None,
+    ) -> requests.Response:
+        req = requests.Request(method=method, url=url, json=json, data=data, headers=headers, params=params)
+        prepared = req.prepare()
+        if auth is not None:
+            prepared = auth(prepared)
+
+        effective_timeout = timeout if timeout is not None else self._timeout
+        logger.info(f"tx {prepared.method} {prepared.url}")
+        logger.debug(f"tx headers: {prepared.headers}")
+        logger.debug(f"tx body: {prepared.body}")
+        try:
+            response = self._session.send(prepared, timeout=effective_timeout)
+        except requests.exceptions.ConnectionError:
+            raise exceptions.UI("Unable to connect to server")
+        except requests.exceptions.ReadTimeout:
+            raise exceptions.UI("Request timed out")
+        logger.info(f"rx {response.status_code}")
+        logger.debug(f"rx headers: {response.headers}")
+        logger.debug(f"rx body: {response.content}")
+
+        if response.status_code in (400, 422):
+            try:
+                problem = response.json()
+                title = problem.get("title", "")
+                detail = problem.get("detail")
+                msg = f"{title} {detail}" if detail else title
+            except Exception:
+                msg = response.text
+            raise exceptions.UI(msg or response.text)
+
+        return response
+
+    def get(
+        self,
+        url: str,
+        *,
+        auth: http_signatures.Auth | None = None,
+        params: dict[str, typing.Any] | None = None,
+    ) -> requests.Response:
+        return self.request("GET", url, auth=auth, params=params)
+
+    def post(
+        self,
+        url: str,
+        *,
+        auth: http_signatures.Auth | None = None,
+        json: typing.Any = None,
+    ) -> requests.Response:
+        return self.request("POST", url, auth=auth, json=json)
+
+    def patch(
+        self,
+        url: str,
+        *,
+        auth: http_signatures.Auth | None = None,
+        json: typing.Any = None,
+    ) -> requests.Response:
+        return self.request("PATCH", url, auth=auth, json=json)
+
+    def delete(
+        self,
+        url: str,
+        *,
+        auth: http_signatures.Auth | None = None,
+    ) -> requests.Response:
+        return self.request("DELETE", url, auth=auth)
+
+    def put(
+        self,
+        url: str,
+        *,
+        auth: http_signatures.Auth | None = None,
+        json: typing.Any = None,
+    ) -> requests.Response:
+        return self.request("PUT", url, auth=auth, json=json)

provablyfine_client/http_signatures.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import hashlib
+import secrets
+import time
+import typing
+import urllib.parse
+
+import http_sfv
+import requests
+
+from . import signer
+
+# http_sfv type stubs are incomplete (private imports, reportPrivateImportUsage)
+# pyright: reportPrivateImportUsage=false
+
+
+def _build_signature_base(
+    request: requests.PreparedRequest,
+    covered: tuple[str, ...],
+    sig_params: str,
+) -> str:
+    parts: list[str] = []
+    for c in covered:
+        match c:
+            case "@method":
+                parts.append(f'"@method": {request.method}')
+            case "@authority":
+                parts.append(f'"@authority": {urllib.parse.urlparse(request.url).netloc}')
+            case "@target-uri":
+                parts.append(f'"@target-uri": {request.url}')
+            case "@signature-params":
+                parts.append(f'"@signature-params": {sig_params}')
+            case _:
+                parts.append(f'"{c}": {request.headers[c]}')
+    return "\n".join(parts)
+
+
+class Auth:
+    """HTTP Message Signatures (RFC 9421) — signs a request with one or more Signer instances."""
+
+    def __init__(self, signers: typing.Sequence[signer.Signer]) -> None:
+        self._signers = signers
+
+    def _sign(
+        self, signer: signer.Signer, request: requests.PreparedRequest, covered: tuple[str, ...]
+    ) -> tuple[str, str]:
+        key_id = f"{signer.prefix()}:{signer.thumbprint()}"
+
+        inner = http_sfv.InnerList([http_sfv.Item(c) for c in covered])
+        inner.params["created"] = int(time.time())
+        inner.params["keyid"] = key_id
+        inner.params["nonce"] = secrets.token_hex(16)
+
+        sig_params = str(inner)
+        sig_base = _build_signature_base(request, covered, sig_params)
+        sig_bytes = signer.sign(sig_base.encode())
+
+        return (
+            f"{signer.prefix()}={sig_params}",
+            f"{signer.prefix()}={http_sfv.Item(sig_bytes)}",
+        )
+
+    def __call__(self, request: requests.PreparedRequest) -> requests.PreparedRequest:
+        if "Content-Digest" not in request.headers:
+            body = request.body or b""
+            if isinstance(body, str):
+                body_bytes = body.encode()
+            else:
+                body_bytes = body if isinstance(body, bytes) else b""
+            digest = hashlib.sha256(body_bytes).digest()
+            request.headers["Content-Digest"] = str(http_sfv.Dictionary({"sha-256": digest}))
+        covered = ("@method", "@authority", "@target-uri", "content-digest", "@signature-params")
+        signatures_input: list[str] = []
+        signatures: list[str] = []
+        for _signer in self._signers:
+            signature_input, signature = self._sign(_signer, request, covered)
+            signatures_input.append(signature_input)
+            signatures.append(signature)
+        request.headers["Signature-Input"] = ", ".join(signatures_input)
+        request.headers["Signature"] = ", ".join(signatures)
+        return request