authorizer-py 0.1.0__py3-none-any.whl

authorizer/__init__.py

@@ -0,0 +1,87 @@
+"""Python SDK for authorizer.dev — self-hosted authentication & authorization."""
+
+from __future__ import annotations
+
+from .async_client import AsyncAuthorizerClient
+from .client import AuthorizerClient
+from .exceptions import AuthorizerConnectionError, AuthorizerError
+from .types import (
+    AuthToken,
+    CheckPermissionsRequest,
+    CheckPermissionsResponse,
+    FgaTupleInput,
+    ForgotPasswordRequest,
+    ForgotPasswordResponse,
+    GenericResponse,
+    GetTokenRequest,
+    GetTokenResponse,
+    ListPermissionsRequest,
+    ListPermissionsResponse,
+    LoginRequest,
+    MagicLinkLoginRequest,
+    MetaData,
+    OAuthProviders,
+    Permission,
+    PermissionCheckInput,
+    PermissionCheckResult,
+    ResendOTPRequest,
+    ResendVerifyEmailRequest,
+    ResetPasswordRequest,
+    ResponseTypes,
+    RevokeTokenRequest,
+    SessionQueryRequest,
+    SignUpRequest,
+    TokenType,
+    UpdateProfileRequest,
+    User,
+    ValidateJWTTokenRequest,
+    ValidateJWTTokenResponse,
+    ValidateSessionRequest,
+    ValidateSessionResponse,
+    VerifyEmailRequest,
+    VerifyOTPRequest,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthorizerClient",
+    "AsyncAuthorizerClient",
+    "AuthorizerError",
+    "AuthorizerConnectionError",
+    "AuthToken",
+    "CheckPermissionsRequest",
+    "CheckPermissionsResponse",
+    "FgaTupleInput",
+    "ForgotPasswordRequest",
+    "ForgotPasswordResponse",
+    "GenericResponse",
+    "GetTokenRequest",
+    "GetTokenResponse",
+    "ListPermissionsRequest",
+    "ListPermissionsResponse",
+    "LoginRequest",
+    "MagicLinkLoginRequest",
+    "MetaData",
+    "OAuthProviders",
+    "Permission",
+    "PermissionCheckInput",
+    "PermissionCheckResult",
+    "ResendOTPRequest",
+    "ResendVerifyEmailRequest",
+    "ResetPasswordRequest",
+    "ResponseTypes",
+    "RevokeTokenRequest",
+    "SessionQueryRequest",
+    "SignUpRequest",
+    "TokenType",
+    "UpdateProfileRequest",
+    "User",
+    "ValidateJWTTokenRequest",
+    "ValidateJWTTokenResponse",
+    "ValidateSessionRequest",
+    "ValidateSessionResponse",
+    "VerifyEmailRequest",
+    "VerifyOTPRequest",
+    "__version__",
+]

authorizer/_core.py

