Class: Otto::Security::Configurator

Inherits:
Object
  • Object
show all
Defined in:
lib/otto/security/configurator.rb

Overview

Consolidates all security configuration methods into a single configurator class. This provides a unified interface for configuring CSRF protection, input validation, rate limiting, trusted proxies, and authentication strategies.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(security_config, middleware_stack, auth_config = nil) ⇒ Configurator

Returns a new instance of Configurator.



19
20
21
22
23
24
 
# File 'lib/otto/security/configurator.rb', line 19

def initialize(security_config, middleware_stack, auth_config = nil)
  @security_config = security_config
  @middleware_stack = middleware_stack
  # Use provided auth_config or initialize a new one
  @auth_config = auth_config || { auth_strategies: {}, default_auth_strategy: 'noauth' }
end

Instance Attribute Details

#auth_config ⇒ Object

Returns the value of attribute auth_config.



17
18
19
 
# File 'lib/otto/security/configurator.rb', line 17

def auth_config
  @auth_config
end

#middleware_stack ⇒ Object (readonly)

Returns the value of attribute middleware_stack.



16
17
18
 
# File 'lib/otto/security/configurator.rb', line 16

def middleware_stack
  @middleware_stack
end

#security_config ⇒ Object (readonly)

Returns the value of attribute security_config.



16
17
18
 
# File 'lib/otto/security/configurator.rb', line 16

def security_config
  @security_config
end

Instance Method Details

#add_auth_strategy(name, strategy) ⇒ Object

Add a single authentication strategy

Part of the Security::Configurator facade for consolidated configuration. This delegates to the same storage as Otto#add_auth_strategy, allowing authentication to be configured alongside other security features.

Prefer using Otto#add_auth_strategy directly for simpler cases, or use this when configuring multiple security features together via the security facade.

Examples:

otto.security.add_auth_strategy('session', SessionStrategy.new)

Parameters:

Raises:

  • (ArgumentError) —

    if strategy name already registered



215
216
217
218
219
220
221
222
 
# File 'lib/otto/security/configurator.rb', line 215

def add_auth_strategy(name, strategy)
  # Strict mode: Detect strategy name collisions
  if @auth_config[:auth_strategies].key?(name)
    raise ArgumentError, "Authentication strategy '#{name}' is already registered"
  end

  @auth_config[:auth_strategies][name] = strategy
end

#add_rate_limit_rule(name, options) ⇒ Object

Add a custom rate limiting rule.

Parameters:

  • name (String, Symbol) —

    Rule name

  • options (Hash) —

    Rule configuration

Options Hash (options):

  • :limit (Integer) —

    Maximum requests

  • :period (Integer) —

    Time period in seconds (default: 60)

  • :condition (Proc) —

    Optional condition proc that receives request



128
129
130
 
# File 'lib/otto/security/configurator.rb', line 128

def add_rate_limit_rule(name, options)
  @security_config.rate_limiting_config[:custom_rules][name.to_s] = options
end

#add_trusted_proxy(proxy) ⇒ Object

Add a trusted proxy server for accurate client IP detection. Only requests from trusted proxies will have their forwarded headers honored.

Parameters:

  • proxy (String, Regexp) —

    IP address, CIDR range, or regex pattern



136
137
138
 
# File 'lib/otto/security/configurator.rb', line 136

def add_trusted_proxy(proxy)
  @security_config.add_trusted_proxy(proxy)
end

#configure(csrf_protection: false, request_validation: false, rate_limiting: false, trusted_proxies: [], trusted_proxy_depth: nil, trusted_proxy_header: nil, security_headers: {}, hsts: false, csp: false, frame_protection: false, authentication: false) ⇒ Object

Unified security configuration method with sensible defaults

Provides a comprehensive, one-stop configuration method for Otto’s security features. This method allows configuring multiple security aspects in a single call, with flexible options.

Examples:

Configure multiple security features in one call

otto.security.configure(
  csrf_protection: true,
  request_validation: true,
  rate_limiting: { requests_per_minute: 100 },
  trusted_proxies: ['10.0.0.0/8'],
  security_headers: { 'x-custom-header' => 'value' },
  hsts: true,
  csp: "default-src 'self'",
  frame_protection: 'SAMEORIGIN'
)

