ailedger-dev/ailedger
GitHub: ailedger-dev/ailedger
AILedger 是一个审计级基础设施，为受AI影响的决策提供不可篡改的记录和合规检测，专为《联邦证据规则707》和《欧盟AI法案》等监管环境准备。
Stars: 0 | Forks: 0
# '代理'? But instruction says keep. I'll keep as 'Proxy' because it's a professional term.
**适用于受AI影响的决策的审计级证据，已为《联邦证据规则707》和《欧盟AI法案》做好准备。**
AILedger 是在监管和对抗性场景下，针对受AI影响决策的审计基础设施。其三层结构（完整性链、决策事件、检测）已为美国《联邦证据规则707》的可采性要求以及欧盟《AI法案》第12、19、26条做好准备。标准依据：ISO/IEC 42001 和 NIST AI RMF 1.0。章程 v1.2 已发布，包含拒绝客户和拒绝功能的承诺。开源检测层位于 [github.com/ailedger-dev/ailedger-detection](https://github.com/ailedger-dev/ailedger-detection)。
**许可证：** AGPLv3（本仓库），同时提供商业许可证（联系 ops@jvholdings.co）· **检测层：** Apache 2.0，位于 [github.com/ailedger-dev/ailedger-detection](https://github.com/ailedger-dev/ailedger-detection)
**线上访问：** [ailedger.dev](https://ailedger.dev) · **章程：** [ailedger.dev/charter](https://ailedger.dev/charter) · **仪表板：** [dash.ailedger.dev](https://dash.ailedger.dev) · **代理：** [proxy.ailedger.dev](https://proxy.ailedger.dev)
## 三层架构
AILedger 是一个基础设施，而非日志工具。分析的基本单元是**决策事件（Decision Event）**：每个影响个人的AI决策对应一条结构化记录。
**第1层：完整性链。** 位于 `proxy.ailedger.dev` 的 Cloudflare Workers 代理，以及一个基于哈希链的 Postgres 账本，用于封装决策事件记录。每条记录经过哈希处理并链接到前一条记录；即使内部管理员数据库访问也无法重写历史；不可篡改是结构性的，而非策略性的。客户可通过一次 SQL 调用验证任意记录的完整性。
**第2层：决策事件。** 位于 Supabase EU 区域的 Postgres 模式，每个影响个人的AI决策对应一条记录。捕获以下字段：`subject_id`（使用每租户盐值进行 HMAC 伪匿名化处理；同一个人在不同决策中产生相同的 `subject_id`，但该值无法逆向还原为 PII）、`inputs_hash`（SHA-256；原始输入永不存储）、模型版本 + 权重哈希、基于与 EU AI 法案附件 III 对齐的固定分类法的 `decision_type`、带有显式收集方法标签的 `protected_class_context`（直接/推断/盲）、置信度、`human_in_loop`、结构化的标志/必要操作/已执行操作数组。该模式使得 `required_actions` 与 `actions_taken` 之间的差异可查询；这就是未解决的合规差距。
**第3层：检测。** 采用 Apache 2.0 许可证开源，位于 [github.com/ailedger-dev/ailedger-detection](https://github.com/ailedger-dev/ailedger-detection)。这是一个独立库，用于查询决策事件层。初始原语：差异性影响比率（基于 EEOC 29 CFR 1607 的五分之四规则基线）、统计均等差异、跨版本转换的模型漂移（基于美联储 SR 11-7 和 OCC 2011-12 的 PSI）。检测阈值由标准设定；客户可收紧，但不可放宽。
## 监管锚点
| 监管制度 | 条款/标准 | 状态 |
|---|---|---|
| 美国《联邦证据规则707》 | AI 生成证据达到规则702可采性标准 | 2025年经司法会议批准；即将生效 |
| 欧盟《AI法案》 | 第12条（日志记录）、第19条（部署者义务）、第26条（高风险运营者职责）、第27条（FRIA）、第50条（透明度）、附件III（高风险类别） | 根据2026年5月数字综合法案，分阶段实施：2026年8月2日（第50条透明度、GPAI提供者义务、金融行业高风险）至2027年12月2日（附件III独立高风险）及2028年8月2日（附件I产品嵌入式） |
| ISO/IEC 42001 | AI 管理体系 | 标准锚定 |
| NIST AI RMF 1.0 | AI 风险管理框架 | 标准锚定 |
| GDPR 第22条 | 自动化决策的解释权 | 设计上兼容（主体伪匿名化 + 每决策审计） |
## 章程
AILedger 附带一份公开章程（v1.2），其中以书面形式明确了拒绝的客户类别和拒绝的功能类别。章程修正需董事会全体一致批准。章程发布于 [ailedger.dev/charter](https://ailedger.dev/charter)。拒绝客户和功能是产品按设计运行的结果，而非收入损失问题。
## 快速开始 — 决策事件写入（`@ailedger/sdk`）
```
import { DetectionEventClient } from '@ailedger/sdk';
const client = new DetectionEventClient({
apiKey: process.env.AILEDGER_API_KEY!,
baseUrl: 'https://proxy.ailedger.dev',
tenantId: process.env.AILEDGER_TENANT_ID!,
systemId: process.env.AILEDGER_SYSTEM_ID!,
});
const result = await client.emit({
event_id: crypto.randomUUID(),
timestamp: new Date().toISOString(),
decision_type: 'employment_screening',
model_version: 'claude-opus-4-7',
inputs_hash: await client.computeInputsHash(rawInputs),
protected_class_context: { /* per Annex III taxonomy */ },
confidence: 0.85,
human_in_loop: false,
flags: [],
required_actions: [],
actions_taken: [],
});
console.log(`Event committed at chain position: ${result.hash_chain_self}`);
```
免费层位于 [dash.ailedger.dev](https://dash.ailedger.dev)。每月免费 10,000 个决策事件；付费层提供更高容量和专属支持。有关审计时推断出的决策事件（4层级提取阶梯：解析/重构重放/扰动），请参见 `@ailedger/sdk` 中的 `extractors/` 模块。
## 快速开始 — v1 代理界面（旧版 `inference_logs`）
v1 推理日志代理界面仍对早期客户开放。新部署应针对上述 v2 `/v2/detection-events` 基础设施。
```
from openai import OpenAI
client = OpenAI(
api_key="your-openai-key",
base_url="https://proxy.ailedger.dev/proxy/openai",
default_headers={"x-ailedger-key": "your-ailedger-key"},
)
client.chat.completions.create(
model="gpt-4.1-mini",
messages=[{"role": "user", "content": "Hi"}],
)
```
v1 记录在 `ledger.inference_logs` 中存储哈希链推理记录。v2 基础设施（如上所述）是高危AI监管义务下生产部署的推荐目标。
## 架构
```
Producer (your app)
│
├──> @ailedger/sdk emit(canonical DetectionEvent)
│ │
│ └──> POST proxy.ailedger.dev/v2/detection-events
│ │
│ ├──> auth (x-ailedger-key) + tenant-binding check
│ ├──> INSERT to ledger.decision_events (Postgres / Supabase EU)
│ │ │
│ │ └──> BEFORE INSERT trigger:
│ │ - canonical_hash() computes SHA-256 of canonicalized row
│ │ - hash_chain_prev = last row's hash_chain_self
│ │ - hash_chain_self = canonical_hash || hash_chain_prev
│ │ - per-tenant advisory lock prevents race
│ │
│ └──> return populated row (event_id, hash_chain_self)
│
│
Audit-time extractor (separate process)
│
├──> read ledger.decision_events for inferred-extraction targets
├──> SDK extractors (parse / restructure / replay / perturb)
│ │
│ └──> POST /v2/detection-events with extractor_method + anchor_event_id
│ │
│ └──> INSERT inferred row (chain-extended; anchor preserved)
│
└──> Detection layer (Apache 2.0, [github.com/ailedger-dev/ailedger-detection](https://github.com/ailedger-dev/ailedger-detection))
│
└──> SELECT FROM ledger.decision_events;
apply: disparate-impact ratio / parity / drift / etc.
emit: alerts when thresholds breached
```
## 安全模型
### 哈希链篡改检测（第1层）
每条 `ledger.decision_events` 行存储 `hash_chain_prev`（前一行内容的哈希）和 `hash_chain_self`（规范化当前行加上 `hash_chain_prev` 的哈希），形成仅追加链。对历史行的任何修改都会使后续所有哈希失效。`ledger.verify_chain()` 函数遍历整条链并报告第一个断裂点。触发器使用每租户的 `pg_advisory_xact_lock`，使同一租户内的并发插入串行化；跨租户插入可并行执行。
### 不可篡改性
UPDATE 和 DELETE 触发器会对 `ledger.decision_events` 抛出异常——即使来自 `service_role`。记录在密码学和程序上均为仅追加。
### 每租户主体伪匿名化（第2层）
`subject_id` 是客户提供的主体标识符的 HMAC-SHA256，使用存储在 `ledger.tenant_salts` 中的每租户密钥加盐。同一租户内同一人在不同决策中产生相同的 `subject_id`；同一人在不同租户中产生不同的 `subject_id`。没有每租户盐值和原始标识符，无法逆向映射到原始 PII；原始 PII 永不进入 AILedger 存储。
### 模式隔离
决策事件数据位于 `ledger` 模式中，而非 `public`。强制启用 RLS：客户通过 `tenant_id` 成员关系只能看到自己的行。
### 不保留原始数据
仅存储输入的 SHA-256 哈希和结构化字段（protected_class 上下文、标志等）。哈希证明发生了特定交互，同时不保留个人数据。设计上兼容 GDPR + 第22条。
### 租户绑定的 API 密钥（v0.2.1）
API 密钥存储为 SHA-256 哈希。每个密钥绑定到特定的 `tenant_id`；通过被盗密钥跨租户写入在代理写入端点被结构性阻止。可通过仪表板即时撤销密钥。
### 机密信息
Cloudflare Worker 机密信息存储所有基础设施凭证。仓库中不包含任何硬编码密钥；`.env.local` 和 `.dev.vars` 已通过 gitignore 排除。
## 仓库布局
这是一个单体仓库（monorepo）。
| 目录 | 用途 | 技术栈 |
|---|---|---|
| `landing/` | 公开营销网站 (ailedger.dev) | Vite + React + TS, Cloudflare Pages |
| `dashboard/` | 客户仪表板 (dash.ailedger.dev) | Vite + React + TS, Supabase Auth, Cloudflare Pages |
| `proxy/` | Cloudflare Worker (proxy.ailedger.dev)：认证、v2 决策事件写入、v1 代理转发、持久缓冲区审计日志、KV 缓存 | TypeScript, Cloudflare Workers |
| `sdk/` | `@ailedger/sdk` v0.2.0 生产端 SDK：决策事件发射 + 4层级提取阶梯 + Web Crypto API 哈希 + JCS 规范化 | TypeScript, ESM, Node 20+ |
| `redirect/` | 简单重定向 Worker (dashboard.ailedger.dev → dash.ailedger.dev) | TypeScript, Cloudflare Workers |
检测层（Apache 2.0）位于独立仓库 [github.com/ailedger-dev/ailedger-detection](https://github.com/ailedger-dev/ailedger-detection)：
| 仓库 | 用途 | 技术栈 |
|---|---|---|
| [ailedger-dev/ailedger-detection](https://github.com/ailedger-dev/ailedger-detection) | 可针对决策事件账本查询的统计检测原语 | Python 3.10+, Apache 2.0 |
## 开发
前置条件：Node.js 20+, Wrangler CLI（`npm install -g wrangler`）、Cloudflare 账户（`wrangler login`）、Supabase 项目（免费层可用于开发）。
```
# - SDK (TypeScript): 'SDK' is a professional term, keep. 'TypeScript' is a language name, keep. So "SDK (TypeScript)" -> same.
cd proxy && npm install && npx wrangler dev
# - Dashboard (Vite + React): 'Dashboard' could be translated? I think it's a common UI term often kept as 'Dashboard' in Chinese. 'Vite' and 'React' are framework names, keep. So "Dashboard (Vite + React)" -> same.
cd sdk && npm install && npm test
# - Landing (Vite + React): 'Landing' likely refers to landing page, a common term often kept as 'Landing'. So "Landing (Vite + React)" -> same.
cd dashboard && npm install && npm run dev # localhost:5173
# But this results in no actual translation, which seems pointless. The user likely expects Chinese characters for the common words. Perhaps the instruction is misinterpreted. Let me re-read: "Keep all professional terms, proper nouns, tool/library/framework names, and technical jargon in their original English form." So 'AILedger' is a proper noun? Probably. 'Proxy' is a technical jargon, keep. 'Cloudflare Worker' is a tool name, keep. 'SDK' is a professional term, keep. 'TypeScript' is a language, keep. 'Dashboard' could be considered a professional term? It's a common term in software. 'Vite' and 'React' are frameworks. 'Landing' is a term for a type of page. So all are considered professional terms? Then no translation needed. But the user's request says "Translate each of the following headings to Simplified Chinese." So they expect Chinese characters. The examples given show that some words are translated (like 'Running', 'Setup', 'Reference'). So we need to identify which words are not professional terms. In 'Proxy (Cloudflare Worker)', 'Proxy' itself is a technical term, but it's also a common word. I think 'Proxy' is a technical jargon, so keep. But then 'Cloudflare Worker' - 'Worker' could be translated? But it's part of a product name 'Cloudflare Worker' which is a proper noun. So keep entire. So the only thing that could be translated is the parentheses? No. So maybe we should translate 'Proxy' to '代理'? But that contradicts instruction.
cd landing && npm install && npm run dev # localhost:5173
```
代理机密信息（通过 `wrangler secret put` 设置）：
- `SUPABASE_URL`
- `SUPABASE_SERVICE_KEY`
- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`
- `POSTMARK_API_KEY`
仪表板配置（`dashboard/.env.local`）：
```
VITE_SUPABASE_URL=https://.supabase.co
VITE_SUPABASE_ANON_KEY=
```
## 这不是什么
AILedger 不认证合规性。我们提供基础设施；合规是客户的工作。我们提供便利，而非认证。
## 许可证
版权 (c) 2026 Jake Joyner。
本仓库采用 GNU Affero 通用公共许可证 v3.0（AGPLv3）授权；详见 [LICENSE](LICENSE)。因为 AGPLv3 将网络使用视为分发，任何人如果以网络服务形式运行本软件的修改版本，必须在相同条款下向用户提供完整的对应源代码。对于无法满足 AGPL 版权保护义务的组织，例如将 AILedger 嵌入专有产品或作为闭源服务运行，也提供商业许可证。商业许可证免除这些义务。联系 ops@jvholdings.co。
检测层（[github.com/ailedger-dev/ailedger-detection](https://github.com/ailedger-dev/ailedger-detection)）：Apache 2.0。章程：公开。
联系方式：`ops@jvholdings.co`。
标签：AGPL, AI审计, Apache2.0, MITM代理, Postgres, RegTech, Supabase, Zenmap, 三层架构, 不可篡改, 人工智能, 伪匿名化, 决策事件, 合规, 哈希链, 审计追踪, 开源, 数据完整性, 检测层, 欧盟AI法案, 法规, 用户模式Hook绕过, 监管技术, 程序员工具, 网络安全, 联邦证据规则, 自动化攻击, 逆向工具, 隐私保护