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

sa_token/permission.py

@@ -0,0 +1,67 @@
+"""权限匹配引擎。
+
+规则刻意保持简单、可预测：只有 ``*`` 一种通配符，按 ``:`` 分段匹配。
+复杂策略（ABAC / ReBAC）请通过 :class:`~sa_token.stp_interface.StpInterface`
+对接 Casbin 等专门的策略引擎，不要把策略语言塞进核心。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Literal
+
+__all__ = ["MatchMode", "vague_match", "has_element", "match_all", "match_any"]
+
+MatchMode = Literal["AND", "OR"]
+
+
+def vague_match(pattern: str, target: str) -> bool:
+    """判断单条已授权的 ``pattern`` 是否覆盖所需的 ``target``。
+
+    - 完全相同：``user:read`` 命中 ``user:read``
+    - 末尾通配：``user:*`` 命中 ``user:read``、``user:read:self``
+    - 中间通配：``user:*:view`` 命中 ``user:admin:view``
+    - 全局通配：``*`` 命中任意权限
+    """
+    if not pattern or not target:
+        return False
+    if pattern == target:
+        return True
+    if "*" not in pattern:
+        return False
+
+    pattern_parts = pattern.split(":")
+    target_parts = target.split(":")
+
+    for index, pattern_part in enumerate(pattern_parts):
+        is_last_pattern_part = index == len(pattern_parts) - 1
+        if pattern_part == "*" and is_last_pattern_part:
+            # 末尾的 * 吃掉剩余全部层级，但至少要有一层可吃。
+            return len(target_parts) > index
+        if index >= len(target_parts):
+            return False
+        if pattern_part != "*" and pattern_part != target_parts[index]:
+            return False
+
+    # 模式已用尽：只有层级数完全相同才算命中，避免 a:b 命中 a:b:c。
+    return len(pattern_parts) == len(target_parts)
+
+
+def has_element(granted: Iterable[str], required: str) -> bool:
+    """已授权集合中是否存在覆盖 ``required`` 的条目。"""
+    return any(vague_match(item, required) for item in granted)
+
+
+def match_all(granted: Iterable[str], required: Sequence[str]) -> str | None:
+    """AND 语义：返回第一个未命中的条目，全部命中时返回 ``None``。"""
+    granted_list = list(granted)
+    for item in required:
+        if not has_element(granted_list, item):
+            return item
+    return None
+
+
+def match_any(granted: Iterable[str], required: Sequence[str]) -> bool:
+    """OR 语义：命中任意一个即可。"""
+    granted_list = list(granted)
+    return any(has_element(granted_list, item) for item in required)

sa_token/security/__init__.py

@@ -0,0 +1,14 @@
+"""框架无关的安全与登录生命周期扩展。"""
+
+from .nonce import NonceManager, NonceRecord
+from .refresh import LoginTokenPair, RefreshTokenManager
+from .temp_token import TempTokenManager, TempTokenRecord
+
+__all__ = [
+    "NonceManager",
+    "NonceRecord",
+    "LoginTokenPair",
+    "RefreshTokenManager",
+    "TempTokenManager",
+    "TempTokenRecord",
+]

sa_token/security/nonce.py

@@ -0,0 +1,93 @@
+"""一次性 Nonce：防止登录、支付等请求被重放。"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import asdict, dataclass
+from typing import TYPE_CHECKING
+
+from ..exception import SecurityException
+from ..model import now_ms
+
+if TYPE_CHECKING:
+    from ..storage.base import SaStorage
+
+__all__ = ["NonceManager", "NonceRecord"]
+
+
+@dataclass(frozen=True)
+class NonceRecord:
+    nonce: str
+    subject: str
+    purpose: str
+    created_at: int
+    state: str = "issued"
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, raw: str) -> NonceRecord | None:
+        try:
+            payload = json.loads(raw)
+            return cls(**payload) if isinstance(payload, dict) else None
+        except (TypeError, ValueError):
+            return None
+
+
+class NonceManager:
+    """签发并原子消费服务端 Nonce。
+
+    与「客户端随便给一个从未见过的字符串」不同，``consume`` 只接受本服务
+    通过 ``issue`` 签发的值，并校验 subject 与 purpose，防止跨用户、跨业务复用。
+    """
+
+    def __init__(
+        self,
+        storage: SaStorage,
+        *,
+        key_prefix: str = "satoken:",
+        timeout: int = 60,
+    ) -> None:
+        if timeout <= 0:
+            raise ValueError("nonce timeout 必须大于 0")
+        self._storage = storage
+        self._key_prefix = key_prefix
+        self.timeout = timeout
+
+    def _key(self, nonce: str) -> str:
+        return f"{self._key_prefix}security:nonce:{nonce}"
+
+    @staticmethod
+    def generate() -> str:
+        return f"nonce_{now_ms()}_{secrets.token_urlsafe(24)}"
+
+    async def issue(self, subject: str, *, purpose: str = "default") -> str:
+        """签发短时 Nonce；极小概率随机冲突时自动重试。"""
+        normalized_subject = str(subject).strip()
+        if not normalized_subject:
+            raise SecurityException("INVALID_NONCE_SUBJECT", "nonce subject 不能为空")
+        for _ in range(12):
+            nonce = self.generate()
+            record = NonceRecord(nonce, normalized_subject, purpose, now_ms())
+            if await self._storage.set_if_absent(self._key(nonce), record.to_json(), self.timeout):
+                return nonce
+        raise SecurityException("NONCE_ALLOCATION_FAILED", "无法分配唯一 nonce")
+
+    async def consume(self, nonce: str, subject: str, *, purpose: str = "default") -> None:
+        """原子消费 Nonce；并发请求中恰好一次成功。"""
+        key = self._key(nonce)
+        raw = await self._storage.get(key)
+        if raw is None:
+            raise SecurityException("INVALID_NONCE", "nonce 无效、已使用或已过期")
+        record = NonceRecord.from_json(raw)
+        if record is None:
+            raise SecurityException("INVALID_NONCE", "nonce 数据损坏")
+        if record.subject != str(subject) or record.purpose != purpose:
+            raise SecurityException("NONCE_MISMATCH", "nonce 与用户或业务不匹配")
+        if not await self._storage.compare_and_delete(key, raw):
+            raise SecurityException("NONCE_REPLAYED", "nonce 已被其它请求使用")
+
+    async def exists(self, nonce: str) -> bool:
+        return await self._storage.exists(self._key(nonce))

