provablyfine-client 0.3.0__tar.gz

provablyfine_client-0.3.0/.gitignore

@@ -0,0 +1,15 @@
+**/__pycache__/*
+**/*.egg-info/*
+**/*.swp
+**/*.db
+**/*.json
+**/*.key
+**/*.pub
+**/*.orig
+**/*.rej
+**/*.patch
+**/*.swo
+.coverage*
+uv.lock
+site
+.idea

provablyfine_client-0.3.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026, Mathieu Lacage
+
+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.

provablyfine_client-0.3.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: provablyfine-client
+Version: 0.3.0
+Summary: HTTP client library for the ProvablyFine API
+Project-URL: Documentation, https://docs.provablyfine.net
+Project-URL: Repository, https://github.com/provablyfine/pf.git
+Project-URL: Issues, https://github.com/provablyfine/pf/issues
+Author-email: Mathieu Lacage <mathieu.lacage@cutebugs.net>
+Maintainer-email: Mathieu Lacage <mathieu.lacage@cutebugs.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: SSH,access-control,bastion
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: http-sfv
+Requires-Dist: pydantic
+Requires-Dist: requests>=2.32.5

provablyfine_client-0.3.0/README.md

@@ -0,0 +1,11 @@
+# Provably Fine, the HTTP client library
+
+This is an HTTP client library for Provably Fine, the SSH
+centralized access control package.
+
+This library will be installed as a dependency when you install
+[ProvablyFine](https://github.com/provablyfine/pf)
+
+## License
+
+This software is released under the [MIT license](./LICENSE.md).

provablyfine_client-0.3.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/provablyfine_client"]
+
+
+[project]
+name = "provablyfine-client"
+authors = [
+  {name = "Mathieu Lacage", email = "mathieu.lacage@cutebugs.net"},
+]
+maintainers = [
+  {name = "Mathieu Lacage", email = "mathieu.lacage@cutebugs.net"},
+]
+description = "HTTP client library for the ProvablyFine API"
+version = "0.3.0"
+license = "MIT"
+license-file = "LICENSE"
+keywords = ["SSH", "access-control", "bastion"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Pydantic",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3",
+  "Natural Language :: English",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+  "http-sfv",
+  "pydantic",
+  "requests>=2.32.5",
+]
+
+[project.urls]
+Documentation = "https://docs.provablyfine.net"
+Repository = "https://github.com/provablyfine/pf.git"
+Issues = "https://github.com/provablyfine/pf/issues"

provablyfine_client-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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