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

hipp_agent/install.py

@@ -0,0 +1,252 @@
+"""把 certbot 签出的证书写到配置指定的文件名，并重新加载 Nginx。"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from hipp_agent.certinfo import read_certificate
+from hipp_agent.config import AppConfig, CertificateSpec, ConfigError
+
+
+@dataclass
+class PublishResult:
+    name: str
+    domains: list[str]
+    cert_file: str
+    key_file: str
+    status: str
+    detail: str
+    not_before: str = ""
+    not_after: str = ""
+    issuer: str = ""
+    stage: str = ""
+    validity_days: int = 0
+    effective_at: str = ""
+    help: str = ""
+    archive_path: str = ""
+    previous_not_before: str = ""
+    previous_not_after: str = ""
+    previous_issuer: str = ""
+
+
+@dataclass
+class _Backup:
+    path: Path
+    existed: bool
+    data: bytes | None
+    mode: int | None
+
+
+def nginx_reload_args(use_systemctl: bool) -> list[str]:
+    if use_systemctl:
+        return ["systemctl", "reload", "nginx"]
+    return ["nginx", "-s", "reload"]
+
+
+def reload_nginx() -> tuple[bool, str]:
+    test = subprocess.run(["nginx", "-t"], capture_output=True, text=True, check=False)
+    if test.returncode != 0:
+        return False, _clip(test.stderr or test.stdout or "nginx -t 未通过")
+    command = nginx_reload_args(shutil.which("systemctl") is not None)
+    completed = subprocess.run(command, capture_output=True, text=True, check=False)
+    if completed.returncode != 0:
+        return False, _clip(completed.stderr or completed.stdout or "重新加载 Nginx 失败")
+    return True, " ".join(command)
+
+
+def publish_all(
+    config: AppConfig,
+    only: set[str] | None = None,
+    reload_fn=None,
+    live_root: Path | None = None,
+) -> list[PublishResult]:
+    if config.staging:
+        raise ConfigError("演练证书不写入 Nginx 使用的路径")
+    if reload_fn is None:
+        reload_fn = reload_nginx
+
+    source_root = live_root or Path("/etc/letsencrypt/live")
+    results: list[PublishResult] = []
+    written: list[tuple[PublishResult, _Backup, _Backup]] = []
+    for spec in config.certificates:
+        if not spec.enabled:
+            continue
+        if only is not None and spec.name not in only:
+            continue
+        result, backups = _stage(spec, source_root)
+        results.append(result)
+        if backups is not None:
+            written.append((result, backups[0], backups[1]))
+
+    if not written:
+        return results
+
+    ok, detail = reload_fn()
+    if not ok:
+        for result, cert_backup, key_backup in written:
+            _restore(cert_backup)
+            _restore(key_backup)
+            _drop_archive(result)
+            result.status = "failed"
+            result.detail = detail
+            _fill_dates(result, Path(result.cert_file))
+        return results
+
+    for result, _cert_backup, _key_backup in written:
+        result.status = "reloaded"
+        result.detail = detail
+        _fill_dates(result, Path(result.cert_file))
+    return results
+
+
+def certificate_stage(spec: CertificateSpec, live_root: Path | None = None) -> str:
+    """申请：签发目录还没有；生效：指定路径未对齐；监听：两边一致。"""
+    root = live_root or Path("/etc/letsencrypt/live")
+    live_cert = root / spec.name / "fullchain.pem"
+    live_key = root / spec.name / "privkey.pem"
+    dest_cert = Path(spec.cert_file)
+    dest_key = Path(spec.key_file)
+    if not live_cert.is_file() or not live_key.is_file():
+        return "apply"
+    if not dest_cert.is_file() or not dest_key.is_file():
+        return "activate"
+    if not _same(live_cert, dest_cert) or not _same(live_key, dest_key):
+        return "activate"
+    return "watch"
+
+
+def describe_installed(config: AppConfig) -> list[PublishResult]:
+    """只读取已经放在指定路径上的证书，不写文件，也不重新加载。"""
+    results: list[PublishResult] = []
+    for spec in config.certificates:
+        if not spec.enabled:
+            continue
+        dest = Path(spec.cert_file)
+        if not dest.is_file():
+            results.append(_blank(spec, "missing", "指定路径上还没有证书文件"))
+            continue
+        result = _blank(spec, "unchanged", "仅上报，未重新加载")
+        _fill_dates(result, dest)
+        results.append(result)
+    return results
+
+
+def _stage(spec: CertificateSpec, live_root: Path) -> tuple[PublishResult, tuple[_Backup, _Backup] | None]:
+    source_cert = live_root / spec.name / "fullchain.pem"
+    source_key = live_root / spec.name / "privkey.pem"
+    dest_cert = Path(spec.cert_file)
+    dest_key = Path(spec.key_file)
+    if dest_cert.is_dir() or dest_key.is_dir():
+        return _blank(spec, "failed", "目标路径是目录，不能当作证书文件"), None
+    if not source_cert.is_file() or not source_key.is_file():
+        return _blank(spec, "missing", "live 目录里还没有这张证书"), None
+    if _same(source_cert, dest_cert) and _same(source_key, dest_key):
+        _ensure_mode(dest_cert, 0o644)
+        _ensure_mode(dest_key, 0o600)
+        result = _blank(spec, "unchanged", "")
+        _fill_dates(result, dest_cert)
+        return result, None
+
+    cert_backup = _snapshot(dest_cert)
+    key_backup = _snapshot(dest_key)
+    result = _blank(spec, "pending", "")
+    if dest_cert.is_file():
+        result.previous_not_before, result.previous_not_after, result.previous_issuer = read_certificate(dest_cert)
+        result.archive_path = _copy_archive(spec, dest_cert, dest_key)
+    try:
+        _atomic_write(dest_cert, source_cert.read_bytes(), 0o644)
+        _atomic_write(dest_key, source_key.read_bytes(), 0o600)
+    except OSError:
+        _restore(cert_backup)
+        _restore(key_backup)
+        _drop_archive(result)
+        raise
+    return result, (cert_backup, key_backup)
+
+
+def _blank(spec: CertificateSpec, status: str, detail: str) -> PublishResult:
+    return PublishResult(
+        name=spec.name,
+        domains=list(spec.domains),
+        cert_file=spec.cert_file,
+        key_file=spec.key_file,
+        status=status,
+        detail=detail,
+    )
+
+
+def _fill_dates(result: PublishResult, path: Path) -> None:
+    not_before, not_after, issuer = read_certificate(path)
+    result.not_before = not_before
+    result.not_after = not_after
+    result.issuer = issuer
+
+
+def _same(source: Path, dest: Path) -> bool:
+    if not dest.is_file():
+        return False
+    return source.read_bytes() == dest.read_bytes()
+
+
+def _ensure_mode(path: Path, mode: int) -> None:
+    if path.is_file() and (path.stat().st_mode & 0o777) != mode:
+        os.chmod(path, mode)
+
+
+def _copy_archive(spec: CertificateSpec, dest_cert: Path, dest_key: Path) -> str:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    folder = dest_cert.parent / "archive" / spec.name / stamp
+    folder.mkdir(parents=True, exist_ok=True)
+    cert_copy = folder / "fullchain.pem"
+    cert_copy.write_bytes(dest_cert.read_bytes())
+    os.chmod(cert_copy, 0o644)
+    if dest_key.is_file():
+        key_copy = folder / "privkey.pem"
+        key_copy.write_bytes(dest_key.read_bytes())
+        os.chmod(key_copy, 0o600)
+    return str(folder)
+
+
+def _drop_archive(result: PublishResult) -> None:
+    folder = result.archive_path
+    result.archive_path = ""
+    result.previous_not_before = ""
+    result.previous_not_after = ""
+    result.previous_issuer = ""
+    if not folder:
+        return
+    path = Path(folder)
+    if path.is_dir():
+        shutil.rmtree(path, ignore_errors=True)
+
+
+def _snapshot(path: Path) -> _Backup:
+    if path.is_file():
+        return _Backup(path, True, path.read_bytes(), path.stat().st_mode & 0o777)
+    return _Backup(path, False, None, None)
+
+
+def _restore(backup: _Backup) -> None:
+    if not backup.existed:
+        if backup.path.is_file():
+            backup.path.unlink()
+        return
+    _atomic_write(backup.path, backup.data or b"", backup.mode or 0o644)
+
+
+def _atomic_write(path: Path, data: bytes, mode: int) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(path.name + ".tmp")
+    temporary.write_bytes(data)
+    os.chmod(temporary, mode)
+    os.replace(temporary, path)
+
+
+def _clip(text: str) -> str:
+    compact = " ".join(text.split())
+    return compact[:300]

hipp_agent/register.py

@@ -0,0 +1,134 @@
+"""用令牌向服务端登记本机，并在运行中取回最新配置。"""
+
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from hipp_agent.config import AppConfig, ConfigError, dump_config, parse_config, write_config
+
+
+def register_agent(server: str, token: str, path: Path) -> str:
+    root = _server(server)
+    secret = _token(token)
+    server_name = socket.gethostname().strip()
+    payload = _request(
+        "POST",
+        root + "/api/agent/register",
+        secret,
+        {"server_name": server_name},
+    )
+    config = write_config(path, _document(root, secret, payload, server_name))
+    if config.certificates:
+        names = "、".join(item.name for item in config.certificates)
+        return f"已登记 {config.server_name}，配置写在 {path}，证书：{names}\n"
+    return (
+        f"已登记 {config.server_name}，配置写在 {path}。"
+        "控制台还没有这个名称的域名。补上之后执行 hipp-agent run，会自动取回。\n"
+    )
+
+
+def refresh(config: AppConfig) -> str:
+    """向服务端取该证书端的最新配置。没有变化时返回空字符串。"""
+    if not config.report_url or not config.report_token or not config.server_name:
+        return ""
+    query = urllib.parse.urlencode({"server_name": config.server_name})
+    try:
+        payload = _request("GET", config.report_url + "/api/agent/config?" + query, config.report_token, None)
+        fresh = parse_config(_document(config.report_url, config.report_token, payload, config.server_name), config.path)
+    except ConfigError as exc:
+        return f"同步配置失败：{exc}"
+    if dump_config(fresh) == dump_config(config):
+        return ""
+    write_config(config.path, dump_config(fresh))
+    config.account_email = fresh.account_email
+    config.agree_tos = fresh.agree_tos
+    config.organization = fresh.organization
+    config.organization_unit = fresh.organization_unit
+    config.webroot = fresh.webroot
+    config.staging = fresh.staging
+    config.server_name = fresh.server_name
+    config.report_url = fresh.report_url
+    config.report_token = fresh.report_token
+    config.retry_seconds = fresh.retry_seconds
+    config.certificates = fresh.certificates
+    return "已从服务端更新配置"
+
+
+def _document(server: str, token: str, payload: dict, server_name: str) -> dict:
+    retry = payload.get("retry_seconds", 60)
+    if isinstance(retry, bool) or not isinstance(retry, int):
+        retry = 60
+    certificates = payload.get("certificates")
+    if not isinstance(certificates, list):
+        certificates = []
+    return {
+        "account_email": payload.get("account_email") or "",
+        "agree_tos": bool(payload.get("agree_tos")),
+        "organization": payload.get("organization") or "",
+        "organization_unit": payload.get("organization_unit") or "",
+        "webroot": payload.get("webroot") or "/var/www/acme",
+        "staging": False,
+        "server_name": payload.get("server_name") or server_name,
+        "report_url": server,
+        "report_token": token,
+        "retry_seconds": retry,
+        "certificates": certificates,
+    }
+
+
+def _server(value: str) -> str:
+    root = value.strip().rstrip("/")
+    if not (root.startswith("http://") or root.startswith("https://")):
+        raise ConfigError("服务端地址必须以 http:// 或 https:// 开头")
+    return root
+
+
+def _token(value: str) -> str:
+    token = value.strip()
+    if not token or any(char.isspace() for char in token):
+        raise ConfigError("令牌不能为空，也不能含空白")
+    return token
+
+
+def _request(method: str, url: str, token: str, body: dict | None) -> dict:
+    data = None if body is None else json.dumps(body).encode("utf-8")
+    request = urllib.request.Request(url, data=data, method=method)
+    request.add_header("Authorization", "Bearer " + token)
+    request.add_header("Accept", "application/json")
+    if data is not None:
+        request.add_header("Content-Type", "application/json")
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            raw = response.read().decode("utf-8", errors="replace")
+            status = response.status
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        message = _detail(detail) or f"服务端返回 {exc.code}"
+        raise ConfigError(message) from exc
+    except OSError as exc:
+        raise ConfigError(f"连不上服务端：{exc}") from exc
+    if status >= 400:
+        raise ConfigError(f"服务端返回 {status}")
+    try:
+        payload = json.loads(raw) if raw else {}
+    except json.JSONDecodeError as exc:
+        raise ConfigError("服务端返回不是 JSON") from exc
+    if not isinstance(payload, dict):
+        raise ConfigError("服务端返回不是 JSON 对象")
+    return payload
+
+
+def _detail(raw: str) -> str:
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return raw.strip()[:200]
+    if isinstance(payload, dict):
+        detail = payload.get("detail") or payload.get("message") or ""
+        return str(detail)[:200]
+    return ""

hipp_agent/render.py

@@ -0,0 +1,95 @@
+"""拼出 certbot 命令，并生成贴进现有 Nginx 的片段。"""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+
+from hipp_agent.config import AppConfig, CertificateSpec, certificate_email
+
+
+def certbot_issue_args(config: AppConfig, spec: CertificateSpec, certbot_bin: str) -> list[str]:
+    command = [
+        certbot_bin,
+        "certonly",
+        "--webroot",
+        "--webroot-path",
+        config.webroot,
+        "--cert-name",
+        spec.name,
+        "--email",
+        certificate_email(config, spec),
+        "--agree-tos",
+        "--non-interactive",
+        "--keep-until-expiring",
+    ]
+    if config.staging:
+        command.append("--staging")
+    for domain in spec.domains:
+        command.extend(["--domain", domain])
+    return command
+
+
+def format_command(command: list[str]) -> str:
+    return shlex.join(command)
+
+
+def render_acme_snippet(webroot: str) -> str:
+    return (
+        "# 放到正在应答该域名 80 端口的 server 内，并位于 return 301 之前。\n"
+        "# 不要把本文件以 .conf 放到 conf.d，避免被 http 直接加载。\n"
+        "location ^~ /.well-known/acme-challenge/ {\n"
+        '    default_type "text/plain";\n'
+        f"    root {webroot};\n"
+        "    try_files $uri =404;\n"
+        "    error_page 404 = @hipp_acme_missing;\n"
+        "}\n"
+        "location @hipp_acme_missing {\n"
+        '    default_type "text/plain";\n'
+        "    error_page 405 =405;\n"
+        '    return 404 "not found\\n";\n'
+        "}\n"
+    )
+
+
+def challenge_help(webroot: str, domains: list[str]) -> str:
+    """给操作者看的配置说明。程序不根据这段说明去改 Nginx。"""
+    names = "、".join(domains)
+    return (
+        "等待 .well-known/acme-challenge\n\n"
+        f"证书端会探测 http://<域名>/.well-known/acme-challenge/<令牌>。当前域名：{names}。\n"
+        "在读到探测文件之前，不会向证书机构申请，也不会修改 Nginx。\n\n"
+        "请自行把下面片段放进正在应答该域名 80 端口的 server，位于任何 return 301 之前。\n"
+        "不要把片段以 .conf 放到 conf.d，避免被 http 直接加载。\n\n"
+        f"{render_acme_snippet(webroot)}\n"
+        "然后执行：nginx -t && systemctl reload nginx\n"
+        "校验通过后，证书端才会继续申请、生效和监听。"
+    )
+
+
+def render_tls_snippet(spec: CertificateSpec) -> str:
+    lines = [
+        f"# {spec.name} 使用固定文件名。续期只覆盖这两个文件，再重新加载 Nginx，不重启进程。",
+    ]
+    if spec.tls == "enable":
+        lines.append("# 放进现有 server。不要加 return 301，不要加 HSTS。")
+        lines.append("listen 443 ssl http2;")
+    else:
+        lines.append("# 用下面两行替换现有 ssl_certificate 与 ssl_certificate_key。不要改 HSTS，不要新增 listen。")
+    lines.append(f"ssl_certificate     {spec.cert_file};")
+    lines.append(f"ssl_certificate_key {spec.key_file};")
+    if spec.tls == "enable":
+        lines.append("ssl_protocols TLSv1.2 TLSv1.3;")
+    return "\n".join(lines) + "\n"
+
+
+def write_snippets(config: AppConfig, out_dir: Path) -> list[Path]:
+    """只写校验说明。HTTPS 和监听端口由用户自己配置，这里不生成。"""
+    nginx_dir = out_dir / "nginx"
+    nginx_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for spec in config.certificates:
+        acme = nginx_dir / f"{spec.name}.acme.inc"
+        acme.write_text(render_acme_snippet(config.webroot), encoding="utf-8")
+        written.append(acme)
+    return written

hipp_agent/report.py

@@ -0,0 +1,65 @@
+"""把本机证书状态送到状态页。正文只有路径和到期时间。"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import urllib.error
+import urllib.request
+
+from hipp_agent.config import AppConfig
+from hipp_agent.install import PublishResult
+
+
+def server_label(config: AppConfig) -> str:
+    if config.server_name:
+        return config.server_name
+    return socket.gethostname() or "未命名"
+
+
+def push_report(config: AppConfig, results: list[PublishResult], agent_status: str = "running") -> str:
+    if not config.report_url:
+        return "未配置 report_url，跳过上报"
+    payload = {
+        "server_name": server_label(config),
+        "agent_status": agent_status,
+        "pid": os.getpid(),
+        "certificates": [
+            {
+                "name": item.name,
+                "domains": item.domains,
+                "not_before": item.not_before,
+                "not_after": item.not_after,
+                "issuer": item.issuer,
+                "cert_file": item.cert_file,
+                "key_file": item.key_file,
+                "reload_status": item.status if item.status != "pending" else "failed",
+                "detail": item.detail,
+                "stage": item.stage,
+                "validity_days": item.validity_days,
+                "effective_at": item.effective_at,
+                "help": item.help,
+                "archive_path": item.archive_path,
+                "previous_not_before": item.previous_not_before,
+                "previous_not_after": item.previous_not_after,
+                "previous_issuer": item.previous_issuer,
+            }
+            for item in results
+        ],
+    }
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    request = urllib.request.Request(
+        config.report_url + "/api/report",
+        data=body,
+        method="POST",
+    )
+    request.add_header("Authorization", "Bearer " + config.report_token)
+    request.add_header("Content-Type", "application/json")
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            return f"已上报（{response.status}）"
+    except urllib.error.HTTPError as exc:
+        return f"上报失败（{exc.code}）"
+    except OSError as exc:
+        return f"上报失败：{exc}"