AI Audit Event Mcp

@kajaril/audit-event-mcp

Agent 管理基础设施——采用哈希链的审计日志，配备 Merkle 公证功能和 GDPR/AI Act 合规技能。

---

功能

• 将 Agent 事件（工具调用、决策、人类回合）记录到每个客户端专属的 SQLite 日志中，并使用 SHA-256 哈希链——每条记录都通过加密方式与前一条记录关联
• 可选择使用 Merkle 根和 Ed25519 签名对批次进行公证（付费层级）——外部审计员无需联系 kajaril 即可验证
• 按需将数据主体的所有事件导出为 NDJSON（GDPR 第 20 条数据可携权）
• 附带一个 Claude Code 技能，可针对任何事件存储运行 8 个 GDPR/AI Act 评估维度

MCP 端点

https://audit-event.kajaril.com/mcp

通过 HTTPS 传输的 JSON-RPC 2.0，使用 Cloudflare Access（服务令牌）或 OAuth 客户端凭证访问令牌进行身份验证——请参阅身份验证。如需开始接入，请联系 [email protected]。

工具

工具	描述
record_event	写入一条审计事件。返回 { id, chain_hash }。
verify_chain	重新计算一系列事件的 chain_hash。返回已验证数量和损坏的条目。
query_events	按会话、Agent、事件类型或日期范围筛选。绝不返回 input_hash。
export_dossier	将 subjectId 的所有事件导出为 NDJSON（GDPR 第 20 条）。返回一个有效期为 1 小时的下载 URL。
request_approval	请求人工批准某项操作。返回 approvalId、用于批准的 approvalUrl 页面以及你的 webhookSecret。该请求会以 approval.requested 事件记录在哈希链中。
check_approval	轮询审批状态：pending | approved | denied | timeout；审批完成后会返回原因和响应者。

快速开始

记录一条事件：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "record_event",
    "arguments": {
      "agentId": "travel-assistant",
      "eventType": "tool.call",
      "purpose": "User requested flight search via travel assistant",
      "sessionId": "550e8400-e29b-41d4-a716-446655440000",
      "input": { "tool": "search_flights", "origin": "LHR", "dest": "JFK" },
      "lawfulBasis": "contract",
      "subjectId": "user-8821"
    }
  }
}

验证哈希链：

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "verify_chain", "arguments": { "limit": 100 } } }

导出数据主体的记录：

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "export_dossier", "arguments": { "subjectId": "user-8821" } } }

身份验证

有三种接入方式；最终都会得到经过签名验证的 client_id，用于选择你的租户—— 绝不会使用用户提供的信息来选择租户。

Cloudflare Access 服务令牌（手动接入）：发送令牌标头，Cloudflare Access 会注入经过验证的 JWT。可使用全部功能。

OAuth 浏览器流程（MCP 客户端，无需复制粘贴）：将客户端指向该服务，让它 自动发现其余信息——

claude mcp add --transport http audit-event https://audit-event.kajaril.com/mcp

RFC 8414 元数据会公布动态客户端注册（/oauth/register）、 使用 PKCE S256 的授权（/oauth/authorize）以及共享的令牌端点。已登录的租户操作员会在浏览器中批准授权；授予的范围（agent 或 admin）会绑定到签发的令牌中。

OAuth 客户端凭证（M2M）：在 POST /oauth/token 处将客户端密钥换取有效期为 1 小时的 Bearer 令牌 （application/x-www-form-urlencoded，使用 HTTP Basic 或在请求体中传递 client_id / client_secret 参数）：

curl -s https://audit-event.kajaril.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d scope=agent

有两个范围，分别签发和轮换：

范围	可调用
agent	record_event、request_approval、check_approval
admin	所有工具，另加 POST /credentials/rotate

密钥在签发或轮换时仅显示一次（POST /credentials/rotate，请求体为 {"scope":"agent"}），并且仅以哈希形式存储在你租户的 Durable Object 中。轮换某个范围会立即使其旧密钥失效；尚未过期的访问令牌会在 1 小时内过期。

审批工具也提供纯 REST 接口，供生产后端使用：POST /approvals（请求体与 request_approval 相同）和 GET /approvals/:id，并使用 Authorization: Bearer <access token>。

工作原理

哈希链

每个事件都会对其之前的所有事件进行承诺。该链可从基本原理重新计算：

