@blueking/bkui-knowledge 0.0.1-beta.1

package/knowledge/skills/nodejs-security-check/references/security-toolkit.md

@@ -0,0 +1,426 @@
+# Node.js 安全工具库
+
+可复用的安全函数模板，基于腾讯 Node.js 代码安全规范。
+
+## 使用方式
+
+创建 `src/utils/security.js` 文件，将以下函数引入项目使用。
+
+## 完整工具库代码
+
+```javascript
+/**
+ * Node.js 安全工具库 - 基于腾讯 Node.js 代码安全规范
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import dns from 'node:dns/promises';
+import net from 'node:net';
+import crypto from 'node:crypto';
+
+// ============= 路径安全 =============
+
+/**
+ * 安全解析文件路径（防路径穿越）
+ */
+export async function resolveSafe(root, userPath) {
+  const abs = path.resolve(root, userPath);
+  const real = await fs.realpath(path.dirname(abs)).then(d => path.join(d, path.basename(abs)));
+  if (!real.startsWith(root + path.sep)) {
+    throw new Error('path escape detected');
+  }
+  return real;
+}
+
+/**
+ * 安全读取文件
+ */
+export async function safeReadFile(root, userPath, options = {}) {
+  const safePath = await resolveSafe(root, userPath);
+  return fs.readFile(safePath, options);
+}
+
+/**
+ * 安全写入文件
+ */
+export async function safeWriteFile(root, userPath, data, options = {}) {
+  const safePath = await resolveSafe(root, userPath);
+  return fs.writeFile(safePath, data, options);
+}
+
+// ============= SSRF 防护 =============
+
+/**
+ * 检查 IP 是否为私网地址
+ */
+export function isPrivateIP(ip) {
+  if (net.isIPv4(ip)) {
+    const n = ip.split('.').map(Number);
+    const v = (n[0]<<24)|(n[1]<<16)|(n[2]<<8)|n[3];
+    const inRange = (a,b) => v>=a && v<=b;
+    return (
+      inRange(0x0A000000,0x0AFFFFFF) ||      // 10.0.0.0/8
+      inRange(0xAC100000,0xAC1FFFFF) ||      // 172.16.0.0/12
+      inRange(0xC0A80000,0xC0A8FFFF) ||      // 192.168.0.0/16
+      inRange(0x7F000000,0x7FFFFFFF) ||      // 127.0.0.0/8
+      inRange(0xA9FE0000,0xA9FEFFFF) ||      // 169.254.0.0/16
+      ip === '169.254.169.254'               // 云元数据
+    );
+  }
+  return ip === '::1' || ip.startsWith('fe80:');
+}
+
+/**
+ * 验证 URL 是否安全（非私网）
+ */
+export async function assertPublicHost(urlStr) {
+  const url = new URL(urlStr);
+  if (!['http:','https:'].includes(url.protocol)) {
+    throw new Error('protocol not allowed');
+  }
+  const addrs = await dns.lookup(url.hostname, { all: true });
+  if (addrs.some(a => isPrivateIP(a.address))) {
+    throw new Error('private address blocked');
+  }
+  return url;
+}
+
+/**
+ * 安全的 HTTP 请求（防 SSRF）
+ */
+export async function safeFetch(urlStr, options = {}) {
+  const { timeoutMs = 8000, maxRedirects = 3, ...init } = options;
+  let url = await assertPublicHost(urlStr);
+  let redirectCount = 0;
+  
+  while (redirectCount++ <= maxRedirects) {
+    const ctrl = new AbortController();
+    const timeout = setTimeout(() => ctrl.abort(), timeoutMs);
+    
+    try {
+      const res = await fetch(url, { ...init, signal: ctrl.signal, redirect: 'manual' });
+      clearTimeout(timeout);
+      
+      if ([301,302,303,307,308].includes(res.status)) {
+        const location = res.headers.get('location');
+        if (!location) break;
+        url = await assertPublicHost(new URL(location, url).toString());
+        continue;
+      }
+      return res;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  throw new Error('too many redirects');
+}
+
+// ============= NoSQL 安全 =============
+
+const FORBIDDEN_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+const NOSQL_OPERATORS = /^[$.]|\.[$]/;
+
+/**
+ * 清洗对象（防 NoSQL 注入 + 原型污染）
+ */
+export function sanitizeObject(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+  
+  for (const key of Object.keys(obj)) {
+    if (FORBIDDEN_KEYS.has(key) || NOSQL_OPERATORS.test(key)) {
+      delete obj[key];
+    } else if (typeof obj[key] === 'object') {
+      sanitizeObject(obj[key]);
+    }
+  }
+  return obj;
+}
+
+/**
+ * 安全对象合并（防原型污染）
+ */
+export function safeMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    if (FORBIDDEN_KEYS.has(key)) continue;
+    
+    const value = source[key];
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      if (!target[key] || typeof target[key] !== 'object') {
+        target[key] = {};
+      }
+      safeMerge(target[key], value);
+    } else {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+/**
+ * 字段白名单过滤
+ */
+export function pickFields(obj, allowedFields) {
+  const result = {};
+  for (const field of allowedFields) {
+    if (Object.prototype.hasOwnProperty.call(obj, field)) {
+      result[field] = obj[field];
+    }
+  }
+  return result;
+}
+
+// ============= Header 安全 =============
+
+/**
+ * 清理 Header 值（防 CRLF 注入）
+ */
+export function sanitizeHeaderValue(value) {
+  return String(value).replace(/[\r\n]/g, ' ');
+}
+
+/**
+ * 安全设置响应头
+ */
+export function safeSetHeader(res, name, value) {
+  res.setHeader(name, sanitizeHeaderValue(value));
+}
+
+// ============= 加密安全 =============
+
+/**
+ * 常量时间字符串比较
+ */
+export function timingSafeEqual(a, b) {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) return false;
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * 生成安全随机字符串
+ */
+export function secureRandomString(length = 32) {
+  return crypto.randomBytes(length).toString('hex');
+}
+
+/**
+ * 生成安全会话 ID
+ */
+export function generateSessionId() {
+  return crypto.randomBytes(32).toString('base64url');
+}
+
+/**
+ * HMAC 签名
+ */
+export function hmacSign(secret, data) {
+  return crypto.createHmac('sha256', secret).update(data).digest('hex');
+}
+
+/**
+ * HMAC 验证（常量时间）
+ */
+export function hmacVerify(secret, data, signature) {
+  const expected = hmacSign(secret, data);
+  return timingSafeEqual(expected, signature);
+}
+
+// ============= Webhook 验签 =============
+
+/**
+ * 验证 Webhook 签名
+ */
+export function verifyWebhookSignature(payload, signature, secret, timestamp, maxAgeSeconds = 300) {
+  // 时间窗校验
+  const ts = parseInt(timestamp, 10);
+  if (isNaN(ts) || Math.abs(Date.now() / 1000 - ts) > maxAgeSeconds) {
+    return false;
+  }
+  
+  // 签名验证
+  const base = `${timestamp}.${payload}`;
+  return hmacVerify(secret, base, signature);
+}
+
+// ============= 日志脱敏 =============
+
+const SENSITIVE_KEYS = ['password', 'token', 'secret', 'authorization', 'cookie', 'apikey', 'credential'];
+
+/**
+ * 日志脱敏
+ */
+export function sanitizeForLog(obj, depth = 0) {
+  if (depth > 10) return '[MAX_DEPTH]';
+  if (!obj || typeof obj !== 'object') return obj;
+  
+  const result = Array.isArray(obj) ? [] : {};
+  for (const [key, value] of Object.entries(obj)) {
+    const lowerKey = key.toLowerCase();
+    if (SENSITIVE_KEYS.some(s => lowerKey.includes(s))) {
+      result[key] = '***REDACTED***';
+    } else if (typeof value === 'object' && value !== null) {
+      result[key] = sanitizeForLog(value, depth + 1);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// ============= URL 安全 =============
+
+const SENSITIVE_PARAMS = ['token', 'auth', 'session', 'sig', 'code', 'state', 'password'];
+
+/**
+ * 移除 URL 中的敏感参数
+ */
+export function stripSensitiveParams(urlStr) {
+  try {
+    const url = new URL(urlStr);
+    SENSITIVE_PARAMS.forEach(param => url.searchParams.delete(param));
+    return url.toString();
+  } catch {
+    return urlStr;
+  }
+}
+
+// ============= 重定向安全 =============
+
+const ALLOWED_REDIRECT_HOSTS = ['qq.com', 'tencent.com']; // 根据项目配置
+
+/**
+ * 安全重定向
+ */
+export function safeRedirect(res, url, defaultUrl = '/') {
+  try {
+    const u = new URL(url, 'http://localhost');
+    
+    // 只允许相对路径或白名单域名
+    const isRelative = url.startsWith('/') && !url.startsWith('//');
+    const isAllowedHost = ALLOWED_REDIRECT_HOSTS.some(h =>
+      u.hostname === h || u.hostname.endsWith('.' + h)
+    );
+    
+    if (isRelative || (u.protocol === 'https:' && isAllowedHost)) {
+      res.redirect(url);
+    } else {
+      res.redirect(defaultUrl);
+    }
+  } catch {
+    res.redirect(defaultUrl);
+  }
+}
+
+// ============= Cookie 安全 =============
+
+/**
+ * 安全设置 Cookie
+ */
+export function safeSetCookie(res, name, value, options = {}) {
+  const defaults = {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/'
+  };
+  res.cookie(name, value, { ...defaults, ...options });
+}
+
+// ============= SQL 安全 =============
+
+/**
+ * LIKE 查询转义
+ */
+export function escapeLike(str) {
+  return String(str).replace(/[%_\\]/g, '\\$&');
+}
+
+/**
+ * 字段名白名单
+ */
+export function validateOrderField(field, allowedFields, defaultField = 'created_at') {
+  return allowedFields.includes(field) ? field : defaultField;
+}
+
+/**
+ * 排序方向白名单
+ */
+export function validateOrderDirection(dir) {
+  return dir?.toLowerCase() === 'asc' ? 'ASC' : 'DESC';
+}
+```
+
+## Express 中间件封装
+
+```javascript
+// src/middlewares/security.js
+import { sanitizeObject, sanitizeForLog } from '@/utils/security';
+
+/**
+ * 请求体清洗中间件
+ */
+export function sanitizeBody(req, res, next) {
+  if (req.body && typeof req.body === 'object') {
+    sanitizeObject(req.body);
+  }
+  next();
+}
+
+/**
+ * 请求日志中间件（脱敏）
+ */
+export function requestLogger(logger) {
+  return (req, res, next) => {
+    logger.info({
+      method: req.method,
+      path: req.path,
+      query: sanitizeForLog(req.query),
+      body: sanitizeForLog(req.body)
+    });
+    next();
+  };
+}
+```
+
+## 依赖安装
+
+```bash
+# 推荐的安全相关依赖
+npm install helmet              # 安全响应头
+npm install express-rate-limit  # 限速
+npm install ajv                 # Schema 验证
+npm install jose                # JWT 处理
+npm install pino                # 结构化日志
+```
+
+## .npmrc 配置
+
+```bash
+# 使用内网镜像源
+registry=https://mirrors.tencent.com/npm/
+strict-ssl=true
+ignore-scripts=true
+fund=false
+audit=false
+```
+
+## CI 安全检查
+
+```bash
+# 使用 lockfile 安装
+npm ci
+
+# 或 pnpm
+pnpm install --frozen-lockfile
+
+# 依赖漏洞扫描
+npm audit --production
+```
+
+---
+
+> 相关资源：
+> - 完整规则清单：`skill://nodejs-security-check/references/checklist.md`
+> - 修复示例：`skill://nodejs-security-check/references/fix-examples.md`

