# 微信小程序「API 接口安全」（数字签名）指导手册

> 对应获证地址：`developers.weixin.qq.com/miniprogram/dev/server/getting_started/api_signature.html`
> 配套文件：本目录 `key/` 下的三个密钥文件（**切勿提交到 git，已忽略**）。

---

## 一、这份文档究竟是干嘛的？

微信小程序服务端在调用微信的**敏感开放接口**（如获取 `access_token`、订阅消息、手机号快速验证、
用户信息等）时，传统做法是「AppSecret + IP 白名单」。这套 **API 数字签名**是微信新推出的
**更强的接口调用安全机制**，做到两层防护：

1. **内容加密** —— 请求/响应体用对称密钥加密，网络上不再是明文 JSON，防泄漏。
2. **签名验签** —— 双方互相信任消息「确实来自对方、且未被篡改」，具备**不可否认性**。

一句话：**它让你的服务器调用微信接口时，不依赖 IP 白名单也能安全、防篡改。**

适用场景：服务器 IP 不固定（云函数/CDN/多地域）时，比维护 IP 白名单更省心；以及需要更高安全等级的敏感接口。

---

## 二、你拿到的三个密钥分别是什么、有什么用

你的三件套（`key/` 目录），经核对是 **AES-256-GCM 对称加密 + RSA 签名**的组合：

| 文件 | 实际类型 | 作用 |
|---|---|---|
| **对称密钥.txt** | base64 编码的 **256-bit AES key**（`AES-256-GCM`） | **加密请求/响应正文** |
| **非对称密钥.txt** | **RSA 私钥**（`BEGIN RSA PRIVATE KEY`） | **对请求签名**（`RSAwithSHA256` PSS），证明请求来自你 |
| **开放平台证书.cer** | 微信**平台公钥证书**（`BEGIN CERTIFICATE`） | **验签微信的回包**，确认回包来自微信且未被改 |

补充：

- **验证签名用的「应用公钥」**：在 MP 后台生成密钥对时，花生处会显示公钥字段，**需要把应用公钥填回配置框上传**，微信用它验证你发的请求签名。你的 `非对称密钥.txt` 是私钥（自留），公钥不在此文件中。
- **三个「编号（Sn）」**：对称密钥编号、非对称密钥编号、证书编号都在 MP 后台「API 安全」页面查看/记录，**不在密钥文件里**，请单独保存，后续算法和请求头需要用到。

---

## 三、算法与签名步骤

### 3.1 对称加密（加密请求正文）

- 算法：`AES-256-GCM`（你的 key 取 `对称密钥.txt` 的 base64 解码）。
- 明文构成：把原始业务字段合并上三个安全字段后 JSON 序列化：
  - `_n`：随机串（随机数）
  - `_appid`：你的小程序 AppID
  - `_timestamp`：与请求头 `Wechatmp-TimeStamp` 一致的统一时间戳（毫秒）
- GCM 附加认证数据（AAD）：`urlpath|appid|timestamp|sn`（竖线分隔）。
- 输出三个 base64 字段：`iv`（12 字节随机）、`data`（密文）、`authtag`（认证标签）。
- 加密后的请求体 JSON（即下文签名用的 `postdata`）形如：
  ```json
  {"_version": 1, "_appid": "...", "_timestamp": 1760000000000, "_sn": "密钥编号", "iv": "...", "data": "...", "authtag": "..."}
  ```

### 3.2 RSA 签名（对加密后的请求签名）

- 算法：`RSAwithSHA256`，**PSS 填充**，salt 长度 **32**。
- 拼接待签名串，字段之间用 `\n` 连接，**末尾无多余换行**：

  ```
  urlpath\nappid\ntimestamp\npostdata
  ```

  其中：
  - `urlpath` = **带 `https://` 的完整接口路径，不含 Query**，例如
    `https://api.weixin.qq.com/wxa/business/getuserphonenumber`；
  - `appid` = 小程序 AppID；
  - `timestamp` = 同上传到密文 `_timestamp` 的值（毫秒）；
  - `postdata` = 第一步加密后的请求体 JSON 字符串。
- 用你的 `非对称密钥.txt`（RSA 私钥）对上述字符串签名，结果 base64。

### 3.3 请求头

把下面的值放到 HTTP 请求头：

```
Wechatmp-AppId:     <小程序 appid>
Wechatmp-TimeStamp: <timestamp>
Wechatmp-Signature: <base64 的 RSA 签名>
```

请求体 `Content-Type: application/json`，body 就是加密后的 JSON。

### 3.4 验签微信回包

- 回包头带 `Wechatmp-Serial`（新证书编号）与 `Wechatmp-Signature`。
- 用 `开放平台证书.cer` 里的平台公钥验签（同样 `RSAwithSHA256` PSS），确认无误后再用对称密钥解密响应正文（算法与加密一致）。
- 若响应头出现 `Wechatmp-Serial-Deprecated` 且与你证书号匹配，说明平台证书即将过期，需及时在 MP 后台更新。

---

## 四、在 MP 后台如何配置（拿这三件套）

路径：`mp.weixin.qq.com` → 「开发」→「开发管理」→「开发设置」→「**API 安全**」→ 管理员微信扫码验证。

1. **对称密钥**：点「随机生成密钥」→「下载密钥」→「确认」。得到 key（`对称密钥.txt`）与编号。
2. **非对称密钥**：点「随机生成密钥对」→「下载私钥」（`非对称密钥.txt`）自留 → 把**公钥**填入输入框上传 →「确认」。
3. **平台证书**：配置好应用公钥后，页面下载「开放平台证书」（`开放平台证书.cer`）。
4. 记录三个**编号（Sn）**，妥善保管（尤其私钥与大对称密钥）。

