befly 3.9.38 → 3.9.40

package/docs/cipher.md

@@ -2,6 +2,8 @@
 
 > 哈希、签名、密码加密与 JWT 令牌
 
+> 本文档已迁移到：[`./plugins/cipher.md`](./plugins/cipher.md)
+
 ## 目录
 
 - [概述](#概述)
@@ -37,7 +39,7 @@ Befly 提供两个安全相关的工具：
 ### 基本导入
 
 ```typescript
-import { Cipher } from '../lib/cipher.js';
+import { Cipher } from "../lib/cipher.js";
 ```
 
 ### 哈希算法
@@ -46,31 +48,31 @@ import { Cipher } from '../lib/cipher.js';
 
 ```typescript
 // 基本用法
-const hash = Cipher.md5('hello');
+const hash = Cipher.md5("hello");
 // '5d41402abc4b2a76b9719d911017c592'
 
 // 指定编码
-const hashBase64 = Cipher.md5('hello', 'base64');
+const hashBase64 = Cipher.md5("hello", "base64");
 ```
 
 #### SHA-1
 
 ```typescript
-const hash = Cipher.sha1('hello');
+const hash = Cipher.sha1("hello");
 // 'aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d'
 ```
 
 #### SHA-256
 
 ```typescript
-const hash = Cipher.sha256('hello');
+const hash = Cipher.sha256("hello");
 // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
 ```
 
 #### SHA-512
 
 ```typescript
-const hash = Cipher.sha512('hello');
+const hash = Cipher.sha512("hello");
 // '9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca...'
 ```
 
@@ -78,9 +80,9 @@ const hash = Cipher.sha512('hello');
 
 ```typescript
 // 支持多种算法
-const hash = Cipher.hash('sha256', 'hello');
-const hash2 = Cipher.hash('sha384', 'hello');
-const hash3 = Cipher.hash('blake2b256', 'hello');
+const hash = Cipher.hash("sha256", "hello");
+const hash2 = Cipher.hash("sha384", "hello");
+const hash3 = Cipher.hash("blake2b256", "hello");
 ```
 
 #### 支持的算法
@@ -108,22 +110,22 @@ const hash3 = Cipher.hash('blake2b256', 'hello');
 HMAC 使用密钥进行签名，用于数据完整性验证：
 
 ```typescript
-const key = 'my-secret-key';
+const key = "my-secret-key";
 
 // HMAC-MD5
-const sig1 = Cipher.hmacMd5(key, 'data');
+const sig1 = Cipher.hmacMd5(key, "data");
 
 // HMAC-SHA1
-const sig2 = Cipher.hmacSha1(key, 'data');
+const sig2 = Cipher.hmacSha1(key, "data");
 
 // HMAC-SHA256（推荐）
-const sig3 = Cipher.hmacSha256(key, 'data');
+const sig3 = Cipher.hmacSha256(key, "data");
 
 // HMAC-SHA512
-const sig4 = Cipher.hmacSha512(key, 'data');
+const sig4 = Cipher.hmacSha512(key, "data");
 
 // 通用 HMAC
-const sig5 = Cipher.hmac('sha256', key, 'data');
+const sig5 = Cipher.hmac("sha256", key, "data");
 ```
 
 #### RSA-SHA256 签名
@@ -135,9 +137,9 @@ const privateKey = `-----BEGIN PRIVATE KEY-----
 MIIEvQIBADANBg...
 -----END PRIVATE KEY-----`;
 
-const signature = Cipher.rsaSha256('data to sign', privateKey);
+const signature = Cipher.rsaSha256("data to sign", privateKey);
 // 或指定编码
-const signatureBase64 = Cipher.rsaSha256('data to sign', privateKey, 'base64');
+const signatureBase64 = Cipher.rsaSha256("data to sign", privateKey, "base64");
 ```
 
 ### 密码加密
@@ -148,17 +150,17 @@ const signatureBase64 = Cipher.rsaSha256('data to sign', privateKey, 'base64');
 
 ```typescript
 // 默认配置（推荐）
-const hash = await Cipher.hashPassword('123456');
+const hash = await Cipher.hashPassword("123456");
 // '$2b$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92...'
 
 // 自定义强度（cost 越高越安全但越慢）
-const hash2 = await Cipher.hashPassword('123456', { cost: 12 });
+const hash2 = await Cipher.hashPassword("123456", { cost: 12 });
 ```
 
 #### 验证密码
 
 ```typescript
-const isValid = await Cipher.verifyPassword('123456', storedHash);
+const isValid = await Cipher.verifyPassword("123456", storedHash);
 if (isValid) {
     // 密码正确
 }
@@ -182,11 +184,11 @@ if (isValid) {
 
 ```typescript
 // 编码
-const encoded = Cipher.base64Encode('hello');
+const encoded = Cipher.base64Encode("hello");
 // 'aGVsbG8='
 
 // 解码
-const decoded = Cipher.base64Decode('aGVsbG8=');
+const decoded = Cipher.base64Decode("aGVsbG8=");
 // 'hello'
 ```
 
@@ -202,19 +204,19 @@ const random = Cipher.randomString(32);
 
 ```typescript
 // 计算文件哈希（异步）
-const fileHash = await Cipher.hashFile('/path/to/file.txt');
+const fileHash = await Cipher.hashFile("/path/to/file.txt");
 // 默认 SHA-256
 
 // 指定算法
-const md5Hash = await Cipher.hashFile('/path/to/file.txt', 'md5');
+const md5Hash = await Cipher.hashFile("/path/to/file.txt", "md5");
 ```
 
 #### 快速哈希（非密码学）
 
 ```typescript
 // 高性能哈希，用于数据指纹、去重等
-const hash = Cipher.fastHash('data');
-const hashWithSeed = Cipher.fastHash('data', 12345);
+const hash = Cipher.fastHash("data");
+const hashWithSeed = Cipher.fastHash("data", 12345);
 ```
 
 ---
@@ -226,12 +228,12 @@ JWT (JSON Web Token) 用于用户认证和 API 授权。
 ### 基本导入
 
 ```typescript
-import { Jwt } from '../lib/jwt.js';
+import { Jwt } from "../lib/jwt.js";
 
 const jwt = new Jwt({
-    secret: 'your-secret-key',
-    expiresIn: '7d',
-    algorithm: 'HS256'
+    secret: "your-secret-key",
+    expiresIn: "7d",
+    algorithm: "HS256"
 });
 ```
 
@@ -283,17 +285,17 @@ interface AuthConfig {
 
 ```typescript
 // 基本用法
-const token = jwt.sign({ userId: 123, role: 'admin' });
+const token = jwt.sign({ userId: 123, role: "admin" });
 
 // 自定义选项
 const token2 = jwt.sign(
     { userId: 123 },
     {
-        expiresIn: '1h',
-        issuer: 'my-app',
-        audience: 'users',
-        subject: 'auth',
-        jwtId: 'unique-id'
+        expiresIn: "1h",
+        issuer: "my-app",
+        audience: "users",
+        subject: "auth",
+        jwtId: "unique-id"
     }
 );
 ```
@@ -329,10 +331,10 @@ try {
 const payload = jwt.verify(token, {
     ignoreExpiration: false, // 是否忽略过期
     ignoreNotBefore: false, // 是否忽略 nbf
-    issuer: 'my-app', // 验证签发者
-    audience: 'users', // 验证受众
-    subject: 'auth', // 验证主题
-    algorithms: ['HS256'] // 允许的算法
+    issuer: "my-app", // 验证签发者
+    audience: "users", // 验证受众
+    subject: "auth", // 验证主题
+    algorithms: ["HS256"] // 允许的算法
 });
 ```
 
@@ -361,11 +363,11 @@ console.log(decoded.signature); // 签名字符串
 ```typescript
 // 通过 befly 访问
 export default {
-    name: '示例接口',
+    name: "示例接口",
     handler: async (befly, ctx) => {
-        const hash = befly.cipher.sha256('data');
+        const hash = befly.cipher.sha256("data");
         const isValid = await befly.cipher.verifyPassword(password, storedHash);
-        return Yes('成功');
+        return Yes("成功");
     }
 } as ApiRoute;
 ```
@@ -375,7 +377,7 @@ export default {
 JWT 插件自动读取配置文件中的 `auth` 配置：
 
 ```json
-// befly.dev.json
+// befly.development.json
 {
     "auth": {
         "secret": "your-dev-secret",
@@ -388,12 +390,12 @@ JWT 插件自动读取配置文件中的 `auth` 配置：
 ```typescript
 // 通过 befly 访问
 export default {
-    name: '登录',
+    name: "登录",
     auth: false,
     handler: async (befly, ctx) => {
         // 签发令牌
         const token = befly.jwt.sign({ userId: user.id, role: user.role });
-        return Yes('登录成功', { token: token });
+        return Yes("登录成功", { token: token });
     }
 } as ApiRoute;
 ```
@@ -406,27 +408,27 @@ export default {
 
 ```typescript
 export default {
-    name: '用户注册',
+    name: "用户注册",
     auth: false,
     fields: {
-        email: { name: '邮箱', type: 'string', regexp: '@email' },
-        password: { name: '密码', type: 'string', min: 6, max: 100 }
+        email: { name: "邮箱", type: "string", regexp: "@email" },
+        password: { name: "密码", type: "string", min: 6, max: 100 }
     },
-    required: ['email', 'password'],
+    required: ["email", "password"],
     handler: async (befly, ctx) => {
         // 加密密码
         const hashedPassword = await befly.cipher.hashPassword(ctx.body.password);
 
         // 存储用户
         await befly.db.insData({
-            table: 'user',
+            table: "user",
             data: {
                 email: ctx.body.email,
                 password: hashedPassword
             }
         });
 
-        return Yes('注册成功');
+        return Yes("注册成功");
     }
 } as ApiRoute;
 ```
@@ -435,29 +437,29 @@ export default {
 
 ```typescript
 export default {
-    name: '用户登录',
+    name: "用户登录",
     auth: false,
     fields: {
-        email: { name: '邮箱', type: 'string', regexp: '@email' },
-        password: { name: '密码', type: 'string', min: 6, max: 100 }
+        email: { name: "邮箱", type: "string", regexp: "@email" },
+        password: { name: "密码", type: "string", min: 6, max: 100 }
     },
-    required: ['email', 'password'],
+    required: ["email", "password"],
     handler: async (befly, ctx) => {
         // 查询用户
         const user = await befly.db.getDetail({
-            table: 'user',
-            columns: ['id', 'email', 'password', 'role'],
+            table: "user",
+            columns: ["id", "email", "password", "role"],
             where: { email: ctx.body.email }
         });
 
         if (!user?.id) {
-            return No('用户不存在');
+            return No("用户不存在");
         }
 
         // 验证密码
         const isValid = await befly.cipher.verifyPassword(ctx.body.password, user.password);
         if (!isValid) {
-            return No('密码错误');
+            return No("密码错误");
         }
 
         // 签发令牌
@@ -466,7 +468,7 @@ export default {
             role: user.role
         });
 
-        return Yes('登录成功', { token: token });
+        return Yes("登录成功", { token: token });
     }
 } as ApiRoute;
 ```
@@ -475,25 +477,25 @@ export default {
 
 ```typescript
 export default {
-    name: '第三方回调',
+    name: "第三方回调",
     auth: false,
     handler: async (befly, ctx) => {
         const { data, signature, timestamp } = ctx.body;
 
         // 验证时间戳（5分钟内有效）
         if (Date.now() - timestamp > 5 * 60 * 1000) {
-            return No('请求已过期');
+            return No("请求已过期");
         }
 
         // 验证签名
-        const expectedSig = befly.cipher.hmacSha256('api-secret-key', `${data}${timestamp}`);
+        const expectedSig = befly.cipher.hmacSha256("api-secret-key", `${data}${timestamp}`);
 
         if (signature !== expectedSig) {
-            return No('签名验证失败');
+            return No("签名验证失败");
         }
 
         // 处理业务逻辑
-        return Yes('验证成功');
+        return Yes("验证成功");
     }
 } as ApiRoute;
 ```
@@ -502,7 +504,7 @@ export default {
 
 ```typescript
 export default {
-    name: '上传文件',
+    name: "上传文件",
     handler: async (befly, ctx) => {
         const { filePath, expectedHash } = ctx.body;
 
@@ -510,10 +512,10 @@ export default {
         const actualHash = await befly.cipher.hashFile(filePath);
 
         if (actualHash !== expectedHash) {
-            return No('文件校验失败');
+            return No("文件校验失败");
         }
 
-        return Yes('文件校验通过');
+        return Yes("文件校验通过");
     }
 } as ApiRoute;
 ```