labull-framework 0.1.0__py3-none-any.whl

labull_framework/__init__.py

@@ -0,0 +1,8 @@
+"""Labull Framework —— 一个可选的 Django app。
+
+只有两块业务逻辑：Authing 登录、magic block。
+其余一律走 Django 原生（用户模型、会话、权限、admin、文件字段、迁移）。
+
+🔴 本文件**什么都不 import**：子模块之间的依赖是单向的，在这里 import 会在
+"配置还没加载完"的时刻把模型拉起来（Django 里最难查的一类循环 import）。
+"""

labull_framework/admin.py

@@ -0,0 +1,63 @@
+"""Django admin 的注册处 —— 这个库**唯一**的管理界面。
+
+🔴 它就是 Django 原生的那一套：用户 / 组 / 权限的日常维护白拿，我们不写任何自己的管理页面。
+🔴 **块的代码在 admin 里只读**：它只能从 magic block 控制台写进去，因为那里有"保存即校验"那一关
+   （`ast` + 子进程试加载）。admin 里放开编辑表单，就等于从 Django 的默认表单往库里塞
+   **未经校验、之后会被 `exec` 执行**的代码，把"体检不过就停用"这套机制绕开。
+   要看、要筛、要重跑体检 —— admin 全都能做；要改代码 —— 去控制台。
+"""
+
+from __future__ import annotations
+
+from django.contrib import admin
+
+from .magic_block import health
+from .models import MagicBlock, User
+
+
+@admin.register(User)
+class UserAdmin(admin.ModelAdmin):
+    """用户：Django 自带的那份管身份，我们只把自加的字段摆进去。
+
+    ⚠️ `username` 装的是 Authing 的 `sub`（登录时同步进来的），所以它**只读** ——
+    改它等于把这一行与那个身份切开。
+    """
+
+    list_display = ('username', 'work_id', 'name', 'is_staff', 'is_active', 'last_login')
+    list_filter = ('is_staff', 'is_superuser', 'is_active')
+    search_fields = ('username', 'work_id', 'name')
+    ordering = ('-date_joined',)
+    readonly_fields = ('username', 'last_login', 'date_joined')
+    fieldsets = (
+        (None, {'fields': ('username', 'password')}),
+        ('身份', {'fields': ('work_id', 'name', 'email')}),
+        ('权限', {'fields': ('is_active', 'is_staff', 'is_superuser', 'groups', 'user_permissions')}),
+        ('时间', {'fields': ('last_login', 'date_joined')}),
+    )
+
+
+@admin.register(MagicBlock)
+class MagicBlockAdmin(admin.ModelAdmin):
+    """功能块：看状态、筛、重跑体检 —— **改代码不在这里**（见文件头）。"""
+
+    list_display = ('id', 'module', 'name', 'enabled', 'health_checked_at', 'updated_at')
+    list_filter = ('module', 'enabled')
+    search_fields = ('id', 'name', 'brief')
+    ordering = ('module', 'name')
+    # 🔴 全字段只读：块的正文与体检结论都由控制台 / 体检模块写。
+    readonly_fields = tuple(field.name for field in MagicBlock._meta.fields)
+    actions = ('rerun_health',)
+
+    @admin.action(description='重新体检选中的块')
+    def rerun_health_action(self, request, queryset):
+        """只体检选中的那几块（全量体检在每次 `migrate` 与进程启动时各跑一次）。"""
+        summary = health.check_all_blocks(list(queryset.values_list('id', flat=True)))
+        self.message_user(
+            request,
+            f'体检 {summary["checked"]} 块：通过 {summary["passed"]}，停用 {summary["disabled"]}。',
+        )
+        return None
+
+    def has_add_permission(self, request) -> bool:
+        # 块的 uuid 由开发者在前端写死（`<MagicBlockHost uuid="…">`），admin 里"新增"没有意义。
+        return False

