fastapi-openrpc 0.1.3__py3-none-any.whl

fastapi_openrpc/__init__.py

@@ -0,0 +1,104 @@
+"""fastapi-openrpc: FastAPI JSON-RPC 2.0 + OpenRPC 1.0 plugin.
+
+Quick start::
+
+    from fastapi import FastAPI
+    from fastapi_openrpc import OpenRpcRouter, method, RpcContext
+
+    app = FastAPI()
+
+    openrpc_router = OpenRpcRouter(
+        title="My API",
+        version="1.0.0",
+    )
+
+    @method(name="getUser")
+    async def get_user(ctx: RpcContext, user_id: str) -> dict:
+        return {"id": user_id, "name": "Alice"}
+
+    app.include_router(openrpc_router)
+"""
+
+from __future__ import annotations
+
+from fastapi_openrpc.authentication import (
+    AuthenticationMiddleware,
+    HMACAuthentication,
+)
+from fastapi_openrpc.authorization import (
+    AuthorizationPolicy,
+    DefaultAuthorizationPolicy,
+    Require,
+)
+from fastapi_openrpc.constants import (
+    JSONRPC_FORBIDDEN,
+    JSONRPC_INTERNAL_ERROR,
+    JSONRPC_INVALID_PARAMS,
+    JSONRPC_INVALID_REQUEST,
+    JSONRPC_METHOD_NOT_FOUND,
+    JSONRPC_PARSE_ERROR,
+    JSONRPC_REPLAY_DETECTED,
+    OPENRPC_VERSION,
+)
+from fastapi_openrpc.decorator import method
+from fastapi_openrpc.document import build_openrpc_document
+from fastapi_openrpc.errors import (
+    AuthenticationError,
+    Forbidden,
+    InternalError,
+    InvalidParams,
+    InvalidRequest,
+    JsonRpcError,
+    MethodNotFound,
+    ParseError,
+    ReplayDetected,
+    RpcError,
+)
+from fastapi_openrpc.registry import add, clear, get, list_methods
+from fastapi_openrpc.router import OpenRpcRouter
+from fastapi_openrpc.types import MethodMeta, RpcContext
+
+__version__ = "0.1.3"
+
+__all__ = [
+    # Version
+    "__version__",
+    "OPENRPC_VERSION",
+    # Core API
+    "method",
+    "OpenRpcRouter",
+    "build_openrpc_document",
+    # Functional Registration API
+    "add",
+    "get",
+    "list_methods",
+    "clear",
+    # Types
+    "MethodMeta",
+    "RpcContext",
+    "Require",
+    "AuthorizationPolicy",
+    "DefaultAuthorizationPolicy",
+    # Error Classes
+    "JsonRpcError",
+    "ParseError",
+    "InvalidRequest",
+    "MethodNotFound",
+    "InvalidParams",
+    "InternalError",
+    "Forbidden",
+    "ReplayDetected",
+    "RpcError",
+    # Constants
+    "JSONRPC_PARSE_ERROR",
+    "JSONRPC_INVALID_REQUEST",
+    "JSONRPC_METHOD_NOT_FOUND",
+    "JSONRPC_INVALID_PARAMS",
+    "JSONRPC_INTERNAL_ERROR",
+    "JSONRPC_FORBIDDEN",
+    "JSONRPC_REPLAY_DETECTED",
+    # Authentication
+    "AuthenticationMiddleware",
+    "AuthenticationError",
+    "HMACAuthentication",
+]

fastapi_openrpc/authentication.py

