{"_id":"@ath-protocol/athx","name":"@ath-protocol/athx","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ath-protocol/athx","version":"0.1.0","description":"Headless CLI client for the ATH (Agent Trust Handshake) protocol — gateway and native mode","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"athx":"dist/cli/main.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"commander":"^14.0.0","jose":"^6.0.0","@ath-protocol/client":"0.1.0","@ath-protocol/types":"0.1.0"},"devDependencies":{"@hono/node-server":"^1.19.14","@types/node":"^22.0.0","hono":"^4.7.0","typescript":"^5.7.0","vitest":"^3.0.0","tsx":"^4.19.0","@ath-protocol/server":"0.1.0"},"engines":{"node":">=18"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/A7um/ATH.git","directory":"athx"},"homepage":"https://github.com/A7um/ATH/tree/main/athx","keywords":["ath","agent-trust-handshake","ai","cli","oauth","agent"],"scripts":{"build":"tsc","test":"vitest run","dev":"tsx src/cli/main.ts"},"_id":"@ath-protocol/athx@0.1.0","bugs":{"url":"https://github.com/A7um/ATH/issues"},"_integrity":"sha512-T528QK9qTbHpR3qDPRh3irHEgQgr8VjKUKvZiMomZv8OJ3lKv0B4ltBYUy5nyXClRVhwnelAkETbWCglKtd8Rg==","_resolved":"/tmp/cfe6611e4d17c4fc84da63fb23f17548/ath-protocol-athx-0.1.0.tgz","_from":"file:ath-protocol-athx-0.1.0.tgz","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-T528QK9qTbHpR3qDPRh3irHEgQgr8VjKUKvZiMomZv8OJ3lKv0B4ltBYUy5nyXClRVhwnelAkETbWCglKtd8Rg==","shasum":"a42a0596ac46a161979c74ff615ff7b81970dc2f","tarball":"https://registry.npmjs.org/@ath-protocol/athx/-/athx-0.1.0.tgz","fileCount":4,"unpackedSize":17750,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFUlna7NxeZeZkwI2r4B75B4+RFFLyZgjDRh3ndukndPAiB+4PrHHBQnK+W6mbEuuDfmLV/TQ4AQXx8F4agot4lz5w=="}]},"_npmUser":{"name":"atumli","email":"lgcpku@gmail.com"},"directories":{},"maintainers":[{"name":"atumli","email":"lgcpku@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/athx_0.1.0_1778313220691_0.41785529405125543"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-09T07:53:40.562Z","0.1.0":"2026-05-09T07:53:40.834Z","modified":"2026-05-09T07:53:41.109Z"},"maintainers":[{"name":"atumli","email":"lgcpku@gmail.com"}],"description":"Headless CLI client for the ATH (Agent Trust Handshake) protocol — gateway and native mode","homepage":"https://github.com/A7um/ATH/tree/main/athx","keywords":["ath","agent-trust-handshake","ai","cli","oauth","agent"],"repository":{"type":"git","url":"git+https://github.com/A7um/ATH.git","directory":"athx"},"bugs":{"url":"https://github.com/A7um/ATH/issues"},"license":"MIT","readme":"# ATHX — ATH协议无头CLI客户端\n\n[English](./README.en.md)\n\n> ⚡ ATH可信生态系统的命令行客户端，用于代理注册、授权、令牌交换和API代理访问\n\n## 🎯 项目简介\n\nATHX是[ATH可信代理握手协议](https://github.com/ath-protocol/agent-trust-handshake-protocol) v0.1的TypeScript CLI客户端实现，支持网关模式和原生模式。它包含完整的ATH协议SDK（`@ath-protocol/types`、`@ath-protocol/client`、`@ath-protocol/server`），以及[zero-review](https://github.com/A7um/zero-review)自动化开发技能插件。\n\nATHX负责处理完整的可信握手流程：代理身份认证（ES256 JWT证明）、两阶段授权（应用侧注册 + 用户侧OAuth/PKCE）、令牌交换（含三方权限范围交集计算）和受保护API访问。\n\n## ✨ 核心能力\n\n### 🔐 代理身份认证\n- ES256 JWT代理证明的签发与验证\n- 代理身份文档的自动获取与公钥提取\n- JTI重放保护，防止证明重用\n- `iat`时间窗口校验（5分钟内）\n\n### 🤝 两阶段可信握手\n- **阶段A（应用侧授权）**：代理注册、权限范围审批、客户端凭证颁发\n- **阶段B（用户侧授权）**：OAuth授权、PKCE S256强制启用、用户同意流程\n- 会话管理（单次使用，10分钟超时）\n- 重定向URI精确匹配验证\n\n### 🎫 令牌管理\n- ATH访问令牌的生成、验证、吊销\n- 令牌绑定：`(agent_id, user_id, provider_id, scopes)`\n- 权限范围交集计算：`有效范围 = 代理已批准 ∩ 用户已同意 ∩ 请求的范围`\n- 空交集时拒绝签发令牌（403）\n\n### 🚦 网关代理\n- `ANY /ath/proxy/{provider_id}/{path}` — 令牌验证与上游转发\n- `X-ATH-Agent-ID` 头校验（必须与令牌绑定的agent_id匹配）\n- 上游服务商OAuth令牌绝不暴露给代理\n- 逐跳头和ATH特有头在转发前被剥离\n\n### 📝 服务发现\n- 网关模式：`GET /.well-known/ath.json` — 列出可用服务商和权限范围\n- 原生模式：`GET /.well-known/ath-app.json` — 服务端点和OAuth配置\n\n## 📦 安装方式\n\n### npm安装\n```bash\nnpm install -g athx\n```\n\n### 源码安装\n```bash\ngit clone https://github.com/ath-protocol/athx.git\ncd athx\npnpm install\npnpm run build\n```\n\n## 🚀 快速开始\n\n### 第一步：发现可用服务商\n```bash\n# 网关模式\nathx discover --gateway https://gateway.example.com --agent-id https://my-agent.example.com/.well-known/agent.json\n\n# 原生模式\nathx discover --mode native --service https://api.example.com --agent-id https://my-agent.example.com/.well-known/agent.json\n```\n\n### 第二步：注册代理（阶段A）\n```bash\nathx register --gateway https://gateway.example.com --agent-id https://my-agent.example.com/.well-known/agent.json \\\n  --provider github --scopes repo,read:user --purpose \"代码审查助手\"\n```\n\n### 第三步：授权用户（阶段B）\n```bash\nathx authorize --gateway https://gateway.example.com --agent-id https://my-agent.example.com/.well-known/agent.json \\\n  --provider github --scopes repo,read:user\n# 输出包含授权URL，在浏览器中打开完成OAuth同意\n```\n\n### 第四步：令牌交换\n```bash\nathx token --gateway https://gateway.example.com --agent-id https://my-agent.example.com/.well-known/agent.json \\\n  --code <授权码> --session <会话ID>\n```\n\n### 第五步：访问API\n```bash\nathx proxy --gateway https://gateway.example.com --agent-id https://my-agent.example.com/.well-known/agent.json \\\n  github GET /user/repos\n```\n\n### 第六步：吊销令牌\n```bash\nathx revoke --gateway https://gateway.example.com --agent-id https://my-agent.example.com/.well-known/agent.json \\\n  --provider github\n```\n\n## 🏗️ 项目架构\n```\n┌─────────────────┐\n│   athx CLI      │  命令行客户端（discover, register, authorize, token, proxy, revoke, status, config）\n├─────────────────┤\n│ ATHXGatewayClient │  网关模式 — 通过ATH网关代理请求\n│ ATHXNativeClient  │  原生模式 — 直接连接ATH原生服务\n├─────────────────┤\n│ @ath-protocol/  │\n│   client        │  ATH客户端SDK（证明签发、注册、授权、令牌交换、代理）\n│   server        │  ATH服务端SDK（处理器、代理、令牌验证、权限范围交集）\n│   types         │  ATH协议类型定义（从JSON Schema自动生成）\n├─────────────────┤\n│ zero-review/    │  自动化开发技能插件（auto-dev, auto-test, auto-req, auto-triage）\n└─────────────────┘\n```\n\n### ATH协议端点\n\n| 端点 | 方法 | 路径 |\n|------|------|------|\n| 网关发现 | GET | `/.well-known/ath.json` |\n| 服务发现 | GET | `/.well-known/ath-app.json` |\n| 代理注册 | POST | `/ath/agents/register` |\n| 发起授权 | POST | `/ath/authorize` |\n| OAuth回调 | GET | `/ath/callback` |\n| 令牌交换 | POST | `/ath/token` |\n| API代理 | ANY | `/ath/proxy/{provider_id}/{path}` |\n| 令牌吊销 | POST | `/ath/revoke` |\n\n## 🎯 适用人群\n- 🤖 AI代理开发者\n- 🔐 安全工程师\n- 🏗️ 系统架构师\n- 👷‍♂️ 平台运维工程师\n\n## 📖 文档资源\n- [ATH协议规范 v0.1](https://github.com/ath-protocol/agent-trust-handshake-protocol/tree/main/specification/0.1)\n- [TypeScript SDK文档](https://github.com/ath-protocol/typescript-sdk)\n- [ATH协议官网](https://athprotocol.dev)\n- [zero-review技能插件](https://github.com/A7um/zero-review)\n\n## 🧪 测试\n\n```bash\npnpm install\npnpm run build\npnpm run test    # 62项测试（36项单元测试 + 26项E2E测试）\n```\n\nE2E测试遵循auto-test `ath-protocol`测试角色，仅模拟外部OAuth服务商。所有ATH协议逻辑均通过真实HTTP请求进行测试：网关处理器、代理验证、令牌绑定、PKCE、权限范围交集和会话管理。\n\n## 📄 开源协议\n本项目采用 **MIT License** 开源协议，具体条款请查看LICENSE文件。\n","readmeFilename":"README.md","_rev":"1-7fff77fa95790b16dff017746fb4b4d1"}