package/knowledge/skills/permission-directive/SKILL.md

@@ -0,0 +1,51 @@
+---
+id: eng-permission-auth
+name: 前端权限控制方案 (IAM)
+category: engineering
+description: 基于蓝鲸 IAM 的前端鉴权方案，包含 v-authority 指令实现、权限组件封装及无权限交互规范。
+tags: [iam, permission, authority, directive, vue3]
+updated_at: 2026-01-09
+---
+
+# 前端权限控制方案 (IAM)
+
+在蓝鲸体系中，权限控制不仅仅是“显示/隐藏”，更重要的是**“发现与申请”**。我们推荐使用**“置灰 + 提示申请”**的交互模式。
+
+## 1. 核心指令 `v-authority`
+
+这个指令会自动处理点击拦截、样式置灰和申请弹窗的唤起。
+
+**使用方式：**
+```html
+<bk-button v-authority="{ permission: hasAuth, actionId: 'host_edit' }">
+  编辑
+</bk-button>
+```
+
+**指令功能：**
+- 有权限 → 正常交互
+- 无权限 → 置灰 + 点击触发申请弹窗 + Tooltip 提示
+
+> 📦 获取完整指令实现：`skill://permission-directive/assets/authority-directive.ts`
+
+## 2. 鉴权组件 `AuthButton`
+
+对于需要更多自定义的场景，可封装鉴权按钮组件。
+
+## 3. 路由级鉴权
+
+在 `vue-router` 的 `beforeEach` 中处理页面级权限。
+
+```typescript
+router.beforeEach(async (to, from, next) => {
+  const meta = to.meta as any;
+  if (meta.auth) {
+    const hasAuth = await checkPageAuth(meta.authAction);
+    if (!hasAuth) {
+      next({ name: '403', query: { action: meta.authAction } });
+      return;
+    }
+  }
+  next();
+});
+```