input_hash_slot = input_hash ?? input_hash_omitted_reason
chain_hash      = SHA-256(id + "|" + event_type + "|" + input_hash_slot + "|" + prev_hash)

当调用方使用 inputHashOmittedReason 而非 input 时，原因字符串会进入链中——省略操作本身也可防篡改。

Merkle 公证服务（付费层级）

每 15 分钟（或待处理事件达到 1,000 条时），公证 Worker 会：

1. 从待处理记录中收集 { id, chain_hash } 对
2. 按 id 排序，并构建 SHA-256 二叉 Merkle 树
3. 使用 Ed25519 对根进行签名
4. 将 merkle_root + notary_sig 写回每条记录

公证服务的公钥发布于 /.well-known/notary-pubkey（在 go.kajaril.com 上也通过同源代理提供，供验证页面使用）。任何审计员都可以离线验证签名，无需联系 kajaril。公证服务永远不会收到 input_hash、payload_ref 或任何载荷内容。

验证档案

export_dossier 会返回一个链接，指向 go.kajaril.com 上便于阅读的档案，并附带原始 JSONL 证据文件。任何人都可以将该文件拖到 **https://go.kajaril.com/verify**——浏览器会根据导出的原像（`id | event_type | input_hash ?? omitted_reason | prev_hash`）重新计算每条记录的链指纹，并使用已发布的公钥检查每个公证 Ed25519 签名。不会上传任何内容；验证结果在客户端计算。

隐私设计

• input 在本地进行哈希；除非明确绑定了 R2 存储桶，否则不会存储原始值
• query_events 响应中不包含 input_hash；档案会将其与 prev_hash 一并导出，作为支持独立验证的链原像——它们是摘要，绝非内容
• 绝不会向调用方返回 payload_ref——每个处理程序边界都会强制执行这一点
• 空的 export_dossier 结果（eventCount: 0）是有效的 GDPR 证据，表明该主体不存在任何数据

事件类型

tool.call | tool.result | decision.made |
human.turn | memory.read | memory.write | error.raised |
approval.requested | approval.decided

approval.* 类型为保留类型：当请求并作出人工审批时，witness 会自行记录这些类型。record_event 会拒绝它们——Agent 绝不能伪造人工决策证据。（approval.deferred 和 approval.escalated 留待以后使用。）

决策 Webhook

当审批包含 callback_url 时，一旦人工作出决定，系统就会将该决定（批准/拒绝）POST 到该地址——这样中断的 Agent 就能恢复运行，而无需轮询。超时不会触发 Webhook；这类情况通过轮询处理。

每次投递都带有签名。请求正文为 JSON：

{
  "type": "approval.decided",
  "approval": { "id": "…", "status": "approved", "reason": null, "responderId": "…",
                "agentId": "…", "sessionId": "…", "actionSummary": "…",
                "actionPayloadHash": "…", "createdAt": "…", "decidedAt": "…", "expiresAt": "…" },
  "chainEvent": { "id": "…", "chainHash": "…" }
}

chainEvent 指向哈希链中的 approval.decided 条目——请将其作为证据引用。

验证签名。 每次 request_approval 响应都会通过 webhookSecret 返回你的 Webhook 密钥（whsec_…），无需使用仪表板。每次投递都包含：

X-Kajaril-Signature: t=<unix seconds>,v1=<hex>

验证步骤：

1. 从标头中读取 t 和 v1。如果 |now − t| 超过 300 秒，则拒绝。
2. 计算 HMAC-SHA256(key = 字面密钥字符串（UTF-8，包含 whsec_ 前缀），message = "{t}." + 原始请求正文)。
3. 进行十六进制编码，并使用恒定时间比较将其与 v1 比较。

const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

参考实现是 src/lib/webhook.ts 中的 verifyWebhookSignature——我们的测试运行的也是同一代码路径。

自托管说明：Webhook 签名会从 WEBHOOK_SIGNING_SECRET Workers Secret 派生每个租户的密钥。如果未设置该密钥，则完全不会发送 Webhook（绝不会发送未签名的 Webhook），且 request_approval 会返回 webhookSecret: null；轮询仍可正常使用。

通知渠道

request_approval 接受 channels: ["telegram", "email"]，并按顺序通知审批人：先即时通知，失败时再使用电子邮件。

