@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/mcp-gateway/src/auth/oauth.ts

@@ -0,0 +1,462 @@
+/**
+ * OAuth 2.1 Authentication for MCP Gateway
+ * 
+ * Implements:
+ * - OAuth 2.1 IETF DRAFT compliance
+ * - PKCE (Proof Key for Code Exchange) - mandatory
+ * - Dynamic Client Registration (RFC 7591)
+ * - Resource Indicators (RFC 8707)
+ * - Scope-based access control
+ * 
+ * @see https://modelcontextprotocol.io/docs/authorization
+ */
+
+import type { IncomingMessage, ServerResponse } from "http";
+import * as crypto from "crypto";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OAuthConfig {
+    /** Issuer URL for token validation */
+    issuer: string;
+    /** Client ID for this MCP server */
+    clientId: string;
+    /** Client secret (for confidential clients) */
+    clientSecret?: string;
+    /** Redirect URIs for authorization flow */
+    redirectUris: string[];
+    /** Supported scopes */
+    scopes: string[];
+    /** Token endpoint */
+    tokenEndpoint?: string;
+    /** Authorization endpoint */
+    authorizationEndpoint?: string;
+    /** JWKS endpoint for token validation */
+    jwksUri?: string;
+    /** Token expiration in seconds */
+    tokenExpiration?: number;
+}
+
+export interface TokenPayload {
+    /** Subject (user/client ID) */
+    sub: string;
+    /** Issuer */
+    iss: string;
+    /** Audience (this MCP server) */
+    aud: string;
+    /** Expiration timestamp */
+    exp: number;
+    /** Issued at timestamp */
+    iat: number;
+    /** Scopes granted */
+    scope: string;
+    /** Client ID */
+    client_id: string;
+}
+
+export interface AuthResult {
+    valid: boolean;
+    payload?: TokenPayload;
+    error?: string;
+    scopes?: string[];
+}
+
+export interface PKCEChallenge {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}
+
+// ============================================================================
+// MCP Scopes Definition
+// ============================================================================
+
+export const MCP_SCOPES = {
+    // Read-only scopes
+    "read:project": "Read project context and structure",
+    "read:graph": "Read dependency graph",
+    "read:search": "Execute search queries",
+
+    // Write scopes
+    "write:sync": "Trigger sync operations",
+    "write:cache": "Modify cache",
+
+    // Execute scopes
+    "execute:tools": "Execute MCP tools",
+    "execute:analysis": "Run code analysis",
+
+    // Admin scopes
+    "admin:config": "Modify server configuration",
+    "admin:users": "Manage user access",
+    "admin:*": "Full administrative access",
+} as const;
+
+export type MCPScope = keyof typeof MCP_SCOPES;
+
+// ============================================================================
+// PKCE Helpers
+// ============================================================================
+
+/**
+ * Generate PKCE code verifier and challenge
+ */
+export function generatePKCE(): PKCEChallenge {
+    // Generate 32-byte random verifier (43 chars base64url)
+    const codeVerifier = crypto.randomBytes(32)
+        .toString("base64url")
+        .replace(/[^a-zA-Z0-9]/g, "")
+        .substring(0, 43);
+
+    // SHA256 hash of verifier, base64url encoded
+    const codeChallenge = crypto
+        .createHash("sha256")
+        .update(codeVerifier)
+        .digest("base64url");
+
+    return {
+        codeVerifier,
+        codeChallenge,
+        codeChallengeMethod: "S256",
+    };
+}
+
+/**
+ * Verify PKCE code challenge
+ */
+export function verifyPKCE(codeVerifier: string, codeChallenge: string): boolean {
+    const computed = crypto
+        .createHash("sha256")
+        .update(codeVerifier)
+        .digest("base64url");
+
+    return crypto.timingSafeEqual(
+        Buffer.from(computed),
+        Buffer.from(codeChallenge)
+    );
+}
+
+// ============================================================================
+// Token Management
+// ============================================================================
+
+// In-memory token store (replace with Redis/DB in production)
+const tokenStore = new Map<string, TokenPayload>();
+const authCodeStore = new Map<string, {
+    clientId: string;
+    scopes: string[];
+    codeChallenge: string;
+    expiresAt: number;
+}>();
+
+/**
+ * Generate access token
+ */
+export function generateAccessToken(
+    config: OAuthConfig,
+    clientId: string,
+    scopes: string[],
+    subject: string = clientId
+): string {
+    const now = Math.floor(Date.now() / 1000);
+    const expiration = config.tokenExpiration || 3600; // 1 hour default
+
+    const payload: TokenPayload = {
+        sub: subject,
+        iss: config.issuer,
+        aud: config.clientId,
+        exp: now + expiration,
+        iat: now,
+        scope: scopes.join(" "),
+        client_id: clientId,
+    };
+
+    // Generate random token ID
+    const tokenId = crypto.randomBytes(32).toString("base64url");
+
+    // Store token for validation
+    tokenStore.set(tokenId, payload);
+
+    // In production, use JWT with RS256
+    // For now, return opaque token
+    return tokenId;
+}
+
+/**
+ * Validate access token
+ */
+export function validateAccessToken(token: string): AuthResult {
+    const payload = tokenStore.get(token);
+
+    if (!payload) {
+        return { valid: false, error: "Invalid token" };
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp < now) {
+        tokenStore.delete(token);
+        return { valid: false, error: "Token expired" };
+    }
+
+    return {
+        valid: true,
+        payload,
+        scopes: payload.scope.split(" "),
+    };
+}
+
+/**
+ * Revoke access token
+ */
+export function revokeAccessToken(token: string): boolean {
+    return tokenStore.delete(token);
+}
+
+// ============================================================================
+// Authorization Code Flow
+// ============================================================================
+
+/**
+ * Generate authorization code
+ */
+export function generateAuthorizationCode(
+    clientId: string,
+    scopes: string[],
+    codeChallenge: string
+): string {
+    const code = crypto.randomBytes(32).toString("base64url");
+
+    authCodeStore.set(code, {
+        clientId,
+        scopes,
+        codeChallenge,
+        expiresAt: Date.now() + 600000, // 10 minutes
+    });
+
+    return code;
+}
+
+/**
+ * Exchange authorization code for tokens
+ */
+export function exchangeAuthorizationCode(
+    config: OAuthConfig,
+    code: string,
+    clientId: string,
+    codeVerifier: string
+): { accessToken?: string; error?: string } {
+    const authCode = authCodeStore.get(code);
+
+    if (!authCode) {
+        return { error: "Invalid authorization code" };
+    }
+
+    if (authCode.expiresAt < Date.now()) {
+        authCodeStore.delete(code);
+        return { error: "Authorization code expired" };
+    }
+
+    if (authCode.clientId !== clientId) {
+        return { error: "Client ID mismatch" };
+    }
+
+    // Verify PKCE
+    if (!verifyPKCE(codeVerifier, authCode.codeChallenge)) {
+        return { error: "PKCE verification failed" };
+    }
+
+    // Delete used code
+    authCodeStore.delete(code);
+
+    // Generate access token
+    const accessToken = generateAccessToken(config, clientId, authCode.scopes);
+
+    return { accessToken };
+}
+
+// ============================================================================
+// Scope Validation
+// ============================================================================
+
+/**
+ * Check if token has required scope
+ */
+export function hasScope(authResult: AuthResult, requiredScope: MCPScope): boolean {
+    if (!authResult.valid || !authResult.scopes) {
+        return false;
+    }
+
+    // Admin wildcard
+    if (authResult.scopes.includes("admin:*")) {
+        return true;
+    }
+
+    // Check prefix wildcards (e.g., "read:*" matches "read:project")
+    const [category] = requiredScope.split(":");
+    if (authResult.scopes.includes(`${category}:*`)) {
+        return true;
+    }
+
+    return authResult.scopes.includes(requiredScope);
+}
+
+/**
+ * Check if token has all required scopes
+ */
+export function hasAllScopes(authResult: AuthResult, requiredScopes: MCPScope[]): boolean {
+    return requiredScopes.every(scope => hasScope(authResult, scope));
+}
+
+/**
+ * Check if token has any of the required scopes
+ */
+export function hasAnyScope(authResult: AuthResult, requiredScopes: MCPScope[]): boolean {
+    return requiredScopes.some(scope => hasScope(authResult, scope));
+}
+
+// ============================================================================
+// HTTP Middleware
+// ============================================================================
+
+/**
+ * Extract bearer token from request
+ */
+export function extractBearerToken(req: IncomingMessage): string | null {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        return null;
+    }
+
+    return authHeader.substring(7);
+}
+
+/**
+ * Authentication middleware
+ */
+export function createAuthMiddleware(config: OAuthConfig) {
+    return function authMiddleware(
+        req: IncomingMessage,
+        res: ServerResponse,
+        next: () => void
+    ): void {
+        const token = extractBearerToken(req);
+
+        if (!token) {
+            res.writeHead(401, {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": 'Bearer realm="MCP Server"',
+            });
+            res.end(JSON.stringify({ error: "Authentication required" }));
+            return;
+        }
+
+        const result = validateAccessToken(token);
+
+        if (!result.valid) {
+            res.writeHead(401, {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": `Bearer realm="MCP Server", error="${result.error}"`,
+            });
+            res.end(JSON.stringify({ error: result.error }));
+            return;
+        }
+
+        // Attach auth result to request for scope checking
+        (req as any).auth = result;
+        next();
+    };
+}
+
+/**
+ * Scope enforcement middleware
+ */
+export function requireScopes(...requiredScopes: MCPScope[]) {
+    return function scopeMiddleware(
+        req: IncomingMessage,
+        res: ServerResponse,
+        next: () => void
+    ): void {
+        const authResult = (req as any).auth as AuthResult | undefined;
+
+        if (!authResult || !hasAllScopes(authResult, requiredScopes)) {
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "Insufficient scope",
+                required: requiredScopes,
+                granted: authResult?.scopes || [],
+            }));
+            return;
+        }
+
+        next();
+    };
+}
+
+// ============================================================================
+// API Key Authentication (Simple Alternative)
+// ============================================================================
+
+const apiKeyStore = new Map<string, { scopes: string[]; name: string }>();
+
+/**
+ * Create API key
+ */
+export function createApiKey(name: string, scopes: string[]): string {
+    const key = `ak_${crypto.randomBytes(24).toString("base64url")}`;
+    apiKeyStore.set(key, { name, scopes });
+    return key;
+}
+
+/**
+ * Validate API key
+ */
+export function validateApiKey(key: string): AuthResult {
+    const data = apiKeyStore.get(key);
+
+    if (!data) {
+        return { valid: false, error: "Invalid API key" };
+    }
+
+    return {
+        valid: true,
+        scopes: data.scopes,
+        payload: {
+            sub: data.name,
+            iss: "api-key",
+            aud: "mcp-gateway",
+            exp: Number.MAX_SAFE_INTEGER,
+            iat: Math.floor(Date.now() / 1000),
+            scope: data.scopes.join(" "),
+            client_id: data.name,
+        },
+    };
+}
+
+/**
+ * Extract API key from request (X-API-Key header)
+ */
+export function extractApiKey(req: IncomingMessage): string | null {
+    return req.headers["x-api-key"] as string || null;
+}
+
+export default {
+    generatePKCE,
+    verifyPKCE,
+    generateAccessToken,
+    validateAccessToken,
+    revokeAccessToken,
+    generateAuthorizationCode,
+    exchangeAuthorizationCode,
+    hasScope,
+    hasAllScopes,
+    hasAnyScope,
+    extractBearerToken,
+    createAuthMiddleware,
+    requireScopes,
+    createApiKey,
+    validateApiKey,
+    extractApiKey,
+    MCP_SCOPES,
+};