package/knowledge/skills/permission-directive/assets/authority-directive.ts

@@ -0,0 +1,104 @@
+/**
+ * v-authority 权限控制指令
+ *
+ * 用途：
+ * - 无权限时置灰元素
+ * - 点击触发权限申请弹窗
+ * - 显示无权限提示 Tooltip
+ *
+ * 使用示例：
+ * <bk-button v-authority="{ permission: hasAuth, actionId: 'host_edit' }">
+ *   编辑
+ * </bk-button>
+ */
+import { type Directive, type DirectiveBinding } from 'vue';
+
+interface AuthBinding {
+  /** 是否有权限 */
+  permission: boolean;
+  /** 权限动作ID (用于申请链接) */
+  actionId: string;
+  /** 资源ID (可选) */
+  resourceId?: string;
+}
+
+const vAuthority: Directive = {
+  mounted(el: HTMLElement, binding: DirectiveBinding<AuthBinding>) {
+    const { permission, actionId } = binding.value;
+    updateAuth(el, permission, actionId);
+  },
+  updated(el: HTMLElement, binding: DirectiveBinding<AuthBinding>) {
+    const { permission, actionId } = binding.value;
+    updateAuth(el, permission, actionId);
+  },
+  unmounted(el: HTMLElement) {
+    // 清理 tooltip
+    if ((el as any)._tippy) {
+      (el as any)._tippy.destroy();
+    }
+  }
+};
+
+function updateAuth(el: HTMLElement, permission: boolean, actionId: string) {
+  if (permission) {
+    // 有权限：恢复正常状态
+    el.classList.remove('is-disabled-auth');
+    el.style.pointerEvents = '';
+    el.style.opacity = '';
+    el.style.cursor = '';
+    // 移除 tooltip
+    if ((el as any)._tippy) {
+      (el as any)._tippy.destroy();
+    }
+    // 移除拦截器
+    (el as any)._authClickHandler = null;
+  } else {
+    // 无权限：置灰 + 拦截点击
+    el.classList.add('is-disabled-auth');
+    el.style.cursor = 'not-allowed';
+    el.style.opacity = '0.6';
+
+    // 拦截点击事件
+    const clickHandler = (e: MouseEvent) => {
+      e.stopImmediatePropagation();
+      e.preventDefault();
+      showApplyPermissionDialog(actionId);
+    };
+
+    // 存储 handler 以便清理
+    if ((el as any)._authClickHandler) {
+      el.removeEventListener('click', (el as any)._authClickHandler, true);
+    }
+    (el as any)._authClickHandler = clickHandler;
+    el.addEventListener('click', clickHandler, true);
+
+    // 添加 Tooltip 提示
+    el.setAttribute('data-bk-tooltips', '无权限，点击申请');
+  }
+}
+
+/**
+ * 唤起 IAM 权限申请弹窗
+ * 需要根据实际项目配置 IAM 申请 URL
+ */
+function showApplyPermissionDialog(actionId: string) {
+  // TODO: 替换为实际的 IAM 申请逻辑
+  const iamApplyUrl = `${window.location.origin}/iam/apply?action=${actionId}`;
+  console.log('[Authority] Redirect to IAM apply:', iamApplyUrl);
+
+  // 方式1: 跳转申请页
+  // window.open(iamApplyUrl, '_blank');
+
+  // 方式2: 使用 InfoBox 弹窗
+  // InfoBox({
+  //   title: '无权限',
+  //   subTitle: '您没有该操作的权限，是否前往申请？',
+  //   confirmText: '去申请',
+  //   onConfirm: () => window.open(iamApplyUrl, '_blank')
+  // });
+}
+
+export default vAuthority;
+
+// 注册指令（在 main.ts 中）
+// app.directive('authority', vAuthority);