@@ -0,0 +1,147 @@
+"""I/O-free request building and response parsing shared by both clients."""
+
+from __future__ import annotations
+
+import json as _json
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlparse
+
+from .exceptions import AuthorizerError
+
+
+@dataclass
+class ClientConfig:
+    client_id: str
+    authorizer_url: str
+    redirect_url: str
+    extra_headers: dict[str, str]
+
+
+@dataclass
+class RequestSpec:
+    method: str
+    url: str
+    headers: dict[str, str]
+    json: dict[str, Any] = field(default_factory=dict)
+
+
+def _origin_from_url(url: str) -> str | None:
+    parsed = urlparse(url)
+    if parsed.scheme and parsed.netloc:
+        return f"{parsed.scheme}://{parsed.netloc}"
+    return None
+
+
+def build_headers(config: ClientConfig, per_call: dict[str, str] | None) -> dict[str, str]:
+    """Assemble headers: identity headers, extra headers, per-call overrides, default Origin."""
+    headers: dict[str, str] = {
+        "Content-Type": "application/json",
+        "x-authorizer-url": config.authorizer_url,
+        "x-authorizer-client-id": config.client_id,
+    }
+    headers.update(config.extra_headers)
+    if per_call:
+        headers.update(per_call)
+    # CSRF guard (Authorizer >= v2.3.0) needs an Origin on state-changing requests.
+    # The server's own origin always passes the same-origin rule under wildcard
+    # ALLOWED_ORIGINS. Callers may override via extra/per-call headers.
+    if "Origin" not in headers:
+        origin = _origin_from_url(config.authorizer_url)
+        if origin:
+            headers["Origin"] = origin
+    return headers
+
+
+def build_graphql_request(
+    authorizer_url: str,
+    query: str,
+    variables: dict[str, Any] | None,
+    headers: dict[str, str],
+) -> RequestSpec:
+    body: dict[str, Any] = {"query": query}
+    if variables:
+        body["variables"] = variables
+    return RequestSpec("POST", f"{authorizer_url}/graphql", headers, body)
+
+
+def build_oauth_request(
+    authorizer_url: str,
+    path: str,
+    body: dict[str, Any],
+    headers: dict[str, str],
+) -> RequestSpec:
+    return RequestSpec("POST", f"{authorizer_url}{path}", headers, body)
+
+
+def _decode(body: bytes) -> Any:
+    if not body:
+        return None
+    try:
+        return _json.loads(body)
+    except ValueError:
+        return None
+
+
+def _raise_for_graphql_errors(status: int, decoded: Any, body: bytes) -> None:
+    """Raise AuthorizerError if *decoded* contains a GraphQL errors array or status >= 400."""
+    if isinstance(decoded, dict):
+        errors = decoded.get("errors")
+        if errors:
+            message = "request failed"
+            if isinstance(errors, list) and errors:
+                first = errors[0]
+                if isinstance(first, dict) and first.get("message"):
+                    message = str(first["message"])
+            elif isinstance(errors, str) and errors:
+                message = errors
+            raise AuthorizerError(
+                message,
+                errors=errors if isinstance(errors, list) else [errors],
+                status=status,
+            )
+    if status >= 400:
+        text = body.decode("utf-8", "replace") if body else ""
+        raise AuthorizerError(f"HTTP {status}: {text}".strip(), status=status)
+
+
+def parse_graphql_response(status: int, body: bytes, field_name: str) -> dict[str, Any] | None:
+    """Return ``data[field_name]`` or raise AuthorizerError.
+
+    Mirrors authorizer-go: a non-empty ``errors`` array is an API error; a
+    >=400 status with no ``errors`` array (CSRF 403, proxy page) is also an error.
+    """
+    decoded = _decode(body)
+    _raise_for_graphql_errors(status, decoded, body)
+    if isinstance(decoded, dict):
+        data = decoded.get("data")
+        if isinstance(data, dict):
+            return data.get(field_name)
+    return None
+
+
+def parse_graphql_data(status: int, body: bytes) -> dict[str, Any]:
+    """Return the whole GraphQL ``data`` object (or {}), raising on errors.
+
+    Behaves like :func:`parse_graphql_response` but returns the full ``data``
+    dict instead of a single named field.  Intended for :meth:`graphql_query`.
+    """
+    decoded = _decode(body)
+    _raise_for_graphql_errors(status, decoded, body)
+    if isinstance(decoded, dict):
+        data = decoded.get("data")
+        if isinstance(data, dict):
+            return data
+    return {}
+
+
+def parse_oauth_response(status: int, body: bytes) -> dict[str, Any]:
+    """Return parsed OAuth JSON or raise AuthorizerError using error fields."""
+    decoded = _decode(body)
+    payload: dict[str, Any] = decoded if isinstance(decoded, dict) else {}
+    if status >= 400:
+        message = str(
+            payload.get("error_description") or payload.get("error") or f"HTTP {status}"
+        )
+        raise AuthorizerError(message, status=status)
+    return payload

authorizer/_queries.py