package/.agent/mcp-gateway/src/auth/scopes.ts

@@ -0,0 +1,227 @@
+/**
+ * MCP Scope Definitions and Tool-to-Scope Mapping
+ * 
+ * Defines the scope requirements for each MCP tool,
+ * enabling fine-grained access control.
+ */
+
+import { MCPScope } from "./oauth.js";
+
+// ============================================================================
+// Tool-to-Scope Mapping
+// ============================================================================
+
+/**
+ * Maps each tool to its required scopes
+ * Tools can require multiple scopes (AND logic)
+ */
+export const TOOL_SCOPES: Record<string, MCPScope[]> = {
+    // Read-only tools
+    "get_project_context": ["read:project"],
+    "get_project_intelligence": ["read:project"],
+    "analyze_dependencies": ["read:graph"],
+    "get_impact_zone": ["read:graph"],
+    "search_knowledge": ["read:search"],
+    "search_code_logic": ["read:search"],
+
+    // Write tools
+    "force_sync": ["write:sync"],
+    "clear_cache": ["write:cache"],
+
+    // Execution tools
+    "execute_analysis": ["execute:analysis"],
+
+    // Admin tools
+    "update_config": ["admin:config"],
+    "manage_users": ["admin:users"],
+};
+
+/**
+ * Default scopes for new clients (minimal access)
+ */
+export const DEFAULT_SCOPES: MCPScope[] = [
+    "read:project",
+    "read:graph",
+    "read:search",
+];
+
+/**
+ * Full read access scopes
+ */
+export const READ_ALL_SCOPES: MCPScope[] = [
+    "read:project",
+    "read:graph",
+    "read:search",
+];
+
+/**
+ * Scopes for trusted agents (read + execute)
+ */
+export const AGENT_SCOPES: MCPScope[] = [
+    "read:project",
+    "read:graph",
+    "read:search",
+    "execute:tools",
+    "execute:analysis",
+];
+
+/**
+ * Full access scopes (for admin clients)
+ */
+export const FULL_ACCESS_SCOPES: MCPScope[] = [
+    "read:project",
+    "read:graph",
+    "read:search",
+    "write:sync",
+    "write:cache",
+    "execute:tools",
+    "execute:analysis",
+    "admin:config",
+    "admin:users",
+];
+
+// ============================================================================
+// Scope Helpers
+// ============================================================================
+
+/**
+ * Get required scopes for a tool
+ */
+export function getRequiredScopes(toolName: string): MCPScope[] {
+    return TOOL_SCOPES[toolName] || ["execute:tools"];
+}
+
+/**
+ * Check if scopes are sufficient for a tool
+ */
+export function hasToolAccess(grantedScopes: string[], toolName: string): boolean {
+    const required = getRequiredScopes(toolName);
+
+    // Admin wildcard check
+    if (grantedScopes.includes("admin:*")) {
+        return true;
+    }
+
+    // Check each required scope
+    return required.every(scope => {
+        // Direct match
+        if (grantedScopes.includes(scope)) {
+            return true;
+        }
+
+        // Category wildcard (e.g., "read:*" matches "read:project")
+        const [category] = scope.split(":");
+        if (grantedScopes.includes(`${category}:*`)) {
+            return true;
+        }
+
+        return false;
+    });
+}
+
+/**
+ * Get human-readable scope description
+ */
+export function getScopeDescription(scope: MCPScope): string {
+    const descriptions: Record<MCPScope, string> = {
+        "read:project": "Read project context and structure",
+        "read:graph": "Read dependency graph",
+        "read:search": "Execute search queries",
+        "write:sync": "Trigger sync operations",
+        "write:cache": "Modify cache",
+        "execute:tools": "Execute MCP tools",
+        "execute:analysis": "Run code analysis",
+        "admin:config": "Modify server configuration",
+        "admin:users": "Manage user access",
+        "admin:*": "Full administrative access",
+    };
+
+    return descriptions[scope] || scope;
+}
+
+/**
+ * Validate scope string format
+ */
+export function isValidScope(scope: string): scope is MCPScope {
+    const validScopes = Object.keys(TOOL_SCOPES).flatMap(tool => TOOL_SCOPES[tool]);
+    const uniqueScopes = [...new Set(validScopes), "admin:*", "read:*", "write:*", "execute:*"];
+    return uniqueScopes.includes(scope as MCPScope);
+}
+
+/**
+ * Parse scope string (space-separated) into array
+ */
+export function parseScopes(scopeString: string): MCPScope[] {
+    return scopeString
+        .split(" ")
+        .filter(s => s.length > 0)
+        .filter(isValidScope);
+}
+
+/**
+ * Serialize scopes to string
+ */
+export function serializeScopes(scopes: MCPScope[]): string {
+    return scopes.join(" ");
+}
+
+// ============================================================================
+// Scope Request Helpers
+// ============================================================================
+
+/**
+ * Get minimum scopes needed for a set of tools
+ */
+export function getScopesForTools(toolNames: string[]): MCPScope[] {
+    const allScopes = toolNames.flatMap(tool => getRequiredScopes(tool));
+    return [...new Set(allScopes)]; // deduplicate
+}
+
+/**
+ * Check if scope request is within allowed limits
+ */
+export function validateScopeRequest(
+    requestedScopes: MCPScope[],
+    allowedScopes: MCPScope[]
+): { valid: boolean; denied: MCPScope[] } {
+    const denied = requestedScopes.filter(scope => {
+        // Admin wildcard allows all
+        if (allowedScopes.includes("admin:*")) {
+            return false;
+        }
+
+        // Direct match
+        if (allowedScopes.includes(scope)) {
+            return false;
+        }
+
+        // Category wildcard
+        const [category] = scope.split(":");
+        if (allowedScopes.includes(`${category}:*` as MCPScope)) {
+            return false;
+        }
+
+        return true;
+    });
+
+    return {
+        valid: denied.length === 0,
+        denied,
+    };
+}
+
+export default {
+    TOOL_SCOPES,
+    DEFAULT_SCOPES,
+    READ_ALL_SCOPES,
+    AGENT_SCOPES,
+    FULL_ACCESS_SCOPES,
+    getRequiredScopes,
+    hasToolAccess,
+    getScopeDescription,
+    isValidScope,
+    parseScopes,
+    serializeScopes,
+    getScopesForTools,
+    validateScopeRequest,
+};