sa-token-python-core 0.1.1__py3-none-any.whl

sa_token/stp_util.py

@@ -0,0 +1,367 @@
+"""StpUtil：全局静态门面。
+
+方法签名与 :class:`~sa_token.stp_logic.StpLogic` 一一对应，只是省去了手动
+传递 Manager。这里刻意逐个显式声明而不是用 ``__getattr__`` 转发，
+这样 IDE 补全、类型检查和文档都能正常工作。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .context import get_current_login_id, get_current_token
+from .exception import SaTokenNotInitializedException
+from .model import DEFAULT_LOGIN_TYPE, TerminalInfo, TokenInfo
+from .permission import MatchMode
+
+if TYPE_CHECKING:  # pragma: no cover - 仅供类型检查
+    from .manager import SaTokenManager
+    from .security import LoginTokenPair
+    from .session import SaSession
+    from .stp_logic import StpLogic
+
+__all__ = ["StpUtil", "set_manager", "get_manager", "clear_manager"]
+
+_manager: SaTokenManager | None = None
+
+
+def set_manager(manager: SaTokenManager) -> None:
+    """设置全局 Manager，一般由 ``SaTokenBuilder.build()`` 自动调用。"""
+    global _manager
+    _manager = manager
+
+
+def get_manager() -> SaTokenManager:
+    if _manager is None:
+        raise SaTokenNotInitializedException()
+    return _manager
+
+
+def clear_manager() -> None:
+    """清除全局实例，主要给测试做隔离。"""
+    global _manager
+    _manager = None
+
+
+class StpUtil:
+    """默认账号体系（``login``）的静态门面。"""
+
+    @staticmethod
+    def logic(login_type: str = DEFAULT_LOGIN_TYPE) -> StpLogic:
+        """取得底层 StpLogic，用于访问门面未暴露的高级能力。"""
+        return get_manager().stp(login_type)
+
+    # 认证 -----------------------------------------------------------------
+
+    @staticmethod
+    async def login(
+        login_id: Any,
+        *,
+        device: str | None = None,
+        timeout: int | None = None,
+        tag: str | None = None,
+        extra: dict[str, Any] | None = None,
+        token_value: str | None = None,
+    ) -> str:
+        return await StpUtil.logic().login(
+            login_id,
+            device=device,
+            timeout=timeout,
+            tag=tag,
+            extra=extra,
+            token_value=token_value,
+        )
+
+    @staticmethod
+    async def login_with_refresh(
+        login_id: Any,
+        *,
+        device: str | None = None,
+        timeout: int | None = None,
+        tag: str | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> LoginTokenPair:
+        return await StpUtil.logic().login_with_refresh(
+            login_id,
+            device=device,
+            timeout=timeout,
+            tag=tag,
+            extra=extra,
+        )
+
+    @staticmethod
+    async def refresh_access_token(refresh_token: str) -> LoginTokenPair:
+        return await get_manager().refresh_tokens.refresh(refresh_token)
+
+    @staticmethod
+    async def logout(login_id: Any, *, device: str | None = None) -> None:
+        await StpUtil.logic().logout(login_id, device=device)
+
+    @staticmethod
+    async def logout_by_token(token: str | None = None) -> None:
+        await StpUtil.logic().logout_by_token(token)
+
+    @staticmethod
+    async def kickout(login_id: Any, *, device: str | None = None) -> None:
+        await StpUtil.logic().kickout(login_id, device=device)
+
+    @staticmethod
+    async def kickout_by_token(token: str | None = None) -> None:
+        await StpUtil.logic().kickout_by_token(token)
+
+    @staticmethod
+    async def replaced(login_id: Any, *, device: str | None = None) -> None:
+        await StpUtil.logic().replaced(login_id, device=device)
+
+    @staticmethod
+    async def is_login(token: str | None = None) -> bool:
+        return await StpUtil.logic().is_login(token)
+
+    @staticmethod
+    async def check_login(token: str | None = None) -> str:
+        return await StpUtil.logic().check_login(token)
+
+    @staticmethod
+    async def get_login_id(token: str | None = None) -> str:
+        return await StpUtil.logic().get_login_id(token)
+
+    @staticmethod
+    async def get_login_id_or_none(token: str | None = None) -> str | None:
+        return await StpUtil.logic().get_login_id_or_none(token)
+
+    @staticmethod
+    def get_token_value() -> str | None:
+        """当前调用链绑定的 token（由中间件或 ``sa_token_context`` 写入）。"""
+        return get_current_token()
+
+    @staticmethod
+    def get_login_id_from_context() -> str | None:
+        """当前调用链已校验过的 login_id，不产生任何存储访问。"""
+        return get_current_login_id()
+
+    @staticmethod
+    async def get_token_info(token: str | None = None) -> TokenInfo | None:
+        return await StpUtil.logic().get_token_info(token)
+
+    @staticmethod
+    async def get_offline_reason(token: str) -> dict[str, Any] | None:
+        return await StpUtil.logic().get_offline_reason(token)
+
+    @staticmethod
+    async def renew_timeout(token: str, timeout: int) -> bool:
+        return await StpUtil.logic().renew_timeout(token, timeout)
+
+    # 权限 / 角色 -----------------------------------------------------------
+
+    @staticmethod
+    async def get_permissions(login_id: Any) -> list[str]:
+        return await StpUtil.logic().get_permissions(login_id)
+
+    @staticmethod
+    async def set_permissions(login_id: Any, permissions: list[str]) -> None:
+        await StpUtil.logic().set_permissions(login_id, permissions)
+
+    @staticmethod
+    async def add_permission(login_id: Any, permission: str) -> None:
+        await StpUtil.logic().add_permission(login_id, permission)
+
+    @staticmethod
+    async def remove_permission(login_id: Any, permission: str) -> None:
+        await StpUtil.logic().remove_permission(login_id, permission)
+
+    @staticmethod
+    async def clear_permissions(login_id: Any) -> None:
+        await StpUtil.logic().clear_permissions(login_id)
+
+    @staticmethod
+    async def has_permission(login_id: Any, permission: str) -> bool:
+        return await StpUtil.logic().has_permission(login_id, permission)
+
+    @staticmethod
+    async def has_permissions_and(login_id: Any, permissions: list[str]) -> bool:
+        return await StpUtil.logic().has_permissions_and(login_id, permissions)
+
+    @staticmethod
+    async def has_permissions_or(login_id: Any, permissions: list[str]) -> bool:
+        return await StpUtil.logic().has_permissions_or(login_id, permissions)
+
+    @staticmethod
+    async def check_permission(
+        login_id: Any,
+        permissions: str | list[str],
+        *,
+        mode: MatchMode = "OR",
+    ) -> None:
+        await StpUtil.logic().check_permission(login_id, permissions, mode=mode)
+
+    @staticmethod
+    async def get_roles(login_id: Any) -> list[str]:
+        return await StpUtil.logic().get_roles(login_id)
+
+    @staticmethod
+    async def set_roles(login_id: Any, roles: list[str]) -> None:
+        await StpUtil.logic().set_roles(login_id, roles)
+
+    @staticmethod
+    async def add_role(login_id: Any, role: str) -> None:
+        await StpUtil.logic().add_role(login_id, role)
+
+    @staticmethod
+    async def remove_role(login_id: Any, role: str) -> None:
+        await StpUtil.logic().remove_role(login_id, role)
+
+    @staticmethod
+    async def has_role(login_id: Any, role: str) -> bool:
+        return await StpUtil.logic().has_role(login_id, role)
+
+    @staticmethod
+    async def has_roles_and(login_id: Any, roles: list[str]) -> bool:
+        return await StpUtil.logic().has_roles_and(login_id, roles)
+
+    @staticmethod
+    async def has_roles_or(login_id: Any, roles: list[str]) -> bool:
+        return await StpUtil.logic().has_roles_or(login_id, roles)
+
+    @staticmethod
+    async def check_role(
+        login_id: Any,
+        roles: str | list[str],
+        *,
+        mode: MatchMode = "OR",
+    ) -> None:
+        await StpUtil.logic().check_role(login_id, roles, mode=mode)
+
+    # Session ---------------------------------------------------------------
+
+    @staticmethod
+    async def get_session(login_id: Any, *, create: bool = True) -> SaSession | None:
+        return await StpUtil.logic().get_session(login_id, create=create)
+
+    @staticmethod
+    async def get_token_session(token: str | None = None) -> SaSession | None:
+        return await StpUtil.logic().get_token_session(token)
+
+    @staticmethod
+    async def delete_session(login_id: Any) -> None:
+        await StpUtil.logic().delete_session(login_id)
+
+    # 封禁 -----------------------------------------------------------------
+
+    @staticmethod
+    async def disable(
+        login_id: Any,
+        seconds: int,
+        *,
+        service: str = "login",
+        level: int = 1,
+    ) -> None:
+        await StpUtil.logic().disable(login_id, seconds, service=service, level=level)
+
+    @staticmethod
+    async def untie(login_id: Any, *, service: str = "login") -> None:
+        await StpUtil.logic().untie(login_id, service=service)
+
+    @staticmethod
+    async def is_disable(login_id: Any, *, service: str = "login", level: int = 1) -> bool:
+        return await StpUtil.logic().is_disable(login_id, service=service, level=level)
+
+    @staticmethod
+    async def get_disable_time(login_id: Any, *, service: str = "login") -> int:
+        return await StpUtil.logic().get_disable_time(login_id, service=service)
+
+    @staticmethod
+    async def get_disable_level(login_id: Any, *, service: str = "login") -> int:
+        return await StpUtil.logic().get_disable_level(login_id, service=service)
+
+    @staticmethod
+    async def check_disable(login_id: Any, *, service: str = "login", level: int = 1) -> None:
+        await StpUtil.logic().check_disable(login_id, service=service, level=level)
+
+    # 二级认证 --------------------------------------------------------------
+
+    @staticmethod
+    async def open_safe(token: str, business: str, seconds: int) -> None:
+        await StpUtil.logic().open_safe(token, business, seconds)
+
+    @staticmethod
+    async def is_safe(token: str | None, business: str) -> bool:
+        return await StpUtil.logic().is_safe(token, business)
+
+    @staticmethod
+    async def check_safe(token: str | None, business: str) -> None:
+        await StpUtil.logic().check_safe(token, business)
+
+    @staticmethod
+    async def close_safe(token: str, business: str) -> None:
+        await StpUtil.logic().close_safe(token, business)
+
+    # 查询 -----------------------------------------------------------------
+
+    @staticmethod
+    async def get_terminal_list(login_id: Any, *, device: str | None = None) -> list[TerminalInfo]:
+        return await StpUtil.logic().get_terminal_list(login_id, device=device)
+
+    @staticmethod
+    async def get_token_value_list_by_login_id(
+        login_id: Any,
+        *,
+        device: str | None = None,
+    ) -> list[str]:
+        return await StpUtil.logic().get_token_value_list_by_login_id(login_id, device=device)
+
+    @staticmethod
+    async def search_token_value(
+        keyword: str = "",
+        *,
+        start: int = 0,
+        size: int = 100,
+    ) -> list[str]:
+        return await StpUtil.logic().search_token_value(keyword, start=start, size=size)
+
+    @staticmethod
+    async def search_session(
+        keyword: str = "",
+        *,
+        start: int = 0,
+        size: int = 100,
+    ) -> list[str]:
+        return await StpUtil.logic().search_session(keyword, start=start, size=size)
+
+    # 安全工具 -------------------------------------------------------------
+
+    @staticmethod
+    async def issue_nonce(subject: Any, *, purpose: str = "default") -> str:
+        return await get_manager().nonces.issue(str(subject), purpose=purpose)
+
+    @staticmethod
+    async def consume_nonce(
+        nonce: str, subject: Any, *, purpose: str = "default"
+    ) -> None:
+        await get_manager().nonces.consume(nonce, str(subject), purpose=purpose)
+
+    @staticmethod
+    async def create_temp_token(
+        value: Any,
+        timeout: int,
+        *,
+        namespace: str = "default",
+        record_index: bool = False,
+    ) -> str:
+        return await get_manager().temp_tokens.create(
+            value,
+            timeout,
+            namespace=namespace,
+            record_index=record_index,
+        )
+
+    @staticmethod
+    async def parse_temp_token(token: str, *, namespace: str = "default") -> Any | None:
+        return await get_manager().temp_tokens.parse(token, namespace=namespace)
+
+    @staticmethod
+    async def consume_temp_token(token: str, *, namespace: str = "default") -> Any | None:
+        return await get_manager().temp_tokens.consume(token, namespace=namespace)
+
+    @staticmethod
+    async def delete_temp_token(token: str, *, namespace: str = "default") -> bool:
+        return await get_manager().temp_tokens.delete(token, namespace=namespace)

sa_token/strategy/__init__.py

@@ -0,0 +1,77 @@
+"""Token 生成策略。
+
+``create_strategy`` 把配置里的字符串风格名翻译成具体实现，
+这样用户既可以用 ``token_style="uuid"``，也能直接注入自定义策略对象。
+"""
+
+from __future__ import annotations
+
+from ..config import SaTokenConfig
+from .base import TokenStrategy
+from .builtin import (
+    HashStrategy,
+    RandomStrategy,
+    SimpleUuidStrategy,
+    TikStrategy,
+    TimestampStrategy,
+    UuidStrategy,
+)
+
+__all__ = [
+    "TokenStrategy",
+    "UuidStrategy",
+    "SimpleUuidStrategy",
+    "RandomStrategy",
+    "HashStrategy",
+    "TimestampStrategy",
+    "TikStrategy",
+    "JwtStrategy",
+    "create_strategy",
+    "BUILTIN_STYLES",
+]
+
+BUILTIN_STYLES = (
+    "uuid",
+    "simple-uuid",
+    "random32",
+    "random64",
+    "random128",
+    "hash",
+    "timestamp",
+    "tik",
+    "jwt",
+)
+
+
+def create_strategy(config: SaTokenConfig) -> TokenStrategy:
+    """按 ``config.token_style`` 创建策略实例。"""
+    style = config.token_style.strip().lower()
+    if style == "uuid":
+        return UuidStrategy()
+    if style in ("simple-uuid", "simple_uuid"):
+        return SimpleUuidStrategy()
+    if style.startswith("random"):
+        suffix = style[len("random") :]
+        return RandomStrategy(int(suffix) if suffix.isdigit() else 32)
+    if style == "hash":
+        return HashStrategy()
+    if style == "timestamp":
+        return TimestampStrategy()
+    if style == "tik":
+        return TikStrategy()
+    if style == "jwt":
+        from .jwt import JwtStrategy
+
+        return JwtStrategy(
+            config.jwt_secret_key or "",
+            algorithm=config.jwt_algorithm,
+        )
+    raise ValueError(f"未知的 token_style: {config.token_style}，可选：{', '.join(BUILTIN_STYLES)}")
+
+
+def __getattr__(name: str):
+    if name == "JwtStrategy":
+        from .jwt import JwtStrategy
+
+        return JwtStrategy
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

sa_token/strategy/base.py

@@ -0,0 +1,22 @@
+"""Token 生成策略契约。
+
+生成什么样的字符串是策略的事；这个字符串代表谁，永远以存储为准。
+因此非 JWT 策略的 :meth:`parse` 返回 ``None`` 是完全正常的。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = ["TokenStrategy"]
+
+
+@runtime_checkable
+class TokenStrategy(Protocol):
+    name: str
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str: ...
+
+    def parse(self, token: str) -> dict[str, Any] | None:
+        """自解释 token（如 JWT）返回载荷，其余返回 ``None``。"""
+        ...

