架构提案：面向多用户产品的连接归属与作用域授权

[D36u99er]

背景

我们正在评估把 OpenConnector 作为一个多用户产品中的连接器执行后端。当前的本地单用户模型很清晰：连接由 service + connection_name 标识，调用方通过运行令牌执行动作。这很适合个人使用或少量可信成员共享一个运行实例。

当同一个运行实例服务多个终端用户或多个工作空间时，还需要回答几个安全问题：

• 一个连接属于哪个外部用户或工作空间？
• 调用方是否有权发现和使用这个连接？
• 能否防止调用方通过猜测或自行传入 connection_name 使用别人的连接？
• OAuth 授权完成后，如何把凭据安全地绑定回发起授权的用户和空间？
• 审计记录能否说明“谁在什么空间，用哪个连接执行了什么动作”？

Roadmap #65 已经规划了运行令牌级动作策略，同时把完整角色权限、多租户团队权限、组织和用户管理列为当前非目标。我认同 OpenConnector 不应该自行建设一套用户、组织或登录系统；但可以考虑提供一层通用的“外部身份上下文和连接归属”能力，让上层产品负责身份与组织管理，OpenConnector 只负责隔离、授权和执行。

目标

希望在不引入完整用户系统的前提下，支持以下能力：

1. 每个连接都有明确且不可伪造的归属范围。
2. 运行令牌只能访问被授权范围内的连接和动作。
3. 执行时由服务端根据身份上下文解析连接，而不是信任调用方任意指定别名。
4. OAuth 状态与连接归属、发起者及回跳上下文绑定。
5. 审计记录包含调用主体、归属范围、连接引用和追踪标识。
6. 现有单用户部署保持完全向后兼容。

建议的抽象

为了避免 OpenConnector 耦合某一种组织模型，可以只引入两个不透明标识：

• namespace_id：外部系统中的租户、项目或工作空间。
• subject_id：外部系统中的用户、服务账号或代理主体。

OpenConnector 不解释这两个标识，也不管理它们的生命周期，只把它们作为授权和数据隔离上下文。

连接可以增加以下归属信息：

interface ConnectionOwnership {
  namespaceId: string;
  ownerSubjectId?: string;
  visibility: "private" | "namespace";
}

• private：只有连接所有者可以使用。
• namespace：同一范围内、具备相应权限的主体可以使用。
• 现有连接可迁移到默认命名空间，保持当前行为不变。

运行令牌与执行上下文

可以在 Roadmap #65 的“运行令牌级动作规则”基础上继续扩展：

interface RuntimePrincipal {
  tokenId: string;
  subjectId?: string;
  namespaceIds?: string[];
  allowedActions?: string[];
  blockedActions?: string[];
}

每次执行先完成：

1. 验证运行令牌并得到主体及允许访问的范围。
2. 校验动作策略。
3. 在允许的范围内解析连接引用。
4. 校验连接可见性和所有权。
5. 执行动作并写入带身份上下文的审计记录。

公开运行接口最好使用不可枚举的 connection_id 或服务端解析出的连接引用。connection_name 可以继续作为本地管理别名，但不应独立构成跨用户环境中的授权依据。

OAuth 上下文

建议待授权状态增加：

interface OAuthAuthorizationContext {
  namespaceId: string;
  subjectId: string;
  connectionId?: string;
  correlationId?: string;
  returnUrl?: string;
}

其中 returnUrl 必须经过配置白名单校验，避免开放重定向。OAuth 回调完成后，运行时根据服务端保存的状态写入连接归属，不接受浏览器在回调阶段重新指定归属。

存储与隔离

SQLite 和 D1 都可以通过向现有表增加归属字段与组合索引实现第一版：

• connections：增加内部连接标识、命名空间、所有者和可见性。
• runtime_tokens：增加主体与授权范围，或者拆分令牌和范围关联表。
• oauth_states：保存授权发起时的身份上下文。
• runs：记录令牌、主体、命名空间、连接和追踪标识。

所有查询都应把归属范围作为存储层接口的必填上下文，避免只依赖路由层约定。未来增加其他数据库实现时，也可以沿用同一存储契约。

明确不做的事情

这个提案不要求 OpenConnector 实现：

• 用户注册和登录界面。
• 组织、成员和角色管理。
• 通用角色权限系统。
• 审批工作流。
• 计费和额度系统。

这些仍由上层产品负责。OpenConnector 只接收已经验证的外部身份上下文，并确保连接、令牌和执行记录不会跨范围泄露。

建议的实施顺序

1. 先定义执行身份上下文、连接归属接口和兼容迁移方案。
2. 扩展运行令牌，使其能绑定主体、范围和动作策略。
3. 在连接查询与动作执行路径强制执行归属校验。
4. 为 OAuth 状态补充归属和安全回跳上下文。
5. 扩展审计记录、管理接口、控制台和文档。
6. 增加跨用户访问、别名猜测、令牌越权和 OAuth 状态篡改测试。

