hearth-sdk 1.0.0__py3-none-any.whl

hearth/__init__.py

@@ -0,0 +1,113 @@
+"""Hearth identity platform Python SDK.
+
+Provides HearthClient (auth flows, RBAC predicates), AdminClient
+(user/realm CRUD), mode-aware middleware, and all request/response types.
+"""
+
+from .client import HearthClient
+from .admin import AdminClient
+from .errors import (
+    HearthError,
+    HearthSdkError,
+    ConfigurationError,
+    DiscoveryError,
+    JWKSFetchError,
+    TokenExpiredError,
+    TokenNotYetValidError,
+    TokenInvalidError,
+    TokenIssuerError,
+    TokenAudienceError,
+    IntrospectionError,
+    RequiredActionError,
+    AuthorizationModeMismatchError,
+)
+from .claims import Claims
+from .middleware import RequirePermissionMiddleware, WsgiPermissionMiddleware
+from .types import (
+    AccessTokenAuthorizationMode,
+    BootstrapResponse,
+    User,
+    CreateUserRequest,
+    UpdateUserRequest,
+    Realm,
+    CreateRealmRequest,
+    UpdateRealmRequest,
+    PageResponse,
+    AuthorizeResponse,
+    TokenResponse,
+    UserInfoResponse,
+    MePermissionsResponse,
+    OAuthClient,
+    RegisterClientRequest,
+    CreateClientRequest,
+    UpdateClientRequest,
+    Role,
+    CreateRoleRequest,
+    UpdateRoleRequest,
+    Group,
+    CreateGroupRequest,
+    UpdateGroupRequest,
+    OrgMember,
+    AddOrgMemberRequest,
+    JwksDocument,
+    IntrospectRequest,
+    IntrospectResponse,
+    CheckPermissionRequest,
+    CheckPermissionResponse,
+)
+
+__all__ = [
+    # Clients
+    "HearthClient",
+    "AdminClient",
+    # Middleware
+    "RequirePermissionMiddleware",
+    "WsgiPermissionMiddleware",
+    # Errors
+    "HearthError",
+    "HearthSdkError",
+    "ConfigurationError",
+    "DiscoveryError",
+    "JWKSFetchError",
+    "TokenExpiredError",
+    "TokenNotYetValidError",
+    "TokenInvalidError",
+    "TokenIssuerError",
+    "TokenAudienceError",
+    "IntrospectionError",
+    "RequiredActionError",
+    "AuthorizationModeMismatchError",
+    # Claims
+    "Claims",
+    # Types
+    "AccessTokenAuthorizationMode",
+    "BootstrapResponse",
+    "User",
+    "CreateUserRequest",
+    "UpdateUserRequest",
+    "Realm",
+    "CreateRealmRequest",
+    "UpdateRealmRequest",
+    "PageResponse",
+    "AuthorizeResponse",
+    "TokenResponse",
+    "UserInfoResponse",
+    "MePermissionsResponse",
+    "OAuthClient",
+    "RegisterClientRequest",
+    "CreateClientRequest",
+    "UpdateClientRequest",
+    "Role",
+    "CreateRoleRequest",
+    "UpdateRoleRequest",
+    "Group",
+    "CreateGroupRequest",
+    "UpdateGroupRequest",
+    "OrgMember",
+    "AddOrgMemberRequest",
+    "JwksDocument",
+    "IntrospectRequest",
+    "IntrospectResponse",
+    "CheckPermissionRequest",
+    "CheckPermissionResponse",
+]

hearth/admin.py

