8.3 MCP OAuth 认证

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

远程 MCP Server 通常需要认证才能访问。与内部 API 使用简单的 API Key 不同，MCP 协议采用了业界标准的 OAuth 2.0 协议作为认证方案。OpenCode 实现了完整的 OAuth 2.0 授权码流程（Authorization Code Flow），包括 PKCE 扩展、动态客户端注册、本地回调服务器等。本节将逐一解析这些组件的源码实现。

衍生解释：OAuth 2.0 与 Authorization Code Flow

OAuth 2.0 是一个开放的授权标准，被 Google、GitHub、Microsoft 等几乎所有主流互联网服务采用。它的核心思想是：用户可以授权第三方应用（如 OpenCode）访问自己在某个服务上的资源，而无需将自己的密码告诉第三方应用。

Authorization Code Flow（授权码流程）是 OAuth 2.0 中最安全的授权方式，流程如下：

1. 应用将用户重定向到授权服务器的登录页面。

2. 用户在授权服务器上登录并同意授权。

3. 授权服务器将用户重定向回应用，URL 中携带一个"授权码"（authorization code）。

4. 应用使用授权码向授权服务器换取"访问令牌"（access token）。

5. 应用使用访问令牌访问用户的资源。

PKCE（Proof Key for Code Exchange） 是对 Authorization Code Flow 的安全增强，专门为"公共客户端"（如 CLI 应用，无法安全存储 client_secret）设计。它在流程中引入了一对 code_verifier（随机字符串）和 code_challenge（其哈希值），确保即使授权码被截获，攻击者也无法使用它来换取访问令牌。

8.3.1 mcp/auth.ts：认证凭据存储

OAuth 认证涉及多种需要持久化存储的数据——访问令牌、刷新令牌、客户端注册信息、PKCE 的 code verifier、CSRF 防护的 state 参数等。McpAuth 模块负责管理这些数据的存储和读取。

数据模型

// mcp/auth.ts
export namespace McpAuth {
  // OAuth 令牌
  export const Tokens = z.object({
    accessToken: z.string(),             // 访问令牌
    refreshToken: z.string().optional(), // 刷新令牌（可选）
    expiresAt: z.number().optional(),    // 过期时间（Unix 时间戳）
    scope: z.string().optional(),        // 授权范围
  })

  // 客户端注册信息（来自动态客户端注册）
  export const ClientInfo = z.object({
    clientId: z.string(),                      // 客户端 ID
    clientSecret: z.string().optional(),        // 客户端密钥
    clientIdIssuedAt: z.number().optional(),    // 颁发时间
    clientSecretExpiresAt: z.number().optional(), // 过期时间
  })

  // 完整的认证条目
  export const Entry = z.object({
    tokens: Tokens.optional(),           // OAuth 令牌
    clientInfo: ClientInfo.optional(),   // 客户端信息
    codeVerifier: z.string().optional(), // PKCE code verifier
    oauthState: z.string().optional(),   // CSRF state 参数
    serverUrl: z.string().optional(),    // 这些凭据对应的服务器 URL
  })
}

每个 MCP Server 对应一个 Entry，包含了完整的 OAuth 生命周期中所有需要持久化的数据。

存储位置与安全性

认证数据存储在用户的全局数据目录中：

const filepath = path.join(Global.Path.data, "mcp-auth.json")
// 典型路径: ~/.local/share/opencode/mcp-auth.json

写入时使用了 0o600 的文件权限，这意味着只有文件所有者（当前用户）可以读写，其他用户和组无权访问：

await Bun.write(file, JSON.stringify(data, null, 2), { mode: 0o600 })

衍生解释：Unix 文件权限 0o600

在 Unix/Linux 系统中，文件权限由三组 rwx（读/写/执行）位组成，分别对应文件所有者、所属组、其他用户。0o600 以八进制表示，展开为 rw-------：

• 所有者（owner）：可读可写（6 = 4+2）

• 所属组（group）：无权限（0）

• 其他用户（others）：无权限（0）

这是存储敏感凭据文件的标准权限设置，类似于 SSH 的 ~/.ssh/id_rsa 文件的权限要求。

URL 绑定验证

McpAuth 模块实现了一个重要的安全特性——URL 绑定验证。每组凭据都记录了它们对应的服务器 URL，读取时会验证当前 URL 是否匹配：

