@blueking/bkui-knowledge 0.0.1-beta.1 → 0.0.1-beta.11

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/vue-directive-comments.md

@@ -0,0 +1,73 @@
+---
+title: Vue Template Directive Comments
+impact: HIGH
+impactDescription: enables fine-grained control over template type checking
+type: capability
+tags: vue-directive, vue-ignore, vue-expect-error, vue-skip, template, type-checking
+---
+
+# Vue Template Directive Comments
+
+**Impact: HIGH** - enables fine-grained control over template type checking
+
+Vue Language Tools supports special directive comments to control type checking behavior in templates.
+
+## Available Directives
+
+### @vue-ignore
+
+Suppress type errors for the next line:
+
+```vue
+<template>
+  <!-- @vue-ignore -->
+  <Component :prop="valueWithTypeError" />
+</template>
+```
+
+### @vue-expect-error
+
+Assert that the next line should have a type error (useful for testing):
+
+```vue
+<template>
+  <!-- @vue-expect-error -->
+  <Component :invalid-prop="value" />
+</template>
+```
+
+### @vue-skip
+
+Skip type checking for an entire block:
+
+```vue
+<template>
+  <!-- @vue-skip -->
+  <div>
+    <!-- Everything in here is not type-checked -->
+    <LegacyComponent :any="props" :go="here" />
+  </div>
+</template>
+```
+
+### @vue-generic
+
+Declare template-level generic types:
+
+```vue
+<template>
+  <!-- @vue-generic {T extends string} -->
+  <GenericList :items="items as T[]" />
+</template>
+```
+
+## Use Cases
+
+- Migrating legacy components with incomplete types
+- Working with third-party components that have incorrect type definitions
+- Temporarily suppressing errors during refactoring
+- Testing that certain patterns produce expected type errors
+
+## Reference
+
+- [Vue Language Tools Wiki - Directive Comments](https://github.com/vuejs/language-tools/wiki/Directive-Comments)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/vue-router-typed-params.md

@@ -0,0 +1,81 @@
+---
+title: Vue Router useRoute Params Union Type Narrowing
+impact: MEDIUM
+impactDescription: fixes "Property does not exist" errors with typed route params
+type: capability
+tags: vue-router, useRoute, unplugin-vue-router, typed-routes, params
+---
+
+# Vue Router useRoute Params Union Type Narrowing
+
+**Impact: MEDIUM** - fixes "Property does not exist" errors with typed route params
+
+With `unplugin-vue-router` typed routes, `route.params` becomes a union of ALL page param types. TypeScript cannot narrow `Record<never, never> | { id: string }` properly, causing "Property 'id' does not exist" errors even on the correct page.
+
+## Symptoms
+
+- "Property 'id' does not exist on type 'RouteParams'"
+- `route.params.id` shows as `string | undefined` everywhere
+- Union type of all route params instead of specific route
+- Type narrowing with `if (route.name === 'users-id')` doesn't work
+
+## Root Cause
+
+`unplugin-vue-router` generates a union type of all possible route params. TypeScript's control flow analysis can't narrow this union based on route name checks.
+
+## Fix
+
+**Option 1: Pass route name to useRoute (recommended)**
+```typescript
+// pages/users/[id].vue
+import { useRoute } from 'vue-router/auto'
+
+// Specify the route path for proper typing
+const route = useRoute('/users/[id]')
+
+// Now properly typed as { id: string }
+console.log(route.params.id)  // string, not string | undefined
+```
+
+**Option 2: Type assertion with specific route**
+```typescript
+import { useRoute } from 'vue-router'
+import type { RouteLocationNormalized } from 'vue-router/auto-routes'
+
+const route = useRoute() as RouteLocationNormalized<'/users/[id]'>
+route.params.id  // Properly typed
+```
+
+**Option 3: Define route-specific param type**
+```typescript
+// In your page component
+interface UserRouteParams {
+  id: string
+}
+
+const route = useRoute()
+const { id } = route.params as UserRouteParams
+```
+
+## Required tsconfig Setting
+
+Ensure `moduleResolution: "bundler"` for unplugin-vue-router:
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+## Caveat: Route Name Format
+
+The route name matches the file path pattern:
+- `pages/users/[id].vue` → `/users/[id]`
+- `pages/posts/[slug]/comments.vue` → `/posts/[slug]/comments`
+
+## Reference
+
+- [unplugin-vue-router#337](https://github.com/posva/unplugin-vue-router/issues/337)
+- [unplugin-vue-router#176](https://github.com/posva/unplugin-vue-router/discussions/176)
+- [unplugin-vue-router TypeScript docs](https://uvr.esm.is/guide/typescript.html)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/vue-tsc-strict-templates.md

@@ -0,0 +1,69 @@
+---
+title: Enable Strict Template Checking
+impact: HIGH
+impactDescription: catches undefined components and props at compile time
+type: capability
+tags: vue-tsc, typescript, type-checking, templates, vueCompilerOptions
+---
+
+# Enable Strict Template Checking
+
+**Impact: HIGH** - catches undefined components and props at compile time
+
+By default, vue-tsc does not report errors for undefined components in templates. Enable `strictTemplates` to catch these issues during type checking.
+
+## Which tsconfig?
+
+Add `vueCompilerOptions` to the tsconfig that includes Vue source files. In projects with multiple tsconfigs (like those created with `create-vue`), this is typically `tsconfig.app.json`, not the root `tsconfig.json` or `tsconfig.node.json`.
+
+**Incorrect (missing strict checking):**
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+  // vueCompilerOptions not configured - undefined components won't error
+}
+```
+
+**Correct (strict template checking enabled):**
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  },
+  "vueCompilerOptions": {
+    "strictTemplates": true
+  }
+}
+```
+
+## Available Options
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `strictTemplates` | `false` | Enables all checkUnknown* options below |
+| `checkUnknownComponents` | `false` | Error on undefined/unregistered components |
+| `checkUnknownProps` | `false` | Error on props not declared in component definition |
+| `checkUnknownEvents` | `false` | Error on events not declared via `defineEmits` |
+| `checkUnknownDirectives` | `false` | Error on unregistered custom directives |
+
+## Granular Control
+
+If `strictTemplates` is too strict, enable individual checks:
+
+```json
+{
+  "vueCompilerOptions": {
+    "checkUnknownComponents": true,
+    "checkUnknownProps": false
+  }
+}
+```
+
+## Reference
+
+- [Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)
+- [Vite Vue+TS Template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-vue-ts)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/with-defaults-union-types.md

@@ -0,0 +1,102 @@
+---
+title: withDefaults Incorrect Default with Union Types
+impact: MEDIUM
+impactDescription: fixes incorrect default value behavior with union type props
+type: capability
+tags: withDefaults, defineProps, union-types, defaults, vue-3.5
+---
+
+# withDefaults Incorrect Default with Union Types
+
+**Impact: MEDIUM** - fixes spurious "Missing required prop" warning with union type props
+
+Using `withDefaults` with union types like `false | string` may produce a Vue runtime warning "Missing required prop" even when a default is provided. The runtime value IS applied correctly, but the warning can be confusing.
+
+## Symptoms
+
+- Vue warns "Missing required prop" despite default being set
+- Warning appears only with union types like `false | string`
+- TypeScript types are correct
+- Runtime value IS correct (the default is applied)
+
+## Problematic Pattern
+
+```typescript
+// This produces a spurious warning (but works at runtime)
+interface Props {
+  value: false | string  // Union type
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  value: 'default'  // Runtime value IS correct, but Vue warns about missing prop
+})
+```
+
+## Fix
+
+**Option 1: Use Reactive Props Destructure (Vue 3.5+)**
+```vue
+<script setup lang="ts">
+interface Props {
+  value: false | string
+}
+
+// Preferred in Vue 3.5+
+const { value = 'default' } = defineProps<Props>()
+</script>
+```
+
+**Option 2: Use runtime declaration**
+```vue
+<script setup lang="ts">
+const props = defineProps({
+  value: {
+    type: [Boolean, String] as PropType<false | string>,
+    default: 'default'
+  }
+})
+</script>
+```
+
+**Option 3: Split into separate props**
+```typescript
+interface Props {
+  enabled: boolean
+  customValue?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  enabled: false,
+  customValue: 'default'
+})
+```
+
+## Why Reactive Props Destructure Works
+
+Vue 3.5's Reactive Props Destructure handles default values at the destructuring level, bypassing the type inference issues with `withDefaults`.
+
+```typescript
+// The default is applied during destructuring, not type inference
+const { prop = 'default' } = defineProps<{ prop?: string }>()
+```
+
+## Enable Reactive Props Destructure
+
+This is enabled by default in Vue 3.5+. For older versions:
+```javascript
+// vite.config.js
+export default {
+  plugins: [
+    vue({
+      script: {
+        propsDestructure: true
+      }
+    })
+  ]
+}
+```
+
+## Reference
+
+- [vuejs/core#12897](https://github.com/vuejs/core/issues/12897)
+- [Reactive Props Destructure RFC](https://github.com/vuejs/rfcs/discussions/502)

package/knowledge/skills/web-security-guide/SKILL.md

@@ -0,0 +1,48 @@
+---
+id: security/web-security-guide
+name: Web 安全漏洞学习指南
+category: security
+description: OWASP 十大漏洞原理、影响与修复方案，覆盖 Python/Java 场景
+tags: [security, owasp, vulnerability, injection, xss, csrf, ssrf]
+updated_at: 2026-01-23
+---
+
+# Web 安全漏洞学习指南
+
+## ⚠️ 核心规则
+
+1. **永不信任用户输入** - 所有外部数据必须校验、转义、参数化
+2. **最小权限原则** - 仅授予完成任务所需的最小权限
+3. **纵深防御** - 多层安全措施，不依赖单一防护
+
+## 十大漏洞速查
+
+| 漏洞 | 危害 | 核心防御 |
+|------|------|----------|
+| 🔴 注入 | RCE/数据泄露 | 参数化查询 |
+| 🔴 XSS | 会话劫持 | 转义输出 |
+| 🔴 认证缺陷 | 账户接管 | 强Token+限速 |
+| 🔴 敏感数据泄露 | 隐私泄露 | 加密+脱敏 |
+| 🔴 访问控制缺失 | 越权操作 | 后端鉴权 |
+| 🟡 安全配置错误 | 信息泄露 | 关闭Debug |
+| 🟡 CSRF | 伪造操作 | Token验证 |
+| 🟡 反序列化 | RCE | 禁用危险接口 |
+| 🟡 SSRF | 内网探测 | 白名单URL |
+| ⚪ 日志不足 | 无法溯源 | 完整审计 |
+
+## 📦 按需加载资源
+
+| 漏洞类型 | URI |
+|----------|-----|
+| 注入漏洞 | `skill://web-security-guide/references/injection.md` |
+| XSS攻击 | `skill://web-security-guide/references/xss.md` |
+| 认证会话 | `skill://web-security-guide/references/auth-session.md` |
+| 数据泄露 | `skill://web-security-guide/references/data-exposure.md` |
+| 访问控制 | `skill://web-security-guide/references/access-control.md` |
+| 配置错误 | `skill://web-security-guide/references/security-config.md` |
+| CSRF | `skill://web-security-guide/references/csrf.md` |
+| 反序列化 | `skill://web-security-guide/references/deserialization.md` |
+| SSRF | `skill://web-security-guide/references/ssrf.md` |
+| 日志监控 | `skill://web-security-guide/references/logging-monitoring.md` |
+
+> 💡 先用速查表定位问题，再按需加载详细文档

package/knowledge/skills/web-security-guide/references/access-control.md

@@ -0,0 +1,123 @@
+# 访问控制缺失
+
+## 1. 漏洞原理
+
+- 访问控制缺失（Broken Access Control）是指应用未对用户访问的功能或资源进行严格的 身份认证与权限校验，导致攻击者可以越权访问、操作他人数据或调用敏感功能。
+
+- 常见问题：
+  - 鉴权仅在前端或网关，后端未做校验。
+  - ID 可控（IDOR，Insecure Direct Object Reference）。
+  - 垂直越权（普通用户可调用管理员接口）。
+  - 鉴权逻辑存在绕过漏洞（路径编码、大小写、截断）。
+
+## 2. 漏洞影响
+
+- 水平越权：攻击者可读取/修改其他用户的数据（如查看他人订单、转账记录）。
+- 垂直越权：普通用户可调用管理员功能（如创建用户、删除数据）。
+- 内部绕过：通过内网直连后端，绕过网关鉴权。
+- 逻辑绕过：利用路径大小写、编码差异，绕过黑名单/路径匹配规则。
+
+## 3. 典型业务场景
+
+### 3.1 功能隐藏在前端 UI，但后端未鉴权
+
+- 前端页面隐藏"导出数据"按钮，但后端接口 /admin/export 无鉴权。
+- 攻击者直接访问接口即可导出敏感数据。
+
+### 3.2 API 可越权访问其他用户数据（IDOR）
+
+- URL 参数可控：/api/user/profile?id=1002。
+- 用户 A 修改参数即可获取用户 B 的信息。
+
+```
+GET /api/user/profile?id=1001  # 合法
+GET /api/user/profile?id=1002  # 越权读取
+```
+
+### 3.3 水平越权：用户可修改 URL 参数访问他人资源
+
+- 类似 IDOR，但更广：订单、合同、文件下载接口。
+- 攻击者通过修改 URL order_id=xxx，获取他人订单详情。
+
+### 3.4 垂直越权：普通用户调用管理员接口
+
+- 普通用户调用 /admin/deleteUser。
+- 若仅靠前端按钮控制权限，后端无校验，则直接越权成功。
+
+### 3.5 鉴权逻辑仅在网关，后端未鉴权
+
+- API Gateway / Nginx 配置了鉴权规则，但后端服务自身无鉴权。
+- 攻击者通过 SSRF / 内网跳板 直连后端，绕过网关调用接口。
+
+```
+# 外网访问被网关阻挡
+GET https://api.example.com/admin/deleteUser?id=123 -> 403 Forbidden
+
+# 内网直连绕过网关
+GET http://10.0.0.5:8080/admin/deleteUser?id=123   -> 200 OK
+```
+
+### 3.6 鉴权逻辑被编码/截断/大小写绕过
+
+- 仅拦截 /admin/，但攻击者用 /admin%2F、/Admin、/admin;.jsp 绕过。
+
+```java
+// Bad：基于 startsWith() 的字符串判断
+if (uri.startsWith("/admin")) {
+    checkAdmin();
+}
+// 绕过：双编码
+GET /admin%2fdeleteUser?id=1  -> 绕过鉴权
+```
+
+## 4. 漏洞修复方案
+
+### 4.1 【必须】所有权限校验在后端完成
+
+- 不依赖前端按钮或网关规则，后端每个接口都必须有鉴权逻辑。
+
+### 4.2 【必须】资源级/行级权限控制（user_id/tenant_id）
+
+- 在数据查询层面增加 user_id/tenant_id 条件，保证只能访问自己的数据。
+
+```python
+# Bad Code: 根据传入 ID 查询
+User findUser(Long id);
+```
+
+```python
+# Good Code: 限制为当前登录用户
+User findUserByIdAndTenant(Long id, Long tenantId);
+```
+
+### 4.3 【必须】敏感接口必须加角色/权限控制注解
+
+- Spring Security: @PreAuthorize("hasRole('ADMIN')")
+- Django: @permission_required("app.delete_user")
+
+### 4.4 【建议】使用统一的 RBAC/ABAC 框架
+
+- 统一鉴权框架，避免业务线各自实现，减少漏鉴权。
+
+### 4.5 【必须】后端服务自身必须做鉴权，不能仅依赖网关
+
+- 网关鉴权是 第一道防线，后端鉴权是 最后一道防线。
+
+### 4.6 【建议】服务间调用采用 mTLS / JWT / API Key
+
+- 即使是内网调用，也要有身份凭证，避免伪造请求。
+
+### 4.7 【必须】统一路径规范化再鉴权
+
+- URL 统一大小写、解码、normalize 后再匹配。
+
+```java
+// Good Code: Spring Security 推荐方式
+http.authorizeHttpRequests()
+    .requestMatchers("/admin/**").hasRole("ADMIN")
+    .anyRequest().authenticated();
+```
+
+### 4.8 【建议】敏感操作二次确认
+
+- 如转账、删号、权限变更，需要二次验证码/密码确认。

package/knowledge/skills/web-security-guide/references/auth-session.md

@@ -0,0 +1,99 @@
+# 认证和会话管理不当
+
+## 1. 漏洞原理
+
+- 认证和会话管理不当指应用程序在登录验证、身份令牌（如JWT、SessionID）、Cookie配置等关键身份凭据的生成、传输、验证过程中存在设计或实现缺陷，导致攻击者可以冒充合法用户或维持非法会话。
+
+## 2. 漏洞影响
+
+- 账户暴力破解：登录接口无限制尝试密码
+- Token猜解/重放：弱Token或无过期机制导致账号被劫持
+- 会话劫持：Cookie 被JS或中间人窃取
+- 权限穿越：身份伪造后访问其他用户数据或管理接口
+- 长时间控制：Token 永不过期、用户退出无效化
+
+## 3. 典型业务场景
+
+### 3.1 登录未限速或缺验证码（暴力破解）
+
+- 漏洞示例代码如下：
+
+```python
+# Flask 示例：无限尝试登录
+@app.route('/login', methods=['POST'])
+def login():
+    username = request.form['user']
+    password = request.form['pass']
+    if check_user(username, password):
+        return 'login ok'
+    else:
+        return 'fail'
+```
+
+### 3.2 Token 可预测或未过期（重放攻击）
+
+- 漏洞示例代码如下：
+
+```python
+# 使用时间戳或用户名作为token
+token = hashlib.md5(username.encode() + str(time.time()).encode()).hexdigest()
+```
+
+### 3.3 Cookie 未设置 HttpOnly / Secure / SameSite（被盗用）
+
+- 漏洞示例代码如下：
+
+```python
+# Flask 设置 cookie 时未加 HttpOnly / Secure
+resp.set_cookie('session_id', session_id)
+```
+
+- 修复建议：
+
+```python
+resp.set_cookie('session_id', session_id,
+    httponly=True,  # 防止JS读取
+    secure=True,    # 仅HTTPS传输
+    samesite='Strict')  # 防止跨站携带
+```
+
+### 3.4 JWT 签名绕过或私钥泄露
+
+- 使用不安全的算法，如 alg: none
+- JWT 密钥泄露、使用弱秘钥（如 test、123456）
+
+### 3.5 用户登出无效，旧会话仍可用
+
+- JWT/Session未绑定设备信息，登出后未销毁旧 token，攻击者可长期使用
+
+## 4. 漏洞修复方案
+
+### 4.1 【必须】使用强随机 Token + 签名验证机制
+
+- 使用 secrets、uuid4、os.urandom 生成随机Token
+- JWT等结构化Token需添加签名 + 加密 + 时效控制
+- 明确算法算法配置（HS256、RS256），禁用"none"
+
+### 4.2 【必须】Token 设置过期时间并支持吊销
+
+- Access Token 推荐有效期 ≤ 15分钟
+- Refresh Token 设置较长时间，并限制单设备有效
+- 可在 Redis 维护 blacklist、revoked 状态表
+
+### 4.3 【必须】配置 Cookie 安全属性
+
+- 开启HttpOnly：禁止 JS 读取 cookie
+- Secure：仅在 HTTPS 下传输
+- SameSite=Strict 阻止第三方携带 Cookie 发起请求
+
+### 4.4 【必须】登录限速 + 验证码策略
+
+- IP维度/账号维度做登录次数限制
+- 多次失败需冷却或触发验证码
+- 应记录登录日志并告警异常登录行为
+
+### 4.5 【建议】用户绑定多端设备与会话管理
+
+- 多终端登录记录中应显示设备、IP、登录时间
+- 后台可选择"踢出其他设备"、"只允许单端登录"
+- 所有 token 使用者身份变化时强制刷新

package/knowledge/skills/web-security-guide/references/csrf.md

@@ -0,0 +1,59 @@
+# 跨站请求伪造（CSRF）
+
+## 1. 漏洞原理
+
+- 跨站请求伪造（Cross-Site Request Forgery, CSRF），是指攻击者诱导已登录的用户，在不知情的情况下向受信任站点发起恶意请求，从而执行敏感操作。
+- 本质：应用只依赖 Cookie/Session 等隐式凭证鉴权，而未绑定用户意图（缺乏额外验证），导致用户在第三方页面访问时也能"自动带上凭证"。
+
+## 2. 漏洞影响
+
+- 用户账户被盗用：攻击者可伪造请求修改用户信息、邮箱、密码。
+- 金融类业务损失：伪造转账、支付、购买请求。
+- 权限维持与系统破坏：攻击者可在后台添加管理员、开启恶意配置。
+- 长期隐患：攻击可通过钓鱼站点、广告投放、论坛嵌入图片等途径批量触发。
+
+## 3. 典型业务场景
+
+### 3.1 用户已登录，访问恶意站点触发转账/改密
+
+- 攻击者在钓鱼网站放置隐藏表单或图片：
+
+```html
+<img src="https://bank.com/transfer?to=attacker&amount=1000">
+```
+
+- 如果银行网站仅依赖 Cookie 鉴权，用户已登录时就会直接完成转账。
+
+### 3.2 使用 GET 请求执行敏感操作
+
+- 系统用 GET 请求处理改密：
+
+```
+https://example.com/resetpwd?new=123456
+```
+
+- 攻击者只需诱导点击链接即可完成修改。
+
+### 3.3 未校验 Origin/Referer
+
+- 后端只依赖 Cookie 验证，未检查请求来源，导致任意第三方页面可发起敏感请求。
+
+## 4. 漏洞修复方案
+
+### 4.1 【必须】启用 CSRF Token / 双提交 Cookie
+
+- 后端生成随机 Token，绑定到用户会话，在表单或请求头中附带，后端验证一致性。
+- 双提交 Cookie 模式：前端 JS 写入 Cookie 和请求参数，后端校验两者一致。
+
+### 4.2 【必须】敏感操作使用 POST/PUT/DELETE
+
+- 禁止使用 GET 请求执行转账、改密、删除等操作。
+
+### 4.3 【必须】校验 Origin/Referer 请求头
+
+- 服务端必须验证请求来源域名与白名单匹配。
+- 对跨域请求强制使用 CORS 配置。
+
+### 4.4 【建议】关键操作需二次确认（验证码/密码输入）
+
+- 转账、改密等高风险操作要求再次输入验证码或密码，增加攻击难度。