部署、安全模型与权限边界

这个模块只解决“可信组织内部”的访问问题

Background Agents（Open-Inspect）的部署安全模型建立在一个明确前提上：

这是一个单租户系统，适合部署在公司或团队内部，所有登录用户都被视为同一组织中的可信成员。

它不是面向 SaaS 多租户场景设计的。也就是说，系统默认：

登录进来的用户属于同一个组织或团队；
用户之间不需要严格的仓库级隔离；
GitHub App 能访问的仓库，原则上系统内用户都可能通过 Agent 访问；
重点防线放在“谁能进入系统”和“GitHub App 安装在哪些仓库”。

这个模块主要解释三件事：

单租户部署的安全边界；
GitHub App Token、用户 OAuth Token、Sandbox Token 等凭据如何分工；
实际部署时应该如何限制入口、仓库范围和 PR 创建行为。

GitHub App 负责代码读写，用户 OAuth 负责 PR 归属

Open-Inspect 的 GitHub 权限模型分成两条线：

凭据	主要用途	权限边界
GitHub App Token	`git clone`、`fetch`、`push` 等 Git 操作	GitHub App 被安装到的仓库
User OAuth Token	创建 PR、获取用户信息	当前 GitHub 用户有权限访问的仓库
Sandbox Auth Token	Sandbox 调用控制面接口	单个 session
WebSocket Token	实时会话鉴权	单个 session

其中最重要的是前两类。

GitHub App Token：共享的仓库访问身份

系统会安装一个 GitHub App 到组织仓库中。控制面在服务端生成短期的 GitHub App installation token，然后通过 git credential helper 按需提供给 sandbox。

这意味着：

sandbox 不需要长期保存 GitHub 凭据；
token 是短期的；
Git 操作统一使用 GitHub App 的权限；
GitHub App 安装到哪些仓库，系统就能对哪些仓库执行 Git 操作。

也意味着一个很关键的边界：

系统不会在创建 session 时逐个检查“当前用户是否有这个仓库的访问权限”。

只要用户已经进入系统，并且目标仓库在 GitHub App 的安装范围内，Agent 就可能访问该仓库。

User OAuth Token：用于 PR 创建和用户归属

用户通过 GitHub 登录时，系统会拿到该用户的 OAuth Token。这个 token 主要用于：

创建 Pull Request；
让 PR 归属到发起任务的用户；
受 GitHub 用户自身权限限制。

因此，PR 创建时通常有这样的行为：

如果用户通过 GitHub 登录，并且 OAuth Token 可用，则使用用户身份创建 PR；
GitHub 会检查该用户是否有目标仓库的写权限；
如果用户不是通过 GitHub 登录，例如 Google 登录，没有 SCM token，则 PR 创建会回退到共享的 GitHub App bot 身份。

这个设计保证了“PR 归属”尽量准确，但它并不等价于“session 创建前做了仓库级权限校验”。

session 创建不是权限隔离点

在这个项目的安全模型里，session 创建更接近“任务启动入口”，而不是强访问控制边界。

典型流程如下：

text
用户登录系统
    ↓
创建后台编码任务 / session
    ↓
控制面启动 sandbox
    ↓
sandbox 需要访问 Git 仓库
    ↓
控制面为 GitHub App 生成短期 installation token
    ↓
git credential helper 将 token 提供给 git clone/fetch/push
    ↓
Agent 修改代码、提交分支
    ↓
创建 PR 时优先使用用户 OAuth Token

需要特别注意：

text
用户能否创建某个仓库的 session
≠
用户本人在 GitHub 上是否有该仓库权限

真正决定 Git 操作能否成功的是：

text
GitHub App 是否安装到了该仓库

真正决定用户身份 PR 能否成功的是：

text
用户 OAuth Token 是否存在
+
该用户在 GitHub 上是否有目标仓库的写权限

部署入口应该放在 SSO、VPN 或组织身份之后

由于系统假设所有用户可信，推荐的部署方式是把 Open-Inspect 放在组织内部边界之后。

常见做法：

部署在公司 VPN 内；
放在已有 SSO 之后；
只允许公司邮箱域名登录；
只允许特定 GitHub 用户登录；
只允许特定 GitHub Organization 成员登录；
配置 ALLOWED_GITHUB_ORGS 限制活跃 GitHub 组织成员。

如果系统暴露在公网，必须至少做登录限制。否则任何能登录的人，都可能间接访问 GitHub App 覆盖的仓库。

GitHub App 的安装范围就是仓库访问边界

GitHub App 安装时，不建议选择：

text
All repositories

更推荐选择：

text
Only select repositories

也就是说，只把 App 安装到确实允许 Agent 访问的仓库。

例如，公司里有这些仓库：

text
org/web-app
org/backend-api
org/internal-payments
org/security-research

如果当前只希望 Agent 处理产品代码，不希望它接触安全研究仓库，那么 GitHub App 应只安装到：

text
org/web-app
org/backend-api

不要安装到：

text
org/security-research

