@luckypiggy/zhihu-ai-cli 0.1.0-test.1

package/README.md

@@ -0,0 +1,92 @@
+# @luckypiggy/zhihu-ai-cli — 智护 Pilot CLI 测试发布包
+
+智护 Pilot CLI P1 只读能力切片提供安全的本机认证闭环：
+
+- `zhihu auth login`：生成 S256 PKCE，打开客户自己的 Pilot 授权页，轮询一次性登录事务，并把仅有的 Pilot CLI Refresh Credential 写入 macOS Keychain 或 Linux Secret Service；
+- `zhihu auth status`：使用本机凭据安全轮换一次，显示 profile、用户/租户、Scope 和 Access Token 到期时间；
+- `zhihu auth logout`：先请求 Pilot 撤销会话，再删除本机凭据；网络失败时保留凭据供重试；
+- `zhihu capabilities list`：通过固定只读网关列出当前登录用户的 canonical Scope 和能力；遇到一次 401 只在 profile 锁内刷新并重试一次；
+- `zhihu employees list`：通过固定只读网关列出当前用户可见的安全数字员工字段；只读请求同样复用 profile 锁内一次 401 重试；
+- `zhihu employees chat <employee-id> --message <text> [--conversation <id>]`：调用 manifest 中允许的只读数字员工并流式输出安全回答；首次请求返回的 opaque `conversation_id` 会在人工模式写到 stderr，后续用 `--conversation` 续接；`--json` 只输出一个最终 envelope；Ctrl+C/断连会尽力取消下游生成；
+- `zhihu assets list [--keyword <text>] [--model <name|code|id>] [--page N] [--page-size N]`：通过固定资产只读网关查询安全投影；模型文本只做名称/编码精确匹配，页码和响应字段严格校验，401 最多刷新并重试一次；
+- `zhihu assets get --id <id>`：通过固定资产详情只读网关读取一个安全投影；资产 ID、响应字段和详情 envelope 严格校验，401 最多刷新并重试一次；
+- `zhihu metrics query --asset <id|ip> --metric <online|cpu|memory|load|disk|io|snmp> [--window 5m..24h] [--max-points N]`：通过固定指标定义查询 VictoriaMetrics；资产 ID 先解析为受控监控 IP，PromQL、VM URL 和标签选择均由 Pilot 服务端固定，响应只返回有限统计和采样点；
+- `zhihu alarms list [--status all|firing|resolved] [--page N] [--page-size N]`：通过固定告警只读网关分页查询安全投影；状态、分页和响应字段严格校验，401 最多刷新并重试一次；
+- `zhihu alarms get --id <id>`：通过固定告警详情只读网关读取单条安全投影；告警 ID、详情 envelope 和响应身份严格校验，401 最多刷新并重试一次；
+- `zhihu incidents diagnose --alarm-id <id>`：通过固定指定告警诊断网关生成结构化证据、确定性分类、稳定结论/置信度/发现/动作 code；仅接受 active signed session 与 `incidents:analyze`、`alarms:read`、`assets:read`、`metrics:read`，固定读取告警详情、精确资产 ID/明确告警 IP 和 allowlist 指标的有界告警事件窗口与最近窗口；客户端不能提供 URL、PromQL、时间窗口、模型提示或 SSH，服务端不调用 LLM、不写数据，30 秒总超时且 401 最多刷新一次；
+- `zhihu inspections run [--model <name|code|id>] [--window 5m..24h]`：通过固定 `/api/zhihu/integrations/v1/inspections/run` 生成结构化 `grade`/`findings`/`actions` 巡检摘要；仅接受 active signed session 与 `inspections:run-readonly`、`assets:read`、`metrics:read`、`alarms:read`，资产和告警各最多 100 条，VM 仅使用 `host_ip`、`instance`、`monitorIp`、`ip`、`agent_hostname` 五类标签并最多解析 10,000 个身份，告警仅按精确资产 ID/IP 关联；客户端不能提供 query 参数、URL、PromQL、任意标签或写操作，30 秒总超时且 401 最多刷新一次；
+- `zhihu install [--base-url <https-url>] [--profile <name>] [--timeout N] [--language zh-CN|en] [--ca-file <absolute-file>] [--codex-skill-dir <absolute-path>] [--skip-login] [--skip-codex] [--force]`：交互 TTY 或显式参数安装向导；按“先安装随包 `zhihu-aiops` Skill → 引导环境配置 → 严格 `/info` 兼容性检查 → 原子写 Profile → 浏览器 OAuth → `doctor`”顺序执行，失败时恢复本地 Profile；非交互/JSON 模式必须显式提供 `--base-url` 和 `--skip-login`；CA 文件只保存绝对路径，不保存证书内容；
+- `zhihu doctor`：结构化检查 Profile/base URL/TLS/CA、OS 凭据存储、Pilot `/api/zhihu/integrations/v1/info` 兼容性、登录状态、能力和 Codex Skill 状态，不会触发登录；
+- `zhihu install codex` / `zhihu uninstall codex`：在临时或用户指定的 Codex Skill 目录原子安装、升级和卸载无密钥的 `zhihu-aiops` Skill；受管文件被修改或目标目录不是本 CLI 创建的安装时默认拒绝，`--force` 仅用于受管安装；
+- `zhihu version`、`zhihu config init`、`zhihu config show --redact` 继续可用。
+
+需要访问已配置环境的命令支持 `--profile`，各命令按帮助说明使用 `--json`。JSON stdout 始终只有一个 success/error envelope；Access/Refresh Token、PKCE secret、授权码和上游正文不会写入 stdout、stderr、日志或 Profile。浏览器无法自动打开时，授权 URL 只作为 stderr 的人工操作提示输出。
+
+当前客户端只访问当前 Profile 的固定 `/api/zhihu/integrations/v1` 路径，拒绝任意 HTTP 重定向和非回环明文 HTTP；Profile 的 CA bundle 用于严格 TLS 校验。macOS 使用 `/usr/bin/security`，Linux 使用固定路径 `/usr/bin/secret-tool`，不提供明文文件 fallback。Refresh rotation 通过 profile 锁和进程内 single-flight 合并，并在 Keychain 写入失败时尝试撤销新会话和清理本机旧值。
+
+本切片提供数字员工、资产、指标、告警、指定告警诊断和巡检只读 `list`/`get`/`query`/`chat`/`diagnose`/`run`，并在包内实现无密钥的外部 `zhihu-aiops` Codex Skill 及其受管安装/卸载，以及本地 `zhihu install` 安装向导。Skill 只调用 `zhihu ... --json`，不读取本机认证材料，不提供写操作或 MCP；客户 URL、npm 发布和正式联调遵循各自发布门禁。安装向导严格验证 `/info` 的服务、协议、版本、能力顺序和 OAuth BFF 配置，拒绝非回环明文 HTTP、重定向、userinfo、query/fragment、符号链接 CA；Profile 与 root current_profile 采用快照恢复，Skill 安装遵守 foreign/modified/force 语义。指定告警诊断只允许 `cpu`/`memory`/`load`/`io`/`disk`/`online`/`unknown` 确定性分类，巡检只允许固定模型/窗口、四个 Scope、资产/告警各 100 条和五类 VM IP 标签，证据不足时保守返回；两条链路均不会接受客户端 URL、PromQL、任意标签或写操作，不调用 LLM，均为 30 秒总超时且 401 最多刷新一次。CLI 只解析签名 JWT 的非敏感展示字段，不以本地解析结果作为授权决策。Chat conversation 映射当前是服务端单 worker 的有界 TTL 内存状态，同进程并发有锁保护；多 worker/多副本部署需要共享状态存储。
+
+## 公网安装契约
+
+目标体验命令为：
+
+```bash
+npx @luckypiggy/zhihu-ai-cli@test install
+```
+
+该命令是包的公网安装入口；客户 URL 和离线 `.tgz` 适用于受控网络或隔离环境。发布与客户联调按批准的发布门禁执行。
+
+`install` 的固定顺序是：
+
+1. 先安装或确认包内 bundled `zhihu-aiops` Skill；Skill 失败时不发起网络请求、不提示环境配置，也不写 Profile。
+2. 引导环境配置，解析 CLI 参数、非空环境变量以及交互/default 值。
+3. 对客户地址执行严格 `/info` 预检，确认服务、协议、版本、能力和 OAuth BFF 契约。
+4. 预检通过后原子写入 Profile/root 指针。
+5. 使用浏览器 OAuth/PKCE 完成登录；令牌不从环境变量或命令行读取，CLI Refresh Credential 只保存到 macOS Keychain 或 Linux Secret Service，Access Token 只在进程内存中短期缓存。
+6. 登录流程结束后运行 `doctor`，输出配置、服务契约、凭据状态和 Skill 状态。
+
+安装向导只支持以下非敏感环境变量，且空值或全空白值按未设置处理：
+
+| 环境变量 | 允许值/用途 |
+| --- | --- |
+| `ZHIHU_PROFILE` | Profile 名称 |
+| `ZHIHU_BASE_URL` | 客户智护 HTTPS 地址 |
+| `ZHIHU_AUTH_MODE=browser` | 唯一支持的认证模式 |
+| `ZHIHU_CA_BUNDLE` | 客户 CA bundle 绝对路径 |
+| `ZHIHU_TIMEOUT` | 请求超时秒数（1～300） |
+
+配置优先级固定为“CLI 参数 > 非空 env > 交互/default”。不支持也不建议 `ZHIHU_ACCESS_TOKEN`、`ZHIHU_USER` 或 `ZHIHU_PASSWORD`；浏览器 OAuth 是唯一认证路径，令牌只通过浏览器 OAuth 获得并由系统凭据库保存 CLI Refresh Credential。安装失败或服务尚未配置时可再次运行 `zhihu install`，向导会保留/恢复一致的本地 Profile。npm `install`/`postinstall` 没有交互钩子，不会在依赖安装阶段启动向导、读取环境变量或打开浏览器。
+
+开发和发布需要 Node.js 22 或更新版本：
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+发布包只包含 `bin/`、编译后的 `dist/*.js`、无密钥的 `assets/codex-skills/`、README 和 package manifest，不包含源码、测试、凭据或 `postinstall` 脚本。正式联调需要 HTTPS 客户地址、真实客户契约（`/info`、OAuth/auth、employees chat、assets、metrics、alarms、incidents diagnose、inspections run）和客户 OS 凭据服务；本地测试覆盖 parser、取消、错误、安装向导非交互校验、Profile 回滚、Skill 安装/卸载和 npm 白名单。客户 URL、npm 发布和跨平台凭据验收按独立门禁执行。
+
+## 完全离线交付（Stage 6A）
+
+离线交付制品由仓库内的纯 Node/npm 脚本生成，不会默认写入仓库。调用方必须先创建一个绝对路径的空目录，再执行：
+
+```bash
+mkdir -p /tmp/zhihu-cli-release
+node scripts/build-offline-release.mjs --output /tmp/zhihu-cli-release
+node scripts/verify-offline-release.mjs --directory /tmp/zhihu-cli-release
+```
+
+制品目录严格包含版本化 `zhihu-ai-cli-<version>.tgz`、CycloneDX 1.5 `sbom.cdx.json`、`manifest.json`、LF 格式的 `SHA256SUMS` 和可单独复制运行的 `verify-release.mjs`。构建拒绝相对路径、根目录、符号链接和非空目录；失败时不会覆盖调用方目录。Manifest 固定声明 `p1-readonly`、Node.js `>=22.0.0`、Integration Protocol `1.0`、`/api/zhihu/integrations/v1` 以及 macOS ARM/x64 和 Linux x64 目标，不宣称 Windows。
+
+Manifest provenance 的 `dirty_scope` 固定为 `packages/zhihu-ai-cli`；`dirty` 只表示 CLI package source scope 是否存在已跟踪改动或未跟踪源文件，不表示整个 monorepo 是否干净。现有 `dist/`、`node_modules/` 和 `releases/` 忽略规则继续排除生成输出、依赖缓存和交付制品；没有 Git 或无法解析 package scope 状态时构建会 fail closed。
+
+离线构建输出目录固定包含五个文件：版本化 CLI `.tgz`、`sbom.cdx.json`、`manifest.json`、`SHA256SUMS` 和可单独运行的 `verify-release.mjs`。复制 verifier 到隔离环境后，可在不安装 npm 依赖的情况下校验五个文件的完整性、allowlist、SBOM 和 provenance；CLI `.tgz` 可使用 `npm install --global --ignore-scripts --offline` 安装。对无法连接服务的安装验收，bundled Skill 会先落地而 Profile 不写入，符合失败回滚契约。
+
+客户安装时可在无网络环境使用本地包（Linux 使用 Node.js >=22，凭据登录需要 `secret-tool`/Secret Service；macOS 使用 Keychain）：
+
+```bash
+npm install --global --prefix /your/prefix --ignore-scripts --offline ./zhihu-ai-cli-<version>.tgz
+/your/prefix/bin/zhihu --version
+```
+
+离线制品与本地校验覆盖 Linux x86_64 禁网场景；真实 OAuth、客户智护 URL、npm 发布、跨平台凭据和客户环境联调需要对应环境与发布门禁。

