Local-First 安全详解：zvec-grep 数据边界、远程模型授权与本地鉴权机制

Local-First 安全详解zvec-grep 数据边界、远程模型授权与本地鉴权机制【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grepzvec-grepzg是一个本地优先Local-First的工作区搜索工具面向人类开发者和 AI Agent 提供统一的搜索接口代码、文档与结构化数据都留在你的机器上只有在你明确授权后内容才会发送给远程嵌入模型。本文带你完整了解它的三层安全设计数据边界、远程模型授权、本地鉴权存储。什么是 Local-First 安全大多数搜索/索引工具会把文件内容当作过路数据而 zvec-grep 的安全模型从一开始就回答了一个关键问题我的代码会流向哪里答案分两种模式本地模式默认源文件、索引、本地嵌入模型全部停留在本机查询文本也绝不离开机器。远程模式可选当且仅当你显式选择远程嵌入模型并授权后已披露的数据查询文本、变更文件等才会发送到指定端点。一句话总结Local by default, remote only with your permission.第一层数据边界——文件都放在哪zvec-grep 把所有本地数据收敛到两个可预期的位置数据类型存放位置说明工作区索引项目根/.zvec-grep/每个被索引的项目独立一份可随.gitignore忽略模型缓存~/.zvec-grep/models本地嵌入模型首次使用时下载带完整性校验授权文件项目根/.zvec-grep/authorization.json远程嵌入的授权凭证权限 0600签名密钥~/.zvec-grep/authorization-signing.key32 字节随机密钥权限 0600目录 0700本地模型如local/potion-code-16m-v2从 Hugging Face 下载后缓存到本机若下载失败会自动回退到固定版本、经完整性校验的 ModelScope 副本。模型选型与缓存策略详见 07-embedding.md。第二层远程模型授权——发数据前先问路当你选择远程嵌入模型例如qwen/qwen3.7-text-embedding时zvec-grep 会先制定授权计划再决定是否需要询问你。计划逻辑位于 planner.ts核心规则只有远程模型才需要授权本地模型provider 为local永远不触发授权流程数据天然不出本机。披露内容精确到发什么授权计划会明确列出本次操作要发送的数据类别——索引操作selected workspace files全量或仅变更文件向量查询query text你的查询文本纯词法搜索或索引已新鲜时零数据发送无需授权授权提示透明可读提示框会显示From哪个工作区→To哪个 provider/model 与端点主机并注明 API charges may apply。格式由 prompt.ts 生成。Agent 场景同样受保护当 MCP 宿主不支持授权交互时Agent 必须改用宿主自带提问工具向你确认且在未收到决定前不会发送任何远程数据见 03-mcp.md。一次典型的授权交互Remote Embedding authorization Send query text and changed workspace files? From my-project To qwen/qwen3.7-text-embedding api.example-host.com API charges may apply.你在交互中选择允许 / 仅用本地 / 取消三种之一。允许后授权范围是当前工作区而不是全局。第三层本地鉴权——带签名的许可证授权一旦授予zvec-grep 会把它落盘为一份带 HMAC 签名的授权文档实现位于 store.ts指纹锁定目标工作区根路径先做realpath规范化再取 SHA-256 指纹与 provider、模型、端点一起构成目标指纹见 target.ts。换端点、换模型、换目录旧授权自动失效。HMAC-SHA256 签名每次授权由本机签名密钥对授权内容签名验证时使用timingSafeEqual恒定时间比较抵御时序攻击。严格文件权限授权文件与密钥文件均以0600写入、目录0700并带读写锁防止并发写坏文档。可随时吊销revoke/revokeAll支持按目标吊销或清空整个工作区的所有授权吊销会同步清理多根目录下的副本。用 CLI 管理授权管理逻辑位于 auth.ts三个动作覆盖完整生命周期# 查看当前工作区的授权状态与有效性 zg --auth status # 显式授予某远程模型对当前工作区的授权 zg --auth grant # 一键吊销所有远程嵌入授权 zg --auth revoke授权管理器 manager.ts 还负责已有授权直接放行、否则走交互的判定确保每次远程调用前都会复核签名是否仍然有效。给新手的 4 条安全建议默认什么都不用配本地模型模式下代码与查询文本永远不出机器这是最省心的用法。选远程模型前先想清楚远程嵌入会发送披露的数据且可能产生 API 费用。离开团队/换端点前跑一次zg --auth revoke干净离场。多工作区隔离授权是工作区级的A 项目的授权对 B 项目无效天然防止一次授权处处放行。小结zvec-grep 的 Local-First 安全不是口号而是三层可验证的机制层级机制关键文件数据边界索引/模型/授权全部本地化权限收紧07-embedding.md远程授权授权计划 精确数据披露 交互确认src/authorization/planner.ts本地鉴权HMAC 签名、指纹绑定、恒定时间校验、0600 权限src/authorization/store.ts数据留在本地是默认流向远程是例外——而例外必须由你亲自签字。更多设计细节可参考 docs/05-architecture.md 与 docs/04-pipeline.md。【免费下载链接】zvec-grepLocal-first search across your workspace, built for humans and AI agents.项目地址: https://gitcode.com/gh_mirrors/zv/zvec-grep创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考