supaapps-platform93-auth 0.1.0__py3-none-any.whl

platform93_auth/__init__.py

@@ -0,0 +1,38 @@
+from .verifier import Claims, Verifier
+from .machine import (
+    BillingSummary,
+    CustomEventInput,
+    EntitlementPage,
+    Invitation,
+    InvitationInput,
+    InvitationPage,
+    MachineClient,
+    NotificationInput,
+    PublishedEvent,
+    QueuedNotification,
+    User,
+    UserPage,
+    Workspace,
+    WorkspaceAccessPage,
+    WorkspacePage,
+)
+
+__all__ = [
+    "BillingSummary",
+    "Claims",
+    "CustomEventInput",
+    "EntitlementPage",
+    "Invitation",
+    "InvitationInput",
+    "InvitationPage",
+    "MachineClient",
+    "NotificationInput",
+    "PublishedEvent",
+    "QueuedNotification",
+    "User",
+    "UserPage",
+    "Verifier",
+    "Workspace",
+    "WorkspaceAccessPage",
+    "WorkspacePage",
+]

platform93_auth/django.py

@@ -0,0 +1,18 @@
+from django.http import JsonResponse
+
+from .verifier import Verifier
+
+
+class Platform93AuthenticationMiddleware:
+    def __init__(self, get_response, verifier: Verifier | None = None):
+        self.get_response = get_response
+        self.verifier = verifier
+
+    def __call__(self, request):
+        authorization = request.headers.get("Authorization", "")
+        if authorization.lower().startswith("bearer ") and self.verifier:
+            try:
+                request.platform93_claims = self.verifier.verify(authorization[7:].strip())
+            except Exception:
+                return JsonResponse({"detail": "Invalid bearer token"}, status=401)
+        return self.get_response(request)

platform93_auth/fastapi.py

@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from fastapi import Header, HTTPException
+
+from .verifier import Claims, Verifier
+
+
+def bearer_dependency(verifier: Verifier):
+    def verify(authorization: Annotated[str | None, Header()] = None) -> Claims:
+        if not authorization or not authorization.lower().startswith("bearer "):
+            raise HTTPException(status_code=401, detail="Bearer token required")
+        try:
+            return verifier.verify(authorization[7:].strip())
+        except Exception as error:
+            raise HTTPException(status_code=401, detail="Invalid bearer token") from error
+
+    return verify

platform93_auth/flask.py

@@ -0,0 +1,23 @@
+from functools import wraps
+
+from flask import g, jsonify, request
+
+from .verifier import Verifier
+
+
+def require_platform93(verifier: Verifier):
+    def decorator(function):
+        @wraps(function)
+        def wrapped(*args, **kwargs):
+            authorization = request.headers.get("Authorization", "")
+            if not authorization.lower().startswith("bearer "):
+                return jsonify(detail="Bearer token required"), 401
+            try:
+                g.platform93_claims = verifier.verify(authorization[7:].strip())
+            except Exception:
+                return jsonify(detail="Invalid bearer token"), 401
+            return function(*args, **kwargs)
+
+        return wrapped
+
+    return decorator