export async function getForUrl(
  mcpName: string,
  serverUrl: string
): Promise<Entry | undefined> {
  const entry = await get(mcpName)
  if (!entry) return undefined

  // 如果没有存储 serverUrl（旧版本数据），认为无效
  if (!entry.serverUrl) return undefined

  // 如果 URL 发生了变化，凭据无效
  if (entry.serverUrl !== serverUrl) return undefined

  return entry
}

这个设计防止了一个微妙但严重的安全问题：如果用户修改了 MCP Server 的 URL（例如从一个可信的服务器改为一个恶意的服务器），旧的令牌不应该被发送到新的 URL。getForUrl() 通过比对 URL 来确保凭据不会被误用。

CRUD 操作

McpAuth 提供了一组原子化的更新函数，每个函数只修改 Entry 中的特定字段：

// 更新 OAuth 令牌
export async function updateTokens(
  mcpName: string, tokens: Tokens, serverUrl?: string
): Promise<void> {
  const entry = (await get(mcpName)) ?? {}
  entry.tokens = tokens
  await set(mcpName, entry, serverUrl)
}

// 更新客户端注册信息
export async function updateClientInfo(
  mcpName: string, clientInfo: ClientInfo, serverUrl?: string
): Promise<void> { ... }

// 更新 PKCE code verifier
export async function updateCodeVerifier(
  mcpName: string, codeVerifier: string
): Promise<void> { ... }

// 更新 CSRF state 参数
export async function updateOAuthState(
  mcpName: string, oauthState: string
): Promise<void> { ... }

// 检查令牌是否过期
export async function isTokenExpired(mcpName: string): Promise<boolean | null> {
  const entry = await get(mcpName)
  if (!entry?.tokens) return null     // 无令牌
  if (!entry.tokens.expiresAt) return false  // 无过期时间，永不过期
  return entry.tokens.expiresAt < Date.now() / 1000  // 与当前时间比较
}

8.3.2 mcp/oauth-provider.ts：OAuth Provider 实现

McpOAuthProvider 类实现了 MCP SDK 定义的 OAuthClientProvider 接口，它是 OAuth 流程中的"桥梁"——将 MCP SDK 的 OAuth 需求映射到 OpenCode 的凭据存储系统。

接口实现