因为一旦 App 安装到了某个仓库，系统内用户就可能通过 Agent session 间接访问它。

关键接口和凭据流转

Git credential helper 按需获取 GitHub App Token

Git 操作不是直接把 token 写死在 sandbox 中，而是通过 credential helper 按需获取。

简化后的职责是：

text
git clone / fetch / push
    ↓
git credential helper 请求凭据
    ↓
sandbox 使用 Sandbox Auth Token 调用控制面
    ↓
控制面确认 session
    ↓
控制面生成短期 GitHub App installation token
    ↓
返回给 git credential helper
    ↓
git 使用 token 完成操作

这个机制的好处是：

GitHub App Token 不需要长期存储在 sandbox；
token 生命周期短；
控制面可以把 token 绑定到当前 session；
sandbox 与控制面之间可以使用 session 级 token 做鉴权。

但它不提供：

每个用户对每个仓库的细粒度校验；
多租户之间的仓库隔离；
不同客户之间的数据隔离。

PR 创建优先使用用户 OAuth Token

PR 创建路径和 Git clone/push 不完全一样。

推荐理解成：

text
如果用户有 GitHub OAuth Token：
    用用户身份创建 PR
    GitHub 校验用户是否有写权限
否则：
    使用 GitHub App bot 身份创建 PR

这带来两个实际结果：

GitHub 登录用户创建的 PR attribution 更准确；
Google 登录、SSO 登录等没有 GitHub token 的用户，PR 可能显示为 bot 创建。

如果组织对代码归属有严格要求，建议强制使用 GitHub 登录，或者在任务入口处限制非 GitHub 登录用户创建 PR。

Sandbox Auth Token 只应该用于单个 session

Sandbox Auth Token 的边界是单个 session。它的职责是让 sandbox 能够调用控制面提供的 session 相关接口，例如请求 Git 凭据、回传状态等。

它不应该被设计成：

用户级长期 token；
跨 session token；
管理员 token；
可访问所有任务的 token。

如果需要排查问题，应从控制面日志定位 session，而不是把 sandbox token 扩大成全局调试凭据。

WebSocket Token 只负责实时会话

WebSocket Token 用于浏览器、协作界面或其他客户端连接实时 session。

它的边界也是单个 session，主要用于：

实时输出；
会话状态同步；
多人协作界面鉴权。

它不应该被复用为 GitHub 凭据，也不应该被用来访问其他 session。

可运行示例：检查当前部署策略是否符合单租户假设

下面这个脚本模拟 Open-Inspect 的权限模型：

登录限制使用邮箱域名和 GitHub 组织；
session 创建只检查“用户是否能进入系统”和“GitHub App 是否安装到仓库”；
PR 创建优先使用用户 OAuth Token；
非 GitHub 登录用户回退到 GitHub App bot。

保存为 security-model-demo.mjs：

js
const config = {
  allowedEmailDomains: ["example.com"],
  allowedGithubOrgs: ["acme"],
  githubAppInstalledRepos: [
    "acme/web-app",
    "acme/backend-api",
  ],
};

const users = [
  {
    name: "alice",
    loginType: "github",
    email: "alice@example.com",
    githubOrgs: ["acme"],
    hasGithubOAuthToken: true,
    githubWriteRepos: ["acme/web-app"],
  },
  {
    name: "bob",
    loginType: "google",
    email: "bob@example.com",
    githubOrgs: [],
    hasGithubOAuthToken: false,
    githubWriteRepos: [],
  },
  {
    name: "mallory",
    loginType: "github",
    email: "mallory@external.test",
    githubOrgs: ["other-org"],
    hasGithubOAuthToken: true,
    githubWriteRepos: ["acme/web-app"],
  },
];

function emailDomain(email) {
  return email.split("@")[1];
}

function canSignIn(user) {
  const domainAllowed = config.allowedEmailDomains.includes(emailDomain(user.email));
  const orgAllowed = user.githubOrgs.some((org) => config.allowedGithubOrgs.includes(org));

  // 实际部署可以二选一或同时要求，这里演示“邮箱域名或 GitHub 组织满足其一即可”
  return domainAllowed || orgAllowed;
}

function isRepoInGithubAppScope(repo) {
  return config.githubAppInstalledRepos.includes(repo);
}

function canCreateSession(user, repo) {
  if (!canSignIn(user)) {
    return {
      allowed: false,
      reason: "用户不满足登录限制",
    };
  }

  if (!isRepoInGithubAppScope(repo)) {
    return {
      allowed: false,
      reason: "GitHub App 未安装到该仓库",
    };
  }

  return {
    allowed: true,
    reason: "单租户模型下允许创建 session；未做用户级仓库权限校验",
  };
}

function resolvePullRequestActor(user, repo) {
  if (user.hasGithubOAuthToken) {
    const canWrite = user.githubWriteRepos.includes(repo);

    if (canWrite) {
      return {
        actor: user.name,
        method: "user-oauth-token",
        result: "PR 将以用户身份创建",
      };
    }

    return {
      actor: user.name,
      method: "user-oauth-token",
      result: "GitHub 会拒绝：用户没有该仓库写权限",
    };
  }

  return {
    actor: "github-app[bot]",
    method: "github-app-token",
    result: "用户没有 GitHub OAuth Token，回退到 GitHub App bot",
  };
}