package/knowledge/skills/pinia-setup/SKILL.md

@@ -0,0 +1,65 @@
+---
+id: eng-state-management
+name: 全局状态管理规范 (Pinia)
+category: engineering
+description: 基于 Pinia 的全局状态管理规范，包含 UserStore、AppStore 的标准定义
+tags: [pinia, store, state, vue3]
+updated_at: 2026-01-09
+---
+
+# 全局状态管理规范 (Pinia)
+
+推荐使用 **Setup Store** 语法（类似 Composition API），比 Options API 更灵活。
+
+## 基础模式
+
+```typescript
+// src/store/user.ts
+import { defineStore } from 'pinia';
+import { ref } from 'vue';
+
+export const useUserStore = defineStore('user', () => {
+  const userInfo = ref(null);
+  const loading = ref(false);
+
+  const fetchUserInfo = async () => {
+    if (userInfo.value) return userInfo.value;
+    loading.value = true;
+    try {
+      userInfo.value = await http.get('/user/info');
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  return { userInfo, loading, fetchUserInfo };
+});
+```
+
+## 组件中使用
+
+```typescript
+<script setup lang="ts">
+import { useUserStore } from '@/store/user';
+import { storeToRefs } from 'pinia';
+
+const userStore = useUserStore();
+// 使用 storeToRefs 保持响应性
+const { userInfo, loading } = storeToRefs(userStore);
+// Action 直接调用
+userStore.fetchUserInfo();
+</script>
+```
+
+## 常见错误
+
+| 错误 | 解决 |
+|------|------|
+| 解构丢失响应性 | 用 `storeToRefs()` |
+| 多次实例化 | Store 单例，直接 `useXxxStore()` |
+
+## 📦 按需加载资源
+
+| 资源 | URI |
+|-----|-----|
+| 完整 Store 模板 | `skill://pinia-setup/assets/store-template.ts` |