export class McpOAuthProvider implements OAuthClientProvider {
  constructor(
    private mcpName: string,      // MCP Server 名称（作为存储的 key）
    private serverUrl: string,     // Server URL（用于 URL 绑定验证）
    private config: McpOAuthConfig,  // 用户提供的 OAuth 配置
    private callbacks: McpOAuthCallbacks,  // 回调（如 onRedirect）
  ) {}

OAuthClientProvider 接口要求实现以下方法，每个方法对应 OAuth 流程中的一个步骤：

回调 URL

get redirectUrl(): string {
  return `http://127.0.0.1:${OAUTH_CALLBACK_PORT}${OAUTH_CALLBACK_PATH}`
  // → http://127.0.0.1:19876/mcp/oauth/callback
}

OAuth 流程需要一个回调 URL，授权服务器在用户授权后会将浏览器重定向到这个 URL。OpenCode 使用本地 HTTP 服务器（端口 19876）来接收这个回调——这是 CLI 应用实现 OAuth 的标准做法。

客户端元数据

get clientMetadata(): OAuthClientMetadata {
  return {
    redirect_uris: [this.redirectUrl],
    client_name: "OpenCode",
    client_uri: "https://opencode.ai",
    grant_types: ["authorization_code", "refresh_token"],
    response_types: ["code"],
    token_endpoint_auth_method: this.config.clientSecret
      ? "client_secret_post"  // 有密钥：通过 POST body 传递
      : "none",               // 无密钥：公共客户端
  }
}

这些元数据在动态客户端注册（RFC 7591）时使用。注意 token_endpoint_auth_method 的动态选择——如果用户配置了 clientSecret，使用 client_secret_post 方式认证；否则标记为公共客户端（none），依赖 PKCE 保障安全。

客户端信息获取

async clientInformation(): Promise<OAuthClientInformation | undefined> {
  // 1. 优先使用用户配置的 clientId
  if (this.config.clientId) {
    return {
      client_id: this.config.clientId,
      client_secret: this.config.clientSecret,
    }
  }

  // 2. 其次使用之前动态注册获取的客户端信息
  const entry = await McpAuth.getForUrl(this.mcpName, this.serverUrl)
  if (entry?.clientInfo) {
    // 检查客户端密钥是否过期
    if (entry.clientInfo.clientSecretExpiresAt &&
        entry.clientInfo.clientSecretExpiresAt < Date.now() / 1000) {
      log.info("client secret expired, need to re-register", { ... })
      return undefined  // 过期了，需要重新注册
    }
    return {
      client_id: entry.clientInfo.clientId,
      client_secret: entry.clientInfo.clientSecret,
    }
  }

  // 3. 都没有 → 返回 undefined，触发动态客户端注册
  return undefined
}

衍生解释：动态客户端注册（RFC 7591）

在传统的 OAuth 中，第三方应用需要预先在授权服务器上注册，获取 client_id 和 client_secret。但对于开源的 CLI 工具来说，这种预注册模式并不实用——用户可能需要连接到任意的授权服务器。

RFC 7591 定义了"动态客户端注册"协议，允许客户端在运行时通过 HTTP 请求向授权服务器注册自己，自动获取 client_id。MCP SDK 内置了对这一协议的支持，当 clientInformation() 返回 undefined 时，SDK 会尝试动态注册。

令牌管理

// 读取已存储的令牌
async tokens(): Promise<OAuthTokens | undefined> {
  const entry = await McpAuth.getForUrl(this.mcpName, this.serverUrl)
  if (!entry?.tokens) return undefined

  return {
    access_token: entry.tokens.accessToken,
    token_type: "Bearer",
    refresh_token: entry.tokens.refreshToken,
    expires_in: entry.tokens.expiresAt
      ? Math.max(0, Math.floor(entry.tokens.expiresAt - Date.now() / 1000))
      : undefined,
    scope: entry.tokens.scope,
  }
}

// 保存新的令牌
async saveTokens(tokens: OAuthTokens): Promise<void> {
  await McpAuth.updateTokens(this.mcpName, {
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
    expiresAt: tokens.expires_in
      ? Date.now() / 1000 + tokens.expires_in
      : undefined,
    scope: tokens.scope,
  }, this.serverUrl)
}

注意 tokens() 方法中 expires_in 的计算——它将绝对过期时间（expiresAt，Unix 时间戳）转换为相对剩余时间（expires_in，秒数），因为 OAuth 标准使用相对时间格式。

PKCE 和 State 参数

// 保存 PKCE code verifier
async saveCodeVerifier(codeVerifier: string): Promise<void> {
  await McpAuth.updateCodeVerifier(this.mcpName, codeVerifier)
}

async codeVerifier(): Promise<string> {
  const entry = await McpAuth.get(this.mcpName)
  if (!entry?.codeVerifier) {
    throw new Error(`No code verifier saved for MCP server: ${this.mcpName}`)
  }
  return entry.codeVerifier
}

// 保存 CSRF state 参数
async saveState(state: string): Promise<void> {
  await McpAuth.updateOAuthState(this.mcpName, state)
}

async state(): Promise<string> {
  const entry = await McpAuth.get(this.mcpName)
  if (!entry?.oauthState) {
    throw new Error(`No OAuth state saved for MCP server: ${this.mcpName}`)
  }
  return entry.oauthState
}

这些方法由 MCP SDK 在 OAuth 流程的不同阶段调用。codeVerifier 用于 PKCE 安全机制，state 用于 CSRF（跨站请求伪造）防护——两者都是 OAuth 安全最佳实践的关键组件。

8.3.3 mcp/oauth-callback.ts：OAuth 回调处理

在 OAuth 的 Authorization Code Flow 中，用户在浏览器中完成授权后，授权服务器需要将授权码回传给应用。对于 CLI 应用来说，接收这个回调的唯一方式是在本地启动一个 HTTP 服务器。McpOAuthCallback 模块正是负责这个任务的。

回调服务器

export namespace McpOAuthCallback {
  let server: ReturnType<typeof Bun.serve> | undefined
  const pendingAuths = new Map<string, PendingAuth>()  // state → PendingAuth
  const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000  // 5 分钟超时

