Attomus/semafore-crypto
GitHub: Attomus/semafore-crypto
这是一个 TypeScript 实现的 SemaFore 端到端加密消息库，用于在消息传输前进行加密保护。
Stars: 0 | Forks: 0
# @attomus/semafore-crypto
SemaFore 端到端加密消息线路格式的 TypeScript 实现。
此包专为需要在消息内容离开调用者控制的环境前，对其进行加密的集成运行时设计。它仅包含加密和线路格式层：无网络调用、无服务令牌处理、无存储、也无聚合功能。
## 状态
`1.0.0` 的发布候选版本。加密线路格式表面已通过字节级一致性向量覆盖，但围绕 SemaFore 的集成表面仍在积极开发中，同时 GitHub Action 正朝着 Marketplace 就绪状态发展。
当前已实现：
- X25519 身份和棘轮密钥
- Ed25519 签名预验证密钥验证
- AES-256-GCM 负载加密
- HKDF-SHA256 密钥派生
- X3DH 发送方和接收方引导助手
- SMX1 首次联系信封
- SMD1 双棘轮后续消息
- 有界跳过消息密钥处理
- DR-v1 和 X3DH/SMX1 向量的字节级一致性测试
该实现与当前已检查一致性向量的 SemaFore iOS Swift 和 Android Kotlin 客户端保持线路兼容，包括存在和不存在一次性预密钥（OPK）的 SMX1 场景。
## 安装
在 npm 发布版发布后：
```
npm install @attomus/semafore-crypto
```
## 快速开始
```
import {
generateIdentityKeyPair,
generateEd25519KeyPair,
generateSignedPrekey,
generateOneTimePrekey,
initReceiverSession,
initSenderSession,
encryptMessage,
decryptMessage
} from '@attomus/semafore-crypto';
const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes);
// Long-lived identity keys: X25519 for ECDH, Ed25519 for signatures.
const aliceIdentity = generateIdentityKeyPair();
const bobIdentity = generateIdentityKeyPair();
const bobSigning = generateEd25519KeyPair();
// Bob publishes a signed prekey and one-time prekeys. Alice fetches them as a bundle.
const bobSpk = generateSignedPrekey(bobSigning.secretKey, 'spk-current');
const bobOpk = generateOneTimePrekey('opk-001');
const aliceSession = initSenderSession({
localIdentity: aliceIdentity,
recipientBundle: {
identityAgreementKey: bobIdentity.publicKey,
identitySigningKey: bobSigning.publicKey,
signedPrekey: bobSpk,
oneTimePrekey: bobOpk
}
});
// First message: carries the X3DH bootstrap. Later messages on this session
// use the Double Ratchet continuation path.
const firstEnvelope = encryptMessage(aliceSession, 'Hello SemaFore');
// Bob's prekey lookups typically hit on-device storage; stubbed here.
const { session: bobSession } = initReceiverSession({
localIdentity: bobIdentity,
peerIdentityPublicKey: aliceIdentity.publicKey,
envelope: firstEnvelope,
signedPrekeyLookup: () => bobSpk,
oneTimePrekeyLookup: () => bobOpk
});
const plaintext = decryptMessage(bobSession, firstEnvelope);
console.log(decode(plaintext)); // 'Hello SemaFore'
// Second message: same session, now continuing under Double Ratchet.
const secondEnvelope = encryptMessage(aliceSession, 'and again');
console.log(decode(decryptMessage(bobSession, secondEnvelope))); // 'and again'
```
## 线路格式
SemaFore 目前使用两种消息信封格式：
- **SMX1**：首次联系 X3DH 预密钥信封。
- **SMD1**：会话引导后的双棘轮消息信封。
线路布局详见 [线路格式文档](./docs/wire-format.md)。
更改任一格式都是破坏性的协议变更。
## 一致性
测试套件包含固定的 SemaFore 向量：
- `dr-v1-interop.json`
- `x3dh-prekey-v1.json`
X3DH/SMX1 向量从 Android 实现中提取，涵盖了存在和不存在一次性预密钥的首次联系流程。
使用以下命令运行完整的本地检查：
```
npm run verify
```
## 安全模型
- 消息明文在离开调用者运行时前被加密。
- AES-256-GCM 对每次加密使用全新的随机 12 字节 nonce。
- X25519、Ed25519、HKDF-SHA256 和 AES-GCM 使用 `@noble/*` 包实现。
- 调用者拥有密钥存储、棘轮状态持久化、服务令牌处理、接收者查找和传输功能。
- 调用者不得以明文形式存储私钥和棘轮状态。
## 负责任披露
请私下报告安全问题。参见 [SECURITY.md](./SECURITY.md)。
## 许可证
Apache-2.0。
标签：AES-256-GCM, CVE, Double Ratchet协议, Ed25519, npm包, TypeScript, X25519, X3DH协议, 加密, 加密协议, 加密解密, 向量兼容, 块加密, 安全插件, 安全通信, 密码学, 密钥交换, 密钥派生, 密钥生成, 手动系统调用, 数字签名, 消息安全, 漏洞扫描器, 端到端加密, 线格式, 自动化攻击