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

sa_token/__init__.py

@@ -0,0 +1,89 @@
+"""sa-token-python：有状态 Token 认证与权限鉴权框架。
+
+核心不依赖任何 Web 框架，脚本、定时任务、RPC 与 Web 接口共用同一套语义::
+
+    from sa_token import SaToken, StpUtil
+    from sa_token.storage import MemoryStorage
+
+    SaToken.builder().storage(MemoryStorage()).build()
+    token = await StpUtil.login(10001)
+"""
+
+from __future__ import annotations
+
+from .config import NEVER_EXPIRE, SaTokenConfig
+from .context import (
+    get_current_login_id,
+    get_current_token,
+    sa_token_context,
+)
+from .exception import (
+    DisableException,
+    NotLoginException,
+    NotLoginType,
+    NotPermissionException,
+    NotRoleException,
+    NotSafeException,
+    SaTokenException,
+    SaTokenNotInitializedException,
+    SecurityException,
+)
+from .listener import Event, EventBus, EventData
+from .manager import SaToken, SaTokenBuilder, SaTokenManager, __version__
+from .model import TerminalInfo, TokenInfo
+from .permission import has_element, vague_match
+from .security import (
+    LoginTokenPair,
+    NonceManager,
+    RefreshTokenManager,
+    TempTokenManager,
+)
+from .session import SaSession
+from .stp_interface import StpInterface
+from .stp_logic import StpLogic
+from .stp_util import StpUtil, clear_manager, get_manager, set_manager
+
+__all__ = [
+    "__version__",
+    # 入口
+    "SaToken",
+    "SaTokenBuilder",
+    "SaTokenManager",
+    "StpUtil",
+    "StpLogic",
+    "set_manager",
+    "get_manager",
+    "clear_manager",
+    # 配置与模型
+    "SaTokenConfig",
+    "NEVER_EXPIRE",
+    "TokenInfo",
+    "TerminalInfo",
+    "SaSession",
+    "StpInterface",
+    "LoginTokenPair",
+    "NonceManager",
+    "RefreshTokenManager",
+    "TempTokenManager",
+    # 上下文
+    "sa_token_context",
+    "get_current_token",
+    "get_current_login_id",
+    # 事件
+    "Event",
+    "EventBus",
+    "EventData",
+    # 权限工具
+    "vague_match",
+    "has_element",
+    # 异常
+    "SaTokenException",
+    "SaTokenNotInitializedException",
+    "NotLoginException",
+    "NotLoginType",
+    "NotPermissionException",
+    "NotRoleException",
+    "DisableException",
+    "NotSafeException",
+    "SecurityException",
+]

sa_token/adapter/__init__.py

@@ -0,0 +1,24 @@
+"""框架无关的适配基础设施。
+
+这一层定义「共同写法」：HttpContext 抽象 + 统一鉴权管道 + 路径规则。
+具体框架绑定放在 :mod:`sa_token.integration`。
+"""
+
+from __future__ import annotations
+
+from .http import HttpContext, SimpleHttpContext
+from .path import PathAuthConfig, PathRule, ant_match
+from .pipeline import AuthResult, build_rule, resolve_token, run_auth_flow, run_path_auth
+
+__all__ = [
+    "HttpContext",
+    "SimpleHttpContext",
+    "PathAuthConfig",
+    "PathRule",
+    "ant_match",
+    "AuthResult",
+    "build_rule",
+    "resolve_token",
+    "run_auth_flow",
+    "run_path_auth",
+]

sa_token/adapter/http.py

