blade-auth-client 0.2.0__py3-none-any.whl

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/casdoor/__init__.py

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

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/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/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/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/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/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/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

blade_auth_client/fastapi/router.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from secrets import token_urlsafe
+from typing import Any
+from urllib.parse import urlencode, urlparse
+
+from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.responses import JSONResponse, RedirectResponse
+
+from blade_auth_client.casdoor.client import OidcClient
+from blade_auth_client.cookie.policy import clear_session_cookie, write_session_cookie
+from blade_auth_client.config import AuthConfig
+from blade_auth_client.errors import CasdoorError, InvalidTokenError, JwksUnavailableError, UserProvisionError
+from blade_auth_client.fastapi.deps import _build_casdoor_claims, make_require_auth_dep
+from blade_auth_client.fastapi.urls import build_callback_url, build_public_casdoor_base, hostname_from_host
+from blade_auth_client.users.provisioner import CasdoorClaims, LazyProvisioner
+from blade_auth_client.verifier.token_verifier import TokenVerifier
+
+LOGGER = logging.getLogger(__name__)
+AUTHORIZE_URL = "/api/auth/login"
+STATE_TTL_SECONDS = 300
+AUTHORIZE_PATH = "/login/oauth/authorize"
+
+# 路由 path 常量（相对于消费方挂载的 prefix；single source of truth）
+LOGIN_PATH = "/login"
+CALLBACK_PATH = "/oauth/casdoor/callback"
+LOGOUT_PATH = "/logout"
+ME_PATH = "/me"
+PROVIDERS_PATH = "/providers"
+
+MeSerializer = Callable[[Any, CasdoorClaims | None, Request], dict[str, Any]]
+
+
+def create_auth_router(
+    config: AuthConfig,
+    *,
+    verifier: TokenVerifier,
+    provisioner: LazyProvisioner[Any],
+    oidc_client: OidcClient,
+    me_serializer: MeSerializer | None = None,
+) -> Any:
+    router = APIRouter()
+    require_auth = make_require_auth_dep(
+        config,
+        verifier=verifier,
+        provisioner=provisioner,
+    )
+    serialize_me = me_serializer or _default_me_serializer
+    state_store: dict[str, tuple[str, float]] = {}
+
+    async def _warm_jwks() -> None:
+        if not hasattr(verifier, "prewarm"):
+            return
+        try:
+            await verifier.prewarm()
+        except JwksUnavailableError:
+            LOGGER.warning("Initial JWKS prewarm failed", exc_info=True)
+
+    router.add_event_handler("startup", _warm_jwks)
+
+    def _prune_states() -> None:
+        now = time.monotonic()
+        expired_states = [key for key, (_, expires_at) in state_store.items() if expires_at <= now]
+        for key in expired_states:
+            state_store.pop(key, None)
+
+    def _store_state(next_url: str) -> str:
+        _prune_states()
+        state = token_urlsafe(32)
+        state_store[state] = (next_url, time.monotonic() + STATE_TTL_SECONDS)
+        return state
+
+    def _consume_state(state: str) -> str | None:
+        _prune_states()
+        entry = state_store.pop(state, None)
+        if entry is None:
+            return None
+
+        next_url, expires_at = entry
+        if expires_at <= time.monotonic():
+            return None
+        return next_url
+
+    @router.get(LOGIN_PATH)
+    async def login(request: Request, next: str | None = None) -> RedirectResponse:
+        if next is None:
+            if not config.allowed_redirect_origins:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="next required: no default redirect origin configured",
+                )
+            next = config.allowed_redirect_origins[0]
+        _validate_next_url(next, config, request=request)
+        state = _store_state(next)
+        callback_url = _resolve_callback_url(request, config, LOGIN_PATH)
+        authorize_url = _build_authorize_url(
+            request=request,
+            config=config,
+            state=state,
+            redirect_uri=callback_url,
+        )
+        return RedirectResponse(authorize_url, status_code=status.HTTP_302_FOUND)
+
+    @router.get(CALLBACK_PATH)
+    async def callback(request: Request, code: str, state: str) -> RedirectResponse:
+        next_url = _consume_state(state)
+        if next_url is None:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid state")
+
+        try:
+            access_token = await oidc_client.exchange_code(
+                code,
+                _resolve_callback_url(request, config, CALLBACK_PATH),
+            )
+            claims = await verifier.verify(access_token)
+            await provisioner.ensure_user(_build_casdoor_claims(claims))
+        except InvalidTokenError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Unauthorized",
+            ) from exc
+        except JwksUnavailableError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="JWKS unavailable",
+            ) from exc
+        except (CasdoorError, UserProvisionError) as exc:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=str(exc),
+            ) from exc
+
+        response = RedirectResponse(next_url, status_code=status.HTTP_302_FOUND)
+        write_session_cookie(response, access_token, config)
+        return response
+
+    @router.get(LOGOUT_PATH)
+    async def logout_redirect(request: Request) -> RedirectResponse:
+        response = RedirectResponse(_build_logout_url(request, config), status_code=status.HTTP_302_FOUND)
+        clear_session_cookie(response, config)
+        return response
+
+    @router.post(LOGOUT_PATH)
+    async def logout_json(request: Request) -> JSONResponse:
+        response = JSONResponse({"logout_url": _build_logout_url(request, config)})
+        clear_session_cookie(response, config)
+        return response
+
+    @router.get(PROVIDERS_PATH)
+    async def providers(request: Request) -> dict[str, Any]:
+        # 根据实际挂载的 router prefix 拼 login URL，避免硬编码 /api/auth/login
+        # 在不同前缀下返回错误地址（blade-os 挂 /api/v1/auth、消费方可能不用前缀）
+        path = request.url.path
+        assert path.endswith(PROVIDERS_PATH)
+        authorize_url = path[: -len(PROVIDERS_PATH)] + LOGIN_PATH
+        return {
+            "providers": [{"name": "casdoor", "authorize_url": authorize_url}],
+            "password_enabled": False,
+        }
+
+    @router.get(ME_PATH)
+    async def me(request: Request, user: Any = require_auth) -> dict[str, Any]:
+        claims = getattr(request.state, "blade_auth_claims", None)
+        return serialize_me(user, claims, request)
+
+    return router
+
+
+def _build_authorize_url(
+    *,
+    request: Request,
+    config: AuthConfig,
+    state: str,
+    redirect_uri: str,
+) -> str:
+    public_base = build_public_casdoor_base(request, public_port=config.public_casdoor_port)
+    return f"{public_base}{AUTHORIZE_PATH}?{urlencode(_authorize_query(config, state, redirect_uri))}"
+
+
+def _authorize_query(config: AuthConfig, state: str, redirect_uri: str) -> dict[str, str]:
+    return {
+        "client_id": config.casdoor_client_id,
+        "redirect_uri": redirect_uri,
+        "response_type": "code",
+        "scope": "openid profile email",
+        "state": state,
+    }
+
+
+def _resolve_callback_url(request: Request, config: AuthConfig, current_route: str) -> str:
+    if request.headers.get("host") or request.url.hostname:
+        return build_callback_url(request, _route_prefix(request, current_route))
+    if config.callback_base_url:
+        return config.callback_base_url.rstrip("/")
+    return build_callback_url(request, "")
+
+
+def _build_logout_url(request: Request, config: AuthConfig) -> str:
+    if request.headers.get("host") or request.url.hostname:
+        return f"{build_public_casdoor_base(request, public_port=config.public_casdoor_port)}/logout"
+    if config.casdoor_endpoint:
+        return f"{config.casdoor_endpoint.rstrip('/')}/logout"
+    return f"{config.internal_casdoor_endpoint.rstrip('/')}/logout"
+
+
+def _route_prefix(request: Request, route_path: str) -> str:
+    path = request.url.path.rstrip("/")
+    normalized_route = route_path.rstrip("/")
+    if path.endswith(normalized_route):
+        return path[: -len(normalized_route)]
+    return ""
+
+
+def _validate_next_url(
+    next_url: str,
+    config: AuthConfig,
+    *,
+    request: Request | None = None,
+) -> None:
+    parsed = urlparse(next_url)
+    if not parsed.scheme or not parsed.netloc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="next must be an absolute URL",
+        )
+
+    origin = f"{parsed.scheme}://{parsed.netloc}"
+    if origin in set(config.allowed_redirect_origins):
+        return
+
+    # 仅在运维没有显式配置 allowlist 时才落入 request-host fallback（动态 IP 场景）；
+    # 一旦配了 allowlist，严格比对完整 origin，不能用 same-host 绕开端口/协议限制。
+    if not config.allowed_redirect_origins and request is not None:
+        request_host = request.headers.get("host")
+        request_hostname = hostname_from_host(request_host) if request_host else request.url.hostname
+        if parsed.hostname == request_hostname:
+            return
+
+    raise HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail="next origin is not allowed",
+    )
+
+
+def _default_me_serializer(
+    user: Any,
+    claims: CasdoorClaims | None,
+    request: Request,
+) -> dict[str, Any]:
+    return {
+        "id": _read_user_value(user, "id"),
+        "username": _coalesce(
+            _read_user_value(user, "username"),
+            _read_user_value(user, "name"),
+            getattr(claims, "preferred_username", None),
+            getattr(claims, "name", None),
+            getattr(claims, "email", None),
+            getattr(claims, "sub", None),
+        ),
+        "avatar_url": _coalesce(
+            _read_user_value(user, "avatar_url"),
+            _read_user_value(user, "avatar"),
+            getattr(claims, "picture", None),
+        ),
+        "token": getattr(request.state, "blade_auth_token", None),
+        "auth_type": "casdoor",
+    }
+
+
+def _read_user_value(user: Any, key: str) -> Any:
+    if isinstance(user, dict):
+        return user.get(key)
+    return getattr(user, key, None)
+
+
+def _coalesce(*values: Any) -> Any:
+    for value in values:
+        if value is not None:
+            return value
+    return None

