funauth 0.1.1__py3-none-any.whl

funauth/__init__.py

@@ -0,0 +1,86 @@
+"""funauth —— 可复用的登录与注册底座。
+
+## 现在有什么
+
+- 密码登录 + 两级角色（`UserRole.ADMIN` / `GUEST`）
+- 邀请码注册：限次、限期、可单独吊销，消耗是原子的
+- bcrypt 密码哈希
+- 表结构以 **mixin** 形式提供，具体表由宿主声明在自己的 `Base` 上
+  （理由见 `funauth.models.mixins` 的模块 docstring）
+
+## 不负责什么
+
+**不依赖任何 web 框架**，也不管 session / cookie / JWT。本包只回答「这个凭据
+对不对、这个人是什么角色」，怎么维持登录态是宿主的事（Starlette 的签名 cookie、
+Redis session、JWT 都行）。抛出来的是 `AuthError` 子类，宿主自己翻译成状态码。
+
+同样不管事务边界：每个方法收一个 `AsyncSession`，由调用方决定什么时候提交。
+
+## 三步接起来
+
+```python
+# 1. 在自己的 Base 上声明表
+import sqlalchemy as sa
+from funauth.models import InviteCodeMixin, UserMixin
+
+class User(UserMixin, TimestampMixin, Base):
+    __tablename__ = "user"
+    __table_args__ = (sa.UniqueConstraint("username", name="uq_user_username"),)
+
+class InviteCode(InviteCodeMixin, TimestampMixin, Base):
+    __tablename__ = "invite_code"
+    __table_args__ = (sa.UniqueConstraint("code", name="uq_invite_code_code"),)
+
+# 2. 建一个单例（放在自己的 services/account.py 之类的绑定模块里）
+from funauth import Accounts
+accounts = Accounts(user_model=User, invite_model=InviteCode)
+
+# 3. 用
+from funauth import BadCredentials
+try:
+    user = await accounts.authenticate(session, username, password)
+except BadCredentials as err:
+    raise HTTPException(401, detail=str(err)) from err
+```
+
+FastAPI 侧完整的两道门（整站要登录 + 后台要管理员）见 README。
+
+## 往后加登录方式
+
+邮箱验证码、短信验证码、QQ / 微信扫码都按同一形状接：各写一个
+`services/*.py` 里的 mixin 挂到 `Accounts` 上，需要存外部身份就再导出一个表
+mixin。`User` 表不用动 —— 多种登录方式共用一个账号，靠一张
+`(provider, external_id) -> user_id` 的身份表关联，而不是给 `User` 不断加列。
+"""
+
+from funauth.enums import UserRole, enum_col
+from funauth.errors import (
+    AuthError,
+    BadCredentials,
+    InviteUnusable,
+    PermissionDenied,
+    UsernameTaken,
+)
+from funauth.models import InviteCodeMixin, TimestampMixin, UserMixin
+from funauth.security import hash_password, verify_password
+from funauth.services import Accounts, describe_invite_status, generate_code
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Accounts",
+    "AuthError",
+    "BadCredentials",
+    "InviteCodeMixin",
+    "InviteUnusable",
+    "PermissionDenied",
+    "TimestampMixin",
+    "UserMixin",
+    "UserRole",
+    "UsernameTaken",
+    "describe_invite_status",
+    "enum_col",
+    "generate_code",
+    "hash_password",
+    "verify_password",
+]

funauth/enums.py