@@ -0,0 +1,110 @@
+"""GraphQL fragments and query/mutation strings used by the SDK.
+
+Mirrors the queries in authorizer-go so server behavior is identical.
+"""
+
+from __future__ import annotations
+
+USER_FRAGMENT = (
+    "id email email_verified given_name family_name middle_name nickname "
+    "preferred_username picture signup_methods gender birthdate phone_number "
+    "phone_number_verified roles created_at updated_at is_multi_factor_auth_enabled "
+    "app_data revoked_timestamp"
+)
+
+AUTH_TOKEN_FRAGMENT = (
+    "message access_token expires_in refresh_token id_token "
+    "should_show_email_otp_screen should_show_mobile_otp_screen should_show_totp_screen "
+    "authenticator_scanner_image authenticator_secret authenticator_recovery_codes "
+    f"user {{ {USER_FRAGMENT} }}"
+)
+
+LOGIN = (
+    "mutation login($data: LoginRequest!) "
+    f"{{ login(params: $data) {{ {AUTH_TOKEN_FRAGMENT} }} }}"
+)
+
+SIGNUP = (
+    "mutation signup($data: SignUpRequest!) "
+    f"{{ signup(params: $data) {{ {AUTH_TOKEN_FRAGMENT} }} }}"
+)
+
+MAGIC_LINK_LOGIN = (
+    "mutation magicLinkLogin($data: MagicLinkLoginRequest!) "
+    "{ magic_link_login(params: $data) { message } }"
+)
+
+VERIFY_OTP = (
+    "mutation verifyOtp($data: VerifyOTPRequest!) "
+    f"{{ verify_otp(params: $data) {{ {AUTH_TOKEN_FRAGMENT} }} }}"
+)
+
+VERIFY_EMAIL = (
+    "mutation verifyEmail($data: VerifyEmailRequest!) "
+    f"{{ verify_email(params: $data) {{ {AUTH_TOKEN_FRAGMENT} }} }}"
+)
+
+RESEND_OTP = (
+    "mutation resendOtp($data: ResendOTPRequest!) { resend_otp(params: $data) { message } }"
+)
+
+RESEND_VERIFY_EMAIL = (
+    "mutation resendVerifyEmail($data: ResendVerifyEmailRequest!) "
+    "{ resend_verify_email(params: $data) { message } }"
+)
+
+FORGOT_PASSWORD = (
+    "mutation forgotPassword($data: ForgotPasswordRequest!) "
+    "{ forgot_password(params: $data) { message should_show_mobile_otp_screen } }"
+)
+
+RESET_PASSWORD = (
+    "mutation resetPassword($data: ResetPasswordRequest!) "
+    "{ reset_password(params: $data) { message } }"
+)
+
+VALIDATE_JWT_TOKEN = (
+    "query validateJWTToken($data: ValidateJWTTokenRequest!)"
+    "{ validate_jwt_token(params: $data) { is_valid claims } }"
+)
+
+VALIDATE_SESSION = (
+    "query validateSession($data: ValidateSessionRequest!)"
+    f"{{ validate_session(params: $data) {{ is_valid user {{ {USER_FRAGMENT} }} }} }}"
+)
+
+META = (
+    "query { meta { version client_id is_google_login_enabled is_facebook_login_enabled "
+    "is_github_login_enabled is_linkedin_login_enabled is_apple_login_enabled "
+    "is_twitter_login_enabled is_discord_login_enabled is_microsoft_login_enabled "
+    "is_twitch_login_enabled is_roblox_login_enabled is_email_verification_enabled "
+    "is_basic_authentication_enabled is_magic_link_login_enabled is_sign_up_enabled "
+    "is_strong_password_enabled is_multi_factor_auth_enabled "
+    "is_mobile_basic_authentication_enabled is_phone_verification_enabled } }"
+)
+
+SESSION = (
+    "query getSession($data: SessionQueryRequest) "
+    f"{{ session(params: $data) {{ {AUTH_TOKEN_FRAGMENT} }} }}"
+)
+
+PROFILE = f"query {{ profile {{ {USER_FRAGMENT} }} }}"
+
+UPDATE_PROFILE = (
+    "mutation updateProfile($data: UpdateProfileRequest!) "
+    "{ update_profile(params: $data) { message } }"
+)
+
+LOGOUT = "mutation { logout { message } }"
+
+DEACTIVATE_ACCOUNT = "mutation deactivateAccount { deactivate_account { message } }"
+
+CHECK_PERMISSIONS = (
+    "query checkPermissions($data: CheckPermissionsInput!)"
+    "{ check_permissions(params: $data) { results { relation object allowed } } }"
+)
+
+LIST_PERMISSIONS = (
+    "query listPermissions($data: ListPermissionsInput!)"
+    "{ list_permissions(params: $data) { objects permissions { object relation } truncated } }"
+)

authorizer/async_client.py

