aris 1.4.2 → 1.5.0

data/docs/plugins/REQUEST_LOGGER.md

@@ -0,0 +1,151 @@
+# Request Logger Plugin
+
+Log incoming HTTP requests in text or JSON format.
+
+## Installation
+
+```ruby
+require_relative 'aris/plugins/request_logger'
+```
+
+## Basic Usage
+
+```ruby
+logger = Aris::Plugins::RequestLogger.build
+
+Aris.routes({
+  "example.com": {
+    use: [logger],
+    "/users": { get: { to: UsersHandler } }
+  }
+})
+```
+
+**Output (text):**
+```
+GET /users
+POST /users/123
+DELETE /users/456
+```
+
+---
+
+## Configuration
+
+```ruby
+logger = Aris::Plugins::RequestLogger.build(
+  format: :json,                    # :text or :json
+  exclude: ['/health', '/metrics'], # Skip these paths
+  logger: Rails.logger              # Custom logger (default: STDOUT)
+)
+```
+
+---
+
+## JSON Format
+
+```ruby
+logger = Aris::Plugins::RequestLogger.build(format: :json)
+```
+
+**Output:**
+```json
+{"method":"GET","path":"/users","host":"api.example.com","timestamp":"2025-01-10T12:34:56Z"}
+{"method":"POST","path":"/users","host":"api.example.com","timestamp":"2025-01-10T12:35:02Z"}
+```
+
+---
+
+## Common Patterns
+
+### Exclude Health Checks
+
+```ruby
+logger = Aris::Plugins::RequestLogger.build(
+  exclude: ['/health', '/ping', '/metrics']
+)
+```
+
+### Custom Logger
+
+```ruby
+# File logger
+file_logger = Logger.new('log/requests.log')
+logger = Aris::Plugins::RequestLogger.build(logger: file_logger)
+
+# Rails logger
+logger = Aris::Plugins::RequestLogger.build(logger: Rails.logger)
+```
+
+### Different Logs Per Domain
+
+```ruby
+api_logger = Aris::Plugins::RequestLogger.build(
+  format: :json,
+  logger: Logger.new('log/api.log')
+)
+
+admin_logger = Aris::Plugins::RequestLogger.build(
+  format: :text,
+  logger: Logger.new('log/admin.log')
+)
+
+Aris.routes({
+  "api.example.com": {
+    use: [api_logger],
+    "/data": { get: { to: DataHandler } }
+  },
+  "admin.example.com": {
+    use: [admin_logger],
+    "/dashboard": { get: { to: DashboardHandler } }
+  }
+})
+```
+
+---
+
+## Production Tips
+
+**1. JSON Format for Log Aggregation**
+
+```ruby
+# Works great with ELK, Splunk, CloudWatch
+logger = Aris::Plugins::RequestLogger.build(
+  format: :json,
+  logger: Logger.new(STDOUT)  # Docker captures STDOUT
+)
+```
+
+**2. Exclude Noisy Endpoints**
+
+```ruby
+logger = Aris::Plugins::RequestLogger.build(
+  exclude: [
+    '/health',
+    '/metrics',
+    '/favicon.ico',
+    '/robots.txt'
+  ]
+)
+```
+
+**3. Log Level**
+
+```ruby
+custom_logger = Logger.new(STDOUT)
+custom_logger.level = Logger::INFO  # or WARN, ERROR
+
+logger = Aris::Plugins::RequestLogger.build(logger: custom_logger)
+```
+
+---
+
+## Limitations
+
+- Logs incoming requests only (no response status/duration)
+- For response logging, use Rack middleware or application logs
+- No request body logging (use separate middleware for that)
+
+---
+
+Need help? Check out the [full plugin development guide](../docs/plugin-development.md).

data/docs/plugins/SECURITY.md

