API 与协议参考

本文是 WingGate 用户可见协议面（SSH 与 MCP）以及管理它们的 Web 控制台的地图。它刻意停留在工作概览层面，不重复字段表、wire schema 或状态机。

协议面一览

• SSH Gateway——WingGate 的 SSH 端点，接受 SSH 客户端连接。认证与授权由服务控制面完成，服务本身不监听 SSH TCP；启用 SSH Direct 的连接器另有本地 listener。
• MCP Streamable HTTP——面向 AI Agent 的工具面。端点位于 wing-connector 而非服务：连接器直接提供，并经反向传输把工具流量代理到目标。
• Web 控制台——管理组织、项目、资产、授权与审计的浏览器管理面，是管理服务的首要方式。

认证

• SSH Gateway 用户认证支持 SSH 公钥、keyboard-interactive password + OTP 与 Web 一次性授权；不支持普通 SSH password 方法。
• MCP 客户端使用绑定到项目的专用凭据认证；连接器在 session 初始化时固定凭据指纹并校验每次 session 请求。
• Web session、access token、MCP 凭据、Agent 凭据与 session stream token 是不同类别，绝不互换。敏感操作需要 reauth 流程；一次性 secret 只出现在专用创建响应中。

授权模型

两层固定授权，都 fail closed：

• 管理面——固定的 Owner/Admin/Member 角色矩阵管辖管理动作。
• 数据面——每次会话与每次文件/MCP 操作都必须有 (project, user) 的 active coarse 项目访问授权。角色绝不蕴含数据面访问。

授权规则由服务对每个请求强制执行；不存在可配置的规则引擎。

协议稳定性

• MCP 端点在会话建立时宣告其协议版本（写作时是 2025-06-18）与可用工具，客户端在运行时发现具体工具面，而不是依赖静态文档。
• 字段级细节随版本变化；以你实际连接的端点为准。

MCP 协议要点

• Streamable HTTP，协议版本 2025-06-18。POST 接受 application/json 与 text/event-stream；GET 是 SSE 流。
• 每个请求携带项目 MCP 凭据。wing-connector 在 session 初始化时固定凭据指纹并校验每次 session 请求；授权由服务控制面完成。
• 工具集按项目启用的工具组与被授权资产过滤——没有授权资产启用的工具不会出现在列表中。

审计

每次认证、会话、授权变更、文件操作与 MCP 调用都进入统一审计路径。审计是 append-only 且组织级作用域；按契约排除 secret 与载荷内容。