@@ -0,0 +1,232 @@
+"""Asynchronous Authorizer client."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from . import _queries as q
+from . import types as t
+from ._core import (
+    ClientConfig,
+    RequestSpec,
+    build_graphql_request,
+    build_headers,
+    build_oauth_request,
+    parse_graphql_data,
+    parse_graphql_response,
+    parse_oauth_response,
+)
+from .exceptions import AuthorizerConnectionError
+
+
+class AsyncAuthorizerClient:
+    """Asynchronous client for an Authorizer instance."""
+
+    def __init__(
+        self,
+        client_id: str,
+        authorizer_url: str,
+        redirect_url: str = "",
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        if not client_id or not client_id.strip():
+            raise ValueError("client_id is required")
+        if not authorizer_url or not authorizer_url.strip():
+            raise ValueError("authorizer_url is required")
+        self._config = ClientConfig(
+            client_id=client_id,
+            authorizer_url=authorizer_url.strip().rstrip("/"),
+            redirect_url=redirect_url.strip().rstrip("/"),
+            extra_headers=dict(extra_headers or {}),
+        )
+        self._http = httpx.AsyncClient()
+
+    # -- lifecycle -------------------------------------------------------- #
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncAuthorizerClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    # -- low-level send --------------------------------------------------- #
+    async def _send(self, spec: RequestSpec) -> httpx.Response:
+        try:
+            return await self._http.request(
+                spec.method, spec.url, json=spec.json, headers=spec.headers
+            )
+        except httpx.HTTPError as e:  # network/transport failure
+            raise AuthorizerConnectionError(str(e)) from e
+
+    async def _graphql(
+        self,
+        query: str,
+        field_name: str,
+        variables: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any] | None:
+        spec = build_graphql_request(
+            self._config.authorizer_url, query, variables, build_headers(self._config, headers)
+        )
+        res = await self._send(spec)
+        return parse_graphql_response(res.status_code, res.content, field_name)
+
+    async def _oauth(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        spec = build_oauth_request(
+            self._config.authorizer_url, path, body, build_headers(self._config, None)
+        )
+        res = await self._send(spec)
+        return parse_oauth_response(res.status_code, res.content)
+
+    # -- public auth flows ----------------------------------------------- #
+    async def login(self, req: t.LoginRequest) -> t.AuthToken:
+        res = await self._graphql(q.LOGIN, "login", {"data": req.to_dict()})
+        return t.AuthToken.from_dict(res or {})
+
+    async def signup(self, req: t.SignUpRequest) -> t.AuthToken:
+        res = await self._graphql(q.SIGNUP, "signup", {"data": req.to_dict()})
+        return t.AuthToken.from_dict(res or {})
+
+    async def magic_link_login(self, req: t.MagicLinkLoginRequest) -> t.GenericResponse:
+        payload = req.to_dict()
+        if not payload.get("redirect_uri") and self._config.redirect_url:
+            payload["redirect_uri"] = self._config.redirect_url
+        res = await self._graphql(q.MAGIC_LINK_LOGIN, "magic_link_login", {"data": payload})
+        return t.GenericResponse.from_dict(res or {})
+
+    async def verify_otp(self, req: t.VerifyOTPRequest) -> t.AuthToken:
+        res = await self._graphql(q.VERIFY_OTP, "verify_otp", {"data": req.to_dict()})
+        return t.AuthToken.from_dict(res or {})
+
+    async def verify_email(self, req: t.VerifyEmailRequest) -> t.AuthToken:
+        res = await self._graphql(q.VERIFY_EMAIL, "verify_email", {"data": req.to_dict()})
+        return t.AuthToken.from_dict(res or {})
+
+    async def resend_otp(self, req: t.ResendOTPRequest) -> t.GenericResponse:
+        res = await self._graphql(q.RESEND_OTP, "resend_otp", {"data": req.to_dict()})
+        return t.GenericResponse.from_dict(res or {})
+
+    async def resend_verify_email(self, req: t.ResendVerifyEmailRequest) -> t.GenericResponse:
+        res = await self._graphql(
+            q.RESEND_VERIFY_EMAIL, "resend_verify_email", {"data": req.to_dict()}
+        )
+        return t.GenericResponse.from_dict(res or {})
+
+    async def forgot_password(self, req: t.ForgotPasswordRequest) -> t.ForgotPasswordResponse:
+        payload = req.to_dict()
+        if not payload.get("redirect_uri") and self._config.redirect_url:
+            payload["redirect_uri"] = self._config.redirect_url
+        res = await self._graphql(q.FORGOT_PASSWORD, "forgot_password", {"data": payload})
+        return t.ForgotPasswordResponse.from_dict(res or {})
+
+    async def reset_password(self, req: t.ResetPasswordRequest) -> t.GenericResponse:
+        res = await self._graphql(q.RESET_PASSWORD, "reset_password", {"data": req.to_dict()})
+        return t.GenericResponse.from_dict(res or {})
+
+    async def validate_jwt_token(
+        self, req: t.ValidateJWTTokenRequest
+    ) -> t.ValidateJWTTokenResponse:
+        res = await self._graphql(
+            q.VALIDATE_JWT_TOKEN, "validate_jwt_token", {"data": req.to_dict()}
+        )
+        return t.ValidateJWTTokenResponse.from_dict(res or {})
+
+    async def validate_session(self, req: t.ValidateSessionRequest) -> t.ValidateSessionResponse:
+        res = await self._graphql(
+            q.VALIDATE_SESSION, "validate_session", {"data": req.to_dict()}
+        )
+        return t.ValidateSessionResponse.from_dict(res or {})
+
+    async def get_meta_data(self) -> t.MetaData:
+        res = await self._graphql(q.META, "meta")
+        return t.MetaData.from_dict(res or {})
+
+    # -- authenticated (credential headers) ------------------------------ #
+    async def get_session(
+        self, req: t.SessionQueryRequest | None = None, headers: dict[str, str] | None = None
+    ) -> t.AuthToken:
+        variables = {"data": req.to_dict()} if req is not None else None
+        res = await self._graphql(q.SESSION, "session", variables, headers)
+        return t.AuthToken.from_dict(res or {})
+
+    async def get_profile(self, headers: dict[str, str] | None = None) -> t.User:
+        res = await self._graphql(q.PROFILE, "profile", None, headers)
+        return t.User.from_dict(res or {})
+
+    async def update_profile(
+        self, req: t.UpdateProfileRequest, headers: dict[str, str] | None = None
+    ) -> t.GenericResponse:
+        res = await self._graphql(
+            q.UPDATE_PROFILE, "update_profile", {"data": req.to_dict()}, headers
+        )
+        return t.GenericResponse.from_dict(res or {})
+
+    async def logout(self, headers: dict[str, str] | None = None) -> t.GenericResponse:
+        res = await self._graphql(q.LOGOUT, "logout", None, headers)
+        return t.GenericResponse.from_dict(res or {})
+
+    async def deactivate_account(self, headers: dict[str, str] | None = None) -> t.GenericResponse:
+        res = await self._graphql(q.DEACTIVATE_ACCOUNT, "deactivate_account", None, headers)
+        return t.GenericResponse.from_dict(res or {})
+
+    async def check_permissions(
+        self, req: t.CheckPermissionsRequest, headers: dict[str, str] | None = None
+    ) -> t.CheckPermissionsResponse:
+        res = await self._graphql(
+            q.CHECK_PERMISSIONS, "check_permissions", {"data": req.to_dict()}, headers
+        )
+        return t.CheckPermissionsResponse.from_dict(res or {})
+
+    async def list_permissions(
+        self, req: t.ListPermissionsRequest, headers: dict[str, str] | None = None
+    ) -> t.ListPermissionsResponse:
+        res = await self._graphql(
+            q.LIST_PERMISSIONS, "list_permissions", {"data": req.to_dict()}, headers
+        )
+        return t.ListPermissionsResponse.from_dict(res or {})
+
+    # -- OAuth REST ------------------------------------------------------- #
+    async def get_token(self, req: t.GetTokenRequest) -> t.GetTokenResponse:
+        grant_type = req.grant_type or "authorization_code"
+        if grant_type == "refresh_token" and not (req.refresh_token and req.refresh_token.strip()):
+            raise ValueError("refresh_token is required for refresh_token grant")
+        body: dict[str, Any] = {
+            "client_id": self._config.client_id,
+            "code": req.code or "",
+            "code_verifier": req.code_verifier or "",
+            "grant_type": grant_type,
+            "refresh_token": req.refresh_token or "",
+        }
+        return t.GetTokenResponse.from_dict(await self._oauth("/oauth/token", body))
+
+    async def revoke_token(self, req: t.RevokeTokenRequest) -> t.GenericResponse:
+        if not req.refresh_token or not req.refresh_token.strip():
+            raise ValueError("refresh_token is required")
+        body: dict[str, Any] = {
+            "refresh_token": req.refresh_token,
+            "client_id": self._config.client_id,
+        }
+        return t.GenericResponse.from_dict(await self._oauth("/oauth/revoke", body))
+
+    # -- escape hatch ----------------------------------------------------- #
+    async def graphql_query(
+        self,
+        query: str,
+        variables: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        spec = build_graphql_request(
+            self._config.authorizer_url, query, variables, build_headers(self._config, headers)
+        )
+        res = await self._send(spec)
+        return parse_graphql_data(res.status_code, res.content)