feat(server): add trusted auth mode for tenant headers

[zhoujh01]

Trusted 模式多租户访问设计方案

Summary

新增一个独立于现有 dev 模式和 api_key 模式的 trusted 认证模式，用于“受信任网络中的无 key 多
租户访问”。在该模式下，服务端不要求 X-API-Key，而是要求请求显式携带 X-OpenViking-Account、
X-OpenViking-User，并可选携带 X-OpenViking-Agent。服务端直接基于这些请求头构造
RequestContext，从而复用现有的数据隔离、文件系统路径隔离、VectorDB tenant filter 和
session/resource/search 等业务链路。

v1 明确不做 account/user 自动创建，不写 accounts.json、users.json，也不让 trusted 模式承担
Admin 管理面职责。这样可以避免引入创建竞态、分布式一致性、缓存失效和注册表膨胀问题，同时满
足“无需显式创建 account/user，也无需传 api key”的核心目标。

Key Changes

1. 认证模式与配置

• 在 server 配置中新增认证模式字段，替代当前“通过是否配置 root_api_key 推断模式”的单一路
  径。
• 建议新增：
  • server.auth_mode: "api_key" | "trusted"
• 模式语义：
  • api_key：保持现有行为不变
  • trusted：不要求 X-API-Key，改为信任 X-OpenViking-* 身份头
• root_api_key 仅在 api_key 模式下生效；trusted 模式下可忽略或禁止同时配置，避免语义混乱。
• 启动校验中新增 trusted 模式专属提示：
  • 明确声明这是“受信任网络模式”，不是公网匿名模式
  • 若绑定到非 localhost 地址，不报“未配置 root_api_key 的 dev 模式错误”，但输出高风险告
    警日志

2. 身份解析与 RequestContext

• 修改 openviking/server/auth.py 的身份解析流程：
  • 按 auth_mode 分支解析身份
  • trusted 模式下：
    • 强制要求 X-OpenViking-Account
    • 强制要求 X-OpenViking-User
    • X-OpenViking-Agent 可选，默认 "default"
    • 缺失 account/user 时，对 tenant-scoped API 直接返回参数错误
• trusted 模式下构造的身份：
  • role = USER
  • account_id = X-OpenViking-Account
  • user_id = X-OpenViking-User
  • agent_id = X-OpenViking-Agent or "default"
• 禁止任何隐式回退到 default/default
• 保持 RequestContext(UserIdentifier(account_id, user_id, agent_id), role) 结构不变，确保后
  续链路无需改动

3. 数据面行为

• 不修改 VikingFS、VectorDB、Session、Resource、Search 的 tenant 行为
• 依赖现有 RequestContext 继续完成：
  • AGFS 路径映射到对应 account/user/agent 作用域
  • VectorDB 基于 ctx.account_id、owner_space 做过滤
  • session / resource / search / fs / relations / pack 等接口按现有多租户逻辑工作
• 因为 trusted 模式下不自动创建注册表实体，所以“数据面可用”与“控制面登记”解耦
• 首次访问某个新 account/user 时，只要业务链路本身支持按路径懒创建目录，就允许直接使用；不
  要求存在于 accounts.json/users.json

4. Admin 与权限边界

• trusted 模式默认只面向数据面，不承担控制面
• 默认角色固定为 USER
• 因此：
  • 普通接口可访问：fs、search/find、resources、sessions、relations、pack、content 等依赖
    get_request_context 的接口
  • 管理接口不可访问：/api/v1/admin/**
• admin 路由现有 require_role(Role.ROOT / ADMIN) 逻辑保持不变
• 文档中明确声明：
  • trusted 模式适合“由调用方或网关提供租户身份”的访问场景
  • 若需要账号列表、用户列表、角色管理、发 key、删账号等控制面能力，仍应使用现有 api_key
    模式

5. 客户端与 HTTP 约定

• 复用现有请求头，不新增 wire format：
  • X-OpenViking-Account
  • X-OpenViking-User
  • X-OpenViking-Agent
• CLI/ovcli.conf 暂不纳入本次设计范围；v1 先保证 direct HTTP / SDK 可用
• 文档中给出典型 curl 示例：
  • add-resource
  • find
  • sessions -> messages -> commit
• 若后续要支持 CLI，可作为单独后续计划，新增：
  • ovcli.conf.account_id
  • ovcli.conf.user_id
  • client.rs 自动发送 X-OpenViking-Account/User

Test Plan

配置与启动

• auth_mode=api_key 时，现有行为完全不变
• auth_mode=trusted 时，服务启动成功且不要求 root_api_key
• trusted 模式绑定非 localhost 地址时，打印明确风险警告
• 非法 auth_mode 配置启动失败

身份解析

• trusted 模式下，带 X-OpenViking-Account/User 且不带 X-API-Key 的请求成功
• 缺失 X-OpenViking-Account 请求失败
• 缺失 X-OpenViking-User 请求失败
• 缺失 X-OpenViking-Agent 时，agent_id 默认为 "default"
• trusted 模式下不会回退到 default/default

数据面接口

• POST /api/v1/resources 在 trusted 模式下可正常写入租户资源
• POST /api/v1/search/find 只能检索到对应 account/user 可见的数据
• POST /api/v1/sessions、/messages、/commit 可正常工作
• 不同 account/user 头之间保持隔离
• 同一 account 不同 user 下的 user/agent/session scope 保持隔离
• resources 共享范围行为与现有 tenant filter 保持一致

权限边界

• 失败码与错误信息清晰表明“当前模式/角色无权访问管理接口”

回归验证

• 现有 api_key 多租户测试全部保持通过

Assumptions and Defaults

• trusted 模式用于受信任内网、服务网格、反向代理后或受控调用方，不面向公网匿名调用
• v1 不做 Auto-provision
• v1 不写 accounts.json/users.json
• v1 默认角色固定为 USER
• v1 不支持通过 trusted 模式访问 Admin 控制面
• v1 只复用现有 X-OpenViking-* 头，不引入可配置上游头名映射

[github-actions]

Failed to generate code suggestions for PR