package/assets/codex-skills/zhihu-aiops/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: zhihu-aiops
+description: 通过智护 Pilot CLI 对登录状态、能力、数字员工、资产、指标、告警、事件诊断和巡检执行安全的只读运维分析。当用户需要查询智护运行状态或解释告警时使用；目标不明确时先询问，不猜测身份或资源。
+---
+
+# 智护 AI 运维
+
+本 Skill 只把明确的结构化查询交给已安装的 `zhihu` CLI，并依据单一 JSON 结果给出分析。先确认用户要看的租户、资产、告警、员工或时间范围，再选择一个最小查询；多个查询之间保留用户给出的精确 ID。
+
+## 工作流程
+
+1. 确认目标和范围。缺少资产 ID、告警 ID、员工 ID、模型或时间窗时提问；不要用名称猜测唯一对象。
+2. 只调用 `zhihu ... --json`，每次调用都等待完整 JSON envelope。不要把诊断参数改写成 URL、查询表达式或任意参数。
+3. 先查认证/能力，再查业务数据；认证失败时仅提示用户运行 `zhihu auth login`，不要要求用户粘贴任何凭据。
+4. 只依据 `ok`、稳定错误码和 `data` 字段回答。字段缺失、对象不唯一或结果过期时明确说明并停止推断。
+5. 对告警或巡检结论引用返回的证据、范围和时间窗；建议动作必须保持在只读排查范围内。
+6. 回复语言跟随当前用户语言；命令和稳定错误码保持原样，解释、确认和结论使用用户选择的中文或英文。
+
+## 可用查询
+
+- `zhihu auth status --json`
+- `zhihu capabilities list --json`
+- `zhihu employees list --json`
+- `zhihu assets list --json` 或 `zhihu assets get --id <id> --json`
+- `zhihu metrics query --asset <id|ip> --metric <online|cpu|memory|load|disk|io|snmp> --window <5m..24h> --json`
+- `zhihu alarms list --status <all|firing|resolved> --json` 或 `zhihu alarms get --id <id> --json`
+- `zhihu incidents diagnose --alarm-id <id> --json`
+- `zhihu inspections run [--model <name|code|id>] [--window <5m..24h>] --json`
+
+筛选、分页、模型和时间窗必须使用 CLI 已声明的取值；不要自行拼接未列出的选项。员工对话只有在用户明确给出员工 ID 和问题时才可使用 `zhihu employees chat <employee-id> --message <text> --json`，不得把对话当作执行变更的入口。
+
+## 输出和安全边界
+
+- 只展示 CLI envelope 中必要的非敏感字段；不要复述认证材料、配置内容、环境变量或本机凭据。
+- 只读命令不等于服务端一定有数据。遇到 `AUTH_RELOGIN_REQUIRED`、`FORBIDDEN`、`CAPABILITY_NOT_AVAILABLE`、`ASSET_NOT_FOUND`、`ALARM_NOT_FOUND`、`DATA_SOURCE_UNAVAILABLE`、`TIMEOUT` 或 `PROTOCOL_ERROR`，说明稳定错误码和下一步，不编造结果。
+- 不直接访问智护服务、监控服务或容器；不执行额外命令，不访问本机配置/凭据存储，不联系外部地址。
+- 本 Skill 不提供 MCP、变更、部署或公网包发布能力；`zhihu install codex` 只安装本地 Skill 文件。
+
+详细命令字段见 [references/commands.md](references/commands.md)，错误处理见 [references/errors.md](references/errors.md)，边界规则见 [references/safety.md](references/safety.md)。