const scenarios = [
  ["alice", "acme/web-app"],
  ["alice", "acme/backend-api"],
  ["bob", "acme/web-app"],
  ["mallory", "acme/web-app"],
  ["alice", "acme/security-research"],
];

for (const [userName, repo] of scenarios) {
  const user = users.find((u) => u.name === userName);
  const session = canCreateSession(user, repo);

  console.log(`\n用户: ${userName}`);
  console.log(`仓库: ${repo}`);
  console.log(`创建 session: ${session.allowed ? "允许" : "拒绝"}`);
  console.log(`原因: ${session.reason}`);

  if (session.allowed) {
    const pr = resolvePullRequestActor(user, repo);
    console.log(`PR 身份: ${pr.actor}`);
    console.log(`凭据: ${pr.method}`);
    console.log(`结果: ${pr.result}`);
  }
}

运行：

bash
node security-model-demo.mjs

示例输出：

text
用户: alice
仓库: acme/web-app
创建 session: 允许
原因: 单租户模型下允许创建 session；未做用户级仓库权限校验
PR 身份: alice
凭据: user-oauth-token
结果: PR 将以用户身份创建

用户: alice
仓库: acme/backend-api
创建 session: 允许
原因: 单租户模型下允许创建 session；未做用户级仓库权限校验
PR 身份: alice
凭据: user-oauth-token
结果: GitHub 会拒绝：用户没有该仓库写权限

用户: bob
仓库: acme/web-app
创建 session: 允许
原因: 单租户模型下允许创建 session；未做用户级仓库权限校验
PR 身份: github-app[bot]
凭据: github-app-token
结果: 用户没有 GitHub OAuth Token，回退到 GitHub App bot

用户: mallory
仓库: acme/web-app
创建 session: 拒绝
原因: 用户不满足登录限制

用户: alice
仓库: acme/security-research
创建 session: 拒绝
原因: GitHub App 未安装到该仓库

这个例子里的第二个场景很重要：

text
alice 可以创建 acme/backend-api 的 session
但 alice 没有该仓库写权限
所以使用用户 OAuth Token 创建 PR 会失败

这正是 Open-Inspect 单租户模型的核心边界：Git 操作依赖 GitHub App 的安装范围，而 PR 用户归属依赖用户 OAuth Token。

不适合直接用于多租户 SaaS

当前模型不适合这样的场景：

text
多个客户共用同一个 Open-Inspect 部署
每个客户只能访问自己的 GitHub 仓库
客户之间需要强数据隔离
不同客户使用不同计费、审计和权限策略

要支持多租户，至少需要补齐：

每个 tenant 独立 GitHub App installation；
session 创建时做 tenant 和仓库权限校验；
数据库模型中加入 tenant 隔离；
sandbox 运行环境按 tenant 隔离；
token、日志、任务队列、缓存都带 tenant 边界；
PR 创建、webhook、cron 触发都校验 tenant 归属。

否则，一个 tenant 的用户可能通过共享 GitHub App 访问另一个 tenant 的仓库，这是不可接受的。

容易误解的边界

“用户能登录”不等于“用户只能访问自己的仓库”

在单租户模型下，登录限制只控制谁能进入系统。进入系统之后，仓库访问能力主要取决于 GitHub App 安装范围。

“PR 用用户 OAuth Token 创建”不等于“所有 Git 操作都是用户身份”

Git clone、fetch、push 使用的是 GitHub App installation token。用户 OAuth Token 主要用于 PR 创建和用户信息。

“短期 token”不等于“仓库级最小权限”

短期 token 可以降低泄露后的影响时间，但 token 的仓库范围仍然来自 GitHub App installation scope。

如果 App 安装到了很多仓库，短期 token 仍然可能访问这些仓库。

“Sandbox Token 是单 session”不等于“sandbox 可以信任所有输入”

Sandbox 仍然会运行代码、执行命令、访问仓库内容。不要把不可信用户放进同一个部署，也不要让不可信任务共享组织内部 GitHub App。

部署前最后检查

上线前建议确认：

Web UI 是否放在 SSO、VPN 或其他组织身份边界后；
是否限制了允许登录的 GitHub 组织，例如 ALLOWED_GITHUB_ORGS；
GitHub App 是否只安装到了必要仓库；
是否接受“系统内用户可访问 App 覆盖仓库”的单租户假设；
是否明确非 GitHub 登录用户的 PR 会回退到 bot；
是否禁止把该部署提供给外部客户或不可信用户；
是否定期审计 GitHub App 安装范围；
是否把敏感仓库排除在 GitHub App 安装范围之外。

只要这些条件不成立，就应该先收紧部署边界，而不是把它当成多租户权限系统使用。

模块拆解：部署、安全模型与权限边界