@getmaapp/signal-wasm

中文文档
0.6.6发布于 2026/08/19AGPL-3.0-onlyTypeScriptES Module零依赖近 30 天下载 2038

为基于浏览器的 E2EE 消息编辑到 WebAssembly 的信号协议

中文使用文档
文档目录23 节
  1. 特征
  2. 安装
  3. 快速启动
  4. API 参考
  5. 加密初级
  6. 协议地址
  7. 存储(内存)
  8. 密钥生成
  9. 礼宾业务
  10. 处理错误
  11. 安全编号
  12. 身份证明
  13. GV2(私人团体)
  14. 数据结构
  15. 工具函数
  16. 虚拟配置
  17. 测试
  18. 从源创建
  19. 警卫
  20. 内存安全和零化
  21. * Panics Brick the Entertainment * * 惊慌失措 *
  22. 许可证
  23. 免责声明

@ getmaapp/ signal-wasm

为基于浏览器的 E2EE 消息编辑到 WebAssembly 的信号协议

License: AGPL-3.0 WASM Version

特征

  • 🔐 端到端加密 - 信号协议(PQXDH + 三重鼠标)
  • 🛡️ 量子后准备 - Kyber1024(P-DH)支助
  • 👥 分组消息 ——发件人密钥和私人团体(GV2)
  • 🆔 灵活身份 - 任意字符串标识符(Firebase UID、用户名、UUID)
  • 🔢 安全编号 - 身份核查指纹
  • 💾 序列化 - 索引数据库持续进出口
  • 🌐 浏览器- 第一 —— 随机性使用 Web Crypto API

安装

npm install @getmaapp/signal-wasm

快速启动

import init, {
  PrivateKey,
  IdentityKeyPair,
  ProtocolAddress,
  InMemIdentityKeyStore,
  InMemSessionStore,
  InMemPreKeyStore,
  InMemSignedPreKeyStore,
  InMemKyberPreKeyStore,
  generateRegistrationId,
  generatePreKeys,
  generateSignedPreKey,
  generateKyberPreKey,
  processPreKeyBundle,
  encryptMessage,
  decryptMessage,
} from "@getmaapp/signal-wasm";

// 1. Initialise the WASM module
await init();

// 2. Generate an identity (no device ID required)
const privateKey = PrivateKey.generate();
const publicKey = privateKey.getPublicKey();
const identityKeyPair = new IdentityKeyPair(publicKey, privateKey);
const registrationId = generateRegistrationId();

// 3. Create stores
const identityStore = new InMemIdentityKeyStore(identityKeyPair, registrationId);
const sessionStore = new InMemSessionStore();
const prekeyStore = new InMemPreKeyStore();
const signedPrekeyStore = new InMemSignedPreKeyStore();
const kyberPrekeyStore = new InMemKyberPreKeyStore();

// 4. Generate keys for registration
const prekeys = await generatePreKeys(1, 100, prekeyStore);
const signedPreKey = await generateSignedPreKey(1, identityKeyPair, signedPrekeyStore);
const kyberPreKey = await generateKyberPreKey(1, identityKeyPair, kyberPrekeyStore);

// 5. Addressing (device ID is only used here)
const localAddress = new ProtocolAddress("alice-firebase-uid", 1);
const bobAddress = new ProtocolAddress("bob-firebase-uid", 1);

// 6. Establish a session (Alice processes Bob's PreKey bundle)
await processPreKeyBundle(
  bobAddress,
  localAddress,
  bobRegistrationId,
  bobIdentityKey,
  bobSignedPreKey.id,
  bobSignedPreKeyPublic,
  bobSignedPreKey.signature,
  bobPreKey.id,
  bobPreKey.public_key,
  bobKyberPreKey.id,
  bobKyberPreKey.public_key,
  bobKyberPreKey.signature,
  sessionStore,
  identityStore,
);

// 7. Encrypt a message
const plaintext = new TextEncoder().encode("Hello Bob! 🔒");
const ciphertext = await encryptMessage(
  plaintext,
  bobAddress,
  localAddress,
  sessionStore,
  identityStore,
);

// 8. Decrypt a message
const result = await decryptMessage(
  ciphertext.body,
  ciphertext.message_type,
  aliceAddress,
  bobAddress,
  sessionStore,
  identityStore,
  prekeyStore,
  signedPrekeyStore,
  kyberPrekeyStore,
);
const plaintext2 = result.plaintext;

