blade-auth-client 0.2.0__tar.gz

blade_auth_client-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+*.db
+.env
+app.conf
+conf/app.conf
+credentials.env
+data/
+
+# Python build artifacts (sdk/python)
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/

blade_auth_client-0.2.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: blade-auth-client
+Version: 0.2.0
+Summary: Shared Casdoor authentication client for Blade ecosystem services.
+Project-URL: Homepage, https://pypi.org/project/blade-auth-client/
+Author-email: yangliu35 <so.2liu@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: httpx
+Requires-Dist: pydantic-settings
+Requires-Dist: pydantic>=2
+Requires-Dist: pyjwt[crypto]
+Requires-Dist: sqlalchemy
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi; extra == 'fastapi'
+Requires-Dist: starlette; extra == 'fastapi'
+Provides-Extra: socketio
+Requires-Dist: python-socketio; extra == 'socketio'
+Description-Content-Type: text/markdown
+
+# blade-auth-client
+
+`blade-auth-client` 是 Blade 生态的共享 Casdoor 认证客户端包。它抽离了统一的 token 校验、FastAPI 装配和 Socket.IO 握手接口，供各个服务复用。
+
+## 安装
+
+```bash
+pip install blade-auth-client[fastapi,socketio]
+```
+
+## Casdoor 配置要求
+
+Casdoor 的 application、scope 和 redirect URI 约束见 [docs/casdoor-setup.md](docs/casdoor-setup.md)。
+
+## 快速上手
+
+```python
+from fastapi import FastAPI
+
+from blade_auth_client import (
+    AuthConfig,
+    OidcClient,
+    TokenVerifier,
+    create_auth_router,
+    make_current_user_dep,
+)
+
+app = FastAPI()
+config = AuthConfig()
+oidc_client = OidcClient(config)
+verifier = TokenVerifier(config)
+current_user = make_current_user_dep(config, verifier=verifier, provisioner=...)
+
+app.include_router(
+    create_auth_router(config, verifier=verifier, provisioner=..., oidc_client=oidc_client)
+)
+```
+
+## 版本策略
+
+`0.0.x` 版本仅用于占位发布和联调验证，不承诺可用性。`0.2.0` 起采用仅校验 `iss` + 签名 + `exp` 的简化策略。

blade_auth_client-0.2.0/README.md

@@ -0,0 +1,41 @@
+# blade-auth-client
+
+`blade-auth-client` 是 Blade 生态的共享 Casdoor 认证客户端包。它抽离了统一的 token 校验、FastAPI 装配和 Socket.IO 握手接口，供各个服务复用。
+
+## 安装
+
+```bash
+pip install blade-auth-client[fastapi,socketio]
+```
+
+## Casdoor 配置要求
+
+Casdoor 的 application、scope 和 redirect URI 约束见 [docs/casdoor-setup.md](docs/casdoor-setup.md)。
+
+## 快速上手
+
+```python
+from fastapi import FastAPI
+
+from blade_auth_client import (
+    AuthConfig,
+    OidcClient,
+    TokenVerifier,
+    create_auth_router,
+    make_current_user_dep,
+)
+
+app = FastAPI()
+config = AuthConfig()
+oidc_client = OidcClient(config)
+verifier = TokenVerifier(config)
+current_user = make_current_user_dep(config, verifier=verifier, provisioner=...)
+
+app.include_router(
+    create_auth_router(config, verifier=verifier, provisioner=..., oidc_client=oidc_client)
+)
+```
+
+## 版本策略
+
+`0.0.x` 版本仅用于占位发布和联调验证，不承诺可用性。`0.2.0` 起采用仅校验 `iss` + 签名 + `exp` 的简化策略。

