openleash/openleash

## 什么是 OpenLeash？ 这是一个开源授权层：所有者设定策略，智能体在行动前先询问，交易对手可以验证智能体是否已获授权。 OpenLeash 在本地运行于您的 AI 智能体运行时（runtime）旁边。当智能体要执行有副作用（side-effectful）的操作（如购买、预订、发送消息、向政府提交）之前，它会询问 OpenLeash。服务器根据 YAML 策略评估请求并返回决策（`ALLOW`、`DENY`、`REQUIRE_APPROVAL`、`REQUIRE_STEP_UP`、`REQUIRE_DEPOSIT`）、义务列表，以及可选的短期证明令牌（PASETO v4.public），供交易对手验证。 ## ⚡ 快速开始 ``` # 克隆并构建 git clone https://github.com/openleash/openleash.git && cd openleash npm install && npm run build # 启动服务器（bootstrap ./data 和 config.yaml） npx openleash start # 运行交互式设置向导 npx openleash wizard ``` ## 🔧 SDK 用法 ``` import { authorize } from '@openleash/sdk-ts'; const result = await authorize({ openleashUrl: 'http://127.0.0.1:8787', agentId: 'my-agent', privateKeyB64: process.env.OPENLEASH_AGENT_PRIVATE_KEY_B64!, action: { action_id: crypto.randomUUID(), action_type: 'purchase', requested_at: new Date().toISOString(), principal: { agent_id: 'my-agent' }, subject: { principal_id: '' }, relying_party: { domain: 'example.com', trust_profile: 'LOW' }, payload: { amount_minor: 5000, currency: 'USD', merchant_domain: 'example.com' }, }, }); console.log(result); ``` 离线验证证明： ``` import { verifyProofOffline } from '@openleash/sdk-ts'; const result = await verifyProofOffline({ token: proofToken, publicKeys: [{ kid: 'key-id', public_key_b64: 'base64...' }], }); console.log(result.valid, result.claims); ``` ## 🧪 测试场（Playground） 运行预定义场景以测试策略行为： ``` npx openleash playground list npx openleash playground run small_purchase_allowed npx openleash playground run large_purchase_requires_approval ``` ## 📋 CLI 命令 | 命令 | 描述 | |---|---| | `openleash start` | 启动服务器 | | `openleash wizard` | 交互式设置向导 | | `openleash policy list` | 列出策略 | | `openleash policy show ` | 显示策略 YAML | | `openleash policy upsert --owner --file ` | 创建/更新策略 | | `openleash policy validate --file ` | 验证策略 YAML | | `openleash playground list` | 列出场景 | | `openleash playground run ` | 运行场景 | | `openleash keys list` | 列出签名密钥 | | `openleash keys rotate` | 轮换签名密钥 | | `openleash testvectors` | 生成测试向量 | ## 📖 API 参考 服务器运行后，可访问交互式 API 参考和机器可读的 OpenAPI 规范： - **交互式参考：** `http://localhost:8787/reference` - **OpenAPI 规范 (JSON)：** `http://localhost:8787/reference/openapi.json` `/v1/health` 端点的响应中也会包含这些 URL。 ## 🏗️ 架构 ``` packages/ core/ # Authorization engine, types, crypto, state management server/ # Fastify HTTP server, routes, middleware gui/ # Server-rendered HTML GUI (admin + owner portal) sdk-ts/ # TypeScript SDK for agents and counterparties cli/ # CLI commands (start, wizard, policy, playground, keys) ``` 四种参与者（actor）类型与 API 交互： | 参与者 | 认证方式 | 端点 | |---|---|---| | **Public** | 无 | `/v1/health`, `/v1/public-keys`, `/v1/verify-proof` | | **Agent** | Ed25519 请求签名 | `/v1/authorize`, `/v1/agent/*` | | **Owner** | PASETO 会话令牌（session token） | `/v1/owner/*` | | **Admin** | Bearer 令牌 / localhost | `/v1/admin/*` | 所有状态均以人类可读的文件存储： - `./data/state.md` — 权威索引（包含 YAML 的 markdown） - `./data/owners/` — 所有者档案（带 YAML frontmatter 的 markdown） - `./data/agents/` — 智能体记录（带 YAML frontmatter 的 markdown） - `./data/policies/` — 策略 YAML 文件 - `./data/keys/` — 签名密钥 JSON 文件 - `./data/approval-requests/` — 审批请求记录 - `./data/policy-drafts/` — 智能体提议的策略草稿 - `./data/invites/` — 所有者设置邀请 - `./data/agent-invites/` — 智能体注册邀请 - `./data/audit.log.jsonl` — 仅追加的审计日志 ## 🔑 审批工作流 当策略包含 `HUMAN_APPROVAL` 义务时，智能体必须获得所有者的明确批准： ``` Agent → POST /v1/authorize → REQUIRE_APPROVAL Agent → POST /v1/agent/approval-requests → Creates pending request Owner → POST /v1/owner/.../approve → Issues approval token Agent → POST /v1/authorize (+ token) → ALLOW + proof token ``` 批准令牌为一次性、针对特定操作且有时效限制。详情请参见 [docs/protocol.md](docs/protocol.md)。 ## 📝 策略草稿 当智能体需要访问现有规则未涵盖的操作类型时，可以向其所有者提议新策略： ``` Agent → POST /v1/agent/policy-drafts → Submits draft YAML + justification Owner → GET /v1/owner/policy-drafts → Reviews pending drafts Owner → POST /v1/owner/.../approve → Creates real policy + binding Agent → GET /v1/agent/policy-drafts/:id → Sees APPROVED + resulting_policy_id ``` 这让智能体可以在所有者的控制下自助服务——最终决定权始终在所有者手中。完整规范请参见 [docs/protocol.md](docs/protocol.md#policy-drafts)。 ## 👤 所有者门户（Owner Portal） 所有者门户是一个自助式 Web 界面，所有者可以在其中管理策略、审查待处理的审批请求以及查看已注册的智能体。访问地址为 `/gui/owner/login`。 **设置流程：** 1. 管理员通过 Admin Dashboard (`/gui/dashboard`) 或 `npx openleash wizard` 创建所有者 2. 管理员生成设置邀请 — GUI 会生成一个可复制的设置链接 3. 所有者打开链接 (`/gui/owner/setup?invite_id=...&invite_token=...`) 并设置密码 4. 设置完成后，系统会提示所有者创建一个 **智能体邀请** — 一个供智能体自行注册的单一 URL 5. 所有者使用其所有者主体 ID（Owner Principal ID）和密码在 `/gui/owner/login` 登录 ## 🤖 智能体注册 智能体通过所有者（或管理员）创建的 **邀请 URL** 进行注册。该邀请 URL 是自包含的 —— 智能体向其 POST 自己的公钥和智能体 ID，即可获得身份、签名协议、所有可用端点以及 SDK 安装说明。 **使用 TypeScript SDK：** ``` import { redeemAgentInvite } from '@openleash/sdk-ts'; const agent = await redeemAgentInvite({ inviteUrl: process.env.OPENLEASH_AGENT_INVITE_URL!, agentId: 'my-agent', }); // agent.openleash_url, agent.private_key_b64, agent.agent_principal_id, ... ``` 所有者可以从以下位置创建智能体邀请： - 所有者设置页面（设置密码后立即提供） - 所有者智能体页面 (`/gui/owner/agents`) - 管理员智能体页面 (`/gui/agents`) 完整的智能体集成指南请参见 [AGENTS.md](AGENTS.md)。 ## 🔍 故障排除 ### NO_POLICY 错误 如果智能体收到带有 `NO_POLICY` 的 `403` 错误，说明没有策略绑定到该智能体或其所有者。请通过所有者门户或 `npx openleash policy upsert` 创建并绑定策略。 ### 时钟偏差（Clock skew）错误 如果出现 `TIMESTAMP_SKEW` 错误，请确保请求系统的时钟已同步。默认允许的偏差为 ±120 秒。在 `config.yaml` 中调整： ``` security: clock_skew_seconds: 300 ``` ### Nonce 重放错误 每个 nonce 在 TTL 窗口（默认 600 秒）内每个智能体只能使用一次。请为每个请求生成唯一的 nonce（UUID）。 ### 无效签名错误 - 确保您使用的是正确的私钥（PKCS8 DER base64 格式） - 签名输入必须严格为：`METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY_SHA256` - Body SHA256 必须与原始请求体字节匹配 ### Admin token 混淆 - 默认管理员模式为 `localhost_or_token`：localhost 请求绕过令牌检查 - 如果远程访问，需要设置 `admin.allow_remote_admin: true` 并提供有效的 bearer token - Token 存储在 `config.yaml` 的 `admin.token` 中 ### 数据文件夹位置 OpenLeash 将所有状态存储在您运行命令位置相对的 `./data/` 中。请确保所有命令都在同一目录下运行。 ## 🤝 贡献 欢迎贡献代码！提交 Pull Request 前请阅读 [贡献指南](CONTRIBUTING.md)。 ## 📄 许可证 [Apache-2.0](LICENSE)

标签：AI 智能体, AI 治理, PASETO, Streamlit, TypeScript, YAML 配置, 人工智能安全, 人工智能安全, 决策系统, 可验证凭证, 合规性, 合规性, 大模型安全, 安全插件, 开源, 护栏机制, 授权管理, 暗色界面, 本地部署, 权限验证, 策略引擎, 网络安全挑战, 自动化攻击, 访问控制, 风险控制