# @getmaapp/signal-wasm 中文文档

规范地址：https://npmcn.com/package/%40getmaapp/signal-wasm/

版本：0\.6\.6
npm 元数据更新时间：2026-08-19T12:50:10.614Z
中文译文更新时间：2026-11-16T14:28:15.335Z
软件包许可：AGPL-3\.0-only

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40getmaapp/signal-wasm
原文对照：https://npmcn.com/package/%40getmaapp/signal-wasm/?lang=original
项目主页：https://github.com/getmaapp/signal-wasm#readme
源码仓库：https://github.com/getmaapp/signal-wasm

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：926 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-01-14T18:39:34.515Z
- 最新版本发布：2026-08-19T12:50:10.444Z
- 近 30 天下载量：2038（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

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

## 安装

```sh
npm install @getmaapp/signal-wasm
```

也可以使用：`pnpm add @getmaapp/signal-wasm`、`yarn add @getmaapp/signal-wasm`、`bun add @getmaapp/signal-wasm`

## README

# @ getmaapp/ signal-wasm

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

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://npmcn.com/package/%40getmaapp/signal-wasm/LICENSE) [![WASM](https://img.shields.io/badge/WASM-Ready-green)](https://webassembly.org/) [![Version](https://img.shields.io/badge/Version-0.6.6-blue)](https://npmcn.com/package/%40getmaapp/signal-wasm/Cargo.toml)

## 特征

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

## 安装

```bash
npm install @getmaapp/signal-wasm
```

## 快速启动

```typescript
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 参考

### 加密初级

| 类 | 方法 |
| --- | --- |
| `PrivateKey` | `generate()`, (中文(简体) ), `getPublicKey()`, (中文(简体) ), `serialize()`, (中文(简体) ), `deserialize(data)` |
| `PublicKey` | `serialize()`, (中文(简体) ), `deserialize(data)` |
| `IdentityKeyPair` | `constructor(publicKey, privateKey)`, (中文(简体) ), `serialize()`, (中文(简体) ), `deserialize(data)` |

### 协议地址

| 类 | 说明 |
| --- | --- |
| `ProtocolAddress` | `constructor(name, deviceId)` —— 说 `name` 可以是任意字符串(Firebase UID,UUID等) |

### 存储(内存)

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

| 存储 | 构造器 | 进出口方法 |
| --- | --- | --- |
| `InMemIdentityKeyStore` | `new(identityKeyPair, registrationId)` | —— 说 |
| `InMemSessionStore` | `new()` | `export_session(address)`, (中文(简体) ), `import_session(address, bytes)`, (中文(简体) ), `has_session(address)`, (中文(简体) ), `archive_session(address)`, (中文(简体) ), `delete_session(address)` |
| `InMemPreKeyStore` | `new()` | `export_pre_key(id)`, (中文(简体) ), `import_pre_key(id, bytes)` |
| `InMemSignedPreKeyStore` | `new()` | `export_signed_pre_key(id)`, (中文(简体) ), `import_signed_pre_key(id, bytes)` |
| `InMemKyberPreKeyStore` | `new()` | `export_kyber_pre_key(id)`, (中文(简体) ), `import_kyber_pre_key(id, bytes)`, (中文(简体) ), `export_kyber_usage()`, (中文(简体) ), `import_kyber_usage(bytes)` |
| `InMemSenderKeyStore` | `new()` | `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` | 已看到信件计数器( 重放/ 复制; 通常是良性) |
| `ReusedKyberBaseKey` | Kyber 反重放拒绝: 此发件人基础密钥已被使用 `(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(私人团体)

| 类 | 方法 |
| --- | --- |
| `WasmGroupMasterKey` | `generate()`, (中文(简体) ), `from_bytes(bytes)`, (中文(简体) ), `derive_identifier()`, (中文(简体) ), `derive_secret_params()` |
| `WasmGroupIdentifier` | `serialize` |
| `WasmGroupSecretParams` | `serialize_master_key` (自0. 5. 0; 返回 32 字节) **主密钥**而不是完整的参数编码, `get_identifier()` |

### 数据结构

| 结构 | 属性 |
| --- | --- |
| `WasmPreKey` | `id`, (中文(简体) ), `public_key`, (中文(简体) ), `record` |
| `WasmSignedPreKey` | `id`, (中文(简体) ), `public_key`, (中文(简体) ), `signature`, (中文(简体) ), `timestamp`, (中文(简体) ), `record` |
| `WasmKyberPreKey` | `id`, (中文(简体) ), `public_key`, (中文(简体) ), `signature`, (中文(简体) ), `timestamp`, (中文(简体) ), `record` |
| `WasmCiphertext` | `message_type`, (中文(简体) ), `body` |
| `WasmSafetyNumber` | `displayable` (弦声), `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()` | 发送者密钥消息类型常数 |

## 虚拟配置

```typescript
// 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` 用于无头浏览器集成测试.

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

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

## 从源创建

```bash
# 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 — 见 [自由主义](https://npmcn.com/package/%40getmaapp/signal-wasm/LICENSE)

此软件包基于 [升号](https://github.com/signalapp/libsignal) v0.101.0 (承诺) [`b056faa6d`](https://github.com/signalapp/libsignal/commit/b056faa6dd02961cff24064c54c089c52e1a0753))由信号技术基金会提供.

## 免责声明

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

## 常见问题

### @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 和提交记录判断。

