@bjorntech/ key-ferry (英语)
Global and project-scoped Key Ferry 证书代理集成 OpenCode V2.
保护什么
原生效果 4 插件拥有一个工程范围 Varlock 代理进程和 保护明确选择的 MCP 服务器 :
- 本地MCP服务器接收占位符支持的环境映射.
- 远程 API- key MCP 服务器使用经认证,范围化回放中继器. 中继器通过 Varlock 的 HTTP 转发流式 HTTP 和 遗留 SSE 配置的 HTTPS 端点的 CONNECT 代理 .
- 启动、刷新、丢失位置持有人、中继和侧车故障失败 关闭。 没有直接运输倒退.
- 未选择的远程服务器,包括本地的OAuth服务器,保持不变.
插件从不包装 OpenCode, 变异全局 process.env,或存储真实
openCode 配置中的秘密值。 公共地位、RPC和TUI产出
永不曝光中继符、环境值、 CA 内容或原始守护进程
输出.
这是范围化的证书 - 代用路线, 不是一个完整的沙盒。 同一用户 进程仍然可以访问正常文件、存储和守护进程。 远程中继器 控制其配置的出入境路径,而不是依赖 MCP 客户端 荣誉代理环境变量,但没有保证响应有效载荷 将每个秘密清洗. 不包括直接提供者/API运输保护.
所需资源
- OpenCode V2 有原生代码
@opencode/plugin/effect @opencode/plugin2.0.30 兼容运行时间- 4.0.1 兼容运行时间
- 22号节点或更新
- Varlock CLI 1.23.0 单独安装为
varlock - 安装的 Varlock CLI 和配置的 Varlock 环境/schema 与 机密和代理规则 您的 MCP 服务器需要
- 一个私有的,可写作的所有权记录运行时间目录. 默认情况下
实值
tmpdir()/key-ferry-<uid>· ;adapter.ownershipDirectory可用于 输入另一个私有、可写目录。 如果无法保证, 启动 未关闭ownership_unavailable诊断(另见key-ferry.doctor) (中文(简体) ). - 配置机密源和认证 Varlock 文档
已同第24号节点和第1.4.2号舱一道进行了核查 原生OpenCode V2包类型和效果 4.0.1.
安装
OpenCode 自动安装配置的 npm 插件 。 将软件包添加到
全局 OpenCode 插件配置( 通常情况下) ~/.config/opencode/opencode.json(中文(简体) )
并保存任何已存在的无关条目 :
{
"plugins": [
{
"package": "@bjorntech/key-ferry",
"options": {
"enabled": true,
"requireStrictEgress": true,
"projectDirectory": ".",
"servers": {
"example-local-mcp": { "env": ["FAKE_API_KEY"] },
"example-remote-mcp": {
"remote": {
"headers": {
"Authorization": { "env": "REMOTE_API_KEY", "prefix": "Bearer " }
}
}
}
}
}
}
]
}
软件包在全球配置,而 projectDirectory 选择
服务器映射决定保护哪个项目上下文。 未放大的 MCP
服务器仍在本地 OpenCode 行为下。 选定的远程 API- key 服务器
必须明确设置 oauth: false; 原生 OAuth 保持不变
未选中服务器 .
分别安装 Varlock CLI 。 优先使用共享的 CLI 安装 在每个工程中安装 :
brew install dmno-dev/tap/varlock
varlock --version
该插件不安装 Varlock 或解锁一个秘密商店 。 配置其 环境与认证,分别遵循 Varlock 文档。 。 。 .
包裹的兄弟们 ./tui 导出在
服务器插件已装入 。 不添加重复内容 cli.json 条目
普通服务器插件安装 。 全球 cli.json 条目仅有用
用于仅连接到远程 OpenCode 服务器的 CLI 或 CLI 部署
已装入服务器插件 .
设定 projectDirectory 至 Varlock 工程根中包含该图案。 这个
插件启动并拥有其 Varlock 侧车本身; 不包写 OpenCode 或
手动运行 varlock proxy。 。 。 .
全球配置和项目选入
本地插件条目可以在 OpenCode 全局配置中安装一次.
设定 projectConfig.enabled 改为 true 使项目文件符合条件; 是
false 默认的反向兼容性。 全球配置拥有
一个瓦洛克集团及其绘图 当前 OpenCode 项目中的一个项目
root 可以在
.opencode/key-ferry.jsonc数字 :
{
"enabled": true,
"servers": {
"project-mcp": { "env": ["PROJECT_API_KEY"] }
}
}
使用 全球实例,则
本地项目示例,则
项目绘图实例 可复制
形状。 项目文件只映射已存在的 MCP 服务器
工程的本地 OpenCode 配置; 它不定义或安装 MCP
服务器,它不需要第二个 Key Ferry 插件条目。 配对
本地项目实例 显示单独
定义。 这个
合成 GLOBAL_API_KEY 财务报告和审定财务报表 PROJECT_API_KEY 名字是计划参考文献,
非证书; 分别配置每个 Varlock 根及其密源
使用 Varlock 文档。工程文件为
相对于 cononic 工程根而不是服务读取
工作目录及其可选 projectDirectory 必须留在里面
树根。 它只包含项目绘图:全球绘图、环境键和
Varlock计划从未进口或联合。 重新使用的项目映射a
全局服务器名必须在 overrides; 否则碰撞
被拒绝。 其他全球约束服务器不受影响.
全球 projectConfig.activation 政策是一层楼. "auto" 激活一个
自动获得资格的项目; "manual" 需要明确
key-ferry.activateProject 命令。 项目可能限制自动全球
使用自己的激活 "activation": "manual",但不能升级手动
全球政策。 手动激活是当前位置的内存,并且是
不是一个存储的入学名单。 状态纯洁,报告所有配置范围,
包括不活动的项目范围。 默认刷新和医生保留
全局行为; 范围化的项目操作只针对选定的活动
项目组,永远不要激活它。 使用 activateProject 首先当
项目正在等待启动.
这种选入是执行政策,而不是认证或安全边界.
Varlock 供应商和 @exec 可执行代码,而一个不信任的寄存器是
而非由此特性所装入的沙盒 。 在启用全局前审查项目文件
自动激活.
配置
本地映射保存 MCP 命令, cwd, 和无关的环境 :
"example-local-mcp": {
"env": { "UPSTREAM_API_KEY": "FAKE_API_KEY" }
}
远程映射地图目标为HTTP头来精确瓦洛克环境名称. 字符串形式是一个环境参考, 绝不是一个原始标题值 :
"example-remote-mcp": {
"remote": {
"headers": {
"Authorization": { "env": "REMOTE_API_KEY", "prefix": "Bearer " },
"X-Tenant": { "env": "REMOTE_TENANT", "suffix": "-synthetic" }
}
}
}
信头名称被验证用于控制、跳跃、协议、复制和
证明性障碍 目标 URL 来自本地的 MCP 远程
配置,不是来自中继绘图. HTTPS 证书和碎片
拒绝。 除非
明确 allowPrivateNetwork: true 政策已经设定。 普通企业DNS
姓名并非仅仅因为可以在国内解决而被拒绝.
使用 examples/single-project/.env.schema 仅用于遗产单根的例子。 给
全球/ 项目设置, 复制 examples/global/.env.schema 输入已配置
全球瓦洛克根和 examples/project/.env.schema 输入项目
分开的瓦洛克根。 不要重用一个综合计划 或围绕这个工作
与 Varlock 导入分离: Varlock 在 Key Ferry 之前装入全部计划
请求的过滤键 。 标记每个远程上游主机 @proxy(domain="...") 保留
@proxyConfig={egress="strict"}通过Varlock配置任何秘密来源;
Key Ferry 不安装 Varlock 、 创建其计划或配置提供者
认证。 永远不要做一个真正的秘密.
经纪人流程仍然可用 idleTimeoutMs 毫秒后
最后一次租赁解除( 默认 : 600000或十分钟). 这个可以重用
在返回项目时认证 Varlock 代理 。 设定
idleTimeoutMs: 0 立即拆卸; 闲置经纪人总是被停止
主机关闭或当其计划/配置身份发生变化时。 这是一个
安全/业绩权衡:已解密仍在代理程序中
保存到项目离开后闲置超时的内存。 启动时键渡
还收获了先前程序留下的孤儿身份核查代理记录.
如果在关闭时停止代理失败, Key Ferry 将保留其所有权记录和
将清理推迟到下一个启动,其收割者重试同一会话UUID.
在 SIGINT 或 SIGTERM 上,它执行有界限的清理(最多 三秒钟),删除
它的信号听器,当它是唯一的听器的时候,它能重新发出信号
保存主机正常终止语义; 主机拥有的信号
听众继续控制.
TUI 命令
| 调色板命令 | 斜线命令 | 难民保护委员会 |
|---|---|---|
key-ferry.status | /key-ferry-status | status |
key-ferry.refresh | /key-ferry-refresh | refresh |
key-ferry.doctor | /key-ferry-doctor | doctor |
key-ferry.project.activate | /key-ferry-project-activate | activateProject |
key-ferry.project.refresh | /key-ferry-project-refresh | refresh({ scope: "project" }) |
key-ferry.project.doctor | /key-ferry-project-doctor | doctor({ scope: "project" }) |
重命名是故意突破0.1.0发布:否 varlock-*
命令别名保留.
刷新和医生报告安全生命周期和远程配置诊断.
项目命令选择活动的项目组;它们不激活
非活动项目 . activateProject 开始一次合格的手工项目
当前位置。 它们不提供证明提示或收集
证书。 医生可以
调和或重建选中的不健康 oauth:false 远程中继器
Varlock 准备成功, 因此认证仍然取决于配置
瓦洛克语境.
本地插件激活并不意味着经纪人准备 。 启动期间, 映射的服务器在编组准备就绪之前一直关闭;一个健康组 如果另一组失败,则继续。 残疾融合不注册 状态RPC,所以预计为404.
运输和生命周期限制
中继支持可流式 HTTP POST/GET/DELETE,流式SSE,范围化 回回认证、 限定请求处理和会话 URL 重写 用于遗留的SSE端点。 现代可流化的HTTP和遗留的SSE反应是: 通过边框流; 压缩或过大流量未关闭 内。 在最多256个注册会话时保持中继功能 路线; 重复登记不消耗容量, 新路线为 盖后被拒绝。 Varlock 刷新时重新设置本地 MCP 会话状态 更改管理器生成或替换中继器时。 现有远程 课程必须重新连接.
Varlock的公用CA在IO边界被读取并被接力所信任. 这个
CA不是一个秘密,而原始的秘密值仍然留在OpenCode之外. 这是
不是一个完整的响应内容洗涤器,也不替换原生 OAuth .
公共CA使用 瓦洛克的要求 0644 信任-物质权限.
清理范围仅限于此项目实例,从未执行全局
瓦洛克关闭.
已打包的根, TUI, 和中继导入路径一起验证 。 无包装 需要进程.
核查
bun typecheck
bun test
bun run build
涵盖范围、事由和每个功能的《加拿大区域行动方案》门的细节记录如下: 质量检查。 。 。 .
两次现场的Varlock测试被锁定并跳过,除非
VARLOCK_LIVE_BINARY 指向绝对的 CLI 路径。 它使用合成
固定装置和孤立的配置。 没有每个测试主机证书或提供者
需要认证。 明确使用:
VARLOCK_LIVE_BINARY=/absolute/path/to/varlock bun test tests/varlock-live.test.ts
VARLOCK_LIVE_BINARY=/absolute/path/to/varlock bun test tests/remote-varlock-live.test.ts
普通的套房和有门的活装置是独立的核查层. 运行 ; 不将普通套件当作 认证每个外部MCP供应商、生产部署或现场 OpenCode TUI 会话.
见 建筑, (中文(简体) ), 解决问题,以及 质量检查, (中文(简体) ), 单项目实例, (中文(简体) ), 全球配置实例,以及 项目文件示例。 。 。 .