# auth3.0 分支整改记录

> 日期：2026-07-15
> 分支：auth3.0（基于 V7.1.2 双连接器架构，保留区块链 + 游戏云兼容）

---

## 一、背景：版本演进回顾

由于年代久远，最初同时兼容游戏连接器和区块链连接器的架构在后续版本中发生了重大变化。通过 Git 历史梳理三个关键版本：

| 版本 | Commit | 日期 | 架构 |
|------|--------|------|------|
| V6.0.6 | `1c9fabd` | 2021-07-03 | 双连接器（`toolkit.conn` + `toolkit.gameconn`），工具函数在 index.js 统一挂载 |
| V7.1.2 | `f5ba0e3` | 2023-11-14 | 工具函数内聚到各模块，引入本地 socket.io 兼容浏览器，OpenSSL 兼容 |
| V8.0.8 | `d80155e` | 2024-02-03 | 合并为单一 Remote 类，删除区块链连接器，支持 HTTPS/URL |

**auth3.0 分支的定位**：基于 V7.1.2，保留双连接器架构（同时支持 `toolkit.conn` 区块链全节点 + `toolkit.gameconn` 游戏云），并进行安全性现代化改造。

---

## 二、仓库与分支管理

### Git 仓库
- **Gitee**（主）：`https://gitee.com/bianque/gamegoldtoolkit.git`
- **GitHub**（镜像）：`https://github.com/bookmansoft/gamegoldtoolkit`

### 分支操作
- 删除本地 `auth2.0` 分支（指向 `d80155e` V8.0.8，未合并，强制删除）
- 推送 `auth3.0` 到远端 `origin/auth3.0`，设置跟踪

---

## 三、安全改造：elliptic → @noble/secp256k1

