Harden auth/vault path sanitization and clean WeKnora docs

2026-07-28 17:04:27 +08:00
parent 2deaf59f7b
commit 26ff1a9c9a
190 changed files with 13454 additions and 4987 deletions
@@ -1,6 +1,6 @@
 # MNote knowledge RAG

-> 2026-07-19 口径：当前默认知识库主线是 **LightRAG**（runtime 默认 `lightrag_legacy` / `lightrag`）。WeKnora 与 RAGFlow 只作为 env 显式切换的备用 / 调试路径，不是普通资料库问答默认。
+> 2026-07-19 口径：当前默认知识库主线是 **LightRAG**（runtime 默认 `lightrag_legacy` / `lightrag`）。RAGFlow 仅作 env 显式切换的备用 / 调试路径，不是普通资料库问答默认。

 使用场景：用户要求“资料库问答”、跨多本书/论文/PDF/Office 附件问答，或需要可回跳 citation 的知识库结果。

@@ -19,6 +19,6 @@
 - 知识库 provider 是派生缓存，不是 MNote Markdown 正文真相。
 - `filePath` 是 provider-local 名称；只有 registry 命中的 reference 才能映射回 MNote source。
 - 如果返回 `locatorDegraded: true`，可以使用返回的 `citationMarkdown`，但必须明说“来源定位降级”，不要伪造页码、bbox 或 provider 内部路径。
- 当前 provider 不可用时，不要声称资料库已查到；提示用户启动或检查 LightRAG / 知识库服务。旧 WeKnora / RAGFlow / LiteParse / `mnote.evidence.*` 本地 evidence 检索不作为默认 fallback。
+- 当前 provider 不可用时，不要声称资料库已查到；提示用户启动或检查 LightRAG / 知识库服务。旧 RAGFlow / LiteParse / `mnote.evidence.*` 本地 evidence 检索不作为默认 fallback。
 - MNote 的职责不是重排、补召回或再做一套全文搜索；MNote 只做 allowed roots、source registry、结果过滤、有限 section context 和 citation/open-reference 映射。
 - 兼容 skill 别名：`mnote-document-evidence` / `mnote-local-index` 只解析到本 skill，不恢复旧 evidence/index 工具面。
@@ -1,8 +1,13 @@
 ---
 name: mnote-vault
 description: >
-  MNote AI 密码本（多 agent 唯一策略）。读密与 login/session：mnote-vault CLI + capability token（不依赖 mnote-web）。
+  【可全机】 MNote AI 密码本（多 agent 唯一策略）。读密与 login/session：mnote-vault CLI + capability token（不依赖 mnote-web）。
  登录态为每账号独立 session 文件；禁扫 .mnote/vault 文件。
+runtime: portable
+class: A
+host: local
+mcp_remote: null
+access: n/a
 ---

 # MNote 密码箱 / AI 密码本
@@ -11,6 +16,54 @@ description: >
 **设计**：
 - `design/12-vault/process/12-2-vaultd-local-token-agent-read-path-v1.md`（agent 读密 / login）
 - `design/12-vault/process/12-3-chrome-extension-vault-save-v1.md` §5.6 / §6.5（每账号 session 文件；扩展只写入）