  export async function ensureRunning(): Promise<void> {
    if (server) return  // 已经在运行

    // 检查端口是否被占用（可能另一个 OpenCode 实例已经启动了回调服务器）
    const running = await isPortInUse()
    if (running) {
      log.info("oauth callback server already running on another instance", ...)
      return
    }

    server = Bun.serve({
      port: OAUTH_CALLBACK_PORT,  // 19876
      fetch(req) {
        const url = new URL(req.url)

        // 只处理回调路径
        if (url.pathname !== OAUTH_CALLBACK_PATH) {
          return new Response("Not found", { status: 404 })
        }

        // 从 URL 参数中提取关键信息
        const code = url.searchParams.get("code")
        const state = url.searchParams.get("state")
        const error = url.searchParams.get("error")
        // ...
      },
    })
  }
}

这个回调服务器基于 Bun 的内置 HTTP 服务器实现，监听固定端口 19876。值得注意的是 ensureRunning() 的幂等性设计——如果服务器已经在运行就直接返回，如果端口被占用（可能是另一个 OpenCode 实例）也不会报错。

CSRF 防护：State 参数验证

回调处理的核心是 State 参数的验证，这是防止 CSRF 攻击的关键：

// 1. 必须有 state 参数
if (!state) {
  const errorMsg = "Missing required state parameter - potential CSRF attack"
  return new Response(HTML_ERROR(errorMsg), { status: 400, ... })
}

// 2. state 必须匹配某个 pending 的认证请求
if (!pendingAuths.has(state)) {
  const errorMsg = "Invalid or expired state parameter - potential CSRF attack"
  return new Response(HTML_ERROR(errorMsg), { status: 400, ... })
}

State 参数的工作原理：

OpenCode                    浏览器                    授权服务器
  │                           │                         │
  │  生成随机 state 参数       │                         │
  │  存储在 pendingAuths 中   │                         │
  │                           │                         │
  │  打开授权 URL              │                         │
  │  (包含 state 参数) ───────►│ ─────────────────────► │
  │                           │                         │
  │                           │ ◄───────────────────── │
  │                           │  重定向回调 URL          │
  │                           │  (包含 code + state)    │
  │                           │                         │
  │ ◄─── HTTP 回调请求 ───────│                         │
  │  验证 state 匹配          │                         │
  │  提取 authorization code  │                         │

衍生解释：CSRF（跨站请求伪造）攻击

CSRF 攻击是一种让用户在不知情的情况下执行非预期操作的攻击方式。在 OAuth 场景中，攻击者可能诱导用户的浏览器向回调 URL 发送一个伪造的请求，试图将攻击者自己的授权码注入到受害者的应用中。

State 参数是 OAuth 2.0 推荐的 CSRF 防护机制。应用在发起授权请求时生成一个随机的 state 值并暂存，当回调到来时验证 state 是否匹配——只有从应用自身发起的授权流程才能通过这个验证。

State 参数的生成

在 startAuth() 函数中，state 参数使用密码学安全的随机数生成器创建：

// mcp/index.ts - startAuth()
const oauthState = Array.from(crypto.getRandomValues(new Uint8Array(32)))
  .map((b) => b.toString(16).padStart(2, "0"))
  .join("")
await McpAuth.updateOAuthState(mcpName, oauthState)

这生成了一个 64 字符的十六进制字符串（32 字节的随机数据），具有 256 位的熵——足以抵御暴力猜测攻击。

回调结果的传递

当回调成功到来时，通过 Promise 的 resolve 将授权码传递回等待的代码：

// 等待回调
export function waitForCallback(oauthState: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const timeout = setTimeout(() => {
      if (pendingAuths.has(oauthState)) {
        pendingAuths.delete(oauthState)
        reject(new Error("OAuth callback timeout - authorization took too long"))
      }
    }, CALLBACK_TIMEOUT_MS)  // 5 分钟超时

    pendingAuths.set(oauthState, { resolve, reject, timeout })
  })
}

这是一个经典的"Promise + 外部 resolve"模式——waitForCallback 创建一个 Promise 并将其 resolve 函数存储在 Map 中。当回调到来时，从 Map 中取出对应的 resolve 函数并调用，从而"解开"等待中的 Promise。

完整的认证流程

将所有组件串联起来，完整的 OAuth 认证流程如下：

