james-api-sign 1.0.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "james-api-sign",
+  "version": "1.0.0",
+  "description": "Axios request interceptor with HMAC-SHA256 API signing (X-Access-Key/X-Timestamp/X-Nonce/X-Sign), Bearer token and comid header injection. Zero-config by default, fully configurable.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "axios",
+    "interceptor",
+    "hmac",
+    "sha256",
+    "api-sign",
+    "signature",
+    "request-signing"
+  ],
+  "author": "james.xu",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "dependencies": {
+    "crypto-js": "^4.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * james-api-sign
+ * 开放接口 HMAC-SHA256 请求签名封装
+ *
+ * 使用：
+ *   import { applyApiSign } from 'james-api-sign'
+ *   // 在 axios 请求拦截器中调用
+ *   applyApiSign(config)
+ */
+export {
+  applyApiSign,
+  sha256HexUpper,
+  hmacSha256HexUpper,
+  randomNonce,
+  parseQueryString,
+  sortedQueryParams,
+  defaultSignOptions,
+} from './signer.js'

package/src/signer.js

@@ -0,0 +1,149 @@
+/**
+ * 开放接口 HMAC-SHA256 签名核心逻辑
+ * 与后端 ApiSignInterceptor 校验规则一一对应：
+ *
+ *   canonicalString = HTTP_METHOD + "\n"
+ *                   + requestPath(不含 context-path/query) + "\n"
+ *                   + sortedQueryParams("k=v" 按key字典序排序, & 连接) + "\n"
+ *                   + sha256Hex(requestBody) + "\n"
+ *                   + timestamp + "\n"
+ *                   + nonce
+ *   sign = hexUpper( HMAC-SHA256( accessSecret, canonicalString ) )
+ *
+ * 环境变量控制（包以 ESM 源码发布，VITE_* 会在使用方的 Vite 构建期被静态替换）：
+ *   VITE_API_SIGN_ENABLED   是否开启（默认 true，后端未开启时多发几个请求头无副作用）
+ *   VITE_API_ACCESS_KEY     访问标识（对应 PHARMACY_CONFIG.access_key）
+ *   VITE_API_ACCESS_SECRET  访问密钥
+ *
+ * james.xu 2026.09.14
+ */
+import CryptoJS from 'crypto-js'
+
+/** 读取使用方构建期注入的 Vite 环境变量；非 Vite 环境下返回 undefined */
+function readViteEnv(key) {
+  return typeof import.meta !== 'undefined' && import.meta.env ? import.meta.env[key] : undefined
+}
+
+/** 默认签名配置，优先级：调用方传参 > VITE_* 环境变量 > 内置默认值 */
+export const defaultSignOptions = {
+  enabled: (readViteEnv('VITE_API_SIGN_ENABLED') ?? 'true') !== 'false',
+  accessKey: readViteEnv('VITE_API_ACCESS_KEY') || '1301',
+  accessSecret: readViteEnv('VITE_API_ACCESS_SECRET') || 'Z1OGF13RJUA2LTCS599DQ6ZOB8W4JNL2',
+  contextPath: '/api/rxcp',
+}
+
+/** SHA-256 摘要，大写 hex；空内容返回空串（与后端约定一致） */
+export function sha256HexUpper(text) {
+  if (!text) return ''
+  return CryptoJS.SHA256(text).toString(CryptoJS.enc.Hex).toUpperCase()
+}
+
+/** HMAC-SHA256 签名，大写 hex */
+export function hmacSha256HexUpper(secret, content) {
+  return CryptoJS.HmacSHA256(content, secret).toString(CryptoJS.enc.Hex).toUpperCase()
+}
+
+/** 生成随机 nonce（32位hex） */
+export function randomNonce() {
+  return CryptoJS.lib.WordArray.random(16).toString(CryptoJS.enc.Hex)
+}
+
+/** 解析 url 中的 query 串为键值对（多值取第一个，与后端约定一致） */
+export function parseQueryString(queryString) {
+  const params = {}
+  if (!queryString) return params
+  queryString.split('&').forEach(pair => {
+    if (!pair) return
+    const idx = pair.indexOf('=')
+    const key = idx >= 0 ? pair.substring(0, idx) : pair
+    const value = idx >= 0 ? pair.substring(idx + 1) : ''
+    if (!(key in params)) {
+      params[decodeURIComponent(key)] = decodeURIComponent(value)
+    }
+  })
+  return params
+}
+
+/** query 参数按 key 字典序排序，以 k=v&k=v 形式拼接（与后端 HmacSignUtils 一致） */
+export function sortedQueryParams(params) {
+  const keys = Object.keys(params).sort()
+  const parts = []
+  keys.forEach(key => {
+    const value = params[key]
+    if (value === undefined || value === null) return
+    parts.push(`${key}=${Array.isArray(value) ? value[0] : value}`)
+  })
+  return parts.join('&')
+}
+
+/**
+ * 为 axios 请求配置追加签名请求头
+ * 仅处理 url 以 contextPath 开头的请求，其余请求原样返回
+ *
+ * 注意：POST/PUT 的 body 在此被序列化为字符串并写回 config.data，
+ * 保证签名摘要与实际发送的字节完全一致
+ *
+ * @param {object} axiosConfig axios 请求配置（会被原地修改）
+ * @param {object|boolean} [options] 签名配置；传 false 表示关闭签名
+ * @param {boolean} [options.enabled]
+ * @param {string} [options.accessKey]
+ * @param {string} [options.accessSecret]
+ * @param {string} [options.contextPath]
+ * @returns {object} 修改后的 axiosConfig
+ */
+export function applyApiSign(axiosConfig, options) {
+  if (options === false) return axiosConfig
+  const cfg = Object.assign({}, defaultSignOptions, options || {})
+  if (!cfg.enabled || !axiosConfig.url || !axiosConfig.url.startsWith(cfg.contextPath)) {
+    return axiosConfig
+  }
+
+  // 拆分 url 中的 path 与 query
+  const qIndex = axiosConfig.url.indexOf('?')
+  const fullPath = qIndex >= 0 ? axiosConfig.url.substring(0, qIndex) : axiosConfig.url
+  const urlQuery = qIndex >= 0 ? axiosConfig.url.substring(qIndex + 1) : ''
+
+  // 签名路径 = 请求路径去掉 context-path（与后端拦截器 resolveSignPath 一致）
+  const signPath = fullPath.startsWith(cfg.contextPath) ? fullPath.substring(cfg.contextPath.length) : fullPath
+
+  // 合并 url query 与 axios params（同名时 url 中的优先，仅影响签名，不影响实际发送）
+  const queryParams = Object.assign({}, parseQueryString(urlQuery))
+  if (axiosConfig.params) {
+    Object.keys(axiosConfig.params).forEach(key => {
+      if (!(key in queryParams)) {
+        queryParams[key] = axiosConfig.params[key]
+      }
+    })
+  }
+
+  // body 统一序列化为字符串，签名与发送使用同一份内容
+  let bodyText = ''
+  axiosConfig.headers = axiosConfig.headers || {}
+  if (axiosConfig.data !== undefined && axiosConfig.data !== null) {
+    bodyText = typeof axiosConfig.data === 'string' ? axiosConfig.data : JSON.stringify(axiosConfig.data)
+    axiosConfig.data = bodyText
+    // data 为字符串时 axios 默认会发 application/x-www-form-urlencoded，需显式指定 JSON
+    if (!axiosConfig.headers['Content-Type'] && !axiosConfig.headers['content-type']) {
+      axiosConfig.headers['Content-Type'] = 'application/json;charset=UTF-8'
+    }
+  }
+
+  const timestamp = Date.now()
+  const nonce = randomNonce()
+  const canonical = [
+    (axiosConfig.method || 'get').toUpperCase(),
+    signPath,
+    sortedQueryParams(queryParams),
+    sha256HexUpper(bodyText),
+    String(timestamp),
+    nonce,
+  ].join('\n')
+
+  const sign = hmacSha256HexUpper(cfg.accessSecret, canonical)
+
+  axiosConfig.headers['X-Access-Key'] = cfg.accessKey
+  axiosConfig.headers['X-Timestamp'] = String(timestamp)
+  axiosConfig.headers['X-Nonce'] = nonce
+  axiosConfig.headers['X-Sign'] = sign
+  return axiosConfig
+}