package/assets/codex-skills/zhihu-aiops/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "智护 AI 运维"
+  short_description: "通过智护 CLI 安全执行只读运维分析能力（只读安全）"
+  default_prompt: "Use $zhihu-aiops to inspect an operational issue through the Zhihu Pilot CLI."

package/assets/codex-skills/zhihu-aiops/references/commands.md

@@ -0,0 +1,33 @@
+# CLI 命令参考
+
+所有调用都必须以 `--json` 结束或等价地启用 JSON 模式；只解析一个完整 envelope：成功看 `ok: true` 与 `data`，失败看 `ok: false`、`error.code`、`error.retryable`。
+
+## 会话与能力
+
+| 目的 | 命令 |
+| --- | --- |
+| 查看当前登录状态 | `zhihu auth status --json` |
+| 查看能力范围 | `zhihu capabilities list --json` |
+| 查看可用数字员工 | `zhihu employees list --json` |
+| 发起只读员工问答 | `zhihu employees chat <employee-id> --message <text> --json` |
+
+问答前必须由用户确认员工 ID；`--message` 只描述查询，不描述变更。
+
+## 资产、指标与告警
+
+| 目的 | 命令 |
+| --- | --- |
+| 查资产 | `zhihu assets list [--keyword <text>] [--model <name|code|id>] --json` |
+| 取资产 | `zhihu assets get --id <id> --json` |
+| 查指标 | `zhihu metrics query --asset <id|ip> --metric <allowed-name> --window <5m..24h> --json` |
+| 列告警 | `zhihu alarms list --status <all|firing|resolved> --json` |
+| 取告警 | `zhihu alarms get --id <id> --json` |
+
+资产和告警 ID 必须来自用户或此前 CLI 返回；IP、指标和窗口必须满足 CLI 的白名单与上限。
+
+## 诊断与巡检
+
+- 指定告警分析：`zhihu incidents diagnose --alarm-id <id> --json`
+- 只读巡检摘要：`zhihu inspections run [--model <name|code|id>] [--window <5m..24h>] --json`
+
+诊断和巡检结果是保守的结构化摘要。证据不足时报告不足，不补全设备、租户、权限或因果关系。