@@ -0,0 +1,71 @@
+"""HttpContext：对「一次请求」的最小抽象。
+
+核心层只认这个协议，不认 ``fastapi.Request`` 或 ``flask.request``。
+新增一个框架支持 = 实现这个协议，而不是重写鉴权。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = ["HttpContext", "SimpleHttpContext"]
+
+
+@runtime_checkable
+class HttpContext(Protocol):
+    """请求上下文协议。
+
+    ``state`` 用于把校验结果回传给上层（``stp_login_id`` / ``stp_token``）。
+    """
+
+    state: dict[str, Any]
+
+    def get_header(self, name: str) -> str | None: ...
+
+    def get_cookie(self, name: str) -> str | None: ...
+
+    def get_query(self, name: str) -> str | None: ...
+
+    def get_path(self) -> str: ...
+
+    def get_method(self) -> str: ...
+
+
+class SimpleHttpContext:
+    """字典驱动的上下文实现。
+
+    适用于测试、非 HTTP 协议（gRPC metadata、MQ 消息头）以及任何
+    还没有官方适配器的框架。
+    """
+
+    def __init__(
+        self,
+        *,
+        headers: dict[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
+        query: dict[str, str] | None = None,
+        path: str = "/",
+        method: str = "GET",
+    ) -> None:
+        # Header 名大小写不敏感，统一转小写存储。
+        self._headers = {key.lower(): value for key, value in (headers or {}).items()}
+        self._cookies = dict(cookies or {})
+        self._query = dict(query or {})
+        self._path = path
+        self._method = method.upper()
+        self.state: dict[str, Any] = {}
+
+    def get_header(self, name: str) -> str | None:
+        return self._headers.get(name.lower())
+
+    def get_cookie(self, name: str) -> str | None:
+        return self._cookies.get(name)
+
+    def get_query(self, name: str) -> str | None:
+        return self._query.get(name)
+
+    def get_path(self) -> str:
+        return self._path
+
+    def get_method(self) -> str:
+        return self._method

sa_token/adapter/path.py

@@ -0,0 +1,163 @@
+"""Ant 风格路径匹配与路径鉴权规则表。
+
+适合网关式、配置驱动的鉴权：不想给每个路由挂装饰器时，用一张规则表描述即可。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..permission import MatchMode
+
+__all__ = ["ant_match", "PathRule", "PathAuthConfig"]
+
+
+def ant_match(pattern: str, path: str) -> bool:
+    """Ant 风格匹配。
+
+    - ``*`` 匹配单层路径
+    - ``**`` 匹配任意层（含 0 层）
+    - 其余为字面量
+    """
+    if pattern == path:
+        return True
+    pattern_parts = [part for part in pattern.strip("/").split("/") if part != ""]
+    path_parts = [part for part in path.strip("/").split("/") if part != ""]
+    return _match_parts(pattern_parts, 0, path_parts, 0)
+
+
+def _match_parts(
+    pattern_parts: list[str],
+    pattern_index: int,
+    path_parts: list[str],
+    path_index: int,
+) -> bool:
+    while pattern_index < len(pattern_parts):
+        part = pattern_parts[pattern_index]
+        if part == "**":
+            # ** 可以吞掉 0..n 层，逐个位置回溯尝试。
+            if pattern_index == len(pattern_parts) - 1:
+                return True
+            for skip in range(path_index, len(path_parts) + 1):
+                if _match_parts(pattern_parts, pattern_index + 1, path_parts, skip):
+                    return True
+            return False
+        if path_index >= len(path_parts):
+            return False
+        if part != "*" and part != path_parts[path_index]:
+            return False
+        pattern_index += 1
+        path_index += 1
+    return path_index == len(path_parts)
+
+
+@dataclass
+class PathRule:
+    """一条路径规则。
+
+    ``ignore=True`` 的规则优先级最高，用于放行登录页、健康检查等公开接口。
+    """
+
+    pattern: str
+    ignore: bool = False
+    require_login: bool = False
+    permissions: list[str] = field(default_factory=list)
+    roles: list[str] = field(default_factory=list)
+    mode: MatchMode = "OR"
+    methods: list[str] = field(default_factory=list)
+
+    def matches(self, path: str, method: str) -> bool:
+        if self.methods and method.upper() not in {m.upper() for m in self.methods}:
+            return False
+        return ant_match(self.pattern, path)
+
+
+class PathAuthConfig:
+    """路径规则表。
+
+    匹配策略：先看是否命中任一 ``ignore`` 规则；否则把全部命中的规则合并，
+    权限与角色取并集。这样 ``/admin/**`` 与 ``/admin/user/**`` 可以叠加约束。
+    """
+
+    def __init__(self) -> None:
+        self._rules: list[PathRule] = []
+
+    @property
+    def rules(self) -> list[PathRule]:
+        return list(self._rules)
+
+    def add(self, rule: PathRule) -> PathAuthConfig:
+        self._rules.append(rule)
+        return self
+
+    def ignore(self, *patterns: str, methods: list[str] | None = None) -> PathAuthConfig:
+        """放行指定路径。``methods`` 为空表示所有 HTTP 方法都放行。
+
+        同一路径要对不同方法区别对待时，必须给 ignore 也加上 ``methods``：
+        ignore 优先级最高，不限方法的 ``.ignore("/article")`` 会把
+        ``POST /article`` 一并放行。
+        """
+        for pattern in patterns:
+            self._rules.append(
+                PathRule(pattern, ignore=True, methods=list(methods or []))
+            )
+        return self
+
+    def login(self, *patterns: str, methods: list[str] | None = None) -> PathAuthConfig:
+        for pattern in patterns:
+            self._rules.append(
+                PathRule(pattern, require_login=True, methods=list(methods or []))
+            )
+        return self
+
+    def permission(
+        self,
+        pattern: str,
+        *permissions: str,
+        mode: MatchMode = "OR",
+        methods: list[str] | None = None,
+    ) -> PathAuthConfig:
+        self._rules.append(
+            PathRule(
+                pattern,
+                require_login=True,
+                permissions=list(permissions),
+                mode=mode,
+                methods=list(methods or []),
+            )
+        )
+        return self
+
+    def role(
+        self,
+        pattern: str,
+        *roles: str,
+        mode: MatchMode = "OR",
+        methods: list[str] | None = None,
+    ) -> PathAuthConfig:
+        self._rules.append(
+            PathRule(
+                pattern,
+                require_login=True,
+                roles=list(roles),
+                mode=mode,
+                methods=list(methods or []),
+            )
+        )
+        return self
+
+    def resolve(self, path: str, method: str) -> PathRule:
+        """把命中的规则合并成一条待执行规则。"""
+        matched = [rule for rule in self._rules if rule.matches(path, method)]
+        if not matched:
+            return PathRule(path)
+        if any(rule.ignore for rule in matched):
+            return PathRule(path, ignore=True)
+
+        merged = PathRule(path, require_login=any(rule.require_login for rule in matched))
+        for rule in matched:
+            merged.permissions.extend(rule.permissions)
+            merged.roles.extend(rule.roles)
+            if rule.mode == "AND":
+                merged.mode = "AND"
+        return merged

