@lessie/mcp-server 0.0.8 → 0.1.1

package/dist/server/routes/auth-token.js

@@ -1,41 +0,0 @@
-import { Router } from "express";
-import pool from "../db.js";
-import { hashApiKey, signJwt } from "../auth.js";
-const router = Router();
-// POST /auth/token — API Key 换取 JWT（无需登录态）
-router.post("/", async (req, res) => {
-    try {
-        const { apiKey } = req.body;
-        if (!apiKey || typeof apiKey !== "string") {
-            res.status(401).json({ error: "Invalid credentials" });
-            return;
-        }
-        const keyHash = hashApiKey(apiKey);
-        const result = await pool.query(`SELECT id, user_id, scopes, expires_at
-       FROM api_keys
-       WHERE key_hash = $1 AND revoked_at IS NULL`, [keyHash]);
-        if (result.rowCount === 0) {
-            res.status(401).json({ error: "Invalid credentials" });
-            return;
-        }
-        const row = result.rows[0];
-        if (row.expires_at && new Date(row.expires_at) < new Date()) {
-            res.status(401).json({ error: "Invalid credentials" });
-            return;
-        }
-        // 异步更新 last_used_at，不阻塞响应
-        pool.query("UPDATE api_keys SET last_used_at = now() WHERE id = $1", [row.id]).catch((err) => console.error("Failed to update last_used_at:", err));
-        const { token, expiresIn } = signJwt({
-            sub: row.user_id,
-            scopes: row.scopes ?? ["read"],
-            via: "api_key",
-            kid: row.id,
-        });
-        res.json({ token, expiresIn });
-    }
-    catch (err) {
-        console.error("POST /auth/token error:", err);
-        res.status(500).json({ error: "Internal server error" });
-    }
-});
-export default router;

package/docs/oauth-client-guide.md

