nonebot-plugin-milock 0.1.0__py3-none-any.whl

nonebot_plugin_milock/__init__.py

@@ -0,0 +1,378 @@
+"""nonebot-plugin-milock：审核制申请 milock 一次性密码。
+
+流程：``/密码`` → （首次）建单送审 → 管理员在管理群或私聊 ``/milock approve <单号>``
+→ 插件向 milock 取一个**尚未发给任何人**的密码 → 私聊发给申请人 →
+把申请、审核、下发（含密码）汇报给管理员私聊与管理群。
+
+配置见 :mod:`nonebot_plugin_milock.config`，全部通过 NoneBot ``.env`` 提供。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from nonebot import get_bots, get_driver, get_plugin_config, on_command, on_keyword
+from nonebot.adapters.onebot.v11 import Bot, Event, GroupMessageEvent, Message
+from nonebot.params import CommandArg
+from nonebot.plugin import PluginMetadata
+
+from . import messages
+from .client import MilockClient
+from .config import Config
+from .flow import handle_application, handle_decision, notify_expired
+from .report import Reporter
+from .schedule import TimeParseError, parse_when
+from .service import OTPService
+from .store import STATUS_APPROVED, Store
+
+__plugin_meta__ = PluginMetadata(
+    name="milock 一次性密码",
+    description="审核制申请 milock 服务生成的一次性密码：单次发放、不可复用、管理员可审计",
+    usage=(
+        "用户：/密码\n"
+        "管理员：/milock approve <单号> | deny <单号> | pending | revoke <QQ> | users | status"
+    ),
+    type="application",
+    config=Config,
+    supported_adapters={"~onebot.v11"},
+)
+
+logger = logging.getLogger("nonebot_plugin_milock")
+
+config = get_plugin_config(Config)
+
+
+class AppState:
+    """插件的全部运行时对象，懒加载一次。"""
+
+    def __init__(self, cfg: Config) -> None:
+        self.config = cfg
+        self.client = MilockClient(
+            cfg.milock_api_base,
+            api_key=cfg.milock_api_key,
+            did=cfg.milock_did,
+            pincode=cfg.milock_pincode,
+            seed_hex=cfg.milock_seed_hex,
+            timeout=cfg.milock_timeout,
+            interval_minutes=cfg.milock_interval_minutes,
+            digits=cfg.milock_digits,
+        )
+        self.store = Store(cfg.milock_db_path)
+        self.service = OTPService(
+            self.client,
+            self.store,
+            max_codes_per_window=cfg.milock_max_codes_per_window,
+            min_remaining_seconds=cfg.milock_min_remaining_seconds,
+            reservation_ttl=cfg.milock_reservation_ttl,
+            approval_timeout=cfg.milock_approval_timeout,
+        )
+        self.reporter = Reporter(
+            admins=cfg.milock_admins | set(get_driver().config.superusers),
+            groups=cfg.milock_admin_groups,
+            report_password=cfg.milock_report_password,
+            report_password_in_groups=cfg.milock_report_password_in_groups,
+            to_admins=cfg.milock_report_to_admins,
+            to_groups=cfg.milock_report_to_groups,
+        )
+        self.sweeper: asyncio.Task[None] | None = None
+
+
+_state: AppState | None = None
+_state_lock = asyncio.Lock()
+
+
+async def get_state() -> AppState:
+    global _state
+    if _state is None:
+        async with _state_lock:
+            if _state is None:
+                _state = AppState(config)
+                _log_config(_state)
+    return _state
+
+
+def _log_config(state: AppState) -> None:
+    cfg = state.config
+    credential = "(未配置!)" if not cfg.has_credentials() else cfg.milock_did or "(seed_hex)"
+    channels = []
+    if state.reporter.to_admins:
+        channels.append(f"私聊×{len(state.reporter.admins)}")
+    if state.reporter.to_groups:
+        channels.append(f"群×{len(state.reporter.groups)}")
+    logger.info(
+        "milock 插件已加载：api=%s did=%s db=%s 汇报=%s 每窗口上限=%d",
+        cfg.milock_api_base,
+        credential,
+        cfg.milock_db_path,
+        "+".join(channels) or "(全部关闭)",
+        cfg.milock_max_codes_per_window,
+    )
+    if not cfg.has_credentials():
+        logger.error("milock: 未配置 MILOCK_DID 或 MILOCK_SEED_HEX，取码一定失败。")
+    if not state.reporter.configured:
+        # 区分"渠道被主动关闭"与"压根没配目标"，两种情况的排查方向不一样。
+        if not cfg.milock_report_to_admins and not cfg.milock_report_to_groups:
+            logger.error("milock: 汇报渠道全部关闭，申请与审核将不再通知任何人。")
+        else:
+            logger.error(
+                "milock: 没有可用的汇报目标（启用渠道内未配置 MILOCK_ADMINS / "
+                "MILOCK_ADMIN_GROUPS），首次申请将无人可审。"
+            )
+    elif not cfg.milock_admin_groups and not _superusers():
+        logger.warning("milock: 未配置管理群，群内审核会被拒绝。")
+
+
+def _superusers() -> set[str]:
+    return {str(item) for item in get_driver().config.superusers}
+
+
+def _is_admin(cfg: Config, qq: str, group_id: str | None) -> bool:
+    """私聊：是管理员即可；群聊：是管理员且位于管理群（超管不受限）。
+
+    注意：群身份只看 ``MILOCK_ADMIN_GROUPS``，与 ``MILOCK_REPORT_TO_GROUPS``
+    无关——关掉群汇报不会顺带关掉群内审核资格。
+    """
+    if qq not in cfg.milock_admins and qq not in _superusers():
+        return False
+    if group_id is None:
+        return True
+    return group_id in cfg.milock_admin_groups or qq in _superusers()
+
+
+def _origin(event: Event) -> str | None:
+    return str(event.group_id) if isinstance(event, GroupMessageEvent) else None
+
+
+def _nickname(event: Event) -> str:
+    sender = getattr(event, "sender", None)
+    return str(getattr(sender, "nickname", "") or "")
+
+
+# --------------------------------------------------------------------------- #
+# 用户：申请密码
+# --------------------------------------------------------------------------- #
+apply_cmd = on_command(
+    config.milock_command,
+    aliases={"申请密码", "取密码", "otp"},
+    priority=10,
+    block=True,
+)
+
+
+async def _run_apply(bot: Bot, event: Event, raw_args: str) -> str | None:
+    """处理一次申请：解析可选的时间参数并交给 flow。"""
+    state = await get_state()
+    at = await _resolve_requested_at(state.config, raw_args)
+    if isinstance(at, str):  # 解析失败，at 是给用户看的错误文案
+        return at
+    return await handle_application(
+        bot,
+        state.service,
+        state.reporter,
+        qq=event.get_user_id(),
+        nickname=_nickname(event),
+        group_id=_origin(event),
+        at=at,
+    )
+
+
+async def _resolve_requested_at(cfg: Config, raw_args: str) -> int | str | None:
+    """把用户输入的时间文本解析成时间戳。
+
+    返回 ``int``（时间戳）、``None``（没写时间，要现在）或 ``str``（错误文案）。
+    """
+    text = raw_args.strip()
+    if not text:
+        return None
+    if not cfg.milock_allow_time_request:
+        return messages.time_disabled_text()
+    try:
+        at = parse_when(text)
+    except TimeParseError as exc:
+        return messages.time_parse_failed_text(exc.message)
+
+    now = int(time.time())
+    if at <= now:
+        return messages.time_in_past_text()
+    limit = now + cfg.milock_max_advance_hours * 3600
+    if at > limit:
+        return messages.time_too_far_text(cfg.milock_max_advance_hours)
+    return at
+
+
+@apply_cmd.handle()
+async def _handle_apply(bot: Bot, event: Event, args: Message = CommandArg()) -> None:
+    reply = await _run_apply(bot, event, args.extract_plain_text())
+    if reply:
+        await apply_cmd.finish(reply)
+
+
+if config.milock_allow_keyword_trigger:
+    apply_keyword = on_keyword({"申请密码"}, priority=11, block=True)
+
+    @apply_keyword.handle()
+    async def _handle_apply_keyword(bot: Bot, event: Event) -> None:
+        # 关键词触发不带参数（"申请密码" 后面跟的时间无法可靠切分），一律按"现在"。
+        reply = await _run_apply(bot, event, "")
+        if reply:
+            await apply_keyword.finish(reply)
+
+
+# --------------------------------------------------------------------------- #
+# 管理员：审核 / 撤销 / 查询
+# --------------------------------------------------------------------------- #
+admin_cmd = on_command("milock", priority=5, block=True)
+
+_APPROVE_WORDS = {"approve", "ok", "yes", "批准", "通过", "同意"}
+_DENY_WORDS = {"deny", "no", "reject", "拒绝", "驳回"}
+
+
+@admin_cmd.handle()
+async def _handle_admin(bot: Bot, event: Event, args: Message = CommandArg()) -> None:
+    state = await get_state()
+    qq = event.get_user_id()
+    group_id = _origin(event)
+    if not _is_admin(state.config, qq, group_id):
+        await admin_cmd.finish(messages.no_permission_text())
+
+    parts = args.extract_plain_text().strip().split()
+    sub = parts[0].lower() if parts else "help"
+    argument = parts[1] if len(parts) > 1 else ""
+
+    if sub in _APPROVE_WORDS | _DENY_WORDS:
+        request_id = _as_int(argument)
+        if request_id is None:
+            await admin_cmd.finish(f"用法：/milock {sub} <单号>")
+        reply = await handle_decision(
+            bot,
+            state.service,
+            state.reporter,
+            request_id=request_id,
+            admin=qq,
+            approve=sub in _APPROVE_WORDS,
+        )
+        await admin_cmd.finish(reply)
+
+    if sub in {"pending", "待审", "列表"}:
+        await admin_cmd.finish(await _render_pending(state))
+
+    if sub in {"revoke", "撤销"}:
+        target = argument.strip()
+        if not target.isdigit():
+            await admin_cmd.finish("用法：/milock revoke <QQ号>")
+        if await state.service.revoke(target, qq):
+            await state.reporter.broadcast(bot, messages.report_revoke(target, qq))
+            try:
+                await state.reporter.send_private(bot, target, messages.revoked_text())
+            except Exception as exc:
+                logger.warning("milock: 撤销通知 %s 发送失败: %s", target, exc)
+            await admin_cmd.finish(f"已撤销 {target} 的授权。")
+        await admin_cmd.finish(f"{target} 当前没有有效授权。")
+
+    if sub in {"users", "授权"}:
+        users = await state.store.list_users(STATUS_APPROVED)
+        if not users:
+            await admin_cmd.finish("当前没有已授权用户。")
+        lines = [
+            f"{index}. {user.qq}（by {user.approved_by or '未知'}）"
+            for index, user in enumerate(users, start=1)
+        ]
+        await admin_cmd.finish("已授权用户：\n" + "\n".join(lines))
+
+    if sub in {"status", "状态"}:
+        await admin_cmd.finish(await _render_status(state))
+
+    # 管理命令固定为 /milock（见上面的 on_command），别把它和用户申请命令名混用。
+    await admin_cmd.finish(messages.admin_help())
+
+
+async def _render_pending(state: AppState) -> str:
+    pending = await state.service.pending()
+    if not pending:
+        return "当前没有待审核申请。"
+    lines = [
+        f"#{item.id} {item.nickname}({item.qq}) 群={item.group_id or '私聊'} "
+        f"{_fmt_time(item.created_at)}"
+        for item in pending
+    ]
+    return "待审核申请：\n" + "\n".join(lines)
+
+
+async def _render_status(state: AppState) -> str:
+    stats = await state.store.stats()
+    reachable = await state.client.healthz()
+    cfg = state.config
+    lines = [
+        "milock 插件状态：",
+        f"服务：{cfg.milock_api_base}（{'可达' if reachable else '不可达'}）",
+        f"凭证：{'已配置' if cfg.has_credentials() else '未配置'}",
+        f"管理员：{len(state.reporter.admins)} 人，管理群：{len(state.reporter.groups)} 个",
+        f"已授权用户：{stats['approved_users']}",
+        f"待审核申请：{stats['pending_requests']}",
+        f"已下发密码：{stats['delivered_codes']}（占位中 {stats['reserved_codes']}）",
+        f"每窗口上限：{cfg.milock_max_codes_per_window} 个/人",
+    ]
+    return "\n".join(lines)
+
+
+def _as_int(value: str) -> int | None:
+    try:
+        return int(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _fmt_time(ts: int) -> str:
+    return time.strftime("%m-%d %H:%M", time.localtime(ts))
+
+
+# --------------------------------------------------------------------------- #
+# 后台清理：超时申请作废 + 失效占位回收
+# --------------------------------------------------------------------------- #
+async def _sweeper(state: AppState) -> None:
+    interval = state.config.milock_sweep_interval
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            result = await state.service.sweep()
+        except Exception:  # 后台任务不能因一次异常退出
+            logger.exception("milock: 清理任务失败")
+            continue
+        bots = get_bots()
+        bot = next(iter(bots.values()), None)
+        if bot is None:
+            if result.expired or result.released:
+                logger.info(
+                    "milock: 清理完成（无在线 Bot，未汇报）过期申请=%d 回收占位=%d",
+                    len(result.expired),
+                    result.released,
+                )
+            continue
+        if result.expired:
+            await notify_expired(bot, state.reporter, result.expired)
+        if result.released:
+            logger.info("milock: 回收了 %d 个未投递的密码占位", result.released)
+
+
+driver = get_driver()
+
+
+@driver.on_startup
+async def _startup() -> None:
+    state = await get_state()
+    if state.sweeper is None or state.sweeper.done():
+        state.sweeper = asyncio.create_task(_sweeper(state))
+
+
+@driver.on_shutdown
+async def _shutdown() -> None:
+    global _state
+    if _state is None:
+        return
+    if _state.sweeper is not None:
+        _state.sweeper.cancel()
+        _state.sweeper = None
+    _state.store.close()
+    _state = None

nonebot_plugin_milock/client.py

@@ -0,0 +1,212 @@
+"""milock HTTP 客户端。
+
+只用标准库（``urllib`` + ``asyncio.to_thread``），因此插件除 NoneBot 外
+不需要任何第三方运行期依赖。对应服务端接口见 ``docs/API.md``：
+
+* ``POST /api/v1/otp/now`` —— 当前窗口
+* ``POST /api/v1/otp``     —— 指定时间（用于提前取下一个窗口）
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Any
+
+__all__ = ["MilockClient", "MilockError", "Window"]
+
+
+class MilockError(Exception):
+    """milock 调用失败。``kind`` 用于决定给用户的提示文案。"""
+
+    #: 服务不可达（网络/连接被拒/DNS 失败）
+    UNREACHABLE = "unreachable"
+    #: 超时
+    TIMEOUT = "timeout"
+    #: API Key 缺失或错误
+    AUTH = "auth"
+    #: 触发服务端限流
+    RATELIMITED = "ratelimited"
+    #: 请求本身有问题（did/pincode 不对等）
+    BAD_REQUEST = "badrequest"
+    #: 服务端 5xx
+    SERVER = "server"
+    #: 响应不是预期的 JSON 结构
+    MALFORMED = "malformed"
+
+    def __init__(self, kind: str, detail: str, status: int | None = None) -> None:
+        super().__init__(detail)
+        self.kind = kind
+        self.detail = detail
+        self.status = status
+
+
+@dataclass(slots=True, frozen=True)
+class Window:
+    """一个时间窗口内的全部密码。"""
+
+    passwords: tuple[str, ...]
+    interval_minutes: int
+    digits: int
+    counter: int
+    window_start: int
+    window_end: int
+    seconds_remaining: int
+    seed_source: str | None = None
+
+    @classmethod
+    def from_payload(cls, data: Any) -> Window:
+        if not isinstance(data, dict):
+            raise MilockError(MilockError.MALFORMED, "响应不是 JSON 对象")
+        try:
+            raw = data["passwords"]
+            if not isinstance(raw, list) or not raw:
+                raise TypeError("passwords")
+            passwords = tuple(str(item) for item in raw)
+            return cls(
+                passwords=passwords,
+                interval_minutes=int(data["interval_minutes"]),
+                digits=int(data["digits"]),
+                counter=int(data["counter"]),
+                window_start=int(data["window_start"]),
+                window_end=int(data["window_end"]),
+                seconds_remaining=int(data["seconds_remaining"]),
+                seed_source=str(data["seed_source"]) if data.get("seed_source") else None,
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise MilockError(MilockError.MALFORMED, f"响应缺少字段或类型错误: {exc!r}") from None
+
+
+def _extract_error(body: bytes) -> str:
+    try:
+        data = json.loads(body.decode("utf-8", "replace"))
+    except (ValueError, UnicodeDecodeError):
+        return body.decode("utf-8", "replace")[:200].strip() or "无响应内容"
+    if isinstance(data, dict):
+        message = data.get("error") or data.get("message")
+        if isinstance(message, str) and message:
+            return message
+    return json.dumps(data, ensure_ascii=False)[:200]
+
+
+class MilockClient:
+    """极简 async 客户端。"""
+
+    def __init__(
+        self,
+        base: str,
+        *,
+        api_key: str = "",
+        did: str = "",
+        pincode: str = "",
+        seed_hex: str = "",
+        timeout: float = 10.0,
+        interval_minutes: int | None = None,
+        digits: int | None = None,
+    ) -> None:
+        self.base = base.rstrip("/")
+        self.api_key = api_key
+        self.did = did
+        self.pincode = pincode
+        self.seed_hex = seed_hex
+        self.timeout = timeout
+        self.interval_minutes = interval_minutes
+        self.digits = digits
+
+    # ------------------------------------------------------------------ #
+    # 公开 API
+    # ------------------------------------------------------------------ #
+    async def window_now(self) -> Window:
+        """当前窗口。"""
+        return await self._window("/api/v1/otp/now", None)
+
+    async def window_at(self, at: int) -> Window:
+        """包含 ``at``（unix 秒）的窗口，用于提前领取下一个窗口。"""
+        return await self._window("/api/v1/otp", at)
+
+    async def healthz(self) -> bool:
+        """服务是否存活（用于启动自检，失败不抛异常）。"""
+        try:
+            await self._call("GET", "/healthz", None)
+        except MilockError:
+            return False
+        return True
+
+    # ------------------------------------------------------------------ #
+    # 内部实现
+    # ------------------------------------------------------------------ #
+    def build_payload(self, at: int | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if self.seed_hex:
+            payload["seed_hex"] = self.seed_hex
+        elif self.did:
+            payload["did"] = self.did
+            if self.pincode:
+                payload["pincode"] = self.pincode
+        if self.interval_minutes is not None:
+            payload["interval"] = self.interval_minutes
+        if self.digits is not None:
+            payload["digits"] = self.digits
+        if at is not None:
+            payload["at"] = int(at)
+        return payload
+
+    async def _window(self, path: str, at: int | None) -> Window:
+        data = await self._call("POST", path, self.build_payload(at))
+        return Window.from_payload(data)
+
+    async def _call(self, method: str, path: str, payload: dict[str, Any] | None) -> Any:
+        try:
+            return await asyncio.to_thread(self._call_sync, method, path, payload)
+        except MilockError:
+            raise
+        except TimeoutError as exc:  # pragma: no cover - 平台差异
+            raise MilockError(MilockError.TIMEOUT, f"请求超时: {exc}") from None
+        except urllib.error.URLError as exc:
+            reason = exc.reason
+            if isinstance(reason, TimeoutError):
+                raise MilockError(MilockError.TIMEOUT, f"请求超时: {reason}") from None
+            raise MilockError(MilockError.UNREACHABLE, f"无法连接 {self.base}: {reason}") from None
+        except OSError as exc:
+            raise MilockError(MilockError.UNREACHABLE, f"网络错误: {exc}") from None
+
+    def _call_sync(self, method: str, path: str, payload: dict[str, Any] | None) -> Any:
+        url = f"{self.base}{path}"
+        data = None
+        headers = {"Accept": "application/json"}
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                body = response.read()
+                status = response.status
+        except urllib.error.HTTPError as exc:
+            body = exc.read()
+            raise MilockError(self._classify(exc.code), _extract_error(body), exc.code) from None
+
+        if status >= HTTPStatus.BAD_REQUEST:  # pragma: no cover - HTTPError 已覆盖
+            raise MilockError(self._classify(status), _extract_error(body), status)
+        if not body:
+            return {}
+        try:
+            return json.loads(body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError) as exc:
+            raise MilockError(MilockError.MALFORMED, f"响应不是合法 JSON: {exc}") from None
+
+    @staticmethod
+    def _classify(status: int) -> str:
+        if status in (HTTPStatus.UNAUTHORIZED, HTTPStatus.FORBIDDEN):
+            return MilockError.AUTH
+        if status == HTTPStatus.TOO_MANY_REQUESTS:
+            return MilockError.RATELIMITED
+        if HTTPStatus.BAD_REQUEST <= status < HTTPStatus.INTERNAL_SERVER_ERROR:
+            return MilockError.BAD_REQUEST
+        return MilockError.SERVER