### 问题
`elliptic` 存在安全漏洞 [GHSA-848j-6mx2-7j84](https://github.com/advisories/GHSA-848j-6mx2-7j84)（ECDSA 密码学原语风险实现），且截至 2026-01 无修复版本。原有 `elliptic` 作为生产依赖被 `secp256k1.js` → `verifyData.js`/`secret.js` → `index.js` 链式引用，用于签名、验签、ECDH 密钥交换。

### 方案
用 `@noble/secp256k1` v1 + `@noble/hashes` v1（CJS 兼容）完全替换 `elliptic`。

### 改动的文件

| 文件 | 操作 |
|------|------|
| `src/utils/secp256k1.js` | **重写** — 15 个导出函数用 noble API 重新实现，保持 Buffer 输入/输出兼容 |
| `package.json` | 移除 `elliptic`，新增 `@noble/secp256k1@^1.7.2` + `@noble/hashes@^1.8.0` |

### API 映射（关键差异）

| 旧 elliptic API | 新 noble API | 注意事项 |
|---|---|---|
| `elliptic.ec('secp256k1')` | `require('@noble/secp256k1')` | 需配置 `utils.hmacSha256Sync` |
| `.sign()` + `.toDER()` | `secp.signSync()` | noble v1 默认返回 DER 格式 |
| `ecdh(pub, priv)` | `getSharedSecret(priv, pub)` | 参数顺序**相反**，需提取 x 坐标 `[1,33)` |
| `verify(msg, sig, key)` | `verify(sig, msg, key)` | 参数顺序**不同**（sig 和 msg 交换） |
| `bn.js` 大数运算 | 原生 `BigInt` | 不再需要 `bn.js` 模块 |
| `Signature.fromDER()` | `Signature.fromDER(hex)` | noble 接受 hex 字符串非 Buffer |

### 验证

新增 `test/utils/secp256k1.js`，45 个测试用例全覆盖：

| 测试类别 | 数量 | 覆盖 |
|----------|------|------|
| 密钥生成 | 6 | `generatePrivateKey`, `privateKeyVerify` |
| 公钥操作 | 8 | `publicKeyCreate`, `publicKeyConvert`, `publicKeyVerify`（含 known-vector `priv=1`） |
| 签名与验证 | 8 | `sign`, `verify`，RFC 6979 确定性签名，篡改/错误密钥检测 |
| DER 转换 | 5 | `fromDER`, `toDER`, `isLowS` |
| ECDH | 3 | 双方一致性，长度验证 |
| 公钥恢复 | 2 | `recover` |
| Tweak | 2 | `privateKeyTweakAdd`, `publicKeyTweakAdd` |
| 上层集成 | 6 | `verifyData.generateKey/signObj/verifyObj`, `Secret` BIP151 握手 |

---

## 四、依赖安全审计：53 → 2 漏洞

### 修复前（53 个漏洞）

| 来源 | 数量 | 严重度 | 根因 |
|------|------|--------|------|
| babel 6.x 全家桶 | ~34 | critical | `babel-core`/`babel-traverse` 废弃 |
| elliptic（webpack 间接） | ~2 | critical | webpack4 的 `crypto-browserify` 链 |
| braces/micromatch | ~14 | low-moderate | webpack-cli 间接依赖 |
| json5 / serialize-javascript | ~3 | high | babel-loader / mocha 间接依赖 |

### 措施

| 操作 | 效果 |
|------|------|
| 删除 babel 全家桶（`babel`, `babel-core`, `babel-loader`, `babel-preset-*`） | 消除 34 个 critical |
| webpack 4 → 5，webpack-cli 3 → 5 | 消除 14 个 low/moderate |
| elliptic → `@noble/secp256k1` | 消除运行时 elliptic 风险 |
| 新增 `hash.js` 为直接依赖（原为 babel 间接依赖） | 修复 digest.js 的 `require('hash.js')` |
| 删除 `.babelrc` | 不再需要 |

### 修复后（2 个漏洞）

剩余 2 个漏洞均来自 mocha 测试框架的 `serialize-javascript` 间接依赖（仅用于 HTML 报告器），需 mocha 10→11 大版本升级才能消除（有破坏性变更风险，暂缓）。

---

## 五、Webpack 5 构建适配

### 问题

webpack 最初用于将项目打包成可在网页中通过 `<script>` 标签引入的单一 JS 文件。webpack 4 → 5 升级后有两个关键变化：
1. **不再自动 polyfill Node.js 核心模块**（`assert`, `buffer`, `crypto`, `stream`, `util`）
2. **默认输出格式变化**：从 IIFE 改为箭头函数，不再自动暴露 `module.exports`

### 最终 webpack.config.js

```js
const path = require('path');
const config = require('./package.json');

module.exports = {
  entry: './src/index.js',
  output: {
      path: path.resolve(__dirname, 'lib'),
      filename: `gamerpc${config.version}.js`,
      library: { name: 'toolkit', type: 'umd' },  // 兼容 <script> 和 require()
      globalObject: 'this',
  },
  target: 'web',
  mode: 'production',
  resolve: {
      fallback: {
          "assert": require.resolve("assert/"),
          "buffer": require.resolve("buffer/"),
          "crypto": require.resolve("crypto-browserify"),
          "stream": require.resolve("stream-browserify"),
          "util": require.resolve("util/"),
      }
  }
};
```

### 验证
- `npm run build` → `lib/gamerpc7.1.3.js`（398 KiB）
- 浏览器使用：`<script src="lib/gamerpc7.1.3.js"></script>` → `window.toolkit.xxx`
- Node.js 使用：`require('./src/')` 直接加载源码

---

## 六、其他修复

| 问题 | 修复 |
|------|------|
| `"main": "./lib/gamerpc7.1.2.js"` 指向不存在的文件 | 改为 `"main": "index.js"` |
| `hash.js` 缺失（原为 babel 间接依赖） | 新增为直接依赖 `"hash.js": "^1.1.7"` |
| Build 命令过于复杂 | 简化为 `"build": "npx webpack --mode=production"` |

---

## 七、当前 package.json 依赖

```json
{
  "dependencies": {
    "@noble/hashes": "^1.8.0",
    "@noble/secp256k1": "^1.7.2",
    "create-hmac": "1.1.7",
    "hash.js": "^1.1.7",
    "socket.io-client": "^4.7.2"
  },
  "devDependencies": {
    "cross-env": "^5.2.1",
    "mocha": "^10.2.0",
    "webpack": "^5.88.0",
    "webpack-cli": "^5.1.4"
  }
}
```

生产依赖仅 6 个，开发依赖 4 个，极度精简。

---

## 八、验证清单

- [x] `npm test` — 45 个单元测试全部通过
- [x] `npm run build` — 成功生成 `lib/gamerpc7.1.3.js`
- [x] `npm audit` — 仅剩 2 个 devDependencies 漏洞（测试工具链，不影响生产）
- [x] 双连接器导出正常（`toolkit.conn` + `toolkit.gameconn`）
- [x] 加密功能完整（签名、验签、ECDH、公钥恢复）
- [x] 浏览器打包产物 UMD 格式正确