@@ -0,0 +1,36 @@
+"""枚举与枚举列。"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+import sqlalchemy as sa
+
+
+def enum_col(py_enum: type[StrEnum], length: int = 32) -> sa.Enum:
+    """把 Python StrEnum 映射成 VARCHAR，不生成数据库侧的 CHECK 约束。
+
+    不生成 CHECK 是刻意的：枚举加一个成员就要写一条迁移去改约束，而这类
+    枚举（登录方式、角色）本来就是会持续扩张的。
+    """
+    return sa.Enum(
+        py_enum,
+        native_enum=False,
+        create_constraint=False,
+        length=length,
+        values_callable=lambda e: [m.value for m in e],
+    )
+
+
+class UserRole(StrEnum):
+    """账号角色，只有两级。
+
+    `GUEST` 是自助注册能拿到的唯一角色；`ADMIN` 只能由服务端显式创建
+    （`Accounts.create_user`）。
+
+    两级之间**不做数值比较**，判定一律写 `role != ADMIN` 这种精确相等 ——
+    以后真要加第三级（比如只读审计员），枚举的定义顺序不该悄悄决定它的权限。
+    """
+
+    ADMIN = "admin"
+    GUEST = "guest"

funauth/errors.py

@@ -0,0 +1,35 @@
+"""账号域的异常。
+
+全是 `RuntimeError` 子类，**不是 HTTP 异常** —— 这个包不依赖任何 web 框架，
+状态码由调用方翻译（见 README 里 FastAPI 的例子）。异常消息是面向终端用户的
+中文，可以直接当 `detail` 回给前端。
+"""
+
+from __future__ import annotations
+
+
+class AuthError(RuntimeError):
+    """本包所有异常的基类。调用方可以只捕这一个。"""
+
+
+class BadCredentials(AuthError):
+    """用户名不存在、密码不对、或账号已停用。
+
+    三种情况**共用一条消息**，见 `Accounts.authenticate` 的说明。
+    """
+
+
+class UsernameTaken(AuthError):
+    """用户名已被占用。"""
+
+
+class InviteUnusable(AuthError):
+    """邀请码不存在 / 已吊销 / 已过期 / 已用完。
+
+    四种情况共用一条消息：分开报等于把注册接口变成「这个码存不存在」的
+    探测器，攻击者能靠枚举问出哪些码是真的、只是暂时用完了。
+    """
+
+
+class PermissionDenied(AuthError):
+    """已登录，但角色不够。"""

funauth/models/__init__.py

@@ -0,0 +1,14 @@
+"""表结构（mixin）与可移植列类型。"""
+
+from funauth.models.mixins import InviteCodeMixin, TimestampMixin, UserMixin
+from funauth.models.types import PkType, UTCDateTime, utcnow, uuid7
+
+__all__ = [
+    "InviteCodeMixin",
+    "PkType",
+    "TimestampMixin",
+    "UTCDateTime",
+    "UserMixin",
+    "utcnow",
+    "uuid7",
+]

funauth/models/mixins.py

@@ -0,0 +1,96 @@
+"""表结构以 **mixin** 形式提供，具体表由宿主项目声明。
+
+## 为什么不直接导出现成的模型类
+
+一个 declarative 模型必须绑在某个 `Base`（也就是某个 `MetaData`）上。如果本包
+自带 `Base`，宿主项目的库里就有两套 `MetaData`：
+
+- `Base.metadata.create_all()` 建不出本包的表，宿主的测试夹具得额外记得建一遍；
+- Alembic 的 `target_metadata` 得写成列表，否则 autogenerate 会兴冲冲地生成
+  「DROP TABLE user」—— 它看不见那张表的定义，只看见库里多了一张表；
+- 宿主自己的表想外键引用 `user.id` 时跨 `MetaData`，得退化成字符串引用。
+
+导出 mixin 就没这些问题：表长在宿主的 `Base` 上，一套 `MetaData`、一条迁移链、
+外键照常写。代价是宿主要自己写一行类声明和 `__table_args__`，很便宜。
+
+```python
+from funauth.models import InviteCodeMixin, UserMixin
+
+class User(UserMixin, TimestampMixin, Base):
+    __tablename__ = "user"
+    __table_args__ = (sa.UniqueConstraint("username", name="uq_user_username"),)
+```
+
+唯一约束刻意**不**放进 mixin：约束名进迁移、进 `ON CONFLICT`，宿主得能看见也能
+改名（已经建好的库里那个名字是什么样就得是什么样，不能由本包的版本决定）。
+
+## 时间列
+
+`TimestampMixin` 这里也给了一份，但宿主已经有自己的就用自己的 —— 两边 DDL
+一致（都是 `DateTime(timezone=True)`），混用不需要迁移。
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+import sqlalchemy as sa
+from sqlalchemy.orm import Mapped, mapped_column
+
+from funauth.enums import UserRole, enum_col
+from funauth.models.types import PkType, UTCDateTime, utcnow, uuid7
+
+
+class TimestampMixin:
+    """创建 / 更新时间。默认值在 Python 侧生成，不依赖数据库函数。"""
+
+    created_at: Mapped[datetime] = mapped_column(
+        UTCDateTime, default=utcnow, nullable=False, index=True
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        UTCDateTime, default=utcnow, onupdate=utcnow, nullable=False
+    )
+
+
+class UserMixin:
+    """登录账号：用户名 + bcrypt 密码哈希 + 角色 + 启用标记。
+
+    不存明文密码，也不做可逆加密。停用走 `is_active` 而不是删除行 —— 否则
+    session / token 里存的 user_id 会变成悬空引用，而那个 id 以后可能被别的
+    新账号复用，等于把旧会话悄悄接到新账号上。
+    """
+
+    id: Mapped[uuid.UUID] = mapped_column(PkType, primary_key=True, default=uuid7)
+    username: Mapped[str] = mapped_column(sa.String(64), nullable=False)
+    #: bcrypt 哈希（含盐）
+    password_hash: Mapped[str] = mapped_column(sa.String(128), nullable=False)
+    #: 默认取 `GUEST` 而不是 `ADMIN`：漏传时往最小权限掉，而不是凭空多出一个
+    #: 管理员。要建管理员必须显式写出来（`Accounts.create_user`）。
+    role: Mapped[UserRole] = mapped_column(
+        enum_col(UserRole, length=16), nullable=False, default=UserRole.GUEST
+    )
+    is_active: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, default=True)
+
+
+class InviteCodeMixin:
+    """一张注册邀请码：码值 + 可用次数 + 过期时间 + 启用标记。
+
+    「还能不能用」是三个条件的合取，判定只许写在 `Accounts.consume_invite` 的
+    那条条件 UPDATE 里 —— 在别处重新拼一遍等于埋一个会和它悄悄分叉的副本。
+    """
+
+    id: Mapped[uuid.UUID] = mapped_column(PkType, primary_key=True, default=uuid7)
+    #: 码值本身。只取大写字母和数字、去掉易混的 0O1Il，方便口头/截图转述
+    code: Mapped[str] = mapped_column(sa.String(32), nullable=False)
+    #: 总共能换出几个账号
+    max_uses: Mapped[int] = mapped_column(sa.Integer, nullable=False, default=1)
+    #: 已经换出去几个。只由 `consume_invite` 的条件 UPDATE 原子递增
+    used_count: Mapped[int] = mapped_column(sa.Integer, nullable=False, default=0)
+    #: 空 = 永不过期
+    expires_at: Mapped[datetime | None] = mapped_column(UTCDateTime)
+    #: 吊销走标记而不是删行 —— 和 `UserMixin.is_active` 同一个理由：保留「这张码
+    #: 换出去过几个账号」的痕迹，删掉就查不出来了
+    is_active: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, default=True)
+    #: 备注，给签发的人自己记「这张给谁的」
+    note: Mapped[str | None] = mapped_column(sa.Text)

