feat(mcp-oauth): add full OAuth 2.1 authentication for MCP servers (#1169)

* feat(mcp-oauth): add oauth field to ClaudeCodeMcpServer schema

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

* feat(mcp-oauth): add RFC 7591 Dynamic Client Registration

* feat(mcp-oauth): add RFC 9728 PRM + RFC 8414 AS discovery

* feat(mcp-oauth): add secure token storage with {host}/{resource} key format

* feat(mcp-oauth): add dynamic port OAuth callback server

* feat(mcp-oauth): add RFC 8707 Resource Indicators

* feat(mcp-oauth): implement full-spec McpOAuthProvider

* feat(mcp-oauth): add step-up authorization handler

* feat(mcp-oauth): integrate authProvider into SkillMcpManager

* feat(doctor): add MCP OAuth token status check

* feat(cli): add mcp oauth subcommand structure

* feat(cli): implement mcp oauth login command

* fix(mcp-oauth): address cubic review — security, correctness, and test issues

- Remove @ts-nocheck from provider.ts, storage.ts, provider.test.ts
- Fix server resource leak on missing code/state (close + reject)
- Fix command injection in openBrowser (spawn array args, cross-platform)
- Mock McpOAuthProvider in login.test.ts for deterministic CI
- Recreate auth provider with merged scopes in step-up flow
- Add listAllTokens() for global status listing
- Fix logout to accept --server-url for correct token deletion
- Support both quoted and unquoted WWW-Authenticate params (RFC 2617)
- Save/restore OPENCODE_CONFIG_DIR in storage.test.ts
- Fix index.test.ts: vitest → bun:test

* fix(mcp-oauth): use explorer instead of cmd /c start on Windows to prevent shell injection

* fix(mcp-oauth): address remaining cubic review issues

- Add 5-minute timeout to provider callback server to prevent indefinite hangs
- Persist client registration from token storage across process restarts
- Require --server-url for logout to match token storage key format
- Use listTokensByHost for server-specific status lookups
- Fix callback-server test to handle promise rejection ordering
- Fix provider test port expectations (8912 → 19877)
- Fix cli-guide.md duplicate Section 7 numbering
- Fix manager test for login-on-missing-tokens behavior

* fix(mcp-oauth): address final review issues

- P1: Redact token values in status.ts output to prevent credential leakage
- P2: Read OAuth error response body before throwing in token exchange
- Test: Fix mcp-oauth doctor test to use epoch seconds (not milliseconds)

---------

Co-authored-by: justsisyphus <justsisyphus@users.noreply.github.com>
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
YeonGyu-Kim
2026-01-29 19:48:36 +09:00
committed by GitHub
parent a94fbadd57
commit dcda8769cc
37 changed files with 3221 additions and 27 deletions
+3
View File
@@ -8,6 +8,7 @@ import { getDependencyCheckDefinitions } from "./dependencies"
import { getGhCliCheckDefinition } from "./gh"
import { getLspCheckDefinition } from "./lsp"
import { getMcpCheckDefinitions } from "./mcp"
import { getMcpOAuthCheckDefinition } from "./mcp-oauth"
import { getVersionCheckDefinition } from "./version"
export * from "./opencode"
@@ -19,6 +20,7 @@ export * from "./dependencies"
export * from "./gh"
export * from "./lsp"
export * from "./mcp"
export * from "./mcp-oauth"
export * from "./version"
export function getAllCheckDefinitions(): CheckDefinition[] {
@@ -32,6 +34,7 @@ export function getAllCheckDefinitions(): CheckDefinition[] {
getGhCliCheckDefinition(),
getLspCheckDefinition(),
...getMcpCheckDefinitions(),
getMcpOAuthCheckDefinition(),
getVersionCheckDefinition(),
]
}
+133
View File
@@ -0,0 +1,133 @@
import { describe, it, expect, spyOn, afterEach } from "bun:test"
import * as mcpOauth from "./mcp-oauth"
describe("mcp-oauth check", () => {
describe("getMcpOAuthCheckDefinition", () => {
it("returns check definition with correct properties", () => {
// #given
// #when getting definition
const def = mcpOauth.getMcpOAuthCheckDefinition()
// #then should have correct structure
expect(def.id).toBe("mcp-oauth-tokens")
expect(def.name).toBe("MCP OAuth Tokens")
expect(def.category).toBe("tools")
expect(def.critical).toBe(false)
expect(typeof def.check).toBe("function")
})
})
describe("checkMcpOAuthTokens", () => {
let readStoreSpy: ReturnType<typeof spyOn>
afterEach(() => {
readStoreSpy?.mockRestore()
})
it("returns skip when no tokens stored", async () => {
// #given no OAuth tokens configured
readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue(null)
// #when checking OAuth tokens
const result = await mcpOauth.checkMcpOAuthTokens()
// #then should skip
expect(result.status).toBe("skip")
expect(result.message).toContain("No OAuth")
})
it("returns pass when all tokens valid", async () => {
// #given valid tokens with future expiry (expiresAt is in epoch seconds)
const futureTime = Math.floor(Date.now() / 1000) + 3600
readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
"example.com/resource1": {
accessToken: "token1",
expiresAt: futureTime,
},
"example.com/resource2": {
accessToken: "token2",
expiresAt: futureTime,
},
})
// #when checking OAuth tokens
const result = await mcpOauth.checkMcpOAuthTokens()
// #then should pass
expect(result.status).toBe("pass")
expect(result.message).toContain("2")
expect(result.message).toContain("valid")
})
it("returns warn when some tokens expired", async () => {
// #given mix of valid and expired tokens (expiresAt is in epoch seconds)
const futureTime = Math.floor(Date.now() / 1000) + 3600
const pastTime = Math.floor(Date.now() / 1000) - 3600
readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
"example.com/resource1": {
accessToken: "token1",
expiresAt: futureTime,
},
"example.com/resource2": {
accessToken: "token2",
expiresAt: pastTime,
},
})
// #when checking OAuth tokens
const result = await mcpOauth.checkMcpOAuthTokens()
// #then should warn
expect(result.status).toBe("warn")
expect(result.message).toContain("1")
expect(result.message).toContain("expired")
expect(result.details?.some((d: string) => d.includes("Expired"))).toBe(
true
)
})
it("returns pass when tokens have no expiry", async () => {
// #given tokens without expiry info
readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
"example.com/resource1": {
accessToken: "token1",
},
})
// #when checking OAuth tokens
const result = await mcpOauth.checkMcpOAuthTokens()
// #then should pass (no expiry = assume valid)
expect(result.status).toBe("pass")
expect(result.message).toContain("1")
})
it("includes token details in output", async () => {
// #given multiple tokens
const futureTime = Math.floor(Date.now() / 1000) + 3600
readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
"api.example.com/v1": {
accessToken: "token1",
expiresAt: futureTime,
},
"auth.example.com/oauth": {
accessToken: "token2",
expiresAt: futureTime,
},
})
// #when checking OAuth tokens
const result = await mcpOauth.checkMcpOAuthTokens()
// #then should list tokens in details
expect(result.details).toBeDefined()
expect(result.details?.length).toBeGreaterThan(0)
expect(
result.details?.some((d: string) => d.includes("api.example.com"))
).toBe(true)
expect(
result.details?.some((d: string) => d.includes("auth.example.com"))
).toBe(true)
})
})
})
+80
View File
@@ -0,0 +1,80 @@
import type { CheckResult, CheckDefinition } from "../types"
import { CHECK_IDS, CHECK_NAMES } from "../constants"
import { getMcpOauthStoragePath } from "../../../features/mcp-oauth/storage"
import { existsSync, readFileSync } from "node:fs"
interface OAuthTokenData {
accessToken: string
refreshToken?: string
expiresAt?: number
clientInfo?: {
clientId: string
clientSecret?: string
}
}
type TokenStore = Record<string, OAuthTokenData>
export function readTokenStore(): TokenStore | null {
const filePath = getMcpOauthStoragePath()
if (!existsSync(filePath)) {
return null
}
try {
const content = readFileSync(filePath, "utf-8")
return JSON.parse(content) as TokenStore
} catch {
return null
}
}
export async function checkMcpOAuthTokens(): Promise<CheckResult> {
const store = readTokenStore()
if (!store || Object.keys(store).length === 0) {
return {
name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
status: "skip",
message: "No OAuth tokens configured",
details: ["Optional: Configure OAuth tokens for MCP servers"],
}
}
const now = Math.floor(Date.now() / 1000)
const tokens = Object.entries(store)
const expiredTokens = tokens.filter(
([, token]) => token.expiresAt && token.expiresAt < now
)
if (expiredTokens.length > 0) {
return {
name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
status: "warn",
message: `${expiredTokens.length} of ${tokens.length} token(s) expired`,
details: [
...tokens
.filter(([, token]) => !token.expiresAt || token.expiresAt >= now)
.map(([key]) => `Valid: ${key}`),
...expiredTokens.map(([key]) => `Expired: ${key}`),
],
}
}
return {
name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
status: "pass",
message: `${tokens.length} OAuth token(s) valid`,
details: tokens.map(([key]) => `Configured: ${key}`),
}
}
export function getMcpOAuthCheckDefinition(): CheckDefinition {
return {
id: CHECK_IDS.MCP_OAUTH_TOKENS,
name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
category: "tools",
check: checkMcpOAuthTokens,
critical: false,
}
}
+2
View File
@@ -32,6 +32,7 @@ export const CHECK_IDS = {
LSP_SERVERS: "lsp-servers",
MCP_BUILTIN: "mcp-builtin",
MCP_USER: "mcp-user",
MCP_OAUTH_TOKENS: "mcp-oauth-tokens",
VERSION_STATUS: "version-status",
} as const
@@ -50,6 +51,7 @@ export const CHECK_NAMES: Record<string, string> = {
[CHECK_IDS.LSP_SERVERS]: "LSP Servers",
[CHECK_IDS.MCP_BUILTIN]: "Built-in MCP Servers",
[CHECK_IDS.MCP_USER]: "User MCP Configuration",
[CHECK_IDS.MCP_OAUTH_TOKENS]: "MCP OAuth Tokens",
[CHECK_IDS.VERSION_STATUS]: "Version Status",
} as const
+3
View File
@@ -4,6 +4,7 @@ import { install } from "./install"
import { run } from "./run"
import { getLocalVersion } from "./get-local-version"
import { doctor } from "./doctor"
import { createMcpOAuthCommand } from "./mcp-oauth"
import type { InstallArgs } from "./types"
import type { RunOptions } from "./run"
import type { GetLocalVersionOptions } from "./get-local-version/types"
@@ -150,4 +151,6 @@ program
console.log(`oh-my-opencode v${VERSION}`)
})
program.addCommand(createMcpOAuthCommand())
program.parse()
+123
View File
@@ -0,0 +1,123 @@
import { describe, it, expect } from "bun:test"
import { Command } from "commander"
import { createMcpOAuthCommand } from "./index"
describe("mcp oauth command", () => {
describe("command structure", () => {
it("creates mcp command group with oauth subcommand", () => {
// given
const mcpCommand = createMcpOAuthCommand()
// when
const subcommands = mcpCommand.commands.map((cmd: Command) => cmd.name())
// then
expect(subcommands).toContain("oauth")
})
it("oauth subcommand has login, logout, and status subcommands", () => {
// given
const mcpCommand = createMcpOAuthCommand()
const oauthCommand = mcpCommand.commands.find((cmd: Command) => cmd.name() === "oauth")
// when
const subcommands = oauthCommand?.commands.map((cmd: Command) => cmd.name()) ?? []
// then
expect(subcommands).toContain("login")
expect(subcommands).toContain("logout")
expect(subcommands).toContain("status")
})
})
describe("login subcommand", () => {
it("exists and has description", () => {
// given
const mcpCommand = createMcpOAuthCommand()
const oauthCommand = mcpCommand.commands.find((cmd: Command) => cmd.name() === "oauth")
const loginCommand = oauthCommand?.commands.find((cmd: Command) => cmd.name() === "login")
// when
const description = loginCommand?.description() ?? ""
// then
expect(loginCommand).toBeDefined()
expect(description).toContain("OAuth")
})
it("accepts --server-url option", () => {
// given
const mcpCommand = createMcpOAuthCommand()
const oauthCommand = mcpCommand.commands.find((cmd: Command) => cmd.name() === "oauth")
const loginCommand = oauthCommand?.commands.find((cmd: Command) => cmd.name() === "login")
// when
const options = loginCommand?.options ?? []
const serverUrlOption = options.find((opt: { long?: string }) => opt.long === "--server-url")
// then
expect(serverUrlOption).toBeDefined()
})
it("accepts --client-id option", () => {
// given
const mcpCommand = createMcpOAuthCommand()
const oauthCommand = mcpCommand.commands.find((cmd: Command) => cmd.name() === "oauth")
const loginCommand = oauthCommand?.commands.find((cmd: Command) => cmd.name() === "login")
// when
const options = loginCommand?.options ?? []
const clientIdOption = options.find((opt: { long?: string }) => opt.long === "--client-id")
// then
expect(clientIdOption).toBeDefined()
})
it("accepts --scopes option", () => {
// given
const mcpCommand = createMcpOAuthCommand()
const oauthCommand = mcpCommand.commands.find((cmd: Command) => cmd.name() === "oauth")
const loginCommand = oauthCommand?.commands.find((cmd: Command) => cmd.name() === "login")
// when
const options = loginCommand?.options ?? []
const scopesOption = options.find((opt: { long?: string }) => opt.long === "--scopes")
// then
expect(scopesOption).toBeDefined()
})
})
describe("logout subcommand", () => {
it("exists and has description", () => {
// given
const mcpCommand = createMcpOAuthCommand()
const oauthCommand = mcpCommand.commands.find((cmd: Command) => cmd.name() === "oauth")
const logoutCommand = oauthCommand?.commands.find((cmd: Command) => cmd.name() === "logout")
// when
const description = logoutCommand?.description() ?? ""
// then
expect(logoutCommand).toBeDefined()
expect(description).toContain("tokens")
})
})
describe("status subcommand", () => {
it("exists and has description", () => {
// given
const mcpCommand = createMcpOAuthCommand()
const oauthCommand = mcpCommand.commands.find((cmd: Command) => cmd.name() === "oauth")
const statusCommand = oauthCommand?.commands.find((cmd: Command) => cmd.name() === "status")
// when
const description = statusCommand?.description() ?? ""
// then
expect(statusCommand).toBeDefined()
expect(description).toContain("status")
})
})
})
+43
View File
@@ -0,0 +1,43 @@
import { Command } from "commander"
import { login } from "./login"
import { logout } from "./logout"
import { status } from "./status"
export function createMcpOAuthCommand(): Command {
const mcp = new Command("mcp").description("MCP server management")
const oauth = new Command("oauth").description("OAuth token management for MCP servers")
oauth
.command("login <server-name>")
.description("Authenticate with an MCP server using OAuth")
.option("--server-url <url>", "OAuth server URL (required if not in config)")
.option("--client-id <id>", "OAuth client ID (optional, uses DCR if not provided)")
.option("--scopes <scopes...>", "OAuth scopes to request")
.action(async (serverName: string, options) => {
const exitCode = await login(serverName, options)
process.exit(exitCode)
})
oauth
.command("logout <server-name>")
.description("Remove stored OAuth tokens for an MCP server")
.option("--server-url <url>", "OAuth server URL (use if server name differs from URL)")
.action(async (serverName: string, options) => {
const exitCode = await logout(serverName, options)
process.exit(exitCode)
})
oauth
.command("status [server-name]")
.description("Show OAuth token status for MCP servers")
.action(async (serverName: string | undefined) => {
const exitCode = await status(serverName)
process.exit(exitCode)
})
mcp.addCommand(oauth)
return mcp
}
export { login, logout, status }
+80
View File
@@ -0,0 +1,80 @@
import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test"
const mockLogin = mock(() => Promise.resolve({ accessToken: "test-token", expiresAt: 1710000000 }))
mock.module("../../features/mcp-oauth/provider", () => ({
McpOAuthProvider: class MockMcpOAuthProvider {
constructor(public options: { serverUrl: string; clientId?: string; scopes?: string[] }) {}
async login() {
return mockLogin()
}
},
}))
const { login } = await import("./login")
describe("login command", () => {
beforeEach(() => {
mockLogin.mockClear()
})
afterEach(() => {
// cleanup
})
it("returns error code when server-url is not provided", async () => {
// given
const serverName = "test-server"
const options = {}
// when
const exitCode = await login(serverName, options)
// then
expect(exitCode).toBe(1)
})
it("returns success code when login succeeds", async () => {
// given
const serverName = "test-server"
const options = {
serverUrl: "https://oauth.example.com",
}
// when
const exitCode = await login(serverName, options)
// then
expect(exitCode).toBe(0)
expect(mockLogin).toHaveBeenCalledTimes(1)
})
it("returns error code when login throws", async () => {
// given
const serverName = "test-server"
const options = {
serverUrl: "https://oauth.example.com",
}
mockLogin.mockRejectedValueOnce(new Error("Network error"))
// when
const exitCode = await login(serverName, options)
// then
expect(exitCode).toBe(1)
})
it("returns error code when server-url is missing", async () => {
// given
const serverName = "test-server"
const options = {
clientId: "test-client-id",
}
// when
const exitCode = await login(serverName, options)
// then
expect(exitCode).toBe(1)
})
})
+38
View File
@@ -0,0 +1,38 @@
import { McpOAuthProvider } from "../../features/mcp-oauth/provider"
export interface LoginOptions {
serverUrl?: string
clientId?: string
scopes?: string[]
}
export async function login(serverName: string, options: LoginOptions): Promise<number> {
try {
const serverUrl = options.serverUrl
if (!serverUrl) {
console.error(`Error: --server-url is required for server "${serverName}"`)
return 1
}
const provider = new McpOAuthProvider({
serverUrl,
clientId: options.clientId,
scopes: options.scopes,
})
console.log(`Authenticating with ${serverName}...`)
const tokenData = await provider.login()
console.log(`✓ Successfully authenticated with ${serverName}`)
if (tokenData.expiresAt) {
const expiryDate = new Date(tokenData.expiresAt * 1000)
console.log(` Token expires at: ${expiryDate.toISOString()}`)
}
return 0
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
console.error(`Error: Failed to authenticate with ${serverName}: ${message}`)
return 1
}
}
+65
View File
@@ -0,0 +1,65 @@
import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test"
import { existsSync, mkdirSync, rmSync } from "node:fs"
import { join } from "node:path"
import { tmpdir } from "node:os"
import { saveToken } from "../../features/mcp-oauth/storage"
const { logout } = await import("./logout")
describe("logout command", () => {
const TEST_CONFIG_DIR = join(tmpdir(), "mcp-oauth-logout-test-" + Date.now())
let originalConfigDir: string | undefined
beforeEach(() => {
originalConfigDir = process.env.OPENCODE_CONFIG_DIR
process.env.OPENCODE_CONFIG_DIR = TEST_CONFIG_DIR
if (!existsSync(TEST_CONFIG_DIR)) {
mkdirSync(TEST_CONFIG_DIR, { recursive: true })
}
})
afterEach(() => {
if (originalConfigDir === undefined) {
delete process.env.OPENCODE_CONFIG_DIR
} else {
process.env.OPENCODE_CONFIG_DIR = originalConfigDir
}
if (existsSync(TEST_CONFIG_DIR)) {
rmSync(TEST_CONFIG_DIR, { recursive: true, force: true })
}
})
it("returns success code when logout succeeds", async () => {
// given
const serverUrl = "https://test-server.example.com"
saveToken(serverUrl, serverUrl, { accessToken: "test-token" })
// when
const exitCode = await logout("test-server", { serverUrl })
// then
expect(exitCode).toBe(0)
})
it("handles non-existent server gracefully", async () => {
// given
const serverName = "non-existent-server"
// when
const exitCode = await logout(serverName, { serverUrl: "https://nonexistent.example.com" })
// then
expect(exitCode).toBe(0)
})
it("returns error when --server-url is not provided", async () => {
// given
const serverName = "test-server"
// when
const exitCode = await logout(serverName)
// then
expect(exitCode).toBe(1)
})
})
+30
View File
@@ -0,0 +1,30 @@
import { deleteToken } from "../../features/mcp-oauth/storage"
export interface LogoutOptions {
serverUrl?: string
}
export async function logout(serverName: string, options?: LogoutOptions): Promise<number> {
try {
const serverUrl = options?.serverUrl
if (!serverUrl) {
console.error(`Error: --server-url is required for logout. Token storage uses server URLs, not names.`)
console.error(` Usage: mcp oauth logout ${serverName} --server-url https://your-server.example.com`)
return 1
}
const success = deleteToken(serverUrl, serverUrl)
if (success) {
console.log(`✓ Successfully removed tokens for ${serverName}`)
return 0
}
console.error(`Error: Failed to remove tokens for ${serverName}`)
return 1
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
console.error(`Error: Failed to remove tokens for ${serverName}: ${message}`)
return 1
}
}
+48
View File
@@ -0,0 +1,48 @@
import { describe, it, expect, beforeEach, afterEach } from "bun:test"
import { status } from "./status"
describe("status command", () => {
beforeEach(() => {
// setup
})
afterEach(() => {
// cleanup
})
it("returns success code when checking status for specific server", async () => {
// given
const serverName = "test-server"
// when
const exitCode = await status(serverName)
// then
expect(typeof exitCode).toBe("number")
expect(exitCode).toBe(0)
})
it("returns success code when checking status for all servers", async () => {
// given
const serverName = undefined
// when
const exitCode = await status(serverName)
// then
expect(typeof exitCode).toBe("number")
expect(exitCode).toBe(0)
})
it("handles non-existent server gracefully", async () => {
// given
const serverName = "non-existent-server"
// when
const exitCode = await status(serverName)
// then
expect(typeof exitCode).toBe("number")
expect(exitCode).toBe(0)
})
})
+50
View File
@@ -0,0 +1,50 @@
import { listAllTokens, listTokensByHost } from "../../features/mcp-oauth/storage"
export async function status(serverName: string | undefined): Promise<number> {
try {
if (serverName) {
const tokens = listTokensByHost(serverName)
if (Object.keys(tokens).length === 0) {
console.log(`No tokens found for ${serverName}`)
return 0
}
console.log(`OAuth Status for ${serverName}:`)
for (const [key, token] of Object.entries(tokens)) {
console.log(` ${key}:`)
console.log(` Access Token: [REDACTED]`)
if (token.refreshToken) {
console.log(` Refresh Token: [REDACTED]`)
}
if (token.expiresAt) {
const expiryDate = new Date(token.expiresAt * 1000)
const now = Date.now() / 1000
const isExpired = token.expiresAt < now
const tokenStatus = isExpired ? "EXPIRED" : "VALID"
console.log(` Expiry: ${expiryDate.toISOString()} (${tokenStatus})`)
}
}
return 0
}
const tokens = listAllTokens()
if (Object.keys(tokens).length === 0) {
console.log("No OAuth tokens stored")
return 0
}
console.log("Stored OAuth Tokens:")
for (const [key, token] of Object.entries(tokens)) {
const isExpired = token.expiresAt && token.expiresAt < Date.now() / 1000
const tokenStatus = isExpired ? "EXPIRED" : "VALID"
console.log(` ${key}: ${tokenStatus}`)
}
return 0
} catch (error) {
const message = error instanceof Error ? error.message : String(error)
console.error(`Error: Failed to get token status: ${message}`)
return 1
}
}