@kne/fastify-signature 1.0.3 → 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',
@@ -27,6 +32,7 @@ module.exports = fp(async (fastify, options) => {
             filter: {
               type: 'object',
               additionalProperties: true,
+              description: '筛选条件',
               properties: {
                 keyword: { type: 'string', description: '关键字（AppId/描述/所属用户）' },
                 appId: { type: 'string', description: 'AppId' },
@@ -34,7 +40,8 @@ module.exports = fp(async (fastify, options) => {
               }
             }
           }
-        }
+        },
+        response: success('密钥分页列表', pageResult('密钥', secret))
       }
     },
     async request => {
@@ -47,7 +54,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: [userAuth, adminAuth],
       schema: {
-        description: '创建密钥',
+        tags: [ADMIN_TAG],
+        description: '生成一对 AppId / 密钥，密钥明文只在创建时返回一次',
         summary: '创建密钥',
         body: {
           type: 'object',
@@ -55,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 => {
@@ -70,7 +88,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: [userAuth, adminAuth],
       schema: {
-        description: '删除密钥',
+        tags: [ADMIN_TAG],
+        description: '删除密钥，删除后该 AppId 无法再通过验签；AppId 不存在时报错',
         summary: '删除密钥',
         body: {
           type: 'object',
@@ -80,7 +99,8 @@ module.exports = fp(async (fastify, options) => {
               description: '密钥ID'
             }
           }
-        }
+        },
+        response: empty('删除成功')
       }
     },
     async request => {
@@ -94,7 +114,8 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: [userAuth, adminAuth],
       schema: {
-        description: '更新密钥',
+        tags: [ADMIN_TAG],
+        description: '修改密钥状态与描述，未传的字段保持原值；AppId 不存在时报错',
         summary: '更新密钥',
         body: {
           type: 'object',
@@ -105,14 +126,15 @@ module.exports = fp(async (fastify, options) => {
             },
             status: {
               type: 'number',
-              description: '密钥状态'
+              description: `密钥${STATUS}`
             },
             description: {
               type: 'string',
               description: '描述'
             }
           }
-        }
+        },
+        response: empty('更新成功')
       }
     },
     async request => {
@@ -125,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',
@@ -136,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/package.json

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