我们愿意贡献

如果维护者认可这个方向，我们愿意继续整理架构决策、数据库迁移和接口兼容设计，并承担其中一部分实现与测试。比较合适的第一步可能是：

• 先提交执行身份上下文和连接归属的数据模型。
• 再基于 Roadmap Roadmap #65 的运行令牌级动作策略，实现范围受限的令牌。
• 用完整测试证明现有单用户模式行为不变，同时阻止跨范围访问。

希望先确认几个问题：

1. “外部身份上下文 + 连接归属”是否符合项目边界，还是维护者更倾向于每个用户独立部署运行实例？
2. 使用不透明的 namespace_id / subject_id，是否比内建租户、工作空间和用户模型更符合项目方向？
3. 是否可以把 Roadmap Roadmap #65 的运行令牌级动作策略作为这项能力的第一个接入点？
4. 维护者更希望先看到架构决策和数据迁移设计，还是一个最小可运行的拉取请求？

[l1shen]

感谢整理这份提案。我们认同其中的核心判断：当一个运行实例中存在多组连接时，仅靠调用方传入 connection_name，无法形成可靠的资源授权边界。运行令牌、OAuth 状态和审计记录也需要一套一致且不可伪造的连接上下文。

不过，我们对 OpenConnector 的职责边界有不同看法。

OpenConnector 不关心一个运行实例最终服务一个还是多个外部主体，也不应该理解上层产品里的用户、组织、成员或工作空间模型。用户身份、连接归属、成员权限和组织级审计仍应以上层产品为准。

基于这个边界，我们暂时不打算在 OpenConnector 的核心模型中引入 subject_id、连接所有者、private / namespace 可见性或完整的外部身份上下文。我们想先确认一个更通用的资源 scope 能否覆盖这些场景。

这里的 scope 是一个不透明的资源隔离范围。OpenConnector 不解释它代表 workspace、project、environment 还是其他外部概念，只保证连接和运行凭证不能跨 scope 访问资源。

概念上可以理解为：

interface Connection {
  id: string;
  scope: string;
  service: string;
  connectionName: string;
}

interface RuntimeTokenRecord {
  id: string;
  tokenHash: string;
  scope: string;
  allowedActions?: string[];
  blockedActions?: string[];
  expiresAt?: string;
  revokedAt?: string;
}

外部调用方不直接传递 RuntimeGrant，也不能在运行请求中指定或覆盖 scope。调用方只发送 opaque runtime token 和目标 connectionId：

Authorization: Bearer
connectionId:

OpenConnector 验证 token 后，根据服务端保存的 token record 生成内部授权结果：

interface RuntimeGrant {
  tokenId: string;
  scope: string;
  allowedActions?: string[];
  blockedActions?: string[];
}

之后，OpenConnector 使用 grant.scope + connectionId 解析连接并校验动作策略。跨 scope 查询按连接不存在处理，避免泄露目标连接是否存在。

外部产品可以按下面的流程接入：

外部系统验证用户和 workspace 权限
-> 选择该 workspace 对应的 runtime token
-> OpenConnector 从 token 解析 scope 和动作策略
-> 在该 scope 内解析连接并执行动作

这样既能由 OpenConnector 强制实施资源隔离，也不需要它知道一个 scope 背后有多少用户，更不用管理用户、组织、成员关系或 RBAC。

对于 runtime token 的生命周期，我们会区分可更新的授权策略和不可变的安全域：

• name、allowedActions、blockedActions 和过期时间可以更新；
• token 可以随时撤销，权限变更应在后续请求中生效；
• token 绑定的 scope 创建后不能修改；
• 如需切换 scope，应创建新 token 并撤销旧 token。

这可以避免已经分发的 token 在调用方不知情时被切换到另一个资源范围。

另外还有几条原则：

1. 连接应有稳定且不可枚举的内部 ID。
2. connection_name 可以继续作为 scope 内的管理别名，但不能单独作为授权依据。
3. 所有连接读取和执行路径都必须在已验证的 scope 内解析连接。
4. OAuth state 应在服务端绑定 scope 和目标连接，回调阶段不能重新指定。
5. OpenConnector 的审计记录可以包含 tokenId、scope、connectionId、actionId 和 traceId。
6. 用户和组织级审计仍由上层系统负责。
7. 现有的本地单用户模式可以使用内部默认 scope，保持目前的使用方式不变。

我们想确认的是：scope + runtime token 能否覆盖你提案里的实际接入场景？

如果不能，具体缺口是什么？例如：

• 某项授权必须由 OpenConnector 识别外部用户才能完成；
• 同一个 scope 内仍需由 OpenConnector 区分连接所有者；
• 上层系统无法通过不同的 scope 或 runtime token 表达 private / namespace 可见性；
• 某项安全约束必须由 OpenConnector 理解 subject_id 才能实现。