// 9. Tombstone any one-time keys the decrypt consumed. All id fields
//    are `undefined` when nothing was consumed (e.g. non-prekey messages).
if (result.kyberPreKeyId !== undefined) {
  // delete kyber prekey result.kyberPreKeyId from your durable store
}
if (result.oneTimePreKeyId !== undefined) {
  // delete X25519 prekey result.oneTimePreKeyId from your durable store
}

API 参考

加密初级

类方法
PrivateKeygenerate(), (中文(简体) ), getPublicKey(), (中文(简体) ), serialize(), (中文(简体) ), deserialize(data)
PublicKeyserialize(), (中文(简体) ), deserialize(data)
IdentityKeyPairconstructor(publicKey, privateKey), (中文(简体) ), serialize(), (中文(简体) ), deserialize(data)

协议地址

类说明
ProtocolAddressconstructor(name, deviceId) —— 说 name 可以是任意字符串(Firebase UID,UUID等)

存储(内存)

所有商店都支持索引数据库的持续进出口.

存储构造器进出口方法
InMemIdentityKeyStorenew(identityKeyPair, registrationId)—— 说
InMemSessionStorenew()export_session(address), (中文(简体) ), import_session(address, bytes), (中文(简体) ), has_session(address), (中文(简体) ), archive_session(address), (中文(简体) ), delete_session(address)
InMemPreKeyStorenew()export_pre_key(id), (中文(简体) ), import_pre_key(id, bytes)
InMemSignedPreKeyStorenew()export_signed_pre_key(id), (中文(简体) ), import_signed_pre_key(id, bytes)
InMemKyberPreKeyStorenew()export_kyber_pre_key(id), (中文(简体) ), import_kyber_pre_key(id, bytes), (中文(简体) ), export_kyber_usage(), (中文(简体) ), import_kyber_usage(bytes)
InMemSenderKeyStorenew()export_sender_key(address, distributionId), (中文(简体) ), import_sender_key(address, distributionId, bytes), (中文(简体) ), remove_sender_key(address, distributionId)

自0.4.0起: 每个 distributionId 一定是被打来的 UUID 字符串 (例如:. crypto.randomUUID()) (中文(简体) ). 包装纸不再从 任意组合字符串. remove_sender_key(address, distributionId) 删除 发送键记录(返回) boolean) 并且必须在 重新制作关于成员去除/妥协的分布图,否则为自定义 重新使用已存在的链条,被移除的成员继续解密.

自0.6.0起: InMemKyberPreKeyStore 也带着开膛手 反重放 内存 - 这套 (kyberId, signedPreKeyId, senderBaseKey) 三倍 引擎已经看到。 坚持下去export_kyber_usage() - 字节, import_kyber_usage(bytes) 与kyber的记录. 没有它,每一次重新装入和重放的后卫 PreKeySignalMessage 对抗活的后遗症密钥再次被斩首. 这与Signal自己的客户端所坚持的一致(Signal-iOS的) KyberPreKeyUseRecord 表,信号-德斯克托普 kyberPreKey_triples) (中文(简体) ).

密钥生成

函数回返说明
generatePreKeys(startId, count, store)Promise<WasmPreKey[]>批量遗传一次性预键
generateSignedPreKey(id, identityKeyPair, store)Promise<WasmSignedPreKey>生成一个签名的 PreKey
generateKyberPreKey(id, identityKeyPair, store)Promise<WasmKyberPreKey>生成 Kyber PreKey (PQXDH)
generateRegistrationId()number生成无偏见的登记身份证(1-16383)

礼宾业务

函数回返说明
processPreKeyBundle(...)Promise<void>从 PreKey 捆绑建立会话
encryptMessage(plaintext, recipient, localAddress, sessionStore, identityStore)Promise<WasmCiphertext>加密 1:1 个消息
decryptMessage(ciphertext, type, sender, localAddress, sessionStore, identityStore, prekeyStore, signedPrekeyStore, kyberPrekeyStore)Promise<WasmDecryptResult>解密1:1个消息. 结果获取器 : plaintext (单位:千美元)Uint8Array),加 (中文(简体) ) kyberPreKeyId 编号 : oneTimePreKeyId 编号 : signedPreKeyId - 一次性预键标识,用于建立新的届会(undefined (没有) 墓碑在你的耐用店里消耗了身份证
createSenderKeyDistribution(localAddress, distributionId, senderKeyStore)Promise<Uint8Array>创建发件人密钥分发信件( E)distributionId 必须是 UUID 字符串)
processSenderKeyDistribution(senderAddress, distMessage, senderKeyStore)Promise<void>处理发送者密钥分发消息( 从信件读取)
encryptGroupMessage(localAddress, distributionId, plaintext, senderKeyStore)Promise<Uint8Array>加密组信件( E)distributionId 必须是 UUID 字符串)
decryptGroupMessage(senderAddress, ciphertext, senderKeyStore)Promise<Uint8Array>解密一个组消息( 从密码文本读取 )

