forgesworn/canary-kit
GitHub: forgesworn/canary-kit
基于TypeScript构建的抗深度伪造身份验证协议，通过动态口语词汇和双向验证机制，有效防御语音钓鱼及AI克隆攻击。
Stars: 2 | Forks: 1
# canary-kit
**Nostr:** [`npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`](https://njump.me/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)
[](https://www.npmjs.com/package/canary-kit)
[](https://github.com/forgesworn/canary-kit/actions)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](vitest.config.ts)
[](https://github.com/sponsors/TheCryptoDonkey)
**[Interactive Demo](https://canary.trotters.cc/)** · [Protocol Spec](CANARY.md) · [Nostr Binding](NIP-CANARY.md) · [Integration Guide](INTEGRATION.md) · [Groups Protocol](GROUPS.md) · [Nostr Transport](NIP-XX.md) · [Threat Model](THREAT-MODEL.md) · [Regulatory](REGULATORY.md)
## 为什么是现在
监管机构和犯罪分子同时到达了同一个转折点。2023 年 3 月，联合国毒品和犯罪问题办公室正式将 AI 合成语音与运营跨国诈骗的有组织犯罪网络联系起来。语音克隆工具现在作为服务提供，月费低于 400 美元；2025 年，语音钓鱼激增了 442%。同一周，阿联酋中央银行设定了 2026 年 3 月 31 日的最后期限，禁止所有持牌金融机构使用短信 OTP（一次性密码）——这是首个强制要求其替代方案的国家监管机构。印度储备银行（RBI）于 2026 年 4 月 1 日跟进，要求所有数字支付交易必须进行双重身份验证。《欧盟人工智能法案》的深度伪造透明度义务（第 50 条）于 2026 年 8 月生效；到 2026 年 12 月，所有 27 个成员国都必须提供 EUDI 钱包。FCA（英国金融行为监管局）的强客户认证技术标准已于 2026 年 3 月更新。
CANARY 正是定位于这些压力的交汇点：语音渠道，这是身份认证最薄弱且监管缺口最大的地方。有关 CANARY 安全属性与各项法规的详细对照，请参阅 [REGULATORY.md](REGULATORY.md)。
完整的验证堆栈涵盖四种呼叫者场景：已知人士、已知机构（由 CANARY 处理）、未知人士以及未知机构的陌生来电——最后一项通过 [Signet](https://github.com/forgesworn/signet) 陌生来电验证（即将推出）实现。深度伪造标记工具和 CANARY 是互补的：前者在事后标记 AI 生成的内容；后者则在交互点实时验证呼叫者的身份。
## 问题所在
2025 年，语音钓鱼激增了 442%。AI 仅需三秒钟的音频即可克隆声音。本应保护我们的工具正在失效：
- **安全问题** 是单向的，且容易受到社会工程学攻击
- **语音生物识别** —— 在遭受深度伪造攻击后，91% 的美国银行正在重新考虑使用
- **TOTP 代码** 向服务器证明了你的身份，但从未向服务器证明它自己的身份
- **“家庭安全词”** 是静态的，从不轮换，且不具备胁迫信号功能
CANARY 是首个将 **双向验证**（双方均证明身份）、**抗胁迫性**（胁迫令牌）和 **口语输出** 结合在一起的协议——这三种特性从未同时存在于同一标准中。
它之所以有效，是因为克隆声音无助于推导出正确的词汇。只有掌握共享秘密才行。
## 快速开始
```
npm install canary-kit
```
### 电话验证（保险、银行）
```
import { createSession } from 'canary-kit/session'
const session = createSession({
secret: sharedSeed,
namespace: 'aviva',
roles: ['caller', 'agent'],
myRole: 'agent',
preset: 'call',
})
session.myToken() // "choose" — what I speak
session.theirToken() // "bid" — what I expect to hear
session.verify('bid') // { status: 'valid' }
```
### 家庭 / 团队验证
```
import { createGroup, getCurrentWord, verifyWord, getCounter } from 'canary-kit'
const group = createGroup({
name: 'Family',
members: [alicePubkey, bobPubkey],
preset: 'family',
})
getCurrentWord(group) // "falcon"
```
## 使用场景
| 使用场景 | 预设 | 轮换周期 | 替代方案 |
|----------|--------|----------|------------------|
| 保险电话 | `call` | 30 秒 | 安全问题 |
| 银行电话 | `call` | 30 秒 | 语音生物识别、回拨 |
| 拼车/配送交接 | `handoff` | 一次性 | 随机 PIN 码 |
| 家庭安全 | `family` | 7 天 | 静态安全词 |
| 新闻 / 行动主义 | `field-ops` | 24 小时 | 无（无现有标准） |
| 企业事件响应 | `enterprise` | 48 小时 | 通过电子邮件进行的挑战-应答 |
## 为什么不直接用...
| 解决方案 | CANARY 解决的局限性 |
|----------|------------------------|
| 安全问题 | 单向。易受社会工程学攻击。无轮换。 |
| 语音生物识别 | 可被 AI 语音克隆攻破。单向。 |
| TOTP (Google Auth) | 机器可读的数字，而非口语词汇。无胁迫信号。单向。 |
| 回拨号码 | 缓慢。无法证明代理的身份。 |
| BIP-39 词表 | 无验证协议。无轮换。无胁迫信号。 |
| “家庭安全词” | 静态。无轮换。无胁迫信号。无协议。 |
| **CANARY** | **双向。深度伪造免疫。具备胁迫感知。自动轮换。离线。开放。** |
## 为什么选择 Canary
**双向。** 双方均证明身份。呼叫者证明他们知道秘密，代理则反向证明。任何一方都无法冒充另一方。
**基于经过验证的原语构建。** CANARY 将 HOTP (RFC 4226) 和 TOTP (RFC 6238) 中的 HMAC 计数器模式扩展到了人际口语验证，并增加了胁迫信号和抗胁迫特性。
**离线优先。** 词汇从共享种子和基于时间的计数器本地推导。初始设置后无需网络。
**具备胁迫感知。** 每一方都有一个与验证词不同的个人胁迫词。说出它会静默地向系统发出警报，同时给攻击者提供合理的推诿余地。
**自动轮换。** 可配置的间隔 —— 电话呼叫为 30 秒，家庭群组为 7 天。
**极简依赖。** 核心加密逻辑为纯 JavaScript。仅使用 `@scure/bip32` 和 `@scure/bip39` 进行助记词密钥恢复。需要 `globalThis.crypto`（Web Crypto API）：支持所有浏览器、Node.js 22+、Deno 以及 edge 运行时。
**协议级。** 具有正式规范，已发布测试向量，并精选了 2048 个口语清晰度词汇表。
## 兼容性
| 运行时 | 版本 | 备注 |
|---------|---------|-------|
| Node.js | 22+ | 完全支持（需要 `globalThis.crypto`） |
| Deno | 1.x+ | 完全支持 |
| Bun | 1.x+ | 完全支持 |
| Browsers | 所有现代版本 | Chrome, Firefox, Safari, Edge |
| Cloudflare Workers | 是 | Web Crypto API 可用 |
| React Native | 通过 polyfill | 需要 `crypto.subtle` polyfill |
仅支持 ESM。提供八个子路径导出以支持 tree-shaking：
```
import { createSession } from 'canary-kit/session' // just sessions
import { deriveToken } from 'canary-kit/token' // just derivation
import { encodeAsWords } from 'canary-kit/encoding' // just encoding
import { WORDLIST } from 'canary-kit/wordlist' // just the wordlist
import { buildGroupStateEvent } from 'canary-kit/nostr' // just Nostr
import { encryptBeacon } from 'canary-kit/beacon' // just beacons
import { applySyncMessage } from 'canary-kit/sync' // just sync protocol
```
## 安全性
- **极简运行时依赖** —— 仅使用 `@scure/bip32` 和 `@scure/bip39` 进行助记词密钥恢复；核心加密逻辑为纯 JS
- **自动化发布** —— 使用 OIDC 可信发布的 GitHub Actions，无存储令牌
- **来源签名** —— 启用 npm 来源证明
- **协议级测试向量** —— CANARY.md 和 NIP-CANARY.md 中包含冻结的规范向量；任何符合规范的实现都必须产生相同的结果
- **时序安全字节比较** —— 提供 `timingSafeEqual()` 工具函数用于常量时间字节操作
- **有限容差** —— `MAX_TOLERANCE` 上限可防止病态迭代
有关漏洞披露和已知限制，请参阅 [SECURITY.md](SECURITY.md)。有关完整的安全分析，请参阅 [CANARY.md](CANARY.md)。
## API
| 子路径导出 | 关键函数 |
|---|---|
| `canary-kit/session` | `createSession`, `generateSeed`, `deriveSeed` |
| `canary-kit/token` | `deriveToken`, `verifyToken`, `deriveDuressToken`, `deriveLivenessToken` |
| `canary-kit/encoding` | `encodeAsWords`, `encodeAsPin`, `encodeAsHex` |
| `canary-kit` | `createGroup`, `getCurrentWord`, `verifyWord`, `addMember`, `reseed` |
| `canary-kit/nostr` | `buildGroupStateEvent`, `buildSignalEvent`, `buildStoredSignalEvent`, `buildRumourEvent` |
| `canary-kit/beacon` | `encryptBeacon`, `decryptBeacon`, `buildDuressAlert` |
| `canary-kit/sync` | `applySyncMessage`, `encodeSyncMessage`, `deriveGroupKey` |
| `canary-kit/wordlist` | `WORDLIST`, `getWord`, `indexOf` |
包含签名、类型和预设的完整 API 文档：**[API.md](API.md)**
## 协议
完整的协议规范位于 [CANARY.md](CANARY.md)。Nostr 绑定位于 [NIP-CANARY.md](NIP-CANARY.md)。金融/企业的集成指南位于 [INTEGRATION.md](INTEGRATION.md)。
| 事件 | Kind | 类型 |
|---|---|---|
| 群组状态 / 存储信号 | `30078` | 可参数化替换 |
| 实时信号 | `20078` | 临时 |
| 种子分发 / 成员更新 | `14` → `1059` | NIP-17 礼物包装（kind 14 谣言密封 + 包装） |
内容使用 **NIP-44** 加密。群组状态事件使用 `ssg/` d-tag 命名空间。种子分发和成员更新使用 **NIP-17** 礼物包装（kind 14 谣言 → kind 13 密封 → kind 1059 礼物包装）。事件可以携带 **NIP-40** `expiration` 标签。
## 针对 AI 助手
- [llms.txt](llms.txt) — 简明的 API 摘要
- [llms-full.txt](llms-full.txt) — 包含所有类型签名的完整参考
## 支持
有关问题和功能请求，请参阅 [GitHub Issues](https://github.com/forgesworn/canary-kit/issues)。
## ForgeSworn 工具包的一部分
[ForgeSworn](https://forgesworn.dev) 为 Nostr 构建开源的加密身份、支付和协调工具。
| 库 | 功能 |
|---------|-------------|
| [nsec-tree](https://github.com/forgesworn/nsec-tree) | 确定性子身份派生 |
| [ring-sig](https://github.com/forgesworn/ring-sig) | secp256k1 上的 SAG/LSAG 环签名 |
| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen 承诺范围证明 |
| [canary-kit](https://github.com/forgesworn/canary-kit) | 抗胁迫口语验证 |
| [spoken-token](https://github.com/forgesworn/spoken-token) | 人类可口语验证令牌 |
| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 支付中间件 |
| [geohash-kit](https://github.com/forgesworn/geohash-kit) | 带多边形覆盖的 Geohash 工具包 |
| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA 可验证证明 |
| [dominion](https://github.com/forgesworn/dominion) | 基于周期的加密访问控制 |
| [nostr-veil](https://github.com/forgesworn/nostr-veil) | 隐私保护的信任网络 |
## 许可证
MIT
标签：AI安全, Chat Copilot, Deepfake检测, DID, MITM代理, Nostr协议, NPM包, OSV-Scalibr, TypeScript, 人工智能安全, 分布式协议, 前端安全, 去中心化身份, 反欺诈, 合规性, 声纹识别, 多模态认证, 安全插件, 安全通信, 实时通信, 开发库, 开放协议, 无声胁迫检测, 深度伪造防御, 生物识别, 端到端加密, 网络安全, 网络安全, 群体同步, 胁迫检测, 自动化攻击, 语音克隆检测, 金融安全, 钓鱼防御, 防伪, 隐私保护, 隐私保护, 零知识证明