oms/backend/app/lib/wechatGateway.js
liufumingren 1847e17ba7 feat(auth): 接入微信扫码登录与微信绑定
- 新增网关客户端与通知验签(sha256(appSecret) 派生 HMAC-SHA256,5 分钟防重放),
  扫码会话与一次性结果存 Redis,openid 仅服务端保存
- 新增 user_wechat_binds 表与迁移:openid 唯一(一个微信只绑一个账号)、
  user_id 唯一(重新绑定覆盖旧微信)
- 新增 /api/auth/wechat/* 接口与 /api/wx/notify 网关回调;登录二维码按 IP 限流,
  未配置网关时相关接口返回 400 提示,不影响账号密码 / 邮箱验证码登录
- 前端:「微信登录」tab(二维码 + 倒计时 + 轮询)与「我的」页微信绑定 / 解绑
- 开发与生产各出一份 WX_GATEWAY_* 配置样板,生产权威副本走 shared-config 覆盖
- 同步补充 swagger 契约与请求日志脱敏字段(bind_code / sign)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-01 23:17:11 +08:00

348 lines
11 KiB
JavaScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
const crypto = require('crypto');
/**
* 微信登录网关(公众号网页静默授权)接入封装。
*
* 链路:后端申请临时码 → 前端把 pageUrl 渲染成二维码 → 用户用手机微信扫码确认
* → 网关带着签名 POST 到本系统的通知接口(/api/wx/notify)。
* 说明:
* 1. appKey / appSecret 只保存在服务端,任何情况下都不下发到前端;
* 2. 临时码一次性、扫码会话与通知结果都存在 Redis,过期即失效;
* 3. 通知必须校验签名与时间戳,签名密钥是 sha256(appSecret)(与网关约定一致)。
*/
/** Redis key 前缀(与 oms:email:* / oms:cache:* 区分) */
const PREFIX = 'oms:wx';
/** 扫码场景:登录 / 绑定 */
const SCENE_LOGIN = 'login';
const SCENE_BIND = 'bind';
/** 网关业务错误码 → 面向用户的提示 */
const GATEWAY_ERROR_MESSAGES = {
40005: '二维码或授权会话已失效,请刷新后重试',
40010: '绑定码不存在、已过期或已被使用',
40011: '绑定码已被使用',
40012: '临时码与绑定码不能混用',
40014: '二维码已失效,请刷新后重试',
40102: '微信网关未配置应用凭证(appKey / appSecret)',
40103: '微信网关应用凭证不正确,请检查 WX_GATEWAY_APP_KEY / WX_GATEWAY_APP_SECRET',
40301: '微信网关应用已停用,请联系管理员',
40302: '回调地址不在微信网关白名单内,请联系管理员',
40401: '微信网关应用不存在,请检查 WX_GATEWAY_APP_KEY',
};
/** 网关调用异常(status 为建议返回给前端的 HTTP 状态码) */
class WechatGatewayError extends Error {
/**
* @param {String} message 面向用户的提示
* @param {Number} status 建议的 HTTP 状态码
*/
constructor(message, status = 502) {
super(message);
this.name = 'WechatGatewayError';
this.status = status;
}
}
/**
* 取微信网关配置
* @param {Egg.Application} app egg application
* @return {Object} 微信网关配置
*/
function gatewayConfig(app) {
return app.config.wechatGateway || {};
}
/**
* 是否已配置微信网关(未配置时相关接口只提示配置,不影响其它登录方式)
* @param {Egg.Application} app egg application
* @return {Boolean} 是否可用
*/
function isEnabled(app) {
const cfg = gatewayConfig(app);
return Boolean(cfg.appKey && cfg.appSecret);
}
/**
* 取配置,未配置时抛出可直接返回给前端的异常
* @param {Egg.Application} app egg application
* @return {Object} 微信网关配置
*/
function requireConfig(app) {
const cfg = gatewayConfig(app);
if (!cfg.appKey || !cfg.appSecret) {
throw new WechatGatewayError('未配置微信登录网关,请先在服务端 .env 中填写 WX_GATEWAY_APP_KEY / WX_GATEWAY_APP_SECRET', 400);
}
return cfg;
}
/** @return {String} 一次性扫码会话标识(回传用,不包含任何业务信息) */
function newState() {
return crypto.randomBytes(16).toString('hex');
}
/** @param {String} state 扫描会话标识 @return {String} redis key */
function stateKey(state) {
return `${PREFIX}:state:${state}`;
}
/** @param {String} state 扫描会话标识 @return {String} redis key */
function loginKey(state) {
return `${PREFIX}:login:${state}`;
}
/** @param {String} state 扫描会话标识 @return {String} redis key */
function bindKey(state) {
return `${PREFIX}:bind:${state}`;
}
/**
* 公共扫码接口的限流 key(按场景 + IP 统计)
* @param {String} scope 场景
* @param {String} ip 客户端IP
* @return {String} redis key
*/
function rateLimitKey(scope, ip) {
return `${PREFIX}:limit:${scope}:${ip}`;
}
/**
* 判断是否超出频率限制(固定窗口计数,防止刷接口消耗网关临时码配额)
* @param {Egg.Application} app egg application
* @param {String} scope 场景
* @param {String} ip 客户端IP
* @param {Number} limit 窗口内允许的次数
* @param {Number} window 窗口秒数
* @return {Promise<Boolean>} true 表示已超限
*/
async function isRateLimited(app, scope, ip, limit, window) {
if (!(limit > 0)) return false;
const key = rateLimitKey(scope, ip);
const count = await app.redis.incr(key);
if (count === 1) await app.redis.expire(key, window > 0 ? window : 600);
return count > limit;
}
/**
* 写入扫码会话(scene + 发起人)
* @param {Egg.Application} app egg application
* @param {String} state 会话标识
* @param {Object} payload { scene, user_id }
* @return {Promise<void>} 无返回值
*/
async function saveState(app, state, payload) {
const { stateTtl } = gatewayConfig(app);
await app.redis.set(stateKey(state), JSON.stringify(payload), 'EX', stateTtl);
}
/**
* 读取扫码会话
* @param {Egg.Application} app egg application
* @param {String} state 会话标识
* @return {Promise<Object|null>} 会话内容,不存在或已过期返回 null
*/
async function readState(app, state) {
if (!state) return null;
const raw = await app.redis.get(stateKey(state));
if (!raw) return null;
try {
return JSON.parse(raw);
} catch {
return null;
}
}
/**
* 删除扫码会话
* @param {Egg.Application} app egg application
* @param {String} state 会话标识
* @return {Promise<void>} 无返回值
*/
async function clearState(app, state) {
await app.redis.del(stateKey(state));
}
/**
* 写入通知结果(登录成功 / 未绑定,绑定成功 / 冲突),供前端轮询取走
* @param {Egg.Application} app egg application
* @param {String} key redis key
* @param {Object} payload 结果内容
* @return {Promise<void>} 无返回值
*/
async function writeResult(app, key, payload) {
const { stateTtl } = gatewayConfig(app);
await app.redis.set(key, JSON.stringify(payload), 'EX', stateTtl);
}
/**
* 读取并清除通知结果(一次性,避免同一结果被重复兑换成登录态)
* @param {Egg.Application} app egg application
* @param {String} key redis key
* @return {Promise<Object|null>} 结果内容
*/
async function takeResult(app, key) {
const raw = await app.redis.get(key);
if (!raw) return null;
await app.redis.del(key);
try {
return JSON.parse(raw);
} catch {
return null;
}
}
/**
* 申请临时码(二维码内容由网关返回的 pageUrl 决定)
* @param {Egg.Application} app egg application
* @param {Object} options 申请参数
* @param {String} options.scene 场景:login 登录 / bind 绑定
* @param {String} options.state 扫码会话标识,网关会在通知里原样回传
* @return {Promise<Object>} 网关返回的临时码数据(tempCode / pageUrl / expiresIn …)
*/
async function createTempCode(app, { scene, state }) {
const cfg = requireConfig(app);
const url = `${cfg.baseUrl}/api/auth/temp-code`;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), cfg.timeout);
let resp;
let text = '';
try {
resp = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-App-Key': cfg.appKey,
'X-App-Secret': cfg.appSecret,
},
body: JSON.stringify({ scene, state }),
signal: controller.signal,
});
text = await resp.text();
} catch (err) {
const message = err.name === 'AbortError'
? '微信网关响应超时,请稍后重试'
: `微信网关请求失败:${err.message}`;
throw new WechatGatewayError(message);
} finally {
clearTimeout(timer);
}
let json;
try {
json = JSON.parse(text);
} catch {
throw new WechatGatewayError(`微信网关返回非 JSON 响应(HTTP ${resp.status})`);
}
if (json.code !== 0) {
const message = GATEWAY_ERROR_MESSAGES[json.code] || json.message || `微信网关返回错误码 ${json.code}`;
// 凭证类错误属于配置问题,按 400 返回,方便前端直接提示管理员检查配置
throw new WechatGatewayError(message, [ 40102, 40103, 40301, 40401 ].includes(json.code) ? 400 : 502);
}
const data = json.data || {};
if (!data.tempCode || !data.pageUrl) {
throw new WechatGatewayError('微信网关未返回可用的二维码地址');
}
return data;
}
/**
* 通知签名原文:appKey.userId.bindCode.timestamp.nonce(与网关保持一致,含 join 的隐式空串处理)
* @param {Object} body 通知报文
* @return {String} 待签名串
*/
function signMessage(body) {
return [ body.appKey, body.userId, body.bindCode, body.timestamp, body.nonce ].join('.');
}
/**
* 计算通知签名
* @param {String} appSecret 应用密钥
* @param {Object} body 通知报文
* @return {String} hex 签名
*/
function computeSign(appSecret, body) {
const secretHash = crypto.createHash('sha256').update(String(appSecret)).digest('hex');
return crypto.createHmac('sha256', secretHash).update(signMessage(body)).digest('hex');
}
/**
* 定长安全比较,避免签名比较泄露时序信息
* @param {String} a 字符串A
* @param {String} b 字符串B
* @return {Boolean} 是否相同
*/
function safeEqual(a, b) {
const bufA = Buffer.from(String(a || ''));
const bufB = Buffer.from(String(b || ''));
if (!bufA.length || bufA.length !== bufB.length) return false;
return crypto.timingSafeEqual(bufA, bufB);
}
/**
* 校验网关通知:应用标识 + 签名 + 时间戳(防重放)
* @param {Egg.Application} app egg application
* @param {Object} body 通知报文
* @param {Object} headers 请求头
* @return {Object} { ok, message }
*/
function verifyNotify(app, body, headers = {}) {
const cfg = requireConfig(app);
if (body.appKey !== cfg.appKey) return { ok: false, message: '通知的应用标识不匹配' };
const timestamp = Number(body.timestamp);
if (!timestamp || Math.abs(Date.now() - timestamp) > cfg.notifyTolerance) {
return { ok: false, message: '通知已过期' };
}
const expected = computeSign(cfg.appSecret, body);
if (!safeEqual(expected, body.sign)) return { ok: false, message: '通知签名校验失败' };
const headerSign = headers['x-gateway-signature'];
if (headerSign && !safeEqual(expected, headerSign)) return { ok: false, message: '通知签名校验失败' };
return { ok: true, message: '' };
}
/**
* openid 脱敏展示(只保留首尾,避免完整标识出现在页面与日志中)
* @param {String} openid 微信 openid
* @return {String} 脱敏后的 openid
*/
function maskOpenid(openid) {
const value = String(openid || '');
if (value.length <= 10) return value ? `${value.slice(0, 2)}****` : '';
return `${value.slice(0, 6)}****${value.slice(-4)}`;
}
module.exports = {
SCENE_LOGIN,
SCENE_BIND,
WechatGatewayError,
gatewayConfig,
isEnabled,
requireConfig,
newState,
stateKey,
loginKey,
bindKey,
rateLimitKey,
isRateLimited,
saveState,
readState,
clearState,
writeResult,
takeResult,
createTempCode,
computeSign,
verifyNotify,
maskOpenid,
};