labull_framework/apps.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class LabullConfig(AppConfig):
+    """这个 app 的登记项。
+
+    🔴 `ready()` 里**只挂一个钩子，不碰数据库**：Django 对"在 `ready()` 里查库"会明确警告
+    （`Accessing the database during app initialization is discouraged`），而且新项目第一次
+    `migrate` 时表还不存在 —— 那时查库会让**整个命令**起不来。
+
+    🔴 启动时要做的两件事（补管理员 → 全量体检）在 `wsgi.py` 里一行显式调用：
+        ```python
+        from labull_framework.magic_block.health import startup_once
+        startup_once()
+        ```
+        那一行是**契约**（函数名与签名都不要改）：`runserver` / gunicorn / uwsgi / ASGI
+        都从那里进来，所以它天然是"每个进程一次"的地方。
+    ⚠️ 它**不是** `post_migrate` 的替代：那个只在迁移之后发（管"库刚被改过"），
+        而启动体检只有 `startup_once()` 能做。
+    """
+
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'labull_framework'
+    verbose_name = 'Labull Framework'
+
+    def ready(self) -> None:
+        # 延迟 import：此刻 app 注册表已经就绪，但避免模块级 import 造成加载顺序问题。
+        # 钩子是"库自己正常工作"的一部分（体检库里存着的块），**不是**对使用者项目的检查。
+        from .magic_block import health
+
+        health.install_hook()

labull_framework/auth/__init__.py

@@ -0,0 +1,4 @@
+# 🔴 本文件故意是空的：这里**不许 import 任何子模块**。
+# 原因：子模块会 import 模型，而 Django 加载 app 时会先 import 本包 ——
+# 在配置（`AUTH_USER_MODEL` / `INSTALLED_APPS`）读完之前碰模型，就是那个
+# `AppRegistryNotReady` 的循环 import。要用哪一个子模块，就写全路径去 import 它。

labull_framework/auth/backend.py