+- `design/07-ai/process/7-76-ai-principal-web-pat-and-auth-hardening-v1.md`（Web PAT vs vault token）
+
+**本 skill 契约文件**（无 secret）：
+- `skills/mnote-vault/env.schema.json` — env 变量声明
+- `skills/mnote-vault/agent-env.example.env` — 本机 env 模板（复制后填值）
+
+## 三种凭证分职（必读 · 禁止混用）
+
+| 凭证 | 前缀 / 形态 | env | 用途 | 禁止 |
+|------|-------------|-----|------|------|
+| Vault capability | `mnv1.*` | `MNOTE_VAULT_TOKEN` / `MNOTE_VAULT_TOKEN_FILE` | `list/get/resolve/login/session` | 调 mnote-web 笔记 API |
+| Web PAT | `mnpat1.*` | `MNOTE_WEB_PAT`（或 `MNOTE_API_TOKEN`） | 机机访问笔记 JSON API | vault resolve / 当密码 |
+| 业务密钥 | 条目字段 | **无长期 env** | `resolve --field apikey\|password\|token` 短时使用 | 写入 skill / git / agent-env 常驻 |
+
+Scope 短名（与 CLI 一致）：`list,get,resolve,login,session`。  
+Web 设置页若传入 `vault.list` 等会在服务端归一化为短名。
+
+## Agent env 加载顺序
+
+```text
+1. 进程已有环境变量
+2. $MNOTE_AGENT_ENV_FILE（若设置）
+3. ~/.config/mnote/agent-env/<agent-name>.env
+4. 本 skill 默认：
+   MNOTE_VAULT_TOKEN_FILE=$HOME/.config/mnote/vault-tokens/default.token
+   MNOTE_AI_VAULT_ACTOR=mnote-e2e
+```
+
+本机布局（**0600，不进仓库**）：
+
+```text
+~/.config/mnote/
+  vault-tokens/
+    mnote-e2e.token      # AI 主体 / 多 agent 共享读密策略
+    <userId>.token       # 用户私有 agent（若代该用户读自己的箱）
+    default.token        # 兼容旧路径；新装建议按 subject 命名
+  agent-env/
+    paseo.env
+    default.env
+  vaultd-hmac.key        # 仅本机签发校验
+```
+
+**一主体一 token 文件**；禁止多人共用并互相覆盖 `default.token`。
+
+人在 **MNote 设置 → API 访问令牌 / 密码箱 AI 访问** 签发后：
+1. 复制 token 或「安装命令」
+2. 写入 `vault-tokens/<subject>.token` 与/或 `agent-env/<agent>.env`
+3. agent：`set -a; source ~/.config/mnote/agent-env/<agent>.env; set +a`

 ## 读密稳态（P0 · 不依赖 mnote-web）

@@ -24,21 +77,24 @@ description: >

 ```bash
 # 一次（人 / 安装）：签发 token（cwd 任意）
+# CLI：
 mnote-vault issue-token --agent paseo --ttl 90d
-# 或绝对路径：
-# /home/lix/.local/bin/mnote-vault issue-token --agent paseo --ttl 90d
+# 或 Web 设置页「密码箱 AI 访问」签发 → 安装到 vault-tokens/<subject>.token

 # Agent 每次（已知 id；cwd 任意，不要求在 mnote 仓库）
+# 可选：source ~/.config/mnote/agent-env/<agent>.env
 export MNOTE_VAULT_TOKEN_FILE="${MNOTE_VAULT_TOKEN_FILE:-$HOME/.config/mnote/vault-tokens/default.token}"
 mnote-vault list
 mnote-vault resolve --id <id> --field password
 # 管道只要明文：
 mnote-vault resolve --id <id> --field password --raw
+# 上游 API Key：
+mnote-vault resolve --id <id> --field apikey --raw
 ```

 **故障排查顺序**（≤2 步，禁止全盘搜索二进制）：
 1. `command -v mnote-vault || ls /home/lix/.local/bin/mnote-vault`
-2. `mnote-vault doctor` → `tokenValid=false` 时只跑 `issue-token`，**不要**起 3000
+2. `mnote-vault doctor` → `tokenValid=false` 时只跑 `issue-token` 或 Web 重签并安装文件，**不要**起 3000

 | 命令 | 用途 |
 |------|------|
@@ -114,6 +170,9 @@ mnote-vault login --id <id> --force-refresh
 ## 硬规则

 1. 禁 file 扫 `.mnote/vault/**`（含 sessions）  
-2. 聊天不贴 password / cookieHeader / token  
-3. Token `0600`；故障先 `issue-token`，不要默认起 3000  
+2. 聊天不贴 password / cookieHeader / token / PAT  
+3. Token 文件 `0600`；故障先 `issue-token` 或 Web 重签安装，不要默认起 3000  
 4. 需要登录态时 **先 `login`**，不要先 `resolve` 密码再手拼 Cookie  