platform93_auth/machine.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import NotRequired, TypedDict, cast
+from urllib.parse import quote
+
+import httpx
+
+
+JsonValue = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+
+
+class NotificationInput(TypedDict):
+    template_key: str
+    user_id: NotRequired[str]
+    recipient: NotRequired[str]
+    locale: NotRequired[str]
+    variables: NotRequired[dict[str, JsonValue]]
+
+
+class QueuedNotification(TypedDict):
+    id: str
+    status: str
+    requested_locale: str
+    resolved_locale: str
+    fallback_used: bool
+
+
+class InvitationInput(TypedDict):
+    email: str
+    workspace_id: NotRequired[str]
+    application_role_keys: NotRequired[list[str]]
+    workspace_role_keys: NotRequired[list[str]]
+    expires_in: NotRequired[int]
+
+
+class Invitation(TypedDict):
+    id: str
+    email: str
+    workspace_id: str | None
+    application_role_keys: list[str]
+    workspace_role_keys: list[str]
+    status: str
+    expires_at: str
+
+
+class InvitationPage(TypedDict):
+    items: list[Invitation]
+    next_cursor: str | None
+
+
+class InvitationResent(TypedDict):
+    id: str
+    last_sent_at: str
+    resend_available_at: str
+    expires_at: str
+
+
+class User(TypedDict):
+    id: str
+    application_id: str
+    email: str
+    first_name: str
+    last_name: str
+    username: str | None
+    locale: str
+    email_verified: bool
+    is_org_verified: bool
+    status: str
+    custom_attributes: dict[str, JsonValue]
+    version: int
+
+
+class UserPage(TypedDict):
+    items: list[User]
+    next_cursor: str | None
+
+
+class Workspace(TypedDict):
+    id: str
+    application_id: str
+    owner_user_id: str
+    key: str
+    name: str
+    metadata: dict[str, JsonValue]
+    status: str
+    version: int
+    created_at: str
+    updated_at: str
+
+
+class WorkspacePage(TypedDict):
+    items: list[Workspace]
+    next_cursor: str | None
+
+
+class WorkspaceAccess(TypedDict):
+    type: str
+    workspace_id: str
+    user_id: str | None
+    email: str | None
+    role_keys: list[str]
+    invitation_id: str | None
+    status: str
+    expires_at: str | None
+
+
+class WorkspaceAccessPage(TypedDict):
+    items: list[WorkspaceAccess]
+    next_cursor: str | None
+
+
+class EntitlementGrant(TypedDict):
+    id: str
+    subject_type: str
+    subject_id: str
+    source_type: str
+    feature_values: dict[str, JsonValue]
+    configuration: dict[str, JsonValue]
+    starts_at: str
+    expires_at: str | None
+    external_reference: str | None
+
+
+class EntitlementPage(TypedDict):
+    items: list[EntitlementGrant]
+    next_cursor: str | None
+
+
+class BillingProfile(TypedDict):
+    id: str
+    subject_type: str
+    subject_id: str
+    name: str | None
+    email: str | None
+    tax_id: str | None
+    version: int
+
+
+class Subscription(TypedDict):
+    id: str
+    subject_type: str
+    subject_id: str
+    price_id: str
+    provider_id: str
+    status: str
+    external_reference: str | None
+
+
+class BillingSummary(TypedDict):
+    subject_type: str
+    subject_id: str
+    billing_profile: BillingProfile | None
+    subscriptions: list[Subscription]
+
+
+class CustomEventInput(TypedDict):
+    type: str
+    subject: str
+    data: dict[str, JsonValue]
+    correlation_id: NotRequired[str]
+    causation_id: NotRequired[str]
+
+
+class PublishedEvent(TypedDict):
+    id: str
+    specversion: str
+    source: str
+    type: str
+    subject: str
+    schema_version: str
+    data: dict[str, JsonValue]
+
+
+class MachineClient:
+    """Server-only Platform93 client with cached OAuth client credentials."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        application_id: str,
+        client_id: str,
+        client_secret: str,
+        scopes: list[str] | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not all((base_url, application_id, client_id, client_secret)):
+            raise ValueError("Platform93 machine client requires base_url, application_id, client_id, and client_secret")
+        self.base_url = base_url.rstrip("/")
+        self.application_id = application_id
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.scopes = scopes or []
+        self.client = client or httpx.Client(timeout=30.0)
+        self._token: str | None = None
+        self._expires_at = 0.0
+        self._lock = threading.Lock()
+
+    def update_secret(self, secret: str) -> None:
+        if not secret:
+            raise ValueError("Platform93 machine client secret is required")
+        with self._lock:
+            self.client_secret = secret
+            self._token = None
+            self._expires_at = 0.0
+
+    def send_notification(self, notification: NotificationInput, idempotency_key: str) -> QueuedNotification:
+        return cast(QueuedNotification, self._request("POST", "/notifications", notification, idempotency_key))
+
+    def create_invitation(self, invitation: InvitationInput) -> Invitation:
+        return cast(Invitation, self._request("POST", "/invitations", invitation))
+
+    def list_invitations(self) -> InvitationPage:
+        return cast(InvitationPage, self._request("GET", "/invitations"))
+
+    def get_invitation(self, invitation_id: str) -> Invitation:
+        return cast(Invitation, self._request("GET", f"/invitations/{quote(invitation_id, safe='')}"))
+
+    def resend_invitation(self, invitation_id: str) -> InvitationResent:
+        return cast(InvitationResent, self._request("POST", f"/invitations/{quote(invitation_id, safe='')}/resend"))
+
+    def revoke_invitation(self, invitation_id: str) -> None:
+        self._request("DELETE", f"/invitations/{quote(invitation_id, safe='')}")
+
+    def list_users(self) -> UserPage:
+        return cast(UserPage, self._request("GET", "/users"))
+
+    def get_user(self, user_id: str) -> User:
+        return cast(User, self._request("GET", f"/users/{quote(user_id, safe='')}"))
+
+    def list_workspaces(self) -> WorkspacePage:
+        return cast(WorkspacePage, self._request("GET", "/workspaces"))
+
+    def get_workspace(self, workspace_id: str) -> Workspace:
+        return cast(Workspace, self._request("GET", f"/service/workspaces/{quote(workspace_id, safe='')}"))
+
+    def get_workspace_access(self, workspace_id: str) -> WorkspaceAccessPage:
+        return cast(WorkspaceAccessPage, self._request("GET", f"/service/workspaces/{quote(workspace_id, safe='')}/access"))
+
+    def get_entitlements(self, subject_type: str, subject_id: str) -> EntitlementPage:
+        return cast(EntitlementPage, self._request("GET", f"/subjects/{self._subject(subject_type, subject_id)}/entitlements"))
+
+    def get_billing(self, subject_type: str, subject_id: str) -> BillingSummary:
+        return cast(BillingSummary, self._request("GET", f"/subjects/{self._subject(subject_type, subject_id)}/billing"))
+
+    def publish_event(self, event: CustomEventInput, idempotency_key: str) -> PublishedEvent:
+        return cast(PublishedEvent, self._request("POST", "/events", event, idempotency_key))
+
+    def _subject(self, subject_type: str, subject_id: str) -> str:
+        if subject_type not in {"user", "workspace"}:
+            raise ValueError("Platform93 subject type must be user or workspace")
+        return f"{subject_type}/{quote(subject_id, safe='')}"
+
+    def _access_token(self) -> str:
+        with self._lock:
+            if self._token and time.time() < self._expires_at - 30:
+                return self._token
+            data = {"grant_type": "client_credentials"}
+            if self.scopes:
+                data["scope"] = " ".join(self.scopes)
+            response = self.client.post(
+                f"{self.base_url}/oidc/token",
+                data=data,
+                auth=(self.client_id, self.client_secret),
+                headers={"Accept": "application/json"},
+            )
+            response.raise_for_status()
+            payload = response.json()
+            token = payload.get("access_token")
+            if not isinstance(token, str) or not token:
+                raise RuntimeError("Platform93 token response did not contain an access token")
+            self._token = token
+            self._expires_at = time.time() + max(1, int(payload.get("expires_in", 300)))
+            return token
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, object] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, object]:
+        headers = {"Accept": "application/json", "Authorization": f"Bearer {self._access_token()}"}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        response = self.client.request(
+            method,
+            f"{self.base_url}/v1/applications/{quote(self.application_id, safe='')}{path}",
+            json=body,
+            headers=headers,
+        )
+        response.raise_for_status()
+        return response.json() if response.content else {}

platform93_auth/verifier.py

@@ -0,0 +1,145 @@
+from dataclasses import dataclass
+import re
+from typing import Any
+
+import jwt
+from jwt import PyJWKClient
+
+
+@dataclass(frozen=True)
+class Claims:
+    values: dict[str, Any]
+
+    @property
+    def locale(self) -> str:
+        return str(self.values.get("locale", ""))
+
+    @property
+    def custom_claims(self) -> dict[str, Any]:
+        value = self.values.get("custom_claims", {})
+        return value if isinstance(value, dict) else {}
+
+    @property
+    def roles(self) -> dict[str, Any]:
+        return self.values["roles"]
+
+    def has_permission(self, permission: str) -> bool:
+        if not _valid_absolute_permission(permission):
+            return False
+        return any(
+            value == permission
+            or (
+                value.endswith("/*")
+                and (permission == value[:-2] or permission.startswith(value[:-1]))
+            )
+            for value in self.values.get("scope", "").split(" ")
+            if _valid_absolute_permission(value)
+        )
+
+
+class Verifier:
+    def __init__(self, issuer: str, audience: str, application_id: str):
+        self.issuer = issuer.rstrip("/")
+        self.audience = audience
+        self.application_id = application_id
+        self.jwks = PyJWKClient(
+            f"{self.issuer}/jwks.json", cache_jwk_set=True, lifespan=300
+        )
+
+    def verify(self, token: str) -> Claims:
+        header = jwt.get_unverified_header(token)
+        if (
+            header.get("alg") != "RS256"
+            or header.get("typ") != "JWT"
+            or not isinstance(header.get("kid"), str)
+            or not header["kid"]
+        ):
+            raise jwt.InvalidTokenError("Platform93 token algorithm rejected")
+        key = self.jwks.get_signing_key_from_jwt(token)
+        values = jwt.decode(
+            token,
+            key.key,
+            algorithms=["RS256"],
+            audience=self.audience,
+            issuer=self.issuer,
+            options={
+                "require": [
+                    "exp", "iat", "nbf", "iss", "sub", "aud",
+                    "application_id", "token_kind", "actor_type", "scope", "roles",
+                ]
+            },
+        )
+        if (
+            not isinstance(values.get("sub"), str)
+            or not values["sub"]
+            or values.get("application_id") != self.application_id
+            or not (
+                values.get("token_kind") == "access"
+                and values.get("actor_type") == "user"
+                or values.get("token_kind") == "machine"
+                and values.get("actor_type") == "client"
+            )
+            or not isinstance(values.get("scope"), str)
+        ):
+            raise jwt.InvalidTokenError("Platform93 token context rejected")
+        actor = values.get("act")
+        if actor is not None and (
+            values["token_kind"] != "access"
+            or not isinstance(actor, dict)
+            or actor.get("type") != "control_user"
+            or not isinstance(actor.get("sub"), str)
+            or not actor["sub"]
+        ):
+            raise jwt.InvalidTokenError("Platform93 delegated token actor rejected")
+        if not _valid_scope_claim(values["scope"], self.application_id) or not _valid_roles_claim(values.get("roles")):
+            raise jwt.InvalidTokenError("Platform93 token authorization claims rejected")
+        if actor is not None and (values["roles"]["application"] or values["roles"]["workspaces"]):
+            raise jwt.InvalidTokenError("Platform93 delegated token roles rejected")
+        return Claims(values)
+
+
+def _valid_scope_claim(scope: Any, application_id: str) -> bool:
+    if not isinstance(scope, str):
+        return False
+    if scope == "":
+        return True
+    if scope != scope.strip() or any(value in scope for value in ("\t", "\r", "\n", "  ")):
+        return False
+    values = scope.split(" ")
+    if len(values) != len(set(values)):
+        return False
+    prefix = f"/applications/{application_id}/"
+    return all(value in _PROTOCOL_SCOPES or value.startswith(prefix) and _valid_absolute_permission(value) for value in values)
+
+
+def _valid_absolute_permission(value: str) -> bool:
+    if not isinstance(value, str) or not value.startswith("/") or any(character in value for character in " :\\%\t\r\n"):
+        return False
+    segments = value[1:].split("/")
+    return len(segments) >= 3 and all(
+        index == len(segments) - 1 if segment == "*" else bool(_SEGMENT.fullmatch(segment))
+        for index, segment in enumerate(segments)
+    )
+
+
+def _valid_roles_claim(value: Any) -> bool:
+    if not isinstance(value, dict) or set(value) != {"application", "workspaces"}:
+        return False
+    application, workspaces = value["application"], value["workspaces"]
+    if not isinstance(application, list) or not isinstance(workspaces, dict) or not _unique_roles(application):
+        return False
+    return all(
+        bool(_WORKSPACE_KEY.fullmatch(workspace_id)) and isinstance(roles, list) and _unique_roles(roles)
+        for workspace_id, roles in workspaces.items()
+    )
+
+
+def _unique_roles(values: list[Any]) -> bool:
+    if not all(isinstance(value, str) and _ROLE_KEY.fullmatch(value) for value in values):
+        return False
+    return len(values) == len(set(values))
+
+_SEGMENT = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+_ROLE_KEY = re.compile(r"^[a-z][a-z0-9_-]{0,62}$")
+_WORKSPACE_KEY = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$")
+_PROTOCOL_SCOPES = {"openid", "profile", "email", "offline_access"}

supaapps_platform93_auth-0.1.0.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.5
+Name: supaapps-platform93-auth
+Version: 0.1.0
+Summary: Strict Platform93 JWT verification
+Project-URL: Homepage, https://github.com/supaapps/platform93
+Project-URL: Repository, https://github.com/supaapps/platform93
+Project-URL: Issues, https://github.com/supaapps/platform93/issues
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pyjwt[crypto]<3,>=2.10
+Provides-Extra: django
+Requires-Dist: django>=5.1; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.1; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# supaapps-platform93-auth
+
+Strict Platform93 JWT verification plus a backend-only `MachineClient`. The machine
+client uses OAuth client credentials and provides notification, invitation, user,
+workspace, entitlement, billing-summary, and custom-event methods. Keep its client
+secret in backend secret storage and never expose it to browser code.
+
+Strict server-side verification for Platform93 application JWTs, including issuer,
+audience, actor type, application boundary, expiry, and JWKS rotation checks.
+
+```bash
+pip install supaapps-platform93-auth
+```
+
+Framework adapters are available through the `fastapi`, `django`, and `flask` extras.
+See the [Platform93 repository](https://github.com/supaapps/platform93) for contracts
+and integration documentation.

supaapps_platform93_auth-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+platform93_auth/__init__.py,sha256=OwWSmYo2KWF6EiQ1zhIFpLRY1uIBLTprx9U6g9HMc3U,717
+platform93_auth/django.py,sha256=VSodLcCVmRuz1xOMPbg1G-_w5c1ocf4B_periGLcneo,697
+platform93_auth/fastapi.py,sha256=pQt1XCr6vauQCpxTbUlRri5xhMQk8RAmJM8TIpYBBrI,620
+platform93_auth/flask.py,sha256=bKz-0QTy_e3RKX4iV0kVZ7N0-Fbh81yEsIMM6PH9z-M,724
+platform93_auth/machine.py,sha256=P0hpYn54hO1XWZR7Y54sFhPigVqLEOjQlS2T60tjezs,8894
+platform93_auth/verifier.py,sha256=PtImj8nnCjDBahaMQ33jy_dnGWmV4vYfLSWn-CsYLhc,5516
+supaapps_platform93_auth-0.1.0.dist-info/METADATA,sha256=4wS7JObp54GOuJgPA_og0EKxfI8pdq-FuN3zj_vHpwY,1441
+supaapps_platform93_auth-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+supaapps_platform93_auth-0.1.0.dist-info/RECORD,,

supaapps_platform93_auth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any