blade_auth_client/fastapi/urls.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from fastapi import Request
+
+DEFAULT_PROVIDER = "casdoor"
+
+
+def build_callback_url(request: Request, prefix: str, provider: str = DEFAULT_PROVIDER) -> str:
+    scheme, host = request_origin(request)
+    normalized_prefix = _normalize_prefix(prefix)
+    return f"{scheme}://{host}{normalized_prefix}/oauth/{provider}/callback"
+
+
+def build_public_casdoor_base(request: Request, *, public_port: int) -> str:
+    scheme, host = request_origin(request)
+    hostname = hostname_from_host(host)
+    return f"{scheme}://{_format_netloc(hostname, public_port)}"
+
+
+def request_origin(request: Request) -> tuple[str, str]:
+    scheme = request.url.scheme or "http"
+    host = request.headers.get("host") or request.url.netloc or "127.0.0.1"
+    return scheme, host
+
+
+def hostname_from_host(host: str) -> str:
+    if host.startswith("["):
+        return host.split("]", 1)[0][1:]
+    if host.count(":") == 1:
+        return host.rsplit(":", 1)[0]
+    return host
+
+
+def _format_netloc(hostname: str, port: int) -> str:
+    if ":" in hostname and not hostname.startswith("["):
+        return f"[{hostname}]:{port}"
+    return f"{hostname}:{port}"
+
+
+def _normalize_prefix(prefix: str) -> str:
+    if not prefix:
+        return ""
+    if not prefix.startswith("/"):
+        prefix = f"/{prefix}"
+    return prefix.rstrip("/")