package/assets/codex-skills/zhihu-aiops/references/errors.md

@@ -0,0 +1,14 @@
+# 稳定错误处理
+
+只依据 JSON envelope 的稳定 `error.code` 和 `error.retryable`。不要读取原始响应正文，也不要把错误中的路径、地址或调试细节扩散给用户。
+
+常见处理：
+
+- `AUTH_RELOGIN_REQUIRED`：提示用户运行 `zhihu auth login`，然后重试原查询。
+- `FORBIDDEN`、`CAPABILITY_NOT_AVAILABLE`：说明当前账号没有所需范围，请用户联系管理员；不要尝试其他身份。
+- `EMPLOYEE_NOT_FOUND`、`ASSET_NOT_FOUND`、`ALARM_NOT_FOUND`：让用户确认精确 ID；不要从相似名称猜测。
+- `INCIDENT_ASSET_IDENTITY_UNAVAILABLE`、`ASSET_METRIC_IDENTITY_UNAVAILABLE`、`METRIC_DATA_NOT_FOUND`：报告目标无法安全关联或没有数据。
+- `DATA_SOURCE_UNAVAILABLE`、`TIMEOUT`、`NETWORK_ERROR`、`RATE_LIMITED`：保留原查询边界，按 `retryable` 决定是否建议稍后重试。
+- `INVALID_ARGUMENT`、`PROTOCOL_ERROR`、`VERSION_INCOMPATIBLE`：说明 CLI 参数或版本问题，先停止分析。
+
+认证、权限、数据源和协议错误都不能被改写成“正常”或“已修复”。