处理错误

每个被否决的诺言都会有真正的联署材料 Error 改为:

  • message —— 说 "SignalError: <detail>" 在调试构造中;平整为 "SignalError: Operation failed" 正在建立(未改变的行为).
  • code ——一个稳定的机器可读字符串,与 libsignal 错误相匹配 类型 因此,即使在释放时,它仍然保持具体:
code含义
NoSenderKeyState信件分发代号没有发件人键记录( 如 SKDM 尚未处理 —— 拉后重试)
DuplicatedMessage已看到信件计数器( 重放/ 复制; 通常是良性)
ReusedKyberBaseKeyKyber 反重放拒绝: 此发件人基础密钥已被使用 (kyberId, signedPreKeyId) 配对 — 一个重放的 PreKey SignalMessage
UntrustedIdentity无法信任地址的发件人身份密钥
InvalidKyberPreKeyId引用的 Kyber 预键id 无效/ 丢失
InvalidPreKeyId引用的预键 ID 无效/ 丢失
InvalidSignedPreKeyId已签名的引用预钥 ID 无效/ 丢失
FingerprintVersionMismatch扫描的 QR 指纹版本与我们的不同( 由 verifyScannableFingerprint(中文(简体) )
FingerprintParsingError扫描的 QR 指纹有效载荷无法解码或变形
Generic其他一切,包括包装侧验证失败

说明: String(err) 现在产量 "Error: SignalError: …" (标准) Error 字符串化),而不是空信,因为抛出值是一个 真实 Error 而不是绳子。 网站阅读 err.message 为: 不受影响.

安全编号

函数回返说明
generateSafetyNumber(localUuid, localIdentityKey, contactUuid, contactIdentityKey)WasmSafetyNumber生成安全编号指纹( E)displayable 字符串 + scannable QR有效载荷)
verifyScannableFingerprint(scanned, localUuid, localIdentityKey, contactUuid, contactIdentityKey)boolean从0.5.0. Canonical 跨视角 QR 校验 (ScannableFingerprint::compare:检查他们的. local \"我们的.remote" 和他们的.remote \"我们的.local" 在恒定的时间。 掷出 FingerprintVersionMismatch 关于版本不匹配, FingerprintParsingError 在不可解码的有效载荷上
verifySafetyNumber(...)boolean从0.5.0. 重新计算我们自己的指纹和字节比对——它永远无法验证一个跨视角扫描. 用于 API 兼容性; 使用 verifyScannableFingerprint

身份证明

服务器可核实的对身份密钥的持有证明(例如授权 (原始内容存档于2018-03-26). Re-key). XEdDSA上方为X25519身份密钥,犬形的libsignal签名.

函数回返说明
signWithIdentityKey(identityPrivateKey, message)Uint8Array签名 message 带有私钥的身份(64字节签名)
verifyIdentitySignature(identityPublicKey, message, signature)boolean经常核查; false 错误的密钥/消息或错误的签名

GV2(私人团体)

类方法
WasmGroupMasterKeygenerate(), (中文(简体) ), from_bytes(bytes), (中文(简体) ), derive_identifier(), (中文(简体) ), derive_secret_params()
WasmGroupIdentifierserialize
WasmGroupSecretParamsserialize_master_key (自0. 5. 0; 返回 32 字节) 主密钥而不是完整的参数编码, get_identifier()

数据结构

结构属性
WasmPreKeyid, (中文(简体) ), public_key, (中文(简体) ), record
WasmSignedPreKeyid, (中文(简体) ), public_key, (中文(简体) ), signature, (中文(简体) ), timestamp, (中文(简体) ), record
WasmKyberPreKeyid, (中文(简体) ), public_key, (中文(简体) ), signature, (中文(简体) ), timestamp, (中文(简体) ), record
WasmCiphertextmessage_type, (中文(简体) ), body
WasmSafetyNumberdisplayable (弦声), scannable (Uint8箭头)

工具函数

函数说明
generate_random_bytes(length)生成 CSPRNG 随机字节( 最大 1 MiB)
generate_uuid()生成一个 UUID v4( 返回 16 字节)
uuid_to_string(bytes)将 16 字节转换为 UUID 字符串
uuid_from_string(str)将 UUID 字符串转换为 16 字节
message_type_signal()普通信号信息类型常数
message_type_pre_key()PreKey 消息类型常数
message_type_sender_key()发送者密钥消息类型常数

虚拟配置

// vite.config.ts
import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";

export default defineConfig({
  plugins: [wasm(), topLevelAwait()],
});

测试

我们用 wasm-bindgen-test 用于无头浏览器集成测试.

# Run tests in Headless Chrome
wasm-pack test --headless --chrome

# Run tests in Headless Firefox
wasm-pack test --headless --firefox

从源创建

# Prerequisites
rustup target add wasm32-unknown-unknown
cargo install wasm-pack

# Build
wasm-pack build --target web --scope getmaapp

警卫

  • ✅ #![deny(unsafe_code)] - 没有不安全的玫瑰花
  • QQ 对所有 WASM 绑定参数进行输入验证
  • 固定拨款额generate_random_bytes 限于1个小米B)
  • PreKey 批量生成限500个键
  • QQ 24 位 PreKey ID 包装( 匹配信号行为)
  • 通过 Web Crypto API 创建 CSPRNG
  • 生产中的一般错误信息构建
  • * 秘密包装缓冲器在滴出时为零(zeroize::Zeroizing)-见下文说明
  • ✅ log_to_console 调试帮助器编译出释放构建

