179 lines
7.9 KiB
Markdown
179 lines
7.9 KiB
Markdown
---
|
||
name: mnote-vault
|
||
description: >
|
||
【可全机】 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 密码本
|
||
|
||
**SSOT**：`/home/lix/.agent-infra/vault-policy.md`
|
||
**设计**：
|
||
- `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）
|
||
|
||
### 可执行入口（agent 必看 · 不要自己 find）
|
||
|
||
| 优先级 | 路径 | 说明 |
|
||
|--------|------|------|
|
||
| **1（默认）** | `mnote-vault` | 已装到 `~/.local/bin/mnote-vault`（symlink） |
|
||
| **2（绝对路径）** | `/home/lix/.local/bin/mnote-vault` | PATH 异常时直接用 |
|
||
| **3（源码构建产物）** | `/mnt/Data1T/mnote/rust/target/debug/mnote-vault` | 开发树；**不要**在 `/home/lix` 下 `find` 全盘 |
|
||
|
||
```bash
|
||
# 一次（人 / 安装）：签发 token（cwd 任意）
|
||
# CLI：
|
||
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` 或 Web 重签并安装文件，**不要**起 3000
|
||
|
||
| 命令 | 用途 |
|
||
|------|------|
|
||
| `doctor` | workspace / token / hmac 状态（无明文） |
|
||
| `issue-token` | 签发 capability token（**不是** master key） |
|
||
| `whoami` | 当前 token claims |
|
||
| `list` / `get` | L0 选型；无密码/cookie 明文；可见 `hasLoginSession` |
|
||
| `resolve` | **取密**；字段 `password` / `apikey` / `token` 等；审计无 value |
|
||
| `login` | **优先复用登录态**；无/过期则 api_first 或 human_required |
|
||
| `session` | 浏览器/人机验证后回写 Cookie（写 session 文件；不启 3000） |
|
||
| `serve` | 可选 UDS vaultd；CLI 默认 sock→内嵌 fallback |
|
||
|
||
**禁止**：为读密 / login / session 去 `auth-e2e` / 起 3000 / 用 cookie 调 `/api/vault/ai/*`。
|
||
**禁止**：`Read` / `cat` / `grep` `.mnote/vault/**`（含 `entries/` 与 `sessions/`）。
|
||
`scripts/mnote-vault-cli.js` 的 web 路径仅调试 UI。
|
||
|
||
## 登录态文件（每账号一份 · 12-3）
|
||
|
||
磁盘（AI 本 / 用户 vault 同结构）：
|
||
|
||
```text
|
||
{workspace}/.mnote/vault/
|
||
entries/{credId}.md # 账号密码；勿手读
|
||
sessions/{credId}/primary.json # 主账号登录态
|
||
sessions/{credId}/{accountId}.json
|
||
```
|
||
|
||
- **写入口（人）**：Chrome 扩展默认保存登录态 → `PUT …/session`；或 Agent `mnote-vault session`。
|
||
- **读入口（AI）**：只经 `login` / `session` /（P1）`resolve --field session`。
|
||
- frontmatter 内旧 `loginSession`：兼容读；**新写一律走 session 文件**。
|
||
- 扩展写入的是**人用 vault**；Agent 默认读 **AI 本** → 须用户 **share-to-ai**（会连同 session 文件复制）。
|
||
|
||
## 登录稳态（外站 cookie · 12-2 P1d + 12-3）
|
||
|
||
需要外站已登录状态（Cookie）时：
|
||
|
||
```bash
|
||
# 1) 优先复用已有 session（读 sessions/…json；无 HTTP 出站）
|
||
mnote-vault login --id <id>
|
||
# 多账号：
|
||
mnote-vault login --id <id> --account-id <accId>
|
||
|
||
# 2a) mode=session | reused | ok → 用响应里的 cookieHeader
|
||
# （仅进程内/管道使用；禁止贴进聊天、commit、issue）
|
||
|
||
# 2b) human_required / CF：chrome-bridge 登录后回写
|
||
mnote-vault session --id <id> --cookie-header 'name=value; …' --source human_bridge
|
||
# 可选：--account-id <accId>
|
||
|
||
# 3) 强制重新 api_first 登录（忽略未过期 session）
|
||
mnote-vault login --id <id> --force-refresh
|
||
```
|
||
|
||
| `login` 结果 | Agent 动作 |
|
||
|--------------|------------|
|
||
| `mode=session` / `reused` / `ok` 且含 `cookieHeader` | 用 Cookie 调目标站 API 或注入浏览器 |
|
||
| `mode=human_required` | chrome-bridge / 人完成验证 → `session` 回写 → 再 `login` |
|
||
| 无 session 且 api_first 失败 | 查 playbook / 人用扩展是否已 share-to-ai |
|
||
|
||
- `resolve` / `session` / `login` 写盘：本地 `.mnote/vault/**`（core），**不**经 mnote-web。
|
||
- `login` 的 `api_first` 仅对目标站出站 HTTP。
|
||
- 默认 session TTL：7 天（`MNOTE_VAULT_SESSION_TTL_HOURS`）。
|
||
|
||
## 与 Chrome 扩展的边界
|
||
|
||
| 角色 | 通道 | 鉴权 |
|
||
|------|------|------|
|
||
| 人：外站保存账号+登录态 | 扩展 → mnote-web `/api/vault/*` | human Bearer（**非** agent token） |
|
||
| AI：读密 / 复用登录态 | `mnote-vault` CLI → core | capability token |
|
||
|
||
扩展 **不是** agent 通道。人保存后若要 AI 用：在确认层勾选 **同步到 AI 密码本**（或工作台 share-to-ai）。
|
||
|
||
## 硬规则
|
||
|
||
1. 禁 file 扫 `.mnote/vault/**`（含 sessions）
|
||
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
|