package/assets/codex-skills/zhihu-aiops/references/safety.md

@@ -0,0 +1,9 @@
+# 安全边界
+
+- 唯一入口是本机 `zhihu` CLI 的 JSON 命令。不要从本机配置、环境变量、凭据服务或日志读取认证材料。
+- 不要直接访问智护 API、监控后端、容器地址或任意网络地址；不要改写请求地址、查询表达式、标签、租户或权限。
+- 不执行额外系统命令，不操作主机、文件、进程、网络设备或部署；不要把 CLI 结果发送给外部服务。
+- 只读范围包括认证状态、能力、数字员工、资产、指标、告警、指定告警诊断和巡检。任何创建、删除、更新、重启、发布或变更请求都应拒绝并说明当前能力限制。
+- 用户没有给出唯一目标时先询问：资产 ID、告警 ID、员工 ID、模型、指标、窗口和语言都不能凭空补全。
+- 结果只保留回答所需的字段。不要输出本机路径、内部地址、完整请求、会话材料或未脱敏正文。
+- 这是本地 Skill，不宣称 MCP、变更能力、在线安装或公网包已经可用。

package/bin/zhihu.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../dist/cli.js";
+
+process.exitCode = await main();

package/dist/auth-service.js

@@ -0,0 +1,204 @@
+import { openSystemBrowser, validAuthorizationUrl } from "./browser.js";
+import { HttpError } from "./http.js";
+import { createPkcePair } from "./pkce.js";
+import { withProfileLock } from "./profile-lock.js";
+import { CliAuthError, TokenManager, decodeClaims, mapFailure } from "./token-manager.js";
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+// ECMAScript Date values are only representable within this inclusive range.
+// JWT NumericDate values outside it must not be allowed to make presentation
+// fail after the refresh credential has already been persisted.
+const MAX_DATE_MILLISECONDS = 8_640_000_000_000_000;
+const DEFAULT_EXPIRES_IN_SECONDS = 900;
+function validDateMilliseconds(value) {
+    return Number.isFinite(value) && value >= 0 && value <= MAX_DATE_MILLISECONDS;
+}
+function safeExpiresAt(now, expiresIn, claims) {
+    const fallbackSeconds = typeof expiresIn === "number" && Number.isFinite(expiresIn) && expiresIn > 0
+        ? expiresIn
+        : DEFAULT_EXPIRES_IN_SECONDS;
+    const baseNow = typeof now === "number" && validDateMilliseconds(now) ? now : Date.now();
+    const fallbackMilliseconds = baseNow + fallbackSeconds * 1000;
+    const safeFallbackMilliseconds = validDateMilliseconds(fallbackMilliseconds)
+        ? fallbackMilliseconds
+        : Math.min(MAX_DATE_MILLISECONDS, Math.max(0, Date.now() + DEFAULT_EXPIRES_IN_SECONDS * 1000));
+    const exp = claims.exp;
+    const expMilliseconds = typeof exp === "number" && Number.isFinite(exp) && exp > 0
+        ? exp * 1000
+        : NaN;
+    const milliseconds = validDateMilliseconds(expMilliseconds) ? expMilliseconds : safeFallbackMilliseconds;
+    try {
+        return new Date(milliseconds).toISOString();
+    }
+    catch {
+        // The fallback above is bounded, but keep presentation total even if a
+        // host supplies an exotic Date implementation in an embedding process.
+        return new Date(0).toISOString();
+    }
+}
+function displayFromToken(profile, token, expiresIn, now, browserOpened) {
+    if (typeof token !== "string" || token.length === 0) {
+        throw new CliAuthError("PROTOCOL_ERROR", "The server returned an invalid login token", { exitCode: 8 });
+    }
+    let claims;
+    try {
+        claims = decodeClaims(token);
+    }
+    catch {
+        // Token claim parsing is presentation-only.  A malformed payload must not
+        // turn a successful login into an unclassified/network failure.
+        claims = {};
+    }
+    const user = typeof claims.zhihu_user_id === "string" ? claims.zhihu_user_id : undefined;
+    const tenant = typeof claims.tenant_id === "string" ? claims.tenant_id : undefined;
+    const scopes = Array.isArray(claims.scopes)
+        ? claims.scopes.filter((item) => typeof item === "string")
+        : typeof claims.scope === "string" ? claims.scope.split(" ").filter(Boolean) : [];
+    return {
+        logged_in: true,
+        profile,
+        ...(user ? { user_id: user } : {}),
+        ...(tenant !== undefined ? { tenant_id: tenant } : {}),
+        scopes,
+        access_expires_at: safeExpiresAt(now, expiresIn, claims),
+        ...(browserOpened === undefined ? {} : { browser_opened: browserOpened }),
+    };
+}
+export class AuthService {
+    tokenManager;
+    client;
+    credentials;
+    profile;
+    browser;
+    onBrowserFailure;
+    wait;
+    now;
+    initialDelay;
+    maxDelay;
+    constructor(client, credentials, profile, options = {}) {
+        this.client = client;
+        this.credentials = credentials;
+        this.profile = profile;
+        this.browser = options.browser ?? openSystemBrowser;
+        this.onBrowserFailure = options.onBrowserFailure;
+        this.wait = options.sleep ?? sleep;
+        this.now = options.now ?? Date.now;
+        this.initialDelay = options.pollInitialDelayMs ?? 250;
+        this.maxDelay = options.pollMaxDelayMs ?? 2000;
+        this.tokenManager = new TokenManager(client, credentials, profile);
+    }
+    async login() {
+        try {
+            return await withProfileLock(this.profile, async () => {
+                let existing;
+                try {
+                    existing = await this.credentials.get();
+                }
+                catch (error) {
+                    throw mapFailure(error);
+                }
+                if (existing) {
+                    throw new CliAuthError("AUTH_ALREADY_LOGGED_IN", "This profile is already logged in; run zhihu auth logout first.", { exitCode: 3 });
+                }
+                const pkce = createPkcePair();
+                let started;
+                try {
+                    started = await this.client.start(pkce.challenge);
+                }
+                catch (error) {
+                    throw mapFailure(error);
+                }
+                if (!validAuthorizationUrl(started.authorization_url)) {
+                    throw new CliAuthError("PROTOCOL_ERROR", "The server returned an unsafe authorization URL", { exitCode: 8 });
+                }
+                const browserOpened = await this.browser(started.authorization_url);
+                if (!browserOpened)
+                    this.onBrowserFailure?.(started.authorization_url);
+                let delay = this.initialDelay;
+                const deadline = this.now() + started.expires_in * 1000;
+                while (this.now() < deadline) {
+                    let outcome;
+                    try {
+                        outcome = await this.client.poll(started.transaction_id, started.polling_secret, pkce.verifier);
+                    }
+                    catch (error) {
+                        if (error instanceof HttpError && error.retryable && this.now() < deadline) {
+                            await this.wait(Math.min(delay, Math.max(1, deadline - this.now())));
+                            delay = Math.min(this.maxDelay, Math.ceil(delay * 1.7));
+                            continue;
+                        }
+                        throw mapFailure(error);
+                    }
+                    if (outcome.status === "pending" || outcome.status === "callback_processing") {
+                        await this.wait(Math.min(delay, Math.max(1, deadline - this.now())));
+                        delay = Math.min(this.maxDelay, Math.ceil(delay * 1.7));
+                        continue;
+                    }
+                    if (outcome.status === "failed") {
+                        throw new CliAuthError(outcome.error_code || "AUTH_RELOGIN_REQUIRED", "Browser authorization was not completed; run zhihu auth login again.", { exitCode: 3 });
+                    }
+                    if (outcome.status !== "completed") {
+                        throw new CliAuthError("PROTOCOL_ERROR", "The server returned an invalid login response", { exitCode: 8 });
+                    }
+                    const accessToken = outcome.access_token;
+                    const refreshCredential = outcome.refresh_credential;
+                    if (typeof accessToken !== "string" || accessToken.length === 0
+                        || typeof refreshCredential !== "string" || refreshCredential.length === 0) {
+                        await this.compensateCompletedLogin(refreshCredential);
+                        throw new CliAuthError("PROTOCOL_ERROR", "The server returned an invalid login response", { exitCode: 8 });
+                    }
+                    try {
+                        await this.credentials.set(refreshCredential);
+                    }
+                    catch {
+                        await this.compensateCompletedLogin(refreshCredential);
+                        throw new CliAuthError("AUTH_RELOGIN_REQUIRED", "Credential storage failed; run zhihu auth login again.", { exitCode: 3 });
+                    }
+                    try {
+                        return displayFromToken(this.profile, accessToken, outcome.expires_in ?? DEFAULT_EXPIRES_IN_SECONDS, this.now(), browserOpened);
+                    }
+                    catch (error) {
+                        await this.compensateCompletedLogin(refreshCredential);
+                        if (error instanceof CliAuthError)
+                            throw error;
+                        // Presentation errors are a server/protocol problem, never a
+                        // transport failure.  Do not expose arbitrary error text because it
+                        // could contain a token supplied by an embedding caller.
+                        throw new CliAuthError("PROTOCOL_ERROR", "The server returned an invalid login token", { exitCode: 8 });
+                    }
+                }
+                throw new CliAuthError("AUTH_LOGIN_TIMEOUT", "Login timed out; run zhihu auth login again.", { retryable: true, exitCode: 3 });
+            });
+        }
+        catch (error) {
+            throw mapFailure(error);
+        }
+    }
+    async status() {
+        const token = await this.tokenManager.refreshNow();
+        const info = this.tokenManager.accessInfo;
+        return displayFromToken(this.profile, token, info ? Math.max(1, Math.round((info.expiresAt - this.now()) / 1000)) : 900, this.now());
+    }
+    async logout() {
+        const state = await this.tokenManager.logout();
+        return { logged_out: true, profile: this.profile, state };
+    }
+    async compensateCompletedLogin(refreshCredential) {
+        if (typeof refreshCredential === "string" && refreshCredential.length > 0) {
+            try {
+                await this.client.logout(refreshCredential);
+            }
+            catch {
+                // Best effort only.  The primary stable auth/protocol error is safer
+                // than exposing a provider or credential-store diagnostic.
+            }
+        }
+        try {
+            await this.credentials.delete();
+        }
+        catch {
+            // Keep the primary error stable even when local cleanup is unavailable.
+        }
+    }
+}

