hipp-https-agent 0.2.0__py3-none-any.whl

hipp_agent/__init__.py

@@ -0,0 +1,3 @@
+"""为 hipp.ink 与 hipp.site 调用系统 certbot 申请和续期证书。"""
+
+__version__ = "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_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_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

hipp_agent/daemon.py

@@ -0,0 +1,220 @@
+"""证书端常驻进程：按申请、生效、监听推进，并定期告诉服务端自己还在运行。"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from hipp_agent.certinfo import read_certificate
+from hipp_agent.config import AppConfig, CertificateSpec
+from hipp_agent.install import PublishResult, certificate_stage, describe_installed
+from hipp_agent.render import challenge_help
+from hipp_agent.report import push_report
+from hipp_agent.register import refresh
+from hipp_agent.runner import PreflightError, deploy, issue, preflight, renew
+
+HEARTBEAT_SECONDS = 60
+RENEW_SECONDS = 12 * 60 * 60
+
+
+def run_daemon(config: AppConfig, sleep=time.sleep, clock=time.time) -> None:
+    record = EffectRecord(config.path)
+    attempted: dict[str, float] = {}
+    errors: dict[str, str] = {}
+    waiting: dict[str, str] = {}
+    renew_at = 0.0
+    renew_failed = False
+    while True:
+        now = clock()
+        moment = datetime.fromtimestamp(now, timezone.utc)
+        synced = refresh(config)
+        if synced:
+            print(synced, flush=True)
+        _advance(config, now, attempted, errors, waiting)
+        if _watch_due(config, moment) and _renew_due(now, renew_at, renew_failed, config.retry_seconds):
+            code, text = renew(config, apply=True, dry_run=False)
+            _print(text)
+            renew_at = now
+            renew_failed = code != 0
+            if code != 0:
+                print(f"本轮续期退出码 {code}", flush=True)
+        for spec in config.certificates:
+            if spec.enabled:
+                record.observe(spec, moment)
+        results = describe_installed(config)
+        _annotate(results, config, record, errors, waiting)
+        print(push_report(config, results, agent_status="running"), flush=True)
+        sleep(HEARTBEAT_SECONDS)
+
+
+def _advance(
+    config: AppConfig,
+    now: float,
+    attempted: dict[str, float],
+    errors: dict[str, str],
+    waiting: dict[str, str],
+) -> None:
+    apply_names: list[str] = []
+    activate_names: list[str] = []
+    for spec in config.certificates:
+        if not spec.enabled:
+            continue
+        stage = certificate_stage(spec)
+        if stage != "apply":
+            waiting.pop(spec.name, None)
+        if stage == "watch":
+            errors.pop(spec.name, None)
+            continue
+        previous = attempted.get(spec.name)
+        if previous is not None and now - previous < config.retry_seconds:
+            continue
+        if stage == "apply":
+            apply_names.append(spec.name)
+        else:
+            activate_names.append(spec.name)
+    ready: list[str] = []
+    for name in apply_names:
+        spec = next(item for item in config.certificates if item.name == name)
+        try:
+            for domain in spec.domains:
+                preflight(domain, Path(config.webroot))
+        except PreflightError as exc:
+            waiting[name] = str(exc)
+            errors[name] = str(exc)
+            attempted[name] = now
+            print(f"{name}：等待校验。{exc}", flush=True)
+            continue
+        waiting.pop(name, None)
+        ready.append(name)
+    if ready:
+        code, text = issue(config, apply=True, only=set(ready))
+        _print(text)
+        _remember(ready, code, text, now, attempted, errors)
+    if activate_names:
+        code, text = deploy(config, apply=True, only=set(activate_names))
+        _print(text)
+        _remember(activate_names, code, text, now, attempted, errors)
+
+
+def _remember(
+    names: list[str],
+    code: int,
+    text: str,
+    now: float,
+    attempted: dict[str, float],
+    errors: dict[str, str],
+) -> None:
+    clipped = _clip(text)
+    for name in names:
+        attempted[name] = now
+        if code != 0:
+            errors[name] = clipped
+        else:
+            errors.pop(name, None)
+
+
+def _watch_due(config: AppConfig, moment: datetime) -> bool:
+    for spec in config.certificates:
+        if not spec.enabled or certificate_stage(spec) != "watch":
+            continue
+        _not_before, not_after, _issuer = read_certificate(Path(spec.cert_file))
+        if _within_window(not_after, spec.validity_days, moment):
+            return True
+    return False
+
+
+def _within_window(not_after: str, validity_days: int, moment: datetime) -> bool:
+    if not not_after:
+        return False
+    try:
+        end = datetime.fromisoformat(not_after)
+    except ValueError:
+        return False
+    if end.tzinfo is None:
+        end = end.replace(tzinfo=timezone.utc)
+    remaining_days = (end - moment).total_seconds() / 86400
+    return remaining_days <= max(1, validity_days // 3)
+
+
+def _renew_due(now: float, renew_at: float, failed: bool, retry_seconds: int) -> bool:
+    if renew_at == 0.0:
+        return True
+    wait = retry_seconds if failed else RENEW_SECONDS
+    return now - renew_at >= wait
+
+
+def _annotate(
+    results: list[PublishResult],
+    config: AppConfig,
+    record: "EffectRecord",
+    errors: dict[str, str],
+    waiting: dict[str, str],
+) -> None:
+    specs = {item.name: item for item in config.certificates}
+    for result in results:
+        spec = specs.get(result.name)
+        if spec is None:
+            continue
+        result.stage = "challenge" if spec.name in waiting else certificate_stage(spec)
+        result.validity_days = spec.validity_days
+        result.effective_at = record.effective_at(spec.name)
+        result.help = challenge_help(config.webroot, spec.domains) if spec.name in waiting else ""
+        if result.stage != "watch" and errors.get(spec.name):
+            result.detail = errors[spec.name]
+        if result.stage != "watch":
+            suffix = f"{config.retry_seconds} 秒后重试"
+            base = result.detail.rstrip("。 ")
+            if not base.endswith(suffix):
+                room = 300 - len(suffix) - 1
+                result.detail = f"{base[:room].rstrip('。')}。{suffix}"
+
+
+def _print(text: str) -> None:
+    print(text, end="" if text.endswith("\n") else "\n", flush=True)
+
+
+def _clip(text: str) -> str:
+    return " ".join(text.split())[:300]
+
+
+class EffectRecord:
+    """记住每张证书第一次生效的时间。证书换成新的之后才更新。"""
+
+    def __init__(self, config_path: Path) -> None:
+        self.path = config_path.with_suffix(".state.json")
+        self._items: dict[str, dict] = {}
+        if self.path.is_file():
+            try:
+                raw = json.loads(self.path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                raw = {}
+            if isinstance(raw, dict):
+                self._items = {key: value for key, value in raw.items() if isinstance(value, dict)}
+
+    def effective_at(self, name: str) -> str:
+        value = (self._items.get(name) or {}).get("effective_at") or ""
+        return value if isinstance(value, str) else ""
+
+    def observe(self, spec: CertificateSpec, moment: datetime) -> None:
+        if not Path(spec.cert_file).is_file():
+            return
+        not_before, _not_after, _issuer = read_certificate(Path(spec.cert_file))
+        current = self._items.get(spec.name) or {}
+        previous = current.get("not_before") or ""
+        if current.get("effective_at") and (not not_before or not_before == previous):
+            return
+        self._items[spec.name] = {
+            "effective_at": moment.astimezone(timezone.utc).isoformat(),
+            "not_before": not_before,
+        }
+        self._save()
+
+    def _save(self) -> None:
+        self.path.write_text(json.dumps(self._items, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        try:
+            os.chmod(self.path, 0o600)
+        except OSError:
+            pass