---

## 五、在项目里如何开发（集成参考）

本仓库当前 `wechat.service.ts` 用的是传统 AppSecret 直连（`code2Session`）。调用**敏感接口**时可按本机制
新增一个「签名 + 加密」请求封装。以下为可参考的 Node.js/TS 实现蓝图（基于 `node:crypto`，无需新依赖）：

```ts
import { createCipheriv, createSign, createVerify, constants } from 'node:crypto';
import axios from 'axios';

// 配置：从 ConfigService / env 读取，切勿硬编码
const CFG = {
  appid: process.env.WX_APPID,
  // 对称密钥（base64）
  symmetricKey: process.env.WX_API_SYMMETRIC_KEY,   // 对应 对称密钥.txt
  symmetricSn: process.env.WX_API_SYMMETRIC_SN,     // 编号 Sn
  // RSA 私钥（PEM 字符串）
  privateKey: process.env.WX_API_PRIVATE_KEY,       // 对应 非对称密钥.txt
  privateSn: process.env.WX_API_SN,                 // 非对称密钥编号
  // 平台证书（PEM），用于回包验签
  platformCert: process.env.WX_PLATFORM_CERT,       // 对应 开放平台证书.cer
};

function sha256PssSign(privateKeyPem: string, message: string): string {
  const sign = createSign('RSA-SHA256');
  sign.update(message, 'utf8');
  // PSS + saltLength 32
  const sig = sign.sign({ key: privateKeyPem, padding: constants.RSA_PKCS1_PSS_PADDING, saltLength: 32 });
  return sig.toString('base64');
}

/** 加密请求体 -> 返回 { body, signature, timestamp } */
function encryptAndSign(data: object, urlpath: string, now: number) {
  const key = Buffer.from(CFG.symmetricKey, 'base64');
  const iv = require('crypto').randomBytes(12);
  const cipher = createCipheriv('aes-256-gcm', key, iv);

  // 明文：业务字段 + _n/_appid/_timestamp
  const plain = JSON.stringify({ ...data, _n: Math.random().toString(36).slice(2), _appid: CFG.appid, _timestamp: now });

  // AAD = urlpath|appid|timestamp|sn
  cipher.setAAD(Buffer.from(`${urlpath}|${CFG.appid}|${now}|${CFG.symmetricSn}`));
  const enc = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
  const body = JSON.stringify({
    _version: 1, _appid: CFG.appid, _timestamp: now, _sn: CFG.symmetricSn,
    iv: iv.toString('base64'), data: enc.toString('base64'), authtag: cipher.getAuthTag().toString('base64'),
  });

  // 待签名串 urlpath\nappid\ntimestamp\npostdata
  const toSign = `${urlpath}\n${CFG.appid}\n${now}\n${body}`;
  const signature = sha256PssSign(CFG.privateKey, toSign);
  return { body, signature, timestamp: now };
}

/** 调用示例：微信「获取用户手机号」类敏感接口 */
async function callWechatApi(urlpath: string, payload: object) {
  const now = Date.now();
  const { body, signature, timestamp } = encryptAndSign(payload, urlpath, now);
  const { data } = await axios.post(urlpath, body, {
    headers: {
      'Content-Type': 'application/json',
      'Wechatmp-AppId': CFG.appid,
      'Wechatmp-TimeStamp': String(timestamp),
      'Wechatmp-Signature': signature,
    },
  });
  return data; // 注意：还需按第四节用平台证书验签 + 对称解密后再取用
}
```

> 说明：`axios` 已在依赖中；`node:crypto` 为 Node 内置，无需安装。正式落地时把这个封装挪进
> `src/wechat/`（如 `src/wechat/api-signature.ts`），配置项接入 `.env`。

---

## 六、注意事项（务必读）

1. **私钥/对称密钥绝不硬编码、绝不进 git**。本手册代码中的 `process.env.*` 即为此；`key/` 已被 `.gitignore` 忽略。
2. **编号（Sn）要单独记录**：文件里只有密钥本身，三个编号在 MP 后台「API 安全」页查看，算法和后续轮换都要用。
3. **部分接口不支持加密**：文档明确「资源上传类 API 暂不支持加密」，且**并非所有接口都要求**这套签名。调用前先看目标接口文档，确认它走哪套鉴权（AppSecret 直连 or 数字签名）。
4. **登录接口 `jscode2session` 当前不走这套签名**，保持现有 AppSecret 直连即可（已实现）。
5. 签名结果每次不同（PSS 含随机因子），属正常。
6. **证书过期**：关注 `Wechatmp-Serial-Deprecated` 响应头，过期前到 MP 后台更新平台证书。
7. 文档示例代码里的密钥是演示用的，不能用。

---

## 七、接入本仓库的待办清单（可按需推进）

- [ ] 在 `.env.example` 增加 `WX_API_SYMMETRIC_KEY / WX_API_SYMMETRIC_SN / WX_API_PRIVATE_KEY / WX_API_SN / WX_PLATFORM_CERT` 占位
- [ ] `src/wechat/` 新增 `api-signature.ts` 封装（按第五节蓝图，含回包验签 + 解密）
- [ ] 用真实小程序 AppID 调通一个敏感接口的加解密全链路
- [ ] 若长期大量调用，考虑把对称密钥/私钥换成环境变量注入（而非文件），并做密钥轮换流程