export async function authenticate(mcpName: string): Promise<Status> {
  // 1. 发起 OAuth 流程，获取授权 URL
  const { authorizationUrl } = await startAuth(mcpName)

  if (!authorizationUrl) {
    // 已经认证过了
    return { status: "connected" }
  }

  // 2. 获取之前生成的 state 参数
  const oauthState = await McpAuth.getOAuthState(mcpName)

  // 3. 在打开浏览器之前注册回调监听（防止竞态条件）
  const callbackPromise = McpOAuthCallback.waitForCallback(oauthState)

  // 4. 打开浏览器让用户授权
  try {
    const subprocess = await open(authorizationUrl)
    // 等待500ms确认浏览器成功打开
    await new Promise<void>((resolve, reject) => {
      const timeout = setTimeout(() => resolve(), 500)
      subprocess.on("error", (error) => {
        clearTimeout(timeout)
        reject(error)
      })
      subprocess.on("exit", (code) => {
        if (code !== null && code !== 0) {
          clearTimeout(timeout)
          reject(new Error(`Browser open failed with exit code ${code}`))
        }
      })
    })
  } catch (error) {
    // 浏览器打开失败（如 SSH 远程环境），发布事件让 CLI 显示 URL
    Bus.publish(BrowserOpenFailed, { mcpName, url: authorizationUrl })
  }

  // 5. 等待回调（用户在浏览器中完成授权后）
  const code = await callbackPromise

  // 6. 验证 state 参数（CSRF 防护的最后一道关卡）
  const storedState = await McpAuth.getOAuthState(mcpName)
  if (storedState !== oauthState) {
    await McpAuth.clearOAuthState(mcpName)
    throw new Error("OAuth state mismatch - potential CSRF attack")
  }

  // 7. 清理 state 并完成认证（用授权码换取令牌）
  await McpAuth.clearOAuthState(mcpName)
  return finishAuth(mcpName, code)
}

这段代码中有一个巧妙的工程细节：在打开浏览器之前就注册回调监听（第 3 步）。这是为了避免一种竞态条件——如果用户的 IdP（身份提供者）有活跃的 SSO 会话，授权可能在浏览器打开后几乎立即完成，回调可能在 waitForCallback 注册之前就到达。通过先注册再打开浏览器，确保不会错过任何回调。

finishAuth() 函数完成最后一步——使用授权码换取访问令牌：

export async function finishAuth(
  mcpName: string,
  authorizationCode: string
): Promise<Status> {
  const transport = pendingOAuthTransports.get(mcpName)

  // 调用传输层的 finishAuth（由 MCP SDK 处理令牌交换）
  await transport.finishAuth(authorizationCode)

  // 清理 PKCE code verifier
  await McpAuth.clearCodeVerifier(mcpName)

  // 重新连接 MCP Server（这次应该能成功认证了）
  pendingOAuthTransports.delete(mcpName)
  const result = await add(mcpName, mcpConfig)
  return result.status[mcpName]
}

用户体验

OAuth 回调页面提供了友好的用户反馈。成功时：

<h1 style="color: #4ade80;">Authorization Successful</h1>
<p>You can close this window and return to OpenCode.</p>
<script>setTimeout(() => window.close(), 2000);</script>

页面会在 2 秒后自动关闭。失败时则显示详细的错误信息。

对于无法打开浏览器的环境（如 SSH 远程开发、Docker 容器等），OpenCode 会通过 Bus 事件系统发布 BrowserOpenFailed 事件，让 TUI 界面显示授权 URL 供用户手动复制到浏览器中打开。

---

本节小结

OpenCode 的 MCP OAuth 认证实现由三个模块组成：McpAuth 负责凭据的持久化存储（使用 0o600 权限保护文件安全），McpOAuthProvider 实现了 MCP SDK 的 OAuthClientProvider 接口（支持预注册客户端和动态客户端注册两种模式），McpOAuthCallback 通过本地 HTTP 服务器接收 OAuth 回调（端口 19876）。整个认证流程采用了 PKCE 扩展和 State 参数双重安全机制，并通过 URL 绑定验证防止凭据被误用到不同的服务器。值得注意的工程细节包括：先注册回调再打开浏览器以避免竞态条件、密码学安全的随机数生成、以及对无浏览器环境的优雅降级处理。