Parameters:

  • csrf_protection (Boolean, Hash) (defaults to: false) —

    Enable CSRF protection

    • ‘true`: Enable with default settings

    • ‘Hash`: Provide custom CSRF configuration

  • request_validation (Boolean) (defaults to: false) —

    Enable input validation and sanitization

  • rate_limiting (Boolean, Hash) (defaults to: false) —

    Enable rate limiting

    • ‘true`: Enable with default settings

    • ‘Hash`: Provide custom rate limiting rules

  • trusted_proxies (String, Array<String>) (defaults to: []) —

    IP addresses or CIDR ranges to trust

  • trusted_proxy_depth (Integer, nil) (defaults to: nil) —

    Count-based proxy depth (“trust the last N hops”) for non-enumerable proxy tiers; mutually exclusive with trusted_proxies (validated at configuration freeze)

  • trusted_proxy_header (String, nil) (defaults to: nil) —

    Forwarded header depth mode counts hops from: ‘X-Forwarded-For’ (default), ‘Forwarded’ (RFC 7239), or ‘Both’. Only consulted in depth mode.

  • security_headers (Hash) (defaults to: {}) —

    Custom security headers to merge with defaults

  • hsts (Boolean) (defaults to: false) —

    Enable HTTP Strict Transport Security

  • csp (Boolean, String) (defaults to: false) —

    Enable Content Security Policy

  • frame_protection (Boolean, String) (defaults to: false) —

    Enable frame protection

  • authentication (Boolean) (defaults to: false) —

    Enable authentication



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/otto/security/configurator.rb', line 62

def configure(
  csrf_protection: false,
  request_validation: false,
  rate_limiting: false,
  trusted_proxies: [],
  trusted_proxy_depth: nil,
  trusted_proxy_header: nil,
  security_headers: {},
  hsts: false,
  csp: false,
  frame_protection: false,
  authentication: false
)
  enable_csrf_protection! if csrf_protection
  enable_request_validation! if request_validation
  enable_rate_limiting!(rate_limiting.is_a?(Hash) ? rate_limiting : {}) if rate_limiting

  Array(trusted_proxies).each { |proxy| add_trusted_proxy(proxy) }
  self.trusted_proxy_depth = trusted_proxy_depth unless trusted_proxy_depth.nil?
  self.trusted_proxy_header = trusted_proxy_header unless trusted_proxy_header.nil?
  self.security_headers = security_headers unless security_headers.empty?

  enable_hsts! if hsts
  enable_csp! if csp
  enable_frame_protection! if frame_protection
end

#configure_auth_strategies(strategies, default_strategy: 'noauth') ⇒ Object

Configure authentication strategies for route-level access control.

Parameters:

  • strategies (Hash) —

    Hash mapping strategy names to strategy instances

  • default_strategy (String) (defaults to: 'noauth') —

    Default strategy to use when none specified



228
229
230
231
232
 
# File 'lib/otto/security/configurator.rb', line 228

def configure_auth_strategies(strategies, default_strategy: 'noauth')
  # Merge new strategies with existing ones, preserving shared state
  @auth_config[:auth_strategies].merge!(strategies)
  @auth_config[:default_auth_strategy] = default_strategy
end

#configure_rate_limiting(config) ⇒ Object

Configure rate limiting settings.

Parameters:

  • config (Hash) —

    Rate limiting configuration

Options Hash (config):

  • :requests_per_minute (Integer) —

    Maximum requests per minute per IP

  • :custom_rules (Hash) —

    Hash of custom rate limiting rules

  • :cache_store (Object) —

    Custom cache store for rate limiting



240
241
242
 
# File 'lib/otto/security/configurator.rb', line 240

def configure_rate_limiting(config)
  @security_config.rate_limiting_config.merge!(config)
end

#enable_csp!(policy = "default-src 'self'") ⇒ Object

Enable Content Security Policy (CSP) header to prevent XSS attacks. The default policy only allows resources from the same origin.

Parameters:

  • policy (String) (defaults to: "default-src 'self'") —

    CSP policy string (default: “default-src ‘self’”)



182
183
184
 
# File 'lib/otto/security/configurator.rb', line 182

def enable_csp!(policy = "default-src 'self'")
  @security_config.enable_csp!(policy)
end

#enable_csp_with_nonce!(debug: false) ⇒ Object

Enable Content Security Policy (CSP) with nonce support for dynamic header generation. This enables the res.send_csp_headers response helper method.

Parameters:

  • debug (Boolean) (defaults to: false) —

    Enable debug logging for CSP headers (default: false)



197
198
199
 
# File 'lib/otto/security/configurator.rb', line 197

def enable_csp_with_nonce!(debug: false)
  @security_config.enable_csp_with_nonce!(debug: debug)
end

#enable_csrf_protection! ⇒ Object