package/dist/browser.js

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+export function validAuthorizationUrl(value) {
+    try {
+        const parsed = new URL(value);
+        const loopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]" || parsed.hostname === "::1";
+        return /^https?:$/.test(parsed.protocol)
+            && (parsed.protocol === "https:" || loopback)
+            && !parsed.username
+            && !parsed.password
+            && !/[\u0000-\u001f\u007f]/.test(value);
+    }
+    catch {
+        return false;
+    }
+}
+/** Launch a browser without a shell; the URL is never logged by this helper. */
+export const openSystemBrowser = (authorizationUrl) => new Promise((resolve) => {
+    if (!validAuthorizationUrl(authorizationUrl)) {
+        resolve(false);
+        return;
+    }
+    const command = process.platform === "darwin" ? "/usr/bin/open" : process.platform === "linux" ? "/usr/bin/xdg-open" : undefined;
+    if (!command) {
+        resolve(false);
+        return;
+    }
+    let child;
+    try {
+        child = spawn(command, [authorizationUrl], { shell: false, stdio: ["ignore", "ignore", "ignore"] });
+    }
+    catch {
+        resolve(false);
+        return;
+    }
+    let settled = false;
+    const timer = setTimeout(() => {
+        child.kill();
+        finish(false);
+    }, 5000);
+    const finish = (ok) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(ok);
+    };
+    child.once("error", () => finish(false));
+    child.once("close", (code) => finish(code === 0));
+});