dotexorg/saferpc

# 安全的 RPC [](https://www.npmjs.com/package/@dotex/saferpc) [](./LICENSE) [](https://www.typescriptlang.org/) **在任何双向通道上进行加密的、类型安全的 RPC。** 两个对等端，一个共享密钥（或一个密钥对）。每次调用都使用 XSalsa20-Poly1305 AEAD 进行端到端加密。WebSocket、`postMessage`、`MessagePort`、`chrome.runtime`、`BroadcastChannel`、WebRTC —— 只要通道能传输字节，Safe RPC 就能加密其中的数据流并保证其类型安全。 可以看作是 tRPC，但与传输层无关，且默认加密。 ``` npm install @dotex/saferpc ```  - **完整文档与设计初衷：** - [快速开始](./spec/getting-started.md) · [API](./spec/api.md) · [通信协议](./spec/protocol.md) · [安全性](./spec/security.md) · [传输层](./spec/integrations.md) ## 特性 - **类型化过程**，使用 Zod 进行输入/输出验证 - **端到端加密。** 采用 X25519 ECDH、XSalsa20-Poly1305 AEAD、HKDF-SHA-256，设计上支持前向保密 - **惰性握手**，在首次调用时进行。会话断开时透明地自动重试 - **三种认证模式：** 预共享密钥、非对称认证（Ed25519 / ECDSA / JWT / 证书 / 多因素认证），或同时使用两者以实现纵深防御 - **同步的** `client()` 和 `server()`。可运行于 Node.js、浏览器、Service Workers、React Native、Vercel Edge、Cloudflare Workers、Deno Deploy - **极简依赖。** 仅包含 `@noble/*` 加密库、`@msgpack/msgpack`、`zod`，别无其他 - **纯 ESM + CJS 双构建**，无副作用，支持 tree-shaking ## 快速开始 ``` import { chain, server, client } from "@dotex/saferpc"; import { z } from "zod"; const d = chain(); const router = { greet: d .input(z.object({ name: z.string() })) .output(z.object({ message: z.string() })) .handler(async ({ input }) => ({ message: `Hello, ${input.name}!`, })), }; const secret = crypto.getRandomValues(new Uint8Array(32)); const auth = { secret: () => secret }; const { destroy: stopServer } = server(router, serverChannel, { auth }); const { api, destroy: stopClient } = client(clientChannel, { auth }); const { message } = await api.greet({ name: "World" }); ``` `client()` 和 `server()` 均为同步操作。无需顶层 `await`。握手会在首次过程调用时惰性执行。如果会话断开，下一次调用会使用全新的握手重试一次。 ## Channel：唯一的传输层契约 ``` interface Channel { send(data: Uint8Array): void | Promise; receive(cb: (data: Uint8Array) => void): () => void; // returns unsubscribe } ``` 任何满足此接口的对象都可以承载 Safe RPC 会话。适用于 WebSocket、`postMessage`、`MessagePort`、Chrome 扩展端口、`BroadcastChannel`、WebRTC、TCP 和 SSE 的现成适配器均位于 [spec/integrations.md](./spec/integrations.md) 中。 ## 身份验证 三种模式。这三种模式下的 `auth` 代码块结构完全相同。 ``` // Secret only. Simple, fast, controlled environments. auth: { secret: () => sharedSecret } // Asymmetric only. Public clients, no shared secrets. auth: { sign: (transcript) => signWithDeviceKey(transcript), verify: (proof, transcript) => verifyPeerSignature(proof, transcript), } // Both. Session binding plus identity proof. auth: { secret: () => deriveSessionSecret(sessionId, deploymentSecret), sign: (transcript) => signWithDeviceKey(transcript), verify: (proof, transcript) => verifyPeerSignature(proof, transcript), } ``` 内置辅助工具支持 Ed25519、ECDSA P-256、JWT、基于证书以及多因素身份验证。所有方式都将其验证凭证与握手记录绑定，因此被截获的 payload 无法在新的会话中重放。完整的威胁模型位于 [spec/security.md](./spec/security.md) 中。 ## 错误处理 ``` import { RPCError, RemoteRPCError } from "@dotex/saferpc"; try { await api.greet({ name: "World" }); } catch (err) { if (err instanceof RemoteRPCError) { // The remote peer threw. err.code / err.message / err.data come from there. } else if (err instanceof RPCError) { // Local failure: TIMEOUT, SESSION, HANDSHAKE, INPUT_VALIDATION, ... } else { throw err; } } ``` ## 包结构 ``` src/ common.ts : shared types, crypto, msgpack, chain builder server.ts : resilient handshake server client.ts : lazy handshake client with auto-retry auth/ index.ts : combined re-exports (deriveSessionSecret + client + server) client.ts : Ed25519, ECDSA, JWT client helpers server.ts : Ed25519, ECDSA, JWT, certificate, multifactor server helpers index.ts : public entry point ``` ``` import { chain, server, client, RPCError } from "@dotex/saferpc"; // Subpaths are also available for tree-shaking: import { server } from "@dotex/saferpc/server"; import { client } from "@dotex/saferpc/client"; import { chain, RPCError } from "@dotex/saferpc/common"; // Auth helpers: combined or split per side import { createEd25519ClientAuth, createEd25519ServerAuth } from "@dotex/saferpc/auth"; import { createEd25519ClientAuth } from "@dotex/saferpc/auth/client"; import { createEd25519ServerAuth } from "@dotex/saferpc/auth/server"; ``` ## 兼容性 Node.js 18+、现代浏览器、Service / Web / Shared Workers、React Native、Vercel Edge、Cloudflare Workers、Deno Deploy。仅在需要使用 ECDSA 和证书辅助工具时，才要求环境具备 WebCrypto 支持。 ## 项目状态 当前为 `0.x` 版本，具有稳定的通信协议（`saferpc-v1` HKDF info，`saferpc-hs-{hello,reply}-v1` 记录前缀）。针对握手攻击、重放攻击、篡改、类型混淆、原型污染、中间件滥用以及 DoS 限制的测试覆盖位于 `test/security/` 目录下。1.0 版本将锁定公开的 API 接口。 ## 发布 只需一条命令即可提升版本号、发布到 npm 并推送标签： ``` npm version patch # or: minor / major / 1.2.3-beta.0 ``` `prepublishOnly` 会在发布前运行 lint、测试和构建。随后 `postversion` 钩子将运行 `npm publish && git push --follow-tags。被推送的 `vX.Y.Z` 标签会触发 `.github/workflows/release.yml`，该工作流会验证版本已在 npm 上线，并根据自上一个标签以来的记录，使用自动生成的更新日志创建一个 GitHub Release。 如果 `npm publish` 失败，标签仅存在于本地而不会被推送。修复问题后重新运行 `npm publish && git push --follow-tags` 即可。若要中止操作，请运行 `git tag -d vX.Y.Z && git reset --hard HEAD~1`。 ## 许可证 MIT © [Dotex](https://dotex.org/about)

标签：RPC框架, TypeScript, 安全插件, 数据加密, 端到端加密, 自动化攻击, 跨平台通信