sa_token/strategy/builtin.py

@@ -0,0 +1,99 @@
+"""内置的不透明 token 生成策略。
+
+全部使用 :mod:`secrets` 而非 :mod:`random`，保证 token 不可预测。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import string
+import uuid
+from typing import Any
+
+from ..model import now_ms
+
+__all__ = [
+    "UuidStrategy",
+    "SimpleUuidStrategy",
+    "RandomStrategy",
+    "HashStrategy",
+    "TimestampStrategy",
+    "TikStrategy",
+]
+
+_TIK_ALPHABET = string.ascii_letters + string.digits
+
+
+class _OpaqueStrategy:
+    """不透明 token 的公共基类：无法从 token 本身反推身份。"""
+
+    name = "opaque"
+
+    def parse(self, token: str) -> dict[str, Any] | None:
+        return None
+
+
+class UuidStrategy(_OpaqueStrategy):
+    name = "uuid"
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str:
+        return str(uuid.uuid4())
+
+
+class SimpleUuidStrategy(_OpaqueStrategy):
+    name = "simple-uuid"
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str:
+        return uuid.uuid4().hex
+
+
+class RandomStrategy(_OpaqueStrategy):
+    """定长随机 hex 串，``length`` 为字符数。"""
+
+    def __init__(self, length: int = 32) -> None:
+        if length < 8:
+            raise ValueError("随机 token 长度不得小于 8")
+        self.length = length
+        self.name = f"random{length}"
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str:
+        return secrets.token_hex((self.length + 1) // 2)[: self.length]
+
+
+class HashStrategy(_OpaqueStrategy):
+    """SHA256(login_id + 随机盐)，长度固定 64。
+
+    掺入随机盐是必须的：否则同一个 login_id 永远得到同一个 token，
+    多端登录与顶号语义会直接失效。
+    """
+
+    name = "hash"
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str:
+        material = f"{login_id}:{now_ms()}:{secrets.token_hex(16)}"
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+
+class TimestampStrategy(_OpaqueStrategy):
+    """``{毫秒时间戳}_{随机串}``，便于从 token 直接看出签发时间。"""
+
+    name = "timestamp"
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str:
+        return f"{now_ms()}_{secrets.token_hex(8)}"
+
+
+class TikStrategy(_OpaqueStrategy):
+    """短 token，适合放进 URL 或口令分享。
+
+    长度短意味着熵低，仅建议用于短期 / 一次性场景。
+    """
+
+    name = "tik"
+
+    def __init__(self, length: int = 8) -> None:
+        self.length = length
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str:
+        return "".join(secrets.choice(_TIK_ALPHABET) for _ in range(self.length))

sa_token/strategy/jwt.py

@@ -0,0 +1,72 @@
+"""有状态 JWT 策略。
+
+token 自带 claims，但校验时**仍然查存储**，因此踢人、顶号、封禁全部继续有效。
+这是刻意的取舍：纯无状态 JWT 无法在服务端即时作废，与本项目的核心语义冲突。
+
+需要额外安装：``pip install "sa-token-python-core[jwt]"``。
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Any
+
+from ..model import now_ms
+
+__all__ = ["JwtStrategy"]
+
+
+class JwtStrategy:
+    name = "jwt"
+
+    def __init__(
+        self,
+        secret_key: str,
+        *,
+        algorithm: str = "HS256",
+        issuer: str | None = None,
+        audience: str | None = None,
+    ) -> None:
+        if not secret_key:
+            raise ValueError("使用 JWT 风格时必须配置 jwt_secret_key")
+        try:
+            import jwt as pyjwt
+        except ImportError as exc:  # pragma: no cover - 依赖缺失路径
+            raise ImportError(
+                'JwtStrategy 需要 PyJWT 依赖，请执行：pip install "sa-token-python-core[jwt]"'
+            ) from exc
+        self._jwt = pyjwt
+        self.secret_key = secret_key
+        self.algorithm = algorithm
+        self.issuer = issuer
+        self.audience = audience
+
+    def generate(self, login_id: str, extra: dict[str, Any] | None = None) -> str:
+        issued_at = now_ms() // 1000
+        payload: dict[str, Any] = {
+            "loginId": login_id,
+            "iat": issued_at,
+            # jti 让相同 login_id 的多次登录得到不同 token，多端语义才成立。
+            "jti": secrets.token_hex(12),
+        }
+        if self.issuer:
+            payload["iss"] = self.issuer
+        if self.audience:
+            payload["aud"] = self.audience
+        if extra:
+            payload.update(extra)
+        return self._jwt.encode(payload, self.secret_key, algorithm=self.algorithm)
+
+    def parse(self, token: str) -> dict[str, Any] | None:
+        try:
+            return self._jwt.decode(
+                token,
+                self.secret_key,
+                algorithms=[self.algorithm],
+                audience=self.audience,
+                issuer=self.issuer,
+                # 过期与否由存储层的 TTL 决定，避免两套过期时间互相打架。
+                options={"verify_exp": False},
+            )
+        except Exception:
+            return None