@@ -0,0 +1,144 @@
+"""OIDC 认证后端：把回调那一步**已经验过的** claims 变成一行 `User`。
+
+🔴 **为什么还要一个认证后端**：OIDC 不是 Django 认识的密码后端（没有 `password` 可比），
+   但我们要的只是它的 `authenticate()` 这一步 —— **会话仍然完全交给 Django 的 `login()`**，
+   所以这个类**不碰会话**、也**不校验 token**（验签是 `sso.py` 的事，视图验完才把 claims 送进来）。
+
+🔴 **权限一个字都不给**：Django 有 `is_staff` / `is_superuser` / `Group` / `Permission`，
+   登录这件事只负责"你是谁"；"你能干什么"由管理员在 admin 里给。
+   所以新建的用户三个布尔位就是 `is_staff=False` / `is_superuser=False` / `is_active=True`。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from django.contrib.auth import get_user_model
+from django.db import IntegrityError, transaction
+
+logger = logging.getLogger(__name__)
+
+#: 缺工号时那句固定报文。
+#: 🔴 没有工号就**拒登**（不落库）：工号是"这个人在组织里是谁"，缺了它这条身份没有意义，
+#: 而"先放进来再补"会让库里留下一批永远要人回头去认的账号。
+NO_WORK_ID_TEXT = (
+    '你的账号在 Authing 里没有 `username`（工号），不放行 —— '
+    '请管理员在 Authing 里给这个账号补上工号后重试。'
+)
+
+#: 老用户每次登录只允许被刷新的两列。🔴 抄进 `update_fields` 的那一份必须是**白名单**：
+#: 一旦顺手写成"全部字段"，管理员在 admin 里设的 `is_staff` / 组 / 权限就会被一次登录冲掉。
+UPDATABLE_FIELDS: tuple[str, ...] = ('name', 'work_id')
+
+
+class LoginRejected(Exception):
+    """这次登录不放行，**一个字都不落库**，报文直接给用户看（视图回 401）。"""
+
+
+class NoWorkId(LoginRejected):
+    """缺工号（`username`）那一支。
+
+    ⚠️ 单独一个类型只是为了让人读日志时一眼看出是哪一支；视图对两者的处理是同一件
+       （401 + 原样报文），所以它们共一个父类、只在视图里 catch 一次。
+    """
+
+
+def _text(value: Any) -> str:
+    """把一个 claim 当字符串用（不是字符串就算空）。
+
+    ⚠️ 不用 `str()` 硬转：claim 完全由 IdP 决定，`str(None)` 会得到 `'None'` ——
+    那是一个**看起来像工号**的东西，它会进唯一索引，然后下一个人永远登不进来。
+    """
+    return value if isinstance(value, str) else ''
+
+
+def _work_id_of(source: Any) -> str:
+    """取工号（**只认 `username`**）。
+
+    🔴 只认这一个键：Authing 为 workId 特设的就是它；OIDC 标准里的 `preferred_username`
+       常常是邮箱 / 昵称，收进来就等于让一个不是工号的东西占住唯一索引。
+    """
+    return _text(source.get('username')).strip() if isinstance(source, dict) else ''
+
+
+def _claim_keys_of(source: Any) -> list[str]:
+    """一份 claim 里**真实出现**的键名（排序后）。
+
+    🔴 只列键名、永不列值：值是 PII（姓名 / 邮箱 / 工号），而这句话要回给浏览器、也会进日志。
+       键名恰好回答得了那个真问题 ——"工号该补在哪个键上"。
+    """
+    return sorted(str(key) for key in source) if isinstance(source, dict) else []
+
+
+class OidcBackend:
+    """`AUTHENTICATION_BACKENDS` 里那一个；`claims` / `userinfo` 由回调视图传进来。"""
+
+    def authenticate(
+        self, request: Any, claims: dict | None = None, userinfo: dict | None = None, **kwargs: Any
+    ):
+        """按 claims 造 / 更新用户行，回 `User` 或 `None`（拒登时抛 `LoginRejected`）。
+
+        ⚠️ 视图已经验过签名，这里只看 claim 的值 —— 再验一次会变成"两处口径"。
+        🔴 不认识的凭据（`username` / `password` 那类）一律回 `None`：`authenticate()` 是
+           Django 的框架出口，凭据不对就抛异常的后端会让 `client.login()` 这类正常调用直接 500。
+        """
+        if claims is None and userinfo is None:
+            # 没有我们认的那两样东西 ⇒ 这不是能靠 OIDC 验的身份（交给别的后端或直接失败）。
+            return None
+        return self._upsert(claims, userinfo)
+
+    def get_user(self, user_id: Any):
+        """按主键取人 —— `AuthenticationMiddleware` 每个请求都靠它把会话里的 id 换回 `User`。
+
+        🔴 少了这个方法，登录那一刻是好的，**下一个请求就 500**（框架在恢复身份时会找它）。
+        ⚠️ 不查 `is_active`：账号停用该由 Django 的 `user_can_authenticate` 判（它就在
+           `login()` / `get_user()` 那条路上），在这里再判一次就是同一条规矩两处口径。
+        """
+        return get_user_model().objects.filter(pk=user_id).first()
+
+    def _upsert(self, claims: dict | None, userinfo: dict | None):
+        """真正的映射（见模块头）：`sub` → `username`、`username` → `work_id`、`name` → `name`。"""
+        data = claims if isinstance(claims, dict) else {}
+        profile = userinfo if isinstance(userinfo, dict) else {}
+        sub = _text(data.get('sub')).strip()
+        if not sub:
+            # 🔴 连"是谁"都定不下来 ⇒ 一个字都不落库（`sub` 是唯一凭据）。
+            raise LoginRejected('id_token 里没有 sub，无法定位用户。')
+
+        # 🔴 工号先看 id_token、再看用户信息接口：Authing 默认不把用户资料放进 id_token，
+        #    所以"id_token 里没有 username"**不等于**"这个人没有工号"。
+        work_id = _work_id_of(data) or _work_id_of(profile)
+        if not work_id:
+            raise NoWorkId(
+                f'{NO_WORK_ID_TEXT}这次 id_token 的键名有 {_claim_keys_of(data)}、'
+                f'用户信息接口的键名有 {_claim_keys_of(profile)}，两处都没有 username。'
+            )
+
+        user_model = get_user_model()
+        current = user_model.objects.filter(username=sub).first()
+        name = _text(data.get('name')) or sub
+        if current is not None:
+            # 🔴 老用户只刷新这两列：`is_staff` / `is_superuser` / 组与权限归管理员，
+            #    密码根本没有（见 `set_unusable_password`）。
+            current.name = name
+            current.work_id = work_id
+            current.save(update_fields=list(UPDATABLE_FIELDS))
+            return current
+
+        try:
+            # ⚠️ `atomic()` 是必须的：唯一约束撞了之后 `IntegrityError` 会让**外层事务**
+            #    也进入"已中止"状态，后面那条重查会抛 `TransactionManagementError`。
+            with transaction.atomic():
+                user = user_model(username=sub, name=name, work_id=work_id)
+                user.set_unusable_password()
+                user.save()
+            return user
+        except IntegrityError:
+            # 并发首登：另一个请求刚插进去。重查拿**赢家写下的那一行** ——
+            # `get_or_create` 在这里回的是它自己那个没落库的对象，拿它写会话就会指向不存在的行。
+            winner = user_model.objects.filter(username=sub).first()
+            if winner is None:
+                logger.error('首次落库撞了唯一约束，按 username=%s 却查不到那一行（多半是工号重复）。', sub)
+                return None
+            return winner

labull_framework/auth/bootstrap.py

@@ -0,0 +1,47 @@
+"""启动时按 `BOOTSTRAP_ADMIN_WORK_IDS` 给点名的人 `is_staff=True` —— **这是"第一个管理员从哪来"的唯一入口**。
+
+🔴 为什么需要它：权限是 Django 的 `is_staff` / `Group`，而库里一行用户都没有时，没有任何人能进
+   admin 去勾那个框（我们**没有自己写的管理界面**，admin 只有 `is_staff` 的人能进）——
+   所以第一个管理员只能从配置里点名。
+🔴 **只增不减**：把某人从清单里删掉、重启，他的 `is_staff` 留着。摘权限必须是人明说的动作
+   （去 admin 里取消勾选），不能由"改一次 `.env` + 重启"完成。
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..env import read_env
+from ..models import User
+
+logger = logging.getLogger(__name__)
+
+MAX_WORK_IDS = 200
+
+
+def sync_staff_work_ids() -> int:
+    """给清单里命中的用户补 `is_staff`，回这次改了几个人。
+
+    🔴 **永不抛**：这是启动路径，库连不上 / 表还没迁移都只该在日志里留一句 ——
+       补管理员失败没有理由让整个后端起不来。
+    """
+    raw = read_env('BOOTSTRAP_ADMIN_WORK_IDS')
+    work_ids = [item.strip() for item in raw.split(',') if item.strip()]
+    if not work_ids:
+        return 0  # 没配就什么都不做（清单本来就是可选的）。
+    if len(work_ids) > MAX_WORK_IDS:
+        logger.warning(
+            'BOOTSTRAP_ADMIN_WORK_IDS 有 %s 个工号，本次只处理前 %s 个（上限 %s）：'
+            '请拆成多批，或确认这一行是不是误粘了。',
+            len(work_ids), MAX_WORK_IDS, MAX_WORK_IDS,
+        )
+        work_ids = work_ids[:MAX_WORK_IDS]
+
+    try:
+        # 🔴 用 `update()` 而不是逐个 `save()`：它不会碰 `date_joined` / `last_login` 这类
+        #    自动字段（"改动角色"不该让"这个人什么时候注册的"跟着变），也一条 SQL 就完事。
+        # ⚠️ 不带 `is_staff=False` 那一半：只增不减，见模块头。
+        return User.objects.filter(work_id__in=work_ids).update(is_staff=True)
+    except Exception as error:  # noqa: BLE001 —— 见 docstring：启动路径永不抛
+        logger.error('按 BOOTSTRAP_ADMIN_WORK_IDS 补 is_staff 失败（不影响启动）：%s', error)
+        return 0

