🔐 Tirisfal

为 AI Agent 设计的自托管凭证管理服务

运行在 Cloudflare Workers 上，支持 Bitwarden 兼容协议

---

✨ 特性

功能	描述
🤖	Machine Accounts - 为每个 Agent 创建独立的机器账号
📁	Projects - 按项目分组管理凭证
🔑	Secrets - 安全存储 API Key、Token、密码等凭证
🎫	Access Tokens - Agent 通过 Token 访问凭证
📊	Audit Logs - 记录所有凭证访问行为
🔒	End-to-End Encryption - AES-256-GCM 加密存储

---

🚀 快速开始

部署

# 克隆仓库
git clone https://github.com/ialer/tirisfal.git
cd tirisfal

# 安装依赖
npm install

# 配置环境变量
cp .dev.vars.example .dev.vars

# 设置密钥
wrangler secret put JWT_SECRET
wrangler secret put ENCRYPTION_KEY

# 初始化数据库
wrangler d1 execute tirisfal-db --file=./migrations/0001_init.sql
wrangler d1 execute tirisfal-db --file=./migrations/0002_sm_tables.sql

# 部署
npm run deploy

本地开发

npm run dev

---

📖 使用指南

1️⃣ 创建 Machine Account

curl -X POST https://your-worker.workers.dev/api/machine-accounts \
  -H "Authorization: Bearer <user-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My AI Agent"}'

2️⃣ 获取 Access Token

curl -X POST https://your-worker.workers.dev/api/machine-accounts/<id>/token \
  -H "Authorization: Bearer <user-token>"

3️⃣ 创建项目和凭证

# 创建项目
curl -X POST https://your-worker.workers.dev/api/projects \
  -H "Authorization: Bearer <user-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}'

# 创建凭证
curl -X POST https://your-worker.workers.dev/api/secrets \
  -H "Authorization: Bearer <user-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "API_KEY", "value": "sk-***", "project_id": "<project-id>"}'

4️⃣ Agent 获取凭证

curl "https://your-worker.workers.dev/api/secrets/by-name/API_KEY?project_id=<id>&environment=prod" \
  -H "Authorization: Bearer <machine-token>" | jq -r .value

---

🔐 安全特性

特性	实现
🔑	AES-256-GCM - 行业标准加密算法
🧂	PBKDF2 600K - OWASP 推荐迭代次数
⏰	Token Rotation - 支持自动轮换和撤销
🛡️	IP Whitelist - 限制访问来源
🕐	Time Window - 基于时间的访问控制
📝	Audit Trail - 完整的访问日志
🚦	D1 Atomic Rate Limiting - 防竞态条件速率限制
🔒	Constant-Time Comparison - 防时序攻击
🛡️	Project Ownership Verification - 防跨用户访问

安全审计

本项目经过全面安全审计，已修复以下问题：

严重漏洞 (已修复)

• ✅ 速率限制绕过 - 移除不安全的导入绕过逻辑
• ✅ Cache API 竞态条件 - 改用 D1 原子操作防止并发绕过
• ✅ 项目所有权验证缺失 - 添加跨用户访问防护

高危漏洞 (已修复)

• ✅ 常量时间比较时序泄漏 - 修复 API Key 比较实现
• ✅ SM 端点缺少速率限制 - 为 Machine Account Token 添加限流
• ✅ 凭证访问审计盲区 - 补全 GET /api/secrets/:id 审计日志

隐性问题 (已修复)

• ✅ 内存溢出风险 - 同步响应添加 50MB 大小限制
• ✅ 缓存无界增长 - AuthService 添加 LRU 淘汰策略
• ✅ 登录锁定过于宽松 - 优化为 5次/15分钟策略

---

🛠️ API 参考

Machine Accounts