Telegram（即时）。 只需连接一次 — POST /channels/telegram/connect（admin scope）会返回一个一次性 t.me 深度链接（15 分钟后过期）。打开链接并点击 Start，审批卡片就会发送到该聊天中，包含内联 Approve / Deny / Deny with reason 按钮。选择拒绝并说明原因时，系统会提示填写简短回复，并将其与决定一并记录 — 相比简单的二元标记，这是更有力的第 14 条证据。再次连接会替换已绑定的聊天。

电子邮件（备用）。 只需设置一次审批人地址 — 使用 {"address": "…"} 调用 POST /channels/email（admin scope）。仅在需要时发送电子邮件：

• 如果没有即时渠道成功送达（未连接、发送失败或未请求），则立即发送；
• 如果即时审批卡片已送达，但审批仍未决定，则在 10 分钟后发送；
• 如果审批会在电子邮件发挥作用前过期，则不发送。

邮件由 [email protected] 发出，包含决定链接；回复会送达人工处理人员 [email protected]。

发送报告。 每个 request_approval 响应都会包含实际发生的情况：

"notifications": { "telegram": "sent", "email": "scheduled" }

（telegram：sent | failed | not_connected | unconfigured | not_requested；email：immediate | scheduled | expires_first | no_address | unconfigured | arm_failed | not_requested。）

TTL 默认值取决于渠道：使用即时渠道时为 30 分钟，仅使用电子邮件时为 4 小时；显式设置的 ttlSeconds 始终优先。

自托管说明：渠道为可选项。如果没有配置 TELEGRAM_BOT_TOKEN / RESEND_API_KEY / CHANNELS_KV，发送报告会显示 unconfigured，但仍可通过 approvalUrl + 轮询完成审批。绑定配置已记录在 wrangler.jsonc 和 wrangler.go.jsonc 中。

合法依据（GDPR 第 6 条）

legitimate_interest | contract | legal_obligation |
vital_interest | public_task | consent

对于任何处理个人数据的事件，请提供 lawfulBasis。对于不处理个人数据的事件，请省略此字段。

套餐

功能	免费	付费
哈希链式事件写入	是	是
verify_chain	是	是
export_dossier（GDPR 第 20 条）	是	是
R2 载荷存储	可选	可选
Merkle 根 + Ed25519 公证	—	是
compliance-audit 轴 6（公证覆盖率）	跳过	评估

compliance-audit 技能

skills/compliance-audit/SKILL.md 是一项 Claude Code 技能，可针对任意事件存储执行 8 个 GDPR/AI 法案合规轴检查。将其复制到工作区：

cp -r node_modules/@kajaril/audit-event-mcp/skills/compliance-audit .claude/skills/

各轴：

1. 存在合法依据 — GDPR 第 5–6 条
2. 目的具体明确 — GDPR 第 5(1)(b) 条
3. human.turn 事件具有关联主体
4. 保留期限有上限（≤ 730 天）
5. 链完整性 — 抽取 10% 样本重新计算
6. 公证覆盖率 ≥ 95%（仅限付费套餐）
7. 高风险事件完整性 — AI 法案第 12–13 条
8. 数据最小化信号 — payload_ref 占比

每个轴都会生成 pass | fail | warn 结果，并附带一段证据摘录。输出包括 JSON 和 Markdown 摘要块。

自托管部署

先决条件

• 已启用 Workers 和 Durable Objects 的 Cloudflare 账户
• 已完成身份验证的 wrangler CLI

步骤

# 1. Create R2 bucket
wrangler r2 bucket create audit-payloads

# 2. Set notary signing key (paid tier)
wrangler secret put NOTARY_PRIVATE_KEY --config wrangler.notary.jsonc
# Value: hex-encoded Ed25519 private key — never committed to source

# 3. Deploy Workers
wrangler deploy
wrangler deploy --config wrangler.notary.jsonc

# 4. Add audit-event.kajaril.com as a CF Access Self-hosted Application
# Issue one service token per client with custom.client_id claim

# 5. Onboard a client
npx tsx src/scripts/onboard-client.ts --client-id acme-crm --tier free --region eu

# 6. Verify
curl https://audit-event.kajaril.com/health

切勿在工作树有未提交更改时运行 wrangler deploy。部署的代码必须与 git HEAD 一致。

开发

npm install
npm test          # 81 tests (node:sqlite adapter, no cloudflare/vitest-pool-workers)
npm run typecheck
npm run lint

许可证

MIT。版权所有 © 2026 Kajaril Ltd。