funauth/models/types.py

@@ -0,0 +1,74 @@
+"""可移植的列类型与主键生成。
+
+宿主项目往往已经有自己的一套（funflix 就有），那就用宿主的 —— 这里提供的是
+给**还没有**的项目用的默认实现。两边 DDL 刻意保持一致（`PkType` 都是
+`sa.Uuid`、时间列都是 `DateTime(timezone=True)`），所以换过来不需要写迁移。
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+import sqlalchemy as sa
+
+#: 主键。PostgreSQL 上是原生 uuid 列，SQLite 上退化成 CHAR(32) 存十六进制。
+#: 客户端生成（见 `uuid7`），不依赖数据库分配。
+PkType = sa.Uuid(as_uuid=True)
+
+
+def utcnow() -> datetime:
+    """当前 UTC 时间（tz-aware）。"""
+    return datetime.now(UTC)
+
+
+def uuid7() -> uuid.UUID:
+    """时间排序主键（RFC 9562 UUIDv7）：48 位毫秒时间戳 + 74 位随机数。
+
+    字典序等于生成顺序，所以 `ORDER BY id DESC` 就是「最新优先」，不用再加一列
+    时间索引；同时全局唯一，多机并发生成不会撞号。
+
+    标准库要到 3.14 才有 `uuid.uuid7()`，本包下限是 3.12，这里自己实现。
+    """
+    ts_ms = time.time_ns() // 1_000_000
+    rand = int.from_bytes(os.urandom(10), "big")
+    rand_a = (rand >> 62) & 0xFFF
+    rand_b = rand & 0x3FFFFFFFFFFFFFFF
+    value = ((ts_ms & 0xFFFFFFFFFFFF) << 80) | (0x7 << 76) | (rand_a << 64) | (0b10 << 62) | rand_b
+    return uuid.UUID(int=value)
+
+
+class UTCDateTime(sa.types.TypeDecorator):
+    """始终以 UTC-aware datetime 进出的 DateTime。
+
+    SQLite 没有原生时间类型，`DateTime(timezone=True)` 读回来是 naive 的，而
+    PostgreSQL 读回来是 aware 的 —— 不处理的话同一份代码在两个库上行为不一致。
+    这里在绑定期强制转 UTC、在返回期补齐 tzinfo，抹平差异。
+    """
+
+    impl = sa.DateTime(timezone=True)
+    cache_ok = True
+
+    def process_bind_param(self, value: datetime | None, dialect: Any) -> datetime | None:
+        """写库前把值统一转成 UTC。
+
+        Raises:
+            ValueError: 传入 naive datetime。宁可当场报错，也不猜它是哪个时区 ——
+                猜错会让时间悄悄偏移几小时且永远查不出来。
+        """
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError(f"拒绝写入 naive datetime: {value!r}，请传带 tzinfo 的值")
+        return value.astimezone(UTC)
+
+    def process_result_value(self, value: datetime | None, dialect: Any) -> datetime | None:
+        """读库后补齐 tzinfo，保证无论哪个数据库取出来都是 UTC-aware 的。"""
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            return value.replace(tzinfo=UTC)
+        return value.astimezone(UTC)

funauth/security.py

@@ -0,0 +1,40 @@
+"""密码哈希。
+
+直接用 `bcrypt`，不引入 passlib —— passlib 已多年未发版，对 bcrypt 4.x 的
+`__about__` 变更没跟上，社区里一堆关于它报 warning/崩溃的 issue。bcrypt 库
+本身的 API 就两个函数，没有再包一层的必要。
+"""
+
+from __future__ import annotations
+
+import bcrypt
+
+
+def hash_password(password: str) -> str:
+    """对明文密码做 bcrypt 哈希。
+
+    Args:
+        password: 用户输入的明文密码。
+
+    Returns:
+        可直接落库的 bcrypt 哈希字符串（含算法标识与随机 salt）。
+    """
+    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    """校验明文密码是否与已存储的哈希匹配。
+
+    Args:
+        password: 登录时用户输入的明文密码。
+        password_hash: `hash_password` 生成并落库的哈希值。
+
+    Returns:
+        匹配返回 `True`；不匹配，或 `password_hash` 本身不是合法的 bcrypt
+        哈希格式（例如历史迁移遗留的明文）时返回 `False`。
+    """
+    try:
+        return bcrypt.checkpw(password.encode("utf-8"), password_hash.encode("utf-8"))
+    except ValueError:
+        # 哈希格式不对（比如库迁移时手滑存了明文）：当作校验失败而不是 500
+        return False

funauth/services/__init__.py

@@ -0,0 +1,34 @@
+"""`Accounts` 门面。
+
+各登录方式一个 mixin，按需组合。目前只有密码登录（`PasswordMixin`）和邀请码
+注册（`InviteMixin`）；邮箱验证码、短信验证码、QQ / 微信扫码往后按同一形状加
+——各自一个 mixin + 各自的 mixin 表，挂上来即可，`User` 表不用动。
+"""
+
+from funauth.services.base import AccountsBase
+from funauth.services.invite import (
+    InviteMixin,
+    describe_invite_status,
+    generate_code,
+)
+from funauth.services.password import PasswordMixin
+
+
+class Accounts(InviteMixin, PasswordMixin, AccountsBase):
+    """账号域的全部操作。宿主建一个单例，别处 import 它。
+
+    ```python
+    accounts = Accounts(user_model=User, invite_model=InviteCode)
+    user = await accounts.authenticate(session, "someone", "pw")
+    ```
+    """
+
+
+__all__ = [
+    "Accounts",
+    "AccountsBase",
+    "InviteMixin",
+    "PasswordMixin",
+    "describe_invite_status",
+    "generate_code",
+]

funauth/services/base.py

@@ -0,0 +1,60 @@
+"""`Accounts` 门面的基座：持有宿主的模型类。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class AccountsBase:
+    """把宿主的模型类绑进来，各登录方式的 mixin 共用。
+
+    ## 为什么是一个实例而不是一组模块级函数
+
+    本包不自带表（见 `funauth.models.mixins`），所以每个函数都得知道宿主的
+    `User` / `InviteCode` 类是哪个。三种办法：
+
+    1. 每个函数多一个 `user_model` 参数 —— 调用方每次都要传，噪音大且传错了
+       编译期发现不了；
+    2. 模块级全局变量 + `configure()` —— import 顺序一变就是个 `None`，而且
+       同一个进程里没法接两套表（测试、多租户都会撞）；
+    3. **实例持有**（本方案）—— 宿主在自己的绑定模块里建一个单例，别处 import
+       它。没有全局可变状态，测试里想换表就再建一个实例。
+
+    ## 为什么不自己管 session
+
+    每个方法都收一个 `AsyncSession`。宿主的事务边界各不相同（FastAPI 一个请求
+    一个 session、CLI 一条命令一个、后台任务一批一个），本包无权决定。
+
+    涉及多步写入的方法（`register_with_invite`）在内部**不提交**中间状态，让
+    整串操作共享调用方的事务 —— 理由见那个方法的 docstring。
+    """
+
+    def __init__(self, *, user_model: Any, invite_model: Any | None = None) -> None:
+        """
+        Args:
+            user_model: 宿主声明的 User 类，必须带 `UserMixin` 的那几列。
+            invite_model: 宿主声明的 InviteCode 类。不打算用邀请码注册可以不传，
+                传 `None` 时调用邀请码相关方法会 `AttributeError` —— 刻意不做
+                优雅降级，那只会把「忘了配」变成运行时的静默失败。
+        """
+        self.user_model = user_model
+        self.invite_model = invite_model
+
+    async def get_by_username(self, session: AsyncSession, username: str) -> Any | None:
+        """按用户名取账号，没有返回 `None`。"""
+        return await session.scalar(
+            select(self.user_model).where(self.user_model.username == username)
+        )
+
+    async def get_by_id(self, session: AsyncSession, user_id: Any) -> Any | None:
+        """按主键取账号，没有返回 `None`。会话校验用。"""
+        return await session.get(self.user_model, user_id)
+
+    async def list_users(self, session: AsyncSession) -> list[Any]:
+        """列出全部账号，按用户名排序。"""
+        return list(
+            await session.scalars(select(self.user_model).order_by(self.user_model.username))
+        )