@@ -0,0 +1,193 @@
+# Security Headers Plugin
+
+Add essential security headers to protect against common web vulnerabilities.
+
+## Installation
+
+```ruby
+require_relative 'aris/plugins/security_headers'
+```
+
+## Basic Usage
+
+### Secure Defaults
+
+```ruby
+security = Aris::Plugins::SecurityHeaders.build
+
+Aris.routes({
+  "example.com": {
+    use: [security],
+    "/": { get: { to: HomeHandler } }
+  }
+})
+```
+
+**Headers set:**
+```
+X-Frame-Options: SAMEORIGIN
+X-content-type-Options: nosniff
+X-XSS-Protection: 0
+Referrer-Policy: strict-origin-when-cross-origin
+```
+
+---
+
+## Configuration
+
+```ruby
+security = Aris::Plugins::SecurityHeaders.build(
+  x_frame_options: 'DENY',
+  x_content_type_options: 'nosniff',
+  hsts: { max_age: 63072000, include_subdomains: true, preload: true },
+  csp: "default-src 'self'; script-src 'self' 'unsafe-inline'",
+  referrer_policy: 'no-referrer',
+  permissions_policy: 'geolocation=(), microphone=()'
+)
+```
+
+### Options
+
+| Option | Default | Description |
+|:---|:---|:---|
+| `x_frame_options` | `'SAMEORIGIN'` | Prevent clickjacking (`DENY`, `SAMEORIGIN`, `nil`) |
+| `x_content_type_options` | `'nosniff'` | Prevent MIME sniffing |
+| `x_xss_protection` | `'0'` | Disable legacy XSS filter (modern browsers ignore) |
+| `hsts` | Not set | HTTP Strict Transport Security |
+| `csp` | Not set | Content Security Policy |
+| `referrer_policy` | `'strict-origin-when-cross-origin'` | Referrer behavior |
+| `permissions_policy` | Not set | Control browser features |
+| `defaults` | `true` | Enable default headers |
+
+---
+
+## Common Patterns
+
+### Production API
+
+```ruby
+api_security = Aris::Plugins::SecurityHeaders.build(
+  x_frame_options: 'DENY',
+  hsts: { max_age: 31536000, include_subdomains: true },
+  csp: "default-src 'none'",
+  referrer_policy: 'no-referrer'
+)
+```
+
+### Web Application
+
+```ruby
+web_security = Aris::Plugins::SecurityHeaders.build(
+  x_frame_options: 'SAMEORIGIN',
+  hsts: true,
+  csp: "default-src 'self'; script-src 'self' https://cdn.example.com; style-src 'self' 'unsafe-inline'",
+  referrer_policy: 'strict-origin-when-cross-origin'
+)
+```
+
+### Different Security Per Route
+
+```ruby
+strict = Aris::Plugins::SecurityHeaders.build(x_frame_options: 'DENY')
+relaxed = Aris::Plugins::SecurityHeaders.build(x_frame_options: 'SAMEORIGIN')
+
+Aris.routes({
+  "example.com": {
+    "/admin": {
+      use: [strict],
+      get: { to: AdminHandler }
+    },
+    "/public": {
+      use: [relaxed],
+      get: { to: PublicHandler }
+    }
+  }
+})
+```
+
+---
+
+## Header Details
+
+**X-Frame-Options**
+- `DENY` - Cannot be framed at all
+- `SAMEORIGIN` - Can be framed by same origin only
+
+**HSTS (HTTP Strict Transport Security)**
+```ruby
+hsts: true  # Simple: max-age=31536000; includeSubDomains
+
+hsts: {
+  max_age: 63072000,         # 2 years
+  include_subdomains: true,
+  preload: true              # Submit to browser preload list
+}
+```
+
+**Content-Security-Policy**
+```ruby
+csp: "default-src 'self'; script-src 'self' 'unsafe-inline'; img-src * data:"
+```
+
+**Permissions-Policy**
+```ruby
+permissions_policy: 'camera=(), microphone=(), geolocation=(self)'
+```
+
+---
+
+## Production Tips
+
+**1. Start Strict, Relax as Needed**
+
+```ruby
+# Start with strictest settings
+security = Aris::Plugins::SecurityHeaders.build(
+  x_frame_options: 'DENY',
+  hsts: { max_age: 31536000, include_subdomains: true },
+  csp: "default-src 'self'"
+)
+
+# Relax only where necessary
+```
+
+**2. Test CSP in Report-Only Mode First**
+
+```ruby
+# Development/Staging
+security = Aris::Plugins::SecurityHeaders.build(
+  csp: "default-src 'self'; report-uri /csp-report"
+)
+
+# Monitor violations before enforcing
+```
+
+**3. HSTS Considerations**
+
+- Start with short `max_age` (300 seconds) to test
+- Increase gradually (3600 → 86400 → 31536000)
+- Only enable `preload` when confident (irreversible!)
+
+**4. Environment-Specific Configs**
+
+```ruby
+security = Aris::Plugins::SecurityHeaders.build(
+  hsts: Rails.env.production? ? { max_age: 31536000 } : nil,
+  csp: ENV['CSP_POLICY']
+)
+```
+
+---
+
+## Security Notes
+
+- ✅ Essential first layer of defense
+- ✅ Protect against clickjacking, XSS, MIME sniffing
+- ✅ Combine with HTTPS (especially HSTS)
+- ❌ Headers alone don't prevent all attacks
+- ❌ CSP requires careful tuning for complex apps
+
+
+---
+
+Need help? Check out the [full plugin development guide](../docs/plugin-development.md).

data/docs/plugins/SESSION.md

