Security Features

This document outlines the comprehensive security features implemented in the MCP agent system.

Tags-as-OAuth-Scopes Security Model

Core Concept

Tags are mapped to OAuth 2.1 scopes using the format tag:{tag-name} (e.g., tag:web, tag:db). This provides fine-grained access control where clients can only access servers for which they have been explicitly granted scope permissions.

Security Benefits

• Fine-grained access control: Clients only access authorized servers
• Standards compliance: Uses OAuth 2.1 scopes properly
• User consent: Explicit approval of requested permissions via web interface
• Fail-secure design: Denies access on any validation failure
• Scope expiration: Scopes expire with access tokens

Scope Validation Security

Input Validation (src/utils/scopeValidation.ts)

• Strict format validation: Only tag:[a-zA-Z0-9_-]+ patterns allowed
• Length limits: Maximum scope and tag length enforcement
• Injection prevention: Blocks path traversal, command injection, and special characters
• Count limits: Maximum number of scopes per request
• Duplicate detection: Prevents duplicate scopes in requests

Allowlist Approach

• Scopes are validated against available server tags only
• No wildcard or pattern matching allowed
• Fail-secure validation with comprehensive error logging

Authentication & Authorization

OAuth 2.1 Implementation (src/auth/sdkOAuthServerProvider.ts)

• PKCE support: Prevents authorization code interception
• Client registration: Dynamic client registration with validation
• Token management: Secure token generation, validation, and revocation
• Session management: Secure session storage with expiration
• Web-based consent: User-friendly consent interface for scope approval

Scope-Based Authorization Middleware (src/transport/http/middlewares/scopeAuthMiddleware.ts)

• Token verification: Validates Bearer tokens on every request
• Scope enforcement: Ensures requested tags are covered by granted scopes
• Backward compatibility: Works seamlessly when auth is disabled
• Fail-secure design: Denies access on any error condition

Rate Limiting

Multi-tier Rate Limiting

1. General OAuth endpoints: Standard rate limiting for OAuth operations
2. Sensitive operations: Stricter rate limiting for consent and token operations
3. Adaptive limits: Different limits for different operation types

Rate Limiting Features

• IP-based limiting: Prevents abuse from specific addresses
• Time window controls: Configurable time windows for rate limits
• Security logging: Logs rate limit violations for monitoring
• Graceful degradation: Proper error responses when limits exceeded

Security Middleware (src/transport/http/middlewares/securityMiddleware.ts)

Security Headers

• X-Frame-Options: Prevents clickjacking attacks
• X-Content-Type-Options: Prevents MIME type sniffing
• X-XSS-Protection: Enables XSS protection in browsers
• Content-Security-Policy: Restricts resource loading for HTML responses
• Referrer-Policy: Controls referrer information leakage

Input Validation

• Injection protection: Detects and blocks common injection patterns
• Header validation: Validates all HTTP headers for suspicious content
• Query parameter validation: Validates query parameters for malicious content
• Body validation: Validates request bodies for POST operations

Session Security

• Cache control: Prevents caching of sensitive responses
• Robot exclusion: Prevents indexing of OAuth endpoints
• Timing attack prevention: Random delays for authentication endpoints

Template Context Trust

Request context is an execution input because template values can reach backend command, args, cwd, and env. The default verified policy accepts context for rendering only when a first-party local Client Surface signs it with the owner-only capability of the selected Runtime Scope. The detached proof binds the readable context hash, runtimeScopeId, and canonical request session.

Unsigned clients are not disconnected: they retain static-server access. Operators can select disabled to ignore all template context, or legacy to restore unsigned rendering. legacy is intentionally unsafe for untrusted clients and requires --confirm-untrusted-template-context on non-loopback HTTP listeners.

Normal audit logs include context source, project name/path, session, context hash, Runtime Scope identity, and verification outcome. Environment and custom values plus user home/email/shell are redacted. General HTTP logs omit raw base64 context and proof signatures.

Audit Logging

Comprehensive Audit Trail (src/utils/scopeValidation.ts)

• Scope operations: All scope validation and authorization events
• Client identification: Tracks which clients perform operations
• Success/failure tracking: Logs both successful and failed operations
• Timestamp recording: Precise timing for all security events

Security Event Logging

• Authentication events: Login attempts, token generation, failures
• Authorization events: Scope grants, denials, violations
• Rate limiting events: When limits are exceeded
• Security violations: Injection attempts, suspicious activity

Network Security

Transport Security

• HTTPS enforcement: All production traffic over encrypted connections
• CORS configuration: Proper cross-origin request handling
• Request size limits: Prevents DoS via large requests

Error Handling

• Secure error responses: No sensitive information in error messages
• Consistent error format: Standard OAuth 2.1 error format
• Error logging: Detailed errors logged server-side only

Input Sanitization (src/utils/sanitization.ts)

Context-Aware Sanitization

• HTML escaping: Prevents XSS in HTML responses
• URL parameter sanitization: Safe handling of URL parameters
• Server name sanitization: Prevents injection via server names
• Error message sanitization: Safe error message display

Backward Compatibility

Auth-Disabled Mode

• Graceful degradation: Full functionality when auth is disabled
• Tag filtering preservation: Original tag filtering when auth off
• Configuration flexibility: Runtime auth enable/disable

Migration Support

• Incremental adoption: Can enable auth gradually
• Existing client support: Works with non-OAuth clients when auth disabled

Security Testing

Comprehensive Test Coverage

• Unit tests: Scope validation, middleware functions
• Integration tests: Full authentication flows
• Security tests: Injection attempts, edge cases, timing attacks
• Performance tests: Load testing for rate limiting and validation

Security Edge Cases

• Buffer overflow prevention: Input length validation
• Null byte injection prevention: Input format validation
• Unicode attack prevention: Character set restrictions
• Prototype pollution prevention: Safe object handling

Security Best Practices

Development Guidelines

• Principle of least privilege: Minimal required scopes granted
• Fail-secure design: Default to deny access
• Defense in depth: Multiple security layers
• Regular security audits: Continuous security monitoring

Operational Security

• Secure configuration defaults: Safe out-of-box configuration
• Environment-specific settings: Different security levels per environment
• Security monitoring: Real-time security event monitoring
• Incident response: Clear procedures for security incidents

Compliance

Standards Adherence

• OAuth 2.1: Full compliance with OAuth 2.1 specification
• RFC 7636: PKCE implementation
• OWASP Top 10: Protection against common web vulnerabilities
• Security headers: Follows security header best practices

Privacy Protection

• Data minimization: Only necessary data collected and stored
• Secure storage: Encrypted session and token storage
• Access logging: Audit trail without exposing sensitive data
• User consent: Explicit consent for all data access