@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lease.py

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+"""lease —— 能力租约：客户端侧的授权闸门（批 C4，2026-09-21）。
+
+为什么需要（以及它为什么不是"防盗版"）：
+  · 客户机上跑的是**本地能力包**，没有服务端依赖就跑得飞起 —— 于是"按能力订阅"只能靠
+    装得上/装不上约束，买了什么全靠自觉。租约把"这一份能力现在还有效吗"变成一个
+    **我们自己签发的、有期限的凭据**，流程执行前查一次即可（轻量、可离线容忍）。
+  · 服务端 `POST /api/argent/lease` 签发（HMAC-SHA256，绑 instanceId + 能力清单 + 到期时间），
+    本地**离线也要能验签** ⇒ 断网不影响在租期内的正常作业（客户机在客户内网里是常态）。
+  · 说明白边界：这是"锁"，不是"保险柜"。拿不到租约时我们会**响亮停住并给人工指南**，
+    而不是偷偷降级；也不会去删客户的数据或产物。
+
+判定（`--check <capability>` 的退出码）：
+  0 允许（租约有效或离线容忍期内）
+  3 宽限（已过期但 ≤ graceUntil：允许跑，但**打醒目告警**并记台账，提示尽快恢复订阅）
+  1 拒绝（超过宽限期 / 该能力不在租约里 / 没有租约且无法联网换新）
+  2 参数或内部错误
+续订提醒（`--remind`）的**输出约定**：带 `⚠️`/`⛔` 才叫"要喊人"（`flow-trigger.sh` 就按这两个
+  符号决定写 stamp / 台账 blocked / 推卡）；不带 ⇒ 只是信息，触发器不产生任何外部动作。
+  「完全没有租约 ∧ 闸门未启用（`lease.enforce=false`）」= 信息：缺租约本就被放行，喊人是噪音；
+  闸门启用、或**租约存在但将到期/已过期** ⇒ 一律照旧告警（判据跟着开关走，不整段静音）。
+用法：
+  python3 scripts/lease.py --status                     # 看本地缓存的租约
+  python3 scripts/lease.py --refresh                    # 向服务端换一份新租约（需要 WHYSHU_API_KEY）
+  python3 scripts/lease.py --check full --flow full      # 闸门（流程执行前调用）
+"""
+from __future__ import annotations
+import argparse, datetime, hashlib, hmac, json, os, pathlib, sys, time, urllib.error, urllib.request
+
+try:
+    from flow_registry import consumer_doc as _registry_doc      # P2a：base + 业务线合并（唯一真源）
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        _p = pathlib.Path(path) if path else (HERE / "flow-requirements.json")
+        return json.loads(_p.read_text(encoding="utf-8"))
+
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / 'lib'))
+from argent_datadir import resolve_data_dir  # noqa: E402  数据目录唯一判据（勿在此复制链）
+DATA = pathlib.Path(resolve_data_dir()['dir'])
+LEASE_FILE = DATA / "lease.json"
+INSTANCE_FILE = DATA / "instance.json"
+EXIT_OK, EXIT_DENY, EXIT_ERR, EXIT_GRACE = 0, 1, 2, 3
+
+
+def _secret() -> str:
+    return (os.environ.get("ARGENT_LEASE_SECRET")
+            or os.environ.get("INSTALL_TICKET_SECRET")
+            or "whyshu-install-ticket-secret")
+
+
+def instance_id() -> str:
+    """机器身份：优先复用遥测的 installId（同一台机器的两个子系统必须同一身份）。
+
+    兼容早期实现写过的其它键（机读为主，读不到就现生成一个并落盘 600）。
+    """
+    for key in ("instanceId", "installId", "id"):
+        try:
+            v = json.loads(INSTANCE_FILE.read_text(encoding="utf-8")).get(key)
+            if v:
+                return str(v)
+        except Exception:                                        # noqa: BLE001
+            continue
+    iid = "inst_" + hashlib.sha256(f"{time.time()}".encode()).hexdigest()[:16]
+    DATA.mkdir(parents=True, exist_ok=True)
+    INSTANCE_FILE.write_text(json.dumps({"instanceId": iid}, ensure_ascii=False) + "\n", encoding="utf-8")
+    try:
+        os.chmod(INSTANCE_FILE, 0o600)
+    except Exception:                                            # noqa: BLE001
+        pass
+    return iid
+
+
+def _registry_lease() -> dict:
+    """注册表里的 `lease` 段（阈值口径的唯一出处；读不到返回空 dict）。"""
+    try:
+        doc = _registry_doc()
+        return doc.get("lease") or {}
+    except Exception:                                            # noqa: BLE001
+        return {}
+
+
+def api_base() -> str:
+    return (os.environ.get("WHYSHU_API_URL") or "https://whyshu.com").rstrip("/")
+
+
+def api_token() -> str:
+    tok = os.environ.get("WHYSHU_API_KEY") or ""
+    if tok:
+        return tok
+    # 与遥测同源：credentials 落盘在 ~/.dsh/argent/*.env（600）
+    for name in ("whyshu.env", "fulfillment.env"):
+        p = DATA / name
+        try:
+            for line in p.read_text(encoding="utf-8").splitlines():
+                t = line.strip()
+                if t.startswith("WHYSHU_API_KEY="):
+                    return t.split("=", 1)[1].strip().strip('"').strip("'")
+        except Exception:                                        # noqa: BLE001
+            continue
+    return ""
+
+
+def signature_of(lease: dict) -> str:
+    """**与服务端逐字一致**的签名串（改了这里必须同步改服务端与测试）。"""
+    caps = sorted(str(c) for c in (lease.get("capabilities") or []))
+    exp = int(lease.get("expiresAtMs") or lease.get("expiresAtMsParsed") or 0)
+    payload = f"{lease.get('leaseId')}.{lease.get('instanceId')}.{exp}.{','.join(caps)}"
+    return hmac.new(_secret().encode(), payload.encode(), hashlib.sha256).hexdigest()
+
+
+def parse_lease(raw: dict) -> dict:
+    """服务端响应 → 本地缓存结构（时间统一存毫秒，便于离线判期）。"""
+    def ms(v):
+        """ISO 字符串 → 毫秒时间戳。**必须按 ISO 里的时区解析**：服务端给的是 `...Z`（UTC），
+        早前用 `time.mktime`（本地时区）解析会整体偏移一个时区（CST 下 8 小时）——
+        对 72h 租期只是几小时的错，但对短租期/宽限边界就是判错。"""
+        if isinstance(v, (int, float)):
+            return int(v)
+        try:
+            dt = datetime.datetime.fromisoformat(str(v).replace("Z", "+00:00"))
+            if dt.tzinfo is None:
+                dt = dt.astimezone()                             # 无时区标记 ⇒ 按本地解释
+            return int(dt.timestamp() * 1000)
+        except Exception:                                        # noqa: BLE001
+            try:
+                return int(time.mktime(time.strptime(str(v)[:19], "%Y-%m-%dT%H:%M:%S")) * 1000)
+            except Exception:                                    # noqa: BLE001
+                return 0
+    return {
+        "leaseId": str(raw.get("leaseId") or ""),
+        "instanceId": str(raw.get("instanceId") or instance_id()),
+        "plan": str(raw.get("plan") or ""),
+        "capabilities": [str(c) for c in (raw.get("capabilities") or [])],
+        "issuedAtMs": ms(raw.get("issuedAt")),
+        "expiresAtMs": ms(raw.get("expiresAt")),
+        "graceUntilMs": ms(raw.get("graceUntil")),
+        "signature": str(raw.get("signature") or ""),
+        "fetchedAt": int(time.time() * 1000),
+    }
+
+
+def read_lease() -> dict:
+    try:
+        return json.loads(LEASE_FILE.read_text(encoding="utf-8"))
+    except Exception:                                            # noqa: BLE001
+        return {}
+
+
+def write_lease(lease: dict) -> None:
+    DATA.mkdir(parents=True, exist_ok=True)
+    tmp = LEASE_FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(lease, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    os.replace(tmp, LEASE_FILE)
+    try:
+        os.chmod(LEASE_FILE, 0o600)
+    except Exception:                                            # noqa: BLE001
+        pass
+
+
+def refresh(ttl_hours: int = 0, caps: list | None = None) -> dict:
+    """向服务端换租约。失败**不抛**：返回 {'error': ...} 交给调用方决定（离线容忍）。"""
+    tok = api_token()
+    if not tok:
+        return {"error": "no-token", "hint": "缺 WHYSHU_API_KEY（~/.dsh/argent/whyshu.env 或进程环境）"}
+    body = {"instanceId": instance_id()}
+    if caps:
+        body["capabilities"] = caps
+    if ttl_hours:
+        body["ttlHours"] = int(ttl_hours)
+    req = urllib.request.Request(f"{api_base()}/api/argent/lease",
+                                 data=json.dumps(body).encode(),
+                                 headers={"Content-Type": "application/json", "Authorization": f"Bearer {tok}"},
+                                 method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=20) as r:
+            raw = json.loads(r.read().decode("utf-8") or "{}")
+    except urllib.error.HTTPError as e:
+        detail = ""
+        try:
+            detail = e.read().decode("utf-8")[:200]
+        except Exception:                                        # noqa: BLE001
+            pass
+        return {"error": f"http-{e.code}", "detail": detail}
+    except Exception as e:                                       # noqa: BLE001
+        return {"error": "offline", "detail": str(e)[:200]}
+    lease = parse_lease(raw)
+    if lease["leaseId"] and lease["expiresAtMs"]:
+        write_lease(lease)
+    return lease
+
+
+def enforcement_on() -> bool:
+    """闸门是否真的拦人：注册表 `lease.enforce`（默认 false）+ 环境变量可临时打开。
+
+    为什么要开关：能力包已经装在客户机上，贸然开闸会让正在跑的生产流程立刻停摆。
+    上线顺序 = 部署服务端 → 客户端拿租约 → 开 enforce → 观察（先 grace 后 deny）。
+    """
+    env = os.environ.get("ARGENT_LEASE_ENFORCE")
+    if env is not None:
+        return env.strip().lower() in ("1", "true", "yes", "on")
+    try:
+        doc = _registry_doc()
+        return bool((doc.get("lease") or {}).get("enforce"))
+    except Exception:                                            # noqa: BLE001
+        return False
+
+
+def days_left(lease: dict | None = None, now_ms: int | None = None) -> float:
+    """租约还剩多少天（负数=已过期）。"""
+    le = lease if lease is not None else read_lease()
+    if not le:
+        return -999.0
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    return (int(le.get("expiresAtMs") or 0) - now) / 86400000.0
+
+
+def grace_left(lease: dict | None = None, now_ms: int | None = None) -> float:
+    """宽限还剩多少天（负数=宽限已过 ⇒ 该停跑）。"""
+    le = lease if lease is not None else read_lease()
+    if not le:
+        return -999.0
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    return (int(le.get("graceUntilMs") or 0) - now) / 86400000.0
+
+
+def needs_refresh(lease: dict | None = None, ahead_hours: float = 12.0, now_ms: int | None = None) -> bool:
+    """要不要现在去换一张新租约：没租约 / 已过期 / 距到期不足 ahead_hours。"""
+    le = lease if lease is not None else read_lease()
+    if not le or not le.get("leaseId"):
+        return True
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    return (int(le.get("expiresAtMs") or 0) - now) <= ahead_hours * 3600 * 1000
+
+
+def check(capability: str, lease: dict | None = None, now_ms: int | None = None) -> dict:
+    """闸门判定（纯函数）：→ {verdict: ok|grace|deny, reason}。"""
+    now = int(now_ms if now_ms is not None else time.time() * 1000)
+    if not enforcement_on():
+        return {"verdict": "ok", "reason": "租约闸门未启用（注册表 lease.enforce=false / \$ARGENT_LEASE_ENFORCE）"}
+    le = lease if lease is not None else read_lease()
+    if not le or not le.get("leaseId"):
+        return {"verdict": "deny", "reason": "no-lease（本机还没有租约：跑一次 lease.py --refresh，"
+                                            "或确认安装时用了 --api-key）"}
+    want = signature_of(le)
+    if le.get("signature") and not hmac.compare_digest(str(le["signature"]), want):
+        return {"verdict": "deny", "reason": "签名不符（租约文件被改过或密钥不一致）⇒ 需重新 --refresh"}
+    if capability and capability not in (le.get("capabilities") or []):
+        return {"verdict": "deny", "reason": f"该能力不在租约里（{capability} ∉ {le.get('capabilities')}）"
+                                            f"：套餐未覆盖或已变更"}
+    if now <= int(le.get("expiresAtMs") or 0):
+        return {"verdict": "ok", "reason": f"租约有效（至 {ms_str(le.get('expiresAtMs'))}）"}
+    if now <= int(le.get("graceUntilMs") or 0):
+        return {"verdict": "grace", "reason": f"已过期但在宽限期内（至 {ms_str(le.get('graceUntilMs'))}）"
+                                             f"⇒ 允许跑但请尽快恢复订阅"}
+    return {"verdict": "deny", "reason": f"租约与宽限期都已过（宽限至 {ms_str(le.get('graceUntilMs'))}）"
+                                        f"⇒ 停跑该能力，联系问述科技续订"}
+
+
+def ms_str(ms) -> str:
+    try:
+        return time.strftime("%Y-%m-%d %H:%M", time.localtime(int(ms) / 1000))
+    except Exception:                                            # noqa: BLE001
+        return "?"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="能力租约（客户端闸门）")
+    ap.add_argument("--status", action="store_true")
+    ap.add_argument("--refresh", action="store_true")
+    ap.add_argument("--check")
+    ap.add_argument("--flow", help="仅用于日志/台账（--check 时的流程名）")
+    ap.add_argument("--ttl-hours", type=int, default=0)
+    ap.add_argument("--refresh-if-needed", action="store_true",
+                    help="只在快到期/没租约时才换租约（定时器每轮调用；不打扰服务端）")
+    ap.add_argument("--ahead-hours", type=float, default=0, help="--refresh-if-needed 的提前量（默认取注册表 lease.refreshAheadHours=12）")
+    ap.add_argument("--remind", action="store_true",
+                    help="续订提醒：租约剩余不足注册表 lease.remindDays 时打印提醒（供触发器推飞书卡）")
+    ap.add_argument("--days", type=float, default=0, help="--remind 的天数阈值（默认取注册表）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+
+    if a.refresh:
+        out = refresh(a.ttl_hours)
+        if a.json:
+            print(json.dumps(out, ensure_ascii=False))
+        elif out.get("error"):
+            print(f"  ❌ 换租约失败：{out.get('error')} {out.get('detail') or out.get('hint') or ''}", file=sys.stderr)
+            return EXIT_ERR
+        else:
+            print(f"  ✅ 新租约 {out['leaseId']}｜plan={out['plan']}｜能力={','.join(out['capabilities'])}"
+                  f"｜有效至 {ms_str(out['expiresAtMs'])}（宽限至 {ms_str(out['graceUntilMs'])}）")
+        return EXIT_OK if not out.get("error") else EXIT_ERR
+
+    if a.refresh_if_needed:
+        ahead = a.ahead_hours or float((_registry_lease() or {}).get("refreshAheadHours") or 12)
+        if not needs_refresh(None, ahead):
+            if a.json:
+                print(json.dumps({"refreshed": False, "daysLeft": round(days_left(), 2)}, ensure_ascii=False))
+            return EXIT_OK
+        out = refresh()
+        if out.get("error"):
+            # 换不到**不是错误**（离线容忍）：宽限期内继续跑，由 --remind / 触发器的检查负责喊人
+            print(f"  ⚠️ 换租约失败（{out.get('error')}）——沿用旧租约，剩余 {days_left():.1f} 天"
+                  + (f"（宽限 {grace_left():.1f} 天）" if grace_left() > 0 else ""), file=sys.stderr)
+            return EXIT_OK
+        print(f"  ✅ 租约已续：{out['leaseId']}｜有效至 {ms_str(out['expiresAtMs'])}（{days_left(out):.1f} 天）")
+        return EXIT_OK
+
+    if a.remind:
+        le = read_lease()
+        days = a.days or float((_registry_lease() or {}).get("remindDays") or 7)
+        dl, gl = days_left(le), grace_left(le)
+        if not le:
+            # 「完全没有租约」**不是一种状态，而是两种**（2026-10-08 误报治理）：
+            #   · 闸门**开着**（lease.enforce=true / $ARGENT_LEASE_ENFORCE）⇒ 真问题：这台机器
+            #     **跑不了**能力 ⇒ 照旧 ⚠️ 喊人续订（触发器据此写 stamp + 台账 blocked + 推卡）。
+            #   · 闸门**关着**（默认 false）⇒ `check()` 第一条就 return ok，缺租约**由设计放行**
+            #     （BYO/未登录问述/离线许可的机器就是这个常态）⇒ 再喊人是**纯噪音**：
+            #     触发器每天写一次 stamp + 台账 blocked + 推（推不出去的）卡，台账钩子又把
+            #     blocked 采成 `needs_agent` 遥测 ⇒ 污染真失败信号（客户机实测每天一条，
+            #     10 条无一可处置）。故这里只打**普通信息**（无 ⚠️/⛔ ⇒ 触发器不会认成提醒）。
+            # 判据**必须跟着闸门开关走**：直接用闸门自己的 `enforcement_on()`（注册表 + 环境变量
+            # 同一条判据），不另立第二份；开关一打开，下一轮立即恢复喊人。
+            # 「租约存在但将到期/已过期」不受本分支影响（下面照旧告警）—— 不能整段静音。
+            if not enforcement_on():
+                print("ℹ️ 本机没有能力租约；但租约闸门未启用（注册表 lease.enforce=false）⇒ 缺租约按设计"
+                      "放行，无需续订（要开始收租约：先跑 `lease.py --refresh`，再把 lease.enforce 改 true）")
+                return EXIT_OK
+            print("⚠️ 本机没有能力租约（跑 `lease.py --refresh` 或检查 WHYSHU_API_KEY）")
+            return EXIT_OK
+        if dl > days:
+            if a.json:
+                print(json.dumps({"daysLeft": round(dl, 2), "needRemind": False}, ensure_ascii=False))
+            return EXIT_OK
+        if dl >= 0:
+            print(f"⚠️ 能力租约将在 {dl:.1f} 天后到期（{ms_str(le.get('expiresAtMs'))}）；"
+                  f"若未自动续订，到期后 7 天宽限（至 {ms_str(le.get('graceUntilMs'))}）内仍可跑，之后对应能力停跑")
+        else:
+            print(f"⛔ 能力租约已过期 {-dl:.1f} 天（宽限剩 {max(0.0, gl):.1f} 天，至 {ms_str(le.get('graceUntilMs'))}）"
+                  f"—— 请尽快续订，否则对应能力将被停跑")
+        return EXIT_OK
+
+    if a.status:
+        le = read_lease()
+        if not le:
+            print("  本机还没有租约（跑 --refresh）" if not a.json else json.dumps({"lease": None}, ensure_ascii=False))
+            return EXIT_OK
+        v = check("", le)
+        if a.json:
+            print(json.dumps({"lease": le, "verdict": v["verdict"], "reason": v["reason"],
+                              "instanceId": instance_id(),
+                              "daysLeft": round(days_left(le), 2), "graceDaysLeft": round(grace_left(le), 2)},
+                             ensure_ascii=False, indent=2))
+        else:
+            print(f"  租约 {le.get('leaseId')}｜plan={le.get('plan')}｜能力={','.join(le.get('capabilities') or [])}")
+            print(f"  有效至 {ms_str(le.get('expiresAtMs'))}（剩 {days_left(le):.1f} 天）"
+                  f"｜宽限至 {ms_str(le.get('graceUntilMs'))}（剩 {grace_left(le):.1f} 天）"
+                  f"｜判定 {v['verdict']}：{v['reason']}")
+        return EXIT_OK
+
+    if a.check:
+        v = check(a.check)
+        if a.json:
+            print(json.dumps({"capability": a.check, "flow": a.flow, **v}, ensure_ascii=False))
+        else:
+            icon = {"ok": "✅", "grace": "⚠️", "deny": "⛔"}[v["verdict"]]
+            print(f"  {icon} 能力租约（{a.check}{'/' + a.flow if a.flow else ''}）：{v['reason']}")
+        return {"ok": EXIT_OK, "grace": EXIT_GRACE, "deny": EXIT_DENY}[v["verdict"]]
+
+    ap.print_help()
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())