@@ -1,354 +0,0 @@
-# Lessie MCP OAuth 2.1 接入指南
-
-本文档面向 MCP Client 开发者，描述如何通过 OAuth 2.1 授权流程获取 access_token 并调用 Lessie MCP 接口。
-
----
-
-## 授权流程概览
-
-```
-MCP Client                                    Lessie 授权服务器
-    │                                               │
-    │ ① POST /mcp (无 token)                        │
-    │──────────────────────────────────────────────►│
-    │◄──────────────── 401 Unauthorized ────────────│
-    │                                               │
-    │ ② GET /.well-known/oauth-authorization-server │
-    │──────────────────────────────────────────────►│
-    │◄──── 元数据 JSON (各端点地址) ─────────────────│
-    │                                               │
-    │ ③ POST /register (动态客户端注册)              │
-    │──────────────────────────────────────────────►│
-    │◄──── { client_id, client_secret }  ───────────│
-    │                                               │
-    │ ④ 打开浏览器 → /authorize?...                 │
-    │          用户登录 → 点击"授权"                 │
-    │◄──── 302 → callback?code=xxx&state=yyy ───────│
-    │                                               │
-    │ ⑤ POST /token (code + code_verifier)          │
-    │──────────────────────────────────────────────►│
-    │◄──── { access_token, token_type, expires_in } │
-    │                                               │
-    │ ⑥ POST /mcp (Authorization: Bearer xxx)       │
-    │──────────────────────────────────────────────►│
-    │◄──── 业务数据 ────────────────────────────────│
-```
-
-> 本服务实现了 OAuth 2.1 + PKCE (S256) 授权码流程，遵循 RFC 8414、RFC 7591、RFC 7636 标准。
-
----
-
-## 基础地址
-
-| 环境 | Base URL |
-|------|----------|
-| 生产 | `https://www.lessie.ai/prod-api` |
-
----
-
-## 1. 授权服务器元数据发现
-
-> RFC 8414
-
-**请求**
-
-```
-GET /.well-known/oauth-authorization-server
-```
-
-**响应 200**
-
-```json
-{
-  "issuer": "https://www.lessie.ai/prod-api",
-  "authorization_endpoint": "https://www.lessie.ai/prod-api/authorize",
-  "token_endpoint": "https://www.lessie.ai/prod-api/token",
-  "registration_endpoint": "https://www.lessie.ai/prod-api/register",
-  "response_types_supported": ["code"],
-  "grant_types_supported": ["authorization_code"],
-  "code_challenge_methods_supported": ["S256"],
-  "token_endpoint_auth_methods_supported": [
-    "client_secret_basic",
-    "client_secret_post",
-    "none"
-  ],
-  "scopes_supported": ["read", "write"]
-}
-```
-
-客户端应通过此端点**动态发现**各接口地址，不要硬编码。
-
----
-
-## 2. 动态客户端注册
-
-> RFC 7591 — 首次连接时调用，无需用户操作
-
-**请求**
-
-```
-POST /register
-Content-Type: application/json
-```
-
-```json
-{
-  "redirect_uris": ["http://127.0.0.1:3000/callback"],
-  "grant_types": ["authorization_code"],
-  "response_types": ["code"],
-  "client_name": "My MCP Client",
-  "token_endpoint_auth_method": "client_secret_basic"
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `redirect_uris` | string[] | 是 | 回调地址列表，仅允许 loopback（`127.0.0.1` / `localhost` / `[::1]`）或 `https` |
-| `grant_types` | string[] | 否 | 默认 `["authorization_code"]` |
-| `response_types` | string[] | 否 | 默认 `["code"]` |
-| `client_name` | string | 否 | 默认 `"MCP Client"`，显示在授权页面上 |
-| `token_endpoint_auth_method` | string | 否 | `"client_secret_basic"`（默认）、`"client_secret_post"` 或 `"none"`（public client） |
-
-**响应 201 Created**
-
-```json
-{
-  "client_id": "lessie-aBcDeFgHiJkLmNoP",
-  "client_secret": "sk-xXxXxXxXxXxXxXxX...",
-  "client_name": "My MCP Client",
-  "redirect_uris": ["http://127.0.0.1:3000/callback"],
-  "grant_types": ["authorization_code"]
-}
-```
-
-> **重要**：`client_secret` 仅在注册响应中返回一次，请安全存储。后续无法再次获取。
-
-**错误响应**
-
-| HTTP 状态码 | error | 说明 |
-|-------------|-------|------|
-| 400 | `invalid_redirect_uri` | redirect_uri 格式不合法（必须是 loopback 或 https） |
-| 403 | `client_limit_exceeded` | 客户端注册数量已达上限 |
-| 429 | `too_many_requests` | 注册频率超限，请稍后重试 |
-
----
-
-## 3. 授权请求
-
-客户端在本地生成 PKCE 参数后，打开浏览器跳转到授权页面。
-
-### 3.1 生成 PKCE 参数
-
-```
-code_verifier  = 随机生成 43-128 字符的 URL-safe 字符串
-code_challenge = BASE64URL(SHA256(code_verifier))
-```
-
-### 3.2 打开浏览器
-
-```
-GET /authorize
-    ?response_type=code
-    &client_id={client_id}
-    &redirect_uri={redirect_uri}
-    &code_challenge={code_challenge}
-    &code_challenge_method=S256
-    &state={随机字符串}
-    &scope=read write
-```
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `response_type` | 是 | 固定为 `code` |
-| `client_id` | 是 | 注册时获取的 client_id |
-| `redirect_uri` | 是 | 必须与注册时提交的地址匹配（loopback 忽略端口） |
-| `code_challenge` | 是 | PKCE challenge (S256) |
-| `code_challenge_method` | 是 | 固定为 `S256` |
-| `state` | 建议 | 防 CSRF 的随机字符串，会原样回传 |
-| `scope` | 否 | 空格分隔，可选值：`read`、`write`。默认 `read write` |
-
-### 3.3 用户操作
-
-1. 用户在浏览器中登录 Lessie 账号（如未登录会自动跳转登录页）
-2. 用户在授权页面看到客户端名称，点击"授权"
-
-### 3.4 授权回调
-
-授权成功后，浏览器 302 重定向到 `redirect_uri`：
-
-```
-http://127.0.0.1:3000/callback?code=xxxx&state=yyyy
-```
-
-| 参数 | 说明 |
-|------|------|
-| `code` | 授权码，10 分钟有效，一次性使用 |
-| `state` | 与请求时一致，客户端应验证其值 |
-
----
-
-## 4. 令牌交换
-
-用授权码 + PKCE code_verifier 换取 access_token。
-
-**请求**
-
-```
-POST /token
-Content-Type: application/x-www-form-urlencoded
-```
-
-### 4.1 客户端认证方式
-
-**方式 A — Basic Auth（推荐）**
-
-```
-Authorization: Basic base64(client_id:client_secret)
-```
-
-表单参数：
-
-```
-grant_type=authorization_code
-&code={授权码}
-&redirect_uri={与授权请求一致的 redirect_uri}
-&code_verifier={PKCE code_verifier}
-```
-
-**方式 B — Form Body**
-
-```
-grant_type=authorization_code
-&code={授权码}
-&redirect_uri={与授权请求一致的 redirect_uri}
-&code_verifier={PKCE code_verifier}
-&client_id={client_id}
-&client_secret={client_secret}
-```
-
-**方式 C — Public Client（无 secret）**
-
-```
-grant_type=authorization_code
-&code={授权码}
-&redirect_uri={与授权请求一致的 redirect_uri}
-&code_verifier={PKCE code_verifier}
-&client_id={client_id}
-```
-
-**响应 200**
-
-```json
-{
-  "access_token": "eyJhbGciOiJIUzI1NiIs...",
-  "token_type": "bearer",
-  "expires_in": 3600,
-  "scope": "read write"
-}
-```
-
-| 字段 | 说明 |
-|------|------|
-| `access_token` | JWT 格式的访问令牌 |
-| `token_type` | 固定为 `bearer` |
-| `expires_in` | 有效期（秒），默认 3600（1 小时） |
-| `scope` | 实际授予的权限范围，空格分隔 |
-
-**错误响应**
-
-| HTTP 状态码 | error | 说明 |
-|-------------|-------|------|
-| 400 | `unsupported_grant_type` | 仅支持 `authorization_code` |
-| 400 | `invalid_request` | 缺少必要参数（code / redirect_uri / code_verifier） |
-| 400 | `invalid_grant` | 授权码无效、已过期、已使用，或 PKCE 验证失败 |
-| 401 | `invalid_client` | 客户端认证失败（client_id 不存在或 secret 错误） |
-
----
-
-## 5. 调用 MCP 接口
-
-在每次请求中携带 Bearer Token：
-
-```
-POST /mcp
-Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
-Content-Type: application/json
-```
-
-### 401 响应处理
-
-| WWW-Authenticate 值 | 含义 | 处理方式 |
-|---------------------|------|----------|
-| `Bearer` | 未携带 token | 触发完整 OAuth 授权流程 |
-| `Bearer error="invalid_token"` | token 无效或已过期 | 重新走授权流程获取新 token |
-
----
-
-## 6. 可用 Scope
-
-| Scope | 说明 |
-|-------|------|
-| `read` | 读取数据 |
-| `write` | 写入数据 |
-
-默认授予 `read write`。
-
----
-
-## 7. 完整接入示例（伪代码）
-
-```python
-# 1. 发现元数据
-metadata = GET("/.well-known/oauth-authorization-server")
-
-# 2. 动态注册（仅首次）
-registration = POST(metadata.registration_endpoint, {
-    "redirect_uris": ["http://127.0.0.1:9876/callback"],
-    "grant_types": ["authorization_code"],
-    "client_name": "My Agent"
-})
-client_id = registration.client_id
-client_secret = registration.client_secret
-
-# 3. 生成 PKCE
-code_verifier = random_url_safe_string(64)
-code_challenge = base64url(sha256(code_verifier))
-
-# 4. 打开浏览器授权
-open_browser(f"{metadata.authorization_endpoint}"
-    f"?response_type=code"
-    f"&client_id={client_id}"
-    f"&redirect_uri=http://127.0.0.1:9876/callback"
-    f"&code_challenge={code_challenge}"
-    f"&code_challenge_method=S256"
-    f"&state={random_state}")
-
-# 5. 本地 HTTP 服务器等待回调，获取 code
-code = wait_for_callback()
-
-# 6. 用 code 换 token
-token_response = POST(metadata.token_endpoint, {
-    "grant_type": "authorization_code",
-    "code": code,
-    "redirect_uri": "http://127.0.0.1:9876/callback",
-    "code_verifier": code_verifier,
-    "client_id": client_id,
-    "client_secret": client_secret
-})
-access_token = token_response.access_token
-
-# 7. 调用 MCP
-response = POST("/mcp", headers={"Authorization": f"Bearer {access_token}"}, ...)
-```
-
----
-
-## 8. 注意事项
-
-- `redirect_uri` 仅允许 loopback 地址（`127.0.0.1` / `localhost` / `[::1]`，任意端口）或 `https` 地址
-- loopback 回调时端口可以与注册时不同（符合 [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3)）
-- `client_secret` 仅注册时返回一次，请妥善保管
-- 授权码 10 分钟有效，且只能使用一次
-- access_token 有效期 1 小时，过期后需重新走授权流程
-- PKCE (S256) 为强制要求，不支持 plain 方式
-- `state` 参数建议始终使用，用于防止 CSRF 攻击