labull_framework/auth/sso.py

@@ -0,0 +1,259 @@
+"""OIDC 那一层：跟 Authing 打交道的算法全在这里（配置 / 拼地址 / 换 token / 验签 / 用户信息 / 登出）。
+
+🔴 **不用现成的 OIDC 客户端包**：那些包假设签名走 JWKS 非对称，而 Authing 还有
+   "HS256 + `client_secret`"那一支（密钥不在 JWKS 里）—— 用它们会让人永远进不去。
+🔴 **不引 `requests`**：这里要的只是一次表单 POST 与一次带 Bearer 的 GET，标准库够。
+🔴 **验签必须按 `alg` 选密钥**：拿 JWKS 去验 HS256 是必然失败，而反过来（把非对称 token 的
+   `alg` 改成 HS256、拿公开的密钥当 HMAC 密钥签）就是伪造身份 ⇒ 两条路都要**显式限定
+   `algorithms=[alg]`**，并钉死 `iss` 与 `aud`。
+🔴 配置只从环境变量读，且**每次调用现读**：不缓存，测试与多租户才好换。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+import jwt
+
+#: 空格分隔的 scope。🔴 `username` 这一档不能少：Authing 按请求的 scope 决定回哪些 claim，
+#: 而"工号"住在它用户的 `username` 字段上 —— 不请求它，`id_token` 与用户信息接口里都不会有。
+SSO_SCOPE = 'openid profile email username'
+
+#: 以下路径都**相对 `SSO_ISSUER`**，而 issuer 自己**已经带 `/oidc`**（OIDC 的惯例：
+#: Authing 的 issuer 就是 `https://<域名>.authing.cn/oidc`）⇒ 这里写的必须是 `/oidc` **之后**那一段。
+#:
+#: 🔴 **别把这些写成绝对路径**：写成 `'/oidc/auth'` 就会拼出 `…/oidc/oidc/auth`，
+#:    而症状是"点登录跳到 Authing 得一个 404"—— 看起来像 Authing 那边配错了，其实是这里多了一层。
+#:    权威值是服务发现文档（`<issuer>/.well-known/openid-configuration`）里的 `authorization_endpoint` 这些，
+#:    它们都是 `/oidc/...` ⇒ 减掉 issuer 那一段正好是下面这几个。
+AUTHORIZE_PATH = '/auth'
+TOKEN_PATH = '/token'
+LOGOUT_PATH = '/session/end'
+JWKS_PATH = '/.well-known/jwks.json'
+#: 用户信息接口：Authing 的是 `<issuer>/me`（不在 `/.well-known` 里，按它的文档）。
+USERINFO_PATH = '/me'
+
+#: 前端地址的默认值（前后端分端口开发时用）。
+DEFAULT_WEB_ORIGIN = 'http://localhost:4173'
+
+#: 跟 Authing 打交道的每一次请求的超时（秒）。🔴 没有超时，Authing 挂住时回调会一直吊着，
+#: 浏览器永远停在"正在登录…"，人既进不去也没法重试。
+TIMEOUT_SECONDS = 10
+
+#: 对称签名：密钥就是应用密钥（`client_secret` 只在服务端出现）。
+HMAC_ALGS: tuple[str, ...] = ('HS256', 'HS384', 'HS512')
+#: 非对称签名：公钥在 JWKS 里。
+ASYM_ALGS: tuple[str, ...] = (
+    'RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512',
+    'ES256', 'ES384', 'ES512', 'EdDSA',
+)
+
+#: 每个必填变量配一行能直接粘进 `.env` 的例子（报错要能照着改，而不只是说"缺了"）。
+#: 🔴 那份真源是 `env.ENV_ITEMS`（"有哪几个环境变量"只有一处），见 `SsoEnv.from_env()`。
+
+
+class SsoError(RuntimeError):
+    """SSO 这一层出的错：配置缺失 / 换 token 失败 / 验签失败 / 算法不支持 / 用户信息取不到。
+
+    视图把这些一律回 401 并把报文原样交给用户（"哪一步坏了"写在报文里，不靠匹配字符串分支）。
+    """
+
+
+@dataclass(frozen=True)
+class SsoEnv:
+    """一次 OIDC 流程要的那几项配置（缺必填就抛，报文点名变量并给一行 `.env` 例子）。"""
+
+    issuer: str
+    client_id: str
+    client_secret: str
+    redirect_uri: str
+    web_origin: str = DEFAULT_WEB_ORIGIN
+
+    @classmethod
+    def from_env(cls) -> SsoEnv:
+        """按 `env.ENV_ITEMS` 里**登录那一组的必填项**读值（名单与 `.env` 例子都不在这里抄）。
+
+        🔴 必填清单是那份表的一个视图：加一项必填（例如以后多一个变量）只改 `env.py`，
+           这里的报错、开发包里的清单、文档三处一起跟着变。
+        """
+        from ..env import LOGIN_GROUP, read_env, required_items
+
+        values: dict[str, str] = {}
+        for item in required_items(LOGIN_GROUP):
+            value = read_env(item.name)
+            if not value:
+                raise SsoError(f'环境变量 {item.name} 没配。请在 .env 里补一行：{item.hint}')
+            # ⚠️ issuer 去尾斜杠：下面全是 `f'{issuer}{PATH}'` 的拼接。
+            values[item.name] = value.rstrip('/') if item.name == 'SSO_ISSUER' else value
+        return cls(
+            issuer=values['SSO_ISSUER'],
+            client_id=values['SSO_CLIENT_ID'],
+            client_secret=values['SSO_CLIENT_SECRET'],
+            redirect_uri=values['SSO_REDIRECT_URI'],
+            web_origin=(read_env('SSO_WEB_ORIGIN') or DEFAULT_WEB_ORIGIN).rstrip('/'),
+        )
+
+
+def _query(params: dict[str, str]) -> str:
+    """拼查询串。⚠️ 用 `quote` 而不是默认的 `quote_plus`：空格编成 `%20`，
+    免得 `scope` 那种"空格分隔的列表"被网关按 `+` 误读。"""
+    return urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
+
+
+def safe_redirect(target: object) -> str:
+    """只放行站内路径（防开放重定向）。
+
+    🔴 `//evil.com` 是**协议相对地址**，浏览器会当跨站绝对地址用 ⇒ "以 `/` 开头"必须
+    再加"不以 `//` 开头"；其它形状（空串 / 非字符串）一律回 `/`。
+    """
+    raw = target if isinstance(target, str) else ''
+    return raw if raw.startswith('/') and not raw.startswith('//') else '/'
+
+
+def authorize_url(state: str) -> str:
+    """拼授权码跳转地址；`state` 由调用方生成并存进会话，回调处比对（防 CSRF）。"""
+    env = SsoEnv.from_env()
+    return f'{env.issuer}{AUTHORIZE_PATH}?' + _query({
+        'client_id': env.client_id,
+        'redirect_uri': env.redirect_uri,
+        'response_type': 'code',
+        'scope': SSO_SCOPE,
+        'state': state,
+    })
+
+
+def logout_url() -> str:
+    """拼 Authing 的会话结束地址。
+
+    🔴 `post_logout_redirect_uri` 回**前端**（不是 `SSO_REDIRECT_URI`）：那是收授权码的
+    后端回调，拿它当登出回跳会落在没有 `code` 的 `/auth/callback` 上报错。
+    🔴 不带 `id_token_hint`：我们不留 token 原文，为带上它而把 token 存进会话，
+    等于拿一个新坑换一个旧坑。
+    """
+    env = SsoEnv.from_env()
+    return f'{env.issuer}{LOGOUT_PATH}?' + _query({
+        'client_id': env.client_id,
+        'post_logout_redirect_uri': f'{env.web_origin}/login',
+    })
+
+
+def _post(url: str, fields: dict[str, str]) -> dict:
+    """发一次表单 POST 并解析 JSON 响应（报文里带 **HTTP 状态码**与地址）。"""
+    request = urllib.request.Request(
+        url,
+        data=urllib.parse.urlencode(fields).encode('utf-8'),
+        method='POST',
+        headers={
+            'Content-Type': 'application/x-www-form-urlencoded',
+            # ⚠️ 显式声明接受 JSON：有些网关没有 `Accept` 时会回表单编码，`json.loads` 就炸了。
+            'Accept': 'application/json',
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+            raw = response.read().decode('utf-8', 'replace')
+    except urllib.error.HTTPError as error:
+        # 状态码要写进报文：400 是 code 用过了 / 过期，401 是密钥错 —— 要改的地方完全不同。
+        raise SsoError(f'{url} 返回状态码 {error.code}') from error
+    except urllib.error.URLError as error:
+        raise SsoError(f'{url} 连不上：{error.reason}') from error
+    try:
+        payload = json.loads(raw)
+    except ValueError as error:
+        raise SsoError(f'{url} 的响应不是 JSON') from error
+    if not isinstance(payload, dict):
+        raise SsoError(f'{url} 的响应不是一份 JSON 对象')
+    return payload
+
+
+def exchange_code(code: str) -> dict:
+    """授权码换 `id_token` + `access_token`（两个都要）并回整份响应。
+
+    🔴 `access_token` 不是可有可无：工号常常只在用户信息接口那一侧，少了它就只剩
+    "没有工号的账号一律拒登"这一条路。
+    """
+    env = SsoEnv.from_env()
+    payload = _post(f'{env.issuer}{TOKEN_PATH}', {
+        'grant_type': 'authorization_code',
+        'client_id': env.client_id,
+        'client_secret': env.client_secret,
+        'redirect_uri': env.redirect_uri,
+        'code': code,
+    })
+    if not payload.get('id_token'):
+        raise SsoError('Authing 换 token 的响应里没有 id_token')
+    if not payload.get('access_token'):
+        raise SsoError('Authing 换 token 的响应里没有 access_token（问用户信息接口要用它）')
+    return payload
+
+
+def verify_id_token(id_token: str) -> dict:
+    """验 `id_token` 并回 claims。
+
+    🔴 按 `alg` 选密钥（见模块头）：HMAC 族用 `client_secret`，其余用 JWKS；
+    不认识的 `alg` 直接拒，并在报文里点名是哪一个。
+    """
+    env = SsoEnv.from_env()
+    try:
+        alg = jwt.get_unverified_header(id_token).get('alg')
+    except jwt.PyJWTError as error:
+        raise SsoError(f'id_token 的头部读不出来：{error}') from error
+    if alg in HMAC_ALGS:
+        key: Any = env.client_secret
+    elif alg in ASYM_ALGS:
+        # 🔴 不设 `lifespan`：Authing 轮换密钥时，缓存过久会让新密钥签出来的 token 验不过
+        #    （症状是"一部分人登录失败、重试又好了"）。`PyJWKClient` 在按 kid 找不到时
+        #    会自己重取一次 JWKS —— 那正是轮换场景。
+        try:
+            key = jwt.PyJWKClient(f'{env.issuer}{JWKS_PATH}').get_signing_key_from_jwt(id_token).key
+        except jwt.PyJWTError as error:
+            raise SsoError(f'从 JWKS 取验签公钥失败（{alg}）：{error}') from error
+    else:
+        raise SsoError(f'Authing 的 id_token 用了不支持的签名算法：{alg!r}')
+    try:
+        # `algorithms=[alg]` 是在防 alg 混淆；`issuer` / `audience` 是在防"别的 IdP 或别的应用
+        # 签出来的 token 进我们这个后端"；`require=['exp']` 是在防"永不过期的 token"。
+        return dict(jwt.decode(
+            id_token, key,
+            algorithms=[alg],
+            issuer=env.issuer,
+            audience=env.client_id,
+            options={'require': ['exp']},
+        ))
+    except jwt.PyJWTError as error:
+        raise SsoError(f'id_token 验签失败（{alg}）：{error}') from error
+
+
+def fetch_userinfo(access_token: str) -> dict:
+    """拿 `access_token` 问用户信息接口，回那份用户资料。
+
+    🔴 报文里带**完整接口地址**：404 与 401 要去 Authing 改的东西完全不同，
+    "平台到底请求了哪个地址"是唯一分得清它们的东西。
+    """
+    env = SsoEnv.from_env()
+    endpoint = f'{env.issuer}{USERINFO_PATH}'
+    request = urllib.request.Request(
+        endpoint,
+        method='GET',
+        headers={'Authorization': f'Bearer {access_token}', 'Accept': 'application/json'},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:
+            raw = response.read().decode('utf-8', 'replace')
+    except urllib.error.HTTPError as error:
+        raise SsoError(f'用户信息接口（{endpoint}）返回状态码 {error.code}') from error
+    except urllib.error.URLError as error:
+        raise SsoError(f'用户信息接口（{endpoint}）连不上：{error.reason}') from error
+    try:
+        profile = json.loads(raw)
+    except ValueError as error:
+        raise SsoError(f'用户信息接口（{endpoint}）的响应不是 JSON') from error
+    if not isinstance(profile, dict):
+        raise SsoError(f'用户信息接口（{endpoint}）回的不是一份用户资料')
+    return profile