blade_auth_client-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "blade-auth-client"
+version = "0.2.0"
+description = "Shared Casdoor authentication client for Blade ecosystem services."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+  { name = "yangliu35", email = "so.2liu@gmail.com" },
+]
+dependencies = [
+  "httpx",
+  "pyjwt[crypto]",
+  "pydantic>=2",
+  "pydantic-settings",
+  "sqlalchemy",
+]
+
+[project.optional-dependencies]
+fastapi = [
+  "fastapi",
+  "starlette",
+]
+socketio = [
+  "python-socketio",
+]
+dev = [
+  "pytest",
+  "pytest-asyncio",
+  "respx",
+  "ruff",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/blade-auth-client/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/blade_auth_client"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"

blade_auth_client-0.2.0/src/blade_auth_client/__init__.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AuthConfig",
+    "AuthError",
+    "AuthMiddleware",
+    "CasdoorClaims",
+    "CasdoorError",
+    "ExpiredTokenError",
+    "InvalidAudienceError",
+    "InvalidTokenError",
+    "JwksCache",
+    "JwksUnavailableError",
+    "LazyProvisioner",
+    "OidcClient",
+    "SqlAlchemyProvisioner",
+    "TokenVerifier",
+    "UserProvisionError",
+    "authenticate_request",
+    "build_callback_url",
+    "clear_session_cookie",
+    "create_auth_router",
+    "make_auth_middleware",
+    "make_current_user_dep",
+    "make_require_auth_dep",
+    "read_session_token",
+    "socketio_auth",
+    "verify_token",
+    "write_session_cookie",
+]
+
+_EXPORTS = {
+    "AuthConfig": ("blade_auth_client.config", "AuthConfig"),
+    "AuthError": ("blade_auth_client.errors", "AuthError"),
+    "AuthMiddleware": ("blade_auth_client.socketio.middleware", "AuthMiddleware"),
+    "CasdoorClaims": ("blade_auth_client.users.provisioner", "CasdoorClaims"),
+    "CasdoorError": ("blade_auth_client.errors", "CasdoorError"),
+    "ExpiredTokenError": ("blade_auth_client.errors", "ExpiredTokenError"),
+    "InvalidAudienceError": ("blade_auth_client.errors", "InvalidAudienceError"),
+    "InvalidTokenError": ("blade_auth_client.errors", "InvalidTokenError"),
+    "JwksCache": ("blade_auth_client.verifier.jwks_cache", "JwksCache"),
+    "JwksUnavailableError": ("blade_auth_client.errors", "JwksUnavailableError"),
+    "LazyProvisioner": ("blade_auth_client.users.provisioner", "LazyProvisioner"),
+    "OidcClient": ("blade_auth_client.casdoor.client", "OidcClient"),
+    "SqlAlchemyProvisioner": ("blade_auth_client.users.sqlalchemy_provisioner", "SqlAlchemyProvisioner"),
+    "TokenVerifier": ("blade_auth_client.verifier.token_verifier", "TokenVerifier"),
+    "UserProvisionError": ("blade_auth_client.errors", "UserProvisionError"),
+    "authenticate_request": ("blade_auth_client.fastapi.deps", "authenticate_request"),
+    "build_callback_url": ("blade_auth_client.fastapi.urls", "build_callback_url"),
+    "clear_session_cookie": ("blade_auth_client.cookie.policy", "clear_session_cookie"),
+    "create_auth_router": ("blade_auth_client.fastapi.router", "create_auth_router"),
+    "make_auth_middleware": ("blade_auth_client.socketio.middleware", "make_auth_middleware"),
+    "make_current_user_dep": ("blade_auth_client.fastapi.deps", "make_current_user_dep"),
+    "make_require_auth_dep": ("blade_auth_client.fastapi.deps", "make_require_auth_dep"),
+    "read_session_token": ("blade_auth_client.cookie.policy", "read_session_token"),
+    "socketio_auth": ("blade_auth_client.socketio.middleware", "socketio_auth"),
+    "verify_token": ("blade_auth_client.verifier.token_verifier", "verify_token"),
+    "write_session_cookie": ("blade_auth_client.cookie.policy", "write_session_cookie"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attribute_name = _EXPORTS[name]
+    module = import_module(module_name)
+    return getattr(module, attribute_name)

blade_auth_client-0.2.0/src/blade_auth_client/casdoor/__init__.py

@@ -0,0 +1,3 @@
+from .client import OidcClient
+
+__all__ = ["OidcClient"]

blade_auth_client-0.2.0/src/blade_auth_client/casdoor/client.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from blade_auth_client.config import AuthConfig
+from blade_auth_client.errors import CasdoorError
+
+TOKEN_PATH = "/api/login/oauth/access_token"
+
+
+class OidcClient:
+    def __init__(
+        self,
+        config: AuthConfig,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._config = config
+        self._http_client = http_client or httpx.AsyncClient(timeout=10.0)
+
+    async def exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+    ) -> str:
+        response = await self._http_client.post(
+            f"{self._config.internal_casdoor_endpoint.rstrip('/')}{TOKEN_PATH}",
+            data={
+                "grant_type": "authorization_code",
+                "client_id": self._config.casdoor_client_id,
+                "client_secret": self._config.casdoor_client_secret,
+                "code": code,
+                "redirect_uri": redirect_uri,
+            },
+        )
+        payload = self._parse_casdoor_response(response)
+        access_token = payload.get("access_token")
+        if not isinstance(access_token, str) or not access_token:
+            raise CasdoorError("Casdoor token response missing access_token")
+        return access_token
+
+    def _parse_casdoor_response(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise CasdoorError("Casdoor returned a non-JSON response") from exc
+
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise CasdoorError(self._extract_error_message(payload)) from exc
+
+        if not isinstance(payload, dict):
+            raise CasdoorError("Casdoor returned an unexpected response payload")
+
+        status = payload.get("status")
+        error = payload.get("error")
+        if status == "error" or error:
+            raise CasdoorError(self._extract_error_message(payload))
+
+        data = payload.get("data")
+        if isinstance(data, dict):
+            merged = dict(data)
+            for key, value in payload.items():
+                if key != "data" and key not in merged:
+                    merged[key] = value
+            return merged
+
+        return payload
+
+    @staticmethod
+    def _extract_error_message(payload: Any) -> str:
+        if not isinstance(payload, dict):
+            return "Casdoor returned an error response"
+        for key in ("error_description", "msg", "message", "error"):
+            value = payload.get(key)
+            if isinstance(value, str) and value:
+                return value
+        return "Casdoor returned an error response"

blade_auth_client-0.2.0/src/blade_auth_client/config.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AuthConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="", extra="ignore")
+
+    casdoor_endpoint: str | None = Field(default=None)
+    casdoor_client_id: str = Field(...)
+    casdoor_client_secret: str = Field(...)
+    internal_casdoor_endpoint: str = Field(default="http://127.0.0.1:19000")
+    public_casdoor_port: int = Field(default=19000)
+    cookie_name: str = Field(default="blade_token")
+    cookie_secure: bool = Field(default=False)
+    cookie_same_site: Literal["lax", "strict", "none"] = Field(default="lax")
+    jwks_cache_ttl_seconds: int = Field(default=300)
+    allowed_redirect_origins: list[str] = Field(default_factory=list)
+    callback_base_url: str | None = Field(default=None)

blade_auth_client-0.2.0/src/blade_auth_client/cookie/__init__.py

@@ -0,0 +1,3 @@
+from .policy import clear_session_cookie, read_session_token, write_session_cookie
+
+__all__ = ["clear_session_cookie", "read_session_token", "write_session_cookie"]

blade_auth_client-0.2.0/src/blade_auth_client/cookie/policy.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+from blade_auth_client.config import AuthConfig
+
+DEFAULT_COOKIE_NAME = "blade_token"
+COOKIE_PATH = "/"
+COOKIE_HTTP_ONLY = True
+
+
+def write_session_cookie(response: Any, token: str, config: AuthConfig) -> None:
+    response.set_cookie(
+        key=config.cookie_name,
+        value=token,
+        httponly=COOKIE_HTTP_ONLY,
+        path=COOKIE_PATH,
+        samesite=config.cookie_same_site,
+        secure=config.cookie_secure,
+    )
+
+
+def clear_session_cookie(response: Any, config: AuthConfig) -> None:
+    response.delete_cookie(
+        key=config.cookie_name,
+        httponly=COOKIE_HTTP_ONLY,
+        path=COOKIE_PATH,
+        samesite=config.cookie_same_site,
+        secure=config.cookie_secure,
+    )
+
+
+def read_session_token(request: Any, config: AuthConfig | None = None) -> str | None:
+    cookie_name = config.cookie_name if config is not None else DEFAULT_COOKIE_NAME
+    cookies = getattr(request, "cookies", None) or {}
+    return cookies.get(cookie_name)

blade_auth_client-0.2.0/src/blade_auth_client/errors.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+
+class AuthError(Exception):
+    """Base exception for blade-auth-client."""
+
+
+class InvalidTokenError(AuthError):
+    """Raised when a token cannot be trusted."""
+
+
+class InvalidAudienceError(InvalidTokenError):
+    """Retained for backward compatibility; no longer raised."""
+
+
+class ExpiredTokenError(InvalidTokenError):
+    """Raised when a token is expired."""
+
+
+class JwksUnavailableError(AuthError):
+    """Raised when JWKS cannot be fetched and no cache is available."""
+
+
+class CasdoorError(AuthError):
+    """Raised when Casdoor returns an error response."""
+
+
+class UserProvisionError(AuthError):
+    """Raised when local user provisioning fails."""

blade_auth_client-0.2.0/src/blade_auth_client/fastapi/__init__.py

@@ -0,0 +1,23 @@
+from .deps import authenticate_request, make_current_user_dep, make_require_auth_dep
+from .router import (
+    CALLBACK_PATH,
+    LOGIN_PATH,
+    LOGOUT_PATH,
+    ME_PATH,
+    PROVIDERS_PATH,
+    create_auth_router,
+)
+from .urls import build_callback_url
+
+__all__ = [
+    "CALLBACK_PATH",
+    "LOGIN_PATH",
+    "LOGOUT_PATH",
+    "ME_PATH",
+    "PROVIDERS_PATH",
+    "authenticate_request",
+    "build_callback_url",
+    "create_auth_router",
+    "make_current_user_dep",
+    "make_require_auth_dep",
+]

blade_auth_client-0.2.0/src/blade_auth_client/fastapi/deps.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Depends, HTTPException, Request, status
+from starlette.responses import Response as StarletteResponse
+
+from blade_auth_client.cookie.policy import clear_session_cookie, read_session_token
+from blade_auth_client.config import AuthConfig
+from blade_auth_client.errors import InvalidTokenError, JwksUnavailableError, UserProvisionError
+from blade_auth_client.users.provisioner import CasdoorClaims
+from blade_auth_client.users.provisioner import LazyProvisioner
+from blade_auth_client.verifier.token_verifier import TokenVerifier
+
+
+async def authenticate_request(
+    request: Request,
+    config: AuthConfig,
+    verifier: TokenVerifier,
+    provisioner: LazyProvisioner[Any],
+    *,
+    allow_query_token: bool = False,
+) -> tuple[Any, CasdoorClaims, str] | None:
+    token, token_source = _extract_token(
+        request,
+        config,
+        allow_query_token=allow_query_token,
+    )
+    if token is None:
+        _set_request_state(request, token=None, claims=None, user=None)
+        return None
+
+    try:
+        payload = await verifier.verify(token)
+    except InvalidTokenError as exc:
+        headers = None
+        if token_source == "cookie":
+            clear_cookie_response = StarletteResponse()
+            clear_session_cookie(clear_cookie_response, config)
+            set_cookie_header = clear_cookie_response.headers.get("set-cookie")
+            if set_cookie_header is not None:
+                headers = {"set-cookie": set_cookie_header}
+        _set_request_state(request, token=None, claims=None, user=None)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Unauthorized",
+            headers=headers,
+        ) from exc
+    except JwksUnavailableError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="JWKS unavailable",
+        ) from exc
+
+    try:
+        claims = _build_casdoor_claims(payload)
+        user = await provisioner.ensure_user(claims)
+    except UserProvisionError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to provision user",
+        ) from exc
+
+    _set_request_state(request, token=token, claims=claims, user=user)
+    return user, claims, token
+
+
+def make_current_user_dep(
+    config: AuthConfig,
+    *,
+    verifier: TokenVerifier,
+    provisioner: LazyProvisioner[Any],
+) -> Any:
+    async def _current_user(request: Request) -> Any | None:
+        authenticated = await authenticate_request(
+            request,
+            config,
+            verifier,
+            provisioner,
+        )
+        if authenticated is None:
+            return None
+        user, _, _ = authenticated
+        return user
+
+    return Depends(_current_user)
+
+
+def make_require_auth_dep(
+    config: AuthConfig,
+    *,
+    verifier: TokenVerifier,
+    provisioner: LazyProvisioner[Any],
+) -> Any:
+    current_user_dep = make_current_user_dep(
+        config,
+        verifier=verifier,
+        provisioner=provisioner,
+    )
+
+    async def _require_auth(current_user: Any = current_user_dep) -> Any:
+        if current_user is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Unauthorized",
+            )
+        return current_user
+
+    return Depends(_require_auth)
+
+
+def _extract_token(
+    request: Request,
+    config: AuthConfig,
+    *,
+    allow_query_token: bool = False,
+) -> tuple[str | None, str | None]:
+    authorization = request.headers.get("authorization", "")
+    scheme, _, credentials = authorization.partition(" ")
+    if scheme.lower() == "bearer" and credentials:
+        return credentials, "bearer"
+
+    if allow_query_token:
+        query_token = request.query_params.get("token", "").strip()
+        if query_token:
+            return query_token, "query"
+
+    cookie_token = read_session_token(request, config)
+    if cookie_token:
+        return cookie_token, "cookie"
+
+    return None, None
+
+
+def _build_casdoor_claims(claims: dict[str, Any]) -> CasdoorClaims:
+    sub = claims.get("sub")
+    if not isinstance(sub, str) or not sub:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Unauthorized",
+        )
+
+    return CasdoorClaims(
+        sub=sub,
+        email=_optional_string(claims.get("email")),
+        preferred_username=_optional_string(claims.get("preferred_username")),
+        name=_optional_string(claims.get("name") or claims.get("displayName")),
+        picture=_optional_string(claims.get("picture") or claims.get("avatar")),
+    )
+
+
+def _set_request_state(
+    request: Request,
+    *,
+    token: str | None,
+    claims: CasdoorClaims | None,
+    user: Any | None,
+) -> None:
+    request.state.blade_auth_token = token
+    request.state.blade_auth_claims = claims
+    request.state.blade_auth_user = user
+
+
+def _optional_string(value: Any) -> str | None:
+    if isinstance(value, str) and value:
+        return value
+    return None