blockauth-sdk 0.5.0__tar.gz

blockauth_sdk-0.5.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Block-Auth (block-auth.io)
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

blockauth_sdk-0.5.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: blockauth-sdk
+Version: 0.5.0
+Summary: BlockAuth Auth SDK (Python) — blockchain-based authentication client.
+Author: Block-Auth.io Team
+License-Expression: ISC
+Project-URL: Homepage, https://block-auth.io
+Project-URL: Repository, https://gitlab.com/blockauthio/blockauth-sdk-python
+Project-URL: Issues, https://gitlab.com/blockauthio/blockauth-sdk-python/-/issues
+Keywords: blockauth,authentication,blockchain,web3,socket.io,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-socketio[client]<6,>=5.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+# BlockAuth SDK (Python)
+
+Cliente headless del servicio de autenticación BlockAuth (Socket.IO v4).
+Puerto de referencia de la capa de protocolo de `@block-auth.io/core`
+(monorepo `blockauth-sdk`, patrón *headless core + thin per-framework adapters*).
+
+## Arquitectura
+
+Este puerto replica la capa `protocol/` del core TypeScript; la reactividad y
+la UI de los bindings (React/Vue/Angular) quedan fuera de alcance.
+
+| Este repo | Upstream (`blockauth-sdk`) |
+| :--- | :--- |
+| `blockauth_sdk/protocol/provider.py` | `packages/core/src/protocol/BlockAuthProvider.ts` |
+| `blockauth_sdk/protocol/ws_client.py` | `packages/core/src/protocol/WsClient.ts` |
+| `blockauth_sdk/protocol/rpc_client.py` | `packages/core/src/protocol/RpcClient.ts` |
+| `blockauth_sdk/protocol/roles.py` | `packages/core/src/protocol/roles.ts` |
+| `blockauth_sdk/protocol/transport.py` | — (abstracción propia del puerto; upstream usa socket.io directo) |
+| `blockauth_sdk/api_bridge.py` | `packages/core/src/utils/apiBridge.ts` (solo la emisión del browser token) |
+| `blockauth_sdk/crypto.py`, `blockauth_sdk/errors.py` | — (infra propia del puerto) |
+
+La API pública se re-exporta desde la raíz del paquete (`from blockauth_sdk import
+BlockAuthProvider`), igual que hace el `index.ts` del core.
+
+## Instalación
+
+```bash
+pip install blockauth-sdk
+```
+
+## Uso
+
+Un backend se autentica con su `apiKey` y su `apiSecret`. El `apiSecret` solo
+vive en el backend.
+
+```python
+from blockauth_sdk import BlockAuthProvider
+
+provider = BlockAuthProvider(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")
+provider.connect()
+
+result = provider.signin()
+if result["success"]:
+    profile = provider.user("0xUserAddress")
+    print(provider.role_names)
+
+provider.disconnect()
+```
+
+No autentiques un backend con un browser token: el ws-server lo rechaza (exige
+un `Origin` de confianza y su scope no da acceso a `user`, `users`, `roles` ni
+`logs`).
+
+### Login por redirección
+
+Para que tus usuarios inicien sesión con BlockAuth, tu backend los manda al
+login alojado y recibe de vuelta un código de un solo uso, que canjea por la
+dirección y los roles del usuario. La dirección la da el ws-server, nunca el
+navegador.
+
+```python
+import json
+import secrets
+import urllib.error
+import urllib.request
+
+from blockauth_sdk.api_bridge import build_ws_server_api_url
+from blockauth_sdk.crypto import sha256_hex
+
+
+def post(path, body):
+    request = urllib.request.Request(
+        build_ws_server_api_url(path),
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(request) as response:
+            data = json.load(response)
+    except urllib.error.HTTPError as err:  # los errores llegan como 400 con el mismo JSON
+        data = json.load(err)
+    if not data.get("success"):
+        raise RuntimeError(data.get("message"))
+    return data["message"]
+
+
+credentials = {"apiKey": "YOUR_API_KEY", "apiSecret": sha256_hex("YOUR_API_SECRET")}
+redirect_uri = "https://tuapp.com/callback"
+
+# 1. Pide el enlace de login y redirige al usuario a él.
+state = secrets.token_hex(16)  # guárdalo en la sesión
+link = post("/auth/authorize", {**credentials, "redirectUri": redirect_uri, "state": state})["url"]
+
+# 2. El usuario vuelve a redirect_uri?code=...&state=... Comprueba que el state es el de la sesión.
+
+# 3. Canjea el código (válido 60 s, un solo uso).
+user = post("/auth/token", {**credentials, "code": code, "redirectUri": redirect_uri})
+address = user["address"]  # también: roles, signedExpiredAt
+```
+
+- El `redirect_uri` tiene que ser `https` en el dominio (o el dominio de
+  desarrollo) de la app; `http` solo en `localhost`.
+- Para cerrar la sesión del usuario en tu app: `post("/auth/signout",
+  {**credentials, "address": address})`.
+
+### Browser token para tu frontend
+
+Si tu frontend usa `@block-auth.io/core`, el backend le emite un browser token
+para que el `apiSecret` no salga nunca del backend:
+
+```python
+provider = BlockAuthProvider(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")
+browser_token = provider.create_browser_token()
+```
+
+El frontend lo usa como `browserToken` en `@block-auth.io/core`.
+
+## API
+
+`BlockAuthProvider`: `connect`, `disconnect`, `is_connected`, `signin`, `create_browser_token`, `refresh`,
+`is_address_signed`, `app`, `user`, `users`, `roles`, `logs`, `kyc_issuer`,
+helpers de roles (`has_role`, `has_role_by_slug`, `has_any_role`,
+`has_any_role_by_slug`) y getters (`current_user`, `role_names`, `ui_config`, …).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Smoke test contra un servidor real
+
+Los tests usan un transporte simulado. Para probar el SDK contra el ws-server
+de PRE (transporte real, login por redirección y canje del código), usa la app
+de prueba de [`examples/test_app/`](https://gitlab.com/blockauthio/blockauth-sdk-python/-/tree/main/examples/test_app).

blockauth_sdk-0.5.0/README.md

@@ -0,0 +1,136 @@
+# BlockAuth SDK (Python)
+
+Cliente headless del servicio de autenticación BlockAuth (Socket.IO v4).
+Puerto de referencia de la capa de protocolo de `@block-auth.io/core`
+(monorepo `blockauth-sdk`, patrón *headless core + thin per-framework adapters*).
+
+## Arquitectura
+
+Este puerto replica la capa `protocol/` del core TypeScript; la reactividad y
+la UI de los bindings (React/Vue/Angular) quedan fuera de alcance.
+
+| Este repo | Upstream (`blockauth-sdk`) |
+| :--- | :--- |
+| `blockauth_sdk/protocol/provider.py` | `packages/core/src/protocol/BlockAuthProvider.ts` |
+| `blockauth_sdk/protocol/ws_client.py` | `packages/core/src/protocol/WsClient.ts` |
+| `blockauth_sdk/protocol/rpc_client.py` | `packages/core/src/protocol/RpcClient.ts` |
+| `blockauth_sdk/protocol/roles.py` | `packages/core/src/protocol/roles.ts` |
+| `blockauth_sdk/protocol/transport.py` | — (abstracción propia del puerto; upstream usa socket.io directo) |
+| `blockauth_sdk/api_bridge.py` | `packages/core/src/utils/apiBridge.ts` (solo la emisión del browser token) |
+| `blockauth_sdk/crypto.py`, `blockauth_sdk/errors.py` | — (infra propia del puerto) |
+
+La API pública se re-exporta desde la raíz del paquete (`from blockauth_sdk import
+BlockAuthProvider`), igual que hace el `index.ts` del core.
+
+## Instalación
+
+```bash
+pip install blockauth-sdk
+```
+
+## Uso
+
+Un backend se autentica con su `apiKey` y su `apiSecret`. El `apiSecret` solo
+vive en el backend.
+
+```python
+from blockauth_sdk import BlockAuthProvider
+
+provider = BlockAuthProvider(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")
+provider.connect()
+
+result = provider.signin()
+if result["success"]:
+    profile = provider.user("0xUserAddress")
+    print(provider.role_names)
+
+provider.disconnect()
+```
+
+No autentiques un backend con un browser token: el ws-server lo rechaza (exige
+un `Origin` de confianza y su scope no da acceso a `user`, `users`, `roles` ni
+`logs`).
+
+### Login por redirección
+
+Para que tus usuarios inicien sesión con BlockAuth, tu backend los manda al
+login alojado y recibe de vuelta un código de un solo uso, que canjea por la
+dirección y los roles del usuario. La dirección la da el ws-server, nunca el
+navegador.
+
+```python
+import json
+import secrets
+import urllib.error
+import urllib.request
+
+from blockauth_sdk.api_bridge import build_ws_server_api_url
+from blockauth_sdk.crypto import sha256_hex
+
+
+def post(path, body):
+    request = urllib.request.Request(
+        build_ws_server_api_url(path),
+        data=json.dumps(body).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(request) as response:
+            data = json.load(response)
+    except urllib.error.HTTPError as err:  # los errores llegan como 400 con el mismo JSON
+        data = json.load(err)
+    if not data.get("success"):
+        raise RuntimeError(data.get("message"))
+    return data["message"]
+
+
+credentials = {"apiKey": "YOUR_API_KEY", "apiSecret": sha256_hex("YOUR_API_SECRET")}
+redirect_uri = "https://tuapp.com/callback"
+
+# 1. Pide el enlace de login y redirige al usuario a él.
+state = secrets.token_hex(16)  # guárdalo en la sesión
+link = post("/auth/authorize", {**credentials, "redirectUri": redirect_uri, "state": state})["url"]
+
+# 2. El usuario vuelve a redirect_uri?code=...&state=... Comprueba que el state es el de la sesión.
+
+# 3. Canjea el código (válido 60 s, un solo uso).
+user = post("/auth/token", {**credentials, "code": code, "redirectUri": redirect_uri})
+address = user["address"]  # también: roles, signedExpiredAt
+```
+
+- El `redirect_uri` tiene que ser `https` en el dominio (o el dominio de
+  desarrollo) de la app; `http` solo en `localhost`.
+- Para cerrar la sesión del usuario en tu app: `post("/auth/signout",
+  {**credentials, "address": address})`.
+
+### Browser token para tu frontend
+
+Si tu frontend usa `@block-auth.io/core`, el backend le emite un browser token
+para que el `apiSecret` no salga nunca del backend:
+
+```python
+provider = BlockAuthProvider(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")
+browser_token = provider.create_browser_token()
+```
+
+El frontend lo usa como `browserToken` en `@block-auth.io/core`.
+
+## API
+
+`BlockAuthProvider`: `connect`, `disconnect`, `is_connected`, `signin`, `create_browser_token`, `refresh`,
+`is_address_signed`, `app`, `user`, `users`, `roles`, `logs`, `kyc_issuer`,
+helpers de roles (`has_role`, `has_role_by_slug`, `has_any_role`,
+`has_any_role_by_slug`) y getters (`current_user`, `role_names`, `ui_config`, …).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Smoke test contra un servidor real
+
+Los tests usan un transporte simulado. Para probar el SDK contra el ws-server
+de PRE (transporte real, login por redirección y canje del código), usa la app
+de prueba de [`examples/test_app/`](https://gitlab.com/blockauthio/blockauth-sdk-python/-/tree/main/examples/test_app).

blockauth_sdk-0.5.0/blockauth_sdk/__init__.py

@@ -0,0 +1,27 @@
+from .errors import BlockAuthError, NotConnectedError
+from .protocol import BlockAuthProvider, RpcClient, WsClient
+from .protocol.roles import (
+    get_user_role_names,
+    get_user_role_slugs,
+    get_user_roles,
+    has_any_role,
+    has_any_role_by_slug,
+    has_role,
+    has_role_by_slug,
+)
+
+__all__ = [
+    "BlockAuthProvider",
+    "RpcClient",
+    "WsClient",
+    "BlockAuthError",
+    "NotConnectedError",
+    "get_user_roles",
+    "get_user_role_names",
+    "get_user_role_slugs",
+    "has_role",
+    "has_role_by_slug",
+    "has_any_role",
+    "has_any_role_by_slug",
+]
+__version__ = "0.5.0"

blockauth_sdk-0.5.0/blockauth_sdk/api_bridge.py

@@ -0,0 +1,45 @@
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .errors import BlockAuthError
+
+DEFAULT_WS_URL = "wss://wss.block-auth.io"
+
+
+def build_ws_server_api_url(path: str, ws_url: str = "") -> str:
+    parsed = urllib.parse.urlsplit(ws_url or DEFAULT_WS_URL)
+    scheme = "https" if parsed.scheme == "wss" else "http"
+    return urllib.parse.urlunsplit((scheme, parsed.netloc, "/api" + path, "", ""))
+
+
+def create_browser_token(api_key: str, api_secret_hash: str, ws_url: str = "", timeout: float = 10.0) -> str:
+    body = json.dumps({"apiKey": api_key, "apiSecret": api_secret_hash}).encode("utf-8")
+    request = urllib.request.Request(
+        build_ws_server_api_url("/browser-token", ws_url),
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload = _read_json(response)
+    except urllib.error.HTTPError as err:
+        payload = _read_json(err)
+    except (urllib.error.URLError, OSError) as err:
+        raise BlockAuthError(f"Browser token request failed: {err}") from err
+
+    message = payload.get("message")
+    if not payload.get("success") or not isinstance(message, dict) or not message.get("accessToken"):
+        raise BlockAuthError(str(message or "Failed to create browser token"))
+    return message["accessToken"]
+
+
+def _read_json(response: Any) -> dict:
+    try:
+        data = json.loads(response.read().decode("utf-8"))
+    except (ValueError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}

blockauth_sdk-0.5.0/blockauth_sdk/crypto.py

@@ -0,0 +1,9 @@
+import hashlib
+
+
+def sha256_hex(text: str) -> str:
+    """SHA256 del texto (UTF-8) como hex en minúsculas.
+
+    Equivalente a crypto-js `SHA256(text).toString()` usado por el SDK TS.
+    """
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()

blockauth_sdk-0.5.0/blockauth_sdk/errors.py

@@ -0,0 +1,9 @@
+class BlockAuthError(Exception):
+    """Base error for the BlockAuth SDK."""
+
+
+class NotConnectedError(BlockAuthError):
+    """Raised when an operation needs an active WebSocket connection."""
+
+    def __init__(self, message: str = "Not connected") -> None:
+        super().__init__(message)

blockauth_sdk-0.5.0/blockauth_sdk/protocol/__init__.py

@@ -0,0 +1,29 @@
+# Espejo de packages/core/src/protocol del SDK TypeScript (@block-auth.io/core).
+from .provider import BlockAuthProvider
+from .roles import (
+    get_user_role_names,
+    get_user_role_slugs,
+    get_user_roles,
+    has_any_role,
+    has_any_role_by_slug,
+    has_role,
+    has_role_by_slug,
+)
+from .rpc_client import RpcClient
+from .transport import SocketIOTransport, Transport
+from .ws_client import WsClient
+
+__all__ = [
+    "BlockAuthProvider",
+    "RpcClient",
+    "WsClient",
+    "Transport",
+    "SocketIOTransport",
+    "get_user_roles",
+    "get_user_role_names",
+    "get_user_role_slugs",
+    "has_role",
+    "has_role_by_slug",
+    "has_any_role",
+    "has_any_role_by_slug",
+]

blockauth_sdk-0.5.0/blockauth_sdk/protocol/provider.py

@@ -0,0 +1,195 @@
+from typing import Any, Optional
+
+from ..api_bridge import create_browser_token
+from ..crypto import sha256_hex
+from ..errors import BlockAuthError, NotConnectedError
+from .rpc_client import RpcClient
+from .ws_client import WsClient
+from .roles import (
+    get_user_role_names,
+    get_user_role_slugs,
+    has_any_role,
+    has_any_role_by_slug,
+    has_role,
+    has_role_by_slug,
+)
+
+
+class BlockAuthProvider:
+    def __init__(
+        self,
+        api_key: str = "",
+        api_secret: str = "",
+        ws_url: str = "wss://wss.block-auth.io",
+        browser_token: str = "",
+        transport: Optional[Any] = None,
+    ) -> None:
+        self._rpc = RpcClient()
+        self._wsc = WsClient(ws_url, True, transport=transport)
+        self._api_key = api_key
+        self._api_secret = api_secret
+        self._browser_token = browser_token or ""
+        self._ws_url = ws_url
+
+    # --- browser token ---
+    @property
+    def browser_token(self) -> str:
+        return self._browser_token
+
+    @browser_token.setter
+    def browser_token(self, token: str) -> None:
+        self._browser_token = token or ""
+
+    def create_browser_token(self) -> str:
+        if not self._api_secret:
+            raise BlockAuthError("API secret required to create a browser token")
+        return create_browser_token(self._api_key, sha256_hex(self._api_secret), self._ws_url)
+
+    # --- conexión ---
+    def connect(self, wait_ms: int = 1000, url: str = "", retries: int = 3) -> None:
+        self._wsc.connect(url, wait_ms, retries)
+
+    def disconnect(self) -> None:
+        self._wsc.close()
+
+    def is_connected(self) -> bool:
+        return self._wsc.is_connected()
+
+    def _require_connection(self) -> None:
+        if not self.is_connected():
+            raise NotConnectedError()
+
+    # --- métodos del protocolo ---
+    def signin(self) -> Any:
+        self._require_connection()
+        credentials = {"apiKey": self._api_key}
+        if self._browser_token:
+            credentials["browserToken"] = self._browser_token
+        elif self._api_secret:
+            credentials["apiSecret"] = sha256_hex(self._api_secret)
+        data = self._wsc.request("sdk:signin", "sdk:signin", credentials)
+        return {"success": data.get("success"), "message": data.get("message")}
+
+    def refresh(self, refresh_token: Optional[str] = None) -> Any:
+        self._require_connection()
+        token = refresh_token or self._wsc.refresh_token
+        if not token:
+            raise BlockAuthError("No refresh token provided")
+        data = self._wsc.request("sdk:refresh", "sdk:refresh", {"refreshToken": token})
+        if not data.get("success"):
+            raise BlockAuthError(str(data.get("message")))
+        return data.get("message")
+
+    def is_address_signed(self, address: str, token: Optional[str] = None) -> Any:
+        self._require_connection()
+        _token = token or self._wsc.access_token
+        data = self._wsc.request("sdk:sign", "sdk:sign", {"token": _token, "address": address})
+        return {"success": data.get("success"), "message": data.get("message")}
+
+    def app(self, token: Optional[str] = None) -> Any:
+        self._require_connection()
+        _token = token or self._wsc.access_token
+        data = self._wsc.request("sdk:app", "sdk:app", {"token": _token})
+        if not data.get("success"):
+            raise BlockAuthError(str(data.get("message")))
+        return data.get("message")
+
+    def user(self, address: str, token: Optional[str] = None) -> Any:
+        self._require_connection()
+        _token = token or self._wsc.access_token
+        data = self._wsc.request("sdk:user", "sdk:user", {"token": _token, "address": address})
+        return {"success": data.get("success"), "message": data.get("message")}
+
+    def users(self, token: Optional[str] = None, data: Optional[dict] = None) -> Any:
+        self._require_connection()
+        _token = token or self._wsc.access_token
+        payload = {"token": _token, **(data or {})}
+        resp = self._wsc.request("sdk:users", "sdk:users", payload)
+        if not resp.get("success"):
+            raise BlockAuthError(str(resp.get("message")))
+        return resp.get("message")
+
+    def roles(self, token: Optional[str] = None, data: Optional[dict] = None) -> Any:
+        self._require_connection()
+        _token = token or self._wsc.access_token
+        payload = {"token": _token, **(data or {})}
+        resp = self._wsc.request("sdk:roles", "sdk:roles", payload)
+        if not resp.get("success"):
+            raise BlockAuthError(str(resp.get("message")))
+        return resp.get("message")
+
+    def logs(self, token: Optional[str] = None, data: Optional[dict] = None) -> Any:
+        self._require_connection()
+        _token = token or self._wsc.access_token
+        payload = {"token": _token, **(data or {})}
+        resp = self._wsc.request("sdk:logs", "sdk:logs", payload)
+        if not resp.get("success"):
+            raise BlockAuthError(str(resp.get("message")))
+        return resp.get("message")
+
+    def kyc_issuer(self, address: str, data: Optional[dict] = None, token: Optional[str] = None) -> Any:
+        self._require_connection()
+        _token = token or self._wsc.access_token
+        payload = {"token": _token, "address": address, "details": {**(data or {})}}
+        resp = self._wsc.request("sdk:kyc:issuer", "sdk:kyc:issuer", payload)
+        if not resp.get("success"):
+            raise BlockAuthError(str(resp.get("message")))
+        return resp.get("message")
+
+    # --- getters ---
+    @property
+    def rpc(self) -> RpcClient:
+        return self._rpc
+
+    @property
+    def wsc(self) -> WsClient:
+        return self._wsc
+
+    @property
+    def socket(self) -> Any:
+        return self._wsc.ws
+
+    @property
+    def ui_config(self) -> dict:
+        return self._wsc.ui_config
+
+    @property
+    def app_users(self) -> list:
+        return self._wsc.users
+
+    @property
+    def app_roles(self) -> list:
+        return self._wsc.roles
+
+    @property
+    def app_logs(self) -> list:
+        return self._wsc.logs
+
+    @property
+    def app_kyc_issuer_by_address(self) -> dict:
+        return self._wsc.kyc_issuer_by_address
+
+    @property
+    def current_user(self) -> dict:
+        return self._wsc.user
+
+    @property
+    def role_names(self) -> list:
+        return get_user_role_names(self.current_user)
+
+    @property
+    def role_slugs(self) -> list:
+        return get_user_role_slugs(self.current_user)
+
+    # --- helpers de roles ---
+    def has_role(self, role_name: str) -> bool:
+        return has_role(self.current_user, role_name)
+
+    def has_role_by_slug(self, role_slug: str) -> bool:
+        return has_role_by_slug(self.current_user, role_slug)
+
+    def has_any_role(self, role_names: list) -> bool:
+        return has_any_role(self.current_user, role_names)
+
+    def has_any_role_by_slug(self, role_slugs: list) -> bool:
+        return has_any_role_by_slug(self.current_user, role_slugs)

blockauth_sdk-0.5.0/blockauth_sdk/protocol/roles.py

@@ -0,0 +1,55 @@
+from typing import Any, Optional
+
+
+def _normalize(value: Any) -> str:
+    return str(value if value is not None else "").strip().lower()
+
+
+def _is_valid_role(role: Any) -> bool:
+    return (
+        isinstance(role, dict)
+        and isinstance(role.get("name"), str)
+        and role["name"].strip() != ""
+        and isinstance(role.get("slug"), str)
+        and role["slug"].strip() != ""
+    )
+
+
+def get_user_roles(user: Optional[dict]) -> list:
+    if not user or not isinstance(user.get("roles"), list):
+        return []
+    return [role for role in user["roles"] if _is_valid_role(role)]
+
+
+def get_user_role_names(user: Optional[dict]) -> list:
+    return [role["name"] for role in get_user_roles(user)]
+
+
+def get_user_role_slugs(user: Optional[dict]) -> list:
+    return [role["slug"] for role in get_user_roles(user) if role["slug"]]
+
+
+def has_role(user: Optional[dict], role_name: str) -> bool:
+    target = _normalize(role_name)
+    if not target:
+        return False
+    return any(_normalize(name) == target for name in get_user_role_names(user))
+
+
+def has_role_by_slug(user: Optional[dict], role_slug: str) -> bool:
+    target = _normalize(role_slug)
+    if not target:
+        return False
+    return any(_normalize(slug) == target for slug in get_user_role_slugs(user))
+
+
+def has_any_role(user: Optional[dict], role_names: list) -> bool:
+    if not isinstance(role_names, list) or len(role_names) == 0:
+        return False
+    return any(has_role(user, name) for name in role_names)
+
+
+def has_any_role_by_slug(user: Optional[dict], role_slugs: list) -> bool:
+    if not isinstance(role_slugs, list) or len(role_slugs) == 0:
+        return False
+    return any(has_role_by_slug(user, slug) for slug in role_slugs)