sa_token/adapter/pipeline.py

@@ -0,0 +1,97 @@
+"""统一鉴权管道：所有框架适配层的唯一入口。
+
+框架适配只做三件事：Request → HttpContext、调用这里、异常翻译成响应。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ..context import set_current
+from ..permission import MatchMode
+from ..token_io import read_token
+from .path import PathAuthConfig, PathRule
+
+if TYPE_CHECKING:  # pragma: no cover - 仅供类型检查
+    from ..manager import SaTokenManager
+    from .http import HttpContext
+
+__all__ = ["AuthResult", "resolve_token", "run_auth_flow", "run_path_auth"]
+
+
+@dataclass
+class AuthResult:
+    """鉴权结果。``login_id`` 为 None 表示匿名放行。"""
+
+    token: str | None = None
+    login_id: str | None = None
+    anonymous: bool = False
+
+
+def resolve_token(ctx: HttpContext, manager: SaTokenManager) -> str | None:
+    """读取 token 并写入上下文，但**不做登录校验**。
+
+    对应 Go 版的 ``TokenInterceptor``：让业务能拿到 token，同时保持接口公开。
+    """
+    token = read_token(ctx, manager.config)
+    ctx.state["stp_token"] = token
+    set_current(token, None)
+    return token
+
+
+async def run_auth_flow(
+    ctx: HttpContext,
+    manager: SaTokenManager,
+    rule: PathRule,
+    *,
+    login_type: str = "login",
+) -> AuthResult:
+    """执行一条规则的完整鉴权流程。"""
+    token = resolve_token(ctx, manager)
+    if rule.ignore:
+        return AuthResult(token=token, anonymous=True)
+    if not (rule.require_login or rule.permissions or rule.roles):
+        return AuthResult(token=token, anonymous=True)
+
+    logic = manager.stp(login_type)
+    login_id = await logic.check_login(token)
+
+    if rule.permissions:
+        await logic.check_permission(login_id, rule.permissions, mode=rule.mode)
+    if rule.roles:
+        await logic.check_role(login_id, rule.roles, mode=rule.mode)
+
+    ctx.state["stp_login_id"] = login_id
+    ctx.state["stp_token"] = token
+    set_current(token, login_id)
+    return AuthResult(token=token, login_id=login_id)
+
+
+async def run_path_auth(
+    ctx: HttpContext,
+    manager: SaTokenManager,
+    path_auth: PathAuthConfig,
+    *,
+    login_type: str = "login",
+) -> AuthResult:
+    """按路径规则表鉴权。"""
+    rule = path_auth.resolve(ctx.get_path(), ctx.get_method())
+    return await run_auth_flow(ctx, manager, rule, login_type=login_type)
+
+
+def build_rule(
+    *,
+    require_login: bool = True,
+    permissions: list[str] | None = None,
+    roles: list[str] | None = None,
+    mode: MatchMode = "OR",
+) -> PathRule:
+    """给装饰器 / Depends 用的临时规则。"""
+    return PathRule(
+        pattern="",
+        require_login=require_login,
+        permissions=list(permissions or []),
+        roles=list(roles or []),
+        mode=mode,
+    )

sa_token/config.py

@@ -0,0 +1,130 @@
+"""sa-token 配置。
+
+配置对象是纯数据，不含任何行为，方便从 YAML / 环境变量 / 配置中心加载后直接构造。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any, Literal
+
+__all__ = [
+    "NEVER_EXPIRE",
+    "OverflowLogoutMode",
+    "ReplacedRange",
+    "SaTokenConfig",
+]
+
+#: timeout 取该值时表示永不过期。
+NEVER_EXPIRE = -1
+
+OverflowLogoutMode = Literal["logout", "kickout", "replaced"]
+ReplacedRange = Literal["curr_device", "all_device"]
+
+
+@dataclass
+class SaTokenConfig:
+    """全局配置项，字段命名与 Java / Go / Rust 版保持一致。"""
+
+    token_name: str = "Authorization"
+    """从 Header / Cookie / Query 中读取 token 时使用的键名。"""
+
+    timeout: int = 2592000
+    """token 绝对有效期（秒），-1 表示永不过期。"""
+
+    active_timeout: int = NEVER_EXPIRE
+    """活跃超时（秒）：超过该时长未访问则冻结，-1 表示不启用。"""
+
+    dynamic_active_timeout: bool = False
+    """是否允许单个 token 覆盖全局 active_timeout。"""
+
+    auto_renew: bool = True
+    """校验通过后是否自动续期。"""
+
+    token_style: str = "uuid"
+    """token 生成风格，见 sa_token.strategy。"""
+
+    token_prefix: str = "Bearer "
+    """读取 Header 时需要剥离的前缀，空字符串表示不剥离。"""
+
+    is_read_header: bool = True
+    is_read_cookie: bool = True
+    is_read_query: bool = True
+    is_write_cookie: bool = False
+    """登录成功后是否把 token 写进 Cookie（需要框架适配层支持）。"""
+
+    cookie_path: str = "/"
+    cookie_domain: str | None = None
+    cookie_secure: bool = False
+    cookie_http_only: bool = True
+    cookie_same_site: str | None = "Lax"
+
+    is_concurrent: bool = True
+    """是否允许同一账号多端同时在线。False 表示新登录顶掉旧登录。"""
+
+    is_share: bool = True
+    """多端在线时是否共享同一个 token。仅在 is_concurrent=True 时生效。"""
+
+    max_login_count: int = 12
+    """同一账号最大同时在线数，-1 表示不限制。"""
+
+    overflow_logout_mode: OverflowLogoutMode = "logout"
+    """超出 max_login_count 时，对最旧登录采取的处理方式。"""
+
+    replaced_range: ReplacedRange = "curr_device"
+    """顶号影响范围：仅同设备类型，还是全部设备。"""
+
+    storage_key_prefix: str = "satoken:"
+    """所有存储键的统一前缀，便于多租户或共享 Redis。"""
+
+    is_logout_keep_session: bool = False
+    """登出后是否保留 Account-Session 数据。"""
+
+    offline_record_enabled: bool = True
+    """是否记录被踢 / 被顶的下线原因，便于前端提示。"""
+
+    offline_record_timeout: int = 3600
+    """下线记录保留秒数。"""
+
+    perm_cache_timeout: int = 0
+    """StpInterface 查询结果的缓存秒数，0 表示不缓存。"""
+
+    refresh_token_timeout: int = 2592000
+    """登录态 Refresh Token 有效期（秒），与 OAuth2 Refresh Token 相互独立。"""
+
+    refresh_token_rotate: bool = True
+    """刷新 access token 时是否同时轮转 refresh token。"""
+
+    refresh_token_reuse_detection: bool = True
+    """检测旧 refresh token 重放并吊销整个 token family。"""
+
+    nonce_timeout: int = 60
+    """服务端签发 Nonce 的默认有效期（秒）。"""
+
+    jwt_secret_key: str | None = None
+    jwt_algorithm: str = "HS256"
+
+    is_print_banner: bool = True
+    """初始化时是否打印启动横幅。"""
+
+    extra: dict[str, Any] = field(default_factory=dict)
+    """给扩展模块（OAuth2 / SSO / 在线用户）放自定义配置。"""
+
+    def __post_init__(self) -> None:
+        if not self.token_name:
+            raise ValueError("token_name 不能为空")
+        if self.storage_key_prefix and not self.storage_key_prefix.endswith(":"):
+            self.storage_key_prefix += ":"
+
+    @classmethod
+    def from_dict(cls, values: dict[str, Any]) -> SaTokenConfig:
+        """从字典构造配置，忽略未知字段，便于对接外部配置中心。"""
+        known = {f.name for f in fields(cls)}
+        return cls(**{key: value for key, value in values.items() if key in known})
+
+    def key_prefix(self, login_type: str) -> str:
+        return f"{self.storage_key_prefix}{login_type}:"
+
+    def make_key(self, login_type: str, suffix: str, identifier: str) -> str:
+        """拼接存储键：``satoken:login:token:abc``。"""
+        return f"{self.key_prefix(login_type)}{suffix}:{identifier}"