内存安全和零化

  • 包装器拥有的秘密缓冲器被包裹 zeroize::Zeroizing 并带有零值的复写:序列化 PreKey/签名PreKey/KyberPreKey记录(每个记录包含私分), 和组合主键字节 WasmGroupMasterKey 编号 : WasmGroupSecretParams。 。 。 .
  • 限制. 长期身份密钥本身是一个自定义 PrivateKey - 上游地区 Copy 类型在一个以上 [u8; 32] 利比诺是 空投时不是零,所以包装器无法保证身份的去除 当它活在WASM线性记忆中时,会变平. 还有 任何字节导出到 Java 脚本 (通过) serialize()等)是JS记忆中的复制品 受浏览器垃圾收集器约束; 无法从中去除 生锈. 用极其小心的方式处理导出密钥 .

* Panics Brick the Entertainment * * 惊慌失措 *

释放构建使用 panic = "abort" (瓦斯姆河对岸没有风) 边界)。 因此,一个Rust恐慌 永久为 WASM 实例建砖 —— 说 之后的每一个呼叫陷阱, 和表面JS作为平地 SignalError: Operation failed 没有可收回的细节。 页面重载( 新实例) 是唯一 补救。 调试构建寄存器 console_error_panic_hook 如此惊慌 在开发过程中在控制台中可见.

许可证

AGPL-3.0 — 见 自由主义

此软件包基于 升号 v0.101.0 (承诺) b056faa6d)由信号技术基金会提供.

免责声明

此套件不隶属于信号技术基金会或得到其认可. 信号与信号协议是信号技术基金会的商标.

版本与发布记录

@getmaapp/signal-wasm 共发布 13 个版本,首次发布于 2026/01/15;过去 12 个月发布了 13 个版本。

版本发布日期距今
0.6.6latest2026/08/192 个月前
0.6.52026/08/163 个月前
0.6.42026/08/163 个月前
0.6.32026/08/153 个月前
0.6.22026/08/153 个月前
0.6.02026/08/123 个月前

关于 @getmaapp/signal-wasm 的常见问题

@getmaapp/signal-wasm 是什么?

为基于浏览器的 E2EE 消息编辑到 WebAssembly 的信号协议

如何安装 @getmaapp/signal-wasm?

在项目目录运行 npm install @getmaapp/signal-wasm,或使用 pnpm add / yarn add / bun add。

@getmaapp/signal-wasm 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getmaapp/signal-wasm 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@getmaapp/signal-wasm 可以商用吗?

@getmaapp/signal-wasm 使用 AGPL-3.0-only 许可。最严格的 Copyleft:除分发外,通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括,不构成法律意见,请以许可原文为准。

@getmaapp/signal-wasm 的下载量有多少?

根据 npm 官方下载统计,@getmaapp/signal-wasm 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,038 次,日均约 68 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getmaapp/signal-wasm 还在维护吗?

最新版本 0.6.6 发布于 2026/08/19(2 个月前);至今共发布 13 个版本,其中过去 12 个月发布了 13 个;首次发布于 2026/01/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。