itsi-server 0.1.1 → 0.2.2

data/lib/itsi/server/config/known_paths/wellknown-rfc5785.txt

@@ -0,0 +1,30 @@
+.well-known/
+.well-known/acme-challenge
+.well-known/apple-app-site-association
+.well-known/apple-developer-merchant-domain-association
+.well-known/ashrae
+.well-known/assetlinks.json
+.well-known/browserid
+.well-known/caldav
+.well-known/carddav
+.well-known/core
+.well-known/csvm
+.well-known/dnt
+.well-known/dnt-policy.txt
+.well-known/est
+.well-known/genid
+.well-known/hoba
+.well-known/host-meta
+.well-known/host-meta.json
+.well-known/keybase.txt
+.well-known/ni
+.well-known/openid-configuration
+.well-known/openorg
+.well-known/posh
+.well-known/reload-config
+.well-known/repute-template
+.well-known/stun-key
+.well-known/time
+.well-known/timezone
+.well-known/void
+.well-known/webfinger

data/lib/itsi/server/config/known_paths.rb

@@ -0,0 +1,20 @@
+module Itsi
+  class Server
+    module KnownPaths
+      ALL = []
+      Dir.glob(File.join(__dir__, 'known_paths', '**', '*.txt')).each do |file|
+        method_name = file[/known_paths\/(.*?)\.txt/,1].gsub(/([a-z])([A-Z])/, "\\1_\\2")
+          .gsub(/-|\.|\//, "_")
+          .gsub(/(^|\/)[0-9]/){|match| "FO"}.downcase.to_sym
+
+        ALL << method_name
+        self.define_singleton_method(method_name) do
+          File.readlines(file).map do |s|
+            s.force_encoding('UTF-8')
+            s.valid_encoding? ? s.strip : s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/middleware/_index.md

@@ -0,0 +1,56 @@
+---
+title: Middleware
+type: docs
+next: allow_list/
+url: /middleware
+prev: options/
+cascade:
+  type: docs
+weight: 2
+---
+
+Itsi Middleware stacks are modular in nature.
+You can pick and choose **just** the features that make sense for you,
+and apply these on a *location-by-location* basis.
+
+{{% details title="What's a location?" closed="false" %}}
+
+> A location in Itsi is similar to a Location in NGINX. It's a logical container for all requests matching some combination of:
+* Routes/Route expressions
+* Request Methods
+* Content Types
+* Accept Headers
+* File types
+* Host/port/scheme.
+
+For example:
+
+```ruby
+location "/admin/*" do
+
+  etag \
+    type: 'strong',
+    algorithm: 'md5',
+    min_body_size: 1024 * 1024
+  # ...
+
+  location "/public/images", extensions: %w[jpg png] do
+    compress \
+      min_size: 1024 * 1024,
+      level: 'fastest',
+      algorithms: %w[zstd gzip br deflate],
+      mime_types: %w[all],
+      compress_streams: true
+    # ...
+  end
+end
+```
+
+
+
+When a route matches a location block, it recursively inherits *all* middleware that is defined within outer ancestor blocks.
+Where a child and an ancestor define the same middleware, the child's middleware takes precedence.
+
+{{% /details %}}
+
+See [location](/middleware/location) for a detailed description of the `location` function.

data/lib/itsi/server/config/middleware/allow_list.md

@@ -0,0 +1,46 @@
+---
+title: Allow List
+url: /middleware/allow_list
+---
+The **allow_list** middleware restricts access to only those clients whose IP address matches one of a set of approved patterns. All other requests receive a configurable forbidden response.
+
+## Configuration
+
+```ruby
+allow_list \
+  allowed_patterns: [
+    /127\.0\.0\.1/,           # only localhost
+    /10\.0\.\d+\.\d+/,        # any 10.0.x.x
+    "192.168.1.0/24"          # CIDR range for 192.168.1.x
+  ],
+  error_response: "forbidden"
+```
+
+*	`allowed_patterns` (required):
+An array of Ruby‑style regexp strings. Each incoming client IP (from req.addr) is tested against this set; if none match, the request is blocked.
+*	`error_response` (optional):
+A built‑in or custom error response (default is forbidden / HTTP 403).
+
+
+## Trusted Proxies
+
+By default, an allow-list uses the IP address from the underlying socket (remote_addr). However, if your server is behind a reverse proxy, all requests will appear to come from the proxy’s IP address. This can break IP-based rules or cause rate-limiting to group all users together.
+
+To address this, you can declare trusted proxies and instruct the server to extract the original client IP from forwarded headers only if the request came from one of these proxies.
+
+
+### Configuring trusted_proxies
+
+To trust one or more upstream proxies, provide a trusted_proxies map in the middleware configuration.
+E.g.
+```ruby {filename=Itsi.rb}
+allow_list \
+  allowed_patterns: [
+    /127\.0\.0\.1/,           # only localhost
+    /10\.0\.\d+\.\d+/,        # any 10.0.x.x
+    "192.168.1.0/24"          # CIDR range for 192.168.1.x
+  ],
+  trusted_proxies: {
+    "192.168.1.1" => { header: { name: "X-Forwarded-For" } }
+  }
+```

data/lib/itsi/server/config/middleware/allow_list.rb

@@ -0,0 +1,42 @@
+module Itsi
+  class Server
+    module Config
+      class AllowList < Middleware
+        require_relative "error_response"
+        require_relative "cidr_to_regex"
+        require_relative "token_source"
+
+        include CidrToRegex
+
+        insert_text <<~SNIPPET
+        allow_list \\
+          allowed_patterns: [${1|"127.0.0.1","127.*", /127\.0\.*/|}],
+          error_response: ${2|"forbidden",{ code: 403\\, plaintext: { inline: "<h1>Forbidden</h1>" } }|}
+        SNIPPET
+
+        detail "Allow only clients whose IP matches one of the given regex patterns."
+
+        schema do
+          {
+            allowed_patterns: Array(Type(String)) & Required(),
+            error_response: Type(ErrorResponseDef).default("forbidden"),
+            trusted_proxies: (Hash(Type(String), Type(TokenSource)) & Required()).default({}),
+          }
+        end
+
+        def initialize(location, params={})
+          params[:allowed_patterns] = Array(params[:allowed_patterns]).map do |pattern|
+            if pattern.is_a?(Regexp)
+              pattern.source
+            elsif pattern =~ /\A\d{1,3}(?:\.\d{1,3}){3}\/\d{1,2}\z/
+              cidr_to_regex(pattern).source
+            else
+              pattern
+            end
+          end
+          super
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/middleware/auth_api_key.md

@@ -0,0 +1,90 @@
+---
+title: API Key
+url: /middleware/auth_api_key
+---
+The API key middleware allows you to protect any set of endpoints with an API Key requirement.
+
+Valid API keys can be loaded from a credentials file (using Itsi’s built‑in [passfile generator](/utilities/passfile_generator)), or defined inline (for example via environment variables).
+
+Keys are required to be hashed using one of the supported [hashing algorithms](/utilities/passfile_generator/#supported-hashing-algorithms).
+
+{{< callout type="info" >}}
+API keys may be **anonymous** (no ID; any valid secret will do), or **identified** (each secret is paired with a Key ID, and both must be supplied on each request).
+{{< /callout >}}
+
+## Configuration
+
+### 1. Load from credentials file
+
+```ruby {filename=Itsi.rb}
+# Look for .itsi-credentials in the project root (format: key_id:secret per line)
+auth_api_key credentials_file: ".itsi-credentials"
+
+# Default behavior. Looks for credentials file at .itsi-credentials
+auth_api_key
+
+```
+
+### 2. Inline anonymous keys
+
+```ruby {filename=Itsi.rb}
+# Only the secret values matter (no IDs)
+auth_api_key valid_keys: [
+  ENV["API_KEY_1"],
+  ENV["API_KEY_2"]
+]
+```
+
+### 3. Inline identified keys
+
+```ruby {filename=Itsi.rb}
+# Each key pair is identified by an ID
+auth_api_key valid_keys: {
+  "consumer_1" => ENV["API_KEY_1"],
+  "consumer_2" => ENV["API_KEY_2"]
+}
+```
+
+### 4. Apply API Key Auth to specific endpoints
+
+> See [location](/middleware/location)
+
+```ruby {filename=Itsi.rb}
+# Apply Basic Authentication to specific endpoints
+location "/admin/*" do
+  auth_api_key valid_keys: {
+    "consumer_1" => ENV["API_KEY_1"],
+    "consumer_2" => ENV["API_KEY_2"]
+  }
+end
+```
+
+
+## Customized Key-ID and Secret sources
+* By default, the secret is expected inside an `Authorization` header, as a Bearer token.
+* By default, the Key-ID (*if not using anonymous auth*) is expected inside an `X-Api-Key-Id` header.
+Both of these sources can be configured using the `key_id_source` and  `token_source` options.
+The source can be either a named `header` (with optional prefix) or `query` parameter,
+{{< callout >}}
+Note: Using a query source for the *Secret* is not recommended, as full URLs are readily leaked and recorded via logs and browser history. You should reserve use of a query token-source for non-sensitive information or test cases.
+{{< /callout >}}
+
+```ruby {filename=Itsi.rb}
+auth_api_key \
+  valid_keys: {.. },
+  key_id_source: { query: 'api_key_id' },
+  token_source: { header: 'Authorization', prefix: 'Bearer ' }
+```
+
+## Customized Error Responses
+This middleware will return a default `unauthorized` response if the API key is missing or invalid.
+However you can override this behaviour, by providing a custom [error response](/middleware/error_response).
+E.g.
+```ruby {filename=Itsi.rb}
+auth_api_key valid_keys: {.. }, error_response: "unauthenticated"
+```
+
+```ruby {filename=Itsi.rb}
+auth_api_key valid_keys: {.. }, error_response: {code: 403, plaintext: {inline: "unauthenticated"} , default: 'plaintext'}
+
+```

data/lib/itsi/server/config/middleware/auth_api_key.rb

@@ -0,0 +1,51 @@
+module Itsi
+  class Server
+    module Config
+      class AuthApiKey < Middleware
+        require_relative "token_source"
+        require_relative "error_response"
+
+        insert_text <<~SNIPPET
+        auth_api_key \\
+          token_source: ${1:{header: {name: 'Authorization', prefix: 'Bearer '}}},
+          key_id_source: ${2|nil,{header: {name: 'X-API-Key'}}|},
+          error_response: ${3|"Unauthorized", "unauthenticated", { code: 408\\, default_format: "html"\\, html: { inline: "<h1>Unauthorized</h1>" } }|},
+          credentials_file: ${4|nil, ".itsi-credentials"|},
+          valid_keys: ${5|nil, [ENV['API_KEY_1']]|}
+        SNIPPET
+
+        detail "Require API Key Auth"
+
+        schema do
+          {
+            valid_keys: Or(Array(Type(String)), Hash(Type(String), Type(String))),
+            credentials_file: Type(String),
+            token_source: (Type(TokenSource) & Required()).default({header: { name: 'Authorization', prefix: 'Bearer ' }}),
+            key_id_source: Type(TokenSource).default({header: { name: 'X-Api-Key-Id' }}),
+            error_response: Type(ErrorResponseDef).default("unauthorized"),
+          }
+        end
+
+        def initialize(location, params)
+          super
+          if @params[:valid_keys] && @params[:valid_keys].is_a?(Array)
+            @params[:valid_keys] = @params[:valid_keys].each_with_index.map { |key, index| [index, key] }.to_h
+            @params[:key_id_source] = nil
+          end
+
+          if File.exist?(".itsi-credentials") && !@params[:credential_file]
+            @params[:credential_file] = ".itsi-credentials"
+          end
+
+          if @params[:credential_file] && File.exist?(@params[:credential_file])
+            @params[:valid_keys] = Passfile.load(@params[:credential_file])
+          end
+
+          unless @params[:valid_keys]&.any?
+            raise "No credentials provided"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/itsi/server/config/middleware/auth_basic.md

@@ -0,0 +1,45 @@
+---
+title: Basic Authentication
+url: /middleware/auth_basic
+---
+The Basic Auth middleware allows you to require Basic Authentication on any set of endpoints.
+
+Valid credentials can be loaded from a credentials file (using Itsi’s built‑in [passfile generator](/utilities/passfile_generator)), or defined inline (for example via environment variables).
+
+Keys are required to be hashed using one of the supported [hashing algorithms](/utilities/passfile_generator/#supported-hashing-algorithms).
+
+## Configuration
+
+### 1. Load from credentials file
+
+```ruby {filename=Itsi.rb}
+# Look for .itsi-credentials in the project root (format: key_id:secret per line)
+auth_basic realm: "Admin Area", credentials_file: ".itsi-credentials"
+
+# Default behavior. Looks for credentials file at .itsi-credentials
+auth_basic
+
+```
+
+### 2. Inline credentials
+```ruby {filename=Itsi.rb}
+# Each key pair is identified by an ID
+auth_basic realm: "Admin Area",  credentials_pairs: {
+  "user_1" => ENV["BASIC_AUTH_PASSWORD_1"],
+  "user_2" => ENV["BASIC_AUTH_PASSWORD_2"]
+}
+```
+
+### 3. Apply Basic Authentication to specific endpoints
+
+> See [location](/middleware/location)
+
+```ruby {filename=Itsi.rb}
+# Apply Basic Authentication to specific endpoints
+location "/admin/*" do
+  auth_basic realm: "Admin Area", credentials_pairs: {
+    "user_1" => ENV["BASIC_AUTH_PASSWORD_1"],
+    "user_2" => ENV["BASIC_AUTH_PASSWORD_2"]
+  }
+end
+```

data/lib/itsi/server/config/middleware/auth_basic.rb

@@ -0,0 +1,44 @@
+module Itsi
+  class Server
+    module Config
+      class AuthBasic < Middleware
+
+        insert_text <<~SNIPPET
+        auth_basic \\
+          realm: ${1:"Admin Area"},
+          credential_pairs: ${2|{ "admin": ENV['ADMIN_PASSWORD'] }|}
+        SNIPPET
+
+        detail "Require Basic Auth"
+
+        schema do
+          {
+            credential_pairs: Hash(Type(String), Type(String)),
+            credentials_file: Type(String),
+            realm: (Type(String) & Required()).default("Admin Area")
+          }
+        end
+
+        def initialize(location, params={})
+          super
+          unless @params[:credential_pairs]&.any?
+            if File.exist?(".itsi-credentials") && !@params[:credential_file]
+              @params[:credential_file] = ".itsi-credentials"
+            end
+
+            if @params[:credential_file] && File.exist?(@params[:credential_file])
+              @params[:credential_pairs] = Passfile.load(@params[:credential_file])
+            end
+          end
+
+          @params[:credential_pairs].compact!
+
+          unless @params[:credential_pairs]&.any?
+            raise "No credentials provided"
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/middleware/auth_jwt.md

@@ -0,0 +1,82 @@
+---
+title: JWT Auth
+url: /middleware/auth_jwt
+---
+The JWT authentication middleware allows you to require valid JWT Authentication for any set of endpoints.
+
+Itsi supports verifying JWTs signed using each of the following algorithms: `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`.
+
+## Configuration
+
+### 1. Supporting multiple verifiers simultaneously
+You can configure multiple verifiers for each algorithm, allowing you to rotate keys without downtime.
+
+```ruby {filename=Itsi.rb}
+auth_jwt verifiers: {
+  "HS256" => [ENV['HS256_SECRET_1'], ENV['HS256_SECRET_2']],
+  "RS512" => [ENV['RS512_SECRET_1'], ENV['RS512_SECRET_2']],
+}
+```
+
+### 2. Further restrictions based on claims
+You can further restrict access based on claims in the JWT payload. For example, you can require a specific role or scope. If claim restrictions are present and unmet, the request will be rejected.
+
+```ruby {filename=Itsi.rb}
+auth_jwt verifiers: {..},
+  audiences: ["aud1", "aud2"],
+  subjects: ["sub1", "sub2"],
+  issuers: ["iss1", "iss2"]
+```
+
+### 3. Apply JWT Authentication to specific endpoints
+
+> See [location](/middleware/location)
+
+```ruby {filename=Itsi.rb}
+# Apply Basic Authentication to specific endpoints
+location "/admin/*" do
+  auth_jwt verifiers: {..}
+end
+```
+
+### 4. Leeway
+You can optionally specify a leeway in seconds to account for clock skew between the client and server.
+
+```ruby {filename=Itsi.rb}
+auth_jwt verifiers: {..},
+  leeway: 60
+```
+
+## Customized Token Source
+* The JWT is expected inside an `Authorization` header, as a Bearer token.
+This source can be overridden using the  `token_source` options.
+A token source can be either a named `header` (with optional prefix) or `query` parameter,
+{{< callout >}}
+Note: Using a query source for the *Secret* is not recommended, as full URLs are readily leaked and recorded via logs and browser history. You should reserve use of a query token-source for non-sensitive information or test cases.
+{{< /callout >}}
+
+```ruby {filename=Itsi.rb}
+auth_jwt \
+  verifiers: {.. },
+  token_source: { header: 'Authorization', prefix: 'Bearer ' }
+```
+
+## Verifier Secrets
+* For `HMAC` algorithms, Itsi expects a `base64` encoded secret.
+* For `RSA` (and `PS`) algorithms, Itsi expects a `PEM`-formatted key.
+* For `ECDSA` algorithms, Itsi expects a `PEM`-formatted key.
+
+Itsi's built-in [secrets management](/utilities/secrets_management) can be used to generate secrets for all supported algorithms.
+
+## Customized Error Responses
+This middleware will return a default `unauthorized` response if the API key is missing or invalid.
+However you can override this behaviour, by providing a custom [error response](/middleware/error_response).
+E.g.
+```ruby {filename=Itsi.rb}
+auth_jwt verifiers: {.. }, error_response: "unauthenticated"
+```
+
+```ruby {filename=Itsi.rb}
+auth_jwt verifiers: {.. }, error_response: {code: 403, plaintext: {inline: "unauthenticated"} , default: 'plaintext'}
+
+```

data/lib/itsi/server/config/middleware/auth_jwt.rb

@@ -0,0 +1,38 @@
+module Itsi
+  class Server
+    module Config
+      class AuthJwt < Middleware
+        require_relative "token_source"
+
+        insert_text <<~SNIPPET
+        auth_jwt \\
+          token_source: ${1:{header: {name: 'Authorization', prefix: 'Bearer '}}},
+          verifiers: ${2:{"HS256": [ENV['JWT_HS_SECRET_1'], ENV['JWT_HS_SECRET_2']]}},
+          audiences: ${3:[]},
+          subjects: ${4:[]},
+          issuers: ${5:[]},
+          leeway: ${6:60}
+        SNIPPET
+
+        detail "Require Basic Auth"
+
+        schema do
+          {
+            token_source: (Type(TokenSource) & Required()).default({header: {name: 'Authorization', prefix: 'Bearer '}}),
+            verifiers: (Hash(Type(String), Array(Type(String)) & Length(1..1024))) & Required() & Length(1..32),
+            audiences: Array(Type(String)),
+            subjects: Array(Type(String)),
+            issuers: Array(Type(String)),
+            leeway: Type(Integer)
+          }
+        end
+
+        def initialize(location, params)
+          super
+          @params[:verifiers].transform_keys!{|k| k.to_s.downcase }
+        end
+
+      end
+    end
+  end
+end

data/lib/itsi/server/config/middleware/cache_control.md

@@ -0,0 +1,78 @@
+---
+title: Cache-Control
+url: /middleware/cache_control
+---
+
+The Cache-Control middleware allows you to configure HTTP caching headers for your application. It creates a standard `Cache-Control` header based on a set of directives and, optionally, an `Expires` header when a maximum age is specified. The middleware also supports setting a `Vary` header and any additional custom headers.
+
+## Cache-Control configuration
+
+```ruby
+cache_control \
+  max_age: 3600,
+  s_max_age: 1800,
+  stale_while_revalidate: 30,
+  stale_if_error: 60,
+  public: true,
+  private: false,
+  no_cache: false,
+  no_store: false,
+  must_revalidate: false,
+  proxy_revalidate: false,
+  immutable: false,
+  vary: ["Accept-Encoding"],
+  additional_headers: { "X-Custom-Header" => "HIT" }
+```
+
+## Cache-Control Applied to a sub-location
+
+```ruby
+location "/static" do
+  cache_control \
+    max_age: 86400,
+    public: true,
+    vary: ["Accept-Encoding", "User-Agent"]
+  get("/assets") { |r| r.ok "static content" }
+end
+```
+
+## Configuration Options
+
+- **max_age**:
+  An optional integer that sets the maximum time (in seconds) the response should be considered fresh. When specified, it also triggers the generation of an `Expires` header with the correct HTTP date.
+
+- **s_max_age**:
+  An optional integer for shared (proxy) cache time. It is set as `s-maxage=<value>` in the header.
+
+- **stale_while_revalidate**:
+  An optional integer that indicates how long (in seconds) a stale response may be served while revalidation occurs.
+
+- **stale_if_error**:
+  An optional integer that allows serving stale content if an error occurs during revalidation.
+
+- **public**:
+  A boolean flag. When `true` (and if `private` is not enabled), adds the `public` directive to the header.
+
+- **private**:
+  A boolean flag. When `true` (and if `public` is not enabled), adds the `private` directive to the header.
+
+- **no_cache**:
+  When `true`, the `no-cache` directive is added, instructing caches to validate the response with the origin server before reuse.
+
+- **no_store**:
+  When `true`, adds the `no-store` directive to completely disable caching.
+
+- **must_revalidate**:
+  When `true`, adds the `must-revalidate` directive ensuring stale responses are not used.
+
+- **proxy_revalidate**:
+  When `true`, the `proxy-revalidate` directive is added, which is similar to `must-revalidate` but for shared caches.
+
+- **immutable**:
+  When `true`, adds the `immutable` directive indicating that the response body will not change over time.
+
+- **vary**:
+  An array of header names as strings; these are concatenated and sent as the `Vary` header to inform caches which request headers might influence the response.
+
+- **additional_headers**:
+  A hash for any extra headers you wish to include in the response. Both keys and values are strings.

data/lib/itsi/server/config/middleware/cache_control.rb

@@ -0,0 +1,45 @@
+module Itsi
+  class Server
+    module Config
+      class CacheControl < Middleware
+
+        insert_text <<~SNIPPET
+        cache_control \\
+          max_age: ${1|3600,7200|},
+          s_max_age: ${2|1800,3600|},
+          stale_while_revalidate: ${3|30,60|},
+          stale_if_error: ${4|60,120|},
+          public: ${5|true,false|},
+          private: ${6|true,false|},
+          no_cache: ${7|true,false|},
+          no_store: ${8|true,false|},
+          must_revalidate: ${9|true,false|},
+          proxy_revalidate: ${10|true,false|},
+          immutable: ${11|true,false|},
+          vary: [\"${12:Accept-Encoding}\"],
+          additional_headers: { \"${13:X-Custom-Header}\" => \"${14:value}\" }
+        SNIPPET
+
+        detail "Sets Cache-Control, Expires, Vary and additional HTTP caching headers."
+
+        schema do
+          {
+            max_age: (Type(Integer)),
+            s_max_age: (Type(Integer)),
+            stale_while_revalidate: (Type(Integer)),
+            stale_if_error: (Type(Integer)),
+            public: Bool().default(false),
+            private: Bool().default(false),
+            no_cache: Bool().default(false),
+            no_store: Bool().default(false),
+            must_revalidate: Bool().default(false),
+            proxy_revalidate: Bool().default(false),
+            immutable: Bool().default(false),
+            vary: Array(Type(String)).default([]),
+            additional_headers: Hash(Type(String), Type(String)).default({}),
+          }
+        end
+      end
+    end
+  end
+end