内容
# x424
> 人类依赖协议 · 公共预发布 · 未经审计
[x424.org](https://x424.org) · [协议规范](docs/PROTOCOL.md) ·
[OpenAPI](openapi/x424.openapi.json)
**x424 让 HTTP 操作依赖于唯一验证的人类。**
x402 让操作依赖于支付。x424 让操作依赖于唯一的人类——无论调用者是浏览器、钱包、后端还是自主代理。
服务器返回 `424 Failed Dependency` 以及 `HUMAN-REQUIRED` 头部。人类完成明确接受的提供者方法，验证器颁发与确切请求和调用者绑定的短时结果，客户端使用 `HUMAN-PROOF` 中的令牌重试。
World ID 4.0 Orb 是第一个提供者适配器。核心是提供者中立的，但提供者永远不会被假定为等价的：依赖方必须命名每个接受的提供者、方法、描述符版本、唯一性范围、保证标签、验证模式和新鲜度规则。
## 线上流程
```text
代理或应用 资源服务器 x424 验证器
| POST /action | |
|---------------------------------->| |
| 424 + HUMAN-REQUIRED | |
|<----------------------------------| |
| 人类完成接受的提供者仪式 |
| POST 提供者原生证明 ----------------------------------->|
|<--------------------------- HUMAN-RESULT (签名，短时) |
| POST /action + HUMAN-PROOF | |
|---------------------------------->| 验证签名，请求， |
| | 受众，绑定，重复播放 |
| 2xx，或下一个依赖（例如 x402） |
|<----------------------------------| |
```
```http
HTTP/1.1 424 Failed Dependency
HUMAN-REQUIRED: <base64url-canonical-json>
Cache-Control: no-store, private
Content-Type: application/problem+json
```
验证后：
```http
POST /action HTTP/1.1
HUMAN-PROOF: <x424-result+jws>
Idempotency-Key: <application-key-for-mutations>
```
`HUMAN-RESULT` 是验证器到客户端的相同签名结果令牌的副本。提供者原生证明不属于头部或资源服务器。
## 已实现的功能
- 规范的、base64url 的 HTTP 需求/结果编码。
- 确切的请求摘要、受众、目的、nonce 和钱包/代理/会话绑定。
- 明确的提供者替代方案，无跨提供者等价性。
- 提供者本地的唯一性范围：全局、依赖方、操作或会话。
- 原子挑战消耗和可选的结果令牌重复播放消耗。
- 受众成对人类标识符，使用依赖方 HMAC 密钥派生。
- Ed25519 `x424-result+jws` 签名和验证。
- 确定性失败关闭结果评估。
- 使用当前 `/api/v4/verify/{rp_id}` 后端边界和应用程序提供的绑定验证器的 World ID 4.0 Orb 参考适配器。
- 参考 Express 路由器和 OpenAPI 3.1 合同。
- 通过 stdio 或本地无状态 Streamable HTTP 的 MCP 服务器。
- 无构建依赖控制台 UI。
- 固定的 conformance 固定装置、MCP 评估和负测试。
- Problee 先发政策和迁移设计。
此存储库不包含托管验证器、生产数据库、生产 RP 密钥、World 证明固定装置、链上注册表、身份钱包、通用凭证协议或授权引擎。
## 快速开始
需求：Node.js 22+ 和 pnpm 9+。
```bash
pnpm install
pnpm check
pnpm example
```
在本地运行 MCP 服务器：
```bash
pnpm mcp
```
或将无状态 MCP 端点绑定到 localhost：
```bash
pnpm mcp:http
# http://127.0.0.1:4240/mcp
```
浏览器控制台位于 [`demo/`](demo/)。从与配置的参考 API 相同的受信任来源提供该目录；它故意不包含提供者或 RP 机密。
## 最小资源服务器挑战
```ts
import { createHumanRequirement, humanRequiredResponse } from "x424";
const requirement = createHumanRequirement({
purpose: "publish-market",
method: "POST",
uri: "https://api.example.com/markets",
audience: "https://api.example.com",
body: requestBody,
binding: { kind: "agent_key", value: agentPublicKeyFingerprint },
accepts: [
{
providerId: "world",
methodId: "world-id-4-orb",
descriptorVersion: "1",
assuranceLevel: "orb",
acceptedScopeKinds: ["action"],
verificationModes: ["backend"],
maximumProofAgeSeconds: 300,
},
],
providerRequests: {
"world:world-id-4-orb": signedWorldRequestFromYourBackend,
},
});
const response = humanRequiredResponse(requirement);
// 发送 response.status、response.headers 和 response.body。
```
在返回之前，在共享的原子 nonce 存储中注册需求。`InMemoryNonceStore` 仅用于测试和本地示例。
## 接受重试请求
```ts
import {
WORLD_ID_ORB_METHOD,
defineMethodCatalog,
verifyHumanProofHeader,
} from "x424";
const result = await verifyHumanProofHeader({
humanProof: request.headers["human-proof"],
requirement,
verifier: trustedVerifierPublicKey,
catalog: defineMethodCatalog([WORLD_ID_ORB_METHOD]),
replayStore,
});
// 结果仅证明命名依赖。您的应用程序仍然授权。
```
对于更改状态的操作，原子消耗 `resultId` 并使用应用程序的正常幂等机制。x424 防止证明重用成为人类依赖重用；它不替换事务幂等。
## World ID 适配器边界
适配器需要四个依赖方决策：
1. 一个 `rp_...` ID 和不可变的动作；
2. 后端生成的签名的 World 请求材料；
3. 服务器端验证 IDKit 证明信号绑定到预期的钱包、代理密钥、请求或会话；和
4. 与 World 进行远程验证。
适配器将原生 IDKit 结果转发到 World's 验证器而不重塑它。它仅存储返回的 nullifier 以派生受众成对 ID；nullifier 从不进入 x424 结果。World ID 4.0 唯一性证明是一次性的。会话证明和 `session_id` 连续性是不同的 World 语义，不会为 Orb 方法默默替换。
## 代理和人类
x424 不将代理标记为人类。它将人类结果绑定到代理的公钥指纹，用于一个请求或狭窄的目的：
- 代理遇到 424 挑战；
- 其钱包/UI 请求人类满足接受的方法；
- 验证器为该确切请求和代理密钥颁发结果；
- 代理重试而不接收人类的提供者 nullifier；和
- 应用程序应用其自己的代理范围、支出控制和策略。
更长寿的“人类拥有此代理”关系需要一个明确的生命周期配置文件，包括同意、范围、到期时间、恢复和撤销。它不是从一个 x424 结果中推断出来的。
## x401 和 x402 组合
x424 不是 x401 或 x402 的替代品：
- x401 请求通用凭证/证明通过 HTTP 401。
- x424 请求通过 HTTP 424 的确切唯一人类依赖。
- x402 请求通过 HTTP 402 的支付。
需要人类和支付的服务将 x424 放在 x402 之前。一旦客户端呈现有效的 `HUMAN-PROOF`，同一个请求可能会收到标准的 x402 挑战。最终重试携带人类结果令牌和支付签名。两个协议都不重新解释对方。
## 存储库映射
```text
src/ 核心，World 适配器，结果令牌，API 和 MCP
openapi/ OpenAPI 3.1 参考合同
demo/ 提供者安全依赖控制台
examples/ HTTP 和 Problee 先发示例
test/ 核心，安全，MCP 和合同测试
evals/ 十个只读 MCP 评估
docs/PROTOCOL.md 规范性 x424/0.1 合同
docs/ARCHITECTURE.md 信任边界和部署形状
docs/SECURITY.md 威胁模型和生产控制
docs/COMPOSITION.md x401/x402 和链上/链下组合
docs/PROBLEE_ADOPTION.md 先发迁移
docs/LANDSCAPE_AND_PRIOR_ART.md 研究和先驱声明限制
```
## 状态和命名
`424 Failed Dependency` 起源于 WebDAV 的 RFC 2518，于 1999 年 2 月发布，目前由 RFC 4918 指定。x424 为 HTTP 扩展重用了依赖思想；它不是 IETF 标准，不得声称 WebDAV 一致性。客户端通过 `HUMAN-REQUIRED` 检测 x424，而不是仅限于原因短语。
确切的协议名称搜索在研究日期未找到活跃的 x424 身份/人类协议，但这不是商标、专利、域名或法律许可。参见研究文档以获取声明限制。
## 安全
预发布且未经审计。不要使用此版本授权生产价值。请阅读 [`docs/SECURITY.md`](docs/SECURITY.md) 并私下报告漏洞，如 [`SECURITY.md`](SECURITY.md) 中所述。
## 许可证
Apache License 2.0。请参见 [`LICENSE`](LICENSE)。
