end_point_blank 0.2.0

data/lib/end_point_blank/masking.rb

@@ -0,0 +1,282 @@
+require "json"
+
+module EndPointBlank
+  # Client-side masking. Applies configured rules to an outgoing payload's
+  # maskable fields for the given record_type, then runs the optional user hook.
+  # Payload keys are SYMBOLS matching the writers' payloads / intake wire keys.
+  #
+  # Rule shape (string-keyed-or-symbol-keyed hash):
+  #   :target            — one of request_body, request_headers, path,
+  #                        response_body, error_message; mapped to a wire key
+  #                        per FIELD_MAP for the record_type.
+  #   :path              — a JSONPath (constrained subset); may be nil/"".
+  #   :regex             — a regex source string; may be nil/"".
+  #   :replacement_value — literal replacement string.
+  #
+  # Matching semantics ("path scopes, regex matches within"):
+  #   path only    — replace each node selected by the path entirely.
+  #   regex only   — global regex substitution on every string leaf.
+  #   path + regex — within each selected node, regex-substitute its string leaves.
+  module Masking
+    FIELD_MAP = {
+      request: { "request_body" => :request, "request_headers" => :headers, "path" => :path },
+      response: { "response_body" => :body },
+      error: { "error_message" => :message },
+      log: {}
+    }.freeze
+
+    # Targets whose wire value is a JSON string body (decode/apply/re-encode).
+    JSON_TARGETS = %w[request_body response_body].freeze
+
+    module_function
+
+    def apply(payload, record_type, rules, hook)
+      masked = (rules || []).reduce(payload) { |acc, rule| apply_rule(acc, record_type, rule) }
+      hook ? hook.call(masked, record_type.to_s) : masked
+    end
+
+    def apply_rule(payload, record_type, rule)
+      field_map = FIELD_MAP.fetch(record_type, {})
+      target = rule[:target]
+      key = field_map[target]
+      return payload unless key && payload.key?(key)
+
+      payload.merge(key => mask_field(payload[key], rule, target))
+    end
+
+    # Body targets: JSON string. Decode, apply on the decoded value, re-encode.
+    # On non-JSON: path no-ops; regex (if present) applies to the raw string.
+    # request_headers: a Hash. path applies; regex applies to string leaves.
+    # path / error_message: plain strings — path no-ops, only regex applies.
+    def mask_field(value, rule, target)
+      case value
+      when String
+        if JSON_TARGETS.include?(target)
+          begin
+            decoded = JSON.parse(value)
+          rescue JSON::ParserError
+            return apply_to_raw_string(value, rule)
+          end
+          JSON.generate(apply_to_value(decoded, rule))
+        else
+          apply_to_raw_string(value, rule)
+        end
+      when Hash
+        apply_to_value(value, rule)
+      else
+        value
+      end
+    end
+
+    # A plain, non-JSON string target: path cannot apply (no-op); regex applies.
+    def apply_to_raw_string(value, rule)
+      re = compiled_regex(rule)
+      return value unless re
+
+      regex_replace_all(re, value, replacement(rule))
+    end
+
+    # Applies the rule to a structured value (decoded JSON or header Hash).
+    def apply_to_value(value, rule)
+      path = rule[:path] || rule["path"]
+      tokens = parse_path(path)
+      return value if tokens.nil? && path.is_a?(String) && path != ""
+
+      re = compiled_regex(rule)
+      repl = replacement(rule)
+
+      if tokens && re
+        # path + regex: select nodes, apply regex to leaves within each.
+        transform(value, tokens) { |old| regex_replace_leaves(old, re, repl) }
+      elsif tokens
+        # path only: replace each selected node entirely.
+        transform(value, tokens) { |_old| repl }
+      elsif re
+        # regex only: substitute across every string leaf.
+        regex_replace_leaves(value, re, repl)
+      else
+        value
+      end
+    end
+
+    def replacement(rule)
+      (rule[:replacement_value] || rule["replacement_value"] || "...").to_s
+    end
+
+    # Compiles rule[:regex]; blank/nil/invalid ⇒ nil (regex step no-ops).
+    def compiled_regex(rule)
+      source = rule[:regex] || rule["regex"]
+      return nil if source.nil? || source == ""
+
+      Regexp.new(source)
+    rescue RegexpError, TypeError
+      nil
+    end
+
+    # Recurse over containers; substitute on every string leaf.
+    def regex_replace_leaves(node, re, repl)
+      case node
+      when String then regex_replace_all(re, node, repl)
+      when Hash then node.each_with_object({}) { |(k, v), out| out[k] = regex_replace_leaves(v, re, repl) }
+      when Array then node.map { |e| regex_replace_leaves(e, re, repl) }
+      else node
+      end
+    end
+
+    # --- Replacement backreferences (shared contract) --------------------------
+    #
+    # In a regex substitution, replacement_value is a TEMPLATE. For each match we
+    # build the replacement ourselves (NOT Ruby's native \N substitution):
+    #   $$         → literal "$"
+    #   $<digits>  → capture group N (full consecutive digit run); 0 = whole
+    #                match; missing/non-participating group → "".
+    #   lone/trailing $ before a non-digit → literal "$".
+    # groups is 0-indexed: groups[0] = whole match, groups[n] = nth capture.
+
+    def regex_replace_all(regexp, string, template)
+      string.gsub(regexp) do
+        m = Regexp.last_match
+        groups = (0...m.size).map { |i| m[i] }
+        expand(template, groups)
+      end
+    end
+
+    def expand(template, groups)
+      out = +""
+      i = 0
+      len = template.length
+      while i < len
+        ch = template[i]
+        if ch != "$"
+          out << ch
+          i += 1
+        elsif template[i + 1] == "$"
+          out << "$"
+          i += 2
+        elsif template[i + 1] =~ /\d/
+          j = i + 1
+          j += 1 while j < len && template[j] =~ /\d/
+          n = template[(i + 1)...j].to_i
+          out << (groups[n] || "")
+          i = j
+        else
+          out << "$"
+          i += 1
+        end
+      end
+      out
+    end
+
+    # --- Constrained JSONPath subset (mirrors intake's JsonPath) ---------------
+    #
+    # Tokens: [:child, name] / [:index, n] / [:wildcard] / [:descendant, name].
+    # parse_path returns a token array, or nil for blank/unsupported/garbled
+    # input (caller treats nil as "matches nothing"). Never raises.
+
+    def parse_path(string)
+      return nil unless string.is_a?(String)
+      return nil unless string.start_with?("$")
+
+      parse_tokens(string[1..], [])
+    end
+
+    def parse_tokens(rest, acc)
+      return acc if rest.empty?
+
+      if rest.start_with?("..")
+        name, remaining = take_name(rest[2..])
+        return nil if name.empty?
+
+        parse_tokens(remaining, acc + [[:descendant, name]])
+      elsif rest.start_with?(".*")
+        parse_tokens(rest[2..], acc + [[:wildcard]])
+      elsif rest.start_with?(".")
+        name, remaining = take_name(rest[1..])
+        return nil if name.empty?
+
+        parse_tokens(remaining, acc + [[:child, name]])
+      elsif rest.start_with?("[")
+        result = parse_bracket(rest[1..])
+        return nil unless result
+
+        token, remaining = result
+        parse_tokens(remaining, acc + [token])
+      end
+    end
+
+    def parse_bracket(rest)
+      if rest.start_with?("*]")
+        [[:wildcard], rest[2..]]
+      elsif rest.start_with?("'")
+        parse_quoted(rest[1..], "'")
+      elsif rest.start_with?('"')
+        parse_quoted(rest[1..], '"')
+      elsif (m = rest.match(/\A(\d+)\](.*)\z/m))
+        [[:index, m[1].to_i], m[2]]
+      end
+    end
+
+    def parse_quoted(rest, quote_char)
+      name, remaining = rest.split("#{quote_char}]", 2)
+      return nil if remaining.nil?
+
+      [[:child, name], remaining]
+    end
+
+    # Consumes a leading [A-Za-z0-9_]+ run; returns [name, remaining].
+    def take_name(string)
+      m = string.match(/\A([A-Za-z0-9_]+)(.*)\z/m)
+      return ["", string] unless m
+
+      [m[1], m[2]]
+    end
+
+    # Walks value following tokens, replacing each fully-matched location with
+    # the block's result and rebuilding parents immutably. Never raises.
+    def transform(value, tokens, &block)
+      return block.call(value) if tokens.empty?
+
+      token, *rest = tokens
+      case token[0]
+      when :child
+        key = token[1]
+        return value unless value.is_a?(Hash) && value.key?(key)
+
+        value.merge(key => transform(value[key], rest, &block))
+      when :index
+        i = token[1]
+        return value unless value.is_a?(Array) && i >= 0 && i < value.length
+
+        out = value.dup
+        out[i] = transform(out[i], rest, &block)
+        out
+      when :wildcard
+        case value
+        when Hash then value.each_with_object({}) { |(k, v), o| o[k] = transform(v, rest, &block) }
+        when Array then value.map { |e| transform(e, rest, &block) }
+        else value
+        end
+      when :descendant
+        descend(value, token[1], rest, &block)
+      else
+        value
+      end
+    end
+
+    # Recursive descent: at this node and every nested node, any entry whose key
+    # is `key` matches the remaining tokens.
+    def descend(value, key, rest, &block)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), out|
+          v = descend(v, key, rest, &block)
+          out[k] = k == key ? transform(v, rest, &block) : v
+        end
+      when Array
+        value.map { |e| descend(e, key, rest, &block) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/end_point_blank/middleware/rack/report_interaction.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module EndPointBlank
+  module Middleware
+    module Rack
+      class ReportInteraction
+        attr_reader :options, :url
+
+        def initialize(app, options = {})
+          @app = app
+          @mapping = options
+        end
+
+        def call(env)
+          ::EndPointBlank::Rack::EnvStore.set(env)
+          ::EndPointBlank::Writers::RequestWriter.write
+
+          status, headers, body = @app.call(env)
+
+          [status, headers, body]
+        rescue ::EndPointBlank::UnauthorizedError => e
+          # We don't want to log unauthorized errors as they are expected to happen
+          status ||= e.respond_to?(:status) && e.status || 401
+          body ||= e.message
+          raise e
+        rescue Exception => e
+          # The exception will be rendered by ActionDispatch::DebugExceptions
+          # (or ShowExceptions in prod), which sits outside this middleware,
+          # so we never see the rendered status / body. Synthesize them so the
+          # response row still gets recorded — intake requires a non-nil status.
+          status ||= 500
+          body ||= "#{e.class}: #{e.message}"
+          Writers::ExceptionWriter.write(e)
+
+          raise e
+        ensure
+          headers = ::EndPointBlank::Rack::Headers.extract
+          ::EndPointBlank::Writers::ResponseWriter.write(status:, headers:, body:)
+          ::EndPointBlank::Rack::EnvStore.clear
+        end
+
+        def on_success(response)
+          EndPointBlank.logger.debug("Successfully reported interaction: #{response.body}")
+        end
+
+        def on_failure(response)
+          EndPointBlank.logger.error("Failed to report interaction: #{response.body}")
+        end
+      end
+    end
+  end
+end

data/lib/end_point_blank/rack/env_store.rb

@@ -0,0 +1,34 @@
+module EndPointBlank
+  module Rack
+    class EnvStore
+      KEY = 'end_point_blank.rack_env'.freeze
+      SOURCE_ENV_ID_KEY = 'end_point_blank.source_application_environment_id'.freeze
+
+      def self.set(env)
+        Thread.current[KEY] = env
+      end
+
+      def self.get
+        Thread.current[KEY]
+      end
+
+      def self.request
+        env = get
+        env && ::Rack::Request.new(env)
+      end
+
+      def self.set_source_application_environment_id(id)
+        Thread.current[SOURCE_ENV_ID_KEY] = id
+      end
+
+      def self.source_application_environment_id
+        Thread.current[SOURCE_ENV_ID_KEY]
+      end
+
+      def self.clear
+        Thread.current[KEY] = nil
+        Thread.current[SOURCE_ENV_ID_KEY] = nil
+      end
+    end
+  end
+end

data/lib/end_point_blank/rack/headers.rb

@@ -0,0 +1,11 @@
+module EndPointBlank
+  module Rack
+    module Headers
+      def self.extract
+        env = ::EndPointBlank::Rack::EnvStore.get
+        env.select { |k,v| k.start_with? 'HTTP_'}.
+          transform_keys { |k| k.sub(/^HTTP_/, '').split('_').map(&:capitalize).join('-') }
+      end
+    end
+  end
+end

data/lib/end_point_blank/rails/authenticated.rb

@@ -0,0 +1,21 @@
+require "active_support/concern"
+
+module EndPointBlank
+  module Rails
+    module Authenticated
+     extend ActiveSupport::Concern
+
+      included do
+        before_action :authenticate!
+      end
+
+      def authenticate!
+        result = EndPointBlank::Commands::EndpointAuthenticate.authenticate(request)
+        result_json = JSON.parse(result.body)
+        if !result || result.status != 201
+          raise UnauthorizedError, "Authentication failed: #{result_json['error']}"
+        end
+      end
+    end
+  end
+end

data/lib/end_point_blank/rails/authorized.rb

@@ -0,0 +1,33 @@
+require "active_support/concern"
+
+module EndPointBlank
+  module Rails
+    module Authorized
+     extend ActiveSupport::Concern
+
+      included do
+        before_action :authorize!
+      end
+
+      def authorize!
+        result = EndPointBlank::Commands::EndpointAuthorize.authorize(request)
+        if result.nil? || result.status != 201
+          raise UnauthorizedError.new(authorize_error_message(result), result&.status || 503)
+        end
+        result_json = JSON.parse(result.body)
+        app_env_id = result_json['data'][0]['source_application_environment_id']
+        ::EndPointBlank::Rack::EnvStore.set_source_application_environment_id(app_env_id)
+      end
+
+      private
+
+      def authorize_error_message(result)
+        return "Authorization service unavailable" if result.nil?
+
+        parsed = JSON.parse(result.body) rescue nil
+        detail = parsed.is_a?(Hash) ? parsed["error"] : nil
+        "Authorization failed: #{detail || result.body}"
+      end
+    end
+  end
+end

data/lib/end_point_blank/rails/railtie.rb

@@ -0,0 +1,18 @@
+require 'rails/railtie' if defined?(::Rails)
+
+module EndPointBlank
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer 'endpointblank.middleware.rails' do |app|
+        require 'end_point_blank/rails/railtie'
+
+        app.config.middleware.insert_after ActionDispatch::DebugExceptions,
+                                          EndPointBlank::Middleware::Rack::ReportInteraction
+      end
+
+      initializer 'endpointblank.logger.rails' do
+        EndPointBlank::Configuration.instance.logger ||= ::Rails.logger
+      end
+    end
+  end
+end

data/lib/end_point_blank/rails/versioned.rb

@@ -0,0 +1,64 @@
+module EndPointBlank
+  module Rails
+    module Versioned
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Define versioning for specific actions
+        # @param versions [Array<String>] List of version strings (e.g., ["v1", "v2"])
+        # @param options [Hash] Options hash with :only or :except keys
+        # @option options [Array<Symbol>] :only Actions to include in versioning
+        # @option options [Array<Symbol>] :except Actions to exclude from versioning
+        #
+        # Example:
+        #   version ["v1", "v2"], only: [:index], state: "Current"
+        #   version ["v3"], except: [:destroy], state: "Deprecated"
+        def version(values, options = {})
+          versions = Array(values)
+          @versioning_config ||= {}
+
+          actions = determine_actions(options)
+
+          actions.each do |action|
+            @versioning_config[action] ||= {}
+            state = options[:state] || "__default__"
+            @versioning_config[action][state] ||= []
+            @versioning_config[action][state] = (@versioning_config[action][state] + versions).uniq
+          end
+        end
+
+        # Returns the versioning configuration hash
+        # @return [Hash] Hash mapping action names to their version arrays
+        #
+        # Example return value:
+        #   {
+        #     index: ["v1", "v2"],
+        #     show: ["v1"]
+        #   }
+        def versions(action)
+          @versioning_config&.fetch(action, {}) || {}
+        end
+
+        private
+
+        # Determine which actions should be affected based on options
+        # @param options [Hash] Options hash with :only or :except keys
+        # @return [Array<Symbol>] Array of action symbols
+        def determine_actions(options)
+          if options[:only]
+            Array(options[:only]).map(&:to_sym)
+          elsif options[:except]
+            # If :except is specified, we need to determine all possible actions
+            # and exclude the specified ones. Get all public methods of the controller.
+            all_actions = self.public_instance_methods(false).map(&:to_sym)
+            excluded_actions = Array(options[:except]).map(&:to_sym)
+            all_actions - excluded_actions
+          else
+            # If no options specified, apply to all common REST actions
+            self.public_instance_methods(false).map(&:to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/end_point_blank/session_configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  # Resolves per-request session state (the current Rack env, and the name
+  # of the environment the app is running in) without depending on any
+  # particular framework or app server.
+  class SessionConfiguration
+    def self.env
+      ::EndPointBlank::Rack::EnvStore.get
+    end
+
+    # Resolves the name of the environment the app is running in, without
+    # assuming any particular framework or app server.
+    #
+    # Resolution order (first non-nil wins):
+    #   1. Configuration.instance.env_name (explicit config, or the
+    #      ENDPOINTBLANK_ENV environment variable)
+    #   2. RACK_ENV
+    #   3. APP_ENV
+    #   4. A Puma "puma.config" entry in the current Rack env, if present
+    #      (back-compat with earlier Puma-only behavior)
+    #   5. ::Rails.env, if Rails is defined
+    #   6. "production" as a final default
+    #
+    # Never raises, even when there is no Rack env at all (e.g. Sinatra /
+    # plain Rack apps outside of a request), and always returns a String.
+    def self.env_name
+      Configuration.instance.env_name ||
+        ENV["RACK_ENV"] ||
+        ENV["APP_ENV"] ||
+        puma_env_name ||
+        (::Rails.env.to_s if defined?(::Rails)) ||
+        "production"
+    end
+
+    # Nil-safe read of the environment name from a Puma "puma.config" entry
+    # in the Rack env, if one exists. Never raises, even when there is no
+    # Rack env at all, or the env has no "puma.config" key.
+    def self.puma_env_name
+      env&.[]("puma.config")&.options&.[](:environment)
+    end
+    private_class_method :puma_env_name
+  end
+end

data/lib/end_point_blank/string_truncator.rb

@@ -0,0 +1,21 @@
+class StringTruncator
+  DEFAULT_LIMIT = 1000
+  DEFAULT_SUFFIX = "<truncated>"
+
+  def self.truncate(str, limit: DEFAULT_LIMIT, suffix: DEFAULT_SUFFIX)
+    return "" if str.nil?
+    return str if str.bytesize <= limit
+
+    suffix_bytes = suffix.bytesize
+    max_bytes = limit - suffix_bytes
+
+    truncated = str.byteslice(0, max_bytes)
+
+    # Ensure valid UTF-8
+    while !truncated.valid_encoding?
+      truncated = truncated.byteslice(0, truncated.bytesize - 1)
+    end
+
+    truncated + suffix
+  end
+end

data/lib/end_point_blank/unauthorized_error.rb

@@ -0,0 +1,10 @@
+module EndPointBlank
+  class UnauthorizedError < StandardError
+    attr_reader :status
+
+    def initialize(message = nil, status = 401)
+      super(message)
+      @status = status
+    end
+  end
+end

data/lib/end_point_blank/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  VERSION = "0.2.0"
+end