blade_auth_client/socketio/__init__.py

@@ -0,0 +1,3 @@
+from .middleware import AuthMiddleware, make_auth_middleware, socketio_auth
+
+__all__ = ["AuthMiddleware", "make_auth_middleware", "socketio_auth"]

blade_auth_client/socketio/middleware.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from http.cookies import SimpleCookie
+from typing import Any, Generic, TypeVar
+
+from blade_auth_client.errors import InvalidTokenError
+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
+
+UserT = TypeVar("UserT")
+
+
+class AuthMiddleware(Generic[UserT]):
+    def __init__(
+        self,
+        verifier: TokenVerifier,
+        provisioner: LazyProvisioner[UserT],
+        cookie_name: str = "blade_token",
+    ) -> None:
+        self._verifier = verifier
+        self._provisioner = provisioner
+        self._cookie_name = cookie_name
+
+    async def __call__(self, sid: str, environ: dict[str, Any], auth: Any | None) -> UserT | None:
+        user, _ = await socketio_auth(
+            self._verifier,
+            self._provisioner,
+            environ,
+            auth=auth,
+            cookie_name=self._cookie_name,
+        )
+        return user
+
+
+async def socketio_auth(
+    verifier: TokenVerifier,
+    provisioner: LazyProvisioner[UserT],
+    environ: Mapping[str, Any],
+    *,
+    auth: Any | None = None,
+    cookie_name: str = "blade_token",
+) -> tuple[UserT, str] | tuple[None, None]:
+    token = _extract_socket_token(auth, environ, cookie_name=cookie_name)
+    if token is None:
+        return None, None
+
+    claims = await verifier.verify(token)
+    user = await provisioner.ensure_user(_build_casdoor_claims(claims))
+    return user, token
+
+
+def make_auth_middleware(
+    verifier: TokenVerifier,
+    provisioner: LazyProvisioner[UserT],
+    cookie_name: str = "blade_token",
+) -> AuthMiddleware[UserT]:
+    return AuthMiddleware(
+        verifier=verifier,
+        provisioner=provisioner,
+        cookie_name=cookie_name,
+    )
+
+
+def _extract_socket_token(
+    auth: Any | None,
+    environ: Mapping[str, Any],
+    *,
+    cookie_name: str,
+) -> str | None:
+    if isinstance(auth, Mapping):
+        raw_token = auth.get("token")
+        if isinstance(raw_token, str):
+            token = raw_token.strip()
+            if token:
+                return token
+
+    raw_cookie = environ.get("HTTP_COOKIE")
+    if not isinstance(raw_cookie, str) or not raw_cookie.strip():
+        return None
+
+    cookie = SimpleCookie()
+    cookie.load(raw_cookie)
+    morsel = cookie.get(cookie_name)
+    if morsel is None:
+        return None
+
+    token = morsel.value.strip()
+    return token or None
+
+
+def _build_casdoor_claims(claims: Mapping[str, Any]) -> CasdoorClaims:
+    sub = claims.get("sub")
+    if not isinstance(sub, str) or not sub:
+        raise InvalidTokenError("Token subject is invalid")
+
+    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 _optional_string(value: Any) -> str | None:
+    if isinstance(value, str) and value:
+        return value
+    return None