sa_token/context.py

@@ -0,0 +1,63 @@
+"""请求级上下文。
+
+Java 用 ThreadLocal，Go 用 context.Context。Python 的异步场景里必须用
+:mod:`contextvars`：``threading.local`` 在同一个事件循环线程上会被多个并发
+请求共用，直接导致身份串号。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+
+__all__ = [
+    "get_current_token",
+    "get_current_login_id",
+    "set_current",
+    "clear_current",
+    "sa_token_context",
+]
+
+_current_token: ContextVar[str | None] = ContextVar("sa_token_current_token", default=None)
+_current_login_id: ContextVar[str | None] = ContextVar("sa_token_current_login_id", default=None)
+
+
+def get_current_token() -> str | None:
+    """当前调用链绑定的 token。"""
+    return _current_token.get()
+
+
+def get_current_login_id() -> str | None:
+    """当前调用链绑定的 login_id（已通过校验）。"""
+    return _current_login_id.get()
+
+
+def set_current(token: str | None, login_id: str | None = None) -> tuple[Token, Token]:
+    """绑定当前身份，返回可用于还原的 reset token。"""
+    return _current_token.set(token), _current_login_id.set(login_id)
+
+
+def clear_current(tokens: tuple[Token, Token] | None = None) -> None:
+    """还原到绑定前的状态。"""
+    if tokens is None:
+        _current_token.set(None)
+        _current_login_id.set(None)
+        return
+    token_ref, login_id_ref = tokens
+    _current_token.reset(token_ref)
+    _current_login_id.reset(login_id_ref)
+
+
+@contextmanager
+def sa_token_context(token: str | None, login_id: str | None = None) -> Iterator[None]:
+    """在一段代码内绑定身份，退出时自动还原。
+
+    同步与异步代码都能用（``with`` 与 ``async with`` 场景下 contextvars 的
+    传播规则一致），因此不必再提供一个异步版本。
+    """
+    refs = set_current(token, login_id)
+    try:
+        yield
+    finally:
+        clear_current(refs)