认证与安全设计：CopilotKit 的多层安全边界

认证与安全设计：CopilotKit 的多层安全边界

学习目标

理解 CopilotKit 的认证和安全架构：

• 前端认证：headers + credentials 模式
• 后端中间件鉴权
• Intelligence 模式的用户识别
• License 验证机制
• CORS 配置

前置知识

本章涉及安全沙箱和企业级安全的通用原理，建议先阅读：

• 安全沙箱设计

项目实践

前端认证

前端支持两种认证方式：

1. 自定义 Headers：

<CopilotKit
  runtimeUrl="/api/copilotkit"
  headers={{ Authorization: "Bearer token" }}
/>

2. HTTP-only Cookies（推荐）：

<CopilotKit
  runtimeUrl="/api/copilotkit"
  credentials="include"  // 浏览器自动携带 cookie
/>

关键安全建议（源码验证）：

• 避免在 headers 中暴露 API Key（前端代码对用户可见）
• 使用 credentials: "include" + HTTP-only cookie 是更安全的方案

ProxiedAgent 的 credentials 传递（源码验证）：

ProxiedCopilotRuntimeAgent 在所有 HTTP 请求中传递 credentials：
fetch(url, {
  ...requestInit,
  ...(this.credentials ? { credentials: this.credentials } : {})
})

后端中间件鉴权

beforeRequestMiddleware 是认证的最佳位置：

const runtime = new CopilotSseRuntime({
  agents: { ... },
  beforeRequestMiddleware: async ({ request }) => {
    const token = request.headers.get("Authorization");
    if (!isValidToken(token)) {
      return new Response("Unauthorized", { status: 401 });
    }
    // 可选：将用户信息附加到 request
  }
});

重要：中间件需要覆盖所有传输路径：

• REST 模式：/agent/{id}/run 等端点
• Single-endpoint 模式：统一的 POST 端点

Intelligence 模式用户识别

Intelligence 模式通过 identifyUser 回调提取用户身份：

const runtime = new CopilotIntelligenceRuntime({
  intelligence: copilotKitIntelligence,
  identifyUser: async (request) => {
    const session = await getSession(request);
    return {
      id: session.userId,
      name: session.userName
    };
  }
});

用途：

• 用户身份关联到线程（每个用户独立的对话历史）
• 审计日志记录
• License 验证归因

License 验证

createLicenseChecker 在服务侧验证 License Token：

验证机制（源码验证）：
const licenseToken = options.licenseToken ?? process.env.COPILOTKIT_LICENSE_TOKEN;
this.licenseChecker = createLicenseChecker(licenseToken);

环境变量：

• COPILOTKIT_LICENSE_TOKEN：License Token（运行时自动读取）

License 验证影响：

• 某些高级功能需要有效 License
• 遥测归因到 License 持有者

CORS 配置

fetch-cors.ts 处理跨域请求：

CORS 头设置（源码验证）：
- Access-Control-Allow-Origin
- Access-Control-Allow-Methods
- Access-Control-Allow-Headers
- Access-Control-Allow-Credentials（当 credentials 模式时）

credentials 模式的 CORS 约束：

• Access-Control-Allow-Origin 不能是 *，必须是具体 origin
• Access-Control-Allow-Credentials: true 必须设置

前端工具的安全边界

前端工具在用户浏览器中执行，安全考虑：

风险	缓解
Agent 生成的恶意工具参数	前端工具 handler 应验证输入参数
工具结果泄露敏感数据	结果通过 SSE 传输 → Agent 可见；避免传递密码等
Catch-all handler 执行未知工具	Catch-all 仅渲染 UI，不自动执行

问题与规避

问题	规避策略
前端 headers 中的 token 被 XSS 窃取	使用 HTTP-only cookie + credentials: "include"
中间件遗漏 single-endpoint 路径	确保中间件同时覆盖 REST 和 single-endpoint 的入口点
CORS credentials 模式配置错误	Origin 必须是具体域名，不能用 *
Intelligence 模式的 identifyUser 抛出异常	添加 try/catch 兜底；返回匿名身份信息

设计取舍

Headers vs Cookies

维度	Headers (Bearer Token)	Cookies (HTTP-only)
安全性	低（前端代码可见）	高（JS 无法读取）
实现复杂度	低	中（需要服务端 cookie 设置）
跨域支持	需要 CORS 配置	需要 credentials: "include" + 具体 origin
推荐场景	开发环境	生产环境

中间件鉴权 vs 端点级鉴权

中间件鉴权（CopilotKit 的选择）：

• 优势：统一位置，不遗漏
• 代价：需要了解中间件的执行时机

端点级鉴权：

• 优势：更灵活（不同端点不同策略）
• 代价：容易遗漏某些端点

参考来源

• packages/core/src/agent.ts（credentials 传递）
• packages/runtime/src/v2/runtime/core/fetch-cors.ts
• packages/runtime/src/v2/runtime/core/middleware.ts
• packages/runtime/src/v2/runtime/core/runtime.ts（identifyUser、licenseChecker）
• @copilotkit/license-verifier 包