sa_token/security/refresh.py

@@ -0,0 +1,300 @@
+"""登录态 Refresh Token：与 OAuth2 Refresh Token 相互独立。"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import asdict, dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from ..exception import SecurityException
+from ..model import DEFAULT_DEVICE, now_ms
+
+if TYPE_CHECKING:
+    from ..manager import SaTokenManager
+
+__all__ = ["LoginTokenPair", "RefreshTokenManager"]
+
+
+@dataclass(frozen=True)
+class LoginTokenPair:
+    access_token: str
+    refresh_token: str
+    token_type: str = "Bearer"
+    expires_in: int = 0
+    refresh_expires_in: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class _RefreshRecord:
+    refresh_token: str
+    access_token: str
+    login_id: str
+    login_type: str
+    device: str
+    family_id: str
+    generation: int
+    created_at: int = field(default_factory=now_ms)
+    state: str = "active"
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, raw: str) -> _RefreshRecord | None:
+        try:
+            payload = json.loads(raw)
+            return cls(**payload) if isinstance(payload, dict) else None
+        except (TypeError, ValueError):
+            return None
+
+
+@dataclass
+class _FamilyRecord:
+    login_id: str
+    login_type: str
+    access_tokens: list[str] = field(default_factory=list)
+    refresh_tokens: list[str] = field(default_factory=list)
+    revoked: bool = False
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, raw: str) -> _FamilyRecord | None:
+        try:
+            payload = json.loads(raw)
+            return cls(**payload) if isinstance(payload, dict) else None
+        except (TypeError, ValueError):
+            return None
+
+
+class RefreshTokenManager:
+    """登录态 access/refresh 生命周期管理。
+
+    旧 refresh token 会保留为 ``used`` 墓碑直到有效期结束。再次使用旧值时，
+    视为泄漏并吊销同一 family 的全部 access/refresh token。
+    """
+
+    def __init__(self, manager: SaTokenManager) -> None:
+        self._manager = manager
+
+    @property
+    def _storage(self):
+        return self._manager.storage
+
+    def _refresh_key(self, token: str) -> str:
+        return self._manager.config.make_key("security", "refresh", token)
+
+    def _family_key(self, family_id: str) -> str:
+        return self._manager.config.make_key("security", "refresh-family", family_id)
+
+    def _user_index_key(self, login_type: str, login_id: str) -> str:
+        return self._manager.config.make_key(
+            "security", "refresh-user", f"{login_type}:{login_id}"
+        )
+
+    async def issue(
+        self,
+        access_token: str,
+        login_id: str,
+        *,
+        login_type: str = "login",
+        device: str = DEFAULT_DEVICE,
+        family_id: str | None = None,
+        generation: int = 0,
+    ) -> LoginTokenPair:
+        resolved_family = family_id or secrets.token_urlsafe(24)
+        for _ in range(12):
+            refresh_token = f"refresh_{secrets.token_urlsafe(36)}"
+            record = _RefreshRecord(
+                refresh_token=refresh_token,
+                access_token=access_token,
+                login_id=login_id,
+                login_type=login_type,
+                device=device,
+                family_id=resolved_family,
+                generation=generation,
+            )
+            if await self._storage.set_if_absent(
+                self._refresh_key(refresh_token),
+                record.to_json(),
+                self._manager.config.refresh_token_timeout,
+            ):
+                break
+        else:
+            raise SecurityException("REFRESH_ALLOCATION_FAILED", "无法分配 refresh token")
+
+        await self._update_family(resolved_family, record)
+        await self._add_user_family(login_type, login_id, resolved_family)
+        access_timeout = self._manager.config.timeout
+        return LoginTokenPair(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            expires_in=access_timeout,
+            refresh_expires_in=self._manager.config.refresh_token_timeout,
+        )
+
+    async def refresh(self, refresh_token: str) -> LoginTokenPair:
+        key = self._refresh_key(refresh_token)
+        raw = await self._storage.get(key)
+        record = _RefreshRecord.from_json(raw) if raw else None
+        if record is None:
+            raise SecurityException("INVALID_REFRESH_TOKEN", "refresh token 无效或已过期")
+        if record.state != "active":
+            if self._manager.config.refresh_token_reuse_detection:
+                await self.revoke_family(record.family_id)
+            raise SecurityException(
+                "REFRESH_TOKEN_REUSED",
+                "检测到旧 refresh token 重放，整个 token family 已吊销",
+                login_type=record.login_type,
+            )
+
+        used_record = _RefreshRecord(**{**asdict(record), "state": "used"})
+        if not await self._storage.compare_and_set(
+            key,
+            raw,
+            used_record.to_json(),
+            self._manager.config.refresh_token_timeout,
+        ):
+            if self._manager.config.refresh_token_reuse_detection:
+                await self.revoke_family(record.family_id)
+            raise SecurityException("REFRESH_TOKEN_REUSED", "refresh token 已被并发使用")
+
+        logic = self._manager.stp(record.login_type)
+        await logic.logout_by_token(record.access_token, revoke_refresh=False)
+        new_access = await logic.login(
+            record.login_id,
+            device=record.device,
+            timeout=self._manager.config.timeout,
+        )
+
+        if not self._manager.config.refresh_token_rotate:
+            active_record = _RefreshRecord(
+                **{
+                    **asdict(record),
+                    "access_token": new_access,
+                    "created_at": now_ms(),
+                    "state": "active",
+                }
+            )
+            await self._storage.set(
+                key,
+                active_record.to_json(),
+                self._manager.config.refresh_token_timeout,
+            )
+            await self._update_family(record.family_id, active_record)
+            return LoginTokenPair(
+                access_token=new_access,
+                refresh_token=refresh_token,
+                expires_in=self._manager.config.timeout,
+                refresh_expires_in=self._manager.config.refresh_token_timeout,
+            )
+
+        return await self.issue(
+            new_access,
+            record.login_id,
+            login_type=record.login_type,
+            device=record.device,
+            family_id=record.family_id,
+            generation=record.generation + 1,
+        )
+
+    async def revoke(self, refresh_token: str) -> bool:
+        key = self._refresh_key(refresh_token)
+        raw = await self._storage.get(key)
+        record = _RefreshRecord.from_json(raw) if raw else None
+        if record is None:
+            return False
+        await self._storage.delete(key)
+        await self._manager.stp(record.login_type).logout_by_token(
+            record.access_token, revoke_refresh=False
+        )
+        return True
+
+    async def revoke_for_access(self, access_token: str) -> None:
+        prefix = self._manager.config.key_prefix("security")
+        cursor: str | None = None
+        while True:
+            cursor, keys = await self._storage.scan(f"{prefix}refresh:*", cursor, 200)
+            for key in keys:
+                raw = await self._storage.get(key)
+                record = _RefreshRecord.from_json(raw) if raw else None
+                if record is not None and record.access_token == access_token:
+                    await self._storage.delete(key)
+            if cursor is None:
+                return
+
+    async def revoke_all_for_login(self, login_type: str, login_id: str) -> None:
+        raw = await self._storage.get(self._user_index_key(login_type, login_id))
+        families = json.loads(raw) if raw else []
+        if isinstance(families, list):
+            for family_id in families:
+                await self.revoke_family(str(family_id))
+        await self._storage.delete(self._user_index_key(login_type, login_id))
+
+    async def revoke_family(self, family_id: str) -> None:
+        key = self._family_key(family_id)
+        raw = await self._storage.get(key)
+        family = _FamilyRecord.from_json(raw) if raw else None
+        if family is None:
+            return
+        family.revoked = True
+        await self._storage.set(key, family.to_json(), self._manager.config.refresh_token_timeout)
+        logic = self._manager.stp(family.login_type)
+        for access_token in set(family.access_tokens):
+            await logic.logout_by_token(access_token, revoke_refresh=False)
+        for token in set(family.refresh_tokens):
+            await self._storage.delete(self._refresh_key(token))
+
+    async def _update_family(self, family_id: str, record: _RefreshRecord) -> None:
+        key = self._family_key(family_id)
+        for _ in range(12):
+            raw = await self._storage.get(key)
+            if raw is None:
+                family = _FamilyRecord(record.login_id, record.login_type)
+                family.access_tokens.append(record.access_token)
+                family.refresh_tokens.append(record.refresh_token)
+                if await self._storage.set_if_absent(
+                    key, family.to_json(), self._manager.config.refresh_token_timeout
+                ):
+                    return
+                continue
+            family = _FamilyRecord.from_json(raw)
+            if family is None or family.revoked:
+                raise SecurityException("REFRESH_FAMILY_REVOKED", "token family 已被吊销")
+            if record.access_token not in family.access_tokens:
+                family.access_tokens.append(record.access_token)
+            if record.refresh_token not in family.refresh_tokens:
+                family.refresh_tokens.append(record.refresh_token)
+            if await self._storage.compare_and_set(
+                key,
+                raw,
+                family.to_json(),
+                self._manager.config.refresh_token_timeout,
+            ):
+                return
+        raise SecurityException("REFRESH_CONFLICT", "更新 token family 时发生并发冲突")
+
+    async def _add_user_family(self, login_type: str, login_id: str, family_id: str) -> None:
+        key = self._user_index_key(login_type, login_id)
+        for _ in range(12):
+            raw = await self._storage.get(key)
+            families = json.loads(raw) if raw else []
+            if family_id in families:
+                return
+            families.append(family_id)
+            new_raw = json.dumps(families, separators=(",", ":"))
+            if raw is None:
+                if await self._storage.set_if_absent(
+                    key, new_raw, self._manager.config.refresh_token_timeout
+                ):
+                    return
+            elif await self._storage.compare_and_set(
+                key, raw, new_raw, self._manager.config.refresh_token_timeout
+            ):
+                return
+        raise SecurityException("REFRESH_CONFLICT", "更新用户 refresh 索引时发生并发冲突")

sa_token/security/temp_token.py

@@ -0,0 +1,114 @@
+"""短时业务 Token：邀请、重置密码、邮箱验证等一次性动作。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+from dataclasses import asdict, dataclass
+from typing import TYPE_CHECKING, Any
+
+from ..exception import SecurityException
+from ..model import now_ms
+
+if TYPE_CHECKING:
+    from ..storage.base import SaStorage
+
+__all__ = ["TempTokenManager", "TempTokenRecord"]
+
+
+@dataclass(frozen=True)
+class TempTokenRecord:
+    value: Any
+    namespace: str
+    created_at: int
+
+    def to_json(self) -> str:
+        return json.dumps(asdict(self), ensure_ascii=False, separators=(",", ":"))
+
+    @classmethod
+    def from_json(cls, raw: str) -> TempTokenRecord | None:
+        try:
+            payload = json.loads(raw)
+            return cls(**payload) if isinstance(payload, dict) else None
+        except (TypeError, ValueError):
+            return None
+
+
+class TempTokenManager:
+    """命名空间隔离的临时 Token 管理器。"""
+
+    def __init__(self, storage: SaStorage, *, key_prefix: str = "satoken:") -> None:
+        self._storage = storage
+        self._key_prefix = key_prefix
+
+    def _key(self, namespace: str, token: str) -> str:
+        return f"{self._key_prefix}security:temp:{namespace}:{token}"
+
+    def _index_key(self, namespace: str, value: str) -> str:
+        digest = hashlib.sha256(value.encode("utf-8")).hexdigest()
+        return f"{self._key_prefix}security:temp-index:{namespace}:{digest}"
+
+    @staticmethod
+    def _validate(namespace: str, timeout: int) -> None:
+        if not namespace or ":" in namespace:
+            raise SecurityException("INVALID_TEMP_NAMESPACE", "namespace 不能为空或包含冒号")
+        if timeout == 0 or timeout < -1:
+            raise SecurityException("INVALID_TEMP_TIMEOUT", "timeout 必须为正数或 -1")
+
+    async def create(
+        self,
+        value: Any,
+        timeout: int,
+        *,
+        namespace: str = "default",
+        record_index: bool = False,
+    ) -> str:
+        """创建临时 Token；``record_index`` 可按字符串业务值反查最新 Token。"""
+        self._validate(namespace, timeout)
+        record = TempTokenRecord(value=value, namespace=namespace, created_at=now_ms())
+        ttl = None if timeout == -1 else timeout
+        for _ in range(12):
+            token = secrets.token_urlsafe(32)
+            if await self._storage.set_if_absent(
+                self._key(namespace, token),
+                record.to_json(),
+                ttl,
+            ):
+                if record_index and isinstance(value, str):
+                    await self._storage.set(self._index_key(namespace, value), token, ttl)
+                return token
+        raise SecurityException("TEMP_TOKEN_ALLOCATION_FAILED", "无法分配唯一临时 token")
+
+    async def parse(self, token: str, *, namespace: str = "default") -> Any | None:
+        raw = await self._storage.get(self._key(namespace, token))
+        record = TempTokenRecord.from_json(raw) if raw else None
+        return record.value if record is not None else None
+
+    async def consume(self, token: str, *, namespace: str = "default") -> Any | None:
+        """原子读取并销毁；并发重复提交时恰好一个调用取得业务值。"""
+        key = self._key(namespace, token)
+        raw = await self._storage.get(key)
+        if raw is None or not await self._storage.compare_and_delete(key, raw):
+            return None
+        record = TempTokenRecord.from_json(raw)
+        if record is None:
+            return None
+        if isinstance(record.value, str):
+            index_key = self._index_key(namespace, record.value)
+            await self._storage.compare_and_delete(index_key, token)
+        return record.value
+
+    async def delete(self, token: str, *, namespace: str = "default") -> bool:
+        key = self._key(namespace, token)
+        raw = await self._storage.get(key)
+        if raw is None:
+            return False
+        record = TempTokenRecord.from_json(raw)
+        deleted = await self._storage.compare_and_delete(key, raw)
+        if deleted and record is not None and isinstance(record.value, str):
+            await self._storage.compare_and_delete(self._index_key(namespace, record.value), token)
+        return deleted
+
+    async def find_token(self, value: str, *, namespace: str = "default") -> str | None:
+        return await self._storage.get(self._index_key(namespace, value))