funauth/services/invite.py

@@ -0,0 +1,167 @@
+"""邀请码：签发、消耗、吊销，以及凭码注册。"""
+
+from __future__ import annotations
+
+import secrets
+from datetime import datetime, timedelta
+from typing import Any
+
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from funauth.enums import UserRole
+from funauth.errors import InviteUnusable
+from funauth.models.types import utcnow
+from funauth.services.password import PasswordMixin
+
+#: 码值字母表：大写字母 + 数字，去掉 `0O1I` 和小写 `l`。这些码要靠人念、靠
+#: 截图转述，`0/O` 和 `1/I/l` 认错的概率太高，与其让人反复试不如直接不用。
+ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+CODE_LENGTH = 8
+
+#: 不存在 / 已吊销 / 已过期 / 已用完共用这一句，理由见 `InviteUnusable`。
+UNUSABLE = "邀请码无效或已用完"
+
+
+def generate_code() -> str:
+    """生成一个码值。用 `secrets` 而不是 `random` —— 这是凭据，不是随机数。"""
+    return "".join(secrets.choice(ALPHABET) for _ in range(CODE_LENGTH))
+
+
+def describe_invite_status(code: Any, *, now: datetime | None = None) -> str:
+    """这张码当前处于什么状态，给管理界面 / CLI 显示用。
+
+    判定条件和 `InviteMixin.consume_invite` 的 WHERE 一一对应。写歪了不会报错
+    （它只负责展示），但会出现「列表里写着可用、注册却说无效」这种最难查的
+    不一致，所以两处要一起改。
+    """
+    moment = now or utcnow()
+    if not code.is_active:
+        return "已吊销"
+    if code.expires_at is not None and code.expires_at <= moment:
+        return "已过期"
+    if code.used_count >= code.max_uses:
+        return "已用完"
+    return "可用"
+
+
+class InviteMixin(PasswordMixin):
+    """邀请码的生命周期 + 凭码自助注册。
+
+    继承 `PasswordMixin` 是因为注册最终要落一个密码账号（复用 `_insert`）。
+    """
+
+    async def issue_invite(
+        self,
+        session: AsyncSession,
+        *,
+        max_uses: int = 1,
+        expires_in_days: int | None = None,
+        note: str | None = None,
+    ) -> Any:
+        """签发一张邀请码并落库。
+
+        Args:
+            max_uses: 这张码总共能换出几个账号。
+            expires_in_days: 多少天后过期；`None` 表示永不过期。
+            note: 备注，给签发的人自己记「这张给谁的」。
+
+        Returns:
+            已落库的邀请码对象，`code` 字段是生成出来的码值。
+        """
+        expires_at = utcnow() + timedelta(days=expires_in_days) if expires_in_days else None
+        code = self.invite_model(
+            code=generate_code(),
+            max_uses=max_uses,
+            expires_at=expires_at,
+            note=note,
+        )
+        session.add(code)
+        await session.commit()
+        await session.refresh(code)
+        return code
+
+    async def consume_invite(
+        self, session: AsyncSession, code: str, *, now: datetime | None = None
+    ) -> None:
+        """占用这张码的一个名额。
+
+        **一条条件 UPDATE 搞定，不许先 SELECT 判断再 UPDATE。** 先查后改在并发
+        下会把一张 `max_uses=1` 的码兑出两个账号：两个请求都读到
+        `used_count == 0`、都认为还有名额，然后各自 `+1`。这里把「还能不能用」
+        整个塞进 WHERE，由数据库保证只有一个人能把它从 0 改到 1，`rowcount`
+        就是裁决结果。
+
+        **不自己提交** —— 调用方（`register_with_invite`）要让「扣名额」和
+        「建账号」同生共死：建号那步因为用户名撞车失败时，名额必须跟着回滚，
+        否则一张码会因为别人手滑输了个重名用户名而白白少一个名额。
+
+        Raises:
+            InviteUnusable: 码不存在、已吊销、已过期，或名额已用完。
+        """
+        moment = now or utcnow()
+        model = self.invite_model
+        result = await session.execute(
+            update(model)
+            .where(
+                model.code == code,
+                model.is_active.is_(True),
+                model.used_count < model.max_uses,
+                (model.expires_at.is_(None)) | (model.expires_at > moment),
+            )
+            .values(used_count=model.used_count + 1, updated_at=moment)
+            .execution_options(synchronize_session=False)
+        )
+        if not result.rowcount:
+            raise InviteUnusable(UNUSABLE)
+
+    async def revoke_invite(self, session: AsyncSession, code: str) -> bool:
+        """吊销一张码。重复吊销是幂等的。
+
+        Returns:
+            码存在返回 `True`，不存在返回 `False`。
+        """
+        result = await session.execute(
+            update(self.invite_model)
+            .where(self.invite_model.code == code)
+            .values(is_active=False, updated_at=utcnow())
+            .execution_options(synchronize_session=False)
+        )
+        await session.commit()
+        return bool(result.rowcount)
+
+    async def list_invites(self, session: AsyncSession) -> list[Any]:
+        """列出全部邀请码，新的在前。"""
+        return list(
+            await session.scalars(
+                select(self.invite_model).order_by(self.invite_model.created_at.desc())
+            )
+        )
+
+    @staticmethod
+    def describe_invite_status(code: Any, *, now: datetime | None = None) -> str:
+        """见模块级的同名函数。"""
+        return describe_invite_status(code, now=now)
+
+    async def register_with_invite(
+        self, session: AsyncSession, username: str, password: str, invite_code: str
+    ) -> Any:
+        """凭邀请码自助注册一个账号。
+
+        **角色硬编码成 `GUEST`，不接受调用方指定。** 这是这个方法存在的意义：
+        注册这条路径通常对公网开放，一旦让它能产出 `ADMIN`，邀请码外泄就等于
+        交出后台；而现在最坏结果只是多几个普通用户。要建管理员走 `create_user`。
+
+        扣名额和建账号在**同一个事务**里：用户名撞车时 `consume_invite` 已经
+        递增的 `used_count` 跟着回滚 —— 不然别人手滑输了个重名用户名，这张码
+        就白少一次，而签发的人完全看不出为什么。
+
+        Raises:
+            InviteUnusable: 码不存在 / 已吊销 / 已过期 / 已用完。
+            UsernameTaken: 用户名已被占用。
+        """
+        await self.consume_invite(session, invite_code)
+        user = await self._insert(session, username, password, UserRole.GUEST)
+        await session.commit()
+        await session.refresh(user)
+        return user

