@kne/fastify-signature 1.0.2 → 1.0.4

package/libs/controllers/main.js

@@ -1,4 +1,8 @@
 const fp = require('fastify-plugin');
+const { str, bool, any, success, empty, pageResult, STATUS, secret } = require('../schema/response');
+
+const ADMIN_TAG = '签名管理后台-密钥';
+const TAG = '签名-验签';
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify[options.name];
@@ -9,7 +13,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: [userAuth, adminAuth],
       schema: {
-        description: '获取密钥列表',
+        tags: [ADMIN_TAG],
+        description: '分页查询全部用户的密钥，按创建时间倒序；密钥只返回脱敏值',
         summary: '获取密钥列表',
         query: {
           type: 'object',
@@ -23,9 +28,20 @@ module.exports = fp(async (fastify, options) => {
               type: 'number',
               description: '每页数量',
               default: 20
+            },
+            filter: {
+              type: 'object',
+              additionalProperties: true,
+              description: '筛选条件',
+              properties: {
+                keyword: { type: 'string', description: '关键字（AppId/描述/所属用户）' },
+                appId: { type: 'string', description: 'AppId' },
+                status: { description: '状态: 0开启，1禁用' }
+              }
             }
           }
-        }
+        },
+        response: success('密钥分页列表', pageResult('密钥', secret))
       }
     },
     async request => {
@@ -38,7 +54,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: [userAuth, adminAuth],
       schema: {
-        description: '创建密钥',
+        tags: [ADMIN_TAG],
+        description: '生成一对 AppId / 密钥，密钥明文只在创建时返回一次',
         summary: '创建密钥',
         body: {
           type: 'object',
@@ -46,9 +63,19 @@ module.exports = fp(async (fastify, options) => {
             description: {
               type: 'string',
               description: '描述'
+            },
+            userId: {
+              description: '密钥所属用户 ID，不传为当前登录用户；验签通过后以该用户身份访问开放接口'
             }
           }
-        }
+        },
+        response: success('创建的密钥', {
+          type: 'object',
+          properties: {
+            appId: str('AppId'),
+            secretKey: str('密钥明文，只返回这一次')
+          }
+        })
       }
     },
     async request => {
@@ -61,7 +88,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: [userAuth, adminAuth],
       schema: {
-        description: '删除密钥',
+        tags: [ADMIN_TAG],
+        description: '删除密钥，删除后该 AppId 无法再通过验签；AppId 不存在时报错',
         summary: '删除密钥',
         body: {
           type: 'object',
@@ -71,7 +99,8 @@ module.exports = fp(async (fastify, options) => {
               description: '密钥ID'
             }
           }
-        }
+        },
+        response: empty('删除成功')
       }
     },
     async request => {
@@ -85,7 +114,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: [userAuth, adminAuth],
       schema: {
-        description: '更新密钥',
+        tags: [ADMIN_TAG],
+        description: '修改密钥状态与描述，未传的字段保持原值；AppId 不存在时报错',
         summary: '更新密钥',
         body: {
           type: 'object',
@@ -96,14 +126,15 @@ module.exports = fp(async (fastify, options) => {
             },
             status: {
               type: 'number',
-              description: '密钥状态'
+              description: `密钥${STATUS}`
             },
             description: {
               type: 'string',
               description: '描述'
             }
           }
-        }
+        },
+        response: empty('更新成功')
       }
     },
     async request => {
@@ -116,7 +147,8 @@ module.exports = fp(async (fastify, options) => {
     `${options.prefix}/verify`,
     {
       schema: {
-        description: '验证密钥',
+        tags: [TAG],
+        description: '免登录。按 HMAC-SHA256(`${appId}|${timestamp}|${expire}`, 密钥) 校验签名，通过后记录最后访问时间；签名错误或过期返回 result=false，AppId 不存在时报错',
         summary: '验证密钥',
         body: {
           type: 'object',
@@ -127,18 +159,26 @@ module.exports = fp(async (fastify, options) => {
             },
             timestamp: {
               type: 'number',
-              description: '时间戳'
+              description: '签名时的时间戳（秒）'
             },
             signature: {
               type: 'string',
-              description: '签名'
+              description: '签名（hex）'
             },
             expire: {
               type: 'number',
-              description: '过期时间'
+              description: '过期时间戳（秒），当前时间超过即验签失败'
             }
           }
-        }
+        },
+        response: success('验签结果', {
+          type: 'object',
+          properties: {
+            result: bool('是否通过验签'),
+            message: str('结果说明'),
+            userId: any('密钥所属用户 ID，仅通过验签时返回')
+          }
+        })
       }
     },
     async request => {

package/libs/schema/response.js

@@ -0,0 +1,39 @@
+// 响应 schema 会参与 fast-json-stringify 序列化：对象一律 additionalProperties: true 以免裁掉未声明字段；
+// 用 nullable 而非类型数组（类型数组遇到不匹配的值会直接 500），类型不确定的字段（如外键 id、日期）只写说明不声明类型
+const str = description => ({ type: 'string', nullable: true, description });
+const num = description => ({ type: 'number', nullable: true, description });
+const bool = description => ({ type: 'boolean', nullable: true, description });
+const any = description => ({ description });
+const list = (description, items) => ({ type: 'array', nullable: true, description, items });
+const obj = (description, properties = {}) => ({ type: 'object', nullable: true, description, additionalProperties: true, properties });
+
+const success = (description, schema) => ({
+  200: Object.assign({}, schema || { type: 'object' }, { description })
+});
+
+const empty = (description = '操作成功，返回空对象') => success(description);
+
+const pageResult = (description, item) => ({
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    pageData: list(`当前页${description}列表`, item),
+    totalCount: num('符合条件的总条数')
+  }
+});
+
+const STATUS = '状态：0 开启，1 禁用';
+
+const secret = obj('密钥', {
+  id: str('密钥 ID（同 appId）'),
+  appId: str('AppId，即密钥 ID'),
+  secretKey: str('脱敏后的密钥，只保留首尾各 3 位'),
+  user: any('所属用户，未关联到用户时为 null'),
+  description: str('描述'),
+  lastVisitedAt: any('最后一次验签成功的时间'),
+  status: num(STATUS),
+  createdAt: any('创建时间'),
+  updatedAt: any('更新时间')
+});
+
+module.exports = { str, num, bool, any, list, obj, success, empty, pageResult, STATUS, secret };

package/libs/services/main.js

@@ -3,16 +3,27 @@ const crypto = require('crypto');
 
 module.exports = fp(async (fastify, options) => {
   const { models, services } = fastify[options.name];
+  const { Op } = fastify.sequelize.Sequelize;
+
+  const escapeLike = value => String(value).replace(/[\\%_]/g, '\\$&');
+
+  const resolveAppId = appId => {
+    if (appId == null || appId === '') {
+      throw new Error('Invalid appId');
+    }
+    // 雪花 id 超过 Number.MAX_SAFE_INTEGER，必须始终按字符串查，禁止 Number(appId)
+    return String(appId);
+  };
 
   const create = async (authenticatePayload, { description, userId: targetUserId }) => {
     const { id: userId } = authenticatePayload;
     const secretKey = crypto.randomBytes(options.secretLength).toString('hex');
     const newSecret = await models.secret.create({ secretKey, description, userId: targetUserId || userId });
-    return { appId: newSecret.id, secretKey: newSecret.secretKey };
+    return { appId: String(newSecret.id), secretKey: newSecret.secretKey };
   };
 
   const verify = async ({ appId, timestamp, expire, signature }) => {
-    const secret = await models.secret.findByPk(appId);
+    const secret = await models.secret.findByPk(resolveAppId(appId));
     if (!secret) {
       throw new Error('Invalid appId');
     }
@@ -47,19 +58,49 @@ module.exports = fp(async (fastify, options) => {
     };
   };
 
-  const list = async (authenticatePayload, { perPage, currentPage }) => {
-    const { id: userId } = authenticatePayload;
+  const list = async (authenticatePayload, { perPage = 20, currentPage = 1, filter }) => {
+    filter = Object.assign({}, filter);
+    const whereQuery = {};
+    const sequelize = fastify.sequelize;
+    const castIdLike = value =>
+      sequelize.where(sequelize.cast(sequelize.col('secret.id'), 'TEXT'), {
+        [Op.iLike]: `%${escapeLike(value)}%`
+      });
+
+    const keyword = filter.keyword != null ? String(filter.keyword).trim() : '';
+    if (keyword) {
+      const like = { [Op.iLike]: `%${escapeLike(keyword)}%` };
+      whereQuery[Op.or] = [castIdLike(keyword), { description: like }, { '$user.nickname$': like }, { '$user.email$': like }, { '$user.phone$': like }];
+    }
+
+    const appId = filter.appId != null ? String(filter.appId).trim() : '';
+    if (appId) {
+      whereQuery[Op.and] = [...(whereQuery[Op.and] || []), castIdLike(appId)];
+    }
+
+    if (filter.status !== undefined && filter.status !== null && filter.status !== '') {
+      whereQuery.status = Number(filter.status);
+    }
+
     const { count, rows } = await models.secret.findAndCountAll({
-      include: options.getUserModel(),
-      where: {},
+      include: [
+        {
+          model: options.getUserModel(),
+          required: false
+        }
+      ],
+      where: whereQuery,
       limit: perPage,
-      offset: (currentPage - 1) * perPage
+      offset: (currentPage - 1) * perPage,
+      order: [['createdAt', 'DESC']],
+      distinct: true
     });
     return {
       pageData: rows.map(item => {
+        const id = String(item.id);
         return {
-          id: item.id,
-          appId: item.id,
+          id,
+          appId: id,
           secretKey: item.secretKey.substring(0, 3) + '*'.repeat(8) + item.secretKey.substring(item.secretKey.length - 3),
           user: item.user,
           description: item.description,
@@ -73,27 +114,20 @@ module.exports = fp(async (fastify, options) => {
     };
   };
 
+  // list/update/remove 均为 admin 接口，可管理任意用户密钥；勿再按创建者校验归属
   const remove = async (authenticatePayload, { appId }) => {
-    const { id: userId } = authenticatePayload;
-    const secret = await models.secret.findByPk(appId);
+    const secret = await models.secret.findByPk(resolveAppId(appId));
     if (!secret) {
       throw new Error('Invalid appId');
     }
-    if (secret.userId !== userId) {
-      throw new Error('Invalid appId');
-    }
     await secret.destroy();
   };
 
   const update = async (authenticatePayload, { appId, status, description }) => {
-    const { id: userId } = authenticatePayload;
-    const secret = await models.secret.findByPk(appId);
+    const secret = await models.secret.findByPk(resolveAppId(appId));
     if (!secret) {
       throw new Error('Invalid appId');
     }
-    if (secret.userId !== userId) {
-      throw new Error('Invalid appId');
-    }
     await secret.update({ status, description });
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-signature",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "用于实现一个签名和验证算法",
   "main": "index.js",
   "scripts": {