@@ -0,0 +1,98 @@
+# Session Plugin
+
+Cookie-based sessions that are safe to use for authentication.
+
+The session is stored in a single cookie as an **AES-256-GCM encrypted and authenticated** payload, keyed from `Aris::Config.secret_key_base`. The browser cannot read what is inside, and a modified, forged, expired, or wrong-key cookie loads as an empty session instead of raising.
+
+## Setup
+
+```ruby
+Aris.configure do |c|
+  c.secret_key_base = ENV.fetch('SECRET_KEY_BASE')  # at least 32 bytes; generate with:
+                                                     # ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'
+end
+
+Aris.routes({
+  "example.com": {
+    use: [:session],
+    "/login"  => { post: { to: LoginHandler } },
+    "/logout" => { post: { to: LogoutHandler } },
+    "/me"     => { get:  { to: MeHandler } }
+  }
+})
+```
+
+Without a secret, the first write to a session raises `ArgumentError` with a message that says so.
+
+## Reading and writing
+
+```ruby
+class LoginHandler
+  def self.call(request, response, params)
+    user = Users.authenticate(request.form_params['email'], request.form_params['password'])
+    return response.redirect('/login') unless user
+    request.session[:user_id] = user[:id]
+    response.redirect('/')
+  end
+end
+
+class MeHandler
+  def self.call(request, response, params)
+    user_id = request.session[:user_id]           # nil when not logged in
+    request.session.key?(:user_id)                # => true/false
+    request.session.fetch(:theme, 'light')
+    response.text("You are #{user_id}")
+  end
+end
+
+class LogoutHandler
+  def self.call(request, response, params)
+    request.session.destroy                       # clears the data and deletes the cookie
+    response.redirect('/login')
+  end
+end
+```
+
+Other methods: `delete(key)`, `clear`, `to_h`, `changed?`, `destroyed?`. Keys are symbols (strings are converted).
+
+The cookie is only written when the session changed during the request. An empty session removes the cookie.
+
+## Options
+
+Set defaults for every scope:
+
+```ruby
+Aris::Plugins::Session.default_config = Aris::Plugins::Session.default_config.merge(
+  key: '_myapp_session',
+  expire_after: 7 * 24 * 3600     # seconds; default 14 days
+)
+```
+
+Or build a configured instance for one scope:
+
+```ruby
+use: [Aris::Plugins::Session.build(key: '_admin', expire_after: 3600, same_site: :strict)]
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `key` | `'_aris_session'` | Cookie name |
+| `expire_after` | 14 days | Lifetime in seconds — enforced server-side, not just via `Max-Age` |
+| `secret` | `Aris::Config.secret_key_base` | Encryption key source (≥ 32 bytes) |
+| `secure` | from `Config.cookie_options`, else `true` in production | Send the cookie only over HTTPS |
+| `same_site` | `:lax` | `SameSite` attribute |
+| `path` | `'/'` | Cookie path |
+
+The cookie is always `HttpOnly`.
+
+## Rotating the secret
+
+Changing `secret_key_base` invalidates every existing session (everyone is logged out). That is the intended way to revoke all sessions at once.
+
+## Pairing with CSRF
+
+`use: [:session, :form_parser, :csrf]` — the CSRF token lives in the session. See [CSRF.md](CSRF.md).
+
+## Before 1.5
+
+Sessions were Base64-encoded JSON (readable and forgeable) and the Rack adapter never read cookies back, so they did not persist at all. Any 1.4 session cookie is ignored by 1.5.

data/lib/aris/adapters/rack/adapter.rb

@@ -141,17 +141,32 @@ module Aris
           body = active_res.body
           body = [body] if body.is_a?(String)
           
-          return [active_res.status, active_res.headers, body]
+          return [active_res.status, rack3_headers(active_res.headers), body]
         end
 
         # 3. Final Fallback (If Joys rendered nothing)
         case result
-        when Array then result
+        when Array then [result[0], rack3_headers(result[1] || {}), result[2]]
         when Hash  then [200, {'content-type' => 'application/json'}, [result.to_json]]
         else            [200, {'content-type' => 'text/plain'}, [result.to_s]]
         end
       end
 
+      # Rack 3 requires lowercase header names, and a header with several
+      # values (set-cookie) must be an Array, never a comma-joined String.
+      def rack3_headers(headers)
+        out = {}
+        headers.each do |key, value|
+          name = key.to_s.downcase
+          if out.key?(name)
+            out[name] = Array(out[name]) + Array(value)
+          else
+            out[name] = value
+          end
+        end
+        out
+      end
+
 
     end
   end

data/lib/aris/adapters/rack/request.rb

@@ -1,30 +1,37 @@
 # lib/aris/adapters/rack/request.rb
+require 'rack/utils'
+
 module Aris
   module Adapters
     module Rack
       class Request
         attr_reader :env
         attr_accessor :json_body
-        
+
         def initialize(env)
           @env = env
         end
-        
-        # Add cookies method to match Mock adapter interface
+
+        # Cookies sent by the client, parsed from the Cookie header.
+        # (Before 1.5 this read env['rack.request.cookie_hash'], which nothing
+        # populated, so cookies were always empty under the Rack adapter.)
         def cookies
-          @env['rack.request.cookie_hash'] || {}
+          @cookies ||= begin
+            header = @env['HTTP_COOKIE']
+            header && !header.empty? ? ::Rack::Utils.parse_cookies_header(header) : {}
+          end
         end
-        
+
         def host
           @env['HTTP_HOST'] || @env['SERVER_NAME']
         end
-        
+
         alias_method :domain, :host
 
         def request_method
           @env['REQUEST_METHOD']
         end
-        
+
         def method
           @env['REQUEST_METHOD']
         end
@@ -32,7 +39,7 @@ module Aris
         def path_info
           @env['PATH_INFO']
         end
-        
+
         alias_method :path, :path_info
 
         def query
@@ -43,14 +50,25 @@ module Aris
           @env.select { |k, v| k.start_with?('HTTP_') }
         end
 
+        # The raw request body. Read once and memoized, and the input is
+        # rewound afterwards, so plugins and handlers can all call it.
         def body
-          @env['rack.input']&.read
+          return @body if defined?(@body)
+          input = @env['rack.input']
+          @body = if input
+            input.rewind if input.respond_to?(:rewind)
+            data = input.read
+            input.rewind if input.respond_to?(:rewind)
+            data
+          end
         end
 
+        # Query-string parameters. The FormParser plugin merges parsed form
+        # fields into this hash as well, so handlers can read both from here.
         def params
           @params ||= ::Rack::Utils.parse_nested_query(@env['QUERY_STRING'] || '')
         end
-        
+
         def [](key)
           case key
           when :method then method
@@ -63,4 +81,4 @@ module Aris
       end
     end
   end
-end
+end

data/lib/aris/plugins/basic_auth.rb

@@ -65,4 +65,6 @@ module Aris
       end
     end
   end
-end
+end
+# BasicAuth always needs credentials, so it is used as an instance:
+#   use: [Aris::Plugins::BasicAuth.build(username: 'u', password: 'p')]

data/lib/aris/plugins/cookies.rb

@@ -1,46 +1,18 @@
 # lib/aris/plugins/cookies.rb
 module Aris
   module Plugins
+    # Since 1.5, `set_cookie` and `delete_cookie` live on every response
+    # (Aris::ResponseHelpers), so this plugin no longer needs to inject them.
+    # It stays registered so `use: [:cookies]` keeps working in existing apps.
     class Cookies
       def self.call(request, response)
-        # Only add cookie helpers when plugin is used
-        add_cookie_helpers(request, response)
         nil # Continue pipeline
       end
 
       def self.build(**config)
         self
       end
-
-      private
-
-      def self.add_cookie_helpers(request, response)
-        # Add cookie writing methods to response
-        response.define_singleton_method(:set_cookie) do |name, value, options = {}|
-          default_options = Aris::Config.cookie_options || {}
-          merged_options = default_options.merge(options)
-          
-          cookie_parts = ["#{name}=#{value}"]
-          cookie_parts << "Path=#{merged_options[:path]}" if merged_options[:path]
-          cookie_parts << "HttpOnly" if merged_options[:httponly]
-          cookie_parts << "Secure" if merged_options[:secure]
-          cookie_parts << "Max-Age=#{merged_options[:max_age]}" if merged_options[:max_age]
-          cookie_parts << "SameSite=#{merged_options[:same_site]}" if merged_options[:same_site]
-          
-          cookie_string = cookie_parts.join("; ")
-          
-          if headers['Set-Cookie']
-            headers['Set-Cookie'] = [headers['Set-Cookie'], cookie_string].join(", ")
-          else
-            headers['Set-Cookie'] = cookie_string
-          end
-        end
-
-        response.define_singleton_method(:delete_cookie) do |name, options = {}|
-          set_cookie(name, "", options.merge(max_age: 0))
-        end
-      end
     end
   end
 end
-Aris.register_plugin(:cookies, plugin_class: Aris::Plugins::Cookies)
+Aris.register_plugin(:cookies, plugin_class: Aris::Plugins::Cookies)

data/lib/aris/plugins/cors.rb

@@ -53,6 +53,11 @@ module Aris
       def self.build(**config)
         new(**config)
       end
+
+      # `use: [:cors]` (the bare symbol) runs an instance with default options.
+      def self.call(request, response)
+        (@default_instance ||= new).call(request, response)
+      end
       
       private
       
@@ -78,4 +83,6 @@ module Aris
       end
     end
   end
-end
+end
+# Self-register so `use: [:cors]` works without an explicit register_plugin call.
+Aris.register_plugin(:cors, plugin_class: Aris::Plugins::Cors)