zhangshichun

OAuth Pkce — Development skill for Claude Code

Development community

OAuth + PKCE授权的经典实现，可直接本地支持WorkBuddy、Claude Code、Trae Work、Codex 各种主流Herness客户端，直接拿去抄和改.

How to install OAuth Pkce

This entry records only its repository, not the path inside it, so there is no exact command to give. Open zhangshichun/oauth-pkce and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What OAuth Pkce does

OAuth + PKCE授权的经典实现，可直接本地支持WorkBuddy、Claude Code、Trae Work、Codex 各种主流Herness客户端，直接拿去抄和改！

Alternatives in Development

Claude Balancer — A load balancer proxy for multiple Claude OAuth accounts with automatic failover, request tracking, and web da 910 ★
OpenSail — OpenSail is the open-source alternative to Codex App, Claude Desktop, Cursor, and Cowork for agentic software 634 ★
AgentHandover — What if OpenClaw, Claude Code, Codex etc. knew how to do your work without you saying it 600 ★

README

oauth-pkce

给 `WorkBuddy`、`Claude Code`、`TraeWork`、`Codex` 等等等等 `AI-Herness` 客户端做 `remote-MCP` 登录的示例 `Demo`。

附带可以直接跑起来的Demo + 全部接口规范 + 架构设计图。

**给 MCP Server 做授权的 OAuth 2.1 + PKCE 授权服务器（AS）**，附带示例资源服务器（demo-rs）与示例客户端（demo-client），三者构成可自测的完整授权闭环。

📖 详细设计与接口契约见 [docs/设计文档.md](docs/设计文档.md)（含名词表、架构图、全部端点入参出参）。

快速开始

前置：**Node 22+**（`node:sqlite` 需 22）。

npm install
copy .env.example .env     # 首次运行；默认 SQLite 持久化 + 127.0.0.1:3000

npm run dev                # 终端 1：AS（http://127.0.0.1:3000）
npm run start:rs           # 终端 2：demo-rs（http://127.0.0.1:4000/mcp）

npm test                   # 23/23 测试（vitest，动态端口自起服务）
npm run typecheck          # tsc --noEmit

手动联调推荐用 MCP Inspector：

npx @modelcontextprotocol/inspector
# 界面里选 Streamable HTTP，URL 填 http://127.0.0.1:4000/mcp → Connect
# 首次会拉起浏览器走 登录（alice / .env 里的 TEST_PASSWORD）→ 同意授权 → echo 调用

它实现了什么

全量 PKCE 强制：所有客户端必须 S256，plain 与"challenge 无 method"直接拒绝（RFC 7636 / 9700 / OAuth 2.1）
JWT Access Token（ES256，RFC 9068 profile），RS 侧 JWKS 无状态验签，aud = RFC 8707 resource indicator
Refresh Token 一次性轮换：旧 RT 立即作废，重放 → invalid_grant 且该授权（grant）名下 token 连坐吊销（RFC 9700）
DCR + CIMD 双轨注册：POST /reg 动态注册（RFC 7591/7592），或 client_id 直接用 https 元数据文档 URL（CIMD 草案，MCP 2026-07-28 修订首选）
RFC 8707 资源白名单 + loopback 等价规则（localhost ≡ 127.0.0.1 ≡ [::1]，AS/RS 共用一份实现）
RFC 9207（授权响应回传 iss）、RFC 7009（令牌撤销）、RFC 8414/9728 双元数据发现
自定义登录 / 授权确认页；SQLite 持久化（重启不丢注册与授权状态）或内存 Adapter

遵循的标准与提案

实现状态：✅ 全量实现 · 🟡 最小子集 · ⬜ 未实现（开放问题，见 spec §14）

协议总纲

| 提案 | 链接 | 提供的能力 | 状态 | | --------------------------------------- | ---------------------------------------------------------- | -----------------------------------------------------------------------------------------------