lars-kluijtmans-admin-sdk 0.0.3__tar.gz

lars_kluijtmans_admin_sdk-0.0.3/.flake8

@@ -0,0 +1,8 @@
+[flake8]
+max-line-length = 120
+# Match the rest of the repo: pyflakes (F*) on; ignore cosmetic pycodestyle checks an
+# autoformatter would own (this project doesn't run one).
+extend-ignore = E501,E203,W503,E302,E303,E305,W391,E127,E128,E131
+exclude = .venv,__pycache__,.pytest_cache,.git,dist,build
+per-file-ignores =
+    tests/*: E402, F811

lars_kluijtmans_admin_sdk-0.0.3/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/

lars_kluijtmans_admin_sdk-0.0.3/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: lars-kluijtmans-admin-sdk
+Version: 0.0.3
+Summary: Python admin SDK for the Auth Platform Management API
+Project-URL: Homepage, https://github.com/LarsKluijtmans/auth
+Project-URL: Source, https://github.com/LarsKluijtmans/auth/tree/main/admin-sdk-python
+Author: Auth Platform
+License: MIT
+Keywords: admin,auth,oauth,rbac,sdk
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == 'dev'
+Requires-Dist: flake8>=7; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lars-kluijtmans-admin-sdk
+
+A Python admin SDK for the **Auth Platform** Management API — modelled on the Firebase
+Authentication Admin SDK. From a server-side program: read projects, clients and providers,
+and read/update users (active state, custom claims, password-reset/verification emails).
+
+```bash
+pip install lars-kluijtmans-admin-sdk
+```
+
+The import package stays `auth_platform_admin` (`from auth_platform_admin import AdminClient`).
+Requires Python 3.10+.
+
+## Authenticating
+
+Two credential modes.
+
+### M2M (recommended for servers)
+
+A **service client** with the `client_credentials` grant. The SDK runs the grant against the
+Login API, then caches and refreshes the token for you:
+
+```python
+from auth_platform_admin import AdminClient
+
+client = AdminClient.from_client_credentials(
+    login_api_url="https://login.example.com",
+    management_url="https://manage.example.com",
+    client_id="client_xxx",
+    client_secret="…",
+)
+```
+
+### Bring-your-own token
+
+Attach an admin access token you already hold (e.g. from a logged-in session):
+
+```python
+client = AdminClient(management_url="https://manage.example.com", token=ACCESS_TOKEN)
+```
+
+What a credential may do is governed by RBAC: a **user** token uses that user's role; a **service
+client** uses the role assigned to it (see *Setting up a service client* below).
+
+`AdminClient` is a context manager and closes its HTTP connection on exit:
+
+```python
+with AdminClient.from_client_credentials(...) as client:
+    ...
+```
+
+## Using it
+
+```python
+# Projects
+project  = client.projects.get(project_id)
+projects = client.projects.list(company_id)
+
+# Clients & providers
+clients   = client.clients.list(project_id)
+provider  = client.providers.catalog()            # platform catalog
+enabled   = client.providers.list(project_id)      # per-project, with enable state
+
+# Users — read
+users = client.users.list(project_id, search="ann", status="active")  # one page
+for user in client.users.iter(project_id):                            # all pages
+    print(user.email, user.is_active)
+user = client.users.get(project_id, user_id)
+
+# Users — update (active state, claims, and profile fields)
+client.users.set_active(project_id, user_id, False)
+client.users.set_claims(project_id, user_id, {"tier": "gold"})
+client.users.set_profile(project_id, user_id, {"display_name": "Ann", "language": "nl"})
+# Firebase-style: apply whichever fields you pass (profile fields accept None to clear).
+client.users.update(project_id, user_id, active=True, claims={"tier": "silver"},
+                    display_name="Ann", language="nl", profile_picture="https://cdn/x.png")
+
+# Users — remediation
+client.users.send_password_reset(project_id, user_id)
+client.users.resend_verification(project_id, user_id)
+client.users.force_logout(project_id, user_id)
+```
+
+Every model exposes `.raw` (the full API payload) so new/unknown fields are always reachable.
+
+> The admin can edit **display name, language, and profile picture** (`set_profile` / `update`),
+> flip active state, set claims, and trigger the reset/verification emails. **Email and password
+> changes remain self-service** on the Login API — they are not part of the admin surface.
+
+## Setting up a service client
+
+1. **Create a client** for the project (Management console → project → Clients, or the API) and
+   enable the **`client_credentials`** grant on it. Keep the `client_id` + secret.
+2. **Assign it a role** — the permissions an m2m token from this client gets:
+   ```http
+   PUT /api/v1/projects/{project_id}/clients/{client_id}/service-role
+   { "role_id": "<a management role id>" }
+   ```
+   (Needs `role:manage`.) A client with no service role can mint a token but is denied everything.
+3. Use `AdminClient.from_client_credentials(...)` with that client's id + secret.
+
+The service account is always scoped to its own company/project and is never a platform admin.
+
+## Errors
+
+Failures raise typed exceptions — `AuthError` (401), `Forbidden` (403), `NotFound` (404),
+`Conflict` (409), `ValidationError` (422), `NetworkError` — all subclasses of `AdminError`
+(carrying `.status` and `.detail`):
+
+```python
+from auth_platform_admin import NotFound, Forbidden
+
+try:
+    client.users.get(project_id, user_id)
+except NotFound:
+    ...
+except Forbidden as exc:
+    print(exc.status, exc.detail)
+```
+
+See [`examples/`](examples/) for runnable scripts (M2M and bring-your-own-token).

lars_kluijtmans_admin_sdk-0.0.3/README.md

@@ -0,0 +1,121 @@
+# lars-kluijtmans-admin-sdk
+
+A Python admin SDK for the **Auth Platform** Management API — modelled on the Firebase
+Authentication Admin SDK. From a server-side program: read projects, clients and providers,
+and read/update users (active state, custom claims, password-reset/verification emails).
+
+```bash
+pip install lars-kluijtmans-admin-sdk
+```
+
+The import package stays `auth_platform_admin` (`from auth_platform_admin import AdminClient`).
+Requires Python 3.10+.
+
+## Authenticating
+
+Two credential modes.
+
+### M2M (recommended for servers)
+
+A **service client** with the `client_credentials` grant. The SDK runs the grant against the
+Login API, then caches and refreshes the token for you:
+
+```python
+from auth_platform_admin import AdminClient
+
+client = AdminClient.from_client_credentials(
+    login_api_url="https://login.example.com",
+    management_url="https://manage.example.com",
+    client_id="client_xxx",
+    client_secret="…",
+)
+```
+
+### Bring-your-own token
+
+Attach an admin access token you already hold (e.g. from a logged-in session):
+
+```python
+client = AdminClient(management_url="https://manage.example.com", token=ACCESS_TOKEN)
+```
+
+What a credential may do is governed by RBAC: a **user** token uses that user's role; a **service
+client** uses the role assigned to it (see *Setting up a service client* below).
+
+`AdminClient` is a context manager and closes its HTTP connection on exit:
+
+```python
+with AdminClient.from_client_credentials(...) as client:
+    ...
+```
+
+## Using it
+
+```python
+# Projects
+project  = client.projects.get(project_id)
+projects = client.projects.list(company_id)
+
+# Clients & providers
+clients   = client.clients.list(project_id)
+provider  = client.providers.catalog()            # platform catalog
+enabled   = client.providers.list(project_id)      # per-project, with enable state
+
+# Users — read
+users = client.users.list(project_id, search="ann", status="active")  # one page
+for user in client.users.iter(project_id):                            # all pages
+    print(user.email, user.is_active)
+user = client.users.get(project_id, user_id)
+
+# Users — update (active state, claims, and profile fields)
+client.users.set_active(project_id, user_id, False)
+client.users.set_claims(project_id, user_id, {"tier": "gold"})
+client.users.set_profile(project_id, user_id, {"display_name": "Ann", "language": "nl"})
+# Firebase-style: apply whichever fields you pass (profile fields accept None to clear).
+client.users.update(project_id, user_id, active=True, claims={"tier": "silver"},
+                    display_name="Ann", language="nl", profile_picture="https://cdn/x.png")
+
+# Users — remediation
+client.users.send_password_reset(project_id, user_id)
+client.users.resend_verification(project_id, user_id)
+client.users.force_logout(project_id, user_id)
+```
+
+Every model exposes `.raw` (the full API payload) so new/unknown fields are always reachable.
+
+> The admin can edit **display name, language, and profile picture** (`set_profile` / `update`),
+> flip active state, set claims, and trigger the reset/verification emails. **Email and password
+> changes remain self-service** on the Login API — they are not part of the admin surface.
+
+## Setting up a service client
+
+1. **Create a client** for the project (Management console → project → Clients, or the API) and
+   enable the **`client_credentials`** grant on it. Keep the `client_id` + secret.
+2. **Assign it a role** — the permissions an m2m token from this client gets:
+   ```http
+   PUT /api/v1/projects/{project_id}/clients/{client_id}/service-role
+   { "role_id": "<a management role id>" }
+   ```
+   (Needs `role:manage`.) A client with no service role can mint a token but is denied everything.
+3. Use `AdminClient.from_client_credentials(...)` with that client's id + secret.
+
+The service account is always scoped to its own company/project and is never a platform admin.
+
+## Errors
+
+Failures raise typed exceptions — `AuthError` (401), `Forbidden` (403), `NotFound` (404),
+`Conflict` (409), `ValidationError` (422), `NetworkError` — all subclasses of `AdminError`
+(carrying `.status` and `.detail`):
+
+```python
+from auth_platform_admin import NotFound, Forbidden
+
+try:
+    client.users.get(project_id, user_id)
+except NotFound:
+    ...
+except Forbidden as exc:
+    print(exc.status, exc.detail)
+```
+
+See [`examples/`](examples/) for runnable scripts (M2M and bring-your-own-token).

lars_kluijtmans_admin_sdk-0.0.3/examples/byo_token_example.py

@@ -0,0 +1,28 @@
+"""Bring-your-own-token example: pass an admin access token you already hold.
+
+    export AUTH_MANAGE_URL=http://127.0.0.1:8000
+    export AUTH_TOKEN=<an admin access token>
+    export AUTH_PROJECT_ID=...
+    export AUTH_USER_ID=...
+    python examples/byo_token_example.py
+"""
+import os
+
+from auth_platform_admin import AdminClient
+
+
+def main() -> None:
+    with AdminClient(management_url=os.environ["AUTH_MANAGE_URL"], token=os.environ["AUTH_TOKEN"]) as client:
+        project_id = os.environ["AUTH_PROJECT_ID"]
+        user_id = os.environ["AUTH_USER_ID"]
+
+        user = client.users.get(project_id, user_id)
+        print(f"{user.email} active={user.is_active} claims={client.users.get_claims(project_id, user_id)}")
+
+        # Tag the user with a custom claim, then read it back.
+        client.users.set_claims(project_id, user_id, {"reviewed": True})
+        print("claims now:", client.users.get_claims(project_id, user_id))
+
+
+if __name__ == "__main__":
+    main()

lars_kluijtmans_admin_sdk-0.0.3/examples/m2m_example.py

@@ -0,0 +1,34 @@
+"""M2M example: authenticate with client_credentials and walk projects -> users.
+
+Run against a local stack (after setting up a service client + role, see the README):
+
+    export AUTH_LOGIN_URL=http://127.0.0.1:8010
+    export AUTH_MANAGE_URL=http://127.0.0.1:8000
+    export AUTH_CLIENT_ID=client_xxx
+    export AUTH_CLIENT_SECRET=...
+    export AUTH_COMPANY_ID=...
+    python examples/m2m_example.py
+"""
+import os
+
+from auth_platform_admin import AdminClient
+
+
+def main() -> None:
+    with AdminClient.from_client_credentials(
+        login_api_url=os.environ["AUTH_LOGIN_URL"],
+        management_url=os.environ["AUTH_MANAGE_URL"],
+        client_id=os.environ["AUTH_CLIENT_ID"],
+        client_secret=os.environ["AUTH_CLIENT_SECRET"],
+    ) as client:
+        for project in client.projects.list(os.environ["AUTH_COMPANY_ID"]):
+            print(f"project {project.name} ({project.id})")
+            print(f"  clients:   {[c.client_id for c in client.clients.list(project.id)]}")
+            enabled = [p.provider_id for p in client.providers.list(project.id) if p.enabled]
+            print(f"  providers: {enabled}")
+            for user in client.users.list(project.id, page_size=5):
+                print(f"  user {user.email} active={user.is_active}")
+
+
+if __name__ == "__main__":
+    main()

lars_kluijtmans_admin_sdk-0.0.3/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lars-kluijtmans-admin-sdk"
+version = "0.0.3"
+description = "Python admin SDK for the Auth Platform Management API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Auth Platform" }]
+keywords = ["auth", "admin", "sdk", "oauth", "rbac"]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "respx>=0.21", "flake8>=7", "build>=1", "twine>=5"]
+
+[project.urls]
+Homepage = "https://github.com/LarsKluijtmans/auth"
+Source = "https://github.com/LarsKluijtmans/auth/tree/main/admin-sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/auth_platform_admin"]

lars_kluijtmans_admin_sdk-0.0.3/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*

lars_kluijtmans_admin_sdk-0.0.3/set_version.py

@@ -0,0 +1,47 @@
+"""Set the package version across pyproject.toml and the package __init__.
+
+Used by the "Deploy to PyPI" workflow so a release can be cut from the Actions tab
+without a manual bump commit:
+
+    python set_version.py --version=0.2.0
+
+Rewrites `version = "..."` in pyproject.toml and `__version__ = "..."` in
+src/auth_platform_admin/__init__.py, then prints the new version.
+"""
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+PYPROJECT = ROOT / "pyproject.toml"
+INIT = ROOT / "src" / "auth_platform_admin" / "__init__.py"
+
+# A normal PEP 440 release like 1.2.3, optionally with a pre/post/dev suffix.
+_VERSION_RE = re.compile(r"^\d+\.\d+\.\d+(?:[._-]?(?:a|b|rc|alpha|beta|post|dev)\d*)?$")
+
+
+def _replace(path: Path, pattern: str, replacement: str) -> None:
+    text = path.read_text(encoding="utf-8")
+    new_text, count = re.subn(pattern, replacement, text, count=1, flags=re.MULTILINE)
+    if count != 1:
+        raise SystemExit(f"error: could not find a version line to update in {path}")
+    path.write_text(new_text, encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Set the SDK version.")
+    parser.add_argument("--version", required=True, help="New version, e.g. 0.2.0")
+    args = parser.parse_args()
+
+    version = args.version.strip().lstrip("v")
+    if not _VERSION_RE.match(version):
+        raise SystemExit(f"error: '{args.version}' is not a valid version number")
+
+    _replace(PYPROJECT, r'^version = "[^"]*"', f'version = "{version}"')
+    _replace(INIT, r'^__version__ = "[^"]*"', f'__version__ = "{version}"')
+    print(f"version set to {version}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lars_kluijtmans_admin_sdk-0.0.3/src/auth_platform_admin/__init__.py

@@ -0,0 +1,31 @@
+"""auth-platform-admin — a Python admin SDK for the Auth Platform Management API."""
+from .client import AdminClient
+from .errors import (
+    AdminError,
+    AuthError,
+    Conflict,
+    Forbidden,
+    NetworkError,
+    NotFound,
+    ValidationError,
+)
+from .models import Client, Project, ProjectProvider, Provider, User
+
+__version__ = "0.0.3"
+
+__all__ = [
+    "AdminClient",
+    "AdminError",
+    "AuthError",
+    "Conflict",
+    "Forbidden",
+    "NetworkError",
+    "NotFound",
+    "ValidationError",
+    "Client",
+    "Project",
+    "Provider",
+    "ProjectProvider",
+    "User",
+    "__version__",
+]

lars_kluijtmans_admin_sdk-0.0.3/src/auth_platform_admin/client.py

@@ -0,0 +1,170 @@
+"""The Auth Platform admin client.
+
+``AdminClient`` is a thin, typed, synchronous wrapper over the Management API. It supports
+two credential modes:
+
+* **M2M** — ``AdminClient.from_client_credentials(...)`` runs the OAuth ``client_credentials``
+  grant against the Login API (the client must have that grant enabled), caches the resulting
+  ``m2m`` access token, and refreshes it on expiry or a 401.
+* **Bring-your-own token** — ``AdminClient(management_url, token=...)`` just attaches a bearer
+  token you already hold (e.g. an admin's session token); its RBAC role governs what you can do.
+
+Resource groups (``client.projects`` etc.) are attached by the resource modules.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Iterator
+
+import httpx
+
+from .errors import NetworkError, raise_for_response
+
+_TOKEN_PATH = "/login/v1/token"
+
+
+class _Token:
+    __slots__ = ("value", "expires_at")
+
+    def __init__(self, value: str, expires_at: float) -> None:
+        self.value = value
+        self.expires_at = expires_at
+
+    def is_expiring(self, skew_seconds: float = 30.0) -> bool:
+        return time.time() >= self.expires_at - skew_seconds
+
+
+class _ClientCredentials:
+    """Mints m2m access tokens via the Login API's client_credentials grant."""
+
+    def __init__(self, login_api_url: str, client_id: str, client_secret: str) -> None:
+        self._url = login_api_url.rstrip("/")
+        self._client_id = client_id
+        self._client_secret = client_secret
+
+    def fetch(self, http: httpx.Client) -> _Token:
+        try:
+            response = http.post(
+                f"{self._url}{_TOKEN_PATH}",
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": self._client_id,
+                    "client_secret": self._client_secret,
+                },
+            )
+        except httpx.HTTPError as exc:  # pragma: no cover - exercised via NetworkError tests
+            raise NetworkError(f"Token request failed: {exc}") from exc
+        raise_for_response(response)
+        body = response.json()
+        return _Token(body["access_token"], time.time() + float(body.get("expires_in", 3600)))
+
+
+class AdminClient:
+    def __init__(
+        self,
+        management_url: str,
+        *,
+        token: str | None = None,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+        _credentials: _ClientCredentials | None = None,
+    ) -> None:
+        if token is None and _credentials is None:
+            raise ValueError("Provide a `token=` or use AdminClient.from_client_credentials(...)")
+        self._base = management_url.rstrip("/")
+        self._static_token = token
+        self._credentials = _credentials
+        self._cached: _Token | None = None
+        self._lock = threading.Lock()
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+        self._attach_resources()
+
+    @classmethod
+    def from_client_credentials(
+        cls,
+        *,
+        login_api_url: str,
+        management_url: str,
+        client_id: str,
+        client_secret: str,
+        timeout: float = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> "AdminClient":
+        credentials = _ClientCredentials(login_api_url, client_id, client_secret)
+        return cls(management_url, timeout=timeout, http_client=http_client, _credentials=credentials)
+
+    def _attach_resources(self) -> None:
+        from .resources import Clients, Projects, Providers, Users
+
+        self.projects = Projects(self)
+        self.clients = Clients(self)
+        self.providers = Providers(self)
+        self.users = Users(self)
+
+    # --- auth ---------------------------------------------------------------
+
+    def _access_token(self) -> str:
+        if self._static_token is not None:
+            return self._static_token
+        assert self._credentials is not None
+        with self._lock:
+            if self._cached is None or self._cached.is_expiring():
+                self._cached = self._credentials.fetch(self._http)
+            return self._cached.value
+
+    def _invalidate_token(self) -> None:
+        with self._lock:
+            self._cached = None
+
+    # --- transport ----------------------------------------------------------
+
+    def request(
+        self, method: str, path: str, *, params: dict | None = None, json: Any = None, _retried: bool = False
+    ) -> Any:
+        """Issue an authenticated request; return the decoded JSON (or None for 204).
+        On a 401 with M2M credentials, refresh the token once and retry."""
+        token = self._access_token()
+        try:
+            response = self._http.request(
+                method,
+                f"{self._base}{path}",
+                params=params,
+                json=json,
+                headers={"Authorization": f"Bearer {token}"},
+            )
+        except httpx.HTTPError as exc:
+            raise NetworkError(f"Request to {path} failed: {exc}") from exc
+
+        if response.status_code == 401 and not _retried and self._credentials is not None:
+            self._invalidate_token()
+            return self.request(method, path, params=params, json=json, _retried=True)
+
+        raise_for_response(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def paginate(self, path: str, *, params: dict | None = None) -> Iterator[dict]:
+        """Iterate every item across the API's `{items,page,page_size,total,pages}` pages."""
+        page = int((params or {}).get("page", 1))
+        while True:
+            data = self.request("GET", path, params={**(params or {}), "page": page})
+            for item in data.get("items", []):
+                yield item
+            if page >= int(data.get("pages") or 0):
+                break
+            page += 1
+
+    # --- lifecycle ----------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "AdminClient":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()