blade_auth_client/users/__init__.py

@@ -0,0 +1,4 @@
+from .provisioner import CasdoorClaims, LazyProvisioner
+from .sqlalchemy_provisioner import SqlAlchemyProvisioner
+
+__all__ = ["CasdoorClaims", "LazyProvisioner", "SqlAlchemyProvisioner"]

blade_auth_client/users/provisioner.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, TypeVar, runtime_checkable
+
+UserT = TypeVar("UserT")
+
+
+@dataclass(slots=True)
+class CasdoorClaims:
+    sub: str
+    email: str | None = None
+    preferred_username: str | None = None
+    name: str | None = None
+    picture: str | None = None
+
+
+@runtime_checkable
+class LazyProvisioner(Protocol[UserT]):
+    async def ensure_user(self, claims: CasdoorClaims) -> UserT:
+        """Return an existing local user or lazily create one."""

blade_auth_client/users/sqlalchemy_provisioner.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy import select
+
+from blade_auth_client.errors import UserProvisionError
+
+from .provisioner import CasdoorClaims
+
+AfterLoginHook = Callable[[Any, Any, CasdoorClaims], Any | Awaitable[Any]]
+
+
+class SqlAlchemyProvisioner:
+    def __init__(
+        self,
+        sessionmaker: Callable[[], Any],
+        user_model: type[Any],
+        after_login: AfterLoginHook | None = None,
+        *,
+        id_field: str = "id",
+        subject_field: str = "casdoor_sub",
+        username_field: str = "username",
+        email_field: str = "email",
+        avatar_url_field: str = "avatar_url",
+    ) -> None:
+        self._sessionmaker = sessionmaker
+        self._user_model = user_model
+        self._after_login = after_login
+        self._id_field = id_field
+        self._subject_field = subject_field
+        self._username_field = username_field
+        self._email_field = email_field
+        self._avatar_url_field = avatar_url_field
+        self._validate_model_fields()
+
+    async def ensure_user(self, claims: CasdoorClaims) -> Any:
+        username = _resolve_username(claims)
+        try:
+            with self._sessionmaker() as session:
+                user = session.scalar(
+                    select(self._user_model).where(
+                        getattr(self._user_model, self._subject_field) == claims.sub
+                    )
+                )
+                created = False
+                if user is None:
+                    user = self._user_model(
+                        **{
+                            self._subject_field: claims.sub,
+                            self._username_field: username,
+                            self._email_field: claims.email,
+                            self._avatar_url_field: claims.picture,
+                        }
+                    )
+                    session.add(user)
+                    session.flush()
+                    created = True
+
+                updated = self._sync_user(user, claims, username)
+                if self._after_login is not None:
+                    maybe_awaitable = self._after_login(session, user, claims)
+                    if isinstance(maybe_awaitable, Awaitable):
+                        await maybe_awaitable
+
+                if created or updated:
+                    session.flush()
+                session.commit()
+                session.refresh(user)
+                return user
+        except UserProvisionError:
+            raise
+        except Exception as exc:
+            raise UserProvisionError("Failed to provision user") from exc
+
+    def _sync_user(self, user: Any, claims: CasdoorClaims, username: str) -> bool:
+        changed = False
+        if getattr(user, self._username_field, None) != username:
+            setattr(user, self._username_field, username)
+            changed = True
+        if claims.email is not None and getattr(user, self._email_field, None) != claims.email:
+            setattr(user, self._email_field, claims.email)
+            changed = True
+        if claims.picture is not None and getattr(user, self._avatar_url_field, None) != claims.picture:
+            setattr(user, self._avatar_url_field, claims.picture)
+            changed = True
+        return changed
+
+    def _validate_model_fields(self) -> None:
+        mapper = sa_inspect(self._user_model)
+        known_fields = set(mapper.attrs.keys())
+        missing = [
+            field_name
+            for field_name in (
+                self._id_field,
+                self._subject_field,
+                self._username_field,
+                self._email_field,
+                self._avatar_url_field,
+            )
+            if field_name not in known_fields
+        ]
+        if missing:
+            raise ValueError(
+                "user_model is missing required fields: " + ", ".join(sorted(missing))
+            )
+
+
+def _resolve_username(claims: CasdoorClaims) -> str:
+    return claims.preferred_username or claims.name or claims.email or claims.sub