@@ -0,0 +1,248 @@
+"""fastapi-openrpc authentication component."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import json
+import logging
+import re
+from typing import TYPE_CHECKING
+
+import redis.asyncio
+from typing_extensions import Protocol, runtime_checkable
+
+from fastapi_openrpc.errors import AuthenticationError, ReplayDetected
+from fastapi_openrpc.types import RpcContext
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class AuthenticationMiddleware(Protocol):
+    """Authentication middleware Protocol.
+
+    Applications can implement custom authentication logic and inject it via
+    OpenRpcRouter(authentication=...).
+    """
+
+    async def authenticate(self, request: Request) -> RpcContext:
+        """Authenticate the requester.
+
+        Raises AuthenticationError on failure, returns RpcContext on success.
+        """
+        ...
+
+
+class HMACAuthentication:
+    """HMAC-SHA256 signature verification authentication.
+
+    Suitable for scenarios where requests are forwarded through a reverse proxy
+    (e.g., winwin-proxy). Supports two header formats:
+
+    - JSON object: ``{"user_id": "...", "roles": ["admin"]}``
+    - JSON array (direct): ``["admin", "developer"]``
+
+    Behavior:
+    - If ``secret_key`` is configured: verifies HMAC-SHA256 signature integrity;
+      raises AuthenticationError if signature is missing or invalid
+    - If ``secret_key=None``: skips signature verification and directly parses
+      header content (suitable for trusted internal network scenarios)
+
+    Optional Nonce replay attack protection:
+    - Requires ``enable_nonce=True`` and ``redis_url`` when enabled
+    - Uses Redis SETEX NX command for atomic deduplication
+    - Degrades according to ``redis_required`` config when Redis is unavailable
+    """
+
+    def __init__(
+        self,
+        roles_header: str = "X-Forwarded-User-Info",
+        signature_header: str = "X-Forwarded-User-Info-Signature",
+        secret_key: str | None = None,
+        enable_nonce: bool = False,
+        redis_url: str | None = None,
+        nonce_ttl: int = 3600,
+        redis_required: bool = True,
+        connect_timeout: float = 2.0,
+        operation_timeout: float = 5.0,
+        cleanup_timeout: float = 2.0,
+    ):
+        """
+        Args:
+            roles_header: Header name for user info, defaults to ``X-Forwarded-User-Info``.
+                Header value can be JSON object (``{"roles": [...]}``) or JSON array.
+            signature_header: Header name for signature, defaults to
+                ``X-Forwarded-User-Info-Signature``.
+            secret_key: HMAC signature key. ``None`` skips signature verification.
+            enable_nonce: Enable Nonce replay attack protection. Defaults to ``False``.
+            redis_url: Redis connection URL (e.g., ``redis://localhost:6379``).
+                Required when ``enable_nonce=True``.
+            nonce_ttl: Nonce TTL in Redis (seconds). Defaults to 3600 (1 hour).
+            redis_required: Whether to reject requests when Redis is unavailable.
+                When True (default) or False: Redis errors always result in
+                request rejection (fail-close). This parameter is kept for
+                behavioral configuration; Redis exceptions reject regardless.
+            connect_timeout: Redis connection timeout (seconds). Defaults to 2.
+            operation_timeout: Redis operation timeout (seconds). Defaults to 5.
+            cleanup_timeout: Redis connection cleanup timeout (seconds). Defaults to 2.
+        """
+        if enable_nonce and not redis_url:
+            raise ValueError(
+                "redis_url is required when enable_nonce=True. "
+                "Example: redis_url='redis://localhost:6379'"
+            )
+        self.roles_header = roles_header
+        self.signature_header = signature_header
+        self.secret_key = secret_key
+        self.enable_nonce = enable_nonce
+        self.redis_url = redis_url
+        self.nonce_ttl = nonce_ttl
+        self.redis_required = redis_required
+        self.connect_timeout = connect_timeout
+        self.operation_timeout = operation_timeout
+        self.cleanup_timeout = cleanup_timeout
+
+    async def authenticate(self, request: Request) -> RpcContext:
+        """Verify HMAC signature and parse role list.
+
+        Args:
+            request: FastAPI/Starlette request object.
+
+        Returns:
+            RpcContext containing the parsed role list.
+
+        Raises:
+            AuthenticationError: Signature verification failed, invalid role format,
+                or Nonce replay.
+        """
+        user_info_raw = request.headers.get(self.roles_header)
+        signature_raw = request.headers.get(self.signature_header)
+
+        # Step 1: Verify signature (if secret_key is configured)
+        if self.secret_key:
+            if not signature_raw:
+                raise AuthenticationError("Missing signature")
+            # user_info_raw may be None; use empty string to avoid .encode() TypeError
+            expected = hmac.new(
+                self.secret_key.encode(),
+                (user_info_raw or "").encode(),
+                hashlib.sha256,
+            ).hexdigest()
+            if not hmac.compare_digest(expected, signature_raw):
+                raise AuthenticationError("Invalid signature")
+
+        # Step 2: Parse roles and user_id (runs even when secret_key=None;
+        # independent of signature verification)
+        user_info_dict: dict | list | None = None
+        if user_info_raw:
+            try:
+                user_info_dict = json.loads(user_info_raw)
+            except json.JSONDecodeError as err:
+                raise AuthenticationError("Invalid user info format") from err
+            # Supports two formats: JSON object ({"roles": [...], "user_id": "..."})
+            # or direct JSON array ([...])
+            if isinstance(user_info_dict, dict):
+                roles = user_info_dict.get("roles", [])
+                user_id = user_info_dict.get("user_id")
+            elif isinstance(user_info_dict, list):
+                roles = user_info_dict
+                user_id = None
+            else:
+                roles = []
+                user_id = None
+        else:
+            roles = []
+            user_id = None
+
+        # Step 3: Nonce verification (if enabled)
+        if self.enable_nonce:
+            nonce: str | None = None
+            if isinstance(user_info_dict, dict):
+                nonce = user_info_dict.get("nonce")
+
+            if not nonce:
+                raise AuthenticationError(
+                    "Missing nonce. When enable_nonce=True, "
+                    "the user_info header must contain a 'nonce' field. "
+                    'Example: {"roles": ["admin"], "nonce": "uuid-here"}'
+                )
+
+            await self._verify_nonce(nonce)
+
+        return RpcContext(roles=roles, user_id=user_id)
+
+    async def _verify_nonce(self, nonce: str) -> None:
+        """Verify whether the Nonce has already been used.
+
+        Uses Redis SET NX EX command for atomic operations:
+        - If nonce does not exist: SET succeeds, returns True, continue processing
+        - If nonce already exists: SET returns None, raises AuthenticationError
+
+        Args:
+            nonce: Client-provided unique identifier.
+                Must be 8-128 hexadecimal characters, may contain dashes.
+
+        Raises:
+            AuthenticationError: Nonce already used (replay attack) or Redis unavailable.
+        """
+        # Nonce validation: length check first (cheap check first)
+        if len(nonce) < 8:
+            raise AuthenticationError("Nonce too short (minimum 8 characters)")
+        if len(nonce) > 128:
+            raise AuthenticationError("Nonce too long (maximum 128 characters)")
+        # Format validation: hexadecimal character set, supports UUID with or without dashes
+        if not re.match(r"^[a-fA-F0-9-]+$", nonce):
+            raise AuthenticationError(
+                "Invalid nonce format (must be hexadecimal with optional dashes)"
+            )
+
+        redis_client = None
+        try:
+            # redis_url already validated in __init__; must exist when enable_nonce=True
+            assert self.redis_url is not None
+            redis_client = redis.asyncio.from_url(
+                self.redis_url,
+                socket_connect_timeout=self.connect_timeout,
+                socket_timeout=self.operation_timeout,
+            )
+            key = f"fastapi_openrpc:nonce:{nonce}"
+            # SET key value EX seconds NX: set only if key does not exist, with expiration
+            result = await redis_client.set(key, "1", ex=self.nonce_ttl, nx=True)
+            if result is None:
+                raise ReplayDetected("Replay detected: nonce has already been used")
+        except redis.asyncio.RedisError as err:
+            logger.error(
+                "Redis error during nonce verification: %s",
+                err,
+            )
+            # fail-close: reject request when Redis is unavailable
+            raise AuthenticationError("Redis unavailable, cannot verify nonce") from err
+        finally:
+            # Always clean up Redis connection, whether success or failure
+            await self._cleanup_redis(redis_client, nonce)
+
+    async def _cleanup_redis(self, redis_client: redis.asyncio.Redis | None, nonce: str) -> None:
+        """Clean up Redis connection with timeout protection."""
+        if redis_client is None:
+            return
+        try:
+            await asyncio.wait_for(redis_client.aclose(), timeout=self.cleanup_timeout)
+        except TimeoutError:
+            logger.warning(
+                "Redis aclose() timed out after %ss for key: fastapi_openrpc:nonce:%s",
+                self.cleanup_timeout,
+                nonce[:8] + "...",
+            )
+
+
+__all__ = [
+    "AuthenticationError",
+    "AuthenticationMiddleware",
+    "HMACAuthentication",
+    "ReplayDetected",
+]

fastapi_openrpc/authorization.py

@@ -0,0 +1,79 @@
+"""Authorization abstraction and default implementation."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from fastapi_openrpc.types import Require
+
+if TYPE_CHECKING:
+    from fastapi_openrpc.types import RpcContext
+
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class AuthorizationPolicy(Protocol):
+    """Authorization policy interface.
+
+    Applications can implement a custom Policy and inject it via
+    OpenRpcRouter(authorization_policy=...).
+    """
+
+    def authorize(
+        self,
+        method_name: str,
+        required_roles: list[str],
+        ctx: RpcContext,
+    ) -> bool:
+        """Determine whether the caller is authorized to invoke the specified method.
+
+        Args:
+            method_name: The name of the RPC method being invoked.
+            required_roles: List of roles required by the method.
+            ctx: Caller context containing roles and require fields.
+
+        Returns:
+            True if authorization is granted, False otherwise.
+        """
+        ...
+
+
+class DefaultAuthorizationPolicy:
+    """Default authorization policy.
+
+    ANY semantics: True if any required_roles match.
+    ALL semantics: True only if all required_roles are present in ctx.roles.
+    Role comparison is case-insensitive (normalized to lowercase).
+    Policy exceptions are treated as authorization denial (fail-close).
+    Returns True when required_roles is empty (no authorization check).
+    """
+
+    def authorize(
+        self,
+        method_name: str,
+        required_roles: list[str],
+        ctx: RpcContext,
+    ) -> bool:
+        # Empty role list -> skip check (backward compatible, R3)
+        if not required_roles:
+            return True
+
+        try:
+            ctx_roles = {r.lower() for r in ctx.roles}
+            needed = {r.lower() for r in required_roles}
+
+            if ctx.require == Require.ALL:
+                return needed <= ctx_roles  # All required_roles present in ctx.roles
+            else:
+                # Require.ANY (default)
+                return bool(ctx_roles & needed)  # Any match == True
+        except Exception:
+            # Policy exception -> fail-close
+            logger.exception("Authorization policy error for %s", method_name)
+            return False
+
+
+__all__ = ["Require", "AuthorizationPolicy", "DefaultAuthorizationPolicy"]

fastapi_openrpc/constants.py

@@ -0,0 +1,43 @@
+"""JSON-RPC 2.0 error code constants.
+
+Standard error codes (JSON-RPC 2.0 spec):
+  -32700 Parse error
+  -32600 Invalid Request
+  -32601 Method not found
+  -32602 Invalid params
+  -32603 Internal error
+
+Library-reserved application error codes (-32000 ~ -32099).
+Custom application error codes should start from -32100.
+"""
+
+from __future__ import annotations
+
+# ----------------------------------------------------------------------
+# JSON-RPC 2.0 Standard Error Codes
+# ----------------------------------------------------------------------
+JSONRPC_PARSE_ERROR = -32700
+JSONRPC_INVALID_REQUEST = -32600
+JSONRPC_METHOD_NOT_FOUND = -32601
+JSONRPC_INVALID_PARAMS = -32602
+JSONRPC_INTERNAL_ERROR = -32603
+
+# ----------------------------------------------------------------------
+# Library-reserved Application Error Codes (-32000 ~ -32099)
+# ----------------------------------------------------------------------
+# 0x7D00 = -32000: Forbidden / insufficient permissions
+JSONRPC_FORBIDDEN = -32000
+# 0x7D01 = -32001: Reserved (formerly used for insufficient permissions)
+# 0x7D02 = -32002: Replay attack detected
+JSONRPC_REPLAY_DETECTED = -32002
+
+# ----------------------------------------------------------------------
+# Security Limit Constants
+# ----------------------------------------------------------------------
+MAX_BATCH_SIZE = 50
+MAX_BODY_BYTES = 1 * 1024 * 1024  # 1 MB
+
+# ----------------------------------------------------------------------
+# OpenRPC Version
+# ----------------------------------------------------------------------
+OPENRPC_VERSION = "1.0.0"