方法	端点	描述
POST	/api/machine-accounts	创建机器账号
GET	/api/machine-accounts	列出所有机器账号
GET	/api/machine-accounts/:id	获取机器账号详情
PUT	/api/machine-accounts/:id	更新机器账号
DELETE	/api/machine-accounts/:id	删除机器账号
POST	/api/machine-accounts/:id/token	生成访问令牌
POST	/api/machine-accounts/:id/revoke-token	撤销访问令牌

Projects

方法	端点	描述
POST	/api/projects	创建项目
GET	/api/projects	列出所有项目
GET	/api/projects/:id	获取项目详情
DELETE	/api/projects/:id	删除项目

Secrets

方法	端点	描述
POST	/api/secrets	创建凭证
GET	/api/secrets?project_id=<id>	列出项目下的凭证
GET	/api/secrets/:id	获取凭证详情
PUT	/api/secrets/:id	更新凭证
DELETE	/api/secrets/:id	删除凭证
GET	/api/secrets/by-name/:name	通过名称获取凭证

---

📦 SDK

我们提供多语言 SDK，简化 Agent 集成：

Python

from tirisfal import TirisfalClient

client = TirisfalClient(
    server="https://your-worker.workers.dev",
    token="your-machine-account-token"
)

secret = client.get_secret("API_KEY", project_id="xxx", environment="prod")
print(secret.value)

Node.js

const { TirisfalClient } = require('@tirisfal/sdk');

const client = new TirisfalClient({
  server: 'https://your-worker.workers.dev',
  token: 'your-machine-account-token'
});

const secret = await client.getSecret('API_KEY', { projectId: 'xxx' });
console.log(secret.value);

Go

import "github.com/ialer/tirisfal/sdk/go"

client := tirisfal.NewClient("https://your-worker.workers.dev", "your-token")
secret, _ := client.GetSecret("API_KEY", "project-id", "prod")
fmt.Println(secret.Value)

---

🏗️ 架构

┌─────────────────────────────────────────────────────────────┐
│                      Cloudflare Workers                       │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │    Auth      │  │    SM API   │  │   Backup    │        │
│  │   Service    │  │   Service   │  │   Service   │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│         │                │                │                  │
│  ┌──────┴────────────────┴────────────────┴──────┐        │
│  │              SecretsManagerService             │        │
│  └──────────────────────┬────────────────────────┘        │
│                         │                                  │
│  ┌──────────────────────┴────────────────────────┐        │
│  │           AES-256-GCM Encryption              │        │
│  └──────────────────────┬────────────────────────┘        │
│                         │                                  │
├─────────────────────────┼──────────────────────────────────┤
│  ┌──────────────────────┴────────────────────────┐        │
│  │                    D1 Database                 │        │
│  │  ┌─────────────┐  ┌─────────────┐            │        │
│  │  │   secrets   │  │   projects  │            │        │
│  │  └─────────────┘  └─────────────┘            │        │
│  └───────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────────┘

---

🔧 配置

环境变量

变量	必填	描述
JWT_SECRET	✅	JWT 签名密钥（32+ 字符）
ENCRYPTION_KEY	✅	加密密钥（32+ 字符）
DB	✅	D1 数据库绑定
ATTACHMENTS	❌	R2 存储桶（可选）

生成密钥

# 生成 JWT 密钥
openssl rand -hex 32

# 生成加密密钥
openssl rand -base64 32

数据库表

项目使用以下 D1 数据表：

表名	用途
users	用户账户
ciphers	密码项
folders	文件夹
attachments	附件
sends	Send 分享
refresh_tokens	刷新令牌
devices	设备绑定
audit_logs	审计日志
login_attempts_ip	登录失败记录
rate_limits	API 速率限制
machine_accounts	机器账号
sm_projects	项目
secrets	凭证
machine_account_projects	机器账号项目权限
secret_access_logs	凭证访问日志

---

📚 文档

• API 文档
• 优化报告

---

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING.md 了解详情。

---

📄 许可证

本项目使用 LGPL-3.0 许可证。

---

_{Built with ❤️ by SN Team}