@opentiny/agent 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-present, OpenTiny contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# OpenTiny Agent
+
+OpenTiny Agent Server
+
+## 安装
+
+```bash
+npm install @opentiny/agent
+```
+
+## 许可证
+
+MIT

package/index.d.ts

@@ -0,0 +1,542 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import { Response, RequestHandler, Request, NextFunction } from 'express';
+import { JwtPayload } from 'jsonwebtoken';
+import { OAuthClientInformationFull, OAuthTokens, OAuthTokenRevocationRequest } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { AuthorizationParams, OAuthServerProvider } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+import { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
+import { AuthRouterOptions } from '@modelcontextprotocol/sdk/server/auth/router.js';
+
+declare const ACCESS_TOKEN_EXPIRES_IN: number;
+declare const REFRESH_TOKEN_EXPIRES_IN: number;
+/**
+ * 内存中的 OAuth 客户端信息存储实现
+ */
+declare class MemoryClientsStore implements OAuthRegisteredClientsStore {
+    /**
+     * 存储注册的 OAuth 客户端信息
+     * key: 客户端 ID
+     * value: OAuth 客户端信息
+     */
+    private clients;
+    /**
+     * 获取注册的 OAuth 客户端信息。
+     *
+     * @param clientId 客户端 ID
+     * @returns OAuth 客户端信息或 undefined
+     */
+    getClient(clientId: string): Promise<OAuthClientInformationFull>;
+    /**
+     * 保存或更新 OAuth 客户端信息。
+     *
+     * @param clientMetadata OAuth 客户端信息
+     * @returns 保存后的 OAuth 客户端信息
+     */
+    saveClient(clientMetadata: OAuthClientInformationFull): Promise<OAuthClientInformationFull>;
+    /**
+     * 删除 OAuth 客户端信息。
+     *
+     * @param clientId 客户端 ID
+     * @returns 是否删除成功
+     */
+    deleteClient(clientId: string): Promise<boolean>;
+    /**
+     * 注册新的 OAuth 客户端。
+     *
+     * @param clientMetadata OAuth 客户端信息
+     * @returns 保存后的 OAuth 客户端信息
+     */
+    registerClient(clientMetadata: OAuthClientInformationFull): Promise<OAuthClientInformationFull>;
+}
+/**
+ * OAuth 授权码存储接口
+ * 用于存储和管理 OAuth 授权码及其相关的授权参数和客户端信息。
+ * 该接口定义了获取、保存和删除授权码数据的方法。
+ */
+interface OAuthAuthorizationCodeStore {
+    /**
+     * 获取授权码的相关数据。
+     *
+     * @param code 授权码
+     * @returns 授权码数据或 undefined
+     */
+    getCodeDate(code: string): Promise<{
+        params: AuthorizationParams;
+        client: OAuthClientInformationFull;
+    } | undefined>;
+    /**
+     * 保存授权码数据。
+     *
+     * @param code 授权码
+     * @param data 包含授权参数和客户端信息的对象
+     * @param data.params 授权参数
+     * @param data.client 客户端信息
+     * @returns 是否保存成功
+     */
+    saveCodeData(code: string, data: {
+        params: AuthorizationParams;
+        client: OAuthClientInformationFull;
+    }): Promise<boolean>;
+    /**
+     * 删除授权码数据。
+     *
+     * @param code 授权码
+     * @returns 是否删除成功
+     */
+    deleteCodeData(code: string): Promise<boolean>;
+}
+/**
+ * 内存中的授权码存储实现
+ */
+declare class MemoryAuthorizationCodeStore implements OAuthAuthorizationCodeStore {
+    /**
+     * 存储授权码的相关数据
+     * key: 授权码
+     * value: 包含授权参数和客户端信息的对象
+     */
+    private codes;
+    /**
+     * 获取授权码的相关数据。
+     *
+     * @param code 授权码
+     * @returns 授权码数据或 undefined
+     */
+    getCodeDate(code: string): Promise<{
+        params: AuthorizationParams;
+        client: OAuthClientInformationFull;
+    }>;
+    /**
+     * 保存授权码数据。
+     *
+     * @param code 授权码
+     * @param data 包含授权参数和客户端信息的对象
+     * @param data.params 授权参数
+     * @param data.client 客户端信息
+     * @returns 是否保存成功
+     */
+    saveCodeData(code: string, data: {
+        params: AuthorizationParams;
+        client: OAuthClientInformationFull;
+    }): Promise<boolean>;
+    /**
+     * 删除授权码数据。
+     *
+     * @param code 授权码
+     * @returns 是否删除成功
+     */
+    deleteCodeData(code: string): Promise<boolean>;
+}
+/**
+ * OAuth 访问令牌存储接口
+ * 用于存储和管理 OAuth 访问令牌及其相关的认证信息。
+ * 该接口定义了获取、保存和删除访问令牌的方法。
+ */
+interface OAuthAccessTokensStore {
+    /**
+     * 获取访问令牌的认证信息。
+     *
+     * @param token 访问令牌
+     * @returns 认证信息或 undefined
+     */
+    getAccessToken(token: string): Promise<AuthInfo | undefined>;
+    /**
+     * 保存访问令牌的认证信息。
+     *
+     * @param token 访问令牌
+     * @param info 认证信息
+     * @returns 是否保存成功
+     */
+    saveAccessToken(token: string, info: AuthInfo): Promise<boolean>;
+    /**
+     * 撤销访问令牌。
+     *
+     * @param token 访问令牌
+     * @returns 是否删除成功
+     */
+    revokeAccessToken(token: string): Promise<boolean>;
+}
+/**
+ * 内存中的访问令牌存储实现
+ */
+declare class MemoryAccessTokensStore implements OAuthAccessTokensStore {
+    /**
+     * 存储访问令牌的认证信息
+     * key: 访问令牌
+     * value: 认证信息对象
+     */
+    private accessTokens;
+    /**
+     * 获取访问令牌的认证信息。
+     *
+     * @param token 访问令牌
+     * @returns 认证信息或 undefined
+     */
+    getAccessToken(token: string): Promise<AuthInfo>;
+    /**
+     * 保存访问令牌的认证信息。
+     *
+     * @param token 访问令牌
+     * @param info 认证信息
+     * @returns 是否保存成功
+     */
+    saveAccessToken(token: string, info: AuthInfo): Promise<boolean>;
+    /**
+     * 撤销访问令牌。
+     *
+     * @param token 访问令牌
+     * @returns 是否删除成功
+     */
+    revokeAccessToken(token: string): Promise<boolean>;
+}
+/**
+ * OAuth 刷新令牌存储接口
+ * 用于存储和管理 OAuth 刷新令牌及其相关的认证信息。
+ * 该接口定义了获取、保存和删除刷新令牌的方法。
+ */
+interface OAuthRefreshTokensStore {
+    /**
+     * 获取刷新令牌的认证信息。
+     *
+     * @param token 刷新令牌
+     * @returns 认证信息或 undefined
+     */
+    getRefreshToken(token: string): Promise<AuthInfo | undefined>;
+    /**
+     * 保存刷新令牌的认证信息。
+     *
+     * @param token 刷新令牌
+     * @param info 认证信息
+     * @returns 是否保存成功
+     */
+    saveRefreshToken(token: string, info: AuthInfo): Promise<boolean>;
+    /**
+     * 撤销刷新令牌。
+     *
+     * @param token 刷新令牌
+     * @returns 是否删除成功
+     */
+    revokeRefreshToken(token: string): Promise<boolean>;
+}
+/**
+ * 内存中的刷新令牌存储实现
+ */
+declare class MemoryRefreshTokensStore implements OAuthRefreshTokensStore {
+    /**
+     * 存储刷新令牌的认证信息
+     * key: 刷新令牌
+     * value: 认证信息对象
+     */
+    private refreshTokens;
+    /**
+     * 获取刷新令牌的认证信息。
+     *
+     * @param token 刷新令牌
+     * @returns 认证信息或 undefined
+     */
+    getRefreshToken(token: string): Promise<AuthInfo>;
+    /**
+     * 保存刷新令牌的认证信息。
+     *
+     * @param token 刷新令牌
+     * @param info 认证信息
+     * @returns 是否保存成功
+     */
+    saveRefreshToken(token: string, info: AuthInfo): Promise<boolean>;
+    /**
+     * 撤销刷新令牌。
+     *
+     * @param token 刷新令牌
+     * @returns 是否删除成功
+     */
+    revokeRefreshToken(token: string): Promise<boolean>;
+}
+/**
+ * 认证服务器提供者选项接口
+ * 用于配置认证服务器提供者的选项，包括存储、令牌过期时间等。
+ */
+interface AuthServerProviderOptions {
+    clientsStore?: OAuthRegisteredClientsStore;
+    codesStore?: OAuthAuthorizationCodeStore;
+    accessTokensStore?: OAuthAccessTokensStore;
+    refreshTokensStore?: OAuthRefreshTokensStore;
+    generateAuthorizationCode?: () => string;
+    generateAccessToken?: () => string;
+    generateRefreshToken?: () => string;
+    accessTokenExpiresIn?: number;
+    refreshTokenExpiresIn?: number;
+}
+/**
+ * 认证服务器提供者
+ * 用于管理 OAuth 客户端信息、授权码、访问令牌和刷新令牌的存储和生成。
+ */
+declare class AuthServerProvider implements OAuthServerProvider {
+    clientsStore: OAuthRegisteredClientsStore;
+    private codesStore;
+    private accessTokensStore;
+    private refreshTokensStore;
+    private generateAuthorizationCode;
+    private generateAccessToken;
+    private generateRefreshToken;
+    private accessTokenExpiresIn;
+    private refreshTokenExpiresIn;
+    constructor(options?: AuthServerProviderOptions);
+    /**
+     * 授权客户端。
+     *
+     * @param client 客户端信息
+     * @param params 授权参数
+     * @param res 响应对象
+     */
+    authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
+    /**
+     * 获取授权码的 code challenge。
+     *
+     * @param client 客户端信息
+     * @param authorizationCode 授权码
+     * @returns 授权码的 code challenge
+     */
+    challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;
+    /**
+     * 交换授权码。
+     *
+     * @param client 客户端信息
+     * @param authorizationCode 授权码
+     * @returns 交换后的 OAuth 令牌
+     */
+    exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<OAuthTokens>;
+    /**shared.js
+     * 交换刷新令牌。
+     *
+     * @param client 客户端信息
+     * @param refreshToken 刷新令牌
+     * @returns 交换后的 OAuth 令牌
+     */
+    exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string): Promise<OAuthTokens>;
+    /**
+     * 验证访问令牌。
+     *
+     * @param token 访问令牌
+     * @returns 认证信息
+     */
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+    /**
+     * 撤销访问令牌。
+     *
+     * @param client 客户端信息
+     * @param request 撤销令牌请求
+     */
+    revokeToken(client: OAuthClientInformationFull, request: OAuthTokenRevocationRequest): Promise<void>;
+}
+/**
+ * 创建 OAuth 认证中间件。
+ *
+ * @param authServerProvider 认证服务器提供者
+ * @param resourceUrl 资源标识符
+ * @returns Express 中间件函数
+ */
+declare const createAuthMiddleware: (authServerProvider: AuthServerProvider, resourceUrl: string) => any;
+/**
+ * 创建 OAuth 认证回调路由，用于处理 OAuth 授权回调请求，存储授权码，并提供获取授权码的接口。
+ *
+ * @param callbackEndpoint 回调端点路径
+ * @param middlewares 中间件，可选
+ * @returns Express 路由处理器
+ */
+declare const createAuthCallbackRouter: (callbackEndpoint: string, ...middlewares: RequestHandler[]) => RequestHandler;
+/**
+ * 创建 OAuth 认证元数据路由。
+ *
+ * @param authServerProvider 认证服务器提供者
+ * @param authUrl 认证 URL
+ * @param resourceUrl 资源 URL
+ * @returns Express 路由处理器
+ */
+declare const createAuthMetadataRouter: (authServerProvider: AuthServerProvider, authUrl: string, resourceUrl: string) => RequestHandler;
+/**
+ * 创建 OAuth 认证路由。
+ *
+ * @param options 认证路由选项
+ * @returns Express 路由处理器
+ */
+declare const createAuthRouter: (options: AuthRouterOptions) => RequestHandler;
+
+/**
+ * 客户端连接的信息，包括客户端实例、用户信息和 Transport 类型。
+ */
+interface ClientInfo {
+    /**
+     * 客户端实例
+     */
+    client: Client;
+    /**
+     * 客户端连接的 Transport 实例
+     */
+    transport: SSEServerTransport | StreamableHTTPServerTransport;
+    /**
+     * 连接的用户信息
+     */
+    user?: AuthInfo | JwtPayload | string;
+    /**
+     * 用于识别不同连接的信息
+     */
+    device: {
+        /**
+         * 连接的来源 IP 地址，可能是 IPv4 或 IPv6 地址
+         */
+        ip: string | string[];
+        /**
+         * 识别浏览器类型和版本 User-Agent 字符串
+         */
+        userAgent: string;
+        /**
+         * 连接的语言设置，通常是浏览器的 Accept-Language 字段
+         */
+        acceptLanguage: string;
+        /**
+         * 连接的来源 URL，通常是 HTTP Referer 字段
+         */
+        referer: string;
+    };
+    /**
+     * 客户端连接的 Transport 类型
+     */
+    type: 'SSE' | 'StreamableHTTP';
+}
+/**
+ * 遥控端连接的信息，包括服务端实例、用户信息和 Transport 类型。
+ */
+interface RemoterInfo {
+    /**
+     * 服务端实例
+     */
+    mcpServer: McpServer;
+    /**
+     * 服务端连接的 Transport 实例
+     */
+    transport: SSEServerTransport | StreamableHTTPServerTransport;
+    /**
+     * 所连接客户端的 Session ID
+     */
+    client: string;
+    /**
+     * 连接的用户信息
+     */
+    user?: AuthInfo | JwtPayload | string;
+    /**
+     * 用于识别不同连接的信息
+     */
+    device: {
+        /**
+         * 连接的来源 IP 地址，可能是 IPv4 或 IPv6 地址
+         */
+        ip: string | string[];
+        /**
+         * 识别浏览器类型和版本 User-Agent 字符串
+         */
+        userAgent: string;
+        /**
+         * 连接的语言设置，通常是浏览器的 Accept-Language 字段
+         */
+        acceptLanguage: string;
+        /**
+         * 连接的来源 URL，通常是 HTTP Referer 字段
+         */
+        referer: string;
+    };
+    /**
+     * 服务端连接的 Transport 类型
+     */
+    type: 'SSE' | 'StreamableHTTP';
+}
+/**
+ * ClientError 接口，在客户端连接或处理过程中发生的错误。
+ */
+interface ClientError {
+    /**
+     * 客户端实例
+     */
+    client: Client;
+    /**
+     * 客户端连接的 Transport 实例
+     */
+    transport: SSEServerTransport | StreamableHTTPServerTransport;
+    /**
+     * 错误信息
+     */
+    error: Error;
+    /**
+     * 服务端连接的 Transport 类型
+     */
+    type: 'SSE' | 'StreamableHTTP';
+}
+/**
+ * RemoterError 接口，在遥控端连接或处理过程中发生的错误。
+ */
+interface RemoterError {
+    /**
+     * 服务端实例
+     */
+    mcpServer: McpServer;
+    /**
+     * 客户端连接的 Transport 实例
+     */
+    transport: SSEServerTransport | StreamableHTTPServerTransport;
+    /**
+     * 所连接客户端的 Session ID
+     */
+    client: string;
+    /**
+     * 错误信息
+     */
+    error: Error;
+    /**
+     * 服务端连接的 Transport 类型
+     */
+    type: 'SSE' | 'StreamableHTTP';
+}
+/**
+ * Express 请求对象的扩展，添加了可选的用户信息属性
+ */
+declare module 'express' {
+    interface Request {
+        user?: JwtPayload | string;
+        auth?: AuthInfo;
+    }
+}
+/**
+ * 认证中间件，用于校验 JWT Token。
+ *
+ * 检查请求头中的 Authorization 字段，提取并校验 Bearer Token。
+ * 校验通过后，将解码后的用户信息挂载到 req.user
+ * 校验失败或缺失 token 时，返回 401 或 403 错误。
+ */
+declare const auth: ({ secret }: {
+    secret: string;
+}) => (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * SSE 与 Streamable HTTP 连接的处理函数，同时返回所有客户端代理实例。
+ */
+declare const useProxyHandles: () => {
+    handleSseProxy: (req: Request, res: Response, endpoint: string) => Promise<void>;
+    handleSseInspector: (req: Request, res: Response, endpoint: string) => Promise<void>;
+    handleSseMessage: (req: Request, res: Response) => Promise<void>;
+    handleStreamRequest: (req: Request, res: Response) => Promise<void>;
+    handleStreamInspector: (req: Request, res: Response) => Promise<void>;
+    clients: Record<string, ClientInfo>;
+    remoters: Record<string, RemoterInfo>;
+    transports: Record<string, any>;
+    inspectors: Record<string, any>;
+    reset: () => {};
+    ping: () => Promise<{
+        clientSessions: string[];
+        remoterSessions: string[];
+    }>;
+    onClientError: (onError: (error: ClientError) => void) => void;
+    onRemoterError: (onError: (error: RemoterError) => void) => void;
+};
+
+export { ACCESS_TOKEN_EXPIRES_IN, AuthServerProvider, MemoryAccessTokensStore, MemoryAuthorizationCodeStore, MemoryClientsStore, MemoryRefreshTokensStore, REFRESH_TOKEN_EXPIRES_IN, auth, createAuthCallbackRouter, createAuthMetadataRouter, createAuthMiddleware, createAuthRouter, useProxyHandles };
+export type { AuthServerProviderOptions, ClientError, ClientInfo, OAuthAccessTokensStore, OAuthAuthorizationCodeStore, OAuthRefreshTokensStore, RemoterError, RemoterInfo };