+5. **分职**：笔记 CRUD 用 `MNOTE_WEB_PAT`；读密用 `mnv1`；业务 API Key 只 `resolve`，不进 skill 源码  
+6. Skill 只声明 env 契约；secret 只在 `~/.config/mnote/**`  
+7. 多 agent 共享读密 → 默认 AI 主体 `mnote-e2e` token + 用户 share-to-AI；用户私有 agent 才持该用户 token  
@@ -0,0 +1,20 @@
+# 复制到本机（勿提交仓库）：
+#   mkdir -p ~/.config/mnote/agent-env
+#   cp agent-env.example.env ~/.config/mnote/agent-env/paseo.env
+#   chmod 600 ~/.config/mnote/agent-env/paseo.env
+# 使用：
+#   set -a; source ~/.config/mnote/agent-env/paseo.env; set +a
+
+# --- Vault capability（mnv1.*）读密 / login ---
+# 推荐按 subject 分文件，避免多用户互相覆盖 default.token
+MNOTE_VAULT_TOKEN_FILE=~/.config/mnote/vault-tokens/mnote-e2e.token
+# MNOTE_VAULT_TOKEN=mnv1....   # 可选：内联；优先于 FILE
+
+# AI 密码本策略默认主体（share-to-AI 后由该主体 token 读）
+MNOTE_AI_VAULT_ACTOR=mnote-e2e
+
+# --- Web PAT（mnpat1.*）笔记 API（可选；与 vault 分职）---
+# MNOTE_WEB_BASE_URL=http://127.0.0.1:3000
+# MNOTE_WEB_PAT=mnpat1....
+
+# 业务上游 API Key 不要写在这里 → 放密码箱条目，resolve 取出
@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "mnote://skills/mnote-vault/env.schema.json",
+  "title": "mnote-vault agent env contract",
+  "description": "Skill 只声明变量契约；真实 secret 写在本机 ~/.config/mnote/**（0600），禁止写入 SKILL.md / git。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "MNOTE_VAULT_TOKEN_FILE": {
+      "type": "string",
+      "secret": true,
+      "description": "Capability token 文件路径（mnv1.* 单行）。优先于默认 default.token。",
+      "default": "~/.config/mnote/vault-tokens/default.token",
+      "examples": [
+        "~/.config/mnote/vault-tokens/mnote-e2e.token",
+        "~/.config/mnote/vault-tokens/liaibo.token"
+      ]
+    },
+    "MNOTE_VAULT_TOKEN": {
+      "type": "string",
+      "secret": true,
+      "description": "内联 mnv1.* token；与 FILE 二选一，进程 env 优先于文件。",
+      "optional": true
+    },
+    "MNOTE_AI_VAULT_ACTOR": {
+      "type": "string",
+      "description": "AI 密码本 actor；多 agent 共享读密策略时默认 mnote-e2e。",
+      "default": "mnote-e2e"
+    },
+    "MNOTE_VAULT_WORKSPACE": {
+      "type": "string",
+      "description": "覆盖 vault workspace 根目录（可选）。",
+      "optional": true
+    },
+    "MNOTE_VAULT_SESSION_TTL_HOURS": {
+      "type": "string",
+      "description": "外站 login session 默认 TTL 小时。",
+      "default": "168",
+      "optional": true
+    },
+    "MNOTE_VAULT_SOCK": {
+      "type": "string",
+      "description": "可选 mnote-vaultd UDS 路径。",
+      "optional": true
+    },
+    "MNOTE_WEB_PAT": {
+      "type": "string",
+      "secret": true,
+      "description": "Web PAT（mnpat1.*）。用于笔记 API，不是 vault resolve。可与 vault 变量同写 agent-env。",
+      "optional": true
+    },
+    "MNOTE_API_TOKEN": {
+      "type": "string",
+      "secret": true,
+      "description": "MNOTE_WEB_PAT 的别名。",
+      "optional": true
+    },
+    "MNOTE_WEB_BASE_URL": {
+      "type": "string",
+      "description": "mnote-web 基址（仅笔记 API 需要）。",
+      "default": "http://127.0.0.1:3000",
+      "optional": true
+    }
+  },
+  "notes": [
+    "业务上游 API Key / 站点密码：只存密码箱条目，运行时 mnote-vault resolve --field apikey|password|token。",
+    "禁止把 secret 写进 skills/** 或仓库。",
+    "一主体一 token 文件：~/.config/mnote/vault-tokens/<subject>.token",
+    "Agent 启动可 source ~/.config/mnote/agent-env/<agent>.env"
+  ]
+}