Enable CSRF protection for POST, PUT, DELETE, and PATCH requests. This will automatically add CSRF tokens to HTML forms and validate them on unsafe HTTP methods.



92
93
94
95
96
97
 
# File 'lib/otto/security/configurator.rb', line 92

def enable_csrf_protection!
  return if middleware_enabled?(Otto::Security::Middleware::CSRFMiddleware)

  @security_config.enable_csrf_protection!
  @middleware_stack.add(Otto::Security::Middleware::CSRFMiddleware)
end

#enable_frame_protection!(option = 'SAMEORIGIN') ⇒ Object

Enable X-Frame-Options header to prevent clickjacking attacks.

Parameters:

  • option (String) (defaults to: 'SAMEORIGIN') —

    Frame options: ‘DENY’, ‘SAMEORIGIN’, or ‘ALLOW-FROM uri’



189
190
191
 
# File 'lib/otto/security/configurator.rb', line 189

def enable_frame_protection!(option = 'SAMEORIGIN')
  @security_config.enable_frame_protection!(option)
end

#enable_hsts!(max_age: 31_536_000, include_subdomains: true) ⇒ Object

Enable HTTP Strict Transport Security (HSTS) header. WARNING: This can make your domain inaccessible if HTTPS is not properly configured. Only enable this when you’re certain HTTPS is working correctly.

Parameters:

  • max_age (Integer) (defaults to: 31_536_000) —

    Maximum age in seconds (default: 1 year)

  • include_subdomains (Boolean) (defaults to: true) —

    Apply to all subdomains (default: true)



174
175
176
 
# File 'lib/otto/security/configurator.rb', line 174

def enable_hsts!(max_age: 31_536_000, include_subdomains: true)
  @security_config.enable_hsts!(max_age: max_age, include_subdomains: include_subdomains)
end

#enable_rate_limiting!(options = {}) ⇒ Object

Enable rate limiting to protect against abuse and DDoS attacks. This will automatically add rate limiting rules based on client IP.

Parameters:

  • options (Hash) (defaults to: {}) —

    Rate limiting configuration options

Options Hash (options):

  • :requests_per_minute (Integer) —

    Maximum requests per minute per IP (default: 100)

  • :custom_rules (Hash) —

    Custom rate limiting rules



114
115
116
117
118
119
 
# File 'lib/otto/security/configurator.rb', line 114

def enable_rate_limiting!(options = {})
  return if middleware_enabled?(Otto::Security::Middleware::RateLimitMiddleware)

  configure_rate_limiting(options)
  @middleware_stack.add(Otto::Security::Middleware::RateLimitMiddleware)
end

#enable_request_validation! ⇒ Object

Enable request validation including input sanitization, size limits, and protection against XSS and SQL injection attacks.



101
102
103
104
105
106
 
# File 'lib/otto/security/configurator.rb', line 101

def enable_request_validation!
  return if middleware_enabled?(Otto::Security::Middleware::ValidationMiddleware)

  @security_config.input_validation = true
  @middleware_stack.add(Otto::Security::Middleware::ValidationMiddleware)
end

#security_headers=(headers) ⇒ Object

Set custom security headers that will be added to all responses. These merge with the default security headers.

Parameters:

  • headers (Hash) —

    Hash of header name => value pairs



164
165
166
 
# File 'lib/otto/security/configurator.rb', line 164

def security_headers=(headers)
  @security_config.security_headers.merge!(headers)
end

#trusted_proxy_depth=(depth) ⇒ Object

Set count-based trusted-proxy depth (“trust the last N hops”) for non-enumerable proxy tiers (Fly, cloud load balancers, dynamic reverse proxies). Mutually exclusive with trusted_proxies; the conflict is validated when the configuration is frozen.

Parameters:

  • depth (Integer, nil) —

    number of trusted hops (nil/0 disables depth mode)



146
147
148
 
# File 'lib/otto/security/configurator.rb', line 146

def trusted_proxy_depth=(depth)
  @security_config.trusted_proxy_depth = depth
end

#trusted_proxy_header=(header) ⇒ Object

Select which forwarded header depth mode counts hops from: ‘X-Forwarded-For’ (default), ‘Forwarded’ (RFC 7239), or ‘Both’. Only consulted when depth mode is active. Mirrors OneTimeSecret’s site.network.trusted_proxy.header.

Parameters:

  • header (String) —

    one of Otto::Security::Config::TRUSTED_PROXY_HEADERS



156
157
158
 
# File 'lib/otto/security/configurator.rb', line 156

def trusted_proxy_header=(header)
  @security_config.trusted_proxy_header = header
end