sa_token/session.py

@@ -0,0 +1,96 @@
+"""Session：挂在账号或单个 token 上的 KV 数据。
+
+Session 对象本身是「远端数据的把手」，每次写操作都会落存储，
+这样多进程部署下不会出现各自持有过期副本的问题。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from .model import SessionData, TerminalInfo
+
+if TYPE_CHECKING:  # pragma: no cover - 仅供类型检查
+    from .storage.base import SaStorage
+
+__all__ = ["SaSession"]
+
+_T = TypeVar("_T")
+_MISSING = object()
+
+
+class SaSession:
+    """会话对象。
+
+    Account-Session（``get_session``）同时承担在线终端索引；
+    Token-Session（``get_token_session``）只放本次登录相关的数据。
+    """
+
+    def __init__(
+        self,
+        storage: SaStorage,
+        key: str,
+        data: SessionData,
+        timeout: int | None,
+    ) -> None:
+        self._storage = storage
+        self._key = key
+        self._data = data
+        self._timeout = timeout
+
+    @property
+    def id(self) -> str:
+        return self._data.id
+
+    @property
+    def create_time(self) -> int:
+        return self._data.create_time
+
+    @property
+    def raw(self) -> SessionData:
+        """底层数据，供核心内部（如终端列表）使用。"""
+        return self._data
+
+    async def get(self, name: str, default: Any = None) -> Any:
+        return self._data.data.get(name, default)
+
+    async def get_typed(
+        self,
+        name: str,
+        expected: type[_T],
+        default: _T | None = None,
+    ) -> _T | None:
+        """按类型取值，类型不符时回落到 ``default``，避免把脏数据带进业务。"""
+        value = self._data.data.get(name, _MISSING)
+        if value is _MISSING or not isinstance(value, expected):
+            return default
+        return value
+
+    async def set(self, name: str, value: Any) -> None:
+        self._data.data[name] = value
+        await self.save()
+
+    async def update(self, values: dict[str, Any]) -> None:
+        self._data.data.update(values)
+        await self.save()
+
+    async def delete(self, name: str) -> None:
+        if self._data.data.pop(name, _MISSING) is not _MISSING:
+            await self.save()
+
+    async def has(self, name: str) -> bool:
+        return name in self._data.data
+
+    async def keys(self) -> list[str]:
+        return list(self._data.data.keys())
+
+    async def clear(self) -> None:
+        self._data.data.clear()
+        await self.save()
+
+    @property
+    def terminal_list(self) -> list[TerminalInfo]:
+        return self._data.terminal_list
+
+    async def save(self) -> None:
+        await self._storage.set(self._key, self._data.to_json(), self._timeout)