@@ -0,0 +1,335 @@
+"""AdminClient: user and realm CRUD operations (requires admin token)."""
+
+from typing import Optional, List
+
+import httpx
+
+from .errors import HearthError
+from .types import (
+    User,
+    CreateUserRequest,
+    UpdateUserRequest,
+    Realm,
+    CreateRealmRequest,
+    UpdateRealmRequest,
+    PageResponse,
+    OAuthClient,
+    CreateClientRequest,
+    UpdateClientRequest,
+    Role,
+    CreateRoleRequest,
+    UpdateRoleRequest,
+    Group,
+    CreateGroupRequest,
+    UpdateGroupRequest,
+    OrgMember,
+    AddOrgMemberRequest,
+)
+
+
+class AdminClient:
+    """Client for Hearth admin operations (user and realm CRUD).
+
+    Requires an admin access token obtained via ``/admin/bootstrap`` or
+    from a user with the ``hearth.admin`` permission.
+
+    Attributes:
+        base_url: The Hearth server base URL.
+        admin_token: A Bearer access token with admin privileges.
+        realm_id: The realm to operate on.
+    """
+
+    def __init__(self, base_url: str, admin_token: str, realm_id: str, timeout: float = 30.0):
+        self._base = base_url.rstrip("/")
+        self._token = admin_token
+        self._realm = realm_id
+        self._http = httpx.Client(
+            headers={
+                "X-Realm-ID": realm_id,
+                "Authorization": f"Bearer {admin_token}",
+            },
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Users
+    # ------------------------------------------------------------------
+
+    def create_user(self, req: CreateUserRequest) -> User:
+        """Create a new user."""
+        resp = self._http.post(
+            f"{self._base}/admin/users", json=req.model_dump(exclude_none=True)
+        )
+        if resp.status_code not in (200, 201):
+            raise HearthError(resp.status_code, resp.text)
+        return User(**resp.json())
+
+    def list_users(
+        self, cursor: Optional[str] = None, limit: int = 50
+    ) -> PageResponse[User]:
+        """List users with cursor-based pagination."""
+        params = {"limit": str(limit)}
+        if cursor:
+            params["cursor"] = cursor
+        resp = self._http.get(f"{self._base}/admin/users", params=params)
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        data = resp.json()
+        return PageResponse[User](**data)
+
+    def get_user(self, user_id: str) -> User:
+        """Get a user by ID."""
+        resp = self._http.get(f"{self._base}/admin/users/{user_id}")
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return User(**resp.json())
+
+    def update_user(self, user_id: str, req: UpdateUserRequest) -> User:
+        """Update an existing user."""
+        resp = self._http.put(
+            f"{self._base}/admin/users/{user_id}",
+            json=req.model_dump(exclude_none=True),
+        )
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return User(**resp.json())
+
+    def delete_user(self, user_id: str) -> None:
+        """Delete a user."""
+        resp = self._http.delete(f"{self._base}/admin/users/{user_id}")
+        if resp.status_code not in (200, 204):
+            raise HearthError(resp.status_code, resp.text)
+
+    # ------------------------------------------------------------------
+    # Realms
+    # ------------------------------------------------------------------
+
+    def create_realm(self, req: CreateRealmRequest) -> Realm:
+        """Create a new realm."""
+        resp = self._http.post(
+            f"{self._base}/admin/realms", json=req.model_dump(exclude_none=True)
+        )
+        if resp.status_code not in (200, 201):
+            raise HearthError(resp.status_code, resp.text)
+        return Realm(**resp.json())
+
+    def list_realms(self) -> List[Realm]:
+        """List all realms."""
+        resp = self._http.get(f"{self._base}/admin/realms")
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        data = resp.json()
+        return [Realm(**r) for r in data.get("items", data)]
+
+    def get_realm(self, realm_id: str) -> Realm:
+        """Get a realm by ID."""
+        resp = self._http.get(f"{self._base}/admin/realms/{realm_id}")
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return Realm(**resp.json())
+
+    def update_realm(self, realm_id: str, req: UpdateRealmRequest) -> Realm:
+        """Update an existing realm."""
+        resp = self._http.put(
+            f"{self._base}/admin/realms/{realm_id}",
+            json=req.model_dump(exclude_none=True),
+        )
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return Realm(**resp.json())
+
+    def delete_realm(self, realm_id: str) -> None:
+        """Delete a realm."""
+        resp = self._http.delete(f"{self._base}/admin/realms/{realm_id}")
+        if resp.status_code not in (200, 204):
+            raise HearthError(resp.status_code, resp.text)
+
+    # ------------------------------------------------------------------
+    # OAuth Clients
+    # ------------------------------------------------------------------
+
+    def create_client(self, req: CreateClientRequest) -> OAuthClient:
+        """Create a new OAuth client."""
+        resp = self._http.post(
+            f"{self._base}/admin/clients", json=req.model_dump(exclude_none=True)
+        )
+        if resp.status_code not in (200, 201):
+            raise HearthError(resp.status_code, resp.text)
+        return OAuthClient(**resp.json())
+
+    def list_clients(
+        self, cursor: Optional[str] = None, limit: int = 50
+    ) -> PageResponse[OAuthClient]:
+        """List OAuth clients with cursor-based pagination."""
+        params = {"limit": str(limit)}
+        if cursor:
+            params["cursor"] = cursor
+        resp = self._http.get(f"{self._base}/admin/clients", params=params)
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        data = resp.json()
+        return PageResponse[OAuthClient](**data)
+
+    def get_client(self, client_id: str) -> OAuthClient:
+        """Get an OAuth client by ID."""
+        resp = self._http.get(f"{self._base}/admin/clients/{client_id}")
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return OAuthClient(**resp.json())
+
+    def update_client(self, client_id: str, req: UpdateClientRequest) -> OAuthClient:
+        """Update an existing OAuth client."""
+        resp = self._http.put(
+            f"{self._base}/admin/clients/{client_id}",
+            json=req.model_dump(exclude_none=True),
+        )
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return OAuthClient(**resp.json())
+
+    def delete_client(self, client_id: str) -> None:
+        """Delete an OAuth client."""
+        resp = self._http.delete(f"{self._base}/admin/clients/{client_id}")
+        if resp.status_code not in (200, 204):
+            raise HearthError(resp.status_code, resp.text)
+
+    # ------------------------------------------------------------------
+    # Roles
+    # ------------------------------------------------------------------
+
+    def create_role(self, req: CreateRoleRequest) -> Role:
+        """Create a new realm-level role."""
+        resp = self._http.post(
+            f"{self._base}/admin/roles", json=req.model_dump(exclude_none=True)
+        )
+        if resp.status_code not in (200, 201):
+            raise HearthError(resp.status_code, resp.text)
+        return Role(**resp.json())
+
+    def list_roles(
+        self, cursor: Optional[str] = None, limit: int = 50
+    ) -> PageResponse[Role]:
+        """List realm-level roles with cursor-based pagination."""
+        params = {"limit": str(limit)}
+        if cursor:
+            params["cursor"] = cursor
+        resp = self._http.get(f"{self._base}/admin/roles", params=params)
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        data = resp.json()
+        return PageResponse[Role](**data)
+
+    def get_role(self, role_id: str) -> Role:
+        """Get a role by ID."""
+        resp = self._http.get(f"{self._base}/admin/roles/{role_id}")
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return Role(**resp.json())
+
+    def update_role(self, role_id: str, req: UpdateRoleRequest) -> Role:
+        """Update an existing role."""
+        resp = self._http.put(
+            f"{self._base}/admin/roles/{role_id}",
+            json=req.model_dump(exclude_none=True),
+        )
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return Role(**resp.json())
+
+    def delete_role(self, role_id: str) -> None:
+        """Delete a role."""
+        resp = self._http.delete(f"{self._base}/admin/roles/{role_id}")
+        if resp.status_code not in (200, 204):
+            raise HearthError(resp.status_code, resp.text)
+
+    # ------------------------------------------------------------------
+    # Groups
+    # ------------------------------------------------------------------
+
+    def create_group(self, req: CreateGroupRequest) -> Group:
+        """Create a new realm-level group."""
+        resp = self._http.post(
+            f"{self._base}/admin/groups", json=req.model_dump(exclude_none=True)
+        )
+        if resp.status_code not in (200, 201):
+            raise HearthError(resp.status_code, resp.text)
+        return Group(**resp.json())
+
+    def list_groups(
+        self, cursor: Optional[str] = None, limit: int = 50
+    ) -> PageResponse[Group]:
+        """List realm-level groups with cursor-based pagination."""
+        params = {"limit": str(limit)}
+        if cursor:
+            params["cursor"] = cursor
+        resp = self._http.get(f"{self._base}/admin/groups", params=params)
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        data = resp.json()
+        return PageResponse[Group](**data)
+
+    def get_group(self, group_id: str) -> Group:
+        """Get a group by ID."""
+        resp = self._http.get(f"{self._base}/admin/groups/{group_id}")
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return Group(**resp.json())
+
+    def update_group(self, group_id: str, req: UpdateGroupRequest) -> Group:
+        """Update an existing group."""
+        resp = self._http.put(
+            f"{self._base}/admin/groups/{group_id}",
+            json=req.model_dump(exclude_none=True),
+        )
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        return Group(**resp.json())
+
+    def delete_group(self, group_id: str) -> None:
+        """Delete a group."""
+        resp = self._http.delete(f"{self._base}/admin/groups/{group_id}")
+        if resp.status_code not in (200, 204):
+            raise HearthError(resp.status_code, resp.text)
+
+    # ------------------------------------------------------------------
+    # Organization Memberships
+    # ------------------------------------------------------------------
+
+    def list_org_members(
+        self, org_id: str, cursor: Optional[str] = None, limit: int = 50
+    ) -> PageResponse[OrgMember]:
+        """List members of an organization with cursor-based pagination."""
+        params = {"limit": str(limit)}
+        if cursor:
+            params["cursor"] = cursor
+        resp = self._http.get(f"{self._base}/admin/orgs/{org_id}/members", params=params)
+        if resp.status_code != 200:
+            raise HearthError(resp.status_code, resp.text)
+        data = resp.json()
+        return PageResponse[OrgMember](**data)
+
+    def add_org_member(self, org_id: str, req: AddOrgMemberRequest) -> OrgMember:
+        """Add a user to an organization."""
+        resp = self._http.post(
+            f"{self._base}/admin/orgs/{org_id}/members",
+            json=req.model_dump(exclude_none=True),
+        )
+        if resp.status_code not in (200, 201):
+            raise HearthError(resp.status_code, resp.text)
+        return OrgMember(**resp.json())
+
+    def remove_org_member(self, org_id: str, user_id: str) -> None:
+        """Remove a user from an organization."""
+        resp = self._http.delete(f"{self._base}/admin/orgs/{org_id}/members/{user_id}")
+        if resp.status_code not in (200, 204):
+            raise HearthError(resp.status_code, resp.text)
+
+    def close(self):
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

hearth/claims.py

@@ -0,0 +1,149 @@
+"""Spec §4 — Claims API.
+
+:class:`Claims` wraps a decoded JWT payload and exposes typed accessors
+for standard OIDC and Hearth-specific claims.  All reads are local —
+no network call is made.  Signature verification is the caller's
+responsibility.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from .errors import (
+    TokenExpiredError,
+    TokenInvalidError,
+    TokenNotYetValidError,
+)
+
+
+class Claims:
+    """Typed accessor for a decoded JWT's claims (spec §4).
+
+    Construct via :meth:`decode` or pass a pre-decoded payload dict.
+    """
+
+    def __init__(self, payload: Dict[str, Any]) -> None:
+        self._payload = payload
+
+    @classmethod
+    def decode(cls, token: str) -> "Claims":
+        """Decode a JWT string without verifying its signature.
+
+        :raises TokenInvalidError: if the string is not a structurally valid JWT.
+        """
+        parts = token.split(".")
+        if len(parts) != 3:
+            raise TokenInvalidError("expected three dot-separated segments")
+        try:
+            padded = parts[1] + "=" * (-len(parts[1]) % 4)
+            payload_bytes = base64.urlsafe_b64decode(padded)
+            payload: Dict[str, Any] = json.loads(payload_bytes)
+        except Exception as exc:
+            raise TokenInvalidError(f"failed to decode JWT payload: {exc}") from exc
+        return cls(payload)
+
+    def assert_valid(self, clock_skew_seconds: int = 0) -> None:
+        """Assert the token is temporally valid.
+
+        :raises TokenExpiredError: if exp is in the past.
+        :raises TokenNotYetValidError: if nbf is in the future.
+        """
+        now = int(time.time())
+        exp = self._payload.get("exp")
+        if exp is not None and now > exp + clock_skew_seconds:
+            raise TokenExpiredError(exp)
+        nbf = self._payload.get("nbf")
+        if nbf is not None and now < nbf - clock_skew_seconds:
+            raise TokenNotYetValidError(nbf)
+
+    def subject(self) -> str:
+        """Return the ``sub`` (subject) claim."""
+        return str(self._payload.get("sub", ""))
+
+    def issuer(self) -> str:
+        """Return the ``iss`` (issuer) claim."""
+        return str(self._payload.get("iss", ""))
+
+    def audiences(self) -> List[str]:
+        """Return the ``aud`` (audiences) claim normalised to a list."""
+        aud = self._payload.get("aud")
+        if aud is None:
+            return []
+        if isinstance(aud, list):
+            return [str(a) for a in aud]
+        return [str(aud)]
+
+    def expiry(self) -> Optional[int]:
+        """Return the ``exp`` claim as a Unix timestamp, or None if absent."""
+        val = self._payload.get("exp")
+        return int(val) if val is not None else None
+
+    def issuedAt(self) -> Optional[int]:
+        """Return the ``iat`` claim as a Unix timestamp, or None if absent."""
+        val = self._payload.get("iat")
+        return int(val) if val is not None else None
+
+    def jwtID(self) -> Optional[str]:
+        """Return the ``jti`` (JWT ID) claim, or None if absent."""
+        val = self._payload.get("jti")
+        return str(val) if val is not None else None
+
+    def scopes(self) -> List[str]:
+        """Return the individual scopes from the ``scope`` claim."""
+        raw = self._payload.get("scope", "")
+        if not raw:
+            return []
+        return [s for s in str(raw).split() if s]
+
+    def hasScope(self, scope: str) -> bool:
+        """Return True iff the token contains the given scope."""
+        return scope in self.scopes()
+
+    def scope(self) -> str:
+        """Return the ``scope`` claim as a space-delimited string (spec §4)."""
+        return str(self._payload.get("scope", ""))
+
+    def in_group(self, group_id: str) -> bool:
+        """Return True iff the token's ``groups`` claim contains the given group."""
+        groups: List[str] = self._payload.get("groups", []) or []
+        return group_id in groups
+
+    def in_org(self, org_id: str) -> bool:
+        """Return True iff the token's ``oid`` claim matches org_id (exact)."""
+        oid = self._payload.get("oid")
+        return oid == org_id if oid is not None else False
+
+    def token_type(self) -> str:
+        """Return the ``token_type`` claim (``'access'``, ``'refresh'``, or ``'required_action'``)."""
+        return str(self._payload.get("token_type", ""))
+
+    def organization_id(self) -> Optional[str]:
+        """Return the ``oid`` (organization ID) claim, or None if absent."""
+        val = self._payload.get("oid")
+        return str(val) if val is not None else None
+
+    def org_groups(self) -> List[str]:
+        """Return the ``org_groups`` claim (Keycloak-style paths, e.g. ``/org-slug/group``)."""
+        val = self._payload.get("org_groups", []) or []
+        return [str(g) for g in val]
+
+    def hasRole(self, role: str) -> bool:
+        """Return True iff the token's ``roles`` claim contains the given role."""
+        roles: List[str] = self._payload.get("roles", [])
+        return role in roles
+
+    def hasPermission(self, permission: str) -> bool:
+        """Return True iff the token's ``permissions`` claim contains the given permission."""
+        permissions: List[str] = self._payload.get("permissions", [])
+        return permission in permissions
+
+    def get(self, key: str) -> Any:
+        """Return an arbitrary claim by key."""
+        return self._payload.get(key)
+
+    def __repr__(self) -> str:
+        return f"Claims(sub={self.subject()!r}, iss={self.issuer()!r})"