blade_auth_client/verifier/__init__.py

@@ -0,0 +1,4 @@
+from .jwks_cache import JwksCache
+from .token_verifier import TokenVerifier, verify_token
+
+__all__ = ["JwksCache", "TokenVerifier", "verify_token"]

blade_auth_client/verifier/jwks_cache.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Callable
+
+import httpx
+import jwt
+
+from blade_auth_client.config import AuthConfig
+from blade_auth_client.errors import InvalidTokenError, JwksUnavailableError
+
+LOGGER = logging.getLogger(__name__)
+JWKS_PATH = "/.well-known/jwks"
+
+
+class JwksCache:
+    def __init__(
+        self,
+        config: AuthConfig,
+        http_client: httpx.AsyncClient | None = None,
+        *,
+        clock: Callable[[], float] | None = None,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._config = config
+        self._http_client = http_client or httpx.AsyncClient(timeout=10.0)
+        self._clock = clock or time.monotonic
+        self._logger = logger or LOGGER
+        self._jwks: dict[str, Any] | None = None
+        self._expires_at = 0.0
+
+    async def get_jwks(self) -> dict[str, Any]:
+        if self._jwks is not None and self._clock() < self._expires_at:
+            return self._jwks
+
+        return await self.refresh()
+
+    async def get_signing_key(self, token: str) -> Any:
+        try:
+            header = jwt.get_unverified_header(token)
+        except jwt.PyJWTError as exc:
+            raise InvalidTokenError("Token header is invalid") from exc
+
+        kid = header.get("kid")
+        if not isinstance(kid, str) or not kid:
+            raise InvalidTokenError("Token header missing kid")
+
+        jwks = await self.get_jwks()
+        key = self._find_key(jwks, kid)
+        if key is not None:
+            return key
+
+        # Casdoor 可能在 TTL 窗口内轮换 kid；本地缓存未命中时强制刷新一次再查，避免
+        # 在 jwks_cache_ttl_seconds 内登录全部失败
+        jwks = await self.refresh()
+        key = self._find_key(jwks, kid)
+        if key is not None:
+            return key
+
+        raise InvalidTokenError("Unable to find signing key for token")
+
+    @staticmethod
+    def _find_key(jwks: dict[str, Any], kid: str) -> Any | None:
+        for key_data in jwks.get("keys", []):
+            if key_data.get("kid") == kid:
+                return jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(key_data))
+        return None
+
+    async def refresh(self) -> dict[str, Any]:
+        try:
+            response = await self._http_client.get(
+                f"{self._config.internal_casdoor_endpoint.rstrip('/')}{JWKS_PATH}"
+            )
+            response.raise_for_status()
+            payload = response.json()
+            if not isinstance(payload, dict) or not isinstance(payload.get("keys"), list):
+                raise ValueError("JWKS payload is missing keys")
+        except Exception as exc:
+            if self._jwks is not None:
+                self._logger.warning("Failed to refresh JWKS, falling back to cached keys", exc_info=exc)
+                return self._jwks
+            raise JwksUnavailableError("Unable to fetch JWKS") from exc
+
+        self._jwks = payload
+        self._expires_at = self._clock() + self._config.jwks_cache_ttl_seconds
+        return payload

