tsikol 0.1.0

data/docs/cookbook/authentication.md

@@ -0,0 +1,651 @@
+# Authentication Recipe
+
+This recipe shows how to add authentication to your MCP server to secure tools and resources.
+
+## Basic Token Authentication
+
+### Simple Token Middleware
+
+```ruby
+class TokenAuthMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @token = options[:token] || ENV['MCP_AUTH_TOKEN']
+    @protected_methods = options[:protected_methods] || ["tools/call", "resources/read"]
+  end
+  
+  def call(request)
+    method = request["method"]
+    
+    # Skip auth for unprotected methods
+    return @app.call(request) unless @protected_methods.include?(method)
+    
+    # Extract token from request
+    provided_token = extract_token(request)
+    
+    # Validate token
+    unless valid_token?(provided_token)
+      return unauthorized_response(request["id"])
+    end
+    
+    # Continue with request
+    @app.call(request)
+  end
+  
+  private
+  
+  def extract_token(request)
+    # Look in multiple places
+    request.dig("params", "_token") ||
+      request.dig("params", "authorization") ||
+      request.dig("meta", "authorization")
+  end
+  
+  def valid_token?(token)
+    return false unless token
+    # Constant-time comparison
+    ActiveSupport::SecurityUtils.secure_compare(token, @token)
+  rescue
+    # Fallback for non-Rails environments
+    token == @token
+  end
+  
+  def unauthorized_response(id)
+    {
+      jsonrpc: "2.0",
+      id: id,
+      error: {
+        code: -32001,
+        message: "Unauthorized",
+        data: { details: "Invalid or missing authentication token" }
+      }
+    }
+  end
+end
+
+# Usage in server.rb
+Tsikol.start(name: "secure-server") do
+  use TokenAuthMiddleware, token: ENV['AUTH_TOKEN']
+  
+  tool SecureTool
+  resource SecureResource
+end
+```
+
+## JWT Authentication
+
+### JWT Middleware with User Context
+
+```ruby
+require 'jwt'
+
+class JWTAuthMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @secret = options[:secret] || ENV['JWT_SECRET']
+    @algorithm = options[:algorithm] || 'HS256'
+    @skip_methods = options[:skip_methods] || ["initialize"]
+  end
+  
+  def call(request)
+    method = request["method"]
+    
+    # Skip auth for certain methods
+    return @app.call(request) if @skip_methods.include?(method)
+    
+    # Extract and verify JWT
+    token = extract_bearer_token(request)
+    
+    begin
+      payload = JWT.decode(token, @secret, true, algorithm: @algorithm)[0]
+      
+      # Check expiration
+      if payload['exp'] && Time.now.to_i > payload['exp']
+        return token_expired_response(request["id"])
+      end
+      
+      # Add user context to request
+      request["authenticated_user"] = payload
+      
+      # Continue with request
+      @app.call(request)
+      
+    rescue JWT::DecodeError => e
+      invalid_token_response(request["id"], e.message)
+    end
+  end
+  
+  private
+  
+  def extract_bearer_token(request)
+    auth_header = request.dig("params", "authorization") ||
+                  request.dig("meta", "authorization") || ""
+    
+    # Extract token from "Bearer <token>" format
+    auth_header.sub(/^Bearer /i, '')
+  end
+  
+  def token_expired_response(id)
+    {
+      jsonrpc: "2.0",
+      id: id,
+      error: {
+        code: -32002,
+        message: "Token expired",
+        data: { details: "Authentication token has expired" }
+      }
+    }
+  end
+  
+  def invalid_token_response(id, details)
+    {
+      jsonrpc: "2.0",
+      id: id,
+      error: {
+        code: -32001,
+        message: "Invalid token",
+        data: { details: details }
+      }
+    }
+  end
+end
+```
+
+### Using User Context in Tools
+
+```ruby
+class UserAwareTool < Tsikol::Tool
+  description "Tool that uses authenticated user information"
+  
+  parameter :action do
+    type :string
+    required
+  end
+  
+  def execute(action:)
+    # Access authenticated user from request context
+    user = Thread.current[:mcp_request]&.dig("authenticated_user")
+    
+    unless user
+      return "Authentication required"
+    end
+    
+    case action
+    when "profile"
+      get_user_profile(user)
+    when "preferences"
+      get_user_preferences(user)
+    else
+      "Unknown action"
+    end
+  end
+  
+  private
+  
+  def get_user_profile(user)
+    {
+      id: user['sub'],
+      email: user['email'],
+      name: user['name'],
+      roles: user['roles'] || []
+    }.to_json
+  end
+  
+  def get_user_preferences(user)
+    # Load preferences based on user ID
+    preferences = load_preferences(user['sub'])
+    preferences.to_json
+  end
+end
+```
+
+## API Key Authentication
+
+### Multi-Tenant API Key System
+
+```ruby
+class APIKeyAuthMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @key_store = options[:key_store] || APIKeyStore.new
+    @rate_limiter = options[:rate_limiter]
+  end
+  
+  def call(request)
+    api_key = extract_api_key(request)
+    
+    unless api_key
+      return missing_key_response(request["id"])
+    end
+    
+    # Validate API key
+    key_info = @key_store.validate(api_key)
+    
+    unless key_info
+      return invalid_key_response(request["id"])
+    end
+    
+    # Check if key is active
+    unless key_info[:active]
+      return inactive_key_response(request["id"])
+    end
+    
+    # Apply rate limiting per API key
+    if @rate_limiter && @rate_limiter.exceeded?(api_key)
+      return rate_limit_response(request["id"])
+    end
+    
+    # Add tenant context
+    request["tenant"] = key_info[:tenant]
+    request["api_key_id"] = key_info[:id]
+    request["permissions"] = key_info[:permissions]
+    
+    # Log API key usage
+    log_usage(api_key, request["method"])
+    
+    @app.call(request)
+  end
+  
+  private
+  
+  def extract_api_key(request)
+    request.dig("params", "api_key") ||
+      request.dig("meta", "x-api-key")
+  end
+  
+  def log_usage(api_key, method)
+    # Log API key usage for analytics
+    Thread.new do
+      @key_store.log_usage(api_key, method, Time.now)
+    end
+  end
+end
+
+class APIKeyStore
+  def initialize
+    @keys = load_keys_from_database
+  end
+  
+  def validate(api_key)
+    key_hash = hash_key(api_key)
+    @keys[key_hash]
+  end
+  
+  def log_usage(api_key, method, timestamp)
+    # Store usage metrics
+  end
+  
+  private
+  
+  def hash_key(api_key)
+    # Use secure hashing
+    Digest::SHA256.hexdigest(api_key)
+  end
+  
+  def load_keys_from_database
+    # Load from your database
+    # Example structure:
+    {
+      "hashed_key_1" => {
+        id: "key_123",
+        tenant: "customer_1",
+        active: true,
+        permissions: ["read", "write"],
+        created_at: Time.now - 86400 * 30
+      }
+    }
+  end
+end
+```
+
+## OAuth 2.0 Integration
+
+### OAuth Middleware
+
+```ruby
+require 'oauth2'
+
+class OAuthMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @client_id = options[:client_id] || ENV['OAUTH_CLIENT_ID']
+    @client_secret = options[:client_secret] || ENV['OAUTH_CLIENT_SECRET']
+    @site = options[:site] || 'https://auth.example.com'
+    @token_url = options[:token_url] || '/oauth/token'
+    @authorize_url = options[:authorize_url] || '/oauth/authorize'
+  end
+  
+  def call(request)
+    token = extract_oauth_token(request)
+    
+    unless token
+      return unauthorized_response(request["id"], "Missing OAuth token")
+    end
+    
+    # Validate token with OAuth provider
+    user_info = validate_token(token)
+    
+    unless user_info
+      return unauthorized_response(request["id"], "Invalid OAuth token")
+    end
+    
+    # Add user info to request
+    request["oauth_user"] = user_info
+    
+    @app.call(request)
+  rescue OAuth2::Error => e
+    unauthorized_response(request["id"], e.message)
+  end
+  
+  private
+  
+  def oauth_client
+    @oauth_client ||= OAuth2::Client.new(
+      @client_id,
+      @client_secret,
+      site: @site,
+      token_url: @token_url,
+      authorize_url: @authorize_url
+    )
+  end
+  
+  def validate_token(token_string)
+    token = OAuth2::AccessToken.new(oauth_client, token_string)
+    
+    # Validate token and get user info
+    response = token.get('/api/userinfo')
+    
+    if response.status == 200
+      JSON.parse(response.body)
+    else
+      nil
+    end
+  end
+  
+  def extract_oauth_token(request)
+    auth_header = request.dig("params", "authorization") || ""
+    auth_header.sub(/^Bearer /i, '')
+  end
+end
+```
+
+## Permission-Based Access Control
+
+### Role-Based Access Control (RBAC)
+
+```ruby
+class RBACMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @permissions = options[:permissions] || default_permissions
+  end
+  
+  def call(request)
+    method = request["method"]
+    
+    # Get required permission for method
+    required_permission = get_required_permission(method)
+    
+    # No permission required
+    return @app.call(request) unless required_permission
+    
+    # Get user from previous auth middleware
+    user = request["authenticated_user"]
+    
+    unless user
+      return unauthorized_response(request["id"], "Authentication required")
+    end
+    
+    # Check user permissions
+    user_permissions = get_user_permissions(user)
+    
+    unless has_permission?(user_permissions, required_permission)
+      return forbidden_response(request["id"], required_permission)
+    end
+    
+    @app.call(request)
+  end
+  
+  private
+  
+  def default_permissions
+    {
+      "tools/list" => "tools:read",
+      "tools/call" => "tools:execute",
+      "resources/list" => "resources:read",
+      "resources/read" => "resources:read",
+      "prompts/list" => "prompts:read",
+      "prompts/get" => "prompts:use"
+    }
+  end
+  
+  def get_required_permission(method)
+    # Check exact match first
+    return @permissions[method] if @permissions[method]
+    
+    # Check wildcard patterns
+    @permissions.each do |pattern, permission|
+      if pattern.include?("*") && method.match?(pattern.gsub("*", ".*"))
+        return permission
+      end
+    end
+    
+    nil
+  end
+  
+  def get_user_permissions(user)
+    # Get permissions from user object or load from database
+    permissions = user["permissions"] || []
+    
+    # Add role-based permissions
+    if user["roles"]
+      user["roles"].each do |role|
+        permissions.concat(role_permissions(role))
+      end
+    end
+    
+    permissions.uniq
+  end
+  
+  def role_permissions(role)
+    # Define role-based permissions
+    case role
+    when "admin"
+      ["tools:*", "resources:*", "prompts:*"]
+    when "developer"
+      ["tools:execute", "resources:read", "prompts:use"]
+    when "viewer"
+      ["tools:read", "resources:read", "prompts:read"]
+    else
+      []
+    end
+  end
+  
+  def has_permission?(user_permissions, required)
+    user_permissions.any? do |perm|
+      # Exact match
+      perm == required ||
+      # Wildcard match (e.g., "tools:*" matches "tools:execute")
+      (perm.end_with?("*") && required.start_with?(perm[0..-2]))
+    end
+  end
+  
+  def forbidden_response(id, permission)
+    {
+      jsonrpc: "2.0",
+      id: id,
+      error: {
+        code: -32003,
+        message: "Forbidden",
+        data: { 
+          details: "Insufficient permissions",
+          required: permission
+        }
+      }
+    }
+  end
+end
+```
+
+## Secure Configuration
+
+### Environment-Based Security
+
+```ruby
+# config/security.rb
+module Security
+  class Config
+    def self.load
+      {
+        auth_enabled: ENV.fetch('MCP_AUTH_ENABLED', 'true') == 'true',
+        auth_type: ENV.fetch('MCP_AUTH_TYPE', 'jwt'),
+        jwt_secret: ENV.fetch('JWT_SECRET') { raise "JWT_SECRET required" },
+        jwt_algorithm: ENV.fetch('JWT_ALGORITHM', 'HS256'),
+        token_expiry: ENV.fetch('TOKEN_EXPIRY', '3600').to_i,
+        require_https: ENV.fetch('REQUIRE_HTTPS', 'true') == 'true',
+        allowed_origins: ENV.fetch('ALLOWED_ORIGINS', '*').split(','),
+        rate_limit: {
+          enabled: ENV.fetch('RATE_LIMIT_ENABLED', 'true') == 'true',
+          max_requests: ENV.fetch('RATE_LIMIT_MAX', '100').to_i,
+          window_seconds: ENV.fetch('RATE_LIMIT_WINDOW', '60').to_i
+        }
+      }
+    end
+  end
+end
+
+# server.rb
+require_relative 'config/security'
+
+Tsikol.start(name: "secure-server") do
+  config = Security::Config.load
+  
+  if config[:auth_enabled]
+    case config[:auth_type]
+    when 'jwt'
+      use JWTAuthMiddleware, 
+          secret: config[:jwt_secret],
+          algorithm: config[:jwt_algorithm]
+    when 'api_key'
+      use APIKeyAuthMiddleware
+    when 'oauth'
+      use OAuthMiddleware
+    end
+    
+    # Add RBAC after authentication
+    use RBACMiddleware
+  end
+  
+  if config[:rate_limit][:enabled]
+    use Tsikol::RateLimitMiddleware,
+        max_requests: config[:rate_limit][:max_requests],
+        window_seconds: config[:rate_limit][:window_seconds]
+  end
+  
+  # Your tools and resources
+  tool SecureTool
+  resource SecureResource
+end
+```
+
+## Testing Authentication
+
+```ruby
+require 'minitest/autorun'
+require 'jwt'
+
+class AuthenticationTest < Minitest::Test
+  def setup
+    @server = create_secure_server
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+  end
+  
+  def test_requires_authentication
+    response = @client.call_tool("secure_tool", {})
+    assert_error_response(response, -32001)
+    assert_match /unauthorized/i, response[:error][:message]
+  end
+  
+  def test_accepts_valid_token
+    token = generate_valid_jwt
+    
+    response = @client.call_tool("secure_tool", {
+      "_token" => token,
+      "action" => "test"
+    })
+    
+    assert_successful_response(response)
+  end
+  
+  def test_rejects_expired_token
+    token = generate_expired_jwt
+    
+    response = @client.call_tool("secure_tool", {
+      "_token" => token,
+      "action" => "test"
+    })
+    
+    assert_error_response(response, -32002)
+    assert_match /expired/i, response[:error][:message]
+  end
+  
+  def test_enforces_permissions
+    # User with limited permissions
+    token = generate_jwt_with_permissions(["tools:read"])
+    
+    response = @client.call_tool("secure_tool", {
+      "_token" => token,
+      "action" => "write"  # Requires tools:execute
+    })
+    
+    assert_error_response(response, -32003)
+    assert_match /forbidden/i, response[:error][:message]
+  end
+  
+  private
+  
+  def create_secure_server
+    server = Tsikol::Server.new(name: "test")
+    server.use JWTAuthMiddleware, secret: "test_secret"
+    server.use RBACMiddleware
+    server.register_tool_instance(SecureTool.new)
+    server
+  end
+  
+  def generate_valid_jwt
+    payload = {
+      sub: "user123",
+      email: "user@example.com",
+      permissions: ["tools:execute"],
+      exp: Time.now.to_i + 3600
+    }
+    JWT.encode(payload, "test_secret", 'HS256')
+  end
+  
+  def generate_expired_jwt
+    payload = {
+      sub: "user123",
+      exp: Time.now.to_i - 3600  # Expired 1 hour ago
+    }
+    JWT.encode(payload, "test_secret", 'HS256')
+  end
+end
+```
+
+## Security Best Practices
+
+1. **Always use HTTPS** in production
+2. **Store secrets securely** using environment variables or secret management systems
+3. **Implement rate limiting** to prevent abuse
+4. **Log authentication attempts** for security monitoring
+5. **Use secure token storage** with proper expiration
+6. **Implement CSRF protection** for web-based clients
+7. **Regular security audits** of your authentication system
+8. **Principle of least privilege** for permissions
+
+## Next Steps
+
+- Implement [Rate Limiting](rate-limiting.md)
+- Add [Logging](logging.md) for security events
+- Set up [Error Handling](error-handling.md)
+- Review [Testing Guide](../guides/testing.md)