bigint-buffer-safe

安全、纯 JS 的 bigint-buffer 替代品。修复了 CVE-2025-3194（CVSS 7.5，缓冲区溢出/拒绝服务）。

零依赖。无原生绑定。适用于 Node.js 和浏览器。

为什么存在？

原始 bigint-buffer 包存在高危缓冲区溢出漏洞（CVE-2025-3194，CVSS 7.5），当传递 toBigIntLE(null) 或其他无效输入时会崩溃进程。维护者自 2019 年 10 月以来未发布更新。依赖它的 @solana/buffer-layout-utils 包已于 2025 年 1 月归档。上游修复无望。

该漏洞通过以下传递依赖链影响整个 Solana 生态系统：

bigint-buffer → @solana/buffer-layout-utils → @solana/web3.js v1.x → @solana/wallet-adapter-*

bigint-buffer-safe 是一个纯 JavaScript 替代品，具有正确的输入验证。API 与 [email protected] 兼容。

安装

npm install bigint-buffer-safe

Solana 项目的直接替换（推荐）

添加到你的 package.json 中以替换整个依赖树中的 bigint-buffer：

npm（v8.3+）：

{
  "overrides": {
    "bigint-buffer": "npm:bigint-buffer-safe@^1.0.0"
  }
}

yarn：

{
  "resolutions": {
    "bigint-buffer": "npm:bigint-buffer-safe@^1.0.0"
  }
}

pnpm：

{
  "pnpm": {
    "overrides": {
      "bigint-buffer": "npm:bigint-buffer-safe@^1.0.0"
    }
  }
}

直接使用 GitHub（如果尚未发布到 npm）：

{
  "overrides": {
    "bigint-buffer": "github:LoserLab/bigint-buffer-safe"
  }
}

然后重新安装：

rm -rf node_modules package-lock.json && npm install

验证漏洞已修复：

npm audit

API

与 [email protected] 完全相同：

import { toBigIntBE, toBigIntLE, toBufferBE, toBufferLE } from "bigint-buffer-safe";

// Buffer → BigInt
toBigIntBE(Buffer.from([0x01, 0x00])); // 256n
toBigIntLE(Buffer.from([0x00, 0x01])); // 256n

// BigInt → Buffer
toBufferBE(256n, 2); // <Buffer 01 00>
toBufferLE(256n, 2); // <Buffer 00 01>

与原版有何不同？

输入验证。 无效输入会抛出 TypeError，而不是崩溃进程：

// 原始 bigint-buffer：崩溃（CVE-2025-3194）
toBigIntLE(null);

// bigint-buffer-safe：抛出 TypeError
toBigIntLE(null); // TypeError: toBigIntLE: expected a Buffer, got null

无原生绑定。 原版包含 N-API C++ 绑定，在浏览器和打包工具中会静默失败（著名的 "bigint: Failed to load bindings" 警告）。此包是纯 JavaScript。

基准测试

纯 JS，无原生绑定。在 Apple Silicon（M 系列）Node.js 上测试，各 100 万次迭代。

对于 Solana 程序中使用的 u64 和 u128 整数（lamports、代币金额、时间戳）来说，性能足够。原版的 N-API 绑定在处理非常大的缓冲区时更快，但这些大小在 Solana 中并不使用。

自己运行基准测试：

npx tsx bench/index.ts

常见问题

谁受到影响？

任何使用 @solana/web3.js v1.x（版本 1.43.1 到 1.98.x）的项目。运行 npm ls bigint-buffer 检查是否在你的依赖树中。

这会影响 @solana/kit（web3.js v2）吗？

不会。@solana/kit 没有第三方依赖，也不使用 bigint-buffer。如果你已经迁移到 Kit，则不受影响。

那“bigint: Failed to load bindings”警告呢？

该警告来自 bigint-buffer 的原生 N-API 绑定在打包环境中加载失败。替换为 bigint-buffer-safe 即可消除，因为此包是纯 JavaScript。

这是永久修复吗？

这是一个桥接方案，适用于仍在使用 @solana/web3.js v1.x 的项目。永久解决方案是迁移到 @solana/kit，它没有外部依赖。

这与 bigint-buffer-fixed 有何不同？

bigint-buffer-fixed 是另一个社区分支。bigint-buffer-safe 彻底移除了原生 N-API 绑定（消除了“Failed to load bindings”警告），包含包含 64 个测试的完整测试套件，并提供了 TypeScript 类型定义。

长期修复

此包是适用于 @solana/web3.js v1.x 项目的桥接方案。永久解决方案是迁移到 @solana/kit（web3.js v2），它没有外部依赖，完全不使用 bigint-buffer。Solana 基金会还发布了 ConnectorKit（@solana/connector）作为钱包适配器生态系统的现代替代品，支持 v1/v2 双版本。

属于 Solana 迁移工具包

四个工具协同工作，帮助你的项目从 web3.js v1 迁移到 Kit v2：

推荐工作流程： solana-deps（找出遗留项） → solana-audit（检查漏洞） → solana-codemod（修复代码） → solana-audit（验证结果）。

作者

由 Heathen 创建

在 Mirra 中构建

许可证

MIT 许可证

版权所有 (c) 2026 Heathen