blade_auth_client/verifier/token_verifier.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any
+
+import jwt
+from jwt.exceptions import (
+    ExpiredSignatureError,
+    InvalidAlgorithmError,
+    InvalidTokenError as JwtInvalidTokenError,
+    MissingRequiredClaimError,
+    PyJWTError,
+)
+
+from blade_auth_client.config import AuthConfig
+from blade_auth_client.errors import ExpiredTokenError, InvalidTokenError
+from blade_auth_client.verifier.jwks_cache import JwksCache
+
+
+class TokenVerifier:
+    def __init__(self, config: AuthConfig, jwks_cache: JwksCache | None = None) -> None:
+        self._config = config
+        self._jwks_cache = jwks_cache or JwksCache(config)
+
+    async def prewarm(self) -> None:
+        await self._jwks_cache.refresh()
+
+    async def verify(self, token: str) -> dict[str, Any]:
+        try:
+            header = jwt.get_unverified_header(token)
+            if header.get("alg") != "RS256":
+                raise InvalidAlgorithmError("Token algorithm is invalid")
+            signing_key = await self._jwks_cache.get_signing_key(token)
+            return jwt.decode(
+                token,
+                key=signing_key,
+                algorithms=["RS256"],
+                options={"require": ["exp"], "verify_aud": False},
+            )
+        except ExpiredSignatureError as exc:
+            raise ExpiredTokenError("Token has expired") from exc
+        except MissingRequiredClaimError as exc:
+            raise InvalidTokenError("Token claims are invalid") from exc
+        except (InvalidAlgorithmError, JwtInvalidTokenError, PyJWTError) as exc:
+            raise InvalidTokenError("Token is invalid") from exc
+
+
+async def verify_token(token: str, *, verifier: TokenVerifier) -> dict[str, Any]:
+    return await verifier.verify(token)

