qsignt 0.1.0__tar.gz

qsignt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AmritaBot
+
+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.

qsignt-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: qsignt
+Version: 0.1.0
+Summary: QsigNT signer 注册工具：OpenPGP 上行 + X25519 下行
+License: MIT
+Project-URL: Repository, https://github.com/AmritaBot/qsignt.py
+Project-URL: Issues, https://github.com/AmritaBot/qsignt.py/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Dynamic: license-file
+
+# qsignt
+
+[![CI](https://github.com/AmritaBot/qsignt.py/actions/workflows/ci.yml/badge.svg)](https://github.com/AmritaBot/qsignt.py/actions/workflows/ci.yml)
+
+QsigNT signer 的注册工具。在 QQ 群里跑一遍流程，把 apikey 换到本地。
+
+依赖：Python 3.10+、gnupg 2.3+（需要 `gpg` 在 PATH 里）。
+
+## 签名申请入口
+
+签名权限只在 QQ 群 **1132696493** 发放，进群后直接发 `#qsignt init` 就能开始，整个
+流程在群里闭环，不需要单独找人。
+
+群号固定写死在工具里，查一下就知道：
+
+```
+qsignt community
+```
+
+（不联网、不读配置，纯粹回显常量，防的是手抄错号。）
+
+apikey 是组织层面的凭证，按用户发放。仓库这边不发 key、也不提供自助领取，抱着
+clone 下来就跑出权限的期待会落空。
+
+能拿到的东西：
+
+- 一个 `qsig_` 开头的 apikey，由 QsigNT daemon 校验，请求头带 `Authorization: Bearer <apikey>`
+- apikey 与用户一一对应，一人一把，不做共享
+- 限速按用户计，默认 20 请求/秒，超了返回 429 和 `Retry-After`
+
+注册流程只在群里走，私聊不办理。群聊之外的旁路申请一律不接，包括找维护者单独要。
+
+## 为什么是 OpenPGP
+
+QQ 客户端与服务端的身份已由平台担保，需要防的只是群里旁观者顺手读到凭证。
+上行用服务端公钥加密就够了，不需要证书链，也不需要指纹交叉验证。
+
+下行不用 OpenPGP，改用一次性 X25519 + AES-256-GCM：客户端在提交时带上本次流程
+的临时公钥，服务端加密回包即可。少一次密钥交换，载荷也短一半。
+
+## 流程
+
+群里发 `#qsignt init`，机器人回一条带公钥的消息。整段复制，然后：
+
+```
+qsignt enroll --msg "SIGNER-KEY-V1 flow=AB12CD34 exp=10m
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+...
+-----END PGP PUBLIC KEY BLOCK-----"
+```
+
+工具打印一条 `#qsignt key submit ...`，发到群里。
+
+机器人回 `#qsignt key open ...`，复制后：
+
+```
+qsignt open --msg "#qsignt key open AbCd..."
+```
+
+工具把 apikey 存到 `~/.config/qsignt/token.json`（权限 0600），并打印
+`#qsignt verify XXXXXXXX`。发出去，激活完成。
+
+`qsignt show` 随时取回 apikey。
+
+## 服务端
+
+```
+qsignt keygen --out /var/lib/qsignt/gpg          # 生成 bot 密钥对，公钥贴到群里
+qsignt decrypt --home /var/lib/qsignt/gpg --msg "..."
+qsignt seal --eph <客户端公钥> --flow AB12CD34 --json reply.json
+```
+
+## 边界
+
+- 中间中断不会白费：流程状态存在本地，`open` 之前重跑 `enroll` 会重开新流程。
+- 群消息会被折叠，复制时可能带上换行和空格，解析时已做容错。
+- apikey 明文只落在本地文件里，工具不做上传、不做同步。

qsignt-0.1.0/README.md

@@ -0,0 +1,77 @@
+# qsignt
+
+[![CI](https://github.com/AmritaBot/qsignt.py/actions/workflows/ci.yml/badge.svg)](https://github.com/AmritaBot/qsignt.py/actions/workflows/ci.yml)
+
+QsigNT signer 的注册工具。在 QQ 群里跑一遍流程，把 apikey 换到本地。
+
+依赖：Python 3.10+、gnupg 2.3+（需要 `gpg` 在 PATH 里）。
+
+## 签名申请入口
+
+签名权限只在 QQ 群 **1132696493** 发放，进群后直接发 `#qsignt init` 就能开始，整个
+流程在群里闭环，不需要单独找人。
+
+群号固定写死在工具里，查一下就知道：
+
+```
+qsignt community
+```
+
+（不联网、不读配置，纯粹回显常量，防的是手抄错号。）
+
+apikey 是组织层面的凭证，按用户发放。仓库这边不发 key、也不提供自助领取，抱着
+clone 下来就跑出权限的期待会落空。
+
+能拿到的东西：
+
+- 一个 `qsig_` 开头的 apikey，由 QsigNT daemon 校验，请求头带 `Authorization: Bearer <apikey>`
+- apikey 与用户一一对应，一人一把，不做共享
+- 限速按用户计，默认 20 请求/秒，超了返回 429 和 `Retry-After`
+
+注册流程只在群里走，私聊不办理。群聊之外的旁路申请一律不接，包括找维护者单独要。
+
+## 为什么是 OpenPGP
+
+QQ 客户端与服务端的身份已由平台担保，需要防的只是群里旁观者顺手读到凭证。
+上行用服务端公钥加密就够了，不需要证书链，也不需要指纹交叉验证。
+
+下行不用 OpenPGP，改用一次性 X25519 + AES-256-GCM：客户端在提交时带上本次流程
+的临时公钥，服务端加密回包即可。少一次密钥交换，载荷也短一半。
+
+## 流程
+
+群里发 `#qsignt init`，机器人回一条带公钥的消息。整段复制，然后：
+
+```
+qsignt enroll --msg "SIGNER-KEY-V1 flow=AB12CD34 exp=10m
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+...
+-----END PGP PUBLIC KEY BLOCK-----"
+```
+
+工具打印一条 `#qsignt key submit ...`，发到群里。
+
+机器人回 `#qsignt key open ...`，复制后：
+
+```
+qsignt open --msg "#qsignt key open AbCd..."
+```
+
+工具把 apikey 存到 `~/.config/qsignt/token.json`（权限 0600），并打印
+`#qsignt verify XXXXXXXX`。发出去，激活完成。
+
+`qsignt show` 随时取回 apikey。
+
+## 服务端
+
+```
+qsignt keygen --out /var/lib/qsignt/gpg          # 生成 bot 密钥对，公钥贴到群里
+qsignt decrypt --home /var/lib/qsignt/gpg --msg "..."
+qsignt seal --eph <客户端公钥> --flow AB12CD34 --json reply.json
+```
+
+## 边界
+
+- 中间中断不会白费：流程状态存在本地，`open` 之前重跑 `enroll` 会重开新流程。
+- 群消息会被折叠，复制时可能带上换行和空格，解析时已做容错。
+- apikey 明文只落在本地文件里，工具不做上传、不做同步。

qsignt-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qsignt"
+version = "0.1.0"
+description = "QsigNT signer 注册工具：OpenPGP 上行 + X25519 下行"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = ["cryptography>=42"]
+
+[project.urls]
+Repository = "https://github.com/AmritaBot/qsignt.py"
+Issues = "https://github.com/AmritaBot/qsignt.py/issues"
+
+[project.scripts]
+qsignt = "qsignt.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.9", "pyright>=1.1.390"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # bugbear
+    "SIM",  # simplify
+    "RUF",  # ruff 自身规则
+    "PL",   # pylint 子集
+    "BLE",  # 禁止 except Exception
+]
+ignore = ["PLR0913", "RUF001", "RUF002", "RUF003"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLR2004"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.10"
+typeCheckingMode = "basic"

qsignt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qsignt-0.1.0/src/qsignt/__init__.py

@@ -0,0 +1,25 @@
+"""qsignt —— QsigNT signer 注册工具。
+
+上行 OpenPGP 加密，下行一次性 X25519 + AES-256-GCM。
+"""
+
+from .box import b64d, b64e, new_keypair, open_sealed, seal
+from .proto import build_init, build_payload, parse_init, parse_payload
+
+# 签名申请只在这一个群发放，其他地方不接。
+COMMUNITY_GROUP = "1132696493"
+
+__all__ = [
+    "COMMUNITY_GROUP",
+    "b64d",
+    "b64e",
+    "build_init",
+    "build_payload",
+    "new_keypair",
+    "open_sealed",
+    "parse_init",
+    "parse_payload",
+    "seal",
+]
+
+__version__ = "0.1.0"

qsignt-0.1.0/src/qsignt/box.py

@@ -0,0 +1,87 @@
+"""下行信封：一次性 X25519 + AES-256-GCM。
+
+上行用 OpenPGP（见 pgpx.py），下行只加密到客户端本次流程的一次性公钥。
+公钥随上行 payload 一起提交，服务端用它对 JSON 做 AEAD 加密。
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+VERSION = 1
+KEY_LEN = 32
+NONCE_LEN = 12
+TAG_LEN = 16
+INFO = b"qsignt-open-v1"
+
+
+def b64e(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode().rstrip("=")
+
+
+def b64d(text: str) -> bytes:
+    text = "".join(text.split())
+    pad = "=" * (-len(text) % 4)
+    return base64.urlsafe_b64decode(text + pad)
+
+
+def new_keypair() -> tuple[X25519PrivateKey, bytes]:
+    """返回 (私钥, 32 字节公钥)。"""
+    priv = X25519PrivateKey.generate()
+    pub = priv.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return priv, pub
+
+
+def _derive(shared: bytes, flow: str) -> bytes:
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=flow.encode(),
+        info=INFO,
+    ).derive(shared)
+
+
+def seal(peer_pub_raw: bytes, flow: str, payload: dict[str, Any]) -> str:
+    """服务端侧。返回 base64url(bot_eph_pub || nonce || ciphertext)。"""
+    if len(peer_pub_raw) != KEY_LEN:
+        raise ValueError("peer public key must be 32 bytes")
+
+    eph_priv, eph_pub = new_keypair()
+    shared = eph_priv.exchange(X25519PublicKey.from_public_bytes(peer_pub_raw))
+    key = _derive(shared, flow)
+
+    nonce = os.urandom(NONCE_LEN)
+    data = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()
+    ct = AESGCM(key).encrypt(nonce, data, flow.encode())
+
+    return b64e(eph_pub + nonce + ct)
+
+
+def open_sealed(blob: str, flow: str, eph_priv: X25519PrivateKey) -> dict[str, Any]:
+    """客户端侧。blob 为下行那串 base64url。"""
+    raw = b64d(blob)
+    if len(raw) < 32 + NONCE_LEN + TAG_LEN:
+        raise ValueError("下行载荷长度不足")
+
+    bot_pub = raw[:32]
+    nonce = raw[32 : 32 + NONCE_LEN]
+    ct = raw[32 + NONCE_LEN :]
+
+    shared = eph_priv.exchange(X25519PublicKey.from_public_bytes(bot_pub))
+    key = _derive(shared, flow)
+    data = AESGCM(key).decrypt(nonce, ct, flow.encode())
+    return json.loads(data)

qsignt-0.1.0/src/qsignt/cli.py

@@ -0,0 +1,182 @@
+"""命令行入口。
+
+人只做三件事：贴初始化消息、贴回包、把工具打印出的指令发回群里。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import COMMUNITY_GROUP, box, pgpx, proto
+
+
+def state_dir() -> Path:
+    root = os.environ.get("QSIGNT_STATE") or os.path.join(
+        os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config"), "qsignt"
+    )
+    p = Path(root)
+    p.mkdir(parents=True, exist_ok=True)
+    os.chmod(p, 0o700)
+    return p
+
+
+def _save(name: str, data: dict) -> None:
+    path = state_dir() / name
+    path.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    os.chmod(path, 0o600)
+
+
+def _load(name: str) -> dict | None:
+    path = state_dir() / name
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def cmd_enroll(args: argparse.Namespace) -> int:
+    init = proto.parse_init(args.msg)
+    priv, pub = box.new_keypair()
+    payload = proto.build_payload(init.flow, pub)
+    ct = pgpx.encrypt_to(init.armor, payload)
+
+    _save(
+        "flow.json",
+        {
+            "flow": init.flow,
+            "eph": box.b64e(priv.private_bytes_raw()),
+        },
+    )
+    print("把下面这条整段发到群里：\n")
+    print(proto.submit_command(ct))
+    return 0
+
+
+def cmd_open(args: argparse.Namespace) -> int:
+    st = _load("flow.json")
+    if not st:
+        print("没有进行中的流程，先跑 enroll", file=sys.stderr)
+        return 2
+
+    blob = args.msg.strip()
+    # 回执可能是合并转发里带说明的一整段，先切到指令本身
+    marker = "#qsignt key open"
+    if marker in blob:
+        blob = blob.split(marker, 1)[1]
+    elif "key open" in blob:
+        blob = blob.split("key open", 1)[1]
+    blob = "".join(blob.split())
+
+    priv = box.X25519PrivateKey.from_private_bytes(box.b64d(st["eph"]))
+    data = box.open_sealed(blob, st["flow"], priv)
+
+    if data.get("flow") != st["flow"]:
+        print("回包的 flow 和本地不一致，丢弃", file=sys.stderr)
+        return 3
+
+    _save(
+        "token.json",
+        {
+            "apikey": data["apikey"],
+            "flow": st["flow"],
+            "exp": data.get("exp"),
+            "state": "pending",
+        },
+    )
+    print(f"apikey 已保存到 {state_dir() / 'token.json'}\n")
+    print("把下面这条发到群里完成激活：\n")
+    print(proto.verify_command(data["chall"]))
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    tok = _load("token.json")
+    if not tok:
+        print("本地没有 apikey", file=sys.stderr)
+        return 2
+    print(tok["apikey"])
+    return 0
+
+
+def cmd_keygen(args: argparse.Namespace) -> int:
+    home = Path(args.out).expanduser()
+    home.mkdir(parents=True, exist_ok=True)
+    os.chmod(home, 0o700)
+    fpr, armor = pgpx.generate(str(home), args.identity)
+    print(f"指纹 {fpr}\n")
+    print(armor)
+    return 0
+
+
+def cmd_decrypt(args: argparse.Namespace) -> int:
+    raw = pgpx.decrypt_with(args.home, args.msg)
+    print(json.dumps(proto.parse_payload(raw), ensure_ascii=False))
+    return 0
+
+
+def cmd_seal(args: argparse.Namespace) -> int:
+    payload = json.loads(Path(args.json).read_text(encoding="utf-8"))
+    print(box.seal(box.b64d(args.eph), args.flow, payload))
+    return 0
+
+
+def cmd_community(args: argparse.Namespace) -> int:
+    """固定输出签名申请群，不接受参数。"""
+    print("签名申请群")
+    print(COMMUNITY_GROUP)
+    print()
+    print("进群后发 #qsignt init 开始注册")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="qsignt", description="QsigNT signer 注册工具")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("enroll", help="用群里的初始化消息生成提交指令")
+    e.add_argument("--msg", required=True, help="整段初始化消息（含 flow 与公钥）")
+    e.set_defaults(func=cmd_enroll)
+
+    o = sub.add_parser("open", help="解开 bot 回包，取出 apikey")
+    o.add_argument("--msg", required=True, help="bot 回的 key open 那条")
+    o.set_defaults(func=cmd_open)
+
+    s = sub.add_parser("show", help="打印本地 apikey")
+    s.set_defaults(func=cmd_show)
+
+    k = sub.add_parser("keygen", help="生成 bot 侧 OpenPGP 密钥对")
+    k.add_argument("--out", required=True)
+    k.add_argument("--identity", default="qsignt-bot")
+    k.set_defaults(func=cmd_keygen)
+
+    d = sub.add_parser("decrypt", help="服务端解密上行 payload")
+    d.add_argument("--home", required=True, help="GNUPGHOME")
+    d.add_argument("--msg", required=True, help="armor 密文")
+    d.set_defaults(func=cmd_decrypt)
+
+    sl = sub.add_parser("seal", help="服务端生成下行密文")
+    sl.add_argument("--eph", required=True, help="客户端一次性公钥 base64url")
+    sl.add_argument("--flow", required=True)
+    sl.add_argument("--json", required=True, help="待加密 JSON 文件路径")
+    sl.set_defaults(func=cmd_seal)
+
+    cm = sub.add_parser("community", help="显示签名申请群号")
+    cm.set_defaults(func=cmd_community)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except (ValueError, pgpx.GPGError) as exc:
+        print(f"失败：{exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qsignt-0.1.0/src/qsignt/pgpx.py

@@ -0,0 +1,149 @@
+"""gpg 命令行薄封装。
+
+不重写 OpenPGP。理由很实际：RFC 4880 的 ECDH 加密要手工拼 MPI、KDF 参数和
+AES key wrap，自己写等于给协议开新坑；gpg 是现成的、经过审计的实现。
+
+前提：本机有 gpg 2.3 以上。
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+GPG = shutil.which("gpg") or shutil.which("gpg2")
+
+
+class GPGError(RuntimeError):
+    pass
+
+
+def _require() -> str:
+    if not GPG:
+        raise GPGError("找不到 gpg，请先安装 gnupg 2.3+")
+    return GPG
+
+
+def _run(args: list[str], homedir: str, stdin: bytes | None = None) -> bytes:
+    env = dict(os.environ)
+    env["GNUPGHOME"] = homedir
+    env.pop("GPG_AGENT_INFO", None)
+    proc = subprocess.run(
+        [_require(), "--homedir", homedir, "--batch", "--yes", "--no-tty", *args],
+        input=stdin,
+        capture_output=True,
+        env=env,
+        timeout=120,
+        check=False,
+    )
+    if proc.returncode != 0:
+        msg = proc.stderr.decode(errors="replace").strip()
+        raise GPGError(msg or f"gpg 退出码 {proc.returncode}")
+    return proc.stdout
+
+
+@contextmanager
+def homedir(path: str | Path | None = None) -> Iterator[str]:
+    """临时 GNUPGHOME，权限 0700。"""
+    if path is not None:
+        p = Path(path)
+        p.mkdir(parents=True, exist_ok=True)
+        os.chmod(p, 0o700)
+        yield str(p)
+        return
+
+    with tempfile.TemporaryDirectory(prefix="qsignt-gpg-") as tmp:
+        os.chmod(tmp, 0o700)
+        yield tmp
+
+
+def _fingerprints(homedir_path: str) -> list[str]:
+    out = _run(["--with-colons", "--list-keys"], homedir_path).decode(errors="replace")
+    fprs: list[str] = []
+    want = False
+    for line in out.splitlines():
+        fields = line.split(":")
+        if fields[0] in ("pub", "sub"):
+            want = True
+        elif fields[0] == "fpr" and want:
+            fprs.append(fields[9])
+            want = False
+    return fprs
+
+
+def generate(
+    homedir_path: str, identity: str = "qsignt-bot", expire: str = "2y"
+) -> tuple[str, str]:
+    """生成 Ed25519 主钥 + cv25519 加密子钥，返回 (指纹, armored 公钥)。"""
+    _run(
+        [
+            "--passphrase",
+            "",
+            "--quick-generate-key",
+            identity,
+            "ed25519",
+            "sign",
+            expire,
+        ],
+        homedir_path,
+    )
+    fprs = _fingerprints(homedir_path)
+    if not fprs:
+        raise GPGError("生成主钥后拿不到指纹")
+    main = fprs[0]
+
+    _run(
+        ["--passphrase", "", "--quick-add-key", main, "cv25519", "encr", expire],
+        homedir_path,
+    )
+    armor = export_public(homedir_path, main)
+    return main, armor
+
+
+def export_public(homedir_path: str, fpr: str | None = None) -> str:
+    args = ["--armor", "--export"]
+    if fpr:
+        args.append(fpr)
+    return _run(args, homedir_path).decode()
+
+
+def import_public(homedir_path: str, armored: str) -> str:
+    _run(["--import"], homedir_path, stdin=armored.encode())
+    fprs = _fingerprints(homedir_path)
+    if not fprs:
+        raise GPGError("导入公钥后拿不到指纹")
+    return fprs[0]
+
+
+def encrypt_to(armored_pub: str, plaintext: bytes) -> str:
+    """用一段 armor 公钥加密，返回 armor 密文。"""
+    with homedir() as tmp:
+        fpr = import_public(tmp, armored_pub)
+        out = _run(
+            ["--armor", "--trust-model", "always", "--recipient", fpr, "--encrypt"],
+            tmp,
+            stdin=plaintext,
+        )
+    return out.decode()
+
+
+def decrypt_with(homedir_path: str, armored_ct: str) -> bytes:
+    return _run(["--decrypt"], homedir_path, stdin=armored_ct.encode())
+
+
+def parse_armor(text: str) -> str:
+    """从一段混杂文本里抽出第一个 armor 公钥块。"""
+    begin = "-----BEGIN PGP PUBLIC KEY BLOCK-----"
+    end = "-----END PGP PUBLIC KEY BLOCK-----"
+    start = text.find(begin)
+    if start < 0:
+        raise ValueError("文本里没有 PGP 公钥块")
+    stop = text.find(end, start)
+    if stop < 0:
+        raise ValueError("公钥块没有结束标记")
+    return text[start : stop + len(end)]

qsignt-0.1.0/src/qsignt/proto.py

@@ -0,0 +1,73 @@
+"""协议里的文本形态：初始化消息、上行 payload、指令拼装。"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass
+
+from . import pgpx
+from .box import b64e
+
+HEADER = "SIGNER-KEY-V1"
+FLOW_RE = re.compile(r"flow=([0-9A-Za-z]{4,16})")
+EXP_RE = re.compile(r"exp=(\d+)\s*(m|min|分钟)?")
+
+
+@dataclass
+class InitMessage:
+    flow: str
+    armor: str
+    expire_minutes: int | None
+
+
+def build_init(flow: str, armored_pub: str, expire_minutes: int = 10) -> str:
+    return f"{HEADER} flow={flow} exp={expire_minutes}m\n{armored_pub.strip()}\n"
+
+
+def parse_init(text: str) -> InitMessage:
+    m = FLOW_RE.search(text)
+    if not m:
+        raise ValueError("初始化消息里没有 flow 标识")
+    e = EXP_RE.search(text)
+    return InitMessage(
+        flow=m.group(1),
+        armor=pgpx.parse_armor(text),
+        expire_minutes=int(e.group(1)) if e else None,
+    )
+
+
+def build_payload(flow: str, eph_pub: bytes, kind: str = "enroll") -> bytes:
+    return json.dumps(
+        {
+            "v": 1,
+            "kind": kind,
+            "flow": flow,
+            "eph": b64e(eph_pub),
+            "ts": int(time.time()),
+        },
+        separators=(",", ":"),
+    ).encode()
+
+
+def parse_payload(raw: bytes) -> dict:
+    data = json.loads(raw)
+    if data.get("v") != 1:
+        raise ValueError("payload 版本不认识")
+    for key in ("flow", "eph"):
+        if key not in data:
+            raise ValueError(f"payload 缺少 {key}")
+    return data
+
+
+def submit_command(armored_ct: str) -> str:
+    return "#qsignt key submit " + armored_ct.strip()
+
+
+def open_command(blob: str) -> str:
+    return "#qsignt key open " + blob.strip()
+
+
+def verify_command(chall: str) -> str:
+    return "#qsignt verify " + chall.strip()

qsignt-0.1.0/src/qsignt.egg-info/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: qsignt
+Version: 0.1.0
+Summary: QsigNT signer 注册工具：OpenPGP 上行 + X25519 下行
+License: MIT
+Project-URL: Repository, https://github.com/AmritaBot/qsignt.py
+Project-URL: Issues, https://github.com/AmritaBot/qsignt.py/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Dynamic: license-file
+
+# qsignt
+
+[![CI](https://github.com/AmritaBot/qsignt.py/actions/workflows/ci.yml/badge.svg)](https://github.com/AmritaBot/qsignt.py/actions/workflows/ci.yml)
+
+QsigNT signer 的注册工具。在 QQ 群里跑一遍流程，把 apikey 换到本地。
+
+依赖：Python 3.10+、gnupg 2.3+（需要 `gpg` 在 PATH 里）。
+
+## 签名申请入口
+
+签名权限只在 QQ 群 **1132696493** 发放，进群后直接发 `#qsignt init` 就能开始，整个
+流程在群里闭环，不需要单独找人。
+
+群号固定写死在工具里，查一下就知道：
+
+```
+qsignt community
+```
+
+（不联网、不读配置，纯粹回显常量，防的是手抄错号。）
+
+apikey 是组织层面的凭证，按用户发放。仓库这边不发 key、也不提供自助领取，抱着
+clone 下来就跑出权限的期待会落空。
+
+能拿到的东西：
+
+- 一个 `qsig_` 开头的 apikey，由 QsigNT daemon 校验，请求头带 `Authorization: Bearer <apikey>`
+- apikey 与用户一一对应，一人一把，不做共享
+- 限速按用户计，默认 20 请求/秒，超了返回 429 和 `Retry-After`
+
+注册流程只在群里走，私聊不办理。群聊之外的旁路申请一律不接，包括找维护者单独要。
+
+## 为什么是 OpenPGP
+
+QQ 客户端与服务端的身份已由平台担保，需要防的只是群里旁观者顺手读到凭证。
+上行用服务端公钥加密就够了，不需要证书链，也不需要指纹交叉验证。
+
+下行不用 OpenPGP，改用一次性 X25519 + AES-256-GCM：客户端在提交时带上本次流程
+的临时公钥，服务端加密回包即可。少一次密钥交换，载荷也短一半。
+
+## 流程
+
+群里发 `#qsignt init`，机器人回一条带公钥的消息。整段复制，然后：
+
+```
+qsignt enroll --msg "SIGNER-KEY-V1 flow=AB12CD34 exp=10m
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+...
+-----END PGP PUBLIC KEY BLOCK-----"
+```
+
+工具打印一条 `#qsignt key submit ...`，发到群里。
+
+机器人回 `#qsignt key open ...`，复制后：
+
+```
+qsignt open --msg "#qsignt key open AbCd..."
+```
+
+工具把 apikey 存到 `~/.config/qsignt/token.json`（权限 0600），并打印
+`#qsignt verify XXXXXXXX`。发出去，激活完成。
+
+`qsignt show` 随时取回 apikey。
+
+## 服务端
+
+```
+qsignt keygen --out /var/lib/qsignt/gpg          # 生成 bot 密钥对，公钥贴到群里
+qsignt decrypt --home /var/lib/qsignt/gpg --msg "..."
+qsignt seal --eph <客户端公钥> --flow AB12CD34 --json reply.json
+```
+
+## 边界
+
+- 中间中断不会白费：流程状态存在本地，`open` 之前重跑 `enroll` 会重开新流程。
+- 群消息会被折叠，复制时可能带上换行和空格，解析时已做容错。
+- apikey 明文只落在本地文件里，工具不做上传、不做同步。

qsignt-0.1.0/src/qsignt.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/qsignt/__init__.py
+src/qsignt/box.py
+src/qsignt/cli.py
+src/qsignt/pgpx.py
+src/qsignt/proto.py
+src/qsignt.egg-info/PKG-INFO
+src/qsignt.egg-info/SOURCES.txt
+src/qsignt.egg-info/dependency_links.txt
+src/qsignt.egg-info/entry_points.txt
+src/qsignt.egg-info/requires.txt
+src/qsignt.egg-info/top_level.txt
+tests/test_proto.py

qsignt-0.1.0/src/qsignt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qsignt-0.1.0/src/qsignt.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qsignt = qsignt.cli:main

qsignt-0.1.0/src/qsignt.egg-info/requires.txt

@@ -0,0 +1 @@
+cryptography>=42

qsignt-0.1.0/src/qsignt.egg-info/top_level.txt

@@ -0,0 +1 @@
+qsignt

qsignt-0.1.0/tests/test_proto.py

@@ -0,0 +1,38 @@
+import json
+
+import pytest
+from cryptography.exceptions import InvalidTag
+
+from qsignt import box, proto
+
+
+def test_seal_open_roundtrip():
+    priv, pub = box.new_keypair()
+    payload = {"v": 1, "flow": "AB12CD34", "apikey": "qsig_test", "chall": "ZZZZ0000"}
+    blob = box.seal(pub, "AB12CD34", payload)
+    out = box.open_sealed(blob, "AB12CD34", priv)
+    assert out == payload
+
+
+def test_flow_binding_mismatch():
+    priv, pub = box.new_keypair()
+    blob = box.seal(pub, "AB12CD34", {"v": 1})
+    with pytest.raises(InvalidTag):
+        box.open_sealed(blob, "OTHERFLOW", priv)
+
+
+def test_parse_init():
+    armor = "-----BEGIN PGP PUBLIC KEY BLOCK-----\nxx\n-----END PGP PUBLIC KEY BLOCK-----"
+    msg = proto.build_init("AB12CD34", armor, 10)
+    got = proto.parse_init(msg)
+    assert got.flow == "AB12CD34"
+    assert got.expire_minutes == 10
+    assert "BEGIN PGP PUBLIC KEY" in got.armor
+
+
+def test_payload_roundtrip():
+    raw = proto.build_payload("AB12CD34", b"\x01" * 32)
+    data = proto.parse_payload(raw)
+    assert data["flow"] == "AB12CD34"
+    assert len(box.b64d(data["eph"])) == 32
+    assert json.loads(raw)["kind"] == "enroll"