hipp-https-agent 0.2.0__tar.gz

hipp_https_agent-0.2.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: hipp-https-agent
+Version: 0.2.0
+Summary: 在本机申请和续期 HTTPS 证书，并用令牌向服务端上报
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# hipp-https-agent
+
+在需要证书的机器上申请和续期 Let’s Encrypt 证书，并把状态上报到服务端。不需要远程登录这台机器。
+
+服务端地址是 `https://hipp.site/cert/`。程序会自己接上 `/api/...`，不要再加接口路径。末尾斜杠可以留着。
+
+## 安装
+
+在证书机器上用 root 安装。申请证书、写 `/etc/nginx/certs` 和重新加载 Nginx 都需要 root，常驻进程也用这个用户。
+
+```sh
+sudo pip install hipp-https-agent
+```
+
+安装后得到命令 `hipp-agent`。包在 PyPI 上的名字是 `hipp-https-agent`。
+
+先装好 certbot，并准备校验目录：
+
+```sh
+sudo apt-get install -y certbot
+sudo mkdir -p /var/www/acme
+```
+
+## 登记
+
+先在 [https://hipp.site/cert/](https://hipp.site/cert/) 用手机号登录，打开「证书端令牌」，按页面上的安装和登记范例操作。证书端名称要填这台机器的 `hostname`。
+
+再用 root 登记，这样配置会写到 root 的家目录，和后面的常驻进程是同一个用户：
+
+```sh
+sudo hipp-agent register -s https://hipp.site/cert/ -t <令牌>
+```
+
+`-s` 是服务端地址。`-t` 是「证书端令牌」页里的令牌。
+
+配置在 `/root/.config/hipp-agent/config.json`。控制台里与本机 hostname 同名的域名会一并写入。还没有域名时也可以先登记，补上之后常驻进程会自动取回。
+
+## 后台常驻
+
+`hipp-agent run` 是常驻循环：每轮向服务端取配置，按申请、生效、监听推进，并上报心跳。它不会自己退出。直接在终端里跑时，关掉终端进程就没了。
+
+用 systemd 把它留在后台，断线、重启机器之后也会再拉起来：
+
+```sh
+sudo tee /etc/systemd/system/hipp-agent.service >/dev/null <<'EOF'
+[Unit]
+Description=hipp certificate agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/hipp-agent --config /root/.config/hipp-agent/config.json run
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+sudo systemctl daemon-reload
+sudo systemctl enable --now hipp-agent
+```
+
+若 `command -v hipp-agent` 不是 `/usr/local/bin/hipp-agent`，先改单元里的 `ExecStart` 再执行。仓库里的 `deploy/hipp-agent.service` 与上面这段相同，给仍从源码安装的人用。
+
+查看是否在跑：
+
+```sh
+systemctl status hipp-agent
+journalctl -u hipp-agent -n 50 --no-pager
+```
+
+停掉或重新拉起：
+
+```sh
+sudo systemctl stop hipp-agent
+sudo systemctl restart hipp-agent
+```
+
+控制台「证书状态」里，最后上报在 3 分钟内为程序在运行。

hipp_https_agent-0.2.0/README.md

@@ -0,0 +1,79 @@
+# hipp-https-agent
+
+在需要证书的机器上申请和续期 Let’s Encrypt 证书，并把状态上报到服务端。不需要远程登录这台机器。
+
+服务端地址是 `https://hipp.site/cert/`。程序会自己接上 `/api/...`，不要再加接口路径。末尾斜杠可以留着。
+
+## 安装
+
+在证书机器上用 root 安装。申请证书、写 `/etc/nginx/certs` 和重新加载 Nginx 都需要 root，常驻进程也用这个用户。
+
+```sh
+sudo pip install hipp-https-agent
+```
+
+安装后得到命令 `hipp-agent`。包在 PyPI 上的名字是 `hipp-https-agent`。
+
+先装好 certbot，并准备校验目录：
+
+```sh
+sudo apt-get install -y certbot
+sudo mkdir -p /var/www/acme
+```
+
+## 登记
+
+先在 [https://hipp.site/cert/](https://hipp.site/cert/) 用手机号登录，打开「证书端令牌」，按页面上的安装和登记范例操作。证书端名称要填这台机器的 `hostname`。
+
+再用 root 登记，这样配置会写到 root 的家目录，和后面的常驻进程是同一个用户：
+
+```sh
+sudo hipp-agent register -s https://hipp.site/cert/ -t <令牌>
+```
+
+`-s` 是服务端地址。`-t` 是「证书端令牌」页里的令牌。
+
+配置在 `/root/.config/hipp-agent/config.json`。控制台里与本机 hostname 同名的域名会一并写入。还没有域名时也可以先登记，补上之后常驻进程会自动取回。
+
+## 后台常驻
+
+`hipp-agent run` 是常驻循环：每轮向服务端取配置，按申请、生效、监听推进，并上报心跳。它不会自己退出。直接在终端里跑时，关掉终端进程就没了。
+
+用 systemd 把它留在后台，断线、重启机器之后也会再拉起来：
+
+```sh
+sudo tee /etc/systemd/system/hipp-agent.service >/dev/null <<'EOF'
+[Unit]
+Description=hipp certificate agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/hipp-agent --config /root/.config/hipp-agent/config.json run
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+sudo systemctl daemon-reload
+sudo systemctl enable --now hipp-agent
+```
+
+若 `command -v hipp-agent` 不是 `/usr/local/bin/hipp-agent`，先改单元里的 `ExecStart` 再执行。仓库里的 `deploy/hipp-agent.service` 与上面这段相同，给仍从源码安装的人用。
+
+查看是否在跑：
+
+```sh
+systemctl status hipp-agent
+journalctl -u hipp-agent -n 50 --no-pager
+```
+
+停掉或重新拉起：
+
+```sh
+sudo systemctl stop hipp-agent
+sudo systemctl restart hipp-agent
+```
+
+控制台「证书状态」里，最后上报在 3 分钟内为程序在运行。

hipp_https_agent-0.2.0/hipp_agent/__init__.py

@@ -0,0 +1,3 @@
+"""为 hipp.ink 与 hipp.site 调用系统 certbot 申请和续期证书。"""
+
+__version__ = "0.2.0"

hipp_https_agent-0.2.0/hipp_agent/__main__.py

@@ -0,0 +1,83 @@
+"""命令行入口。不加 --apply 时只打印，不向证书机构申请。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from hipp_agent.config import (
+    ConfigError,
+    default_config_path,
+    load_config,
+    project_root,
+    resolve_config_path,
+)
+from hipp_agent.daemon import run_daemon
+from hipp_agent.register import register_agent
+from hipp_agent.runner import build_plan, deploy, install_hook, issue, renew, report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="为 hipp.ink 与 hipp.site 申请和续期 HTTPS 证书")
+    parser.add_argument("--config", help="配置文件路径。默认使用登记后的用户配置，否则用当前目录的 config.json")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    register_cmd = sub.add_parser("register", help="用服务端地址和令牌登记本机")
+    register_cmd.add_argument("-s", "--server", required=True, help="服务端根地址，不要带具体接口路径")
+    register_cmd.add_argument("-t", "--token", required=True, help="业务配置中的令牌")
+
+    plan = sub.add_parser("plan", help="打印命令并写出 Nginx 片段")
+    plan.add_argument("--out", default="", help="片段输出目录，默认 <仓库>/out")
+
+    issue_cmd = sub.add_parser("issue", help="探测通过后调用 certbot 申请")
+    issue_cmd.add_argument("--apply", action="store_true", help="真正执行。省略时只打印")
+
+    renew_cmd = sub.add_parser("renew", help="在本机调用 certbot renew，并安装到指定路径")
+    renew_cmd.add_argument("--apply", action="store_true", help="真正执行。省略时只打印")
+    renew_cmd.add_argument("--dry-run", action="store_true", help="与 --apply 合用，只演练续期")
+
+    deploy_cmd = sub.add_parser("deploy", help="把已签出的证书写到指定文件名并重新加载 Nginx")
+    deploy_cmd.add_argument("--apply", action="store_true", help="真正执行。省略时只打印")
+
+    report_cmd = sub.add_parser("report", help="读取已安装证书并上报，不重新加载 Nginx")
+    report_cmd.add_argument("--apply", action="store_true", help="真正上报。省略时只打印")
+
+    hook_cmd = sub.add_parser("install-hook", help="安装续期后写证书并重新加载 Nginx 的钩子")
+    hook_cmd.add_argument("--apply", action="store_true", help="真正写入。省略时只打印")
+
+    sub.add_parser("run", help="常驻：按周期续期、写证书，并向服务端心跳")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "register":
+            path = Path(args.config) if args.config else default_config_path()
+            sys.stdout.write(register_agent(args.server, args.token, path))
+            return 0
+        config = load_config(resolve_config_path(args.config))
+        if args.command == "run":
+            run_daemon(config)
+            return 0
+        if args.command == "plan":
+            out = Path(args.out) if args.out else project_root() / "out"
+            sys.stdout.write(build_plan(config, out))
+            return 0
+        if args.command == "renew":
+            code, text = renew(config, apply=args.apply, dry_run=args.dry_run)
+        elif args.command == "deploy":
+            code, text = deploy(config, apply=args.apply)
+        elif args.command == "report":
+            code, text = report(config, apply=args.apply)
+        elif args.command == "install-hook":
+            code, text = install_hook(config, apply=args.apply)
+        else:
+            code, text = issue(config, apply=args.apply)
+        sys.stdout.write(text)
+        return code
+    except (ConfigError, PermissionError, OSError) as exc:
+        sys.stderr.write(str(exc) + "\n")
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hipp_https_agent-0.2.0/hipp_agent/certinfo.py

@@ -0,0 +1,42 @@
+"""从已安装的证书文件读取到期时间。不读取私钥。"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def read_certificate(path: Path) -> tuple[str, str, str]:
+    """返回 not_before、not_after 的 UTC 时间和颁发者。读不到时均为空字符串。"""
+    if not path.is_file() or shutil.which("openssl") is None:
+        return "", "", ""
+    completed = subprocess.run(
+        ["openssl", "x509", "-in", str(path), "-noout", "-startdate", "-enddate", "-issuer"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        return "", "", ""
+    not_before = ""
+    not_after = ""
+    issuer = ""
+    for line in completed.stdout.splitlines():
+        if line.startswith("notBefore="):
+            not_before = _openssl_time(line.split("=", 1)[1])
+        elif line.startswith("notAfter="):
+            not_after = _openssl_time(line.split("=", 1)[1])
+        elif line.startswith("issuer="):
+            issuer = line.split("=", 1)[1].strip()
+    return not_before, not_after, issuer
+
+
+def _openssl_time(value: str) -> str:
+    text = value.strip().removesuffix(" GMT")
+    try:
+        parsed = datetime.strptime(text, "%b %d %H:%M:%S %Y")
+    except ValueError:
+        return ""
+    return parsed.replace(tzinfo=timezone.utc).isoformat()

hipp_https_agent-0.2.0/hipp_agent/config.py

@@ -0,0 +1,300 @@
+"""读取并校验证书配置。"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ConfigError(ValueError):
+    """配置不符合签发要求。"""
+
+
+@dataclass
+class CertificateSpec:
+    name: str
+    domains: list[str]
+    tls: str
+    enabled: bool
+    cert_file: str
+    key_file: str
+    validity_days: int = 90
+    account_email: str = ""
+    agree_tos: bool | None = None
+    organization: str = ""
+    organization_unit: str = ""
+
+
+@dataclass
+class AppConfig:
+    account_email: str
+    agree_tos: bool
+    webroot: str
+    staging: bool
+    server_name: str
+    report_url: str
+    report_token: str
+    certificates: list[CertificateSpec]
+    path: Path
+    retry_seconds: int = 60
+    organization: str = ""
+    organization_unit: str = ""
+
+
+def project_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def default_config_path() -> Path:
+    return Path.home() / ".config" / "hipp-agent" / "config.json"
+
+
+def resolve_config_path(explicit: str | None) -> Path:
+    if explicit:
+        return Path(explicit)
+    home = default_config_path()
+    if home.is_file():
+        return home
+    root = project_root()
+    local = root / "config.json"
+    if local.is_file():
+        return local
+    example = root / "config.example.json"
+    if example.is_file():
+        return example
+    return home
+
+
+def load_config(path: Path) -> AppConfig:
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ConfigError(f"找不到配置文件：{path}") from exc
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"配置不是合法 JSON：{path}（{exc}）") from exc
+    return parse_config(raw, path)
+
+
+def parse_config(raw: object, path: Path) -> AppConfig:
+    if not isinstance(raw, dict):
+        raise ConfigError("配置根节点必须是对象")
+
+    webroot = _abs_path(raw.get("webroot"), "webroot")
+    email = raw.get("account_email", "")
+    if not isinstance(email, str):
+        raise ConfigError("account_email 必须是字符串")
+    agree = raw.get("agree_tos", False)
+    if not isinstance(agree, bool):
+        raise ConfigError("agree_tos 必须是 true 或 false")
+    staging = raw.get("staging", False)
+    if not isinstance(staging, bool):
+        raise ConfigError("staging 必须是 true 或 false")
+
+    server_name = raw.get("server_name", "")
+    if not isinstance(server_name, str) or any(char in server_name for char in "\r\n"):
+        raise ConfigError("server_name 必须是一行内的字符串")
+    server_name = server_name.strip()
+    if len(server_name) > 64:
+        raise ConfigError("server_name 最长 64 个字符")
+
+    report_url = raw.get("report_url", "")
+    if not isinstance(report_url, str):
+        raise ConfigError("report_url 必须是字符串")
+    report_url = report_url.strip().rstrip("/")
+    if report_url and not (report_url.startswith("http://") or report_url.startswith("https://")):
+        raise ConfigError("report_url 必须以 http:// 或 https:// 开头")
+    report_token = raw.get("report_token", "")
+    if not isinstance(report_token, str):
+        raise ConfigError("report_token 必须是字符串")
+    report_token = report_token.strip()
+    if report_url and not report_token:
+        raise ConfigError("写了 report_url 时必须填写 report_token")
+    if any(char.isspace() for char in report_token):
+        raise ConfigError("report_token 不能含空白")
+
+    items = raw.get("certificates")
+    if items is None:
+        items = []
+    if not isinstance(items, list):
+        raise ConfigError("certificates 必须是数组")
+
+    specs = [_certificate(item, webroot) for item in items]
+    names = [item.name for item in specs]
+    if len(names) != len(set(names)):
+        raise ConfigError("certificates[].name 不能重复")
+    retry_seconds = _bounded_int(raw.get("retry_seconds", 60), 60, 3600, "retry_seconds")
+    organization = _optional_line(raw.get("organization", ""), "organization")
+    organization_unit = _optional_line(raw.get("organization_unit", ""), "organization_unit")
+
+    return AppConfig(
+        account_email=email.strip(),
+        agree_tos=agree,
+        webroot=webroot,
+        staging=staging,
+        server_name=server_name,
+        report_url=report_url,
+        report_token=report_token,
+        certificates=specs,
+        path=path,
+        retry_seconds=retry_seconds,
+        organization=organization,
+        organization_unit=organization_unit,
+    )
+
+
+def dump_config(config: AppConfig) -> dict:
+    return {
+        "account_email": config.account_email,
+        "agree_tos": config.agree_tos,
+        "organization": config.organization,
+        "organization_unit": config.organization_unit,
+        "webroot": config.webroot,
+        "staging": config.staging,
+        "server_name": config.server_name,
+        "report_url": config.report_url,
+        "report_token": config.report_token,
+        "retry_seconds": config.retry_seconds,
+        "certificates": [
+            {
+                "name": item.name,
+                "domains": item.domains,
+                "tls": item.tls,
+                "enabled": item.enabled,
+                "cert_file": item.cert_file,
+                "key_file": item.key_file,
+                "validity_days": item.validity_days,
+                "account_email": item.account_email,
+                "agree_tos": item.agree_tos,
+                "organization": item.organization,
+                "organization_unit": item.organization_unit,
+            }
+            for item in config.certificates
+        ],
+    }
+
+
+def write_config(path: Path, raw: dict) -> AppConfig:
+    """先校验，再写入。校验失败时不改已有文件。"""
+    config = parse_config(raw, path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(json.dumps(dump_config(config), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.chmod(0o600)
+    temporary.replace(path)
+    path.chmod(0o600)
+    return config
+
+
+def _optional_line(value: object, label: str) -> str:
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise ConfigError(f"{label} 必须是字符串")
+    text = value.strip()
+    if any(char in text for char in "\r\n") or len(text) > 64:
+        raise ConfigError(f"{label} 须为一行，最长 64 个字符")
+    return text
+
+
+def certificate_email(config: AppConfig, spec: CertificateSpec) -> str:
+    return spec.account_email or config.account_email
+
+
+def certificate_agreed(config: AppConfig, spec: CertificateSpec) -> bool:
+    if spec.agree_tos is None:
+        return config.agree_tos
+    return spec.agree_tos
+
+
+def validate_for_issue(config: AppConfig) -> None:
+    enabled = [item for item in config.certificates if item.enabled]
+    if not enabled:
+        raise ConfigError("没有 enabled 为 true 的证书")
+
+
+def _certificate(item: object, webroot: str) -> CertificateSpec:
+    if not isinstance(item, dict):
+        raise ConfigError("certificates 中的每一项必须是对象")
+    name = _domain(item.get("name"), "name")
+    domains_raw = item.get("domains")
+    if not isinstance(domains_raw, list) or not domains_raw:
+        raise ConfigError(f"{name} 的 domains 不能为空")
+    domains = [_domain(domain, f"{name} 的 domains") for domain in domains_raw]
+    if name not in domains:
+        raise ConfigError(f"{name} 必须出现在自己的 domains 里")
+    tls = item.get("tls")
+    if tls not in ("replace", "enable"):
+        raise ConfigError(f"{name} 的 tls 只能是 replace 或 enable")
+    enabled = item.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise ConfigError(f"{name} 的 enabled 必须是 true 或 false")
+    cert_file = _file_path(item.get("cert_file"), f"{name} 的 cert_file")
+    key_file = _file_path(item.get("key_file"), f"{name} 的 key_file")
+    if cert_file == key_file:
+        raise ConfigError(f"{name} 的证书文件和私钥文件不能是同一路径")
+    if _is_inside(cert_file, webroot) or _is_inside(key_file, webroot):
+        raise ConfigError(f"{name} 的证书和私钥不能放在校验目录 {webroot} 下面")
+    validity_days = _bounded_int(item.get("validity_days", 90), 1, 90, f"{name} 的 validity_days")
+    email = item.get("account_email", "")
+    if not isinstance(email, str):
+        raise ConfigError(f"{name} 的 account_email 必须是字符串")
+    agree = item.get("agree_tos", None)
+    if agree is not None and not isinstance(agree, bool):
+        raise ConfigError(f"{name} 的 agree_tos 必须是 true 或 false")
+    return CertificateSpec(
+        name=name,
+        domains=domains,
+        tls=tls,
+        enabled=enabled,
+        cert_file=cert_file,
+        key_file=key_file,
+        validity_days=validity_days,
+        account_email=email.strip(),
+        agree_tos=agree,
+        organization=_optional_line(item.get("organization", ""), f"{name} 的 organization"),
+        organization_unit=_optional_line(item.get("organization_unit", ""), f"{name} 的 organization_unit"),
+    )
+
+
+def _bounded_int(value: object, low: int, high: int, label: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not low <= value <= high:
+        raise ConfigError(f"{label} 必须是 {low} 到 {high} 的整数")
+    return value
+
+
+def _domain(value: object, label: str) -> str:
+    if not isinstance(value, str):
+        raise ConfigError(f"{label} 必须是字符串")
+    domain = value.strip().lower().rstrip(".")
+    if not domain or any(char.isspace() for char in domain):
+        raise ConfigError(f"{label} 不是合法域名")
+    if "*" in domain:
+        raise ConfigError(f"{domain} 含有通配符。HTTP 文件校验不能申请通配符证书")
+    if "/" in domain or ".." in domain:
+        raise ConfigError(f"{label} 不是合法域名：{domain}")
+    return domain
+
+
+def _file_path(value: object, label: str) -> str:
+    path = _abs_path(value, label)
+    if Path(path).name in ("", ".", ".."):
+        raise ConfigError(f"{label} 必须包含文件名")
+    return path
+
+
+def _is_inside(child: str, parent: str) -> bool:
+    try:
+        Path(child).relative_to(parent)
+    except ValueError:
+        return False
+    return True
+
+
+def _abs_path(value: object, label: str) -> str:
+    if not isinstance(value, str) or not value.startswith("/"):
+        raise ConfigError(f"{label} 必须是绝对路径")
+    path = value.rstrip("/") or "/"
+    if path == "/":
+        raise ConfigError(f"{label} 不能是文件系统根目录")
+    return path