blade_auth_client-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+blade_auth_client/__init__.py,sha256=JCY1fBnFiEGw_N51eLOPwfAFtpFiFzDPUENZJCYX6P0,3175
+blade_auth_client/config.py,sha256=VuPQvudOiPdopb-cPSxjpqyDgbXdyaR5vOUHKcbgmFE,882
+blade_auth_client/errors.py,sha256=LGaGTPxg27VVRMYJGTq05dTsPi6t6gWvgMRWTNL83c4,697
+blade_auth_client/casdoor/__init__.py,sha256=vv2YHkjOvo17fllrwB6MuQM8wTq3_hiP1O0zDUYrYtQ,57
+blade_auth_client/casdoor/client.py,sha256=_RJAYWivYDl6DUptYim0-d09dZNX5rTWO4P9m8krh0I,2726
+blade_auth_client/cookie/__init__.py,sha256=Rkr2m-sqWkL7MQipC-vrsn5s6CjlBGTlf0wAXqIjN54,165
+blade_auth_client/cookie/policy.py,sha256=RdIpAQtmWrXmr40u7f_4rtqz0tpVLC_c1hqEEd1S3F8,1033
+blade_auth_client/fastapi/__init__.py,sha256=So7Jrw4GBuwdXk5lIfEUy6fiS2S5dwejkLGLfZ6VYYY,503
+blade_auth_client/fastapi/deps.py,sha256=GRSSx84NkvCOFgCSnnYxh-Ua-zRI17jpWzg_D2OAHqE,5124
+blade_auth_client/fastapi/router.py,sha256=PPbHYTLwQGtOl4iWtZN8GrffZkmrbEz5mlHchUgc99E,10330
+blade_auth_client/fastapi/urls.py,sha256=QoEbABsSMYOi6DGcr_2fsPOvLEfA3V67WFLUZeEtOnw,1346
+blade_auth_client/socketio/__init__.py,sha256=RWTH5J0CXVRTidR5OnFObFISvdjdjH6YtAUc0Z_9tDU,147
+blade_auth_client/socketio/middleware.py,sha256=-WDQ6infIHLycZMXgwJ3gwpQi-pwXTaR0BbGtOiwJ4M,3192
+blade_auth_client/users/__init__.py,sha256=oni6WJ7T1Ka-845Hl7MjkFbfVVC1-bJ2Ul4X4jvIkNc,187
+blade_auth_client/users/provisioner.py,sha256=JrX7NZVqFxANY6xCWOCsNLaUkig8kd5EUryp4PVqxOY,533
+blade_auth_client/users/sqlalchemy_provisioner.py,sha256=Jhe7GJT6k_3ejsX0aUkdHuY4uryw-sJkKPCs8MijJTA,4129
+blade_auth_client/verifier/__init__.py,sha256=rpEVqBAPueWw0RwaqIH1vhM0dzveXqM_WZ3oQe_25oY,148
+blade_auth_client/verifier/jwks_cache.py,sha256=n9VRNbe_oeUA1Y6oOmP9wb81eyO_kdV61nLxyw2nWgw,3058
+blade_auth_client/verifier/token_verifier.py,sha256=4XfV0Fz7MSSNk2d79BEkaSxSNRX_CH4eMRlN0r4YS2E,1739
+blade_auth_client-0.2.0.dist-info/METADATA,sha256=faXG-6keF4oA1cUaMRFAYuRX7rzvTFWZ_DmgpPAN_k8,1906
+blade_auth_client-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+blade_auth_client-0.2.0.dist-info/RECORD,,

blade_auth_client-0.2.0.dist-info/WHEEL

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