funauth/services/password.py

@@ -0,0 +1,109 @@
+"""密码登录与建号。
+
+这是本包目前唯一实现了的登录方式。往后加邮箱验证码、短信验证码、QQ / 微信
+扫码，各写一个同形状的 mixin 挂到 `Accounts` 上，共用这里的 `User` 表和
+`AccountsBase.get_by_username` 等基础查询。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from funauth.enums import UserRole
+from funauth.errors import BadCredentials, PermissionDenied, UsernameTaken
+from funauth.security import hash_password, verify_password
+from funauth.services.base import AccountsBase
+
+#: 用户名不存在 / 密码不对 / 账号停用，三种都回这一句。见 `authenticate`。
+BAD_CREDENTIALS = "用户名或密码不正确"
+
+
+class PasswordMixin(AccountsBase):
+    """密码登录、角色判定、建号改密。"""
+
+    async def authenticate(self, session: AsyncSession, username: str, password: str) -> Any:
+        """校验用户名密码，返回对应账号。
+
+        **不区分「用户不存在」和「密码不对」**，连「账号已停用」也归到同一条
+        消息里。分开报的话这个接口就是个用户名枚举器：拿字典刷一遍，回「密码
+        不对」的那些就是真实存在的账号，接下来只用对这几个爆破密码。
+
+        停用账号也混进去是同一个道理 —— 「这个用户被停用了」同样确认了它存在。
+        真正需要知道区别的是运维自己，而运维看得到数据库。
+
+        Raises:
+            BadCredentials: 上述任一种情况。
+        """
+        user = await self.get_by_username(session, username)
+        if user is None or not user.is_active:
+            raise BadCredentials(BAD_CREDENTIALS)
+        if not verify_password(password, user.password_hash):
+            raise BadCredentials(BAD_CREDENTIALS)
+        return user
+
+    @staticmethod
+    def require_role(user: Any, role: UserRole) -> None:
+        """要求 `user` 正好是 `role` 这个角色，不然抛异常。
+
+        用精确相等而不是「大于等于」：`UserRole` 只有两级，而枚举的定义顺序
+        不该悄悄决定权限高低（理由见 `UserRole` 的 docstring）。以后真有三级，
+        这里要显式写出每级能干什么，而不是靠排序蒙对。
+
+        Raises:
+            PermissionDenied: 角色不匹配。
+        """
+        if user.role != role:
+            raise PermissionDenied("需要管理员权限")
+
+    async def create_user(
+        self, session: AsyncSession, username: str, password: str, role: UserRole
+    ) -> Any:
+        """服务端直接建号，角色由调用方指定。自助注册请走 `register_with_invite`。
+
+        Raises:
+            UsernameTaken: 用户名已被占用。
+        """
+        user = await self._insert(session, username, password, role)
+        await session.commit()
+        await session.refresh(user)
+        return user
+
+    async def set_password(self, session: AsyncSession, username: str, password: str) -> bool:
+        """重置密码。用户不存在返回 `False`。"""
+        user = await self.get_by_username(session, username)
+        if user is None:
+            return False
+        user.password_hash = hash_password(password)
+        await session.commit()
+        return True
+
+    async def set_active(self, session: AsyncSession, username: str, active: bool) -> bool:
+        """启用 / 停用账号。用户不存在返回 `False`。"""
+        user = await self.get_by_username(session, username)
+        if user is None:
+            return False
+        user.is_active = active
+        await session.commit()
+        return True
+
+    async def _insert(
+        self, session: AsyncSession, username: str, password: str, role: UserRole
+    ) -> Any:
+        """查重后插入，**不提交**。
+
+        这里的查重**挡不住并发**（两个请求可以都查到「没占用」然后都插），真正
+        的保证是宿主表上的唯一约束。先查一遍只是为了在绝大多数情况下回一句人能
+        看懂的「用户名已存在」，而不是把 IntegrityError 原样抛给调用方。
+        """
+        taken = await session.scalar(
+            select(self.user_model.id).where(self.user_model.username == username)
+        )
+        if taken is not None:
+            raise UsernameTaken(f"用户名已存在：{username}")
+        user = self.user_model(username=username, password_hash=hash_password(password), role=role)
+        session.add(user)
+        await session.flush()
+        return user

funauth-0.1.1.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.5
+Name: funauth
+Version: 0.1.1
+Summary: 可复用的登录与注册底座：密码登录、角色、邀请码注册（SQLAlchemy 异步）
+Project-URL: Organization, https://github.com/farfarfun
+Project-URL: Repository, https://github.com/farfarfun/funauth
+Project-URL: Releases, https://github.com/farfarfun/funauth/releases
+Author-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
+Maintainer-email: 牛哥 <niuliangtao@qq.com>, farfarfun <farfarfun@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,auth,invite,login,sqlalchemy
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: bcrypt>=4.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Description-Content-Type: text/markdown
+
+# funauth

funauth-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+funauth/__init__.py,sha256=snw26Tx_XVlqiv4tbdG-KCG3P9HZTm1Wrfv2dSnXo54,2893
+funauth/enums.py,sha256=LzPA0PEY7ZXpzsXidwlGOZz8_J4AirVukl5dW8iAJD0,1092
+funauth/errors.py,sha256=Ring0cHjKde-ldy_SONVJFDdRGMqXyUXSOccnfzEcOg,1068
+funauth/security.py,sha256=h_HkzriOZu4uPc4Av_uM-NZdSdNwqlUm8lK9ntLmlUM,1373
+funauth/models/__init__.py,sha256=gcG5yoaUGP4eUidGQUR-hnSqXYFjPQnd9JwVuY5pjYE,334
+funauth/models/mixins.py,sha256=1u-_C2nDAM_xQeg-E4qfyPKJXpTIHhni-6_wsfcoooY,4542
+funauth/models/types.py,sha256=wVA9Irmg0Shs98S87Abu9TRAbcAAkB-tE2smIdTyATQ,2877
+funauth/services/__init__.py,sha256=nFgZorlOjBh-W5E5vX0kzgowUDdIL5GF2Ugt9DbrCX0,976
+funauth/services/base.py,sha256=qSZUtYBwVeNJoHpFxI8-poyRIkn-yVQUUMnx789nxKM,2791
+funauth/services/invite.py,sha256=jQnNgr7YkyjkmJ9qKbh4GtQSys7tcElCBLcurnPhyw8,6714
+funauth/services/password.py,sha256=SOn1jJBV5sjysdhRLsoJy0Vk_nK18asyfMaJyVYv2Jg,4641
+funauth-0.1.1.dist-info/METADATA,sha256=dSpT579ZsnPB1VMSdZS9eoS6QFJOnE7n3VncmlNNM8Q,1083
+funauth-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+funauth-0.1.1.dist-info/licenses/LICENSE,sha256=BvvS-yeQjeaYgHQW2Vh7Msedpzoc-r7mnjNCpqUUbgM,1066
+funauth-0.1.1.dist-info/RECORD,,

funauth-0.1.1.dist-info/WHEEL

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

funauth-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 farfarfun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.